12 AI 协同前端工程化实战：项目改造与扩充联调

AI 协同前端工程化实战：项目改造与扩充联调

关联：索引

问题探究：

本段按“先规范输入（任务卡/约束/计划），再写提示词生成补丁”的顺序组织，避免先写代码后补规则导致返工。

在企业里，规范写在 Wiki 往往“看过就忘”，引入 AI 后更容易“生成时跑偏”。Trae 的 Skills 可以把规范做成可复用的“约束层”，在 AI 生成/改造代码时持续对齐，帮助把规范从“写在文档里”变成“写进生成过程里”。

  1. code-standards（工程/类型/目录约束）：让 AI 不敢写 any、不敢乱放文件、不敢编造脚本
  2. vue3-file-template（Vue3 文件结构模板）：让 AI 生成的 .vue 文件块顺序一致、可读性一致

Skill 示例 1：code-standards（本课程版，结构示例）

---
name: code-standards
description: 前端工程规范约束（本课程版）
globs:
  - "**/*.ts"
  - "**/*.vue"
---

# Instructions

## TypeScript 门禁
- 禁止使用 any；必要时用 unknown + 类型守卫
- 禁止到处使用类型断言（as）；若必须断言，只能在边界层集中处理并说明原因
- 领域类型集中在 src/types/*，不允许在 views/components 重复定义口径

## 目录职责（必须遵守）
- src/views：页面编排
- src/components：可复用组件
- src/services：数据获取/请求/模拟数据
- src/utils：纯函数工具（映射、格式化、判定）
- src/types：领域类型与口径

## 生成与改造约束
- 不引入新依赖
- 必须按“文件路径 + 完整代码”交付，不给片段与省略号
- 只改任务卡允许的文件边界；不得偷偷加新功能

Skill 示例 2：vue3-file-template（本课程版，结构示例）

---
name: vue3-file-template
description: Vue3 SFC 结构约束（本课程版）
globs:
  - "src/views/**/*.vue"
  - "src/components/**/*.vue"
---

# Instructions

生成或改造 Vue3 单文件组件时，必须按以下区块顺序组织代码：
1) import 区
2) 类型区（type/interface）
3) 响应式状态（ref/reactive）
4) 纯逻辑函数（优先抽到 utils/composables）
5) 事件处理/业务方法
6) 生命周期（onMounted 等）
7) style（如有）

页面文件（src/views）优先“变薄”，把映射/判定/过滤分页等纯逻辑抽到 src/utils 或 src/composables。

本讲不依赖任何特定指令体系，核心是把“输入写清 + 约束固定 + 输出可覆盖 + 过程可回归”这四件事做稳。Skills 的作用是把团队工程约束变成“生成时就会生效”的约束层，减少风格漂移与返工。

  1. 再列实施步骤（5–9 步即可）：每步写清“改哪些文件 + 为什么改 + 怎么验证”
  2. 最后写提示词：明确“已启用 Skills 名称 + 文件级交付 + 只改允许文件边界 + 不引入依赖”
目标：把 09_element_plus_demo/src/views/DeviceListView.vue 做“规范化改造”，不改变 UI 结构与交互结果。

工程约束（以已启用 Skills 为准）：
1) 已启用 Skills：code-standards、vue3-file-template
2) 不引入新依赖；不使用 any；领域类型以 src/types/device.ts 为唯一口径
3) 目录职责：types / utils / services / composables / views 分层明确，views 尽量变薄

唯一事实输入：
- 我会提供 src/views/DeviceListView.vue 与 src/types/device.ts 的完整内容（以及需要参考的现有文件）

交付要求（强制）：
1) 输出“文件路径 + 完整代码”，可直接复制覆盖运行
2) 每个文件附“为何改/如何验证”
3) 最后输出 6 条自查清单，并对应到验收标准与回归点

本讲的“规范化”不是重写页面，而是让已有代码更像团队可维护代码：目录职责清晰、口径集中复用、页面变薄、纯逻辑可测试、交付可回归。

建议的规范化改造落点（从现状出发）：

  1. 视图文件变薄：筛选/分页/映射/离线判定不再堆在 view 内部
  2. 类型门禁通过：不出现 any，不到处 as，领域口径统一复用
  3. 交互不回退：筛选/重置回到第 1 页；分页与筛选条件联动正确
  4. 离线联动正确：离线 Tag 正确展示；启停/告警确认等高风险操作置灰不可点（可选提示原因）
  5. 弹窗闭环完整：新增/编辑共用弹窗；校验生效；关闭清空校验；保存关闭并刷新
  6. 文件级交付可覆盖：按路径输出全量文件，复制覆盖后可 npm run dev、/dashboard 与 /device-list 可访问

0.3 小组多人协作：把规范式开发跑成“可合入流程”

协作交付物（每组最后必须交齐）：

  1. 改造步骤清单（写清步骤与验证方式）

  2. 文件级改造补丁（文件路径 + 完整代码）

  3. 门禁结果（至少：npm run build 是否通过 + 回归点复测记录）

  4. 口径负责人先产出任务卡，并把“唯一事实输入”冻结：
    src/views/DeviceListView.vue + src/types/device.ts（允许另附 src/views/DashboardView.vue 作为参照，但不允许让 AI 臆测不存在的文件）

  5. 开发者拆分实施步骤，并把“文件所有权”写进步骤清单：

  1. 质量负责人做轻量互审：对照 Skills 与回归点，指出 3 个可执行改进（例如 any/目录漂移/重复映射/函数过长），并写清“如何验证”
  2. 合入前门禁：执行 npm run build，并按回归点逐条复测（筛选归 1、分页保留条件、离线禁用不回退等），不通过则回到对应步骤修复
【任务名称】（一句话）
【目标】你要交付的可验收结果是什么？
【范围】包含/不包含什么（防止越界加功能）
【页面/文件边界】允许改哪些文件？新增哪些文件？（文件路径级）
【业务规则】口径、禁用条件、边界行为（空态/异常/离线）
【数据契约】入参/出参、分页字段、空值策略、mock 规则
【工程约束】不允许 any；目录职责；命名规则；错误处理要求
【验收标准】用 5 条以内的可点击/可复现验收点描述
【回归点】改动后必须不回退的旧功能点

“文件级交付”提示词的 5 条强制条款（规范输出）：

2. 规范包补齐（示例提示词：把第 11 讲页面变成“可交付代码”）

我已经有第 11 讲产出的 `09_element_plus_demo` 项目（Vue3 + Vite + TS + Element Plus），其中关键文件为：
- src/views/DeviceListView.vue
- src/views/DashboardView.vue
- src/types/device.ts
现在要把其中一个页面改造成“团队可交付代码”。
请你按下面规则输出“文件路径 + 完整代码”（只输出需要新增/修改的文件），用于在现有项目中直接粘贴覆盖：

【已启用 Skills（必须遵守）】
- code-standards：约束 TypeScript/目录职责/文件级交付（适用范围：**/*.ts、**/*.vue）
- vue3-file-template：约束 Vue SFC 结构与 views 变薄（适用范围：src/views/**/*.vue、src/components/**/*.vue）
- 若你输出的文件路径不在上述 globs 覆盖范围内，也必须手动遵守同等约束（避免风格漂移）

【改造目标】
1) 让页面代码更可维护：目录分层清晰，职责拆分，避免在 view 里堆映射/过滤/格式化
2) 让核心逻辑更可测试：把纯逻辑抽成纯函数（输入→输出），避免依赖 UI/全局状态
3) 不改变 UI 结构与交互结果：筛选/分页/弹窗/操作栏行为不回退（沿用第 11 讲验收点）

【允许新增/调整的文件建议】（按实际情况选择）
- src/utils/mappers.ts：状态文案与 Tag 映射（集中管理）
- src/utils/offline.ts：离线判定与状态归一（纯函数）
- src/services/device.ts：listDevices/queryDevices（可先 mock）
- src/composables/useDeviceList.ts：把“查询条件 + 分页 + 列表刷新”抽出（避免 view 过大）
- src/types/device.ts：若已存在则沿用，只做最小必要补齐（不重复定义）

【强制约束】
- 不使用 any，不使用到处 as
- 不编造不存在的依赖与脚本命令
- 每个文件末尾附“为何改/如何验证”
- 最后附 6 条自查清单（必须包含：类型无 any、改造前后交互不回退、离线禁用逻辑不回退）

3. 自查清单（闭环 A：改造不回退）

  1. 教师抽 1 组展示：指出 1 处“会导致不可交付/不可复查”的缺口并现场修正。

项目工坊主题：绿色食品智能分拣系统综合实战：结构 + 路由 + 状态 + 主界面整合联调（以 09_element_plus_demo 为基础），并在 Skills 约束下完成规范统一与问题修复。

A. 选择改造对象（示例：设备列表页面）

示例提示词：

下面是第 11 讲 `09_element_plus_demo` 项目里的页面文件内容（以及 `src/types/device.ts` 的类型定义）。请你把它当作唯一事实来源：
1) 先给出“改造方案”：拆分哪些职责到 services/utils/composables，为什么（对齐 Skills 与目录职责）
2) 再输出改造后的“文件路径 + 完整代码”（只输出有变更的文件，可直接复制覆盖运行）
3) 最后输出 6 条自查清单（覆盖类型门禁、目录门禁、交互回归点）
约束：
- 不改变页面 UI 结构与交互结果（沿用第 11 讲验收点）
- 不引入新 UI 组件库
- 不使用 any；类型以现有 src/types/* 为准（若需补齐，最小化修改）

B. 扩充任务（从 demo 到分拣系统：结构 + 路由 + 状态 + 主界面）

扩充的目标不是“加很多页面”，而是在 Skills 约束下，把新增模块做成可扩展的工程结构，并能与现有 /dashboard、/device-list 联调跑通。

  1. 新增 1 个业务页面：分拣任务（Sorting Tasks）或告警中心（Alarm Center）
  2. 新增 1 个 Pinia 模块：维护列表查询条件、分页、加载态（把可复用逻辑从 view 中抽走）
  3. 新增 1 个 services 层：先用 mock 数据，后续可替换为真实接口
  4. 打通主界面：侧边栏菜单新增入口；路由可达；主区域正常渲染

建议的文件边界（按实际情况增减）：

C. 人工优化与规范统一（当堂必须做）

加练任务（进度较快的小组可选）