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

添加项目架构、组件索引、变更记录、工作流和开发计划等文档
- ARCHITECTURE.md: 系统架构与工程配置说明
- COMPONENTS.md: 组件目录索引与说明
- CHANGELOG.md: 功能更新记录
- 工作流.md: 开发工作流程指南
- 暂存用户打卡信息.md: 草稿功能详细规划
- 26.1.26新功能开发计划.md: 打卡互动功能规划
- TODO/26.1.26新功能.md: 功能开发清单

+# 架构实现与工程配置
+
+## 入口与初始化
+
+- 应用入口：[/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. 有些规则如果是必要的, 可以在项目规则里面写.