nc/chisup
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: define flask factory and archive logging

Browse Source
This commit is contained in:
ila
2026-07-04 23:13:00 +08:00
parent 21dbdf81ed
commit 22e69ccce1
14 changed files with 154 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/00-ai-start-here.md
+3 -2
View File
@@ -22,7 +22,7 @@
## 固定开工流程
1. `pwd`：确认在 `D:\PythonP\chisup`。
1. `pwd`：确认在项目根目录（Windows 下为 `D:\PythonP\chisup`，WSL / bash 下为 `/mnt/d/PythonP/chisup`）。
2. 读 [../progress.md](../progress.md) 和 [current-state.md](current-state.md)。
3. 查看当前文件清单和最近改动；如果未来接入 git，先看 `git status` 和 `git log --oneline -5`。
4. 若已有项目代码，运行标准验证命令；如果还未初始化代码，先完成 Phase 0 任务。
@@ -67,7 +67,8 @@ MVP 不做：
当前尚未初始化代码，文档检查命令：
```powershell
Get-ChildItem -Recurse -File
Get-ChildItem -Recurse -File # PowerShell
# bash 等价: find . -type f -not -path './.git/*'
```
项目初始化后，把真实命令同步到 [03-tech-stack.md](03-tech-stack.md)、[05-coding-rules.md](05-coding-rules.md) 和 [current-state.md](current-state.md)。
docs/02-requirements.md
+5 -3
View File
@@ -30,7 +30,8 @@
| 会话有效性确认 | 通过账号信息查询或等价接口确认登录有效 | P0 |
| 体检详情只读查询 | 根据体检主键和必要关联参数查询 CHIS 体检详情 | P0 |
| 体检数据转换 | 将第三方输入转换为 CHIS `hcData` 等保存结构 | P0 |
| 通用 CHIS request | 统一处理超时、错误码、登录失效、日志脱敏 | P0 |
| 通用 CHIS request | 统一处理超时、错误码、登录失效、日志摘要和请求归档 | P0 |
| 日志与请求归档 | `logs/` 每天滚动保留 1 年；`archives/` 每请求一个完整原始归档文件 | P0 |
| 幂等控制 | 第三方重试不会重复创建体检记录 | P0 |
### 后续迭代
@@ -63,7 +64,8 @@
- 数据转换：最小体检样例能生成 CHIS 保存请求所需的 `hcData` 和相关数据块。
- CHIS 提交：能通过通用 request 提交到 CHIS 的目标接口，并返回 CHIS 业务结果。
- 幂等：相同幂等键重复提交不会重复创建记录。
- 日志：日志包含 trace_id、接口、耗时、结果，不包含明文密码、Cookie、完整身份证号。
- 日志：`logs/` 中每天一个综合日志文件，包含不同级别摘要日志，保留 1 年；日志包含 trace_id、接口、耗时、结果，不包含明文密码、Cookie、完整身份证号。
- 请求归档：`archives/` 中每个 API 请求生成一个 archive JSON 文件，文件名包含日期、trace_id、request_id 等唯一字段；内容包含 `api` 和 `chis` 请求 / 响应数组；archive 不脱敏，仅用于内网前置机本地受控排查。
## 六、范围边界与决策
@@ -84,4 +86,4 @@
- 第三方请求体：字段、字典、幂等键、账号引用方式待定。
- CHIS 保存接口：最终 `serviceId`、`method`、`schema`、`module` 和请求体需要用真实请求验证。
- 账号安全：是否允许第三方每次传 CHIS 账号密码需要业务确认；推荐平台配置账号，第三方只传机构或账号引用。
- 隐私合规：体检数据和身份证号属于敏感信息，日志、存储、传输必须脱敏和受控。
- 隐私合规：体检数据和身份证号属于敏感信息；运行日志必须摘要化，archive 按当前决策保存完整原始数据且不脱敏，因此必须受控访问、不进 git、不通过 API 暴露。
docs/03-tech-stack.md
+9 -2
View File
@@ -7,11 +7,13 @@
| 维度 | 选型 | 状态 | 理由 / 说明 |
| --- | --- | --- | --- |
| 运行时 | 当前系统 Python 3.8 | 已定 | 用户指定，不创建虚拟环境 |
| Web 框架 | Flask 3.0.3 | 已定 | 用户指定，适合轻量 API 服务 |
| Web 框架 | Flask 3.0.3 + application factory | 已定 | 用户指定 Flask 版本；factory 模式便于配置注入和测试 |
| 数据校验 | 待定，建议 Pydantic v1 或 Marshmallow | 待定 | Python 3.8 下需注意版本兼容 |
| HTTP 客户端 | 待定，建议 `requests.Session` | 待定 | CHIS 会话 cookie 管理简单稳定 |
| Redis 客户端 | 待定，建议 `redis-py` | 待定 | 保存 CHIS 会话、幂等和短期状态 |
| SM2 加密 | 待定，建议 `gmssl` | 待定 | 需兼容 `hans_chis.sm2.sm2_encrypt` 的 `CryptSM2(mode=0)` 行为 |
| 日志 | Python logging + TimedRotatingFileHandler | 已定 | `logs/` 每天一个综合日志文件，保留 1 年 |
| 请求归档 | 本地 JSON 文件 | 已定 | `archives/` 每个接口请求一个完整归档文件，部署在内网前置机，不脱敏 |
| 数据库 | 待定 | 待定 | MVP 可先只用 Redis；上报流水可能需要 MySQL / SQLite / PostgreSQL |
| 第三方鉴权 | 待定，建议 app_key + HMAC 或 Bearer Token | 待定 | 不建议第三方直接裸传 CHIS 账号密码 |
| 测试 | pytest | 建议 | 适合 mapper、client、service 单元测试 |
@@ -21,7 +23,10 @@
- Flask 3.0.3 + Python 3.8 已定，但 Python 3.8 生命周期已结束；如果部署环境允许，未来建议评估 Python 3.10+。
- 本项目使用当前系统 Python 3.8 环境，不创建虚拟环境；依赖仍必须写入 `requirements.txt` 并固定关键版本。
- Flask 应用必须使用 application factory 模式，即 `app/__init__.py` 暴露 `create_app(config_object=None)`；不要在模块导入时创建并配置全局业务 app。
- Redis 是会话缓存核心，不建议把 CHIS 会话保存在进程内存。
- 运行日志保存到 `logs/`，每天一个综合日志文件，包含 INFO/WARNING/ERROR/EXCEPTION 等级摘要，保留 1 年。
- 接口请求归档保存到 `archives/`，一个 API 请求一个 JSON archive 文件，文件内容保存完整 API 与 CHIS 请求 / 响应，不脱敏；该目录仅用于内网前置机本地审计排查，不提交 git。
- CHIS public key 从配置文件或环境变量读取；当前不依赖 `/chis/logon/publicKey` 动态获取。
- CHIS 登录代码来自 Django 项目参考实现，迁移到 Flask 时只复用登录链路、SM2 算法和请求形状，不复用 Django model/cache。
- 当前不引入异步队列，先跑通同步单条上报闭环；批量和重试队列放到 V2。
@@ -41,7 +46,8 @@
当前可用文档检查：
```powershell
Get-ChildItem -Recurse -File
Get-ChildItem -Recurse -File # PowerShell
# bash 等价: find . -type f -not -path './.git/*'
```
## 四、依赖纪律
@@ -50,3 +56,4 @@ Get-ChildItem -Recurse -File
- 不创建 `.venv`、`venv` 或其他项目虚拟环境目录；如需隔离，必须先更新本文并取得确认。
- 和 CHIS 登录、SM2/RSA/AES 加密相关的依赖必须由真实登录代码驱动，不要凭 HAR 猜；当前 SM2 参考 `hans_chis.sm2.sm2_encrypt`。
- 不允许在代码或 `.env.example` 中写真实 CHIS 地址、账号、密码、Cookie。
- `logs/` 和 `archives/` 必须加入 `.gitignore`；archive 文件包含敏感原始数据，不得进入代码仓库或测试快照。
docs/04-architecture.md
+89 -3
View File
@@ -10,6 +10,8 @@
| HTTPS JSON
v
Flask API / middleware
|
| create_app 注册 blueprint / middleware / config
|
| 参数校验、鉴权、幂等
v
@@ -29,10 +31,23 @@ Redis
|
v
基卫 CHIS *.jsonRequest / 登录接口
API / service / CHIS client
|
+--> logs/ # 每天一个综合运行日志，保留 1 年
|
+--> archives/ # 每个 API 请求一个完整原始归档 JSON，不脱敏
```
## 二、职责划分
**Flask application factory**
- `app/__init__.py` 暴露 `create_app(config_object=None)`。
- 在 factory 内加载配置、注册 blueprint、注册 middleware / error handler。
- 不在模块导入时读取真实 CHIS 凭证、连接 Redis 或发起外部请求。
- 测试通过 factory 注入测试配置和 fake / mock 组件。
**API / view**
- 接收第三方请求。
@@ -82,12 +97,23 @@ Redis
- 保存幂等键和处理结果摘要。
- 可保存短期锁，避免同一账号并发重登。
**logging / archive**
- `logs/` 保存运行日志：每天一个综合日志文件，包含 INFO、WARNING、ERROR、EXCEPTION 等不同级别记录，保留 1 年。
- 运行日志只记录摘要：`trace_id`、接口、耗时、状态、错误码、CHIS service/action、必要定位字段。
- `archives/` 保存请求归档：一个 API 请求一个 archive JSON 文件，保存该次 API 请求 / 响应以及期间所有 CHIS 请求 / 响应。
- archive 文件不脱敏，用于部署在内网前置机后的本地审计和故障排查。
- archive 写入不应影响主业务成功 / 失败判定；写入失败必须记入运行日志。
- archive 文件必须原子写入：先写 `.tmp`，完整落盘后 rename 为 `.json`。
- `logs/` 与 `archives/` 必须加入 `.gitignore`，不得进入代码仓库。
- 上线前必须评估磁盘容量；保留 1 年需要有清理任务或运维策略。
## 三、建议项目结构
```text
chisup/
├── app/
│ ├── __init__.py
│ ├── __init__.py # create_app(config_object=None)
│ ├── api/
│ │ └── health_check.py
│ ├── middleware/
@@ -107,6 +133,8 @@ chisup/
│ └── config.py
├── tests/
├── docs/
├── logs/ # 运行时生成，不提交 git
├── archives/ # 运行时生成，不提交 git，保存原始敏感归档
├── reverse_file/
├── requirements.txt
└── README.md
@@ -193,6 +221,64 @@ chisup/
注意：当前资料不能证明“只传 `healthCheck` 就能查详情”。若外部 API 要支持只传体检 id，需要先验证如何由 `healthCheck` 反查 `phrId`、`idCard`、`checkDate`、`empiId`、`createUser`。
### 4.5 请求归档文件
archive 文件按日期和接口分层保存，建议路径：
```text
archives/
└── YYYY/
└── MM/
└── DD/
└── api-name/
└── YYYYMMDD_HHMMSS_trace_<trace_id>_req_<request_id>.json
```
文件名至少包含：
- 日期时间。
- API 名称或安全化后的接口标识。
- `trace_id`。
- 第三方 `request_id`；没有时使用服务端生成的唯一值。
- 可选：`healthCheck` 等业务定位字段。
文件内容格式：
```json
{
"meta": {
"trace_id": "TRACE_ID",
"api": "POST /api/v1/health-checks/query-detail",
"request_id": "third-party-request-id",
"created_at": "2026-07-04T21:15:30+08:00",
"duration_ms": 1234,
"result": "success"
},
"api": [
{
"request": {},
"response": {}
}
],
"chis": [
{
"service_id": "chis.healthCheckService",
"service_action": "getHMNIListOfHTML",
"request": {},
"response": {},
"duration_ms": 456
}
]
}
```
约束：
- archive 保存完整原始数据，不脱敏。
- archive 目录只能在内网前置机本地受控访问，禁止通过 API 静态暴露。
- archive 中允许保存 CHIS 请求和响应原文，但不得提交到 git、测试快照或公开文档。
- archive 文件保留 1 年，过期清理策略后续在部署任务中落地。
## 五、关键技术难点
| 难点 | 说明 | 应对 |
@@ -202,7 +288,7 @@ chisup/
| 只传体检 id 查询详情 | `getHMNIListOfHTML` 还需要 `phrId` 和 `idCard` | 先要求调用方传全参数，后续验证反查链路 |
| 体检字段转换 | CHIS 前端保存逻辑复杂，数据块多 | 先做最小样例 mapper，逐步补字段测试 |
| 幂等 | 第三方重试可能导致重复体检记录 | 使用 `source + request_id` 或业务唯一键保存结果 |
| 隐私与日志 | 涉及身份证号、体检数据、账号凭证 | 统一脱敏，敏感字段禁止落日志 |
| 隐私与日志 / 归档 | 日志只存摘要，archive 保存完整原始敏感数据 | `logs/` 每天滚动且摘要化；`archives/` 不脱敏但本地受控、原子写入、保留 1 年、不进 git |
| CHIS 接口变化 | 逆向接口可能因版本变化失效 | client 层集中封装，转换层有测试样例 |
## 六、推荐开发顺序
@@ -216,4 +302,4 @@ chisup/
7. 定义第三方体检上报 API 和统一响应。
8. 实现最小体检 mapper。
9. 通过通用 CHIS request 提交最小样例。
10. 补幂等、日志脱敏、错误码和测试。
10. 补幂等、日志 / archive、错误码和测试。
docs/05-coding-rules.md
+6 -2
View File
@@ -13,7 +13,8 @@
## 1. 安全纪律
- 绝不把真实账号、密码、Cookie、token、内网地址写入代码、文档示例或测试快照。
- 日志必须脱敏：身份证号、姓名、手机号、账号、Cookie、密码、体检明细都要受控。
- 运行日志必须摘要化：身份证号、姓名、手机号、账号、Cookie、密码、体检明细不得进入 `logs/` 的普通日志正文。
- archive 归档文件按项目决策保存完整原始请求 / 响应且不脱敏，但只能写入 `archives/`，不得进入日志、git、测试快照或公开文档。
- 第三方传来的 CHIS 密码如果无法避免，只能在请求生命周期中使用，不得写日志，不得明文持久化。
- Redis 中不保存明文密码。
- 不绕过 CHIS 权限、角色、机构、验证码、风控或审计。
@@ -40,6 +41,8 @@
- CHIS 登录失败、会话失效、权限不足、参数错误、网络超时要有不同错误码。
- CHIS 返回未登录时最多自动重登一次，避免无限递归。
- 任何失败响应都要带 trace_id。
- archive 写入失败不能改变业务接口结果，但必须写入 `logs/` 运行日志。
- archive 文件必须先写临时文件再 rename，避免半截 JSON。
## 5. 测试与验证
@@ -53,7 +56,8 @@
当前文档阶段可运行：
```powershell
Get-ChildItem -Recurse -File
Get-ChildItem -Recurse -File # PowerShell
# bash 等价: find . -type f -not -path './.git/*'
```
代码阶段的真实命令待 T-001 补齐。
docs/06-tasks.md
+6 -5
View File
@@ -18,9 +18,9 @@
| ID | 任务 | 依赖 | 验收要点 | 状态 |
| --- | --- | --- | --- | --- |
| T-001 | 初始化 Flask 项目骨架 | - | 使用当前系统 Python 3.8，不创建虚拟环境；创建 `requirements.txt` 并固定 `Flask==3.0.3`；本地 health check API 可启动；真实命令同步到技术栈和当前状态 | TODO |
| T-001 | 初始化 Flask 项目骨架 | - | 使用当前系统 Python 3.8，不创建虚拟环境；创建 `requirements.txt` 并固定 `Flask==3.0.3`；使用 application factory 模式实现 `create_app(config_object=None)`；本地 health check API 可启动；真实命令同步到技术栈和当前状态 | TODO |
| T-002 | 建立基础配置与目录 | T-001 | 目录符合架构文档；配置从环境变量读取；无真实密钥 | TODO |
| T-003 | 建立最小测试框架 | T-001 | pytest 可运行；至少有 health check 或 app factory 测试 | TODO |
| T-003 | 建立最小测试框架 | T-001 | pytest 可运行；至少有 `create_app` / health check 测试，能通过测试配置创建 Flask app | TODO |
## Phase 1 · CHIS 登录与会话
@@ -62,9 +62,10 @@
| ID | 任务 | 依赖 | 验收要点 | 状态 |
| --- | --- | --- | --- | --- |
| T-501 | 补齐错误码和日志脱敏 | T-403 | 常见错误有统一 code；日志不包含明文敏感信息 | TODO |
| T-502 | 完整 MVP 验收 | T-501 | `02-requirements.md` 的 P0 验收全部通过 | TODO |
| T-503 | 部署运行文档 | T-502 | 新环境能按文档安装、配置、启动、验证 | TODO |
| T-501 | 补齐错误码和运行日志 | T-403 | 常见错误有统一 code；`logs/` 每天一个综合日志文件，包含多级别摘要日志，保留 1 年；普通日志不包含明文敏感信息 | TODO |
| T-502 | 实现请求 archive 归档 | T-501 | `archives/` 每个 API 请求一个 JSON 文件；文件名包含日期、trace_id、request_id 等唯一字段；内容包含 `api` 和 `chis` 请求 / 响应数组；archive 不脱敏、原子写入、不进 git | TODO |
| T-503 | 完整 MVP 验收 | T-502 | `02-requirements.md` 的 P0 验收全部通过 | TODO |
| T-504 | 部署运行文档 | T-503 | 新环境可按文档安装、配置、启动、验证；说明 `logs/` 和 `archives/` 保留 1 年、磁盘容量与清理策略 | TODO |
## Backlog
docs/README.md
+3 -1
View File
@@ -25,7 +25,9 @@
当前可用事实来源：
- `reverse_file/20260702_442525195910165439_create_health_check.har`：CHIS 登录、查询、体检相关请求样例。
- `reverse_file/20260702_442525195910165439_create_health_check.har`：CHIS 登录、查询、体检保存相关请求样例。
- `reverse_file/20260704_query_health_check.har`：体检详情只读查询 HAR，包含 `getHMNIListOfHTML` 和 `getCheckInfoDetail`，Phase 2 只读验证的主要事实来源。
- `reverse_file/20260704_sm2s.js`：CHIS 前端 SM2 加密脚本，做 T-101 登录与密码/时间戳加密时对照参考（当前 SM2 另参考 `hans_chis.sm2.sm2_encrypt`）。
- `reverse_file/chis.application.hc.script.HealthCheckHtmlForm.js`：CHIS 前端体检表单保存逻辑。
- `reverse_file/chis.application.hc.schemas.*.sc`：体检相关 schema 逆向资料。
- 后续用户提供的其他项目 CHIS 登录代码和账号信息查询代码。
docs/api.md
+1
View File
@@ -9,6 +9,7 @@
- 时间格式：`YYYY-MM-DD` 用于业务日期，时间戳使用 ISO 8601。
- 第三方鉴权：待定，推荐 `Authorization: Bearer <token>` 或 `X-App-Key` + `X-Signature`。
- 每个响应包含 `trace_id`。
- 每个 API 请求都生成一个 archive 文件，保存 API 和 CHIS 请求 / 响应，详见 [架构设计](04-architecture.md) 的请求归档文件章节。
成功响应：
docs/current-state.md
+7 -3
View File
@@ -6,7 +6,7 @@
- 日期：2026-07-04
- 阶段：MVP 起步 / 文档与逆向资料整理
- 技术栈：目标为当前系统 Python 3.8、Flask 3.0.3、Redis；代码尚未初始化；不创建虚拟环境
- 技术栈：目标为当前系统 Python 3.8、Flask 3.0.3 application factory、Redis；代码尚未初始化；不创建虚拟环境
- 生产代码：暂无
- 测试：暂无
- 数据 / 资料：`reverse_file/` 下已有 CHIS HAR、前端脚本和 schema；`D:\hans\chupd\chis\login_client_v2.py` 可作为登录链路参考
@@ -30,7 +30,7 @@
任务状态以 [06-tasks.md](06-tasks.md) 为准。
- 已完成：DOC-001 建立 harness coding 项目文档。
- 已完成：DOC-001 建立 harness coding 项目文档；DOC-002 更新 CHIS 登录与只读查询验证路线；DOC-003 明确使用系统 Python 3.8；DOC-004 明确 Flask factory 模式；DOC-005 明确日志与请求归档方案。详见 [../progress.md](../progress.md)。
- 正在进行：无。
- 下一个可领取任务：T-001 初始化 Flask 项目骨架。
@@ -38,16 +38,20 @@
- CHIS public key 可通过配置文件或环境变量提供。
- 使用当前系统 Python 3.8 环境，不创建虚拟环境；T-001 创建 `requirements.txt` 固定依赖。
- Flask 应用使用 application factory 模式，`app/__init__.py` 暴露 `create_app(config_object=None)`。
- 登录链路参考 `login_client_v2.py`：`myRoles` -> 选择 `责任医生助理` / `责任医生` -> `myApps` -> 拼接 cookie。
- SM2 加密参考 `hans_chis.sm2.sm2_encrypt`：`gmssl.sm2.CryptSM2(mode=0)`，返回带 `04` 前缀密文。
- 会话验证可用 `chis.myPageService / getLanderInfo`。
- 体检详情查询第一版可用 `healthCheck + phrId + idCard` 调 `getHMNIListOfHTML`，用 `idCard + checkDate` 调 `getCheckInfoDetail`。
- 当前不能证明只传 `healthCheck` 就能查完整详情。
- 运行日志保存到 `logs/`，每天一个综合日志文件，保留 1 年。
- 每个 API 请求保存一个 `archives/` JSON 归档文件，包含完整 API 和 CHIS 请求 / 响应，archive 不脱敏，仅用于内网前置机本地受控排查。
## 当前可运行内容
```powershell
Get-ChildItem -Recurse -File
Get-ChildItem -Recurse -File # PowerShell
# bash 等价: find . -type f -not -path './.git/*'
```
## 开始编码前检查