rui-docs/AGENTS.md

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 组件规范

文件结构

<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 服务层规范

// 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 请求工具封装

// 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）

// 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/ 目录

<!-- 推荐：原子化 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 环境变量

# .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 代理配置

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

---

七、性能优化

7.1 代码分割

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

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

7.2 资源优化

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

---

八、测试规范

8.1 单元测试

# 待配置 Vitest

8.2 E2E 测试

# 待配置 Playwright

---

九、OpenCode 使用规范

9.1 启动方式

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
• 后端项目规范
• 跨团队协作规范
• OpenCode 操作指南

---

十一、附录

11.1 常用命令

# 安装依赖
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。