学生异动视图只读 API
从 MySQL 视图 vw_jw_student_change_export 拉取数据，供教务或其它系统调用。
- Python：开发与生产建议 3.7.9（与现网一致）。
- 依赖：见
requirements.txt（Flask 2.0.x + PyMySQL）。
配置文件与环境对应关系
| 本目录文件 | 后端配置来源 | 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 生产环境：pip3：未找到命令 / No module named pymysql
很多最小化系统只有 python3，没有独立的 pip3 命令。请用 当前解释器自带的 pip 模块 安装依赖，例如：
cd /path/to/api_service
# 1）优先尝试（与 python3 一一对应）
python3 -m pip install -r requirements.txt
# 若 `python3 -m pip` 报 No module named pip，先装系统级 pip（需 root）：
# CentOS 7 / 部分 RHEL：
# yum install -y python3-pip
# CentOS 8+ / RHEL 8+ / Fedora：
# dnf install -y python3-pip
# 装完再执行：
python3 -m pip install -r requirements.txt
# 若无 yum/dnf 或仓库无 python3-pip，可用官方引导脚本（任选其一 Python 版本需为 3.7+）：
# curl -sS https://bootstrap.pypa.io/pip/3.7/get-pip.py -o get-pip.py
# python3 get-pip.py
# python3 -m pip install -r requirements.txt
# （3.7 专用 get-pip 见：https://bootstrap.pypa.io/pip/3.7/get-pip.py ）
确认：
python3 -c "import pymysql, flask; print('ok')"
启动时请用 python3 app.py（或与安装依赖时相同的 python3），避免混用 python 指向旧版 2.x。
选用配置并启动
测试/开发（与 dev 库一致）：
cp config.dev.ini config.ini
python app.py
或直接：
export JW_CX_CONFIG="$(pwd)/config.dev.ini"
python app.py
生产：
export JW_CX_CONFIG=/opt/jw-cx/config.prod.ini
python app.py
配置文件说明
| 环境变量 | 说明 |
|---|---|
JW_CX_CONFIG |
配置文件路径；不设则使用当前工作目录下的 config.ini（相对路径相对于进程启动时的工作目录） |
模板见 config.ini.example。config.ini 已在 .gitignore 中忽略，避免把本地覆盖提交上去。
INI 节说明
[database]：host、port、user、password、database
[api]：
| 键 | 说明 |
|---|---|
api_key |
与请求头 X-Jw-Cx-Key 一致 |
bind_host / bind_port |
HTTP 监听（仅直接运行 python app.py 时生效） |
page_size |
默认每页条数；请求可带 page_size Query 覆盖，程序内限制 1～5000 |
recent_days |
默认近 N 天；请求可带 recent_days / days 覆盖，程序内限制 1～3660 |
密钥校验
所有 /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
监听地址/端口以 gunicorn 的 -b 为准；bind_port 仅对直接运行 python app.py 有效。
接口说明
GET /health
返回 {"status":"ok"}。
GET /api/v1/student-changes
数据范围：仅 提交时间 在最近 N 个自然日内的记录；N 由 recent_days（或 days）指定，未传则使用配置 [api] recent_days（默认 30）。
分页：每页条数 page_size 可传 Query 覆盖，未传则使用 [api] page_size（默认 500）。
| Query | 说明 | 未传时的默认值 |
|---|---|---|
page |
页码，从 1 开始 | 1 |
page_size |
每页条数，有效范围 1～5000 | [api] page_size |
recent_days |
查询近 N 天（与视图列「提交时间」比较），有效范围 1～3660 | [api] recent_days |
days |
与 recent_days 同义，二选一即可 |
（同上） |
成功响应中除 data、page、page_size、total 外，还包括：
| JSON 字段 | 说明 |
|---|---|
filter_recent_days |
本次请求实际生效的近 N 天（含 URL 覆盖后的值） |
filter_by_column |
固定为 提交时间（筛选字段名） |
未授权（HTTP 401）：未带或错误的 X-Jw-Cx-Key。
调用示例
# 使用配置中的 page_size、recent_days
curl -s -H "X-Jw-Cx-Key: JWCX001" \
"http://127.0.0.1:5050/api/v1/student-changes?page=1"
# 指定每页 50 条、近 7 天
curl -s -H "X-Jw-Cx-Key: JWCX001" \
"http://127.0.0.1:5050/api/v1/student-changes?page=1&page_size=50&recent_days=7"
安全说明
config.dev.ini/config.prod.ini含数据库凭据，与后端 YAML 同源；请按公司规范控制仓库可见性与部署权限。- 建议数据库侧使用仅对视图
vw_jw_student_change_export有SELECT的专用账号，与后端root分离。 - 生产将
api_key换为强随机串，并走 HTTPS；必要时加网络白名单。