docs: 完善项目文档结构并更新内容指南

- 添加详细目录结构，便于快速导航 - 新增快速开始章节，包含环境准备和新手指南 - 扩展常用开发命令和目录结构说明 - 完善核心架构模式解释，补充组合式函数详情 - 新增常见问题与解决方案章节，涵盖Video.js、API调用、Vant组件等常见问题 - 更新功能更新记录，按时间分类整理 - 优化组件目录结构说明，增加文档索引

docs: 完善项目文档结构并更新内容指南
- 添加详细目录结构，便于快速导航 - 新增快速开始章节，包含环境准备和新手指南 - 扩展常用开发命令和目录结构说明 - 完善核心架构模式解释，补充组合式函数详情 - 新增常见问题与解决方案章节，涵盖Video.js、API调用、Vant组件等常见问题 - 更新功能更新记录，按时间分类整理 - 优化组件目录结构说明，增加文档索引
hookehuyr
Commit 89f8608cd4fcd9f80fb02712fc4d9bbc3d25b49a 89f8608c 1 parent a6530330
Showing 1 changed file with 218 additions and 62 deletions
CLAUDE.md
--- a/CLAUDE.md
View file @89f8608
+++ b/CLAUDE.md
View file @89f8608
@@ -2,18 +2,74 @@
 此文件为 Claude Code (claude.ai/code) 在此代码库中工作时提供指导。
+## 目录
+
+- [项目概述](#项目概述) - 技术栈与基本信息
+- [快速开始](#快速开始) - 环境准备与新手指南
+- [常用开发命令](#常用开发命令) - 开发、测试、部署命令
+- [目录结构](#目录结构) - 项目文件组织
+- [路径别名](#路径别名) - 导入路径快捷方式
+- [核心架构模式](#核心架构模式) - API、组件、路由、样式、状态管理
+- [重要注意事项](#重要注意事项) - 常见陷阱与最佳实践
+- [业务系统架构](#业务系统架构) - 6大业务模块说明
+- [常见问题与解决方案](#常见问题与解决方案) - Q&A
+- [功能更新记录](#功能更新记录) - 最近变更历史
+- [文档索引](#文档索引) - 相关文档链接
+
 ## 项目概述
 **美乐爱觉 (mlaj)** - 基于 Vue 3 的教育平台，深度集成微信生态，服务于教师和学生。
-- **框架**: Vue 3 (Composition API + `<script setup>`)
+- **框架**: Vue 3.5.13 (Composition API + `<script setup>`)
 - **构建工具**: Vite 6.2.0
 - **包管理器**: pnpm (项目使用 `.nvm` 管理 Node.js 18.19.1)
-- **UI 框架**: Vant 4.9.22 (移动端优先)
+- **UI 框架**: Vant 4.9.22 (移动端优先，组件自动导入)
-- **样式**: TailwindCSS + Less (分层)
+- **样式**: TailwindCSS 3.4.1 + Less 4.2.2 (分层架构)
 - **状态管理**: Context API (`/src/contexts/`) + localStorage
 - **路由**: Vue Router 4.5.0，支持懒加载和路由守卫
 - **HTTP**: Axios 1.8.4，集中式拦截器
+- **视频播放**: Video.js 7.21.7 (通过 `@videojs-player/vue` 封装)
+
+## 快速开始
+
+### 环境准备
+
+1. **Node.js 版本**: 使用 `.nvm` 管理 Node.js 18.19.1
+   ```bash
+   nvm use 18.19.1
+   ```
+
+2. **安装依赖**:
+   ```bash
+   pnpm install
+   ```
+
+3. **启动开发服务器**:
+   ```bash
+   pnpm dev
+   ```
+
+### 新手指南
+
+**添加新页面**:
+1. 在 `/src/views/` 相应模块下创建页面组件
+2. 在 `/src/router/` 对应路由文件中注册路由
+3. 如需认证，在路由 `meta` 中添加 `requiresAuth: true`
+
+**调用 API**:
+1. 在 `/src/api/` 对应模块中定义 API 函数
+2. 遵循统一返回结构：`{ code: 1, data: any, msg: string }`
+3. 使用 `if (res.code === 1)` 检查成功（而非 `if (res.code)`）
+
+**创建可复用组件**:
+1. 放置在 `/src/components/ui/`（通用）或相应业务目录
+2. 使用 `defineProps` 和 `defineEmits` 定义接口
+3. 通过 emit 事件向父组件传递操作，避免直接调用 API
+
+**提取逻辑到 Composable**:
+1. 在 `/src/composables/` 创建 `useXxx.js`
+2. 返回响应式 refs 和函数
+3. 内部处理副作用（API 调用、事件监听等）
 ## 常用开发命令
@@ -39,10 +95,12 @@ pnpm oa_upload     # 部署到 OA 服务器
 ```
 src/
-├── api/              # API 接口层 - 按领域模块化
+├── api/              # API 接口层 - 15个模块，按领域组织
 │   ├── auth.js       # 认证相关接口
+│   ├── checkin.js    # 打卡/作业接口
 │   ├── course.js     # 课程相关接口
 │   ├── teacher.js    # 教师端接口
+│   ├── recall_users.js # 召回系统接口
 │   └── ...
 ├── assets/           # 静态资源 (图片、CSS、模拟数据)
 ├── components/       # 可复用的 Vue 组件
@@ -50,7 +108,13 @@ src/
 │   ├── checkin/      # 打卡相关组件
 │   ├── courses/      # 课程相关组件
 │   └── studyDetail/  # 学习详情页组件
-├── composables/      # Vue 组合式函数，用于逻辑复用 (useStudyComments, useStudyRecordTracker 等)
+├── composables/      # 13个组合式函数，用于逻辑复用
+│   ├── useAuth.js           # 认证相关逻辑
+│   ├── useCheckin.js        # 打卡流程与提交
+│   ├── useCheckinDraft.js   # 打卡草稿缓存
+│   ├── useStudyComments.js  # 评论获取、提交、分页
+│   ├── useStudyRecordTracker.js # 学习时长追踪和分析
+│   └── ...
 ├── contexts/         # 全局状态提供者 (auth, cart)
 ├── common/           # 共享常量和工具
 ├── router/           # Vue Router 配置
@@ -120,9 +184,11 @@ src/
 - 通过 emit 事件向父组件传递操作
 **组合式函数** (`/src/composables/`): 可复用逻辑：
+- `useAuth`: 认证状态管理与登录流程
+- `useCheckin`: 打卡流程和提交（七牛上传、校验、提交）
+- `useCheckinDraft`: 打卡草稿自动缓存（防止数据丢失）
 - `useStudyComments`: 评论获取、提交、分页
 - `useStudyRecordTracker`: 学习时长追踪和分析
-- `useCheckin`: 打卡流程和提交
 - 返回响应式 refs 和函数，内部处理副作用
 ### 路由与认证
@@ -240,6 +306,17 @@ Vant 组件通过 `unplugin-vue-components` 自动导入：
 ### 打卡系统
+**核心 composable**: `useCheckin.js` 封装打卡流程：
+- 文件上传：七牛云 + Hash 秒传（避免重复上传）
+- 支持类型：文本、图片、视频、音频、计数打卡
+- 数据校验：文件大小、数量、类型验证
+- 提交流程：新增/编辑统一处理
+
+**草稿缓存**: `useCheckinDraft.js` 防止数据丢失：
+- 自动保存：输入内容实时缓存到 localStorage
+- 智能恢复：页面加载时自动填充上次未提交的内容
+- 清理机制：提交成功或手动清除时移除草稿
+
 **统一组件**: `CheckInDialog.vue` 处理所有打卡流程：
 - 接收 `items_today` 和 `items_history` props
 - 每项包含 `id`, `name`, `task_type` ('checkin'/'upload'), `is_gray`
@@ -259,6 +336,12 @@ Vant 组件通过 `unplugin-vue-components` 自动导入：
 - `VITE_PROXY_TARGET` - 后端 API 目标
 - `VITE_OUTDIR` - 构建输出目录
+**环境与部署**:
+- **开发环境**: `http://oa-dev.onwall.cn/`
+- **生产环境**: `http://oa.onwall.cn`
+- **部署流程**: 构建 → 归档(tar.gz) → SCP 上传 → 服务器解压 → 清理归档
+- **代码分割**: 手动配置 chunks，Office 工具和图片工具单独打包
+
 ### Speckit 框架命令
 位于 `.cursor/commands/`:
@@ -285,6 +368,14 @@ Vant 组件通过 `unplugin-vue-components` 自动导入：
 - 混合使用 2 空格/4 空格缩进
 - 混合使用 function/箭头函数
 - 混合使用中文/英文注释
+- API 返回值语义不一致（部分返回 `false` 而非标准结构）
+- 部分页面组件过大，应考虑拆分
+
+**改进建议**:
+- 统一使用 ESLint + Prettier 进行代码格式化
+- 制定统一的 API 返回值规范
+- 大型页面组件应拆分为多个子组件
+- 增加单元测试覆盖（当前测试文件较少）
 ## 特殊功能
@@ -395,54 +486,102 @@ Vant 组件通过 `unplugin-vue-components` 自动导入：
   - `checkAuth`：基于白名单或 `meta.requiresAuth` 拦截未登录访问。
   - `startWxAuth`：按需触发微信授权流程（非自动触发，避免死循环）。
-## 目录结构说明
+## 常见问题与解决方案
+
+### Q: 为什么 Video.js 在切换显示/隐藏时无法正常工作？
+
+**A**: Video.js 在 `v-show` (display: none) 状态下初始化会失败。
+- **解决**: 使用 `v-if` 而非 `v-show`
+- **正确模式**: 设置 `isPlaying = true`，然后 `setTimeout` 再调用 `play()`
+- **参考**: `StudyDetailPage.vue` 中的实现
+
+### Q: 为什么我的 401 响应导致页面跳转到登录页？
+
+**A**: 这是预期的行为，但仅对需要认证的页面生效。
+- 公开页面（如课程详情）不会跳转
+- 受限页面会清理登录信息并重定向
+- 如需自定义处理，在组件内监听 API 错误
+
+### Q: 如何正确检查 API 响应是否成功？
+**A**: 始终使用 `if (res.code === 1)` 而非 `if (res.code)`。
+```javascript
+// ✓ 正确
+const { code, data } = await getCourseDetailAPI({ i: courseId })
+if (code === 1) { /* 成功 */ }
+
+// ✗ 错误 - 会将 401/403 当作成功
+if (code) { /* ... */ }
 ```
-src/
+
-├── api/              # API 接口层
+### Q: 为什么 Vant 组件导入后报错或无法使用？
-│   ├── auth.js       # 认证
+
-│   ├── checkin.js    # 打卡/作业
+**A**: Vant 组件已配置自动导入，无需手动导入。
-│   ├── course.js     # 课程
+```javascript
-│   ├── teacher.js    # 教师端
+// ✗ 错误
-│   ├── recall_users.js # 召回系统
+import { Button } from 'vant'
-│   └── ...
+
-├── components/       # UI 组件
+// ✓ 正确
-│   ├── ui/           # 通用组件 (VideoPlayer, CheckInDialog, SearchBar)
+// 直接使用 <van-button>，无需导入
-│   ├── checkin/      # 打卡业务组件
+```
-│   ├── teacher/      # 教师端组件
+
-│   └── ...
+### Q: 如何在微信环境下正确处理支付和授权？
-├── composables/      # 逻辑复用 (useCheckin, useAuth, useStudyRecordTracker)
+
-├── contexts/         # 全局状态 (auth, cart)
+**A**: 使用 `wxInfo()` 工具函数检测环境：
-├── router/           # 路由配置
+```javascript
-│   ├── checkin.js    # 打卡路由
+import { wxInfo } from '@/utils/tools'
-│   ├── teacher.js    # 教师路由
+
-│   └── ...
+// 检测微信环境
-├── views/            # 页面视图
+if (wxInfo().isWeiXin) {
-│   ├── auth/         # 登录/注册
+  // 微信浏览器
-│   ├── checkin/      # 打卡相关页面 (Index, Detail, Upload)
+} else {
-│   ├── courses/      # 课程相关页面
+  // 其他浏览器
-│   ├── teacher/      # 教师端页面 (Task, Student, Class)
+}
-│   ├── recall/       # 召回系统页面
+```
-│   ├── profile/      # 个人中心
+
-│   └── ...
+### Q: 打卡时如何避免数据丢失？
-└── ...
+
+**A**: 使用 `useCheckinDraft` 自动缓存草稿：
+```javascript
+import { useCheckinDraft } from '@/composables/useCheckinDraft'
+
+const { saveDraft, loadDraft, clearDraft } = useCheckinDraft()
+
+// 输入时自动保存
+onMounted(() => loadDraft())
+watch(inputValue, () => saveDraft(inputValue.value))
+
+// 提交成功后清除
+onSubmitSuccess(() => clearDraft())
 ```
 ## 功能更新记录 (Recent Changes)
-- **打卡详情页重构 (`/checkin/detail`)**：
+### 最近重要更新
-  - 统一了文本、媒体上传和计数打卡的入口。
+
-  - 实现了基于 `useCheckin` 的通用提交流程。
+**打卡系统增强** (2025):
-  - 优化了附件预览和编辑回填逻辑。
+- 打卡详情页重构 (`/checkin/detail`)：统一文本、媒体上传和计数打卡入口
+- 新增草稿缓存功能 (`useCheckinDraft`)：防止数据丢失，自动保存和恢复
+- 优化附件预览和编辑回填逻辑
+- 实现基于 `useCheckin` 的通用提交流程
+
+**教师端完善** (2025):
+- 作业管理页面 (`/teacher/tasks`)
+- 作业主页 (`/teacher/tasks/:id`)：统计与日历视图
+- 学员作业记录页面 (`/teacher/student-record`)
-- **教师端功能完善**：
+**召回系统** (2025):
-  - 新增作业管理、作业主页（统计与日历视图）、学员作业记录页面。
+- 身份证查询历史功能
-- **基础体验优化**：
+- 时光机旅程 (Timeline) 展示用户里程碑
-  - 登录逻辑调整：仅在点击微信图标时触发授权。
+- 专属海报生成与分享
-  - 搜索栏优化：支持 iOS 软键盘搜索键。
-  - 课程详情页：增加动态 Open Graph 标签，优化分享体验。
-功能更新记录
+**基础体验优化** (2025):
+- 登录逻辑调整：仅在点击微信图标时触发授权
+- 搜索栏优化：支持 iOS 软键盘搜索键
+- 课程详情页：动态 Open Graph 标签，优化分享体验
+- 401 拦截策略优化：公开页面不再跳转登录页
+
+### 历史功能更新 (详细记录)
 - 教师端新增作业管理页面：路径 `/teacher/tasks`，标题“作业管理”。
   - 列表展示：作业名称、开始时间、截止时间。
@@ -569,21 +708,38 @@ src/
   - 预览能力：
     - 上传组件点击预览时，根据扩展名识别：音频使用 `AudioPlayer` 底部弹窗；视频使用 `VideoPlayer` 居中弹窗（封面 → 点击播放 → 关闭时重置进度）；图片使用 `van-image-preview`。
-## /src/components 目录下组件
+## /src/components 目录结构
-
+
-| 目标目录（src/components/） | 包含组件                                                     | 说明             |
+项目包含 **12个主要组件目录**，涵盖了从基础 UI 到业务功能的完整组件体系：
-| --------------------------- | ------------------------------------------------------------ | ---------------- |
+
-| `checkin/`                  | `CheckInDialog.vue`, `CheckInList.vue`, `CheckInResult.vue`  | 打卡相关组件     |
+| 目录 | 组件示例 | 说明 |
-| `media/`                    | `AudioPlayer.vue`, `VideoPlayer.vue`, `MusicPlayer.vue`      | 音视频播放组件   |
+|------|---------|------|
-| `activity/`                 | `ActivityApplyHistoryPopup.vue`, `ActivityCard.vue`, `ActivityStatusBadge.vue`, `ActivityTicket.vue` | 活动相关组件     |
+| `ui/` | `VideoPlayer`, `AudioPlayer`, `CheckInDialog`, `SharePoster`, `SearchBar` | 通用 UI 组件库 |
-| `common/`                   | `ConfirmDialog.vue`, `GradientHeader.vue`, `MenuItem.vue`, `SearchBar.vue`, `TermsPopup.vue`, `UserAgreement.vue` | 通用基础组件     |
+| `checkin/` | `CheckInDialog`, `CheckInList`, `CheckInResult` | 打卡业务组件 |
-| `effects/`                  | `FrostedGlass.vue`, `LoadingSpinner.vue`                     | 视觉特效组件     |
+| `media/` | `AudioPlayer`, `VideoPlayer`, `MusicPlayer` | 音视频播放组件 |
-| `courses/`                  | `CourseCard.vue`, `LiveStreamCard.vue`                       | 课程展示组件     |
+| `activity/` | `ActivityCard`, `ActivityTicket`, `ActivityStatusBadge` | 活动相关组件 |
-| `payment/`                  | `WechatPayment.vue`                                          | 支付组件         |
+| `common/` | `ConfirmDialog`, `GradientHeader`, `MenuItem` | 通用基础组件 |
-| `studyDetail/`              | `StudyMaterialsPopup.vue`                                    | 学习资料弹窗     |
+| `effects/` | `FrostedGlass`, `LoadingSpinner` | 视觉特效组件 |
-| `layout/`                   | `AppLayout.vue`, `BottomNav.vue`                             | 布局与导航       |
+| `courses/` | `CourseCard`, `LiveStreamCard` | 课程展示组件 |
-| `share/`                    | `SharePoster.vue`                                            | 分享海报         |
+| `payment/` | `WechatPayment` | 支付组件 |
-| `files/`                    | `FilePreview.vue`                                            | 文件预览         |
+| `studyDetail/` | `StudyMaterialsPopup` | 学习资料弹窗 |
-| `feedback/`                 | `FeedbackForm.vue`                                           | 反馈表单         |
+| `layout/` | `AppLayout`, `BottomNav` | 布局与导航 |
+| `share/` | `SharePoster` | 分享海报 |
+| `files/` | `FilePreview` | 文件预览 |
+| `feedback/` | `FeedbackForm` | 反馈表单 |
+| `teacher/` | 教师端专用组件 | 教师业务组件 |
+
+---
+
+## 文档索引
+
+项目包含以下文档，帮助理解不同方面：
+
+- **CLAUDE.md** (本文档) - 项目总体架构与开发指南
+- **VUE_CODE_STYLE_GUIDE.md** - Vue 代码风格规范与最佳实践
+- **CHANGELOG.md** - 变更日志记录
+- **package.json** - 依赖与脚本配置
+- **vite.config.js** - 构建工具配置
+- **tailwind.config.js** - 样式系统配置
 ---