# 代码实现

## 实现输入

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，不等于子任务最终完成。