docs: record activity history incremental save and paging (P4)

2026-10-04 00:33:19 +08:00
parent 5d0ca44b22
commit 39fc15efe0
2 changed files with 23 additions and 1 deletions
@@ -122,7 +122,7 @@ Main 负责窗口、生命周期、权限和消息转发。数据库查询、文
 | P1 | 写入和大量同步数据库调用仍在 Main；没有独立数据进程。文档解析、分块和大文件哈希已移到 worker |
 | P2 | `App.tsx` 约 7,900 行。输入区、隐藏路由、任务和结果事件、切换会话已不再整体重渲染 App；当前会话的流式吸收（每 250 ms）、队列和活动记录仍经过 App |
 | P3 | 已基本满足：流式输出和终端输出都已按帧合并 |
-| P4 | 界面仍发送整份活动记录；部分 `*Changed` 通知之后还会重新查全量 |
+| P4 | 活动记录已改为增量保存、按页读取（界面只保留已加载的页，计数和分组来自 Main 的汇总）；部分 `*Changed` 通知之后还会重新查全量 |
 | P5 | 已基本满足：消息、会话、笔记、文件树、知识库文档表格都只渲染可见部分 |
 | P6 | 已有基线（`npm run perf:startup`）：启动到输入框可用约 1.0 秒，Main 模块加载约 415 ms、本地工具环境初始化约 155 ms，还没有优化 |
 | P9 | 性能阈值还没有接入 CI，也没有真实低端机的基线 |
@@ -931,6 +931,28 @@ Renderer 主线程降速 4 倍（Main 不降速，每次 reload 后重新应用

 本轮回归：`perf:app` 60 项阈值全部通过（不降速，流式和流式打字长任务均为 0）；typecheck、全量 lint 通过；全量测试中 2 个失败分别为 OpenCode 免费额度 403 的集成用例和 `magic-notes-*` 真实 Electron 测试在整套并行负载下的偶发失败，后者单独运行和 6 个 Electron 布局测试并行连跑 3 次均通过。

+### 7.2.1 活动记录增量与分页（2026-10-04，P2/P4/P5）
+
+之前启动时整份读取活动记录（本机约 2.4 万条、10 MB），任何变化 250 ms 后把整份列表 `replace` 回 Main；Main 每次在列表前面插入记录都要重写顺序 JSON。分三次提交改完：
+
+1. **增量保存（`6aab78b`）。** 活动记录移出 App 状态，放进 `activity-store.ts`。领域动作（新增、更新请求、审批、按请求删除、按调用删除、结束请求、对账、清空）修改状态，同时排入对应的契约变更；`activity-sync.ts` 每 250 ms 用 `activityHistory.update` 发送（每次最多 2 万条），失败的变更按原顺序留在队列里，退避重试；退出和卸载前也会刷盘。清空改为新增的 `activityHistory.clear()`，Main 在一个事务里完成。
+2. **Main 分页、汇总、对账（`352da66`）。** 第 57 版 schema 重建 `activity_history_records`：`order_seq`（越新越大，移到最前就分配新的最大值）加上从记录 JSON 生成的存储列（状态、类型、请求、会话、项目、创建时间）和索引。顺序从 `record_order_json` 原样迁移；旧数据里的重复 ID 保留，仍然只显示第一条。`ActivityHistoryRepository` 负责全部 SQL：按索引倒序分页 `page`，`summary` 返回面板原来从整份列表算出的计数、会话标题和会话状态，`reconcile` 用 SQL 关联任务表（追加的说明行由界面传入本地化文本），以及 `clear`。分页和汇总走只读 worker。
+3. **界面只保留已加载的页（`bf9850a`）。** 启动顺序：发送排队的变更，Main 对账，再加载首页（200 条）。打开运行记录页时补足一批（500 条，和以前首屏一样多），“继续显示”先显示下一批，再在后台加载下一页；切换筛选会重新取首页；离开页面只留一批。计数、分组、标题、会话状态和清空数量都来自 Main 的汇总。没加载的记录也照样增量更新：`update` 新增按内容匹配的变更（`upsert-call`、`update-request`、`resolve-approval`、`settle-request`、`remove-request`、`remove-call`），由 Main 在 SQL 里执行，界面对已加载的页用同一份参考实现处理。任务刷新后的对账也改在 Main 里用 SQL 完成。旧 localStorage 记录改成增量变更迁移，界面不再调用 `replace`。
+
+`npm run perf:main`，2.4 万条活动记录，两轮结果一致（括号内为 Main 事件循环最大延迟）：
+
+| 路径 | 之前 | 之后 |
+| --- | --- | --- |
+| 启动读取 | 整份 `get`：14.2 MB，178 ms（198 ms），在 Main 上执行 | 首页 + 汇总：114 KB，16 ms，在 worker 上执行（Main 0.6 ms） |
+| 首页 200 条（同步路径，参考） | — | 1.0 ms（1.3 ms） |
+| 汇总（同步路径，参考） | — | 14 ms（15.6 ms） |
+| 保存 1 条变化 | 整份 `replace`：98 ms（114 ms） | `update`：3.9 ms（6.9 ms） |
+| 每次保存的载荷 | 整份列表（约 14 MB） | 只含变化的记录，与总量无关（单元测试：3 条变化 < 1.5 KB） |
+
+测试：随机动作序列（含翻页、截断、刷盘和注入的保存失败），在真实数据库上与改动前的整份列表逻辑逐步对比，最终数据库与整份 `replace` 的结果一致（含重复 ID 和移到最前）；启动后界面不超过一页；保存载荷只取决于变化的记录（含未加载的）；随机数据集（含重复 ID）下，分页加汇总渲染出的计数、分组、标题、状态和清空数量与整份列表渲染一致；重启后遗留的进行中记录被标为中断，说明文本相同；清空后数据库、界面和汇总都为空；SQL 变更语义与参考实现一致。`perf:app` 60 项阈值全部通过。
+
+未做：汇总按已加载的会话查询，加载 5,000 个以上会话时只取前 5,000 个；分组里“会话活动数”统计的仍是已加载的记录，和以前统计已显示的记录一致。
+
 ### 7.3 体验倒退复查（2026-10-03）

 逐一复查了所有性能提交对交互体验的影响，并新增原则 P10“体验不倒退”。发现并修复：