soloforge 1.1.46 → 1.1.48

package/templates/build//346/265/213/350/257/225/344/274/230/345/205/210/347/274/226/347/240/201.md

@@ -1,99 +1,70 @@
 ---
-id: ka-procedure-测试优先编码工作流
+id: ka-guidance-测试优先编码
 kind: guidance
 title: 测试优先编码
 sync_policy: copy_to_project
 status: active
 triggers:
-  - 实现需求
-  - 编码
-  - 开发功能
-  - 写代码
-  - coding
-  - test first
-  - 测试优先
+  - 测试
+  - TDD
+  - 覆盖率
+  - 单元测试
   - 先写测试
+  - 测试优先
+  - test first
+  - 测试驱动
+  - 写测试
 extra:
-  name: test-first-coding-workflow
-  type: procedure
+  name: test-first-coding
   scope:
-    - backend
-    - frontend
+    - '*'
   products:
     - '*'
-  consumed_contracts:
-    - coding_readiness_contract_entry
-    - existing_system_analysis_contract_entry
-    - architecture_design_contract_entry
-    - detail_discipline_contract
-    - first_principles_contract
-  required_sections:
-    - 编码准备门
-    - 测试优先计划
-    - 约束消费报告
-    - 主线消费检查
-    - 编码完成审查
-  hard_rules:
-    - coding workflow 不得直接进入实现
-    - 必须先生成 CodingReadinessGate
-    - 必须先生成 TestFirstPlan 或合法 not_applicable_with_reason
-    - 有测试框架且行为可断言时，必须先写失败测试或回归测试
-    - readiness_status=blocked/manual_required 时不得写实现代码
-    - 现有项目新需求必须消费 ExistingSystemAnalysis 和 RequirementGapAnalysis
-    - 根据架构设计编码时必须消费 ArchitectureDesignContract
-    - 测试失败不得删除测试、降低断言、skip 后声称通过
-    - 每个切片至少覆盖 ≥9 个测试场景（≥3 正常路径 + ≥3 边界条件 + ≥3 异常路径）
-    - 模式 B 不得用于支付/状态流转/权限/跨系统同步逻辑
-  acceptance_checks:
-    - CodingReadinessGate status 非 blocked
-    - TestFirstPlan 已创建且 status 为 written 或 expected_failure_recorded
-    - 约束消费报告无 blocking_missing_constraints
-    - 主线消费检查无 orphan_findings
-    - 编码完成审查 review.passed 为 true
+  type: procedure
   lifecycle_status: active
-  version: 1.2.0
-  last_reviewed: '2026-06-04'
-  domain: build
+  version: 1.0.0
+  last_reviewed: '2026-06-17'
   verification_layer: L2
   stage: build
+  domain: build
   owner_mechanism: mc-coding-readiness
 ---
 
-## 适用场景
-任何编码实现前必须先通过编码准备门和测试优先计划。适用于有测试框架和可断言业务逻辑的项目。
+# 测试优先编码：怎么让代码可验证
+
+> 吸收旧的「测试优先编码」「覆盖率标准」「测试质量」。
+> [[工程执行总纲]] 目标驱动：先定可验证目标，未执行验证不算完成。
+
+## 何时必须先写测试
+
+- 有测试框架且行为可断言时，先写失败测试（red）再实现（green）
+- 修 bug 时先写复现测试（回归测试）
+
+## TDD 循环
+
+red（失败测试）→ green（最小实现通过）→ refactor（重构保持绿）
+
+- 每一步都可验证，不积累"最后再测"
+- 测试描述行为，不测实现细节（实现变了测试不该挂）
+
+## 覆盖率标准
+
+- 增量代码行覆盖率 ≥ 80%（build-gate BLD-G05 守护）
+- 覆盖率是下限不是目标——覆盖关键路径比追数字重要
+- 重点覆盖：正常路径 / 错误路径 / 边界 / 权限 / 并发
+
+## 测试质量（禁止伪满足）
+
+- 禁止"测试自己证明自己"（断言恒真、mock 掉被测逻辑）
+- 禁止为过门禁删断言/加无关 mock/降低覆盖率（[[工程执行总纲]] 精准修改硬失败）
+- 测试要有意义：能抓到真实回归
+
+## 不适用场景
 
-## 步骤
-1. **编码准备门**:
-   - 检查是否有验证计划 (verification_plan_ref)
-   - 检查前置条件（现有项目需差距分析，架构设计需 ArchitectureDesignContract）
-   - 检查约束消费
-2. **测试优先计划**:
-   - 有测试框架且行为可断言 → test_first（先写失败测试）
-   - 不能自动测试 → verification_case_first 或 manual_acceptance_first
-   - TestFirstPlan 绑定需求、主链路入口和验收标准
-2a. **头脑风暴触发**：若实现方案选择存在不确定性（模式 A/B 不确定、模块间依赖不清晰、反复修复同一逻辑）：
-   → 进入「不确定时头脑风暴流程」（templates/procedures/不确定时头脑风暴.md）
-   → 若 fundamental_need 为空 → 先触发 FP-01
-3. **编码实现**: 按 TestFirstPlan 选择模式：
-   - **模式 A**：严格测试先行（red→green→refactor）——推荐核心逻辑
-     1. 编写失败测试（red）
-     2. 编写最小实现使测试通过（green）
-     3. 重构优化（refactor）
-   - **模式 B**：红绿合并（同时编写测试和实现）——适用简单逻辑/CRUD
-     - 约束：不降低覆盖率（≥9 场景）；不适用于支付/状态流转/权限/跨系统同步
-   - **模式 B 约束**：不降低覆盖率（≥9 场景）；禁止用于支付/状态流转/权限/跨系统同步逻辑
-4. **主线消费检查**: 新增文件、组件、API、service 被真实消费
-5. **编码完成审查**: reviewCodingCompletion 验证所有硬规则
+- 纯 UI 布局/配置/无行为逻辑的代码：标注 `not_applicable_with_reason`，不强行写无意义测试
 
-## 检查点
-- [ ] CodingReadinessGate allowed
-- [ ] TestFirstPlan status 为 written
-- [ ] 约束消费无 blocking_missing
-- [ ] 主线消费无 orphan
-- [ ] 编码完成审查 passed
+## 验证
 
-## 禁止退化
-- 缺验证计划不得编码
-- blocked/manual_required 不得写实现代码
-- 测试失败不得删测试或降断言
-- 未消费前置条件不得编码
+- 测试全绿（BLD-G05）
+- 覆盖率达标
+- 关键路径有断言，不是空壳测试

package/templates/build//346/265/213/350/257/225/350/256/241/345/210/222.md

@@ -12,8 +12,8 @@ extra:
   products:
     - '*'
   lifecycle_status: active
-  version: 1.3.0
-  last_reviewed: '2026-06-04'
+  version: 2.0.0
+  last_reviewed: '2026-06-17'
   type: artifact
   domain: build
   stage: build
@@ -22,25 +22,32 @@ extra:
 
 # 测试计划
 
+> **产物定位**：build 阶段必出。定义"测什么、怎么测、什么证据算通过"。
+> **核心纪律**：禁止假验证——E0（无运行时证据）不可接受（[[证据驱动与反幻觉]] 第 5/10 条）。覆盖正常/异常/边界/权限/并发，不只 happy path。
+> **反退化纪律**：每个测试条目（T-*）必须在「测试条目」表中逐行填写真实编号（REQ-*/SLC-*），禁止只列前几行后用「…」省略、禁止用一句话概括代替表格行。
+
 ## 1. 测试范围
-- 关联任务卡片：
+- 关联任务/需求：
 - 测试目标（验证哪些功能点）：
-- 不在测试范围内的事项：
+- 不在范围内的事项：
 
 ## 2. 测试条目
-| 编号 | 功能点 | 测试类型 | 覆盖策略 | 关联需求基线 | 关联切片 | 关联任务卡 | test_phase | 优先级 | Evidence 级别 |
-|------|--------|---------|---------|-------------|-----------|-----------|-----------|--------|--------------|
-| T-01 | 正常流程 | 集成测试 | 正常路径 | REQ-NNN | SLC-{模块}-{序号} | TASK-NNN | red→green | P0 | E1 |
-| T-02 | 参数缺失 | 单元测试 | 错误路径 | REQ-NNN | SLC-{模块}-{序号} | TASK-NNN | red→green | P0 | E1 |
-| T-03 | 权限不足 | 集成测试 | 错误路径 | REQ-NNN | SLC-{模块}-{序号} | TASK-NNN | red→green | P0 | E2 |
-| T-04 | 边界值 | 单元测试 | 边界场景 | REQ-NNN | SLC-{模块}-{序号} | TASK-NNN | combined_red_green | P1 | E1 |
 
-> **Evidence 级别说明**：E0（不可接受：无运行时证据）、E1（最低要求：测试输出/API 响应日志）、E2（推荐：端到端浏览器验证截图 + API 响应 + 数据库状态验证）。P0 核心业务流程推荐 E2。
+> 填**真实编号**：REQ-001（需求分析的真实 REQ）、SLC-用户-01（切片规划的真实切片）。build-gate cross_validation 校验测试↔需求的 REQ-* 一致性+覆盖率，占位符 REQ-NNN 会 fail-closed 阻断。
+
+| 编号 | 功能点 | 测试类型 | 覆盖策略 | 关联需求 | 关联切片 | test_phase | 优先级 | Evidence 级别 |
+|------|--------|---------|---------|---------|-----------|-----------|--------|--------------|
+| T-01 | 正常流程 | 集成测试 | 正常路径 | REQ-001 | SLC-用户-01 | red→green | P0 | E1 |
+| T-02 | 参数缺失 | 单元测试 | 错误路径 | REQ-001 | SLC-用户-01 | red→green | P0 | E1 |
+| T-03 | 权限不足 | 集成测试 | 错误路径 | REQ-002 | SLC-用户-01 | red→green | P0 | E2 |
+| T-04 | 边界值 | 单元测试 | 边界场景 | REQ-001 | SLC-用户-01 | combined | P1 | E1 |
+
+> 覆盖策略必含：正常路径 / 错误路径 / 边界 / 权限 / 并发（适用时）。缺一类须说明理由。
 
 ## 3. 环境与数据
 - 测试环境：
-- 数据准备方式（业务API/页面操作/SQL初始化脚本）：
-- 前置依赖（DDL迁移/配置项/第三方Mock）：
+- 数据准备方式（业务API/页面操作/SQL脚本）：
+- 前置依赖（DDL迁移/配置/Mock）：
 
 ## 4. 执行顺序
 1. DDL 迁移验证
@@ -51,19 +58,19 @@ extra:
 ## 5. 验收标准
 - [ ] 所有 P0 测试条目通过
 - [ ] 所有 P1 测试条目通过
-- [ ] 高风险变更有运行时验证
+- [ ] 高风险变更有运行时验证（非静态分析）
 - [ ] DDL 变更有回滚验证
 
-## 6. Agent 行为测试（如适用）
+## Evidence 级别
 
-| 编号 | Agent 行为 | 测试方式 | 预期结果 | Evidence |
-|------|-----------|---------|---------|---------|
-| AT-01 | 工具调用正确性 | 集成测试 | Agent 调用正确的工具和参数 | 调用日志 |
-| AT-02 | 规划循环收敛性 | 超时检测 | Agent 在 max_steps 内收敛 | 步骤计数 |
-| AT-03 | 错误恢复路径 | 异常注入 | Agent 遇到错误后能重试或降级 | 恢复日志 |
+- **E0**：无运行时证据（仅静态分析/AI 摘要）— **不可接受**
+- **E1**：运行时证据（测试输出/截图/API 响应日志）— 最低要求
+- **E2**：完整运行时 + 端到端浏览器验证 — 推荐用于 P0 项
 
-## 7. Evidence 级别声明
+## 完成判定
 
-- E0: 无运行时证据（仅静态分析/AI 摘要）— 不可接受
-- E1: 运行时证据（测试输出/截图/API 响应日志）— 最低要求
-- E2: 完整运行时 + 端到端浏览器验证 — 推荐用于 P0 项
+- [ ] 测试条目覆盖正常/错误/边界/权限四类（适用时含并发）
+- [ ] 每条标注 Evidence 级别，无 E0
+- [ ] P0 项有验收标准且执行通过
+- [ ] 失败用例有修复或明确说明
+- [ ] 测试条目表逐行填真实编号，无「…」省略、无一句话概括代替

package/templates/build//347/274/226/347/240/201/347/272/252/345/276/213.md

@@ -0,0 +1,101 @@
+---
+id: ka-guidance-编码纪律
+kind: guidance
+title: 编码纪律
+sync_policy: copy_to_project
+status: active
+triggers:
+  - 实现
+  - 编码
+  - 写代码
+  - 开发
+  - 编码阶段
+  - 切片执行
+  - 后端实现
+  - 前端实现
+extra:
+  name: coding-discipline
+  scope:
+    - '*'
+  products:
+    - '*'
+  type: procedure
+  lifecycle_status: active
+  version: 1.0.0
+  last_reviewed: '2026-06-17'
+  verification_layer: L2
+  stage: build
+  domain: build
+  owner_mechanism: mc-coding-readiness
+---
+
+# 编码纪律：怎么把代码写对
+
+> 吸收旧的「编码阶段执行」「编码就绪审查」「编码质量」「切片执行纪律」「防御性编码」。
+> 基本功（命名/注释/单一职责/错误处理）见 [[工程纪律]]，不重复。
+
+## 超大系统：先研讨实现策略再动手
+
+开发切片计划 SLC 切片数 ≥ 5（超大系统）时，build 写代码前**必须**先 `sf_work action=deliberate target=code` 与用户研讨实现策略（头脑风暴 + 第一性原理），收敛后把结论总结留痕到 `docs/研讨记录/构建/产物-研讨记录.md`，再 act 写代码。
+
+- 此规则由 build-gate `BLD-DELIB` 确定性门禁兜底——未研讨则 build 阻断，不是软建议
+- 小任务（切片 < 5 或无切片计划）不强制，正常列改动清单即可
+- 研讨重点：切片实现顺序、跨切片共享代码先沉淀、风险切片先行验证
+
+## 工程骨架：首个切片建多工程目录（涉及多端时）
+
+build 域第一个切片（首次 `act target=code`）时，按架构 §6.3 端清单 + intent.yaml `projects` 创建工程目录骨架——每个端一个独立工程目录（`backend/` `client-portal/` `admin-web/` `miniapp/` `shared/`），每个工程目录内建标准 `src/` + 独立 `.gitignore`（按技术栈）+ 各自构建配置（package.json/pom.xml 等）。
+
+- 工程目录结构 = 架构 §6.3 端清单 + intent.yaml `projects`（build scope `allowed_paths` 据此放行）
+- **每个工程独立 `.gitignore`**（不要只在根目录一个）：前端 `node_modules/` `dist/`、Java `target/` `build/`、小程序 `miniprogram_npm/` 等
+- 各工程独立构建配置（package.json/pom.xml/build.gradle），独立依赖、独立构建
+- 单工程项目（纯后端 API）保持根 `src/`，不强制多工程
+
+## 前端骨架先行（涉及 FE-* 端时）
+
+涉及前端端（架构 §6.3 声明 FE-*）的项目，前端骨架切片先于业务页面：每个 FE-* 端先落地路由 / 状态管理 / API service 壳 / 认证拦截器 / 脱敏工具，再填充业务页面。
+
+- 骨架切片须覆盖架构 §6.3 所有 FE-* 端（XVAL-SLC 校验 ARCH-*/FE-* 覆盖）
+- 共享层（shared：类型/API client/工具）先于各端业务沉淀，避免散落
+- 前端 API 调用封装到 service 层，禁止组件内直接 fetch/axios（build-gate ARC-06）
+- Vue3/uni-app 等无内置脚手架的技术栈，配自定义模板合同（`config.scaffold.contracts`）
+
+## 实现前：先列改动清单（精准修改）
+
+动手前明确（[[工程执行总纲]] 精准修改）：
+- 要改哪些文件、改什么行为
+- 主链路入口在哪、必须接入（不接入=孤岛）
+- 类型/schema 变化的必要联动调用方
+- 不改什么（范围外文件不动）
+
+## 实现中：不写半成品
+
+- 不留空函数体、空 catch、TODO 占位（build-gate BLD-G02 守护）
+- 关键业务行有中文注释，业务日志用中文事件名（BLD-G03）
+- 错误处理：禁止静默吞异常，错误信息说清哪步失败+原因+下一步
+- 边界：空数据、null、超长、并发、重复提交都要处理
+
+## 类型安全（TS）
+
+- 禁 `as any` 绕类型（TS-Q01），禁 `@ts-ignore/@ts-nocheck`（TS-Q02）
+- 禁 `==`/`!=`，用 `===`/`!==`（TS-Q03）
+- 禁 `var`，用 `let`/`const`（TS-Q04）
+
+## 接口契约先行
+
+- 接口契约先于实现（避免前端等后端）
+- 后端接口有 OpenAPI 文档
+- 每完成一个子模块及时联调，不要全做完才联调
+
+## 防御性编码
+
+- 外部输入一律校验（类型/范围/权限）
+- 写操作考虑幂等
+- 跨系统调用考虑超时/重试/熔断（[[安全加固]]）
+
+## 反规避
+
+- 空函数体/TODO 占位 = 半成品（违规）
+- 不接入主链路 = 孤岛（违规）
+- 静默 catch = 吞异常（违规）
+- 为了过测试删断言/降覆盖率（违规，[[工程执行总纲]] 精准修改硬失败）

package/templates/build//350/260/203/350/257/225/346/216/222/346/237/245.md

@@ -1,105 +1,74 @@
 ---
-id: ka-procedure-调试排查流程
+id: ka-guidance-调试排查
 kind: guidance
 title: 调试排查
 sync_policy: copy_to_project
 status: active
 triggers:
+  - bug
   - 调试
+  - 排查
+  - 报错
+  - 异常
+  - 失败
   - 排障
-  - 排查问题
-  - bug定位
-  - 问题排查
-  - 线上排查
-  - 异常排查
-  - 错误定位
+  - 定位
   - 日志排查
   - 缺陷修复
-  - Bug修复
-  - 问题修复
-  - 异常修复
-  - 错误修复
-  - bug fix
-  - 缺陷处理
+  - bugfix
 extra:
   name: debug-investigation
-  type: procedure
   scope:
-    - backend
-    - frontend
+    - '*'
   products:
     - '*'
+  type: procedure
   lifecycle_status: active
-  version: 1.2.0
-  last_reviewed: '2026-06-04'
-  domain:
-    - build
-    - verify
+  version: 1.0.0
+  last_reviewed: '2026-06-17'
   verification_layer: L2
   stage: build
+  domain: build
   owner_mechanism: mc-verifier
 ---
 
-## 适用场景
-功能异常、性能问题、线上报错等需要定位根因的场景。遵循「先观察后假设再验证」的原则。
+# 调试排查：出了 bug 怎么定位根因
+
+> 吸收旧的「调试排查」「Bug分析」「调试方法论」「全栈流程修复」「新老逻辑比对日志」。
+> [[工程执行总纲]] 思考先行：禁止只修表象不找根因。
+
+## 第一步：稳定复现
+
+- 先找到稳定复现路径（无复现=瞎改）
+- 记录复现步骤、环境、输入、预期 vs 实际
+
+## 第二步：定位根因（不是表象）
 
-## 四阶段调试法
-1. **观察阶段**：获取具体操作步骤、输入数据、环境信息，确认可复现
-2. **假设阶段**：根据观察提出一个假设，不要同时提出多个假设
-3. **验证阶段**：设计最小实验验证假设，记录结果（包括被否定的假设）
-4. **修复阶段**：确认根因后编写最小修复 + 回归测试
+- 读日志/堆栈，追到真实失败点
+- 区分：症状（报什么）vs 根因（为什么报）
+- 二分法/日志插桩缩小范围
+- 靠证据，不靠猜（[[证据驱动与反幻觉]]）
 
-## 步骤
-1. 复现问题：获取具体操作步骤、输入数据、环境信息
-2. 确定影响范围：是全部用户还是特定条件？是偶发还是必现？
-3. 查看日志：根据时间窗口搜索 traceId，查看完整请求链路日志
-4. 查看监控：接口响应时间、错误率、资源使用（CPU/内存/磁盘）
-5. 定位代码：根据日志中的异常堆栈定位到具体文件和方法
-6. 分析根因：区分是代码 Bug、配置错误、数据异常还是环境问题
-7. 验证假设：在本地或测试环境复现并验证根因（一次只验证一个假设）
-8. 编写最小修复：修复范围只覆盖确认的根因，禁止顺手改其他代码
-9. 使用 RED-GREEN 验证：回退修复 → 确认失败 → 恢复修复 → 确认通过
-10. 添加回归测试（防止同类问题再发生）
+## 第三步：最小修复
 
-## 调试报告格式
+- 只改根因点，不扩大范围（[[工程执行总纲]] 精准修改）
+- 改老系统先比对新老逻辑差异
+- 修复限于同一上下文；跨模块回到任务拆解
 
-### 基本信息
-| 项目 | 内容 |
-|------|------|
-| 问题描述 | <!-- 现象描述 --> |
-| 影响范围 | <!-- 用户/模块/接口 --> |
-| 复现条件 | <!-- 步骤 --> |
-| 严重程度 | P0/P1/P2 |
+## 第四步：回归测试
 
-### 调试过程
-| 阶段 | 假设 | 验证方法 | 结果 |
-|------|------|---------|------|
-| 观察 | — | <!-- 日志/监控 --> | <!-- 发现 --> |
-| 假设 1 | <!-- 假设内容 --> | <!-- 验证方法 --> | 确认/否定 |
-| 假设 2 | <!-- 假设内容 --> | <!-- 验证方法 --> | 确认/否定 |
+- 先写复现测试（证明 bug 存在）→ 修复后证明 bug 消失
+- 跑相关测试，确认没引入新问题
 
-### 修复方案
-| 修改文件 | 修改内容 | 关联切片 |
-|---------|---------|---------|
-| <!-- 文件路径 --> | <!-- 修改说明 --> | SLC-{模块}-{序号} |
+## 第五步：防复发
 
-### RED-GREEN 验证
-- [ ] 回退修复后测试失败（RED）
-- [ ] 恢复修复后测试通过（GREEN）
+- 补测试守住这个修复
+- 想想同类问题会不会在别处出现（举一反三）
+- 必要时沉淀成规则/检查
 
-## 检查点
-- [ ] 问题可稳定复现（或记录了偶现条件）
-- [ ] 日志中有 traceId 可追踪完整链路
-- [ ] 调试过程有假设-验证记录
-- [ ] 根因已确认而非停留在表象
-- [ ] 修复范围仅限确认的根因
-- [ ] 修复包含回归测试
+## 禁止
 
-## 注意事项
-- 不要在没有复现的情况下直接修改代码
-- 日志排查优先使用 traceId，避免大海捞针
-- 性能问题优先看慢查询日志和接口耗时
-- 同一现象修复失败 3 次后停止猜测，重新审视假设，考虑是否为架构问题
-- 禁止通过删除断言、增加 sleep、降低覆盖率、增加 mock 来制造通过
-- 调试修复须遵守 SED-04（禁止跨任务修改），修复范围仅限当前切片涉及文件
-- 修复范围超出当前切片涉及文件时，须触发重规划（参见切片计划 §7 动态重规划）
+- 不复现就改（违规，改了也不知道对不对）
+- 只修表象不找根因（违规，bug 会回来）
+- 改一大片"可能相关"的代码（违规，扩大风险）
+- 修复后不写回归测试（违规，无法证明修好）

package/templates/build//351/207/215/346/236/204/346/226/271/346/263/225.md

@@ -0,0 +1,68 @@
+---
+id: ka-guidance-重构方法
+kind: guidance
+title: 重构方法
+sync_policy: copy_to_project
+status: active
+triggers:
+  - 重构
+  - refactor
+  - 解耦
+  - 耦合
+  - 重构方案
+  - 改善代码
+  - 抽象
+extra:
+  name: refactoring-method
+  scope:
+    - '*'
+  products:
+    - '*'
+  type: procedure
+  lifecycle_status: active
+  version: 1.0.0
+  last_reviewed: '2026-06-17'
+  verification_layer: L2
+  stage: build
+  domain: build
+  owner_mechanism: mc-code-maintainability-observability-contract
+---
+
+# 重构方法：怎么改老代码不翻车
+
+> 吸收旧的「重构方案」「重构流水线」「耦合检测」「OOD设计摘要」。
+
+## 何时该重构（先想清楚）
+
+- 代码确实难以理解/修改/扩展，且有测试保护
+- 重构服务于当前目标，不是"看着不爽"
+
+## 何时不该重构
+
+- 没有测试覆盖的代码（先补测试）
+- 跟当前任务无关的顺手重构（[[工程执行总纲]] 精准修改：禁止）
+- 需求紧急、没有回滚余量时
+
+## 重构步骤
+
+1. **先有测试**：覆盖现有行为（重构后行为不变是验证标准）
+2. **小步前进**：每步可编译可测试，不一次性大改
+3. **每步验证**：跑测试，绿了再下一步
+4. **新老逻辑比对**（改老系统）：行为一致才算通过
+
+## 解耦判断
+
+- 检测高耦合点（模块间循环依赖、上帝对象、散弹式修改）
+- 用接口/事件/适配器解耦，但不过度抽象（[[工程执行总纲]] 简单优先）
+- 引入新抽象前说明必要性
+
+## 禁止
+
+- 无测试就重构（违规，无法验证行为不变）
+- 顺手重构无关模块（违规）
+- 大爆炸式重构（违规，无法回滚）
+- 为重构而抽象（违规，增加复杂度）
+
+## 验证
+
+重构后必须给出：测试全绿 + 行为不变的证据（新老比对/覆盖率不降）。

package/templates/design/API/346/216/245/345/217/243/350/247/204/346/240/274/346/226/207/346/241/243.md

@@ -12,8 +12,8 @@ extra:
     - frontend
   products:
     - '*'
-  version: 1.2.0
-  last_reviewed: '2026-06-04'
+  version: 2.0.0
+  last_reviewed: '2026-06-17'
   type: artifact
   domain: design
   stage: design
@@ -22,29 +22,39 @@ extra:
 
 # API 接口规格文档
 
+> **产物定位**：涉及前后端接口对接时产出（按需）。把接口契约先于实现定清楚，避免前端等后端。
+> **核心纪律**：契约先行（[[编码纪律]]）；每个 endpoint 有验收场景 + 验证证据（[[证据驱动与反幻觉]]）。
+> **反退化纪律**：每个 endpoint 必须完整重复其全部必填结构块，禁止退化——
+> - 禁止「前详后废」（前几个 endpoint 完整、后面的退化成一行文字）
+> - 禁止用一行文字 `**xxx**：…` 代替表格，或省略标 `[Always]` 的必填块（基本信息/响应体字段/错误与副作用/验收场景）
+> - 章节标题必须用 `###`，禁止降级为 `**粗体**`
+> - 禁止「同上格式」「见上文」「…」等偷懒占位
+> 任一 endpoint 缺任一必填块 = 未完成，须补齐后再推进。
+> **完成判定**：见文末，每个 endpoint 须满足。
+
 OpenAPI 权威路径: `docs/api/openapi.yaml`
 
 ## Endpoint: `METHOD /api/v1/resource`
 
-> **接口编号**: `DD-A01`（每个 endpoint 唯一，供切片计划/代码审查引用，cross_validation 据此校验一致性+覆盖）
-> **关联需求**: `REQ-001`（本接口实现的需求编号，供 cross_validation 校验与需求分析一致；多个用 `/` 分隔）
+> **接口编号**: `DD-A01`（每个 endpoint 唯一，供切片计划/代码审查引用）
+> **关联需求**: `REQ-001`（供 cross_validation 校验与需求一致；多个用 `/` 分隔）
 
 ### 基本信息 [Always — 每个 endpoint 必填]
 
 | endpoint_id | 用途 | 调用端 | 权限 | 幂等 | 限流 | 副作用 |
 |-------------|------|--------|------|------|------|--------|
 
-### 请求 Header 字段 [Ask first — 有认证/自定义 Header 时必填]
+### 请求 Header 字段 [有认证/自定义 Header 时必填]
 
 | 字段路径 | 类型 | 必填 | 格式/约束 | 数据映射 | 说明 | 示例 |
 |----------|------|------|-----------|----------|------|------|
 
-### 请求 Path / Query 字段 [Ask first — 有路径/查询参数时必填]
+### 请求 Path / Query 字段 [有路径/查询参数时必填]
 
 | 字段路径 | 类型 | 必填 | 默认值 | 格式/约束 | 说明 | 示例 |
 |----------|------|------|--------|-----------|------|------|
 
-### 请求体字段 [Ask first — 有请求体时必填]
+### 请求体字段 [有请求体时必填]
 
 | 字段路径 | 类型 | 必填 | 可空 | 枚举/格式/校验 | 数据映射 | 说明 | 示例 |
 |----------|------|------|------|----------------|----------|------|------|
@@ -64,32 +74,32 @@ OpenAPI 权威路径: `docs/api/openapi.yaml`
 | 场景 | 输入 | 预期响应 | 数据/状态变化 | 验证证据 |
 |------|------|----------|---------------|----------|
 
-### 枚举值定义 [Ask first — 有枚举字段时必填]
+### 枚举值定义 [有枚举字段时必填]
 
 | 枚举名 | 值 | 含义 |
 |--------|------|------|
 
-### 页面交互映射 [Ask first — 前端直接调用的接口必填]
+### 页面交互映射 [前端直接调用的接口必填]
 
 | 页面操作 | 触发接口 | 加载状态 | 成功行为 | 失败行为 |
 |---------|---------|---------|---------|---------|
 
-### 接口规范检查 [Always — 每个 endpoint 必填]
-
-- [ ] 是否定义了接口版本号和演进策略（如 /api/v1/）
-- [ ] 是否有幂等设计（写接口需标注幂等键或唯一约束）
-- [ ] 错误码体系是否完整（业务码 + HTTP 状态码双映射）
-- [ ] 是否有分页参数上限限制（防止恶意大翻页）
-- [ ] 是否有接口限流策略（QPS/并发上限）
-- [ ] 批量操作是否有数量上限（≤ 500 条）
-
-### AI Agent 格式校验 [Always — 每个 endpoint 必填]
-
-- [ ] 每个 endpoint_id 全局唯一且遵循命名规范（{资源}-{动作}）
-- [ ] 所有 数据映射 字段已精确到 表名.字段名 格式（禁止仅写表名）
-- [ ] 所有 类型 字段使用标准类型（string/integer/number/boolean/array/object/date/datetime/enum）
-- [ ] 所有 格式/约束 字段使用标准约束格式（min:0,max:100 或 pattern:regex）
-- [ ] 错误映射表中每个 HTTP 状态码至少对应一个业务码
-- [ ] 验收场景表中每行必须包含 验证证据（不得为空）
-- [ ] 枚举值定义覆盖了所有字段中出现的枚举类型
-- [ ] 页面交互映射覆盖了所有涉及前端调用的接口
+## 接口规范检查
+
+- [ ] 接口有版本号和演进策略（如 /api/v1/）
+- [ ] 写接口有幂等设计（幂等键或唯一约束）
+- [ ] 错误码体系完整（业务码 + HTTP 状态码双映射）
+- [ ] 分页参数有上限（防恶意大翻页）
+- [ ] 接口有限流策略（QPS/并发上限）
+- [ ] 批量操作有数量上限（≤ 500 条）
+
+## 完成判定（每个 endpoint 须满足）
+
+- [ ] endpoint_id 全局唯一且遵循命名规范（{资源}-{动作}）
+- [ ] 所有 数据映射 字段精确到 表名.字段名（禁止仅写表名）
+- [ ] 所有 类型 用标准类型（string/integer/number/boolean/array/object/date/datetime/enum）
+- [ ] 错误映射表每个 HTTP 状态码至少对应一个业务码
+- [ ] 每个验收场景有验证证据（不得为空）
+- [ ] 枚举值定义覆盖所有枚举字段
+- [ ] 涉及前端调用的接口有页面交互映射
+- [ ] 每个 endpoint 都含全部必填表格块（基本信息/响应体字段/错误与副作用/验收场景），无一行文字替代、无偷懒占位