Kanban/docs/adr.md

架构决策记录（ADR）

本文件记录个人看板工具 MVP 的关键技术决策。每条包含：背景、结论、被否决的方案及原因。

---

ADR-001 · 看板列固定为三列，不支持配置

背景 初版设计在设置页提供「列配置」，但数据模型中 status 为固定枚举 todo | doing | done，两者互相矛盾。

结论 MVP 固定三列：todo（待办）/ doing（进行中）/ done（已完成）。status 使用 TypeScript 字面量联合类型，不使用 enum（同时满足 erasableSyntaxOnly 编译约束）。

被否决的方案

• 引入 columns 表 + task.columnId：需要额外的列 CRUD、列删除时的任务迁移、列顺序持久化。对单人任务管理而言，收益为零，成本约为原方案的两倍。
• 用 enum 定义列：与 erasableSyntaxOnly: true 冲突，且 enum 在纯类型场景下没有优势。

影响 若未来确需自定义列，需一次性迁移 status → columnId，并在 schemaVersion 中登记。

---

ADR-002 · 存储采用 TaskRepository 接口 + localStorage 实现

背景 初版方案直接选用 Dexie（IndexedDB）。但个人看板在 200 个任务规模下，数据量约 60KB，远低于 localStorage 5MB 上限。

结论 定义 TaskRepository 接口（list / get / create / update / remove / replaceAll），MVP 只提供 localStorage 实现。UI 与 Store 仅依赖接口，不感知具体实现。

被否决的方案

• 直接用 Dexie：收益是索引查询与大容量，在该规模下用不上；代价是 Pinia 与 DB 双份状态、异步竞态、多标签页同步、测试需引入 fake-indexeddb，约多花 1.5 人天。
• 直接在组件里读写 localStorage：数据访问散落各处，无法测试，也无法替换实现。

影响 数据量增长到万级或需要复杂查询时，新增一个 Dexie 实现并切换注入即可，接口不变。

---

ADR-003 · dueDate 只表示日期，不表示时刻

背景 dueDate 若同时承载日期与时刻，需要处理时区转换（本机为 Asia/Hong_Kong），并会在「今天到期」的判定上产生歧义。

结论 dueDate 类型为 string | null，格式固定 YYYY-MM-DD，不含时刻与时区信息。「是否逾期」以本地日历日比较得出。

被否决的方案

• 存储 ISO 8601 完整时间戳：需要引入时区处理，且个人看板不需要精确到分钟的截止时间。
• 存储 Date 对象：JSON 序列化后仍会退化为字符串，且容易在反序列化时引入时区偏移。

影响 若未来需要提醒功能，应新增独立字段（如 remindAt），而不是改变 dueDate 的语义。

---

ADR-004 · 不引入 vue-router

状态：已被 ADR-005 取代。 本决策在 MVP 阶段成立；当「今日视图」真的落地后， 它预判的触发条件（"若未来增加今日视图、统计等真正的独立页面"）已经满足。

背景 初版信息架构包含「主看板页」「任务详情」「设置页」三个页面。

结论 MVP 为单视图应用：主看板常驻，任务详情使用 Drawer，导入导出与快捷键说明使用 Modal。不引入 vue-router。

被否决的方案

• 引入 vue-router：三个「页面」中有两个本质是覆盖层（overlay），用路由表达会让 URL 与状态同步复杂化，且多一个运行时依赖。
• 用 URL query 承载筛选状态：MVP 不做分享与深链需求，暂不需要。

影响 若未来增加「今日视图」「统计」等真正的独立页面，再引入路由；届时筛选状态可一并迁移到 query。

---

ADR-005 · 引入 vue-router，拆分看板与今日两个视图

背景 ADR-004 决定 MVP 不引入路由，并注明「若未来增加今日视图、统计等真正的独立页面，再引入路由」。 现在补做了「今日视图 + 简单统计」，触发条件成立。

「今日视图」与看板的关系值得说清楚：它不是看板的另一种筛选，而是换了一个组织维度 —— 看板按「状态」组织（待办/进行中/已完成），今日视图按「紧急度」组织（逾期 → 今天到期 → 进行中）。 同一批数据，两种视角，用户需要在它们之间来回切换，而不是叠加在同一屏里。

结论 引入 vue-router，两条路由：

• / — 看板
• /today — 今日视图（含统计卡片与按紧急度排序的待办列表）

使用 createWebHistory（而非 hash），并导出 createAppRouter(history) 工厂函数而非单例， 以便测试注入 memory history。

被否决的方案

• 把今日视图做成一个 Drawer / Modal：Drawer 适合「聚焦单条记录」（任务详情、备份面板）， 不适合承载一个完整的列表视图；而且它无法被收藏或分享，PWA 的 manifest shortcuts 也无处可指。
• 在工具栏加一个「今日」筛选按钮：那只是筛选，不是视图。用户仍然面对三列结构， 还得自己在心里把「逾期」和「进行中」拼起来。
• 用 hash 路由避免服务器配置：URL 会变成 /#/today，不美观，且 PWA 的 start_url 与 shortcuts 指向带 hash 的地址会让某些平台的安装体验变差。代价是部署时必须配置 SPA 回落 —— 这一点已在 README 的部署章节明确写出。

影响

• 部署要求变化：服务器必须把未知路径回落到 index.html，否则直接访问 /today 会 404。 README 已给出 Nginx 与 Netlify 的配置。
• 今日视图按路由懒加载，不进入首屏包（独立 chunk 约 4KB）。
• Service Worker 的 navigateFallback 设为 index.html，离线时深链 /today 同样可用。
• 看板原有的筛选状态仍留在 Pinia 中，未迁移到 query —— 目前没有分享带筛选链接的需求， 迁移只会增加复杂度。

---

ADR-006 · 覆盖式操作前自动快照，归档任务提供恢复入口

背景

MVP 有「启动快照 + 手动导出」两道保护，但两个整份覆盖的动作没有退路：导入 JSON 与从快照恢复 都会直接替换当前数据。归档功能的设计说明写的是「可随时恢复」，实际只有归档后 5 秒内的 Toast 撤销能恢复，界面上找不到入口。另外，详情抽屉不能改状态、未保存的修改点一下遮罩就丢， 是日常使用里最高频的两处摩擦。

结论

1. importJson / restoreSnapshot 在覆盖前调用 repository.snapshot(当前数据)； 快照写入失败不阻断主流程。空看板不写，避免产生无意义备份。
2. 导入校验增加 id 唯一性检查：严格导入路径直接拒绝并指出重复的两条； 宽容读取路径保留先出现的那条，避免重复 id 破坏 v-for 与 findIndex。
3. 详情抽屉增加「状态」三列切换，并展示归档状态与「恢复」入口。
4. 详情抽屉维护 dirty 状态：有未保存修改时关闭需要二次确认，不再静默丢弃草稿。
5. Toast 自动关闭支持悬停/聚焦暂停，移开后按剩余时间继续；撤销不再「刚要点击就消失」。
6. 存储写失败时把 persistent 置为 false 并把提示提升到 App 级，两个视图都能看到告警。

被否决的方案

• 给删除加二次确认弹窗：与现有「立即删除 + Toast 撤销」的约定冲突，且删除频率高， 弹窗会拖慢操作；改为延长撤销的可操作性（暂停计时）成本更低。
• 把归档任务从列内排序序列中剥离，让归档后排序仍可用：需要同时改 sortOrder 计算、 拖拽下标映射与渲染顺序，收益仅是「已完成列可排序」。当前保留禁用策略， 把原因写进工具栏提示（「归档 N 个，列内排序已暂停」），让用户知道为什么拖不动。
• 导入后自动生成版本快照：没有服务端与版本库，快照只是本地兜底，不应膨胀成版本历史。

影响

• 快照最多占用 4 份全量数据（主数据 + 3 份快照）；任务量接近 localStorage 配额时 需要清理旧快照或按 ADR-002 迁移到 IndexedDB。
• persistent 现在会随写入成功/失败翻转，UI 可据此判断「改动是否真的落盘」。
• 关闭详情抽屉的默认行为从「直接关闭」变为「有改动先确认」，相关组件测试已同步调整。
• 新增 .gitea/workflows/ci.yml，把 lint / typecheck / test / build 纳入推送与合并请求检查。

---

ADR-007 · 删除改为软删除，导入提供覆盖 / 合并两种模式

背景

删除此前只有 5 秒内的 Toast 撤销，超过窗口后只能去自动备份里碰运气；而多设备、多次导出之后， 覆盖式导入又只能二选一，「把两份数据拼起来」需要手工处理。本批同时解决这两件事，并顺带把多选 从「批量删除工具」升级为「批量编辑器」。

结论

1. Task 增加 deletedAt，schemaVersion 升到 3；删除写 deletedAt（软删除），任务进入回收站， 30 天后在启动时自动清理。永久删除只允许作用于回收站里的任务，且需要二次确认。
2. 软删除是数据状态而不是筛选维度：store 提供 activeTasks，列、计数、统计、今日视图、 标签下拉、归档候选全部消费它；matchesFilter 仍然只负责归档可见性。回收站数据由 trashTasks 单独提供，按删除时间倒序。
3. 恢复只清除 deletedAt，保留原 sortOrder 与 archivedAt，因此位置和归档态都会还原。 导出仍包含已删除任务，保证换设备后回收站也能带走。
4. 批量编辑与单条编辑共用 applyTaskPatch（src/utils/taskPatch.ts），状态进出「已完成」、 updatedAt 刷新、标签去重、标题回退只有一份规则。批量标签采用增 / 删语义， 避免统一加标签时把每条任务原有的其它标签抹掉。
5. 导入增加合并模式：按 id 匹配，同 id 以 updatedAt 较新的一方为准；文件新增项追加到对应列末尾 并重算 sortOrder；本地独有任务保留；两种模式执行前都调用同一套快照逻辑。
6. 标签治理（重命名 / 合并 / 删除）放在 src/utils/tags.ts 的纯函数里，store 只负责找出真正变化的 任务、刷新 updatedAt 并一次落盘。回收站里的任务不参与改写。

被否决的方案

• 把 deletedAt 塞进 TaskFilter：回收站不是「筛掉一部分」，而是一条独立的数据状态。 放进筛选会让每个调用点都要记得带上「排除已删除」，漏一处就会把删除项泄漏到看板或统计里。 改为在 activeTasks 层统一剔除，失败模式从「N 处可能漏」收敛为「一处必须对」。
• 给删除加二次确认：删除是高频操作，弹窗会拖慢节奏；软删除 + 回收站已经提供了比确认框更好的退路。
• 批量改属性做 [{id, before}] 快照式撤销：需要额外的内存态与 UI 语义，收益低于成本； 标签是增删语义，改错了再改回来即可。批量删除 / 归档仍有 Toast 撤销。 （已被 ADR-010 推翻：批量编辑器扩张到 四类属性之后，这个取舍不再成立；但实现方式改为整份快照，而非字段级 diff。）
• 合并时对整列 sortOrder 做 normalize：会悄悄重排用户已有数据。新增项追加列尾已经足够， 既有冲突留给后续显式整理。
• 给回收站做搜索 / 筛选：列表按删除时间倒序已经能覆盖「刚删错」这个主场景，先不加。

影响

• 数据面变大：回收站会占用 localStorage 配额，靠 30 天自动清理与手动清空兜底；导出文件也会包含 已删除任务，体积略增。
• 所有「看板语义」的读取点必须走 activeTasks。新增读取点时若直接用 tasks，会把已删除任务 泄漏到 UI；可见性矩阵已写进测试（列、统计、标签、今日视图、归档候选）。
• 迁移链新增 2 → 3，且 parsePersistedState / 快照恢复共用同一套解析，旧备份仍可读。
• 详情抽屉的编辑对象改为在 activeTasks 里查找，删除后抽屉会立即关闭，而不是停留在一条已删除的任务上。

---

ADR-008 · 任务时间只读展示，不参与排序与筛选

背景

Task 从 T03 起就有 createdAt / updatedAt / completedAt，后者还承担「本周完成」统计与归档候选的判断， 但界面上没有任何入口能把它们读出来 —— 想知道任务哪天创建、哪天完成，只能导出 JSON 自己找。 时间字段是只写不读的，等于白存。

结论

1. 详情抽屉底部新增只读「时间」区块：创建 / 更新常驻，完成时间在 completedAt 为空时显示「未完成」， 归档任务追加一行归档时间。时间不属于可编辑字段，不进入草稿与 dirty 判定。
2. 已完成卡片在元信息行右侧显示 完成于 M月D日（跨年补年份）；未完成卡片不渲染该行，避免给待办增加噪音。
3. 卡片根元素带 title，汇总创建 / 完成 / 归档时间（精确到分钟）。悬停即得，不占版面； 移动端与键盘用户由详情抽屉兜底。
4. 回收站条目同时显示创建时间与删除时间，原先内联的 formatTime 被 @/utils/date 的 formatDateTime 取代。
5. 格式化统一收敛到 src/utils/date.ts：formatDateTime 输出 YYYY-MM-DD HH:mm，formatCompactDate 按是否跨年输出 M月D日 / YYYY年M月D日。两者对空值与非法时间戳返回 null，由调用方决定占位符 —— 界面上永远不会出现 Invalid Date。

被否决的方案

• 卡片同时显示创建时间：待办卡片的元信息行已有优先级、截止日期与标签，再加一行会挤掉真正的决策信息。 创建时间对「先做哪件」几乎没有影响，放进 title 与详情抽屉足够。
• 增加「按创建 / 完成时间排序」开关：完成列的顺序由手动 sortOrder 表达，再引入第二种排序会让 「看到的顺序」与「拖拽写回的顺序」产生两个真相；当前也没有对应使用场景。 （其中「完成列按完成时间排序」后来被 ADR-009 部分推翻。）
• 用相对时间（「3 天前」）：文案依赖渲染时刻，页面开一整天就会和实际完成日对不上； 复盘场景下具体日期更有用。
• 提升 schemaVersion 做迁移：字段早已存在，且 coerceTask 已把它们收敛为字符串或 null，无需迁移。

影响

• 时间展示纯只读；completedAt 的写入仍收敛在状态流转处 —— 单条 / 批量编辑走 applyTaskPatch， 拖拽换列走 moveTask，两者规则一致（进入「已完成」写时间、离开即清空），展示值与状态不会互相矛盾。
• 新增两个纯函数与对应单测；TrashPanel 少了一个私有格式化函数。
• 卡片 title 是纯提示信息，不参与可访问性命名（aria-label 仅在多选态给出），读屏语义不变。

---

ADR-009 · 已完成列改按完成时间倒序展示

背景

ADR-008 否掉了「完成列按时间排序」，理由是维持单一顺序来源。但实际使用中这个取舍站不住： 完成任务时 sortOrder 是「追加到列尾」，于是刚勾完的任务沉到列表最底下 —— 打开看板想问「我刚才做完什么」，得滚到列底；做完几十条之后，已完成列变成一条只有 「按完成先后升序」的考古记录。对已完成的任务来说，用户唯一关心的顺序就是完成时间。

结论

1. 已完成列的展示顺序由 completedAt 倒序决定，不再消费 sortOrder。 排序键收敛为一个纯函数 sortCompletedDesc（src/utils/sortOrder.ts）， 转换只在 BoardView 的 visibleColumns 单点发生，store 与数据层语义不变。
2. 该列停用列内排序：拖拽与 ↑ ↓ 只允许跨列（sortDisabled 对 done 恒为 true）， 避免写出「永远看不见结果」的 sortOrder。
3. 列头标注「按完成时间倒序」，把口径写在界面上，用户不会误以为拖不动是故障。
4. 不做数据迁移：sortOrder、导入导出、快照结构与 schemaVersion 全都不动。 completedAt 缺失的旧数据（手工导入、更早的备份）排在有完成时间的任务之后， 彼此之间退回 sortOrder 倒序，至少保持「新完成的在上面」。

被否决的方案

• 一次性按完成时间重排 sortOrder，新完成插列首：需要迁移存量数据，且用户只要拖过一次， 顺序就再次和时间脱钩 —— 等于保留两个真相，还多了写操作。
• 只改插入位置（新完成插列首）：改动最小，但存量列表仍是旧的升序，首屏出现 「新任务在顶、旧任务按升序续在后面」的断裂顺序。
• 加排序开关：一个开关多一份状态、多一组需要测试的组合，而「已完成」只有一种合理顺序。

影响

• 落入已完成列的落点不再由拖拽位置决定（completedAt 刚写入即最新），这是预期行为。
• store.byColumn.done 仍是 sortOrder 语义，只有视图层按时间倒序；两者差异集中在 BoardView.visibleColumns，测试覆盖了「顺序与 sortOrder 无关」这一条。
• 已完成列成为只读顺序：拖拽、↑ ↓、批量移动（只能移出该列）都不会改变其内部顺序。

---

ADR-010 · 引入全局撤销栈，取代逐个操作做撤销

背景

ADR-007 明确否决了「批量改属性做 [{id, before}] 快照式撤销」，理由是「需要额外的内存态与 UI 语义， 收益低于成本」。当时这个判断成立：批量编辑器只能改标签，改错了再改回来即可。

但现在批量编辑器已经能一次改动目标列、优先级、截止日期、归档状态四类属性 —— 一次误操作波及的是 几十条任务的多个字段，逐条手工回滚已不现实。同时 Ctrl+Z 是所有人对「撤销」的肌肉记忆， 按下去没反应本身就是一个缺陷。重新评估之后，结论反过来了。

结论

1. 撤销 / 重做基于整份 tasks 数组快照，而不是命令模式。stores/tasks.ts 的所有变更都是 不可变替换（tasks.value = [...]），未被改动的 Task 对象在相邻快照之间共享引用 —— 50 步历史的实际内存增量只是「被改过的那几个对象」，与任务总数无关。
2. 快照的采集点是 commit() 这唯一的写入出口：维护一个 lastCommitted 指针指向 「上一次提交后的状态」，commit() 时把它压栈并更新指针。三十多个写方法一行都没改， 因此不存在「新增操作忘了写 undo」这类漏点。
3. undo() / redo() 刻意不走 commit()：撤销本身不是一次新的业务变更。若也压栈， 用户按 Ctrl+Z 就会在两步之间来回跳。
4. commit() 同时清空 redo 栈 —— 撤销之后又做了新操作，原来那条重做分支已经与当前状态分叉。
5. 上限 50 步，超出丢弃最旧的；历史不落盘，刷新即清空。
6. 快捷键单开一条通道（matchUndoShortcut），不复用 matchShortcut：后者的语义是「裸键」， 带修饰键的组合一律交还浏览器（Ctrl+F 查找、Cmd+R 刷新）。把撤销混进去，这条放行规则就失效了。
7. 在输入框内不拦截 Ctrl+Z：编辑任务详情时应当撤销文字输入，而不是把整个任务的状态回滚。
8. 历史为空时弹一句短提示（2 秒）；成功时不提示 —— 列表已经变了，本身就是反馈。

被否决的方案

• 命令模式（每个操作记录逆操作）：需要为 createTasks / updateTasks / moveTask / archiveTasks / renameTag 等三十多个方法各写一份逆操作，且之后每加一个写方法都要记得补。 快照方案把「必须做对」的点从 N 处收敛到 commit() 一处。
• 字段级 diff 栈：字段之间有关联（status 与 completedAt 必须同步、换列要重算 sortOrder）， 字段级还原极易留下不一致的中间态。整份快照天然自洽。
• 持久化撤销历史到 localStorage：刷新后仍能撤销「上一次会话」的操作，会让历史与当前数据的 边界变模糊，也显著放大配额占用。编辑器的撤销本来就是会话级的。
• 复用 matchShortcut 处理 Ctrl+Z：会迫使该函数区分「允许哪些修饰键」，Ctrl+F 之类的 放行规则随之含糊。
• 撤销时弹 Toast 说明撤销了什么：需要给 commit() 加操作名参数，进而改动所有调用点； 收益只是「多说一句话」，而视觉变化已经足够。

影响

• stores/tasks.ts 新增 undo / redo / canUndo / canRedo / resetHistory； undoStack / redoStack 只存在于内存。
• 跨标签页收到同步消息后（reloadFromRepository）调用 resetHistory：本页的历史已与最新数据分叉， 保留下来会在下次撤销时抹掉对方的改动。
• 启动时的过期回收站清理（purgeExpiredTrash）也走 commit()，因此在 init() 末尾显式 resetHistory()，避免「打开页面就能撤销一次数据清理」。
• ADR-007 中「批量改属性不做撤销」一条作废；其余结论（软删除、activeTasks 单一剔除点、 标签增删语义）不变。

---

ADR-011 · 标签颜色独立存储，不进入任务数据

背景

「已知限制」里长期挂着一条「标签还没有颜色」。标签是纯字符串，在卡片上与优先级、截止日期挤在同一行， 标签一多就难以扫读，上色是最直接的缓解手段，成本也远低于子任务、多设备同步这类结构性改动。

真正的决策点不是「怎么上色」，而是颜色存在哪里：放进 PersistedState（跟随导出、快照、导入）， 还是单独一个 localStorage 键。

结论

1. 颜色存独立的 kanban.tagColors，结构为 { [tag: string]: 色板id }，不进 PersistedState， 因此 schemaVersion 保持 3，不需要任何迁移。
2. 存的是色板 id（rose / sky / …）而不是 class 字符串。以后调整视觉样式只改代码，不用动用户数据。
3. 色板固定 8 色，每个色板在源码里写完整类名字符串。Tailwind v4 构建时扫描源码， 动态拼接的 bg-${color}-500 不会被生成，样式会静默失效 —— 这是这个功能唯一的硬坑。
4. 未设置颜色的标签不画圆点，也不在映射里占位。默认给每个标签一个灰点只是把噪音放大，等于没上色。
5. 标签治理（重命名 / 合并 / 删除）在 stores/tasks.ts 的三个方法里顺带调用颜色 store， 把颜色的键名一起搬走。放在这里而不是面板组件里，是为了以后新增一种治理操作时不会漏掉颜色迁移。
6. 目标标签已经有颜色时保留目标的：那是用户为它单独设过的，来源方更像「顺手被并过来」的一方。
7. 读写失败静默降级（隐私模式 / 配额满）。颜色丢了不影响任何任务，不值得弹告警打断使用。

被否决的方案

• 放进 PersistedState，跟随导出与快照：好处是换设备能带走。代价是导入语义变浑 —— 覆盖导入会变成「连别人的审美一起覆盖」，合并导入又该不该合并颜色？为了让导出多带几个键， 引入一套「导入时忽略某字段」的特例，不划算。而且颜色是可重建的，任务不是。
• 允许任意取色器：会带来对比度失控（深色模式尤甚）、需要对存储值额外校验，以及一堆无法被 Tailwind 静态扫描的动态类名。8 个手挑的色板足够区分，每档都验证过明暗两套主题。
• 卡片上用整块 chip 背景着色：标签行与优先级、截止日期共处一行，加背景色会把行撑高， 也会与「红色 = 逾期」的语义打架。改成小圆点 + 文字保持中性，既区分了标签，又不干扰紧急度判断。

影响

• 新增 src/utils/tagColors.ts（纯逻辑）与 src/stores/tagColors.ts（持久化），共 41 个单测。
• TaskCard / TagFilter / TagManagerPanel 三处消费颜色；前两者改为依赖 store， 因此对应组件测试需要 setActivePinia。
• 标签圆点带 data-role="tag-dot"：卡片上本来就有别的圆点元素（状态点、勾选框）， 用 .rounded-full 这类样式选择器会误伤，单测与 e2e 一律按 data-role 定位。
• 导出 JSON 不含颜色，README 的已知限制已写明。

---

ADR-012 · 统计视图：完成趋势与热力图

背景

README 的「已知限制」里长期挂着一条「统计只覆盖本周完成数等基础指标，没有趋势图或历史留存」。 而 completedAt 从 T03 起就在数据里，除了算「本周完成」和判断归档候选之外没有任何出口 —— 用户想知道「我这几周到底做了多少」，只能导出 JSON 自己数。

ADR-005 在引入路由时就写明：「若未来增加今日视图、统计等真正的独立页面，再引入路由」。 统计视图正是那句话里的第二个页面。

结论

1. 独立路由 /stats，与今日视图平级。今日视图往前看（今天该做什么），统计往回看（做过什么）， 两者的信息密度和使用时机都不同，塞在同一屏会互相稀释。按 ADR-005 的既有惯例懒加载。
2. 数据只从 completedAt 推算，不引入「每日完成计数」表。按本地日期分组， 逐条走 localDateOf —— completedAt 存的是 UTC ISO，直接截前 10 位在东八区会把晚上完成的任务算到前一天。
3. 热力图 53 周（一年），列为一周、行为周一到周日（周一为一周之始，与 utils/stats.ts 口径一致）。 先用 26 周试过：只占卡片一半宽，右侧大片留白，且看不出季节性起伏。
4. 强度固定阈值分档（0 / 1 / 2 / 3 / 4+）。按最大值相对分档会让数据一变多就所有格子一起变深， 反而看不出「哪天特别猛」；固定阈值可预测，也便于测试。
5. 月份标签只打在该月第一周（周一落在 1–7 号）。最初用「月份变了就打」，结果 4 月与 5 月 这种相邻两周各打一个，而每列只有 14px 宽，两个标签直接叠在一起。每月一次后间隔必然 ≥ 4 列。
6. 连续完成天数允许「今天还没开始」：今天没有记录就从昨天起算。否则每天零点一过 streak 归零， 等于在用户还没开始工作的时候先把成绩抹掉。
7. 回收站里的任务不计入（软删除的语义是「这件事不算了」），已归档的计入（归档只是隐藏）。
8. 没有完成记录时仍然渲染完整网格，只把脚注换成引导文案 —— 空白的热力图本身就在表达「还没有开始」。
9. 月份标签绝对定位。53 列时容器 clientWidth 814px、scrollWidth 828px，凭空多出一条横向滚动条。 根因不是格子尺寸（11px + 3px 间距本是按 814px 排的），而是月份标签的 whitespace-nowrap 把所在列 从 11px 撑到 20px 以上 —— 流内文字参与了列宽计算。改为 absolute 定位后列宽恒定，原位置只留 h-[14px] 占位块保住行高，1280 / 1024 / 900 三种宽度下 scrollWidth === clientWidth。 2026-10-25 修正：当时用 inline-flex w-fit mx-auto 想让整块居中，但 inline-flex 是行内级 元素，auto margin 在水平方向按 0 处理，居中根本没生效 —— 实测 814 的容器里左边贴 15px、右边空 60px， 整块偏左，右侧一大块空白。 改为让周列容器 flex-1 占满剩余宽度、justify-between 把富余空间均分到 52 个间隙： 宽屏时间隙从 3px 涨到 4.15px，格子保持 11×11 正方。 窄屏用 minWidth: weeks × 14 − 3（53 列 = 739px）兜住 3px 最小间隙，装不下就横向滚动 —— 格子尺寸在任何宽度下都不变，只是间隙变化。 同日二次修正：铺满后最右列顶死在容器右边界（rightGap = 0），把今天那格的 ring-1 切掉一条 —— ring 是画在元素外侧的 box-shadow，超出 overflow-x-auto 边界即被裁（实测超出 innerRight 恰好 1px）。 给内容补 pr-[15px]，即左侧星期标签列的镜像（w-3 12px + 父级 gap 3px）， 方块阵列距内容左右边界各 15px，几何上真正对称，同时给描边留出余量（ringOverflow 由 +1 变 −14）。 pt-[1px] 同理，为落在最上面一行的 today 描边留出上侧空间。 不靠 justify-center 居中：内容超宽时它会从左边缘开始裁，第一列看不见。 不把富余宽度摊给格子：那会让格子变成 12.1×11 的扁方块，14px 见方的阵列里 1px 的偏差是能看出来的。 不给 overflow 容器直接加 padding-right：历史实现里 padding 不计入 scrollWidth， 放在内层 flex 上可以绕开这个差异。
10. 热力图之后补两块内容：标签分布（「时间花在哪」）与四项细节指标（平均完成周期 / 最长连续 / 有记录 / 平均每天）。理由：热力图只回答「哪几天动了手」，回答不了「时间花在什么方向」。 两块都是既有数据的第二种切法，没有引入新存储。
11. 标签分布按「每个标签各计一次」，而不是把任务分桶到某个标签。一个任务同时属于「后端」和「安全」， 对两个方向都算贡献；因此各项之和会大于完成任务数，这一点在卡片脚注与 README 里都写明， 免得用户拿它跟「累计完成」对不上账。
12. 完成周期取中位数，并且不足一天显示「当天」。平均值会被一条躺了半年的任务拉到 60 天以上， 中位数仍然描述「大多数活多久能做完」。负数跨度（时钟回拨或被手工改过的数据）直接跳过。
13. 「平均每天」按有记录的天数算，不按自然日。按自然日会把周末与休假算成效率下降。

被否决的方案

• 新增 dailyCompletions 计数表：能得到不随删除变化的准确历史，代价是「两份真相」—— 恢复一条被删的任务要不要把计数加回去？撤销删除、合并导入、快照恢复都会撞上这个问题。 宁可数字偏保守，也不要出现「热力图说完成了 5 个，任务列表只有 3 个」。
• 把热力图放进今日视图顶部：今日视图腾不开（一排 7 个分组 + 统计卡片已经够满）， 而且它回答的不是「今天该做什么」。做成独立页面才能给足高度和一年的宽度。
• 画柱状趋势图：热力图本身就是趋势的可视化，再叠一个按周聚合的柱状图是同一组数据的第二遍表达。 确实要看「最近几周在变多还是变少」时，热力图右侧那几列的深浅已经能看出来。
• 按最大值相对分档上色：见结论 4。
• 给热力图每个格子加独立的可访问名称：一年 371 个格子逐个朗读只会变成噪音， 改为容器一个 role="img" 汇总「有多少天产生过记录、累计多少个」，格子本身 aria-hidden， 悬停的 title 作为视觉用户的补充。
• 把统计入口做成今日视图里的一个按钮：不可深链、无法收藏，PWA 的 shortcuts 也没有落点。
• 完成周期用平均值：见结论 12。平均值仍然算出来留在 completionCycle().mean 里供后续使用， 只是不作为主指标展示 —— 将来若要做「异常长尾」的提示，那个字段就是入口。
• 标签分布用饼图：六个标签的饼图无法按长度比较，且标签名必须挤在图例里。横向条形按长度对齐， 标签名左侧留白足够，还能顺便带上标签自己的颜色圆点。
• 压缩热力图格子来消除滚动条：把 11px 压到 8px 确实能塞下，但 8px 的方块已经分不清是「一格」 还是「两个挨着的格子」。滚动条是果，列宽被文字撑开才是因，改因不改果。

影响

• 新增 src/utils/activity.ts（纯函数：分组、热力图排布、汇总、连续天数、标签分布、完成周期、 最长连续）与 src/views/StatsView.vue。 组件的职责只有取数与渲染，所有口径都在纯函数里，时间可注入，便于测跨周与跨月的边界。
• 路由新增 /stats；AppNav 的入口从两个变三个，AppNav.spec.ts 的断言同步更新。
• 热力图格子带 data-role="heatmap-cell" 与 data-date / data-count / data-level， 标签条形带 data-role="tag-bar" 与 data-tag / data-count： 单测和 e2e 都靠它定位，避免依赖 size-[11px] 这类会被改动的样式类。
• 窄屏（< 768px）热力图仍然横向滚动，这是有意的：一年 53 列在手机上无法在不失真的前提下压缩。
• 数值会随删除而减少。这一点写进了 README 的已知限制，也写在统计页脚注里 —— 用户看到数字变少时能立刻知道原因，而不是怀疑数据坏了。