open-source/qinglong
1
0
Fork 0
mirror of https://github.com/whyour/qinglong.git synced 2026-09-20 16:07:11 +08:00
Code Issues Packages Projects Releases Wiki Activity

test(ql3): lock legacy core api contracts

Browse Source
This commit is contained in:
whyour
2026-08-20 15:41:39 +08:00
parent c0ef9a969e
commit 0c503932cc
4 changed files with 478 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/adr/ADR-0471-legacy-core-api-compatibility-baseline.md
+65
View File
@@ -0,0 +1,65 @@
# ADR-0471：Legacy 核心执行 API 兼容基线
- 状态：Accepted
- 日期：2026-08-20
- 关联 RFC：QL-RFC-0001 D-378、PR-0、Runtime Milestone Gate
- 关联 ADR：ADR-0002、ADR-0445、ADR-0454、ADR-0470
## 上下文
QingLong 3.0 已经具备 Shadow Run、受门禁的 Manual Primary、Run/Event、取消恢复和本地/集群执行协议，但这些新能力不能以破坏 2.x
Cron 与 Subscription API 为代价。现有路由仍是 Web UI、Shell、Open API 适配层和大量部署脚本的产品契约；仅验证 Runtime 内部状态机，不能证明
3.0 开关两侧仍保留相同的 HTTP method、path、请求校验、服务参数和响应 envelope。
首个兼容基线应从最靠近现有用户执行闭环的路径开始：Cron 与 Subscription 的列表、创建、更新、启停、手动运行、停止和日志。测试必须执行真实
Express Router 与 Celebrate 校验器，而不是复制一份路径清单或只搜索源码。它也不能为了测试方便启动完整 QingLong master/worker、数据库、gRPC、
Scheduler 或任何 3.0 后台 lifecycle。
## 决策
1. 增加独立的真实回环 HTTP 契约测试，直接注册生产 `back/api/cron.ts` 与 `back/api/subscription.ts` Router，并挂载在现行 `/api` 前缀。
2. 服务层使用 TypeDI 注入的确定性 spy，因此测试只裁决 Router 责任：HTTP method/path、Celebrate request contract、参数透传、2.x response envelope
与错误请求在 service dispatch 前拒绝。它不伪造数据库、进程或 Scheduler 集成证据。
3. Cron 基线覆盖 list、create、update、disable、enable、run、stop、单日志、日志列表和单实例 stop。`run|stop|enable|disable` 继续返回
`{code: 200}`，不得因为 3.0 内部拥有 Run ID 而向 2.x 成功 envelope 强塞 v3 字段。
4. Subscription 基线覆盖 list、create、update、disable、enable、run、stop 和日志；`searchValue`、`ids` 与 numeric ID 的现有转换语义保持不变。
5. 非法 Cron run 与 Subscription stop body 必须由真实校验器返回 HTTP 400，且 service spy 调用数保持不变，证明无副作用 dispatch。
6. 本切片只增加测试、ADR 和 RFC 状态，不修改任何生产 function/class/method，不新增依赖、package、binary、schema、migration、端口、服务、timer、
queue、cache、数据库连接或部署对象。测试结束时关闭临时回环 listener 并清理 TypeDI token。
7. 本基线不是“完整 2.x 兼容已完成”的声明。System、Script、Open API、鉴权/错误码、真实 SQLite 升级、Primary 开关双态、目标实例回滚和 UI/Shell
仍须后续独立 contract 与 rehearsal，完成前 Runtime Milestone Gate 保持未关闭。
## 被拒绝的替代方案
### 只用正则扫描路由源码
拒绝。文本存在不能证明路由注册顺序、校验器转换、TypeDI 调用和实际 JSON 序列化行为。
### 启动完整 QingLong 服务作为每次后端单测前置条件
拒绝。它会把数据库、gRPC、cluster fork、文件系统和调度器故障混入 Router contract，增加低配开发机和 CI 的成本，也无法精确定位兼容漂移。
### 让 2.x run 响应直接返回 QingLong 3.0 Run 对象
拒绝。现有客户端依赖 code-only 的异步接受语义；Run/Event 应通过 `/api/v3` 或后续显式兼容扩展发现，不能静默改变 2.x envelope。
### 将全部 2.x API 一次性冻结在一个超大测试中
拒绝。首个阶段优先覆盖执行主路径，并明确登记剩余域；后续 contract 应按 Identity/Open API、System/Script、文件与日志等稳定产品边界扩展，避免难以维护的
单体 fixture。
## 升级与回滚
- 本切片没有生产行为和持久化变更。升级只增加 CI 回归门，运行中实例不加载测试文件。
- 若契约基线本身错误，可回滚测试、ADR 与 RFC 增量；不得通过删除测试掩盖真实 2.x 兼容回归，应先由 Maintainer 明确批准兼容变更。
## 验证与证据
- 聚焦真实 Router 契约为 `18/18`，覆盖 16 个成功路径/子路径和 2 个校验前拒绝路径；每个成功路径同时校验 HTTP 状态、JSON envelope 与 service 参数。
- 完整 backend 为 `1,523 total / 1,521 pass / 2 conditional skip / 0 fail`；18-package clean build 与逐包测试在允许既有 Worker TLS
回环门后单次退出 0。
- package boundary、Cluster dependency、Edge import、Cluster/Worker deployment、Console 与 Console distribution 七项审计全部
compatible/passed；workspace 仍为 18 packages、`singleSourcePackages=[]`、`shallowSourcePackages=[]`。
- 14 档 Local artifact audit 全部 compatible；基础 Edge/Standalone 为 `2,598,669 / 2,598,747` bytes、57 loaded modules，
Application+AI 为 `4,501,822 / 4,501,954`，MCP 为 `7,324,601 / 7,324,709`。新增测试不进入任何运行制品。
- PostgreSQL HA 不重跑且不重新占有既有证明，因为本切片没有 schema、ACL、repository、role、Pool、连接或 failover 变化。
docs/adr/README.md
+1
View File
@@ -474,6 +474,7 @@
| [ADR-0468](./ADR-0468-optional-console-worker-observation.md) | 可选 Console Worker 只读观察 | Accepted |
| [ADR-0469](./ADR-0469-optional-console-package-installation-observation.md) | 可选 Console Package Installation 只读观察 | Accepted |
| [ADR-0470](./ADR-0470-session-scoped-console-capability-discovery.md) | Console 会话级能力发现与服务端操作围栏 | Accepted |
| [ADR-0471](./ADR-0471-legacy-core-api-compatibility-baseline.md) | Legacy 核心执行 API 兼容基线 | Accepted |
## 规则