docs: define flask factory and archive logging

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_<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、错误码和测试。