Appearance
日常打卡（小程序 · 设计定稿）
状态：P0/P1 已落地（Sys 模块 + 小程序 pages/daily-check-in/*）；库表 mini_daily_check_in_* 已通过 zen:push 同步。
入口：首页九宫格 「常用」（miniapp/src/constants/mobile-shell-local.ts 本地注入）。
约束：与个人记账相同 — miniapp-bookkeeping-user-scope（openid/JWT sub、无 siteId、不跳账号登录页）。
架构：P0 = Sys 内模块，不单独微服务（见 microservice-split-decision.md）。
产品定稿
| 项 | 约定 |
|---|---|
| 名称 | 日常打卡 |
| 核心 | 用户 自定义类型；一日一类可多条 记录 |
| 统计优先级 | ① 连续天数（按类型） → ② 本月总次数 |
| 全局连续 | P0 不做（仅按类型统计连续；P1+ 可单独立项） |
完整功能清单
图例：[P0] 首版必做 · [P1] 二期 · [P2] 可选 · [工程] 非用户可见
一、打卡类型（用户自定义）
| # | 功能 | 阶段 | 说明 |
|---|---|---|---|
| 1.1 | 新建类型 | P0 | 名称必填（如 ≤32 字）；可选图标（预设 menuIconKey）、标签色 |
| 1.2 | 编辑类型 | P0 | 改名称 / 图标 / 颜色 |
| 1.3 | 类型列表 | P0 | 未归档类型；按 sort 排序展示 |
| 1.4 | 拖拽 / 上下调整排序 | P0 | type/sort 批量更新 |
| 1.5 | 归档类型 | P0 | 从「今日」列表隐藏；历史记录保留 |
| 1.6 | 恢复归档 | P0 | 重新出现在今日列表 |
| 1.7 | 删除类型 | P0 | 仅当该类型无任何历史记录 可物理删；否则提示改归档 |
| 1.8 | 空态引导 | P0 | 无类型时引导「先添加想记录的事」 |
二、打卡记录（一日一类多条）
| # | 功能 | 阶段 | 说明 |
|---|---|---|---|
| 2.1 | 新增一条打卡 | P0 | 选类型 + 默认当前时间；写入 bizDate（业务日） |
| 2.2 | 再记一次 | P0 | 同类型、同一 bizDate 可多条；无 (用户,类型,日) 唯一约束 |
| 2.3 | 可选备注 | P0 | 如「5km」「第 2 次」；record/save / update |
| 2.4 | 编辑备注 / 发生时间 | P0 | 单条 record/update |
| 2.5 | 删除单条记录 | P0 | record/delete；不影响同类型其它条 |
| 2.6 | 今日次数展示 | P0 | 卡片显示「今日 n 次」+ 最近一条摘要（时间/备注） |
| 2.7 | 补记过去日期 | P0 | 主屏切换日期或明细页指定 bizDate 后新增 |
| 2.8 | 查看某日全部记录 | P0 | 按「类型 + 日期」列表（当日明细页） |
| 2.9 | 附件 / 拍照 | P2 | 不在 P0/P1 范围 |
三、今日打卡（主屏）
| # | 功能 | 阶段 | 说明 |
|---|---|---|---|
| 3.1 | 默认展示今天 | P0 | bizDate = 今天（与用户时区约定一致，对齐记账） |
| 3.2 | 左右切换日期 | P0 | 回看某天是否打过、可补记 |
| 3.3 | 类型卡片：未打 | P0 | 主按钮「打卡」→ 新增一条 |
| 3.4 | 类型卡片：已打 | P0 | 展示次数；「再记一次」；点击进入当日明细 |
| 3.5 | 快捷入口「类型管理」 | P0 | 跳转 types 页 |
| 3.6 | 下拉刷新 | P0 | 重拉 record/day-summary + 类型列表 |
四、当日明细
| # | 功能 | 阶段 | 说明 |
|---|---|---|---|
| 4.1 | 列表展示 | P0 | 该类型 + 该日全部记录（时间、备注） |
| 4.2 | 单条编辑 / 删除 | P0 | 见 2.4 / 2.5 |
| 4.3 | 底部「再记一次」 | P0 | 同 2.2 |
| 4.4 | 空态 | P0 | 该日该类型 0 条时的提示 |
五、打卡统计
| # | 功能 | 阶段 | 说明 |
|---|---|---|---|
| 5.1 | 周期 Tab：周 / 月 | P0 | query period=week|month |
| 5.2 | 主指标：连续天数 | P0 | 按类型；类型下拉切换；从周期末日往前，每日 ≥1 条 +1 |
| 5.3 | 次指标：本月总次数 | P0 | 当前类型 + 全类型合计 |
| 5.4 | 分类型汇总列表 | P0 | 每行：类型名、连续 X 天、本月 Y 次 |
| 5.5 | 活跃天数（辅助） | P1 | 月内有记录的自然日数（≠ 次数） |
| 5.6 | 自定义日期区间 | P1 | 对齐记账 stats-custom：多选类型 + dateFrom/dateTo |
| 5.7 | 日历热力格 | P1 | 点格看当日条数 |
| 5.8 | 生成分享图 | P1 | 参考 bookkeeping/stats 分享 canvas |
| 5.9 | 全局连续天数 | P2 | 任意类型每天至少 1 次 |
六、类型管理页
| # | 功能 | 阶段 | 说明 |
|---|---|---|---|
| 6.1 | 列表（含已归档区） | P0 | 归档折叠或分 Tab |
| 6.2 | 新建 / 编辑弹窗或子页 | P0 | 表单：名称、图标、颜色 |
| 6.3 | 排序 | P0 | 与 1.4 一致 |
| 6.4 | 归档 / 恢复 / 删除 | P0 | 与 1.5–1.7 一致 |
七、首页「常用」入口
| # | 功能 | 阶段 | 说明 |
|---|---|---|---|
| 7.1 | 日常打卡 | P0 | PagePath.dailyCheckInToday，pinOrder 约 -10 |
| 7.2 | 打卡统计 | P0 | .../stats?period=month（或 week，与记账一致） |
| 7.3 | 类型管理 | P0 | .../types |
| 7.4 | 分组 | P0 | groupKey: common，groupTitle: 常用 |
| 7.5 | 不与远端重复 path 去重 | P0 | mergeLocalShellApps 按完整 path 去重 |
八、账号 / 会话 / 网关（与个人记账一致）
| # | 功能 | 阶段 | 说明 |
|---|---|---|---|
| 8.1 | 微信 openid 换 JWT 即可进 | P0 | 不要求绑手机 |
| 8.2 | 无 JWT 不跳登录页 | P0 | 失败回首页换票 |
| 8.3 | 请求不附 X-Site-Id | P0 | postApiShouldAttachSiteHeader 增加 /sys/daily-check-in/ |
| 8.4 | 豁免手机门闸 | P0 | credential-gate / isDailyCheckInPath |
| 8.5 | 401 回首页 | P0 | 复用 bookkeeping-session 或抽 ensurePersonalSession |
| 8.6 | 数据仅 sub 隔离 | P0 | Service 层 assertActor 按当前用户，禁止 siteId |
九、后端（Sys 模块）
| # | 功能 | 阶段 | 说明 |
|---|---|---|---|
| 9.1 | ZenStack 模型 + zen:push | P0 | mini_daily_check_in_types、mini_daily_check_in_records |
| 9.2 | 软删 | P0 | 对齐 backend-soft-delete |
| 9.3 | POST .../type/save | P0 | 新建/更新 |
| 9.4 | POST .../type/list | P0 | 含归档标记 |
| 9.5 | POST .../type/archive | P0 | 归档/恢复 |
| 9.6 | POST .../type/delete | P0 | 无记录可删 |
| 9.7 | POST .../type/sort | P0 | { ids: string[] } 或 { items: {id,sort}[] } |
| 9.8 | POST .../record/save | P0 | 新增 |
| 9.9 | POST .../record/update | P0 | 备注、时间 |
| 9.10 | POST .../record/delete | P0 | 单条 |
| 9.11 | POST .../record/page | P0 | PageQueryDto + typeId? + dateFrom/dateTo |
| 9.12 | POST .../record/day-summary | P0 | 某日各 typeId → count、最近一条摘要 |
| 9.13 | POST .../stats/summary | P0 | 周/月：连续天数、次数、分类型数组 |
| 9.14 | Sys 路由权限 registry | P0 | @SysRoutePermission({ kind: 'authenticated' }) |
| 9.15 | Swagger / Knife4j | P0 | @ApiSysPost* + DTO @ApiProperty |
| 9.16 | 网关路径 | P0 | /api/sys/daily-check-in/*，文档前缀一致 |
十、小程序工程
| # | 功能 | 阶段 | 说明 |
|---|---|---|---|
| 10.1 | pages.json 注册页面 | P0 | today、day-detail、types、stats（+ stats-custom P1） |
| 10.2 | page-paths.ts 常量 | P0 | |
| 10.3 | shared/api 或 api/daily-check-in.ts | P0 | 对接上述 POST |
| 10.4 | useHomeShellOpenApp 会话 | P0 | 打开前 ensureBookkeepingSession（或扩展 path 判断） |
| 10.5 | 各页 onShow 会话守卫 | P0 | 失败 reLaunch 首页 |
| 10.6 | 布局 | P0 | 表单/列表遵循 miniapp-form-layout、miniapp-list-page |
| 10.7 | 统计图表 | P1 | miniapp-charts-canvas（若有环图/柱图） |
十一、文档与规则
| # | 功能 | 阶段 | 说明 |
|---|---|---|---|
| 11.1 | 扩展 miniapp-bookkeeping-user-scope.mdc | P0 | 补充 daily-check-in 路径与 API 前缀 |
| 11.2 | roadmap-four-tracks Track 3 勾选 | P0 | 开发中更新 checkbox |
| 11.3 | 改表时 database-docs-sync | P0 | schema 变更后同步表文档 |
十二、P2 / 不做
| # | 功能 | 阶段 | 说明 |
|---|---|---|---|
| 12.1 | 订阅消息提醒 | P2 | 每日提醒打卡 |
| 12.2 | 类型「每周目标 N 次」 | P2 | 完成率 |
| 12.3 | 导出 CSV | P2 | |
| 12.4 | 多人协作 / 监督打卡 | — | 不做，除非单独立项 |
| 12.5 | 与 Acc / 站点 / 记工联动 | — | 不做 |
| 12.6 | PC Web 管理端 | — | P0 仅小程序 |
数据模型
表：mini_daily_check_in_types
| 字段 | 说明 |
|---|---|
userId | 所属用户 |
name | 类型名称 |
iconKey | 可选，预设图标 |
color | 可选，#RRGGBB |
sort | 排序 |
archived | 是否归档 |
| Base | id、软删、审计字段 |
表：mini_daily_check_in_records
| 字段 | 说明 |
|---|---|
userId | 所属用户 |
typeId | 类型 FK |
bizDate | 业务日 YYYY-MM-DD |
occurredAt | 发生时刻 |
note | 可选备注 |
| Base | 软删 |
索引建议：(userId, bizDate)、(userId, typeId, bizDate)（非唯一）。
统计口径
| 指标 | 计算 |
|---|---|
| 连续天数 | 按 typeId，从 anchor 日往前，有 ≥1 条则 streak++，否则断 |
| 本月总次数 | bizDate 落在当月内的记录条数 COUNT |
| 周统计 | dateFrom/dateTo 为本周一至周日（或与自然周配置一致） |
页面与路由（规划）
| 页面 | 路径 | P0 |
|---|---|---|
| 今日打卡 | /pages/daily-check-in/today | ✓ |
| 当日明细 | /pages/daily-check-in/day-detail?typeId=&bizDate= | ✓ |
| 类型管理 | /pages/daily-check-in/types | ✓ |
| 打卡统计 | /pages/daily-check-in/stats?period=week|month | ✓ |
| 自定义统计 | /pages/daily-check-in/stats-custom | P1 |
API 一览（POST /sys/daily-check-in/*）
| 路径 | P0 |
|---|---|
type/save | ✓ |
type/list | ✓ |
type/archive | ✓ |
type/delete | ✓ |
type/sort | ✓ |
record/save | ✓ |
record/update | ✓ |
record/delete | ✓ |
record/page | ✓ |
record/day-summary | ✓ |
stats/summary | ✓ |
P0 验收标准
自动化
bash
pnpm run check
pnpm run check:miniapp页面只显示 pages/daily-check-in/today.wxml 无内容
多为 dev 产物占位页（先登记 pages.json、后补 .vue，且未重启编译）。处理：
bash
cd miniapp
pnpm run clean:mp-weixin
pnpm run dev:mp-weixin微信开发者工具导入目录须为 miniapp/dist/dev/mp-weixin（勿用旧缓存）。dev:mp-weixin 启动前会自动检测并清理占位 wxml。
手工（微信）
- 未绑手机：首页 常用 → 日常打卡 可进，不跳登录页。
- 新建类型「跑步」→ 今日打卡 2 次（再记一次）→ 今日显示 2 次。
- 当日明细可删 1 条 → 今日变 1 次。
- 打卡统计 · 月：跑步本月 2 次；连续天数与操作一致。
- 归档类型后今日列表不显示；统计仍计历史。
- 抓包：无
X-Site-Id；仅/api/sys/daily-check-in/*。
分期总表
| 阶段 | 包含清单章节 |
|---|---|
| P0 | 一～四、六～十一（不含 P1/P2 行）；九、十全部 API/页面 |
| P1 | 5.5–5.8、4.6、stats-custom、日历、分享图 |
| P2 | 十二 12.1–12.3、2.9、5.9 |
相关文档
- roadmap-four-tracks.md — Track 3 排队项
- microservice-split-decision.md — 不拆 personal 服务（P0）