94 lines
3.8 KiB
Markdown
94 lines
3.8 KiB
Markdown
# 学生基本信息 — 教务对接说明
|
||
|
||
## 接口
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| 路径 | `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` |
|
||
| 所在校区 | 学生 `class_id` → `xg_class_msg.campus_id` → `xg_dorm_campus.campus_name`，再回退班级冗余 `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` |
|
||
| 培养层次 | 班级 `xg_class_msg.class_type` 字典值（`zsjy_education_level`），**非中文名称** |
|
||
| 系部信息 | 优先 `college_id` → `sys_dept.dept_name`（学生表，其次班级表），再回退冗余 `college_name` |
|
||
| 专业信息 | 优先 `major_id` → `sys_dept.dept_name`（学生表，其次班级表），再回退冗余 `major_name` |
|
||
| 班级信息 | `class_id` → `xg_class_msg.class_name`（优先班级表，再回退学生表冗余字段） |
|
||
|
||
## 培养层次字典值（`zsjy_education_level`）
|
||
|
||
| 字典值 | 中文名称 |
|
||
|--------|----------|
|
||
| 0 | 三年制中级技工 |
|
||
| 1 | 三年制技师 |
|
||
| 2 | 四年制高级工 |
|
||
| 3 | 五年制高级技工 |
|
||
| 4 | 六年制技师 |
|
||
| 5 | 中高职一体 |
|
||
|
||
## 学生当前状态映射（本系统 → 教务中文名）
|
||
|
||
| 本系统 `student_status` | 本系统标签 | 接口输出（教务中文名） |
|
||
|-------------------------|------------|------------------------|
|
||
| 1 | 在读 | 在读 |
|
||
| 2 | 休学 | 休学 |
|
||
| 3 | 复学 | 复学 |
|
||
| 4 | 退学 | 退学 |
|
||
| 5 | 毕业 | 毕业 |
|
||
| 6 | 不在籍 | 其他 |
|
||
| 7 | 结业 | 结业 |
|
||
| 8 | 停学 | 停学 |
|
||
| 9 | 分流 | 其他 |
|
||
|
||
教务附件2 字典值（供联调参考，接口当前输出**中文名称**）：
|
||
|
||
| 教务状态名称 | 字典值 |
|
||
|--------------|--------|
|
||
| 在读 | XSDQZT016 |
|
||
| 休学 | XSDQZT015 |
|
||
| 退学 | XSDQZT014 |
|
||
| 停学 | XSDQZT013 |
|
||
| 复学 | XSDQZT012 |
|
||
| 毕业 | XSDQZT010 |
|
||
| 结业 | XSDQZT009 |
|
||
| 其他 | XSDQZT007 |
|
||
|
||
## 部署
|
||
|
||
```bash
|
||
# 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`）
|