前端团队 AI Core Workflow：从心法到落地

一、启动心法：Prompt 的四个核心维度 (Frontend Edition)

在启动任何一个前端功能（Feature）开发时，我们必须在 Inception（构思）阶段的第一个 Prompt 中明确以下四点。这不是废话，这是防止 AI "胡乱发挥" 的基石。

1. 功能边界 (Scope)

做什么：明确是开发一个"通用组件"还是"业务页面"。
不做什么：明确是否包含后端接口 Mock，是否处理极端边界情况（如 IE 兼容性）。

2. 技术约束 (Constraints)

技术栈：Vue 3.5+ / Nuxt 3 / TypeScript (Strict Mode)。
样式库：Tailwind CSS (禁止写行内 style，禁止手写 raw CSS)。
状态管理：Pinia (必须使用 Setup Store 写法)。
组件规范 ：必须使用 <script setup>, Props 必须定义类型接口。

3. 交付物格式 (Deliverables)

代码：.vue 文件，独立的 useLogic.ts (Composable)，以及 types.ts。
文档：组件用法说明 (Markdown)，包含 Props/Emits 表格。
测试：Vitest 单元测试文件（针对核心逻辑）。

4. 实现计划 (Phasing)

Phase 1: 类型定义 (Types) & API Mock。
Phase 2: 静态 UI (Skeleton & Tailwind)。
Phase 3: 逻辑接入 (Composable & State)。

二、 Plan 模式：前端复杂任务的 WBS 分解

得物的案例是后端视角的，我将其转化为前端视角的"拜访任务系统"分解。前端的复杂性在于组件拆分、状态通信和交互反馈。

现状痛点

直接让 AI "写一个拜访任务页面"，结果通常是：

巨型组件 ：一个 .vue 文件写了 800 行代码。
样式污染 ：随便起了个 .container 类名，影响了全局。
逻辑耦合：API 调用、数据处理、UI 展示混在一起，无法维护。

解决方案：前端模块化 WBS

我们将后端 M1-M12 映射为前端组件与逻辑模块：

第一步：模块清单 (Module Breakdown)

模块 ID	模块名称	类型	描述与复杂度
M1	`types/visit.ts`	Type	全局类型定义（任务、审批、状态枚举）。(Low)
M2	`useVisitStore`	Store	Pinia 状态管理（列表缓存、筛选条件、当前选中任务）。(Medium)
M3	`useVisitService`	Hook	API 封装层（处理 Axios、防抖、错误拦截）。(Medium)
M4	`VisitCreateForm`	UI	创建表单组件（包含多级联动选择器、表单验证规则）。(High)
M5	`VisitListFilter`	UI	列表筛选器组件（日期范围、状态下拉、搜索框）。(Low)
M6	`VisitListCard`	UI	任务卡片组件（展示摘要、状态 Tag、操作按钮插槽）。(Medium)
M7	`VisitDetailDrawer`	UI	详情抽屉组件（复用卡片信息，展示审批流 Timeline）。(High)
M8	`VisitUploadModal`	UI	结果上传弹窗（图片上传、OSS 签名处理）。(Medium)

第二步：技术方案设计 (Tech Solution)

M2 (Store) : 使用 Map 结构存储列表以优化查找性能；实现 fetchList 和 updateItem action。
M4 (Form) : 使用 FormKit 或 ElementPlus Form；校验规则抽离为 rules.ts。
M6 (List): 实现虚拟滚动 (Virtual Scroll) 如果预期数据超过 100 条。

第三步：优先级排序 (Priority)

P0 (核心链路): M1 (Types) -> M3 (API) -> M6 (List UI) -> M2 (Store 基础)。
P1 (交互闭环): M4 (Create Form) -> M7 (Detail Drawer)。
P2 (增强功能): M5 (Filter) -> M8 (Upload)。

三、三阶段对话模型 (前端实操版)

这是我们与 AI 结对编程的标准 SOP。

阶段一：需求定义 (UI/UX Definition)

目标：让 AI "看懂" 设计图和交互逻辑。

User Prompt 示例:

"我们要实现【M4: 任务创建表单】。

用户故事：作为销售，我点击'新建'按钮，弹出一个模态框，填写拜访对象（需远程搜索）、时间和备注。

验收标准 (AC)：

'拜访对象'支持服务端模糊搜索，防抖 300ms。

'时间'不能早于当前时间。

提交时按钮 loading，禁止重复点击。

提交成功后关闭弹窗并刷新列表。"

阶段二：边界明确 (Tech Constraints)

目标：锁死技术栈，防止 AI 引入奇怪的库。

User Prompt 示例:

"技术约束 (Must Follow):

组件路径：src/components/business/visit/VisitCreateForm.vue。

UI 库：使用 Element Plus 的 <el-dialog> 和 <el-form>。

样式：使用 Tailwind CSS 处理布局 (flex/grid) 和间距 (m-4, p-4)。

逻辑抽离：表单提交逻辑必须封装在 composables/useVisitAction.ts 中，不要写在组件内部。

类型安全：所有 Props 必须引入 types/visit.ts 定义的接口。"

阶段三：迭代反馈 (Iterative Verification)

目标：分层验证，拒绝"一步到位"。

Step 1 - 骨架屏验证 : "先生成组件的 <template> 结构和 Props 定义，不要写具体逻辑。确认 UI 布局是否符合设计？" -> 人工 Review。
Step 2 - 逻辑注入 : "结构确认。现在实现 useVisitAction 中的提交逻辑，并绑定到 Template 上。" -> 人工 Review。
Step 3 - 完善细节: "添加表单验证规则和 Loading 状态。"

四、真实踩坑经验与技巧 (Tips)

1. "遗忘约束" 的对抗策略 (Context Anchor)

AI 在写到第三个组件时，经常忘记我们一开始说的 "所有 API 请求都要经过 request.ts 封装"。

技巧：在每个新 Prompt 的开头，一句话回顾关键约束。
- Prompt : "现在我们开始写 M6 列表组件。Remember : 依然保持 Tailwind 样式，且点击事件通过 emit 向外抛出，不要在组件内直接调用 API。"

2. "幻觉" 依赖管理

AI 喜欢引入它熟悉的库（比如 moment.js 或 lodash），但我们项目里可能用的是 dayjs 和 lodash-es。

技巧：在 System Prompt 或 .cursorrules 中明确："禁止引入 package.json 中不存在的依赖。"

3. 上下文管理的 "Thread 隔离"

不要：在一个对话框里从头聊到尾，聊完列表聊详情，再聊登录。
要：
- Thread A: "拜访系统 - 数据结构设计" (产出 JSON/TS)。
- Thread B: "拜访系统 - 列表页开发" (喂入 Thread A 的 TS 产物)。
- Thread C: "拜访系统 - 表单开发"。

五、质量控制 (Quality Control)

前端的质量控制分为三层，AI 负责底层，人类负责高层。

验证层级	执行者	内容
L1: 代码规范	AI + Lint	ESLint 检查，TypeScript 类型检查 (不能有 `any`)，Props 定义完整性。
L2: 逻辑验证	AI (Unit Test)	让 AI 为 `useVisitService.ts` 编写 Vitest 测试用例，Mock 接口返回，确保状态流转正确。
L3: 体验验收	Human	视觉还原度（Pixel Perfect），交互流畅度，Loading/Error 状态的各种边界测试。