soloforge 1.1.45 → 1.1.47

package/templates/design//345/216/237/345/236/213/346/272/220/347/240/201/346/217/220/345/217/226.md

@@ -1,78 +0,0 @@
----
-id: 原型源码提取
-kind: guidance
-title: 原型源码提取
-sync_policy: copy_to_project
-status: active
-triggers:
-  - 原型提取
-  - 源码分析
-  - source extraction
-  - prototype source
-extra:
-  name: prototype-source-extraction
-  type: constraint
-  domain: design
-  lifecycle_status: active
-  scope:
-    - backend
-    - frontend
-  products:
-    - '*'
-  verification_layer: L2
-  stage: design
-  owner_mechanism: mc-command-router
----
-
-# 原型源码提取规则
-
-## 必须读取的源码材料
-
-需求分析阶段，必须从以下路径模式读取源码材料：
-
-1. `src/**/*Controller.ts` — 控制器层，提取路由定义和请求处理逻辑
-2. `src/**/*Service.ts` — 服务层，提取业务规则和流程编排
-3. `src/**/*Repository.ts` / `src/**/*Dao.ts` — 数据访问层，提取数据模型和查询逻辑
-4. `src/**/*Model.ts` / `src/**/*Entity.ts` — 实体定义，提取字段和约束
-5. `src/**/*Config.ts` / `config/**/*` — 配置文件，提取环境依赖和参数
-6. `src/**/*Middleware.ts` — 中间件，提取横切关注点（认证、日志等）
-7. `src/pages/**/*` / `src/views/**/*` / `app/**/page.tsx` — 页面组件，提取路由和页面结构
-8. `src/components/**/*` — UI 组件，提取组件树和 props
-9. `src/stores/**/*` / `src/state/**/*` — 状态管理，提取数据流和状态转换
-10. `src/styles/**/*` / `src/tokens.*` / `tailwind.config.*` — 设计令牌，提取色彩/间距/字体
-11. `src/api/**/*` / `src/services/**/*` — API 客户端，提取接口调用和数据绑定
-12. `src/i18n/**/*` / `src/locales/**/*` — 国际化文件，提取文案和术语
-
-### 可选设计资源路径
-
-> SoloForge 核心场景是从源码提取。以下路径为可选，但一旦存在必须标注引用。
-
-13. `design/**/*` / `figma-export/**/*` / `prototype-export/**/*` — 设计稿导出文件
-14. `*.figma` / `*.sketch` — 原始设计文件路径（仅标注，不直接读取）
-15. `docs/design/**/*` / `docs/architecture/**/*` / `docs/analyze/**/*` — 设计文档（数据库/API/详细/架构/原型说明）
-
-### 接口与数据规格路径
-
-16. `openapi.*` / `swagger.*` / `api-docs/**/*` — API 规格文件
-17. `prisma/schema.prisma` / `drizzle/schema.ts` / `knexfile.*` — ORM schema
-18. `migrations/**/*` / `db/migrate/**/*` — 数据库迁移文件
-
-## 禁止来源
-
-以下来源不得作为需求分析的源码材料依据：
-
-1. 禁止仅凭口头描述编写需求，必须有源码证据支撑
-2. 禁止从 `node_modules/` 或第三方库源码推断需求
-3. 禁止使用 `dist/` 或编译产物代替源码
-4. 禁止从测试文件反推需求规格（测试用于验证，不用于定义）
-
-## 证据标记规范
-
-每个提取的需求点必须标注来源证据：
-
-- `[SRC:文件路径:行号]` — 直接从源码提取
-- `[LOG:日志片段]` — 从运行日志推导（需标注日志来源）
-- `[CFG:配置项]` — 从配置文件提取
-- `[REF:引用链路]` — 从调用链路推导（需标注链路起点和终点）
-- `[DES:设计资源路径]` — 设计稿提取（需人工确认）
-- `[INF:推理结论]` — AI 推理（低置信，必须标注推理依据，须人工确认才可进入基线）

package/templates/design//345/216/237/345/236/213/350/257/264/346/230/216.md

@@ -1,200 +0,0 @@
----
-id: ka-artifact_template-prototype-specification
-kind: artifact
-title: 原型说明
-sync_policy: copy_to_project
-status: active
-extra:
-  name: prototype-specification
-  scope:
-    - frontend
-  products:
-    - '*'
-  lifecycle_status: active
-  version: 1.3.1
-  last_reviewed: '2026-06-05'
-  type: artifact
-  domain: design
-  stage: design
-  owner_mechanism: mc-generic-artifact
----
-
-# [页面名称] 原型与交互规约
-
-> **源码提取约束**：按 `原型源码提取.md` 执行。禁止从非源码来源臆测原型信息。
-
-## 1. 页面元数据
-- **所属模块/端**：
-- **关联 PRD 节点**：
-- **页面核心目标**：
-- **页面路由路径**：
-- **入口来源**：
-- **提取依据**：[Source Code / Source Doc / Source Asset / Manual Confirm]
-
-> **根本目标引用**：本产物的 `fundamental_need` 见需求分析文档 §1.3。若未声明，引用审查规则 FP-01。
-
----
-
-## 2. 设计令牌 (Design Tokens)
-
-### 2.1 色彩
-| 令牌名 | 色值 | 用途 |
-|--------|------|------|
-
-### 2.2 间距与圆角
-| 令牌名 | 值 | 用途 |
-|--------|------|------|
-
-### 2.3 字体
-| 令牌名 | 值 | 用途 |
-|--------|------|------|
-
----
-
-## 3. 页面布局树
-
-### 3.1 整体布局
-- **布局方式**：
-- **[Header]** 顶部导航栏：
-- **[FilterBar]** 筛选区（如有）：
-- **[ContentArea]** 主体内容区：
-- **[Footer]** 底部操作区（如有）：
-
-### 3.2 核心组件布局
-- 外层样式：
-- 内部布局：
-
----
-
-## 4. 组件数据绑定与渲染逻辑
-
-### 4.1 字段映射
-| UI 元素 | 绑定字段 | 格式化规则 | 动态行为 |
-|---------|---------|-----------|---------|
-
-### 4.2 动态渲染规则
--
-
----
-
-## 5. 交互流转与状态机
-
-### 5.1 事件：[核心交互]
-
-```text
-[初始状态] → 触发 → [前置校验]
-                       ├─ 条件A → 动作A → [状态X]
-                       └─ 条件B → 动作B → [状态Y]
-```
-
-### 5.2 事件：[次要交互]
--
-
----
-
-## 6. 组件视觉状态
-
-| 组件 | 状态 | 视觉变化 |
-|------|------|---------|
-<!-- 组件视觉状态表：填写各组件的默认/Hover/Active/Disabled 等状态及对应视觉变化 -->
-
----
-
-## 7. 响应式断点
-
-| 断点 | 宽度范围 | 布局变化 |
-|------|---------|---------|
-<!-- 响应式断点表：至少覆盖 Desktop 和 Mobile 两个断点 -->
-
----
-
-## 8. 动效规范
-
-| 交互 | 动效 | 时长 | 缓动函数 |
-|------|------|------|---------|
-<!-- 动效规范表：列出页面中所有动效的触发交互、动效类型、持续时间和缓动函数 -->
-
----
-
-## 9. 边界与异常分支
-
-### 9.1 数据边界
-
-| 场景名 | 触发条件 | UI 表现 | 交互行为 | 证据标记 |
-|--------|---------|---------|---------|---------|
-| 空列表（首次使用） | 数据源返回空 + 用户首次访问 | 插图+引导文案+CTA 按钮 | 引导创建第一条数据 | |
-| 空列表（用户清空） | 数据源返回空 + 用户曾操作 | 确认文案+快捷操作入口 | 允许撤销或重新添加 | |
-| 搜索无结果 | 筛选条件命中 0 条 | 建议文案+放宽条件提示 | 允许清除筛选 | |
-| 数据截断 | 字段值超最大长度 | 截断+Tooltip 完整内容 | Hover/Click 展示完整内容 | |
-| 分页末尾 | 已加载全部数据 | "没有更多了"提示 | 停止加载 | |
-
-### 9.2 网络与权限异常
-
-| 场景名 | 触发条件 | UI 表现 | 交互行为 | 证据标记 |
-|--------|---------|---------|---------|---------|
-| 网络超时 | 请求超时 | Toast/Snackbar+重试按钮 | 允许重试 | |
-| 服务端错误（5xx） | 服务端返回 5xx | 错误页面/内联错误+重试 | 允许重试或返回 | |
-| 权限不足（403） | 用户无操作权限 | 权限提示+申请入口 | 引导联系管理员 | |
-| 登录过期（401） | Token 失效 | 登录弹窗/跳转 | 重新登录后恢复当前操作 | |
-| 网络离线 | 断网检测 | 离线横幅+缓存数据 | 提示恢复网络 | |
-
-### 9.3 并发与竞态
-
-| 场景名 | 触发条件 | UI 表现 | 交互行为 | 证据标记 |
-|--------|---------|---------|---------|---------|
-| 重复提交 | 用户快速重复点击 | 按钮禁用+Loading | 防抖/节流+服务端幂等 | |
-| 数据过期 | 他人已修改同一数据 | 冲突提示+最新数据预览 | 允许覆盖/合并/放弃 | |
-| 并发锁 | 资源被锁定 | 锁定提示+预计释放时间 | 等待或通知 | |
-
-### 9.4 加载态
-
-| 场景名 | 触发条件 | UI 表现 | 交互行为 | 证据标记 |
-|--------|---------|---------|---------|---------|
-| 首次加载 | 页面初始化 | 骨架屏/Loading Spinner | < 3s 显示骨架屏 | |
-| 局部刷新 | 局部数据更新 | 组件内 Loading/乐观更新 | < 1s 乐观更新 | |
-| 提交中 | 表单/操作提交 | 按钮 Loading+禁用 | 防重复点击 | |
-| 背景同步 | 后台数据拉取 | 进度条/Silent refresh | 不阻塞交互 | |
-
-## 10. 无障碍 (Accessibility)
-
-> scope 限定：frontend
-
-### 10.1 键盘导航
-
-| 功能 | Tab 序 | 快捷键 | 焦点管理 |
-|------|--------|--------|---------|
-| <!-- 功能名 --> | <!-- Tab 序号 --> | <!-- 如 Ctrl+N --> | |
-
-### 10.2 ARIA 角色与标注
-
-| 组件 | role | aria-label | aria-describedby | 状态标注 |
-|------|------|-----------|-----------------|---------|
-| | | | | |
-
-### 10.3 焦点管理
-
-| 场景 | 焦点来源 | 焦点目标 | 说明 |
-|------|---------|---------|------|
-| 弹窗打开 | 触发元素 | 弹窗内首个可聚焦元素 | Tab 循环限制在弹窗内 |
-| 弹窗关闭 | — | 回到触发元素 | |
-| 路由切换 | — | 新页面主内容区 | |
-| 列表更新 | — | 当前操作项 | |
-| 内联编辑完成 | — | 编辑后的内容 | |
-
-### 10.4 色彩与对比度
-
-| 元素类型 | 前景色 | 背景色 | 对比度 | 最低要求 |
-|---------|--------|--------|--------|---------|
-| 正文 | | | | ≥ 4.5:1 |
-| 大文本 | | | | ≥ 3:1 |
-| 交互元素 | | | | ≥ 3:1 |
-
-### 10.5 屏幕阅读器
-
-| 场景 | aria 属性 | 值 | 说明 |
-|------|----------|-----|------|
-| 动态列表更新 | aria-live | polite | |
-| Toast 通知 | aria-live / role | assertive / alert | |
-| 加载态 | aria-busy | true | |
-| 表单验证错误 | aria-describedby | 关联到字段 | |
-| 弹窗/抽屉 | role + aria-modal | dialog + true | |

package/templates/design//345/216/237/345/236/213/350/257/264/346/230/216/345/256/241/346/237/245.md

@@ -1,81 +0,0 @@
----
-id: ka-review-rule-原型说明审查规则
-kind: guidance
-title: 原型说明审查
-sync_policy: copy_to_project
-status: active
-triggers:
-  - 原型审查
-  - 原型说明审查
-  - prototype review
-extra:
-  name: prototype-specification-review
-  type: constraint
-  scope:
-    - frontend
-  products:
-    - '*'
-  lifecycle_status: active
-  domain: design
-  verification_layer: L2
-  stage: design
-  owner_mechanism: mc-generic-artifact
----
-
-# 原型说明审查规则
-
-## PROT-01: 完整性
-
-check_hint: 原型说明模版 10 个章节无空洞
-severity: error
-scope: [frontend]
-description: 原型说明必须完整覆盖 10 个章节（含第 9 章边界异常和第 10 章无障碍），不得有空章节、TODO 占位或 `-` 单独占位。
-
-## PROT-02: 证据标记
-
-check_hint: 所有章节内容标注来源标记
-severity: warning
-scope: [frontend]
-description: 所有内容必须使用统一证据标记体系 [SRC]/[LOG]/[CFG]/[REF]/[DES]/[INF]，不得有无标记的断言。
-
-## PROT-03: 交互闭环
-
-check_hint: 状态机无死端，所有异常分支有处理
-severity: error
-scope: [frontend]
-description: 第 5 章交互流转的状态机图必须所有路径有终止状态，第 9 章异常分支每个子节至少 1 条场景。
-
-## PROT-04: 术语一致
-
-check_hint: 使用与项目术语表一致的命名
-severity: warning
-scope: [frontend]
-description: 原型说明中的术语必须与需求分析第 3 章术语表一致，不得使用未定义的同义词。
-
-## PROT-05: 令牌引用
-
-check_hint: 色彩/间距/字体引用设计令牌而非硬编码色值
-severity: warning
-scope: [frontend]
-description: 第 2 章设计令牌中定义的令牌名必须在第 6 章视觉状态中引用，禁止出现硬编码色值（如 #FF0000）。
-
-## PROT-06: 无障碍完备
-
-check_hint: 第 10 章 5 个子节无空洞
-severity: warning
-scope: [frontend]
-description: 第 10 章无障碍的 5 个子节（键盘导航/ARIA/焦点管理/色彩对比度/屏幕阅读器）必须全部填写，不得有空子节。
-
-## PROT-07: 响应式覆盖
-
-check_hint: 至少覆盖 Desktop / Mobile 两个断点
-severity: warning
-scope: [frontend]
-description: 第 7 章响应式断点必须至少包含 Desktop 和 Mobile 两个断点定义。
-
-## PROT-08: 异常覆盖
-
-check_hint: 第 9 章 4 个子节每节至少 1 条场景
-severity: error
-scope: [frontend]
-description: 第 9 章边界与异常分支的 4 个子节（数据边界/网络权限异常/并发竞态/加载态）每节至少 1 条场景记录。

package/templates/design//345/220/221/345/220/216/345/205/274/345/256/271/346/200/247/345/220/210/350/247/204/346/212/245/345/221/212.md

@@ -1,52 +0,0 @@
----
-id: 向后兼容性合规报告
-kind: artifact
-title: 向后兼容性合规报告
-sync_policy: copy_to_project
-status: active
-extra:
-  name: backward-compatibility-report
-  type: artifact
-  scope:
-    - '*'
-  domain: design
-  lifecycle_status: active
-  stage: design
-  owner_mechanism: mc-existing-system-artifact
----
-
-# 向后兼容性合规报告
-
-## 1. 检查范围
-- 检查时间：<!-- 日期 -->
-- 检查版本：<!-- 版本号 -->
-
-## 2. 接口兼容性
-
-| 接口 | 检查项 | COMP 规则 | 兼容 | 说明 |
-|---|---|---|---|---|
-| <!-- 接口名 --> | 参数是否被删除 | COMP-API-01 | 是/否 | <!-- 说明 --> |
-| <!-- 接口名 --> | 参数类型是否窄化 | COMP-API-02 | 是/否 | <!-- 说明 --> |
-| <!-- 接口名 --> | 返回结构是否破坏性变更 | COMP-API-03 | 是/否 | <!-- 说明 --> |
-
-## 3. 数据库兼容性
-
-| 表 | 检查项 | COMP 规则 | 兼容 | 说明 |
-|---|---|---|---|---|
-| <!-- 表名 --> | 是否删除列 | COMP-DB-01 | 是/否 | <!-- 说明 --> |
-| <!-- 表名 --> | 新增列是否有默认值 | COMP-DB-03 | 是/否 | <!-- 说明 --> |
-| <!-- 表名 --> | 变更对老数据是否兼容 | — | 是/否 | <!-- 说明 --> |
-
-## 3.5 行为兼容性
-
-| 功能 | 检查项 | COMP 规则 | 兼容 | 证据 |
-|------|--------|---------|------|------|
-| <!-- 功能 --> | 开关关闭时输出与老版本一致 | COMP-BEH-01 | 是/否 | 新老逻辑比对日志 |
-| <!-- 功能 --> | 新老逻辑可共存 | COMP-BEH-02 | 是/否 | Feature Toggle 切换测试 |
-| <!-- 功能 --> | 回滚后功能恢复正常 | COMP-BEH-03 | 是/否 | 回滚验证记录 |
-
-## 4. 结论
-- **兼容率：** 兼容项数 / 总检查项数 = <!-- 百分比 -->
-- **整体结论：** 通过（兼容率 100%）/ 不通过
-- **风险项：**
-  - <!-- 风险描述 -->

package/templates/design//345/221/275/344/273/244/346/211/247/350/241/214-procedures.md

@@ -1,45 +0,0 @@
----
-id: ka-procedure-命令执行流程
-kind: guidance
-title: 命令执行
-sync_policy: copy_to_project
-status: active
-triggers:
-  - 命令执行流程
-extra:
-  name: command-execution-workflow
-  scope:
-    - '*'
-  products:
-    - '*'
-  lifecycle_status: active
-  version: 1.1.0
-  last_reviewed: '2026-06-01'
-  type: procedure
-  domain:
-    - build
-    - design
-  verification_layer: L2
-  stage: design
-  owner_mechanism: mc-command-execution
----
-
-# 命令执行流程
-
-## 步骤
-
-1. 接收命令 (command string)
-2. 调用 classifyCommand 分级
-3. 检查分级结果:
-   - destructive → 需人工确认
-   - mutating → 可执行，记录证据
-   - read_only → 自由执行
-4. 执行命令
-5. 收集执行结果和证据
-6. 记录到 task_context
-
-## 注意事项
-
-- 命令分级基于模式匹配，不是白名单
-- 未知命令默认为 mutating
-- 命令参数中的敏感信息需脱敏

package/templates/design//345/221/275/344/273/244/350/267/257/347/224/261-procedures.md

@@ -1,46 +0,0 @@
----
-id: ka-procedure-命令路由流程
-kind: guidance
-title: 命令路由
-triggers:
-  - 命令路由
-  - 路由
-  - 命令分发
-sync_policy: copy_to_project
-status: active
-extra:
-  name: command-routing-workflow
-  scope:
-    - '*'
-  products:
-    - '*'
-  type: procedure
-  lifecycle_status: active
-  domain:
-    - design
-    - build
-    - verify
-    - operate
-  version: 2.0.0
-  last_reviewed: '2026-06-12'
-  verification_layer: L2
-  stage: design
-  owner_mechanism: mc-command-router
----
-
-# 命令路由流程
-
-## 步骤
-
-1. sf_task 接收用户意图文本（intent）+ 上下文（system_context / tech_stack）
-2. sf_task（start 动作）调用 `routeIntent(intent, context, domainContracts)`
-3. `routeIntent` 遍历 `ROUTE_TABLE`，匹配意图关键词
-4. 命中 → 返回 `{ domain, required_artifacts }`（`required_artifacts` 由该域契约 `required` 产物推导）
-5. 未命中 → 默认返回 `{ domain: "design", required_artifacts: [] }`（先想清楚再做）
-6. sf_task 将 `domain` 写入 task_context，后续工具按域分发
-
-## 注意事项
-
-- `routeIntent` 是纯计算函数，不读写任务状态，不触发副作用
-- 轻量任务（直接问答 / 单产物脚手架）由 sf_task / sf_scaffold 承载，不经域路由强制
-- `ROUTE_TABLE` 与 4 能力域枚举的一致性由 `check:schema-enum` 门禁守护

package/templates/design//345/221/275/345/220/215.md

@@ -1,49 +0,0 @@
----
-id: ka-pattern-naming-convention
-kind: knowledge
-title: 命名
-sync_policy: copy_to_project
-status: active
-extra:
-  name: naming-convention
-  scope:
-    - backend
-    - frontend
-  products:
-    - '*'
-  lifecycle_status: active
-  version: 1.1.0
-  last_reviewed: '2026-06-01'
-  type: knowledge
-  domain:
-    - build
-    - design
-  verification_layer: L2
-  stage: design
-  owner_mechanism: mc-general-pattern
----
-
-## 决策规则
-- Java 类名使用 UpperCamelCase，方法/变量使用 lowerCamelCase，常量使用 UPPER_SNAKE_CASE
-- 数据库表名使用 snake_case，字段名使用 snake_case，主键统一命名为 id
-- API 路径使用 kebab-case 复数名词（如 /api/v1/user-orders），禁止在路径中使用动词
-- 前端组件文件名使用 PascalCase，CSS 类名使用 kebab-case，路由路径使用 kebab-case
-- 禁止使用无业务含义的命名（data、info、result、temp、list、item、obj）
-- Boolean 变量/方法必须以 is/has/can/should 开头（如 isActive、hasPermission）
-- 接口/抽象类命名应体现行为意图（如 UserRepository、PaymentService）
-- 枚举类名使用名词，枚举值使用 UPPER_SNAKE_CASE
-- 包名使用全小写点分隔（com.company.module.service），禁止下划线或大写
-- 常量必须定义在常量类或枚举中，禁止散落在业务代码各处
-- 方法名应为动词或动词短语（getUserById、calculateTotalAmount）
-- 泛型类型参数使用大写单字母或简写（T、E、K、V、R、REQ、RESP）
-- 配置项 key 使用点分隔的 kebab-case（spring.datasource.url）
-
-## 验收项
-- [AC-01] Java 类/方法/变量/常量命名风格一致
-- [AC-02] 数据库表名/字段名统一 snake_case
-- [AC-03] API 路径 kebab-case + 复数名词
-- [AC-04] 前端组件 PascalCase、CSS kebab-case
-- [AC-05] 无无含义命名（data/info/result/temp）
-- [AC-06] Boolean 变量 is/has/can 前缀
-- [AC-07] 方法名为动词短语
-- [AC-08] 枚举值 UPPER_SNAKE_CASE

package/templates/design//345/242/236/351/207/217/350/276/271/347/225/214/347/225/214/345/256/232/346/226/207/346/241/243.md

@@ -1,48 +0,0 @@
----
-id: 增量边界界定文档
-kind: artifact
-title: 增量边界界定文档
-sync_policy: copy_to_project
-status: active
-extra:
-  name: incremental-boundary-document
-  type: artifact
-  scope:
-    - '*'
-  domain: design
-  lifecycle_status: active
-  stage: design
-  owner_mechanism: mc-existing-system-artifact
----
-
-# 增量边界界定文档
-
-## 1. 变更范围
-- 系统名称：<!-- 系统名 -->
-- 版本基线：<!-- 基线版本 -->
-
-## 2. 受影响模块
-
-| # | 模块 | 变更类型 | 关联需求 | 说明 |
-|---|------|---------|---------|------|
-| 1 | <!-- 模块名 --> | 新增/修改/删除 | REQ-NNN | <!-- 说明 --> |
-
-> 变更类型判定：纯新文件/函数/表 → 新增；已有文件中的新增字段/接口 → 修改；移除已有功能 → 删除
-
-## 3. 受影响接口
-
-| # | 接口 | 变更类型 | 关联需求 | 说明 |
-|---|------|---------|---------|------|
-| 1 | <!-- 接口名 --> | 新增/修改/废弃 | REQ-NNN | <!-- 说明 --> |
-
-## 4. 纯新增功能
-
-| # | 功能 | 关联需求 | 涉及模块 | 说明 |
-|---|------|---------|---------|------|
-| 1 | <!-- 功能描述 --> | REQ-NNN | <!-- 模块名 --> | <!-- 说明 --> |
-
-## 5. 改造范围
-
-| # | 改造项 | 原逻辑 | 改造目标 | 关联需求 | 风险等级 |
-|---|--------|--------|---------|---------|---------|
-| 1 | <!-- 改造描述 --> | <!-- 原有行为 --> | <!-- 改造后行为 --> | REQ-NNN | 高/中/低 |

package/templates/design//345/267/245/345/205/267/350/260/203/347/224/250-procedures.md

@@ -1,41 +0,0 @@
----
-id: ka-procedure-工具调用流程
-kind: guidance
-title: 工具调用
-sync_policy: copy_to_project
-status: active
-triggers:
-  - 工具调用流程
-extra:
-  name: tool-invocation-workflow
-  scope:
-    - '*'
-  products:
-    - '*'
-  lifecycle_status: active
-  version: 1.1.0
-  last_reviewed: '2026-06-01'
-  type: procedure
-  domain:
-    - build
-    - design
-  verification_layer: L2
-  stage: design
-  owner_mechanism: mc-tool-invocation-contract
----
-
-# 工具调用流程
-
-## 步骤
-
-1. 接收工具调用请求 (tool_name, arguments)
-2. 在 Tool Invocation Contract Registry 中查找工具契约
-3. 检查当前调用链是否违反 forbidden_next_tools
-4. 检查 strict_controlled 工具的前置审批
-5. 执行工具调用
-6. 记录 tool_trace
-
-## 注意事项
-
-- 只读工具可自由调用，不受转换约束
-- 工具调用失败时记录到 task_context

package/templates/design//345/271/266/345/217/221/346/216/247/345/210/266.md

@@ -1,50 +0,0 @@
----
-id: ka-pattern-concurrency-control
-kind: knowledge
-title: 并发控制
-sync_policy: copy_to_project
-status: active
-extra:
-  name: concurrency-control
-  scope:
-    - backend
-  products:
-    - '*'
-  lifecycle_status: active
-  version: 1.1.0
-  last_reviewed: '2026-06-01'
-  type: knowledge
-  domain:
-    - build
-    - design
-  verification_layer: L2
-  stage: design
-  owner_mechanism: mc-backend-pattern
----
-
-## 决策规则
-- 涉及金额、库存、配额、计数器等可变共享状态的操作必须显式声明并发控制策略
-- 乐观锁适用于读多写少场景（版本号字段 + CAS），悲观锁适用于写多竞争激烈场景（SELECT FOR UPDATE）
-- 分布式环境必须使用分布式锁（Redis SETNX / Redisson / ZooKeeper），禁止依赖 JVM 级锁跨实例
-- 锁粒度必须最小化：锁具体资源而非整个表，锁业务 ID 而非全局锁
-- 分布式锁必须设置超时时间（防止死锁），建议默认 30 秒
-- 幂等方案优先于加锁：唯一约束、去重表、Token 机制比分布式锁更可靠
-- 超卖/超扣场景必须使用数据库原子操作（UPDATE SET stock = stock - 1 WHERE stock >= 1），禁止先查后改
-- 乐观锁冲突必须有用户可见提示（"数据已被修改，请刷新重试"），禁止静默失败
-- 批量并发操作必须限制并发度（信号量/线程池），禁止无限制并发
-- ThreadLocal 必须在请求结束时 remove()，否则线程池复用导致数据串线
-- 锁的获取和释放必须在同一个 try-finally 块中，防止异常导致死锁
-- 分布式锁必须设置过期时间（如 30s），防止持有者崩溃导致永久死锁
-- 原子操作优先使用 CAS（AtomicInteger/LongAdder），无竞争场景性能优于锁
-- 线程池必须通过 ThreadPoolExecutor 构造函数创建，禁止使用 Executors（避免 OOM）
-
-## 验收项
-- [AC-01] 共享可变状态操作有显式并发控制策略
-- [AC-02] 分布式锁有超时设置
-- [AC-03] 超卖场景使用原子操作而非先查后改
-- [AC-04] 乐观锁冲突有用户提示
-- [AC-05] 批量并发操作有并发度限制
-- [AC-06] ThreadLocal 请求结束清理
-- [AC-07] 锁释放 try-finally 保护
-- [AC-08] 分布式锁有超时时间
-- [AC-09] 线程池显式创建