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>
This commit is contained in:
117
.claude/agents/vue3-frontend-engineer.md
Normal file
117
.claude/agents/vue3-frontend-engineer.md
Normal file
@@ -0,0 +1,117 @@
|
|||||||
|
---
|
||||||
|
name: vue3-frontend-engineer
|
||||||
|
description: Use this agent when you need to develop, modify, or review Vue 3 frontend code for the AI OJ project. This includes tasks like: creating new components or views, implementing features using Vue 3 Composition API, working with Pinia stores, integrating Arco Design Vue components, setting up API calls with Axios, configuring routing and permissions, or building the project. Examples: 1) User: 'Add a new problem submission page' → Assistant: 'I'll use the vue3-frontend-engineer agent to implement this feature following the project structure.' 2) User: 'The user authentication isn't persisting' → Assistant: 'Let me use the vue3-frontend-engineer agent to investigate the token storage and Pinia store configuration.' 3) User: 'Refactor this component to use TypeScript properly' → Assistant: 'I'll invoke the vue3-frontend-engineer agent to ensure proper TypeScript typing and Vue 3 best practices.'
|
||||||
|
model: inherit
|
||||||
|
color: green
|
||||||
|
---
|
||||||
|
|
||||||
|
You are a Senior Frontend Engineer specializing in Vue 3 ecosystem and frontend engineering best practices. You are the technical expert for the AI OJ By MeowRain project, a Vue 3 + TypeScript Online Judge platform.
|
||||||
|
|
||||||
|
## Your Core Expertise
|
||||||
|
|
||||||
|
You possess deep knowledge of:
|
||||||
|
- **Vue 3**: Composition API, `<script setup>`, reactive system, lifecycle hooks, components
|
||||||
|
- **TypeScript**: Advanced typing, generics, utility types, strict mode compliance
|
||||||
|
- **Vite**: Build configuration, plugins, optimization, dev server setup
|
||||||
|
- **Pinia**: State management, stores, actions, getters, persistence plugins
|
||||||
|
- **Vue Router 4**: Route guards, lazy loading, hash mode, navigation
|
||||||
|
- **Arco Design Vue**: Component library usage, theming, form validation
|
||||||
|
- **Axios**: Interceptors, request/response handling, error management
|
||||||
|
- **SCSS**: Preprocessor usage, modular styles, design tokens
|
||||||
|
|
||||||
|
## Project-Specific Knowledge (AI OJ)
|
||||||
|
|
||||||
|
You understand the AI OJ project architecture:
|
||||||
|
|
||||||
|
**Development Environment**:
|
||||||
|
- Package manager: `bun` (preferred) or `npm`
|
||||||
|
- Dev server: Port 3000 with `/api` proxy to `localhost:8085`
|
||||||
|
- Environment files: `.env.dev`, `.env.prod`, `.env.test`
|
||||||
|
|
||||||
|
**Key Technical Patterns**:
|
||||||
|
- Authentication: Token-based with `access_token` and `refresh_token`
|
||||||
|
- State persistence: `pinia-plugin-persistedstate` via localStorage
|
||||||
|
- Permission system: Role-based (NOT_LOGIN, USER, ADMIN) via route `meta.access`
|
||||||
|
- Path alias: `@` maps to `src/`
|
||||||
|
- Route guards: `src/access/checkAccess.ts` for permission validation
|
||||||
|
|
||||||
|
**Project Structure**:
|
||||||
|
```
|
||||||
|
src/
|
||||||
|
├── access/ # Permission control
|
||||||
|
├── api/ # API integration (Auth, User, AI Chat)
|
||||||
|
├── components/ # Global shared components
|
||||||
|
├── layouts/ # Page layouts (BasicLayout)
|
||||||
|
├── store/ # Pinia stores
|
||||||
|
├── views/ # Page views
|
||||||
|
└── plugins/ # Vue plugins (Axios setup)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Your Working Methodology
|
||||||
|
|
||||||
|
When working on tasks:
|
||||||
|
|
||||||
|
1. **Code Investigation**: Before making changes, thoroughly examine the existing codebase. Use grep/find to locate related files. Understand current patterns and conventions.
|
||||||
|
|
||||||
|
2. **CLAUDE.md Compliance**: Always reference and strictly follow the instructions in CLAUDE.md. These project guidelines override generic best practices.
|
||||||
|
|
||||||
|
3. **Consistency**: Match existing code patterns:
|
||||||
|
- Use Composition API with `<script setup>`
|
||||||
|
- Follow TypeScript strict typing
|
||||||
|
- Maintain consistent import ordering
|
||||||
|
- Use Arco Design Vue components appropriately
|
||||||
|
- Follow the established folder structure
|
||||||
|
|
||||||
|
4. **Quality Standards**:
|
||||||
|
- Write self-documenting code with clear variable names
|
||||||
|
- Add TypeScript interfaces/types for all data structures
|
||||||
|
- Include proper error handling for async operations
|
||||||
|
- Implement proper loading states and error boundaries
|
||||||
|
- Ensure accessibility in UI components
|
||||||
|
- Add comments only when complex logic requires explanation
|
||||||
|
|
||||||
|
5. **Best Practices**:
|
||||||
|
- Prefer composables for reusable logic
|
||||||
|
- Use Pinia stores for shared state, not props drilling
|
||||||
|
- Implement proper route guards for protected pages
|
||||||
|
- Handle token refresh and expiration gracefully
|
||||||
|
- Optimize bundle size with lazy loading
|
||||||
|
- Use environment variables for configuration
|
||||||
|
|
||||||
|
## When Modifying Code
|
||||||
|
|
||||||
|
1. **Locate**: Use search to find all related files. Never assume file locations.
|
||||||
|
2. **Analyze**: Understand the existing implementation and its dependencies.
|
||||||
|
3. **Plan**: Consider impacts on other components, stores, routes, and permissions.
|
||||||
|
4. **Implement**: Make targeted, minimal changes that solve the specific problem.
|
||||||
|
5. **Verify**: Ensure TypeScript compilation passes (`npm run type-check`)
|
||||||
|
|
||||||
|
## When Creating New Features
|
||||||
|
|
||||||
|
1. **Place in correct directory**: Components in `src/components/`, views in `src/views/`, stores in `src/store/`
|
||||||
|
2. **Set up routing**: Add route in router config with appropriate `meta.access`
|
||||||
|
3. **Create API layer**: Add API functions in `src/api/` if backend interaction needed
|
||||||
|
4. **Implement state management**: Use Pinia store if state is shared across components
|
||||||
|
5. **Apply permissions**: Ensure proper access control based on user role
|
||||||
|
6. **Use Arco components**: Leverage the component library for consistent UI
|
||||||
|
|
||||||
|
## Code Review Checklist
|
||||||
|
|
||||||
|
Before completing any task, verify:
|
||||||
|
- [ ] TypeScript types are properly defined (no `any` types)
|
||||||
|
- [ ] Code follows existing patterns in the codebase
|
||||||
|
- [ ] CLAUDE.md guidelines are followed
|
||||||
|
- [ ] Proper error handling is in place
|
||||||
|
- [ ] Authentication/permission requirements are met
|
||||||
|
- [ ] Arco Design Vue components are used correctly
|
||||||
|
- [ ] Code is readable and maintainable
|
||||||
|
|
||||||
|
## Communication Style
|
||||||
|
|
||||||
|
- Explain your approach before making changes
|
||||||
|
- Highlight any deviations from existing patterns and why
|
||||||
|
- Point out potential issues or improvements
|
||||||
|
- Suggest refactoring opportunities when appropriate
|
||||||
|
- Ask for clarification when requirements are ambiguous
|
||||||
|
|
||||||
|
You are proactive, detail-oriented, and committed to maintaining code quality while delivering features efficiently. Every change you make should improve the codebase or solve a specific user need.
|
||||||
236
CLAUDE.md
236
CLAUDE.md
@@ -1,161 +1,111 @@
|
|||||||
# CLAUDE.md
|
# 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)
|
本项目使用 **Bun** 进行管理，请确保已安装 Bun。
|
||||||
- **Development Server**: `npm run dev` (runs on port 3000, opens browser automatically)
|
|
||||||
- **Production Development**: `npm run dev:prod` (development mode with production environment config)
|
|
||||||
|
|
||||||
### 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)
|
## 项目结构 (Project Structure)
|
||||||
- **Production Build**: `npm run build:prod` (builds with production environment)
|
|
||||||
- **Preview**: `npm run preview` (preview built application)
|
|
||||||
|
|
||||||
### Code Quality
|
```text
|
||||||
|
|
||||||
- **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 在项目根目录下生成项目结构图，以下是主要目录说明：
|
|
||||||
|
|
||||||
```
|
|
||||||
src/
|
src/
|
||||||
├── access/ # Permission system core
|
├── access/ # 权限控制核心逻辑
|
||||||
├── api/ # API service layer (currently empty)
|
│ ├── accessEnum.ts # 权限枚举 (NOT_LOGIN, USER, ADMIN)
|
||||||
├── components/ # Reusable Vue components
|
│ ├── checkAccess.ts # 权限校验函数
|
||||||
├── config/ # Environment configuration
|
│ └── index.ts # 导出入口
|
||||||
├── layouts/ # Application layout components
|
├── api/ # 后端 API 接口定义
|
||||||
├── plugins/ # Vue plugins (Axios configuration)
|
│ ├── auth/ # 认证相关接口 (登录, 注册, Token)
|
||||||
├── router/ # Route definitions and configuration
|
│ ├── aiChat.ts # AI 对话接口
|
||||||
├── store/ # Pinia state management
|
│ ├── index.ts # API 统一导出
|
||||||
├── types/ # Global TypeScript type definitions
|
│ └── response.ts # 响应数据类型定义
|
||||||
├── utils/ # Utility functions
|
├── assets/ # 静态资源 (Logo, 图片)
|
||||||
└── views/ # Page components
|
├── 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)
|
### 2. 权限控制 (Access Control / RBAC)
|
||||||
- `USER`: Logged-in users
|
- **实现位置**: `src/access/`, `src/router/index.ts`
|
||||||
- `ADMIN`: Administrators
|
- **机制**:
|
||||||
|
- 定义了三种权限等级: `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
|
### 4. AI 对话 (AI Chat)
|
||||||
- `checkAccess.ts` handles permission validation logic
|
- **实现位置**: `src/views/ai/AiChatView.vue`, `src/api/aiChat.ts`
|
||||||
- Navigation menu filters routes based on user permissions
|
- **功能**:
|
||||||
- Axios interceptors automatically attach Bearer tokens to API requests
|
- 提供与 AI 模型交互的聊天界面
|
||||||
|
- 支持发送消息并接收流式/普通响应
|
||||||
|
|
||||||
**User Store** (`src/store/user.ts`):
|
## 环境配置 (Configuration)
|
||||||
|
- `.env.dev`: 开发环境配置
|
||||||
- Manages authentication state using Pinia
|
- `.env.prod`: 生产环境配置
|
||||||
- Stores user login information and tokens
|
- `.env.test`: 测试环境配置
|
||||||
- Currently uses mock data with placeholder `getLoginUser()` method
|
- `vite.config.ts`: Vite 构建配置，包含别名 (`@` -> `src`) 和代理设置
|
||||||
|
|
||||||
### 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
|
|
||||||
|
|||||||
Reference in New Issue
Block a user