# Backend Foundation

## Goals

- 使用 Rust workspace 作为产品的长期结构。
- 将可复用业务能力放入 `crates/redis-core`，避免把 Redis 语义散落在 GUI 层。
- 让 desktop 壳层只负责窗口与命令桥接，不负责领域规则。

## Current Domain Model

当前只定义启动和连接建模所需的最小领域对象：

- `ConnectionTarget`: Redis 目标地址、端口、数据库序号、用户名和 TLS 模式。
- `ConnectionProfileDraft`: GUI 或未来 CLI 收集到的连接表单草稿。
- `RedisConnectionRequest`: 一次请求内使用的连接上下文，包含非持久化密码。
- `RedisKeyBrowseRequest`: key 浏览请求，显式携带 `SCAN` cursor、pattern 与 page size。
- `RedisKeyMetadataRequest`: 单个 key 的元数据读取请求，用于 inspector 刷新与删除前确认。
- `RedisValueReadRequest`: 单个 key 的 typed value 读取请求。
- `RedisValueWriteRequest`: 单个 key 的 value 写入请求；当前仅允许 string 整值替换。
- `RedisKeyTtlUpdateRequest`: 单个 key 的 TTL 修改请求，支持设置过期时间和移除 TTL。
- `RedisCommandRequest`: 基础命令执行请求，显式拆分命令名与参数。
- `RedisKeyMetadata`: key 浏览与 inspector 共享的稳定元数据结构，覆盖存在性、类型和 TTL。
- `RedisValueRecord`: inspector 使用的稳定结构，组合 key 元数据、typed value 数据、value 写入能力和 TTL 修改能力。
- `RedisValueData`: typed value 返回体，覆盖 `string/hash/list/set/zset/stream` 与缺失 key。
- `RedisValueWriteCapability`: 当前明确区分 `replace_string` 与 `none`，让入口层知道哪些类型仍是只读。
- `CommandExecutionResult`: 以稳定的 RESP2 派生结构返回基础命令结果。
- `BackendError`: 结构化错误码，区分连接配置、认证、连接失败和命令失败。
- `BackendBootstrap`: 向入口层暴露当前支持的能力边界和安全约束。

这些对象构成当前阶段的稳定后端契约：

- 单实例连接测试通过 `PING` 验证回路。
- 认证通过请求态 `AUTH` 握手完成。
- DB 切换在连接建立后通过 `SELECT` 保证。
- 命令执行按 RESP2 基础类型映射为稳定结构体，避免 GUI 直接处理原始 socket 数据。
- key 浏览按 `SCAN` 分页返回，并为每个命中的 key 补充 `TYPE` 与 `PTTL` 元数据。
- inspector 可对单个 key 单独刷新元数据，避免 UI 为了刷新单项而重跑整页浏览。
- typed value surface 当前覆盖 `string/hash/list/set/zset/stream` 六类 Redis 数据，并显式保留类型差异。
- V1 value 编辑只允许已有 string key 的整值替换；非 string key 保持只读，避免错误覆盖集合类型。
- string 写入会保留原 TTL，TTL 修改独立通过 `PERSIST` / `PEXPIRE` 语义建模。

## Persistence Boundary

当前阶段明确保持以下约束：

- 连接密钥和密码不落盘。
- 密码仅存在于单次 `RedisConnectionRequest` 的内存生命周期内。
- 连接配置目录和迁移策略尚未启用，因此不存在历史数据兼容承诺。
- GUI 仅消费 `redis-core` 导出的稳定结构体，不直接定义持久化格式。

后续进入产品化时，应新增独立的存储 crate，并补充：

- 配置文件 schema
- 版本字段与迁移器
- 敏感信息存储策略
- 向前/向后兼容测试

## Compatibility Notes

- 当前后端只覆盖单实例 Redis 的同步 RESP2 交互。
- workspace 通过 `.cargo/config.toml` 启用 `resolver.incompatible-rust-versions = "fallback"`，避免在 `rustc 1.85` 环境下把 Tauri 传递依赖解析到更高 MSRV 的版本带。
- key 浏览当前基于 Redis `SCAN` + 每 key `TYPE`/`PTTL` 的顺序读取，优先保证正确性和契约清晰，而不是在原型期过早做 pipeline 或并发优化。
- `TlsMode::disabled` 可用，`preferred` 和 `required` 目前明确返回 `unsupported_tls_mode`，避免伪支持。
- 命令执行结果目前覆盖 RESP2 的 `simple string`、`bulk string`、`integer`、`array` 和 `null`。
- typed value 读取当前是 key 级 eager 读取：`HGETALL`、`LRANGE 0 -1`、`SMEMBERS`、`ZRANGE ... WITHSCORES`、`XRANGE - +`。这保证了契约直接，但尚未引入大 key 分页、截断或流式读取策略。
- string 写入使用事务化的 `SET ... XX` 与 TTL 恢复，避免把非 string key 误写成 string，也避免默认清空现有 TTL。
- key 元数据仍未覆盖编码、内存占用、slot、cluster 拓扑或 ACL 细粒度探测。
- 这层契约已足以支撑连接管理、基础命令台、key 浏览、value inspector 与 TTL 编辑，但还不足以覆盖 cluster、pub/sub、流式结果或长连接会话管理。

## Entry Point Contract

- Tauri 命令只暴露共享核心层的数据，不直接返回临时字符串。
- 当前桌面入口暴露八个命令：`backend_bootstrap`、`test_redis_connection`、`browse_redis_keys`、`inspect_redis_key`、`read_redis_value`、`write_redis_value`、`update_redis_key_ttl`、`execute_redis_command`。
- 任何新增入口都应优先复用 `redis-core`，保证 CLI、GUI 行为模型一致。
- 桌面入口允许演进 UI，但不应绕过领域约束自行定义 Redis 协议行为。

## Verification Notes

当前已验证的重点是：

- Rust 核心 crate 的测试与格式正确性
- Tauri desktop 命令桥可以在当前 Linux 环境完成编译检查
- Linux 下 Tauri 所需系统依赖已通过 `pkg-config` 验证

当前已完成的验证：

- `cargo test -p redis-core`
- mock Redis 测试覆盖 AUTH、SELECT、PING、SCAN 分页、TYPE、PTTL、缺失 key 元数据映射、typed value 读取、string 安全写入和 TTL 修改
- `Cargo.lock` 已重新解析到 Rust 1.85 兼容版本带：`serde_with 3.17.0`、`darling 0.21.0`、`time 0.3.44`
- `cargo check -p desktop-shell --locked`
- `pkg-config` 校验通过：`gtk+-3.0`、`webkit2gtk-4.1`、`libsoup-3.0`、`javascriptcoregtk-4.1`
- `pnpm run desktop:build`