# rui-frontend AGENTS.md

> **睿核科技前端项目** — Vue 3 + TypeScript 前端工程  
> **版本**: v1.0  
> **更新日期**: 2026-06-04

---

## 一、项目概览

### 1.1 项目信息

| 属性 | 内容 |
|------|------|
| **项目名称** | rui-frontend |
| **项目类型** | Vue 3 前端工程（多项目管理）|
| **仓库地址** | https://gitee.com/rui/rui-frontend |
| **包管理器** | pnpm |
| **构建工具** | Vite |

### 1.2 仓库结构

```
rui-frontend/
├── admin-ui/              # 管理后台系统
│   ├── src/
│   │   ├── api/           # API 接口
│   │   ├── assets/        # 静态资源
│   │   ├── components/    # 公共组件
│   │   ├── composables/   # 组合式函数
│   │   ├── layouts/       # 布局组件
│   │   ├── locales/       # 国际化
│   │   ├── router/        # 路由配置
│   │   ├── service/       # 服务层（API 调用）
│   │   ├── stores/        # Pinia 状态管理
│   │   ├── styles/        # 全局样式
│   │   ├── types/         # 类型定义
│   │   ├── utils/         # 工具函数
│   │   └── views/         # 页面视图
│   ├── package.json
│   └── vite.config.ts
│
├── cashier-mobile/        # 收银系统移动端（待开发）
├── customer-mobile/       # 收银系统顾客端（待开发）
├── package.json           # 根 package.json
├── pnpm-workspace.yaml    # pnpm 工作区配置
└── README.md              # 项目说明
```

### 1.3 技术栈

| 组件 | 版本 | 说明 |
|------|------|------|
| Vue | 3.5+ | 前端框架 |
| TypeScript | 5.4+ | 类型系统 |
| Vite | 5.x | 构建工具 |
| Element Plus | 2.9+ | UI 组件库（admin-ui）|
| Pinia | 2.2+ | 状态管理 |
| Vue Router | 4.4+ | 路由管理 |
| Axios | 1.7+ | HTTP 客户端 |
| pnpm | 8.x | 包管理器 |

---

## 二、编码规范

### 2.1 命名规范

| 类型 | 规范 | 示例 |
|------|------|------|
| **组件文件** | PascalCase | `UserForm.vue`, `OrderList.vue` |
| **组合式函数** | camelCase, use 前缀 | `useUser.ts`, `usePermission.ts` |
| **工具函数** | camelCase | `formatDate.ts`, `deepClone.ts` |
| **常量** | UPPER_SNAKE_CASE | `API_BASE_URL`, `DEFAULT_PAGE_SIZE` |
| **类型定义** | PascalCase, 后缀 Type | `UserType`, `OrderFormType` |
| **接口定义** | PascalCase, 前缀 I | `IUser`, `IOrder` |
| **枚举** | PascalCase, 后缀 Enum | `StatusEnum`, `GenderEnum` |

### 2.2 Vue 组件规范

#### 文件结构

```vue
<script setup lang="ts">
// 1. 类型导入
import type { UserType } from '@/types'

// 2. Vue 核心导入
import { ref, computed, onMounted } from 'vue'

// 3. 第三方库
import { ElMessage } from 'element-plus'

// 4. 本地模块
import { useUserStore } from '@/stores/user'
import { formatDate } from '@/utils/date'

// 5. 组合式函数
const userStore = useUserStore()

// 6. 类型定义
interface Props {
  userId: number
}

// 7.  Props & Emits
const props = defineProps<Props>()
const emit = defineEmits<{
  submit: [data: UserType]
}>()

// 8. 响应式数据
const userList = ref<UserType[]>([])
const loading = ref(false)

// 9. 计算属性
const userCount = computed(() => userList.value.length)

// 10. 方法
async function fetchUserList() {
  loading.value = true
  try {
    // API 调用
  } catch (error) {
    ElMessage.error('获取用户列表失败')
  } finally {
    loading.value = false
  }
}

// 11. 生命周期
onMounted(() => {
  fetchUserList()
})
</script>

<template>
  <div class="user-list">
    <!-- 模板内容 -->
  </div>
</template>

<style scoped lang="scss">
.user-list {
  // 样式
}
</style>
```

#### 组件编写原则

- **使用 `<script setup>`**：简洁、类型友好
- **使用 TypeScript**：所有组件必须 `lang="ts"`
- ** Props 必须定义类型**：使用 `defineProps<Props>()`
- **Emit 必须定义类型**：使用 `defineEmits<{}>()`
- **避免直接使用 any**：必须定义类型

### 2.3 API 服务层规范

```typescript
// service/userService.ts
import request from '@/utils/request'
import type { UserType, PageResult } from '@/types'

export const UserService = {
  // 查询列表
  getList(params: PageParams) {
    return request.get<PageResult<UserType>>('/user/admin/list', { params })
  },

  // 查询详情
  getById(id: number) {
    return request.get<UserType>(`/user/admin/${id}`)
  },

  // 新增
  create(data: UserFormType) {
    return request.post('/user/admin', data)
  },

  // 修改
  update(id: number, data: UserFormType) {
    return request.put(`/user/admin/${id}`, data)
  },

  // 删除
  delete(id: number) {
    return request.delete(`/user/admin/${id}`)
  }
}
```

**原则**：
- 使用对象封装相关 API
- 返回类型必须明确
- 统一错误处理在 request 拦截器中

### 2.4 请求工具封装

```typescript
// utils/request.ts
import axios from 'axios'
import { ElMessage } from 'element-plus'

const request = axios.create({
  baseURL: import.meta.env.VITE_API_BASE_URL,
  timeout: 10000
})

// 请求拦截器
request.interceptors.request.use(
  (config) => {
    const token = localStorage.getItem('token')
    if (token) {
      config.headers.Authorization = `Bearer ${token}`
    }
    return config
  }
)

// 响应拦截器
request.interceptors.response.use(
  (response) => {
    const { code, msg, data } = response.data
    if (code === 200) {
      return data
    }
    ElMessage.error(msg || '请求失败')
    return Promise.reject(new Error(msg))
  },
  (error) => {
    ElMessage.error(error.message || '网络错误')
    return Promise.reject(error)
  }
)

export default request
```

### 2.5 状态管理（Pinia）

```typescript
// stores/user.ts
import { defineStore } from 'pinia'
import { ref, computed } from 'vue'
import type { UserType } from '@/types'

export const useUserStore = defineStore('user', () => {
  // State
  const userInfo = ref<UserType | null>(null)
  const token = ref('')

  // Getters
  const isLoggedIn = computed(() => !!token.value)

  // Actions
  function setUserInfo(user: UserType) {
    userInfo.value = user
  }

  function logout() {
    userInfo.value = null
    token.value = ''
  }

  return {
    userInfo,
    token,
    isLoggedIn,
    setUserInfo,
    logout
  }
})
```

**原则**：
- 使用 Setup Store 风格（函数式）
- State 使用 `ref()`
- Getters 使用 `computed()`
- Actions 使用普通函数

### 2.6 样式规范

- 使用 **UnoCSS** 原子化 CSS（已配置）
- 复杂样式使用 **SCSS**
- 组件样式使用 `<style scoped>`
- 全局样式放在 `styles/` 目录

```vue
<!-- 推荐：原子化 CSS -->
<template>
  <div class="flex items-center justify-between p-4 bg-white rounded">
    <span class="text-lg font-bold">标题</span>
    <el-button type="primary">按钮</el-button>
  </div>
</template>

<!-- 复杂组件使用 SCSS -->
<style scoped lang="scss">
.user-form {
  &__header {
    @apply flex items-center justify-between;
    border-bottom: 1px solid #eee;
  }
}
</style>
```

---

## 三、目录规范

### 3.1 新增页面步骤

1. 在 `views/` 下创建目录和文件
2. 在 `router/` 下添加路由配置
3. 在 `service/` 下添加 API（如需要）
4. 在 `types/` 下添加类型（如需要）

### 3.2 组件分类

| 位置 | 用途 | 示例 |
|------|------|------|
| `components/common/` | 全局通用组件 | `RuiTable.vue`, `IconPicker.vue` |
| `views/{module}/` | 页面级组件 | `views/user/Index.vue` |
| `views/{module}/components/` | 页面私有组件 | `views/user/components/UserForm.vue` |

---

## 四、开发流程

### 4.1 新增功能流程

```
1. 确认后端接口已就绪（Swagger 文档）
2. 创建类型定义（types/）
3. 创建 API 服务（service/）
4. 创建页面组件（views/）
5. 配置路由（router/）
6. 联调测试
7. 提交代码
```

### 4.2 与后端协作

1. **需要新接口**：
   - 在 spring-ai 仓库创建 `[API-REQ]` Issue
   - 等待后端实现并回复 Swagger 地址
   - 根据 Swagger 开发前端

2. **接口变更**：
   - 关注后端 Issue 更新
   - 及时更新前端 service/

---

## 五、Git 提交规范

### 5.1 提交格式

```
type(scope): 中文描述

示例：
feat(user): 添加用户列表页面
fix(order): 修复订单金额显示错误
docs(readme): 更新项目说明
style(css): 优化表格样式
```

### 5.2 Type 类型

| 类型 | 说明 |
|------|------|
| `feat` | 新功能 |
| `fix` | 修复 Bug |
| `docs` | 文档更新 |
| `style` | 代码格式（不影响功能）|
| `refactor` | 重构 |
| `perf` | 性能优化 |
| `test` | 测试相关 |
| `chore` | 构建/工具链 |

### 5.3 Scope 范围

| Scope | 说明 |
|-------|------|
| `admin-ui` | 管理后台 |
| `cashier` | 收银系统 |
| `common` | 公共代码 |
| `deps` | 依赖更新 |

---

## 六、环境配置

### 6.1 环境变量

```bash
# .env.development
VITE_API_BASE_URL=http://localhost:8080
VITE_APP_TITLE=睿核管理系统

# .env.production
VITE_API_BASE_URL=https://api.vifo.cc
VITE_APP_TITLE=睿核管理系统
```

### 6.2 代理配置

```typescript
// vite.config.ts
server: {
  proxy: {
    '/api': {
      target: 'http://localhost:8080',
      changeOrigin: true
    }
  }
}
```

---

## 七、性能优化

### 7.1 代码分割

```typescript
// 路由懒加载
const UserList = () => import('@/views/user/Index.vue')

// 组件懒加载
const Dialog = defineAsyncComponent(() => import('./Dialog.vue'))
```

### 7.2 资源优化

- 图片使用 WebP 格式
- 大组件使用异步加载
- 使用 CDN 加载第三方库（生产环境）

---

## 八、测试规范

### 8.1 单元测试

```bash
# 待配置 Vitest
```

### 8.2 E2E 测试

```bash
# 待配置 Playwright
```

---

## 九、OpenCode 使用规范

### 9.1 启动方式

```bash
cd /Users/zhangsheng/rhkj/rui-frontend
opencode
```

### 9.2 启动提示词

```
你现在进入【前端开发模式】。

工作目录：/Users/zhangsheng/rhkj/rui-frontend
技术栈：Vue 3、TypeScript、Element Plus、Vite、pnpm
规则：
1. 只能修改前端项目目录下的代码
2. 需要后端接口时，提醒用户创建 Gitee Issue
3. 遵循本文档的编码规范
4. 使用 pnpm，不要混用 npm/yarn

当前任务：【描述具体任务】
```

### 9.3 禁止事项

- ❌ 修改 backend/ 或 app/ 目录下的代码
- ❌ 使用 npm/yarn（必须使用 pnpm）
- ❌ 提交 node_modules/ 到 Git
- ❌ 在代码中写死 API 地址（使用环境变量）

---

## 十、相关文档

- [项目 README](../README.md)
- [后端项目规范](../../spring-ai/AGENTS.md)
- [跨团队协作规范](../../spring-ai/docs/cross-team-workflow.md)
- [OpenCode 操作指南](../../spring-ai/docs/opencode-workflow.md)

---

## 十一、附录

### 11.1 常用命令

```bash
# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev:admin

# 构建
pnpm build:admin

# 类型检查
pnpm type-check

# 代码检查
pnpm lint

# 安装子项目依赖
cd admin-ui && pnpm install
```

### 11.2 错误码对照

| 错误码 | 说明 |
|--------|------|
| 200 | 成功 |
| 400 | 请求参数错误 |
| 401 | 未授权 |
| 403 | 无权限 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |

---

> **提示**：本文档是活文档，根据项目发展持续更新。如有建议请提交 PR。