FruitServer/docs/plans/2026-10-17-K3.md

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