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

## 接口

| 项目 | 说明 |
|------|------|
| 路径 | `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`）