# CLAUDE.md

## 1. 文档目的

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

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

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

优先级如下：

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

---

# 2. 技术栈

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

## 前端框架

* Vue 3

必须使用 Vue 3 Composition API。

推荐使用：

```vue
<script setup>
```

---

## UI 组件库

* Vant UI 4

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

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

常用组件：

* Button - 按钮
* Cell / CellGroup - 单元格
* List - 列表
* Popup - 弹出层
* Dialog - 对话框
* Tab / Tabs - 标签页
* NavBar - 导航栏
* Icon - 图标
* Toast - 轻提示
* Form / Field - 表单
* Picker - 选择器
* DatePicker - 日期选择器
* PullRefresh - 下拉刷新
* ActionSheet - 动作面板

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

Vant 文档：https://vant-ui.github.io/vant/#/zh-CN

---

## 编程语言

* JavaScript

不使用 TypeScript。

---

## 样式方案

* Less

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

示例：

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

  .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           # 首页
├── UserProfile.vue    # 用户资料页
├── OrderList.vue      # 订单列表页
└── OrderDetail.vue    # 订单详情页
```

### 页面结构

推荐页面结构：

```vue
<template>
  <div class="page-name">
    <van-nav-bar title="页面标题" left-arrow @click-left="onClickLeft" />
    <div class="page-content">
      <!-- 页面内容 -->
    </div>
  </div>
</template>

<script setup>
import { useRouter } from 'vue-router'

const router = useRouter()

const onClickLeft = () => router.back()
</script>

<style lang="less" scoped>
.page-name {
  min-height: 100vh;
  background-color: #f5f5f5;

  .page-content {
    padding: 16px;
  }
}
</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)
  }
}
```

---

# 5. UI 设计与布局规范

## 设计规范

页面布局必须参考 Material Design 3 中的 Layout 规范。

主要遵循以下原则：

### 布局结构

推荐页面结构：

```
NavBar
Content
Bottom Action / Tabbar
```

或

```
Header
Scrollable Content
Floating Action
```

---

### 页面间距

推荐间距体系：

* 8px
* 12px
* 16px
* 24px

默认页面 padding：16px

---

### 内容宽度

页面应采用 **移动端优先布局**。

避免出现：

* PC 管理后台式布局
* 大量表格
* 多栏复杂结构

---

### 卡片式布局

推荐使用 Card / Cell 组合布局。

示例：

```
Card
  Title
  Content
  Actions
```

---

# 6. 主题色规范

项目主色调：

```
#ff5f16
```

AI 在生成 UI 时应遵守：

* 主按钮使用主色
* 重要操作使用主色
* 高亮状态使用主色

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

## 参考图片色调规则

当用户提供参考图片时：

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

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

## 图表规范

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

图表色调要求：

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

---

# 7. Less 样式规范

## 基本规则

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

## 命名规范

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

示例：

```less
.order-list-page {
  min-height: 100vh;
  background-color: #f5f5f5;

  .header {
    display: flex;
    align-items: center;
    padding: 16px;

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

  .content {
    padding: 0 16px;
  }
}
```

## 样式变量

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

```less
<style lang="less" scoped>
@primary-color: #ff5f16;
@border-radius: 8px;

.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 })
}
```

---