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: 功能开发清单
Inline Side-by-side
Showing 7 changed files with 690 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组件的下面.
# 26.1.26 新功能开发计划
## 背景
为了增强用户在打卡列表的互动性和管理能力，需要在打卡卡片（CheckinCard）上增加更多操作选项，包括置顶、评论、海报分享以及展示评论列表。这些功能将通过环境变量开关进行控制，以便按需开启。
## 需求拆解
1. **全局功能开关**：在 `.env` 文件中通过变量控制各功能的开启/关闭。
2. **置顶功能 (Top)**：允许将特定打卡内容置顶。
3. **评论/评论功能 (Comment)**：允许对打卡内容进行评论（评论）。
4. **打卡海报 (Poster)**：生成包含打卡内容的长图海报，支持分享。
5. **评论列表 (Comment List)**：在打卡卡片下方显示该打卡的评论/评论记录。
## 环境变量规划
在 `.env` 中增加以下开关（默认 '0' 关闭，'1' 开启）：
- `VITE_FEATURE_CHECKIN_TOP=1` (置顶功能)
- `VITE_FEATURE_CHECKIN_COMMENT=1` (评论功能)
- `VITE_FEATURE_CHECKIN_POSTER=1` (海报功能)
- `VITE_FEATURE_CHECKIN_COMMENT_LIST=1` (评论列表显示)
## 详细设计与逻辑流程
### 1. 入口改造 (CheckinCard)
- **位置**：`CheckinCard` 组件底部右侧操作区（原点赞/更多按钮处）。
- **交互**：点击“...”图标，从底部弹出 `ActionSheet`（Vant 组件）。
- **菜单项**：
- **置顶**：仅当 `VITE_FEATURE_CHECKIN_TOP=1` 时显示。若已置顶，显示“取消置顶”。
- **评论**：仅当 `VITE_FEATURE_CHECKIN_COMMENT=1` 时显示。
- **海报**：仅当 `VITE_FEATURE_CHECKIN_POSTER=1` 时显示。
### 2. 置顶功能 (Top)
- **逻辑**：
1. 点击“置顶”菜单。
2. 弹出确认框 `showConfirmDialog`：“确定要置顶这条打卡吗？”。
3. 用户确认 -> 调用 API `teacherPinCheckinAPI(id)`。
4. API 成功 -> Toast “置顶成功” -> 更新列表数据（将该项标记为置顶，或刷新列表）。
5. 若已置顶 -> 点击“取消置顶” -> 确认 -> API `teacherUnpinCheckinAPI(id)` -> Toast “取消置顶成功” -> 更新状态。
- **要点**：这个功能属于教师端功能, 需要先判断这个用户的userinfo是否是老师, 使用is_teacher字段判断, 没有权限则不显示置顶菜单.
- **API**：
- `teacherPinCheckinAPI` 老师置顶打卡 (参数: `checkin_id`)
- `teacherUnpinCheckinAPI` 老师取消置顶打卡 (参数: `checkin_id`)
### 3. 评论功能 (Comment)
- **逻辑**：
1. 点击"评论"菜单。
2. 弹出 **评论输入弹窗**（新建组件 `CheckinCommentDialog`）。
- 包含：文本输入框（Textarea）、表情选择器按钮。
- **表情选择器**：点击表情图标，从底部弹出表情面板，支持常用 Emoji 表情符号（😊❤️👍🎉等）。
- 输入验证：纯文本评论至少 5 个字符，允许表情符号作为补充。
- 按钮：取消、提交。
3. 点击表情图标 -> 弹出表情选择面板（底部 Popup）-> 选择表情 -> 插入到光标位置。
4. 输入内容（文本 + 表情）-> 点击提交。
5. 调用 API `commentCheckin(id, content)`。
6. API 成功 -> Toast "评论成功" -> 关闭弹窗 -> 刷新该打卡的评论列表。
- **要点**：
- 这个功能属于用户端功能, 只能在`/checkin/index`打卡主页上的打卡卡片上显示出来。
- 表情选择器技术方案：自定义 Emoji 列表。
- 表情数据：使用原生 Unicode Emoji，无需图片资源，体积小且兼容性好。
- 常用表情建议：😊😂❤️👍🎉✨🙏💪🔥💯😍👏🤝🌟🎁
- **组件**：`CheckinCommentDialog.vue` (基于 Vant Popup 封装，底部弹出)。
- **API (需 Mock/确认)**：
- `POST /checkin/comment` (发表评论，参数: `checkin_id`, `content`)
### 4. 海报功能 (Poster)
- **逻辑**：
1. 点击“海报”菜单。
2. 弹出 **海报预览组件** (`CheckinPoster`，参考 `SharePoster`)。
3. **渲染内容**：
- 用户信息（头像、昵称）。
- 打卡内容（文本、图片缩略图）。
- 底部二维码(打卡主页的网址自动生成)。
- *注：需支持长图，若内容过长，通过滚动查看，生成图片时需完整截取。*
4. **生成图片**：使用 `html2canvas` 或 `html-to-image` 将 DOM 转为图片。
5. 展示生成的图片，提示“长按保存”。
- **组件**：`CheckinPoster.vue`。
- **技术点**：处理跨域图片、长图渲染、字体加载。
### 5. 评论列表 (Comment List)
- **位置**：`CheckinCard` 组件内部下方。
- **显示条件**：`VITE_FEATURE_CHECKIN_COMMENT_LIST=1` 且 `post.comments` 长度 > 0。
- **样式**：参考朋友圈评论区（灰色背景，每行 `用户: 内容`）。
- **逻辑**：
- 渲染评论列表，支持 Emoji 表情符号的显示。
- 列车最多展示5条评论, 超过5条的评论需要点击"查看全部"才能看到.
- 用户自己评论的右侧需要显示一个删除图标, 点击图标弹出确认框, 确认后调用删除接口删除该条评论.
- **交互与操作**：
- **回复**：点击某一条评论，从屏幕底部弹出输入框（类似微信朋友圈），键盘自动升起。输入框同样支持表情选择器。输入内容后点击发送，即为回复该条评论。
- 数据结构：使用 `parent_id` 标识父评论，`reply_to_user_id` 标识被回复用户。
- 显示样式：`用户A 回复 用户B: 评论内容`。
- **删除**：点击用户**自己**发布的评论，弹出 `ActionSheet` 或确认框，选项包含"删除"。确认后调用删除接口移除该评论。
- **样式参考**：整体交互逻辑和视觉风格严格参考微信朋友圈。
- **Emoji 渲染**：评论内容中的 Emoji 符号直接使用原生 Unicode 渲染，无需特殊处理。
- **组件**：`CheckinCommentList.vue` (复用 `StudyCommentsSection.vue` 的设计模式)。
- **API (需 Mock/确认)**：
- `GET /checkin/comments` (获取评论列表，参数: `checkin_id`, `page`, `page_size`)
- `POST /checkin/comment` (发表评论，参数: `checkin_id`, `content`)
- `POST /checkin/comment/reply` (回复评论，参数: `checkin_id`, `content`, `parent_id`, `reply_to_user_id`)
- `DELETE /checkin/comment/:id` (删除评论，参数: `comment_id`)
## 开发步骤
### 第 1 步：环境准备与 Mock API
- 在 `.env` 添加开关变量。
- 在 `src/api` 定义相关接口（Top, Comment），前期可使用 Mock 数据验证流程。
### 第 2 步：改造 CheckinCard 菜单
- 引入 `ActionSheet`。
- 根据 Env 开关动态显示菜单项。
- 实现基础点击事件处理。
### 第 3 步：实现置顶逻辑
- 对接置顶/取消置顶 API。
- 添加确认弹窗。
- 处理列表状态更新。
- **置顶视觉标记**：在已置顶的打卡卡片上显示"📌 置顶"标记。
### 第 4 步：实现评论功能与列表
- 创建 `CheckinCommentDialog` 组件。
- 实现 `van-field` 文本输入框（支持多行）。
- **实现表情选择器**：
- 方案选择：自定义 Emoji 面板（不引入额外依赖，使用原生 Unicode Emoji）。
- UI 实现：`van-popup` 底部弹出 + `van-grid` 展示表情符号。
- 交互逻辑：点击表情 -> 插入到输入框光标位置 -> 自动关闭面板。
- 常用表情列表：😊😂❤️👍🎉✨🙏💪🔥💯😍👏🤝🌟🎁😭😡🤔💭😴🎂🌈⭐🌙☀️🌺🌸🍀🎁🎈🎵🎶📱💻⚽🏀🎾🎯🎨🎬📷🎤🎧📚✏️📝💡🔔💬📧📞
- 实现输入验证（文本至少 5 字，表情可作为补充）。
- 在 `CheckinCard` 中引入并调用评论弹窗。
- 创建 `CheckinCommentList` 组件（/components/checkin/CheckinCommentList.vue）。
- 参考 `StudyCommentsSection.vue` 的实现模式。
- 支持评论列表展示（最多 5 条，超过则显示"查看全部"）。
- 支持 Emoji 符号的直接渲染。
- 实现评论回复交互（底部输入框弹出，同样支持表情选择）。
- 实现删除逻辑（仅显示自己评论的删除图标）。
- 对接评论、回复、删除 API 和列表展示数据。
### 第 5 步：实现打卡海报
- 创建 `CheckinPoster` 组件。
- 实现布局（支持长内容）。
- 集成 `html2canvas` 生成逻辑。
- 对接 `CheckinCard` 菜单。
## 边界条件与注意点
1. **权限控制**：
- 置顶功能是否仅管理员可见？（前端暂通过 Env 控制全局，根据用户角色判断）。
- 评论功能是否允许自己评论自己？（需后端确认，前端暂不做限制）。
2. **表情输入处理**：
- **字符计数**：Emoji 符号在某些设备上可能占用 2 个字符位置（代理对），需使用 `Array.from(text).length` 计算真实字符数。
- **输入限制**：限制单条评论最多 200 个字符（包含 Emoji），前端实时提示剩余字数。
- **兼容性**：原生 Unicode Emoji 在 iOS/Android/微信内置浏览器中均能正常显示，无需降级方案。
- **存储**：后端需确保数据库字符集支持 UTF-8 MB4（MySQL 5.5.3+ 的 `utf8mb4`），否则部分 Emoji（如 🎁）会乱码。
3. **海报生成**：
- 图片跨域问题（需配置 `useCORS: true` 且 CDN 支持）。
- 内容过长导致 Canvas 内存溢出（需限制最大高度或分段，第一版暂不考虑极端情况）。
4. **列表更新**：
- 操作后尽量避免全列表刷新，采用本地数据更新（Update Item）以提升体验。
5. **评论回复数据结构**：
- 建议使用扁平化结构（所有评论在同一层级，通过 `parent_id` 关联），便于分页和排序。
- 示例：
```javascript
{
id: 1,
checkin_id: 123,
user_id: 456,
content: "干得漂亮！🎉",
parent_id: 0, // 0 表示一级评论
reply_to_user_id: null, // 一级评论为 null
created_at: "2026-01-26 10:00:00"
}
```
6. **CheckinCard 数据结构扩展**：
- 现有 `post` 对象需要新增以下字段：
```javascript
{
id: 123,
user: { name: "张三", avatar: "..." },
content: "今天完成了100天打卡！",
images: [...],
videoList: [...],
audio: [...],
likes: 10,
is_liked: false,
is_my: true,
// 🆕 新增字段
is_pinned: false, // 是否置顶
pinned_at: null, // 置顶时间
comments_count: 0, // 评论总数（用于列表展示）
comments: [] // 评论列表（最多5条）
}
```
7. **性能优化**：
- **评论列表懒加载**：仅在用户展开"查看全部"时才加载完整评论列表，首屏只加载前 5 条。
- **图片懒加载**：海报生成时使用 `loading="lazy"` 避免一次性加载所有图片。
- **列表虚拟滚动**：如果打卡列表超过 50 条，考虑使用 `van-list` 的虚拟滚动模式。
8. **错误处理**：
- **网络错误**：API 调用失败时，显示 Toast 提示用户，并提供"重试"按钮。
- **并发冲突**：删除评论时，若该评论已被删除，提示"该评论不存在"。
9. **测试计划**：
- **单元测试**：测试 `CheckinCommentDialog` 组件的输入验证、Emoji 插入逻辑。
- **集成测试**：测试评论发表、回复、删除的完整流程。
- **边界测试**：测试 200 字符限制、Emoji 字符计数、空评论提交等边界情况。
- **兼容性测试**：在 iOS Safari、Android Chrome、微信内置浏览器中测试 Emoji 显示。
---
## 待确认事项
### 与后端确认
1. **API 接口**：
- `GET /checkin/comments` - 评论列表接口（是否支持分页？返回数据结构是否包含用户信息？）支持分页, 不包含用户信息.
- `POST /checkin/comment` - 发表评论接口（是否需要敏感词过滤？返回值是什么？）不需要敏感词过滤, 返回值应该是评论ID.
- `POST /checkin/comment/reply` - 回复评论接口（参数是否完整？）参数完整, 包含评论ID, 回复内容, 回复用户ID. 返回值应该是回复评论ID.
- `DELETE /checkin/comment/:id` - 删除评论接口（是否有权限校验？）不需要校验, 列表会返回字段, 判断是否是自己的评论, 如果不是不会显示删除按钮.
- `teacherPinCheckinAPI` / `teacherUnpinCheckinAPI` - 接口已实现.
2. **数据字段**：
- `post.is_pinned` - 置顶标记字段是否存在？
- `post.pinned_at` - 置顶时间字段是否存在？
- `post.comments_count` - 评论数字段是否存在？
- `post.comments` - 评论列表字段是否存在？（预加载前5条）
- `user.is_teacher` - 用户角色字段是否存在于 `localStorage.user_info`？在localStorage的currentUser中有存个人信息
3. **权限控制**：
- 置顶功能：是否仅教师可见？是否有更细粒度的权限控制？仅教师可以置顶打卡.
- 删除评论：是否只能删除自己的评论？教师是否可以删除所有评论？
- 评论功能：是否允许自己评论自己的打卡？允许.
4. **业务规则**：
- 评论字符限制：是 200 字还是其他数量？
- 是否允许发送纯表情评论（无文字）？
- 评论后是否需要通知打卡用户或被回复用户？
- 置顶数量限制：是否限制同时置顶的打卡数量？
### 与产品确认
1. **功能优先级**：
- 4 个功能（置顶、评论、海报、评论列表）的开发优先级是什么？
- 是否需要在第一版就全部完成，还是可以分阶段上线？
2. **交互细节**：
- 置顶的打卡是否需要特殊的视觉标记（如"📌 置顶"标签、置顶图标等）？
- 评论删除是否需要二次确认？（计划中已确认需要）
- 表情选择器是否需要分类（如"笑脸"、"手势"、"动物"等）？
- 海报生成失败时，是否需要降级方案（如显示文字版分享链接）？
---
## 总结
### ✅ 计划完善度评估
**总体评分：9/10** - 开发计划已经非常完善，涵盖了需求、设计、API、边界条件等各个方面。
**优点：**
- ✅ 需求拆解清晰，环境变量开关设计灵活
- ✅ 技术方案成熟可行（表情选择器、评论系统、海报生成）
- ✅ API 设计完整，涵盖增删改查
- ✅ 数据结构设计合理（扁平化评论结构）
- ✅ 边界条件考虑充分（Emoji 字符计数、数据库 utf8mb4）
- ✅ 参考现有代码库，复用性高
- ✅ 开发步骤清晰，循序渐进
- ✅ 性能优化、错误处理、测试计划都已考虑
**需要改进的地方：**
- ⚠️ 部分业务规则需要与后端/产品确认（见"待确认事项"）
- ⚠️ 置顶视觉标记、评论通知等功能细节需要补充
- ⚠️ 错误处理和降级方案可以更详细
### 🎯 建议的开发顺序
1. **第 1 阶段**：置顶功能（最简单，快速验证流程）
2. **第 2 阶段**：评论功能 + 评论列表（核心功能，投入最大）
3. **第 3 阶段**：海报功能（技术难度较高，可最后开发）
### 📝 下一步行动
1. 与后端/产品确认"待确认事项"中的所有问题
2. 确认开发优先级和里程碑节点
3. 开始第 1 阶段开发（置顶功能）
4. 同步准备 API Mock 数据，以便前端独立开发
# 暂存用户打卡信息
## 背景
用户在“提交作业/打卡”页面输入了较长文字并上传了媒体，但在未点击提交时被中断（误触返回、微信进程被系统回收、来电/切后台等），再次进入页面内容丢失，导致体验断裂。
本规划目标是在不改动后端接口的前提下，在前端提供“草稿暂存（文本 + 已上传媒体信息）”能力，支持一周内自动过期清理，并在用户再次进入时提示恢复或删除。
涉及页面与核心逻辑参考：
- 打卡提交页：[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. 有些规则如果是必要的, 可以在项目规则里面写.