chisup/docs/05-coding-rules.md

编码规则（Coding Rules）

每次写代码前先读完本文件。与技术细节冲突时，以 技术栈 / 架构设计 的事实为准；与范围冲突时，以 需求 为准。

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、api.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 测试：鉴权失败、参数失败、幂等重复、成功提交。

当前文档阶段可运行：

Get-ChildItem -Recurse -File          # PowerShell
# bash 等价: find . -type f -not -path './.git/*'

代码阶段的真实命令待 T-001 补齐。

6. 绝不

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