# 学员名单准入与导入需求变更记录

日期：2026-07-07

## 背景

此前用户端手机号验证码登录采用“首次登录自动创建普通用户”的口径。这种方式适合开放注册，但不适合当前内部学员使用场景。

现在需求调整为：系统必须先有学员记录，手机号才允许登录。没有被管理员添加或批量导入的手机号，不允许登录，也不能使用用户端程序。

## 新口径

1. 前台用户不再自动注册。
2. 管理员负责维护学员名单。
3. 管理员可以手动新增单个学员。
4. 管理员可以批量导入学员。
5. 发送验证码和登录时都应校验手机号是否存在于系统学员名单中。
6. 只有系统中存在、未删除、启用状态正常且未过期的手机号可以登录成功。

## 后台用户管理要求

### 手动添加学员

管理员至少需要填写：

- 手机号
- 姓名

可选维护：

- 昵称
- 状态
- 每日聊天额度
- 账号有效期

### 批量导入学员

批量导入从轻量 CSV 文本粘贴调整为 Excel 模板导入。后台需要提供“下载模板”和“上传 Excel 导入”两个入口。

模板字段：

| 字段 | 必填 | 说明 |
| --- | --- | --- |
| 手机号 | 是 | 登录准入手机号，必须符合中国大陆手机号格式。 |
| 姓名 | 是 | 学员姓名。 |
| 昵称 | 否 | 可为空。 |
| 每日聊天额度 | 否 | 不填时使用系统配置默认值。 |
| 状态 | 否 | 支持“启用/禁用”或 `1/0`。 |
| 有效期 | 否 | 不填表示不过期。 |

导入规则：

- 手机号必填且格式必须正确。
- 姓名必填。
- 昵称可为空。
- 每日聊天额度为空时使用系统配置 `daily_chat_limit`。
- 已存在手机号不重复创建，按导入内容更新姓名、昵称、状态和额度。
- 已被软删除的手机号再次导入时恢复为未删除。
- 导入结果需要返回新增数、更新数、失败数和失败明细。

## 用户端登录要求

- 未在学员名单中的手机号：
  - 发送验证码时拒绝。
  - 登录时拒绝。
  - 提示文案应明确为“手机号不在学员名单中，请联系管理员”。
- 已禁用或已过期的学员：
  - 登录失败。
  - 保持现有状态/有效期提示。

## 对现有文档的覆盖说明

旧文档中“首次手机号登录后自动创建用户”“自动创建普通用户”等描述从本次变更后废弃。

后续开发和验收以本记录以及更新后的 `development_records/` 文档为准。

## 验收重点

1. 管理员可以手动添加学员。
2. 管理员可以下载 Excel 模板并批量导入学员，导入后看到结果。
3. 已导入或手动添加的学员可以通过验证码登录。
4. 系统中不存在的手机号不能发送验证码，也不能登录。
5. 禁用或过期学员仍不能登录。
