cykj/hzdyjs

0 Fork 0

Files

T

zlwu c0de1b9bef 提交

2026-06-26 15:30:24 +08:00

4.5 KiB

Raw Blame History

学生异动视图只读 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；必要时加网络白名单。

4.5 KiB Raw Blame History Unescape Escape