adspecs 0.1.12

package/skills/adspecs-utest/SKILL.md

@@ -0,0 +1,390 @@
+---
+name: adspecs-utest
+description: "基于后端系统设计文档，生成 Service 层 / Controller 层单元测试代码，并按模板输出单元测试报告"
+argument-hint: "指定功能名或系统设计文档路径，如 M06-01 或 docs/30-system-design/crm/M06-01-销售预测_system-design.md"
+compatibility: "需要 docs/ 目录体系：docs/20-prd（PRD）+ docs/30-system-design（系统设计+tasks）+ CLAUDE.md（ECP 编码宪章）"
+metadata:
+  author: "qingwen"
+  source: "基于 adspecs-analyze 通用模板 + ECP 全链路追溯 ID 体系 + CLI 规范 10 条 + TDD 一致性检测改造"
+user-invocable: true
+disable-model-invocation: false
+---
+
+# 生成单元测试用例与测试报告
+
+## 定位
+
+本技能是 adspecs 流水线中 **编码实现之后** 的质量保障环节：
+
+```
+/adspecs-prd → /adspecs-plan → /adspecs-tasks → subagent-driven-development → 本技能（adspecs-utest）
+```
+
+| 对比项   | 本技能（adspecs-utest）                | /adspecs-tasks     |
+| -------- | -------------------------------------- | ------------------ |
+| 输出     | 测试代码（Java）+ 测试报告（md）       | TDD 任务清单（md） |
+| 目标读者 | 开发工程师 / 测试工程师                | 开发工程师         |
+| 关注点   | 验证 Service/Controller 业务逻辑正确性 | 拆解编码实现步骤   |
+| 阶段     | 编码完成后                             | 编码之前           |
+
+## 任务
+
+读取用户指定的后端系统设计文档，生成 **两类输出**：
+
+1. **单元测试代码**（`.java`）— Service 层测试 + Controller 层测试，JUnit 5 + Mockito，遵循项目现有测试模式
+2. **单元测试报告**（`.md`）— 按 `.adspecs/templates/07-单元测试报告模板.md` 结构填写
+
+本技能**不修改**业务代码、不生成集成测试、不执行测试运行。
+
+## 路径配置加载
+
+在开始执行之前，先确定输入/输出目录：
+
+1. 检查项目根目录是否存在 `.adspecs/paths.json`
+2. 如果存在，读取其中的 `paths` 对象，提取本技能需要的配置键
+3. 如果不存在或配置键缺失，使用下方表格中的默认值
+
+| 配置键            | 默认值                  | 用途                     |
+| ----------------- | ----------------------- | ------------------------ |
+| `design_dir`      | `docs/30-system-design` | 系统设计文档目录（输入） |
+| `test_report_dir` | `docs/80-development`   | 单元测试报告输出目录     |
+
+将解析后的路径分别记为 `DESIGN_DIR` 和 `TEST_REPORT_DIR`，后续步骤中引用这些变量而非硬编码路径。
+
+## 输入
+
+### 必读文件（按顺序）
+
+| 序号 | 文件                                                                               | 用途                                                     |
+| ---- | ---------------------------------------------------------------------------------- | -------------------------------------------------------- |
+| 1    | 用户指定的系统设计文件（如 `{DESIGN_DIR}/crm/M01-01-产品主数据_system-design.md`） | 提取 Service 方法、Controller 端点、异常码、§12 测试场景 |
+| 2    | `.adspecs/templates/07-单元测试报告模板.md`                                         | 测试报告的输出模板（6 部分结构）                         |
+| 3    | `CLAUDE.md`                                                                        | 项目模块结构、测试框架约定、包路径规范                   |
+
+### 参考文件（按需读取）
+
+| 序号 | 文件                                         | 用途                                 |
+| ---- | -------------------------------------------- | ------------------------------------ |
+| 4    | 已有的 `*Test.java` 文件（同模块或相邻模块） | 对齐项目现有测试风格和 Mock 模式     |
+| 5    | 对应的 `*_tasks.md` 文件                     | 了解 T0xx 任务编号与 US 的映射关系   |
+| 6    | 实际的 Service / Controller 源码             | 了解方法签名、依赖注入、业务逻辑细节 |
+| 7    | 对应的 i18n `.properties` 文件               | 确认消息码与实际异常描述的对应       |
+
+## 项目测试约定
+
+### 技术栈
+
+| 项         | 值                                                                       |
+| ---------- | ------------------------------------------------------------------------ |
+| 测试框架   | JUnit 5（`org.junit.jupiter`）                                           |
+| Mock 框架  | Mockito（`@ExtendWith(MockitoExtension.class)`）                         |
+| 断言       | JUnit 5 Assertions（`assertEquals`, `assertNotNull`, `assertThrows` 等） |
+| 显示名称   | `@DisplayName("T0xx [US-xx] 描述")`                                      |
+| 覆盖率目标 | 行覆盖率 100%，分支覆盖率 100%                                           |
+
+### 测试类命名与位置
+
+| 被测类                 | 测试类命名                 | 测试类位置                                                                                                 |
+| ---------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `CrmProductService`    | `CrmProductServiceTest`    | `3100-crm-{mod}-application/src/test/java/com/sie/crm/{mod}/model/service/impl/CrmProductServiceTest.java` |
+| `CrmProductController` | `CrmProductControllerTest` | `3100-crm-{mod}-application/src/test/java/com/sie/crm/{mod}/api/controller/CrmProductControllerTest.java`  |
+
+### Service 层测试模式（Mockito + @Spy + @InjectMocks）
+
+```java
+@ExtendWith(MockitoExtension.class)
+@DisplayName("{ClassName} 单元测试")
+class {ClassName}Test {
+
+    @Mock
+    private {DaoName} {daoField};
+
+    @Spy
+    @InjectMocks
+    private {ServiceImplName} {serviceField};
+
+    // setUp() 中构建 mock 数据
+
+    @Test
+    @DisplayName("T0xx [US-xx] 场景描述 — 预期结果")
+    void methodName_scenario() {
+        // Given
+        doReturn(...).when(...).method(...);
+        // When
+        var result = service.method(args);
+        // Then
+        assertNotNull(result);
+        assertEquals(expected, result.getXxx());
+    }
+}
+```
+
+**关键约定**：
+
+- Service 实现类使用 `@Spy + @InjectMocks`，因为需要 mock 继承自 `BaseCommonServer` 的方法（如 `getById`, `save`, `updateById`, `deleteById`）
+- DAO 使用 `@Mock`
+- 测试方法命名：`methodName_scenarioDescription`（驼峰式，不用下划线分隔单词）
+- 异常测试用 `assertThrows(ExceptionClass.class, () -> ...)`
+- 无异常测试用 `assertDoesNotThrow(() -> ...)`
+
+### Controller 层测试模式（Mockito + @InjectMocks）
+
+```java
+@ExtendWith(MockitoExtension.class)
+@DisplayName("{ClassName} 集成测试")
+class {ClassName}Test {
+
+    @Mock
+    private II{Entity} {serviceField};
+
+    @InjectMocks
+    private {ControllerName} controller;
+
+    // setUp() 中构建 mockEntity 和 mockRo
+
+    @Test
+    @DisplayName("T0xx [US-xx] HTTP METHOD /path → 预期结果")
+    void endpointName_scenario() {
+        // Given
+        doReturn(...).when(service).method(...);
+        // 构造 RequestData / PaginationRequestData
+        // When
+        ResponseData<...> response = controller.method(requestData);
+        // Then
+        assertNotNull(response);
+        assertNotNull(response.getData());
+    }
+}
+```
+
+**关键约定**：
+
+- Controller 使用 `@InjectMocks`（非 Spy），因为不测试继承行为
+- Service 使用 `@Mock`
+- 需手动构造 `RequestData<Dto>` 和 `PaginationRequestData<Dto>`
+- 测试 Controller 的 dto 为 null 场景（返回 `ResponseData.fail`）
+- 验证 `ResponseData` 的 code / data 结构
+
+### @DisplayName 命名规则
+
+**Service 测试**：`T0xx [US-xx] 方法名 — 场景描述，预期结果`
+
+- 示例：`T016-1 [US-01] 分页查询 — 无条件分页，返回 1 条记录`
+- 示例：`T028-2 [US-03] 新增 — 编码重复，抛出 GushenRuntimeException`
+
+**Controller 测试**：`T0xx [US-xx] HTTP方法 /端点 → 预期结果`
+
+- 示例：`T021 [US-03] POST /save → 200 + entity，productCode 非空`
+- 示例：`T030 [US-01] POST /find-pagination → dto 为 null → 返回失败`
+
+## 工作流程
+
+### 步骤 1：读取并分析系统设计文档
+
+1. 读取用户指定的 `*_system-design.md` 文件
+2. 提取以下关键信息并记录：
+
+| 提取项                         | 来源章节            | 用途                       |
+| ------------------------------ | ------------------- | -------------------------- |
+| 模块元数据（端口、包名、表名） | §1                  | 确定测试类路径、消息码前缀 |
+| Entity 字段定义                | §2.2                | 构建 mock 数据             |
+| DTO 字段与校验规则             | §2.3                | 构造测试入参               |
+| Ro 字段定义                    | §2.4                | 验证详情查询返回           |
+| DAO 方法签名                   | §3.3.1              | 确定 DAO Mock 方法         |
+| Service 接口与实现逻辑         | §4.4, §4.5          | 确定被测方法和业务逻辑分支 |
+| Controller 端点                | §5.1, §5.2          | 确定 Controller 测试端点   |
+| 异常码与触发条件               | §7.1, §7.3          | 确定异常测试用例           |
+| **§12 测试场景（最重要）**     | §12.1, §12.2, §12.3 | **直接映射为测试用例**     |
+
+3. 读取 `CLAUDE.md` 确认模块路径和测试框架约定
+
+### 步骤 2：读取参考文件（对齐风格）
+
+1. 检查同模块下已有的 `*Test.java` 文件，对齐测试风格
+2. 如果没有，读取相邻模块的测试文件作为参考：
+   - `3100-crm-mdm/.../CrmProductServiceTest.java`
+   - `3100-crm-mdm/.../CrmCustomerControllerTest.java`
+3. 如果存在 `*_tasks.md`，读取 T0xx 编号与 US 的映射
+
+### 步骤 3：生成 Service 层测试代码
+
+根据 §12 测试场景和 §4 Service 设计，为每个 Service 方法生成测试：
+
+**每个 Service 方法至少覆盖以下测试分类**：
+
+| 分类     | 数量要求 | 说明                                       |
+| -------- | -------- | ------------------------------------------ |
+| 正常场景 | ≥1       | 合法输入，验证返回值关键字段               |
+| 异常场景 | ≥1       | 不存在/重复/非法输入，验证异常类型和消息码 |
+| 边界场景 | ≥1       | 空列表/空值/极值/分页超出范围              |
+
+**Service 测试生成规则**：
+
+1. **分页查询方法**（`findPagination`）：
+   - 无条件分页查询
+   - 按单个条件精确筛选
+   - 多条件组合筛选
+   - 无匹配结果（空列表）
+   - 分页超出范围
+
+2. **新增方法**（`saveXxx`）：
+   - 合法数据保存成功
+   - 唯一性字段重复（抛出 `GushenRuntimeException`）
+   - 默认值设置（如 isActive=1）
+
+3. **编辑方法**（`updateXxx`）：
+   - 合法更新成功，不可修改字段不变
+   - 数据不存在（抛出 `RecordNotExistsException`）
+
+4. **删除方法**（`deleteXxx`）：
+   - 存在数据逻辑删除成功
+   - 数据不存在（抛出 `RecordNotExistsException`）
+
+5. **详情查询方法**（`findById`）：
+   - 数据存在，返回完整字段
+   - 数据不存在（抛出 `RecordNotExistsException`）
+
+6. **编码查询方法**（`findByCode`）：
+   - 上架产品，返回完整信息
+   - 编码不存在，返回 null
+   - 已下架产品（如有此业务规则，抛出异常）
+
+**Mock 数据构建规则**：
+
+- 在 `@BeforeEach setUp()` 中构建 1-2 个可复用的 mock 对象
+- mock 对象的业务字段必须使用真实业务数据（如产品编码 "PROD-001"、产品名称 "5052 铝板"），不使用 "test1"、"abc" 等无意义数据
+- 异常场景专用的 mock 对象在测试方法内部构建
+
+### 步骤 4：生成 Controller 层测试代码
+
+根据 §5 Controller 设计和 §12 测试场景，为每个端点生成测试：
+
+**每个端点至少覆盖**：
+
+| 场景             | 验证内容                                      |
+| ---------------- | --------------------------------------------- |
+| 正常请求         | ResponseData 非空，data 字段正确              |
+| dto 为 null      | 返回 `ResponseData.fail`（Controller 空校验） |
+| Service 抛出异常 | 异常传播（Controller 不吞异常）               |
+
+**Controller 测试生成规则**：
+
+- 手动构造 `RequestData<Dto>` 和 `PaginationRequestData<Dto>`
+- 验证 `ResponseData` 的 code 和 data 结构
+- dto 为 null 场景直接传入 null 或构造空 RequestData
+
+### 步骤 5：生成单元测试报告
+
+按 `.adspecs/templates/07-单元测试报告模板.md` 的 6 部分结构生成测试报告：
+
+| 部分            | 内容来源                      | 填写规则                                                                               |
+| --------------- | ----------------------------- | -------------------------------------------------------------------------------------- |
+| 1. 测试概览     | 系统设计文档 §1, §4           | 填写基本信息、测试目标、测试范围、测试环境、测试标准                                   |
+| 2. 测试用例清单 | §12 测试场景 + 生成的测试方法 | **每个测试方法对应一个测试用例条目**，含测试描述、方法名、前置条件、输入数据、预期结果 |
+| 3. 测试覆盖率   | 基于代码分析                  | 列出每个被测类的预期覆盖率（目标 100%），分析未覆盖的代码（如有）                      |
+| 4. 测试结果     | 测试方法统计                  | 填写测试统计（总数、通过数、失败数）、占位测试执行日志                                 |
+| 5. 缺陷报告     | 基于测试分析                  | 如测试通过则填"无缺陷"；如发现逻辑问题则记录缺陷                                       |
+| 6. 测试总结     | 整体分析                      | 总结测试成果、关键发现、改进建议                                                       |
+
+**测试用例清单填写规则**：
+
+- 按被测类分组（如 `2.1 CrmProductService测试`）
+- 按场景分类（正常场景 / 异常场景 / 边界场景）
+- 每个用例包含：测试描述、测试方法名、前置条件、输入数据列表、预期结果、测试状态（设计阶段填"待执行"）
+- 输入数据用 `- 参数名: 值 - 说明` 格式
+
+### 步骤 6：保存文件
+
+| 输出            | 保存位置                                                                                             |
+| --------------- | ---------------------------------------------------------------------------------------------------- |
+| Service 测试    | `{port}-{mod}-application/src/test/java/com/sie/crm/{mod}/model/service/impl/{ServiceName}Test.java` |
+| Controller 测试 | `{port}-{mod}-application/src/test/java/com/sie/crm/{mod}/api/controller/{ControllerName}Test.java`  |
+| 测试报告        | `{TEST_REPORT_DIR}/{模块编号}-{模块名}_单元测试报告.md`                                              |
+
+## 输出
+
+### 文件命名
+
+| 文件类型        | 命名规则                              | 示例                                |
+| --------------- | ------------------------------------- | ----------------------------------- |
+| Service 测试    | `{ServiceName}Test.java`              | `CrmProductServiceTest.java`        |
+| Controller 测试 | `{ControllerName}Test.java`           | `CrmProductControllerTest.java`     |
+| 测试报告        | `{模块编号}-{模块名}_单元测试报告.md` | `M01-01-产品主数据_单元测试报告.md` |
+
+### 输出目录映射
+
+测试代码目录根据系统设计文档的模块元数据确定：
+
+| 系统设计文档中的模块 | 测试代码根路径                                                                     |
+| -------------------- | ---------------------------------------------------------------------------------- |
+| 3100-crm-mdm         | `crm-service/3100-crm-mdm/3100-crm-mdm-application/src/test/java/`                 |
+| 3103-crm-contract    | `crm-service/3103-crm-contract/3103-crm-contract-application/src/test/java/`       |
+| 3104-crm-fulfillment | `crm-service/3104-crm-fulfillment/3104-crm-fulfillment-application/src/test/java/` |
+
+## 测试用例编号规则
+
+测试用例编号与系统设计文档 §12 测试场景对应，同时也与 `*_tasks.md` 中的 T0xx 任务编号对齐：
+
+| 编号格式  | 说明                  | 示例                 |
+| --------- | --------------------- | -------------------- |
+| `T0xx-N`  | 主任务编号-子用例序号 | `T016-1`, `T028-2`   |
+| `[US-xx]` | 关联的用户故事        | `[US-01]`, `[US-03]` |
+
+**映射方法**：
+
+1. 如果 `*_tasks.md` 存在，读取其中的 T0xx 与测试方法的对应关系
+2. 如果不存在，按 Service 方法顺序分配 T0xx 编号：
+   - 第一个 Service 方法 → T01x
+   - 第二个 Service 方法 → T02x
+   - 以此类推
+
+## 质量检查
+
+生成文件后，逐项核对以下清单：
+
+### 测试代码质量
+
+- [ ] 每个 Service 方法至少 3 个测试用例（正常+异常+边界）
+- [ ] 每个 Controller 端点至少 2 个测试用例（正常+dto 为 null）
+- [ ] 测试方法命名规范：`methodName_scenarioDescription`
+- [ ] @DisplayName 包含 T0xx 编号和 [US-xx] 关联
+- [ ] Mock 数据使用真实业务数据，不使用无意义字符串
+- [ ] Service 测试使用 `@Spy + @InjectMocks`
+- [ ] Controller 测试使用 `@InjectMocks`
+- [ ] 异常测试使用 `assertThrows` 并验证异常类型
+- [ ] 无 import 未使用的类
+- [ ] 测试类在正确的包路径下
+
+### 测试报告质量
+
+- [ ] 报告 6 个部分全部覆盖
+- [ ] 测试用例清单与生成的测试方法一一对应
+- [ ] 每个用例包含完整的前置条件、输入数据、预期结果
+- [ ] 测试覆盖率表列出所有被测类
+- [ ] 测试统计数字与测试方法总数一致
+- [ ] 缺陷报告与实际测试分析一致
+
+### 覆盖完整性
+
+- [ ] §12.1 正常场景全部覆盖
+- [ ] §12.2 异常场景全部覆盖
+- [ ] §12.3 边界场景全部覆盖
+- [ ] §7.1 异常清单中每个异常至少有一个测试用例
+- [ ] §6.2 数据校验规则中的必填字段有对应的校验测试
+
+## 约束
+
+- **仅生成测试代码和测试报告**：不修改业务代码
+- **遵循项目现有测试模式**：参照已有的 `*Test.java` 文件风格
+- **不执行测试**：生成代码后不自动运行 `mvn test`
+- **不生成集成测试**：仅 Service 层单元测试 + Controller 层单元测试
+- **禁止 QueryWrapper**：测试中不直接使用 QueryWrapper 构造查询条件
+- **mock 继承方法**：对 `BaseCommonServer` 的 `getById`/`save`/`updateById`/`deleteById` 使用 `doReturn(...).when(spy).method(...)` 模式
+- **测试独立性**：每个测试方法独立运行，不依赖其他测试方法的执行顺序或结果
+
+## 触发关键词
+
+- `adspecs-utest` — 直接使用本技能
+- `生成单元测试` — 触发本技能
+- `生成测试用例` — 触发本技能
+- 在对话中指定系统设计文件即可，如：`使用 adspecs-utest 处理 {DESIGN_DIR}/crm/M01-01-产品主数据_system-design.md`

package/skills/adspecs-write-planning-report/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: adspecs-write-planning-report
+description: 汇总调研期所有分析输出，生成完整产品规划报告并落盘到 docs/00-planning/，是规划期的核心必选节点。
+---
+
+# Skill: adspecs-write-planning-report
+
+**类型**: 规划期 Skill（planning/ 组，必选）  
+**调用时机**: product-planning pipeline 第 5 节点（人工审批前）
+
+---
+
+## 用途
+
+汇集本次调研期的所有分析输出（用户反馈洞察、市场调研、竞品分析、当前产品快照），生成完整产品规划报告，落盘到 `docs/00-planning/{YYYY-MM-DD}-{slug}.md`。
+
+---
+
+## 参数
+
+| 参数                  | 类型   | 必填 | 说明                                                                               |
+| --------------------- | ------ | ---- | ---------------------------------------------------------------------------------- |
+| `topic`               | string | ✅   | 规划主题（写入报告标题）                                                           |
+| `target_version`      | string | ❌   | 目标版本号（写入 frontmatter）                                                     |
+| `prev_outputs`        | string | ❌   | 上游节点产物摘要（由 pipeline 自动注入）                                           |
+| `review_feedback`     | object | ❌   | 来自 review-planning-report 的 blockers、repair-instructions；存在时进入自修复模式 |
+| `self_repair_attempt` | number | ❌   | 当前自动修复轮次，由 pipeline reviewLoop 注入                                      |
+
+---
+
+## 执行步骤
+
+### Step 1 — 汇总上游输入
+
+读取对话上下文中的所有上游节点输出（analyze-user-feedback / conduct-market-research / run-competitive-analysis / analyze-current-product），将可用输出合并为规划报告的输入素材。若某节点标记为 SKIPPED，则对应章节填写"本次调研跳过此维度"。
+
+### Step 2 — 生成规划报告
+
+若存在 `review_feedback`，先进入自修复模式：
+
+1. 读取 `review_feedback.blockers`、`repair-instructions` 与上一版规划报告。
+2. 只围绕被指出的问题修订同一报告内容；不得无关扩写或重排已确认章节。
+3. 在报告末尾维护 `## 修订记录`，记录 `self_repair_attempt`、修复时间和 fixed-blockers。
+4. 输出必须包含 fixed-blockers，供下一轮 `review-planning-report` 核对。
+
+按以下结构生成报告：
+
+```yaml
+---
+id: planning-{YYYY-MM-DD}-{slug}
+type: PLANNING-REPORT
+title: {topic} 产品规划报告
+date: {YYYY-MM-DD}
+target-version: {target_version 或 tbd}
+status: draft
+summary: "{规划摘要第一段，30-80 字的执行摘要（从报告正文首节提炼）}"
+---
+```
+
+报告章节：
+
+1. **规划摘要**（Executive Summary，3-5 句）
+2. **调研背景** — 触发本次规划的关键事件 / 数据
+3. **用户反馈洞察** — 引用 analyze-user-feedback 输出（或"已跳过"）
+4. **市场与竞品信号** — 引用 conduct-market-research + run-competitive-analysis 输出
+5. **当前产品现状** — 引用 analyze-current-product 输出
+6. **规划建议** — 综合以上分析，给出 P0/P1/P2 优先级建议列表
+7. **路标建议** — 版本节奏建议（哪些功能进哪个版本）
+8. **待决策项** — 需人工审批确认的关键决策点
+
+### Step 3 — 落盘
+
+路径：`docs/00-planning/{YYYY-MM-DD}-{slug}.md`
+
+> **id 与文件名对齐规则**：
+>
+> - `_index.yml` 新增 entry 时，`id` 字段填写**不带 `planning-` 前缀**的值（即 `{YYYY-MM-DD}-{slug}`），与文件名保持一致，确保 `readIndexedCollection` 能按 id 正确定位文件。
+> - frontmatter 内部的 `id` 字段保持完整格式 `planning-{YYYY-MM-DD}-{slug}`，由 frontmatter 优先覆盖规则在 UI 层呈现完整 id。
+
+若文件已存在且不是自修复模式，在文件名追加 `-v{N}` 后缀。若是自修复模式，修订原规划报告路径，保持 review 与 human approval 引用稳定。
+
+### Step 4 — 输出摘要
+
+输出落盘路径、报告摘要、"待决策项"清单，以及自修复模式下的 fixed-blockers，供下一轮 `review-planning-report` 使用。只有评审通过后才进入人工审批。
+
+---
+
+## 错误处理
+
+| 场景                       | 处理                                     |
+| -------------------------- | ---------------------------------------- |
+| 所有上游节点均 SKIPPED     | 仍然生成框架报告，各章节填写"数据不可用" |
+| `docs/00-planning/` 不存在 | 自动创建目录                             |

package/skills/adspecs-write-roadmap/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: adspecs-write-roadmap
+description: 人工审批通过后，将规划报告中的版本节奏建议追写/更新到 docs/00-planning/roadmap.md，完成调研规划期的最终输出。
+---
+
+# Skill: adspecs-write-roadmap
+
+**类型**: 规划期 Skill（planning/ 组）  
+**调用时机**: product-planning pipeline 最后节点（人工审批通过后）
+
+---
+
+## 用途
+
+将规划报告中已审批通过的版本节奏建议追写到 `docs/00-planning/roadmap.md`，保持路标文档的持续更新。若文件不存在则新建。
+
+---
+
+## 参数
+
+| 参数                   | 类型   | 必填 | 说明                                          |
+| ---------------------- | ------ | ---- | --------------------------------------------- |
+| `topic`                | string | ✅   | 本次规划主题（用于路标条目标题）              |
+| `target_version`       | string | ❌   | 版本号；若为空则从规划报告 frontmatter 中读取 |
+| `planning_report_path` | string | ❌   | 规划报告文件路径（由 pipeline 自动注入）      |
+
+---
+
+## 执行步骤
+
+### Step 1 — 读取规划报告
+
+读取 `{{planning_report_path}}` 中的"路标建议"章节，提取各版本的功能集与时间节点。
+
+### Step 2 — 读取现有路标
+
+读取 `docs/00-planning/roadmap.md`（若不存在则视为空文档）。
+
+### Step 3 — 合并更新
+
+追写/更新规则：
+
+- 若路标中已存在 `{{target_version}}` 条目：在该版本条目下追加本次规划新增的功能项（不删除已有内容）
+- 若路标中无该版本：在合适位置（按版本号顺序）插入新版本节
+
+路标格式约定：
+
+```markdown
+## 路标（Roadmap）
+
+> 最后更新：{YYYY-MM-DD}
+
+### {target_version}（{计划时间范围}）
+
+**主题**：{版本主题}
+
+| 功能 / CR                        | 优先级 | 来源            | 状态   |
+| -------------------------------- | ------ | --------------- | ------ |
+| {feature-id 或 CR-ID}（{title}） | P0     | planning-{date} | 规划中 |
+```
+
+### Step 4 — 落盘
+
+幂等写回 `docs/00-planning/roadmap.md`。
+
+Commit：`[planning] update roadmap for {topic} (${target_version})`
+
+### Step 5 — 输出摘要
+
+```
+✅ 路标更新完成
+   文件     : docs/00-planning/roadmap.md
+   新增条目 : {N} 条
+   版本节   : {target_version}
+```
+
+---
+
+## 注意事项
+
+1. **幂等**：重跑不产生重复条目（按功能 ID 去重）
+2. **只追加不删除**：不得删除路标中已有的条目，仅新增或更新状态字段
+3. **不影响 wiki/**：路标文件仅位于 `docs/00-planning/`，与 wiki/ 无关