156 lines
4.9 KiB
Markdown
156 lines
4.9 KiB
Markdown
# FruitShorts（ReelShort）客户端
|
||
|
||
FruitShorts 是面向印尼市场的短剧 Flutter 客户端。当前版本已连接
|
||
`FruitServer` 的 `/app/**` 接口，支持沉浸播放、找剧、账号、观看记录、收藏、
|
||
下载授权、评论互动、站内通知和中英印尼三语界面。
|
||
|
||
## 技术栈
|
||
|
||
- Flutter 3.47.7 / Dart 3.13.5
|
||
- Provider 状态管理与依赖注入
|
||
- dio 网络请求
|
||
- video_player 播放
|
||
- shared_preferences 与 `SharedPreferencesAsync` 本地配置
|
||
- flutter_localizations，支持 `en`、`zh`、`id`
|
||
- Android 系统画中画
|
||
|
||
## 目录结构
|
||
|
||
```text
|
||
lib/
|
||
core/
|
||
config/ 地址、语言和运行时配置
|
||
data/ models、remote API、repository、controller
|
||
formatting/ 文案与日期格式化
|
||
platform/ 触觉等平台能力
|
||
theme/ 颜色与主题
|
||
widgets/ 跨页面复用组件
|
||
l10n/ 三语 ARB 与生成代码
|
||
pages/ 业务页面
|
||
test/ 单元、组件、页面和联调测试
|
||
integration_test/ 设备侧集成测试
|
||
android/ Android 工程
|
||
ios/ iOS 工程与 SPM 配置
|
||
assets/ 图标、图片和本地媒体文件
|
||
```
|
||
|
||
## 已接接口
|
||
|
||
以下接口均在 `lib/core/data/remote/` 中有实际调用，共 26 个不同路径、
|
||
31 个 HTTP 方法级调用。
|
||
|
||
| 分组 | 契约 | 接口 |
|
||
| --- | --- | --- |
|
||
| 账号 | §1.1 | `POST /app/auth/register`、`/login`、`/refresh`、`/logout` |
|
||
| 内容 | §1.3、§1.4 | `GET /app/home/feed`、`/app/discover/feed`、`/app/categories`、`/app/dramas/{id}`、`/app/episodes/{id}/play` |
|
||
| 观看记录 | §1.5 | `POST/GET /app/watch/progress`、`GET /app/watch/recent`、`DELETE /app/watch/progress/{dramaId}`、`DELETE /app/watch/progress` |
|
||
| 收藏 | §1.5 | `POST /app/favorites/toggle`、`GET /app/favorites`、`DELETE /app/favorites/{dramaId}` |
|
||
| 下载授权 | §1.6 | `GET /app/downloads/policy`、`PUT /app/downloads/settings`、`POST/GET /app/downloads`、`GET /app/downloads/{episodeId}/url`、`POST /app/downloads/{episodeId}/progress`、`DELETE /app/downloads/{episodeId}`、`DELETE /app/downloads` |
|
||
| 互动 | §1.7 | `GET/POST /app/comments`、`DELETE /app/comments/{id}`、`POST /app/likes/toggle`、`POST /app/reports` |
|
||
| 公告 | §1.9.2 | `GET /app/notices` |
|
||
|
||
客户端没有调用 `/app/config` 或创作者入驻接口。
|
||
|
||
## 运行
|
||
|
||
### 安装依赖
|
||
|
||
```bash
|
||
flutter pub get
|
||
```
|
||
|
||
### Android USB
|
||
|
||
手机开启 USB 调试并连接电脑后：
|
||
|
||
```bash
|
||
adb devices
|
||
adb reverse tcp:8081 tcp:8081
|
||
flutter run -d <device> \
|
||
--dart-define=API_BASE_URL=http://127.0.0.1:8081
|
||
```
|
||
|
||
`adb reverse` 将手机的 `127.0.0.1:8081` 转发到电脑；USB 断开或重新连接后需要
|
||
重新执行。
|
||
|
||
Android 模拟器访问宿主机时使用：
|
||
|
||
```bash
|
||
flutter run --dart-define=API_BASE_URL=http://10.0.2.2:8081
|
||
```
|
||
|
||
### iOS
|
||
|
||
手机与 Mac 需在同一网络，首次启动允许“本地网络”权限：
|
||
|
||
```bash
|
||
flutter run -d <udid> \
|
||
--dart-define=API_BASE_URL=http://<Mac局域网IP>:8081
|
||
```
|
||
|
||
### Debug 运行时地址
|
||
|
||
debug 版本可在「我的 → 设置 → 服务器地址」修改后端地址，保存后重启 App 生效。
|
||
地址优先级：
|
||
|
||
```text
|
||
本地运行时设置 > --dart-define(API_BASE_URL) > 平台默认地址
|
||
```
|
||
|
||
因此不带 `--dart-define` 构建的 debug APK 也可在安装后改成当前电脑 IP。
|
||
release 版本不显示入口，也不会读取本地覆盖。
|
||
|
||
## 环境注意
|
||
|
||
### iOS Swift 版本
|
||
|
||
`pubspec.yaml` 将 `shared_preferences_foundation` 固定为 `2.5.6`。该版本兼容
|
||
Xcode 16.2 / Swift 6.0.3；`2.6.0` 的生成代码使用 Swift 6.1 才支持的 trailing
|
||
comma。不要手工升级该依赖，`flutter pub get` 后应显示
|
||
`shared_preferences_foundation 2.5.6 (overridden)`。
|
||
|
||
### iOS SPM 包缺失
|
||
|
||
如果 Xcode 报 `Missing package product FlutterGeneratedPluginSwiftPackage`：
|
||
|
||
```bash
|
||
rm -rf ~/Library/Developer/Xcode/DerivedData/Runner-*
|
||
flutter clean
|
||
flutter pub get
|
||
xcodebuild -resolvePackageDependencies \
|
||
-project ios/Runner.xcodeproj \
|
||
-scheme Runner
|
||
```
|
||
|
||
随后重新打开工程构建。`Runner.xcscheme` 的 PreAction 会先执行
|
||
`flutter pub get`，再执行 Flutter prepare。
|
||
|
||
### Android libdartjni
|
||
|
||
若启动时报 `libdartjni.so` 加载失败，通常是旧安装中的原生库残留：
|
||
|
||
```bash
|
||
adb uninstall com.stormg.lumadrama
|
||
flutter run -d <device> \
|
||
--dart-define=API_BASE_URL=http://127.0.0.1:8081
|
||
```
|
||
|
||
## 门禁
|
||
|
||
```bash
|
||
dart analyze lib test
|
||
flutter test
|
||
flutter build apk --debug
|
||
```
|
||
|
||
测试文件按模块放在 `test/` 下，用例名使用
|
||
`should_<期望>_when_<条件>`。真实后端联调测试在服务未启动时会跳过。
|
||
|
||
## 当前边界
|
||
|
||
- 下载仅管理服务端授权，不落盘、不续传、不支持离线播放。
|
||
- 没有独立搜索接口，搜索能力尚未形成完整闭环。
|
||
- 站内通知没有已读/未读和红点状态。
|
||
- 支付、金币和会员权益尚未形成客户端闭环。
|
||
- Android 支持系统画中画；iOS 画中画尚未接入。
|