feat(claude): 添加 Vue3 前端工程师 Agent 并优化项目文档

- 新增 vue3-frontend-engineer.md 专用 Agent，用于处理 Vue 3 相关开发任务 - 重构 CLAUDE.md 文档，改为中英文双语结构 - 优化项目文档结构，新增核心功能模块详细说明 - 完善技术栈、开发命令和项目结构的文档描述 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2026-01-07 20:31:46 +08:00
parent fad13e00e5
commit 40b2ae3126
2 changed files with 210 additions and 143 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,161 +1,111 @@
 # CLAUDE.md

-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+## 项目简介 (Project Overview)

-## Project Overview
+这是一个基于 **Vue 3** + **TypeScript** + **Vite** 的 AI 在线判题 (Online Judge) 平台前端项目。
+项目采用 **Bun** 作为包管理器，集成 **Arco Design** UI 组件库，实现了完整的用户认证、权限管理和 AI 对话功能。

-This is a Vue 3 + TypeScript frontend application for an AI Online Judge (OJ) platform called "AI OJ By MeowRain". The application uses modern Vue 3 patterns with Composition API and includes a comprehensive authentication and permission system.
+## 技术栈 (Tech Stack)

-## Development Commands
+- **运行时/包管理**: [Bun](https://bun.sh/)
+- **核心框架**: Vue 3 (Composition API + `<script setup>`)
+- **构建工具**: Vite
+- **语言**: TypeScript
+- **UI 组件库**: Arco Design Vue (`@arco-design/web-vue`)
+- **路由**: Vue Router 4 (Hash 模式)
+- **状态管理**: Pinia (配合 `pinia-plugin-persistedstate` 实现持久化)
+- **HTTP 客户端**: Axios
+- **CSS 预处理**: SCSS

-### Environment Setup
+## 开发常用命令 (Development Commands)

- **Package Manager**: Uses `bun` (evidenced by bun.lock file)
- **Development Server**: `npm run dev` (runs on port 3000, opens browser automatically)
- **Production Development**: `npm run dev:prod` (development mode with production environment config)
+本项目使用 **Bun** 进行管理，请确保已安装 Bun。

-### Building
+- **安装依赖**: `bun install`
+- **启动开发服务器**: `bun run dev` (默认端口 3000, 代理 `/api` 到 `localhost:8085`)
+- **生产环境预览**: `bun run dev:prod`
+- **构建生产版本**: `bun run build:prod`
+- **构建开发版本**: `bun run build`
+- **预览构建产物**: `bun run preview`
+- **代码检查 (Lint)**: `bun run lint`
+- **类型检查**: `bun run type-check`

- **Development Build**: `npm run build` (builds with development environment)
- **Production Build**: `npm run build:prod` (builds with production environment)
- **Preview**: `npm run preview` (preview built application)
+## 项目结构 (Project Structure)

-### Code Quality
-
- **Type Checking**: `npm run type-check` (Vue TypeScript compiler check without emit)
- **Linting**: `npm run lint` (ESLint for .ts and .vue files)
- **Type Generation**: `npm run build:types` (generates TypeScript declaration files)
-
-### Environment Configuration
-
-The application uses environment-specific configuration files:
-
- `.env.dev` - Development environment (API: <http://localhost:8080>)
- `.env.prod` - Production environment (API: <http://localhost:8080>)
- `.env.test` - Test environment
-
-## Architecture Overview
-
-### Technology Stack
-
- **Frontend**: Vue 3 with Composition API (`<script setup>`)
- **Language**: TypeScript with strict type checking
- **Build Tool**: Vite (using rolldown-vite@7.2.2)
- **UI Framework**: Arco Design Vue
- **State Management**: Pinia stores
- **Routing**: Vue Router 4 with hash-based routing
- **HTTP Client**: Axios with interceptors
- **CSS**: SCSS support
-
-### Project Structure
-
-你可以使用 命令 tree src /F  在项目根目录下生成项目结构图，以下是主要目录说明：
-
-```
+```text
 src/
-├── access/              # Permission system core
-├── api/                # API service layer (currently empty)
-├── components/         # Reusable Vue components
-├── config/             # Environment configuration
-├── layouts/            # Application layout components
-├── plugins/            # Vue plugins (Axios configuration)
-├── router/             # Route definitions and configuration
-├── store/              # Pinia state management
-├── types/              # Global TypeScript type definitions
-├── utils/              # Utility functions
-└── views/              # Page components
+├── access/              # 权限控制核心逻辑
+│   ├── accessEnum.ts    # 权限枚举 (NOT_LOGIN, USER, ADMIN)
+│   ├── checkAccess.ts   # 权限校验函数
+│   └── index.ts         # 导出入口
+├── api/                 # 后端 API 接口定义
+│   ├── auth/            # 认证相关接口 (登录, 注册, Token)
+│   ├── aiChat.ts        # AI 对话接口
+│   ├── index.ts         # API 统一导出
+│   └── response.ts      # 响应数据类型定义
+├── assets/              # 静态资源 (Logo, 图片)
+├── components/          # 公共组件
+│   └── GlobalHeader.vue # 全局顶部导航栏
+├── config/              # 全局配置
+│   └── index.ts         # 环境配置导出
+├── layouts/             # 页面布局组件
+│   └── BasicLayout.vue  # 基础布局 (包含 Header 和 Content)
+├── plugins/             # 第三方插件配置
+│   └── axios.ts         # Axios 实例配置 (拦截器, 错误处理)
+├── router/              # 路由配置
+│   ├── index.ts         # 路由守卫 (权限拦截)
+│   └── router.ts        # 路由表定义
+├── store/               # Pinia 状态管理
+│   ├── user.ts          # 用户状态 (登录信息, Token)
+│   └── types.d.ts       # Store 类型定义
+├── types/               # 全局 TypeScript 类型
+├── utils/               # 工具函数
+│   ├── requets.ts       # 请求相关工具
+│   └── token.ts         # Token 存储与获取工具
+└── views/               # 页面视图
+    ├── ai/              # AI 相关页面
+    │   └── AiChatView.vue # AI 对话界面
+    ├── user/            # 用户相关页面
+    │   ├── UserLoginView.vue    # 登录页
+    │   └── UserRegisterView.vue # 注册页
+    ├── HomeView.vue     # 首页
+    ├── AboutView.vue    # 关于页
+    └── NoAuthView.vue   # 403 无权限页
 ```

-### Authentication & Permission System
+## 核心功能模块 (Core Features)

-**Access Levels**: Role-based access control with three levels:
+### 1. 认证与用户管理 (Authentication)
+- **实现位置**: `src/store/user.ts`, `src/api/auth/`
+- **功能**:
+  - 用户登录/注册
+  - Token 管理 (Access Token + Refresh Token)
+  - 登录状态持久化 (Local Storage)
+  - 自动获取当前登录用户信息

- `NOT_LOGIN`: Public access (default)
- `USER`: Logged-in users
- `ADMIN`: Administrators
+### 2. 权限控制 (Access Control / RBAC)
+- **实现位置**: `src/access/`, `src/router/index.ts`
+- **机制**:
+  - 定义了三种权限等级: `NOT_LOGIN`, `USER`, `ADMIN`
+  - 路由配置中通过 `meta.access` 指定所需权限
+  - 全局路由守卫 (`beforeEach`) 自动拦截未授权访问
+  - `checkAccess` 函数用于组件内的细粒度权限判断 (如菜单显隐)

-**Permission Implementation**:
+### 3. 网络请求 (Networking)
+- **实现位置**: `src/plugins/axios.ts`
+- **特性**:
+  - 全局拦截器自动附加 `Bearer Token`
+  - 统一的错误处理与提示
+  - 开发环境 `/api` 代理配置 (见 `vite.config.ts`)

- Routes include `meta.access` property defining required permission level
- `checkAccess.ts` handles permission validation logic
- Navigation menu filters routes based on user permissions
- Axios interceptors automatically attach Bearer tokens to API requests
+### 4. AI 对话 (AI Chat)
+- **实现位置**: `src/views/ai/AiChatView.vue`, `src/api/aiChat.ts`
+- **功能**:
+  - 提供与 AI 模型交互的聊天界面
+  - 支持发送消息并接收流式/普通响应

-**User Store** (`src/store/user.ts`):
-
- Manages authentication state using Pinia
- Stores user login information and tokens
- Currently uses mock data with placeholder `getLoginUser()` method
-
-### Routing Architecture
-
- **Hash-based routing**: Uses `createWebHashHistory()` for compatibility
- **Route metadata**: Each route includes `hideInMenu` and `access` properties
- **Permission-based navigation**: Menu items filtered by user access level
- **Route guards**: Permission checks before route access
-
-### HTTP Client Configuration
-
- **Base URL**: Configured via environment variables (`VITE_API_URL`)
- **Interceptors**: Automatic token attachment and response handling
- **Error Handling**: Centralized error handling in `src/plugins/axios.ts`
-
-## Key Patterns and Conventions
-
-### Vue 3 Patterns
-
- Uses `<script setup>` syntax for all components
- Composition API with reactive refs and computed properties
- TypeScript integration with proper type definitions
-
-### State Management
-
- Pinia stores for centralized state management
- Type-safe store definitions with TypeScript interfaces
- Reactive state updates with proper reactivity
-
-### Styling
-
- Arco Design Vue component library for consistent UI
- SCSS support for custom styling
- Global CSS in `src/style.css`
-
-### Path Aliases
-
- `@` alias points to `src/` directory for clean imports
- Configured in both Vite config and TypeScript config
-
-## Development Notes
-
-### Current Implementation Status
-
- ✅ Basic Vue 3 + TypeScript setup
- ✅ Arco Design UI integration
- ✅ Permission-based routing system
- ✅ Authentication state management
- ✅ Environment configuration
- ✅ HTTP client with interceptors
- ⚠️ API service layer is empty
- ⚠️ User authentication uses mock data
- ❌ No backend integration yet
- ❌ No testing framework configured
-
-### Known Issues
-
- Bug in `src/access/checkAccess.ts:24` - should return `true` for USER access
- `getLoginUser()` method in user store is not implemented
- No actual API endpoints implemented in `src/api/`
-
-### Development Workflow
-
-1. Use `npm run dev` for development server
-2. Environment variables are loaded automatically based on mode
-3. TypeScript strict mode is enabled
-4. ESLint configuration for code quality
-
-### Backend Integration
-
- Configured to connect to `localhost:8080` for API calls
- Uses Bearer token authentication
- Expected to work with a separate backend service
- OpenAPI codegen dependency available for API client generation
+## 环境配置 (Configuration)
+- `.env.dev`: 开发环境配置
+- `.env.prod`: 生产环境配置
+- `.env.test`: 测试环境配置
+- `vite.config.ts`: Vite 构建配置，包含别名 (`@` -> `src`) 和代理设置