dbtool-cli-v1/TUI_BACKEND_CONTRACT.md

# TUI Backend Contract

日期：2026-03-27  
作者：Senior Backend Engineer

## 1. 当前后端边界

- `crates/db-core`：数据库无关的领域对象与基础校验。
- `crates/db-config`：连接 profile、密码环境变量注入与脱敏摘要。
- `crates/db-drivers`：PostgreSQL / MySQL / SQLite 驱动实现与差异收敛。
- `crates/db-app`：`connect` / `inspect` / `query` / `export` 共享应用编排、结构化结果、统一错误对象，以及 TUI worker 可复用的执行状态。
- `apps/cli`：参数解析、stdout/stderr 渲染、退出码。

## 2. 持久化边界

- 当前产品仍是单次命令执行模型，没有连接配置持久化、历史记录持久化或后台状态存储。
- 当前写路径只有：
  - `export` 明确指定的输出文件
  - SQLite 目标数据库本身（由用户选择）
- TUI 第二阶段 live integration 仍不引入新的数据库、本地缓存库或后台 daemon 存储契约。

## 3. 共享请求对象

TUI worker 应直接构造共享 Rust 对象，不要拼接 CLI flags，更不要解析 CLI 文本。

### Connect

- 输入：`db_config::ConnectionProfile`
- 说明：
  - `name` 用于当前会话内的目标标识
  - `target` 复用 `db_core::ConnectionTarget`
  - `password_env_var` 只作为脱敏标签保留；secret 仍通过环境变量注入，不进入持久化

### Inspect

- 输入：`db_core::InspectRequest`
- 字段：
  - `schema: Option<String>`
  - `table: Option<String>`
- 约束：
  - `table.is_some()` 时必须同时提供 `schema`

### Query

- 输入：`db_core::QueryRequest`
- 字段：
  - `sql`
  - `source`
  - `parameters`
- `source` 语义：
  - `QuerySource::Inline`
  - `QuerySource::File`

### Export

- 输入：
  - `db_core::QueryRequest`
  - `db_core::ExportRequest`
- `ExportRequest` 字段：
  - `format`
  - `output_path`
  - `overwrite`
- 约束：
  - 只允许导出返回结果集的查询
  - 不静默覆盖已有文件
  - 不为 TUI 增加新的导出元数据存储

## 4. 共享结构化结果

TUI 应优先直接调用 `crates/db-app`，不要解析 CLI 的人类可读文本。

### Connect

- 返回 `ConnectResponse`
- 字段：
  - `target.profile_name`
  - `target.driver`
  - `target.endpoint`
  - `target.password_env_var`
  - `status`
- 当前 `status` 固定为 `connected`

### Inspect

- 返回 `InspectResponse`
- 字段：
  - `target`
  - `scope.schema`
  - `scope.table`
  - `payload`
- `payload.kind` 为：
  - `schemas`
  - `tables`
  - `columns`
- `payload.items` 允许为空；空数组不是错误

### Query

- 返回 `QueryResponse`
- 字段：
  - `target`
  - `source.kind`：`inline` / `file`
  - `source.label`
  - `source.path`
  - `result.columns`
  - `result.rows`
  - `result.rows_affected`
  - `result.row_count`
- `rows_affected != null` 表示 command-style 执行成功但没有结果集

### Export

- 返回 `ExportResponse`
- 字段：
  - `target`
  - `source`
  - `export.format`
  - `export.output_path`
  - `export.overwrite`
  - `row_count`

## 5. 错误模型

`db-app::AppError.kind` 当前分为：

- `validation`
- `connection`
- `authentication`
- `inspect`
- `query`
- `export`

这组分类是 TUI banner、QA 断言和未来 GUI 状态映射的当前稳定基础。

`AppError.target` 为可选字段：

- 有目标上下文时返回脱敏后的 `ConnectionSummary`
- 参数校验在目标尚未构成时可为 `null`

## 6. Worker / Channel 状态契约

`crates/db-app` 现提供：

- `AppOperation`：`connect | inspect | query | export`
- `OperationState`：`running | success | empty | error`
- `AppEvent<T>`：worker / channel 推荐 envelope

推荐发送顺序：

1. 先发 `AppEvent::running(operation)`
2. 成功后发送 `response.into_event()`
3. 失败时发送 `error.into_event()`

状态语义固定如下：

- `connect`
  - `running`：正在测试连接
  - `success`：连接成功
  - `error`：连接失败
- `inspect`
  - `success`：返回非空 schema / table / column 集合
  - `empty`：返回空集合，但请求本身成功
  - `error`：inspect 失败
- `query`
  - `success`：返回至少一行，或 `rows_affected` 非空
  - `empty`：返回零行且 `rows_affected == null`
  - `error`：执行失败
- `export`
  - `success`：文件写入成功；`row_count == 0` 仍算成功
  - `error`：导出校验、查询或文件写入失败

示例：

```rust
use db_app::{AppEvent, AppOperation};

sender.send(AppEvent::<()>::running(AppOperation::Query))?;

match db_app::query(&profile, &request) {
    Ok(response) => sender.send(response.into_event())?,
    Err(error) => sender.send(error.into_event())?,
}
```

## 7. CLI 结构化输出

CLI 继续保留默认文本输出，同时新增：

- `--result-format text`
- `--result-format json`

JSON 返回 envelope：

```json
{
  "status": "success",
  "operation": "query",
  "data": {}
}
```

错误返回 envelope：

```json
{
  "status": "error",
  "operation": "query",
  "error": {
    "operation": "query",
    "kind": "query",
    "message": "..."
  }
}
```

CLI JSON envelope 继续作为跨入口回归样本，但 TUI live path 不应以调用 CLI 二进制作为主集成方式。

## 8. Frontend 接入约束

- TUI 直接依赖 `crates/db-app` 与 `db-core`，不解析 CLI stdout/stderr
- UI 状态映射应优先使用 `OperationState`，不要自行发明另一套 success/empty/error 语义
- `ConnectionSummary.endpoint` 与 `password_env_var` 仅用于展示脱敏上下文，不应用作 secret 来源
- `AppError.kind` 必须原样进入状态区 / inspector，避免把 `validation`、`connection`、`query` 混成统一“失败”
- 若未来引入异步 worker 池，仍以共享 response/error 对象作为唯一 UI 数据源

## 9. 当前回归边界

- `crates/db-app` 回归需覆盖：
  - response -> `OperationState` 映射
  - `AppEvent<T>` / `AppError` 序列化
  - 空 inspect / 空 query / command query 语义
- `apps/cli` 回归继续覆盖：
  - `--result-format json` envelope
  - text/json 输出在相同 `db-app` 结果上的一致性

## 10. 演进规则

- CLI 文本文案可小幅演进，但 `db-app` 结构化对象字段应保持兼容。
- 新增数据库驱动时，优先扩展 `db-drivers` 与 `db-app`，不要在 TUI/CLI 内复制数据库语义。
- 若未来引入本地持久化（例如连接历史），应先新增独立文档定义存储边界，再进入实现。