# Flutter终端架构设计

版本号：v0.1.0
最后更新：2026-04-04

## 1. 目的

本文档用于定义本项目移动终端的第一版架构，明确 Flutter 在系统中的职责、分层方式和与本地算法核心、远端服务之间的边界。

## 2. 终端定位

本项目中的 Flutter 终端不是单纯展示层，而是“移动实验室终端”。

它需要承担：

- 采集音频
- 展示观测结果
- 展示实验树
- 展示证据和结论
- 发起分析流程
- 管理本地会话和样本历史

但它不应承担：

- 重型 DSP 主计算
- 重型声源分离
- Gemma 4 主编排推理

## 3. 技术栈建议

第一版建议：

- 框架：Flutter
- 语言：Dart
- 状态管理：Riverpod
- 路由：go_router
- 本地数据库：SQLite
- 网络通信：HTTP + WebSocket
- 本地算法核心：Rust
- Flutter 与 Rust 集成：FFI

## 4. 分层结构

建议分为五层：

1. 表现层
2. 交互状态层
3. 应用服务层
4. 平台能力层
5. 本地算法桥接层

## 5. 表现层

职责：

- 页面 UI
- 图形化结果展示
- 操作入口

第一版建议页面：

- 首页
- 录音页
- 样本详情页
- 实验过程页
- 结果结论页
- 历史记录页
- 设置页

## 6. 交互状态层

职责：

- 管理页面状态
- 管理分析任务状态
- 管理实验树展示状态

建议以 feature 为单位组织 provider，而不是按技术层随意分散。

## 7. 应用服务层

职责：

- 协调录音、上传、分析启动、结果轮询、历史查询
- 封装对本地数据库和远端服务的访问

建议拆分为：

- `ObservationService`
- `AnalysisSessionService`
- `ExperimentService`
- `ConclusionService`
- `SettingsService`

## 8. 平台能力层

职责：

- 麦克风录音
- 文件导入
- 权限管理
- 后台任务
- 网络可用性检测

这一层可使用插件，也可在需要时补自定义平台通道。

## 9. 本地算法桥接层

职责：

- 调用 Rust 本地探针算法
- 管理输入输出序列化
- 将结果映射回 Dart 侧模型

建议第一版仅在本地桥接层承载：

- normalize
- resample
- energy probe
- spectral probe
- onset probe
- periodicity probe

## 10. 本地与远端边界

### 10.1 本地优先处理

建议本地先做：

- 录音预处理
- 通用探针链
- 初始 evidence 生成

### 10.2 远端处理

建议远端负责：

- Gemma 4 编排
- 重型验证链
- 多轮实验管理
- 最终结论整合

## 11. 数据流

建议第一版数据流如下：

1. 用户录音或导入音频
2. Flutter 生成 `Observation`
3. 本地 Rust 探针引擎生成初始 `Evidence`
4. Flutter 将样本摘要和 evidence 发给远端
5. 远端 AI 编排并返回实验计划
6. 远端或本地执行实验
7. Flutter 展示实验过程、证据和结果

## 12. 页面重点

### 12.1 首页

重点展示：

- 开始分析
- 最近样本
- 当前分析任务

### 12.2 样本详情页

重点展示：

- 波形摘要
- 录音信息
- 初始 probe evidence

### 12.3 实验过程页

重点展示：

- 当前假设
- 已执行实验
- 分数变化
- 失败原因

### 12.4 结果页

重点展示：

- 结论摘要
- 支持证据
- 冲突证据
- 不确定性
- 下一步建议

## 13. 终端状态模型建议

建议明确区分下列状态：

- `idle`
- `recording`
- `probing`
- `planning`
- `executing`
- `reviewing`
- `completed`
- `failed`

终端不应把整个分析过程只表示成一个模糊的 loading 状态。

## 14. 第一版目录建议

```text
lib/
  app/
  features/
    capture/
    observation/
    analysis/
    experiment/
    conclusion/
    history/
    settings/
  services/
  data/
  ffi/
  routing/
```

## 15. 第一版实现重点

第一版应优先保证：

- 录音稳定
- 本地探针可跑
- 远端编排闭环打通
- 实验过程可视化
- 结论结构清晰

第一版不应优先追求：

- 复杂视觉设计
- 离线全功能
- 大量插件化能力
- 多平台差异细节优化

## 16. 结论

Flutter 在本项目中的正确角色是移动实验室终端。

它负责：

- 采集
- 展示
- 会话管理
- 分析流程可视化

而本地 Rust 和远端 AI 服务分别承担基础探针与高级编排能力。