21 天健康习惯打卡设计

背景与目标

新增一个面向学校作业的独立在线打卡页面，参考现有纸质版“21 天健康好习惯训练清单”的信息结构，并复用现有晨起清单的纯浏览器交互方式。

目标是让使用者填写班级、姓名和开始日期，按天完成“学习、运动、护眼、护脊”四项打卡，在当前浏览器中持续保存进度，并可通过浏览器打印功能生成单页 A4 PDF。

现有 /tools/morning-pilot-checklist/ 保持不变，新功能不与晨起清单切换或共享数据。

产品边界

本期包含

• 独立路由 /tools/health-habit-checklist/。
• 固定 21 天、固定四项习惯。
• 班级、姓名、开始日期三个可编辑字段，默认留空。
• 21 个天数卡片，每天包含四个独立复选框。
• 完成天数、21 天进度和第 7、14、21 天里程碑展示。
• 21 天小复盘：坚持天数、最棒的习惯、家长鼓励、五星评分。
• 浏览器 localStorage 自动保存和恢复。
• 单页 A4 纵向打印样式，以及“生成 PDF”入口。
• 工具总览、路由地图、资产记录和在线工具 Wiki 同步。

本期不包含

• 账号、登录、服务器存储或云同步。
• 后端接口、数据库、外部 API 或凭证。
• 自定义习惯名称、数量或训练周期。
• 提醒、通知、排行榜、社交分享或二维码。
• JSON 导入导出、跨设备迁移或多人协作。
• 独立移动版静态页面。
• 自动下载 PDF 的新第三方依赖。

页面与组件

页面入口

• 建议页面源文件：docs/07.工具/20.学习工具/80.21天健康习惯打卡.md。
• 固定 permalink：/tools/health-habit-checklist/。
• 页面通过 ClientOnly 引用独立 Vue 组件。
• 页面正文说明适用场景、数据仅保存在浏览器、PDF 保存方式和隐私边界。

Vue 组件

• 建议组件：docs/.vuepress/components/HealthHabitChecklist.vue。
• 桌面端和手机端共用一个响应式组件。
• 组件只负责该工具，不修改 MorningPilotChecklist.vue。
• 可独立测试的状态计算和存储校验放入小型逻辑模块，避免把全部行为堆在组件中。

信息与视觉结构

页面主体按照参考图从上到下排列：

1. 深蓝标题区：标题、副标题、训练原则和目标。
2. 绿色提示条：说明四项全部完成才算当天完整打卡。
3. 身份信息区：班级、姓名、开始日期。
4. 21 天进度区：完成天数及 1–21 天进度格。
5. 每日四项标准区：展示四项固定习惯及完成标准。
6. 21 天打卡区：桌面和打印版为 7 列 × 3 行；手机端使用更适合点击的响应式列数。
7. 21 天小复盘区：坚持天数、最佳习惯、家长鼓励和五星评分。
8. 页面操作区：“生成 PDF”按钮和本地保存状态提示；打印时隐藏。

视觉沿用参考图的深蓝、绿色、橙色、蓝色和紫色体系。第 7、14、21 天显示金色里程碑。公开页面不预填真实姓名、班级或其他个人信息。

固定习惯

编号	名称	完成标准	标识色
1	学习	阅读或复习，认真完成	橙色
2	运动	户外运动 2 小时，注意安全	绿色
3	护眼	一尺一拳一寸 + 20-20-20	蓝色
4	护脊	坐姿端正，完成护脊操	紫色

习惯名称和标准在本期固定，不向使用者提供增删或编辑能力。

交互规则

身份信息

• 班级、姓名使用普通文本输入。
• 开始日期使用日期输入。
• 开始日期只作为作业信息展示，不据此限制或自动切换可打卡的天数。
• 三项都允许暂时为空，不阻塞打卡或打印，便于打印后手写补充。
• 输入变化后实时保存。

每日打卡

• 21 个天数卡片均可操作，不限制只能编辑当天，允许补录学校作业。
• 每个天数卡片包含四个复选框，再次点击可取消。
• 只有同一天四项全部选中时，该天才计入“已坚持 X 天”。
• 完成天数是 21 天中完整完成的天数总数，不要求日期连续。
• 进度格根据对应日期是否完整完成显示完成或未完成状态。
• 第 7、14、21 天无论是否完成都保留里程碑位置；完成后使用金色完成态。

小复盘

• “我坚持了 X 天”直接使用完整完成天数，不单独编辑。
• “我最棒的习惯”和“家长鼓励”使用文本输入。
• 五星评分允许选择 1–5 星，再次选择其他星级即覆盖。
• 所有变化实时保存。

浏览器存储

使用独立、带版本号的 localStorage key，例如 health_habit_checklist_v1，不得复用晨起清单的 key。

建议数据结构：

{
  "version": 1,
  "profile": {
    "className": "",
    "studentName": "",
    "startDate": ""
  },
  "days": {
    "1": ["study", "exercise"],
    "2": ["study", "exercise", "eyes", "spine"]
  },
  "review": {
    "bestHabit": "",
    "parentMessage": "",
    "rating": 0
  }
}

约束：

• 页面挂载时读取并校验版本、对象类型、日期编号和习惯 ID。
• 只接受 1–21 的日期编号和四个已知习惯 ID。
• 缺失字段使用默认空值补齐。
• JSON 无法解析或结构完全无效时，页面使用空白状态并显示本地数据异常提示；在使用者点击“清空异常数据并重新开始”前，禁用保存，不能静默覆盖原值。
• 不把姓名、班级、日期或打卡记录发送到服务器。

生成 PDF

“生成 PDF”采用现有仓库已经使用的浏览器打印方案，不增加 PDF 依赖：

1. 点击按钮后进入打印状态。
2. 隐藏博客导航、页面说明、操作按钮和保存提示。
3. 使用 @page 和打印媒体样式固定为 A4 纵向、单页布局。
4. 调用 window.print() 打开系统打印界面。
5. 使用者可选择“另存为 PDF”或直接打印。
6. 打印完成或取消后恢复普通页面状态。

打印内容必须包含身份信息、21 天进度、四项标准、全部打卡状态和小复盘，不包含调试信息、网页导航或隐私提示。

响应式设计

• 桌面端保持接近参考图的完整卡片布局。
• 手机端不跳转到独立静态页面，改用同一组件的响应式布局。
• 手机端优先保证输入和复选框可点击，不强制维持 7 列。
• 打印媒体样式不受当前屏幕宽度影响，始终恢复为 7 列 × 3 行 A4 布局。

错误处理

• localStorage 不可用：页面仍可临时使用，显示“当前浏览器无法保存进度”。
• 存储数据损坏：使用空白状态渲染并提示；只有使用者明确确认“清空异常数据并重新开始”后，才移除损坏值并恢复保存。
• window.print 不可用：按钮显示简短失败提示，页面其他打卡能力不受影响。
• 所有异常只在当前页面处理，不引入远程日志或个人数据上报。

测试与验证

逻辑测试

• 四项全部完成才计为完整一天。
• 少于四项、重复习惯 ID 和未知习惯 ID 不计为完整一天。
• 完成天数统计范围始终为第 1–21 天。
• 第 7、14、21 天里程碑状态正确。
• 有效存储数据可以恢复；缺失字段使用默认值。
• 损坏 JSON 和非法结构不会导致页面崩溃，也不会在未经确认时覆盖原值。

接线测试

• Markdown 页面、permalink 和组件引用存在。
• 组件使用独立存储 key，并包含固定四项、21 天、小复盘和打印入口。
• 工具总览包含新页面入口。
• 打印样式包含 A4 纵向、打印隐藏区域和 7 列打卡布局。
• 现有晨起清单的页面、组件、路由和存储 key 保持不变。

完整验证

• 使用 Node.js 20 运行新增定向脚本。
• 运行现有晨起清单和书包挑战的相关接线回归。
• 运行 node scripts/test_llm_wiki.js。
• 运行 git diff --check。
• 使用 Node.js 20 运行完整构建。
• 本地浏览器检查桌面和手机交互。
• 从本地页面打印为 PDF，确认单页 A4、文字清晰、无裁切、无网页导航元素。

本地构建和 PDF 验证不代表线上已发布；部署需要用户另行明确授权。

Wiki 与入口同步

实现时同步更新：

• docs/07.工具/00.概览.md
• LLM_WIKI/20_内容体系/在线工具.md
• LLM_WIKI/10_博客结构/页面与路由地图.md
• LLM_WIKI/30_资产库/资产总表.md

是否进入顶级导航或首页卡片，以现有工具入口密度为准；本期默认不新增顶级导航或首页卡片，只加入工具总览。

验收标准

1. /tools/health-habit-checklist/ 为独立页面，现有晨起清单行为不变。
2. 页面固定提供学习、运动、护眼、护脊四项和 21 天卡片。
3. 仅四项全部选中时才增加一天完成数。
4. 身份、打卡和复盘数据刷新后可从当前浏览器恢复。
5. 页面不向服务器发送身份或打卡数据。
6. 第 7、14、21 天具有明确里程碑视觉状态。
7. “生成 PDF”可打开 A4 纵向打印界面，保存结果为单页且内容完整。
8. 桌面和手机均可完成输入、打卡和复盘。
9. 新增定向测试、Wiki 校验、差异检查和 Node.js 20 构建全部通过。
10. 未经另行授权不部署、不推送远端、不修改生产服务。