AI 驱动前端需求快速交付与质量保障

适用场景：已经有产品原型 URL、Figma 设计稿、Apifox 接口文档和现有前端代码库，希望借助 AI 快速完成需求，同时保证代码质量、业务正确性和上线稳定性。

核心原则

不要把三个链接直接交给 AI 并要求“一次做完”。正确方法是先把原型、Figma、Apifox 和现有代码库定义为四个事实源，再让 AI 按契约和验收标准完成一条可验证的纵向业务链路。

AI 负责分析、生成、检查和加速；业务冲突、安全边界和最终上线决策仍由人负责。

1. 建立四个事实源

事实源	负责回答	不应该负责
产品原型 URL	用户流程、页面跳转、业务操作和交互顺序	精确颜色、间距和真实接口字段
Figma	布局、视觉、组件、变量、响应式和设计状态	后端业务规则和最终权限
Apifox/OpenAPI	URL、方法、参数、响应、错误码和数据结构	页面布局和交互体验
现有代码库	技术栈、组件库、架构、规范和工程命令	自动决定尚未确认的业务规则

当四者冲突时，AI 必须列出冲突并停止猜测：

• 业务行为冲突由产品确认。
• 视觉与组件冲突由设计确认。
• 接口字段与状态冲突由后端确认。
• 架构与公共能力变更由技术负责人确认。

2. 开工前准备 AI 需求包

不要只提供链接，应一次性准备以下上下文：

需求名称：
业务目标：
目标用户和角色：
成功指标：

原型 URL：
测试账号：
必须覆盖的操作流程：

Figma Frame/Node URL：
目标分辨率：
响应式要求：
设计系统或组件库：

Apifox OpenAPI RAW URL：
测试环境 Base URL：
认证方式：
涉及的接口标签：

代码仓库与目标分支：
技术栈：
允许修改的目录：
禁止修改的模块：
参考页面和已有组件：

本次必须实现：
明确不在本次范围内：
验收标准：
测试、类型检查和构建命令：

Figma 应提供具体 Frame 或 Node 链接，而不是只给文件首页。Figma MCP 可以向 AI 提供组件、变量和布局等结构化设计上下文；已有设计系统时应使用 Code Connect 将设计组件映射到真实代码组件。

Apifox 应提供 OpenAPI 3.0/3.1 的 JSON、YAML 或 RAW URL，并保证接口具有稳定 operationId、请求示例、成功响应、错误响应和字段说明。Apifox 支持导出 OpenAPI，因此没有必要让 AI 根据截图猜接口。

3. 第一阶段只分析，不写代码

AI 第一次工作应该输出以下内容：

1. 页面、弹窗和路由清单。
2. 用户主流程和状态转换。
3. Figma 组件到现有代码组件的映射。
4. 页面操作到 Apifox API 的映射。
5. loading、empty、error、disabled、无权限等状态清单。
6. 权限、分页、取消、重复提交和并发风险。
7. 原型、Figma、接口和代码之间的冲突。
8. 需要产品、设计或后端确认的问题。

推荐使用需求矩阵：

页面/弹窗	用户操作	Figma 节点	API	成功状态	空状态	错误状态	权限	验收方式
用户列表	搜索	frame-list	GET users	展示列表	无结果	重试	user:read	E2E
编辑用户	提交	modal-edit	PUT user	关闭并刷新	—	保留表单	user:write	集成测试

没有确认的问题必须标记为 待确认，不得让 AI 自行补业务规则。

4. API 采用契约优先

推荐数据链路：

Apifox
→ OpenAPI 3.1
→ 生成 TypeScript 类型和 API Client
→ 生成 Mock 与 Fixture
→ 页面开发
→ 契约测试

可以使用：

• openapi-typescript：从 OpenAPI 生成 TypeScript 类型。
• Orval：生成 API Client、查询 hooks 和 mock。
• Apifox Mock：前后端并行开发。
• MSW：在浏览器、组件测试和 Node 测试中拦截网络请求。
• Zod 或 JSON Schema：验证进入系统的运行时数据。

禁止以下做法：

• 根据页面截图猜字段。
• 在前端手写一份与 Apifox 重复的 DTO。
• 使用 any 绕过不一致。
• 只实现 HTTP 200，不处理业务错误码。
• 把 Mock 数据直接写死在页面组件中。

每个请求至少要考虑：

• 认证过期。
• 超时和用户取消。
• 重复提交。
• 分页与筛选。
• 响应乱序。
• 错误码到用户提示的映射。
• 接口的向后兼容。

5. Figma 应映射到设计系统

正确路径：

Figma Node
→ 识别 Design Token
→ 搜索现有组件
→ 确认缺失组件
→ 组装页面
→ 视觉回归

AI 写页面前必须搜索：

• 是否已有 Button、Dialog、Table、Form 和 Tabs。
• 是否已有颜色、间距、圆角和字体 Token。
• 是否有相似业务页面可以复用。
• 项目标准的表单、请求、权限和错误处理方式。

复用优先级：

1. 复用已有业务组件。
2. 复用设计系统组件。
3. 扩展现有组件的 variant。
4. 确实无法复用时才新建组件。

禁止 AI：

• 大量使用 Figma 导出的绝对定位。
• 给每个颜色创建新的十六进制值。
• 为单个页面重新实现 Button 或 Modal。
• 通过大量零散 margin 追求截图相似。
• 忽略响应式、长文本、空数据和字体差异。

6. 先实现一条纵向主链路

不要同时生成所有页面。先选择一条最能体现业务价值的链路：

进入页面
→ 加载数据
→ 搜索或筛选
→ 打开详情/弹窗
→ 修改数据
→ 提交
→ 成功刷新
→ 失败重试

第一条链路必须同时具备：

• 路由和页面框架。
• 真实或 Mock API。
• 表单和运行时校验。
• loading、empty、error。
• 权限判断。
• 成功和失败反馈。
• 请求取消和防重复提交。
• 单元或集成测试。
• 一条 Playwright E2E。

主链路通过以后，其他页面才适合交给 AI 批量复用模式。

7. 可直接使用的 AI 实施任务模板

## 目标

实现用户列表和编辑用户主链路。

## 事实源

- 原型：...
- Figma Node：...
- OpenAPI：...
- 参考页面：src/pages/...
- 现有组件：src/components/...

## 必须实现

- 列表加载、搜索、分页
- 编辑弹窗
- 成功、空、错误和无权限状态
- 请求取消和防重复提交

## 约束

- 不新建设计 Token
- 不修改公共请求拦截器
- 必须复用 ExistingTable 和 FormDialog
- API 类型必须从 OpenAPI 生成
- 禁止使用 any

## 验收

- typecheck、lint、unit、build 通过
- Playwright 覆盖搜索和编辑
- 1440px、1280px、移动端截图符合 Figma
- 接口失败后表单数据不能丢失

同时明确要求：

先检查仓库、现有实现和测试，输出映射、风险与计划；确认没有冲突后再修改。不要根据截图自行创造业务逻辑。

8. 不能绕过的质量门禁

8.1 静态质量

• TypeScript strict。
• ESLint 或项目既有代码检查。
• 禁止新增 any、未处理 Promise 和不必要的类型断言。
• 生产构建通过。
• Bundle 体积没有异常增长。

8.2 测试质量

风险	推荐验证方式
纯业务逻辑	Vitest 单元测试
表单和组件交互	Testing Library
请求与状态协作	MSW 集成测试
关键用户流程	Playwright E2E
Figma 视觉一致性	Playwright Screenshot
无障碍	axe 或 Playwright 无障碍测试
API 契约	OpenAPI 生成与契约测试

Playwright 可以通过 toHaveScreenshot() 保存和比较视觉基线。截图应在固定浏览器、操作系统和字体环境中生成，避免无意义差异。

CI 失败时使用 Playwright Trace Viewer 检查操作步骤、DOM 快照、网络、日志和截图，而不只是得到“元素不存在”的错误。

8.3 业务状态

至少覆盖：

• 首次进入。
• 有数据与无数据。
• 加载缓慢。
• 接口失败。
• 认证过期。
• 没有权限。
• 重复点击。
• 页面离开时取消请求。
• 响应乱序。
• 长文本和极端数据。
• 刷新后的状态恢复。

9. 业务稳定性的设计约束

9.1 请求不能散落在组件中

推荐分层：

页面组件
→ 业务 Hook/Service
→ 领域逻辑
→ 生成的 API Client
→ HTTP 层

页面负责展示，业务层负责状态和规则，生成客户端负责接口契约。

9.2 使用显式状态

不要只用多个布尔值表示请求状态：

type RequestState<T> =
  | { type: 'idle' }
  | { type: 'loading' }
  | { type: 'success'; data: T }
  | { type: 'empty' }
  | { type: 'error'; error: AppError }

9.3 写操作考虑幂等和未知结果

• 按钮禁用不能替代服务端幂等。
• 创建、支付和审批等操作应携带 idempotency key。
• 网络失败不能直接判断服务端一定没有执行。
• 自动重试只用于明确安全或幂等的操作。

9.4 权限必须由服务端强制

前端隐藏按钮只是体验优化，必须同时检查：

• 路由权限。
• 操作权限。
• 数据权限。
• 租户边界。
• API 服务端授权。

10. 发布、灰度和监控

上线前可以让 AI 生成：

• 变更摘要。
• 测试场景。
• 数据和接口兼容性检查。
• 灰度方案。
• 回滚步骤。
• 监控指标。
• 客服或运营说明。
• 已知限制。

推荐发布流程：

Feature Flag
→ 测试环境
→ 内部用户
→ 小比例灰度
→ 观察错误率和业务指标
→ 全量发布

至少监控：

• 页面 JavaScript 错误率。
• API 成功率和 P95。
• 白屏与静态资源加载失败。
• 关键操作完成率。
• 表单提交失败率。
• 权限拒绝和异常访问。
• 新旧版本业务指标差异。

11. AI 与人的职责边界

AI 适合负责

• 分析原型页面和操作流程。
• 提取 Figma 组件和设计变量。
• 生成类型、Client、Mock 和 Fixture。
• 创建页面骨架和重复表单。
• 编写单元、集成和 E2E 测试。
• 检查遗漏状态和错误路径。
• 生成发布、灰度和回滚文档。

人必须负责

• 业务规则冲突。
• 权限和数据边界。
• 原型、Figma、Apifox 不一致时的裁决。
• 复杂交互和产品取舍。
• 安全、支付和不可逆操作。
• 最终视觉和业务验收。
• 上线决策与事故责任。

12. Definition of Done

• [ ] 原型、Figma、OpenAPI 和代码映射已经完成。
• [ ] 所有冲突都有明确结论，不存在 AI 猜测的业务规则。
• [ ] API 类型来自契约，没有重复手写 DTO。
• [ ] 页面复用了现有 Design Token 和组件。
• [ ] 主流程及 loading、empty、error、无权限状态完整。
• [ ] 请求支持取消、防重复提交和错误恢复。
• [ ] TypeScript、Lint、测试和生产构建通过。
• [ ] 关键流程有 Playwright E2E 和失败 Trace。
• [ ] 核心页面通过视觉回归和响应式检查。
• [ ] 权限由服务端强制，前端只做展示投影。
• [ ] 发布有 Feature Flag、灰度、监控和回滚方案。
• [ ] 产品、设计、后端和测试完成最终验收。

最容易失败的做法

把原型 URL、Figma 和 Apifox 直接交给 AI，然后要求“完整实现全部页面”，通常只能得到一个看起来接近、局部能运行，但业务状态、权限、错误处理和接口边界不可靠的 Demo。

AI 提速依赖减少搜索、重复编码和测试编写；生产质量依赖事实源、契约、自动化门禁、灰度和人类决策。