docs: 新增项目文档并重构README结构
将原README中的详细内容拆分为多个文档,提升可维护性 - 新增docs/COMPONENTS.md:组件目录索引 - 新增docs/CHANGELOG.md:功能更新记录 - 新增docs/ARCHITECTURE.md:架构实现与工程配置 - 重构README.md为项目概览与快速索引
Showing
4 changed files
with
163 additions
and
0 deletions
This diff is collapsed. Click to expand it.
docs/ARCHITECTURE.md
0 → 100644
| 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 | +``` |
docs/CHANGELOG.md
0 → 100644
| 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) |
docs/COMPONENTS.md
0 → 100644
| 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) 并存,建议后续合并归一 |
-
Please register or login to post a comment