# CLAUDE.md

## 1. 文档目的

本文件用于指导 AI 在本项目中的开发行为，包括：

* 页面生成
* 组件开发
* 接口联调
* Mock 数据生成
* 文档生成

AI 在进行任何代码生成或修改时，必须遵守本文件中的规则。

优先级如下：

1. 用户输入要求
2. 本文件规则
3. 项目已有代码风格
4. 常见开发最佳实践

---

# 2. 技术栈

AI 在本项目中生成代码时，必须严格使用以下技术栈，不得引入其他框架或替代方案。

## 前端框架

* Vue 3

必须使用 Vue 3 Composition API。

推荐使用：

```vue
<script setup>
```

---

## UI 组件库

* Element Plus

页面 UI 应优先使用 Element Plus 组件完成。

避免自行实现已有组件能力。

常用组件：

* Button - 按钮
* Table - 表格
* Form / FormItem - 表单
* Input - 输入框
* Select - 选择器
* DatePicker - 日期选择器
* Dialog - 对话框
* Drawer - 抽屉
* Pagination - 分页
* Card - 卡片
* Menu - 菜单
* Tabs - 标签页
* Breadcrumb - 面包屑
* Dropdown - 下拉菜单
* Message / MessageBox - 消息提示
* Loading - 加载

如果 Element Plus 已有组件可以实现需求，应优先使用。

Element Plus 文档：https://element-plus.org/zh-CN/

---

## 编程语言

* JavaScript

不使用 TypeScript。

---

## 样式方案

* Less

组件样式必须使用 Less，并添加 `scoped` 属性。

示例：

```vue
<style lang="less" scoped>
.page-container {
  padding: 20px;

  .title {
    font-size: 18px;
    color: #333;
  }
}
</style>
```

---

## 构建工具

* Vite

---

# 3. 项目结构

```
src/
├── api/           # API 接口定义
├── assets/        # 静态资源（图片、字体等）
├── components/    # 公共组件
│   ├── ui/        # 纯 UI 组件
│   └── business/  # 业务组件
├── config/        # 配置文件
├── mock/          # Mock 数据
├── router/        # 路由配置
├── store/         # Vuex 状态管理
├── utils/         # 工具函数
├── views/         # 页面组件
├── App.vue        # 根组件
└── main.js        # 入口文件
```

---

# 4. 开发规范

## 4.1 页面开发

### 页面位置

所有页面必须放在 `src/views/` 目录下。

### 页面命名

* 使用大驼峰命名法（PascalCase）
* 文件名与路由 name 保持一致

示例：

```
views/
├── Home.vue           # 首页
├── UserList.vue       # 用户列表页
├── UserDetail.vue     # 用户详情页
├── OrderList.vue      # 订单列表页
└── OrderDetail.vue    # 订单详情页
```

### 页面结构

推荐页面结构：

```vue
<template>
  <div class="page-name">
    <el-card>
      <template #header>
        <span>页面标题</span>
      </template>
      <!-- 页面内容 -->
    </el-card>
  </div>
</template>

<script setup>
</script>

<style lang="less" scoped>
.page-name {
  padding: 20px;
}
</style>
```

---

## 4.2 组件开发

### 组件位置

* UI 组件：`src/components/ui/`
* 业务组件：`src/components/business/`

### 组件命名

* 使用大驼峰命名法（PascalCase）
* 组件名应具有描述性，避免使用缩写

### 组件设计原则

组件必须遵循可复用设计。

#### 单一职责

组件只负责一个 UI 或功能。

避免：

* 过大组件
* 多业务混合组件

#### UI 与业务逻辑分离

UI 组件只负责展示，业务组件负责逻辑。

#### 明确输入输出

组件输入：`props`
组件输出：`emit`

避免：

* 组件直接修改外部状态
* 隐式依赖

#### 可复用性

组件设计应尽量抽象。

例如：

不要写：`UserOrderList.vue`
优先写：`OrderList.vue`

---

## 4.3 路由规范

### 路由定义

路由定义在 `src/router/index.js` 中。

### 路由配置

```javascript
{
  path: '/order-list',
  name: 'OrderList',
  component: () => import('@/views/OrderList.vue'),
  meta: {
    title: '订单列表'
  }
}
```

### 路由跳转

使用 `useRouter` 进行编程式导航：

```javascript
import { useRouter } from 'vue-router'

const router = useRouter()

// 跳转页面
router.push('/order-list')
router.push({ name: 'OrderList' })

// 返回上一页
router.back()
```

---

## 4.4 API 请求

### 请求封装

项目已封装 axios，位于 `src/utils/request.js`。

### 接口定义

所有接口定义在 `src/api/` 目录下，按模块组织。

示例 `src/api/order.js`：

```javascript
import request from '@/utils/request'

export const getOrderList = (params) => {
  return request.get('/api/orders', { params })
}

export const getOrderDetail = (id) => {
  return request.get(`/api/orders/${id}`)
}

export const createOrder = (data) => {
  return request.post('/api/orders', data)
}
```

### 使用方式

```javascript
import { getOrderList } from '@/api/order'

const fetchOrders = async () => {
  try {
    const res = await getOrderList({ page: 1, size: 10 })
    // 处理数据
  } catch (error) {
    console.error('获取订单列表失败', error)
  }
}
```

---

## 4.5 状态管理

### 使用 Vuex

状态管理使用 Vuex 4。

### Store 结构

```javascript
// src/store/modules/user.js
export default {
  namespaced: true,
  state: {
    userInfo: null
  },
  mutations: {
    SET_USER_INFO(state, info) {
      state.userInfo = info
    }
  },
  actions: {
    setUserInfo({ commit }, info) {
      commit('SET_USER_INFO', info)
    }
  }
}
```

### 使用方式

```javascript
import { useStore } from 'vuex'

const store = useStore()

// 读取 state
const userInfo = computed(() => store.state.user.userInfo)

// 调用 mutation
store.commit('user/SET_USER_INFO', info)

// 调用 action
store.dispatch('user/setUserInfo', info)
```

---

# 5. UI 设计与布局规范

## 设计规范

页面布局应遵循 Element Plus 的设计规范。

主要遵循以下原则：

### 布局结构

推荐后台管理页面结构：

```
Sidebar (侧边栏导航)
Header (顶部栏)
Content (主内容区)
```

或

```
Header
Main Content
Footer
```

---

### 页面间距

推荐间距体系：

* 8px
* 16px
* 20px
* 24px

默认页面 padding：20px

---

### 内容宽度

PC 端页面应采用响应式布局。

常用布局方式：

* 固定宽度居中（推荐最大宽度 1200px - 1440px）
* 流式布局（适应屏幕宽度）
* 侧边栏 + 主内容区布局

---

### 表格布局

PC 端推荐使用表格展示列表数据。

使用 Element Plus 的 `el-table` 组件。

---

# 6. 主题色规范

项目使用 Element Plus 默认主题色。

主色调：

```
#409eff
```

AI 在生成 UI 时应遵守：

* 主按钮使用主色 `type="primary"`
* 重要操作使用主色
* 高亮状态使用主色

Element Plus 主题配置已在 `main.js` 中引入，无需额外配置。

## 参考图片色调规则

当用户提供参考图片时：

* 如果用户**明确要求**参考图片中的色调，则使用图片中的色调
* 如果用户**未明确要求**参考图片中的色调，则**必须使用项目定义的主色调**（#409eff），而非图片中的色调

此规则确保项目视觉风格的一致性。

## 图表规范

项目中如需使用图表，必须使用 **ECharts**。

图表色调要求：

* 图表主色调必须与项目主色调（#409eff）保持一致
* 图表配色方案应基于项目主色调进行扩展
* 避免使用与项目风格冲突的配色

---

# 7. Less 样式规范

## 基本规则

* 所有组件样式必须使用 Less
* 必须添加 `scoped` 属性避免样式污染
* 使用嵌套语法组织层级关系

## 命名规范

* 类名使用小写，多个单词用连字符（kebab-case）
* 页面根元素类名与页面 name 保持一致

示例：

```less
.order-list-page {
  padding: 20px;

  .header {
    display: flex;
    align-items: center;
    margin-bottom: 20px;

    .title {
      font-size: 18px;
      font-weight: 500;
    }
  }

  .content {
    background-color: #fff;
  }
}
```

## 样式变量

如需定义 Less 变量，可在组件内定义：

```less
<style lang="less" scoped>
@primary-color: #409eff;
@border-radius: 4px;

.card {
  background-color: #fff;
  border-radius: @border-radius;
  border: 1px solid @primary-color;
}
</style>
```

---

# 8. Mock 数据规则

## 基本原则

无论接口来源如何，都必须创建 Mock 数据。

* 用户提供接口
* AI 自行设计接口

## 接口数据设计原则

在设计 Mock 接口的数据时，如果用户没有明确说明，遵循以下原则：

* **明显是动态数据的应设计为接口数据**：如用户信息、订单列表、商品数据等会随业务变化的动态内容
* **值比较固定的组件不应设计为接口数据**：如月份选择器、日期选择器、省市区选择器等选项值固定的组件，这些数据应直接在组件内定义，不需要从接口请求

示例：

```
// 需要设计为接口的数据
- 用户列表、订单列表、商品列表
- 用户详情、订单详情
- 动态配置项

// 不需要设计为接口的数据
- 月份选项（1-12月）
- 星期选项（周一至周日）
- 省市区数据（可使用静态数据）
- 性别选项、状态选项等固定枚举值
```

## Mock 文件位置

```
src/mock/
```

每个接口对应一个 mock 文件。

示例：

```
src/mock/orderList.js
src/mock/userInfo.js
```

## Mock 文件格式

```javascript
export default {
  code: 0,
  message: 'success',
  data: []
}
```

## Mock 与真实请求切换

是否发送真实请求由以下配置决定：

```
src/config/index.js
```

配置字段：`mock`

### mock = true

不发送真实请求，直接使用 mock 数据。

### mock = false

发送真实请求，通过接口访问后端服务。

## Mock 逻辑实现

当 `mock = true` 时，API 层应直接返回 mock 数据。

示例：

```javascript
import config from '@/config'
import mockData from '@/mock/orderList'

export const getOrderList = (params) => {
  if (config.mock) {
    return Promise.resolve(mockData)
  }
  return request.get('/api/orders', { params })
}
```

---

# 9. 接口文档规则

## 用户提供接口文档时

AI 必须：

1. 严格按照接口文档实现请求逻辑
2. 保持字段名称一致
3. 保持返回结构一致
4. 不随意修改字段含义
5. 不自行扩展字段

请求参数结构必须与接口文档保持一致。

## 未提供接口文档时

AI 必须根据页面结构自行设计接口。

设计原则：

* 数据结构合理
* 字段语义清晰
* 避免冗余字段
* 符合 REST 风格

示例：

```json
{
  "id": 1,
  "title": "订单标题",
  "price": 99.9,
  "status": "paid",
  "createdAt": "2025-01-01"
}
```

## 接口文档生成

如果接口是 AI 自行设计的，必须在以下目录创建文档：

```
docs/接口设计.md
```

文档内容必须包含：

* 接口名称
* 请求路径
* 请求方式
* 请求参数
* 返回结构
* 字段说明
* 示例数据

---

# 10. 文档维护规则

新增修改以下内容时必须更新文档：

* 接口
* 模块
* 组件体系

文档存放目录：

```
docs/
```

---

# 11. 代码生成原则

当 AI 生成代码时，应遵守：

* 使用 Vue3 Composition API
* 使用 `<script setup>` 语法
* 使用 Element Plus 组件
* 使用 Less 样式，必须加 `scoped`
* 遵循 Element Plus 设计规范

---

# 12. 修改代码原则

修改已有代码时：

* 不破坏原有功能
* 不改变已有接口结构
* 不影响其他模块

若修改影响较大，应先提出方案。

---

# 13. 执行计划文档维护

## 执行计划文档

在开发过程中，AI 必须维护执行计划文档：

```
docs/实施计划.md
```

### 文档内容

执行计划文档应包含：

* 项目背景与目标
* 功能模块划分
* 开发阶段规划
* 每个阶段的具体任务清单
* 任务优先级与依赖关系
* 预计时间估算
* 当前进度状态

### 更新时机

AI 必须在以下情况下更新执行计划：

* 任务开始前：记录计划要做的内容
* 任务完成后：标记完成状态，记录实际结果
* 需求变更时：调整计划以反映新的需求
* 遇到阻塞时：记录阻塞原因和待解决问题

### 文档格式

使用 Markdown 格式，结构清晰，便于阅读和维护。

---

# 14. 测试用例文档维护

## 测试用例文档

在开发过程中，AI 必须维护测试用例文档：

```
docs/测试用例.md
```

### 文档内容

测试用例文档应包含：

* 功能测试用例
* 边界条件测试
* 异常场景测试
* 交互流程测试
* 页面布局测试
* 兼容性测试要点
* 测试数据准备

### 更新时机

AI 必须在以下情况下更新测试用例：

* 新增功能时：补充对应的测试用例
* 修改功能时：更新受影响的测试用例
* 发现 Bug 时：记录 Bug 场景及修复后的验证点
* 完成开发后：整理完整的测试清单

### 验证要求

在标记任务完成前，AI 必须：

* 对照测试用例进行自测
* 确保核心功能正常
* 确保主要交互流程通畅

---

# 15. 项目规范 Skill

## Skill 文件位置

AI 必须维护项目规范 Skill：

```
.claude/skills/项目规范.md
```

### Skill 内容

该 Skill 用于总结和记录：

* 对话过程中用户提出的规范要求
* UI 设计偏好和风格约定
* 交互方式的习惯和偏好
* 代码组织方式的偏好
* 特殊业务逻辑处理方式
* 其他项目中需要持续遵循的约定

### 记录时机

AI 必须在以下情况下更新项目规范 Skill：

* 用户明确提出规范要求时
* 用户纠正 AI 的实现方式时
* 用户表达对某种交互或展示方式的偏好时
* 项目开发过程中形成的约定俗成规则

### 使用方式

在开始新功能开发或页面修改前，AI 必须：

1. 调用 `Skill` 工具读取项目规范
2. 遵循规范中的约定进行开发
3. 确保不遗忘用户之前强调过的要求

### Skill 格式

```yaml
---
name: 项目规范
description: 记录项目开发过程中的规范要求、用户偏好和约定
trigger: 新增页面或功能前必须调用
---

## UI 规范
...

## 交互规范
...

## 代码规范
...
```

# 16. 发布测试环境 Skill

## Skill 文件位置

```
.claude/skills/发布测试环境/SKILL.md
```

### 记录时机

当用户输入包含"发布测试"、"打包测试"、"build test"、"deploy test"、"发布到测试环境"等关键词时触发
