docs(plans): 新增 K1 条目（客户端对接：详情+播放+进度续看+收藏，含 UI 三态）
PM 勘察：客户端只调了 6 个 C 端接口（契约已实现 44 个）；无 playback/watch/library api 类；WatchHistoryRepository 仍是 SharedPreferences 本地存储、mine_logic 用 demoProfileId 假数据；EngagementRepository 亦为本地。K1 打通首页→详情→播放→续看→收藏一条链路。
This commit is contained in:
jianghaifeng committed
1 parent
0cab094194
commit
59d064f8c6
1 file changed
+76
-1
+76
-1
@@ -19,7 +19,82 @@
|
||||
|
||||
---
|
||||
|
||||
## [已处理·待用户验收] 2026-10-16 18:30 | J1 全局 ID 字符串化（Long → String）+ 契约统一
|
||||
## [待处理] 2026-10-16 19:40 | K1 客户端对接：详情 + 播放 + 进度续看 + 收藏（看剧闭环）+ UI 调整
|
||||
|
||||
**用户指令（2026-10-16 19:30）**：「现在你要做的事对接客户端接口及 UI 调整，仍然严格按照 specs 执行」→ 转到 **客户端 `ReelShort`（Flutter）**，按 specs 阶段 A 推进。
|
||||
|
||||
### 一、PM 已勘察的现状（实测，直接用）
|
||||
|
||||
**客户端目前只调了 6 个 C 端接口**（契约里已实现 **44 个**）：
|
||||
```
|
||||
/app/home/feed /app/discover/feed
|
||||
/app/auth/register /app/auth/login /app/auth/refresh /app/auth/logout
|
||||
```
|
||||
- `lib/core/data/remote/` 下**只有** `api_client / api_exception / api_interceptors / auth_api / catalog_api` —— **没有** playback / watch / library / interaction / me 的 api 类。
|
||||
- `WatchHistoryRepository` 是 **`SharedPreferencesWatchHistoryRepository`（本地存储）**，`mine_logic` 还在用 **`demoProfileId`** 假数据 —— 观看进度/续看位置**全在本机**，没接 `/app/watch/*`。
|
||||
- `EngagementRepository` 是 `SharedPreferences` / `InMemory` —— 点赞/收藏状态**也是本地假数据**。
|
||||
- 已有：`dio` 网络层 + 拦截器（A1 ✅）、改名 + 印尼语（✅）、`json_numbers.dart` 兼容字符串 id（J1 ✅）。
|
||||
|
||||
### 二、本批范围（K1：一条完整看剧闭环）
|
||||
|
||||
> 目标：**从首页点进一部剧 → 详情正确 → 能起播 → 进度能续看 → 能收藏**，全链路走真接口。
|
||||
|
||||
1. **详情（A3 的一块）**：新增 `catalog_api` 方法对接 `GET /app/dramas/{id}`（含剧集列表；**免费集带已签名播放地址**）。
|
||||
2. **播放（A4）**：新增 `lib/core/data/remote/playback_api.dart`
|
||||
- `GET /app/episodes/{id}/play` → 票据 + 签名地址。**签名地址原样使用，不要拼接/改写**（文档硬要求）。
|
||||
- 起播前取票据；票据/签名地址有有效期，**过期要重新取**，不要缓存到失效后还用。
|
||||
3. **进度与续看（A5 的一块）**：
|
||||
- `POST /app/watch/progress`（**每 10s 一次**，切集/退出/切后台各补一次）
|
||||
- `GET /app/watch/progress?dramaId=`（进入详情/播放时定位续看位置）
|
||||
- `GET /app/watch/recent?limit=20`（"我的"页最近观看）
|
||||
- **把 `WatchHistoryRepository` 的本地实现换成远程实现**（保留抽象接口，测试注入内存假实现）；`mine_logic` **去掉 `demoProfileId`**。
|
||||
4. **收藏（A5 的一块）**：`POST /app/favorites/toggle`、`GET /app/favorites`、`DELETE /app/favorites/{dramaId}`；收藏状态**以服务端为准**（不要再用本地 `EngagementRepository` 存收藏）。
|
||||
5. **UI 调整**（本批必须一起做）：
|
||||
- 详情页 / 播放页 / "我的"页：**加载中 / 空 / 失败**三态齐备（失败要能重试，不要白屏或假装成功）
|
||||
- 进度条与**续看定位**、收藏按钮的真实状态与乐观更新回滚
|
||||
- 断网/超时的提示文案走 l10n（en / zh / id 三份都要有）
|
||||
|
||||
### 三、口径与约束（照 specs）
|
||||
|
||||
- **ID 是字符串**（J1 刚统一）：解析走 `json_numbers.dart`，不要直接 `as int`。**计数类**（`viewCount`/`expiresIn`）也是字符串。
|
||||
- `accessType` 等枚举**用后端返回值驱动 UI**（免费/付费/试看），**不要在前端写死**；付费集解锁不在本批（属 B2）。
|
||||
- 接口层与业务层分离：**新增 api 类**、controller/logic 只依赖 repository 抽象（沿用现有 `catalog_api` + `catalog_controller` 的分层做法）。
|
||||
- **不要动**已对接的首页/发现/登录注册逻辑（除必要的最小接线）。
|
||||
- 新文件首行 `// Author: fruit.com.cn`；测试命名 `should_<期望>_when_<条件>`。
|
||||
|
||||
### 四、门禁
|
||||
|
||||
- `dart analyze lib test` **零告警** + `flutter test` **全过**（存量 27 个测试文件不得跑红；新增测试要覆盖：票据过期重取、进度上报节流、续看定位、收藏切换回滚、失败态）
|
||||
- **真实后端联调**（8081）：跑一次端到端并留证据 —— 首页 → 详情 → 播放 → 上报进度 → 重新进入看到续看位置 → 收藏出现在收藏列表
|
||||
- 在 `ReelShort` **`develop`** 提交并 `git push origin develop`；**不动 `main`**
|
||||
|
||||
### 五、节奏
|
||||
|
||||
先写 `docs/plans/2026-10-16-K1.md`（计划 + 影响面 + 风险）→ 做 → 停下写回执（含**用户可照做的验证步骤 + 每步预期结果**，以及"哪几个页面现在走真数据、哪几个还是假的"的清单）。**不要连做 K2。**
|
||||
|
||||
> **后续批次（预告，不用现在做）**：**K2** = 记录/最近观看页 + 收藏列表页 + 分类/搜索 + 下载授权（A5/A3 剩余）；**K3** = 互动（评论/点赞/举报/分享，A6）；**K4** = 账号剩余（资料/设备/注销；**Google 登录需 Google OAuth 凭据**，属待你提供的付费/密钥类）。
|
||||
|
||||
---
|
||||
|
||||
## [已处理 · 待用户验收] 2026-10-16 18:30 | J1 全局 ID 字符串化（Long → String）+ 契约统一
|
||||
|
||||
> **PM 独立复核（Trae 2026-10-16 19:05）—— 交付 `FruitServer f35db2c` / `ReelShortWeb 3ec9ea6` / `ReelShort 94ff9f1`（三仓均在 `develop` 且与远端同步），验证通过。**
|
||||
> - **门禁复跑**：`mvn test` **110 → 115 条全过**（commerce 33 / admin-api **16→21** / app-api 49 / worker 12）+ BUILD SUCCESS ✅
|
||||
> - **全局配置落位核实**：`fruitshorts-framework/.../web/JacksonLongToStringConfig.java` 存在（一处生效两端，未改 yml）✅
|
||||
> - **端到端真实验证（PM 亲自跑，非采信回执）**：新注册用户雪花 id `2111018722574602241` →
|
||||
> ① `/admin/app-users/page` 返回 **`"id":"2111018722574602241"`（字符串）**、**无裸数字大 id**、`"total":2` **仍是数字**（符合约定）；
|
||||
> ② 用该 id 调 `/admin/app-users/{id}` → **`code=0`**（修复前此场景即 `200002`）；
|
||||
> ③ **真 node 逐位比对**：`typeof parsed.id === 'string'`、`String(parsed.id)` 与库值**逐位相等 = true**；测试数据已清理（残留 0）。
|
||||
> - **按红线第 7 条，最终验收权仍归用户。**
|
||||
>
|
||||
> ⚠️ **三处口径待用户点头（PM 意见附后）**：
|
||||
> 1. **唯一例外 `PageResult.total` 保持数字** —— PM 意见：**接受**（它是条数不是 id，前端分页组件要数字）；但需在契约 §0「ID 一律字符串」处**显式写出这个例外**，否则前端会困惑。待 Codex 补一句。
|
||||
> 2. **客户端改动比"只改 id 解析"略宽（物理上必须）** —— Codex 查明 Flutter 的 id 本来就是 `toString()` 不会崩，真正会崩的是被全局规则扫到的 **Long 计数**，故只改了 `expiresIn`、`viewCount` 等 3 处 + 新增 `json_numbers.dart`。PM 认可这个判断与最小改动口径。⚠️ **另需用户知晓**：`ReelShort` 原先**只有 `main`**，Codex 新建了 `develop` 并推送；若客户端同事仍在 `main` 上开发，这笔需要带过去。
|
||||
> 3. **Codex 自我纠正了一处统计错误** —— 它第一版清理脚本用 `psql ... returning 1 | wc -l` 数行数，数到的是 psql 命令标签（删 0 行也输出 1），那轮"删除 1 行"是假数字；随后用**全库扫描**复核（uid/邮箱/雪花 id 零命中）确认无残留。PM 认可其如实披露。
|
||||
>
|
||||
> 📌 **仍挂着**：禅道里同样**没有 J1 任务**（项目 2 下只有 S0/S1、A1–A6、B1/B2、C1–C3），无可同步状态。
|
||||
>
|
||||
> ⚠️ **PM 顺手说明**：为做端到端验证，8080（PID 80375）/ 8081（80383）/ 3005 均为 Codex 重启后的新 jar，接口与页面正常。
|
||||
|
||||
**用户裁定（2026-10-16 18:10）**：雪花 id 精度问题 **「按方案 (a) 全局修改，统一契约」**。
|
||||
|
||||
|
||||
Reference in new issue
Block a user