架构总览

总体设计

IriX 采用「Flutter UI + Rust 底层 + FFI 桥接」的三层架构：

1. UI 层（Dart / Flutter）：页面、组件与状态管理，负责交互与展示
2. FFI 桥接层（Dart）：lib/services/*_ffi.dart 使用 package:ffi 绑定 Rust 导出函数
3. 底层（Rust workspace）：七个 crate 各司其职，承担所有重活

分层职责

层	目录	职责
页面	lib/screens/	home、nodes、marketplace、frp、database、ai 等页面
组件	lib/widgets/	通用 UI 组件（参考 lib/utils/apple_widgets.dart）
状态	lib/state/	AppState、NodeState（Provider，不在 widget 内直接持有全局状态）
服务	lib/services/	API 服务与 FFI 封装（*_ffi.dart、*_api_service.dart、*_provider.dart）
模型	lib/models/	实例、节点、市场、远程等数据模型
静态数据	lib/data/	config_descriptions、server_cores 等

Rust workspace

crate	职责
backup	ZIP 并行压缩 / 解压
downloader	HTTP 流式 / 分片下载（断点续传）
http_client	通用 HTTP 请求（GET/POST/PUT/PATCH/DELETE/HEAD，响应含 base64 体）
file_ops	文件扫描、移动、回收站
logger	日志
db_client	远程数据库客户端（MySQL/MariaDB/PostgreSQL/Redis，统一 db_request 入口）
vector_store	向量知识库（rusqlite + sqlite-vec，存取与相似检索）

所有 crate 使用统一 workspace 配置，release profile 开启 opt-level = 3 + lto。

一次请求的完整链路

以「下载服务器文件」为例：

1. UI 层调用 Downloader.downloadFile（lib/services/downloader.dart）
2. Dart 通过 FFI 调用 xmc_downloader 动态库
3. Rust 端以 ureq + rustls 发起流式请求，分片写入磁盘（支持断点续传）
4. 进度经 FFI 回调返回 Dart，UI 更新进度条

关键设计决策

• 网络统一走 Rust：所有 HTTP 请求由 http_client / downloader crate 处理（ureq + rustls，无 OpenSSL）；Dart 侧不再使用 package:http（仅测试保留）
• 数据库统一走 Rust：远程数据库由 db_client crate 的纯 Rust 驱动执行；本地持久化用 SQLite（sqflite_common_ffi）
• 存储统一：设置全部存 SQLite settings 表，无 SharedPreferences
• 性能优先：Rust 承担压缩、下载、文件、日志、向量检索等计算密集任务