# 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**：弹出快速切换智能体列表（多智能体场景）