提交
This commit is contained in:
zlwu committed
1 parent
a88d87047d
commit
c0de1b9bef
19 files changed
+17083
-202
No files matched your search
@@ -4,6 +4,7 @@
|
||||
|
||||
- **Python**：开发与生产建议 **3.7.9**（与现网一致）。
|
||||
- **依赖**：见 `requirements.txt`（Flask 2.0.x + PyMySQL）。
|
||||
- **异动类型映射**：见上级目录 [`异动类型映射说明.md`](../异动类型映射说明.md)
|
||||
|
||||
## 配置文件与环境对应关系
|
||||
|
||||
@@ -25,55 +26,23 @@ source .venv/bin/activate # Windows: .venv\Scripts\activate
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
### Linux 生产环境：`pip3：未找到命令` / `No module named pymysql`
|
||||
|
||||
很多最小化系统只有 `python3`，没有独立的 **`pip3`** 命令。请用 **当前解释器自带的 pip 模块** 安装依赖，例如：
|
||||
### Linux 生产环境
|
||||
|
||||
```bash
|
||||
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 ）
|
||||
```
|
||||
|
||||
确认：
|
||||
|
||||
```bash
|
||||
python3 -c "import pymysql, flask; print('ok')"
|
||||
```
|
||||
|
||||
启动时请用 **`python3 app.py`**（或与安装依赖时相同的 `python3`），避免混用 `python` 指向旧版 2.x。
|
||||
|
||||
## 选用配置并启动
|
||||
|
||||
**测试/开发**（与 dev 库一致）：
|
||||
**测试/开发**：
|
||||
|
||||
```bash
|
||||
cp config.dev.ini config.ini
|
||||
python app.py
|
||||
```
|
||||
|
||||
或直接：
|
||||
|
||||
```bash
|
||||
export JW_CX_CONFIG="$(pwd)/config.dev.ini"
|
||||
python app.py
|
||||
```
|
||||
|
||||
**生产**：
|
||||
|
||||
```bash
|
||||
@@ -81,14 +50,6 @@ 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`
|
||||
@@ -98,8 +59,7 @@ python app.py
|
||||
|----|------|
|
||||
| `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 |
|
||||
| `default_year` | **默认筛选年份**（按视图列「异动生效时间」）；未配置则使用当前自然年；请求可带 `year` 覆盖 |
|
||||
|
||||
## 密钥校验
|
||||
|
||||
@@ -119,8 +79,6 @@ 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`
|
||||
@@ -129,39 +87,58 @@ gunicorn -w 2 -b 0.0.0.0:5050 app:app
|
||||
|
||||
### GET `/api/v1/student-changes`
|
||||
|
||||
**数据范围**：仅 **`提交时间` 在最近 N 个自然日内**的记录；N 由 **`recent_days`**（或 `days`）指定，**未传则使用配置** `[api] recent_days`（默认 30）。
|
||||
**分页**：每页条数 **`page_size`** 可传 Query 覆盖，**未传则使用** `[api] page_size`（默认 500）。
|
||||
**数据范围**：**`异动生效时间` 落在指定自然年**内的已办结记录，**一次返回全部**（不分页）；年份由 **`year`** 指定，**未传则使用当前自然年**（或配置 `default_year`）。
|
||||
|
||||
| Query | 说明 | 未传时的默认值 |
|
||||
|--------|------|------------------|
|
||||
| `page` | 页码，从 1 开始 | `1` |
|
||||
| `page_size` | 每页条数，有效范围 1～5000 | `[api] page_size` |
|
||||
| `recent_days` | 查询近 N 天（与视图列「提交时间」比较），有效范围 1～3660 | `[api] recent_days` |
|
||||
| `days` | 与 `recent_days` 同义，二选一即可 | （同上） |
|
||||
| `year` | 按「异动生效时间」所在自然年筛选，有效范围 2000～2100 | 当前自然年 |
|
||||
|
||||
成功响应中除 `data`、`page`、`page_size`、`total` 外，还包括：
|
||||
**响应 `data` 每条记录字段**（与教务对接清单一致）：
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| 提交时间 | `YYYY-MM-DD` |
|
||||
| 异动生效学期 | 本系统无数据，为 `null` |
|
||||
| 异动类型 | **教务中文名称**（退学、休学、复学、转班级） |
|
||||
| 申请人学号 / 姓名 | |
|
||||
| 异动前/后 年级、院系、专业、班级、学制 | 学籍异动「前」优先取处理前快照 |
|
||||
| 异动前/后 所在校区 | 本系统无数据，为 `null` |
|
||||
| 异动后班主任工号 / 姓名 | |
|
||||
| 新名字 | 本系统无改名流水，为 `null` |
|
||||
| 审核状态 | 固定「已通过」 |
|
||||
|
||||
成功响应元数据：
|
||||
|
||||
| JSON 字段 | 说明 |
|
||||
|-----------|------|
|
||||
| `filter_recent_days` | **本次请求实际生效**的近 N 天（含 URL 覆盖后的值） |
|
||||
| `filter_by_column` | 固定为 `提交时间`（筛选字段名） |
|
||||
| `total` | 本次返回的记录总数（等于 `data` 数组长度） |
|
||||
| `filter_year` | 本次请求实际生效的筛选年份 |
|
||||
| `filter_by_column` | 固定为 `异动生效时间` |
|
||||
|
||||
**未授权**（HTTP 401）：未带或错误的 `X-Jw-Cx-Key`。
|
||||
|
||||
## 调用示例
|
||||
|
||||
```bash
|
||||
# 使用配置中的 page_size、recent_days
|
||||
# 拉取当前自然年（如 2026）全部异动
|
||||
curl -s -H "X-Jw-Cx-Key: JWCX001" \
|
||||
"http://127.0.0.1:5050/api/v1/student-changes?page=1"
|
||||
"http://127.0.0.1:5050/api/v1/student-changes"
|
||||
|
||||
# 指定每页 50 条、近 7 天
|
||||
# 指定 2026 年
|
||||
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"
|
||||
"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` 含数据库凭据，与后端 YAML 同源；请按公司规范控制仓库可见性与部署权限。
|
||||
1. `config.dev.ini` / `config.prod.ini` 含数据库凭据，请按公司规范控制仓库可见性与部署权限。
|
||||
2. 建议数据库侧使用**仅对视图** `vw_jw_student_change_export` 有 `SELECT` 的专用账号，与后端 `root` 分离。
|
||||
3. 生产将 **`api_key`** 换为强随机串，并走 HTTPS；必要时加网络白名单。
|
||||
Reference in new issue
Block a user