美乐爱觉项目（mlaj）

测试环境网站：https://oa-dev.onwall.cn/f/mlaj

项目概览

本项目是面向移动端（以微信内置浏览器为主）的教育业务 H5，覆盖「用户登录/微信授权 → 课程浏览/购买 → 学习与内容预览 → 打卡作业（学生端/教师端）→ 活动报名 → 召回促活 → 积分/订单」等完整链路。

技术栈

• Vue 3 + Vite 6（Hash 路由）
• UI：Vant 4 + TailwindCSS 3 + Less（Tailwind 负责布局，Less 做补充）
• 路由：Vue Router 4（带全局守卫与白名单/Meta 双策略鉴权）
• 请求：Axios（统一注入认证头、统一 401 策略）
• 测试：Vitest（已有 composables/utils 单测）
• 微信生态：weixin-js-sdk、OAuth/OpenID 登录态探测与手动触发授权、微信支付
• 媒体与文档：Video.js、PDF/Office 预览组件

项目结构（快速索引）

src/
├── api/               # 按业务域拆分的接口封装（auth/course/checkin/teacher/...）
├── components/        # 组件（按业务域归类）
├── composables/       # 组合式函数（逻辑复用，含单测）
├── contexts/          # 全局状态（provide/inject：auth/cart）
├── router/            # 路由定义与守卫
├── utils/             # 工具层（axios、上传、鉴权存储、版本更新等）
└── views/             # 页面（按业务域归类）

可复用能力清单

• 认证与登录态：/src/contexts/auth.js
• 购物车：/src/contexts/cart.js
• Axios 统一策略：/src/utils/axios.js
• 微信能力封装：/src/router/guards.js、/src/api/wx
• 上传与文件处理：/src/utils/upload.js、/src/utils/qiniuFileHash.js
• 内容预览组件：/src/components/media
• 滚动/播放/图片容错等组合式函数：/src/composables
• 版本更新提示：/src/utils/versionUpdater.js

项目优缺点（基于现状扫描）

优点

• 业务域拆分清晰：api / views / components / composables 的分层直观
• 复用意识强：打卡、媒体预览、海报、鉴权与请求拦截均做了抽象
• 微信场景适配完整：授权、JSSDK、支付链路齐全，并避免路由守卫自动授权死循环
• 具备基础测试资产：composables/utils 已引入 Vitest 并有用例

缺点与风险

• 文档与代码存在不一致：README/CLAUDE 中的组件目录、路径描述与实际目录不一致
• 依赖与工程规范不够统一：同时存在 pnpm/yarn/npm 的 lock 文件，容易引起依赖漂移
• 状态来源较多：localStorage + contexts + axios 默认头并存，一致性风险偏高
• 全局屏蔽 warnHandler：/src/main.js 会吞掉 Vue 警告，可能掩盖潜在问题
• 布局目录已归一：统一使用 /src/components/layout，已移除 /src/layouts

文档索引

📚 完整文档导航: docs/README.md - 所有文档的分类索引

快速链接

架构设计:

• 架构文档 - 应用架构与工程配置
• 组件索引 - /src/components 组件目录索引

开发配置:

• ESLint + Prettier - 代码规范与格式化
• Husky + lint-staged - Git Hooks 配置
• 开发工作流 - 团队开发流程

测试文档:

• Playwright 指南 - E2E 测试框架
• E2E 认证指南 - 测试登录认证
• E2E 代理配置 - 测试服务器代理

工具指南:

• Claude Skills - Claude Code 技能完全指南

其他:

• 更新日志 - 功能更新记录
• 代码风格指南 - Vue 代码最佳实践
• 已知问题与改进建议 - 待优化项列表
• 项目协作说明 - Claude Code 开发指南（详细）

业务系统架构

1. 用户与认证 (User & Auth)

• 核心流程：支持手机号+验证码/密码登录，注册流程。
• 微信集成：
  • 环境检测：wxInfo().isWeiXin 检测微信浏览器。
  • 授权登录：基于 OAuth 2.0，通过 getAuthInfoAPI 获取 OpenID/UserInfo，支持静默/显式授权。
  • 分享配置：通过 JS-SDK 配置自定义分享标题、描述和图片。
• 个人中心：管理个人资料（头像/昵称/手机/密码）、消息通知、帮助中心。
• 状态管理：contexts/auth.js 维护全局 currentUser，使用 localStorage 持久化，Axios 拦截器自动注入 Token。

2. 课程系统 (Courses)

• 展示与浏览：首页推荐、课程列表（热门/精选/搜索）、课程详情页（介绍/目录/评价）。
• 购买流程：
  • 购物车：contexts/cart.js 支持单品/多品模式，本地持久化。
  • 结算：收银台页面 (/checkout)，集成微信支付 (api/wx/pay.js)。
  • 环境校验：付费课程强制在微信环境内购买。
• 学习体验：
  • 学习页：展示课程目录与学习进度。
  • 内容预览：集成 Video.js 播放视频，PDF.js 预览文档，Office Web Viewer 预览 Word/Excel/PPT。
  • 记录追踪：useStudyRecordTracker 自动追踪学习时长与进度。

3. 打卡与作业系统 (Check-in & Tasks)

• 学生端：
  • 作业日历：IndexCheckInPage 展示每日打卡状态，支持按月切换。
  • 统一打卡页 (/checkin/detail)：
  • 支持类型：文本、图片、视频、音频、计数打卡（如感恩日记）。
  • 核心逻辑：useCheckin 封装上传（七牛云+Hash秒传）、校验、提交逻辑。
  • 交互：支持补卡、编辑已提交内容、选择打卡对象（计数模式）；支持自动保存草稿与断点恢复。
  • 互动社区：打卡动态流，支持点赞、评论、查看他人作品。
• 教师端 (/teacher)：
  • 作业管理：发布新作业，查看作业列表与详情（完成率/出勤率统计）。
  • 班级管理：查看班级学员列表，进入学员详情页。
  • 审批流程：审核学生提交的打卡内容，支持通过/驳回。

4. 活动系统 (Activities)

• 功能：活动列表展示、活动详情、在线报名表单 (/activities/:id/signup)。
• 记录：用户可查看“我的活动”历史记录。

5. 召回系统 (Recall)

• 目标：面向老用户的营销与促活流程。
• 流程：
  1. 登录/身份验证（支持身份证查询历史）。
  2. 引导页与信息补全。
  3. 时光机旅程 (Timeline)：展示用户在平台的历史里程碑。
  4. 活动历史回顾与积分汇总。
  5. 专属海报：生成个性化分享海报。
  6. 导流：引导至 AI 星球或最新课程。

6. 积分与订单

• 订单：查看订单状态（待支付/已支付/退款），支持取消订单。
• 积分：查看积分余额与变动明细，积分可用于抵扣或兑换（视具体业务规则）。

架构实现与工程配置

实现细节（登录态注入、401 策略、微信授权、上传/预览、Vite 代理与环境变量等）已迁移到：/docs/ARCHITECTURE.md

功能更新记录 (Recent Changes)

详细记录已迁移到：/docs/CHANGELOG.md

/src/components 目录下组件

组件目录索引已迁移到：/docs/COMPONENTS.md

---