---
name: soloforge-code
description: 按切片实现生产代码与测试，并保持需求、设计和运行时行为一致。
when: 代码实现 / code / build 阶段
---

# 代码实现

## 适用性

测试计划和当前切片的上游契约已就绪后使用。若需要改变用户目标、公共 API、数据模型或发布拓扑，停止编码并先更新相应决策与产物。

## 事实输入

- 当前切片的目标、文件范围、依赖和验收契约。
- 需求、设计、适用的 API/数据/原型契约和测试计划。
- 现有代码规范、构建命令、测试框架和兼容约束。
- `examples.md` 的正反例。

## 关键决策

- 选择最小直接实现，避免为假想扩展引入层次、框架或通用引擎。
- 需求追踪通过测试名称、测试报告、变更清单或项目已有的追踪机制建立，不为了追踪向生产代码添加任务号注释。注释写"为什么"不复述"是什么"（公共 API 说明输入/输出/失败语义），注释中不出现任务编号/需求号/工单号的任何形式，不写日期+动作的变更日志（确定性源码扫描拦截）。
- 异常、重试、幂等、事务、权限和并发行为必须符合契约。

## 产出方法

1. 只实现当前切片，先写或确认失败测试，再完成最小生产实现。
2. 前端实现前必须打开该页原型锚点（原型说明素材证据表中的源码文件或可运行原型）：文案逐字迁移，表格列、操作集、状态集、弹窗/页面跳转等形态忠实迁移；原型说明文档只做业务规则校准与差异清单，不替代素材对照。
3. 后端实现前打开当前切片的上游契约锚点：接口对照 API 规格端点（路径、参数、字段、错误码），数据层对照数据库设计（表、列、约束），业务规则与状态机对照需求/设计编号；不得凭记忆或通用模板补契约。
4. 更新必要的配置、迁移、契约和文档，保持同一变更闭环。
5. 在测试计划、测试名称或报告中建立需求到行为和证据的映射；只有项目现有规范明确要求时才在代码中使用追踪标记。
6. 运行项目真实的格式化、类型检查、编译和测试命令。
7. **后端转换层禁手写 get/set 样板**：实体/DTO 用 Lombok（或项目已选等价方案）消实体样板；对象间转换用 MapStruct（或项目已选等价 mapper）等声明式映射消 DTO 转换样板——手写几十行 getX/setX 转换层是维护负担与错字段温床。ORM 选型（MyBatis-Plus/JPA 等）跟随项目既有决策，本条只约束"转换与样板"，不切换持久化栈。
8. **分层遵循 SOLID**（完整条文与正反例见知识资产「核心代码质量约束」）：Controller 只做参数绑定与响应组装、业务规则进 Service、数据访问止于 Repository/Mapper——单一职责不混层；依赖方向单向（外层依赖内层），高层依赖抽象不依赖具体实现，新依赖先确认方向不倒置；分支膨胀的类先拆策略/组合再继续加分支——第三种类型出现仍往同一 if-else 链加分支即违规。
9. **可维护性硬指标**：sf_verify full 的确定性源码扫描机械拦截四项——方法 ≤50 行、类 ≤300 行、参数 ≤5 个、控制流嵌套 ≤3 层；其余硬要求由审查承载：重复代码第 3 处出现前抽公共实现、魔法值常量化、异常明确类型不吞、日志带业务上下文。超标先拆分职责，确有合理场景（长映射表、生成代码）用 waiver 按 finding 精确豁免并注明理由，不用注释绕过。
10. **分层禁令（sf_verify full 确定性拦截）**：Controller 层禁 SQL 片段与事务注解（事务边界属 Service）；前端 HTTP 调用全部收敛到 api/ 模块，`.vue` 组件内禁直调 `axios`/`fetch`/`uni.request`/`wx.request`——改后端契约只动 api 层一处。
11. **前端组件通用化封装**：同形态第三处出现前抽出通用组件（表格页/表单弹窗/筛选栏/状态标签等），props/slots 驱动、无业务耦合、落项目的组件目录并登记用途；页面级差异不上提进通用组件。通用封装只承载无形态契约的机制（请求、分页逻辑、校验）；凡原型或契约有明确形态的区域（搜索区、Tab、工具栏、卡片、单据、弹窗形态、列结构）按原型/契约形态实现，不得用通用外壳覆盖。

## 禁止项

- 不得吞异常、返回假成功、留空实现、硬编码测试数据或绕过类型系统。
- 不得用注释、TODO 或 mock 结果冒充已实现行为。
- 不得顺手重构无关区域或修改未获授权的公共契约。
- 不得仅为通过检查复制模式；每个抽象必须有当前消费者和清晰边界。

## 交付自检

- 当前切片的每个验收点都有实现和可运行验证。
- 前端页完成五项对照：文案逐字、表格列、操作集、状态集、形态；后端完成契约对照：端点/字段/错误码、表列/约束、状态机与上游编号一致。
- 错误、边界、权限、并发和恢复路径没有只测成功分支。
- 新代码与模块边界、数据所有权和依赖方向一致。
- 没有未解释的跳过测试、宽松 catch 或伪造证据。

## 权威验证

调用 `sf_verify action="full" task_id="当前任务ID" artifact="code"`。完整验证会执行项目配置中适用的源码检查、编译、测试及上游证据新鲜度检查；需求到行为的追溯完整性还要由测试计划、测试报告和审查证据共同闭环。部署级运行证据在 deployment 就绪后取得。修复 findings 后必须重新 full verify。

## 交付前对抗审查

`sf_verify` 通过只证明结构/编译/测试层；代码的语义质量（主链路接入、异常/并发/权限/边界是否可靠、抽象是否必要）必须经独立对抗审查。在 advance/deliver 前，用 `sf_review action="start" task_id="当前任务ID" artifact="code"` 发起 per_artifact 审查，用**独立 session/subagent**（非产代码的同一会话）执行返回的 prompt、submit findings，按 next_step 完成 K 次独立采样与闭环。deliver 会阻断未完成/未闭环的审查。