# 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 环境影响；若失败会记录原始输出，不以开发机接口请求代替设备证据。
- 当前没有待确认的产品问题；若执行中出现契约与实现不一致，按任务书先停并登记。