AI前端开发上下文指南

为AI辅助前端开发提供完整的文档上下文和开发规范，确保生成的代码符合项目标准

📋 使用说明

核心目的：本指南为AI（GitHub Copilot、ChatGPT等）提供开发前端画面所需的完整上下文，包括：

项目架构和标准：技术栈、设计原则、编码规范
AI专用提示词：预定义的chatmodes和prompts
组件库定义：Storybook中的组件API和设计令牌
开发流程：从设计文档到代码的实现路径

用户（开发者）职责：

提供外部设计文档（Excel/Word）的内容摘要
选择适当的AI模式（chatmode）和提示词（prompt）
验证生成的代码符合项目标准
补充AI无法获取的业务逻辑细节

AI职责：

严格遵守本指南中的规范和标准
使用预定义的组件和设计令牌
生成类型安全、可测试的代码
遵循项目的目录结构和命名约定

🏗️ 项目架构概览

技术栈

前端框架: Nuxt 3 (SPA模式)
开发语言: TypeScript 5
UI库: Element Plus (通过atoms组件包装)
组件设计: Atomic Design (atoms/molecules/organisms/templates/domains)
状态管理: Pinia
测试: Vitest (单元测试), Playwright (E2E)
组件文档: Storybook

关键约束

SPA模式：不使用SSR/SSG，纯客户端渲染
类型安全：严格TypeScript模式，避免any类型
设计令牌：所有样式必须使用CSS自定义属性（设计令牌）
组件包装：Element Plus组件必须通过components/atoms/包装后使用
国际化：所有文本必须通过useI18n()获取，禁止硬编码

目录结构（简化）

frontend/src/
├── components/           # Atomic Design组件
│   ├── atoms/           # UI最小单位 (包装Element Plus)
│   ├── molecules/       # atoms组合
│   ├── organisms/       # 复杂UI部件
│   ├── templates/       # 页面布局结构
│   └── domains/         # 业务领域组件
├── composables/         # 组合式函数 (API调用、业务逻辑)
├── pages/               # 页面组件 (文件路由)
├── layouts/             # 布局组件
├── stores/              # Pinia状态管理
├── types/               # TypeScript类型定义
├── utils/               # 工具函数
└── assets/styles/       # 设计令牌和样式

🤖 AI专用配置（`.github/`目录）

1. Copilot基础指令

文件: .github/copilot-instructions.md 作用: 定义AI在整个仓库中的行为准则 关键规则:

安全原则：禁止处理机密信息
输出规则：结构化回答（根拠→要約→結論）
代码生成：遵循现有编码规范，包含错误处理
禁止事项：未经确认不得删除文件、调用外部API等

2. 专家模式（Chatmodes）

目录: .github/chatmodes/ 核心模式: 1-expert-nuxt3-frontend-engineer.chatmode.md

提供Nuxt 3 + TypeScript前端工程专家指导
包含项目结构、最佳实践、代码示例
强调SPA模式、Composition API、TypeScript类型安全

其他相关模式:

0-agent-optimized-4.1.chatmode.md：通用代理优化
0-blueprint-engineer-4.1.chatmode.md：蓝图工程师
1-expert-spring-boot-engineer.chatmode.md：后端参考

3. 专用提示词（Prompts）

目录: .github/prompts/

提示词文件	用途	输入参数
`atomic-component.prompt.md`	生成Atomic Design组件	`componentName`, `layer`, `baseComponent`, `props`
`mock-screen.prompt.md`	从线框图生成页面模版	`screenName`, `screenType`, `apply`
`frontend-unittest.prompt.md`	生成前端单元测试	无参数，基于当前选择的代码
`frontend-code-review.prompt.md`	前端代码审查	无参数，基于当前代码
`refactor-component.prompt.md`	重构现有组件	无参数，基于当前组件

使用方式:

# 在GitHub Copilot Chat中直接使用
/atomic-component componentName=button layer=atoms baseComponent=el-button props='{"type":"primary|default"}' apply=true

/mock-screen screenName=login screenType=form apply=true

#frontend-unittest

📚 设计标准和实现指南

1. 前端实现标准（架构圣经）

文件: docs/guidelines/implementation/frontend.md 必读章节:

目录结构和路径映射
Atomic Design组件层次定义
API调用模式（集中在composables/）
状态管理规范（Pinia使用）
表单验证实现（Zod + Element Plus）
国际化（i18n）配置

2. 组件设计指南

文件: docs/guidelines/design/11_frontend-component-design-guidelines.md 核心内容:

Atomic Design采用理由和成本效益分析
各层次（atoms/molecules/organisms）的职责划分
“3次规则”：只有被使用3次以上的UI才应组件化
组件分割的判断标准

3. 命名规范

文件: docs/guidelines/design/10_naming-conventions-guidelines.md 关键规则:

文件命名：kebab-case（例：labeled-input.vue）
组件标签：自动添加tao-前缀（例：<tao-button>）
变量命名：camelCase（TypeScript/JavaScript）
常量命名：UPPER_SNAKE_CASE
类型定义：PascalCase（接口、类型别名）

4. 前端设计指南

文件: docs/guidelines/design/03_frontend-design-guidelines.md 设计原则:

响应式设计基准
可访问性要求
性能优化指导
用户体验约束

5. 验证指南

文件: docs/guidelines/design/02_validation-guidelines.md 验证模式:

前端验证规则ID格式（例：VAL-F-REQ）
错误消息国际化
验证层次结构（UI层、API层、业务层）

🛠️ 实现教程（具体步骤）

1. 环境搭建和Mock实现

文件: frontend/docs/getting-started/installation.md 包含:

开发环境设置步骤
Mock数据配置（MSW - Mock Service Worker）
Storybook启动方法

2. 表单验证实现

文件: frontend/docs/guides/validation.md 核心模式:

// 使用Element Plus FormRules + Zod验证
const rules: FormRules = {
  email: [
    { required: true, message: t('validation.required'), trigger: 'blur' },
    { type: 'email', message: t('validation.email'), trigger: 'blur' }
  ]
}

3. 国际化实现

文件: frontend/docs/guides/i18n.md 关键点:

Vue I18n配置
语言文件结构
动态语言切换
格式化函数（日期、货币、数字）

4. 代码质量标准

文件: frontend/docs/standards/code-quality.md 工具链:

ESLint：代码质量检查
Prettier：代码格式化
TypeCheck：类型检查
import自动排序

🎨 设计系统和组件库

1. 设计令牌（Design Tokens）

位置: frontend/src/assets/styles/

tokens.css：基本令牌（间距、字体、边框半径）
tokens-ui.css：语义化令牌（颜色、UI状态）
colors-primitive.css：原始颜色定义

使用原则:

禁止硬编码：不使用color: #e65080，使用color: var(--ui-primary)
语义化优先：使用--ui-primary而非--color-red-500
响应式令牌：使用CSS自定义属性实现主题切换

2. Storybook组件定义

位置: frontend/src/components/**/*.stories.ts

组件层次结构:

Atoms：frontend/src/components/atoms/*.stories.ts
- Button, Input, Select, Checkbox等基础UI
- 包装Element Plus组件，添加项目特定样式
Molecules：frontend/src/components/molecules/*.stories.ts
- LabeledInput, SearchBox, FormField等组合组件
- 由多个atoms组成，实现特定功能
Organisms：frontend/src/components/organisms/*.stories.ts
- FormSection, DataTable, Card等复杂部件

组件API规范（以Button为例）:

// 来自 button.stories.ts
argTypes: {
  variant: {
    control: 'select',
    options: ['primary', 'outline', 'tertiary', 'ghost'],
    description: 'ボタンのバリエーション',
  },
  size: {
    control: 'select',
    options: ['large', 'medium', 'small'],
    description: 'ボタンのサイズ',
  },
  // ... 其他属性
}

查看方式:

# 启动Storybook
npm run storybook
# 访问 http://localhost:6006

3. 现有组件库

根据Storybook文件，已定义以下组件：

Atoms（基础组件）

Button：按钮组件，支持variant、size、shape、disabled等属性
Input：输入框，支持各种类型和状态
Select：下拉选择器
Checkbox：复选框
Radio：单选框
DatePicker：日期选择器
Dialog：对话框
Table：表格
更多详见frontend/src/components/atoms/目录

Molecules（组合组件）

LabeledInput：带标签的输入框
FormGroup：表单组
Pagination：分页组件
DateRange：日期范围选择器
RadioGroup：单选框组
更多详见frontend/src/components/molecules/目录

Organisms（复杂组件）

目前较少，根据业务需求逐步添加

🔄 开发工作流程

阶段1：需求分析（用户提供）

输入：外部设计文档（Excel/Word线框图） 用户需要提取并提供：

页面结构：布局、组件排列、导航关系
组件清单：使用的UI组件及其属性
业务规则：验证规则、计算逻辑、状态流转
数据模型：表单字段、API接口、数据类型
交互细节：按钮点击、表单提交、页面跳转

建议格式：

## 页面: 用户登录
- **路径**: `/auth/login`
- **类型**: 表单页面
- **组件**:
  - 邮箱输入框 (Input, 必填, 邮箱格式)
  - 密码输入框 (Input, type=password, 必填, 最小8位)
  - 登录按钮 (Button, variant=primary)
  - "忘记密码"链接 (Link)
- **验证规则**:
  - 邮箱: 必填, 邮箱格式
  - 密码: 必填, 8-32位字符
- **业务逻辑**:
  - 提交后调用`POST /api/auth/login`
  - 成功跳转到`/dashboard`
  - 失败显示错误消息

阶段2：组件选择或创建（AI辅助）

决策流程：

检查现有组件：查看Storybook中是否有合适组件
使用atomic-component提示词：创建新原子组件
组合现有组件：使用molecules/organisms组合功能

组件创建规则：

3次规则：只有被使用3次以上的UI才创建为组件
原子性：atoms应是最小可复用单元
包装原则：atoms包装Element Plus组件，添加设计令牌

阶段3：页面实现（AI辅助）

使用mock-screen提示词：

/mock-screen screenName=login screenType=form apply=true

前提：用户已在聊天中上传线框图图片

生成内容：

页面组件 (pages/auth/login.vue)
表单验证规则
国际化文本占位符
必要的布局组件

阶段4：业务逻辑集成（用户+AI协作）

AI生成：

API调用封装 (composables/useAuth.ts)
状态管理 (stores/auth.ts)
类型定义 (types/auth.ts)

用户补充：

实际API端点URL
业务特定计算逻辑
权限控制规则
错误处理策略

阶段5：测试生成（AI辅助）

使用frontend-unittest提示词：

#frontend-unittest

生成内容：

单元测试（Vitest + Vue Testing Library）
测试用例覆盖正常系、异常系、边界值
可访问性测试
类型安全测试

阶段6：代码审查（AI辅助）

使用frontend-code-review提示词：

#frontend-code-review

检查项：

是否符合设计标准
是否使用设计令牌
类型安全性
可访问性
性能优化

🧪 测试和质量保证

测试标准

文件: docs/guidelines/testing/frontend-unittest-guidelines.md 覆盖率目标：

行覆盖率：≥80%
分支覆盖率：≥70%
语句覆盖率：≥80%
函数覆盖率：≥80%

测试分类

正常系测试：基本渲染、Props、事件、状态变化
异常系测试：API错误、网络错误、无效输入
边界值测试：最小值/最大值、空数组、零值
验证测试：表单验证、Zod模式验证
可访问性测试：ARIA属性、键盘导航、焦点管理
国际化测试：文本翻译、格式本地化

测试工具

Vitest：测试运行器
Vue Testing Library：组件测试
Playwright：E2E测试
MSW：API模拟

🚨 常见陷阱和解决方案

陷阱1：硬编码样式

错误示例：

.button {
  color: #e65080; /* 硬编码颜色 */
  padding: 8px;   /* 硬编码间距 */
}

正确做法：

.button {
  color: var(--ui-primary);
  padding: var(--spacing-2);
}

陷阱2：直接使用Element Plus组件

错误示例：

<template>
  <el-button type="primary">提交</el-button>
</template>

正确做法：

<template>
  <tao-button variant="primary">提交</tao-button>
</template>

陷阱3：硬编码文本

错误示例：

<template>
  <h1>用户登录</h1>
</template>

正确做法：

<script setup lang="ts">
const { t } = useI18n()
</script>

<template>
  <h1>{{ t('pages.login.title') }}</h1>
</template>

陷阱4：缺少类型定义

错误示例：

const user = ref(null) // 类型为any

正确做法：

interface User {
  id: string
  name: string
  email: string
}

const user = ref<User | null>(null)

陷阱5：过度组件化

判断标准：3次规则

使用1-2次：内联实现
使用3次以上：创建组件

📋 检查清单（每次生成代码后验证）

架构合规性

使用SPA模式（非SSR/SSG）
目录结构符合Atomic Design
API调用集中在composables/
状态管理使用Pinia（stores/）

代码质量

使用TypeScript严格模式
无any类型，使用具体类型或unknown
包含错误处理（try-catch）
添加适当的JSDoc注释

设计系统

使用设计令牌（CSS自定义属性）
无硬编码颜色、间距、字体大小
包装Element Plus组件（通过atoms/）
遵循命名规范（kebab-case文件，camelCase变量）

国际化

文本通过useI18n()获取
无硬编码日语/英语文本
使用翻译键而非直接文本

可访问性

表单元素有相关标签
按钮有明确的ARIA标签
支持键盘导航
颜色对比度符合WCAG标准

性能

大型列表使用虚拟滚动
图片使用懒加载
组件按需加载（defineAsyncComponent）
避免不必要的重新渲染

🔗 快速参考

常用命令

# 开发
npm run dev          # 启动开发服务器 (localhost:3001)
npm run storybook    # 启动Storybook (localhost:6006)

# 代码质量
npm run lint         # ESLint检查
npm run lint:fix     # ESLint自动修复
npm run format       # Prettier格式化
npm run typecheck    # TypeScript类型检查

# 测试
npm run test         # 单元测试
npm run test:coverage # 带覆盖率的测试
npm run test:e2e     # E2E测试

关键文件路径

项目标准:
  docs/guidelines/implementation/frontend.md          # 前端实现标准
  docs/guidelines/design/11_frontend-component-design-guidelines.md  # 组件设计

AI配置:
  .github/copilot-instructions.md                    # Copilot基础指令
  .github/chatmodes/1-expert-nuxt3-frontend-engineer.chatmode.md  # 专家模式
  .github/prompts/atomic-component.prompt.md         # 组件生成提示词

设计系统:
  frontend/src/assets/styles/tokens.css              # 设计令牌
  frontend/src/components/atoms/button.stories.ts    # Button组件定义
  frontend/src/components/atoms/input.stories.ts     # Input组件定义

实现教程:
  frontend/docs/guides/validation.md                 # 表单验证教程
  frontend/docs/guides/i18n.md                       # 国际化教程
  frontend/docs/guides/mock-implementation.md        # Mock实现教程

紧急情况处理

问题: AI生成的代码不符合项目标准 解决方案:

使用#frontend-code-review提示词进行代码审查
参考docs/guidelines/implementation/frontend.md修正架构问题
检查是否使用了正确的设计令牌
验证类型安全性

问题: 缺少所需组件 解决方案:

使用/atomic-component提示词创建新组件
参考现有Storybook组件保持一致性
应用”3次规则”判断是否真的需要新组件

📞 支持与升级

文档更新

本指南应随项目演进定期更新
新增组件需添加到Storybook和本指南的”现有组件库”部分
架构变更需同步更新frontend.md和本指南

问题反馈

架构问题：更新docs/guidelines/implementation/frontend.md
组件问题：更新对应的Storybook文件和设计令牌
AI提示词问题：更新.github/prompts/中的提示词文件

版本历史

v1.0 (2026-02-03): 初始版本，基于当前项目状态创建
维护者: APJ-B2B开发团队
目标用户: AI辅助开发工具和前端开发者

AI前端开发上下文指南

📋 使用说明

🏗️ 项目架构概览

技术栈

关键约束

目录结构（简化）

🤖 AI专用配置（.github/目录）

1. Copilot基础指令

2. 专家模式（Chatmodes）

3. 专用提示词（Prompts）

📚 设计标准和实现指南

1. 前端实现标准（架构圣经）

2. 组件设计指南

3. 命名规范

4. 前端设计指南

5. 验证指南

🛠️ 实现教程（具体步骤）

1. 环境搭建和Mock实现

2. 表单验证实现

3. 国际化实现

4. 代码质量标准

🎨 设计系统和组件库

1. 设计令牌（Design Tokens）

2. Storybook组件定义

3. 现有组件库

Atoms（基础组件）

Molecules（组合组件）

Organisms（复杂组件）

🔄 开发工作流程

阶段1：需求分析（用户提供）

阶段2：组件选择或创建（AI辅助）

阶段3：页面实现（AI辅助）

阶段4：业务逻辑集成（用户+AI协作）

阶段5：测试生成（AI辅助）

阶段6：代码审查（AI辅助）

🧪 测试和质量保证

测试标准

测试分类

测试工具

🚨 常见陷阱和解决方案

陷阱1：硬编码样式

陷阱2：直接使用Element Plus组件

陷阱3：硬编码文本

陷阱4：缺少类型定义

陷阱5：过度组件化

📋 检查清单（每次生成代码后验证）

架构合规性

代码质量

设计系统

国际化

可访问性

性能

🔗 快速参考

常用命令

关键文件路径

紧急情况处理

📞 支持与升级

文档更新

问题反馈

版本历史

🤖 AI专用配置（`.github/`目录）