From 22e69ccce14ddb255dda996bb557013b0df6302d Mon Sep 17 00:00:00 2001 From: QiuSW Date: Sat, 4 Jul 2026 23:13:00 +0800 Subject: [PATCH] docs: define flask factory and archive logging --- .gitignore | 4 +- AGENTS.md | 3 +- README.md | 1 + docs/00-ai-start-here.md | 5 ++- docs/02-requirements.md | 8 ++-- docs/03-tech-stack.md | 11 ++++- docs/04-architecture.md | 92 ++++++++++++++++++++++++++++++++++++++-- docs/05-coding-rules.md | 8 +++- docs/06-tasks.md | 11 ++--- docs/README.md | 4 +- docs/api.md | 1 + docs/current-state.md | 10 +++-- progress.md | 18 ++++++++ tasks.md | 2 +- 14 files changed, 154 insertions(+), 24 deletions(-) diff --git a/.gitignore b/.gitignore index 69850a1..19a749e 100644 --- a/.gitignore +++ b/.gitignore @@ -174,4 +174,6 @@ cython_debug/ # PyPI configuration file .pypirc -reverse_file/ \ No newline at end of file +reverse_file/ +logs/ +archives/ diff --git a/AGENTS.md b/AGENTS.md index 4d42b74..3f513e9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -45,7 +45,8 @@ 当前尚未有生产代码，暂以文件和文档检查为主： ```powershell -Get-ChildItem -Recurse -File +Get-ChildItem -Recurse -File # PowerShell +# bash 等价: find . -type f -not -path './.git/*' ``` 项目初始化后，必须把真实安装、测试和启动命令同步到 `docs/03-tech-stack.md`、`docs/05-coding-rules.md` 和 `docs/current-state.md`。 diff --git a/README.md b/README.md index 7a55a86..13c8dd4 100644 --- a/README.md +++ b/README.md @@ -28,6 +28,7 @@ - Python 版本目标：当前系统 Python 3.8，不创建虚拟环境。 - Web 框架目标：Flask 3.0.3。 +- Flask 结构：使用 application factory 模式，T-001 实现 `create_app(config_object=None)`。 - 依赖管理：T-001 创建 `requirements.txt`，使用 `python -m pip install -r requirements.txt` 安装到当前系统 Python 3.8 环境。 - 计划使用 Redis 保存 CHIS 会话缓存。 - 当前已有资料：`reverse_file/` 下的 CHIS 前端脚本、schema 和 HAR。 diff --git a/docs/00-ai-start-here.md b/docs/00-ai-start-here.md index 0d6a32e..fd6c9ab 100644 --- a/docs/00-ai-start-here.md +++ b/docs/00-ai-start-here.md @@ -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)。 diff --git a/docs/02-requirements.md b/docs/02-requirements.md index 7793ce5..1da7e7d 100644 --- a/docs/02-requirements.md +++ b/docs/02-requirements.md @@ -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 暴露。 diff --git a/docs/03-tech-stack.md b/docs/03-tech-stack.md index a327e99..00f105c 100644 --- a/docs/03-tech-stack.md +++ b/docs/03-tech-stack.md @@ -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 文件包含敏感原始数据，不得进入代码仓库或测试快照。 diff --git a/docs/04-architecture.md b/docs/04-architecture.md index 85722ef..c775333 100644 --- a/docs/04-architecture.md +++ b/docs/04-architecture.md @@ -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__req_.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、错误码和测试。 diff --git a/docs/05-coding-rules.md b/docs/05-coding-rules.md index ec7974b..2beafd3 100644 --- a/docs/05-coding-rules.md +++ b/docs/05-coding-rules.md @@ -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 补齐。 diff --git a/docs/06-tasks.md b/docs/06-tasks.md index 13dfa73..6c696b5 100644 --- a/docs/06-tasks.md +++ b/docs/06-tasks.md @@ -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 diff --git a/docs/README.md b/docs/README.md index 92bfc48..072c969 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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 登录代码和账号信息查询代码。 diff --git a/docs/api.md b/docs/api.md index f7286cc..4faf4eb 100644 --- a/docs/api.md +++ b/docs/api.md @@ -9,6 +9,7 @@ - 时间格式：`YYYY-MM-DD` 用于业务日期，时间戳使用 ISO 8601。 - 第三方鉴权：待定，推荐 `Authorization: Bearer ` 或 `X-App-Key` + `X-Signature`。 - 每个响应包含 `trace_id`。 +- 每个 API 请求都生成一个 archive 文件，保存 API 和 CHIS 请求 / 响应，详见 [架构设计](04-architecture.md) 的请求归档文件章节。 成功响应： diff --git a/docs/current-state.md b/docs/current-state.md index 5424895..93da48c 100644 --- a/docs/current-state.md +++ b/docs/current-state.md @@ -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/*' ``` ## 开始编码前检查 diff --git a/progress.md b/progress.md index 60e5737..67ecafc 100644 --- a/progress.md +++ b/progress.md @@ -52,3 +52,21 @@ - 阻塞：无。 - 决策：项目使用当前系统 Python 3.8，不创建虚拟环境；T-001 创建 `requirements.txt` 并固定 `Flask==3.0.3`；依赖安装命令使用 `python -m pip install -r requirements.txt`。 - 下一步：T-001 初始化 Flask 项目骨架。 + +## 2026-07-04 DOC-004 明确 Flask factory 模式 + +- 状态：DONE +- 变更：更新 `docs/03-tech-stack.md`、`docs/04-architecture.md`、`docs/06-tasks.md`、`docs/current-state.md` 和 `README.md`。 +- 验证：已执行 `rg` 检查 `factory`、`application factory`、`create_app`、`Flask 3.0.3` 等关键词，并执行 `git diff` 确认仅包含 Flask factory 模式相关文档变更。 +- 阻塞：无。 +- 决策：Flask 应用使用 application factory 模式；T-001 实现 `app/__init__.py:create_app(config_object=None)`；测试通过 factory 注入测试配置。 +- 下一步：T-001 初始化 Flask 项目骨架。 + +## 2026-07-04 DOC-005 明确日志与请求归档方案 + +- 状态：DONE +- 变更：更新 `.gitignore`、`docs/03-tech-stack.md`、`docs/04-architecture.md`、`docs/05-coding-rules.md`、`docs/02-requirements.md`、`docs/api.md`、`docs/06-tasks.md` 和 `docs/current-state.md`。 +- 验证：已执行 `rg` 检查 `logs/`、`archives/`、`不脱敏`、`保留 1 年`、`archive`、`原子写入`、`.gitignore`、`每天一个` 等关键词，并执行 `git diff` 检查日志与归档方案相关文档变更。 +- 阻塞：无。 +- 决策：运行日志写入 `logs/`，每天一个综合日志文件，包含多级别摘要日志，保留 1 年；每个 API 请求在 `archives/` 写入一个完整原始 JSON 归档文件，包含 `api` 和 `chis` 请求 / 响应数组，archive 不脱敏，仅用于内网前置机本地受控排查；`logs/` 和 `archives/` 不提交 git。 +- 下一步：T-001 初始化 Flask 项目骨架。 diff --git a/tasks.md b/tasks.md index a9e83b0..7970f81 100644 --- a/tasks.md +++ b/tasks.md @@ -13,7 +13,7 @@ MVP 起步。当前仓库已具备逆向资料和项目文档，尚未初始化 | T-001 | 初始化 Flask 项目骨架 | TODO | | T-002 | 建立基础配置与目录 | TODO | | T-003 | 建立最小测试框架 | TODO | -| T-101 | 接入用户提供的 CHIS 登录代码 | TODO | +| T-101 | 迁移 CHIS 登录链路 | TODO | | T-102 | 接入账号信息查询验证会话 | TODO | | T-103 | 实现 Redis 会话缓存 | TODO | | T-201 | 实现通用 CHIS jsonRequest client | TODO |