mirror of
https://github.com/whyour/qinglong.git
synced 2026-09-20 16:07:11 +08:00
81 lines
4.3 KiB
Markdown
81 lines
4.3 KiB
Markdown
# ADR-0269：Profile-aware Local SQLite Readiness 诊断边界
|
||
|
||
- 状态：Accepted
|
||
- 日期：2026-08-04
|
||
- 关联 RFC：QL-RFC-0001 D-06、D-17、D-20、D-40、D-250
|
||
- 关联 ADR：ADR-0004、ADR-0063、ADR-0064、ADR-0086、ADR-0257
|
||
|
||
## 背景
|
||
|
||
仓库根命令 `audit:schema:ql3` 原先默认打开 `data/db/database.sqlite`，并用
|
||
`back/migrations` 的 legacy/Shadow ownership manifest 审计。该路径通常是用户的 2.x 数据库，
|
||
而 fresh/adopted QingLong 3.0 的正式 SQLite authority 已经迁移到
|
||
`@qinglong/local-sqlite` 的独立 84 条 migration stream 与 capability v42。
|
||
|
||
旧命令虽然只读，但默认选择现网路径会产生三个问题：
|
||
|
||
- 把 2.x 数据库误称为 3.0 fresh schema，并稳定输出缺失表误报；
|
||
- 无法验证 edge `DELETE` 与 standalone `WAL` 的 Profile 差异；
|
||
- 让诊断结果与 application、Compose preflight 使用的 readiness authority 分叉。
|
||
|
||
## 决策
|
||
|
||
### 1. `audit:schema:ql3` 只表示正式 Local 3.0 readiness
|
||
|
||
根命令现在调用既有 `@qinglong/local-owner-cli` 中的 `ql3-local-readiness`。调用者必须显式
|
||
提供 `--database` 与 `--profile=edge|standalone`；不存在默认数据库，也不从 cwd、环境变量或
|
||
2.x 配置猜测 authority。
|
||
|
||
诊断复用 `@qinglong/local-sqlite/readiness-inspection`，因此与启动/Compose preflight 共用同一
|
||
migration checksum、capability、required schema、foreign-key、quick-check 和 repository
|
||
integrity 权威。edge 必须是 `DELETE` journal，standalone 必须是 `WAL`；不能用一个 Profile 的
|
||
成功结果替另一个 Profile 背书。
|
||
|
||
### 2. 诊断入口保持短生命周期、只读和低敏
|
||
|
||
数据库必须是 canonical absolute path、当前 UID 所有、精确 `0600`、非 symlink regular file。
|
||
诊断使用 Node 24 defensive/query-only SQLite，不执行 migration、repair、journal 切换或任何业务
|
||
查询。成功只输出 contract name/version、migration/table 数、SQLite version 与 journal mode，
|
||
不输出数据库路径、row、credential、digest 或 Secret。
|
||
|
||
失败输出只有稳定 code/name；底层可能包含路径的异常不能进入 stdout/stderr 产品结果。
|
||
|
||
### 3. legacy/Shadow 审计显式隔离
|
||
|
||
旧 ownership drift 工具保留为 `audit:legacy-schema:ql3`，供 2.x Shadow migration 兼容诊断使用。
|
||
它必须显式传 `--database`；已删除隐式 `data/db/database.sqlite` 默认值，JSON 报告标记
|
||
`mode=legacy-shadow`。它不能作为 fresh/adopted 3.0 readiness 证据。
|
||
|
||
### 4. 不增加包或常驻成本
|
||
|
||
实现只在既有 `@qinglong/local-owner-cli` 增加一个 subpath/bin，复用已存在的
|
||
`@qinglong/local-sqlite` dependency。workspace 保持 19，不增加 dependency、migration、daemon、
|
||
listener、timer、watcher 或数据库连接池。诊断只在 operator 显式调用时加载。
|
||
|
||
## 替代方案
|
||
|
||
- **继续默认审计 `data/db/database.sqlite`**：拒绝。会把 2.x 路径冒充 3.0 authority。
|
||
- **复制一份 schema manifest 到根脚本**：拒绝。会与 application readiness 再次漂移。
|
||
- **诊断时自动 migration/切换 journal**：拒绝。readiness 不能同时是隐式修复 authority。
|
||
- **为诊断新建 workspace package**：拒绝。没有独立交付或 authority 价值，会突破包粒度约束。
|
||
- **从文件内容自动推断 Profile**：拒绝。部署 Profile 是 operator intent，不应由当前 journal
|
||
状态反向猜测。
|
||
|
||
## 验证
|
||
|
||
- `pnpm --filter @qinglong/local-owner-cli test`
|
||
- `node --test test/back/ql3ClusterDependencyAudit.test.cjs test/back/nodeSqliteSchemaCompatibility.test.cjs`
|
||
- `pnpm audit:cluster-dependencies:ql3`
|
||
- `pnpm audit:package-boundaries:ql3`
|
||
- edge/standalone fresh database 的 `audit:schema:ql3` 正向门；跨 Profile、重复参数、隐式路径和
|
||
`0644` database 负向门。
|
||
|
||
当前证据为 Owner CLI 91/91、dependency/legacy 定向门 46/46、Worker Runtime 132/132、
|
||
后端 1093 pass/2 条件 skip/0 fail；完整 package 门退出 0，workspace 仍为 19/19。正式 edge
|
||
实测输出为 capability v42、84 条 migration、76 张表和 `DELETE` journal，且不包含数据库路径。
|
||
|
||
## 影响
|
||
|
||
调用旧根命令但未传参数的开发脚本会失败关闭，需要明确选择 Local 3.0 或 legacy/Shadow 模式。
|
||
这是一项有意的诊断兼容性收紧，不影响应用启动、migration 或用户数据。
|