req-analyze: 前端需求落点与影响范围分析

职责:把用户的一段需求 / PRD / 设计描述转成可执行的前端影响分析,回答:

• 这是改页面、加功能、加组件、改公共组件、改接口/状态/路由中的哪一类?
• 预计要改哪些文件?哪些是主改文件,哪些是联动文件?
• 被改文件引用了哪些组件 / composable / store / API?改动会不会影响它们?
• 关联页面、关联功能、公共能力是否有回归风险?
• 建议怎么拆步骤,先改哪里,最后验证什么?

核心纪律:只读分析,不擅自改代码。 用户说「按这个分析去改」「开始实现」后,才进入实现类工作流。

与 codebase-parse 的分工:用户要读懂整个项目(技术栈、全量页面索引、接口总表、动效清单)走 codebase-parse;用户已给具体需求要评估改哪些文件,走本 skill。陌生仓库可先 /codebase-parse 再 /req-analyze。

启动:先拿到需求

1. 用户已给需求文本 / 链接 / 截图 / 设计稿

直接进入分析,不要让用户重复描述。

• 需求文本:抽取业务目标、用户动作、入口、页面状态、字段、权限、接口、埋点 / 跳转 / 异常态。
• 本地截图路径:用 Read 查看图片,提取页面区域、交互入口、视觉变化。
• Lanhu PRD / 原型链接:先按 Lanhu PRD 工具流程读取页面列表和文本概要;如果需要深入,问用户选择 developer / tester / explorer 视角后再取 full。
• Lanhu UI 设计链接:先取设计图列表,再分析用户指定设计图;视觉参数以返回的 HTML+CSS 为准。

2. 用户只说「分析一下这个需求」但没给内容

只问一次,让用户补充以下任一项:

不要同时问一串细节;先拿到需求主体再读项目。

项目探测顺序

进入项目后,先读结构,再下结论。能并行读的并行读。

1. 技术栈与目录

优先检查:

• package.json:框架、路由、状态库、UI 库、请求库、测试框架。
• nuxt.config.* / vite.config.* / vue.config.*:别名、自动导入、全局组件、模块。
• tsconfig.json:路径别名。
• 根目录与 src/ / app/ / pages/ / components/ / stores/ / composables/ / api/ / services/ / router/ / layouts/ / middleware/ / types/。
• 小程序 / uni-app 项目额外读 pages.json、manifest.json、src/pages、src/components、src/api、src/store。

2. 需求关键词定位

从需求中抽取 3 类关键词做搜索:

搜索不到时,扩大同义词:中文文案、英文变量名、路由片段、接口路径、枚举值。

3. 建调用关系图

对候选主文件逐个读完整内容,再追踪:

• template 中使用的组件:本地 import、自动导入组件、全局 UI 组件。
• script 中使用的 composable / store / API / util / type。
• 路由和入口:页面文件、layout、middleware、tabBar、菜单配置、路由守卫。
• 数据来源:请求封装、接口模块、mock、Pinia/Vuex、props、query/params。
• 对外影响:emit 事件、slot、props、provide/inject、store mutation/action、全局事件。

只读必要文件。候选文件很多时,先列 Top 10 证据最强的文件,再深入。

需求类型判定

一个需求可以同时命中多类,输出主类型 + 次类型。

判断规则:

• 只改已有页面局部展示,无新数据/状态/路由 → 主类型「改页面」。
• 新增用户可完成的一段业务动作,尤其涉及提交/保存/校验/结果页 → 主类型「加功能」。
• 需求描述的是一个可复用模块,或两个以上页面都要用 → 主类型「加组件」。
• 命中公共组件或 store/API 的签名变化 → 必须标记「影响面扩大」。

文件影响分析方法

1. 输出文件分层

每个文件必须归类为:

• 主改文件:需求直接落点,不改无法完成需求。
• 联动文件:类型、接口、store、路由、样式、测试、配置等配套改动。
• 需核对文件:可能受影响但是否改动取决于实现选择。
• 回归关注文件:通常不改,但必须验证相关功能不坏。

2. 影响级别

3. 证据要求

不要写「可能在某某文件」。每条文件建议至少带一个证据:

• 路由证据:pages/order/detail.vue 对应 /order/detail。
• 文案证据:文件内已有「提交订单」按钮。
• 依赖证据:OrderDetail.vue import 了 useOrderStore。
• 引用证据:BaseDialog 被 8 个文件引用。
• 接口证据:getOrderDetail 在该页面调用。

证据不足时,明确标 待确认,并说明要确认什么。

关联组件与关联功能检查

1. 组件影响

对每个主改组件 / 公共组件,必须检查:

• 它被哪些页面 / 组件引用。
• props 是否会新增、删除、改类型、改默认值。
• emits / slot / expose 是否会改变。
• 样式是否 scoped;是否会影响全局 class 或 UI 库主题。
• 是否存在同名自动导入组件导致引用不显式。

输出结论:

• 无外溢:仅页面内私有组件,引用方 1 个。
• 有限外溢:2-3 个明确引用方,可逐个回归。
• 公共外溢:公共组件 / 自动导入 / 全局样式,需要全量引用方回归。

2. 功能影响

至少检查以下关联面:

• 路由跳转:入口、返回、未登录跳转、query/params 是否兼容。
• 数据链路:接口参数、响应字段、缓存、分页、空态、错误态。
• 状态链路:登录态、会员态、购物车、筛选条件、全局设置。
• 权限链路:游客/登录用户/会员/管理员等差异。
• 表单链路:校验、提交、防重复提交、编辑回填。
• 视觉链路:响应式 375 / 768 / 1280,暗色模式,主题 token。
• 性能链路:是否引入重组件、首屏请求瀑布、长列表。

输出格式

固定输出,方便用户直接进入实现。

## 需求分析结论

**需求摘要**:一句话复述目标
**主类型**:改页面 / 加功能 / 加组件 / 改公共组件 / 改接口 / 改状态 / 改路由
**影响级别**:高 / 中 / 低
**信心**:高 / 中 / 低(低信心必须写缺什么信息)

## 1. 判断依据
- `path/to/file.vue:42` 已有 xxx 入口,需求是在此基础上新增/调整
- `path/to/api.ts:18` 当前接口返回 xxx,需求需要 yyy

## 2. 建议改动文件
| 层级 | 文件 | 是否改 | 原因 | 风险 |
|------|------|--------|------|------|
| 主改 | `pages/order/detail.vue` | 必改 | 需求主页面 | 中 |
| 联动 | `api/order.ts` | 可能 | 新增字段/接口参数 | 中 |
| 回归 | `pages/order/list.vue` | 不改但测 | 共用订单 store | 中 |

## 3. 关联组件影响
| 组件 | 引用方 | 影响判断 | 处理建议 |
|------|--------|----------|----------|
| `components/BaseDialog.vue` | 8 处 | 公共外溢 | 不改签名;如必须改,逐个回归 |

## 4. 关联功能风险
- 高/中/低 `功能名`:风险说明 → 验证方式

## 5. 推荐实施顺序
1. 先改类型/API/composable 边界
2. 再改页面或组件 UI
3. 最后补状态、空态、错误态和回归验证

## 6. 验证清单
- [ ] 375 / 768 / 1280 页面布局
- [ ] 登录 / 未登录 / 权限不足
- [ ] loading / empty / error / success
- [ ] 关联入口与返回路径
- [ ] 共用组件引用方回归

没有发现影响时也要明确写「未发现」,不要省略章节。

不确定性处理

• 需求缺接口字段:标为「待后端确认」,不要编字段。
• 找不到目标页面:列出最接近的候选页面和匹配理由,让用户选。
• 可能有多种实现路径:给 2 个以内方案,推荐一个,说明取舍。
• 文件数过多:先输出影响地图,不要一次读爆全项目。
• 分析中发现需求本身矛盾:先指出矛盾,再给可落地解释。

禁止

• 禁止在分析阶段编辑文件。
• 禁止只根据需求文案脑补文件清单,必须读项目证据。
• 禁止把所有文件都列为「可能要改」来逃避判断。
• 禁止输出泛泛的「注意兼容性」「注意测试」,必须落到具体功能和验证动作。
• 禁止为了完整性引入用户没提的新功能。
• 禁止在报告 / 中文回复中使用斜体(*文字* / _文字_);需要强调统一用粗体,引用文件 / 行号 / 字段名 / 命令用反引号。