功能简介

教师信息维护是本学院教师基础信息库的统一维护入口，对应导航「教师信息」一级菜单（图标 fa-users-cog），下设两个子项：

• 教师信息维护：对本学院教师档案（一卡通号、姓名、性别、手机号、QQ、所在系室、学历、职务、毕业院校、紧急联系电话、特殊状态等）做增、删、改、查、批量导入与导出，并提供「系室维护」名称规范化。
• 一卡通号查询：按姓名 / 一卡通号做单条或批量查询，支持复制一卡通号、电话列用于回填表格；超管还能在同一入口查中央用户与角色范围。

这份教师库是监考排班、教师电话/一卡通自动填写、达成度报送等多个模块的共同数据来源。注意区分：本页是面向全院的通用教师信息维护；它与监考模块共用同一张 Invigilator 表与同一个 /maintain_invigilators 路由，但「教师信息」菜单本身不依赖监考排班逻辑，定位是教师档案而非监考轮次/安排（轮次、预安排、推荐见 监考安排管理）。

入口与权限

• 入口：
• 教师信息 → 教师信息维护（路由 /maintain_invigilators）
• 教师信息 → 一卡通号查询（路由 /teacher_cardid_lookup）
• 「教师信息」菜单的显隐由 can_access_teacher_directory 统一控制（模板变量同名），后端校验为 _can_access_teacher_directory / _ensure_teacher_directory_access，不满足直接 abort(403)。判定规则：
• 超管：始终可见、可用，且一卡通号查询会聚合所有已配置学院库。
• 学院管理员：只要当前学院开通了 invigilation、course_archives、course_changes、science_city_attendance、teaching_material_submission 中任一模块即可见。注意：仅开通「教学课件报送」的学院管理员也应能看到本菜单——历史上漏算该模块导致这类管理员无「教师信息」入口，已于 2026-05-22 修正。
• 跨学院校级账号（教务处/运行科等组织单位账号）：对上述教师目录模块有学校级管理权时可见。
• 预览/只读账号：可进入查看，但所有写操作（导入、新增、编辑、删除、导出）被 _block_preview_only_user 拦截；列表中一卡通号、手机、QQ 做脱敏显示。
• 学生：明确排除，不可见、不可用。
• 「特殊状态」列与编辑项是否可写，另由 _can_manage_invigilator_special_status 控制（需当前学院开通监考且账号具监考模块权限）；无此权限者看不到也改不了特殊状态字段，但仍可维护其余基础信息。

操作步骤（分角色）

管理员：维护教师档案（/maintain_invigilators）

1. 批量导入：在「教师信息导入与编辑」卡片选择 Excel 文件后点「导入」（/upload_invigilators）。导入按 一卡通号 为主键 upsert：已存在则更新，不存在则新增；识别的列含 一卡通号、姓名、性别、手机号码、QQ号码、所在院系、最高学历、职务或职称、毕业院校、紧急联系电话、特殊状态。无一卡通号的行跳过；导入会先自动备份数据库。
2. 新增 / 编辑单条：点「新增」或行内「编辑」展开编辑区。带红色 * 的为必填项：一卡通号、姓名、性别（默认「男」）、手机号码、QQ号码、所在系室；前后端均做必填校验，口径一致。保存走 /add_teacher（新增）或 /update_invigilator/<card_id>（更新）。
3. 筛选：顶部「全字段筛选」按姓名 / 一卡通号 / 系室（有特殊状态权限时含状态关键词）实时过滤；另有「系室」下拉（默认「全部系室」）和「重置筛选」。
4. 导出：点「导出」（/export_invigilators），默认文件名为「教师基础信息表_时间.xlsx」。
5. 删除：行内删除，二次确认弹窗会提示「该操作会同步清理该教师关联的监考安排记录」。
6. 系室维护：点「系室维护」展开面板，对本学院非标准系室名做「一键替换」规范化（详见 监考安排管理 与系部规范化约定）。

管理员：单条 / 批量查询（/teacher_cardid_lookup）

1. 关键词查询：在「关键词」框输入姓名 / 一卡通号 / 院系 / 职务 / 手机 / QQ，点查询。后端 /teacher_cardid_lookup/search 对教师库全字段匹配。
2. 批量查询：在「批量姓名 / 一卡通号」文本域粘贴多个值，支持空格、顿号、中英文逗号、换行混合分隔（re.split(r'[、,，\s]+', ...)），点「批量查询」（POST 到 /teacher_cardid_lookup）。结果按输入 token 的原始顺序逐条返回。
3. 复制回填：结果出现后显示「复制一卡通号」「复制电话」按钮，把对应列整列复制到剪贴板，便于粘回 Excel 表格。
4. 每个输入框旁有清除图标按钮，仅清空本框并隐藏对应的错误、结果与复制按钮，方便二次查询。

超管：附带用户与角色查询

超管使用同一个关键词框时，/teacher_cardid_lookup/search 除返回教师库结果外，还并行返回中央用户与角色范围（/teacher_cardid_lookup/users 仅超管可调，非超管 403）；一卡通号查询页对超管聚合全部学院教师库。

字段与状态口径

教师档案字段（Invigilator 表）：

「系室」文案：2026-06-01 起，本页面可见的「院系/系部」一律改称「系室」，覆盖筛选项、列名、编辑标签与系室维护面板；同期为关键必填字段加红色 * 标记。导入模板表头仍兼容「所在院系」列名。

删除替代「离校归档」（2026-06-02）：早期用「离校归档」特殊状态做软删过渡，现已改为直接删除教师记录。删除时会先把该教师基础信息写入其关联监考安排的备注快照（_append_assignment_teacher_snapshot），再清理这些安排记录，避免非空外键悬挂。前端已移除归档筛选、归档统计与「恢复在册」入口；_active_invigilator_filter() 仍兼容过滤历史遗留的「离校归档」标签，使旧数据不混入当前排班候选。

常见问题

• 登录后看不到「教师信息」菜单：当前学院须至少开通监考、课程归档、增免修、科学城出勤、教学课件报送之一；学院管理员只开通教学课件报送也应可见（历史漏算已修复）。学生角色一律不可见。
• 编辑/导入提示「XX 不能为空」：一卡通号、姓名、性别、手机、QQ、所在系室为必填，前后端双重校验，留空会被拦截。
• 新增提示「该一卡通号已存在」：一卡通号是唯一主键；同号一律按重复拦截，不再走「恢复在册」。如需改隶属请先在原学院删除该教师记录（一位教师只应保留在一个主学院教师库）。
• 删除教师会丢历史监考记录吗：删除会同步清理该教师关联的监考安排，但删除前已把教师基础信息写入各安排的备注快照留痕；这些通常是过去日期的安排。操作前系统会弹二次确认。
• 一卡通批量查询为什么保留空行：批量复制面向 Excel 粘贴回填，必须让输入项、结果行、粘贴行三者一一对应。若复制时过滤掉「未找到」或电话为空的行，会压缩行数，粘回表格后整列与原查询项错位。因此复制按结果表行数原样生成文本，未找到/缺手机号的位置保留空行；仅当整列完全无内容时才提示「没有可复制的数据」（2026-06-06 修复）。
• 批量框可以混填姓名和一卡通号吗：可以。支持姓名与一卡通号混合输入，用空格、顿号、中英文逗号或换行分隔，结果按输入顺序返回；同名多条会标注「同名教师多条」。
• 超管查到了别的学院教师：一卡通号查询对超管会聚合所有已配置学院库，属预期；普通管理员只查当前学院上下文。
• 预览账号不能编辑/导出：预览/只读账号被显式拦截写操作，且一卡通、电话、QQ 做脱敏显示。

相关页面

• 监考安排管理 监考排班复用本教师库（轮次、初始轮次、预安排、推荐、特殊状态过滤、系室维护）
• 用户管理 用户与角色管理；跨学院教师主学院归属、外院授课在此确认（与一卡通号查询的超管用户/角色结果互通）
• 科学城出勤统计 科学城出勤等模块同样以本教师库为基础数据来源