201 lines
6.6 KiB
Markdown
201 lines
6.6 KiB
Markdown
# 教务同步只读 API（学生异动 + 学生基本信息）
|
||
|
||
供教务或其它系统调用，**对外接口说明见 [`接口调用说明.md`](./接口调用说明.md)**。
|
||
|
||
- **学生异动**：视图 `vw_jw_student_change_export` → `GET /api/v1/student-changes`
|
||
- **学生基本信息**：视图 `vw_jw_student_export` → `GET /api/v1/students`
|
||
|
||
- **Python**：开发与生产建议 **3.7.9**（与现网一致）。
|
||
- **依赖**：见 `requirements.txt`（Flask 2.0.x + PyMySQL）。
|
||
- **异动类型映射**：见 [`异动类型映射说明.md`](../异动类型映射说明.md)
|
||
- **学生基本信息口径**：见 [`学生基本信息对接说明.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` 未传时）；未配置则当前自然年 |
|
||
| `page_size` | 学生基本信息接口默认每页条数；请求可带 `page_size` 覆盖，范围 1～5000 |
|
||
|
||
## 密钥校验
|
||
|
||
所有 **`/api/v1/*`** 业务接口必须在 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` |
|
||
| 异动类型 | **教务中文名称**（退学、休学、复学、转班级） |
|
||
| 申请人学号 / 姓名 | |
|
||
| 异动前/后 年级、院系、专业、班级、学制 | 院系/专业优先 `sys_dept`；班级优先 `xg_class_msg`；学籍异动「前」优先历史快照 |
|
||
| 异动前/后 所在校区 | 班级 `campus_id` → `xg_dorm_campus.campus_name`，再回退班级 `campus_name` |
|
||
| 异动后班主任工号 / 姓名 | |
|
||
| 新名字 | 本系统无改名流水，为 `null` |
|
||
| 审核状态 | 固定「已通过」 |
|
||
|
||
成功响应元数据：
|
||
|
||
| JSON 字段 | 说明 |
|
||
|-----------|------|
|
||
| `total` | 本次返回的记录总数（等于 `data` 数组长度） |
|
||
| `filter_year` | 本次请求实际生效的筛选年份 |
|
||
| `filter_by_column` | 固定为 `异动生效时间` |
|
||
|
||
**未授权**（HTTP 401）：未带或错误的 `X-Jw-Cx-Key`。
|
||
|
||
### GET `/api/v1/students`
|
||
|
||
**数据范围**：全部未逻辑删除的学生（`xg_student_msg.deleted = 0`），**分页返回**。
|
||
|
||
| Query | 说明 | 未传时的默认值 |
|
||
|--------|------|------------------|
|
||
| `page` | 页码，从 1 开始 | `1` |
|
||
| `page_size` | 每页条数，有效范围 1～5000 | `[api] page_size`（默认 500） |
|
||
|
||
成功响应元数据：
|
||
|
||
| JSON 字段 | 说明 |
|
||
|-----------|------|
|
||
| `total` | 符合条件的记录总数 |
|
||
| `page` | 当前页码 |
|
||
| `page_size` | 本页大小 |
|
||
| `total_pages` | 总页数（`ceil(total / page_size)`） |
|
||
|
||
字段口径见 [`学生基本信息对接说明.md`](../../跟教务系统同步学生基础信息/学生基本信息对接说明.md)。
|
||
|
||
**拉取全量示例**（教务侧循环）：
|
||
|
||
```python
|
||
page = 1
|
||
while True:
|
||
resp = get(f"/api/v1/students?page={page}&page_size=500")
|
||
# 处理 resp["data"]
|
||
if page >= resp["total_pages"]:
|
||
break
|
||
page += 1
|
||
```
|
||
|
||
## 调用示例
|
||
|
||
```bash
|
||
# 异动：当前自然年全部
|
||
curl -s -H "X-Jw-Cx-Key: JWCX001" \
|
||
"http://127.0.0.1:5050/api/v1/student-changes?year=2026"
|
||
|
||
# 学生基本信息：分页（第 1 页，默认每页 500 条）
|
||
curl -s -H "X-Jw-Cx-Key: JWCX001" \
|
||
"http://127.0.0.1:5050/api/v1/students?page=1"
|
||
|
||
# 指定每页 1000 条、第 2 页
|
||
curl -s -H "X-Jw-Cx-Key: JWCX001" \
|
||
"http://127.0.0.1:5050/api/v1/students?page=2&page_size=1000"
|
||
```
|
||
|
||
## 部署前：重建视图
|
||
|
||
```bash
|
||
mysql -h <host> -u root -p hzdyjs_xg < docs/设计文档/database/vw_jw_student_change_export.sql
|
||
mysql -h <host> -u root -p hzdyjs_xg < docs/设计文档/database/vw_jw_student_export.sql
|
||
```
|
||
|
||
## 联调测试脚本
|
||
|
||
仅调用两个业务接口（学生基本信息、学生异动）并打印结果：
|
||
|
||
```bash
|
||
cd 跟教务系统同步学生异动信息/api_service
|
||
|
||
# 生产
|
||
python test_jw_cx_api.py --prod
|
||
|
||
# 若 Nginx 带路径前缀
|
||
python test_jw_cx_api.py --base-url http://web.hzdyjsxy.cn:18081/jw-cx-api --year 2026
|
||
```
|
||
|
||
脚本仅依赖 Python 标准库；详见 `test_jw_cx_api.py --help`。
|
||
|
||
## 安全说明
|
||
|
||
1. `config.dev.ini` / `config.prod.ini` 含数据库凭据，请按公司规范控制仓库可见性与部署权限。
|
||
2. 建议数据库侧使用**仅对视图** `vw_jw_student_change_export`、`vw_jw_student_export` 有 `SELECT` 的专用账号，与后端 `root` 分离。
|
||
3. 生产将 **`api_key`** 换为强随机串，并走 HTTPS；必要时加网络白名单。
|