adspecs 0.1.12

package/.adspecs/templates/14-/351/234/200/346/261/202/350/277/275/346/272/257/347/237/251/351/230/265/346/250/241/346/235/277.md

@@ -0,0 +1,225 @@
+# 需求追溯矩阵模板
+
+> **版本**: v1.0
+> **创建日期**: 2026-06-09
+> **适用人员**: 测试工程师、AI助手
+> **目的**: 提供需求→设计→用例全链路追溯矩阵的标准模板，由 AI 自动扫描各阶段文档的 ID 引用聚合生成，支撑验收评审
+
+---
+
+## 📝 使用说明
+
+### 生成方式
+
+本矩阵**不是手工维护品**。AI 在测试用例编写完成后，通过扫描以下固定标签自动聚合生成：
+
+| 扫描源 | 扫描标签 | 产出 |
+|--------|---------|------|
+| 需求分析文档 | `## 0. 需求 ID 映射` 表格 | 完整 ID 清单（基准） |
+| 系统设计文档 | `**实现需求**:` | 需求→设计映射 |
+| 测试用例文档 | `**覆盖需求**:` | 用例→需求映射 |
+
+### 生成时机
+
+在 `adspecs-systemdesign` 完成后、测试用例编写完成后，AI 执行扫描并生成矩阵。
+
+### 用途
+
+- **验收评审**：评审者只需看矩阵中某条验收标准的"设计覆盖"和"用例覆盖"是否打 ✅
+- **缺失发现**：覆盖率 < 100% 的行即为"未对齐"，需补充设计或测试
+- **审计追溯**：从任意测试用例可反向定位到验证的需求；从任意需求可正向查找覆盖它的设计和用例
+
+---
+
+## 矩阵模板
+
+```markdown
+# 需求追溯矩阵
+
+**功能**: {功能名称}
+**需求分析文档**: {需求分析文档路径}
+**系统设计文档**: {系统设计文档路径}
+**更新日期**: {YYYY-MM-DD}
+
+---
+
+## 表1 — 需求→设计→用例（前向追溯）
+
+> 验"做全了没有"：每条需求是否有设计实现、是否有测试验证？
+
+### 1.1 用户故事
+
+| 需求 ID | 故事简述 | 设计覆盖 | 用例覆盖 | 状态 |
+|---------|---------|:---:|:---:|:---:|
+| US-01 | {故事标题} | {设计要素1, 设计要素2} | {用例1, 用例2} | {✅/❌} |
+| US-02 | {故事标题} | {设计要素} | {用例} | {✅/❌} |
+
+### 1.2 验收场景
+
+| 需求 ID | 场景简述 | 所属故事 | 设计覆盖 | 用例覆盖 | 状态 |
+|---------|---------|---------|:---:|:---:|:---:|
+| US-01-AC1 | {场景描述} | US-01 | ✅ | ✅ | ✅ |
+| US-01-AC2 | {场景描述} | US-01 | ❌ | ✅ | ⚠️ 缺设计 |
+
+### 1.3 业务规则
+
+| 需求 ID | 规则简述 | 设计覆盖 | 用例覆盖 | 状态 |
+|---------|---------|:---:|:---:|:---:|
+| BR-01 | {规则标题} | {Service 方法 / DO 索引} | {用例编号} | {✅/❌} |
+| BR-02 | {规则标题} | ❌ | ❌ | ❌ 缺失 |
+
+### 1.4 功能条目
+
+| 需求 ID | 功能简述 | 设计覆盖 | 用例覆盖 | 状态 |
+|---------|---------|:---:|:---:|:---:|
+| FUNC-01 | {功能简述} | {Controller + Service} | {用例编号} | {✅/❌} |
+| FUNC-02 | {功能简述} | ❌ | ❌ | ❌ 缺失 |
+
+### 1.5 权限项
+
+| 需求 ID | 权限标识 | 涉及角色 | 设计覆盖 | 用例覆盖 | 状态 |
+|---------|---------|---------|:---:|:---:|:---:|
+| PERM-01 | {module}:{resource}:create | 管理员/工艺员 | ✅ | ✅ | ✅ |
+| PERM-02 | {module}:{resource}:query | 全部角色 | ✅ | ❌ | ⚠️ 缺用例 |
+
+---
+
+## 表2 — 设计→需求（验证设计有据）
+
+> 验"设计有没有来源"：每个设计要素是否都能追溯到需求？
+
+| 设计要素 | 类型 | 实现的需求 ID |
+|---------|------|-------------|
+| {ClassName}.create() | Controller 方法 | US-01-AC1, FUNC-01, BR-01 |
+| {ClassName}.validateUnique() | Service 私有方法 | BR-01 |
+| {TableName} 表 | 数据表 | BR-01, BR-03 |
+| CODE_RULE_DUPLICATE | 错误码 | US-01-AC2, BR-01 |
+| POST /admin-api/{module}/{domain}/create | API 接口 | FUNC-01, US-01-AC1 |
+
+---
+
+## 表3 — 用例→需求（反向追溯）
+
+> 验"测的是对的"：每个测试用例覆盖了哪些需求？
+
+| 用例编号 | 用例描述 | 覆盖的需求 ID | 覆盖状态 |
+|---------|---------|-------------|:---:|
+| UT-{模块}-001 | {用例描述} | US-01-AC1, BR-01 | ✅ |
+| UT-{模块}-002 | {用例描述} | US-01-AC2 | ⚠️ 设计缺失 |
+| API-{模块}-001 | {用例描述} | FUNC-01, PERM-02 | ✅ |
+
+---
+
+## 覆盖率汇总
+
+| 需求类别 | 总数 | 设计已覆盖 | 用例已覆盖 | 全闭环 | 闭环率 |
+|----------|------|:---:|:---:|:---:|:---:|
+| 用户故事 | {n} | {n1} | {n2} | {n3} | {n3/n}% |
+| 验收场景 | {n} | {n1} | {n2} | {n3} | {n3/n}% |
+| 业务规则 | {n} | {n1} | {n2} | {n3} | {n3/n}% |
+| 功能条目 | {n} | {n1} | {n2} | {n3} | {n3/n}% |
+| 权限项 | {n} | {n1} | {n2} | {n3} | {n3/n}% |
+| **合计** | **{total}** | **{t1}** | **{t2}** | **{t3}** | **{t3/total}%** |
+
+> **全闭环** = 设计覆盖 ✅ 且 用例覆盖 ✅ 且 用例全部 PASS ✅。
+> 本表统计的是"设计+用例"覆盖率。测试执行结果（PASS/FAIL）在测试报告中体现。
+
+---
+
+## 状态图例
+
+| 符号 | 含义 |
+|------|------|
+| ✅ | 已覆盖 |
+| ❌ | 缺失（需要补充） |
+| ⚠️ | 部分覆盖（有设计缺用例 / 有用例缺设计） |
+```
+
+---
+
+## 扫描规则（AI 生成指南）
+
+### 步骤 1：解析 ID 清单基准
+
+从需求分析文档中逐节提取：
+
+```
+匹配模式: | {ID} | {来源位置} | {简述} |
+来源: "## 0. 需求 ID 映射" 章节下的  0.1~0.5 五个子表
+输出: ID 清单数组 [{id, category, description}]
+```
+
+### 步骤 2：解析设计→需求映射
+
+从系统设计文档中提取：
+
+```
+匹配模式: **实现需求**: {逗号分隔的 ID 列表}
+上下文: 该标签所在位置的前一个标题或类名作为"设计要素"
+输出: [{designElement, type, requirementIds[]}]
+```
+
+### 步骤 3：解析用例→需求映射
+
+从所有测试用例文件中提取：
+
+```
+匹配模式: **覆盖需求**: {逗号分隔的 ID 列表}
+上下文: 该标签所在行前面的 "**用例编号**: {编号}" 作为用例标识
+输出: [{testCaseId, description, requirementIds[]}]
+```
+
+### 步骤 4：聚合生成矩阵
+
+```
+输入: ID 清单 + 设计映射 + 用例映射
+1. 对每个 ID，查找是否出现在设计映射中 → 填充"设计覆盖"列
+2. 对每个 ID，查找是否出现在用例映射中 → 填充"用例覆盖"列
+3. 对每个 ID，判定状态：两者都有 = ✅ / 两者都无 = ❌ / 部分 = ⚠️
+4. 聚合表2（设计→需求）：按设计要素分组，列出其所有引用 ID
+5. 聚合表3（用例→需求）：按用例分组，列出其所有引用 ID
+6. 聚合覆盖率汇总：按需求类别分别统计
+```
+
+### 步骤 5：异常检测
+
+在生成过程中发现以下异常时，在矩阵末尾增加"异常报告"章节：
+
+| 异常类型 | 检测方式 | 示例 |
+|---------|---------|------|
+| 孤立 ID | 某 ID 出现在 ID 清单中，但既无设计也无用例覆盖 | "US-05（导入订单信息）缺失" |
+| 悬空引用 | 用例中引用了不在 ID 清单中的 ID | "UT-XYZ-099 引用了不存在的 BR-99" |
+| 设计冗余 | 设计要素引用了非功能性需求 ID（不应出现在设计层面） | 忽略（仅做信息提示） |
+```
+
+---
+
+## 验收评审使用指南
+
+### 评审前条件
+
+- [ ] 需求分析文档已完成，包含"需求 ID 映射表"
+- [ ] 系统设计文档已完成，所有 `**实现需求**:` 标签已标注
+- [ ] 测试用例清单已完成，所有 `**覆盖需求**:` 标签已标注
+- [ ] 追溯矩阵已由 AI 自动生成
+
+### 验收通过标准
+
+1. **闭环率要求**：
+   - P0 级别需求（US-01 ~ US-05 级别用户故事）全闭环率 = 100%
+   - 全部需求全闭环率 ≥ 90%
+2. **无孤立 ID**：ID 清单中的所有 ID 至少有一个设计要素和至少一个测试用例覆盖
+3. **无悬空引用**：所有测试用例引用的 ID 均能在 ID 清单中找到
+4. **测试全部 PASS**：覆盖率汇总中标记为全闭环的用例在测试报告中全部 PASS
+
+### 评审不通过的处理
+
+- 闭环率不达标 → 补充缺失的设计或测试用例
+- 存在孤立 ID → 为缺失的需求补充设计和用例
+- 存在悬空引用 → 修正用例的 `**覆盖需求**:` 标签
+
+---
+
+**文档结束**
+
+*本模板作为项目需求追溯矩阵的标准格式。*

package/.adspecs/templates/15-/344/270/232/345/212/241/345/212/237/350/203/275/346/236/266/346/236/204/346/226/207/346/241/243/346/250/241/346/235/277.md

@@ -0,0 +1,168 @@
+# {项目名称} — 业务功能架构
+
+> 版本：v{版本号} | 日期：{日期} | 基于《{源文档名称}》v{源版本} 编写
+
+### 修订记录
+
+| 版本号 | 修订日期 | 修订人   | 修订内容                                                                                       |
+| ------ | -------- | -------- | ---------------------------------------------------------------------------------------------- |
+| v1.0   | {日期}   | {修订人} | 初始版本：基于《{源文档名称}》编写业务功能架构文档架构，定义 {模块范围} 共 {模块数量} 个主模块 |
+
+---
+
+## 一、文档说明
+
+本文档基于《{功能规划文档}》中定义的功能模块清单，结合{行业名称}行业销售业务特点，对{项目简称}平台进行模块化拆分，并将每个业务场景的操作步骤对应到具体的子模块。
+
+**架构设计原则：**
+- **Module-First**：每个模块是独立的业务边界上下文，内部高内聚、模块间松耦合，适合 AI 编程 Agents 集群并行开发
+- **Clean Architecture**：业务逻辑与技术实现分离，通过 {平台底座模块} 提供统一基础设施
+- **AI-Native**：{AI模块编号} AI Agent 模块采用分层架构，支持各场景的智能化能力
+- **可扩展性**：编码规则配置、流程配置支持业务规则的快速扩展
+<!-- 可选：根据项目需要添加分层架构说明 -->
+<!-- - **L1/L2 分层**：内部采用 L1（法律文件层）+ L2（内部执行层）两层架构 -->
+
+**核心对象层级关系：**
+
+<!-- 按项目实际情况填写核心业务对象层级 -->
+
+| 层级              | 核心对象   | 英文     | 职责       |
+| ----------------- | ---------- | -------- | ---------- |
+| **L1 {层级名称}** | {对象名称} | {英文名} | {职责描述} |
+| L1                | {对象名称} | {英文名} | {职责描述} |
+| **L2 {层级名称}** | {对象名称} | {英文名} | {职责描述} |
+
+**关键数量关系：**
+- {对象A} → {对象B} = 1:N
+- {对象B} → {对象C} = **1:1**
+<!-- 按项目实际业务关系填写 -->
+
+**模块编号规则：**
+- 主模块编号：P00~P{最大编号}（M00 对应系统管理/平台底座，P01~P{N} 为业务模块）
+- 子模块编号：{主模块}-01, {主模块}-02, ...（按二级编号命名）
+- 业务场景编号：S-{主模块}-{子模块}-{序号}（S=场景，如 S-M03-01-001）
+- 端到端场景编号：E2E-{项目简称}-01, E2E-{项目简称}-02, ...
+
+**模块分层说明：**
+- **{层级1名称}（P{起始}~P{结束}）**：{层级描述}
+- **{层级2名称}（P{起始}~P{结束}）**：{层级描述}
+- **{层级3名称}（P{起始}~P{结束}）**：{层级描述}
+- **平台支撑层（M00）**：系统管理、权限、流程、集成等横切关注点
+<!-- 按项目实际分层填写 -->
+
+**适用范围：** {适用组织/公司/业务范围}
+
+---
+
+## 二、系统模块总览
+
+### 2.1 模块清单
+
+| 模块编号 | 模块名称   | 子模块数 | 核心职责       | 优先级    |
+| -------- | ---------- | -------- | -------------- | --------- |
+| P00      | 系统管理   | {数量}   | {核心职责描述} | P0        |
+| P01      | {模块名称} | {数量}   | {核心职责描述} | P{优先级} |
+| P02      | {模块名称} | {数量}   | {核心职责描述} | P{优先级} |
+<!-- 按项目实际模块填写 -->
+
+### 2.2 子模块清单
+
+#### P00 系统管理
+
+| 子模块编号 | 子模块名称     | 说明                                    | {外部项目}范围 | {阶段}范围 | 分期规划       |
+| ---------- | -------------- | --------------------------------------- | -------------- | ---------- | -------------- |
+| SYS-01     | 组织架构管理   | 多层级组织树管理与配置                  | —              | —          | {平台}基础模块 |
+| SYS-02     | 角色与权限管理 | RBAC 角色定义、数据范围权限             | —              | —          | {平台}基础模块 |
+| SYS-03     | 字段配置       | 字段自定义、枚举值管理、必填/可见性配置 | —              | —          | {平台}基础模块 |
+| SYS-04     | 流程配置       | 可配置审批工作流引擎                    | —              | —          | {平台}基础模块 |
+| SYS-05     | 编码规则配置   | 各业务对象编码规则自定义                | —              | —          | {平台}基础模块 |
+| SYS-06     | 数据字典       | 统一枚举值与系统参数管理                | —              | —          | {平台}基础模块 |
+| SYS-07     | 日志与审计     | 操作日志、数据变更追溯                  | —              | —          | {平台}基础模块 |
+| SYS-08     | 集成接口管理   | API 网关配置、接口文档、调用监控        | —              | —          | {平台}基础模块 |
+| SYS-09     | 消息与通知配置 | 消息模板、通知渠道、触达规则            | —              | —          | {平台}基础模块 |
+<!-- 按项目实际情况增减 -->
+
+> **说明：** P00 系统管理模块依赖{平台名称}技术底座，基础设施已覆盖此模块核心能力，不再单独做设计。
+
+#### P{XX} {模块名称}
+
+| 子模块编号 | 子模块名称   | 说明   | {外部项目}范围 | {阶段}范围 | 分期规划      |
+| ---------- | ------------ | ------ | -------------- | ---------- | ------------- |
+| P{XX}-01   | {子模块名称} | {说明} | {是/—}         | {是/—}     | {一期/未排期} |
+| P{XX}-02   | {子模块名称} | {说明} | {是/—}         | {是/—}     | {一期/未排期} |
+<!-- 为每个主模块复制此表格结构 -->
+
+> **说明：** {模块补充说明}
+
+---
+
+## 三、各模块业务场景详述
+
+### P{XX} {模块名称}
+
+> {模块定位说明}
+
+#### S-P{XX}-{YY}: {场景名称}
+
+**场景概述：** {场景的业务描述}
+
+| 步骤 | 操作描述       | 所属子模块   |
+| ---- | -------------- | ------------ |
+| 1    | {操作步骤描述} | {子模块编号} |
+| 2    | {操作步骤描述} | {子模块编号} |
+| 3    | {操作步骤描述} | {子模块编号} |
+<!-- 按场景实际步骤填写 -->
+
+<!-- 为每个场景复制此结构 -->
+
+---
+
+## 四、端到端业务场景
+
+### E2E-{项目简称}-01: {端到端场景名称}
+
+**场景描述：** {端到端流程的完整描述}
+
+| 阶段       | 步骤 | 操作描述   | 涉及子模块   |
+| ---------- | ---- | ---------- | ------------ |
+| {阶段名称} | 1    | {操作描述} | {子模块编号} |
+| {阶段名称} | 2    | {操作描述} | {子模块编号} |
+| {阶段名称} | 3    | {操作描述} | {子模块编号} |
+<!-- 按端到端流程填写 -->
+
+### E2E-{项目简称}-02: {端到端场景名称}
+
+<!-- 复制上述结构 -->
+
+---
+
+## 五、系统集成关系
+
+### 5.1 {项目简称}与外部系统集成矩阵
+
+| 外部系统   | 集成方向         | 集成内容       | 相关模块   |
+| ---------- | ---------------- | -------------- | ---------- |
+| {系统名称} | {双向/入站/出站} | {集成内容描述} | {模块编号} |
+| {系统名称} | {双向/入站/出站} | {集成内容描述} | {模块编号} |
+<!-- 按项目实际外部系统填写 -->
+
+### 5.2 {项目简称}内部模块依赖关系
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                   {层级名称}                              │
+│  P00 系统管理 ──→ 所有模块（横切基础设施）                  │
+│  P{XX} {模块} ──→ P{YY} {模块}、P{ZZ} {模块}            │
+│  P{XX} {模块} ──→ P{YY} {模块}                          │
+├─────────────────────────────────────────────────────────┤
+│                    {层级名称}                             │
+│  P{XX} {模块} ──→ P{YY} {模块}                          │
+├─────────────────────────────────────────────────────────┤
+│                    {层级名称}                             │
+│  P{XX} {模块} ──→ 所有业务模块（数据消费方）               │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+**文档结束**