From 969538e6c9d42c93a56e4411b658f6066a2692b4 Mon Sep 17 00:00:00 2001
From: Zhou Weidong <502333560@qq.com>
Date: Sat, 17 Oct 2026 15:27:42 +0800
Subject: [PATCH] =?UTF-8?q?docs(plans):=20=E8=AE=B0=E5=BD=95=20K3=20?=
 =?UTF-8?q?=E4=BA=92=E5=8A=A8=E5=AE=9E=E6=96=BD=E4=B8=8E=E9=AA=8C=E6=94=B6?=
 =?UTF-8?q?=E5=9B=9E=E6=89=A7?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/plans/2026-10-17-K3.md |  92 ++++++++++++
 docs/plans/INBOX.md         | 111 +++++++++++++-
 docs/plans/PROGRESS.md      | 291 ++++++++++++++++++++++++++++++++++++
 3 files changed, 493 insertions(+), 1 deletion(-)
 create mode 100644 docs/plans/2026-10-17-K3.md

diff --git a/docs/plans/2026-10-17-K3.md b/docs/plans/2026-10-17-K3.md
new file mode 100644
index 0000000..d0ee5b1
--- /dev/null
+++ b/docs/plans/2026-10-17-K3.md
@@ -0,0 +1,92 @@
+# 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 环境影响；若失败会记录原始输出，不以开发机接口请求代替设备证据。
+- 当前没有待确认的产品问题；若执行中出现契约与实现不一致，按任务书先停并登记。
diff --git a/docs/plans/INBOX.md b/docs/plans/INBOX.md
index 70d2c93..7ecd509 100644
--- a/docs/plans/INBOX.md
+++ b/docs/plans/INBOX.md
@@ -20,7 +20,7 @@
 
 ---
 
-## [待处理] 2026-10-17 | K3 客户端第三批：互动（评论 + 点赞 + 举报 + 分享）
+## [已处理·待用户验收] 2026-10-17 | K3 客户端第三批：互动（评论 + 点赞 + 举报 + 分享）
 
 **用户指令（2026-10-17）**：客户端继续对接接口及 UI，严格执行 specs。
 
@@ -127,6 +127,115 @@
 - 每步「叙述 + 命令 + 原始输出 + 解读」追加到 `docs/plans/PROGRESS.md`。
 - 做完停下写回执：真数据/本地数据页面清单、用户验证步骤与预期、门禁原始输出、提交号。
 
+### 七、K3 完成回执（2026-10-17）
+
+**结论**：K3-A 评论、K3-B 点赞、K3-C 举报、K3-D 分享回归均已完成并停止，
+未开始 K4。后端、`ReelShortWeb`、specs 均未修改。
+
+#### 7.1 真数据 / 本地数据页面清单
+
+真数据（走契约 §1.7）：
+
+- 播放页评论弹窗：匿名评论列表、游标加载更多、顶层评论、一层回复、
+  BLOCK/REPLACE/REVIEW 结果、本人删除、评论点赞。
+- 播放页剧集点赞：`POST /app/likes/toggle` 切换，乐观更新与服务端状态校准；
+  **不展示剧集点赞数字**。
+- 评论更多菜单与详情页更多菜单：评论/短剧举报，固定五项原因，可选描述。
+
+本地/系统能力：
+
+- 剧集 liked 仅保存在当前 App 会话内。因详情/卡片契约没有 `likeCount/liked`，
+  App 重启或换账号后不展示服务端初始点赞状态。
+- 分享继续走 `PlatformShareService` 系统分享，不新增后端接口。
+- “我的 → 喜欢”只过滤当前 feed 的会话内 liked，没有契约外加“我的点赞列表”接口。
+
+按降级方案未做：拉黑、举报用户、举报后台处理、无限嵌套、图片/表情/@、我的评论列表。
+
+#### 7.2 门禁原始结果
+
+```
+$ cd /Users/jianghaifeng/Desktop/ReelShort/ReelShort
+$ dart analyze lib test
+Analyzing lib, test...
+No issues found!
+
+$ flutter test
+00:11 +241 ~1: All tests passed!
+
+$ flutter build apk --debug
+Running Gradle task 'assembleDebug'...                              6.8s
+✓ Built build/app/outputs/flutter-apk/app-debug.apk
+```
+
+`~1` 是既有 `live_watch_flow_test` 在 8081 未启动时按测试机制跳过，不是失败。
+
+#### 7.3 Git
+
+- 功能提交：`d361034226ec2bc431548d45068dc60046e5e473`
+  `feat(flutter): 接入互动评论点赞举报`
+- `--no-ff` 合并提交：`9db6935308e65342be46c81419c2992ed2df1df0`
+  `merge: 合并 K3 客户端互动能力`
+- 已推送：`45f5f25..9db6935 develop -> develop`
+- author 与 committer 均为 `Zhou Weidong <502333560@qq.com>`；未操作 `main`。
+
+#### 7.4 用户真机验证步骤与预期
+
+前置：启动 8081 客户端接口服务，准备可登录测试账号；在 Android 设备安装
+`build/app/outputs/flutter-apk/app-debug.apk`，确认 App 使用设备可访问的后端地址。
+以下证据必须由用户在设备侧取得，Codex 未执行真机验证。
+
+1. 未登录打开任意有评论的剧集，点播放页评论入口。
+
+预期：评论列表正常加载；空列表显示“还没有评论”；断网后显示失败与重试，不白屏。
+
+2. 未登录点发布、评论点赞或举报，再点剧集点赞。
+
+预期：均先出现登录提示；关闭提示后不发业务请求；登录后可重试。
+
+3. 登录后发表顶层评论，再输入命中 `REPLACE` 或 `REVIEW` 策略的词。
+
+预期：顶层评论出现在列表；REPLACE 展示服务端替换后的内容；REVIEW 显示“审核中”；
+BLOCK 原样显示后端 message 且输入框内容保留。
+
+4. 在顶层评论点“回复”并发布。
+
+预期：请求带 `parentId`；回复归入该楼层，只做一层回复；点“查看回复”可展开。
+
+5. 连续加载超过首屏 20 条的评论。
+
+预期：按 `nextCursor` 续拉，不重复、不跳页；没有下一页时加载更多消失。
+
+6. 点赞一条评论和当前剧集，再点一次取消。
+
+预期：图标立即切换；评论计数在服务端响应后校准；断网时状态回滚并提示；
+剧集点赞不显示数字。
+
+7. 删除自己的评论：更多 → 删除评论 → 二次确认。
+
+预期：成功后从列表移除；制造断网/服务失败时恢复原位置并提示。其他人的评论不显示删除项。
+
+8. 举报评论与短剧：更多 → 举报；分别选择 `SPAM/ABUSE/PORN/AD/OTHER` 和可选描述。
+
+预期：成功后提示“举报已提交，感谢反馈。”；重复举报原样显示后端
+“你已举报过该内容，我们正在处理”；举报自己发布内容原样显示后端 message。
+
+9. 点播放页分享。
+
+预期：打开系统分享面板；文本顺序为标题、简介、`FruitShorts` footer；
+切换 en/zh/id 后三类文案同步切换。
+
+10. 在 Android logcat 保存评论/点赞/举报请求与响应，并保留关键页面截图。
+
+预期：可见 `/app/comments*`、`/app/likes/toggle`、`/app/reports` 的真实响应；
+设备侧取证由用户执行，开发机 `curl` 或本机返回 200 不替代本步骤。
+
+#### 7.5 未验证与已知边界
+
+- 真机、模拟器、设备日志、设备截图均未由 Codex 执行，状态为“设备侧取证待用户执行”。
+- 剧集点赞初始状态和数字因契约缺口无法展示，App 重启后当前会话状态丢失。
+- 敏感词具体词表、限流阈值、后台审核联动由后端/运营环境决定，本轮只做客户端透传与状态展示。
+- 拉黑与 K4 不在本轮范围。
+
 ---
 
 ## [已处理·待用户验收] 2026-10-17 | K2 客户端第二批：分类 + 观看记录 + 收藏列表 + 下载授权（A3/A5 剩余）+ UI
diff --git a/docs/plans/PROGRESS.md b/docs/plans/PROGRESS.md
index f3f1529..b688e6e 100644
--- a/docs/plans/PROGRESS.md
+++ b/docs/plans/PROGRESS.md
@@ -1320,3 +1320,294 @@ jianghaifeng 口径作废，后续统一使用 Zhou Weidong，本回执提交已
 - 文件分片落盘、断点续传、离线播放、`licenseKey` 本地校验不在 K2 范围，仍未实现，也不能验收。
 - 收藏接口没有分页参数，本批按全量列表验收，不验收服务端分页。
 - 搜索契约没有接口，本批不验收搜索。
+
+---
+
+## 2026-10-17 K3-A 评论实施（【Codex】）
+
+叙述：按 K3 任务书先补计划文档基线，再按评论 API/controller/UI 顺序做 TDD。
+首轮测试在实现前运行，用于确认红灯；实现后运行同一组定向测试转绿。
+
+### 18.1 计划文档
+
+命令：使用补丁工具增量更新 `docs/plans/2026-10-17-K3.md`。
+
+原始结果：
+
+```
+Success. Updated the following files:
+M /Users/jianghaifeng/Desktop/ReelShort/FruitServer/docs/plans/2026-10-17-K3.md
+```
+
+解读：保留既有 K3 计划，仅补记 ReelShort `45f5f25`、FruitServer `a0156ee`
+和计划文件未跟踪的实测基线，没有覆盖已有内容。
+
+### 18.2 K3-A 首次红灯
+
+命令：
+
+```
+$ cd /Users/jianghaifeng/Desktop/ReelShort/ReelShort
+$ flutter test test/comment/comment_api_test.dart test/comment/comment_controller_test.dart
+```
+
+原始输出（节选）：
+
+```
+Error when reading 'lib/core/data/remote/comment_api.dart': No such file or directory
+Error when reading 'lib/core/data/models/comment.dart': No such file or directory
+Error when reading 'lib/core/data/services/comment_controller.dart': No such file or directory
+00:00 +0 -2: Some tests failed.
+```
+
+解读：生产 API、模型和 controller 尚不存在，红灯原因符合预期。
+
+### 18.3 K3-A 数据层绿灯
+
+命令：实现评论模型、API、仓库和 controller 后，重跑同一组定向测试。
+
+原始输出：
+
+```
+00:00 +9: All tests passed!
+```
+
+解读：评论游标分页、String ID、发布回复、替换内容、敏感词 BLOCK message、
+删除成功与失败回滚均通过。
+
+### 18.4 K3-A UI 红灯与绿灯
+
+首次运行：
+
+```
+$ flutter test test/comment/drama_comments_sheet_test.dart
+ProviderNotFoundException: Could not find the correct Provider<EngagementController>
+00:00 +0 -5: Some tests failed.
+```
+
+解读：旧弹窗仍直接依赖本地 `EngagementController`，符合 UI 红灯预期。
+
+替换为服务端 controller、三态和回复输入后：
+
+```
+00:01 +5: All tests passed!
+```
+
+随后运行整个评论测试目录：
+
+```
+$ flutter test test/comment
+00:01 +14: All tests passed!
+```
+
+解读：API、controller 和弹窗测试共 14 项全部通过。
+
+### 18.5 K3-A 静态分析
+
+首次分析：
+
+```
+info - lib/core/data/remote/comment_api.dart:23:9 - use_null_aware_elements
+info - lib/core/data/remote/comment_api.dart:24:9 - use_null_aware_elements
+2 issues found.
+```
+
+按 lint 改为 null-aware map value 后：
+
+```
+$ dart analyze lib test
+Analyzing lib, test...
+No issues found!
+```
+
+解读：K3-A 达到零告警口径。真机交互未执行，设备侧取证仍由用户完成。
+
+### 18.6 K3-B 点赞红灯
+
+命令：
+
+```
+$ cd /Users/jianghaifeng/Desktop/ReelShort/ReelShort
+$ flutter test test/interaction test/comment/drama_comments_sheet_test.dart
+```
+
+原始输出（节选）：
+
+```
+Error when reading 'lib/core/data/services/interaction_controller.dart': No such file or directory
+Method not found: 'InteractionController'.
+00:01 +8 -1: Some tests failed.
+```
+
+解读：互动 API 已先通过，缺失的剧集点赞 controller 构成 K3-B 红灯。
+
+### 18.7 K3-B 绿灯
+
+实现 `InteractionController`、替换播放页右栏、去掉本地互动演示层后：
+
+```
+$ flutter test test/interaction test/comment/drama_comments_sheet_test.dart
+00:01 +11: All tests passed!
+```
+
+补齐评论点赞成功/回滚和整机 AuthGate 断言后：
+
+```
+$ flutter test test/comment/comment_controller_test.dart test/widget_test.dart
+00:04 +23: All tests passed!
+```
+
+静态分析：
+
+```
+$ dart analyze lib test
+Analyzing lib, test...
+No issues found!
+```
+
+解读：剧集与评论点赞均使用服务端结果校准；失败会回滚；未登录点剧集赞会打开
+AuthGate 且仓库调用次数为 0。剧集点赞数字未展示，符合契约缺口降级方案。
+
+### 18.8 K3-C 举报红灯
+
+命令：
+
+```
+$ cd /Users/jianghaifeng/Desktop/ReelShort/ReelShort
+$ flutter test test/interaction/report_dialog_test.dart test/comment/drama_comments_sheet_test.dart test/widget_test.dart
+```
+
+原始输出（节选）：
+
+```
+Error when reading 'lib/pages/interaction/widgets/report_dialog.dart': No such file or directory
+Found 0 widgets with key [<'comment-menu-10'>]
+Found 0 widgets with key [<'detail-more'>]
+00:05 +21 -5: Some tests failed.
+```
+
+解读：举报弹窗、评论更多菜单和详情页更多菜单均尚未实现，红灯符合 K3-C 范围。
+
+### 18.9 K3-C 绿灯
+
+实现固定五项 `SPAM/ABUSE/PORN/AD/OTHER` 单选、可选描述、评论与短剧举报入口后：
+
+```
+$ flutter test test/interaction/report_dialog_test.dart test/comment/drama_comments_sheet_test.dart test/widget_test.dart
+00:05 +26: All tests passed!
+```
+
+解读：举报原因与描述提交、评论举报成功、重复举报 message 透传、未登录 AuthGate
+和详情页举报短剧均通过。
+
+### 18.10 K3-C 静态分析
+
+首次分析：
+
+```
+info - lib/pages/drama_detail/drama_detail_view.dart:319:42 - use_build_context_synchronously
+info - lib/pages/drama_detail/drama_detail_view.dart:321:26 - use_build_context_synchronously
+info - lib/pages/drama_detail/drama_detail_view.dart:327:26 - use_build_context_synchronously
+3 issues found.
+```
+
+改为 State 自身 `context` + `mounted` 守卫后：
+
+```
+$ dart analyze lib test
+Analyzing lib, test...
+No issues found!
+```
+
+解读：举报实现达到零告警口径。
+
+### 18.11 K3-D 分享回归
+
+命令：
+
+```
+$ cd /Users/jianghaifeng/Desktop/ReelShort/ReelShort
+$ flutter test test/core/platform_share_service_test.dart test/formatting/localized_content_test.dart test/widget_test.dart
+```
+
+原始输出：
+
+```
+00:05 +25: All tests passed!
+```
+
+解读：系统分享文本保持“标题 → 简介 → footer”顺序；en/zh/id 三语均生成
+非空标题、简介和 `FruitShorts` footer；播放页分享入口回归通过。
+
+### 18.12 代码规模红线修正
+
+提交前检查命令：
+
+```
+$ wc -l lib/pages/player/widgets/drama_comments_sheet.dart
+535 lib/pages/player/widgets/drama_comments_sheet.dart
+```
+
+解读：主弹窗超过单文件 500 行红线。将评论条目与交互回调拆到
+`comment_tile.dart` 后：
+
+```
+$ wc -l lib/pages/player/widgets/drama_comments_sheet.dart lib/pages/player/widgets/comment_tile.dart
+396 lib/pages/player/widgets/drama_comments_sheet.dart
+149 lib/pages/player/widgets/comment_tile.dart
+```
+
+拆分后复跑互动定向测试：
+
+```
+00:06 +51: All tests passed!
+```
+
+解读：行为未回归，两个文件均低于 500 行。
+
+### 18.13 最终门禁
+
+```
+$ dart analyze lib test
+Analyzing lib, test...
+No issues found!
+
+$ flutter test
+00:11 +241 ~1: All tests passed!
+
+$ flutter build apk --debug
+Running Gradle task 'assembleDebug'...                              6.8s
+✓ Built build/app/outputs/flutter-apk/app-debug.apk
+```
+
+解读：唯一跳过项是既有 live watch 用例，因客户端接口服务未启动而按测试机制跳过。
+真机/设备侧集成、截图、设备日志仍未执行。
+
+### 18.14 Git 合并与推送
+
+ReelShort 功能提交：
+
+```
+d361034226ec2bc431548d45068dc60046e5e473
+author: Zhou Weidong <502333560@qq.com>
+committer: Zhou Weidong <502333560@qq.com>
+subject: feat(flutter): 接入互动评论点赞举报
+```
+
+`--no-ff` 合并提交：
+
+```
+9db6935308e65342be46c81419c2992ed2df1df0
+author: Zhou Weidong <502333560@qq.com>
+committer: Zhou Weidong <502333560@qq.com>
+subject: merge: 合并 K3 客户端互动能力
+```
+
+推送：
+
+```
+To http://git.reelshort2.com/jianghaifeng/ReelShort.git
+   45f5f25..9db6935  develop -> develop
+```
+
+解读：K3 已合并到 ReelShort `develop` 并推送，未操作 `main`。