chisup/docs/05-coding-rules.md

# 编码规则（Coding Rules）

> 每次写代码前先读完本文件。与技术细节冲突时，以 [技术栈](03-tech-stack.md) / [架构设计](04-architecture.md) 的事实为准；与范围冲突时，以 [需求](02-requirements.md) 为准。

## 0. 黄金法则

1. 不臆造：CHIS 字段、接口、登录参数、错误码，不确定就查证或询问。
2. 守范围：MVP 只做体检上报闭环。
3. 照架构：view、service、mapper、CHIS client、auth、repository 分层清楚。
4. 小步改：一次只解决一个任务，不夹带无关重构。
5. 可验证：改完必须能运行对应测试或说明无法验证原因。

## 1. 安全纪律

- 绝不把真实账号、密码、Cookie、token、内网地址写入代码、文档示例或测试快照。
- 运行日志必须摘要化：身份证号、姓名、手机号、账号、Cookie、密码、体检明细不得进入 `logs/` 的普通日志正文。
- archive 归档文件按项目决策保存完整原始请求 / 响应且不脱敏，但只能写入 `archives/`，不得进入日志、git、测试快照或公开文档。
- 第三方传来的 CHIS 密码如果无法避免，只能在请求生命周期中使用，不得写日志，不得明文持久化。
- Redis 中不保存明文密码。
- 不绕过 CHIS 权限、角色、机构、验证码、风控或审计。

## 2. 事实来源纪律

- CHIS 登录事实以后续用户提供代码为准。
- CHIS 体检保存结构以真实 HAR、`HealthCheckHtmlForm.js` 和 schema 验证为准。
- 不能因为字段名“看起来像”就写入 mapper。
- 数据结构变化必须同步更新 [04-architecture.md](04-architecture.md)、[api.md](api.md) 和 [current-state.md](current-state.md)。

## 3. 分层纪律

- API / view 不写字段转换和 HTTP 细节。
- middleware 不直接拼 CHIS 请求。
- service 负责流程编排，不负责底层 HTTP。
- mapper 只做数据转换，不访问 Redis 和 CHIS。
- CHIS client 不理解第三方业务字段。
- repository 只负责存取，不写业务判断。

## 4. 错误处理

- 所有外部请求必须设置 timeout。
- CHIS 登录失败、会话失效、权限不足、参数错误、网络超时要有不同错误码。
- CHIS 返回未登录时最多自动重登一次，避免无限递归。
- 任何失败响应都要带 trace_id。
- 访问 CHIS 的外部请求必须统一经过 CHIS client；不得在 auth、service 或 mapper 中绕过 client 单独发请求，避免遗漏 timeout、cookie、proxy、日志和 archive 逻辑。
- `CHIS_PROXY` 为空时必须直连；有值时 CHIS 登录、会话验证、只读查询和保存请求都必须走同一代理配置。
- archive 写入失败不能改变业务接口结果，但必须写入 `logs/` 运行日志。
- archive 文件必须先写临时文件再 rename，避免半截 JSON。

## 5. 测试与验证

项目初始化后至少建立：

- mapper 单元测试：输入第三方样例，输出 CHIS 请求体。
- auth 测试：登录成功、登录失败、会话有效、会话失效。
- client 测试：超时、CHIS 错误码、未登录重登。
- API 测试：鉴权失败、参数失败、幂等重复、成功提交。

当前标准测试命令：

```powershell
python -m pytest
```

必要时可补充运行 `python -m unittest discover -s tests`，但 T-003 之后以 pytest 为主测试入口。

## 6. 绝不

- 绝不为了跑通而吞掉 CHIS 错误。
- 绝不把未验证字段标为必然正确。
- 绝不在没有幂等策略时开放生产上报。
- 绝不擅自删除 `reverse_file/` 中的逆向资料。
- 绝不使用破坏性 git 或文件命令清理用户文件。