meowrain
40b2ae3126
- 新增 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>
112 lines
4.6 KiB
Markdown
112 lines
4.6 KiB
Markdown
# CLAUDE.md
|
|
|
|
## 项目简介 (Project Overview)
|
|
|
|
这是一个基于 **Vue 3** + **TypeScript** + **Vite** 的 AI 在线判题 (Online Judge) 平台前端项目。
|
|
项目采用 **Bun** 作为包管理器，集成 **Arco Design** UI 组件库，实现了完整的用户认证、权限管理和 AI 对话功能。
|
|
|
|
## 技术栈 (Tech Stack)
|
|
|
|
- **运行时/包管理**: [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
|
|
|
|
## 开发常用命令 (Development Commands)
|
|
|
|
本项目使用 **Bun** 进行管理，请确保已安装 Bun。
|
|
|
|
- **安装依赖**: `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`
|
|
|
|
## 项目结构 (Project Structure)
|
|
|
|
```text
|
|
src/
|
|
├── 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 无权限页
|
|
```
|
|
|
|
## 核心功能模块 (Core Features)
|
|
|
|
### 1. 认证与用户管理 (Authentication)
|
|
- **实现位置**: `src/store/user.ts`, `src/api/auth/`
|
|
- **功能**:
|
|
- 用户登录/注册
|
|
- Token 管理 (Access Token + Refresh Token)
|
|
- 登录状态持久化 (Local Storage)
|
|
- 自动获取当前登录用户信息
|
|
|
|
### 2. 权限控制 (Access Control / RBAC)
|
|
- **实现位置**: `src/access/`, `src/router/index.ts`
|
|
- **机制**:
|
|
- 定义了三种权限等级: `NOT_LOGIN`, `USER`, `ADMIN`
|
|
- 路由配置中通过 `meta.access` 指定所需权限
|
|
- 全局路由守卫 (`beforeEach`) 自动拦截未授权访问
|
|
- `checkAccess` 函数用于组件内的细粒度权限判断 (如菜单显隐)
|
|
|
|
### 3. 网络请求 (Networking)
|
|
- **实现位置**: `src/plugins/axios.ts`
|
|
- **特性**:
|
|
- 全局拦截器自动附加 `Bearer Token`
|
|
- 统一的错误处理与提示
|
|
- 开发环境 `/api` 代理配置 (见 `vite.config.ts`)
|
|
|
|
### 4. AI 对话 (AI Chat)
|
|
- **实现位置**: `src/views/ai/AiChatView.vue`, `src/api/aiChat.ts`
|
|
- **功能**:
|
|
- 提供与 AI 模型交互的聊天界面
|
|
- 支持发送消息并接收流式/普通响应
|
|
|
|
## 环境配置 (Configuration)
|
|
- `.env.dev`: 开发环境配置
|
|
- `.env.prod`: 生产环境配置
|
|
- `.env.test`: 测试环境配置
|
|
- `vite.config.ts`: Vite 构建配置，包含别名 (`@` -> `src`) 和代理设置
|