hookehuyr

docs: 新增项目文档并重构README结构

将原README中的详细内容拆分为多个文档,提升可维护性
- 新增docs/COMPONENTS.md:组件目录索引
- 新增docs/CHANGELOG.md:功能更新记录
- 新增docs/ARCHITECTURE.md:架构实现与工程配置
- 重构README.md为项目概览与快速索引
This diff is collapsed. Click to expand it.
1 +# 架构实现与工程配置
2 +
3 +## 入口与初始化
4 +
5 +- 应用入口:[/src/main.js](file:///Users/huyirui/program/itomix/git/mlaj/src/main.js)
6 + - 创建 App、注册全局 Icon 组件、挂载路由
7 + - 全局注入 axios 到 app.config.globalProperties.$http
8 +- 根组件:[/src/App.vue](file:///Users/huyirui/program/itomix/git/mlaj/src/App.vue)
9 + - 初始化全局认证与购物车:provideAuth / provideCart
10 + - 生产环境 + 微信环境:初始化微信 JSSDK(配置签名 URL)
11 + - 生产环境:版本更新探测(弹窗提示刷新)
12 +
13 +## 路由与权限
14 +
15 +- 路由入口:[/src/router/index.js](file:///Users/huyirui/program/itomix/git/mlaj/src/router/index.js)
16 + - Hash 路由:createWebHashHistory(import.meta.env.VITE_BASE || '/')
17 + - beforeEach:统一登录页回跳处理,并在必要时探测“是否已登录”
18 +- 鉴权策略:[/src/router/guards.js](file:///Users/huyirui/program/itomix/git/mlaj/src/router/guards.js)
19 + - 白名单 + meta.requiresAuth 双策略判断
20 + - 未登录时重定向 /login 并带 redirect
21 +- 微信授权策略:[/src/router/guards.js](file:///Users/huyirui/program/itomix/git/mlaj/src/router/guards.js)
22 + - 不在路由守卫自动触发授权,避免循环
23 + - 仅在用户触发(如点击微信图标/购买流程探测)时调用 startWxAuth
24 +
25 +## 请求与登录态注入
26 +
27 +- Axios 封装:[/src/utils/axios.js](file:///Users/huyirui/program/itomix/git/mlaj/src/utils/axios.js)
28 + - 请求拦截:动态读取本地 user_info 并注入 User-Id / User-Token
29 + - 响应拦截:code=401 时,仅当当前路由确实需要登录才跳转登录(公开页面不强制跳转)
30 +- 登录态管理:[/src/contexts/auth.js](file:///Users/huyirui/program/itomix/git/mlaj/src/contexts/auth.js)
31 + - provide/inject 维护 currentUser/loading/login/logout
32 + - localStorage 持久化 currentUser
33 + - 初始化流程中会探测授权/登录态并拉取用户信息
34 +
35 +## 购物车与结算
36 +
37 +- 购物车上下文:[/src/contexts/cart.js](file:///Users/huyirui/program/itomix/git/mlaj/src/contexts/cart.js)
38 + - 单品/多品两种模式(App.vue 默认使用单品模式)
39 + - localStorage 带时间戳的过期策略(默认一天过期)
40 + - handleCheckout 负责构建订单数据并提交订单
41 +
42 +## 上传与预览
43 +
44 +- 上传工具:[/src/utils/upload.js](file:///Users/huyirui/program/itomix/git/mlaj/src/utils/upload.js)[/src/utils/qiniuFileHash.js](file:///Users/huyirui/program/itomix/git/mlaj/src/utils/qiniuFileHash.js)
45 + - 前端计算文件 Hash,支持“秒传检测 + 直传对象存储”
46 +- 关键业务复用:[/src/composables/useCheckin.js](file:///Users/huyirui/program/itomix/git/mlaj/src/composables/useCheckin.js)
47 + - 打卡/作业提交流程:校验、上传、提交、编辑回填等
48 +- 预览组件:[/src/components/media](file:///Users/huyirui/program/itomix/git/mlaj/src/components/media)
49 + - 视频/音频播放器、PDF/Office 预览等
50 +
51 +## Vite 配置与环境变量
52 +
53 +- Vite 配置:[/vite.config.js](file:///Users/huyirui/program/itomix/git/mlaj/vite.config.js)
54 + - 自动按需引入 Vant 组件(unplugin-auto-import / unplugin-vue-components)
55 + - 别名:@ / @components / @utils / @api 等
56 + - 本地代理:createProxy(viteEnv.VITE_PROXY_PREFIX, viteEnv.VITE_PROXY_TARGET)
57 +- 环境变量示例:[.env](file:///Users/huyirui/program/itomix/git/mlaj/.env)
58 + - VITE_PORT:开发端口
59 + - VITE_PROXY_TARGET / VITE_PROXY_PREFIX:接口代理目标与前缀
60 + - VITE_OUTDIR:构建输出目录
61 + - VITE_CONSOLE:调试开关
62 +
63 +## 目录结构(详细)
64 +
65 +```
66 +mlaj/
67 +├── build/ # Vite 代理封装
68 +├── docs/ # 项目文档(本目录)
69 +├── public/ # 静态资源
70 +├── src/
71 +│ ├── api/ # 按业务域拆分的接口封装(auth/course/checkin/teacher/...)
72 +│ ├── assets/ # 图片等资源
73 +│ ├── common/ # 常量
74 +│ ├── components/ # 组件(按业务域归类)
75 +│ ├── composables/ # 组合式函数(逻辑复用,含单测)
76 +│ ├── contexts/ # 全局状态(provide/inject:auth/cart)
77 +│ ├── router/ # 路由定义与守卫
78 +│ ├── utils/ # 工具层(axios、上传、鉴权存储、版本更新等)
79 +│ └── views/ # 页面(按业务域归类)
80 +├── tailwind.config.js # Tailwind 配置
81 +└── vite.config.js # Vite 配置
82 +```
1 +# 功能更新记录(Recent Changes)
2 +
3 +说明:该章节从 README 迁移到本文件,避免 README 过长。后续新增变更建议追加在文件顶部。
4 +
5 +## 打卡详情页重构(/checkin/detail)
6 +
7 +- 统一了文本、媒体上传和计数打卡的入口
8 +- 实现了基于 composables 的通用提交流程:[/src/composables/useCheckin.js](file:///Users/huyirui/program/itomix/git/mlaj/src/composables/useCheckin.js)
9 +- 页面入口:[/src/views/checkin/CheckinDetailPage.vue](file:///Users/huyirui/program/itomix/git/mlaj/src/views/checkin/CheckinDetailPage.vue)
10 +- 优化了附件预览与编辑回填逻辑(音频/视频/图片预览能力)
11 +
12 +## 教师端功能完善(/teacher)
13 +
14 +- 新增作业管理页面:/teacher/tasks(列表展示:名称、开始/截止时间)
15 +- 新增作业主页:/teacher/tasks/:id(统计 + 日历视图)
16 +- 新增学员作业记录页:/teacher/student-record(作业帖子 + 点赞/点评)
17 +
18 +## 基础体验优化
19 +
20 +- 登录逻辑调整:仅在登录页点击微信图标时触发授权(避免路由守卫自动授权导致的循环)
21 + - 关键文件:[/src/router/guards.js](file:///Users/huyirui/program/itomix/git/mlaj/src/router/guards.js)[/src/router/index.js](file:///Users/huyirui/program/itomix/git/mlaj/src/router/index.js)[/src/views/auth/LoginPage.vue](file:///Users/huyirui/program/itomix/git/mlaj/src/views/auth/LoginPage.vue)
22 +- 搜索栏优化:提升 iOS 软键盘“搜索”键触发稳定性
23 +- 课程详情页:增加动态 Open Graph 标签,优化分享体验
24 +
25 +## 课程详情页动态 Open Graph 元标签
26 +
27 +- 行为:进入课程详情页时,在 head 中插入 og:title / og:description / og:image / og:url;离开页面时移除
28 +- CDN 规则:图片域名为 cdn.ipadbiz.cn 时,追加 ?imageMogr2/thumbnail/200x/strip/quality/70
29 +- 位置:[/src/views/courses/CourseDetailPage.vue](file:///Users/huyirui/program/itomix/git/mlaj/src/views/courses/CourseDetailPage.vue)
30 +
31 +## 购买流程环境校验与微信授权探测
32 +
33 +- 行为:仅对非免费课程在详情页点击“购买”时进行校验;生产环境必须为微信内置浏览器
34 +- 微信环境内:若未完成微信授权(openid_has=false),会自动发起一次微信授权并中止本次购买,授权后再次点击进入结算
35 +- 位置:[/src/views/courses/CourseDetailPage.vue](file:///Users/huyirui/program/itomix/git/mlaj/src/views/courses/CourseDetailPage.vue)
36 +
37 +## 401 拦截策略优化(公开页面不再跳登录)
38 +
39 +- 行为:接口返回 code=401 时,仅当当前路由确实需要登录时才重定向登录
40 +- 位置:[/src/utils/axios.js](file:///Users/huyirui/program/itomix/git/mlaj/src/utils/axios.js)
41 +
42 +## 搜索栏回车搜索兼容性提升
43 +
44 +- 行为:输入框类型改为 search,并可选开启 form submit 机制,同时保留 keyup.enter
45 +- 位置:[/src/components/common/SearchBar.vue](file:///Users/huyirui/program/itomix/git/mlaj/src/components/common/SearchBar.vue)
46 +
47 +## 分享海报弹窗(可复用)
48 +
49 +- 入口:课程详情页底部操作栏“分享”按钮
50 +- 组件:[/src/components/poster/SharePoster.vue](file:///Users/huyirui/program/itomix/git/mlaj/src/components/poster/SharePoster.vue)
51 +- 能力:弹窗打开时通过 Canvas 合成海报(封面、二维码、文案),生成 dataURL 展示,用户长按保存
52 +
53 +## 打卡弹窗与列表组件(可复用)
54 +
55 +- 打卡弹窗:[/src/components/checkin/CheckInDialog.vue](file:///Users/huyirui/program/itomix/git/mlaj/src/components/checkin/CheckInDialog.vue)
56 +- 打卡列表:[/src/components/checkin/CheckInList.vue](file:///Users/huyirui/program/itomix/git/mlaj/src/components/checkin/CheckInList.vue)
1 +# /src/components 组件目录索引
2 +
3 +## 目录划分
4 +
5 +| 目录 | 代表组件 | 说明 |
6 +| --- | --- | --- |
7 +| activity/ | ActivityCard.vue、ActivityApplyHistoryPopup.vue | 活动卡片、报名/历史相关弹窗 |
8 +| calendar/ | CollapsibleCalendar.vue、TaskCalendar.vue | 日历与任务日历组件 |
9 +| checkin/ | CheckInDialog.vue、CheckInList.vue、CheckinCard.vue、UploadVideoPopup.vue | 打卡/作业相关组件(弹窗、列表、卡片、上传) |
10 +| common/ | ConfirmDialog.vue、GradientHeader.vue、SearchBar.vue、UserAgreement.vue | 通用基础组件(确认、头部、搜索、协议) |
11 +| count/ | AddTargetDialog.vue、CheckinTargetList.vue、postCountModel.vue | 计数型打卡相关组件 |
12 +| courses/ | CourseCard.vue、CourseList.vue、LiveStreamCard.vue、ReviewPopup.vue | 课程展示与列表、直播卡片、评价弹窗等 |
13 +| effects/ | FrostedGlass.vue、StarryBackground.vue | 视觉效果组件 |
14 +| homePage/ | FeaturedCoursesSection.vue、LatestActivitiesSection.vue | 首页区块组件(精选/活动/推荐等) |
15 +| infoEntry/ | formPage.vue | 信息录入相关组件 |
16 +| layout/ | AppLayout.vue、BottomNav.vue | 页面布局与底部导航 |
17 +| media/ | AudioPlayer.vue、VideoPlayer.vue、PdfPreview.vue、OfficeViewer.vue | 音视频播放器与文档预览 |
18 +| payment/ | WechatPayment.vue | 微信支付相关组件 |
19 +| poster/ | RecallPoster.vue、SharePoster.vue | 海报生成与分享相关组件 |
20 +| studyDetail/ | StudyCatalogPopup.vue、StudyCommentsSection.vue、StudyMaterialsPopup.vue | 学习详情页的弹窗与评论区 |
21 +| teacher/ | TaskFilter.vue、TaskCascaderFilter.vue | 教师端筛选与任务相关组件 |
22 +
23 +## 备注
24 +
25 +- 历史遗留目录:[/src/layouts](file:///Users/huyirui/program/itomix/git/mlaj/src/layouts)[/src/components/layout](file:///Users/huyirui/program/itomix/git/mlaj/src/components/layout) 并存,建议后续合并归一