Quentin
9b0910ccb1
后端 (book_mcp_server.py, 335 行, 15 个 MCP 工具):
- create_book / add_document / mark_html_ready / mark_json_ready / mark_failed
- update_book_status / soft_delete_book / retry_failed
- get_book / list_books / get_document / list_documents / get_document_url
- upload_to_rustfs / health
- 走 JSON-RPC + stateless_http + json_response（前端可直接调）
- launchd 守护 / 6 秒拉起（macOS）
- systemd 守护脚本（Linux/codelab）
存储:
- MongoDB (mongo:8.0 容器) - book/book_document/document_file 三表
- RustFS 对象存储（fs.code-lab.cn/scan/）- book/<id>/docs/<doc_id>/{docx,html,json}
- 幂等设计: zip_sha256 唯一 + (book_id+original_path) 唯一
前端 (Vue 3 + TS + Arco Design):
- 列表页 /book/list - 搜索 + 状态过滤 + 进度
- 详情页 /book/:id - 文档折叠 + 文件下载
- MCP 客户端 src/api/mcp.ts (JSON-RPC over fetch)
部署:
- deploy/install.sh (codelab 一键装 backend + systemd)
- deploy/install-frontend.sh (vite dev / 生产构建)
- docs/deploy.md (运维手册)
测试:
- tests/test_basic.py (sanity 7 项)
- tests/test_e2e.py (完整 e2e: docx→HTML→入库→上传→校验)
213 lines
8.6 KiB
Plaintext
213 lines
8.6 KiB
Plaintext
# Frontend Cursor Rules
|
||
|
||
## 1. 基础规范
|
||
- Vue 3 Composition API (`<script setup>`)
|
||
- TypeScript
|
||
- Arco Design Vue 2.x（组件自动导入）
|
||
|
||
## 2. 目录结构
|
||
- **API (`src/api/`)**: API 接口定义
|
||
- 按功能模块组织文件（如 `user.ts`、`dashboard.ts`）
|
||
- 使用 Axios 进行 HTTP 请求
|
||
- 统一在 `src/api/interceptor.ts` 配置拦截器
|
||
- **组件 (`src/components/`)**: 全局可复用组件
|
||
- 按功能模块组织子目录
|
||
- 全局组件在 `src/components/index.ts` 中注册
|
||
- 使用 Arco Design 组件时无需手动导入（自动导入已配置）
|
||
- 注意：模块专用组件应放在对应模块目录下的 `components/` 文件夹，而非全局 `src/components/`
|
||
- **视图 (`src/views/`)**: 页面级组件
|
||
- 按功能模块组织目录
|
||
- 每个模块包含 `index.vue` 和 `locale/` 目录（国际化文案）
|
||
- 模块专用组件放在模块目录下的 `components/` 文件夹（如 `src/views/User/UserInfo/components/`）
|
||
- **路由 (`src/router/`)**: 路由配置
|
||
- 路由定义在 `router/routes/` 目录，按模块组织
|
||
- 路由守卫在 `router/guard/` 目录
|
||
- **状态管理 (`src/store/`)**: Pinia Store
|
||
- 按模块组织 store（如 `user/`、`app/`）
|
||
- 使用 `defineStore` 定义 store
|
||
- **工具 (`src/utils/`)**: 通用工具函数
|
||
- **Hooks (`src/hooks/`)**: 组合式函数
|
||
- 可复用的 Composition API 逻辑
|
||
|
||
## 2.1. 命名规范（重要）
|
||
- **目录命名**：必须使用**驼峰命名法（PascalCase）**
|
||
- ✅ `UserManage/`、`QuestionBank/`、`PaperManage/`、`UserInfo/`
|
||
- ❌ `user-manage/`、`question-bank/`、`user-info/`
|
||
- **组件文件命名**：必须使用**驼峰命名法（PascalCase）**
|
||
- ✅ `UserList.vue`、`RoleManage.vue`、`MenuManage.vue`、`UserInfoHeader.vue`
|
||
- ❌ `user-list.vue`、`role-manage.vue`、`user-info-header.vue`
|
||
- **独立子页面**：必须单独建立文件夹
|
||
- 如果页面有独立的子页面（如用户详情页），应单独建立文件夹
|
||
- 示例：`User/UserInfo/`、`User/UserSetting/`
|
||
- 每个子页面目录包含 `index.vue` 和可选的 `components/` 文件夹
|
||
|
||
## 2.2. 组件化原则
|
||
- **公共组件**：放在 `src/components/` 目录下
|
||
- 可在多个页面复用的组件
|
||
- **页面私有组件**：放在页面目录下的 `components/` 文件夹
|
||
- 仅当前页面使用的组件
|
||
- 示例：`User/UserInfo/components/UserInfoHeader.vue`
|
||
- **页面组件化**：能够拆成组件的都组件化
|
||
- 将复杂页面拆分为多个小组件
|
||
- 示例：`UserManage/index.vue` 包含 `UserList`、`RoleManage`、`MenuManage` 三个组件
|
||
|
||
## 2.3. 页面结构示例
|
||
```
|
||
views/
|
||
├── User/ # 用户个人信息页面
|
||
│ ├── UserInfo/ # 用户信息子页面（独立文件夹）
|
||
│ │ ├── components/ # 私有组件（仅当前页面用）
|
||
│ │ │ ├── UserInfoHeader.vue
|
||
│ │ │ ├── LatestActivity.vue
|
||
│ │ │ └── MyProject.vue
|
||
│ │ └── index.vue # 详情页主文件
|
||
│ └── UserSetting/ # 用户设置子页面（独立文件夹）
|
||
│ ├── components/
|
||
│ │ ├── UserPanel.vue
|
||
│ │ └── BasicInformation.vue
|
||
│ └── index.vue
|
||
│
|
||
└── UserManage/ # 用户管理页面（管理员功能）
|
||
├── components/ # 组件化（可复用）
|
||
│ ├── UserList.vue # 用户列表组件
|
||
│ ├── RoleManage.vue # 角色管理组件
|
||
│ └── MenuManage.vue # 菜单管理组件
|
||
└── index.vue # 主页面（标签页容器）
|
||
```
|
||
|
||
## 3. 代码风格
|
||
|
||
### 格式化规范（遵循 `.prettierrc.js`）
|
||
- **缩进**: 2 个空格（`tabWidth: 2`）
|
||
- **引号**: 单引号（`singleQuote: true`）
|
||
- **分号**: 必须使用分号（`semi: true`）
|
||
- **行宽**: 80 字符（`printWidth: 80`）
|
||
- **对象属性引号**: 保持一致（`quoteProps: 'consistent'`）
|
||
- **HTML 空白**: 严格模式（`htmlWhitespaceSensitivity: 'strict'`）
|
||
- **Vue 脚本样式缩进**: 启用（`vueIndentScriptAndStyle: true`）
|
||
|
||
### 代码检查规范（遵循 `.eslintrc.js`）
|
||
- **代码风格**: Airbnb JavaScript Style Guide
|
||
- **TypeScript**: 使用 `@typescript-eslint/recommended` 规则
|
||
- **Vue 3**: 使用 `plugin:vue/vue3-recommended` 规则
|
||
- **导入**: 使用 `plugin:import` 规则，支持 TypeScript 路径解析
|
||
- **关键规则**:
|
||
- 事件名使用 camelCase（`vue/custom-event-name-casing`）
|
||
- 允许 `@ts-ignore` 注释（`@typescript-eslint/ban-ts-comment: 0`）
|
||
- 允许 `any` 类型（`@typescript-eslint/no-explicit-any: 0`）
|
||
- 导入时不需要扩展名（`import/extensions`）
|
||
- 生产环境禁止 `debugger`，开发环境允许
|
||
|
||
### TypeScript
|
||
- 使用 `camelCase` 命名变量和函数
|
||
- 使用 `PascalCase` 命名类和组件
|
||
- 使用类型提示，但不需要比 Python 更严格
|
||
- 避免使用 `abstract` 类和 `protected` 修饰符
|
||
- 命名方式需与后端 Python 代码保持一致（API 调用时保持命名一致性）
|
||
|
||
### Vue 组件
|
||
- 使用 `<script setup>` 语法
|
||
- **组件文件名必须使用 PascalCase**（如 `UserProfile.vue`、`UserList.vue`）
|
||
- **目录名必须使用 PascalCase**（如 `UserManage/`、`QuestionBank/`）
|
||
- Props 和 Emits 使用 `defineProps` 和 `defineEmits`
|
||
- 使用 `ref` 和 `reactive` 管理响应式状态
|
||
- 使用 `computed` 和 `watch` 处理派生状态和副作用
|
||
- 事件名使用 camelCase（如 `@update:value`）
|
||
|
||
### 样式
|
||
- 使用 Less 作为 CSS 预处理器
|
||
- 组件样式使用 `<style lang="less" scoped>`
|
||
- 全局样式在 `src/assets/style/global.less`
|
||
- 使用 Arco Design CSS 变量（如 `var(--color-bg-1)`）
|
||
- 响应式使用 Less 变量 `@screen-*`（定义在 `src/assets/style/breakpoint.less`）
|
||
|
||
## 4. UI 组件使用
|
||
|
||
### Arco Design 组件
|
||
- **优先使用 Arco Design 组件**: 优先使用 Arco Design Vue 提供的组件
|
||
- **自动导入**: Arco 组件已配置自动导入，无需手动 import
|
||
- **主题变量**: 使用 Arco Design CSS 变量，支持主题切换
|
||
- **图标**: 使用 `@arco-design/web-vue/es/icon` 中的图标
|
||
- **样式修改**: 不要擅自修改 Arco Design 组件的默认样式，除非收到明确的修改命令
|
||
|
||
### 自定义组件
|
||
- 放置在 `src/components/` 目录
|
||
- 按功能模块组织子目录
|
||
- 全局组件在 `src/components/index.ts` 中注册
|
||
|
||
## 5. API 调用
|
||
|
||
### 请求配置
|
||
- 使用 `src/api/interceptor.ts` 中的 Axios 实例
|
||
- 统一错误处理在拦截器中配置
|
||
- Token 认证通过请求头自动添加
|
||
|
||
### API 文件组织
|
||
- 按功能模块组织 API 文件（如 `user.ts`、`dashboard.ts`）
|
||
- 导出函数命名使用 camelCase
|
||
- 使用 TypeScript 类型定义请求和响应
|
||
|
||
## 6. 状态管理
|
||
|
||
### Pinia Store
|
||
- 使用 `defineStore` 定义 store
|
||
- Store 文件按模块组织在 `src/store/modules/` 目录
|
||
- 使用组合式 API 风格（`setup` 函数）
|
||
|
||
### 状态命名
|
||
- State 使用 camelCase
|
||
- Actions 使用 camelCase，动词开头（如 `fetchUserInfo`）
|
||
- Getters 使用 camelCase
|
||
|
||
## 7. 路由
|
||
|
||
### 路由配置
|
||
- 路由定义在 `router/routes/` 目录，按模块组织
|
||
- 使用懒加载：`component: () => import('@/views/xxx/index.vue')`
|
||
- 路由元信息在 `meta` 字段中定义
|
||
|
||
### 路由守卫
|
||
- 认证守卫：`router/guard/userLoginInfo.ts`
|
||
- 权限守卫：`router/guard/permission.ts`
|
||
- 全局守卫：`router/guard/index.ts`
|
||
|
||
## 8. 国际化
|
||
- 使用 `useI18n()` 获取 `t` 函数
|
||
- 页面文案：`views/[module]/locale/`，全局文案：`src/locale/`
|
||
- 文案 key 使用点号分隔（如 `user.login.title`）
|
||
|
||
## 9. 数据可视化
|
||
|
||
### ECharts
|
||
- 使用 `vue-echarts` 封装 ECharts
|
||
- 图表组件统一在 `src/components/chart/` 目录
|
||
- 图表配置使用 `hooks/chart-option.ts` 统一管理
|
||
|
||
## 10. 开发规范
|
||
|
||
### 环境变量
|
||
- 使用 Vite 环境变量（`VITE_*` 前缀）
|
||
- 开发环境：`.env.development`
|
||
- 生产环境：`.env.production`
|
||
- API 地址：`VITE_API_BASE_URL`
|
||
|
||
### Mock 数据
|
||
- 开发环境支持 Mock.js
|
||
- Mock 配置在 `src/mock/` 目录
|
||
- 使用 `src/utils/setup-mock.ts` 设置 Mock
|
||
|
||
### 代码质量
|
||
- **ESLint**: 代码检查（配置在 `.eslintrc.js`），遵循 Airbnb 风格和 Vue 3 规范
|
||
- **Prettier**: 代码格式化（配置在 `.prettierrc.js`），2空格缩进、单引号、分号
|
||
- **Stylelint**: 样式检查（配置在 `.stylelintrc.js`）
|
||
- **lint-staged**: 提交前自动格式化（配置在 `package.json`）
|
||
- **重要**: 生成的代码必须符合 Prettier 和 ESLint 规范，避免格式化错误
|
||
|
||
## 11. 性能优化
|
||
- 路由级别懒加载
|
||
- 组件按需加载
|
||
|
||
## 12. 响应式设计
|
||
- 使用 Less 变量 `@screen-xs` 到 `@screen-xxl`
|
||
- 使用 `hooks/responsive.ts` 获取响应式状态
|