docs(client): 重写 README 并补充任务与文件说明

2026-10-17 23:02:28 +08:00
1 parent f95325d581
commit 5a28845b5e
@@ -0,0 +1,99 @@
+# 客户端文件说明
+
+## 目录树
+
+```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 包管理工具维护，应提交但不手工编辑。
@@ -0,0 +1,38 @@
+# 客户端任务清单
+
+状态按当前 `develop` 中已合入的功能整理。契约章节以
+`FruitServer/docs/api-phase1.md` 为准；任务过程记录见
+`FruitServer/docs/plans/PROGRESS.md`。
+
+## K1-K13
+
+| 批次 | 范围 | 状态 | 关键提交或契约章节 | 备注 |
+| --- | --- | --- | --- | --- |
+| K1 | 详情、播放票据、观看进度、续看、收藏 | 已完成并合入 | §1.3-§1.5 | 已有三态和基础页面 |
+| K2 | 分类、观看记录、收藏列表、下载授权管理 | 已完成并合入 | §1.2、§1.5、§1.6 | 下载只管理授权，不落盘 |
+| K3 | 评论、回复、点赞、举报、分享 | 已完成并合入 | §1.7 | 分享使用系统分享面板 |
+| K4 | 账号剩余能力 | 未开始 | §1.1 | Google 登录所需凭据和契约范围需核对 |
+| K5 | 克莱因蓝主题、印尼语适配 | 已完成并合入 | 无接口变更 | 三语为 en/zh/id |
+| K6 | 登录页、底部导航、触觉反馈 | 已完成并合入 | 无接口变更 | 触觉通过 `Haptics` 封装 |
+| K7 | 首页轮播、站内通知 | 已完成并合入 | §1.3、§1.9.2 | 通知无已读态 |
+| K8 | 登录页视觉重设计 | 已完成并合入 | 无接口变更 | 保留原有登录逻辑和校验 |
+| K9 | 首页全部剧目双列网格 | 已完成并合入 | 无接口变更 | 数据源为 feed 分类结果 |
+| K10 | 统一空列表占位 | 已完成并合入 | 无接口变更 | 评论弹窗使用 compact 变体 |
+| K11 | 首页三列、分类首位“全部” | 已完成并合入 | 无接口变更 | 网格比例保持 2:3 |
+| K12 | 首页去标题、空态视觉重做 | 已完成并合入 | 无接口变更 | 双层同心圆空态 |
+| K13 | debug 运行时服务器地址 | 已完成并合入 | 无接口变更 | 保存后重启生效，release 不开放 |
+
+## 待办
+
+| 事项 | 状态 | 依赖或说明 |
+| --- | --- | --- |
+| K4 账号剩余能力 | 待办 | Google 登录需要客户端凭据、平台配置和后端契约，范围需核对 |
+| B1 支付与金币 | 待办 | 客户端尚未接入 §1.8 的支付/权益闭环，商品、渠道和验证方式需核对 |
+| 搜索 | 待办 | 当前没有独立搜索接口，接口契约和数据范围需核对 |
+| 下载落盘 | 待办 | 需要新增文件下载、进度持久化、续传、离线播放和本地清理设计 |
+
+## 维护规则
+
+- 新批次完成后更新本表，不写未经确认的提交号。
+- 功能状态以当前 `develop` 代码和自动化测试为准。
+- “需核对”表示产品范围、接口或外部凭据尚未确认，不能按已完成处理。