ClassHelper/docs/app/imports.md

---
title: 表格与课表导入
description: 表格预览、名单与成绩校验，以及完整离线档案导入。
---

# 表格与课表导入

解析与写入均在服务端完成，Web 收集文件、展示预览和逐行结果。
表格支持成绩、学生、教师与班级任课关系等 kind，类型和模板以 shared/imports 模块为准。

## 表格流程

下载模板 → 选择 xlsx/xls/csv/tsv → 预览列名与映射 → 确认模式并提交。
文件上限 8 MB，JSON 请求体 12 MB，超限 413 IMPORT_TOO_LARGE；结果含新增/更新/跳过/失败、errors/warnings。
错误行号包含表头，便于在 Excel 定位。

- 学生成绩按学号匹配，姓名兜底要求同班唯一；转出学生不参与匹配，重复记录和写入模式由服务校验。
- 学生模板使用学号、姓名、班级、性别、家长电话，无密码；学号 1–32 位字母/数字/._-，在 Student 表查重。
- 教师模板使用工号、姓名、手机号、初始密码、角色；学生/教师名单导入仍要求管理员和导入权限。
- 成绩表格导入当前先要求管理员或本班班主任，再校验每行科目任课关系；科任老师的单条/批量成绩写入权限不代表能走表格导入。
- 任课关系导入用于既有班级、科目和教师的对应关系，不把档案中的 TeacherName 当账号授权。

## 完整 ClassIsland 档案

在“课表档案 → 导入档案”选择或粘贴 JSON，先预览再导入。
完整输入包含 TimeLayouts、ClassPlans、Subjects 字典，可包含 ClassPlanGroups 和 OrderedSchedules 等配置。
JSON 只作为离线文件导入，不依赖在线联动插件。

现行写入由 class-plans/profile-import.service.ts 完成：

| 项目      | 写入规则                                                                |
| --------- | ----------------------------------------------------------------------- |
| 时间类型  | 0/1/2/3 对应 LESSON/BREAK/DIVIDER/ACTION，保存为关系化时间点            |
| 课程对齐  | Classes[i] 引用第 i 个上课时间点，课间/分割线不占课位，数据库用显式外键 |
| 星期      | 完整导入 0=不按天、1–7=周一至周日                                       |
| 轮换      | 原样保留 WeekCountDiv/WeekCountDivTotal，支持 1–9 周，不降级成每周      |
| 状态      | 保留空课、停用、临时换课标记和关联层                                    |
| 群组/预定 | 保存群组及可识别的预定/临时选择                                         |
| 缺失科目  | 复用该班课程；新建需该班已有班主任，教师名不授予权限                    |
| merge     | 基于班级与来源 id 生成稳定 id，重复导入更新同一套对象                   |
| replace   | 事务内删除该班预定和日课表后写入，保留的对象以实现为准                  |

日课表导入需本班班主任/管理员检查。旧 /imports/class-plan/preview 是扁平预览，
不完整展示群组/空课/停用等结构；提交直接调用完整导入，不能把预览的单双周列当作实际数据模型。
完整导入失败时事务回滚；部分缺失引用可能返回 warnings，须检查导入结果和日课表编辑器。

## 时间配置兼容入口

旧 /imports/time-layout 接口保留，写入和删除需 timetable:manage，现行写入同步关系化时间点。
常规使用时间表/日课表编辑器或整套档案导入；旧预览解析兼容性不代表完整导入接受所有旧输入形态。

接口索引见[REST API](../dev/api.md)，迁移边界见[当前实现约定](../dev/implementation.md)。