学生异动视图只读 API
从 MySQL 视图 vw_jw_student_change_export 拉取数据，供教务或其它系统调用。
- Python：开发与生产建议 3.7.9（与现网一致）。
- 依赖：见
requirements.txt（Flask 2.0.x + PyMySQL）。 - 异动类型映射：见上级目录
异动类型映射说明.md
配置文件与环境对应关系
| 本目录文件 | 后端配置来源 | Spring 环境 |
|---|---|---|
config.dev.ini |
backend/ruoyi-admin/src/main/resources/application-dev.yml（spring.datasource.dynamic.datasource.master） |
dev（测试/开发） |
config.prod.ini |
backend/ruoyi-admin/src/main/resources/application-prod.yml（同上） |
prod（生产） |
主机、端口、库名、用户名、密码已与上述 YAML 中 master 数据源保持一致；后端配置变更时请同步修改对应 INI。
安装
开发机（推荐虚拟环境）
cd 跟教务系统同步学生异动信息/api_service
python3.7 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt
Linux 生产环境
cd /path/to/api_service
python3 -m pip install -r requirements.txt
python3 -c "import pymysql, flask; print('ok')"
选用配置并启动
测试/开发：
cp config.dev.ini config.ini
python app.py
生产：
export JW_CX_CONFIG=/opt/jw-cx/config.prod.ini
python app.py
INI 节说明
[database]：host、port、user、password、database
[api]：
| 键 | 说明 |
|---|---|
api_key |
与请求头 X-Jw-Cx-Key 一致 |
bind_host / bind_port |
HTTP 监听（仅直接运行 python app.py 时生效） |
default_year |
默认筛选年份（按视图列「异动生效时间」）；未配置则使用当前自然年；请求可带 year 覆盖 |
密钥校验
所有 /api/v1/student-changes 请求必须在 HTTP Header 中携带：
X-Jw-Cx-Key: <与配置文件中 [api] api_key 相同，默认 JWCX001>
/health 不做密钥校验。
生产进程（gunicorn）
pip install 'gunicorn>=20.1.0,<21'
export JW_CX_CONFIG=/path/to/config.prod.ini
gunicorn -w 2 -b 0.0.0.0:5050 app:app
接口说明
GET /health
返回 {"status":"ok"}。
GET /api/v1/student-changes
数据范围：异动生效时间 落在指定自然年内的已办结记录，一次返回全部（不分页）；年份由 year 指定，未传则使用当前自然年（或配置 default_year）。
| Query | 说明 | 未传时的默认值 |
|---|---|---|
year |
按「异动生效时间」所在自然年筛选，有效范围 2000～2100 | 当前自然年 |
响应 data 每条记录字段（与教务对接清单一致）：
| 字段 | 说明 |
|---|---|
| 提交时间 | YYYY-MM-DD |
| 异动生效学期 | 本系统无数据，为 null |
| 异动类型 | 教务中文名称（退学、休学、复学、转班级） |
| 申请人学号 / 姓名 | |
| 异动前/后 年级、院系、专业、班级、学制 | 学籍异动「前」优先取处理前快照 |
| 异动前/后 所在校区 | 本系统无数据，为 null |
| 异动后班主任工号 / 姓名 | |
| 新名字 | 本系统无改名流水，为 null |
| 审核状态 | 固定「已通过」 |
成功响应元数据：
| JSON 字段 | 说明 |
|---|---|
total |
本次返回的记录总数（等于 data 数组长度） |
filter_year |
本次请求实际生效的筛选年份 |
filter_by_column |
固定为 异动生效时间 |
未授权（HTTP 401）：未带或错误的 X-Jw-Cx-Key。
调用示例
# 拉取当前自然年（如 2026）全部异动
curl -s -H "X-Jw-Cx-Key: JWCX001" \
"http://127.0.0.1:5050/api/v1/student-changes"
# 指定 2026 年
curl -s -H "X-Jw-Cx-Key: JWCX001" \
"http://127.0.0.1:5050/api/v1/student-changes?year=2026"
部署前：重建视图
代码更新后，请在目标库执行：
mysql -h <host> -u root -p hzdyjs_xg < docs/设计文档/database/vw_jw_student_change_export.sql
安全说明
config.dev.ini/config.prod.ini含数据库凭据，请按公司规范控制仓库可见性与部署权限。- 建议数据库侧使用仅对视图
vw_jw_student_change_export有SELECT的专用账号，与后端root分离。 - 生产将
api_key换为强随机串，并走 HTTPS；必要时加网络白名单。