68 lines
2.8 KiB
Markdown
68 lines
2.8 KiB
Markdown
# 编码规则（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、密码、体检明细都要受控。
|
||
- 第三方传来的 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。
|
||
|
||
## 5. 测试与验证
|
||
|
||
项目初始化后至少建立：
|
||
|
||
- mapper 单元测试：输入第三方样例，输出 CHIS 请求体。
|
||
- auth 测试：登录成功、登录失败、会话有效、会话失效。
|
||
- client 测试：超时、CHIS 错误码、未登录重登。
|
||
- API 测试：鉴权失败、参数失败、幂等重复、成功提交。
|
||
|
||
当前文档阶段可运行：
|
||
|
||
```powershell
|
||
Get-ChildItem -Recurse -File
|
||
```
|
||
|
||
代码阶段的真实命令待 T-001 补齐。
|
||
|
||
## 6. 绝不
|
||
|
||
- 绝不为了跑通而吞掉 CHIS 错误。
|
||
- 绝不把未验证字段标为必然正确。
|
||
- 绝不在没有幂等策略时开放生产上报。
|
||
- 绝不擅自删除 `reverse_file/` 中的逆向资料。
|
||
- 绝不使用破坏性 git 或文件命令清理用户文件。
|