first commit

2026-07-25 23:45:09 +08:00
commit c7bd957e6f
47 changed files with 3870 additions and 0 deletions
@@ -0,0 +1,145 @@
+# 代码实现
+
+## 实现输入
+
+L2 编码以三份已确认文档为直接依据：
+
+```text
+01.需求分析.md
+02.技术实现方案.md
+03.冒烟与逻辑验证.md
+```
+
+确认需求版本、代码基线、开发工程和真实开发工作区。不得误在 `management/.../code/` 分析副本中开发。
+
+Agent 可以使用 `git status`、`git diff`、`git log` 等只读命令调查和 Review，但禁止执行 `git add`、`git commit`、`git push`。暂存、提交和推送均由用户完成；其他可能改变分支或历史的操作必须符合用户指示和安全规则。
+
+## 项目规范优先
+
+编码前调查：
+
+- `AGENTS.md`、`CLAUDE.md` 等 Agent 指令；
+- `README.md`、`CONTRIBUTING.md` 和架构文档；
+- `.editorconfig`、格式化、Lint、静态分析和构建配置；
+- 测试规范；
+- 当前模块和相邻同类代码。
+
+作用域更近的项目规则优先。没有书面规范时，从同一模块的同类近期实现中提炼惯例，不得凭单个偶然文件确定全局风格。
+
+保持目录、分层、命名、DTO/VO/Entity 划分、校验、异常、错误码、日志、权限、事务、数据访问、Redis、ES、消息、配置、依赖注入、注释和测试风格一致。
+
+保持风格不代表复制明显错误、过时代码或安全缺陷；发现问题时说明并采用最小安全处理。
+
+## 控制范围
+
+禁止借需求开发进行无关的：
+
+- 全工程格式化；
+- 大范围重命名；
+- 目录或框架替换；
+- 旧代码全面重构；
+- 注释清洗；
+- 个人偏好的设计模式改造；
+- 不必要的第三方依赖引入。
+
+新增依赖前检查项目已有能力、统一实现、兼容性、构建/部署/安全风险和必要性，并写入方案与实现记录。
+
+## 敏感信息保护
+
+- 不在代码、配置、需求文档、日志、测试记录或验证证据中写入密码、Token、Cookie、私钥、访问密钥和完整连接串。
+- 手机号、身份证、地址、客户数据和其他生产敏感信息必须脱敏。
+- 接口请求响应、数据库结果、日志和截图只保留验证所需字段。
+- 凭据通过项目认可的安全环境注入；缺少凭据时请求用户处理，不得创建或保存临时明文凭据。
+- 发现疑似密钥或生产敏感数据进入改动时，立即停止受影响工作并报告。
+
+## 实施顺序
+
+```text
+检查工作区、分支、Commit 和用户已有改动
+→ 读取项目规范
+→ 确认开发基线
+→ 按功能点和工程依赖实施
+→ 编写/更新自动化测试
+→ 构建和测试
+→ 对照冒烟用例自测
+→ 更新实现记录和 STATUS
+```
+
+多工程通常按照：
+
+```text
+数据脚本与公共模型
+→ 服务提供方
+→ 服务调用方
+→ 消息消费者
+→ 前端或外部接入方
+→ 联调
+```
+
+实际顺序以已确认方案为准。
+
+## TDD
+
+适合自动化的功能执行：
+
+```text
+建立失败测试
+→ 确认因目标能力缺失而失败
+→ 最小实现
+→ 测试通过
+→ 重构
+→ 相关回归
+```
+
+缺陷修复优先建立可复现问题的测试。外部环境导致无法标准测试先行时，记录原因并使用可执行替代验证。
+
+不得通过删除测试、弱化断言、跳过必要用例、吞异常或修改测试迎合错误实现来制造通过。
+
+## 方案偏差
+
+编码中发现方案不可行时：
+
+```text
+记录问题
+→ 判断需求和影响
+→ 更新 02
+→ 更新 03
+→ 必要时重开门禁
+→ 继续实现
+```
+
+接口契约、数据模型、涉及工程、业务流程、状态、权限、兼容性或需求范围变化时，必须先更新方案。仅私有结构调整且不改变这些内容时，写入实现记录即可。
+
+## `04.技术实现记录.md`
+
+记录实现事实，不复制整份方案：
+
+```markdown
+# ST-XXX 技术实现记录
+
+## 1. 实现信息
+- 需求版本：
+- 技术方案版本：
+- 开发工程：
+- 开发分支：
+- 实现前 Commit：
+- 实现后 Commit：
+- 当前状态：
+
+## 2. 功能实现状态
+| 功能编号 | 功能名称 | 涉及工程 | 实现状态 | 方案章节 | 备注 |
+|---|---|---|---|---|---|
+
+## 3. 工程及代码改动
+## 4. 数据模型改动
+## 5. 接口改动
+## 6. 自动化测试改动
+## 7. 与技术方案的差异
+## 8. 编译和测试结果
+## 9. 项目规范遵循情况
+## 10. 遗留问题及风险
+```
+
+项目规范遵循情况应列出已读取规范、参考实现、执行的格式/静态检查、差异和原因。
+
+实现完成仅表示代码准备进入 Review，不等于子任务最终完成。