151 lines
6.2 KiB
Markdown
151 lines
6.2 KiB
Markdown
# App 导航重构说明
|
||
|
||
> commit: `d5930ff` — feat(app): redesign navigation — floating robot FAB + 4-tab layout
|
||
> 日期: 2026-03-07
|
||
|
||
---
|
||
|
||
## 一、重构背景
|
||
|
||
原设计沿用"传统运维工具"思维（仪表盘 / 对话 / 任务 / 告警 / 设置），与产品真实定位不符。
|
||
iAgent App 的核心是一个 **AI 元智能体**——用户通过对话让 iAgent 帮助创建、部署、管理其他智能体（OpenClaw 等），而非手动填表操作服务器。
|
||
|
||
新设计围绕这个定位重构导航结构，使「对话」成为随时可呼出的浮层入口，Tab 展示的是 AI 已经为用户创建的成果。
|
||
|
||
---
|
||
|
||
## 二、导航结构对比
|
||
|
||
| 位置 | 旧版 | 新版 |
|
||
|------|------|------|
|
||
| Tab 1 | 仪表盘（服务器概览） | **主页**（智能体卡片 + 引导） |
|
||
| Tab 2 | 对话（核心功能） | **我的创建**（已创建的智能体） |
|
||
| Tab 3 | 任务（运维任务列表） | **账单**（套餐 / 用量 / 充值） |
|
||
| Tab 4 | 告警（告警事件列表） | **我**（个人资料 + 设置） |
|
||
| Tab 5 | 设置 | ~~合并进"我"~~ |
|
||
| 悬浮 | 无 | **机器人 FAB**（→ 对话页） |
|
||
|
||
---
|
||
|
||
## 三、新增文件说明
|
||
|
||
### `lib/core/widgets/robot_painter.dart`
|
||
|
||
纯 Flutter `CustomPainter` 实现的机器人画师，**无需任何外部动画资源**。
|
||
|
||
绘制内容：
|
||
- 天线（竖线 + 顶部光球）
|
||
- 头部（圆角矩形 + 彩色边框）
|
||
- 眼睛（支持正常/旋转弧/闭眼 3 种形态）
|
||
- 嘴巴（支持微笑弧/波形/横线 3 种形态）
|
||
- 身体（圆角矩形 + 胸口小圆点）
|
||
- 光晕（头部周围的模糊光圈）
|
||
|
||
5 种状态的视觉表现：
|
||
|
||
| 状态 | 颜色 | 眼睛 | 嘴巴 | 光晕 |
|
||
|------|------|------|------|------|
|
||
| `idle` | 靛蓝 `#6366F1` | 正常椭圆 + 眨眼 | 微笑弧 | 慢脉冲 |
|
||
| `thinking` | 橙色 `#F59E0B` | 旋转加载弧 | 浅弧 | 中速脉冲 |
|
||
| `executing` | 橙红 `#F97316` | 旋转弧（更快） | 浅弧 | 快脉冲 |
|
||
| `speaking` | 青色 `#0EA5E9` | 正常 | 波形动画 | 中速脉冲 |
|
||
| `alert` | 红色 `#EF4444` | 正常 | 横线闪烁 | 红色快闪 |
|
||
|
||
### `lib/core/widgets/robot_avatar.dart`
|
||
|
||
封装 `RobotPainter` 的动画组件，使用 `TickerProviderStateMixin` 驱动两个 `AnimationController`：
|
||
|
||
- `_mainCtrl`：主动画（呼吸/旋转/波形），速率随状态变化
|
||
- idle: 2400ms 来回
|
||
- thinking: 900ms 循环
|
||
- executing: 600ms 循环
|
||
- speaking: 700ms 循环
|
||
- alert: 500ms 循环
|
||
- `_blinkCtrl`：眨眼（150ms），每隔 2~5 秒随机触发，`thinking/executing` 状态时跳过
|
||
|
||
使用方式：
|
||
```dart
|
||
RobotAvatar(state: RobotState.idle, size: 56)
|
||
RobotAvatar(state: RobotState.thinking, size: 32) // AppBar 里的小版本
|
||
```
|
||
|
||
### `lib/core/widgets/floating_robot_fab.dart`
|
||
|
||
悬浮机器人按钮，包含：
|
||
|
||
1. **`robotStateProvider`**：将 `chatProvider` 的 `AgentStatus` 映射为 `RobotState`
|
||
```
|
||
idle → RobotState.idle
|
||
thinking → RobotState.thinking
|
||
executing → RobotState.executing
|
||
awaitingApproval → RobotState.alert
|
||
error → RobotState.alert
|
||
```
|
||
|
||
2. **`FloatingRobotFab`**：圆形容器包裹 `RobotAvatar(size: 52)`，
|
||
- 外圈光晕颜色跟随机器人状态
|
||
- 点击触发 `PageRouteBuilder` 从底部滑入 `ChatPage`（`transitionDuration: 350ms`，`fullscreenDialog: true`）
|
||
|
||
### `lib/features/home/presentation/pages/home_page.dart`
|
||
|
||
"主页" Tab，包含：
|
||
|
||
- **`_AgentStatusCard`**：实时展示 iAgent 当前状态（`RobotAvatar` + 状态文字 + 消息数），点击暗示可进入对话
|
||
- **`_OfficialAgentsRow`**：3 张 IT0 官方智能体横向滑动卡片（运维助手 / 安全审计 / 数据库巡检），纯展示，后续可接入后端
|
||
- **`_MyAgentsPlaceholder`**：用户无自建智能体时的引导（目前硬编码，后续接 `my_agents` 数据）
|
||
- **`_QuickTipsCard`**：示例对话语句，引导用户主动使用 AI
|
||
|
||
### `lib/features/my_agents/presentation/pages/my_agents_page.dart`
|
||
|
||
"我的创建" Tab，包含：
|
||
|
||
- **`myAgentsProvider`**：请求 `GET /api/v1/agent/configs`，失败时返回空列表（不 crash）
|
||
- 无数据时显示 **3步引导** + **4格模板 Grid**（OpenClaw 编程助手 / 运维自动化 / 数据分析 / 安全巡检）
|
||
- 有数据时显示 **`_AgentListCard`** 列表，展示名称 / 描述 / 引擎类型 / 创建时间
|
||
|
||
### `lib/features/profile/presentation/pages/profile_page.dart`
|
||
|
||
"我" Tab，整合原 `SettingsPage` 全部功能，新增：
|
||
|
||
- 账单入口在**最显眼位置**（个人卡片正下方），显示当前套餐名（当前为 "Free"，后续接 `billingProvider`）
|
||
- 其余设置项（主题 / 语言 / 引擎 / 音色 / 风格 / 通知 / 改密码 / 版本 / 检查更新）完整保留
|
||
|
||
---
|
||
|
||
## 四、修改文件说明
|
||
|
||
### `lib/core/router/app_router.dart`
|
||
|
||
**完全重写**，主要变化：
|
||
|
||
- Shell 路由从 5 个减至 4 个：`/home` / `/my-agents` / `/billing` / `/profile`
|
||
- `ScaffoldWithNav.routes` 静态常量更新
|
||
- `Scaffold` 新增 `floatingActionButton: FloatingRobotFab()`，位置 `FloatingActionButtonLocation.endFloat`
|
||
- Splash 跳转目标从 `/dashboard` 改为 `/home`
|
||
|
||
### `lib/features/chat/presentation/pages/chat_page.dart`
|
||
|
||
- 导入 `robot_avatar.dart` 和 `floating_robot_fab.dart`
|
||
- AppBar `title` 从纯文字改为 `Consumer` 内嵌的 `Row(RobotAvatar(size:32) + Text('iAgent'))`
|
||
- 机器人颜色实时反映 Agent 工作状态（用户打开对话窗口时一眼可感知）
|
||
- 其他逻辑**完全不变**（消息列表 / 输入框 / 工具卡片 / 审批卡片 / 语音按钮）
|
||
|
||
### `lib/core/config/api_endpoints.dart`
|
||
|
||
新增：
|
||
```dart
|
||
static const String agentConfigs = '$agent/configs';
|
||
// → /api/v1/agent/configs
|
||
```
|
||
对应 `agent-service` 的 `AgentConfig` 实体 CRUD（已有后端实现）。
|
||
|
||
---
|
||
|
||
## 五、未来扩展方向
|
||
|
||
1. **主页智能体卡片动态化**：接入 `GET /api/v1/agent/configs` 替换当前硬编码官方卡片
|
||
2. **账单 Tab 套餐显示**：在 ProfilePage 账单入口展示实时套餐名（接 `billingProvider`）
|
||
3. **RobotState.speaking**：当 TTS 播放时切换为 `speaking` 状态（需要 voice provider 信号）
|
||
4. **我的创建 → 智能体详情页**：点击列表项进入配置/对话/用量详情
|
||
5. **长按机器人 FAB**：弹出快速切换智能体列表（多智能体场景）
|