Hooke / mlaj

Go to a project
Toggle navigation Toggle navigation pinning
hookehuyr
a8d3041b 1 parent 6829003b

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

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