Initial commit: book-mcp 教辅处理 MCP server + Arco Vue 管理端

后端 (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→入库→上传→校验)
2026-10-11 18:03:45 +08:00
parent f7fb571bce
commit 9b0910ccb1
160 changed files with 23628 additions and 3 deletions
--- a/frontend/.cursorrules
+++ b/frontend/.cursorrules
@@ -0,0 +1,212 @@
+# 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` 获取响应式状态