qa-functional-test

name	qa-functional-test
description	功能测试用例设计与产物输出。由 qalore 调用，不独立触发。 以断言集合为输入，设计覆盖正向/边界/异常/上下游的测试用例，产出 story 和脑图产物。 业务逻辑由 qa-understand 提炼后传入，或已存在于 story 文件中。
practices_min_version	2026-06-15-v18

qa-functional-test：功能测试用例设计与产物输出

前置说明

变量	来源	fallback
{practices_path}	qalore 注入	自动恢复：读 ~/.claude/qalore-config.json 重建 context
{story_path}	qalore 注入	自动恢复：读 ~/.claude/qalore-config.json 重建 context
{确认项目名}	qalore 注入	立即终止，输出「项目名 context 已丢失，请重新执行任务」

---

核心思考哲学：用户影响优先的用例集

拿到断言集合后，先问： 如果这个模块今天在生产中出问题，用户最先感受到什么损失？

以这个答案定义 2-3 个优先测试场景，为这些场景设计多角度用例。 断言集合作为覆盖验证：⚠️ 和 （待代码确认） 断言额外追加高优先用例； 其余断言遵循 cases.md 覆盖规则处理。

多模块任务： 本 capability 负责驱动多模块间的迭代执行，遵循 handbook.md「多模块任务规范」章节。网关完成路由后不介入，由本 capability 自主推进每个模块的流程并控制 .mm 产物输出时机。

输入来源（按优先级）：

• context 中存在 【测试意图已提炼】 交接块 → 以此为主输入（格式见 story-formats.md「统一交接块格式」章节）
• 无交接块，story 中两个文件都存在（业务逻辑.md + 代码逻辑.md）→ 以业务逻辑.md 为主，代码逻辑.md 补充代码独立断言；遇到同一场景的⚠️冲突标注，暂停向用户确认以哪个版本为准后再继续
• 无交接块，story 中只有其中一个文件 → 直接使用该文件
• 两者均无 → 无法继续，告知用户先触发 qa-understand

存量用例处置原则：

• TC 文件不存在 → 全新设计，TC 序号从 001 开始
• TC 文件已存在，有新的断言输入（新需求/新版本/明确要求更新）→ 增量处理：新功能点新增用例（3.1），已有功能点变更时更新用例（3.2），功能点消失时删除用例（3.3）
• TC 文件已存在，同时满足以下全部条件时，进入直接输出模式（跳过设计，读 story 直接产出 .mm）：
  1. 用户当前会话中未提供任何文档、代码或需求描述
  2. qa-understand 未在本会话被触发
  3. 用户意图是「查看或输出当前状态」而非「更新内容」——若有任何迹象显示用户期望内容发生变更（新功能、版本更新、需求调整等），无论措辞如何，不进入直接输出模式 以上任一条件不满足 → 默认走增量处理，不选直接输出模式
• 不确定时默认选增量处理，不选直接输出模式

版本号来源（用于 changelog 和用例头部）：

• 有交接块时：使用交接块中的版本信息（由 qa-understand 提取）
• 无交接块时：读 story/index.json 的 prd_version 字段
• 用户在当前会话中直接提供版本号时：以用户提供的为准
• 无法确定 → 暂停向用户确认，不猜测

断言置信度对用例设计的影响：

• （✓）：正常设计，前置条件可精确到实现细节
• （✓,部分代码确认）：正常设计，在用例备注中标注「部分实现待确认，执行前核实未覆盖仓库」
• （待代码确认）：正常设计，在用例备注中标注「实现待确认，执行前需与开发核实」
• （代码独立）：与其他断言同等对待，按业务重要程度设定优先级，标注「来自代码分析」
• （代码独立,多源）：与其他断言同等对待，可信度高于单源代码独立断言，标注「多仓库代码均发现」
• ⚠️：暂停，将文本-代码冲突列入执行计划，要求用户确认以哪个版本为准后再继续
• ⚠️(代码)：暂停，将多源代码冲突列入执行计划，要求用户确认以哪个仓库逻辑为准后再继续

---

执行约束（不可违反的技术规则）

TC 序号续接约束：

• 执行前必须操作：若 TC 文件已存在，在展示执行计划前先 Read {story_path}/{项目}/{模块}/{模块名}-功能-测试用例.md，取文件中最大 TC 序号 N，新增用例从 N+1 开始
• 不得依赖 context 中记忆的序号，必须从文件读取
• TC 文件不存在时从 001 开始
• 不得跳号，不得复用已有序号

---

practices 文件

按需加载规范遵循 {practices_path}/common/handbook.md「context 标记规范」章节。

本 capability 使用的 practices 文件：

• tech-stacks/functional/cases.md（设计用例时）
• tech-stacks/functional/changelog.md（写入 changelog 时）
• tech-stacks/functional/output.md（生成 .mm 产物时）
• tech-stacks/functional/story-formats.md（读写 story 文件时）

---

执行前确认

遵循 handbook.md「执行前确认规范」章节。本 capability 的计划摘要格式：

【功能测试执行计划】
项目：{确认项目名}
模块：{模块名}
功能点范围：{列出将要覆盖的功能点}
测试维度：正向 / 边界 / 异常 / 上下游
预计用例数：P0 {n} 条 / P1 {n} 条 / P2 {n} 条 / P3 {n} 条
新增 TC ID 范围：TC-{PREFIX}-{起始序号} ～ TC-{PREFIX}-{结束序号}
产物输出：{.mm（{范围}）/ 仅更新 TC 文件}
规范版本：{practices version}

TC 前缀不存在时自动推断（模块名英文意译首字母缩写，2-5个大写字母，与同项目已有前缀不冲突），推断结果纳入执行计划展示，并单独要求用户对推断前缀做出明确确认（是/否），否则不得继续（因前缀注册后不可变，一旦写入无法修改）。

---

产出写入声明

输出【待沉淀】声明，操作类型遵循 handbook.md「用例变更规则」：

【待沉淀】
| 文件 | 路径 | 操作 | 变更摘要 |
|------|------|------|---------|
| {模块名}-功能-测试用例.md | {路径}/ | {3.1新增/3.2更新/3.3删除} | TC-{PREFIX}-{起}-{止}（{n}条），现有 {m} 条 → 变更后 {总数} 条 |
| {模块名}-功能-测试用例.changelog.md | {路径}/ | 只增不删 | {版本} {操作摘要} |
| index.json | {路径}/ | {新建条目/patch} | {变更字段摘要} |

新增/更新用例预览（供用户确认内容正确性）：
{逐行列出本次新增或更新的用例 ID + 标题，格式：TC-{PREFIX}-{seq}：{标题}（{测试维度}·{优先级}·{n}个断言）}

TC 关联标注（有跨模块上下游断言时）： 遵循 cases.md「跨模块 TC 归属规则」，若业务逻辑.md 中存在带 [模块::功能点] 标签的【上下游】断言，TC 写入完成后须回写业务逻辑.md：找到对应的【上下游】断言行，在行末追加 → 见 TC-{PREFIX}-{seq}，建立断言与用例的双向关联。在【待沉淀】声明中追加该行：

| {模块名}-功能-业务逻辑.md | {路径}/ | 3.2更新 | 在 {n} 条【上下游】断言行末追加 → 见 TC 关联标注 |

测试用例文件头部（新建时写入，更新时同步刷新）：

# {模块名} 功能测试用例
> TC 前缀：{PREFIX} | 用例总数：{n} 条 | 最新版本：{v1.2 / 未关联版本} | 最后更新：{YYYY-MM-DD}

外部路径（deliverable_path）处理：用户消息中存在文件系统路径时，该路径为 deliverable_path，.mm 产物同时输出至该路径。story 写入不受影响，仍正常执行。deliverable_path 只接收 .mm 文件，不接收 story 文件。

错误处理：

• 路径不存在 → 告知用户，询问是否创建目录；用户拒绝 → story 正常写入，.mm 仅在对话中输出
• 相对路径 → 告知用户须提供绝对路径，请求重新提供；未提供 → 同上
• 无法访问/权限不足 → 告知错误，story 正常写入，.mm 仅在对话中输出

---

执行后验证（每次 TC 写入后必执行）

TC 文件写入完成后必须执行以下检查，任一项不通过则暂停展示问题清单：

1. 计数验证

检查	方法
tc_count	grep -c "^用例 ID：" {TC文件} 与 index.json 一致
pending_count	BL pending + CL pending 与 index.json 一致
assert_seq	max(BL maxID, CL maxID) 与 index.json 一致
文件头断言数	BL 头声明的断言数与实际一致
文件头用例数	TC 头声明的用例数与实际一致

2. 覆盖验证

• 遍历 BL ## 功能点：{name} 节
• 交叉验证 TC 功能点： 第一级覆盖
• 无覆盖 → 警告用户

3. 格式验证

• 每条 TC 含全部 7 个必填字段（见 cases.md「用例格式」）
• TC ID 无重复、无跳号

4. 语言验证

扫描 TC 步骤和预期，检测以下禁止的工程语言模式：

禁止模式	正则
API 调用	调用\s*(POST|PUT|DELETE|GET)\s+/api/
组件 API	ElMessage\.|authService\.|router\.(push|replace)
CSS 类名	\.agent-|\.chat-|\.preset-|\.empty-|\.editor-
内部变量	showDashedBorder|sidebarCollapseKey|collapsedTimelines|autoScroll

在灰盒注解 （） 中出现时豁免。

5. 断言覆盖验证

检查	方法
断言覆盖率	每条 TC 的每个 → 预期： 至少对应一个 → 断言：
断言格式	每个 → 断言： 符合 {类型}({参数}) 格式
断言类型合法性	类型名在 execution.md 定义的 10 种范围内，不得使用未定义类型