README.md



美乐爱觉项目（mlaj）

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


🚀 快速开始

# 1. 使用 nvm 切换到正确的 Node.js 版本
nvm use 18.19.1

# 2. 安装依赖
pnpm install

# 3. 启动开发服务器
pnpm dev

# 4. 运行测试
pnpm test

# 5. 构建生产版本
pnpm build


新手上路:


📖 架构文档 - 了解项目结构
🎨 代码风格指南 - Vue 代码最佳实践
🔧 开发工作流 - 团队开发流程
✅ 查看完整文档: docs/README.md


项目概览

本项目是面向移动端（以微信内置浏览器为主）的教育业务 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 - 13+ 篇文档的分类索引


📑 文档分类


🏗️ 架构设计


架构文档 - 应用架构、工程化配置、目录结构

组件索引 - 22个组件目录的分类索引


💻 开发配置


ESLint + Prettier - 代码规范与自动格式化配置

Husky + lint-staged - Git Hooks 自动化检查配置

开发工作流 - 团队开发流程与规范


🧪 测试文档


Playwright 指南 - E2E 测试框架完整指南

E2E 认证指南 - 测试登录认证流程

E2E 代理配置 - Vite 反向代理配置说明

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)


目标：面向老用户的营销与促活流程。

流程：


登录/身份验证（支持身份证查询历史）。
引导页与信息补全。

时光机旅程 (Timeline)：展示用户在平台的历史里程碑。
活动历史回顾与积分汇总。

专属海报：生成个性化分享海报。
导流：引导至 AI 星球或最新课程。


6. 积分与订单


订单：查看订单状态（待支付/已支付/退款），支持取消订单。

积分：查看积分余额与变动明细，积分可用于抵扣或兑换（视具体业务规则）。


架构实现与工程配置

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


🎉 功能更新记录


最新更新 (2026-01)

欢迎页功能 ✨ (2026-01-28):


首次访问欢迎页 (/welcome)：星空宇宙主题视频背景
首次访问检测：localStorage 标志位 + 路由守卫拦截
水平布局功能入口：课程、活动、个人中心（带浮动动画）
环境变量控制：VITE_WELCOME_PAGE_ENABLED 开关
详细文档：docs/tasks/done/26.1.28-欢迎页开发计划/


打卡系统增强 📝 (2026-01):


打卡详情页重构 (/checkin/detail)：统一文本、媒体上传和计数打卡入口
新增草稿缓存功能 (useCheckinDraft)：防止数据丢失，自动保存和恢复
打卡卡片优化 (CheckinCard)：长文本折叠、多附件 Tab 切换
草稿恢复时的作业有效性校验：作业失效时自动清理
优化附件预览和编辑回填逻辑
实现基于 useCheckin 的通用提交流程
完整文档：docs/tasks/done/暂存用户打卡信息.md


历史功能更新:

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


/src/components 目录下组件

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