145 lines
4.5 KiB
Markdown
145 lines
4.5 KiB
Markdown
# 学生异动视图只读 API
|
||
|
||
从 MySQL 视图 `vw_jw_student_change_export` 拉取数据，供教务或其它系统调用。
|
||
|
||
- **Python**：开发与生产建议 **3.7.9**（与现网一致）。
|
||
- **依赖**：见 `requirements.txt`（Flask 2.0.x + PyMySQL）。
|
||
- **异动类型映射**：见上级目录 [`异动类型映射说明.md`](../异动类型映射说明.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。
|
||
|
||
## 安装
|
||
|
||
### 开发机（推荐虚拟环境）
|
||
|
||
```bash
|
||
cd 跟教务系统同步学生异动信息/api_service
|
||
python3.7 -m venv .venv
|
||
source .venv/bin/activate # Windows: .venv\Scripts\activate
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### Linux 生产环境
|
||
|
||
```bash
|
||
cd /path/to/api_service
|
||
python3 -m pip install -r requirements.txt
|
||
python3 -c "import pymysql, flask; print('ok')"
|
||
```
|
||
|
||
## 选用配置并启动
|
||
|
||
**测试/开发**：
|
||
|
||
```bash
|
||
cp config.dev.ini config.ini
|
||
python app.py
|
||
```
|
||
|
||
**生产**：
|
||
|
||
```bash
|
||
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 中携带：
|
||
|
||
```http
|
||
X-Jw-Cx-Key: <与配置文件中 [api] api_key 相同，默认 JWCX001>
|
||
```
|
||
|
||
**`/health`** 不做密钥校验。
|
||
|
||
## 生产进程（gunicorn）
|
||
|
||
```bash
|
||
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`。
|
||
|
||
## 调用示例
|
||
|
||
```bash
|
||
# 拉取当前自然年（如 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"
|
||
```
|
||
|
||
## 部署前：重建视图
|
||
|
||
代码更新后，请在目标库执行：
|
||
|
||
```bash
|
||
mysql -h <host> -u root -p hzdyjs_xg < docs/设计文档/database/vw_jw_student_change_export.sql
|
||
```
|
||
|
||
## 安全说明
|
||
|
||
1. `config.dev.ini` / `config.prod.ini` 含数据库凭据，请按公司规范控制仓库可见性与部署权限。
|
||
2. 建议数据库侧使用**仅对视图** `vw_jw_student_change_export` 有 `SELECT` 的专用账号，与后端 `root` 分离。
|
||
3. 生产将 **`api_key`** 换为强随机串，并走 HTTPS；必要时加网络白名单。
|