dsh-switchman 1.3.0

package/skills/requirement-docs/references/templates.md

@@ -0,0 +1,187 @@
+# 文档模板
+
+按文档类型选骨架，一级标题序号风格全文统一。四条核心原则见 SKILL.md 第二节。
+
+## 设计文档（重点模板）
+
+适用：存量系统改造的技术方案。文件名 `yyyy-mm-dd-模块-业务设计.md`。
+
+````markdown
+# {模块} — {业务}设计
+
+> 版本：v1.0　　日期：yyyy-mm-dd　　关联模块：`service-a`、`service-b`
+>
+> **已确认决策（yyyy-mm-dd）**：
+> - **{决策点1}**：{结论}。
+> - **{决策点2}**：{结论，含绕过/复用/回滚等关键动作}。
+
+## 1. 需求概述
+
+一两段话讲清要解决什么问题、在现有逻辑基础上新增/改造什么。分条列核心能力点，粗体点关键词。
+
+## 2. 现状分析（带代码证据，禁止空写背景）
+
+### 2.1 关键调用链
+
+从入口画到核心逻辑，标 `文件名:行号`：
+```
+Controller.xxx()                          // XxxController.java:123
+  └─ ServiceImpl.xxx()                    // XxxServiceImpl.java:456
+       └─ [回调] YyyServiceImpl.zzz()     // YyyServiceImpl.java:101
+            ├─ 现有方法A()                 // :160  ★改造点
+            └─ 现有方法B()                 // :170  异常被吞
+```
+附关键结论：后处理真正在哪、哪些异常被吞、哪些代码已注释废弃。
+
+### 2.2 现有逻辑清单
+
+| 块 | 触发条件 | 逻辑 | 对本需求影响 |
+|---|---|---|---|
+| 逻辑A | 条件A | 做了什么 | ✅ 可复用 / ❌ 需改造 |
+
+### 2.3 可参照样板（如有）
+
+项目里已有类似实现（哪怕另一入口/端）就指出：位置、做了什么、与本需求的差异。避免重复造轮子。
+
+### 2.4 表/接口/枚举现状
+
+| 关注点 | 现状 | 影响 |
+|---|---|---|
+| 某查询 | 全仓库不存在 | ❌ 需新增 |
+
+## 3. 差异点对比表（全文最实用的部分）
+
+| # | 差异点 | 现状 | 本需求要求 |
+|---|---|---|---|
+| D1 | 适用范围 | 仅写表 | 写表 **且** 出库 |
+| D2 | 查找口径 | 线边库 | 按明细行料仓 |
+
+## 4. 技术方案
+
+按差异点逐个给方案，子节标题标对应编号。
+
+### 4.1 {核心难点}（对应 D1/D2）
+
+**问题**：为什么难（时机、状态一致性…）。
+**方案**：具体怎么改，引用改造点 `文件:行号` 与方法名，可给前后对比代码或伪代码。
+> ⚠️ {需确认/小心的点}。
+
+## 5. 数据来源口径
+
+关键字段从哪取，歧义处列方案对比并给倾向：
+
+1. **【已定】字段A**：取 `Entity.field`。⚠️ 落地前验证空值兜底。
+2. **【待定】字段B**：方案1 `create_time`（简单）/ 方案2 `MIN(create_time)`（精确，需 JOIN）。倾向：方案1，需拍板。
+
+## 6. 影响面与风险
+
+每条风险必附应对，不只列风险：
+
+| 风险 | 说明 | 应对 |
+|---|---|---|
+| 并发抢占 | 同时被多请求操作 | 真实失败回滚、写日志人工处理 |
+| 窗口期 | 预校验与执行间状态被改 | 预校验软拦截，以原子操作为准 |
+
+## 7. 待确认问题清单
+
+已确认决策见文首。此处逐条对照（已定也列出，待定必须给倾向）：
+
+1. **【已定】{点1}**：{结论}。
+2. **【待定】{点2}**：{问题}？倾向：{建议}。
+
+## 8. 落地方案概览
+
+改造后的调用结构图 + 新增/改造文件清单（按服务分组，每文件一句话职责）。
+
+## 附录 A：关键文件与行号速查
+
+| 内容 | 位置 |
+|---|---|
+| 入口 | `XxxController.java:123` |
+| 可参照样板 | `YyyServiceImpl.java:300-400`（`sampleMethod`） |
+| 状态枚举 | `XxxStatusEnum.java` |
+````
+
+---
+
+## 需求分析（轻量模板）
+
+适用：明确"做什么、为什么、完成标准"。文件名 `yyyy-mm-dd-模块-业务需求分析.md`。存量改造时保留现状分析，纯新功能可省差异点表。
+
+````markdown
+# {模块} — {业务}需求分析
+
+- 日期：yyyy-mm-dd　　状态：草案 / 评审中 / 已确认
+
+## 1. 需求概述
+
+要解决什么问题、交付什么价值。
+
+## 2. 背景与现状
+
+现状怎么做的（带 `文件:行号` 证据）、什么痛点、为什么现在做。
+
+## 3. 用户角色与场景
+
+角色 + 典型操作路径。
+
+## 4. 功能性需求
+
+按模块编号拆条目，写清输入/处理/输出。
+
+## 5. 非功能性需求
+
+性能 / 安全 / 兼容 / 可观测性。
+
+## 6. 验收标准
+
+可测的完成标准（checklist 或 Given-When-Then）。
+
+## 7. 待确认问题清单
+
+1. **【待定】{点}**：{问题}？倾向：{建议}。
+
+## 8. 范围外
+
+明确不做什么。
+````
+
+---
+
+## 开发计划
+
+适用：把设计落成可执行任务。文件名 `yyyy-mm-dd-模块-业务开发计划.md`。
+
+````markdown
+# {模块} — {业务}开发计划
+
+- 日期：yyyy-mm-dd　　状态：进行中 / 部分完成 / 已完成
+- 关联设计：`docs/需求分析与设计/yyyy-mm-dd-xxx-xxx设计.md`
+
+## 1. 目标
+
+一句话目标。
+
+## 2. 任务拆解
+
+按差异点编号或阶段分组，任务用 checkbox：
+
+### 阶段 1：预校验（对应设计 D1/D4）
+- [ ] T1 新增 `checkXxx()`，在 `approve()` 插入（涉及：`XxxServiceImpl.java`）
+
+## 3. 文件结构
+
+新增/修改文件清单，每文件一句话职责。
+
+## 4. 依赖与顺序
+
+哪些必须先做、哪些可并行。
+
+## 5. 里程碑 / 验收点
+
+阶段性可验证的交付物。
+
+## 6. 风险项
+
+对应设计文档第 6 节的风险，标注本次如何应对。
+````