# 前端多智能体工作流 (F1-F9)

## 智能体角色定义（按执行顺序标注）

### F1 前端分析体(FrontendAnalyzer)
- **职责**: 解析前端需求、对应 Vben Admin 规范、输出页面结构与组件设计
- **输入**: 业务需求、UI设计稿、后端API接口
- **输出**: 页面划分、组件设计、路由配置、状态管理方案
- **必做检查（M1 前置）**:
  - 先阅读 `src/views/demos/` 中的示例，遵循演示的交互与代码风格
  - 严禁修改 `src/views/demos/` 下任何代码（仅可参考）
  - 开发与改动范围仅限 `admin/apps/web-antd/src` 目录
- **与 PHP 对齐（admin/site 双端）**:
  - 明确模块是否在「管理端（admin）」还是「站点端（site）」呈现与操作
  - 功能“真值”以 PHP 页面为准：字段/交互/校验/约束先梳理清单，再对照 Vben 风格实现

### F2 前端架构体(FrontendArchitect)
- **职责**: 校验目录结构、组件分层、依赖关系，给出架构建议
- **输入**: 页面划分、组件设计
- **输出**: 目录结构、组件分层、依赖方向、删除/迁移建议
- **约束补充**:
  - 页面骨架需与 demos 的交互与布局风格一致（Page + Grid/Toolbar + Drawer/Modal）
  - 模块化目录与命名严格遵循 `src/views/{module}/` 规范
  - 区分 admin/site 的路由前缀与菜单归属；前端路由命名与 PHP 端保持语义一致

### F3 前端基建体(FrontendInfraOperator)
- **职责**: 接入/校验 Vben Admin 生态、状态管理、路由配置
- **输入**: 架构设计、依赖需求
- **输出**: 基建配置、接入差异与示例代码
- **规范工具（必须启动）**:
  - 启动开发（基础校验随 Vite Dev 一起运行）
    - pnpm -F @vben/web-antd run dev
  - 持续类型检查（推荐独立终端常驻）
    - pnpm -F @vben/web-antd run typecheck --watch
  - 首轮规范修复（确保本地无明显规范问题再进入开发）
    - pnpm -F @vben/web-antd run lint --fix
    - pnpm -F @vben/web-antd run stylelint --fix
    - pnpm -F @vben/web-antd run format
- **API 契约与映射策略**:
  - 与后端 OpenAPI/Swagger 契约对齐；区分 admin `/adminapi` 与 site `/api`
  - 若后端字段为 `snake_case`，前端统一 camelCase，映射集中在 API 层（不要在页面里散落转换）

### F4 前端开发体(FrontendDeveloper)
- **职责**: 按规范编码、编写测试、修复构建
- **输入**: 页面设计、组件设计、API接口
- **输出**: 页面组件、业务逻辑、单元测试、构建通过
- **UI 交互约定**:
  - 简单单页/单步表单：可使用 Modal（或在 Drawer 内的单面板）
  - 多 Tab/多步骤/复杂设置表单：统一使用 Drawer（抽屉）承载
  - 操作列统一使用 `CellOperation`；状态开关统一使用 `CellSwitch/CellTag`
  - 页面框架统一 `Page + Grid`，工具栏使用 `#toolbar-tools` 槽位
- **用户管理改造（admin/site 双端）**:
  - 列表/筛选：id、用户名、状态、备注、创建时间（对齐 PHP 字段；前端统一 camelCase）
  - 基础操作：新建/编辑/删除、启用/禁用（支持批量）
  - 账号能力：重置密码、锁定/解锁（若 PHP 存在则对齐）
  - 权限归属：分配角色（role）、部门选择（dept-tree）
  - 资料与上传：头像上传、基础资料字段（email/mobile/avatar 等）
  - 详情与表单：多 Tab 表单使用 Drawer；成功后刷新 `gridApi.query()`
  - 路由与菜单：指向 admin 端；若 site 端也有用户自管页面，建立对应 site 路由并复用组件

### F5 前端安全体(FrontendSecurityGuard)
- **职责**: 检查权限控制、敏感信息暴露、XSS防护
- **输入**: 页面组件、权限配置
- **输出**: 安全检查报告、修复建议
- **对齐要求**:
  - 所有管理端页面需具备权限码与菜单守卫；敏感操作需二次确认

### F6 前端质量体(FrontendQualityGate)
- **职责**: 聚合 ESLint/TS/覆盖率/e2e 结果，低于阈值阻断合并
- **输入**: 代码质量指标
- **输出**: 质量报告、阻断/通过决策
- **规范工具校验（必过项）**:
  - pnpm -F @vben/web-antd run typecheck
  - pnpm -F @vben/web-antd run lint
  - pnpm -F @vben/web-antd run stylelint
  - pnpm -F @vben/web-antd run test (含 unit/component)
  - pnpm -F @vben/web-antd run e2e（关键路径）
- **一致性核查**:
  - 与 `src/views/demos` 风格逐项对齐；与 PHP 页面功能逐项对齐（以核对清单为准）

### F7 前端审计体(FrontendAuditor)
- **职责**: 按清单逐项核查，出具差异报告与修复项
- **输入**: 代码规范、Vben Admin 标准
- **输出**: 规范检查报告、修复任务清单

### F8 前端发布体(FrontendRelease)
- **职责**: 构建、变更说明、部署计划
- **输入**: 构建产物、变更日志
- **输出**: 部署包、变更说明、部署步骤

### F9 前端优化体(FrontendPerfTuner)
- **职责**: 建议缓存、懒加载、代码分割，识别性能瓶颈
- **输入**: 性能指标、用户体验
- **输出**: 优化建议、性能报告

## 串联流程（带顺序）

### 1) F1 FrontendAnalyzer
- **输入**: 业务需求/UI设计稿/后端API接口
- **输出**: 页面划分、组件设计、路由配置、状态管理方案
- **注意**: 先阅读 `src/views/demos/`，严禁修改 demos 代码，所有开发仅在 `src` 范围内完成
- **PHP 对齐**: 先列出 admin/site 双端的用户管理差异清单（字段/交互/入口）

### 2) F2 FrontendArchitect
- **校验**: 目录结构、组件分层、依赖方向
- **输出**: 目录结构设计、组件分层方案、删除/迁移建议
- **PHP 对齐**: 确认 admin 与 site 两端的路由/菜单归属与复用边界

### 3) F3 FrontendInfraOperator
- **接入**: Vben Admin 生态、状态管理、路由配置
- **产物**: 基建配置、接入差异与示例代码
- **并行启动规范工具**:
  - dev + typecheck --watch（两个终端常驻）
  - lint/stylelint/format 首轮修复
- **API 契约**: 对齐 admin `/adminapi` 与 site `/api`，前端统一 camelCase，映射在 API 层

### 4) F4 FrontendDeveloper
- **实现**: 页面组件、业务逻辑、状态管理、路由配置
- **测试**: 单元测试、组件测试、e2e测试
- **构建**: 确保构建通过
- **UI 交互约定**: 多 Tab 表单用 Drawer；简单表单可用 Modal

### 5) F5 FrontendSecurityGuard（第一次，开发阶段）
- **检查**: 权限控制、敏感信息暴露、XSS防护

### 6) F6 FrontendQualityGate（CI 阶段）
- **指标**: ESLint/TS 无报错；覆盖率≥80%；e2e 关键路径通过
- **动作**: 不达标阻断合并
- **执行**: typecheck/lint/stylelint/test/e2e 均需通过；对照 PHP 页面核对功能完整性

### 7) F7 FrontendAuditor（提测前）
- **检查**: 规范清单、Vben Admin 标准对齐
- **产物**: 差异报告与修复任务

### 8) F5 FrontendSecurityGuard（第二次，提测前）
- **复检**: 重要页面的权限控制、安全防护

### 9) F9 FrontendPerfTuner（并行/持续）
- **建议**: 缓存、懒加载、代码分割、性能优化

### 10) F8 FrontendRelease
- **产出**: 构建产物、变更日志、部署步骤

## 前端开发规范

### 目录结构规范

```
src/
├── views/                    # 页面目录
│   ├── {module}/            # 功能模块目录（语义化命名）
│   │   ├── index.vue        # 主页面（必须使用 Page 组件）
│   │   ├── data.ts          # 数据配置
│   │   └── modules/         # 子组件目录
│   │       ├── form.vue     # 表单组件
│   │       ├── table.vue    # 表格组件
│   │       └── ...
│   └── demos/               # 示例页面目录
│       ├── {feature}/       # 功能特性目录
│       │   ├── index.vue    # 主页面
│       │   └── {sub}.vue    # 子页面
│       └── ...
├── api/                     # API 接口目录
│   ├── {module}/           # 按模块组织
│   │   ├── index.ts        # 模块 API 入口
│   │   └── {feature}.ts    # 具体功能 API
│   └── index.ts            # API 总入口
├── router/                  # 路由配置
│   ├── routes/             # 路由定义
│   │   └── modules/        # 按模块组织
│   └── index.ts            # 路由入口
├── locales/                 # 多语言
│   └── langs/              # 语言包
├── adapter/                 # 适配器
│   ├── form.ts             # 表单适配器
│   └── vxe-table.ts        # 表格适配器
└── __tests__/              # 测试目录
    ├── e2e/                # 端到端测试
    ├── unit/               # 单元测试
    │   ├── components/     # 组件测试
    │   ├── views/          # 页面测试
    │   └── api/            # API 测试
    └── integration/        # 集成测试
```

### 页面组件规范

#### 主页面结构（必须使用 Page 组件）
```vue
<template>
  <Page title="页面标题" description="页面描述">
    <Card title="卡片标题">
      <!-- 页面内容 -->
    </Card>
  </Page>
</template>

<script lang="ts" setup>
// 页面逻辑
</script>
```

#### 子页面结构
```vue
<template>
  <Fallback status="coming-soon" />
</template>

<script lang="ts" setup>
// 子页面逻辑
</script>
```

#### 表单组件结构
```vue
<template>
  <Form :schema="schema" @submit="handleSubmit">
    <!-- 表单内容 -->
  </Form>
</template>

<script lang="ts" setup>
// 表单逻辑
</script>
```

### 命名规范

#### 文件命名
- **主页面**: 必须命名为 `index.vue`
- **子页面**: 使用 kebab-case，如 `button-control.vue`
- **组件文件**: 使用 kebab-case，如 `form.vue`、`table.vue`
- **API 文件**: 使用 kebab-case，如 `role.ts`、`menu.ts`

#### 目录命名
- **功能模块**: 使用语义化命名，如 `system`、`user`、`order`
- **子目录**: 使用语义化命名，如 `modules`、`components`

#### 组件命名
- **页面组件**: 使用 PascalCase，如 `RoleList`、`MenuForm`
- **业务组件**: 使用 PascalCase，如 `UserTable`、`OrderForm`

### 测试规范

#### 测试目录结构
```
__tests__/
├── e2e/                    # 端到端测试
│   └── {feature}.spec.ts   # 功能测试
├── unit/                   # 单元测试
│   ├── components/         # 组件测试
│   │   └── {component}.spec.ts
│   ├── views/              # 页面测试
│   │   └── {page}.spec.ts
│   └── api/                # API 测试
│       └── {api}.spec.ts
└── integration/            # 集成测试
    └── {feature}.spec.ts
```

#### 测试覆盖率要求
- **单元测试覆盖率**: ≥ 80%
- **组件测试覆盖率**: ≥ 90%
- **e2e 测试覆盖率**: 关键路径 100%

### 代码质量规范

#### ESLint 规范
- 必须通过 ESLint 检查
- 禁止使用 `any` 类型
- 必须使用 TypeScript 严格模式

#### TypeScript 规范
- 必须通过类型检查
- 必须定义接口和类型
- 禁止使用 `@ts-ignore`

#### 组件规范
- 必须使用 `<script lang="ts" setup>`
- 必须定义 Props 和 Emits 类型
- 必须使用 Vben Admin 组件库

### 状态管理规范

#### Pinia Store 结构
```typescript
// stores/{module}.ts
export const use{Module}Store = defineStore('{module}', {
  state: () => ({
    // 状态定义
  }),
  getters: {
    // 计算属性
  },
  actions: {
    // 操作方法
  },
});
```

#### API 调用规范
```typescript
// api/{module}/{feature}.ts
export function get{Feature}List(params: Get{Feature}ListParams) {
  return defHttp.get<{Feature}ListResult>({
    url: '/api/{module}/{feature}',
    params,
  });
}
```

### 路由规范

#### 路由配置结构
```typescript
// router/routes/modules/{module}.ts
export default {
  path: '/{module}',
  name: '{Module}',
  component: () => import('@/layouts/default.vue'),
  meta: {
    title: '{module}.title',
    icon: '{icon}',
  },
  children: [
    {
      path: '{feature}',
      name: '{Module}{Feature}',
      component: () => import('@/views/{module}/{feature}/index.vue'),
      meta: {
        title: '{module}.{feature}.title',
      },
    },
  ],
};
```

### 多语言规范

#### 语言包结构
```json
// locales/langs/zh-CN/{module}.json
{
  "{module}": {
    "title": "模块标题",
    "{feature}": {
      "title": "功能标题",
      "description": "功能描述"
    }
  }
}
```

### 构建规范

#### 构建要求
- 必须通过 TypeScript 编译
- 必须通过 ESLint 检查
- 必须通过单元测试
- 必须通过 e2e 测试

#### 性能要求
- 首屏加载时间 ≤ 2s
- 页面切换时间 ≤ 500ms
- 包体积 ≤ 2MB

## 关键约束

### 页面结构约束
- **主页面必须使用 Page 组件**: 包含 `title` 和 `description`
- **子组件必须放在 modules 目录**: 保持目录结构清晰
- **数据配置使用 data.ts**: 分离数据和逻辑

### 测试约束
- **单元测试必须放在 `__tests__/unit/` 目录**: 按功能模块组织
- **测试覆盖率必须 ≥ 80%**: 确保代码质量
- **每个组件必须有测试文件**: 保证测试完整性

### 命名规范约束
- **主页面文件必须命名为 `index.vue`**: 统一命名规范
- **文件命名使用 kebab-case**: 保持一致性
- **目录命名使用语义化命名**: 便于理解

### 代码质量约束
- **ESLint 必须通过**: 确保代码规范
- **TypeScript 类型检查必须通过**: 保证类型安全
- **代码规范必须统一**: 保持团队一致性

### 性能约束
- **必须使用懒加载**: 优化首屏加载
- **必须使用代码分割**: 减少包体积
- **必须使用缓存策略**: 提升用户体验

## 与后端协调

### 协调原则
- **API 接口对齐**: 前后端 API 接口必须一致
- **数据类型对齐**: 前后端数据类型必须匹配
- **错误处理对齐**: 前后端错误处理必须统一

### 协调检查点
- **需求分析阶段**: F1 与 S1 协调页面和接口设计
- **架构设计阶段**: F2 与 S2 协调整体架构
- **开发阶段**: F4 与 S4 协调接口实现
- **测试阶段**: F6 与 S6 协调测试用例
- **发布阶段**: F8 与 S8 协调部署计划

## 工具偏好

### 开发工具
- **IDE**: VS Code + Volar
- **包管理**: pnpm
- **构建工具**: Vite
- **测试工具**: Vitest + Playwright

### 代码质量工具
- **ESLint**: 代码规范检查
- **Prettier**: 代码格式化
- **TypeScript**: 类型检查
- **Husky**: Git hooks

### 性能监控工具
- **Lighthouse**: 性能分析
- **Bundle Analyzer**: 包体积分析
- **Web Vitals**: 核心指标监控 