# 隐藏"AI 全能助手"模块 实施计划

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 通过新增全局开关 `AppConfig.hideAiAssistant`，在 true 时让首页和发现页切换为隐藏"AI 全能助手"的精简布局。

**Architecture:** 单一全局静态 bool 控制 UI 分支。两个 View 各新增一个 `_buildSimplifiedAILayout()` 方法，原有方法和 controller 数据完全不动。新布局使用现有的卡片样式语言（渐变色、圆角、阴影），保持视觉一致性。

**Tech Stack:** Flutter, GetX, flutter_screenutil, flutter_intro

**Spec:** [`docs/superpowers/specs/2026-04-28-hide-ai-assistant-design.md`](../specs/2026-04-28-hide-ai-assistant-design.md)

---

## 文件清单

| 文件 | 改动 | 说明 |
|---|---|---|
| `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、路由、翻译资源。

---

## 关于测试策略

本项目 `test/` 目录只有翻译资源测试，没有 widget test 体系。本次为纯 UI 布局调整，强行写 widget test 既不符合项目惯例又脆弱。验证手段为：

- **静态校验**：`flutter analyze` 不引入新 warning
- **手动验证**：在两种开关值下分别启动应用，肉眼比对首页和发现页

每个 Task 末尾会包含静态校验步骤。手动验证集中放在最后的 Task 4。

---

## Task 1: 新增配置开关

**Files:**
- Modify: `lib/data/models/appconfig.dart`

- [ ] **Step 1: 在 AppConfig 类中新增静态字段**

打开 `lib/data/models/appconfig.dart`，找到 `class AppConfig {` 后第一行（`static late UserGetAppConfigResp config;` 上方），插入字段。

最终类的开头部分应是：

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

  static late UserGetAppConfigResp config;

  // 新增一个私有的静态布尔值来跟踪初始化状态
  static bool _isInitialized = false;

  // ... 其余方法保持不变
```

- [ ] **Step 2: 静态校验**

Run: `cd /Users/liuxiamin/work/flutter_projects/deep_voice && flutter analyze lib/data/models/appconfig.dart`
Expected: 无新增 warning/error

- [ ] **Step 3: 提交**

```bash
git add lib/data/models/appconfig.dart
git commit -m "feat: 新增 AppConfig.hideAiAssistant 全局开关"
```

---

## Task 2: 首页新增精简布局

**Files:**
- Modify: `lib/modules/home/views/home_view.dart`

- [ ] **Step 1: 新增 import**

确认 `home_view.dart` 顶部已 import `'../../../data/models/appconfig.dart'`。该文件第 9 行已有 `import '../../../data/models/appconfig_model.dart';`，需要**追加**一行：

```dart
import '../../../data/models/appconfig.dart';
```

- [ ] **Step 2: 在 build() 中按开关分发**

在 `home_view.dart` 找到 `build()` 方法中以下代码（约 145-147 行）：

```dart
              // 热门AI体验
              _buildSectionTitle(isDarkMode),
              SizedBox(height: 16.h),
              _buildPremiumAILayout(),
```

替换为：

```dart
              // 热门AI体验
              _buildSectionTitle(isDarkMode),
              SizedBox(height: 16.h),
              AppConfig.hideAiAssistant
                  ? _buildSimplifiedAILayout()
                  : _buildPremiumAILayout(),
```

- [ ] **Step 3: 在文件末尾（HomeView 类的最后一个方法 `_buildFeatureCard` 之后、类闭合 `}` 之前）新增精简布局方法**

在 `_buildFeatureCard` 方法结束后，类闭合大括号之前，添加：

```dart
  // 精简布局：隐藏"AI全能助手"，仅保留翻译 + 会议助手，左右等宽
  // 注意：本布局不包裹 IntroStepBuilder(order: 3)，新手引导走完唤醒后自然结束
  Widget _buildSimplifiedAILayout() {
    final bool isDarkMode = Get.isDarkMode;
    return Row(
      crossAxisAlignment: CrossAxisAlignment.start,
      children: [
        // 左侧：翻译
        Expanded(
          flex: 1,
          child: _buildFeatureCard(
            title: 'interpretation'.tr,
            description: 'simultaneousInterpretationInfo'.tr,
            icon: Icons.translate,
            gradient: LinearGradient(
              begin: Alignment.topLeft,
              end: Alignment.bottomRight,
              colors: [
                const Color(0xFF4CAF50).withOpacity(0.3),
                const Color(0xFF009688).withOpacity(0.3),
              ],
            ),
            onTap: controller.openTranslation,
            iconOnTop: true,
            height: 140.h,
            isDarkMode: isDarkMode,
            iconColor: const Color(0xFF4CAF50),
          ),
        ),
        SizedBox(width: 16.w),
        // 右侧：会议助手
        Expanded(
          flex: 1,
          child: _buildFeatureCard(
            title: 'conferenceAssistant'.tr,
            description: 'conferenceAssistantInfo'.tr,
            icon: Icons.people,
            gradient: LinearGradient(
              begin: Alignment.topLeft,
              end: Alignment.bottomRight,
              colors: [
                const Color(0xFFab47bc).withOpacity(0.3),
                const Color(0xFFec407a).withOpacity(0.3),
              ],
            ),
            onTap: () => controller.openMeet(),
            iconOnTop: true,
            height: 140.h,
            isDarkMode: isDarkMode,
            iconColor: const Color(0xFFd81b60),
          ),
        ),
      ],
    );
  }
```

- [ ] **Step 4: 静态校验**

Run: `cd /Users/liuxiamin/work/flutter_projects/deep_voice && flutter analyze lib/modules/home/views/home_view.dart`
Expected: 无新增 warning/error

- [ ] **Step 5: 提交**

```bash
git add lib/modules/home/views/home_view.dart
git commit -m "feat(home): 新增精简布局，隐藏 AI 全能助手时使用"
```

---

## Task 3: 发现页新增精简布局

**Files:**
- Modify: `lib/modules/explore/views/explore_view.dart`

- [ ] **Step 1: 新增 import**

在 `explore_view.dart` 顶部 import 区追加：

```dart
import '../../../data/models/appconfig.dart';
```

- [ ] **Step 2: 在 build() 中按开关分发**

找到 `explore_view.dart` 中以下代码（约第 67-68 行）：

```dart
                      // AI功能列表
                      SizedBox(height: 24.h),
                      _buildCustomAILayout(isDarkMode),
```

替换为：

```dart
                      // AI功能列表
                      SizedBox(height: 24.h),
                      AppConfig.hideAiAssistant
                          ? _buildSimplifiedAILayout(isDarkMode)
                          : _buildCustomAILayout(isDarkMode),
```

- [ ] **Step 3: 在文件末尾（`_buildAIFeatureItemWide` 方法之后、ExploreView 类闭合 `}` 之前）新增精简布局方法**

```dart
  // 精简布局：隐藏"AI全能助手"，仅保留翻译 + 会议助手，上下堆叠 banner 卡
  // 复用 controller.aiFeatures 中索引 1（翻译）和 2（会议助手）的数据
  Widget _buildSimplifiedAILayout(bool isDarkMode) {
    return Column(
      crossAxisAlignment: CrossAxisAlignment.start,
      children: [
        Text(
          'aiFunction'.tr, // AI功能
          style: TextStyle(
            fontSize: 18.sp,
            fontWeight: FontWeight.w600,
            color: isDarkMode ? Colors.white : Colors.grey[800],
          ),
        ),
        SizedBox(height: 16.h),
        // 翻译（banner 卡）
        _buildSimplifiedBannerCard(controller.aiFeatures[1], 1, isDarkMode),
        SizedBox(height: 12.h),
        // 会议助手（banner 卡）
        _buildSimplifiedBannerCard(controller.aiFeatures[2], 2, isDarkMode),
      ],
    );
  }

  // 精简布局下的 banner 卡（图标右上角，标题/描述左下角）
  Widget _buildSimplifiedBannerCard(
      AIFeature feature, int index, bool isDarkMode) {
    return GestureDetector(
      onTap: () => controller.onAIFeatureTap(index),
      child: Container(
        height: 130.h,
        padding: EdgeInsets.all(16.w),
        decoration: BoxDecoration(
          gradient: LinearGradient(
            begin: Alignment.topLeft,
            end: Alignment.bottomRight,
            colors: [
              feature.startColor.withOpacity(0.3),
              feature.endColor.withOpacity(0.3),
            ],
          ),
          borderRadius: BorderRadius.circular(20.r),
          boxShadow: [
            BoxShadow(
              color: isDarkMode
                  ? Colors.black.withOpacity(0.2)
                  : Colors.grey.withOpacity(0.1),
              blurRadius: 8,
              offset: const Offset(0, 4),
            ),
          ],
        ),
        child: Stack(
          children: [
            // 图标右上角
            Positioned(
              top: 0,
              right: 0,
              child: Container(
                width: 44.w,
                height: 44.w,
                decoration: BoxDecoration(
                  color: feature.iconColor.withOpacity(0.2),
                  shape: BoxShape.circle,
                ),
                child: Icon(
                  feature.icon,
                  size: 22.sp,
                  color: feature.iconColor,
                ),
              ),
            ),
            // 标题 + 描述左下角
            Align(
              alignment: Alignment.bottomLeft,
              child: Column(
                crossAxisAlignment: CrossAxisAlignment.start,
                mainAxisSize: MainAxisSize.min,
                children: [
                  Text(
                    feature.title,
                    style: TextStyle(
                      fontSize: 16.sp,
                      fontWeight: FontWeight.w600,
                      color: isDarkMode ? Colors.white : Colors.grey[800],
                    ),
                    maxLines: 1,
                    overflow: TextOverflow.ellipsis,
                  ),
                  SizedBox(height: 4.h),
                  Text(
                    feature.description,
                    style: TextStyle(
                      fontSize: 12.sp,
                      color: isDarkMode ? Colors.grey[400] : Colors.grey[600],
                    ),
                    maxLines: 2,
                    overflow: TextOverflow.ellipsis,
                  ),
                ],
              ),
            ),
          ],
        ),
      ),
    );
  }
```

- [ ] **Step 4: 静态校验**

Run: `cd /Users/liuxiamin/work/flutter_projects/deep_voice && flutter analyze lib/modules/explore/views/explore_view.dart`
Expected: 无新增 warning/error

- [ ] **Step 5: 提交**

```bash
git add lib/modules/explore/views/explore_view.dart
git commit -m "feat(explore): 新增精简布局，隐藏 AI 全能助手时使用"
```

---

## Task 4: 全量校验与手动验证

- [ ] **Step 1: 整个项目静态校验**

Run: `cd /Users/liuxiamin/work/flutter_projects/deep_voice && flutter analyze`
Expected: 无新增 warning/error（项目已有的告警可忽略）

- [ ] **Step 2: 跑现有测试**

Run: `cd /Users/liuxiamin/work/flutter_projects/deep_voice && flutter test`
Expected: 全部 PASS（应不受本次改动影响）

- [ ] **Step 3: 默认场景手动验证（hideAiAssistant = false）**

确认 `AppConfig.hideAiAssistant` 为 `false`（默认值），启动应用：

Run: `cd /Users/liuxiamin/work/flutter_projects/deep_voice && flutter run`

肉眼检查：
- 首页"热门AI体验"区域：左大卡（AI 全能助手）+ 右两小卡（翻译、会议助手），与改动前一致
- 发现页"AI 功能"区域：上层 2 方卡（AI 全能助手 + 同声传译）+ 下层 1 宽卡（商务会议助手），与改动前一致
- 新手引导走完三步：设备状态 → 唤醒 → AI 全能助手
- 暗色主题切换正常

- [ ] **Step 4: 精简场景手动验证（hideAiAssistant = true）**

临时修改 `lib/data/models/appconfig.dart` 中：
```dart
static bool hideAiAssistant = true;
```

重启应用，肉眼检查：
- 首页"热门AI体验"：仅显示翻译 + 会议助手，左右等宽，高度约 140.h，绿色/紫粉渐变
- 发现页"AI 功能"：上下堆叠两张 banner 卡，高度约 130.h，图标右上、标题左下
- 新手引导走完两步后正常结束（不再被引到 AI 全能助手）
- 翻译卡和会议助手卡点击能正常跳转
- 暗色主题切换正常

- [ ] **Step 5: 还原默认值**

把 `hideAiAssistant` 改回 `false`：

```dart
static bool hideAiAssistant = false;
```

确认本次改动**不修改默认值**进入仓库。

- [ ] **Step 6: 最终提交（如 Step 5 有改动）**

```bash
git status # 确认无未提交改动
```

如果有，则：
```bash
git add lib/data/models/appconfig.dart
git commit -m "chore: 还原 hideAiAssistant 默认值为 false"
```

---

## 完成标准

- 三次提交（Task 1/2/3 各一次），代码符合 spec 中的"文件改动清单"
- `flutter analyze` 通过
- 手动验证两种开关值下首页和发现页表现符合预期
- 新手引导在两种值下都能走完不卡顿