93 lines
5.4 KiB
Markdown
93 lines
5.4 KiB
Markdown
# 2026-10-17 K3 客户端第三批：互动
|
||
|
||
## 一、目标与边界
|
||
|
||
本轮只完成 Flutter 客户端互动能力的真实接口接入：
|
||
|
||
- K3-A 评论：匿名游标列表、顶层评论与一层回复、发布、敏感词三档、删除、三态与重试。
|
||
- K3-B 点赞：剧集与评论点赞、乐观更新、失败回滚、未登录拦截、防连点。
|
||
- K3-C 举报：举报评论与短剧、固定原因单选、可选描述、成功与失败提示。
|
||
- K3-D 分享回归：沿用现有系统分享，核对标题、简介与 footer 的三语文案。
|
||
|
||
不做 K4、拉黑、举报用户、后台治理、图片/表情/@提及、无限嵌套、我的评论列表和并发压测。
|
||
后端代码、后台 Web、specs 仓库均不改；接口只使用 `FruitServer/docs/api-phase1.md` §1.7。
|
||
|
||
## 一之一、实测基线
|
||
|
||
- ReelShort：`develop` / `feature/flutter-k3-interaction` 均为 `45f5f25`，功能分支从 K2 合并点派生。
|
||
- FruitServer：`develop` 为 `a0156ee`，比 `origin/develop` 多 1 个仅包含 INBOX 的派单提交。
|
||
- 本计划文件在开工前的 FruitServer 工作区中已存在且尚未提交，本轮仅增量补充，不覆盖既有内容。
|
||
|
||
## 二、契约与数据口径
|
||
|
||
| 能力 | 接口 | 客户端处理 |
|
||
| --- | --- | --- |
|
||
| 评论列表 | `GET /app/comments?dramaId=&episodeId=&rootId=&cursor=&size=` | 首屏 20 条，按 `nextCursor` 续拉，用 `hasMore` 控制加载更多 |
|
||
| 发布评论 | `POST /app/comments` | 顶层传 `dramaId/content`，回复额外传 `parentId` |
|
||
| 删除评论 | `DELETE /app/comments/{id}` | 仅 `mine=true` 可操作，二次确认，失败恢复列表 |
|
||
| 点赞切换 | `POST /app/likes/toggle` | `DRAMA` / `COMMENT`，以响应 `{liked,count}` 为最终态 |
|
||
| 举报 | `POST /app/reports` | `COMMENT` / `DRAMA`，`reasonCode` 必填 |
|
||
| 系统分享 | 无后端接口 | 保持 `PlatformShareService` |
|
||
|
||
评论字段按 `CommentRespVO` 解析，ID 全部使用字符串。所有新增用户可见文案进入
|
||
`lib/l10n/app_{en,zh,id}.arb` 并重新生成。
|
||
|
||
## 三、已确认的契约缺口与降级
|
||
|
||
1. `AppDramaDetailVO` / `AppDramaCardVO` 没有 `likeCount` / `liked`。
|
||
降级：不展示剧集点赞数字，只维护当前会话内的 liked 状态。
|
||
建议：后端详情与卡片补 `likeCount` / `liked`，需 specs 负责人变更契约。
|
||
2. §1.7 没有定义 `reasonCode` 枚举，后端当前不校验。
|
||
降级：客户端固定 `SPAM / ABUSE / PORN / AD / OTHER` 五项，文案进三语 arb。
|
||
建议：后端补 `reasonCode` 枚举与后台工单映射。
|
||
3. §1.7 没有拉黑接口。
|
||
降级：本批不做拉黑，不提供入口。
|
||
|
||
## 四、预计影响文件
|
||
|
||
FruitServer 文档：
|
||
|
||
- `docs/plans/2026-10-17-K3.md`
|
||
- `docs/plans/PROGRESS.md`
|
||
- `docs/plans/INBOX.md`
|
||
|
||
ReelShort 客户端：
|
||
|
||
- `lib/core/data/remote/comment_api.dart`
|
||
- `lib/core/data/remote/interaction_api.dart`
|
||
- `lib/core/data/repositories/comment_repository.dart`
|
||
- `lib/core/data/repositories/interaction_repository.dart`
|
||
- `lib/core/data/services/comment_controller.dart`
|
||
- 互动相关模型、Provider 注入与页面/组件
|
||
- `lib/pages/player/widgets/drama_comments_sheet.dart`
|
||
- `lib/pages/player/player_view.dart`
|
||
- 详情页举报入口及互动弹窗
|
||
- `lib/l10n/app_{en,zh,id}.arb` 与生成文件
|
||
- 对应 `test/**/*_test.dart`
|
||
|
||
实际文件以现有 K1/K2 分层和注入方式为准，避免无关重构。
|
||
|
||
## 五、TDD 与执行顺序
|
||
|
||
1. 只读核对 `ReelShort` 与 `FruitServer` 的 `develop` 基线、工作区状态与提交。
|
||
2. 从 `develop` 建 `feature/flutter-k3-interaction`。
|
||
3. K3-A：先写评论分页、发布、敏感词、删除、失败回滚和未登录测试并确认红灯，再实现并转绿。
|
||
4. K3-B：先写剧集/评论点赞成功、计数、乐观更新、回滚和未登录测试并确认红灯，再实现并转绿。
|
||
5. K3-C：先写举报成功、重复举报 message 透传和未登录测试并确认红灯，再实现并转绿。
|
||
6. K3-D：补充分享文案回归检查，确认三语资源完整。
|
||
7. 每块执行定向测试和 `dart analyze lib test`。
|
||
8. 全量执行 `dart analyze lib test`、`flutter test`、`flutter build apk --debug`。
|
||
9. 分块提交，`--no-ff` 合并回 `develop` 并 push；文档单独提交并 push。
|
||
10. 在 `PROGRESS.md` 与 INBOX 写回执，列出用户真机验证步骤，并明确设备侧取证未由 Codex 执行。
|
||
|
||
## 六、风险与待确认
|
||
|
||
- 评论游标的实际响应字段以已实现后端 VO 为准；若与任务书 `nextCursor/hasMore` 不一致，先停止并在 INBOX 顶部登记待协助，不自行扩契约。
|
||
- 剧集点赞没有初始查询接口，页面重建后会话内状态可能丢失；本批按降级方案不伪造初始值。
|
||
- 匿名列表可见，但发布、点赞、举报必须登录；需确保 AuthGate 在发起业务请求前拦截。
|
||
- 举报重复与举报自己依赖后端 message，客户端只原样展示，不自行判断。
|
||
- 敏感词 `REVIEW` 的 pending 评论仅自己可见，客户端必须保留发布成功返回内容并显示“审核中”。
|
||
- 现有互动控制器为本地演示数据，移除时不得破坏 K2 的分类、记录、收藏、下载和播放进度逻辑。
|
||
- 全量构建可能受本机 Flutter/Android SDK 环境影响；若失败会记录原始输出，不以开发机接口请求代替设备证据。
|
||
- 当前没有待确认的产品问题；若执行中出现契约与实现不一致，按任务书先停并登记。
|