# 客户端文件说明

## 目录树

```text
.
├── android/                  Android 工程与 Gradle 配置
├── assets/
│   ├── icon/                 启动图标
│   ├── images/               本地图片
│   └── media/                本地视频文件（当前未在 pubspec 声明）
├── integration_test/         设备侧集成测试
├── ios/
│   ├── Flutter/              Flutter 生成配置与 SPM 临时包
│   ├── Runner/               iOS Runner
│   ├── Runner.xcodeproj/     Xcode 工程与共享 Scheme
│   └── RunnerTests/          iOS 原生测试
├── lib/
│   ├── core/
│   │   ├── config/           地址、语言、运行时服务器设置
│   │   ├── data/             models、remote、repositories、services
│   │   ├── formatting/       多语言文案、日期和错误文本
│   │   ├── platform/         平台能力封装
│   │   ├── theme/            颜色与 ThemeData
│   │   └── widgets/          通用组件
│   ├── l10n/                 ARB 与本地化生成代码
│   └── pages/                业务页面
├── test/                     单元和 Widget 测试
├── docs/                     客户端任务与文件说明
├── pubspec.yaml              依赖、资源和 Flutter 配置
└── README.md                 运行、接口与环境说明
```

## 关键文件

| 路径 | 职责 |
| --- | --- |
| `lib/main.dart` | 初始化 Flutter、屏幕方向、debug 服务器覆盖并启动 App |
| `lib/app.dart` | Provider、repository、controller、ApiClient 和主题装配 |
| `lib/core/config/app_config.dart` | 地址优先级、超时、媒体 URL 和平台默认地址 |
| `lib/core/config/server_endpoint.dart` | debug 运行时地址规范化、读取、保存和清除 |
| `lib/core/config/locale_controller.dart` | 语言选择与系统语言回退 |
| `lib/core/data/models/` | 账号、剧目、评论、观看、下载、公告等数据结构 |
| `lib/core/data/remote/` | `/app/**` 接口调用；`api_client.dart` 统一鉴权和错误映射 |
| `lib/core/data/repositories/` | HTTP 与内存实现的 repository 边界 |
| `lib/core/data/services/` | 页面 controller、播放会话、分享、画中画等业务服务 |
| `lib/core/formatting/` | 本地化内容、日期与错误文本 |
| `lib/core/platform/haptics.dart` | 可注入的触觉反馈封装 |
| `lib/core/theme/app_colors.dart` | 克莱因蓝和界面颜色 token |
| `lib/core/theme/app_theme.dart` | light/dark ColorScheme 与组件主题 |
| `lib/core/widgets/empty_state.dart` | 统一空列表占位 |
| `lib/core/widgets/remote_image.dart` | 后端相对图片地址与失败占位 |
| `lib/core/widgets/auth_gate.dart` | 未登录操作拦截 |
| `lib/core/widgets/download_action.dart` | 下载授权操作 |
| `lib/pages/home/` | 根页面、四个底部 tab 和抽屉 |
| `lib/pages/player/` | 竖屏播放、选集、进度和播放器交互 |
| `lib/pages/discover/` | 首页/发现信息流、轮播、分类与三列剧目网格 |
| `lib/pages/drama_detail/` | 剧目详情与剧集入口 |
| `lib/pages/auth/` | 登录/注册页面与表单逻辑 |
| `lib/pages/mine/` | 我的页、片单、设置、语言与 debug 地址入口 |
| `lib/pages/favorites/` | 收藏列表 |
| `lib/pages/watch_records/` | 独立观看记录页 |
| `lib/pages/downloads/` | 下载授权与策略页面 |
| `lib/pages/notices/` | 站内通知分页和详情 |
| `lib/pages/interaction/` | 举报弹窗 |
| `lib/l10n/*.arb` | en/zh/id 源文案，修改后执行 `flutter gen-l10n` |
| `ios/Runner.xcodeproj/xcshareddata/xcschemes/Runner.xcscheme` | iOS SPM 预构建脚本 |

## 测试结构

| 目录 | 覆盖范围 |
| --- | --- |
| `test/auth/` | 登录 controller、表单、视觉与交互 |
| `test/catalog/`、`test/category/` | 首页数据、分类和模型解析 |
| `test/comment/`、`test/interaction/` | 评论、点赞、举报和弹窗 |
| `test/config/` | 三语、系统语言和运行时服务器地址 |
| `test/core/` | ApiClient、ID 解析、触觉、分享和画中画 |
| `test/discover/`、`test/home/` | 首页、轮播、网格和导航 |
| `test/download/`、`test/library/`、`test/watch/` | 下载、收藏、观看记录 |
| `test/drama_detail/`、`test/player/`、`test/playback/` | 详情、播放器与播放队列 |
| `test/notice/` | 通知分页、空态、详情与入口 |
| `test/empty_state/`、`test/theme/` | 空态组件与主题 token |
| `test/integration/` | 依赖本机后端的联调测试，服务未启动时跳过 |
| `integration_test/app_backend_test.dart` | 设备侧后端连通性测试 |
| `test/support/` | fake repository、HTTP adapter、播放器和测试数据 |

## 生成物

以下内容由工具生成，不要手工修改：

- `lib/l10n/app_localizations*.dart`
- `*.g.dart`
- `.dart_tool/`
- `build/`
- `ios/Flutter/ephemeral/`
- `ios/Runner/GeneratedPluginRegistrant.h`
- `ios/Runner/GeneratedPluginRegistrant.m`

`pubspec.lock` 由 Dart 包管理工具维护，应提交但不手工编辑。