导入学生¶
完成本页后，你可以下载当前学生 CSV 模板，准备并上传学生数据，检查解析预览，通过验证码确认执行，并在学生列表中核对实际结果。
适用对象¶
- 需要一次建立或更新多名学生的学校行政或教务人员。
- 已整理学生和监护人资料，需要使用 CSV 批量处理的人员。
- 需要在写入前通过解析预览检查文件的人员。
所需权限¶
当前账号需要具有当前学校实际配置的 维护学生档案 权限，权限编码为 student.manage，并能够进入 学生管理、看到并成功执行 导入 CSV。
菜单或按钮显示不能代替权限检查。应以当前账号实际打开导入窗口、解析文件和确认执行的结果为准，不要只根据“管理员”等角色名称判断。
前置条件¶
- 已确认当前登录的是目标学校和账号。
- 需要引用的班级已经建立，并已核对班级名称、年级和入学年份。
- 已取得学校批准导入的学生和监护人资料。
- 已决定本次是新增学生、更新已有学生，还是两者都可能存在。
- 已安排敏感信息的安全存储和传递方式。
- 不使用旧模板字段或其他学校的示例文件推测当前规则。
如果只添加一名学生，优先使用添加学生。班级尚未建立时，先阅读新建班级。
进入路径¶
登录系统后，从左侧菜单进入 学生管理，选择页面右上角的 导入 CSV。
当前窗口提供 下载模板、选择文件、上传解析预览、验证码确认执行。截图还提示 UTF-8 CSV 最稳妥，并区分空单元格和 __CLEAR__。
截图中的后台学生资料属于测试环境，只用于说明导入窗口位置，不作为模板填写示例。
操作步骤¶
1. 下载当前模板¶
在学生 CSV 导入窗口中选择 下载模板。每次准备新的导入任务时，优先从当前系统重新下载，不使用历史文件替代。
当前已核对的模板具有以下结构：
| 项目 | 已确认结果 |
|---|---|
| 文件编码 | UTF-8 BOM |
| 字段数量 | 53 个，字段名无重复 |
| 示例数据 | 没有示例数据行 |
| 学生基础字段 | 13 个 |
| 监护人字段 | 4 组，每组 10 个，共 40 个 |
不要删除、翻译、合并或改写表头。模板只有字段名，没有提供中文说明、必填标记或示例值。
2. 认识学生基础字段¶
模板中的 13 个学生基础字段为：
| 序号 | 字段名 | 当前可确认的范围 |
|---|---|---|
| 1 | student_no |
模板字段存在；匹配和唯一性未确认 |
| 2 | name |
模板字段存在；必填规则未确认 |
| 3 | class_name |
模板字段存在；班级引用规则未确认 |
| 4 | grade_name |
模板字段存在；年级引用规则未确认 |
| 5 | entry_grade_name |
模板字段存在；与其他年级字段联动未确认 |
| 6 | gender |
模板字段存在；允许值未确认 |
| 7 | identity_no |
模板字段存在；格式和匹配规则未确认 |
| 8 | nationality |
模板字段存在；允许值未确认 |
| 9 | phone |
模板字段存在；格式未确认 |
| 10 | email |
模板字段存在；格式未确认 |
| 11 | enrollment_year |
模板字段存在；格式和校验未确认 |
| 12 | external_id |
模板字段存在；匹配和唯一性未确认 |
| 13 | status |
模板字段存在；允许值未确认 |
表中的“未确认”表示不能只根据英文名称补充产品规则。填写值应来自学校已确认资料，并在解析预览中查看当前系统实际反馈。
3. 认识监护人字段¶
模板提供 guardian_1 至 guardian_4 四组监护人字段，每组包含以下 10 个后缀：
| 字段后缀 | 记录内容 |
|---|---|
name |
只在学校批准时填写对应监护人资料 |
identity_no |
敏感信息，按学校授权处理 |
phone |
敏感信息，按学校授权处理 |
email |
敏感信息，按学校授权处理 |
address |
敏感信息，按学校授权处理 |
note |
只填写学校允许记录的内容 |
relationship |
字段存在；允许值未确认 |
is_primary |
字段存在；布尔值格式未确认 |
is_emergency |
字段存在；布尔值格式未确认 |
status |
字段存在；允许值未确认 |
例如第一组对应 guardian_1_name 至 guardian_1_status，其余组按相同字段后缀编号。字段分组只用于识别表头，不表示四组都必须填写。
CSV 包含学生和监护人敏感信息
身份证号、电话、邮箱、地址和监护人资料只能在学校批准的范围内保存和传递。不要把已填写的 CSV、解析明细或真实数据截图加入用户手册或公开共享位置。
4. 填写并检查数据¶
保留全部 53 个表头，在对应列填写学校已经确认的资料。提交前至少完成以下人工检查：
- 每行是否属于当前学校。
- 班级名称、年级和入学年级是否来自当前学校资料。
- 同一文件中是否出现需要人工确认的重复学号、外部编号、证件号或姓名与班级组合。
- 敏感字段是否经过授权。
- 未确认字段是否没有使用猜测值填充。
这一步的重复检查属于导入前的数据质量检查，不表示系统会使用其中某个字段作为匹配键。
5. 正确使用空单元格和清空标记¶
更新已有学生时，已确认规则如下：
| CSV 内容 | 已确认含义 |
|---|---|
| 空单元格 | 保留已有值，不覆盖 |
__CLEAR__ |
请求清空对应字段 |
__CLEAR__ 必须准确写成左右各两个下划线的完整标记，不能写成 CLEAR 或其他形式。
清空规则边界
当前没有确认哪些字段允许清空，也没有确认必填字段使用 __CLEAR__ 时的错误结果。需要清空资料时，只能在解析预览中核对系统实际动作和提示；没有明确反馈时不要确认执行。
6. 保存为 UTF-8 CSV¶
填写完成后将文件保存为 CSV，并优先使用 UTF-8 编码。再次打开文件，确认：
- 第一行仍是完整的 53 个表头；
- 中文内容没有乱码；
- 没有增加说明行、合计行或额外标题；
- 学号、外部编号等标识没有因表格软件自动处理而发生非预期变化。
7. 选择文件并上传解析预览¶
回到学生 CSV 导入窗口：
- 选择 选择文件，指定准备好的 CSV。
- 选择 上传解析预览。
- 等待页面显示当前文件的实际解析结果。
学生预览材料边界
现有截图只证明解析预览阶段存在，没有记录学生预览会显示哪些统计项、变更明细和错误格式。
不要把教师导入的统计项目或错误表现直接套用到学生导入。只记录学生页面本次实际显示的行数、动作、警告、错误和字段变化。
8. 检查预览并处理问题¶
在确认执行前逐项检查页面实际显示内容：
- 解析到的学生和行数是否符合文件内容；
- 页面识别出的新增、更新或其他动作是否符合本次目的；
- 班级、年级和入学年级是否指向预期数据；
- 是否出现警告或错误；
- 使用
__CLEAR__的行是否显示预期的清空动作。
如果结果不符合预期，停止执行并返回 CSV 核对。当前没有证据支持以下结论：
- 错误一定会定位到具体行号和字段；
- 一次会列出所有错误；
- 有错误时仍可执行有效行；
- 重复学生一定会合并、更新、跳过或拒绝。
因此不能根据文件看起来正确就跳过预览，也不能把页面没有报错理解为所有业务关系都正确。
9. 通过验证码确认执行¶
只有预览结果与本次目的一致，并且所有需要确认的警告和错误都已处理后，才选择 验证码确认执行，再按当前页面提示完成确认。
当前材料没有确认验证码的获取方式、有效期和错误提示，也没有学生导入完成后的结果截图。执行期间不要刷新或关闭页面；如果已经发生，应记录实际结果，不推断操作一定继续或回滚。
10. 核对执行结果和学生列表¶
执行后先记录页面实际显示的成功、失败、跳过或其他结果，不使用教师导入统计代替。然后返回学生列表，抽查本次文件中的代表记录：
- 使用学号和姓名搜索学生。
- 核对班级和入学年级。
- 核对本次实际填写且允许在列表中显示的其他字段。
- 记录状态和页面实际结果。
- 检查是否出现非预期重复记录。
现有材料没有学生导入后的列表证据。只有页面明确显示执行结果，并且代表学生在列表中的资料符合预期，才能把本次导入记录为完成。
完成标志¶
同时满足以下条件，表示学生 CSV 导入已经完成：
- 使用的是当前系统下载的模板，表头保持完整。
- 文件使用 UTF-8 编码，中文和标识字段没有非预期变化。
- 已在执行前检查重复数据、班级、年级、入学年级和敏感信息。
- 更新已有学生时正确区分空单元格和
__CLEAR__。 - 已查看学生导入页面实际解析结果，没有套用教师导入规则。
- 已按页面实际流程完成验证码确认，并记录执行结果。
- 已在学生列表中抽查代表记录及班级关联。
- 没有宣称未知的匹配键、重复处理、部分执行或失败回滚规则。
下一步¶
返回学生管理，继续检查学生列表；需要单独补充一名学生时，使用添加学生。
学生准备完成后，可进入配置教师身份、角色与绑定，再使用目标教师账号验证数据范围。