dbtool-cli-v1/plans/2026-03-31-cmp-62-backend-restricted-schema-contract.md

CMP-62 backend restricted schema contract

日期：2026-03-31
负责人：Senior Backend Engineer

Goal

在不引入新持久化层或 migration 的前提下，补齐 shared inspect contract 对 PostgreSQL restricted schema 的可见性与错误语义，避免继续把 restricted schema 误判为 empty / hidden。

Assessment

• crates/db-core / crates/db-app 当前 shared inspect payload 原本只有 schema 名称，没有权限可见性字段。
• PostgreSQL root inspect 之前基于 information_schema.schemata，restricted schema 会被直接省略。
• 显式 schema inspect 之前基于 information_schema.tables，restricted schema 会退化成空列表，和 empty schema 混淆。
• 当前仓库仍没有 app-owned persistence schema；本轮变更只涉及 shared contract、驱动语义和 CLI 可见输出。

Scope

1. 为 schema root inspect 增加 item-level availability / note
2. PostgreSQL root inspect 改为保留 restricted schema 名称
3. PostgreSQL explicit schema inspect 在 restricted scope 上返回 inspect error，而非 empty
4. 同步 TUI_BACKEND_CONTRACT.md 与 USABLE_APP_CLI_CONTRACT_SNAPSHOT.md
5. 为 shared contract / driver / CLI 文本输出补最小测试

Validation

export CARGO_HOME="$AGENT_HOME/.cargo"
export RUSTUP_HOME="$AGENT_HOME/.rustup"
export PATH="$AGENT_HOME/tools:$CARGO_HOME/bin:/paperclip/.cargo/bin:${PATH}"
unset CARGO_REGISTRIES_CRATES_IO_PROTOCOL
. "$CARGO_HOME/env"

cargo test -p db-core -p db-app -p db-drivers -p dbtool-cli

Result

• shared inspect schema item 现可区分 ready 与 restricted
• PostgreSQL root inspect 不再静默隐藏 restricted schema
• PostgreSQL explicit schema inspect 不再把 restricted schema 误报为 empty
• 当前剩余缺口转为 consumer 侧消费与 live fixture 权限模型验证，不是持久化或 migration blocker