纯前端 ORK 目标管理工具：IndexedDB 本地存储与进度计算

目标管理这件事，卡住大多数人的从来不是工具，而是写下第一个目标那一刻的犹豫。我见过的失败案例里，十有八九不是"软件不好用"，而是"软件太重了"——要先注册、建空间、邀请成员、配置权限，折腾半小时，热情已经耗光了。所以我一直想做一个东西：打开网页就能用，数据全在自己机器上，关掉网络也能继续写，功能上把 ORK（Objectives、Results、Key results，目标与关键结果）那套方法论的核心骨架完整撑起来。这篇就是我把这个纯前端 ORK 管理软件从零做出来的完整过程记录，包括数据模型怎么拆、进度怎么算、本地存储怎么保证不丢、以及上线之后被真实使用打脸的那几个地方。适合有基础前端能力、想自己撸一个效率工具的人，也适合产品同学看看"一个目标管理工具的最小完整形态"到底长什么样。

1. 纯前端做 ORK 工具，到底是省事还是自找麻烦

先把这个决定的账算清楚。纯前端意味着没有后端、没有数据库服务、没有账号体系，所有逻辑跑在浏览器里，所有数据存在 IndexedDB 里。很多人第一反应是"这不就是个玩具吗"，但在 ORK 这个具体场景下，它的合理性比想象中高得多。

1.1 ORK 的本质是一套结构化记录，而不是协作系统

把 ORK 拆开看，它其实就是四类数据的增删改查：目标（Objective）、关键结果（Key Result）、进展记录（Check-in）、周期（Cycle）。用户的核心动作是"季度初写目标 → 每周填进展 → 季度末复盘"，整个链路上没有强实时协作需求。

我做过统计，个人和小团队（5 人以下）使用目标管理工具时，真正高频的操作是：写目标、改数字、看进度条、翻历史。这些操作全部可以在单机完成。真正的多人协同——比如两个人同时改同一个 KR 的数值——一年可能发生不了几次，为它付出后端 + 用户体系 + 权限模型的成本，非常不划算。

所以我的判断是：在第一版里，把"结构化记录"这件事做到极致，协作部分用导出/导入文件解决，是性价比最高的路径。这也是纯前端方案能成立的根本原因。

1.2 数据留在本地，反而成了一个卖点

有个做咨询的朋友跟我说过一句话，我印象很深：目标里写的东西，往往比简历还敏感——收入目标、团队问题、个人短板全在里面。让他把这些填到一个不知道服务器在哪的在线工具里，他心里是打鼓的。

本地存储在这件事上天然占优。数据不出浏览器，不经过任何网络请求，用户甚至可以断网使用。这个特性在演示的时候特别有说服力：打开开发者工具的网络面板，全程零请求，说服力比任何隐私政策都强。

代价也很明确，我必须提前想清楚并在 UI 里明确告知用户：

这张表我在需求阶段就列出来了，后面每一行都对应了具体的功能实现，而不是写完再说。

1.3 技术栈选型的三个约束条件

选型我给自己定了三条硬约束：首屏要快、离线要能用、数据层要可测试。基于这三点，最终的组合是这样的（框架部分 React 和 Vue 都可以，我下面用 React 举例，但逻辑是通用的）：

• 构建工具：Vite。冷启动和热更新速度快，产物是纯静态文件，扔到任何静态托管上就能跑，不需要 Node 运行时。
• 语言：TypeScript。这一条不可妥协，因为 ORK 的数据模型有大量嵌套和联合类型（不同类型的 KR 有不同的字段），没有类型系统，后面的进度计算逻辑会写成一团乱麻。
• 存储层：IndexedDB，用 Dexie 做薄封装。不用 localStorage 的原因后面会详细说，简单讲就是容量太小、同步阻塞、只能存字符串。
• 状态管理：Zustand 或 Pinia 这类轻量方案。目标管理的数据量不大（一个季度几十条记录），不需要重型状态库。
• 样式：Tailwind 或任意原子化方案。这个项目的 UI 元素高度重复（进度条、标签、输入行），原子化写起来最快。

真正需要花心思的不是"用哪个框架"，而是数据层怎么和 UI 解耦。我采用的是经典的三层：UI 组件 → 状态层（含派生计算）→ 仓储层（Repository，唯一接触 IndexedDB 的地方）。这个分层在第 4 章会展开讲，它是整个项目能不能长期维护的关键。

提示：如果你也打算做类似工具，第一条要守住的纪律是——任何组件里都不允许直接出现 IndexedDB 的调用。所有读写必须经过仓储层，否则后面加缓存、加迁移、加测试的时候会哭。

2. 把 ORK 拆成四张表，数据结构定生死

我做这类工具有一个习惯：先不写一行 UI，先把数据模型在纸上画完。因为目标管理软件最怕的就是"用着用着发现数据存不下"，等到有用户数据了再改结构，迁移成本会高到你想推倒重来。

2.1 四个核心实体的字段设计

先说 Objective。它承载的是"方向"，字段要少而准：

interface Objective { id: string; // uuid，客户端生成，保证可离线创建 title: string; description?: string; cycleId: string; // 所属周期，如 "2025-Q2" parentId: string | null; // 上级目标，顶层为 null status: 'active' | 'done' | 'archived'; orderKey: string; // 排序用，见 5.2 节 createdAt: number; updatedAt: number; }

KeyResult 是重点，因为我让一个 KR 支持多种度量方式，这是它比"一个进度条"复杂的地方：

type KRType = 'percent' | 'number' | 'boolean' | 'milestone'; interface KeyResult { id: string; objectiveId: string; title: string; type: KRType; startValue: number; // 起始值，number 类型必填 targetValue: number; // 目标值 currentValue: number; // 当前值 unit?: string; // 单位，如 "%"、"个"、"篇" weight: number; // 权重，默认 1 confidence: number; // 信心指数 1-10 milestones?: { id: string; title: string; done: boolean }[]; // 里程碑型专用 createdAt: number; updatedAt: number; }

CheckIn 是流水，只增不改（改动用软删除标记），这样能完整还原一条 KR 的变化曲线：

interface CheckIn { id: string; krId: string; value: number; confidence: number; note?: string; createdAt: number; }

Cycle 相对简单，但有个细节：周期不能只存名字，必须存起止时间戳，因为健康度计算要按"已过时间占比"来算。

interface Cycle { id: string; // "2025-Q2" name: string; // "2025 年第二季度" startAt: number; // 毫秒时间戳 endAt: number; status: 'planning' | 'active' | 'closed'; }

2.2 对齐关系：为什么我最终放弃了单 parentId

ORK 的精髓之一是"对齐"——下级目标要能说清楚自己支撑了哪个上级目标。一开始我用的是 Objective 上的parentId单字段，简单直接。做到第二周就撞墙了：一个团队的目标，经常同时支撑两个上级目标，比如"提升内容产出效率"既服务于"用户增长"也服务于"品牌建设"。

单 parentId 逼着用户二选一，这在真实场景里是错的。所以我改成了独立的关系表：

interface Alignment { id: string; fromObjectiveId: string; // 下级 toObjectiveId: string; // 上级 weight: number; // 这个下级对上级的贡献权重 }

改完之后立刻多出两个必须处理的问题：环检测和权重归一。

环检测好理解——A 支撑 B，B 又支撑 A，递归计算进度的时候会栈溢出。我的做法是在写入 Alignment 之前做一次深度优先搜索，检查toObjectiveId是否已经能到达fromObjectiveId，如果能到达就拒绝写入。这个检查必须在写库之前同步完成，不能放到渲染时再判断，否则脏数据已经进库了。

权重归一是个容易被忽略的细节。假设上级目标 A 有三个下级目标支撑，权重分别是 2、1、1，那 A 的进度应该是(B进度×2 + C进度×1 + D进度×1) / 4，而不是除以 3。我第一版就漏了归一，导致进度条经常超过 100%。这个 bug 在测试阶段没被发现，因为测试数据里权重全是 1，一除以 N 看不出问题，直到我自己录入真实数据才炸出来。

2.3 IndexedDB 的索引怎么建

用 Dexie 建表的时候，声明字符串里的加号代表复合索引，方括号代表联合索引，这个语法一开始很反直觉，我列一下最终版本：

db.version(3).stores({ objectives: 'id, cycleId, parentId, status, orderKey', keyResults: 'id, objectiveId, [objectiveId+orderKey]', checkIns: 'id, krId, [krId+createdAt], createdAt', alignments: 'id, fromObjectiveId, toObjectiveId', cycles: 'id, status, startAt', meta: 'key' });

几个索引的用途说明一下，这些都是实际查询时被逼出来的：

• keyResults上的[objectiveId+orderKey]复合索引：目标详情页要按顺序拉取某个 O 下的所有 KR，有复合索引可以一次范围查询搞定，不用取出来再排序。
• checkIns上的[krId+createdAt]：画趋势图时按 KR 取时间序列，这是最高频的查询之一。
• alignments上的两个索引：既要查"我的上级是谁"，也要查"谁支撑了我"，两个方向都得快。

还有一点值得单独说：所有主键都用客户端生成的 uuid。不用自增 ID 的原因很简单——纯前端没有中心化的 ID 分配器，多标签页同时打开时自增会冲突。uuid 生成成本可以忽略，换来的是彻底避免 ID 冲突，以及导入外部数据时不会和现有数据撞号。

3. 进度与健康度：ORK 软件最容易做错的地方

如果只能保留一个功能，我留进度计算。这块看起来是小学数学，实际是重灾区——我见过太多工具在这里偷懒，用简单平均糊弄过去，结果就是整套方法论失真。

3.1 四种 KR 类型，四条不同的进度公式

不同类型的 KR，进度算法完全不同，不能一把梭：

百分比型：最直观，progress = currentValue / 100。适合"完成度""覆盖率"这种天然带百分比的事情。

数值型：这是最容易写错的一个。正确公式是(current - start) / (target - start)，而不是current / target。举例：起始值 20，目标值 100，当前 60，正确进度是(60-20)/(100-20) = 50%，而错误的算法会给出 60%。差别在于前者承认了"起点已经有的基础"。

布尔型：只有完成和未完成，progress = done ? 1 : 0。看起来简单，但要处理一个语义问题：一个被标记为完成的 KR，如果后续被改回未完成，历史 Check-in 该怎么算？我的处理是以最新状态为准，历史记录保留但只用于展示。

里程碑型：progress = 已完成里程碑数 / 总里程碑数。它的存在价值在于让"上线一个大功能"这种模糊目标可以被拆开度量。

这里有个坑必须提：逆向指标。像"线上事故数降到 5 次以下""页面加载时间降到 800ms"这类目标，target 小于 start。如果不特殊处理，数值型公式会算出负数进度。我的做法是不改公式，而是在计算前统一判断方向：

function calcNumberProgress(kr: KeyResult): number { const { startValue: s, targetValue: t, currentValue: c } = kr; if (t === s) return c >= t ? 1 : 0; // 防止除零 const raw = (c - s) / (t - s); return clamp(raw, 0, 1); } function clamp(v: number, min: number, max: number) { return Math.min(max, Math.max(min, v)); }

clamp这一步不能省。因为"降事故数"这种目标，如果当前值已经低于目标值，(c-s)/(t-s)会算出大于 1 的数，不截断的话进度条会溢出。更麻烦的是负数——如果当前值比起点还差（事故数涨了），会算出负数，进度条渲染直接变形。截断到 [0,1] 之后，语义也更清晰：你已经完成了，或者你一点没动。

3.2 加权汇总：简单平均是方法论杀手

假设一个目标有三个 KR：KR1 权重 3（最重要的核心指标，当前 10%）、KR2 权重 1（当前 100%）、KR3 权重 1（当前 100%）。简单平均算出来是 70%，看起来还不错；加权算出来是(0.1×3 + 1×1 + 1×1) / 5 = 26%，这才是真实情况——最重要的那件事几乎没动。

ORK 方法论里，权重就是"你有多在乎"的量化表达。抹掉权重，工具就退化成待办清单了。所以我把权重做成了必填项，默认值都是 1，但 UI 上会明确提示"重要的 KR 请调高权重"。

汇总到 Objective 层的完整逻辑是这样的：

function objectiveProgress( obj: Objective, krs: KeyResult[], childObjectives: { progress: number; weight: number }[] ): number { const own = krs.length ? krs.reduce((sum, kr) => sum + krProgress(kr) * kr.weight, 0) / krs.reduce((sum, kr) => sum + kr.weight, 0) : null; const fromChildren = childObjectives.length ? childObjectives.reduce((s, c) => s + c.progress * c.weight, 0) / childObjectives.reduce((s, c) => s + c.weight, 0) : null; if (own === null && fromChildren === null) return 0; if (own === null) return fromChildren!; if (fromChildren === null) return own; return (own + fromChildren) / 2; // 自身 KR 与下级目标各占一半 }

最后那一行(own + fromChildren) / 2是我权衡过的结果。理论上应该再给权重，但实测下来用户很难理解"我的 KR 和我的子目标谁更重要"这种抽象问题，五五开是个可解释的默认值，而且我在 UI 上把两部分进度分开显示了，用户能看明白这个数字是怎么来的。

还有个边界情况：父目标的进度是递归计算的，必须做记忆化。一个三层结构的目标树，如果每次都从头递归，每次输入框变化都触发全量重算，在中低端手机上会明显掉帧。我加了一个按objectiveId + updatedAt缓存的 Map，只要数据没变就直接命中。

3.3 健康度：用斜率判断"还来不来得及"

进度条只告诉你走了多远，不告诉你走得多快。ORK 复盘时真正有价值的问题是"按现在这个速度，季度末能不能达成"。这就是健康度。

我的算法不复杂，但阈值调了好几轮。核心思路是：取最近 N 次 Check-in（N 默认 3，少于 2 次就跳过判断），对(时间, 进度)做一元线性回归得到斜率，然后和"剩余时间内的所需斜率"做对比。

function healthOf(kr: KeyResult, checkIns: CheckIn[], cycle: Cycle) { if (checkIns.length < 2) return 'unknown'; const pts = checkIns.slice(-3).map(c => ({ x: (c.createdAt - cycle.startAt) / DAY, y: c.value })); const slope = linearSlope(pts); // 每天涨多少 const remainDays = Math.max(1, (cycle.endAt - Date.now()) / DAY); const need = (kr.targetValue - kr.currentValue) / remainDays; if (need <= 0) return 'done'; if (slope <= 0) return 'red'; const ratio = slope / need; if (ratio >= 1) return 'green'; if (ratio >= 0.6) return 'yellow'; return 'red'; } function linearSlope(pts: { x: number; y: number }[]): number { const n = pts.length; const sx = pts.reduce((s, p) => s + p.x, 0); const sy = pts.reduce((s, p) => s + p.y, 0); const sxy = pts.reduce((s, p) => s + p.x * p.y, 0); const sxx = pts.reduce((s, p) => s + p.x * p.x, 0); const denom = n * sxx - sx * sx; if (Math.abs(denom) < 1e-9) return 0; return (n * sxy - sx * sy) / denom; }

这个 0.6 的阈值是我自己用了一个季度之后定的。最初用 0.8，结果满屏飘红，反而让人焦虑到放弃看；改成 0.5 又太宽松，到最后一周才发现红了已经来不及。0.6 大致对应"当前速度只有需求的六成，需要加把劲但还有救"。

注意：健康度用的是斜率而不是绝对值，这点很关键。一个进度只有 20% 的 KR，如果每周围都在稳步上涨，它是绿的；一个进度 90% 的 KR，如果过去三周一动不动，它应该是红的。只看绝对值的工具，会把最危险的情况藏起来。

4. 状态层与持久化：纯前端的数据可靠性该怎么做

纯前端最容易翻车的地方不是 UI，是数据。用户敲了半小时的目标，一个刷新全没了，这个产品就死了。我在这一层花的精力比 UI 多得多。

4.1 三层架构：UI 只负责渲染，仓储只负责存取

我把代码分成三层，边界非常清楚：

• 仓储层（Repository）：唯一的 IndexedDB 入口，提供listObjectives(cycleId)、upsertKeyResult(kr)这类方法，返回 Promise。
• 状态层（Store）：内存中的完整数据快照 + 所有派生计算（进度、健康度、排序后的列表）。UI 从这里订阅。
• UI 层：纯展示和事件转发，拿到数据就渲染，不要做任何计算。

写操作走的是"乐观更新 + 异步落盘"：先在内存里改，UI 立刻响应，然后再把变更写进 IndexedDB。这里有个关键设计——写操作要进队列。因为用户快速连点进度 +1 按钮时，可能同时触发十几个写请求，如果不管顺序，后写的可能被先写的覆盖。

class WriteQueue { private chain: Promise<void> = Promise.resolve(); push(task: () => Promise<void>): Promise<void> { this.chain = this.chain.then(task).catch(err => { console.error('[write-queue] task failed', err); }); return this.chain; } }

用 Promise 链做串行化是最省事的办法，不需要引入任何库。代价是同一时刻只有一个写操作在执行，但 ORK 这种数据量，这个代价完全可以接受。

4.2 IndexedDB 事务的坑：await 一下就没了

这是我在整个项目里踩得最深的一个坑，值得单独讲。

IndexedDB 的事务有一个非常反直觉的规则：当事务创建之后，如果当前事件循环里没有新的请求被排入队列，事务会自动提交（commit）。翻译成人话就是，如果你在事务回调里await了一个和 IndexedDB 无关的操作（比如一个 fetch、一个 setTimeout、一个文件读取），等你 await 回来，事务已经是 inactive 状态了，后续任何请求都会抛TransactionInactiveError。

我最初的代码是这样写的，看起来很合理：

// 错误写法 await db.transaction('rw', db.keyResults, db.checkIns, async () => { const kr = await db.keyResults.get(id); // 这一步之后就危险了 const computed = await someAsyncCalc(kr); // 只要这里有 await，事务可能已提交 await db.keyResults.put({ ...kr, ...computed }); });

修复方式很朴素，但需要纪律：把所有纯计算放在事务外面，事务内部只留 IndexedDB 操作。

// 正确写法 const kr = await db.keyResults.get(id); // 独立读 const computed = someSyncCalc(kr); // 纯同步计算 await db.transaction('rw', db.keyResults, db.checkIns, async () => { await db.keyResults.put({ ...kr, ...computed }); await db.checkIns.add(buildCheckIn(kr, computed)); });

这个改动看起来只是挪了位置，但它是"数据偶发丢失"这类玄学问题的根源。如果你在做类似项目，我建议一开始就把这条纪律写进代码规范里。

4.3 数据迁移：schema 从 v1 到 v3 的实操

只要产品还在迭代，schema 就一定会变。我从 v1 到 v3 改了两次结构：v1 是 Objective 带 parentId 的单亲模式；v2 引入了 Alignment 表；v3 给 KeyResult 加了 weight 和 milestones。

Dexie 的版本机制是链式的，每次db.version(n)只在上一个版本升级完成后执行：

db.version(1).stores({ objectives: 'id, cycleId, parentId', keyResults: 'id, objectiveId', checkIns: 'id, krId' }); db.version(2).stores({ alignments: 'id, fromObjectiveId, toObjectiveId' }).upgrade(async tx => { // 把 v1 的 parentId 迁移成 Alignment 记录 const objs = await tx.table('objectives').toArray(); const rows = objs .filter(o => o.parentId) .map(o => ({ id: crypto.randomUUID(), fromObjectiveId: o.id, toObjectiveId: o.parentId, weight: 1 })); if (rows.length) await tx.table('alignments').bulkAdd(rows); }); db.version(3).stores({ keyResults: 'id, objectiveId, [objectiveId+orderKey]' }).upgrade(async tx => { await tx.table('keyResults').toCollection().modify(kr => { if (kr.weight == null) kr.weight = 1; if (kr.confidence == null) kr.confidence = 5; }); });

有三条经验值得分享：

第一，迁移函数必须幂等。如果用户升级到一半关掉页面，下次打开会重新跑一次迁移。我在 v3 里用了if (kr.weight == null)这种判断，而不是无脑赋值，就是为了幂等。

第二，迁移前自动备份。执行version之前，我先把整个库 dump 成一个 JSON 存到 meta 表里。这样即使用户升级后发现问题，也能通过一个隐藏入口回滚。这个功能从来没被用过，但我知道它在那儿就安心。

第三，永远不要删除旧版本的stores声明。Dexie 需要完整的版本链才能从 v1 直升 v3，删掉 v1 的声明会让老用户升级失败。

5. 交互细节：决定这个工具"有没有人用"

到这里，功能其实已经完整了：能建目标、能填 KR、能打卡、能看进度。但我很清楚，功能完整和目标管理工具真的被用起来，是两件事。目标管理是典型的"低频高意愿、极易半途而废"的场景，交互摩擦每增加一点，放弃的概率就上升一点。

5.1 键盘流和内联编辑，是我最满意的两个设计

我自己用了一个季度之后，最大的感受是：填进展这件事必须快到不需要思考。所以我做了几乎全键盘的操作路径：

• N：新建目标
• E：编辑当前选中的条目
• Esc：取消编辑
• Cmd/Ctrl + Enter：保存
• ↑ / ↓：在 KR 列表里移动
• 1-5：快速给信心指数打分

内联编辑这块，我踩了一个中文输入法的大坑。一开始用的是contentEditable，结果发现每次中文输入法还在拼写候选阶段，input事件就触发了，导致每敲一个拼音字母就保存一次，字符串被截断得乱七八糟。后来换成textarea配合自动高度，并且用compositionstart/compositionend事件来控制保存时机：

let composing = false; textarea.addEventListener('compositionstart', () => { composing = true; }); textarea.addEventListener('compositionend', () => { composing = false; }); textarea.addEventListener('input', () => { if (composing) return; // 输入法拼写过程中不保存 autoResize(textarea); scheduleSave(textarea.value); });

scheduleSave用的防抖是 400ms。这个值我调过几次：200ms 太频繁，打字快的时候会触发大量写入；800ms 又会让用户在打字后立刻关闭页面时丢失最后一句。400ms 是一个体感上"几乎即时保存"又不至于频繁写库的平衡点。

配套的还有自动高度：

function autoResize(el: HTMLTextAreaElement) { el.style.height = 'auto'; el.style.height = `${el.scrollHeight}px`; }

这两行代码解决了"输入框高度跳动"和"内容被截断"两个问题，成本几乎为零，收益极大。

5.2 拖拽排序：为什么我放弃了整数 sortIndex

KR 的排序是很自然的需求——用户想按重要性从上到下排列。最直觉的做法是整数字段sortIndex，但用整数的代价是：每次插入都要重排后面所有记录。一个目标下有 10 个 KR，把最后一个拖到第一位，就要写 10 条记录。虽然数据量不大，但配合乐观更新和事务，代码会变得很啰嗦，而且并发时容易产生顺序错乱。

我改用 fractional indexing（分数索引），思路是每次插入时取相邻两个元素 orderKey 的中间值：

function midKey(prev?: string, next?: string): string { if (!prev && !next) return 'm'; if (!prev) return shiftDown(next!); if (!next) return shiftUp(prev); return between(prev, next); } // 简化实现：用浮点数 function betweenSimple(prev: string, next: string): string { const a = parseFloat(prev), b = parseFloat(next); return String((a + b) / 2); }

浮点数版本写起来简单，但有个致命缺陷：精度会被耗尽。字符串长度固定 53 位有效数字的情况下，两个数之间反复取中值，大概 50 次之后就没有间隙了，插入会失败。

所以我实际用的是基于字符串的版本，思路是把排序键当成 36 进制的小数，在两个字符串之间生成一个新的字符串。核心是找到第一个不同的字符位置，在它中间插入一个字符；如果没间隙，就往后补位。这套算法在开源社区有成熟实现，思路不复杂但边界条件很多，我建议直接移植一个经过验证的实现，不要自己从零推。

拖拽的交互实现上，我没有用 HTML5 的 drag and drop API。原因很实际：它在移动端基本不可用，触屏设备上会触发页面滚动而不是拖拽。改用 Pointer Events 之后，拖拽逻辑统一了，移动端和桌面端是一套代码：

// 简化后的拖拽流程 onPointerDown -> 记录起点、设置 setPointerCapture onPointerMove -> 超过 4px 阈值才认定为拖拽，更新占位位置 onPointerUp -> 计算目标位置，写入新的 orderKey

那个 4px 的阈值很重要，不加的话轻点也会被误判成拖拽，导致点击事件失效。

5.3 周期切换：默认视图就该是"现在"

周期这个设计我纠结过很久。有的工具需要用户手动选择"我要看哪个季度"，多一步操作；有的工具只显示当前周期，历史数据要翻好几层。

我的方案是：默认永远显示当前周期，顶部有一个横向的周期切换器，历史周期以"归档"的形式平铺在旁边。用户打开就干活，想复盘就点一下。

这里有个容易被忽略的细节——周期边界的自动切换。用户可能在 4 月 1 日凌晨打开应用，这时候"当前周期"应该自动变成 Q2，但如果 Q2 还不存在，是自动创建还是提示用户？我选择了自动创建：如果今天落在某个周期的区间内但库里没有对应记录，就静默创建一个空的 cycles 记录。用户不会看到任何弹窗，写第一个目标时它已经在那儿了。

另外还做了个"时间旅行"的小功能：在周期选择器上按住 Shift 点击，可以查看任意时间点的数据快照（基于 Check-in 历史重建）。这个功能使用频率不高，但在做季度复盘的时候特别好用——能看到某个 KR 在第三周是什么状态，从而判断是"一开始就没想清楚"还是"中途掉队了"。

6. 数据逃生舱：导入导出和存储保底

纯前端没有服务器兜底，那"数据安全"这件事就只能靠用户自己。所以我把导入导出做成了核心功能，而不是藏在设置里的附属品。

6.1 JSON 全量备份必须带版本号和校验

导出的 JSON 长这样，几个字段是刻意留的：

{ "format": "ork-backup", "schemaVersion": 3, "exportedAt": 1730000000000, "checksum": "sha256:...", "data": { "objectives": [], "keyResults": [], "checkIns": [], "alignments": [], "cycles": [] } }

schemaVersion是给导入端用的：如果用户的备份是 v2 导出的，而当前应用是 v3，导入时就要跑一遍迁移逻辑，否则字段缺失会导致整个应用报错。checksum用于防御"文件被部分下载"的情况——用户从网盘下了一个断掉的 JSON，没有校验的话会导入一半然后数据错乱。

导入流程我设计得比较保守，因为它是最危险的写操作：

1. 读取文件 → JSON.parse，失败直接报错。
2. 校验format和schemaVersion，不匹配就走迁移。
3. 逐表做结构校验（字段类型、必填项、外键存在性）。
4. 展示预览："将导入 12 个目标、47 个 KR、183 条进展记录"。
5. 用户确认后，先自动导出一份当前数据作为回滚点。
6. 执行导入，采用upsert 而非清空重建，避免误删本地新数据。

第 6 步的策略值得多说一句。有些工具导入时会先清空再写入，逻辑简单但非常危险——用户本来只想补充几条数据，结果把本地的东西全洗了。用 upsert 的话，同 id 的覆盖、不同 id 的新增，行为更符合直觉。当然，如果用户明确选择"完全替换"，那另说。

6.2 Markdown 和 CSV，各有各的用处

导出 HTML 或者 PDF 适合存档，但我发现自己实际用得最多的是两种纯文本格式：

Markdown用于季度复盘。结构大致是这样：

## 目标：把内容生产效率提升 50% **总进度**：62%（加权） ### KR1 单篇稿件的平均产出时间从 8 小时降到 4 小时 - 类型：数值（逆向） - 当前：5.2 小时 / 目标：4 小时 - 进度：70% - 健康度：绿 - 最近记录： - 06-12 5.2h 信心 7 - 模板化改造已生效 - 06-05 6.0h 信心 6

导出成 Markdown 的好处是能直接粘进任何笔记工具，也能被搜索引擎检索。比封在 IndexedDB 里强得多。

CSV用于向上汇报。领导要的通常是一张能塞进表格的清单，一行一个 KR，带进度和负责人。做这个功能的时候我特意加了一个"仅导出当前周期"的选项，不然全量几百行导出去没人看。

6.3 存储被清掉怎么办：能做的防御都做了

这是纯前端方案的固有风险，我没法彻底消除，但做了三层防御：

第一层，申请持久化存储权限。navigator.storage.persist()可以请求浏览器不要自动清理这个站点的数据：

async function ensurePersistent() { if (!navigator.storage?.persist) return false; if (await navigator.storage.persisted()) return true; return await navigator.storage.persist(); }

这个 API 的授予策略各浏览器不同，有的看用户是否安装为应用、是否加了书签、是否有过交互。所以调用时机放在用户创建第一个目标之后，成功率比首屏就调高得多。

第二层，做成 PWA。加上 manifest 和 service worker，用户可以"安装"到桌面或主屏。安装后的应用在存储策略上通常更宽松，而且能离线启动——这两个收益都很实在。

第三层，也是最有效的一层：把"该备份了"做成可见的状态。我在顶栏放了一个小圆点，记录"上次导出时间"，超过 14 天变成橙色，超过 30 天变红。点击就弹出导出面板。这个设计比任何提示文案都管用——用户看到颜色变化会主动点一下，而一条"请定期备份"的提示会被永久无视。

提示：千万不要用 localStorage 当主力存储。它有两个硬伤：容量通常只有 5MB 左右（一个季度的 Check-in 加上备注很快就到顶），以及它是同步 API，在存大 JSON 时会阻塞主线程，输入框会明显卡顿。localStorage 我只用来存 UI 偏好（比如上次选中的周期、侧栏是否展开），这类数据丢了也无所谓。

7. 上线后被打脸的六个问题

这部分是我最想写的，因为前面那些设计再周全，真实使用还是会把没想过的地方一个个捅出来。

7.1 日期与时区：跨时区的"今天"不是一个今天

第一版我用new Date().toISOString().slice(0,10)存日期字符串，在本地测得好好的。后来一位出差的朋友反馈说，他的打卡记录时间戳显示成了前一天。

原因很清楚：toISOString()永远返回 UTC 时间，UTC+8 的晚上 8 点，转成 UTC 是当天 12 点（没问题），但凌晨 1 点转成 UTC 就是前一天的 17 点。所有涉及"哪一天"的判断全错位了。

修复方案是所有时间戳统一存毫秒数，格式化在展示层做，按本地时区：

// 存的时候：永远存时间戳 const createdAt = Date.now(); // 展示的时候：按本地时区格式化 function formatDay(ts: number): string { const d = new Date(ts); return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`; }

这个原则看起来是常识，但在写第一版的时候真的很容易图省事用字符串。教训是：凡是涉及日期的地方，存时间戳，绝不存字符串。

7.2 数字输入的精度：0.1 + 0.2 不是 0.3

KR 的当前值可能是小数（比如"平均响应时间 1.3 秒"），进度条又需要百分比。中间经过currentValue / targetValue * 100一系列浮点运算，展示时会出现66.66666666666667%这种鬼东西。

处理方式是两层：计算过程不做任何取整，只在最终展示时格式化，并且用toFixed(1)而不是Math.round保留一位小数。另外绝对不要用浮点数做等值比较，判断"是否达成目标"要用容差：

const reached = Math.abs(current - target) < 1e-6;

7.3 空目标的除零：0 除以 0 是 NaN，不是 0

新建一个目标但还没加 KR 的时候，进度的分母是 0。第一版直接算，得到NaN，然后进度条宽度变成NaN%，整个 UI 布局会崩掉——浏览器遇到非法宽度值会忽略该属性，进度条就消失了。

修法是在所有汇总函数的入口做守卫：

function safeDivide(numerator: number, denominator: number, fallback = 0) { if (!Number.isFinite(denominator) || denominator === 0) return fallback; const r = numerator / denominator; return Number.isFinite(r) ? r : fallback; }

这个函数在整个项目里被调用了三十多次。事后看，这应该是第一天就写的工具函数。

7.4 对齐环导致的递归爆栈

虽然我在写入时做了环检测，但还是漏了一条路径：导入数据的时候没走检测。用户从别人那里拿到一份 JSON，里面正好有个环（可能是手工编辑过的），导入之后一渲染整个页面就白屏，控制台刷出一屏Maximum call stack size exceeded。

补了两个地方：导入校验阶段加环检测；递归函数本身加深度上限和访问集合：

function collectDescendants(rootId: string, edges: Alignment[], seen = new Set<string>()): string[] { if (seen.has(rootId) || seen.size > 500) return []; seen.add(rootId); const children = edges.filter(e => e.toObjectiveId === rootId).map(e => e.fromObjectiveId); return children.flatMap(c => [c, ...collectDescendants(c, edges, seen)]); }

seen集合既解决环，也顺便解决了菱形依赖导致的重复计算。深度上限则是一道兜底保险——宁可少算，不能白屏。

7.5 大量 Check-in 让列表卡顿

一个用了半年的用户，Check-in 记录可能过千条。第一版我是全量toArray()拉出来再在内存里过滤，页面加载时明显能感觉到卡。后来做了三件事：

• 分页读取：列表只取最近 50 条，滚动到底部再取下一页。
• 虚拟滚动：长列表只渲染可视区域的十几行，配合IntersectionObserver做懒加载。
• 趋势图按需查询：只在用户展开某个 KR 时才去查它的时间序列，而不是一次性全查。

改完之后首屏加载从接近 2 秒降到 200 毫秒以内。这个优化让我意识到：纯前端不代表性能自动好，浏览器里的数据量也是会增长的。

7.6 撤销：用户删掉一个目标，五秒后才反应过来

删除操作是最容易出事的。我最初的实现是弹个确认框"确定删除吗"，但用户点确定的速度比看文案快得多。

改成软删除 + 延迟清理之后体验好很多：删除时只把status标成archived并记录deletedAt，UI 立刻移除，同时右下角弹出"已删除，撤销"提示条，8 秒后提示条消失，真正的物理删除放到下次应用启动时执行。

这套机制还顺带解决了另一个问题：用户误删之后关掉页面重开，只要还在宽限期内（我设的是下次启动前），数据依然能通过历史入口找回。

8. 后续还能往哪儿长

如果这个工具继续迭代，我脑子里排队的几个方向是这样的。第一是多标签页同步，现在两个标签页同时打开会各写各的，用BroadcastChannel做一次写后广播就能解决，成本很低但体验提升明显。第二是目标模板，把我自己用下来觉得好用的几套季初模板内置进去，用户新建周期时可以直接套用，这比教方法论有用得多。第三是复盘引导，季度末生成一份带提问的复盘页——"哪个 KR 掉队最严重、原因写一句"——引导用户把数据变成结论，而不是看完进度条就关掉。

我个人在实际操作中的体会是，做这类工具最大的诱惑是不断加功能，而真正的门槛在于"减法"：哪些字段是必须的，哪些视图可以直接砍掉，哪个按钮应该让用户永远不用点。我砍掉过甘特图、砍掉过标签系统、砍掉过自定义字段，每一次都心疼，但每次砍完产品都更清楚。如果你的目标也是做一个自己愿意天天打开的效率工具，建议先把"每周填一次进展"这条最短路径打磨到极致的顺滑，剩下的都可以慢慢来。