需求到交付（Requirement → Delivery）端到端流程指南
先说一个核心判断：把一份需求文档变成可上线的代码，中间至少隔着七道关键工序。这个过程，就是将任意形式的需求文档——飞书链接、Markdown文件、PRD，甚至用户直接粘贴的一段描述——一步步转化为可上线的代码，并附带自动化测试。整体走7个阶段，严格按顺序来，每个阶段都得用户确认，绝对不能跳步。
全流程总览如下：
Phase 1 需求文档落盘 ↓
Phase 2 互动澄清（AskQuestion写回文档） ↓
Phase 3 设计参照确认（参照模块 / Figma链接 / 自行创作） ↓
Phase 4 接口与字段定义（已给 / 预设占位） ↓
Phase 5 测试策略确认（框架 / 类型 / 位置） ↓
Phase 6 代码实现（强制分批 + 用户确认） ↓
Phase 7 自动化测试（e2e / 单元，按Phase 5选定的框架）
一旦启动，立刻用TodoWrite把上述7个阶段建好待办，全程同步进度。
Phase 1：获取需求文档并落盘
触发条件很直接：用户甩过来任意形式的需求文档，包括但不限于：
- 飞书/Lark链接，比如
feishu.cn或larksuite.com这些公共域名，或者企业文档平台给的官方链接 - 项目里已有的Markdown或PRD文件路径
- 用户在对话中直接粘贴的需求描述文字
- Figma设计稿链接，如果里面带了需求说明
- 其他网页链接、PDF、图片等
具体实施步骤：
- 先通过AskQuestion问一句：文档放在哪个docs目录？给出几个常见选项，比如
src/views/<模块>/docs/、docs/，或者让用户自定义。 - 根据需求来源分支获取原文：
- 飞书/Lark链接 → 用当前环境已配置的Lark/飞书MCP或官方导出能力读取全文。
- 项目内Markdown/PRD文件 → 直接用Read工具读取。
- 用户直接粘贴的文字 → 直接用对话内容。
- Figma链接 → 用Figma MCP的
get_design_context获取，这个同时可作为Phase 3的设计稿来源。 - 其他网页链接 → 用WebFetch抓取。
- 在指定目录下新建Markdown文件，文件名建议用
<需求英文短名>-requirement.md这样的格式。 - 按下列骨架填充内容，关键章节先占位，后续Phase再填：
# {需求名称}
> 需求来源：{原始链接 / 文件路径 / "用户对话直接提供"}
> 同步时间：{YYYY-MM-DD}
## 一、需求概览（3-5句话）
…
## 二、原文摘录（关键内容，非全文复制）
…
## 三、待确认问题
- [ ] 问题1
- [ ] 问题2
## 四、参照模块 / 设计稿
（Phase 3填充）
## 五、接口与字段定义
（Phase 4填充）
## 六、测试策略
（Phase 5填充：测试框架、测试类型、文件位置、测试场景）
## 七、实现拆解
（Phase 6填充）
完成后展示文档路径给用户，再进入Phase 2。注意：不要在此阶段输出大段需求总结给用户看，所有内容写进文档就行。
Phase 2：互动澄清（AskQuestion驱动，结果回写文档）
这里有个核心机制：所有需要用户回答的选择题或不明确点，必须用AskQuestion工具，禁止用普通对话列1/2/3让用户回复。
执行步骤：
- 扫描文档，把所有的歧义点、模糊的地方、遗漏的边界场景全挖出来，写入「三、待确认问题」。
- 通过AskQuestion分批询问，每批不超过5个。优先级这样排：
- 阻塞实现的核心规则，比如唯一性、必填、互斥这些。
- 交互细节，比如弹窗还是抽屉、要不要二次确认、Loading怎么处理。
- 数据校验，比如长度限制、正则表达式、重复检测。
- 权限粒度，不同角色能看到什么、能操作什么。
- 边界场景，比如空数据、极端数据、网络异常、并发情况。
- 收到回答后立即把答案合并到文档对应章节，别等到全部问完再回写。
- 把已解决的
- [ ]勾掉，继续下一批，直到没有歧义为止。
Phase 3：设计参照确认
通过AskQuestion问一个三选一的分支问题：
分支A：参照现有模块
- 追问参照哪个模块，用AskQuestion给出项目内典型模块作为选项。如果没明显候选，就让用户输入路径。
- 在文档「四、参照模块 / 设计稿」记录：参照模块名加文件路径，还有维度对齐对比表，包括路由、菜单、权限、API、列表页、编辑页、状态枚举这些。
分支B：有Figma链接
- 阻塞等待用户提供Figma链接，比如
figma.com/design/...这种。 - 拿到链接后写入「四、参照模块 / 设计稿」。
- 到了Phase 6代码实现时，必须用Figma MCP的
get_design_context（fileKey + nodeId从该链接解析）获取设计上下文，再开始写代码。
分支C：自行创作（必须遵循系统风格）
这里有个铁律：自由度高不等于可以随意发挥。必须先扫描并对齐项目已有风格，再开始设计。
C.1 扫描项目设计系统（强制前置）
进入Phase 6之前必须完成以下扫描，把结论写进文档「四、参照模块 / 设计稿」：
| 扫描维度 | 找什么 | 怎么找 |
|---|---|---|
| 设计Token | CSS变量、颜色/字号/间距/圆角/阴影 | 全局样式 / :root / 设计Token文件，以项目为准 |
| 通用组件 | 弹窗 / 下拉 / 表格 / 表单 / Popover | 组件库目录或业务封装组件目录 |
| 图标体系 | 项目统一图标用法 | src/assets/、src/icons/等，以项目为准 |
| 布局范式 | 列表页骨架、表单页骨架、抽屉骨架 | 同业务域内现有页面 |
| 交互范式 | 危险二次确认、Loading、空状态、分页样式 | 现有同类页面 |
| 文案风格 | 按钮文字 / 表头 / 提示语调，比如"确认/取消/删除" | 现有页面 |
C.2 找一个"风格最近邻"作为隐式参照
即使没有官方参照模块，也要从项目里挑一个业务最相近的页面作为视觉和交互范本。在文档中记录：
## 四、参照模块 / 设计稿（自行创作 — 隐式参照）
- **隐式参照模块**：`src/views/xxx/YyyList.vue`（理由：与本需求交互模式最接近）
- **沿用的设计Token**：颜色 / 间距等，列出实际使用的CSS变量名
- **沿用的通用组件**：列出项目内封装组件名
- **自创部分**：仅XXX区块，说明为何不能复用现有范式
C.3 提交设计草案让用户预审
在动手写代码前，先用结构化文字描述设计方案，不要直接写代码。通过AskQuestion让用户确认：
- 页面骨架，比如顶部筛选加表格加分页、左导航加右内容、卡片网格等。
- 关键交互流，比如创建走抽屉还是弹窗？删除是否二次确认？
- 状态展示，比如Tag颜色映射、空状态文案。
- 风险点，任何无法直接套用现有范式的地方。
用户确认后才进入Phase 4或Phase 6。
C.4 创作禁区（绝不要做）
- 引入项目里没有的颜色，应该先在全局Token或主题中扩展，再在业务中使用。
- 绕过既有设计系统自造一整套基础控件，应该优先复用项目封装。
- 与项目图标规范冲突的用法，以项目规则为准。
- 行内
style=写样式，除非项目规则明确允许动态样式。 - 复制网上抄来的UI风格混搭进项目。
Phase 4：接口与字段定义
通过AskQuestion：
分支A：已有接口文档
解析接口文档，在「五、接口与字段定义」按下表整理：
| 接口 | 方法 | URL | 入参字段 | 出参字段（含类型/含义） |
|---|
后续代码直接按此表对接，不再自行编字段。
分支B：接口暂无 — 生成占位定义区
这里是个关键机制：生成一个显眼的占位区，让后续接口给出后可整体替换：
## 五、接口与字段定义（⚠️ 待接口文档确认）
### 实体：Xxx（前端预设）
| 字段名（预设） | 类型 | 含义 | 备注 |
| -------------- | ------ | -------- | ------ |
| id | string | 主键 | 待确认 |
| name | string | 名称 | 待确认 |
| status | number | 状态枚举 | 待确认 |
| createTime | string | 创建时间 | 待确认 |
| …||||
### 接口（前端预设）
- 列表：`POST /xxx/list` — 入参：`{ page, size, keyword }` — 出参：`{ list: Xxx[], total }`
- 创建：`POST /xxx/create` — 入参：`{ name, … }` — 出参：`{ id }`
- 编辑：`POST /xxx/edit` — 入参：`{ id, name, … }`
- 删除：`POST /xxx/delete` — 入参：`{ id }`
> ⚠️ 上述字段名与接口路径均为前端预设，等接口文档给出后**全文替换**。
> 代码中所有mock接口与字段引用，都应能通过搜索字段名/路径一次性替换。
代码实现阶段，所有字段引用都走这套预设，方便后期一次性替换。
Phase 5：测试策略确认（框架 / 类型 / 位置）
核心原则：测试方案等于项目现有配置加上用户偏好，不预设任何框架。
5.1 探测项目现有测试栈
先用Glob或Read探测项目里已经存在的测试基础设施：
| 探测目标 | 典型证据 |
|---|---|
| Cypress | cypress.config.{js,ts} / cypress/目录 / package.json含cypress依赖 |
| Playwright | playwright.config.{js,ts} / e2e/或tests/目录 / @playwright/test |
| Vitest | vitest.config.{js,ts} / vitest在devDependencies |
| Jest | jest.config.{js,ts} / __tests__/ / *.test.js |
| Vue Test Utils | @vue/test-utils在devDependencies |
| 其他 | Mocha、Karma、Testing Library等 |
把探测结果作为AskQuestion的默认推荐选项。
5.2 通过AskQuestion让用户确认3件事
问题1：测试类型？（允许多选）
- A. 端到端测试（e2e，覆盖完整用户路径）
- B. 集成/组件测试（挂载组件验证交互）
- C. 单元测试（纯函数 / utils / store / composable）
- D. 不写自动化（明确跳过Phase 7）
问题2：使用什么测试框架？按5.1探测结果列出项目已有的框架作为优先选项。如果项目里都没有，再让用户选择新引入哪个。
问题3：测试文件放在哪里？按选定框架的项目约定给出候选路径，比如：
- e2e：
cypress/e2e/xxx.cy.js/tests/e2e/xxx.spec.ts/e2e/xxx.spec.ts - 单元：
src/**/__tests__/xxx.spec.ts/tests/unit/xxx.spec.js
5.3 写入需求文档
把上述3个回答写入文档「六、测试策略」章节：
## 六、测试策略
- **测试类型**：e2e / 单元 / 两者都有
- **测试框架**：Cypress 14 / Vitest 1.x / …
- **文件位置**：cypress/e2e/xxx.cy.js（e2e），src/views/xxx/__tests__/（单元）
- **测试场景**（用户提供或后续补充）：
- 场景1：…
- 场景2：…
重点：本阶段只确认策略，把信息写入文档，不立即写测试代码。测试代码统一在Phase 7完成。
Phase 6：代码实现（强制分批，绝不一次性完成）
铁律：永远不要一次把所有代码改完。必须分批加上checkpoint，每一批让用户确认后再继续。
6.1 拆解任务并建TodoWrite
按以下粒度拆todo，粒度尽量小：
- 单个文件、单个组件、单个API模块为一批。
- 多文件改动按「常量定义 → API层 → 单组件 → 子组件 → 集成 → 路由/菜单接入」的顺序拆。
- 把拆解结果写入需求文档「七、实现拆解」章节。
6.2 Figma分支预处理
如果Phase 3选了B（要Figma）：进入6.3前，先调Figma MCP的get_design_context，fileKey和nodeId从需求文档中记录的链接解析。把设计稿与项目内已有设计系统或业务组件做映射，然后再按6.3分批实现。
6.3 执行策略（每个todo一个循环）
- 把下一个todo标
in_progress。 - 只完成这一个todo涉及的文件改动。
- 改完立即调ReadLints自查lint问题。
- 主动暂停，向用户报告：这一批做了什么、涉及哪些文件、是否有需要用户决策的点，然后明确说“请确认OK后我再继续下一批”。
- 等用户确认后才标
completed并启动下一个todo。
6.4 项目规范自查清单（每批都过）
- Vue/前端框架规范：以当前仓库
.cursor/rules/、CONTRIBUTING或README中针对Vue 2/Vue 3/其他栈的约定为准，实现前对齐版本与风格（Composition API/Options API等）。 - 定义注释规范：若项目规则要求，则为每个
ref/reactive/computed/const/箭头函数/data属性/methods/api function等补充简洁说明，字数与格式以项目规则为准。 - 统一组件与样式：弹窗、表单控件、图标、主题色等一律遵循项目既有封装与设计Token，禁止与全局规范冲突的另起炉灶。
- 危险操作（删除/结束/暂停/冻结等）：按项目要求做二次确认，勿静默执行不可逆操作。
- API错误提示：若全局拦截器已统一提示，业务层避免重复弹同一类错误，以免打扰用户。
- 可测试性属性（Phase 5选了e2e/集成测试时必加）：所有交互元素打上项目约定的稳定测试属性，比如
data-cy/data-test/data-testid，命名使用kebab-case。 - 可测试性结构（Phase 5选了单元测试时）：纯逻辑尽量抽到
utils/或composable，避免深埋于单文件组件内难以单测。
Phase 7：自动化测试（按Phase 5选定的方案落地）
只在所有代码批次完成，且用户最终确认通过后启动。如果Phase 5选了D（不写自动化），直接跳过本阶段并告知用户。
7.1 通用步骤（不分框架）
- 把Phase 5收集的测试场景中可自动化的部分识别出来。
- 不可自动化的，比如纯视觉对比、跨域第三方页面、真实支付、等待真实异步几分钟这些，明确告知用户跳过并说明原因。
- 在Phase 5指定的测试文件路径下写测试用例。
- 测试代码同样分批写：一个测试文件或一个describe一次，写完跑通后再写下一个。
7.2 按框架适配
按Phase 5选定的框架自动套用对应规范：
e2e类（Cypress / Playwright）通用要点：
- 选择器优先用稳定的
data-cy / data-test / data-testid，禁止脆弱的CSS选择器，比如nth-child或长ID链。 - 等待网络请求用拦截加别名，禁止硬编码
wait(数字毫秒)：Cypress用cy.intercept加cy.wait('@alias')，Playwright用page.waitForResponse(/url/)。 - 绕过UI登录：按项目文档或测试基建约定注入会话（localStorage / sessionStorage / cookie等），禁止在仓库中硬编码真实账号密码或长期有效的密钥。
- 用相对路径访问页面，禁止硬编码域名，由配置的baseURL提供。
- 断言用强断言，比如
should('be.visible')或toBeVisible()，而不是仅检查存在。 - 若仓库已有e2e测试规范文档，比如
*.mdc或docs/下的说明，严格遵循。
单元/组件类（Vitest / Jest / Vue Test Utils）通用要点：
- 优先测纯函数和逻辑分支，UI渲染快照不主测。
- 组件测试用
mount或shallowMount，外部依赖（API / store / router）全mock。 - 异步逻辑必须
await flushPromises()或等到状态稳定再断言。 - 命名清晰：
describe('XxxList', () => { it('在加载完成后渲染表格行', ...) })。 - 单测覆盖率不追求100%，覆盖核心业务逻辑加边界条件即可。
7.3 兜底
如果项目从未配置过测试框架，且Phase 5让你“新引入”某框架：先增量安装依赖、加最小配置文件，比如vitest.config.ts或cypress.config.js等。配置和首个测试用例分开两个todo提交，每步暂停等用户确认。最后给出运行命令，比如pnpm test:unit或pnpm cypress open，让用户能本地验证。
跨阶段强约束
| 约束 | 做法 |
|---|---|
| 永远先确认再执行 | Phase之间显式暂停，不要默认继续 |
| AskQuestion优先 | 任何需要用户选择的问题都用AskQuestion，禁止纯文本列选项 |
| 文档单一来源 | 所有澄清结果回写需求文档，不要让信息散落在对话里 |
| TodoWrite全程同步 | 从Phase 1启动到Phase 7完成，TodoWrite状态实时更新 |
| 小步快跑 | 每批改动小到可单独revert，便于用户随时退回 |
| 中文交流 | 与用户的所有沟通、文档内容、注释一律中文，若项目另有语言要求则从其约定 |
反模式（绝不要做）
- 一上来就写代码，连需求来源都没搞清楚。
- 用纯文本让用户“请回答：1. xxx 2. xxx 3. xxx”，应该用AskQuestion。
- Phase 6一次性改完8个文件后说“都做完了，看看吧”，应该分批加checkpoint。
- 接口字段直接编，或者直接调用未确认的接口路径，应该走Phase 4的占位机制。
- 跳过Phase 5，直接在Phase 7才问测试用例放哪里。
- 不看项目现有测试栈，强行引入新框架，应该优先复用项目已有的。
- 在测试代码里硬编码等待时间，比如
cy.wait(5000)或page.waitForTimeout(5000)，或使用nth-child这种脆弱选择器。 - 把澄清问题攒一波只问一次，应该分批，每批不超过5个。
启动Checklist（接到任意形式的需求文档后立刻做）
复制以下checklist作为TodoWrite初始内容：
- [ ] Phase 1：确认docs目录 → 按来源获取原文（飞书/文件/粘贴/Figma/网页）→ 落盘需求文档骨架
- [ ] Phase 2：用AskQuestion分批澄清歧义点 → 回写需求文档
- [ ] Phase 3：确认参照模块 OR Figma链接 OR 自行创作（强制扫描项目风格）→ 写入文档
- [ ] Phase 4：确认接口文档 OR 生成预设字段占位区 → 写入文档
- [ ] Phase 5：探测项目测试栈 → AskQuestion确认测试类型/框架/位置 → 写入文档
- [ ] Phase 6：分批实现代码（每批暂停等用户确认）
- [ ] Phase 7：按Phase 5选定方案写自动化测试（e2e / 单元，分批）
