hookehuyr

feat(checkin): 新增打卡草稿缓存功能

- 新增 useCheckinDraft composable,支持草稿的自动保存、恢复和清理
- 在打卡详情页集成草稿功能:自动保存表单内容,进入时提示恢复
- 优化文件上传逻辑,确保草稿恢复后能正确预览附件
- 修复 countValue 初始化顺序导致的 ReferenceError
- 更新环境变量配置,添加 VITE_CHECKIN_DRAFT_CACHE 开关
- 完善相关文档和测试用例
......@@ -18,3 +18,6 @@ VITE_APPID=微信appID
# 是否开启多附件功能
VITE_CHECKIN_MULTI_ATTACHMENT = 0
# 是否开启打卡草稿缓存功能
VITE_CHECKIN_DRAFT_CACHE = 0
......
......@@ -97,7 +97,7 @@ src/
- **统一打卡页** (`/checkin/detail`):
- 支持类型:文本、图片、视频、音频、计数打卡(如感恩日记)。
- 核心逻辑:`useCheckin` 封装上传(七牛云+Hash秒传)、校验、提交逻辑。
- 交互:支持补卡、编辑已提交内容、选择打卡对象(计数模式)。
- 交互:支持补卡、编辑已提交内容、选择打卡对象(计数模式);支持自动保存草稿与断点恢复
- **互动社区**:打卡动态流,支持点赞、评论、查看他人作品。
- **教师端** (`/teacher`):
- **作业管理**:发布新作业,查看作业列表与详情(完成率/出勤率统计)。
......
......@@ -2,6 +2,17 @@
说明:该章节从 README 迁移到本文件,避免 README 过长。后续新增变更建议追加在文件顶部。
## 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)
- 统一了文本、媒体上传和计数打卡的入口
......
用户反馈:
# 暂存用户打卡信息
## 背景
用户在“提交作业/打卡”页面输入了较长文字并上传了媒体,但在未点击提交时被中断(误触返回、微信进程被系统回收、来电/切后台等),再次进入页面内容丢失,导致体验断裂。
本规划目标是在不改动后端接口的前提下,在前端提供“草稿暂存(文本 + 已上传媒体信息)”能力,支持一周内自动过期清理,并在用户再次进入时提示恢复或删除。
涉及页面与核心逻辑参考:
- 打卡提交页:[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)
......@@ -179,7 +179,7 @@ describe('useCheckin 提交兼容', () => {
await onSubmit({ subtask_id: 's1' })
expect(addUploadTaskAPI).toHaveBeenCalledTimes(0)
expect(showToast).toHaveBeenCalledWith('当前接口暂不支持多类型附件,请分别提交')
expect(showToast).toHaveBeenCalledWith('当前接口暂不支持多类型附件,请删除其他类型附件之后再提交')
})
it('开启多附件开关时允许 mixed files 提交', async () => {
......
import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest'
import { useCheckinDraft } from '../useCheckinDraft'
// Mock localStorage
const localStorageMock = (() => {
let store = {}
return {
getItem: vi.fn(key => store[key] || null),
setItem: vi.fn((key, value) => { store[key] = value.toString() }),
removeItem: vi.fn(key => { delete store[key] }),
clear: vi.fn(() => { store = {} }),
key: vi.fn(i => Object.keys(store)[i] || null),
get length() { return Object.keys(store).length }
}
})()
global.localStorage = localStorageMock
describe('useCheckinDraft', () => {
beforeEach(() => {
localStorageMock.clear()
vi.clearAllMocks()
// Mock Date.now
vi.useFakeTimers()
})
afterEach(() => {
vi.useRealTimers()
})
const mockContext = {
user_id: 'u123',
task_id: 't456',
date: '2026-01-25',
task_type: 'upload',
status: 'create'
}
const {
build_key,
save_draft,
read_draft,
clear_draft,
cleanup_expired
} = useCheckinDraft()
it('should generate correct key', () => {
const key = build_key(mockContext)
expect(key).toBe('CHECKIN_DRAFT_V1:u123:t456:2026-01-25:upload:create')
})
it('should save and read draft', () => {
const key = build_key(mockContext)
const payload = { message: 'hello', file_list: [] }
save_draft(key, payload)
const saved = read_draft(key)
expect(saved).not.toBeNull()
expect(saved.payload).toEqual(payload)
expect(saved.version).toBe(1)
})
it('should return null for expired draft', () => {
const key = build_key(mockContext)
const payload = { message: 'expired' }
save_draft(key, payload)
// Advance time by 8 days (TTL is 7 days)
vi.setSystemTime(Date.now() + 8 * 24 * 60 * 60 * 1000)
const saved = read_draft(key)
expect(saved).toBeNull()
// Should also remove from storage
expect(localStorage.getItem(key)).toBeNull()
})
it('should cleanup only expired drafts', () => {
const ctx1 = { ...mockContext, task_id: 't1' }
const ctx2 = { ...mockContext, task_id: 't2' }
const key1 = build_key(ctx1)
const key2 = build_key(ctx2)
const otherKey = 'OTHER_KEY'
save_draft(key1, { msg: 'expire soon' })
save_draft(key2, { msg: 'keep' })
localStorage.setItem(otherKey, 'some value')
// Set key1 to expire
// We need to manually manipulate storage to simulate different saved_at
// Or just save key1, advance time, save key2
// Reset storage and start over
localStorageMock.clear()
// Save key1
save_draft(key1, { msg: 'old' })
// Advance 8 days
const eightDays = 8 * 24 * 60 * 60 * 1000
vi.setSystemTime(Date.now() + eightDays)
// Save key2 (fresh)
save_draft(key2, { msg: 'new' })
// Other key
localStorage.setItem(otherKey, 'val')
// Run cleanup
cleanup_expired()
expect(localStorage.getItem(key1)).toBeNull()
expect(localStorage.getItem(key2)).not.toBeNull()
expect(localStorage.getItem(otherKey)).toBe('val')
})
it('should only save "done" files with meta_id', () => {
const key = build_key(mockContext)
const files = [
{ status: 'done', meta_id: 'm1', name: 'f1' },
{ status: 'uploading', name: 'f2' },
{ status: 'failed', name: 'f3' },
{ status: 'done', name: 'f4' } // no meta_id
]
save_draft(key, { file_list: files })
const saved = read_draft(key)
expect(saved.payload.file_list).toHaveLength(1)
expect(saved.payload.file_list[0].meta_id).toBe('m1')
})
})
......@@ -205,9 +205,29 @@ export function useCheckin() {
hash: md5
})
// 根据当前 activeType 或文件类型判断
let currentFileType = activeType.value
if (!['image', 'video', 'audio'].includes(currentFileType)) {
// 如果 activeType 不是这三种(比如 text),尝试从文件类型推断
if (file.file.type.startsWith('image/')) currentFileType = 'image'
else if (file.file.type.startsWith('video/')) currentFileType = 'video'
else if (file.file.type.startsWith('audio/')) currentFileType = 'audio'
else currentFileType = 'file' // 默认
}
// 文件已存在,直接返回
if (tokenResult.data) {
return tokenResult.data
const data = tokenResult.data
let finalUrl = data.url || data.src
// 如果没有URL但有filekey,尝试手动拼接
if (!finalUrl && (data.filekey || data.key || data.filepath) && tokenResult.domain) {
const key = data.filekey || data.key || data.filepath
const domain = tokenResult.domain
const cleanDomain = domain.endsWith('/') ? domain : domain + '/'
const cleanKey = key.startsWith('/') ? key.slice(1) : key
finalUrl = cleanDomain + cleanKey
}
return { ...data, url: finalUrl, file_type: currentFileType } // 确保返回 file_type
}
// 新文件上传
......@@ -215,16 +235,6 @@ export function useCheckin() {
const suffix = /.[^.]+$/.exec(file.file.name) || ''
let fileName = ''
// 根据当前 activeType 或文件类型判断
let currentFileType = activeType.value
if (!['image', 'video', 'audio'].includes(currentFileType)) {
// 如果 activeType 不是这三种(比如 text),尝试从文件类型推断
if (file.file.type.startsWith('image/')) currentFileType = 'image'
else if (file.file.type.startsWith('video/')) currentFileType = 'video'
else if (file.file.type.startsWith('audio/')) currentFileType = 'audio'
else currentFileType = 'file' // 默认
}
if (currentFileType === 'image') {
fileName = `mlaj/upload/checkin/${currentUser.value.mobile}/img/${md5}${suffix}`
} else {
......@@ -252,7 +262,18 @@ export function useCheckin() {
}
const { data } = await saveFileAPI(saveData)
return { ...data, file_type: currentFileType }
// 确保返回URL,如果后端未返回则手动拼接
let finalUrl = data?.url || data?.src
if (!finalUrl && tokenResult.domain) {
// 优先使用接口返回的域名
const domain = tokenResult.domain
const cleanDomain = domain.endsWith('/') ? domain : domain + '/'
const cleanKey = uploadResult.filekey.startsWith('/') ? uploadResult.filekey.slice(1) : uploadResult.filekey
finalUrl = cleanDomain + cleanKey
}
return { ...data, url: finalUrl, file_type: currentFileType }
}
}
return null
......@@ -425,6 +446,7 @@ export function useCheckin() {
/**
* 提交打卡
* @param {Object} extraData - 额外提交数据
* @param {Function} onSuccess - 提交成功回调 (新增)
* @description
* 提交流程:
* 1. 表单校验(内容长度、是否上传文件)
......@@ -433,7 +455,7 @@ export function useCheckin() {
* 4. 调用对应 API (addUploadTaskAPI / editUploadTaskInfoAPI)
* 5. 成功后设置 sessionStorage 刷新标记并返回上一页
*/
const onSubmit = async (extraData = {}) => {
const onSubmit = async (extraData = {}, onSuccess = null) => {
if (uploading.value) return
// 表单验证
......@@ -568,6 +590,11 @@ export function useCheckin() {
if (result?.code === 1) {
showToast('提交成功')
// 执行成功回调(如清理草稿)
if (typeof onSuccess === 'function') {
onSuccess()
}
// 设置刷新标记,用于列表页更新数据
const refreshType = route.query.status === 'edit' ? 'edit' : 'add';
sessionStorage.setItem('checkin_refresh_flag', refreshType);
......
/**
* 打卡草稿缓存逻辑封装
* @module useCheckinDraft
* @description
* 提供打卡草稿的增删改查能力,基于 localStorage。
*
* 核心功能:
* 1. 构建唯一的缓存 Key(用户+任务+日期+状态维度)。
* 2. 保存草稿:自动过滤未完成的附件,只存 meta_id/url 等元数据。
* 3. 读取草稿:支持过期检查(TTL 7天)。
* 4. 自动清理:支持惰性清理和全量扫描清理过期项。
*
* 使用场景:
* - CheckinDetailPage 自动保存与恢复。
*/
import { useRoute } from 'vue-router'
export function useCheckinDraft() {
const DRAFT_PREFIX = 'CHECKIN_DRAFT_V1'
const TTL_MS = 7 * 24 * 60 * 60 * 1000 // 7天过期
/**
* 判断功能是否开启
* @returns {boolean}
*/
const is_enabled = () => {
// 支持 URL 参数覆盖 (CheckinDetailPage 会用到 route,但此处为纯函数逻辑,依赖调用方传入或在组件内判断)
// 这里仅读取环境变量
// 实际使用时建议结合 route.query.enable_draft 判断
return import.meta.env.VITE_CHECKIN_DRAFT_CACHE === '1'
}
/**
* 构建缓存 Key
* @param {Object} context
* @param {string} context.user_id 用户ID
* @param {string} context.task_id 任务ID
* @param {string} context.date 日期
* @param {string} context.task_type 任务类型
* @param {string} context.status 状态 (create/edit)
* @returns {string} Key
*/
const build_key = ({ user_id, task_id, date, task_type, status }) => {
// 确保所有字段都存在,避免生成 undefined
const parts = [
user_id || 'guest',
task_id || 'default',
date || 'nodate',
task_type || 'default',
status || 'create'
]
return `${DRAFT_PREFIX}:${parts.join(':')}`
}
/**
* 保存草稿
* @param {string} key 缓存Key
* @param {Object} payload 业务数据
* @param {string} payload.message 文本
* @param {Array} payload.file_list 文件列表
* @param {string} payload.active_type 当前类型
* @param {string|number} payload.subtask_id 子任务ID
* @param {Array} payload.selected_task_value 选中的任务值
* @param {Object} payload.count 计数打卡数据
*/
const save_draft = (key, payload) => {
if (!key) return
try {
// 过滤附件:只保存已上传成功且有 meta_id 的
const validFiles = (payload.file_list || []).filter(item =>
item.status === 'done' && item.meta_id
).map(item => ({
meta_id: item.meta_id,
url: item.url,
name: item.name,
file_type: item.file_type
}))
const data = {
version: 1,
saved_at: Date.now(),
expires_at: Date.now() + TTL_MS,
payload: {
...payload,
file_list: validFiles
}
}
localStorage.setItem(key, JSON.stringify(data))
console.log(`[草稿缓存] 已保存: ${key}`, data.payload)
} catch (e) {
console.error('[草稿缓存] 保存失败:', e)
}
}
/**
* 读取草稿
* @param {string} key 缓存Key
* @returns {Object|null} 草稿数据或null
*/
const read_draft = (key) => {
if (!key) return null
try {
const raw = localStorage.getItem(key)
if (!raw) return null
const data = JSON.parse(raw)
// 检查版本
if (data.version !== 1) {
console.warn('[草稿缓存] 版本不匹配,丢弃旧数据')
clear_draft(key)
return null
}
// 检查过期
if (data.expires_at && Date.now() > data.expires_at) {
console.log('[草稿缓存] 数据已过期,自动清理')
clear_draft(key)
return null
}
return data
} catch (e) {
console.error('[草稿缓存] 读取失败:', e)
return null
}
}
/**
* 清除指定草稿
* @param {string} key
*/
const clear_draft = (key) => {
if (!key) return
localStorage.removeItem(key)
console.log(`[草稿缓存] 已清除: ${key}`)
}
/**
* 清理所有过期草稿
*/
const cleanup_expired = () => {
try {
const keysToRemove = []
const now = Date.now()
for (let i = 0; i < localStorage.length; i++) {
const key = localStorage.key(i)
if (key && key.startsWith(DRAFT_PREFIX)) {
try {
const raw = localStorage.getItem(key)
const data = JSON.parse(raw)
if (data.expires_at && now > data.expires_at) {
keysToRemove.push(key)
}
} catch (e) {
// 解析失败的脏数据也清理掉
keysToRemove.push(key)
}
}
}
keysToRemove.forEach(key => {
localStorage.removeItem(key)
console.log(`[草稿缓存] 自动清理过期项: ${key}`)
})
} catch (e) {
console.error('[草稿缓存] 批量清理失败:', e)
}
}
return {
is_enabled,
build_key,
save_draft,
read_draft,
clear_draft,
cleanup_expired
}
}
This diff is collapsed. Click to expand it.