From b1dd60ab6ea219ee2023c76324dc92a5cb725a29 Mon Sep 17 00:00:00 2001
From: pigeon <zs@vifo.net>
Date: Thu, 4 Jun 2026 05:28:50 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=E5=89=8D=E7=AB=AF?=
 =?UTF-8?q?=E5=BC=80=E5=8F=91=E8=A7=84=E8=8C=83=E6=96=87=E6=A1=A3=E5=92=8C?=
 =?UTF-8?q?=20OpenCode=20=E9=85=8D=E7=BD=AE?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 创建 AGENTS.md（前端编码规范、开发流程、Git 提交规范）
- 创建 .opencode/workspace/frontend.json（前端工作区配置）
- 更新 .gitignore
---
 .opencode/workspace/frontend.json |  11 +
 AGENTS.md                         | 541 ++++++++++++++++++++++++++++++
 2 files changed, 552 insertions(+)
 create mode 100644 .opencode/workspace/frontend.json
 create mode 100644 AGENTS.md

diff --git a/.opencode/workspace/frontend.json b/.opencode/workspace/frontend.json
new file mode 100644
index 0000000..525d8f5
--- /dev/null
+++ b/.opencode/workspace/frontend.json
@@ -0,0 +1,11 @@
+{
+  "name": "rui-frontend",
+  "description": "睿核科技前端开发会话 - 负责 rui-frontend 目录下的前端代码",
+  "scope": ["admin-ui/**", "cashier-mobile/**", "customer-mobile/**"],
+  "readonly": [],
+  "prompt": "你是 rui 前端开发助手。\n\n## 工作范围\n你只能修改 rui-frontend/ 目录下的前端代码。\n\n## 技术栈\n- Vue 3 + TypeScript\n- Element Plus（admin-ui）\n- Vite\n- pnpm workspace\n\n## 编码规范\n1. 使用 `<script setup lang=\"ts\">`\n2. Props 和 Emit 必须定义类型\n3. API 服务层封装在 service/ 目录\n4. 状态管理使用 Pinia（Setup Store 风格）\n5. 样式使用 UnoCSS + SCSS\n\n## 协作规则\n1. 需要后端接口时，提醒用户创建 Gitee Issue\n2. 不修改后端代码（backend/、app/）\n3. 遵循 AGENTS.md 规范\n\n## 常用命令\n- pnpm dev:admin - 启动管理后台\n- pnpm build:admin - 构建管理后台\n- pnpm install - 安装依赖",
+  "git": {
+    "defaultBranch": "main",
+    "commitMessageFormat": "type(scope): 中文描述"
+  }
+}
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..5e9cc6c
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,541 @@
+# 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。