# K24 计划：客户端 UI 对齐设计稿

日期：2026-10-19
客户端基线：`ReelShort/develop` = `b1c69e2`
文档基线：`FruitServer/develop` = `93b2299`
分支：`feature/flutter-k24-design-system`

## 一、范围

本批只做设计系统、3 Tab 底部导航、首页沉浸层、发现页：

- 设计 token：Obsidian Flare 色板、字体、间距/圆角、玻璃面板。
- 底部导航：Home / Discover / Me 三项；My List 不再独立成 Tab，内容并入 Me 页。
- 首页：保留 `PlayerPage(homeMode: true)` 播放链路，只替换叠加层与信息卡。
- 发现页：品牌行、搜索、分类 chips、Continue Watching、4 个快捷入口、2 列 Trending。

不做：详情页、播放器、我的页、登录页的视觉重做（K25/K26）；后端、Web、specs、main。

## 二、设计口径

权威来源：`docs/design/README.md` + `screens/01-home.html` + `screens/02-discover.html`。
不采用 `DESIGN.md` 顶部 YAML 的 `#ffb4a5/#cdbdff`。

| 语义 | 值 |
| --- | --- |
| background / ink / bar | `#0B0C10` |
| card | `#16181F` |
| surface-elevated / raised | `#1D1E28` |
| primary / blue | `#FF5B3D` |
| pressed / bluePressed | `#FF4321` |
| secondary / lavender / blueSoft | `#9278EA` |
| gold | `#FBBF24` |
| success | `#34D399` |
| on-surface | `#FFFFFF` / `#E3E2E8` |
| muted | `#A1A1AA` |
| subtle | `#71717A` |
| border | `rgba(255,255,255,0.08)` |

字体：Outfit（标题）、Plus Jakarta Sans（正文），OFL TTF 本地打包，不运行时联网。
下载失败时保留系统字体，并在回执与 PROGRESS 标注未完成项。

## 三、TDD 顺序

1. 设计 token / 主题：先更新 `test/theme/app_theme_test.dart` 期望值与新增 token 断言，再改
   `app_colors.dart`、`app_theme.dart`、`app_dimens.dart`。
2. GlassPanel：先写组件测试（blur、渐变、描边、圆角），再实现 `glass_panel.dart`。
3. 3 Tab：先改导航测试为 `tab-home/tab-discover/tab-my`，覆盖选中态、映射、沉浸隐藏；
   再改 `app_bottom_nav.dart` 与 `home_view.dart`。
4. 首页：先用现有 Player 测试保证播放/进度/收藏不回归，再新增首页结构断言
   （剧名、HOT、右侧互动栏、底部玻璃卡、Follow Series、Episodes）。
5. 发现页：先写搜索过滤、2 列网格、Continue Watching 隐藏/显示测试，再改
   `discover_view.dart` / `discover_logic.dart` / `home_drama_grid.dart`。
6. 回归：更新 4 Tab 与轮播挂载相关断言，保留播放、进度、收藏、举报等行为测试。

## 四、影响文件

- `lib/core/theme/app_colors.dart`
- `lib/core/theme/app_theme.dart`
- `lib/core/theme/app_dimens.dart`
- `lib/core/widgets/glass_panel.dart`（新增）
- `lib/core/widgets/app_bottom_nav.dart`
- `lib/pages/home/home_view.dart`
- `lib/pages/home/home_logic.dart`
- `lib/pages/discover/discover_view.dart`
- `lib/pages/discover/discover_logic.dart`
- `lib/pages/discover/widgets/home_drama_grid.dart`
- `lib/pages/player/player_view.dart`（仅 homeMode 叠加层）
- `lib/pages/mine/mine_view.dart`（仅把 My List 区块并入 Me）
- `pubspec.yaml`、`assets/fonts/*`
- 相关 `test/**`

## 五、数据缺口与降级

| 设计字段 | 现有数据 | 处理 |
| --- | --- | --- |
| 评分 | `Drama` 无评分字段 | 隐藏，不伪造 |
| 完结状态 | 无完结字段 | 隐藏 |
| 榜单名次 | 无字段 | 用 `isHot` + `viewCount` 排序展示，不编名次 |
| VIP 徽章 | 无 VIP 字段；`Episode.locked` 仅集级 | 列表不显示 VIP 徽章 |
| Free 徽章 | `freeEpisodes` 仅详情接口 | 有值才显示 |
| 点赞/评论数 | 互动接口无剧级计数 | 只显示图标或文案，不编数字 |
| Continue Watching 集数/剩余时长 | `WatchProgress` 有位置/时长，无集号 | 有记录才显示，集号缺失时省略 |

## 六、风险

- 首页叠加层改动可能影响沉浸模式、PiP、下载入口与既有 tooltip；通过保留原有行为入口并跑
  `test/widget_test.dart`、`test/home/**`、`test/player/**` 控制风险。
- 3 Tab 合并会触碰多个导航测试；只调整 Tab 数量/Key 断言，不改播放与收藏断言。
- 新字体增加安装包体积；只打包 Regular/SemiBold/Bold 必要字重。
- 发现页数据源仍用 `CategoryController.visibleDramas`，不新增接口。

## 七、门禁

```bash
flutter pub get
dart analyze lib test
flutter test
flutter build apk --debug
```

提交作者/提交者：`Zhou Weidong <502333560@qq.com>`。