# 隐藏"AI 全能助手"模块 · UI 排版重设计

**日期**：2026-04-28
**背景**：某客户（对应 BLE 设备 PID 为 `B017`）的产品定位上不需要"AI 全能助手"模块，需要在 UI 上屏蔽该入口，并对首页和发现页的"翻译 / 会议助手"两个剩余模块重新排版。

---

## 一、目标与范围

### 范围内
- 新增一个全局开关 `AppConfig.hideAiAssistant`
- 当开关为 `true` 时，**首页（HomeView）** 与 **发现页（ExploreView）** 切换为新的 UI 排版（隐藏 AI 全能助手入口）
- 当开关为 `true` 时，**新手引导（novice guide）** 跳过引导用户点开 AI 全能助手的步骤
- 当开关为 `false`（默认）时，所有 UI 行为与当前一致

### 范围外
- AI agent 模块本身（`lib/modules/agent/`）的代码、路由、controller **保持原样**，不做删除
- 翻译资源 key（`aiAssistant`、`aiAssistantInfo` 等）**全部保留**
- 开关与 BLE PID 的联动逻辑（即"连接 B017 设备时自动设置开关为 true"）**留待后续单独实现**
- 其它可能与 AI 全能助手相关的次要露出（如设置页、付费页面）目前未发现，后续如发现再补

---

## 二、配置开关

### 位置与定义

在已有的 `lib/data/models/appconfig.dart` 的 `AppConfig` 类中新增一个静态字段：

```dart
class AppConfig {
  static late UserGetAppConfigResp config;
  static bool _isInitialized = false;

  // 中文注释：是否隐藏"AI全能助手"模块。
  // true  => 首页/发现页切换为精简布局，新手引导跳过 AI 引导步骤
  // false => 保持原有布局
  // TODO: 后续接入 BLE PID 判断逻辑，B017 设备连接时自动置 true
  static bool hideAiAssistant = false;

  // ... 其它已有方法
}
```

### 调用方式

UI 层直接读取：`AppConfig.hideAiAssistant`，不引入新的 service 或新文件。

### 默认值

`false`（保持当前所有用户的体验不变）。

需要为 B017 客户验证新布局时，临时把默认值改为 `true` 重新编译即可，或在测试入口手动赋值。

---

## 三、首页（HomeView）改造

### 当前布局

`_buildPremiumAILayout()` 当前是 **左侧大卡片（AI 全能助手）+ 右侧两个小卡片（翻译 + 会议助手）** 的 1+2 结构。

### 新布局（开关为 true 时）

**方案 A：左右等宽方形双卡**

- 删除"AI 全能助手"卡片
- 翻译 / 会议助手两张卡片**等宽并列**，高度统一约 `140.h`（介于原大卡片 175 和小卡片 85 之间）
- 卡片样式延用现有渐变色方案：
  - 翻译：`#4CAF50 → #009688` 绿色系
  - 会议助手：`#ab47bc → #ec407a` 紫粉系
- 图标置左上角，标题加粗、描述 2 行省略，与原小卡片保持一致的视觉语言但放大

### 实现方式

在 `home_view.dart` 中：
- 保留原 `_buildPremiumAILayout()` 方法不动
- 新增 `_buildSimplifiedAILayout()` 方法返回新布局
- 在 `build()` 中按开关分发：

```dart
AppConfig.hideAiAssistant
    ? _buildSimplifiedAILayout()
    : _buildPremiumAILayout(),
```

区域标题"热门AI体验"（`topAiExperiences`）继续保留，不修改。

---

## 四、发现页（ExploreView）改造

### 当前布局

`_buildCustomAILayout()` 当前是 **2x2 网格**：上层左 AI 全能助手 + 上层右 同声传译，下层会议助手占满整行。`controller.aiFeatures` 列表有 3 项，索引 0 是 AI 全能助手。

### 新布局（开关为 true 时）

**方案 C：上下堆叠大型 banner 卡**

- 删除 AI 全能助手卡片
- 翻译 / 会议助手两张卡片**上下堆叠**，每张占满整行
- 每张卡片高度约 `130.h`，padding 加大（`16.w`）
- 图标置右上角约 `44.w`，标题左下角加粗放大（`16.sp`），描述放在标题下方
- 渐变色与首页保持一致（绿色系 / 紫粉系）

### 实现方式

在 `explore_view.dart` 中：

**a. 不改动 `controller.aiFeatures` 列表本身**（保持向后兼容）

**b. 在 view 中根据开关分支**：
- 保留原 `_buildCustomAILayout()` 方法不动
- 新增 `_buildSimplifiedAILayout()` 方法返回新布局，内部直接使用 `controller.aiFeatures[1]`（翻译）和 `controller.aiFeatures[2]`（会议助手），跳过索引 0
- 在 `build()` 中按开关分发

区域标题"AI 功能"（`aiFunction`）继续保留。

---

## 五、新手引导（novice guide）调整

### 现状

`home_view.dart` 中 `IntroStepBuilder(group: 'home', order: 3)` 包裹了 AI 全能助手大卡片，引导用户在唤醒成功后点开 AI 全能助手。

### 调整

当 `AppConfig.hideAiAssistant == true` 时：
- 精简布局中**不渲染 order:3 的 IntroStepBuilder**
- 用户完成 order:1（设备状态）和 order:2（唤醒）后，引导自然结束

### 实现方式

在 `_buildSimplifiedAILayout()` 中**不包裹任何 IntroStepBuilder**，引导框架找不到 order:3 的目标 widget 后会自动跳过。

也可以在 `NoviceGuideService` 的 `home` group 流程中加判断，但前者改动更小、更稳。

---

## 六、风险与注意事项

1. **GlobalKey 缺失**：原 `IntroStepBuilder(order: 3)` 不渲染时，必须确认引导服务不会因找不到目标 widget 报错或卡住。需要在测试时验证 B017 用户的引导走完是否顺畅。
2. **后续 PID 联动**：`AppConfig.hideAiAssistant` 现在是普通静态字段，赋值后不会触发 `Obx` 重建。如果后续做 PID 联动并要求"插拔 B017 实时切换 UI"，需要把字段改造成 `Rx<bool>` 或在赋值时主动触发 controller 刷新。本次设计不引入响应式包装。
3. **页面缓存**：GetX 的 controller 默认是单例，UI 切换是在 `build()` 阶段判断的。第一次进入页面后，开关变化需要重新构建页面才能生效。本次场景下开关在编译期/启动期就已确定，不存在运行时切换问题。
4. **资源未删除**：AI 全能助手相关的图标/文案/路由都保留，包体积无变化。

---

## 七、文件改动清单

| 文件 | 改动类型 | 说明 |
|---|---|---|
| `lib/data/models/appconfig.dart` | 修改 | 新增静态字段 `hideAiAssistant` |
| `lib/modules/home/views/home_view.dart` | 修改 | 新增 `_buildSimplifiedAILayout()`；`build()` 中按开关分发 |
| `lib/modules/explore/views/explore_view.dart` | 修改 | 新增 `_buildSimplifiedAILayout()`；`build()` 中按开关分发 |

无需新建文件，无需修改 controller、route、translations。

---

## 八、验证清单

- [ ] `AppConfig.hideAiAssistant = false` 时，首页和发现页 UI 与当前完全一致
- [ ] `AppConfig.hideAiAssistant = false` 时，新手引导走完 3 步并跳到 AI 全能助手
- [ ] `AppConfig.hideAiAssistant = true` 时，首页"热门AI体验"区域显示翻译 + 会议助手等宽并列
- [ ] `AppConfig.hideAiAssistant = true` 时，发现页"AI 功能"区域显示翻译 + 会议助手上下堆叠 banner
- [ ] `AppConfig.hideAiAssistant = true` 时，新手引导走完 2 步后正常结束，无卡顿/异常
- [ ] 暗色主题下两种布局的渐变和文字对比度符合预期
- [ ] 翻译/会议助手卡片的点击仍然能跳转到对应页面