feat(ql3): paginate native task trigger and run ledgers

2026-09-20 16:07:11 +08:00 · 2026-09-04 03:23:21 +08:00
parent 8e1f1ed7ae
commit ce8c3a7d2a
6 changed files with 666 additions and 57 deletions
@@ -1,5 +1,7 @@
 # QingLong 3.0 Architecture RFC

+- D-431/ADR-0533（原生 Console 源码候选）：Task、Trigger、Run 列表接入既有 keyset API，开放下一页、回到首页和当前页刷新，每次最多 64 条并替换 DOM，不缓存历史页、不轮询或扩大后端查询。验证规范 cursor、页内/跨页顺序与继续边界；请求/选择代次防止旧列表、错误、详情和 Secret catalog 覆盖当前页面。客户端与生产 HTTP parser 集成 15/15、完整 Local API 114/114，静态资产共 111,857 bytes；默认 headless/Cluster 不变。远端 CI、浏览器证据和 exact 阶段实物分别核验，不借用 D-430 archive。
+
 - D-430/ADR-0532（原生 Console 源码候选）：在原生运行详情中开放日志下一片段、回到开头与当前片段刷新，固定 32 KiB 替换窗口，不累计全文或后台轮询。严格验证响应身份、字节范围与前进 cursor，按不含凭据的选择代次丢弃过期响应，防止切换或断开后覆盖新详情。复用既有 API/Policy/Audit，不新增包、依赖、迁移或后端 authority；默认 headless 与 Cluster 不变。客户端行为测试和真实 Chromium 预览覆盖分页、重复点击、过期响应与字节边界；远端 CI 和 exact 双架构 Console 实物尚待验证。

 - D-429/ADR-0531（exact 双架构 Console 阶段实物已交付）：现有面板的 Cron “日志”入口不恢复 2.x `/api/crons/:id/log` 或文件系统日志权威，而是复用规范 v3 Run/Attempt/Artifact 链。`BoundedRunListItem` 仅增加经 128 字节无控制字符验证的可选 `triggerId`；页面按 `triggerId + taskId` 在 Edge 64/Standalone 256 条 Run 总预算中定位最新 Run，再读取 detail 的 latest Attempt 与 16/32 KiB 首个日志片段，明确呈现 pending/retired/truncated。所有请求继续走 Bearer、Project Policy、durable audit、credential reconfirm 与 Artifact retention；不暴露路径、Artifact id、Secret 或其他 Run 私有字段。QL3 Action 列只开放日志，列表关闭旧 10 秒轮询，日志关闭旧 2 秒轮询，仅由初次进入、点击与手动刷新驱动；2.x 行为保持不变。没有新增 package、dependency、migration、schema、listener、连接或后台进程，headless 与 Cluster authority 不变。本地 runtime-core 594/594、Local API 93/93、全包/后端/架构审计、Node 20 production build、240 files / 11,965,017 bytes 闭包审计和真实 Chromium journey 均通过；浏览器稳定 15 秒只有一次 Cron list，日志稳定 5 秒只有 Run list/detail/log 各一次。运行时代码提交 `09ef1745226c05521a9a44accb9d9ef95dd46c85` 的主 CI run `33787481413` 为 42 success / 3 expected skip / 0 fail，Console artifact run `33789576578` 为 43 success / 2 expected skip / 0 fail；amd64/arm64/milestone artifact `9907367021`/`9907250404`/`9907412968` 保留至 2026-10-03，下载后的 `SHA256SUMS` 与 v7 离线 auditor 均返回 `compatible=true`。
@@ -0,0 +1,30 @@
+# ADR-0533：原生 Console 的任务、定时与运行列表分页
+
+- 状态：Accepted（D-431 源码候选；远端 CI 与阶段实物待验证）
+- 日期：2026-09-04
+- 关联：QL-RFC-0001 D-431、ADR-0532
+
+## 问题
+
+原生 Console 已能创建任务、配置定时、运行和读取日志，但 Task、Trigger、Run 列表在第 64 条后要求操作者自行调用 API。超过一屏的数据无法从页面到达，不能作为日常管理体验。后端已有三类规范 keyset API，不需要新增分页服务或恢复旧 Cron 权威。
+
+## 决策
+
+- 三类列表共用当前静态客户端中的小型分页逻辑，不新增 workspace package、依赖或后端路由。页脚提供“下一页”“回到首页”“刷新当前页”；顶部刷新、切换栏目和管理写入后的列表刷新从首页开始。
+- 每个显式动作最多一个列表 GET、64 条记录，替换当前 DOM；只保留当前请求边界，不缓存历史页、累积记录、自动翻页、轮询或增加总数扫描。Run 详情和日志仍按既有显式选择流程读取。
+- Task/Trigger 分别按 `taskId`/`triggerId` 升序；Run 按 `createdAtMs`、同时间戳下 `runId` 降序。客户端核对页内及跨页顺序、重复 ID、64 条上限、继续标志、完整 cursor 字段与最后一行一致性。异常页不显示继续操作。
+- 查询使用正式 HTTP parser 接受的 canonical ASCII ID；这些 ID 不含查询分隔符，不能把合法冒号编码成 parser 不接受的别名。新增测试将真实客户端生成的 URL 送入生产 HTTP surface，验证三类 continuation 被解析成正确的 typed cursor。
+- 每轮刷新绑定 Project、栏目与不含 credential 的请求代次；过期成功、失败和 finally 不覆盖新的列表、连接状态或 busy 状态。刷新清空旧详情选择；Task/Trigger 详情响应也绑定选择代次和列表代次。Secret 仍保持原有有界目录，但列表响应在提交 catalog/DOM 前同样检查代次。
+- 页脚在旧 DOM 被替换后不能再发起请求；重复点击同一个页脚只提交一次。失败的后续页保留当前边界重试与回首页入口，空的后续页不会被误报为整个 Project 没有数据。
+
+## 明确边界
+
+这不是数据库快照：浏览期间新建或更新的数据可能需要回首页重读。没有虚构总页数、随机跳页或无界上一页历史。它不包含 Secret 全目录分页、Run Event/Step 分页、筛选搜索、Cluster UI 或旧面板写操作。默认 headless 的资源和安装闭包不变。
+
+## 验证
+
+客户端测试直接执行发布的 `console.js`，覆盖三类第 65 条到达、刷新/回首页、同时间戳 Run、空页、503 重试、错误 cursor/顺序、重复点击、切换栏目、断开、同栏目重读、旧详情和旧 Secret catalog 丢弃；含真实 HTTP parser 集成合计 15/15。完整 Local API 为 114/114，无失败或跳过；完整后端 1685 项（1683 pass / 2 环境条件 skip / 0 fail）。Local image 与 18-package boundary audit 均 compatible。
+
+原生 JS 为 80,336 bytes，三项静态资产共 111,857 bytes，仍小于单文件 96 KiB / 合计 192 KiB。D-430 的 `12ed38b7` 构建不含本切片；本地测试不等于 exact 双架构产物交付。
+
+真实 Chromium 使用当前原生静态资产与合成 HTTP 数据验证了 Task、Trigger、Run 的第 65 条可达，任务详情可从第二页打开，DOM 每次只保留当前页。请求记录包含三个规范 continuation URL，浏览期间没有自动列表轮询。该浏览器证据验证交互，不冒充真实数据库、Owner 写入或双架构镜像验收。
@@ -536,6 +536,7 @@
 | [ADR-0530](./ADR-0530-bounded-local-panel-capability-bootstrap.md)                                | 有界 Local 面板能力发现与启动适配                                                                                                                                                                                                        | Accepted（D-428 exact Console 双架构阶段实物已交付） |
 | [ADR-0531](./ADR-0531-canonical-run-log-bridge-for-legacy-panel.md)                               | 现有面板到规范 Run 日志的有界桥接                                                                                                                                                                                                         | Accepted（D-429 exact Console 双架构阶段实物已交付） |
 | [ADR-0532](./ADR-0532-native-console-log-window-navigation.md) | 原生 Console 日志窗口导航 | Accepted（D-430 源码候选；实物待验证） |
+| [ADR-0533](./ADR-0533-native-console-ledger-pagination.md) | 原生 Console 任务、定时与运行列表分页 | Accepted（D-431 源码候选；实物待验证） |

 ## 规则

@@ -24,6 +24,8 @@ D-418 已闭合独立 Console image/Trial Kit；D-419 的 v5 quickstart 进一

 上表的旧面板是 bundle 自带的适配版本，不是未修改的 2.x 静态页面；旧账号密码/JWT、现有 2.x 数据和 Cluster 管理能力不会因页面可打开而自动接通。

+D-431 源码候选进一步给原生 Task、Trigger、Run 列表增加页脚“下一页／回到首页／刷新当前页”。每次只显示最多 64 条，翻页替换旧记录和详情，不累积全文；顶部刷新与切换栏目回首页，页脚刷新保留当前边界。浏览期间数据可能变化，因此不提供固定总页数或快照承诺。Secret 目录和 Run Event/Step 仍维持现有窗口限制。此功能尚未交付到上表的 D-429 或 D-430 archive，见 [ADR-0533](../adr/ADR-0533-native-console-ledger-pagination.md)。
+
 D-426b2c 又补齐了 Console 镜像的 adopted-target 入口证据：切换演练使用 `ql3-local-api --cutover-probe --config <local-api.json>`，同时绑定外层 API 配置、内层 Application 配置与 exact mounts，但该模式不会启动本页使用的 listener、credential、scheduler 或 mutation surface。正常启动仍使用下文不带 `--cutover-probe` 的命令；提交 `229c3cb4e826866a0c7c4d81cb5e52cdc3975eec` 的 [artifact run 33463415938](https://github.com/whyour/qinglong/actions/runs/33463415938) 已交付 exact amd64/arm64 Console Trial Kit 与 milestone，三份下载产物的离线 auditor 均为 `compatible=true`。

 ## 前置条件