hzdyjs/跟教务系统同步学生基础信息/学生基本信息对接说明.md

学生基本信息 — 教务对接说明

接口

项目	说明
路径	GET /api/v1/students
鉴权	Header X-Jw-Cx-Key
数据范围	全部 xg_student_msg.deleted = 0 的学生，分页返回
视图 DDL	docs/设计文档/database/vw_jw_student_export.sql
服务代码	跟教务系统同步学生异动信息/api_service/app.py（与异动接口同进程）

字段口径（已确认）

教务字段	口径
身份证件类型	有 id_card →「居民身份证」，否则 null
所在校区	有有效宿舍分配（xg_dorm_bed_student.status=0）→ xg_dorm_campus.campus_name，否则 null
班主任工号	class_teacher_id → sys_user.user_no，空则 user_name
学生是否在校	默认「在校」；学籍状态为 退学(4)、毕业(5) →「不在校」
异动类型	固定 null
毕业时间	年份整数。已毕业(5)：取 BI_YE 已处理异动的 effective_date 年份；否则 入学年份 + 学制（或班级 graduation_year）
毕业学年学期	{毕业年-1}-{毕业年}-2，例如 2025-2026-2；无法推算则为 null
学习经历 / 何年何月-何年何月 / 在何地学习	固定 null
在校照片	固定 null
性别	0→「男」，1→「女」
成员1	父亲姓名/关系「父亲」/ father_phone
成员2	母亲姓名/关系「母亲」/ mother_phone

学生当前状态映射（本系统 → 教务中文名）

本系统 student_status	本系统标签	接口输出（教务中文名）
1	在读	在读
2	休学	休学
3	复学	复学
4	退学	退学
5	毕业	毕业
6	不在籍	其他
7	结业	结业
8	停学	停学
9	分流	其他

教务附件2 字典值（供联调参考，接口当前输出中文名称）：

教务状态名称	字典值
在读	XSDQZT016
休学	XSDQZT015
退学	XSDQZT014
停学	XSDQZT013
复学	XSDQZT012
毕业	XSDQZT010
结业	XSDQZT009
其他	XSDQZT007

部署

# 1. 建视图
mysql -h <host> -u root -p hzdyjs_xg < docs/设计文档/database/vw_jw_student_export.sql

# 2. 重启 API（与异动接口相同进程）
export JW_CX_CONFIG=/path/to/config.prod.ini
python app.py

# 3. 调用示例
curl -s -H "X-Jw-Cx-Key: JWCX001" \
  "http://127.0.0.1:5050/api/v1/students?page=1&page_size=500"

响应含 total（总条数）、page、page_size、total_pages，教务可按页循环直至 page >= total_pages。

与异动接口关系

• 异动接口：/api/v1/student-changes?year=2026（按异动生效年份）
• 学生基本信息：/api/v1/students?page=1&page_size=500（分页，含 total / total_pages）
• 毕业时间在学生接口中仍可使用；毕业记录不再通过异动接口同步（异动接口已排除 BI_YE）