Hooke / mlaj

Go to a project
Toggle navigation Toggle navigation pinning
hookehuyr
2cbcafc6 1 parent 67aaaf3b

docs: 新增项目文档和开发计划 

添加项目架构、组件索引、变更记录、工作流和开发计划等文档
- ARCHITECTURE.md: 系统架构与工程配置说明
- COMPONENTS.md: 组件目录索引与说明
- CHANGELOG.md: 功能更新记录
- 工作流.md: 开发工作流程指南
- 暂存用户打卡信息.md: 草稿功能详细规划
- 26.1.26新功能开发计划.md: 打卡互动功能规划
- TODO/26.1.26新功能.md: 功能开发清单
Expand all
Inline Side-by-side
Showing 7 changed files with 396 additions and 0 deletions
# 架构实现与工程配置
## 入口与初始化
- 应用入口：[/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 过长。后续新增变更建议追加在文件顶部。
## 2026-01-26 13:40:00
- 优化打卡卡片组件(CheckinCard)：
- 增加长文本折叠功能：内容超过5行自动显示省略号，并提供“全文/收起”切换按钮
- 增加多附件Tab切换功能：当同时存在多种附件（图片、视频、音频）时，使用 Tab 标签页切换展示，避免页面过长
## 2026-01-26 11:43:00
- 新增草稿恢复时的作业有效性校验：若草稿对应的作业已失效（不在当前任务列表中），则弹窗提示并自动清理该草稿
## 2026-01-25 19:28:00
- 优化项目配置：从 git 版本控制中移除以下文件夹的跟踪，以避免将开发工具配置和生成的文档提交到远程仓库：
- `.claude`
- `.cursor`
- `.specify`
- `.trae`
- `.github`
- `docs`
## 2026-01-25
- 新增「暂存用户打卡信息」开发规划：[/docs/plan/暂存用户打卡信息.md](file:///Users/huyirui/program/itomix/git/mlaj/docs/plan/%E6%9A%82%E5%AD%98%E7%94%A8%E6%88%B7%E6%89%93%E5%8D%A1%E4%BF%A1%E6%81%AF.md)
- 完成「暂存用户打卡信息」功能开发
- 核心逻辑：[/src/composables/useCheckinDraft.js](file:///Users/huyirui/program/itomix/git/mlaj/src/composables/useCheckinDraft.js)
- 页面集成：[/src/views/checkin/CheckinDetailPage.vue](file:///Users/huyirui/program/itomix/git/mlaj/src/views/checkin/CheckinDetailPage.vue)
- 支持自动保存、过期清理、恢复提示
- 修复打卡详情页 `countValue` 初始化顺序导致的 ReferenceError 报错
- 修复附件上传成功后未保存 URL 导致草稿恢复后无法预览的问题
- 优化文件 URL 获取逻辑：移除硬编码默认域名，优先使用接口返回的 URL 或 src，仅在有域名信息时拼接 URL
## 打卡详情页重构（/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/components/layout](file:///Users/huyirui/program/itomix/git/mlaj/src/components/layout)，已移除 /src/layouts
新功能开发list(在.env加上配置开关控制下面设计到的功能点, 比如是否开启置顶功能,开启点评打卡, 开启打卡海报,开启点评列表):
入口页IndexCheckInPage涉及功能
- CheckinCard组件 <#footer-right> 3个点的缩略显示, 点击后从底部弹出vant的ActionSheet组件, 面板有置顶和点评两个选项.
1. 置顶的功能, 使用图标back-top, 点击图标的时候弹出确认弹窗, 确认后调用接口置顶帖子.
2. 点评打卡作业的功能, 使用图标comment, 点击图标的时候弹出确认弹窗, 确认后调用接口点评打卡作业. 评论弹框做成一个单独的组件以后扩展.
3. 海报功能, 使用图标share, 可以参考SharePoster组件的实现, 新增一个组件打卡海报, 这个组件最大的不同就是可能生成的图片是一张长图, 如果超过屏幕高度, 用户可以滑动查看. 现在内容和字段还不确定, 等确定了再实现可以先规划.
- 显示点评列表功能, 在CheckinCard组件里面, 需要新增一个组件专门显示用户点评打卡的列表. 类似于朋友圈下面的评论列表, 放在CheckinCard组件的下面.
This diff is collapsed. Click to expand it.
# 暂存用户打卡信息
## 背景
用户在“提交作业/打卡”页面输入了较长文字并上传了媒体，但在未点击提交时被中断（误触返回、微信进程被系统回收、来电/切后台等），再次进入页面内容丢失，导致体验断裂。
本规划目标是在不改动后端接口的前提下，在前端提供“草稿暂存（文本 + 已上传媒体信息）”能力，支持一周内自动过期清理，并在用户再次进入时提示恢复或删除。
涉及页面与核心逻辑参考：
- 打卡提交页：[CheckinDetailPage.vue](file:///Users/huyirui/program/itomix/git/mlaj/src/views/checkin/CheckinDetailPage.vue)
- 打卡核心逻辑：[useCheckin.js](file:///Users/huyirui/program/itomix/git/mlaj/src/composables/useCheckin.js)
- 环境变量约定：[.env](file:///Users/huyirui/program/itomix/git/mlaj/.env)
## 需求拆解（逐条对齐）
1. 缓存最多保存一周：写入时记录 saved_at，读写时执行过期清理（>7天删除）。
2. 用户提交后清空缓存：提交成功（code===1）后删除对应草稿。
3. 进入页面若存在未完成信息：弹框提示“继续/删除”，继续则回填，删除则清空。
4. 功能开关放到 .env：新增 VITE_CHECKIN_DRAFT_CACHE（0/1），默认建议 1（也可先默认 0，灰度开启）。
## 范围与不做项（第一版）
- 覆盖：文字内容、已上传成功的媒体（含 url/meta_id/file_type/name）。
- 不覆盖：未上传完成的 File/Blob（localStorage 无法可靠持久化；要支持需 IndexedDB 存 Blob，复杂度与风险较高）。
- 编辑模式（route.query.status===edit）：第一版建议默认不启用草稿恢复，避免与“编辑回显（来自后端）”冲突；若要覆盖编辑场景，采用独立 key（见“扩展”）。
## 关键设计
### 1) 存储介质
- 使用 localStorage：实现成本低，满足“一周”与“断网/切后台后仍可恢复”。
- 数据量控制：只存“已上传成功”的附件元数据；不存 File 本体。
### 2) 草稿 Key 设计（避免串号）
建议 key 包含用户与作业上下文，确保不同用户/不同作业互不影响：
- 前缀：CHECKIN_DRAFT_V1
- 维度：user_id、task_id、date、task_type、status
示例：
- CHECKIN_DRAFT_V1:{user_id}:{task_id}:{date}:{task_type}:{status}
其中：
- user_id：来自 currentUser（contexts/auth.js 本地持久化）
- task_id/date/task_type/status：来自路由 query（CheckinDetailPage 已使用 route.query.task_id/date/task_type/status）
### 3) 数据结构（建议）
```json
{
"version": 1,
"saved_at": 1730000000000,
"expires_at": 1730000000000,
"context": {
"user_id": "123",
"task_id": "456",
"date": "2026-01-25",
"task_type": "upload",
"status": "create"
},
"payload": {
"message": "...",
"active_type": "image",
"subtask_id": "789",
"file_list": [
{
"meta_id": "xxx",
"url": "https://...",
"name": "a.jpg",
"file_type": "image"
}
],
"count": {
"gratitude_count": 1,
"gratitude_form_list": []
}
}
}
```
说明：
- file_list：仅保存 useCheckin.afterRead 上传成功后写入的字段（item.status===done 且 meta_id 存在）。
- count：来源于 CheckinDetailPage 的 selectedTargets/countValue（第一版可以先不存，或存但不影响非 count 类型）。
### 4) 触发保存的时机（自动暂存）
- 文本变化：watch(message) debounce 500ms 保存。
- 附件变化：watch(fileList) 深度监听 debounce 500ms 保存（仅保存 done 项）。
- 作业选择变化：watch(selectedTaskValue) debounce 200ms 保存。
- 页面离开兜底：beforeRouteLeave 或 window.pagehide/visibilitychange 时强制保存一次（避免最后一次变更没落盘）。
落盘时机要遵循开关：VITE_CHECKIN_DRAFT_CACHE === '1' 才启用。
### 5) 弹框提示与回填流程
进入 [CheckinDetailPage.vue](file:///Users/huyirui/program/itomix/git/mlaj/src/views/checkin/CheckinDetailPage.vue)（且非 edit 模式）时：
1. 读取 key 对应草稿；若不存在或已过期，直接进入正常流程。
2. 若存在草稿且 payload 有实际内容（message 有非空或 file_list 非空）：弹框提示。
3. 用户选择：
- 继续：将草稿回填到 message / activeType / fileList / selectedTaskValue（以及 count 数据如启用），并立刻再保存一次（避免回填后又丢）。
- 删除：删除草稿并保持空表单。
弹框建议用 showConfirmDialog（Vant 4），取消分支需要 catch，避免控制台出现 Uncaught (in promise) cancel（Vant 文档：showConfirmDialog.then/catch）[3](https://develop365.gitlab.io/vant/zh-CN/dialog/)。
### 6) 清理策略（“定期清除一周前”）
采用“惰性清理 + 低频全量清理”组合：
- 惰性清理：每次读/写草稿时，如果 expires_at < now 则删除。
- 低频全量：进入打卡页时，扫描 localStorage 中以 CHECKIN_DRAFT_V1: 开头的 key，删除所有过期项。
说明：localStorage 没有内建 TTL，必须业务侧维护 expires_at。
### 7) 提交成功后清空
清空动作必须绑定到“真正提交成功”之后：
- 建议在 useCheckin.onSubmit 中，当 add/edit API 返回 code===1 且后续逻辑准备 router.back 前，删除对应 key。
这样可覆盖“不同入口页复用 onSubmit”以及“提交后立即返回上一页”的场景。
## 开发步骤（可落地的实现顺序）
### 第 0 步：验证手段先行（TDD）
新增 Vitest 用例，先定义以下可验证点：
- 写入后能读取同一 key 的草稿；过期后读取返回空且自动删除。
- 仅保存 status===done 且含 meta_id 的附件。
- 清理函数能删除所有过期 key，不误删其他业务 localStorage。
- 提交成功时会调用清理（可通过 mock API 返回 code===1 验证）。
### 第 1 步：抽离草稿存储模块
位置建议：src/utils/checkinDraftCache.js（纯函数、无 UI 依赖）。
对外 API（示例）：
- is_enabled(): boolean（读取 env + 可选 query override）
- build_key(context): string
- save_draft(key, draft)
- read_draft(key): draft|null（含 TTL 处理）
- clear_draft(key)
- cleanup_expired(prefix)
### 第 2 步：在 CheckinDetailPage 接入“检测 + 弹框 + 回填”
- onMounted：初始化后读取草稿并弹框。
- 回填时机：建议在任务详情/子任务列表加载完成后再回填 selectedTaskValue，避免 option 未加载导致显示异常。
### 第 3 步：在 CheckinDetailPage 接入“自动保存”
- 对 message/fileList/selectedTaskValue/countValue/selectedTargets 建立 watch + debounce。
- 页面离开事件兜底（pagehide/visibilitychange）。
### 第 4 步：在 useCheckin.onSubmit 接入“成功清理”
- onSubmit 成功分支清除草稿。
- 失败分支不清除，保留草稿以便重试。
## 边界条件与遗漏点梳理（建议补齐）
1. 多用户切换：key 必须含 user_id，否则会串草稿。
2. 多任务并存：key 必须含 task_id/date/task_type，否则会在不同作业之间误恢复。
3. 附件未上传完成：
- 仅保存已上传成功的项；如果用户退出时仍有 uploading 项，恢复后无法找回该 File。
- 可在保存时统计未保存数量，并在恢复弹框里追加提示“有 X 个附件上传未完成未被暂存”。
4. 关闭开关后的行为：
- 关闭后不再读/写；建议仍执行一次 cleanup_expired，避免历史堆积。
5. 版本升级/数据结构变更：draft.version 不匹配时丢弃并清除，避免解析异常。
6. localStorage 配额：图片多但只存 url/meta_id 一般不会超；仍需 try/catch JSON 与 setItem 异常。
7. 编辑模式：
- 要支持“编辑中断恢复”，建议 key 加 post_id 维度，并在 initEditData 回显后再弹框询问是否覆盖当前表单。
## 环境变量（规划）
在 [.env](file:///Users/huyirui/program/itomix/git/mlaj/.env) 增加：
- VITE_CHECKIN_DRAFT_CACHE = 1
约定：
- '1' 开启，'0' 关闭
- 可选增加 URL 覆盖用于灰度测试：?enable_draft=1 / ?enable_draft=0（模式同 VITE_CHECKIN_MULTI_ATTACHMENT）
1. 确定一个功能或者方案, 比如打卡, 请假, 报销等. 把相应的逻辑框架描述给agent, 让它查漏补缺之后, 完善逻辑.
2. 生成计划文档写入plan里面, 之后拿着plan去生成代码.
3. 生成的代码如果有问题, 顶多尝试一次, 不行撤回生成. 或者换大模型生成.
4. 项目规则如果能复用的留意下次其他项目使用.
5. 项目规则似乎是每次必执行, 比个人规则好像更强制一点.
6. 有些规则如果是必要的, 可以在项目规则里面写.