Hooke / mlaj

Go to a project
Toggle navigation Toggle navigation pinning
hookehuyr
89f8608c 1 parent a6530330

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

- 添加详细目录结构，便于快速导航
- 新增快速开始章节，包含环境准备和新手指南
- 扩展常用开发命令和目录结构说明
- 完善核心架构模式解释，补充组合式函数详情
- 新增常见问题与解决方案章节，涵盖Video.js、API调用、Vant组件等常见问题
- 更新功能更新记录，按时间分类整理
- 优化组件目录结构说明，增加文档索引
Inline Side-by-side
Showing 1 changed file with 218 additions and 62 deletions
......@@ -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 (移动端优先)
- **样式**: TailwindCSS + Less (分层)
- **UI 框架**: Vant 4.9.22 (移动端优先，组件自动导入)
- **样式**: 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 接口层
│ ├── auth.js # 认证
│ ├── checkin.js # 打卡/作业
│ ├── course.js # 课程
│ ├── teacher.js # 教师端
│ ├── recall_users.js # 召回系统
│ └── ...
├── components/ # UI 组件
│ ├── ui/ # 通用组件 (VideoPlayer, CheckInDialog, SearchBar)
│ ├── checkin/ # 打卡业务组件
│ ├── teacher/ # 教师端组件
│ └── ...
├── composables/ # 逻辑复用 (useCheckin, useAuth, useStudyRecordTracker)
├── contexts/ # 全局状态 (auth, cart)
├── router/ # 路由配置
│ ├── checkin.js # 打卡路由
│ ├── teacher.js # 教师路由
│ └── ...
├── views/ # 页面视图
│ ├── auth/ # 登录/注册
│ ├── checkin/ # 打卡相关页面 (Index, Detail, Upload)
│ ├── courses/ # 课程相关页面
│ ├── teacher/ # 教师端页面 (Task, Student, Class)
│ ├── recall/ # 召回系统页面
│ ├── profile/ # 个人中心
│ └── ...
└── ...
### Q: 为什么 Vant 组件导入后报错或无法使用？
**A**: Vant 组件已配置自动导入，无需手动导入。
```javascript
// ✗ 错误
import { Button } from 'vant'
// ✓ 正确
// 直接使用 <van-button>，无需导入
```
### Q: 如何在微信环境下正确处理支付和授权？
**A**: 使用 `wxInfo()` 工具函数检测环境：
```javascript
import { wxInfo } from '@/utils/tools'
// 检测微信环境
if (wxInfo().isWeiXin) {
// 微信浏览器
} else {
// 其他浏览器
}
```
### 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`)
- **教师端功能完善**：
- 新增作业管理、作业主页（统计与日历视图）、学员作业记录页面。
- **基础体验优化**：
- 登录逻辑调整：仅在点击微信图标时触发授权。
- 搜索栏优化：支持 iOS 软键盘搜索键。
- 课程详情页：增加动态 Open Graph 标签，优化分享体验。
**召回系统** (2025):
- 身份证查询历史功能
- 时光机旅程 (Timeline) 展示用户里程碑
- 专属海报生成与分享
功能更新记录
**基础体验优化** (2025):
- 登录逻辑调整：仅在点击微信图标时触发授权
- 搜索栏优化：支持 iOS 软键盘搜索键
- 课程详情页：动态 Open Graph 标签，优化分享体验
- 401 拦截策略优化：公开页面不再跳转登录页
### 历史功能更新 (详细记录)
- 教师端新增作业管理页面：路径 `/teacher/tasks`，标题“作业管理”。
- 列表展示：作业名称、开始时间、截止时间。
......@@ -569,21 +708,38 @@ src/
- 预览能力：
- 上传组件点击预览时，根据扩展名识别：音频使用 `AudioPlayer` 底部弹窗；视频使用 `VideoPlayer` 居中弹窗（封面 → 点击播放 → 关闭时重置进度）；图片使用 `van-image-preview`。
## /src/components 目录下组件
| 目标目录（src/components/） | 包含组件 | 说明 |
| --------------------------- | ------------------------------------------------------------ | ---------------- |
| `checkin/` | `CheckInDialog.vue`, `CheckInList.vue`, `CheckInResult.vue` | 打卡相关组件 |
| `media/` | `AudioPlayer.vue`, `VideoPlayer.vue`, `MusicPlayer.vue` | 音视频播放组件 |
| `activity/` | `ActivityApplyHistoryPopup.vue`, `ActivityCard.vue`, `ActivityStatusBadge.vue`, `ActivityTicket.vue` | 活动相关组件 |
| `common/` | `ConfirmDialog.vue`, `GradientHeader.vue`, `MenuItem.vue`, `SearchBar.vue`, `TermsPopup.vue`, `UserAgreement.vue` | 通用基础组件 |
| `effects/` | `FrostedGlass.vue`, `LoadingSpinner.vue` | 视觉特效组件 |
| `courses/` | `CourseCard.vue`, `LiveStreamCard.vue` | 课程展示组件 |
| `payment/` | `WechatPayment.vue` | 支付组件 |
| `studyDetail/` | `StudyMaterialsPopup.vue` | 学习资料弹窗 |
| `layout/` | `AppLayout.vue`, `BottomNav.vue` | 布局与导航 |
| `share/` | `SharePoster.vue` | 分享海报 |
| `files/` | `FilePreview.vue` | 文件预览 |
| `feedback/` | `FeedbackForm.vue` | 反馈表单 |
## /src/components 目录结构
项目包含 **12个主要组件目录**，涵盖了从基础 UI 到业务功能的完整组件体系：
| 目录 | 组件示例 | 说明 |
|------|---------|------|
| `ui/` | `VideoPlayer`, `AudioPlayer`, `CheckInDialog`, `SharePoster`, `SearchBar` | 通用 UI 组件库 |
| `checkin/` | `CheckInDialog`, `CheckInList`, `CheckInResult` | 打卡业务组件 |
| `media/` | `AudioPlayer`, `VideoPlayer`, `MusicPlayer` | 音视频播放组件 |
| `activity/` | `ActivityCard`, `ActivityTicket`, `ActivityStatusBadge` | 活动相关组件 |
| `common/` | `ConfirmDialog`, `GradientHeader`, `MenuItem` | 通用基础组件 |
| `effects/` | `FrostedGlass`, `LoadingSpinner` | 视觉特效组件 |
| `courses/` | `CourseCard`, `LiveStreamCard` | 课程展示组件 |
| `payment/` | `WechatPayment` | 支付组件 |
| `studyDetail/` | `StudyMaterialsPopup` | 学习资料弹窗 |
| `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** - 样式系统配置
---
......