redis-gui-foundation/docs/architecture.md

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 读取请求。
• RedisValueCreateRequest: 单个 key 的显式创建请求；当前仅允许新建 string key，并可选携带创建时 TTL。
• RedisValueWriteRequest: 单个 key 的 value 写入请求；当前仅允许 string 整值替换。
• RedisKeyTtlUpdateRequest: 单个 key 的 TTL 修改请求，支持设置过期时间和移除 TTL。
• RedisCommandRequest: 基础命令执行请求，显式拆分命令名与参数。
• RedisKeyMetadata: key 浏览与 inspector 共享的稳定元数据结构，覆盖存在性、类型和 TTL。
• RedisValueRecord: inspector 使用的稳定结构，组合 key 元数据、typed value 数据、value 写入能力和 TTL 修改能力。
• RedisValueCreateResult: 创建成功后的稳定返回体，复用 RedisValueRecord 让调用方立即获得可浏览/可检查的最新状态。
• 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 Add Key 通过独立 create contract 建模，只允许显式新建 string key，并通过 SET ... NX 拒绝任何隐式覆盖。
• 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 key 创建使用单条 SET key value NX [PX ttl]，确保重复 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、create_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