docs(plans): 合并 K3 互动任务回执

This commit is contained in:
Zhou Weidong committed 2026-10-17 15:27:53 +08:00
commit 22f458606d
3 files changed
+493 -1

No files matched your search

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