soloforge 1.1.46 → 1.1.47

package/templates/build/enforced.md

@@ -5,6 +5,8 @@ gate: build-gate
 title: build阶段强制检查清单
 sync_policy: engine_only
 status: active
+extra:
+  owner_mechanism: mc-stage-gate-engine
 checks:
   - id: TS-Q01
     executor: regex_pattern_scan
@@ -166,6 +168,77 @@ checks:
     evidence_required: ["regex_pattern_scan 扫描结果（git diff 变更文件无未校验 JWT 命中）"]
     gate: build-gate
     target: "self"
+  # —— 代码架构检查（从 design-gate 迁入，代码实现阶段归属）——
+  - id: ARC-01
+    executor: regex_pattern_scan
+    rule: "Controller 禁止包含业务逻辑（计算/校验等应下沉 Service）"
+    severity: error
+    check_type: deterministic
+    pattern: '/\bclass\s+\w*Controller\b[\s\S]{0,500}\b(if|for|while|calculate|compute)\s*\(/'
+    languages: [java]
+    evidence_required: ["regex_pattern_scan 扫描结果（git diff 变更文件无 Controller 含业务逻辑命中）"]
+    gate: build-gate
+    target: "self"
+  - id: ARC-02
+    executor: regex_pattern_scan
+    rule: "禁止 Entity 直接暴露给外部接口，必须用 DTO"
+    severity: error
+    check_type: deterministic
+    pattern: '/\bpublic\s+\w*Entity\b\s+\w+\s*\(/'
+    languages: [java]
+    evidence_required: ["regex_pattern_scan 扫描结果（git diff 变更文件无 Entity 直接暴露命中）"]
+    gate: build-gate
+    target: "self"
+  - id: ARC-03
+    executor: regex_pattern_scan
+    rule: "写操作（save/create/update/delete）必须有 @Transactional"
+    severity: error
+    check_type: deterministic
+    pattern: '/\.(save|insert|update|delete|remove|create)\s*\(/'
+    languages: [java]
+    evidence_required: ["regex_pattern_scan 扫描结果（git diff 变更文件无写操作缺事务命中）"]
+    gate: build-gate
+    target: "self"
+  - id: ARC-04
+    executor: regex_pattern_scan
+    rule: "禁止直接 new Service/Repository/Mapper/Manager，必须依赖注入"
+    severity: error
+    check_type: deterministic
+    pattern: '/\bnew\s+\w*(Service|Repository|Repo|Dao|Mapper|Manager)\s*\(/'
+    languages: [java]
+    evidence_required: ["regex_pattern_scan 扫描结果（git diff 变更文件无直接 new 服务对象命中）"]
+    gate: build-gate
+    target: "self"
+  - id: ARC-06
+    executor: regex_pattern_scan
+    rule: "前端 API 调用必须封装到 service 层，禁止组件内直接 fetch/axios"
+    severity: error
+    check_type: deterministic
+    pattern: '/\b(fetch|axios)\s*\(/'
+    languages: [ts]
+    evidence_required: ["regex_pattern_scan 扫描结果（git diff 变更文件无组件直接 API 调用命中）"]
+    gate: build-gate
+    target: "self"
+  - id: ARC-07
+    executor: regex_pattern_scan
+    rule: "禁止 @Autowired + @Lazy 循环依赖"
+    severity: error
+    check_type: deterministic
+    pattern: '/@Autowired[\s\S]{0,50}@Lazy|@Lazy[\s\S]{0,50}@Autowired/'
+    languages: [java]
+    evidence_required: ["regex_pattern_scan 扫描结果（git diff 变更文件无循环依赖命中）"]
+    gate: build-gate
+    target: "self"
+  - id: ARC-08
+    executor: regex_pattern_scan
+    rule: "Service 层禁止直接操作 HttpServletRequest/Response"
+    severity: error
+    check_type: deterministic
+    pattern: '/\bHttpServletRequest\b|\bHttpServletResponse\b/'
+    languages: [java]
+    evidence_required: ["regex_pattern_scan 扫描结果（git diff 变更文件无 Service 操作 HttpServlet 命中）"]
+    gate: build-gate
+    target: "self"
   - id: BLD-G01
     executor: upstream_gate_check
     rule: "design-gate 已通过，所有前置设计产物完备"

package/templates/build//344/270/223/351/241/271/345/256/236/347/216/260.md

@@ -0,0 +1,75 @@
+---
+id: ka-guidance-专项实现
+kind: guidance
+title: 专项实现
+sync_policy: copy_to_project
+status: active
+triggers:
+  - 数据库迁移
+  - 接口集成
+  - 性能优化
+  - 性能分析
+  - 异步
+  - 缓存
+  - 定时任务
+  - 文件上传
+extra:
+  name: specialized-implementation
+  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-backend-pattern
+---
+
+# 专项实现：特定场景怎么做
+
+> 吸收旧的「数据库迁移」「接口集成流水线」「性能分析」「性能流水线」「缓存策略」「异步导出」等。
+> 按需注入，不强制全套。
+
+## 数据库迁移
+
+- migration 脚本成对（up + down），可回滚
+- 大表变更评估锁表影响，分批/在线 DDL
+- 数据迁移新老比对，回滚后一致性验证
+- 详见 [[兼容性与迁移评估]]
+
+## 接口集成
+
+- 接口契约先行（OpenAPI），契约评审后再实现
+- 字段映射精确到 表.字段
+- 对接外部系统考虑超时/重试/幂等/签名
+- 异常路径明确（对方不可用怎么办）
+
+## 性能优化
+
+- 先测量后优化（性能分析数据为证据，不靠猜）
+- 优化目标量化（如 P99 < 200ms）
+- 关注 N+1 查询、大循环、不必要序列化
+- 缓存考虑一致性/失效/穿透/雪崩
+
+## 异步与定时
+
+- 异步任务幂等（可重试不重复执行）
+- 定时任务考虑并发执行/分布式锁
+- 长任务可中断、可观测进度
+
+## 文件上传/导出
+
+- 限制类型/大小，校验内容（防恶意文件）
+- 大文件流式处理/分片，不一次性进内存
+- 导出异步化，提供进度查询
+
+## 禁止
+
+- 迁移脚本无回滚（违规）
+- 接口集成不定义契约（违规）
+- 性能优化无测量证据（违规，[[证据驱动与反幻觉]]）
+- 异步任务不幂等（违规）

package/templates/build//345/256/211/345/205/250/345/212/240/345/233/272.md

@@ -0,0 +1,75 @@
+---
+id: ka-guidance-安全加固
+kind: guidance
+title: 安全加固
+sync_policy: copy_to_project
+status: active
+triggers:
+  - 安全
+  - 权限
+  - 认证
+  - 授权
+  - 加固
+  - 鉴权
+  - 熔断
+  - 限流
+extra:
+  name: security-hardening
+  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-privacy-boundary
+---
+
+# 安全加固：编码时怎么堵漏洞
+
+> 吸收旧的「安全加固」「安全审查」「安全审计」「权限认证」「熔断降级」。
+> build-gate 的 SEC-01~12 是硬门禁（确定性正则），本 guidance 是方法指导。
+
+## 输入校验（第一道防线）
+
+- 所有外部输入校验：类型、范围、格式、长度
+- SQL 用参数化查询，禁字符串拼接（SEC-01）
+- 禁 innerHTML 直接赋值，用安全 DOM API/转义（SEC-02，防 XSS）
+- 禁 eval/Function 动态执行（SEC-03）
+
+## 认证与授权
+
+- 每个接口明确权限要求
+- 写操作必须鉴权
+- JWT 校验签名算法，禁未校验 decode（SEC-12）
+- Cookie 设 secure/httpOnly（SEC-11）
+
+## 敏感信息
+
+- 密钥走环境变量/密钥管理，禁硬编码（SEC-04，shared-gate SEC-02）
+- 日志禁打印密码/token/身份证（SEC-05）
+- 路径参数防遍历（SEC-07）
+
+## 外部交互
+
+- 重定向校验目标（SEC-06，防开放重定向）
+- 外部请求校验目标（SEC-09，防 SSRF）
+- 反序列化白名单（SEC-08）
+- CORS 收紧 allowedOrigins，禁 `*`（SEC-10）
+
+## 稳定性（熔断降级）
+
+- 跨系统调用设超时/重试/熔断
+- 限流保护核心接口
+- 降级策略：依赖不可用时系统的行为
+
+## 禁止
+
+- 信任客户端输入不校验（违规）
+- 拼接 SQL（违规）
+- 打印敏感信息到日志（违规）
+- 写接口不鉴权（违规）

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,28 @@ extra:
 
 # 测试计划
 
+> **产物定位**：build 阶段必出。定义"测什么、怎么测、什么证据算通过"。
+> **核心纪律**：禁止假验证——E0（无运行时证据）不可接受（[[证据驱动与反幻觉]] 第 5/10 条）。覆盖正常/异常/边界/权限/并发，不只 happy path。
+
 ## 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 |
+| 编号 | 功能点 | 测试类型 | 覆盖策略 | 关联需求 | 关联切片 | test_phase | 优先级 | Evidence 级别 |
+|------|--------|---------|---------|---------|-----------|-----------|--------|--------------|
+| T-01 | 正常流程 | 集成测试 | 正常路径 | REQ-NNN | SLC-x | red→green | P0 | E1 |
+| T-02 | 参数缺失 | 单元测试 | 错误路径 | REQ-NNN | SLC-x | red→green | P0 | E1 |
+| T-03 | 权限不足 | 集成测试 | 错误路径 | REQ-NNN | SLC-x | red→green | P0 | E2 |
+| T-04 | 边界值 | 单元测试 | 边界场景 | REQ-NNN | SLC-x | combined | P1 | E1 |
 
-> **Evidence 级别说明**：E0（不可接受：无运行时证据）、E1（最低要求：测试输出/API 响应日志）、E2（推荐：端到端浏览器验证截图 + API 响应 + 数据库状态验证）。P0 核心业务流程推荐 E2。
+> 覆盖策略必含：正常路径 / 错误路径 / 边界 / 权限 / 并发（适用时）。缺一类须说明理由。
 
 ## 3. 环境与数据
 - 测试环境：
-- 数据准备方式（业务API/页面操作/SQL初始化脚本）：
-- 前置依赖（DDL迁移/配置项/第三方Mock）：
+- 数据准备方式（业务API/页面操作/SQL脚本）：
+- 前置依赖（DDL迁移/配置/Mock）：
 
 ## 4. 执行顺序
 1. DDL 迁移验证
@@ -51,19 +54,18 @@ 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,75 @@
+---
+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
+---
+
+# 编码纪律：怎么把代码写对
+
+> 吸收旧的「编码阶段执行」「编码就绪审查」「编码质量」「切片执行纪律」「防御性编码」。
+> 基本功（命名/注释/单一职责/错误处理）见 [[工程纪律]]，不重复。
+
+## 实现前：先列改动清单（精准修改）
+
+动手前明确（[[工程执行总纲]] 精准修改）：
+- 要改哪些文件、改什么行为
+- 主链路入口在哪、必须接入（不接入=孤岛）
+- 类型/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 = 吞异常（违规）
+- 为了过测试删断言/降覆盖率（违规，[[工程执行总纲]] 精准修改硬失败）