fix(content): 短剧保存时始终同步分集价格

Co-authored-by: Cursor <cursoragent@cursor.com>

.env.example

@@ -30,6 +30,11 @@ MEDIA_ROOT_DIR=/data/uploads
 #   false = 两个都关闭（生产若不希望暴露 UI 就设 false，机器可读契约也一并关闭）
 SWAGGER_ENABLED=true
 
+# ── 监控 ───────────────────────────────────────────────
+# Grafana 管理员密码（必填）：3000 端口对外开放，不允许用默认 admin/admin
+GRAFANA_ADMIN_USER=admin
+GRAFANA_ADMIN_PASSWORD=
+
 # ── 可选：Google Play 商店票据校验（不配则保持 disabled）──
 STORE_VERIFIER=disabled
 GOOGLE_PLAY_PACKAGE_NAME=

blackbox/blackbox.yml

@@ -0,0 +1,11 @@
+# Author: fruit.com.cn
+# blackbox-exporter 探针模块：只探测 HTTP 2xx，跟随重定向
+modules:
+  http_2xx:
+    prober: http
+    timeout: 5s
+    http:
+      preferred_ip_protocol: ip4
+      valid_http_versions: ["HTTP/1.1", "HTTP/2.0"]
+      valid_status_codes: [200]
+      follow_redirects: true

docker-compose.yml

@@ -99,10 +99,16 @@ services:
     env_file: .env
     environment:
       SERVER_PORT: "8080"
+      SPRING_SERVLET_MULTIPART_MAX_FILE_SIZE: "2GB"
+      SPRING_SERVLET_MULTIPART_MAX_REQUEST_SIZE: "2GB"
+      CORS_ALLOWED_ORIGINS: "http://localhost:3005,http://127.0.0.1:3005,http://39.162.50.99:3005,http://192.168.31.250:3005"
       DB_URL: ${DB_URL:-jdbc:postgresql://db:5432/${DB_NAME:-fruitshorts}}
+      # 管理端仅内网，页面上直接播放/下载裸媒资地址（不签播放签名），
+      # 因此这里不启用 /files/episode/** 的签名校验；公开的 app-api 仍保持开启。
+      FRUITSHORTS_MEDIA_PROTECTED_PREFIXES: ""
     ports:
-      # docs/12-上线检查清单「管理端仅内网」：只绑本机，公网不直接暴露
-      - "127.0.0.1:8080:8080"
+      # docs/12-上线检查清单「管理端仅内网」：只对局域网开放；不在路由器做端口转发，公网访问不到
+      - "8080:8080"
     volumes:
       - ./data/uploads:/data/uploads
     depends_on:
@@ -142,7 +148,71 @@ services:
       start_period: 40s
       retries: 3
 
+  # ─────────── 监控 ───────────
+  # 编排统一在这里：prometheus（应用指标 + 容器指标 + 黑盒探活）+ grafana（自动加载看板）
+  prometheus:
+    image: prom/prometheus:latest
+    container_name: fruitshorts-prometheus
+    restart: unless-stopped
+    ports:
+      - "9090:9090"
+    volumes:
+      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
+      - prometheus-data:/prometheus
+    command:
+      - "--config.file=/etc/prometheus/prometheus.yml"
+      # 15 天保留期，避免磁盘无限增长
+      - "--storage.tsdb.retention.time=15d"
+      - "--web.enable-lifecycle"
+    healthcheck:
+      test: ["CMD-SHELL", "wget -qO- http://127.0.0.1:9090/-/healthy >/dev/null || exit 1"]
+      interval: 30s
+      timeout: 5s
+      start_period: 20s
+      retries: 3
+
+  grafana:
+    image: grafana/grafana:latest
+    container_name: fruitshorts-grafana
+    restart: unless-stopped
+    ports:
+      - "3000:3000"
+    volumes:
+      - grafana-data:/var/lib/grafana
+      # 数据源与看板全部来自仓库，换机器不需要手工配
+      - ./grafana/provisioning:/etc/grafana/provisioning:ro
+      - ./grafana/dashboards:/var/lib/grafana/dashboards:ro
+    environment:
+      GF_SECURITY_ADMIN_USER: ${GRAFANA_ADMIN_USER:-admin}
+      GF_SECURITY_ADMIN_PASSWORD: ${GRAFANA_ADMIN_PASSWORD:?Grafana 管理员密码必填，见 .env.example}
+      GF_USERS_ALLOW_SIGN_UP: "false"
+      TZ: Asia/Shanghai
+    depends_on:
+      - prometheus
+
+  # 黑盒探活：从外部探测接口可用性与耗时
+  blackbox:
+    image: prom/blackbox-exporter:latest
+    container_name: fruitshorts-blackbox
+    restart: unless-stopped
+    volumes:
+      - ./blackbox/blackbox.yml:/etc/blackbox_exporter/config.yml:ro
+
+  # 容器资源指标（CPU / 内存 / 网络 / 重启），供 Prometheus 抓取
+  cadvisor:
+    image: gcr.io/cadvisor/cadvisor:latest
+    container_name: fruitshorts-cadvisor
+    restart: unless-stopped
+    privileged: true
+    volumes:
+      - /:/rootfs:ro
+      - /var/run:/var/run:ro
+      - /sys:/sys:ro
+      - /var/lib/docker/:/var/lib/docker:ro
+
 volumes:
   # 命名卷：跟着 compose 项目走，`docker compose down -v` 才会删
   db-data:
   redis-data:
+  prometheus-data:
+  grafana-data:

docs/api-phase1.md

@@ -113,10 +113,24 @@ POST /app/auth/register
 | `targetType=PHONE` | 维持原状：`code` **必填** |
 | 邮箱规范化 | 去空格 + 转小写（`batch1@Example.com ` → `batch1@example.com`）；格式不合法直接 `400 邮箱格式不正确` |
 | 密码强度 | 8–64 位，且**同时包含字母与数字**（不强制特殊字符：低端机输入成本高，拦机器注册靠频控） |
-| 注册频控 | 同 IP 24h ≤ **5** 个、同设备 24h ≤ **3** 个，超出返回 `429`（`TOO_MANY_REQUESTS`） |
+| 注册频控 | 同 IP / 同设备 24h 默认上限分别为 5 / 3 个，超出返回 `429`（`TOO_MANY_REQUESTS`） |
 | 邮箱验证状态 | 免码注册时 `app_user_credential.verified = 0`（保留"待验证"），**不阻塞登录**；只有**验证码登录**会把 `verified` 置 1，密码登录不改变该状态 |
 
-频控口径落库在 `app_user.register_ip` / `register_device_id` 上（按 24h 计数，不新建计数表）。
+频控口径落库在 `app_user.register_ip` / `app_user.register_device_id` 上（按 24h 计数，不新建计数表）。
+
+注册频控阈值存储在 `sys_config`，可在后台「系统配置」修改：
+
+```text
+app.register.max-per-ip-per-day
+app.register.max-per-device-per-day
+```
+
+运行时优先读取 `sys_config`。键缺失或值不是整数时，回退 `application.yml`
+中的 `fruitshorts.auth.register-max-per-ip-per-day` /
+`fruitshorts.auth.register-max-per-device-per-day`，缺省为 5 / 3；
+值小于等于 0 表示对应维度不限制。
+开发种子配置为 0 / 0，生产建议恢复为 5 / 3。
+
 **残留风险**：IP 取自 `X-Forwarded-For`、设备号由客户端上报，都能伪造，只能挡脚本批量；
 真要防住需要接图形/行为验证码或风控服务，本阶段未做。验证码通道目前是 `LogOtpSender`（只写日志不发信），
 所以邮箱**可达性**未验证 —— 这也是"不阻塞注册"的前提。
@@ -151,10 +165,88 @@ POST /app/auth/register
 
 | 方法 | 路径 | 说明 |
 | --- | --- | --- |
-| GET | `/app/home/feed` | 首页：轮播 + 分区，卡片带 `preview` 可播预览集 |
+| GET | `/app/home/feed` | 首页：轮播 + 分区，卡片带 `preview` 可播预览集与 `language` 语种 |
 | GET | `/app/discover/feed` | 发现页分区 |
+| GET | `/app/feed?types=ANIME,LIVE&categoryId=7&cursor=&size=20` | 推荐流；支持内容类型与分类叠加过滤，游标翻页 |
 | GET | `/app/categories` | 分类列表 |
 | GET | `/app/dramas/{id}` | 详情（含剧集列表，免费集带**已签名**播放地址） |
+| GET | `/app/search?keyword=&pageIndex=&pageSize=` | 搜索已上线短剧：按标题/简介模糊匹配，分页返回卡片列表 |
+
+> 卡片（`AppDramaCardVO`）统一新增 `language` 字段（取值如 `zh-CN` / `id`），
+> 首页、发现页、分类、收藏、搜索等所有下发卡片的场景都带该字段，客户端可据此做语言筛选。
+>
+> 卡片同时下发 `likeCount` / `favoriteCount` / `commentCount`（均为 JSON 字符串）。
+> `favoriteCount` 取整部剧；`likeCount` / `commentCount` 取卡片 `preview` 当前集的
+> `drama_episode.like_count` 与 `content_comment.episode_id` 统计（排除逻辑删除与 `status = 'deleted'`）；
+> `viewCount` 热度仍取整部剧。首页、发现、分类、收藏、搜索等列表卡片结构一致。
+>
+> 卡片新增 `dramaType`：`ANIME` 表示漫剧，`LIVE` 表示真人剧。
+> 客户端字段仍返回主内容类型；后台多选值保存在 `drama.drama_types`，
+> App 类型筛选按逗号列整词匹配，因此 `ANIME,LIVE` 多标签剧可被任一类型命中。
+
+#### 推荐类型流（`GET /app/feed`）
+
+- `types` 可选，逗号分隔，支持 `ANIME`、`LIVE` 或多选 `ANIME,LIVE`；不传或空值返回全部已上线内容。
+  过滤按 `drama_types` 整词匹配，多标签剧可被多个类型同时命中。
+- `categoryId` 可选；不传返回全部分类。传入后按 `category_ids` 整词匹配，
+  可与 `types` 叠加，只返回同时命中内容类型和分类的已上线短剧。
+- `cursor` 可选，上一页返回的 `nextCursor`；`size` 默认 20，最大 50。
+  游标短剧必须同时满足已上线、内容类型命中和分类命中，否则返回空列表。
+- 排序：`recommend_weight DESC NULLS LAST, view_count DESC, id DESC`。
+- 返回 `Result<CursorResult<AppDramaCardVO>>`，卡片字段与首页一致，包含互动计数、`preview`、`language`、`dramaType`。
+
+#### 短剧详情响应（`GET /app/dramas/{id}`）
+
+```json
+{
+  "code": 0, "message": "ok",
+  "data": {
+    "id": "5",
+    "title": "命运的相遇",
+    "synopsis": "一次意外的相遇，让两个世界的人走到一起。",
+    "cover": "/files/drama/202610/cover.jpg",
+    "genre": "都市 · 情感",
+    "category": "都市",
+    "totalEpisodes": 80,
+    "freeEpisodes": 10,
+    "unlockCoin": 30,
+    "isHot": true,
+    "viewCount": "12400",
+    "likeCount": "3200",
+    "favoriteCount": "1800",
+    "commentCount": "96",
+    "episodes": [
+      {
+        "id": "2111012753262120962",
+        "number": 1,
+        "title": "第 1 集",
+        "duration": "03:00",
+        "durationSec": 180,
+        "isFree": true,
+        "locked": false,
+        "unlockCoin": 0,
+        "likeCount": "45",
+        "commentCount": "8",
+        "playUrl": "/files/episode/202610/xxx.mp4?e=1760000000&s=9f2c..."
+      }
+    ]
+  }
+}
+```
+
+详情里的互动数量：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `likeCount` | Long（JSON 字符串） | 剧级历史汇总，保留兼容；新客户端按集使用 `episodes[].likeCount` |
+| `favoriteCount` | Long（JSON 字符串） | 取 `drama.favorite_count`，短剧累计收藏数 |
+| `commentCount` | Long（JSON 字符串） | `content_comment` 中该剧未删除评论数：按 `drama_id` 统计，排除 `status = 'deleted'` 与逻辑删除记录 |
+| `viewCount` | Long（JSON 字符串） | 取 `drama.view_count`，累计播放量，既有字段语义不变 |
+| `episodes[].likeCount` | Long（JSON 字符串） | 本集点赞数，取 `drama_episode.like_count` |
+| `episodes[].commentCount` | Long（JSON 字符串） | 本集未删除评论数，按 `episode_id` 统计 |
+
+计数是只读快照：互动操作完成后客户端重新拉取详情即可刷新；`Long` 字段一律按字符串下发，
+客户端需要转成数字再展示（与 `viewCount` 相同）。
 
 ### 1.4 播放（已实现，链路已重做）
 
@@ -172,7 +264,9 @@ POST /app/auth/register
     "playUrl": "/files/episode/202610/xxx.mp4?e=1760000000&s=9f2c...",
     "qualities": ["AUTO"],
     "unlockCoin": 0,
-    "previewSeconds": 0
+    "previewSeconds": 0,
+    "likeCount": "45",
+    "commentCount": "8"
   }
 }
 ```
@@ -226,8 +320,9 @@ POST /app/auth/register
 | --- | --- | --- | --- |
 | POST | `/app/comments` | 登录 | 发表评论/回复：过敏感词后按策略发布或转待审 |
 | GET | `/app/comments?dramaId=&cursor=&size=` | 匿名 | 游标翻页；不传 `rootId` 返回顶层评论，传了返回该楼层回复 |
+| GET | `/app/comments/count?dramaId=&episodeId=` | 匿名 | 传 `episodeId` 返回该集评论数；仅传 `dramaId` 返回全剧兼容汇总 |
 | DELETE | `/app/comments/{id}` | 登录 | 删除自己的评论（逻辑置为 `deleted`） |
-| POST | `/app/likes/toggle` | 登录 | 点赞/取消点赞，`targetType` 支持 `DRAMA` / `COMMENT` |
+| POST | `/app/likes/toggle` | 登录 | 点赞/取消点赞，`targetType` 支持 `DRAMA` / `EPISODE` / `COMMENT`；新客户端点赞按集 |
 | POST | `/app/reports` | 登录 | 举报评论/用户/短剧；同一目标只保留一条待处理工单 |
 
 **敏感词三档处置**：`BLOCK` 直接拒绝并返回原因、`REPLACE` 替换后放行、`REVIEW` 转人工待审。
@@ -243,9 +338,17 @@ POST /app/auth/register
 | --- | --- | --- |
 | GET | `/app/wallet` | 金币余额 + 最近流水 |
 | POST | `/app/episodes/{id}/unlock` | 金币解锁分集；幂等键 `unlock:{userId}:{episodeId}`，重复调用不重复扣币 |
+| GET | `/app/products` | 充值商品列表（只返回上架商品，`type` 可选 `COIN_PACK`/`VIP`） |
+| POST | `/app/orders` | 创建充值订单（`body` 传 `productId`，返回 `CREATED` 订单，等待支付） |
 | GET | `/app/orders` | 我的订单 |
 | POST | `/app/orders/verify` | 提交 Google Play 票据：服务端校验 → 建单 → 发权益（详见下方说明） |
 
+> `GET /app/products` 只返回 `status=1`（上架）的商品，按 `sort` 升序、`id` 降序。
+> `POST /app/orders` 请求体 `{ "productId": 123 }`，商品下架时返回 `400 商品已下架`；
+> 订单 `coinAmount = coinAmount + bonusCoin`（与商店票据口径一致），状态为 `CREATED`。
+> VIP 商品下单后交付时发放 `TYPE_VIP` 权益（`dramaId=0`、`episodeId=0`，永久有效），
+> 播放/下载的权益判定在 `EntitlementPort` 中增加「存在有效 VIP 权益即放行」的判定。
+
 解锁后播放入口与下载入口会同时放行 —— 权益判定由交易模块的 `EntitlementPort` 实现提供，
 播放域与下载域都不需要改代码。金币变动一律带幂等键并写 `coin_ledger`，钱包余额与流水同事务。
 
@@ -430,10 +533,10 @@ GET /app/notices?pageIndex=1&pageSize=20
 
 | 方法 | 路径 | 权限点 | 说明 |
 | --- | --- | --- | --- |
-| GET | `/admin/dramas/page` | `drama:list` | 检索（含热门、状态筛选） |
+| GET | `/admin/dramas/page` | `drama:list` | 检索（含热门、状态、`dramaTypes[]`、`categoryIds[]` 多选筛选） |
 | GET | `/admin/dramas/{id}` | `drama:list` | 详情 |
-| POST | `/admin/dramas` | `drama:create` | 新建短剧 |
-| PUT | `/admin/dramas/{id}` | `drama:update` | 编辑短剧 |
+| POST | `/admin/dramas` | `drama:create` | 新建短剧；优先接收 `dramaTypes[]` / `categoryIds[]` |
+| PUT | `/admin/dramas/{id}` | `drama:update` | 编辑短剧；优先接收 `dramaTypes[]` / `categoryIds[]` |
 | DELETE | `/admin/dramas/{id}` | `drama:delete` | 删除短剧 |
 | POST | `/admin/dramas/{id}/submit` | `drama:review` / `drama:update` | 提交审核 |
 | POST | `/admin/dramas/{id}/approve` | `drama:review` | 审核通过 |
@@ -442,6 +545,15 @@ GET /app/notices?pageIndex=1&pageSize=20
 | POST | `/admin/dramas/{id}/offline` | `drama:review` | 下线 |
 | GET | `/admin/dramas/{id}/review-records` | `drama:list` | 审核记录 |
 
+多选字段说明：
+
+- 保存优先使用 `dramaTypes[]` / `categoryIds[]`，去重并保持提交顺序；
+  `drama_type` / `category_id` 写第一个值，供旧客户端与旧接口兼容。
+- 仅传 `dramaType` / `categoryId` 时保持原单值行为。
+- 列表响应返回 `dramaTypes[]`、`categoryIds[]` 与按选中顺序映射的 `categoryNames[]`；
+  分类名缺失时回退 `genre`。
+- 后台与 App 过滤均使用 `(',' || column || ',') LIKE '%,value,%'` 整词匹配。
+
 **剧集**
 
 | 方法 | 路径 | 权限点 | 说明 |
@@ -493,6 +605,7 @@ GET /app/notices?pageIndex=1&pageSize=20
 | GET | `/admin/app-users/{id}` | `app-user:list` | 详情 |
 | GET | `/admin/app-users/{id}/ban-records` | `app-user:list` | 封禁与申诉记录 |
 | GET | `/admin/app-users/{id}/watch-history` | `app-user:list` | 观看流水明细（带剧名/集号，客服核对用） |
+| GET | `/admin/watch-history/page` | `watch-history:list` | 跨用户观看记录分页：keyword、userId、dramaTitle、dramaId、episodeId、source、finished、startTime、endTime |
 | PUT | `/admin/app-users/{id}/status` | `app-user:update` | 改状态：normal/limited/banned |
 
 状态处置会**立即吊销该用户全部会话**并写入封禁记录，避免"封了还能用"。
@@ -510,15 +623,18 @@ GET /app/notices?pageIndex=1&pageSize=20
 
 | 方法 | 路径 | 权限点 | 说明 |
 | --- | --- | --- | --- |
-| GET | `/admin/comments/page` | `comment:list` | 检索评论，`status=pending` 即审核队列 |
+| GET | `/admin/comments/page` | `comment:list` | 检索评论；`status` 为空返回全部，`pending` 即审核队列 |
 | GET | `/admin/comments/{id}/audit-records` | `comment:list` | 审核留证：机审与人审的完整链路 |
 | PUT | `/admin/comments/{id}/audit` | `comment:audit` | 通过 / 驳回（带原因码与说明） |
 | DELETE | `/admin/comments/{id}` | `comment:audit` | 删除评论 |
-| GET | `/admin/reports/page` | `report:list` | 举报工单检索（状态 / 类型 / 原因） |
+| GET | `/admin/reports/page` | `report:list` | 举报工单检索（状态 / 类型 / 原因），返回举报人、剧名、集号、集标题与目标摘要 |
 | PUT | `/admin/reports/{id}/handle` | `report:handle` | 处理工单；结论成立会联动驳回被举报评论，可选择同时封禁被举报用户 |
 | GET | `/admin/sensitive-words/page` | `sensitive-word:list` | 敏感词检索 |
 | POST/PUT/DELETE | `/admin/sensitive-words[/{id}]` | `sensitive-word:update` | 维护词库，改动即时生效（服务端缓存失效重建） |
 
+后台评论行除 `dramaId/episodeId` 外，还返回 `dramaTitle/episodeNo/episodeTitle`；
+剧或集已删除时对应展示字段留空。后台评论与举报的 `status` 空值均表示全部状态。
+
 ### 2.6 订单与权益（已实现）
 
 | 方法 | 路径 | 权限点 | 说明 |

docs/plans/2026-10-17-K10.md

@@ -0,0 +1,90 @@
+# 2026-10-17 K10 统一空列表占位（EmptyState）
+
+## 一、目标与边界
+
+新建统一 `EmptyState` 组件，替换任务书列出的 10 处纯文字空态，保留现有空态
+文案、按钮行为和错误态逻辑。只改空态视觉、三语 l10n 与测试，不改数据、接口、
+列表加载/失败逻辑或页面信息架构。
+
+- 客户端分支：`feature/flutter-k10-empty-states`，基线 `develop 19babb8`。
+- 文档分支：`docs/k10-empty-states`，FruitServer 基线 K10 任务书 `3f84bc6`。
+- 不引入图片、SVG、字体或第三方依赖。
+- 不跑真机，设备侧深色/浅色、小屏和页面状态由用户验收。
+
+## 二、组件设计
+
+`lib/core/widgets/empty_state.dart`：
+
+1. 默认居中，最大宽度 280，外层 Padding 24。
+2. 默认图形 96x96、圆角 28，背景 `AppColors.blue` 透明度 0.11；图标 42。
+3. 深色图标色 `AppColors.blueSoft`，浅色图标色 `AppColors.blue`。
+4. compact 图形 64x64、圆角 18、图标 28，用于评论弹窗。
+5. 标题 16/w600（compact 14）、最多 2 行；可选副标题 13、`muted`、最多 2 行。
+6. 可选主色 TextButton，最小点击区域 44x44；保留调用方动作。
+7. 外层 `Semantics(label: title)`；图形、标题和副标题文本使用
+   `ExcludeSemantics`，避免重复朗读，操作按钮仍保持可访问。
+8. 稳定 Key：`empty-state-art`、`empty-state-icon`、`empty-state-title`、
+   `empty-state-action`。
+
+新增通用副标题 `emptyHint`：
+
+- zh：有新内容时会显示在这里。
+- en：New content will appear here.
+- id：Konten baru akan muncul di sini.
+
+## 三、10 处替换与图标
+
+| 位置 | 图标 | 行为 |
+|---|---|---|
+| 首页 noStories | `movie_outlined` | 保留重试 |
+| 首页分类空 | `grid_view_rounded` | 无新增动作 |
+| 首页搜索空 | `search_off_rounded` | 无新增动作 |
+| 收藏 noFavorites | `favorite_border_rounded` | 原按钮不变 |
+| 通知 noNotices | `notifications_none_rounded` | 原下拉刷新不变 |
+| 详情 noEpisodesYet | `video_library_outlined` | 保留重试 |
+| 我的-片单 noSavedShows | `bookmark_border_rounded` | 无新增动作 |
+| 我的-最近剧目 noStories | `history_rounded` | 无新增动作 |
+| 下载 noDownloads | `download_outlined` | 原清空按钮不变 |
+| 观看记录 noWatchRecords | `history_rounded` | 原清空/刷新逻辑不变 |
+| 评论 noComments | `chat_bubble_outline_rounded` | compact |
+
+首页错误态继续使用 `error_outline_rounded` 和 `catalogError`；分类、收藏、通知、
+记录、评论等失败态继续使用原错误图标/重试，不允许用 `EmptyState` 冒充失败。
+
+## 四、影响文件
+
+- `lib/core/widgets/empty_state.dart`（新增）
+- `lib/pages/home/home_view.dart`
+- `lib/pages/discover/widgets/home_drama_grid.dart`
+- `lib/pages/favorites/favorites_page.dart`
+- `lib/pages/notices/notices_page.dart`
+- `lib/pages/drama_detail/drama_detail_view.dart`
+- `lib/pages/mine/mine_view.dart`
+- `lib/pages/downloads/downloads_page.dart`
+- `lib/pages/watch_records/watch_records_page.dart`
+- `lib/pages/player/widgets/drama_comments_sheet.dart`
+- `lib/l10n/app_en.arb`、`app_zh.arb`、`app_id.arb` 与生成文件
+- 组件测试及收藏/下载/记录/通知/评论页面空态测试
+- `FruitServer/docs/plans/2026-10-17-K10.md`
+- `FruitServer/docs/plans/PROGRESS.md`
+- `FruitServer/docs/plans/INBOX.md`
+
+## 五、TDD 与门禁
+
+1. 先新增 `EmptyState` 组件测试和五处页面空态测试，确认组件不存在时红灯。
+2. 实现组件并替换 10 处空态后跑定向测试绿灯。
+3. 运行 `dart analyze lib test`、`flutter test`、`flutter build apk --debug`。
+4. 构建前检查并发 `flutter run/build`；当前有用户 iOS `flutter run` 会话，
+   不主动终止，若仍未结束则等待其退出后再构建。
+5. 完成后 `merge --no-ff` 回客户端 `develop` 并 push；FruitServer 文档同样
+   合并推送。作者与提交者统一为
+   `Zhou Weidong <502333560@qq.com>`。
+
+## 六、风险与待确认
+
+- 首页当前把 `catalog.error` 与空列表放在同一分支，需先拆出错误态，再单独用
+  `EmptyState` 渲染 noStories，避免错误态被误认为空态。
+- 部分空态位于 Sliver、固定高度滚动区或弹窗内，需保持可滚动和居中。
+- 组件外层统一读标题，若操作按钮位于同一 Semantics 容器内，必须确保按钮自身
+  语义未被 `ExcludeSemantics` 吞掉。
+- 最大宽度 280 与 compact 64 图标容器需在 320px 宽度和浅/深色主题下无溢出。

docs/plans/2026-10-17-K11.md

@@ -0,0 +1,63 @@
+# 2026-10-17 K11 首页网格 3 列 + 分类首位「全部」
+
+## 一、目标与边界
+
+在 K9 首页「全部剧目」网格上做最小修订：每行从 2 个改为 3 个，分类首个仍绑定
+`CategoryController.allCode`，文案改为「全部 / All / Semua」。
+
+- 客户端分支：`feature/flutter-k11-home-grid-3col`，基线 `develop 0466b4b`。
+- 文档分支：`docs/k11-home-grid-3col`，FruitServer 基线任务书 `2a06190`。
+- 不改轮播、空态、三态、数据源、接口、分页或其他页面。
+- 不跑真机；设备侧 3 列布局、分类切换和详情跳转由用户验收。
+
+## 二、实现方案
+
+1. `home_drama_grid.dart`：
+   - `crossAxisCount: 3`
+   - `mainAxisSpacing: 14`
+   - `crossAxisSpacing: 10`
+   - `childAspectRatio: 2 / 3` 不变
+2. 3 列下卡片仍只保留标题最多 2 行、类型最多 1 行；由现有 `Text` 的
+   `maxLines` / `ellipsis` 保证不溢出。
+3. `discover_view.dart` 分类第一项 code 保持 `CategoryController.allCode`，
+   label 从 `l10n.forYou` 改为 `l10n.all`。
+4. 已核对三份 ARB 已存在 `all` key：
+   - en：All
+   - zh：全部
+   - id：Semua
+
+因此直接复用现有 l10n，不重复插入 JSON key；热门、最新和服务端分类顺序不变。
+
+## 三、测试
+
+- 更新 K9 网格断言：`crossAxisCount == 3`、`crossAxisSpacing == 10`、
+  `mainAxisSpacing == 14`、比例仍为 2/3。
+- 新增首个分类 chip 文案断言为 `All`；切换分类时仍能更新网格。
+- K9/K10 既有测试保留，不删除用例；只更新本次行为明确变化的参数断言。
+- 组件/页面空态测试保持通过。
+
+## 四、影响文件
+
+- `ReelShort/lib/pages/discover/widgets/home_drama_grid.dart`
+- `ReelShort/lib/pages/discover/discover_view.dart`
+- `ReelShort/test/discover/home_all_dramas_grid_test.dart`
+- `FruitServer/docs/plans/2026-10-17-K11.md`
+- `FruitServer/docs/plans/PROGRESS.md`
+- `FruitServer/docs/plans/INBOX.md`
+
+## 五、门禁与 Git
+
+1. 先更新测试取得与 3 列/全部文案相关的红灯。
+2. 实现后运行定向测试。
+3. 运行 `dart analyze lib test`、`flutter test`、`flutter build apk --debug`。
+4. 当前有 Android `flutter run` 会话，不主动终止；构建前检查进程，必要时使用
+   独立工作区副本构建，避免争用原项目 `build/`。
+5. 完成后 `merge --no-ff` 回客户端 `develop` 并 push；FruitServer 文档同样
+   合并推送。作者与提交者统一为
+   `Zhou Weidong <502333560@qq.com>`。
+
+## 六、风险与待确认
+
+- 3 列后单卡宽度变窄，长标题和类型必须继续 ellipsis，不允许改变卡片结构。
+- 现有 `all` l10n 已具备三语，新增重复 key 会破坏 ARB；本批复用现有 key。
+- 用户正在运行的 Flutter `run` 不终止；APK 构建需隔离原 `build/`。

docs/plans/2026-10-17-K12.md

@@ -0,0 +1,79 @@
+# 2026-10-17 K12 首页去标题 + 空态视觉重做
+
+## 一、目标与边界
+
+在 K11 首页基础上做两项视觉修订：
+
+1. 删除首页「全部剧目」标题，分类 chips 后直接显示网格。
+2. 将 `EmptyState` 从单个实心圆角块改为轻盈的双层同心圆。
+
+只改首页间距、`EmptyState` 视觉与对应测试，不改接口、数据、轮播、三态或其他页面。
+
+- 客户端分支：`feature/flutter-k12-home-empty-polish`，基线 `develop b5a8656`。
+- 文档分支：`docs/k12-home-empty-polish`，FruitServer 基线任务书 `87a37e9`。
+- 不引入图片、SVG、字体或动画；不跑真机。
+
+## 二、首页去标题
+
+- 删除 `Key('home-all-dramas-title')` 的 Text。
+- 删除标题与 chips 之间、标题与网格之间的多余间距。
+- chips 与网格间距调整为 14px。
+- 网格、数据、空态和分类切换逻辑保持不变。
+
+## 三、EmptyState 双层同心圆
+
+默认：
+
+- 外层直径 84，blue 5.5% 填充，1px blue 11% 描边。
+- 内层直径 56，blue 11% 填充。
+- 图标 27px，深色 `blueSoft` / 浅色 `blue`。
+- 标题 15/w600，与图形间距 14。
+- 副标题 12.5 muted，行高 1.45，与标题间距 6。
+- TextButton 13 主色，点击区至少 44，与副标题间距 8。
+- 上下 Padding 28，最大宽度 260。
+
+compact：
+
+- 外层 60、内层 40、图标 21。
+- 图形与标题间距 10，上下 Padding 16。
+
+保留外层 Key `empty-state-art`，新增内层 Key `empty-state-art-inner`；继续使用
+`empty-state-icon/title/action`。外层 Semantics 仍只读标题。
+
+## 四、测试
+
+- 更新组件测试：外/内层尺寸、图标尺寸、标题 15、副标题 12.5、按钮 44、
+  最大宽 260、compact 尺寸与深浅主题颜色。
+- 首页测试：`home-all-dramas-title` 不存在；chips 存在后直接能找到
+  `home-all-dramas-grid`。
+- K9/K10/K11 既有用例保留，不删除测试文件；只更新本次明确变化的视觉/锚点断言。
+- 既有壳层测试中若用「All Dramas」作为页面定位锚点，改用当前稳定锚点
+  `All` chip，不降低导航流程覆盖。
+
+## 五、影响文件
+
+- `ReelShort/lib/core/widgets/empty_state.dart`
+- `ReelShort/lib/pages/discover/discover_view.dart`
+- `ReelShort/test/empty_state/empty_state_test.dart`
+- `ReelShort/test/discover/home_all_dramas_grid_test.dart`
+- `ReelShort/test/widget_test.dart`（仅稳定锚点更新）
+- `FruitServer/docs/plans/2026-10-17-K12.md`
+- `FruitServer/docs/plans/PROGRESS.md`
+- `FruitServer/docs/plans/INBOX.md`
+
+## 六、门禁与 Git
+
+1. 先更新组件与首页测试，取得标题仍存在、空态仍是旧尺寸的红灯。
+2. 实现后跑定向测试。
+3. 运行 `dart analyze lib test`、`flutter test`、`flutter build apk --debug`。
+4. 当前已确认真机会话停止且无并发构建；构建前再次检查。
+5. 完成后 `merge --no-ff` 回客户端 `develop` 并 push；FruitServer 文档同样
+   合并推送。作者与提交者统一为
+   `Zhou Weidong <502333560@qq.com>`。
+
+## 七、风险与待确认
+
+- 删除标题后，部分既有测试用「All Dramas」文本定位页面；需改为稳定的
+  `All` chip 或网格 Key，保持原测试流程。
+- 双层圆使用固定尺寸和 Stack，小屏需保证 84/60 不溢出。
+- 副标题 12.5 与按钮 13 是视觉规格；测试按 double 精确断言。

docs/plans/2026-10-17-K13.md

@@ -0,0 +1,121 @@
+# 2026-10-17 K13 运行时服务器地址设置（仅 debug）
+
+## 一、目标与边界
+
+解决 debug APK 不带 `--dart-define` 时固定回退到
+`http://jiangdeMacBook-Air.local:8081` 的问题。增加仅 debug 可用的运行时地址
+覆盖，保存后下次启动生效。
+
+优先级：
+
+```text
+SharedPreferencesAsync dev.api_base_url
+  > --dart-define(API_BASE_URL)
+  > AppConfig 现有默认地址
+```
+
+- 客户端分支：`feature/flutter-k13-dev-server-setting`，基线 `b762289`。
+- 文档分支：`docs/k13-dev-server-setting`，FruitServer 基线 `1a5951c`。
+- release 不读取 SharedPreferences 覆盖，也不显示设置入口。
+- 不做环境列表、远程配置、接口或后端改动。
+- 不跑真机。当前有真机 `flutter run` 时，构建使用隔离副本，不终止用户会话。
+
+## 二、运行时解析
+
+新增 `lib/core/config/server_endpoint.dart`：
+
+1. 常量 key：`dev.api_base_url`。
+2. `normalize`：
+   - `trim()`；
+   - 只接受 `http://` 或 `https://`；
+   - `Uri.host` 必须非空；
+   - 去掉末尾所有 `/`。
+3. `resolve`：
+   - 本地值有效时使用本地值；
+   - 否则使用有效 dart-define；
+   - 否则使用现有默认值。
+4. `load({debug, preferences})`：
+   - debug=false 时立即返回，不创建/读取 SharedPreferences；
+   - debug=true 时读取并规范化，合法值写入 `AppConfig` 的运行时覆盖。
+5. `save` 与 `clear`：
+   - save 前规范化，非法值返回 false 且不写；
+   - clear 删除 key。
+
+`AppConfig` 增加运行时覆盖读写入口和编译期/默认地址 getter；`apiBaseUrl` 优先
+返回已加载的运行时值。`main()` 在 `runApp` 前
+`await ServerEndpoint.load(debug: kDebugMode)`，确保 `LumaDramaApp` 创建
+`ApiClient` 前已加载完成。
+
+## 三、Debug 设置入口
+
+`MineLogic.showLanguage` 增加 `showServerSetting` 参数。我的页设置弹窗中在语言
+列表下方增加「服务器地址」行：
+
+- 仅 `MyPage.debugShowSetting == true` 时显示，默认值 `kDebugMode`，测试可注入；
+- 副标题显示当前 `AppConfig.apiBaseUrl`；
+- 点击打开编辑弹窗，预填当前地址；
+- 保存合法地址后关闭编辑弹窗并提示“重启 App 生效”；
+- 非法地址在输入框显示校验错误，不保存；
+- 提供「恢复默认」，清除本地 key，并提示重启生效；
+- release 默认不显示，也不触发本地读取。
+
+新增三语文案：
+
+- `serverAddress`
+- `serverAddressHint`
+- `saveAddress`
+- `restartToApply`
+- `restoreDefault`
+- `invalidServerAddress`
+
+## 四、测试
+
+新增 `test/config/server_endpoint_test.dart`：
+
+- 本地覆盖 > dart-define > 默认；
+- 非法本地值忽略并回落；
+- trim、末尾斜杠、http/https；
+- `ftp://`、无 scheme、空 host 被拒绝；
+- debug=false 不读取覆盖；
+- save/clear 对 SharedPreferencesAsync 的行为。
+
+新增/扩展设置弹窗测试：
+
+- debug 注入 true：显示服务器地址行，可打开编辑弹窗；
+- 注入 false：不显示入口；
+- 非法地址显示错误且不写入。
+
+既有测试只更新必要锚点/新增断言，不删除用例。
+
+## 五、影响文件
+
+- `ReelShort/lib/core/config/server_endpoint.dart`（新增）
+- `ReelShort/lib/core/config/app_config.dart`
+- `ReelShort/lib/main.dart`
+- `ReelShort/lib/pages/mine/mine_view.dart`
+- `ReelShort/lib/pages/mine/mine_logic.dart`
+- `ReelShort/lib/l10n/app_en.arb`、`app_zh.arb`、`app_id.arb` 与生成文件
+- `ReelShort/test/config/server_endpoint_test.dart`（新增）
+- 我的设置弹窗测试
+- `FruitServer/docs/plans/2026-10-17-K13.md`
+- `FruitServer/docs/plans/PROGRESS.md`
+- `FruitServer/docs/plans/INBOX.md`
+
+## 六、门禁与 Git
+
+1. 先写运行时解析与入口可见性测试，确认红灯。
+2. 实现后跑定向测试。
+3. 运行 `dart analyze lib test`、`flutter test`、`flutter build apk --debug`。
+4. 当前真机 run 会话不终止；构建在独立副本中进行，原 `build/` 不受影响。
+5. 完成后 `merge --no-ff` 回客户端 `develop` 并 push；FruitServer 文档同样
+   合并推送。作者与提交者统一为
+   `Zhou Weidong <502333560@qq.com>`。
+
+## 七、风险与待确认
+
+- `AppConfig.apiBaseUrl` 当前是纯 getter；增加运行时静态状态后，测试必须显式
+  清理，避免用例间污染。
+- release 的“完全不读取”由 `ServerEndpoint.load(debug: kDebugMode)` 和主入口
+  的 debug 参数共同保证；测试使用可注入 debug 参数验证。
+- 保存和恢复默认都只在下次启动生效，当前 ApiClient 不在运行中重建。
+- 设置入口只在 debug 显示，不修改发布包的信息架构。

docs/plans/2026-10-17-K16.md

@@ -0,0 +1,40 @@
+# 2026-10-17 K16 注册限流可配置
+
+## 范围
+
+将 C 端注册的 IP/设备 24 小时限流阈值从硬编码改为后台 `sys_config` 配置：
+
+```text
+app.register.max-per-ip-per-day
+app.register.max-per-device-per-day
+```
+
+运行时优先读取后台配置；键缺失或非整数时回退 `@Value` 注入值（默认 5/3）；
+值小于等于 0 时跳过对应 guard。注册接口、错误码和错误文案不变。
+
+## 实现
+
+1. `AppAuthService` 注入 `ConfigService`，从 `sys_config` 优先读取两个键；
+   再用 `@Value` 注入 yml 值作为缺失/非法时的 fallback。
+2. `sql/data-phase1.sql` 幂等写入开发默认 0/0 和说明。
+3. `application.yml` 只声明 fallback（默认 5/3），运行时不以后台固化值为准。
+4. `docs/api-phase1.md` §1.1 补充后台配置键、缺省/非法回退和 0=不限制口径。
+5. 测试 mock `ConfigService`，覆盖自定义、0、缺省/非数字回退。
+6. 确认后台「系统设置」页面可访问 `/admin/configs`；若现有表单未展示新键，
+   记录为待后续 Web 表单补充，不把配置固化回 yml。
+
+## 验证与交付
+
+- `mvn test`
+- `mvn -pl fruitshorts-app-api -am package -DskipTests`
+- 停止当前 8081 服务，启动新 jar，`/healthz` 通过
+- 使用新设备号连续注册至少 4 次，确认不再 429（接口自检）
+- 后台把 IP 上限临时改为 2：前两次成功，第三次返回 429；恢复 0 后继续注册成功
+- `feature/backend-register-rate-config-fix` 以 `--no-ff` 合并回 `develop` 并 push
+- PROGRESS 记录命令、原始输出和解读
+
+## 风险
+
+- 配置 0 会关闭注册滥用保护，仅用于当前开发环境；生产需在后台恢复 5/3。
+- 旧 8081 服务重启期间会有短暂不可用。
+- 限流仍基于客户端可伪造 IP/设备号，本次不放宽其他风控。

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

docs/plans/2026-10-17-K5.md

@@ -0,0 +1,82 @@
+# 2026-10-17 K5 客户端视觉：克莱因蓝主题 + 印尼市场适配
+
+## 一、目标与边界
+
+本轮只完成 Flutter 客户端的主题色、蓝色收敛、印尼语 locale 和回归测试：
+
+- K5-A：建立克莱因蓝 token 与浅色/深色显式 `ColorScheme`，主色统一 `#002FA7`。
+- K5-B：清理页面层的旧蓝字面量，统一使用 `AppColors` / `ColorScheme`；不改语义色。
+- K5-C：`LocaleController` 支持 `id`；未显式选择时跟随系统，非 `en/zh/id` 回退 `id`；
+  两个现有语言入口增加 Bahasa Indonesia。
+- K5-D：补主题 token、对比度、硬编码扫描、locale 回退与语言切换测试，
+  回归深色/浅色、三态和小屏布局。
+
+不做 K4、支付、Google 登录、新接口、下载落盘、App 图标/启动图或信息架构调整；
+不改后端、`ReelShortWeb`、specs。
+
+## 二、用户裁定色值
+
+| Token | 值 | 用途 |
+| --- | --- | --- |
+| `blue` | `#002FA7` | Klein Blue / IKB 主色 |
+| `bluePressed` | `#00227A` | 按下/激活态与大面积蓝色背景 |
+| `blueSoft` | `#5B7BE0` | 深色背景上的高亮/次级文字与图标 |
+| `onPrimary` | `#FFFFFF` | 主色上的文字/图标 |
+| `ink` | `#0B0C10` | 保持现值 |
+| `bar` | `#101114` | 保持现值 |
+| `card` | `#17191F` | 保持现值 |
+| `muted` | `#B7BDC9` | 保持现值 |
+
+对比度口径：正文 ≥ 4.5:1，大字/图标 ≥ 3:1；错误红、成功绿、点赞红等语义色不改。
+
+## 三、预计影响文件
+
+- `lib/core/theme/app_colors.dart`
+- `lib/app.dart`
+- `lib/core/config/locale_controller.dart`
+- `lib/pages/mine/mine_logic.dart`
+- `lib/pages/home/widgets/home_quick_drawer.dart`
+- `lib/pages/home/home_view.dart`
+- `lib/pages/discover/discover_view.dart`
+- `lib/pages/drama_detail/drama_detail_view.dart`
+- `lib/pages/player/player_view.dart`
+- `lib/pages/player/player_logic.dart`
+- `lib/pages/player/widgets/seek_progress_bar.dart`
+- `lib/pages/player/widgets/comment_tile.dart`
+- `lib/pages/player/widgets/drama_comments_sheet.dart`
+- `lib/pages/mine/mine_view.dart`
+- `lib/pages/watch_records/watch_records_page.dart`
+- `lib/pages/downloads/downloads_page.dart`
+- `lib/pages/auth/auth_view.dart`
+- `lib/core/widgets/auth_gate.dart`
+- `lib/l10n/app_{en,zh,id}.arb` 与生成文件
+- `test/theme/*`、`test/config/*`、相关页面 widget 测试
+
+实际改动以静态扫描结果为准；不改业务逻辑和页面布局。
+
+## 四、TDD 顺序
+
+1. 写主题 token/对比度、硬编码蓝色扫描、locale `id` 持久化与未知语言回退测试，确认红灯。
+2. K5-A：新增色值 token 和浅色/深色 `ColorScheme`，补主题测试转绿。
+3. K5-B：按扫描结果替换页面蓝色字面量，补语言入口和 widget 回归。
+4. K5-C：实现 `id` locale、系统语言跟随、未知系统语言回退 `id`，两个入口增加
+   Bahasa Indonesia。
+5. K5-D：全量扫描、深色/浅色与小屏 widget 回归。
+6. 门禁：`dart analyze lib test`、`flutter test`、`flutter build apk --debug`。
+7. `--no-ff` 合并回 `develop` 并 push；FruitServer 仅提交 `docs/plans`。
+
+## 五、风险与处理
+
+- 克莱因蓝在浅色背景上作为文字可能对比不足：正文继续使用现有着色，
+  主色主要用于按钮/图标/选中态；主色背景统一配 `onPrimary`。
+- `blueSoft` 仅用于深色背景高亮，避免在浅色背景当正文色造成低对比度。
+- 现有 `_orange` 等历史命名可能实际承载蓝色，替换时按语义改名，避免误导。
+- 直接替换主题色可能影响 FilledButton、Slider、Switch 等 Material 控件：
+  通过显式 `ColorScheme` 和 widget 测试统一验证。
+- 语言入口两处需同步，避免“我的”和快捷抽屉行为不一致。
+- 真机、设备截图与系统语言切换证据由用户执行，Codex 不跑真机。
+
+## 六、待确认
+
+- 当前无产品歧义；按用户裁定的方案 A 色值执行。
+- specs 无成文色板，若后续提供 Stitch 视觉稿，再按新稿更新 token 与页面映射。

docs/plans/2026-10-17-K6.md

@@ -0,0 +1,102 @@
+# 2026-10-17 K6 客户端 UI：登录页 + 底部导航优化
+
+## 一、目标与边界
+
+本批只优化 Flutter 登录页和首页底部导航，基于 K5 克莱因蓝主题：
+
+- K6-A：登录页品牌区、autofill、密码显隐、键盘 next/done 提交、
+  提交中禁用、主题语义错误色、小屏键盘可用性。
+- K6-B：底部导航背景/边框/选中态统一使用 K5 token，安全区适配，
+  点击区域 ≥48pt，切换动效 ≤200ms。
+- K6-C：新增可注入 `Haptics` 封装，只对关键操作提供 selection/light/medium 反馈。
+- K6-D：新增 widget 测试并保持既有 Key、导航逻辑与沉浸隐藏行为。
+
+不做忘记密码、Google/Apple 登录、隐私勾选、新 tab、页面信息架构调整；
+不改接口、业务校验、注册/登录流程、后端、Web 或 specs。
+
+## 二、设计口径
+
+- 主色：`AppColors.blue = #002FA7`。
+- 按下态/大面积激活背景：`AppColors.bluePressed = #00227A`。
+- 深色底高亮：`AppColors.blueSoft = #5B7BE0`。
+- 主色上的文字/图标：`AppColors.onPrimary = #FFFFFF`。
+- 错误提示使用 `ColorScheme.error/onError` 对应语义色。
+- 底栏背景使用现有 `AppColors.bar`，顶部边框使用主题 outline 或现有暗色 token；
+  页面不新增色值字面量。
+
+## 三、预计影响文件
+
+- `lib/pages/auth/auth_view.dart`
+- `lib/pages/home/home_view.dart`
+- `lib/core/platform/haptics.dart`
+- `lib/app.dart`（Haptics Provider）
+- 收藏、点赞、评论、举报、下载、记录相关页面回调
+- `lib/l10n/app_{en,zh,id}.arb` 与生成文件
+- `test/auth/auth_page_test.dart`
+- `test/widget_test.dart`
+- 必要时补首页导航专用测试文件
+
+不修改 `HomeLogic` 的 tab 顺序、选中规则和 Key；不动播放页沉浸状态来源。
+
+## 四、交互与可用性
+
+### 登录页
+
+- 品牌区显示 App 名和印尼市场副标题，全部走 l10n 三语。
+- 邮箱 `TextInputAction.next`，提交后焦点进入密码框。
+- 密码 `TextInputAction.done`，提交后直接执行现有 `_submit()`。
+- 邮箱 `AutofillHints.email`，密码 `AutofillHints.password`。
+- 密码显隐按钮语义标签走 l10n，所有点击区域 ≥44pt。
+- `busy` 时禁用两个输入框、显隐按钮、提交和模式切换。
+- 使用 `resizeToAvoidBottomInset` + ListView/SafeArea，保证小屏键盘下
+  submit 可滚动到可见区域。
+
+### 底部导航
+
+- 保持 4 个 tab 的数量、顺序、Key 和回调不变。
+- 选中态采用克制的背景胶囊（现有方案收敛）或短指示条，二选一即可；
+  使用 `bluePressed` 胶囊 + `blueSoft` 高亮文字/图标。
+- 底栏高度 + SafeArea bottom 适配 home indicator。
+- 每个 tab 的可点击区域至少 48pt；动效控制在 200ms 内。
+- `logic.videoImmersive == true` 时保持 `bottomNavigationBar: null`。
+
+### 点击震动反馈
+
+- 使用 Flutter 内置 `HapticFeedback`，统一封装为 `Haptics` 抽象 +
+  `FlutterHaptics` 默认实现，通过 Provider 注入，测试使用 fake。
+- tab 真正切换：`selectionClick()`。
+- 登录/注册提交、收藏/取消、点赞/取消、评论发送、举报提交、下载授权申请：
+  `lightImpact()`。
+- 清空记录、清空下载、删除记录/授权：`mediumImpact()`。
+- 全部 `unawaited`；平台不可用时默认实现静默忽略；普通列表/滚动/页面切换不触发。
+
+## 五、TDD 顺序
+
+1. 新增登录页密码显隐、autofill、next/done 焦点、busy 禁用、错误语义色测试。
+2. 新增底栏 4 Key、tab 切换选中态、沉浸隐藏、最小点击区域和硬编码色扫描测试。
+3. 新增 fake Haptics 测试，覆盖 tab selection、主操作 light、危险操作 medium、
+   普通列表不触发与默认实现异常静默。
+4. 先运行定向测试确认红灯，再实现登录页、底栏与 Haptics 转绿。
+5. 补 320×568 小屏与键盘弹出回归。
+6. 全量门禁：`dart analyze lib test`、`flutter test`、
+   `flutter build apk --debug`。
+
+## 六、风险与处理
+
+- 登录页已有业务逻辑较长：仅提取品牌区和表单展示组件，不改
+  `AuthLogic`、接口调用与校验规则。
+- 键盘焦点流转依赖 `FocusNode`：显式创建并释放，测试使用
+  `tester.testTextInput.receiveAction(TextInputAction.next/done)`。
+- busy 状态下测试请求不能立即返回：使用可控 Fake Auth 或延迟 Future，
+  验证输入和按钮禁用，再释放请求避免测试悬挂。
+- 底栏新增动画可能影响既有 `pumpAndSettle`：统一使用 ≤200ms，
+  不引入第三方动画库。
+- Haptics 注入遗漏会让页面测试缺少 Provider：所有直接 pump 页面的测试
+  统一注入 fake；生产默认实现吞掉平台不可用异常，不影响业务。
+- 安全区/小屏可能压缩按钮高度：使用最小点击区约束与
+  `SafeArea(minimum: ...)`，保持现有 Key 可定位。
+
+## 七、待确认
+
+- specs 无 UI 设计稿，按“视觉统一 + 可用性”执行；不引入图片资源。
+- 当前无产品歧义；若真机出现键盘安全区差异，由用户提供设备侧截图后再做最小修正。

docs/plans/2026-10-17-K7.md

@@ -0,0 +1,91 @@
+# 2026-10-17 K7 首页轮播图 + 站内信通知
+
+## 一、目标与边界
+
+本批只完成 Flutter 客户端两项能力：
+
+- K7-A：增强现有 `CoverCarousel`，继续使用 `feed.banners` 和 3D 翻转风格，
+  增加自动轮播、交互暂停、指示器、失败占位和语义。
+- K7-B：新增匿名站内信分页页，接入 `GET /app/notices`，在我的页增加通知入口。
+- K7-C：补轮播/通知/响应式与 locale 时间测试。
+
+不做已读未读、红点、FCM、通知设置、`/app/config noticeEnabled`、首页铃铛、
+新 banner 接口、后端、Web 或 specs 修改。
+
+## 二、契约口径
+
+### Banner
+
+- 数据源：`GET /app/home/feed` / `GET /app/discover/feed` 的 `banners[]`。
+- 无独立接口；空列表继续 `SizedBox.shrink()`。
+- 点击继续沿用 `linkType=DRAMA` + `linkValue` 的现有 `onOpen`。
+
+### Notices
+
+- `GET /app/notices?pageIndex=1&pageSize=20`，匿名。
+- 响应：`{total, list:[{id,title,content,type,publishAt,expireAt}]}`。
+- ID 全部按字符串；`total` 是数字。
+- `list.length` 用于判断当前页是否有数据；是否加载更多按
+  “已加载数量 < total”判断。
+- `type` 原样展示，不建立客户端枚举映射。
+
+## 三、预计影响文件
+
+轮播：
+
+- `lib/pages/discover/widgets/cover_carousel.dart`
+- `lib/pages/discover/discover_view.dart`
+- `lib/core/widgets/remote_image.dart`（可选失败图标参数）
+- `test/discover/cover_carousel_test.dart`
+
+通知：
+
+- `lib/core/data/models/notice.dart`
+- `lib/core/data/remote/notice_api.dart`
+- `lib/core/data/repositories/notice_repository.dart`
+- `lib/core/data/services/notices_controller.dart`
+- `lib/pages/notices/notices_page.dart`
+- `lib/pages/mine/mine_view.dart`
+- `lib/app.dart`（NoticeRepository Provider）
+- `test/notice/**`
+- `lib/l10n/app_{en,zh,id}.arb` 与生成文件
+
+## 四、实现口径
+
+### 轮播
+
+- `Timer.periodic` 4.5s；单张不创建定时器；`dispose` 取消。
+- 使用 `TickerMode.of(context)`/`Visibility` 语义监听页面可见性；
+  不可见时取消，恢复时重新启动。
+- pointer down 暂停，up/cancel 恢复；拖拽时沿用现有 3D 翻转。
+- 指示器采用底部圆点，使用 `AppColors.onPrimary` + `muted` 低透明度。
+- 语义标签进入三语 arb。
+- 图片失败使用现有 `RemoteImage` 并显示图标占位。
+
+### 通知
+
+- `NoticesController` 管理首屏、分页、加载更多、刷新、错误。
+- `NoticesPage` 深色页，保留 K5/K6 主题与 Haptics 不触发滑动振动。
+- 列表项标题/类型/时间/两行摘要；点击打开详情 Dialog。
+- 详情 `content` 用可滚动 `Text` 保留 `\n`，长内容不溢出。
+- `publishAt` / `expireAt` 使用现有 `formatLocalizedDateTime`。
+- 我的页 `_menuCard` 增加通知入口，匿名可进入。
+
+## 五、TDD 顺序
+
+1. 轮播：自动切页、单张无 Timer、指示器、触摸暂停、点击回调、失败占位。
+2. 通知 API/model：分页字段、字符串 ID、时间解析。
+3. Controller：首屏、追加、加载更多条件、空/失败/刷新。
+4. NoticesPage：三态、列表、分页、详情、长内容、小屏。
+5. 我的页入口与三语文案。
+6. 门禁：`dart analyze lib test`、`flutter test`、
+   `flutter build apk --debug`。
+
+## 六、风险与待确认
+
+- 自动轮播 Timer 与 3D AnimationController 并存，需避免 dispose 后 setState。
+- 页面用 `IndexedStack` 保持状态，需通过 `TickerMode` 判断真实可见性。
+- `total` 可能在分页期间变化，以本次响应 total 与已加载数量比较。
+- 详情长内容必须可滚动，避免小屏 overflow。
+- `noticeEnabled` 属 `/app/config`，本批不接；通知入口暂时常驻，已登记后续。
+- 无独立 banner 接口和已读接口，不自行扩展契约。

docs/plans/2026-10-17-K8.md

@@ -0,0 +1,63 @@
+# 2026-10-17 K8 登录页视觉重设计
+
+## 一、目标与边界
+
+将现有登录页从表单堆叠改为深色、克莱因蓝品牌的单页视觉，保留 K6 已完成的
+AuthLogic、校验、接口、登录/注册流程、autofill、键盘流转、busy 状态和 Haptics。
+
+- 客户端分支：`feature/flutter-k8-auth-visual`，基线 `develop 6cc5bfc`。
+- 文档分支：`docs/k8-auth-visual`，FruitServer 只改 `docs/plans/`。
+- 不改后端、Web、specs、接口契约、其他页面或业务逻辑。
+- 不新增图片、字体、第三方依赖；品牌图形使用 Material Icons。
+- 不跑真机，设备侧视觉、键盘与小屏验收由用户执行。
+
+## 二、视觉与交互实现
+
+1. 页面背景使用 `AppColors.ink`，顶部叠加克莱因蓝渐变光晕，颜色透明度不超过
+   0.18，并忽略指针事件。
+2. 品牌区使用 48px 克莱因蓝圆角方块、白色剧集图标、App 名和现有
+   `authBrandTagline`。
+3. 表单放入 20px 圆角、1px `outlineVariant` 边框、20px 内边距的
+   `AppColors.card` 卡片。
+4. 输入框使用 52px 高、14px 圆角、`AppColors.bar` 填充，带邮箱/锁前缀图标；
+   聚焦时显示 1.5px 主色边框并高亮图标；密码显隐按钮保留。
+5. 主按钮全宽 52px、26px 圆角、`AppColors.blue` 背景、白色 16/w700 文字，
+   pressed 态使用 `bluePressed`，loading 为 18px 白色环，busy 时输入、切换与
+   提交均禁用。
+6. 登录/注册改为双段 pill，实际可见标签为 `signIn` / `signUp`；点击调用现有
+   `toggleMode()`。保留既有 `auth-switch-mode` 兼容入口，避免破坏既有测试。
+7. 错误提示使用红色 10% 透明背景、12px 圆角、图标和主题 error 色文字的胶囊。
+8. 首帧使用 220ms 的 `TweenAnimationBuilder` 完成淡入和上滑。
+9. 保留 `auth-scroll`、`auth-email`、`auth-password`；新增
+   `auth-brand`、`auth-card`、`auth-mode-sign-in`、`auth-mode-sign-up`、
+   `auth-submit`、`auth-error-capsule` 等稳定 Key。
+
+## 三、影响文件
+
+- `ReelShort/lib/pages/auth/auth_view.dart`
+- `ReelShort/test/auth/auth_visual_test.dart`（新增）
+- `ReelShort/test/auth/auth_page_test.dart`（既有用例保持不变）
+- `FruitServer/docs/plans/2026-10-17-K8.md`
+- `FruitServer/docs/plans/PROGRESS.md`
+- `FruitServer/docs/plans/INBOX.md`（完成后标记 K8 已处理）
+
+## 四、TDD 与门禁
+
+1. 先新增视觉测试并运行，确认分段控件、品牌、错误胶囊和尺寸断言红灯。
+2. 实现登录页视觉后，定向 auth 测试绿灯。
+3. 运行 `dart analyze lib test` 零告警。
+4. 运行 `flutter test` 全过。
+5. 构建前确认没有并发 `flutter run/build`；运行
+   `flutter build apk --debug`。
+6. 完成后 `merge --no-ff` 回客户端 `develop` 并 push；FruitServer 文档同样
+   合并推送。提交作者与提交者统一为
+   `Zhou Weidong <502333560@qq.com>`。
+
+## 五、风险与待确认
+
+- 旧测试按文字链接和 `auth-switch-mode` TextButton 检查交互；本次通过保留
+  兼容入口满足旧用例，同时可见交互必须由新 pill 分段控件完成。
+- 320px 小屏和键盘弹出时，卡片、错误胶囊及按钮需保持可滚动且不溢出。
+- 当前检测到 Android `flutter run` 会话；构建门禁前必须复查，若仍占用
+  `build/` 则等待其结束，不能并发构建。
+- specs 无登录页设计稿，颜色与尺寸以本 INBOX 条目为准，无需新增契约。

docs/plans/2026-10-17-K9.md

@@ -0,0 +1,70 @@
+# 2026-10-17 K9 首页剧目列表改造（2 列全部剧目）
+
+## 一、目标与边界
+
+首页（发现 tab）移除「继续观看」区块，在分类 chips 下方以懒构建的 2 列网格展示
+当前分类的全部剧目；保留 header、轮播、分类、三态、空态和底部导航。
+
+- 客户端分支：`feature/flutter-k9-home-grid`，基线 `develop 99f64ab`。
+- 文档分支：`docs/k9-home-grid`，FruitServer 基线 K9 任务书 `b434f65`。
+- 只改首页（发现页）、三语 l10n、对应 widget 测试与 `docs/plans/`。
+- 不改接口、数据模型、CategoryController 过滤逻辑、轮播、通知、观看记录、
+  收藏、下载或底部导航。
+- 不新增图片、依赖或分页；继续使用 `RemoteImage` 懒加载。
+- 不跑真机，设备侧滚动、布局、分类切换和详情跳转由用户验收。
+
+## 二、实现方案
+
+1. 删除 `_continueHeader`、`_dramaContent`、`_continueTile`、`_ShowcaseCard`
+   与 `_cardsFor`，首页不再构建或保留「继续观看」文案和代码。
+2. 将页面滚动容器改为 `CustomScrollView`，依次放置：
+   carousel `SliverToBoxAdapter`、分类与标题 `SliverToBoxAdapter`、状态
+   `SliverToBoxAdapter` 或剧目 `SliverGrid`、底部留白 `SliverToBoxAdapter`。
+3. 剧目网格使用 `SliverGridDelegateWithFixedCrossAxisCount`：
+   `crossAxisCount: 2`、`crossAxisSpacing: 12`、`mainAxisSpacing: 16`、
+   `childAspectRatio: 2 / 3`；左右由 `SliverPadding` 保持 16。
+4. 卡片封面使用 2:3 比例、14px 圆角、`RemoteImage` 和现有底部深色渐变；
+   标题最多 2 行，类型最多 1 行。点击调用现有
+   `logic.openCard(..., embedded, onDramaSelected, onAction)`。
+5. 数据直接使用 `CategoryController.visibleDramas`；`For You` 使用其全量
+   去重结果。分类切换后由 ChangeNotifier 驱动 sliver 内容更新。
+6. 保留 `categories.loading` 首载进度、`categories.error` 重试、
+   `noCategoryDramas` / `noSearchResults` 空态文案。
+7. l10n 新增 `allDramas`：
+   `全部剧目` / `All Dramas` / `Semua Drama`，并重新生成 l10n。
+
+## 三、影响文件
+
+- `ReelShort/lib/pages/discover/discover_view.dart`
+- `ReelShort/lib/l10n/app_en.arb`
+- `ReelShort/lib/l10n/app_zh.arb`
+- `ReelShort/lib/l10n/app_id.arb`
+- `ReelShort/lib/l10n/app_localizations*.dart`（生成物）
+- `ReelShort/test/discover/home_all_dramas_grid_test.dart`（新增）
+- `ReelShort/test/widget_test.dart`（仅更新作废的「继续观看」断言）
+- `FruitServer/docs/plans/2026-10-17-K9.md`
+- `FruitServer/docs/plans/PROGRESS.md`
+- `FruitServer/docs/plans/INBOX.md`
+
+## 四、测试与门禁
+
+1. 先新增 K9 首页 widget 测试并取得红灯。
+2. 实现后验证：无「继续观看」、有「全部剧目」、2 列 sliver、左右/行列间距、
+   2:3 封面、分类切换更新、空态与失败态。
+3. 运行 `dart analyze lib test`、`flutter test`、`flutter build apk --debug`；
+   构建前检查无并发 `flutter run/build`。
+4. 完成后 `merge --no-ff` 回客户端 `develop` 并 push；FruitServer 文档同样
+   合并推送。作者与提交者统一为
+   `Zhou Weidong <502333560@qq.com>`。
+
+## 五、风险与待确认
+
+- 既有 `test/widget_test.dart` 有两个壳层用例断言首页出现
+  `Continue Watching`。K9 明确要求该文案彻底消失，因此原断言与
+  `find.text('Continue Watching'), findsNothing` 不可能同时成立。
+  处理方式：保留两个既有用例及完整导航流程，只把已作废的文案断言更新为
+  `All Dramas`，不删除任何测试用例。
+- 首页 feed 可能一次返回较多剧目；必须使用 `SliverGrid` 懒构建，不能嵌套
+  `GridView(shrinkWrap: true)`。
+- 2:3 卡片在小屏需要保持标题 2 行和类型 1 行不溢出；测试覆盖 320px 宽度。
+- 不改 `CategoryController` 的数据语义；筛选仍由现有分区 code 决定。

docs/plans/2026-10-19-K19.md

@@ -0,0 +1,87 @@
+# 2026-10-19 K19 客户端账号中心
+
+## 基线
+
+- ReelShort `develop`: `7d68699`
+- FruitServer `develop`: `5c93ba9`
+- 只改 ReelShort；不改 FruitServer 业务代码、ReelShortWeb、specs、main。
+
+## 范围
+
+对接 `docs/api-phase1.md` §1.2 的六个个人中心接口：
+
+| 方法 | 路径 | 客户端用途 |
+| --- | --- | --- |
+| GET | `/app/me` | 资料展示 |
+| PUT | `/app/me` | 修改昵称、性别、生日 |
+| GET | `/app/me/devices` | 只读登录设备列表 |
+| GET | `/app/me/export` | 账号数据摘要与完整 JSON 复制 |
+| POST | `/app/me/deactivate` | 申请注销并进入 15 天冷静期 |
+| POST | `/app/me/deactivate/cancel` | 撤销待处理注销申请 |
+
+## 接口口径
+
+1. 资料响应仅使用：
+   `uid/nickname/avatarUrl/gender/countryCode/regionCode/language/timezone/currency/status/maskedTarget/createdAt/lastLoginAt/vipLevel/vipExpireAt`。
+   `vipLevel` 是整数；时间字段按 `LocalDateTime` 字符串解析。
+2. 资料更新只发送本次变更字段：
+   `nickname/avatarUrl/gender/birthday/language/timezone/regionCode`。
+   本页只修改 `nickname/gender/birthday`；昵称 trim 后非空且不超过 30 字符，
+   性别取 `male/female/unknown`，生日格式 `yyyy-MM-dd`。
+3. 设备数组只解析并展示
+   `deviceId/platform/deviceModel/firstSeenAt/lastSeenAt/status`；
+   `id/userId/deleted` 不展示、不打印。页面只读。
+4. 导出按实际结构解析
+   `{profile, credentials, consents, devices}`，展示资料摘要、凭据、授权记录数和设备数；
+   “复制完整 JSON”只写系统剪贴板，不写本地文件。
+5. 注销请求只发送 `reason`，不采集或上送密码；成功返回 `scheduledAt`。
+   成功后清本地会话，不调用 logout。撤销接口成功 `data=null`，失败原样透传后端文案。
+6. 所有数值和 ID 使用 `jsonToId/jsonToInt`；错误由 `ApiException` 透传到逻辑层。
+
+## 客户端改造
+
+- `lib/core/data/remote/account_api.dart`
+- `lib/core/data/models/account_profile.dart`
+- `lib/core/data/models/account_device.dart`
+- `lib/core/data/models/account_export.dart`
+- `lib/core/data/repositories/account_repository.dart`
+- `lib/pages/account/` 下四个页面及各自的 binding/logic
+- `lib/pages/mine/mine_view.dart` 登录态新增“账号”卡
+- `lib/core/data/services/auth_controller.dart` 新增 `applyProfile`
+- `lib/app.dart` 注册 `AccountRepository` Provider
+- `lib/l10n/app_{en,zh,id}.arb` 与生成文件
+- 测试新增 `test/account/`、`test/support/fake_account_repository.dart`
+
+## TDD 顺序
+
+1. 先写 API/模型测试：六条路径、方法、请求体、字符串/数字 ID、缺字段；
+   运行定向测试确认红灯。
+2. 实现 AccountApi、三个模型和 AccountRepository，定向测试转绿。
+3. 先写 AuthController.applyProfile 测试：保留令牌、更新昵称/头像并持久化；
+   再实现。
+4. 先写 profile/device/export/deactivate logic 测试：
+   资料保存回调登录态、注销成功清会话、撤销失败透传文案、导出复制内容；
+   再实现逻辑层。
+5. 先写 widget 测试：我的页入口登录可见、资料回填与保存、设备空态、
+   注销二次确认、导出加载/失败/重试；再实现页面和入口。
+6. 生成 l10n，跑全量门禁；最后一次全量测试与 APK 构建。
+
+## 门禁
+
+```text
+dart analyze lib test
+flutter test
+flutter build apk --debug
+```
+
+Flutter 分支：`feature/flutter-k19-account`。
+
+## 风险与待确认
+
+- `GET /app/me` 不返回注销申请状态，UI 不猜测状态；撤销失败展示后端文案。
+- 无设备下线接口，设备页只读；`TC-ACCOUNT-10` 的“单点下线”保留为缺口。
+- 无头像上传接口，头像只展示；空值使用现有占位。
+- 资料响应不含 `birthday`，也没有清空入口。本批生日只能设置，无法回填或清除；
+  不补后端字段，页面文案明确为本次设置。
+- 注销成功后服务端立即吊销全部会话，本地同步清理；撤销入口在重新登录后仍可使用。
+- 真机验证由用户执行，本批不提供开发机 curl 或设备侧结果作为证据。

docs/plans/2026-10-19-K20.md

@@ -0,0 +1,60 @@
+# 2026-10-19 K20 客户端视觉统一
+
+## 基线
+
+- ReelShort `develop`: `42ce1d1`
+- FruitServer `develop`: `810d9fc`
+- 只改 ReelShort 视觉与布局；不改业务逻辑、接口、后端、Web、specs、main。
+- 保留辣椒红 `AppColors.blue = #C4322A`。
+
+## 统一 Token
+
+新增 `lib/core/theme/app_dimens.dart`：
+
+| Token | 值 |
+| --- | --- |
+| 页面左右边距 | 16 |
+| 卡片圆角 / 内边距 | 16 / 16 |
+| 内嵌块圆角 / 内边距 | 12 / 12 |
+| 胶囊圆角 | 20 |
+| caption / body / list / section / page | 12 / 14 / 15 / 16 / 20 |
+| 导航标签 | 11 |
+| 详情主标题 | 24 |
+| 主按钮高度 | 48；整页主操作 52 |
+| 点击区 | 44 × 44 |
+| 导航高度 / 图标 | 64 / 22 |
+| 进度条高度 / 圆角 | 4 / 4 |
+| 账号卡高度 / 图标 / 标签 | 64 / 18 / 11 |
+| 观看占位高度 | 114 |
+
+## 改造顺序
+
+1. 加 token 与主题：`AppDimens`、`AppColors.favorite`、深色唯一口径、
+   按钮最小高度、OutlinedButton 主题、AppBar/状态栏样式。
+2. 新增 `AppBottomNav` / `AppBottomNavItem`，替换 home/discover/mine/player fallback。
+3. 调整账号入口卡为 64 高、18 图标、11 标签、44 点击区，并回归 K19 首屏测试。
+4. 收敛字号下限：业务文案 ≥12，导航 11；清理 9.5/10。
+5. 收敛卡片圆角与间距：页面 16、卡片 16/12、区块 16/12。
+6. 替换任务书列出的硬编码颜色；收藏红心使用 `AppColors.favorite`。
+7. 统一详情、记录、下载进度条为 4 高、4 圆角、blueSoft/white24；播放器拖动条保持金色。
+8. 统一页面/区块/列表标题层级与按钮高度，移除 mine 按钮 VisualDensity.compact。
+9. 详情加载/失败分支补返回 AppBar，封面顶部加黑色渐变，详情边距 24→16。
+10. 点赞/收藏选中态改实心图标；分类和 my tabs 补 selected 语义。
+11. HeaderPill / LoginButton / 分类 Chip 点击区补到 44。
+12. 列表页底部安全区补齐；观看记录占位高度 114，与真实卡片 padding 一致。
+
+## 测试与门禁
+
+- 新增 `AppDimens` token 测试与 `AppBottomNav` 组件测试。
+- 不修改既有测试断言；视觉布局变化导致测试失败时改实现。
+- `dart analyze lib test`
+- `flutter test`
+- `flutter build apk --debug`
+
+## 风险与边界
+
+- 账号卡升高到 64 可能重新挤压“我的”页首屏；必须保持 K19 语言设置和观看历史入口测试通过。
+- 保留页面级深色 Theme 包装以降低大范围回归风险，但根 `themeMode` 必须固定 `dark`。
+- 不碰 K21 范围：搜索、Android 返回键、播放器切票黑屏、登录后续操作、下拉刷新、
+  注销状态闭环、日期/时长格式、语言上送。
+- 真机验收由用户执行，本批不提供设备侧截图或日志。

docs/plans/2026-10-19-K21.md

@@ -0,0 +1,70 @@
+# 2026-10-19 K21 登录页 UI 优化
+
+## 基线
+
+- ReelShort `develop`: `e44fbdf`
+- FruitServer `develop`: `af28161`
+- 只改 `ReelShort/lib/pages/auth/**`、l10n 与必要的新增测试。
+
+## 布局方案
+
+- 用 `LayoutBuilder + SingleChildScrollView + ConstrainedBox + Center`，
+  让品牌与卡片在可视区域垂直居中，键盘弹起时仍可滚动。
+- 保留 `auth-scroll`，底部 padding 继续使用 `28 + viewInsets.bottom`。
+- 返回按钮移到顶部 `Positioned + SafeArea` 浮层，不再占据内容流。
+- 内容最大宽度继续为 440，页面左右边距 16。
+- 保留主 background glow（alpha ≤0.18），新增独立 Key 的 warm glow（alpha ≤0.06）。
+
+## 品牌与卡片
+
+- 品牌区居中竖排：48×48 splash mark、App 名 26/w800、tagline 14/blueSoft。
+- `auth-brand`、`auth-brand-mark` 保留，mark 尺寸严格 48×48。
+- 卡片结构保持：模式切换 → 标题 25/w800 → 副标题 → 字段 → 错误胶囊 → 提交。
+- 登录继续使用 `authSubtitle`；注册使用新增 `authSignUpSubtitle`。
+- 注册态密码框下显示 12px 的 `authPasswordHint`，登录态隐藏。
+
+## 字段错误与交互
+
+- `AuthLogic` 增加 `fieldError`；`validate()` 记录具体错误，输入变化或切换模式时清除。
+- 邮箱/密码字段按 `fieldError` 使用 1.5px semantic error `errorBorder` /
+  `focusedErrorBorder`。
+- 保留 `auth-error-capsule`、`auth-error` 的文案、圆角 12 和 alpha 0.1。
+- `_submit()` 首行 busy 短路；异步 catch 中的 `setState` 前检查 mounted。
+- 密码框 done 提交仍走同一 `_submit()`，busy 时自然忽略。
+- 提交按钮增加极淡辣椒红阴影，背景和按下色保持不变。
+
+## 不可变清单
+
+```text
+auth-brand-mark 48x48
+auth-card radius 20 / border outlineVariantDark / width 1
+input height 52 / radius 14 / fill bar / focus blue 1.5
+submit height 52 / radius 26 / blue / bluePressed
+auth-enter-animation <=220ms / tween 0 -> 1
+mode switch keys, hidden compatibility copy
+error capsule radius 12 / alpha 0.1 / semantic color
+small screen 320x568 + keyboard 260 scroll reachability
+```
+
+## TDD
+
+1. 新增测试：注册副标题、注册态密码提示、登录态不显示提示、字段错误红框。
+2. 先确认红灯。
+3. 补 `authSignUpSubtitle` 三语并生成 l10n。
+4. 调整 AuthLogic、表单字段、品牌和页面布局。
+5. 跑两份既有 Auth 测试与新增测试，再跑全量门禁。
+
+## 门禁
+
+```text
+dart analyze lib test
+flutter test
+flutter build apk --debug
+```
+
+## 风险
+
+- 居中布局与小屏滚动会互相影响，必须保持 `auth-submit` 可滚动到。
+- 字段红框不能通过 errorText 增加字段高度，否则会破坏 52 高度断言。
+- 品牌改为图片资源后仍必须保持 `auth-brand-mark` 为 48×48。
+- 不改接口、后端、Web、specs、main；真机由用户验收。

docs/plans/2026-10-19-K22.1.md

@@ -0,0 +1,56 @@
+# 2026-10-19 K22.1 后台收尾
+
+## 基线
+
+- ReelShortWeb `develop`: `5494190`
+- FruitServer `develop`: `2807ae6`
+- 只改 ReelShortWeb 的后台视觉与资源引用、构建配置及无引用文件。
+- 不改接口契约、后端业务、客户端与 main。
+
+## 登录页
+
+1. 保留 hero 品牌 mark、kicker 与标题。
+2. 删除标题下方说明段落及 `pointDrama/pointPublish/pointAccess` 三个标签。
+3. 删除不再使用的三语 key 与 hero 列表样式。
+4. 删除注册切换、注册表单、入口事件及相关导出和文案。
+
+## 品牌与图标
+
+1. `brand-mark.png` 复制到 `public`，作为浏览器 favicon 与首屏 loading。
+2. 首屏背景改为 `#100C0A`，loading mark 增加圆角。
+3. 删除 `public/logo.png`、`public/favicon.ico`。
+4. 四个 env 均关闭在线图标，由 `PurgeIcons` 本地打包 Material Symbols。
+5. 构建后扫描旧前缀、`<el-icon>`、Element Plus 图标引用，并检查浏览器实际图标。
+
+## Mock 清理
+
+1. dev/pro/test 环境关闭 `VITE_USE_MOCK`。
+2. 删除 `mock/` 与 `viteMockServe` 配置。
+3. 全仓确认不再存在 mock 环境分支和旧 mock 图标来源。
+
+## 文件删除
+
+删除前分别对目标路径执行全仓 grep，确认只命中自身或已同步处理的引用：
+
+- `src/assets/imgs/logo.png`
+- `src/assets/imgs/avatar.jpg`
+- `public/logo.png`
+- `public/favicon.ico`
+- `src/views/permission/CustomMenuView.vue`
+- `src/views/Login/components/RegisterForm.vue`
+- `mock/`
+
+禁止删除仍被路由、菜单、组件或构建配置引用的文件。
+
+## 门禁
+
+- `pnpm lint:eslint`
+- `pnpm build:pro`
+- 浏览器自查登录页、后台壳、菜单、顶栏、表格工具栏与首屏 loading。
+- 控制台无 `/logo.png`、mock 或旧图标资源 404。
+
+## 风险
+
+- 在线图标关闭后必须确认 PurgeIcons 已本地打包全部实际使用图标。
+- 删除 mock 后需确认开发环境只依赖真实后台接口。
+- 删除文件前先处理所有引用，避免残留 import 或路由失败。

docs/plans/2026-10-19-K22.md

@@ -0,0 +1,78 @@
+# 2026-10-19 K22 后台管理视觉与交互统一
+
+## 基线
+
+- ReelShortWeb `develop`: `5c087f4`
+- FruitServer `develop`: `b025bfd`
+- 只改 Web 视觉/交互与 FruitServer 菜单图标 SQL，不改接口、客户端、main。
+
+## 图标体系
+
+1. 新增 `src/constants/icons.ts`：
+   - `AppIcons` 保存语义名到 `material-symbols:*-rounded` 的映射；
+   - `normalizeAppIcon()` 兼容后端旧短名和历史 Iconify 名；
+   - `MenuIconOptions` 供菜单管理页选择。
+2. 新增 `src/components/AppIcon`：
+   - 复用现有 `Icon` 组件；
+   - 默认尺寸 18，支持颜色/悬停色；
+   - 全局注册 `AppIcon`。
+3. 替换 `src/components/**`、`src/views/**` 的旧图标前缀与 Element Plus 图标组件。
+4. 对 `node_modules/@iconify/json/json/material-symbols.json` 做存在性校验。
+
+任务书要求的 `language/view-column/lock/chevron-down` 在当前 JSON 中没有对应的
+`*-rounded` 名，实施时使用同语义且存在的
+`translate-rounded/combine-columns-rounded/lock-person-rounded/keyboard-arrow-down-rounded`。
+
+## 菜单落库
+
+更新 `sql/data.sql` 与 `sql/data-phase1.sql` 中 id 1/2/3/6/15/17/20/22/24/26/32：
+
+| 菜单 | 图标 |
+| --- | --- |
+| 工作台 | `material-symbols:dashboard-rounded` |
+| 内容管理 | `material-symbols:video-library-rounded` |
+| 后台管理 | `material-symbols:settings-rounded` |
+| 用户管理 | `material-symbols:group-rounded` |
+| 创作者管理 | `material-symbols:movie-edit-rounded` |
+| 内容治理 | `material-symbols:policy-rounded` |
+| 订单与权益 | `material-symbols:payments-rounded` |
+| 数据看板 | `material-symbols:monitoring-rounded` |
+| 创作者中心 | `material-symbols:video-camera-front-rounded` |
+| 运营管理 | `material-symbols:campaign-rounded` |
+
+执行两份 SQL，管理员登录后请求 `/admin/auth/menus`，断言所有 icon 以
+`material-symbols:` 开头。
+
+## 品牌与登录
+
+- 复制客户端 `splash_mark.png` 为 `src/assets/imgs/brand-mark.png`。
+- Logo 组件展开/收起统一使用品牌 mark。
+- 删除 admin/admin123 占位、记住密码持久化、固定 `FruitShorts Studio`。
+- 记住我只保存用户名；store reset 时删除 loginInfo。
+- 表单回车提交、loading 覆盖请求与动态路由、防止重复。
+- 960 以下压缩 hero，登录卡首屏完整。
+
+## 全局壳与主题
+
+- 修复深色模式菜单、头部、标签关闭、主题开关、面包屑对比度。
+- body 去掉 `min-width: 980px`，补 1200/768 断点。
+- 顶栏、标签页、表格工具栏、弹窗统一 AppIcon。
+- CSS token：一组字体变量、4/6/12 圆角、`#409eff !important` 改
+  `var(--el-color-primary)`，删除或合并未使用壳层选择器。
+- 用户信息读取 `userStore`，不再使用固定 avatar/Archer。
+- 清除缓存增加二次确认。
+
+## 门禁与自查
+
+- 静态扫描：无旧图标前缀、无 `<el-icon>`、无页面 `@element-plus/icons-vue` 引用。
+- `node_modules/@iconify/json/json/material-symbols.json` 逐个校验新图标。
+- `pnpm lint:eslint` 零错误。
+- `pnpm build:pro` 成功。
+- 浏览器自查：登录页、侧边栏展开/折叠、顶栏、标签页、浅/深色、1024/800/375。
+
+## 风险
+
+- 图标批量替换可能影响动态图标与右键菜单，保留 normalize 兜底。
+- 窄屏下侧栏与固定内容宽度可能冲突，优先保证内容区不裁切。
+- 登录 loading 必须覆盖动态路由生成，避免二次提交。
+- 本轮不碰表格、筛选、分页、拦截器、删除确认、rules、权限与上传校验。

docs/plans/2026-10-19-K23.1.md

@@ -0,0 +1,32 @@
+# 2026-10-19 K23.1 后台修正
+
+## 基线
+
+- ReelShortWeb `develop`: `fe1ae95`
+- FruitServer `develop`: `b8676d0`
+- 只改 ReelShortWeb 视觉与交互，不改接口、后端、客户端、main。
+
+## 品牌文字
+
+1. 浅色菜单品牌字与浅色顶栏文字固定为 `#303133`。
+2. 处理本地持久化的旧 `inherit` 值，避免刷新后仍继承主色。
+3. 检查 Logo、ToolHeader、Breadcrumb 的实际颜色。
+
+## 删除按钮
+
+1. 扫描所有删除、移除、退款、回收、冻结危险按钮。
+2. 统一 `type="danger"`、表格内 `size="small"`，禁止 link/plain/text 和浅色 `danger-action`。
+3. 删除确认按钮保持 `el-button--danger` 实心红底。
+4. 调整过窄操作列，保证按钮不换行。
+
+## 布局回归
+
+1. 1440×900、1024×768、375×812。
+2. 检查侧栏品牌、菜单 42px 基线、popper、短剧编辑弹窗、锁屏弹窗和表格操作列。
+3. 检查顶栏、标签页、面包屑图标与文字基线。
+
+## 门禁
+
+- `pnpm lint:eslint`
+- `pnpm build:pro`
+- 浏览器控制台 0 error、0 404，页面无横向溢出。

docs/plans/2026-10-19-K23.md

@@ -0,0 +1,41 @@
+# 2026-10-19 K23 后台视觉深化
+
+## 基线
+
+- ReelShortWeb `develop`: `3e8312e`
+- FruitServer `develop`: `9c96e18`
+- 只改后台视觉/交互与菜单图标种子，不改接口契约、权限和业务流程。
+
+## 主色
+
+1. Element Plus 主色改为辣椒红 `#c4322a`，同步 light-3/5/7/8/9 与 dark-2。
+2. 清理后台源码中的默认 Element 蓝与蓝色透明背景。
+3. 验证按钮、开关、链接、选中菜单、标签页和焦点环对比度。
+
+## 菜单
+
+1. 一级菜单保留 Material Symbols Rounded 图标；所有二级菜单图标置空。
+2. 开发库幂等执行后通过 `/admin/auth/menus` 检查一级图标存在、二级 icon 为空。
+3. 菜单管理只允许目录菜单选择图标，保存子菜单时强制清空。
+4. 一级菜单行高 44，二级菜单行高 40；父子文字统一落在 42px 基线。
+5. 二级菜单不渲染图标、不保留图标空位，折叠态和 popper 同样只显示文字。
+
+## 短剧编辑弹窗
+
+1. 680px 三区块表单：基础信息、付费设置、封面。
+2. 表单增加 model/rules，数字输入固定 180px 且控件在右。
+3. 封面改为预览卡：basename、状态、更换/移除、类型/大小校验、进度与失败提示、查看原图。
+4. 保存按钮防重复，保存中与上传中禁止关闭。
+
+## 锁屏弹窗
+
+1. 440px 紧凑弹窗，移除全屏入口。
+2. 重做标题、说明、内容和底部按钮。
+3. 支持回车锁定，删除调试日志。
+
+## 门禁
+
+- 图标名逐个对照 `node_modules/@iconify/json/json/material-symbols.json`。
+- `pnpm lint:eslint` 零错误。
+- `pnpm build:pro` 通过。
+- 浏览器自查登录页、工作台、短剧管理、锁屏；1024/375、明暗主题、控制台 0 error、0 404。

docs/plans/2026-10-19-K24.md

@@ -0,0 +1,102 @@
+# K24 计划：客户端 UI 对齐设计稿
+
+日期：2026-10-19
+客户端基线：`ReelShort/develop` = `b1c69e2`
+文档基线：`FruitServer/develop` = `93b2299`
+分支：`feature/flutter-k24-design-system`
+
+## 一、范围
+
+本批只做设计系统、3 Tab 底部导航、首页沉浸层、发现页：
+
+- 设计 token：Obsidian Flare 色板、字体、间距/圆角、玻璃面板。
+- 底部导航：Home / Discover / Me 三项；My List 不再独立成 Tab，内容并入 Me 页。
+- 首页：保留 `PlayerPage(homeMode: true)` 播放链路，只替换叠加层与信息卡。
+- 发现页：品牌行、搜索、分类 chips、Continue Watching、4 个快捷入口、2 列 Trending。
+
+不做：详情页、播放器、我的页、登录页的视觉重做（K25/K26）；后端、Web、specs、main。
+
+## 二、设计口径
+
+权威来源：`docs/design/README.md` + `screens/01-home.html` + `screens/02-discover.html`。
+不采用 `DESIGN.md` 顶部 YAML 的 `#ffb4a5/#cdbdff`。
+
+| 语义 | 值 |
+| --- | --- |
+| background / ink / bar | `#0B0C10` |
+| card | `#16181F` |
+| surface-elevated / raised | `#1D1E28` |
+| primary / blue | `#FF5B3D` |
+| pressed / bluePressed | `#FF4321` |
+| secondary / lavender / blueSoft | `#9278EA` |
+| gold | `#FBBF24` |
+| success | `#34D399` |
+| on-surface | `#FFFFFF` / `#E3E2E8` |
+| muted | `#A1A1AA` |
+| subtle | `#71717A` |
+| border | `rgba(255,255,255,0.08)` |
+
+字体：Outfit（标题）、Plus Jakarta Sans（正文），OFL TTF 本地打包，不运行时联网。
+下载失败时保留系统字体，并在回执与 PROGRESS 标注未完成项。
+
+## 三、TDD 顺序
+
+1. 设计 token / 主题：先更新 `test/theme/app_theme_test.dart` 期望值与新增 token 断言，再改
+   `app_colors.dart`、`app_theme.dart`、`app_dimens.dart`。
+2. GlassPanel：先写组件测试（blur、渐变、描边、圆角），再实现 `glass_panel.dart`。
+3. 3 Tab：先改导航测试为 `tab-home/tab-discover/tab-my`，覆盖选中态、映射、沉浸隐藏；
+   再改 `app_bottom_nav.dart` 与 `home_view.dart`。
+4. 首页：先用现有 Player 测试保证播放/进度/收藏不回归，再新增首页结构断言
+   （剧名、HOT、右侧互动栏、底部玻璃卡、Follow Series、Episodes）。
+5. 发现页：先写搜索过滤、2 列网格、Continue Watching 隐藏/显示测试，再改
+   `discover_view.dart` / `discover_logic.dart` / `home_drama_grid.dart`。
+6. 回归：更新 4 Tab 与轮播挂载相关断言，保留播放、进度、收藏、举报等行为测试。
+
+## 四、影响文件
+
+- `lib/core/theme/app_colors.dart`
+- `lib/core/theme/app_theme.dart`
+- `lib/core/theme/app_dimens.dart`
+- `lib/core/widgets/glass_panel.dart`（新增）
+- `lib/core/widgets/app_bottom_nav.dart`
+- `lib/pages/home/home_view.dart`
+- `lib/pages/home/home_logic.dart`
+- `lib/pages/discover/discover_view.dart`
+- `lib/pages/discover/discover_logic.dart`
+- `lib/pages/discover/widgets/home_drama_grid.dart`
+- `lib/pages/player/player_view.dart`（仅 homeMode 叠加层）
+- `lib/pages/mine/mine_view.dart`（仅把 My List 区块并入 Me）
+- `pubspec.yaml`、`assets/fonts/*`
+- 相关 `test/**`
+
+## 五、数据缺口与降级
+
+| 设计字段 | 现有数据 | 处理 |
+| --- | --- | --- |
+| 评分 | `Drama` 无评分字段 | 隐藏，不伪造 |
+| 完结状态 | 无完结字段 | 隐藏 |
+| 榜单名次 | 无字段 | 用 `isHot` + `viewCount` 排序展示，不编名次 |
+| VIP 徽章 | 无 VIP 字段；`Episode.locked` 仅集级 | 列表不显示 VIP 徽章 |
+| Free 徽章 | `freeEpisodes` 仅详情接口 | 有值才显示 |
+| 点赞/评论数 | 互动接口无剧级计数 | 只显示图标或文案，不编数字 |
+| Continue Watching 集数/剩余时长 | `WatchProgress` 有位置/时长，无集号 | 有记录才显示，集号缺失时省略 |
+
+## 六、风险
+
+- 首页叠加层改动可能影响沉浸模式、PiP、下载入口与既有 tooltip；通过保留原有行为入口并跑
+  `test/widget_test.dart`、`test/home/**`、`test/player/**` 控制风险。
+- 3 Tab 合并会触碰多个导航测试；只调整 Tab 数量/Key 断言，不改播放与收藏断言。
+- 新字体增加安装包体积；只打包 Regular/SemiBold/Bold 必要字重。
+- 发现页数据源仍用 `CategoryController.visibleDramas`，不新增接口。
+
+## 七、门禁
+
+```bash
+flutter pub get
+dart analyze lib test
+flutter test
+flutter build apk --debug
+```
+
+提交作者/提交者：`Zhou Weidong <502333560@qq.com>`。
+

docs/plans/2026-10-19-K25.md

@@ -0,0 +1,79 @@
+# K25 计划：客户端详情页 + 播放器对齐设计稿
+
+日期：2026-10-19
+基线：`ReelShort/develop` = `4553606`
+分支：`feature/flutter-k25-detail-player`
+
+## 一、范围
+
+只改详情页与 `homeMode=false` 的播放器：
+
+- 详情页：16:9 hero、玻璃导航、元数据、简介展开、CTA、选集 chips、2 列剧集卡。
+- 卡片播放器：顶部导航、9:10 视频框、进度条、三按钮行、精选评论卡。
+- `homeMode=true` 的 K24 首页沉浸 feed 保持现状。
+
+不改：后端接口/模型字段、首页、发现页、我的页、登录页、`playback_session`/ticket 协议。
+
+## 二、设计口径
+
+沿用 K24 Obsidian Flare token、Outfit/Plus Jakarta Sans、`GlassPanel`。
+
+详情页结构：
+
+1. 16:9 hero（当前模型只有 `posterUrl`，作为 hero 图；无 `coverUrl` 字段）。
+2. 左侧玻璃返回，右侧分享/收藏/更多（举报在更多菜单）。
+3. 集数 pill、24px 标题、Season 副标题、viewCount、题材标签。
+4. 16px 简介卡，2 行 + More/Less。
+5. 橙色全宽 CTA + 48×48 收藏/下载，续看进度与错误重试保留。
+6. Episodes 标题 + 范围 chip（无区间数据时显示 All）+ 46×44 横向集数 chips。
+7. 2 列剧集预览卡：缩略图 96×64、Free/Coin、时长、锁态、下载/播放入口。
+
+播放器结构（`homeMode=false`）：
+
+1. 顶部返回、剧名 + Ep.x、更多（下载/PiP）。
+2. 9:10 圆角 16 视频框，Auto-Next/1.0x pill、中心橙色播放、右侧点赞/全屏。
+3. 1.5px 进度条，白色缓冲、橙色播放、白色 thumb；保留拖动 seek。
+4. Episodes / Comments / Next Ep 三按钮；末集 Next Ep 置灰。
+5. 精选评论卡复用 `CommentController`，无评论隐藏；VIP/总评论数字段缺失时隐藏。
+
+## 三、TDD 顺序
+
+1. 详情 widget 测试：hero 16:9、CTA 行、简介展开、集数 chips、2 列剧集卡。
+2. 详情实现：先复用现有 `DramaDetailLogic`，只重排视图和控件。
+3. 播放器 widget 测试：卡片模式结构、三按钮行、进度条颜色/thumb、末集禁用。
+4. 播放器实现：新增卡片布局，保留原全屏 feed；复用 ticket/session/queue。
+5. 回归：PiP、票据错误、进度、收藏、下载、举报、评论、自动连播。
+
+## 四、数据缺口
+
+| 设计字段 | 模型状态 | 处理 |
+| --- | --- | --- |
+| coverUrl | 无（只有 posterUrl） | hero 使用 posterUrl |
+| 评分 | 无 | 隐藏 |
+| 完结状态 | 无 | 隐藏 |
+| Top 排名 | 无 | 隐藏 |
+| Trailer/4K | 无 | 隐藏 |
+| VIP | 无 | 隐藏 |
+| 剧级点赞/评论总数 | 无 | 只显示文案/已加载数量，不伪造 |
+| 场景标签 | 无 | 隐藏 |
+| 集数范围 | 无 | 显示 All chip |
+| 倍速能力 | 无播放速率接口 | 显示 1.0x，不伪造切换能力 |
+
+## 五、风险
+
+- 卡片播放器切换全屏时复用同一 `PageController`；只在二者之一挂载，避免控制器绑定两个 PageView。
+- 自动连播依赖 PageController 动画，卡片模式保留 PageView 作为视频底层。
+- 评论卡新增一次评论首屏请求；无评论/失败时直接隐藏，不影响播放。
+- 详情页 hero、2 列剧集卡在小屏下需自适应缩略图宽度，避免溢出。
+
+## 六、门禁与 Git
+
+```bash
+dart analyze lib test
+flutter test
+flutter build apk --debug
+```
+
+完成后 `--no-ff` 合并回 `develop` 并 push；作者/提交者
+`Zhou Weidong <502333560@qq.com>`。真机验收由用户执行。
+

docs/plans/2026-10-19-K26.md

@@ -0,0 +1,83 @@
+# K26 计划：客户端按「移动端设计预览」校正六屏
+
+日期：2026-10-19
+基线：`ReelShort/develop` = `eefabb6`
+分支：`feature/flutter-k26-mobile-preview`
+
+## 一、范围
+
+按本地 `/Users/jianghaifeng/Desktop/ReelShort/docs/移动端设计预览.html`
+校正六屏：首页、发现、详情、播放器、我的、登录。该文件优先于此前 Stitch screens。
+
+保留 K24 的 Outfit / Plus Jakarta Sans、Provider 业务逻辑、现有接口与数据模型。
+不改后端、Web、specs、main。
+
+## 二、Token
+
+| 语义 | 值 |
+| --- | --- |
+| primary | `#FF5B3D` |
+| secondary | `#9278EA` |
+| background | `#0B0C10` |
+| nav | `#0D0D11` |
+| card | `#1B1C21` |
+| cardAlt | `#1C1D21` |
+| input / quick | `#25252A` / `#202126` |
+| gold card | `#201B1E` |
+| text / dim / accent | `#E6E1E3` / `#D2CDD0` / `#FFA490` |
+| border | `white 8%` |
+
+圆角：卡片 10-14、按钮 9、chips 20、封面 10。
+新增紧凑字号 token（9/10/11/12/13/14/15/18/20）与按钮高度 token（28/32/34/40/44）。
+
+## 三、六屏
+
+1. 首页：剧名 + 搜索/菜单；Like/Comment/Share/Favorite 四互动；底部玻璃卡
+   （tags、第 x/共 y 集、13px 标题、34px 追剧/选集）；去掉 HOT/Season/Follow。
+2. 发现：Logo + 发现 + 搜索/头像；36px 搜索框；分类 chips；52×66 Continue Watching；
+   4 个 62px 快捷入口；热门短剧标题 + 2 列封面高 120 网格。
+3. 详情：190px hero + 28px 返回；N 集、18px 标题、11px 简介、40px 开始观看、选集 chips；
+   收藏/下载/举报收进更多；删除统计行、预览卡与底部 Tab。
+4. 播放器：全屏；46px 顶栏；中心 52px 播放 + 1.0x；3px 进度；32px 选集/评论/下一集；
+   一条精选评论卡；无右侧互动栏；下载/PiP/互动收进更多。
+5. 我的：顶部 Logo + 我的 + 搜索/头像；48px 用户行；金币卡；Continue Watching；
+   历史/收藏/喜欢；语言行；底部 3 Tab。
+6. 登录：64px 渐变 Logo + 水果短剧 + 副标题；Google/手机号/邮箱三个 44px 入口；
+   Google/手机号置灰提示即将开放，邮箱进入 K21 表单；底部法律文案。
+
+## 四、TDD 顺序
+
+1. Token / AppDimens / GlassPanel 测试。
+2. 首页 overlay 结构与底部导航测试。
+3. 发现页搜索、Continue Watching、快捷入口、2 列网格测试。
+4. 详情页 190px hero、40px CTA、选集 chips 测试。
+5. 播放器全屏顶栏、三按钮、精选评论测试。
+6. 我的页用户行、金币卡、Continue Watching、语言行测试。
+7. 登录入口与邮箱二级表单测试。
+8. 回归播放、进度、收藏、下载、PiP、票据错误、评论与导航。
+
+## 五、数据缺口
+
+- 剧级点赞/评论数、已完结、Top 排名、VIP、评分、场景标签无模型字段：隐藏。
+- Continue Watching 仅有 `episodeId/position/duration`；集号能从剧集列表匹配时显示。
+- 金币余额与 Google/手机号登录后端未就绪：金币显示 0，Google/手机号入口提示即将开放。
+- 剧集时长只有 `durationSec`；缺失则不显示。
+
+## 六、风险
+
+- 六屏同时调整会触碰大量既有 widget 测试；只改视觉/布局与入口，不改业务逻辑。
+- 登录页改成入口页后，K21 邮箱表单测试需要先点击邮箱入口；表单本身与认证逻辑保持不变。
+- 播放器仍复用 ticket/PlaybackSession/PlaybackQueue；只替换非首页的 overlay。
+- 卡片圆角与按钮高度变化可能影响小屏布局，用 320×568、360×720、390×844 回归。
+
+## 七、门禁
+
+```bash
+dart analyze lib test
+flutter test
+flutter build apk --debug
+```
+
+完成后 `--no-ff` 合并回 `develop` 并 push；作者/提交者
+`Zhou Weidong <502333560@qq.com>`。真机验收由用户执行。
+

docs/plans/2026-10-20-K28-ui-wireframe.md

@@ -0,0 +1,139 @@
+# 2026-10-20 K28 客户端 UI 重构（按简图）
+
+> 来源：用户 2026-10-19 提供的 5 屏 + 4 面板手绘简图。
+> 原则：先出 UI，再划分功能任务；本批不改后端契约、不伪造接口、不放假按钮的“可用”承诺。
+> 设计语言沿用现有深色主题（Obsidian Flare），简图只定结构与层级。
+
+## 一、信息架构
+
+底部 4 Tab：
+
+| Tab | 页面 | 说明 |
+|---|---|---|
+| 首页 | `home` | 浏览型首页（Banner + 继续观看 + 热门漫剧） |
+| 剧场 | `theater` | 分类 + 语言筛选 + 两列剧库 + 搜索 |
+| 创作 | `create` | AI 制作 / 上传发布 两个入口 |
+| 我的 | `mine` | 账户、金币、会员、菜单 |
+
+播放页改为**推入式全屏页**（保留现有 `PlayerPage` 双模式能力），从首页 Banner/卡片、“继续观看”、剧场卡片、选集进入。
+
+## 二、分屏口径
+
+### 01 首页
+
+- 顶栏：搜索框（占满剩余宽度）+ 头像入口 + 星期文案（周一…周日）。
+- 频道 Tab：`热门 / 免费 / 新剧 / 榜单`，选中项主色下划线/胶囊；`榜单` 跳剧场榜单区。
+- Hero Banner：封面图、剧名（大字号 Outfit）、一句文案、底部页码点；自动轮播 + 手势切换。
+- 继续观看：标题行 + 「查看全部」；卡片含封面、剧名、`第 n 集 · 还剩 m 分钟`、播放按钮。
+- 热门漫剧：标题行 + 「查看更多」；两列卡片，封面 + 标题 + 题材 + `免费/集数` + 热度。
+- 无数据时用现有 `EmptyState`；下拉刷新可选（本批可不加）。
+
+### 02 剧场
+
+- 顶栏：搜索框 + 头像（与首页一致）。
+- 分类 chips：全部 + 服务端分类；语言 chips：全部语言 / 中文 / 印尼语 / 马来语 / 英语。
+- 两列剧卡：封面（原图比例铺满）、标题、题材、`免费` 角标、集数、热度。
+- 搜索：保留现有搜索输入与结果页；点击页面失焦。
+- 下拉刷新保留。
+- 语言筛选：当前接口未下发 `language`，本批只做 UI 选中态，不做数据过滤；在任务清单标注为后端缺口。
+
+### 03 创作
+
+- 标题「创作」+ 副标题「让故事成为漫剧」。
+- 卡 1「AI 制作」：从故事或想法开始，右侧箭头。
+- 卡 2「上传发布」：发布已完成的漫剧，右侧箭头。
+- 入口行为：本批统一进入「敬请期待 / 入驻申请」的诚实占位页，不做假上传、假 AI 生成。
+- 后续功能任务单列（见第五节）。
+
+### 04 我的
+
+- 头像 + 昵称 + 签名/身份文案 + 右侧箭头。
+- 三快捷入口：收藏/追剧、观看历史、本地下载。
+- 金币卡：`金币余额` + 数值 + `充值` 按钮（跳现有钱包/充值页）。
+- 会员卡：`开通会员，解锁更多精彩内容`（跳现有 VIP 页；无 C 端商品时展示“暂未开放”）。
+- 菜单：我的作品、创作者中心、消息通知（支持红点）、设置、帮助与反馈。
+- 未登录：头像区显示登录入口，金币/会员/菜单保持可点但需登录。
+
+### 05 竖屏播放
+
+- 顶栏：返回、更多（右上）。
+- 右侧互动 rail：点赞（含数量）、评论（含数量）、收藏、分享。
+- 底部：剧名、`第 n 集`、题材标签 + `关注`、简介、进度条 + `当前/总时长`、`选集`、`更多`。
+- 中心播放按钮：仅暂停时显示（已定口径）。
+- 清屏：保留现有清屏/退出清屏与“清屏状态跨集保持”。
+
+### 面板
+
+1. **选集**：标题「选集」+ 剧名 + `共 n 集` + 关闭；6 列等宽网格，当前集主色，锁定集显示锁图标，点击切集。
+2. **评论**：标题 `评论 (n)` + 关闭；列表项（头像、昵称、时间、内容、点赞数、回复）；底部输入框 + 发送。
+3. **更多操作**：倍速（当前值）、清晰度（自动）、下载到本地、文字大小、投诉；行尾箭头/当前值。
+4. **内容解锁**：金币解锁、看广告解锁、查看会员内容三条；底部说明「具体方式以作品而定」；仅展示可行入口，不可用项明确禁用/说明。
+
+## 二·五 视觉风格 v2（浅色暖橙，2026-10-20 用户指定）
+
+> 用户提供两张参考图（剧场页、竖屏剧集页），以此为准；K28 各屏不再沿用深色主题。
+
+### 色板
+
+| 用途 | 值 |
+|---|---|
+| 页面背景 | `#FFF8F0`（顶部带 `#FFE9D6` 暖色渐变） |
+| 卡片/弹层 | `#FFFFFF` |
+| 主色（按钮/选中/图标） | `#FF7A1A` |
+| 主色渐变（中央按钮） | `#FF9A3D → #FF6A00` |
+| 主文字 | `#1F1B16` |
+| 次要文字 | `#8C837B` |
+| 弱文字/占位 | `#B3AAA1` |
+| 分割线/描边 | `#F0E4D6` |
+| 粉色角标底 | `#FFE3EC`（文字 `#FF6A8A`） |
+| 深色角标（锁定数） | `#33000000` + 白字 |
+
+### 组件
+
+- 圆角：卡片 16、封面 16、弹层 20、chips 999（胶囊）、按钮 999。
+- 阴影：`0x14FF8A3D`，blur 18，y 6；卡片不使用重描边。
+- 分类 chips：选中为橙色实心 + 白字；未选中为白底 + 深色字，间距 10。
+- 剧卡：大封面（原图比例或 3:4）、左上「桃花源」粉色胶囊、右上锁图标 + 数量、封面右下「全 24 集 / 大结局」米色胶囊、标题 15–16 粗体、副行「更新至 18 集 · 09-04」12px 灰字、右下橙色圆形「+」。
+- 底部导航：白/米色毛玻璃，**保持 4 槽（首页 / 剧场 / 创作 / 我的）**，选中图标与文字为橙色；参考图中间的橙色「+」不实现。
+- 播放/剧集页：大标题 24 粗体 + 橙点、副标题 14 灰、右侧「…」与圆形按钮；Hero 大图 20 圆角 + 右上题材胶囊 + 分页点；下方横向剧集卡（第 01 集 初遇 / 更新中胶囊）。
+
+### 落地方式
+
+1. 先改 `AppColors/AppTheme/AppDimens` 全局 token，使现有组件整体切换为浅色暖橙。
+2. `AppBottomNav` 保持 4 项（首页/剧场/创作/我的），只做视觉换肤；不新增中央按钮/`nav-center-action`。
+3. K28-A1 先完成结构；样式统一由 K28-S 批次落地，后续 A2/B/C 直接使用新 token。
+
+## 三、复用与约束
+
+- 底部导航复用 `AppBottomNav`（需支持 4 项）。
+- 主题色/字号沿用 `AppColors/AppDimens`；标题 Outfit、正文 Plus Jakarta Sans。
+- 所有新增文案走 l10n（en/zh/id），禁止硬编码。
+- 所有手写 Dart 首行 `// Author: fruit.com.cn`；public 类/方法有文档注释。
+- Key 约定：`tab-home` / `tab-theater` / `tab-create` / `tab-mine`；`home-channel-*`；`theater-language-*`；`create-ai` / `create-upload`；`mine-wallet` / `mine-vip`；播放面板沿用 `player-episodes` / `player-comments` / `player-more-*` / `player-unlock-*`。
+- 单文件 ≤500 行：现有 `player_view.dart` 已超限，本批允许拆文件，不新增超大文件。
+
+## 四、实施批次（先 UI）
+
+| 批次 | 范围 | 验收 |
+|---|---|---|
+| K28-A | 4 Tab IA + 首页 + 剧场 | 4 Tab 可切换；首页/剧场结构与简图一致；既有播放/详情链路可达；`dart analyze` 零告警 + `flutter test` 全过 |
+| K28-B | 创作 + 我的 | 两个新页面结构与简图一致；金币/会员/菜单入口可达；未登录态正确 |
+| K28-C | 竖屏播放 UI + 四面板 | 播放页结构与简图一致；四面板可开合；选集切集/评论/倍速/清屏回归通过 |
+| K28-D | 回归与门禁 | l10n 三语齐全；全部测试通过；APK 构建成功；PROGRESS 留痕 |
+
+## 五、UI 之后的功能任务（待排期）
+
+1. 首页频道真实数据（热门/免费/新剧/榜单）与 Banner 数据补齐。
+2. 剧场语言筛选：后端 VO 下发 `language` 后再接真实过滤。
+3. 创作：AI 制作与上传发布需 C 端创作接口/资质（当前契约缺口，见 INBOX 顶部）。
+4. 金币充值：支付通道接入前保持入口隐藏或明确“暂未开放”。
+5. 会员：C 端会员商品/订阅接口缺失。
+6. 看广告解锁：需要广告平台账号、广告位 ID 与发奖校验接口。
+7. 播放清晰度：接口仅下发 `AUTO`，多清晰度需后端补齐。
+8. 文字大小：需全局字号偏好与持久化。
+
+## 六、风险 / 待确认
+
+- 简图为浅色线稿，实际落地为现有深色主题；如需要浅色版需另出视觉稿。
+- 「创作」两个入口在后端能力缺失时只做诚实占位，不做假流程。
+- 首页频道与周几文案涉及新增 l10n key，需三语翻译。

docs/plans/2026-10-20-ux-theatre-3tabs.md

@@ -0,0 +1,44 @@
+# UX 改造计划：红果式 3 Tab + 剧场九宫格 + 我的页减法
+
+日期：2026-10-20
+仓库：`C:\work\ReelShort`（Flutter）
+分支：`feature/ux-theatre-3tabs`（基线 `develop`）
+
+## 一、范围
+
+- 底部导航 4 → 3：推荐（播放）/ 发现（剧场）/ 我的。
+- 删除独立榜单 tab，榜单内容并入发现页。
+- 发现页改为剧场：顶部搜索框 + 分类九宫格 + 榜单区块 + 全部剧目网格。
+- 点击分类进入该分类剧目列表页。
+- 我的页只保留：继续观看、我的追剧、观看历史、下载、金币钱包、会员、设置。
+- 移除手动语言切换，App 跟随系统（默认印尼语/英语，系统中文仍可解析）。
+- 保留首页沉浸式上下滑播放。
+
+## 二、实施顺序
+
+1. 导航 4 → 3，删除 RankingPage 路由。
+2. 发现页重构：分类九宫格、分类剧目页、榜单区块、搜索；删除语言筛选与发现页续看。
+3. 我的页重构：删除语言行、内嵌历史/收藏/点赞列表、账号卡、通知入口；新增设置页承载通知与账号。
+4. 清理死代码：RankingPage、LocaleController 手动选择、CategoryController 筛选态、DiscoverLogic 续看/语言筛选。
+5. 更新测试与 l10n 断言，跑 `dart analyze lib test` + `flutter test`。
+6. `--no-ff` 合并回 `develop` 并 `git push origin develop`。
+
+## 三、风险与对策
+
+- 玩家页从 My/Discover 返回依赖 action 枚举：保留 home/discover/resume 必要动作，删除 watchlist/detail 等不再产生的动作。
+- 设置页承载账号卡与通知，避免删除入口后留下死路由。
+- 分类九宫格点击后进入独立列表页，避免全局筛选态残留。
+- 测试大量断言 4 Tab/语言行/内嵌列表；按新 UX 重写对应断言，不改播放链路。
+- 参数 ≤5：Discover/My 页使用 callbacks 聚合对象，页面 constructor 保持 ≤5 参数。
+
+## 四、门禁
+
+```bash
+dart analyze lib test
+flutter test
+```
+
+## 五、待确认
+
+- 系统语言为中文时是否仍显示中文：本计划保留系统中文解析，仅移除手动切换入口。
+- 通知功能保留但收进设置页；若要求彻底删除通知功能，需要另行删除 Notice 客户端链路。

docs/plans/2026-10-21-K100-episode-batch-upload.md

@@ -0,0 +1,26 @@
+# K100 后台剧集多选上传（分片 + 断点续传 + 批量建集）
+
+> 日期：2026-10-21  
+> 范围：仅 `ReelShortWeb`；不改 FruitServer 后端、不改 ReelShort 客户端、不改接口契约。
+
+## 目标
+
+剧集管理页「批量上传」：多选视频 → 队列分片上传（文件并发 2 / 分片并发 3）→ 单项与字节加权总进度 → 失败隔离/可重试 → localStorage 断点续传 → 上传完成后批量创建分集。
+
+## 步骤
+
+1. 从 `develop` 拉 `feature/episode-batch-upload`。
+2. 新建 `src/views/contentManagement/upload/uploadSessions.ts`：`reel_upload_sessions` 读写/过滤/清理。
+3. 新建 `useUploadQueue.ts`：状态机、文件并发泵、进度加权、pause/retry/remove、complete 写回 assetId/url、挂接 session。
+4. 新建 `UploadTaskRow.vue` / `BatchUploadDialog.vue` / `CreateEpisodesDialog.vue`。
+5. `EpisodeManagementView.vue` 仅加「批量上传」入口，保留原单文件上传。
+6. `zh-CN.ts` / `en.ts` 补齐文案；白名单 mp4/mov/mkv/webm；超限标红不入队；`beforeunload`。
+7. 门禁：`pnpm lint:eslint` + `pnpm build:dev`。
+8. 提交 `feat(admin): 剧集多选分片上传与断点续传` → `--no-ff` 合回 `develop` 并 push。
+
+## 风险 / 待确认
+
+- 续传需用户重新选择本地文件才能匹配；换机器/改名无法自动续传（产品已接受）。
+- 暂停不 abort 进行中分片，已在传任务会跑完再停派发。
+- `EpisodeManagementView.vue` 存量已超 500 行，本轮只加入口，不整体拆旧编辑器。
+- 手工联调（多选/暂停/刷新续传/建集）由 PM 在 8080+3005 复核，本轮不操作真机、不 kill 已运行端口。

docs/plans/2026-10-21-K85-interaction-count.md

@@ -0,0 +1,46 @@
+# K85 收藏数 / 评论数实时更新实施计划
+
+## 目标
+
+修复收藏数、评论数在列表、播放页和详情页不实时更新的问题，并让服务端收藏计数与关系数据保持一致。
+
+## 前置结论
+
+根因已由任务书确认，不再重复排查：
+
+- 收藏关系写入/删除时没有同步维护 `drama.favorite_count`。
+- 客户端首页收藏未复用现有计数增量逻辑。
+- 评论面板关闭后没有重新查询评论总数。
+- 详情页收藏切换后没有本地收藏数增量。
+
+## A. FruitServer
+
+1. `DramaService` 新增原子收藏计数调整方法，参考现有点赞计数实现。
+2. `FavoriteService` 在收藏、取消收藏、批量取消时按实际删除/插入结果同步增减，避免重复操作导致漂移。
+3. 新增一次性 `sql/backfill_favorite_count.sql`，从 `user_favorite` 回填现有收藏数，不在应用启动时自动执行。
+4. `AppCommentController` 新增匿名评论总数接口，复用 `CommentService.countByDrama`。
+5. 补收藏同步维护、批量取消、评论计数接口测试。
+6. 门禁：JDK 21 下完整 `mvn test`。
+
+## B. ReelShort
+
+1. `CommentApi` / `CommentRepository` 新增评论总数查询，兼容数字和字符串两种 Long 返回。
+2. 播放器统一维护按剧评论数缓存；评论面板关闭后刷新，失败保留旧值。
+3. 首页 feed 收藏复用 `_toggleSave`，与全屏播放页共用收藏增量更新。
+4. 详情页收藏成功后本地显示收藏数增量，失败回滚，不修改 `Drama` 模型。
+5. 补评论计数解析、收藏增量、首页 rail 刷新测试。
+6. 门禁：`dart analyze lib test` 零告警、`flutter test` 全过。
+
+## 风险与处理
+
+- 并发收藏切换可能造成计数竞争：服务端使用 SQL 原子自增/自减，减法不低于 0。
+- 历史收藏数全为 0：提供一次性回填脚本，由验收环境显式执行。
+- 评论面板取消打开时仍刷新一次计数，用于获取匿名新增评论带来的总数变化；查询失败静默保留旧值。
+- 详情页只在收藏状态确实变化时调整本地增量，避免重复点击造成累计误差。
+
+## 合并与验收
+
+- FruitServer：`fix/favorite-comment-count`，`--no-ff` 合回 `develop` 并推送。
+- ReelShort：`fix/interaction-count-refresh`，`--no-ff` 合回 `develop` 并推送。
+- 作者统一 `Zhou Weidong <502333560@qq.com>`。
+- 不修改 specs 仓库，不执行真机安装；完成后等待用户验收。

docs/plans/2026-10-21-K86-comments-sheet.md

@@ -0,0 +1,59 @@
+# K86 评论面板按参考图重做实施计划
+
+## 目标
+
+仅调整 ReelShort 客户端评论面板和评论行视觉，使顶部标题、评论元信息、回复入口和底部输入区接近参考图；不修改后端接口、控制器数据逻辑或评论业务能力。
+
+## 范围
+
+- `lib/pages/player/widgets/drama_comments_sheet.dart`
+- `lib/pages/player/widgets/comment_tile.dart`
+- `test/comment/drama_comments_sheet_test.dart`
+- 必要的 PROGRESS 留痕
+
+## 实现计划
+
+1. 顶部栏
+   - 删除拖拽把手和剧名行。
+   - 左侧放置 44x44 向下箭头，保留 `player-comments-close`，点击关闭面板。
+   - 中间使用现有 `commentsWithCount` / `comments`，16px、w600、`AppColors.onSurface`，保留 `comment-count-label`。
+   - 右侧留空，保持标题视觉居中。
+
+2. 评论行
+   - 头像改为 40px，回复行 28px；文字区左间距 12。
+   - 昵称 12px muted、正文 16px cream、行高 1.4。
+   - 时间与回复入口组合为灰色元信息行，时间继续使用 `formatLocalizedDateTime`。
+   - 删除点赞按钮、心形图标与数字展示，控制器点赞逻辑保留但不绑定 UI。
+   - 举报/删除入口改为右上角 18px 的更多图标，保留 `comment-menu-{id}` 和现有菜单行为。
+   - 去除行间分隔线，调整上下留白为 12/14。
+
+3. 回复
+   - 展开/收起回复使用 12px muted 文本，前面增加 16x1 的 border 色短横线。
+   - 展开后的回复沿用相同评论行样式，并通过 40px 头像宽度加 12px 间距与正文对齐。
+
+4. 输入区
+   - 输入框改为 44px 高、22px 圆角、`AppColors.commentInput` 底色。
+   - 保留登录提示、回复态 banner、橙色 38px 发送按钮及 `comment-post` Key。
+   - 保持现有键盘避让和面板高度 clamp。
+
+5. 状态与交互
+   - 保留加载、错误、空态、待审核、展开回复、翻页、回复、删除、举报和发送逻辑。
+   - 保留登录闸、自动聚焦和登录后输入框聚焦行为。
+
+## 测试
+
+- 删除依赖 `comment-like-10` 的点赞展示用例。
+- 断言不存在任何 `comment-like-*` 按钮或心形计数。
+- 断言 `player-comments-close` 可关闭面板。
+- 断言标题居中、字号和字重符合规格。
+- 断言头像、正文、元信息、回复入口、输入框与发送按钮尺寸。
+- 保持既有评论分页、登录、发布、展开回复、删除和举报用例通过。
+
+## 门禁与 Git
+
+- ReelShort 从 `develop` 创建 `fix/comments-sheet-style`。
+- 提交：`fix(player): 评论面板按参考图重做`。
+- 作者：`Zhou Weidong <502333560@qq.com>`。
+- `--no-ff` 合回 ReelShort `develop` 并 push，不使用 force push，不执行 `git add -A`。
+- 门禁：`dart analyze lib test` 零告警、`flutter test` 全过。
+- 不安装真机；完成后等待用户验收。

docs/plans/2026-10-21-K86.21-composer-stable-inset.md

@@ -0,0 +1,46 @@
+# K86.21 评论输入浮层稳定定位实施计划
+
+## 目标
+
+修复 Android 收起评论输入键盘时，输入浮层因键盘收起动画中的瞬时 inset 被逐帧 `max` 抬高而向上跳动的问题。评论列表面板、输入内容和关闭规则保持不变。
+
+## 根因
+
+- `CommentComposerSheet.build` 每次重建都用 `math.max` 累积当前 effective keyboard inset。
+- IME 收起动画期间可能出现高于稳定值的瞬时 inset，累计后永久抬高 `_pinnedKeyboardInset`。
+- 面板布局随后按更高的 pinned 值重新定位，造成输入浮层向上跳一小段。
+
+## 范围
+
+- ReelShort `lib/pages/player/widgets/comment_composer_sheet.dart`
+- ReelShort `test/comment/drama_comments_sheet_test.dart`
+- FruitServer `docs/plans/PROGRESS.md`
+
+## 实现计划
+
+1. 移除 `build` 中逐帧更新 `_pinnedKeyboardInset` 的逻辑，新增键盘可见状态和 80ms 稳定捕获 Timer。
+2. effective inset 从 0 变为正数时启动 Timer；Timer 触发时只读取一次当前 inset，并取整后写入 pinned。
+3. 键盘持续可见期间，后续 inset 变大或变小都不更新 pinned；inset 归零只取消 Timer 并重置可见状态，下一次弹起可重新捕获。
+4. pinned 上限为屏幕高度的 60%；非有限值、负值或超过上限的异常值忽略，保证 pinned 不小于 0。
+5. 保持 `Positioned(bottom: 0)`、白色 Material 铺到屏幕底部及 `Padding(bottom: pinned)` 布局，不使用位移或回落动画。
+6. 返回键/IME 下箭头只收键盘；透明外部点击和发表成功仍为关闭入口。
+
+## 测试计划
+
+- 先新增失败测试：2200 高视口模拟 `0 → 1100（稳定）→ 1150（收起瞬时峰值）→ 600 → 0`，断言 1100 捕获后输入浮层 top、bottom、高度均保持不变。
+- 运行旧实现确认红灯，记录实际偏移。
+- 新实现后运行定向测试、完整评论面板测试文件、`dart analyze lib test` 和全量 `flutter test --no-pub`。
+
+## 风险与处理
+
+- 80ms 可能早于极慢 IME 动画结束；按任务要求采用固定稳定窗口，不在后续可见阶段继续累计。
+- 超过屏幕 60% 的异常值被忽略后，需等下一次 0 → 正数弹起再捕获，避免错误定位。
+- Timer 在 dispose 时取消，避免 Overlay 关闭后回调访问已卸载 State。
+
+## Git
+
+- ReelShort 从 `develop` 创建 `fix/composer-stable-inset`。
+- 提交：`fix(player): 固定评论输入浮层位置避免收键盘跳动`。
+- 作者：`Zhou Weidong <502333560@qq.com>`。
+- `--no-ff` 合回 `develop` 并 push，不使用 force push，不执行 `git add -A`。
+- FruitServer 追加 PROGRESS 留痕；不安装真机，完成后等待用户验收。

docs/plans/2026-10-21-K86.22-composer-safearea.md

@@ -0,0 +1,45 @@
+# K86.22 评论输入浮层去除底部安全区位移实施计划
+
+## 目标
+
+修复 Android 收起评论输入键盘后，`SafeArea` 引入底部手势条 padding，导致输入区上移约 48px 的问题。输入区位置只由固定 `_pinnedKeyboardInset` 决定，键盘收起前后保持像素级一致。
+
+## 根因
+
+- 输入面板 Material 内使用 `SafeArea(top: false)`。
+- 键盘可见时系统导航栏被 IME 覆盖，`MediaQuery.padding.bottom` 为 0。
+- 键盘收起后手势条 padding 恢复，`SafeArea` 自动追加约 48px 底部内边距，把输入区顶高。
+- K86.19 的白色实底和固定 12px 内容内边距本身正常，问题仅来自额外安全区。
+
+## 范围
+
+- ReelShort `lib/pages/player/widgets/comment_composer_sheet.dart`
+- ReelShort `test/comment/drama_comments_sheet_test.dart`
+- FruitServer `docs/plans/PROGRESS.md`
+
+## 实现计划
+
+1. 面板 `SafeArea` 设置 `bottom: false`，不再消费 `MediaQuery.padding.bottom`。
+2. 保持 `Positioned(bottom: 0)`、白色 Material 铺到屏幕底部、顶部圆角 20。
+3. 键盘区域继续由内部 `Padding(bottom: _pinnedKeyboardInset)` 决定，内容区底部保持固定 12。
+4. 透明外部点击或发表成功仍为关闭入口；返回键/IME 下箭头只收键盘。
+
+## 测试计划
+
+- 先新增失败测试：视口 390×844，键盘弹起时 `viewInsets.bottom=180`、`padding.bottom=0`，记录输入框全局矩形。
+- 收起键盘时同时设置 `viewInsets.bottom=0`、`padding.bottom=48`，断言输入框 top、bottom、height 偏移均小于 0.1。
+- 旧实现预期因 SafeArea 多出 48px 而失败；修复后运行完整评论面板测试、静态分析和全量 Flutter 测试。
+
+## 风险与处理
+
+- 关闭底部 SafeArea 后，输入内容依赖固定 12px 底部内边距；与 K86.19 白色实底填充一致，不再叠加系统手势条。
+- 面板本身仍延伸到屏幕底部，视觉圆角和白底不受影响。
+- 不改 KeyboardInsetNotifier、pinned 稳定捕获、关闭规则或评论列表布局。
+
+## Git
+
+- ReelShort 从 `develop` 创建 `fix/composer-safearea`。
+- 提交：`fix(player): 去除评论输入面板安全区导致的收键盘位移`。
+- 作者：`Zhou Weidong <502333560@qq.com>`。
+- `--no-ff` 合回 `develop` 并 push，不使用 force push，不执行 `git add -A`。
+- FruitServer 追加 PROGRESS 留痕；不安装真机，完成后等待用户验收。

docs/plans/2026-10-21-K87-pull-to-refresh-hold.md

@@ -0,0 +1,47 @@
+# K87 下拉刷新完成后回弹实施计划
+
+## 目标
+
+将全局 `AppPullToRefresh` 改为刷新完成前保持下拉高度：松手达到阈值后内容停在 56px，显示“正在刷新”，`onRefresh` 完成后再用 200ms easeOut 回弹到 0。
+
+## 根因
+
+- 当前下拉位移主要由 `BouncingScrollPhysics` 的系统 overscroll 提供。
+- 松手后滚动位置立即执行系统回弹，组件只保留一个小指示器。
+- 刷新期间没有独立的内容保持位移，因此无法维持下拉状态。
+
+## 范围
+
+- ReelShort `lib/core/widgets/app_pull_to_refresh.dart`
+- ReelShort `test/core/app_pull_to_refresh_test.dart`
+- FruitServer `docs/plans/PROGRESS.md`
+
+## 实现计划
+
+1. 将 `AppPullToRefresh.physics` 从 Bouncing 改为 Clamping，阻止系统 overscroll 自行产生内容位移。
+2. 使用 `AnimationController` 和 `Transform.translate` 统一控制内容位移；pull/armed 使用当前拖动距离，refreshing 固定 56，完成后回 0。
+3. 松手达到阈值后，200ms easeOut 将当前距离过渡到 56；刷新期间忽略滚动通知并通过 `IgnorePointer` 阻止重复下拉。
+4. `onRefresh` 完成后以 200ms easeOut 回到 0；指示器透明度跟随位移回弹淡出，结束后状态为 idle。
+5. 检查全部 11 个使用方均传入 `AppPullToRefresh.physics`，保证全局组件行为一致。
+
+## 测试计划
+
+- 使用挂起的 `Completer` 模拟刷新未完成。
+- 松手瞬间断言内容仍高于 hold，200ms 后稳定为 56，再等待 300ms 仍保持 56。
+- 断言刷新状态显示 `CircularProgressIndicator` 与 `Refreshing…`。
+- 刷新中再次下拉，断言 `onRefresh` 调用数仍为 1、offset 仍为 56。
+- 完成 `Completer` 后断言 offset 回到 0、刷新指示器消失。
+
+## 风险与处理
+
+- 改为 Clamping 后不再依赖平台 overscroll 提供下拉视觉；内容位移完全由组件控制，避免双倍移动。
+- 刷新期间阻止列表交互，避免用户手势破坏保持高度。
+- 组件卸载时动画控制器会取消动画；异步刷新完成后仅在 mounted 时执行回弹收尾。
+
+## Git
+
+- ReelShort 从 `develop` 创建 `feat/pull-to-refresh-hold`。
+- 提交：`feat(ui): 下拉刷新完成后才回弹`。
+- 作者：`Zhou Weidong <502333560@qq.com>`。
+- `--no-ff` 合回 `develop` 并 push，不使用 force push，不执行 `git add -A`。
+- FruitServer 追加 PROGRESS 留痕；不安装真机，完成后等待用户验收。

docs/plans/2026-10-21-K87.1-pull-refresh-freeze.md

@@ -0,0 +1,46 @@
+# K87.1 下拉刷新冻结位移实施计划
+
+## 目标
+
+修复刷新 pending 期间仍从松手距离回收到 56px 的视觉回弹。达到阈值后冻结当前下拉距离 D，刷新完成前 offset 不变化，完成后才用 200ms easeOut 回到 0。
+
+## 根因
+
+- K87 已将系统 physics 改为 Clamping，避免原生 overscroll 回弹叠加。
+- 但 `_refresh` 仍先执行 `_animateOffsetTo(_holdDistance)`，会把松手时的 D（例如 96）回收到 56。
+- 用户感知为“页面已经弹回去”，实际是组件自身在刷新开始时主动缩短 offset。
+
+## 范围
+
+- ReelShort `lib/core/widgets/app_pull_to_refresh.dart`
+- ReelShort `test/core/app_pull_to_refresh_test.dart`
+- FruitServer `docs/plans/PROGRESS.md`
+
+## 实现计划
+
+1. 保留 `AlwaysScrollableScrollPhysics(parent: ClampingScrollPhysics())`，系统不移动 overscroll 内容。
+2. 删除 `_holdDistance` 与刷新前的 56px 过渡动画。
+3. 达到阈值松手后立即进入 refreshing，AnimationController 保持当前 D；刷新期间滚动通知和手势均忽略。
+4. `onRefresh` 完成后再从 D 执行 200ms easeOut 回 0，指示器随 offset 淡出。
+5. 未达阈值松手时新增 `_retracting` 状态，执行 200ms easeOut 回到 0，不触发 `onRefresh`。
+
+## 测试计划
+
+- 达阈值测试：记录松手 offset D，挂起 300ms 后仍等于 D；刷新中重复下拉不改变 D、不增加调用。
+- complete 后断言 offset 回 0、指示器消失。
+- 未达阈值测试：松手后立即开始回弹，100ms 时 offset 介于 0 与 D 之间，最终回 0 且 `onRefresh` 未调用。
+- 断言 `AppPullToRefresh.physics.parent` 为 `ClampingScrollPhysics`。
+
+## 风险与处理
+
+- 保持 D 时下拉越高，内容下移越明显，但这是用户松手时的真实位置，刷新完成后才回收。
+- 未达阈值回弹期间通过 `_retracting` 忽略新滚动通知，避免动画目标被手势覆盖。
+- 不逐个页面改动，所有使用共享 physics 与组件的页面自动生效。
+
+## Git
+
+- ReelShort 从 `develop` 创建 `fix/pull-refresh-freeze`。
+- 提交：`fix(ui): 下拉刷新刷新期间冻结下拉位移`。
+- 作者：`Zhou Weidong <502333560@qq.com>`。
+- `--no-ff` 合回 `develop` 并 push，不使用 force push，不执行 `git add -A`。
+- FruitServer 追加 PROGRESS 留痕；不安装真机，完成后等待用户验收。

docs/plans/2026-10-21-K88-drama-type-feed.md

@@ -0,0 +1,51 @@
+# K88 内容类型、互动数据编辑与分类 Feed 实施计划
+
+## 目标
+
+- 后台短剧管理支持内容类型和互动数据编辑：收藏、点赞、热度可编辑，评论数实时统计只读。
+- 新增 `drama.drama_type`，取值为 `ANIME` / `LIVE`，默认 `LIVE`。
+- App 新增 `GET /app/feed`，支持 `ANIME,LIVE` 多选类型，不传类型时返回推荐全部。
+
+## FruitServer A
+
+1. 数据库
+   - 新增 `sql/migrate-k88-drama-type.sql`，只提交迁移文件，不执行数据库变更。
+   - `sql/schema.sql` 的 drama 建表语句补 `drama_type`，默认 `LIVE`。
+
+2. 后台管理
+   - `Drama`、`DramaSaveReqVO`、`DramaRespVO` 增加 `dramaType`。
+   - `DramaSaveReqVO` 增加可空 `favoriteCount`、`likeCount`、`heat`；服务层校验非负，`heat` 映射 `view_count`。
+   - create 默认内容类型 LIVE、互动数 0；update 仅覆盖请求非 null 的互动字段。
+   - 后台分页增加 `dramaTypes` 多选过滤，并保持 CommentService 批量回填评论数。
+
+3. App Feed
+   - `AppDramaCardVO` 增加 `dramaType`，现有 home/discover/detail 仅新增字段。
+   - `GET /app/feed` 支持 `types`、`cursor`、`size`；size 默认 20、最大 50。
+   - 排序为 `recommend_weight DESC NULLS LAST, view_count DESC, id DESC`。
+   - cursor 使用最后一条 drama id，服务端反查其 recommendWeight/viewCount/id，再按三元组做 keyset 查询，避免 offset 翻页重漏。
+   - 卡片复用现有 `toCards`，确保 preview、互动数、评论数与首页一致。
+   - 更新 `docs/api-phase1.md` 的 dramaType 与 `/app/feed` 契约。
+
+4. 测试
+   - `/app/feed`：全部、ANIME、ANIME+LIVE、游标翻页不重不漏。
+   - 后台 update：部分字段更新、heat 写 viewCount、负数与非法 dramaType 报错。
+
+## ReelShortWeb B
+
+1. 类型定义补齐 dramaType、favoriteCount、likeCount、commentCount、heat。
+2. 短剧列表增加内容类型筛选和标签列，播放量列改为热度，增加收藏/点赞/评论列。
+3. 编辑弹窗增加必填内容类型、互动数据区块；评论数只读。
+4. 不改审核、发布、删除逻辑。
+
+## 风险与处理
+
+- 推荐排序包含可空 recommend_weight，SQL 与 Java 条件必须显式处理 NULLS LAST。
+- 三字段排序不能只按 id 做 cursor，需以 cursor id 反查上一页最后一条的排序值。
+- 存量数据不主动修改，迁移默认 LIVE；数据库脚本由 PM 执行。
+- 全部改动只使用显式文件暂存，不执行 `git add -A`，不改 specs 与 Flutter 客户端。
+
+## 门禁与 Git
+
+- FruitServer：`mvn test` 全过；提交 `feat(content): 新增内容类型与首页分类 feed`；`--no-ff` 合回 develop 并 push。
+- ReelShortWeb：`pnpm ts:check`、`pnpm build:dev` 通过；提交 `feat(admin): 短剧列表展示并编辑互动数据`；`--no-ff` 合回 develop 并 push。
+- 作者统一 `Zhou Weidong <502333560@qq.com>`；各自 PROGRESS 追加 K88 留痕。

docs/plans/2026-10-21-K89-episode-like.md

@@ -0,0 +1,59 @@
+# K89 点赞/评论按集、收藏/热度按剧实施计划
+
+## 目标
+
+- 收藏、热度继续归属整部剧。
+- 点赞、评论归属具体剧集：新增 `drama_episode.like_count`，`content_like` 使用 `EPISODE` 目标。
+- App 卡片、详情、播放响应按当前集装配点赞/评论；后台短剧/剧集页提供对应汇总与只读展示。
+
+## FruitServer A
+
+1. 数据库
+   - 新增 `sql/migrate-k89-episode-like.sql`，只提交不执行。
+   - `sql/schema-phase1.sql` 的 drama_episode 增量字段补 like_count，默认 0。
+
+2. 分集点赞
+   - `DramaEpisode` 增加 likeCount；`EpisodeService` 提供原子增减与批量 SUM。
+   - `LikeService` 增加 `TYPE_EPISODE`，校验已上线剧集的已上线分集，切换时同步分集计数，返回该集最新值。
+   - 保留 DRAMA/COMMENT 点赞兼容。
+
+3. 分集评论
+   - `CommentService.countByEpisodes` 按 episode_id 批量分组统计未删除评论。
+   - `/app/comments/count` 增加可选 episodeId；传集数返回该集，只有 dramaId 时维持全剧兼容语义。
+
+4. App 装配
+   - 卡片 preview 集的 likeCount/commentCount 写入卡片；favoriteCount/viewCount 仍取剧。
+   - 详情 episodes[] 每项增加 likeCount/commentCount。
+   - 播放响应增加 episodeId 对应的 likeCount/commentCount。
+
+5. 后台
+   - EpisodeRespVO 增加本集 like/comment 与所属剧 favorite/heat；Controller.list 批量回填。
+   - EpisodeSaveReqVO 增加可空 likeCount，update 仅覆盖非 null，负数 BAD_REQUEST。
+   - DramaRespVO likeCount 改为分集 SUM，commentCount 保持全剧汇总；分页一次批量聚合避免 N+1。
+   - 更新 API 契约。
+
+6. 测试
+   - EPISODE 点赞 +1/-1、不越界、目标不存在。
+   - App 卡片按 preview 集、剧级 favorite/heat。
+   - 后台分集列表计数与剧级收藏/热度。
+   - 短剧分页 likeCount 为分集汇总。
+
+## ReelShortWeb B
+
+1. EpisodeItem / EpisodeSaveData 增加对应互动字段。
+2. 剧集表格增加本集点赞、评论，以及所属剧收藏、热度列。
+3. 编辑弹窗增加本集点赞输入和评论只读；“按集实时统计”。
+4. 短剧管理保持收藏/热度可编辑，点赞/评论展示为后端只读汇总。
+
+## 风险与处理
+
+- 存量 `drama.like_count` 保留不删，不回填分集；新展示以分集 SUM 为准。
+- App 评论数按 preview 集统计，只有 episodeId 为空的历史评论仍计入全剧汇总。
+- 评论/点赞接口保持匿名/登录既有安全语义，不新增第三方依赖。
+- 迁移脚本由 PM 执行；本地门禁不访问真实数据库。
+
+## 门禁与 Git
+
+- FruitServer：`mvn test` 全过；提交 `feat(interaction): 点赞与评论按集统计`；`--no-ff` 合回 develop 并 push。
+- ReelShortWeb：`pnpm ts:check`、`pnpm build:dev` 通过；提交 `feat(admin): 剧集列表展示分集互动数据`；`--no-ff` 合回 develop 并 push。
+- 作者统一 `Zhou Weidong <502333560@qq.com>`；禁止 `git add -A`；各自 PROGRESS 追加 K89 留痕。

docs/plans/2026-10-21-K91-watch-history.md

@@ -0,0 +1,114 @@
+# K91 后台观看记录独立菜单、评论分集展示与全部状态筛选
+
+## 目标
+
+- FruitServer 新增跨用户观看记录分页接口，并给后台评论补充短剧名、集号与集标题。
+- ReelShortWeb 新增「观看记录」独立页面，评论/举报状态筛选默认展示全部。
+- 迁移脚本只提交文件，不执行数据库变更；不改 specs 仓库和 Flutter 客户端。
+
+## 分支
+
+- FruitServer：`feat/k91-watch-history`，从 `origin/develop` 创建。
+- ReelShortWeb：`feat/k91-watch-history-page`，从 `origin/develop` 创建。
+
+## A. FruitServer
+
+### A1 观看记录分页
+
+1. 新增 `WatchHistoryQueryReqVO`，字段：
+   `pageIndex/pageSize/keyword/userId/dramaTitle/dramaId/episodeId/source/finished/startTime/endTime`。
+2. 新增 `AdminWatchHistoryVO`，返回用户、短剧、分集、进度、完成、来源、设备与观看时间。
+3. 新增 `WatchHistoryAdminService`，直接注入：
+   - `WatchHistoryMapper`
+   - `AppUserMapper`
+   - `DramaMapper`
+   - `DramaEpisodeMapper`
+4. 查询流程：
+   - `keyword` 先批量命中 `app_user.uid/nickname` 的 id；无命中直接空页。
+   - `dramaTitle` 先批量命中 `drama.title` 的 id；无命中直接空页。
+   - 精确 id 条件与模糊命中集合取交集。
+   - `finished` 在 SQL 层表达，允许区间两侧都落在 `duration_ms = 0` 等边界。
+   - 按 `watched_at DESC, id DESC` 排序。
+   - 对结果页的用户、剧、集各做一次批量查询后装配，禁止逐行查询。
+5. 新增 `WatchHistoryAdminController`，权限点 `watch-history:list`，保留旧用户详情观看流水接口。
+
+### A2 评论后台分集信息
+
+1. `CommentRespVO` 增加 `dramaTitle/episodeNo/episodeTitle`。
+2. 仅 `CommentService.adminPage` 对当前页批量补剧、集信息。
+3. `toRespList` 的 C 端路径保持不增加查询。
+
+### A3 SQL 与契约
+
+1. 新增幂等迁移 `sql/migrate-k91-watch-history-menu.sql`：
+   - 权限点 `1105 watch-history:list`
+   - 菜单使用 id `34`，挂 parent `15`
+   - `component=views/userManagement/WatchHistoryView`
+   - 超管角色权限与菜单关联
+2. 同步 `sql/data-phase1.sql`。
+3. 更新 `docs/api-phase1.md` §2.3、§2.5。
+
+### A4 测试
+
+- `WatchHistoryAdminServiceTest` 覆盖：
+  - 默认分页与排序
+  - keyword 用户命中
+  - dramaTitle 剧名命中
+  - finished 真/假 SQL 条件
+  - 时间范围
+  - 命中集合为空直接空页
+  - pageSize 上限收敛为 100
+- `CommentServiceTest` 覆盖后台页批量补齐剧名、集号、集标题。
+- 门禁：`mvn test` 全模块通过。
+
+## B. ReelShortWeb
+
+### B1 类型/API
+
+- 扩展 `WatchHistoryItem`：`userId/uid/nickname/episodeTitle`。
+- 扩展 `CommentItem`：`dramaTitle/episodeNo/episodeTitle`。
+- `appUser.ts` 新增 `pageWatchHistoryApi(params)`。
+
+### B2 观看记录页面
+
+- 新建 `src/views/userManagement/WatchHistoryView.vue`：
+  - 用户、短剧名称、来源、完成状态、时间范围筛选。
+  - 观看时间、用户、短剧、分集、进度、完成、来源、设备列。
+  - 10/20/50 分页。
+  - 复用 App 用户页的 `panel/console-toolbar/pagination/app-user-*` 视觉与格式化函数。
+
+### B3 评论/举报全部状态
+
+- 评论与举报状态首项增加 `{ value: '', label: '全部状态', tag: 'info' }`。
+- 两个筛选默认值改为空串，请求时空串转 `undefined`。
+- 评论表以「短剧 / 分集」替换短剧 ID 单列：
+  - 显示剧名与集号/集标题。
+  - 缺少剧名时回退短剧 id。
+  - 缺少集号时回退分集 id；历史 `episodeId=0` 显示未关联分集。
+  - 原始短剧 id / 分集 id 通过 tooltip 保留。
+
+### B4 门禁
+
+- `pnpm ts:check`
+- `pnpm build:dev`
+
+## 风险与待确认
+
+1. `watch_history` 是月分区表，现有索引为 `(user_id, watched_at)` 与
+   `(drama_id, watched_at)`，没有跨用户的全局 `watched_at` 索引。本次按要求实现跨用户时间排序，
+   不擅自新增索引；数据量增长后由 PM 评估是否增加全局观看时间索引。
+2. 用户/剧名模糊检索先取 id 集合，符合“命中为空不退化成全表”的要求；
+   超大关键词命中集合的批大小由后续实际数据量评估，本次不擅自加截断以免漏结果。
+3. 历史评论的 `episode_id=0` 不回填；后台显示“未关联分集”，原始 id 仍保留在 tooltip。
+4. 迁移脚本只写文件，不执行数据库；菜单落库由 PM 按发布流程执行。
+5. 任务书建议菜单 id `26`，但当前 `data-phase1.sql` 已将 `26` 用作“创作者中心”目录，
+   `27-30` 为其子菜单。为避免覆盖线上已有菜单树，本次使用下一个空闲 id `34`；
+   父级、路由、组件与权限点均不变。
+
+## 提交与合并
+
+- FruitServer 提交：`feat(admin): 新增观看记录分页与评论分集信息`
+- ReelShortWeb 提交：`feat(admin): 观看记录独立菜单与治理状态全部筛选`
+- 两仓库均 `--no-ff` 合回 `develop` 并 push。
+- 作者与提交者：`Zhou Weidong <502333560@qq.com>`。
+- 禁止 `git add -A`，所有文件逐项暂存。

docs/plans/2026-10-21-K92-report-target.md

@@ -0,0 +1,108 @@
+# K92 举报工单展示短剧名称与分集
+
+## 目标
+
+- `/admin/reports/page` 不再只返回 `targetType / targetId`，而是返回举报人、目标短剧与分集的展示信息。
+- Web 举报工单列表与处理弹窗使用同一份目标摘要，不再展示裸对象 ID。
+- 不改既有举报处理逻辑、评论列表接口、观看记录接口或数据库结构。
+
+## 分支
+
+- FruitServer：`feat/k92-report-target`，从 `origin/develop` 创建。
+- ReelShortWeb：`feat/k92-report-target-ui`，从 `origin/develop` 创建。
+
+## A. FruitServer
+
+### A1 返回模型
+
+新增 `com.fruitshorts.admin.vo.AdminReportRespVO`，包含：
+
+- 工单：`id/reasonCode/description/status/handleBy/handleAt/handleNote/createdAt`
+- 举报人：`reporterId/reporterNickname/reporterUid`
+- 目标：`targetType/targetId/targetSummary`
+- 剧集：`dramaId/dramaTitle/episodeId/episodeNo/episodeTitle`
+- 评论/用户：`commentContent/targetNickname/targetUid`
+
+### A2 查询和解析
+
+新增 `com.fruitshorts.admin.service.ReportAdminService`：
+
+1. 分页查询 `content_report`，条件与 `ReportService.page` 保持一致：
+   `status/targetType/reasonCode/reporterId` 均仅在有文本或非空时加入，空值返回全部；
+   排序保持 `id DESC`。
+2. 当前页批量查询：
+   - COMMENT 目标评论：一次查询，且必须包含逻辑删除记录，用于判断“评论已删除”。
+   - 评论与 DRAMA 目标剧：一次批量查询 `drama`。
+   - 评论目标分集：一次批量查询 `drama_episode`。
+   - USER 目标用户与全部 reporter：合并 id 后一次批量查询 `app_user`。
+3. 禁止逐行查询。
+
+`ContentCommentMapper` 增加显式批量查询方法，绕过 `@TableLogic` 的自动过滤；
+普通 `selectBatchIds` 仍保持原行为。
+
+### A3 摘要规则
+
+- COMMENT：
+  - 正常评论且剧存在：`剧名 · 第 N 集`，有集标题时追加 ` · 集标题`。
+  - 评论删除、逻辑删除、评论不存在或剧不存在：`评论 #targetId`。
+- DRAMA：
+  - 剧存在：剧名。
+  - 不存在：`短剧 #targetId`。
+- USER：
+  - 用户存在：`昵称（uid）`。
+  - 不存在：`用户 #targetId`。
+
+### A4 Controller 与文档
+
+- `ReportAdminController.page` 改为返回 `Result<PageResult<AdminReportRespVO>>`。
+- `handle` 继续调用原 `ReportService.handle`，不变更业务行为。
+- 更新 `docs/api-phase1.md` §2.5。
+
+### A5 测试
+
+新增 `ReportAdminServiceTest`，覆盖：
+
+- COMMENT / DRAMA / USER 三类摘要。
+- 评论集标题、举报人昵称/uid、目标用户昵称/uid。
+- 空筛选条件表示全部。
+- 评论逻辑删除和目标剧不存在时退化文案。
+- 验证按页批量查询，不产生 N+1。
+
+门禁：`mvn test` 全模块通过。
+
+## B. ReelShortWeb
+
+### B1 类型
+
+`ReportItem` 补齐后台新增字段，保留原 `targetId` 用于 tooltip 排查。
+
+### B2 治理页
+
+1. 「对象」列：
+   - 中文类型标签：评论 / 用户 / 短剧。
+   - 显示 `targetSummary`。
+   - tooltip 显示原始 `#targetId`，评论类型有内容时追加评论内容。
+2. 删除独立「对象ID」列。
+3. 「举报人」列显示昵称；无昵称回退 uid；再无回退 `#reporterId`。
+4. 处理弹窗「工单对象」显示类型标签 + `targetSummary`。
+
+### B3 门禁
+
+- `pnpm ts:check`
+- `pnpm build:dev`
+- 对改动文件执行定向 ESLint
+
+## 风险与说明
+
+1. 评论逻辑删除记录默认被 MyBatis-Plus 过滤；本次使用显式 mapper 查询识别，
+   不改变评论正常查询和删除行为。
+2. 已删除评论不展示正文，避免后台误读已删除内容；仍保留 `targetId` tooltip 便于排查。
+3. 目标关联数据已物理删除时按任务书使用 `评论 #id / 短剧 #id / 用户 #id` 退化。
+4. 本任务无数据库迁移，不改 specs 仓库和 Flutter 客户端。
+
+## Git
+
+- FruitServer：`feat(admin): 举报工单返回短剧与分集信息`
+- ReelShortWeb：`feat(admin): 举报列表展示短剧与分集`
+- 两仓库均 `--no-ff` 合回 `develop` 并 push。
+- 作者：`Zhou Weidong <502333560@qq.com>`；禁止 `git add -A`。

docs/plans/2026-10-21-K93-drama-multi-tag.md

@@ -0,0 +1,121 @@
+# K93 短剧类型与内容类型支持多选
+
+## 目标
+
+- 后台短剧基础信息中的「类型」「内容类型」改为至少选一项的多选。
+- 后台列表筛选、列表展示支持多分类与多内容类型。
+- App 分类分区和内容类型 feed 使用多标签字段做整词匹配。
+- 单值字段继续保留，兼容创作者中心、旧接口和现有 App 卡片。
+
+## 分支
+
+- FruitServer：`feat/k93-drama-multi-tag`，从 `origin/develop` 创建。
+- ReelShortWeb：`feat/k93-drama-multi-tag-ui`，从 `origin/develop` 创建。
+
+## A. FruitServer
+
+### A1 数据库
+
+- 新增 `sql/migrate-k93-drama-multi-tag.sql`：
+  - `drama.drama_types VARCHAR(32) NOT NULL DEFAULT ''`
+  - `drama.category_ids VARCHAR(255) NOT NULL DEFAULT ''`
+  - 从现有 `drama_type / category_id` 幂等回填。
+- 同步 `sql/schema.sql` 的 drama 建表字段。
+- 只提交迁移文件，不执行数据库。
+
+### A2 实体与 VO
+
+- `Drama`：增加 `dramaTypes/categoryIds` 逗号字符串。
+- `DramaSaveReqVO`：
+  - 新增 `List<String> dramaTypes`、`List<Long> categoryIds`，列表优先。
+  - 保留 `dramaType/categoryId` 单值兜底。
+- `DramaPageReqVO`：增加 `List<Long> categoryIds`，保留 `categoryId`。
+- `DramaRespVO`：增加 `dramaTypes/categoryIds/categoryNames`，旧单值字段语义不变。
+
+### A3 保存规则
+
+- 内容类型列表：normalize、去重、保持提交顺序；主值写第一个，完整列表写 `drama_types`。
+- 分类列表：过滤 null/非正数、去重、保持提交顺序；主值写第一个或 0，完整列表写 `category_ids`。
+- 列表为空时回退单值；单值也没有时保留当前值。
+- 创建时内容类型最终为空则默认 LIVE。
+- 非法内容类型继续返回 BAD_REQUEST。
+
+### A4 查询规则
+
+统一使用整词匹配：
+
+```sql
+(',' || column || ',') LIKE '%,value,%'
+```
+
+- 后台分页：
+  - `dramaTypes` 非空：`drama_types` token 匹配。
+  - `categoryIds` 非空：`category_ids` token 匹配。
+  - `categoryIds` 为空：回退 `category_id` 等值。
+- App `listPublishedFeed`：`drama_types` token 匹配。
+- App feed 游标：marker 的解析后 `dramaTypes` 与任一筛选类型相交才允许继续。
+- App `listPublished(categoryId)`：`category_ids` token 匹配，使多分类剧出现在每个分类分区。
+
+### A5 响应装配
+
+- 解析 `drama_types/category_ids`，空值回退单值。
+- `categoryNames` 按 categoryIds 顺序映射分类名。
+- 分类名缺失时回退 `genre`。
+- 现有 `dramaType/categoryId/category` 保持旧语义。
+
+### A6 文档与测试
+
+- 更新 `docs/api-phase1.md` 的后台保存/分页字段、App feed 和分类说明。
+- 增加服务测试覆盖：
+  - 多类型/多分类去重、顺序与主值写回。
+  - 单值兜底行为不变。
+  - 后台分页 token 条件。
+  - feed 多标签 marker 可被 ANIME/LIVE 命中。
+  - App 分类分区 token 条件。
+  - 响应多值解析和分类名顺序。
+- 门禁：`mvn test` 全模块通过。
+
+## B. ReelShortWeb
+
+### B1 类型
+
+- `DramaItem` 增加 `dramaTypes/categoryIds/categoryNames`。
+- `DramaSaveData` 增加 `dramaTypes/categoryIds`。
+- `DramaPageParams` 增加 `categoryIds`。
+
+### B2 表单
+
+- `form.categoryIds: number[]`，默认空数组。
+- `form.dramaTypes: string[]`，创建默认 `['LIVE']`。
+- 两个下拉均使用 multiple、collapse-tags、collapse-tags-tooltip、filterable。
+- 校验至少 1 项。
+- 编辑时优先数组，缺失回退单值。
+- 提交数组；`genre` 使用所选分类名以 ` / ` 拼接。
+
+### B3 筛选与表格
+
+- 分类筛选改为 `categoryIds: number[]`。
+- 内容类型筛选改为 `dramaTypes: string[]`。
+- 查询传数组，重置为空数组。
+- 类型列显示 `categoryNames.join(' / ')`，回退 `genre`。
+- 内容类型列逐个渲染标签，缺失时回退 `dramaType`。
+
+### B4 门禁
+
+- `pnpm ts:check`
+- `pnpm build:dev`
+- 对修改文件执行定向 ESLint
+
+## 风险与说明
+
+1. 新代码依赖迁移后的 `drama_types/category_ids` 列，发布顺序必须先执行迁移再启动新版本。
+2. 逗号列仅存储受控内容类型和数字 id，不允许用户输入；查询值均来自校验后的数组。
+3. 主值继续保留，降低旧客户端、创作者中心和旧接口的兼容风险。
+4. 本次不改 specs 与 Flutter 客户端，不执行数据库迁移，不操作真机。
+
+## Git
+
+- FruitServer：`feat(content): 短剧类型与内容类型支持多选`
+- ReelShortWeb：`feat(admin): 短剧类型与内容类型多选`
+- 两仓库均 `--no-ff` 合回 `develop` 并 push。
+- 作者：`Zhou Weidong <502333560@qq.com>`；禁止 `git add -A`。

docs/plans/2026-10-21-K94-home-type-feed.md

@@ -0,0 +1,126 @@
+# K94 首页内容类型 Feed 与无感切换
+
+## 目标
+
+- 首页顶栏「漫剧 / 真人剧 / 推荐」接入既有 `/app/feed`。
+- 每频道独立缓存与分页，切换时先同步展示缓存，再后台静默刷新。
+- 推荐首屏复用 `/app/home/feed` 打平数据，首次进入不额外转圈。
+- 无缓存频道只在黑色内容区显示小转圈，顶栏和底栏保持。
+- 滑动接近末尾自动加载下一页，并在播放器队列中原地追加。
+
+## 分支
+
+- ReelShort：`feat/k94-home-type-feed`，从 `origin/develop` 创建。
+- FruitServer 仅文档留痕，不改功能代码。
+
+## A. 数据层
+
+### A1 FeedPage
+
+新增 `lib/core/data/models/feed_page.dart`：
+
+- `dramas` 使用 `Drama.fromCardJson`。
+- `nextCursor` 兼容数字/字符串，空值或字符串 `"null"` 转为 null。
+- `hasMore` 读取布尔值。
+
+### A2 CatalogApi / Repository
+
+- `CatalogApi.feed({types, cursor, size})` 请求 `/app/feed`。
+- types 为空不传；非空用逗号拼接。
+- cursor 为空不传。
+- 返回结构异常抛 `ApiException(-1, '返回数据格式异常')`。
+- `CatalogRepository` 与 HTTP 实现增加 `fetchFeed`。
+- 所有测试 CatalogRepository 实现同步补齐方法。
+
+## B. 频道控制器
+
+新增：
+
+- `lib/pages/home/home_feed_channel.dart`
+- `lib/core/data/services/home_feed_controller.dart`
+
+`HomeFeedController` 使用每个频道独立状态：
+
+- dramas / cursor / hasMore / loaded / loadingMore / requestSeq
+- 当前 channel，默认 recommend
+- `seedRecommend`：同步写入推荐首屏，不发请求
+- `selectChannel`：同步切频道并 notify；无缓存加载第一页，有缓存静默刷新
+- `refreshCurrent`：失败保留旧列表
+- `loadMore`：cursor 追加，按 drama.id 去重
+- 所有响应必须同时满足“仍为当前频道 + requestSeq 最新”才应用
+- dispose 后停止 notify
+
+## C. 首页接入
+
+### C1 顶栏受控
+
+`HomeFeedHeader`：
+
+- 删除内部 tab 状态、comingSoon 和 SnackBar。
+- 新增 `channel` 与 `onChannelSelected`。
+- 三个 Key 保持不变。
+- refresh 内部 loading 状态保留。
+
+### C2 HomePage
+
+- `_HomePageState` 用 `CatalogController.repository` 创建 HomeFeedController。
+- Catalog 首次有数据时同步 seed recommend，随后在 post-frame 静默刷新 recommend。
+- `_HomeTabs` 使用稳定 Key，删除 `ValueKey(catalog.dramas.first.id)`。
+- 当前频道无数据时，保留 `_HomeTabs` 顶栏/底栏，body 用黑色背景 + 居中
+  `home-feed-channel-loading`。
+- 当前频道有数据时把频道列表传给 PlayerPage。
+- 刷新回调改 `refreshCurrent`；分页回调改 `loadMore`。
+
+### C3 PlayerPage / PlayerLogic
+
+- PlayerPage 增加 `feedChannel` 和 `onLoadMore`。
+- 同频道 feed 列表变化：`updateFeed(..., keepDramaId: currentDramaId)`。
+- channel 变化：`updateFeed(..., keepDramaId: null)`，回到新频道第 1 个。
+- PlayerLogic 保存 factory/coordinator，支持需要换内容时替换 PlaybackSession。
+- 空列表清空 queue/visibleIndices 并停止旧播放。
+- 当前剧仍在新列表且索引不变时，只扩展队列与 episode 列表，不重新 select。
+- PageView 在 `position >= visibleIndices.length - 3` 时调用 onLoadMore。
+
+## D. 测试
+
+新增 `test/core/data/services/home_feed_controller_test.dart`：
+
+- recommendation seed 不发请求
+- 三频道请求 types 分别为 `[] / [ANIME] / [LIVE]`
+- 缓存频道切换不清空并后台刷新
+- loadMore 追加去重、无更多后不再请求
+- 串包只接受最新频道请求
+- refresh 失败保留旧数据
+
+新增顶栏 widget 测试：
+
+- 三个 Key 存在
+- 点击分别回调 anime/live/recommend
+- 当前 channel 决定选中样式
+
+PlayerLogic 测试补充：
+
+- updateFeed 空列表安全
+- 追加列表保持当前剧
+- 切频道列表回到第 1 个
+
+门禁：
+
+- `dart analyze lib test`
+- `flutter test --no-pub`
+- `flutter build apk --debug`
+
+## 风险与控制
+
+1. PlaybackSession 的 episodes 是构造时绑定的列表；分页原地追加时会同步扩展该列表，
+   避免仅换 queue 而 session 仍指向旧列表。
+2. 换频道可能释放并重建播放器 session，这是内容源变化；静默刷新/分页在顺序不变时
+   不重新 select 当前剧，避免视频重启。
+3. 推荐 seed 只保证首帧立即有内容；后台 `/app/feed` 刷新失败时保留 seed。
+4. 首页仍在 `/app/home/feed` 首次加载期间使用既有启动页；频道切换不再触发整页 splash。
+
+## Git
+
+- 提交：`feat(home): 首页按内容类型分频道 Feed 并支持分页`
+- `--no-ff` 合回 ReelShort `develop` 并 push。
+- 作者：`Zhou Weidong <502333560@qq.com>`；禁止 `git add -A`。

docs/plans/2026-10-21-K95-feed-switch-loading.md

@@ -0,0 +1,100 @@
+# K95 修复首页频道快速切换卡 Loading
+
+## 目标
+
+- 频道请求完成后始终写回发起请求的频道缓存，不再因用户切走而丢失结果。
+- 每频道明确区分 loaded / loading / in-flight / error，无请求时绝不显示首屏转圈。
+- 首屏和刷新请求增加可注入的 10 秒超时兜底。
+- PlayerLogic 保证连续 feed 更新串行应用，只让最后一次 feed/session 生效。
+
+## 分支
+
+- ReelShort：`fix/k95-feed-switch-loading`，从 `origin/develop` 创建。
+- FruitServer 仅提交计划与 PROGRESS，不改功能代码。
+
+## A. HomeFeedController
+
+每个频道状态增加：
+
+- `List<Drama> dramas`
+- `String? cursor`
+- `bool hasMore`
+- `bool loaded`
+- `bool loading`
+- `bool loadingMore`
+- `String? lastError`
+- `int requestSeq`
+- `Future<bool>? inFlight`
+
+请求规则：
+
+1. 响应成功/失败都写入发起请求的频道状态。
+2. 只有频道仍为当前频道时才 `notifyListeners`。
+3. `requestSeq` 只比较同一频道的新旧请求，不参与跨频道过滤。
+4. 超时时间通过构造参数注入，默认 10 秒。
+5. `loadingFirstPage = !loaded && loading`。
+6. `selectChannel`：
+   - 有缓存：同步显示，未在飞时后台静默刷新
+   - 无缓存且正在飞：等待现有请求，不重复发
+   - 无缓存且有历史错误：自动重试
+   - 从未加载：发起首屏请求
+7. `refreshCurrent` 同样复用 in-flight，防止并发重复刷新。
+8. `loadMore` 失败保留 cursor/hasMore，允许下次继续重试。
+
+## B. PlayerLogic / PlayerPage
+
+### B1 Feed revision
+
+- PlayerLogic 增加 `int feedRevision`。
+- 每次 `updateFeed` 自增 revision，记录最新目标 feed。
+- `_replaceSession` 与 `selectEpisode` 在 await 后校验 revision，过期流程直接返回。
+- 连续 updateFeed 使用串行队列：当前应用结束后再应用最新待处理 feed。
+
+### B2 空队列与频道切换
+
+- 空 feed 不创建新 session，只清空 queue/visibleIndices 并停播。
+- 空 → 非空必须恢复 route visible，并 select 第 0 个。
+- 频道变化通过额外 reset 标志传入 `updateFeed`，即使 drama id 列表相同，
+  也重置到第 1 个并开始播放。
+
+### B3 PlayerPage 更新判定
+
+- `didUpdateWidget` 用 `feedDramas` 的 drama id 列表签名判断内容变化。
+- 同一列表的新 List 实例不重复 updateFeed。
+- 频道变化始终触发 updateFeed，并传 `resetToFirst=true`。
+
+## C. 测试
+
+### HomeFeedController
+
+- A 挂起 → B 成功 → A 成功：A/B loaded 均为 true，切回 A 立即有数据。
+- 同频道旧失败响应不得覆盖新成功响应。
+- 无在飞请求时 `loadingFirstPage=false`。
+- 永不返回的请求在注入超时后结束 loading、写 lastError、loaded=true。
+- 失败频道再次 select 自动重试。
+- loadMore 失败保留原有 hasMore/cursor。
+
+### PlayerLogic
+
+- 连续 5 次 updateFeed，最终 queue/session 对应最后一次列表。
+- 空 → 非空会创建 session 并 select 第 0 个。
+- 频道变化时相同 id 列表也回到第 1 个。
+
+门禁：
+
+- `dart analyze lib test`
+- `flutter test --no-pub`
+- `flutter build apk --debug`
+
+## 风险与控制
+
+1. 跨频道响应写回缓存必须与同频道 seq 校验同时存在；前者解决缓存丢失，后者解决同频道旧请求覆盖新结果。
+2. Player session 替换以 revision 作为唯一有效性判断，避免旧 close/select 回调干扰新 session。
+3. 空队列期间不创建 PlaybackSession；恢复非空时重新创建并起播。
+4. 不改后端、ReelShortWeb、specs；不安装或操作真机。
+
+## Git
+
+- 提交：`fix(home): 修复频道快速切换卡 loading`
+- `--no-ff` 合回 ReelShort `develop` 并 push。
+- 作者：`Zhou Weidong <502333560@qq.com>`；禁止 `git add -A`。

docs/plans/2026-10-21-K95.1-seamless-first-switch.md

@@ -0,0 +1,83 @@
+# K95.1 首次切换频道无感显示
+
+## 目标
+
+- 推荐首屏成功后后台预取 anime/live，避免第一次切换出现阻断式 loading。
+- 目标频道尚未返回时保留上一频道 PlayerPage 和视频画面，只叠加轻量 loading 遮罩。
+- 数据到达后原子替换为新频道 feed，并从第 1 个播放。
+
+## 分支
+
+- ReelShort：`fix/k95.1-seamless-first-switch`，从已包含 K95 的 `origin/develop` 创建。
+- FruitServer 仅文档留痕，不改功能代码。
+
+## A. HomeFeedController
+
+新增 `Future<void> prefetchChannels()`：
+
+- 仅处理 anime/live。
+- 只对 `!loaded && !loading` 的频道请求。
+- 请求结果写回对应频道缓存。
+- 不切换当前频道、不改变当前列表；仅目标恰为当前频道时 notify。
+- 失败只写 lastError，不向外抛。
+- 成功预取设置一次性 `skipNextRefresh`：首次切到该频道直接使用缓存，不立刻重复静默刷新；
+  后续再次切回仍执行正常缓存静默刷新。
+- 预取期间用户切换到该频道时等待已有 inFlight，不重复请求。
+
+## B. HomePage / _HomeTabs
+
+### B1 最近可见 feed
+
+`_HomeTabsState` 维护：
+
+- `List<Drama>? _visibleDramas`
+- `HomeFeedChannel? _visibleChannel`
+
+当前频道有数据时更新这两个值，并以当前频道渲染 PlayerPage。
+
+### B2 首次切换
+
+当前频道无数据且 loading：
+
+- 继续复用上一频道 `_visibleDramas/_visibleChannel` 渲染同一个 PlayerPage。
+- header 使用当前选中频道，但 PlayerPage.feedChannel 仍使用可见旧频道，避免队列更新。
+- Stack 上叠加 `IgnorePointer + ColoredBox(black26) + 24px spinner`，
+  Key 为 `home-feed-channel-loading`。
+- 数据返回后页面树保持同一层级的 PlayerPage，传入新 feed/channel，触发原子更新和第 1 个起播。
+- 空结果/失败后才切到「暂无剧目 / 重试」占位。
+
+### B3 Prefetch 触发
+
+推荐首屏后台刷新成功后 `unawaited(prefetchChannels())`。
+
+## C. 测试
+
+HomeFeedController：
+
+- prefetch 后首次 select anime 不再发请求。
+- prefetch 期间选择 anime 不重复请求。
+- prefetch 失败不影响推荐，也不向外抛。
+
+Widget：
+
+- 首切未缓存频道时 PlayerPage 仍在树中且出现 loading 遮罩。
+- 数据返回后遮罩消失并使用新频道 feed。
+
+门禁：
+
+- `dart analyze lib test`
+- `flutter test --no-pub`
+- `flutter build apk --debug`
+
+## 风险与控制
+
+1. 预取完成与 select 同时发生时，select 等待同一 inFlight，避免重复请求。
+2. 加载遮罩 IgnorePointer，不阻断顶栏/底栏交互。
+3. PlayerPage 在正常和 loading 状态都放在相同 Stack 层级，保证 State 不因分支切换被销毁。
+4. 不改后端、ReelShortWeb、specs；不安装或操作真机。
+
+## Git
+
+- 提交：`fix(home): 首切频道预取并保留播放画面`
+- `--no-ff` 合回 ReelShort `develop` 并 push。
+- 作者：`Zhou Weidong <502333560@qq.com>`；禁止 `git add -A`。

docs/plans/2026-10-21-K95.2-poster-transition.md

@@ -0,0 +1,54 @@
+# K95.2 首切频道用封面过渡
+
+## 目标
+
+- 首页频道切换后立即显示目标短剧封面，视频首帧就绪后再淡入。
+- 首页模式视频初始化期间不再显示 `player-session-loading` 大转圈。
+- 非首页播放器及票据加载状态保持现有行为。
+
+## 分支
+
+- ReelShort：`fix/k95.2-poster-transition`，从最新 `origin/develop` 创建。
+- FruitServer 仅写计划与 PROGRESS 留痕，不改后端功能代码。
+
+## A. PlayerVideoSurface
+
+- 新增可选参数 `posterUrl = ''`。
+- 未 reveal 时：
+  - `posterUrl` 非空显示 `RemoteImage(path: posterUrl, fit: BoxFit.cover)`，
+    Key 为 `player-video-poster`。
+  - `posterUrl` 为空继续显示黑色 `ColoredBox`，保留
+    `player-fallback-background` Key。
+- 视频 reveal 后继续通过现有 200ms `AnimatedOpacity` 淡入覆盖封面。
+
+## B. PlayerPage
+
+- `PlayerVideoSurface` 传入当前 `drama.posterUrl`。
+- `player-session-loading` 条件增加 `!widget.homeMode`：
+  - 首页模式视频初始化期间只显示封面。
+  - 非首页播放器继续显示原 session loading。
+- 首页 `player-ticket-loading` 不变。
+
+## C. 测试
+
+- 视频表面：非空 poster 显示 `player-video-poster`，空 poster 保留黑底且无封面。
+- 首页模式：视频未就绪时不出现 `player-session-loading`。
+- 非首页模式：视频未就绪时仍出现 `player-session-loading`。
+- 复跑既有播放器、首页相关测试。
+
+## 门禁
+
+- `dart analyze lib test`
+- `flutter test`
+- `flutter build apk --debug`
+
+## Git
+
+- ReelShort 提交：`fix(home): 频道切换用封面过渡`
+- `--no-ff` 合回 `develop` 并 push。
+- 作者 `Zhou Weidong <502333560@qq.com>`；禁止 `git add -A`。
+
+## 约束
+
+- 全程中文；不改后端、ReelShortWeb、specs。
+- 不安装或操作真机；完成后停住等待验收。

docs/plans/2026-10-21-K96-theater-feed.md

@@ -0,0 +1,86 @@
+# K96 剧场页服务端分类分页
+
+## 目标
+
+- `/app/feed` 支持按分类过滤，并与内容类型过滤叠加。
+- 剧场页「全部」展示全部已上线短剧，任意分类展示该分类全部已上线短剧。
+- 列表使用游标分页，切分类优先命中缓存，支持静默刷新、加载更多和失败重试。
+
+## 分支
+
+- FruitServer：`feat/k96-feed-category`
+- ReelShort：`feat/k96-theater-feed`
+
+## A. FruitServer
+
+1. `AppCatalogController.feed` 增加可选 `Long categoryId` 并传给服务层。
+2. `AppCatalogService.feed` 增加 `categoryId`，传给
+   `DramaService.listPublishedFeed`。
+3. `DramaService.listPublishedFeed` 增加 `categoryId`：
+   - 非空时使用 `DramaMultiTagSupport.applyCategoryIdTokens`
+     按 `category_ids` 整词匹配。
+   - 游标 marker 必须同时满足已上线、内容类型命中和分类命中，否则返回空列表。
+4. 补充服务层、控制器契约测试：
+   - 仅 categoryId。
+   - categoryId + types。
+   - 分类游标翻页。
+   - marker 分类不命中返回空。
+5. 更新 `docs/api-phase1.md` 的 `/app/feed` 参数和分类过滤说明。
+
+门禁：`mvn test` 全模块通过。
+
+## B. ReelShort
+
+### B1. API 与仓库
+
+- `CatalogApi.feed` 增加可选 `String? categoryId`，非空才拼 query。
+- `CatalogRepository.fetchFeed` 同步参数，HTTP 实现透传。
+
+### B2. TheaterFeedController
+
+- 新增 `lib/core/data/services/theater_feed_controller.dart`。
+- 按 `String? categoryId` 独立缓存状态：
+  `dramas / cursor / hasMore / loaded / loading / loadingMore / lastError /
+  requestSeq / inFlight`。
+- `select(id)` 同步切分类；有数据先渲染并静默刷新，无数据时加载。
+- `loadMore` 游标追加并按 id 去重；`hasMore=false` 停止。
+- `refreshCurrent` 失败保留旧数据；切换回失败分类自动重试。
+- 单请求 10 秒超时，响应写回发起分类，requestSeq 仅处理同分类顺序。
+
+### B3. 剧场接入
+
+- `DiscoverPage` 创建并持有 TheaterFeedController，初始请求「全部」。
+- 「全部」和分类 chips 的网格统一读取 `theater.dramas`，不再使用
+  `categories.feed.dramas` / `dramasOf`。
+- `_selectCategory` 同时更新 `DiscoverLogic.selectedCategoryId` 和
+  `theater.select(categoryId)`。
+- 滚动剩余不足 400px 时触发 `loadMore`；搜索模式不触发剧场分页。
+- 下拉刷新并行执行 `categories.load()` 和 `theater.refreshCurrent()`。
+- 无缓存首屏显示转圈；空、失败和重试保持既有剧场视觉。
+
+### B4. 测试
+
+- TheaterFeedController：
+  - 全部使用空 categoryId，分类使用对应 id。
+  - 缓存切回不闪烁。
+  - 分页去重、hasMore=false 停止。
+  - 失败保留旧数据、失败分类切回自动重试。
+- 剧场 widget：
+  - 点击分类请求对应 categoryId。
+  - 接近底部触发下一页。
+  - 搜索、下拉刷新与既有布局不回归。
+
+门禁：`dart analyze lib test` 零告警、`flutter test` 全过、
+`flutter build apk --debug` 成功。
+
+## Git
+
+- FruitServer 提交：`feat(app): 推荐流支持分类过滤`
+- ReelShort 提交：`feat(theater): 剧场分类列表服务端分页`
+- 两仓库作者：`Zhou Weidong <502333560@qq.com>`，禁止 `git add -A`。
+- 各自 `--no-ff` 合回 `develop` 并 push，两仓库 PROGRESS 留痕。
+
+## 约束
+
+- 全程中文；不改 specs、ReelShortWeb，不改首页 K94/K95 已交付逻辑。
+- 不安装或操作真机；完成后停住等待验收。

docs/plans/2026-10-21-K97-ios-comment-keyboard.md

@@ -0,0 +1,64 @@
+# K97 修复 iOS 评论输入弹窗键盘避让
+
+## 目标
+
+- iOS 评论输入浮层实时跟随 `MediaQuery.viewInsets.bottom`，确保输入框与发表按钮
+  位于键盘上方。
+- Android 保留既有 MethodChannel + 80ms 防抖 pinned 策略，不恢复底部 SafeArea，
+  避免键盘收起时 48px 抖动回归。
+- 聚焦、`TextInput.show` 兜底和发表成功提示逻辑不变。
+
+## 分支
+
+- ReelShort：`fix/k97-ios-comment-keyboard`，从最新 `origin/develop` 创建。
+- FruitServer 仅写计划与 PROGRESS 留痕，不改后端功能代码。
+
+## A. 平台区分
+
+- `_isAndroid = !kIsWeb && defaultTargetPlatform == TargetPlatform.android`。
+- Android：
+  - 继续监听 `KeyboardInsetNotifier`。
+  - 继续使用 80ms 防抖后的 `_pinnedKeyboardInset`。
+- iOS / 其他平台：
+  - 不读取 pinned/channel 值。
+  - `build` 中直接读取 `MediaQuery.viewInsetsOf(context).bottom`。
+  - inset 超过屏幕高度 60% 时按 0 处理，负值归零。
+
+## B. 面板布局
+
+- 面板主体使用 `AnimatedPadding`，只设置 bottom：
+  - `duration: 160ms`
+  - `curve: Curves.easeOutCubic`
+  - Android 使用 pinned 值。
+  - iOS / 其他平台使用实时 viewInsets。
+- Material 仍铺到屏幕底部，用于键盘收起后的实色填充。
+- Android 不包裹 SafeArea。
+- iOS / 其他平台包裹 `SafeArea(top: false)`，保留 home indicator 底部避让。
+
+## C. 测试
+
+- iOS + `viewInsets.bottom=300`：
+  - 键盘避让 AnimatedPadding 的 bottom 为 300。
+  - `comment-composer-post` 底边位于屏幕高度减 300 之上。
+- iOS + `viewInsets=0`：padding 为 0。
+- Android 既有 pinned/channel、焦点、弹出、关闭、发布用例保持通过。
+- 所有平台 override 测试结束恢复
+  `debugDefaultTargetPlatformOverride = null`。
+
+## 门禁
+
+- `dart analyze lib test`
+- `flutter test`
+- `flutter build apk --debug`
+- `flutter build ios --simulator --no-codesign`
+
+## Git
+
+- ReelShort 提交：`fix(comment): 修复 iOS 评论输入弹窗键盘避让`
+- 作者 `Zhou Weidong <502333560@qq.com>`；禁止 `git add -A`。
+- `--no-ff` 合回 `develop` 并 push，两仓库 PROGRESS 留痕。
+
+## 约束
+
+- 全程中文；不改后端、ReelShortWeb、specs。
+- 不安装或操作真机；完成后停住等待验收。

docs/plans/2026-10-21-K98-auth-keyboard.md

@@ -0,0 +1,73 @@
+# K98 修复登录与手机号登录键盘遮挡
+
+## 目标
+
+- 登录/注册页在邮箱或密码框聚焦后，自动滚动到键盘上方。
+- 手机号登录弹窗的手机号/验证码框同样保持可见。
+- Android `adjustNothing` 下通过既有 MethodChannel 获取键盘高度，iOS 使用实时
+  `MediaQuery.viewInsets`。
+
+## 分支
+
+- ReelShort：`fix/k98-auth-keyboard`，从最新 `origin/develop` 创建。
+- FruitServer 仅写计划与 PROGRESS 留痕，不改后端功能代码。
+
+## A. 有效键盘高度
+
+在 `keyboard_inset.dart` 增加：
+
+```dart
+double effectiveKeyboardInset(
+  BuildContext context,
+  KeyboardInsetNotifier notifier, {
+  double maxRatio = 0.6,
+});
+```
+
+- 取 MediaQuery viewInsets 与 Android channel 逻辑像素值的最大值。
+- Web/非 Android 不读取 channel。
+- 超过屏幕高度 60% 时按 0 处理，负值/非法值归零。
+
+## B. AuthPage
+
+1. `initState` 启动 `KeyboardInsetNotifier`，监听并用 setState 刷新。
+2. `SingleChildScrollView` 增加 `ScrollController`。
+3. 底部 padding 使用固定底部留白 + effectiveKeyboardInset。
+4. 邮箱/密码 FocusNode 监听焦点；聚焦或键盘高度变化后：
+   - 通过 FocusNode.context 的 RenderBox 获取字段全局底边。
+   - 与屏幕高度 - 键盘高度 - 24 比较。
+   - 被遮挡时用 200ms easeOutCubic animateTo 补足滚动。
+5. `resizeToAvoidBottomInset` 保持 false。
+
+## C. PhoneAuthSheet
+
+1. 接入 KeyboardInsetNotifier 和 ScrollController。
+2. 底部 padding 改用 effectiveKeyboardInset。
+3. 手机号/验证码 FocusNode 增加与 AuthPage 相同的焦点/键盘变化滚动校正。
+4. 保持现有 SingleChildScrollView、弹窗和返回键行为。
+
+## D. 测试
+
+- iOS viewInsets=300：登录密码框、注册密码框均在键盘上方。
+- Android platform + MethodChannel 键盘高度：密码框仍在键盘上方。
+- iOS：手机号弹窗验证码框在键盘上方。
+- 所有平台 override 测试返回前显式恢复
+  `debugDefaultTargetPlatformOverride = null`。
+
+## 门禁
+
+- `dart analyze lib test`
+- `flutter test`
+- `flutter build apk --debug`
+
+## Git
+
+- ReelShort 提交：`fix(auth): 登录注册与手机号登录键盘避让`
+- 作者 `Zhou Weidong <502333560@qq.com>`；禁止 `git add -A`。
+- `--no-ff` 合回 `develop` 并 push，两仓库 PROGRESS 留痕。
+
+## 约束
+
+- 全程中文；不改后端、ReelShortWeb、specs。
+- 不改评论输入框已验证的 Android pinned 策略。
+- 不安装或操作真机；完成后停住等待验收。

docs/plans/2026-10-21-drama-free-episodes-sync.md

@@ -0,0 +1,30 @@
+# 2026-10-21 | 短剧保存免费集数同步分集
+
+## 目标
+
+后台短剧编辑改 `freeEpisodes` / `unlockCoin` 后，同步 `drama_episode.is_free` / `unlock_coin`，与定价页 `PriceService.save()` 规则一致。
+
+## 方案
+
+1. 抽出 `EpisodePriceSync.syncByDramaRule(dramaId, freeEpisodes, unlockCoin)`，供 `DramaService.update` 与 `PriceService.save` 共用。
+2. `DramaService.update` 在 `updateById` 后，仅当免费集数或解锁金币相对更新前有变化时调用同步。
+3. TDD：先写 `DramaServiceTest` 复现失败，再改实现转绿。
+
+## 范围
+
+- 仅 `fruitshorts-module-content`
+- 不改 Controller / VO / 契约 / 前端
+
+## 门禁
+
+```bash
+mvn -pl fruitshorts-module-content test -Dtest=DramaServiceTest
+mvn -pl fruitshorts-module-content test
+```
+
+## 分支 / 提交
+
+- `feature/drama-free-episodes-sync` ← `develop`
+- `test(content): 覆盖短剧免费集数同步分集价格`
+- `fix(content): 短剧保存免费集数时同步分集免费状态`
+- `merge --no-ff` 回 develop 并 push

docs/plans/2026-10-21-drama-price-sync-idempotent.md

@@ -0,0 +1,24 @@
+# 2026-10-21 | 短剧保存始终同步分集价格（幂等纠偏）
+
+## 背景
+
+承接 K104。短剧 `free_episodes=9` 重存后，分集 5~9 仍收费。
+
+## 根因
+
+`DramaService.update()` 仅在 `freeEpisodes` / `unlockCoin` 相对更新前有变化时调用 `EpisodePriceSync`。历史数据已漂移时，同值重存不触发同步。
+
+## 方案
+
+1. 测试：覆盖「规则字段未变、分集已漂移」仍纠正。
+2. `DramaService.update()`：每次保存都调用 `EpisodePriceSync.syncByDramaRule(drama)`。
+3. `EpisodePriceSync`：仅对有差异的行走 `updateById`（已具备，保持）。
+
+## 范围
+
+只改 `fruitshorts-module-content` 的 `DramaService` / `EpisodePriceSync` / `DramaServiceTest`。不改 Controller / VO / 契约 / 前端。
+
+## 提交
+
+1. `test(content): 覆盖免费集数未变但分集漂移的修复场景`
+2. `fix(content): 短剧保存时始终同步分集价格`

docs/plans/INBOX.md

@@ -1,811 +1,95 @@
-# INBOX — 给 Codex 的指令队列（FruitServer 仓库内）
+# INBOX
 
-> **Codex 每次开始任务前必须先读本文件**（2026-10-16 起指令通道从 specs 仓库迁到本仓库）。
-> 按条目顺序执行，处理完的条目标记 `[已处理]`。指令来源：项目经理（Trae）。有异议在条目下留言，不要静默跳过。
->
-> **规范以 specs 仓库为准**（`AGENTS.md`、`CODING_STANDARDS.md`、`GIT_WORKFLOW.md`、`docs/01~20`、`docs/plans/codex-研发任务清单.md`）——
-> specs 现在**只拉取、由项目负责人更新**，我们不再往它提交。工作留痕写在本仓库 `docs/plans/PROGRESS.md`。
+> 本轮任务：K100 后台剧集多选上传（分片 + 断点续传 + 进度展示）。**[已处理]**
+> 开工前置：先读 `AGENTS.md`、`CODING_STANDARDS.md`、`GIT_WORKFLOW.md` 本文件，再读
+> `ReelShortWeb/src/utils/uploader.ts`、`src/api/admin/media.ts`、`src/views/contentManagement/EpisodeManagementView.vue`。
 
-> ⚠️ **双 Agent 协作红线（Trae + Codex 共守）**
-> 1. **单一写者**：同一时刻只有一个 agent 在改代码/写 PROGRESS/跑门禁。
-> 2. **留痕**：谁干活谁写 `docs/plans/PROGRESS.md`（命令 + 原始输出 + 解读，逐动作追加）。Trae 接手时用「【Trae 接手】」标记。
-> 3. **git 不冲突**：提交前先 `git status`/`git log`；只 `git add` 自己的文件，禁止 `git add -A`/`.`；不夹带对方改动。
-> 4. **文件不覆盖**：写 INBOX/PROGRESS 前先读最新，追加不覆盖。
-> 5. **求助通道**：遇到阻塞/不确定，在本文件顶部写「【待 Trae 协助】+ 问题描述」。
-> 6. **禅道同步**：任务「开始/完成」时同步更新禅道任务状态。
-> 7. **验收归用户**：每批做完**停在干净交接点**，由用户亲自验证；回执必须含「用户可照做的验证步骤 + 每步预期结果」。
-> 8. **门禁（不达标不提交）**：后端 = `mvn test` 全过（核心接口须有契约测试）；Web = `pnpm build:pro` 通过 + eslint 零错误；Flutter = `dart analyze lib test` 零告警 + `flutter test` 全过。
-> 9. **分支（按 `GIT_WORKFLOW.md`）**：从 `develop` 拉 `feature/<模块>-<简述>`，小步提交；完成后 `git checkout develop && git merge --no-ff feature/...` 再 `git push origin develop`；**绝不动 `main`**（dev→main 走 PR，由用户操作）。
-> 10. **设备验证必须「设备侧取证」（2026-10-16 新增，血的教训）**：真机 / 模拟器 / 小程序等目标设备的验证，**证据必须产自设备侧**（设备侧集成测试、设备日志、设备截图、设备侧抓到的连接）。**禁止**用"在开发机上 `curl` 某地址返回 200"证明设备可达 —— 本机 curl 本机网卡地址必然 200，这是**假阳性**（已实际误导过一次：`10.157.242.1` 是开发机 VPN 网卡地址，手机根本不可达，导致真机「剧目列表加载失败」）。**拿不到设备侧证据的，一律标「未验证」**，不得写成"已验证"。
+### Codex 回执（K100）
 
----
+- ReelShortWeb 分支：`feature/episode-batch-upload` → `--no-ff` 合入 `develop` 并 push
+- 提交：`feat(admin): 剧集多选分片上传与断点续传`
+- 门禁：`pnpm lint:eslint` 零错误；`pnpm build:dev` 成功
+- 未验证：PM 手工多选/暂停/刷新续传/批量建集（8080+3005）
+- 风险：续传需重选相同本地文件；暂停不 abort 进行中分片
 
-## [已处理·待用户验收] 2026-10-17 | K2 客户端第二批：分类 + 观看记录 + 收藏列表 + 下载授权（A3/A5 剩余）+ UI
+## 现状（已勘察，不要重复排查）
 
-**用户指令（2026-10-17）**：「现在先做客户端 对接相关接口 及ui 严格执行specs 内的要求」。
+- 后端分片上传已具备且不改：`POST /admin/media/upload/init` → `POST /admin/media/upload/chunk` →
+  `POST /admin/media/upload/complete`；断点查询 `GET /admin/media/upload/{uploadId}`
+  返回 `receivedChunks/totalChunks/chunkSize/percent/status/assetId/url`。
+- 前端已有 `src/utils/uploader.ts`：`uploadFile()` 分片并发 3、`resumeUpload()` 按服务端已收片数续传、
+  `probeVideoDuration()` 探测时长。**这两个函数已可用，本次在其上做批量队列 UI**。
+- 当前剧集管理 `EpisodeManagementView.vue` 只有一个 `el-upload` 单文件入口（`http-request="uploadVideo"`），
+  **不支持多选、没有进度条、没有断点续传入口**，`onSession` 也没有落盘。
 
-> **本批只做 K2，做完停下写回执，不要连做 K3/K4。**
-> 规范以 specs 为准（`docs/plans/codex-研发任务清单.md` 阶段 A3/A5、`docs/16-测试用例库.md` CONTENT/RECORD、`docs/09-测试计划.md`）；
-> 接口只认 `FruitServer/docs/api-phase1.md` §1.3 / §1.5 / §1.6，**契约里没有的接口一律不许自造**。
+## 目标
 
-### 〇、开工前必读（按 specs 顺序，缺一不可）
+在剧集管理页提供「批量上传」：一次选多个视频 → 队列分片上传 → 每个文件独立进度 → 失败可重试 →
+刷新/重进页面能续传 → 上传完成后批量创建分集。
 
-1. `AGENTS.md`（项目上下文、强制约束、自主执行与沟通节奏）
-2. `CODING_STANDARDS.md`（三端红线、Dart/Flutter 专章、门禁总表）
-3. `GIT_WORKFLOW.md`（Git Flow、提交格式、审查门槛）
-4. `FruitServer/docs/api-phase1.md` §0 / §1.3 / §1.5 / §1.6（接口唯一权威）
-5. `docs/plans/codex-研发任务清单.md`（A3/A5）、`docs/16-测试用例库.md`（CONTENT/RECORD）、`docs/09-测试计划.md`
-6. 本 INBOX 条目
+## A. 上传队列（新建 `src/views/contentManagement/upload/useUploadQueue.ts`）
 
-**硬性执行口径（摘自上述规范，违反即打回）**
+1. 输入：`File[]` + `dramaId` + 可选 `bizType`
+2. 每项状态机：`waiting → uploading → merging → done / failed / paused`；对外暴露 `items`、`overallPercent`、
+   `start()`、`pause()`、`retry(id)`、`retryAll()`、`remove(id)`、`clear()`
+3. 队列并发：同时最多 2 个文件上传（文件内分片并发沿用 `uploadFile` 的 3）
+4. 进度：文件内 `onProgress` 回调更新单项百分比；总进度 = 各文件字节加权，不是简单平均
+5. 失败隔离：单文件失败不影响其它文件，错误原因记在该项 `error`
+6. 暂停语义（本轮简化，不做 abort）：暂停后不再派发新任务，已在传的分片让其完成
+7. 上传完成后 `completeUploadApi` 拿到 `assetId/url/durationSec` 写回该项
 
-- **Git**：从 `develop` 拉 `feature/flutter-k2-library` 开发；提交信息 `type(scope): 描述`（`type` ∈ feat/fix/docs/test/refactor/style/perf/chore，≤50 字符，一个 commit 只做一件事）；完成后 `git merge --no-ff` 回 `develop` 再 push；**禁止直接改 `main`**；只 `git add` 自己的文件，禁止 `git add -A`/`.`。
-- **TDD**：先写测试（红灯）→ 实现（绿灯）→ 重构；测试命名 `should_<期望>_when_<条件>`；核心类（repository/service/logic）必配 `*_test.dart`。
-- **Dart**：`provider` binding/logic/view 三层；`dio`；全程 `async/await`，**禁裸 `then()`**；IO 失败用结果对象/控制器错误字段承接，**不把异常直接抛到 UI**；禁止空 catch。
-- **代码规模**：函数 ≤50 行、参数 ≤5、类 ≤300 行、单文件 ≤500 行、嵌套 ≤4 层、圈复杂度 ≤10；除 `0/1/-1/null/空串/布尔` 外禁止魔法值。
-- **注释**：每个 public 类/方法必须有文档注释；文件头写一行中文职责；新文件首行 `// Author: fruit.com.cn`；代码/注释/提交信息**不得出现任何 AI 痕迹**。
-- **留痕**：每步「叙述 + 工具命令 + 原始输出 + 解读」，追加到 `docs/plans/PROGRESS.md`；做前先写 `docs/plans/2026-10-17-K2.md`（步骤/影响文件/风险/待确认）。
-- **l10n 生成物**（`lib/l10n/app_localizations*.dart`）豁免作者头，但 `.arb` 必须手写三份。
+## B. 断点续传（关键）
 
-### 一、PM 已勘察的现状（实测，直接用）
+1. 上传开始（拿到 `uploadId`）即写入 `localStorage`：键 `reel_upload_sessions`，
+   值数组项含 `{ uploadId, fileName, fileSize, lastModified, dramaId, bizType, createdAt }`
+2. 页面进入时读取该键，过滤 `dramaId` 匹配且 24 小时内的会话，弹出提示「发现 N 个未完成上传，是否续传」
+3. 续传前用 `file.name + size + lastModified` 匹配本地重新选择的文件；
+   **文件匹配不上（换机器/改名）则不自动续传，提示后由用户手动重选**
+4. 续传走现有 `resumeUpload(file, uploadId)`；`GET /admin/media/upload/{uploadId}` 返回 404 或已 completed 的会话要从 localStorage 清理
+5. 上传成功、用户移除、用户放弃续传三种情况都要清理对应记录
 
-- `ReelShort`（`develop` `00280ca`）已接：`/app/home/feed`、`/app/discover/feed`、`/app/dramas/{id}`、`/app/episodes/{id}/play`、`/app/watch/progress`（POST/GET）、`/app/watch/recent`、`DELETE /app/watch/progress/{dramaId}`、`/app/favorites`（toggle/list/delete）、账号 4 个接口。
-- **未接**：`GET /app/categories`、观看记录删除/清空、下载全部 8 个接口、`/app/me*`（属 K4）、互动（属 K3）。
-- 现状缺陷：
-  - 发现页分类**是本地按 sections 下标硬编码**（[discover_view.dart](file:///Users/jianghaifeng/Desktop/ReelShort/ReelShort/lib/pages/discover/discover_view.dart#L363)），不是 `GET /app/categories`；
-  - "我的-记录"只渲染**能在已加载首页/发现目录里匹配到**的剧（[mine_view.dart](file:///Users/jianghaifeng/Desktop/ReelShort/ReelShort/lib/pages/mine/mine_view.dart#L634-L716)），匹配不到就消失；
-  - 收藏列表嵌在"我的"页签里，不能单独刷新/取消收藏；
-  - 下载**完全没有**。
+## C. 批量创建分集
 
-### 二、本批范围（4 块，按顺序做）
+1. 上传完成列表提供「批量创建分集」按钮
+2. 默认值：按文件名自然排序（去扩展名后再比较，`第2集` 排在 `第10集` 之前）；
+   集号 = 该剧当前最大集号 + 1 起顺延；标题取文件名去扩展名；是否免费沿用现有新建默认值
+3. 弹窗内每行可改：集号、标题、是否免费；冲突集号在提交前本地校验并标红
+4. 提交：逐条调用现有 `createEpisodeApi`（`src/api/admin/episode.ts`），
+   逐条显示成功/失败，失败的保留在弹窗内可重试；全部结束后刷新剧集列表
+5. **不新增后端接口**，契约不动
 
-#### K2-A 分类（A3 剩余）
+## D. 组件拆分（红线：单文件 ≤ 500 行）
 
-- 接口：`GET /app/categories` → `[{ id: string, name: string }]`（J1：**id 是字符串**）。
-- UI：发现页分类条改为**服务端分类**；点分类展示该分类的剧。
-  - 内容来源只允许 `GET /app/discover/feed` 的 `sections[]` 中 `code == "category-{id}"` 的分区（后端已按分类生成，见 `AppCatalogService#discoverFeed`）。
-  - 某分类在 discover 里没有对应分区 → 显示空态，**不要自己拼请求/自造接口**。
-  - 保留现有 `hot` / `new` 分区的入口与样式。
+- `src/views/contentManagement/upload/BatchUploadDialog.vue`：多选、队列列表、总进度、暂停/重试/移除
+- `src/views/contentManagement/upload/UploadTaskRow.vue`：单行（文件名、大小、进度条、状态、操作）
+- `src/views/contentManagement/upload/CreateEpisodesDialog.vue`：批量建分集表单
+- `src/views/contentManagement/upload/useUploadQueue.ts`：队列逻辑（纯逻辑单元，不写 UI）
+- `EpisodeManagementView.vue` 只加一个「批量上传」入口按钮，并保持原单文件上传入口可用
 
-#### K2-B 观看记录页（A5 剩余）
+## E. 细节要求
 
-- 接口：
-  - `GET /app/watch/recent?limit=20` → `[{ dramaId, episodeId, positionMs, durationMs, finished, playCount, updatedAt }]`（全部 ID 为字符串）
-  - `DELETE /app/watch/progress/{dramaId}`、`DELETE /app/watch/progress`（清空）
-- **契约缺口（必须按下面方式处理，不许改后端）**：`recent` **不返回剧名/封面**。做法：
-  - 先去重 `dramaId`，再对每个 id 调 `GET /app/dramas/{id}` 补卡片；
-  - **并发上限 4**，结果按 dramaId 缓存（同页内不重复请求）；
-  - 单条详情失败**不能拖垮整页**：该条显示占位（剧名"加载失败"+重试），其余正常渲染；
-  - 在计划文档里记为「契约缺口：建议后续在 `ProgressRespVO` 补卡片字段（需 specs 负责人改契约）」。
-- UI：独立"观看记录"页（入口：我的 → 观看记录）
-  - 每条：封面、剧名、第 N 集、`positionMs/durationMs` 进度、更新时间；点击进详情并续看；
-  - 单条删除、清空（二次确认）；删除**乐观更新**，失败回滚并提示；
-  - 未登录 → 复用现有 `AuthGate` 登录引导（接口需要登录，见 `SecurityConfig`）；
-  - 三态：加载中 / 空（"还没有观看记录"）/ 失败（可重试）。
+- 文件类型白名单：`mp4/mov/mkv/webm`（`accept="video/*"` + `before-upload` 二次校验）
+- 单文件大小上限从现有常量取值，超限直接标红不入队
+- 所有文案走 `src/locales/zh-CN.ts` / `en.ts`，禁止硬编码中文
+- 进度与错误展示用项目现有样式变量，不新引入 UI 依赖
+- 上传期间：关闭页面前用 `beforeunload` 提示存在未完成上传
 
-#### K2-C 收藏列表页（A5 剩余）
+## F. 门禁
 
-- 接口：`GET /app/favorites`（返回 `AppDramaCardVO[]`，**与首页卡片同结构**）、`DELETE /app/favorites/{dramaId}`、`POST /app/favorites/toggle`。
-- UI：独立"我的收藏"页（我的 → 收藏），复用首页卡片渲染：
-  - 取消收藏（按钮或长按/左滑，二选一但要能发现）→ **乐观更新 + 失败回滚**；
-  - 点击进详情；空/错/载三态；未登录 → `AuthGate`。
-- **契约缺口**：TC-RECORD-04 写"分页正确"，但 `GET /app/favorites` **没有分页参数**、返回全量数组 → 本批按全量实现，计划文档登记该缺口，**不许自造 `page/size`**。
+- `pnpm lint:eslint` 零错误
+- `pnpm build:dev` 构建成功
+- 手工验证（PM 会复核）：本地起 8080 + 3005，多选 3 个视频 → 三条并行进度 → 中途暂停 → 刷新页面 → 出现续传提示 → 续传完成 → 批量建分集成功
 
-#### K2-D 下载授权与管理（A5 最后一块，**不做实际落盘**）
+## Git
 
-- 接口（§1.6，全部需登录；设备号优先请求体、其次 `X-Device-Id`，现有 `ApiClient` 已带）：
-  | 方法 | 路径 | 本批用途 |
-  |---|---|---|
-  | GET | `/app/downloads/policy` | 配额/授权天数/wifiOnly/清晰度/已用/剩余/`expirePolicyText` |
-  | PUT | `/app/downloads/settings` | 仅 Wi-Fi、最高清晰度 |
-  | POST | `/app/downloads` | 申请授权（body `episodeId`，`quality` 可省=AUTO） |
-  | GET | `/app/downloads` | 我的下载授权列表 |
-  | GET | `/app/downloads/{episodeId}/url` | 续传前刷新短时效地址（本批只提供 API 方法） |
-  | POST | `/app/downloads/{episodeId}/progress` | 进度上报（本批只提供 API 方法） |
-  | DELETE | `/app/downloads/{episodeId}` | 删除单条 |
-  | DELETE | `/app/downloads` | 清空，返回条数 |
-- UI：
-  - 详情页/播放页加"下载"入口：调 `POST /app/downloads`；**付费/未解锁/配额满时直接展示后端 `message`**，不要自造判断（判定归服务端）；
-  - 我的 → 下载：策略卡（剩余配额、授权天数、`expirePolicyText`）、授权列表（剧名、集号、`status`、`taskStatus`、`progressPercent`、到期时间）、单条删除、清空、仅 Wi-Fi/清晰度设置；
-  - 状态枚举全部**后端返回值驱动**（`ACTIVE/EXPIRED/REVOKED`、`QUEUED/DOWNLOADING/PAUSED/COMPLETED/FAILED/CANCELED`），前端不新增枚举；
-  - 空/错/载三态 + 未登录 `AuthGate`。
-- **明确不做**（写进计划文档，避免误判"没做完"）：文件分片落盘、断点续传、离线播放、`licenseKey` 本地校验 —— 需要存储/权限/加密播放方案，另立批次。本批只交付"授权与状态管理"。
+- ReelShortWeb：从 `develop` 拉 `feature/episode-batch-upload` → 提交
+  `feat(admin): 剧集多选分片上传与断点续传` → `--no-ff` 合回 `develop` 并 push
+- 作者 `Zhou Weidong <502333560@qq.com>`；禁止 `git add -A`；源码首行 `// Author: fruit.com.cn`
 
-### 三、UI 与规范约束（严格执行 specs）
+## 约束
 
-- **语言**：所有新增文案必须进 `lib/l10n/app_{en,zh,id}.arb` **三份齐全**并重新生成；禁止硬编码中文/英文。印尼语为首发语言。
-- **视觉**：沿用现有深色主题与 `AppColors`/组件风格（specs 里未提供 Stitch 出稿；若用户后续给出稿，再单独做视觉替换，本批不自行改主题）。
-- **三态**：每个新页面/列表都要有加载、空、失败（可重试）；失败文案走 `errorText` + l10n，禁止白屏/假装成功。
-- **分层**：新增 `category_api / download_api`（放 `lib/core/data/remote/`），页面只依赖 repository/controller 抽象；沿用 K1 的分层与依赖注入方式。
-- **ID**：19 位雪花 ID 一律按字符串解析（`json_numbers.dart`），**禁止 `as int`**；计数/时长同理按契约类型处理。
-- **不要动**：首页/发现已接 feed 逻辑（分类来源替换除外）、登录注册、播放/进度/收藏已有逻辑（除必要接线）、`ReelShortWeb`、`FruitServer` 后端。
-- 新文件首行 `// Author: fruit.com.cn`；测试命名 `should_<期望>_when_<条件>`。
-
-### 四、门禁（不达标不提交）
-
-1. `dart analyze lib test` **零告警**；`flutter test` **全过**（存量 33 个测试文件不得跑红）。
-2. `flutter build apk --debug` 通过（CODING_STANDARDS §6 门禁总表含构建）；若本机缺 Android SDK，回执里贴失败原始输出并标「未验证」，不得静默跳过。
-3. 新增测试至少覆盖：分类→section 映射（含无分区空态）、记录页 N+1 详情请求去重/并发上限/单条失败降级、删除与清空回滚、收藏取消回滚、下载策略/授权列表渲染、未登录 AuthGate；核心类覆盖率 ≥80%。
-4. **真机/设备侧验证由用户执行**（红线 7、10）：回执里给"用户可照做的步骤 + 每步预期结果"，**禁止用开发机 `curl` 冒充设备可达**；拿不到设备证据就标「未验证」。
-5. Git：`feature/flutter-k2-library` 开发 → `git merge --no-ff` 回 `develop` → `git push origin develop`；**不动 `main`**；合并/推送前再跑一次门禁。
-
-### 五、节奏与留痕
-
-- 先写 `FruitServer/docs/plans/2026-10-17-K2.md`：范围、影响文件清单、上述 3 个契约缺口、风险、待确认。
-- **TDD 节奏**：每块先写测试（红灯）→ 实现（绿灯）→ 重构；每完成一个模块跑一次门禁，零告警才继续。
-- 每步在公司 `PROGRESS.md` 追加「叙述 + 命令 + 原始输出 + 解读」（PM 验收口径，缺一即打回）。
-- 做完**停下写回执**（追加到 `docs/plans/PROGRESS.md` + 本条下），回执必须含：
-  - 哪些页面已走真数据、哪些仍是本地/未做；
-  - 用户可照做的验证步骤与每步预期；
-  - 测试与 analyze 的原始输出；
-  - 提交号。
-- 禅道：开工/完成各同步一次任务状态。
-
-### 六、PM 登记：specs 契约缺口（Codex 不要动，反馈给项目负责人）
-
-1. **搜索**：任务清单 A3 写了"搜索"、TC-CONTENT-05 有搜索用例，但 `api-phase1.md` **没有 `/app/search` 接口** → 本批**不做搜索**。
-2. `GET /app/favorites` 无分页参数，与 TC-RECORD-04"分页正确"不一致。
-3. `GET /app/watch/recent` 不返回剧名/封面，记录页需 N+1 详情请求（建议后端补卡片字段）。
-
-> **用户裁定（2026-10-17）**：**先按现状契约执行，上述缺口后期再补**。本批不得因缺口停工，也不得临时改后端或自造接口；按第二节的降级方案实现，缺口留到后续批次。
-
-### 七、Codex 回执（2026-10-17）
-
-**状态**：K2-A/B/C/D 代码、自动化测试、Android debug 构建与 develop 推送已完成；
-真机/模拟器侧业务验证**未验证**，按红线交用户执行。用户照做清单与测试跳过口径见
-`docs/plans/PROGRESS.md`「动作 17：用户真机验收清单」。K3/K4 未开始。
-
-**提交**
-
-```
-feature: cc4d7c5a9dc6a4f6f0565a32503cce5973af703c
-merge:   45f5f25640a274edb51bd90b3b5e52c43ba9d9cd
-branch:  feature/flutter-k2-library -> develop（--no-ff，已 push，feature 已删除）
-main:    未改动
-```
-
-**已接真实契约数据**
-
-- 发现页分类：`GET /app/categories` + `GET /app/discover/feed`；
-  服务端分类只匹配 `category-{id}`，无分区显示空态。
-- 独立观看记录页：`GET /app/watch/recent?limit=20`、按 dramaId 去重并发上限 4 补详情、
-  `DELETE /app/watch/progress/{dramaId}`、`DELETE /app/watch/progress`。
-- 独立我的收藏页：`GET /app/favorites`、`POST /app/favorites/toggle`、
-  `DELETE /app/favorites/{dramaId}`。
-- 我的下载页：§1.6 全部 8 个 `/app/downloads*` 接口；详情页/播放页下载入口调用
-  `POST /app/downloads`，拒绝时直接展示后端 `message`。
-- 三页面均为加载 / 空 / 失败可重试三态；未登录显示登录引导。
-
-**仍本地或未做**
-
-- 搜索未做：契约没有搜索接口。
-- 文件分片落盘、断点续传、离线播放、`licenseKey` 本地校验未做；本批只交付授权与状态管理。
-- 点赞/评论仍沿用既有本地状态，属 K3，不在本批。
-- 发现 feed 当前只下发 `category-{id}`；若后端没有 `hot`/`new` 分区，保留的入口显示空态。
-- 收藏接口仍返回全量数组，本批未发送 `page/size`。
-
-**门禁原始输出**
-
-```
-$ dart analyze lib test
-Analyzing lib, test...
-No issues found!
-
-$ flutter test
-00:11 +220 ~1: All tests passed!
-
-$ flutter build apk --debug
-Running Gradle task 'assembleDebug'... 2,377ms
-✓ Built build/app/outputs/flutter-apk/app-debug.apk
-```
-
-`~1` 是既有真实后端联调用例因本机 8081 服务未启动而按设计跳过，不是失败。
-首次冷构建也成功，耗时 `705.7s`；最终修复后缓存构建 `2,377ms`。
-
-**用户验证步骤与预期**
-
-1. 在 ReelShort 执行 `git checkout develop && git pull origin develop`，确认 HEAD 为
-   `45f5f25`；后端 8081 已启动，手机与开发机在同一局域网。
-2. 取局域网地址并运行：`IP=$(ipconfig getifaddr en0)`，
-   `flutter run -d <device-id> --dart-define=API_BASE_URL=http://$IP:8081`。
-   预期：App 启动、首页/发现能加载；地址必须按当前网络重新获取。
-3. 打开发现页：分类条应出现 `/app/categories` 返回的分类。选择一个有内容分类，
-   预期显示 discover feed 对应 `code=category-{id}` 的剧；选择无分区分类显示空态。
-4. 播放任意免费集约 10 秒后返回，进入“我的 → 观看记录”。
-   预期：出现该剧封面/剧名/集号/进度/更新时间；即使该剧不在首页分区也能显示。
-   单条删除先立即消失；断网重试删除时，记录应恢复并提示失败。清空应先弹二次确认。
-5. 在详情或播放页收藏一部剧，进入“我的 → 我的收藏”。
-   预期：卡片来自服务端；点粉色收藏按钮取消后立即消失；断网取消应恢复卡片并提示失败。
-6. 登录后在详情页/播放页点下载入口。
-   预期：成功时提示“下载授权已就绪”；付费、未解锁或配额满时，直接出现后端 `message`。
-   进入“我的 → 下载”，预期策略卡显示剩余配额/授权天数/`expirePolicyText`；
-   列表显示后端 `status`、`taskStatus`、`progressPercent`、到期时间；
-   仅 Wi-Fi、清晰度、单删、清空可操作。
-7. 退出登录后分别进入观看记录、我的收藏、我的下载。
-   预期：三页都显示登录引导，不显示网络错误或白屏。
-
-**证据口径**
-
-- 以上设备侧步骤尚未执行，因此真机/模拟器验证统一标记「未验证」。
-- 没有用开发机 `curl` 冒充设备可达证据。
-- 本批不包含实际文件下载，因此不能据此验收“离线播放”。
-
----
-
-## [已处理] 2026-10-17 | 三库全量拉取 + `main` → `develop` 同步（Trae 执行，无代码改动）
-
-**用户指令（2026-10-17）**：「先拉最新全量代码，三个库全拉，相关规范已经备齐、接口文档完备、INBOX更新、环境地址清单在docs下21-环境地址清单.md 同步main 分支到开发分支」。
-
-### 一、执行结果（实测）
-
-| 仓库 | 分支 | HEAD | 落后 origin/develop | 领先 | `origin/main` 未并入 | 工作区 |
-|---|---|---|---|---|---|---|
-| FruitServer | develop | `2d70858` | 0 | 0 | 0 | 干净 |
-| ReelShort | develop | `00280ca` | 0 | 0 | 0 | 干净 |
-| ReelShortWeb | develop | `3ec9ea6` | 0 | 0 | 0 | 干净 |
-
-- 三库 `git fetch --all --prune` 后均无新提交，无需 `pull`。
-- **ReelShort** 是唯一有 `main` 未同步的库：`eaf8fb4 style: 全量补充作者标识` 与 develop 改名（`nontonki`→`fruitshorts`）冲突 15 个文件。
-  解法：保留 develop 口径（`package:fruitshorts`）+ 按文件类型补回署名头（`.dart` → `//`，`.yaml` → `#`，`.xml` → `<!-- -->`）；
-  `main` 版复活了 develop 已删除的 5 个文件（`test/catalog/demo_media_test.dart`、`test/catalog/home_feed_category_test.dart`、
-  `lib/pages/home/home_feed_sections.dart`、`lib/pages/home/widgets/home_feed_header.dart`、`lib/pages/home/widgets/category_swipe_region.dart`）→ 已 `git rm`；
-  `lib/l10n/app_localizations*.dart`（生成文件）不加署名头，已还原。
-  门禁：`dart analyze lib test` → `No issues found!`；提交 `00280ca`（作者 `jianghaifeng <haifeng_hello@163.com>`），已推 `origin/develop`。
-
-### 二、⚠️ 待 PM / 用户确认
-
-1. **`docs/21-环境地址清单.md` 在 specs 仓库中不存在**。已核对：specs `docs/`（仅 01~20 + README + plans + 参考规范材料清单 + 代码现状盘点）、三个代码仓 `git ls-files`、specs 全部远端分支（只有 `origin/main`）—— 均无此文件。请确认是尚未推送，还是在别的路径/仓库。
-2. specs 本地仍有 22 笔提交未推送到远端（无写权限，`origin/main` 停在 `c528345`）。若以远端为准，需要决定是否把本地回退到 `origin/main`。
-
-### 三、用户裁定（2026-10-17）
-
-1. **specs 只有 `main`，只需同步** → 已将本地 `specs` 强制对齐到 `origin/main`（`c528345`），本地领先的 22 笔未推送提交已丢弃；此后 specs **只拉取，不提交**。
-2. **specs 是唯一权威** → 规范、接口契约、任务清单一律以 specs 为准；与本仓库文档冲突时以 specs 为准。
-3. **执行前置动作** → Codex 每次开始任务前**必须先读本文件（INBOX）**，按条目顺序执行；新条目由 PM 追加，不覆盖历史。
-
----
-
-## [已交接 · 未验证（真机验证改由用户执行）] 2026-10-16 20:30 | K1-verify：用**正确地址**重做真机验证（设备侧取证）
-
-**用户指令（2026-10-16 20:20）**：「让 Codex 用正确地址重做一次真机验证」。
-
-**背景（为什么必须重做）**：你 1-3/1-4 那批的真机验证用的是
-`--dart-define=API_BASE_URL=http://10.157.242.1:8081` —— 该地址是**开发机某块 VPN 网卡（utun）的地址**，
-现已不存在，**手机侧没有这块网卡**，所以按它构建、安装到手机上的 App **在真机上必然请求失败**
-（用户实测提示「**剧目列表加载失败**」，报错里就显示着这个地址）。
-更关键的是：当时那条"证据"是**在开发机上 `curl` 本机网卡地址拿到 200** —— 本机 curl 本机必然 200，
-**不构成真机可达的证据（假阳性）**。PM 已把 specs 里 4 处记录修正并作废该结论（`481d4bb`）。
-
-### 一、重做验证（**必须设备侧取证**，见红线第 10 条）
-
-1. **先取真实地址，不要硬编码**：`ipconfig getifaddr en0` 拿开发机局域网 IP（PM 实测当前 `192.168.31.187`；**换网络会变**）。
-2. **前置条件**：手机与开发机在**同一局域网**；iPhone 已授权「**本地网络**」权限（设置 → 隐私与安全性 → 本地网络）。
-3. 真机跑：`flutter run -d 00008101-000875813E42001E --dart-define=API_BASE_URL=http://<步骤1得到的IP>:8081`
-4. **证据至少一条来自设备侧**（优先级从高到低）：
-   - **首选：加设备侧集成测试**（`integration_test` 依赖 + `integration_test/` 目录），
-     用 `flutter test integration_test -d <device> --dart-define=API_BASE_URL=http://<IP>:8081` 在**手机进程里**
-     真实请求 `/app/home/feed` 与 `/app/dramas/{id}`，断言 `code=0` 且列表非空。
-     —— 这是可重复、可入库的最硬证据，也顺带把"设备验证"变成可回归的。
-   - 或：App 运行时抓**从手机 IP 到 8081 的已建立连接**（`lsof -nP -iTCP:8081 | grep <手机IP>`），
-     并**同时**给出后端侧确实收到该请求的证据。
-   - 或：手机侧截图（`device` 截图不支持无线 iPhone —— 那就用设备侧测试或连接证据替代）。
-5. **若都拿不到：如实标「未验证」**，并说明卡在哪一步（同网段？权限未授权？），**不许含糊**。
-6. 顺带确认原故障已消失：首页「剧目列表」能出内容（或由步骤 4 的测试断言覆盖）。
-
-### 二、留痕要求（**只写本仓库，别动 specs**）
-
-- `docs/plans/PROGRESS.md`（本仓库 FruitServer 这份）**追加**逐动作留痕：命令 + 原始输出 + 解读。
-- 本条下写回执，含**用户可照做的验证步骤 + 每步预期结果**，并**明确标注"证据来自设备侧"**。
-- **不要去改 specs 仓库**（它只拉取；那 4 处 PM 已修正，别重复改）。
-
-### 三、门禁与 git
-
-- `dart analyze lib test` 零告警 + `flutter test` 全过（新增的 integration_test 一起跑；若它依赖真机、无法在纯本机跑，就在回执里说明并给出真机执行命令与输出）。
-- 在 `ReelShort` **`develop`** 提交并 `git push origin develop`；**不动 `main`**；新文件首行 `// Author: fruit.com.cn`。
-
-### 四、节奏
-
-做完**停下写回执**，不要连做下一批。
-
----
-
-## [已处理·待用户验收] 2026-10-16 19:40 | K1 客户端对接：详情 + 播放 + 进度续看 + 收藏（看剧闭环）+ UI 调整
-
-**用户指令（2026-10-16 19:30）**：「现在你要做的事对接客户端接口及 UI 调整，仍然严格按照 specs 执行」→ 转到 **客户端 `ReelShort`（Flutter）**，按 specs 阶段 A 推进。
-
-### 一、PM 已勘察的现状（实测，直接用）
-
-**客户端目前只调了 6 个 C 端接口**（契约里已实现 **44 个**）：
-```
-/app/home/feed   /app/discover/feed
-/app/auth/register   /app/auth/login   /app/auth/refresh   /app/auth/logout
-```
-- `lib/core/data/remote/` 下**只有** `api_client / api_exception / api_interceptors / auth_api / catalog_api` —— **没有** playback / watch / library / interaction / me 的 api 类。
-- `WatchHistoryRepository` 是 **`SharedPreferencesWatchHistoryRepository`（本地存储）**，`mine_logic` 还在用 **`demoProfileId`** 假数据 —— 观看进度/续看位置**全在本机**，没接 `/app/watch/*`。
-- `EngagementRepository` 是 `SharedPreferences` / `InMemory` —— 点赞/收藏状态**也是本地假数据**。
-- 已有：`dio` 网络层 + 拦截器（A1 ✅）、改名 + 印尼语（✅）、`json_numbers.dart` 兼容字符串 id（J1 ✅）。
-
-### 二、本批范围（K1：一条完整看剧闭环）
-
-> 目标：**从首页点进一部剧 → 详情正确 → 能起播 → 进度能续看 → 能收藏**，全链路走真接口。
-
-1. **详情（A3 的一块）**：新增 `catalog_api` 方法对接 `GET /app/dramas/{id}`（含剧集列表；**免费集带已签名播放地址**）。
-2. **播放（A4）**：新增 `lib/core/data/remote/playback_api.dart`
-   - `GET /app/episodes/{id}/play` → 票据 + 签名地址。**签名地址原样使用，不要拼接/改写**（文档硬要求）。
-   - 起播前取票据；票据/签名地址有有效期，**过期要重新取**，不要缓存到失效后还用。
-3. **进度与续看（A5 的一块）**：
-   - `POST /app/watch/progress`（**每 10s 一次**，切集/退出/切后台各补一次）
-   - `GET /app/watch/progress?dramaId=`（进入详情/播放时定位续看位置）
-   - `GET /app/watch/recent?limit=20`（"我的"页最近观看）
-   - **把 `WatchHistoryRepository` 的本地实现换成远程实现**（保留抽象接口，测试注入内存假实现）；`mine_logic` **去掉 `demoProfileId`**。
-4. **收藏（A5 的一块）**：`POST /app/favorites/toggle`、`GET /app/favorites`、`DELETE /app/favorites/{dramaId}`；收藏状态**以服务端为准**（不要再用本地 `EngagementRepository` 存收藏）。
-5. **UI 调整**（本批必须一起做）：
-   - 详情页 / 播放页 / "我的"页：**加载中 / 空 / 失败**三态齐备（失败要能重试，不要白屏或假装成功）
-   - 进度条与**续看定位**、收藏按钮的真实状态与乐观更新回滚
-   - 断网/超时的提示文案走 l10n（en / zh / id 三份都要有）
-
-### 三、口径与约束（照 specs）
-
-- **ID 是字符串**（J1 刚统一）：解析走 `json_numbers.dart`，不要直接 `as int`。**计数类**（`viewCount`/`expiresIn`）也是字符串。
-- `accessType` 等枚举**用后端返回值驱动 UI**（免费/付费/试看），**不要在前端写死**；付费集解锁不在本批（属 B2）。
-- 接口层与业务层分离：**新增 api 类**、controller/logic 只依赖 repository 抽象（沿用现有 `catalog_api` + `catalog_controller` 的分层做法）。
-- **不要动**已对接的首页/发现/登录注册逻辑（除必要的最小接线）。
-- 新文件首行 `// Author: fruit.com.cn`；测试命名 `should_<期望>_when_<条件>`。
-
-### 四、门禁
-
-- `dart analyze lib test` **零告警** + `flutter test` **全过**（存量 27 个测试文件不得跑红；新增测试要覆盖：票据过期重取、进度上报节流、续看定位、收藏切换回滚、失败态）
-- **真实后端联调**（8081）：跑一次端到端并留证据 —— 首页 → 详情 → 播放 → 上报进度 → 重新进入看到续看位置 → 收藏出现在收藏列表
-- 在 `ReelShort` **`develop`** 提交并 `git push origin develop`；**不动 `main`**
-
-### 五、节奏
-
-先写 `docs/plans/2026-10-16-K1.md`（计划 + 影响面 + 风险）→ 做 → 停下写回执（含**用户可照做的验证步骤 + 每步预期结果**，以及"哪几个页面现在走真数据、哪几个还是假的"的清单）。**不要连做 K2。**
-
-> **后续批次（预告，不用现在做）**：**K2** = 记录/最近观看页 + 收藏列表页 + 分类/搜索 + 下载授权（A5/A3 剩余）；**K3** = 互动（评论/点赞/举报/分享，A6）；**K4** = 账号剩余（资料/设备/注销；**Google 登录需 Google OAuth 凭据**，属待你提供的付费/密钥类）。
-
----
-
-## [已处理 · 待用户验收] 2026-10-16 18:30 | J1 全局 ID 字符串化（Long → String）+ 契约统一
-
-> **PM 独立复核（Trae 2026-10-16 19:05）—— 交付 `FruitServer f35db2c` / `ReelShortWeb 3ec9ea6` / `ReelShort 94ff9f1`（三仓均在 `develop` 且与远端同步），验证通过。**
-> - **门禁复跑**：`mvn test` **110 → 115 条全过**（commerce 33 / admin-api **16→21** / app-api 49 / worker 12）+ BUILD SUCCESS ✅
-> - **全局配置落位核实**：`fruitshorts-framework/.../web/JacksonLongToStringConfig.java` 存在（一处生效两端，未改 yml）✅
-> - **端到端真实验证（PM 亲自跑，非采信回执）**：新注册用户雪花 id `2111018722574602241` →
->   ① `/admin/app-users/page` 返回 **`"id":"2111018722574602241"`（字符串）**、**无裸数字大 id**、`"total":2` **仍是数字**（符合约定）；
->   ② 用该 id 调 `/admin/app-users/{id}` → **`code=0`**（修复前此场景即 `200002`）；
->   ③ **真 node 逐位比对**：`typeof parsed.id === 'string'`、`String(parsed.id)` 与库值**逐位相等 = true**；测试数据已清理（残留 0）。
-> - **按红线第 7 条，最终验收权仍归用户。**
->
-> ⚠️ **三处口径待用户点头（PM 意见附后）**：
-> 1. **唯一例外 `PageResult.total` 保持数字** —— PM 意见：**接受**（它是条数不是 id，前端分页组件要数字）；但需在契约 §0「ID 一律字符串」处**显式写出这个例外**，否则前端会困惑。待 Codex 补一句。
-> 2. **客户端改动比"只改 id 解析"略宽（物理上必须）** —— Codex 查明 Flutter 的 id 本来就是 `toString()` 不会崩，真正会崩的是被全局规则扫到的 **Long 计数**，故只改了 `expiresIn`、`viewCount` 等 3 处 + 新增 `json_numbers.dart`。PM 认可这个判断与最小改动口径。⚠️ **另需用户知晓**：`ReelShort` 原先**只有 `main`**，Codex 新建了 `develop` 并推送；若客户端同事仍在 `main` 上开发，这笔需要带过去。
-> 3. **Codex 自我纠正了一处统计错误** —— 它第一版清理脚本用 `psql ... returning 1 | wc -l` 数行数，数到的是 psql 命令标签（删 0 行也输出 1），那轮"删除 1 行"是假数字；随后用**全库扫描**复核（uid/邮箱/雪花 id 零命中）确认无残留。PM 认可其如实披露。
->
-> 📌 **仍挂着**：禅道里同样**没有 J1 任务**（项目 2 下只有 S0/S1、A1–A6、B1/B2、C1–C3），无可同步状态。
->
-> ⚠️ **PM 顺手说明**：为做端到端验证，8080（PID 80375）/ 8081（80383）/ 3005 均为 Codex 重启后的新 jar，接口与页面正常。
-
-**用户裁定（2026-10-16 18:10）**：雪花 id 精度问题 **「按方案 (a) 全局修改，统一契约」**。
-
-**背景（两方独立复现同一根因，故现在铺全局）**：
-- 你在 I1 里实测到：UI 点「下架」后端回 `200002 公告不存在` —— 库里 `2111011206851596290`，浏览器 `JSON.parse` 后变 `2111011206851596300`，回查自然找不到。你把修复**限定在本轮两个模块**并留了待裁定。
-- PM 独立复核同样确认：新注册用户 id `2111012753262120962` 由 `/admin/app-users/page` **以裸 JSON 数字**下发；用真 JS 引擎验证 `JSON.parse('{"id":2111012753262120962}').id` → `2111012753262121000`（**不相等**）。根因是 JS `Number.MAX_SAFE_INTEGER = 9007199254740991`，19 位雪花 id 必然超出；而服务端**没有全局 `Long→String` 序列化配置**。
-- 种子数据都是小 id（4/5/25）所以老页面一直正常 —— 这是**只要"新建后立刻拿 id 操作"就必然踩**的坑。
-
-### 一、后端：全局序列化（放 `fruitshorts-framework`，两个入口都生效）
-
-1. `Long.class` 与 `Long.TYPE` 一律用 `ToStringSerializer`。
-2. ⚠️ **不要动 `Integer` / `int`**（分页 `pageIndex`/`pageSize` 等保持数字）。
-3. 必须覆盖：普通字段、**嵌套对象**、`List`/`Map` 的值、分页 `list`。
-4. **反序列化方向也要验**：请求体 / 路径变量 / 查询参数里 id 传**字符串**要能正确绑定成 `Long`（前端回传的就是字符串）。
-
-### 二、契约统一（`docs/api-phase1.md` §0 通用约定）
-
-- 写明「**所有 ID 字段一律以字符串下发**」（含主键与外键 id），并给示例。
-- 把 I1 里逐模块的描述（商品/公告 VO 各自加 `ToStringSerializer`）**收拢到这条总口径**，不要各写一套。
-- 顺手把 §2.11/§2.12 里与总口径重复的表述改成引用 §0。
-
-### 三、两个前端适配
-
-1. **ReelShortWeb**：审计现有页面有没有把 id 当**数字**用 —— `parseInt(id)` / `Number(id)` / `id + 1` / 拿 id 当数组下标 / `===` 与数字比较 / `sort((a,b)=>a.id-b.id)`，逐处改成字符串语义。本轮新加的两个页面已按 `string` 写，**别回退**。
-2. **ReelShort（Flutter）**：`fromJson` 里 `json['id'] as int` 这类写法在字符串下发时会**直接抛异常**，必须审计并修。策略二选一（推荐前者，改动小且向前兼容）：
-   - **兼容解析**：统一按"接受字符串或数字"的方式解析（如 `int.tryParse(v.toString())`），或把模型里的 id 保留为 `String`；
-   - 或全量改成 `String`（改动更大，要与客户端同事对齐）。
-   - ⚠️ 客户端现由另一同事在推进：**只做"ID 解析"这一类最小改动**，不要顺手改别的；有分歧或改不动就写「【待 Trae 协助】」，并在回执里给出**逐文件清单**。
-
-### 四、验证（必须有证据，不接受"应该没问题"）
-
-1. 后端契约测试：`Long` 字段确实以**字符串**输出（含嵌套 / 分页 list / Map）。
-2. **端到端复现 I1 那个 bug 并证明已消失**：admin 新建一条记录 → 用响应里的 id 调详情 / 编辑 / 上下架 → **成功**（全局范围内，不再只限商品/公告）。
-3. **JS 侧一致性证据**：拿真实响应喂 `node -e 'const d=JSON.parse(...); console.log(String(d.id))'`，证明与库里的值**逐位相等**。
-4. C 端：注册 / 播放票据 / 订单等返回的 id 也是字符串，且**客户端解析不崩**（Flutter 侧跑测试）。
-
-### 五、门禁与 git
-
-- `mvn test` 存量 **110 条不得跑红** + 新增测试；Web `pnpm ts:check` + eslint 零错误 + `pnpm build:pro` 通过；若改了客户端则 `dart analyze lib test` 零告警 + `flutter test` 全过。
-- FruitServer / ReelShortWeb / ReelShort **各自在 `develop` 提交并推送**；**绝不动 `main`**。
-- 新写文件首行 `// Author: fruit.com.cn`（Vue/TS 同；Dart 用 `// Author: fruit.com.cn`）。
-
-### 六、节奏
-
-先写 `FruitServer/docs/plans/2026-10-16-J1.md`（方案 + 影响面清单 + 风险）→ 做 → 跑门禁 → **停在干净交接点写回执**，回执必须含：
-- 每个仓库改了哪些文件（**客户端逐文件清单**要单独列）
-- 「用户可照做的验证步骤 + 每步预期结果」
-- 若客户端有未改完/有分歧的部分，**如实列出**（不许含糊）
-
----
-
-## [已处理·待用户验收] 2026-10-16 17:30 | I1 后台管理端：商品（金币包）配置 + 系统公告管理（后端接口 + Web 页面）
-
-**用户指令（2026-10-16 17:10）**：「现在做后台管理端，规范还是按照 specs」+「ReelShortWeb 就是这个项目」→ **后台管理端 = `ReelShortWeb`（Vue3 + Element Plus），本批后端接口与页面一起做**。
-
-### 一、PM 已勘察的两个缺口（实测证据，直接用）
-
-| # | 缺口 | 证据 |
-| --- | --- | --- |
-| 1 | **商品/金币包配置：后台完全没有入口** | `product` 表 **16 个字段**已建（`code/name/type/platform/store_product_id/coin_amount/bonus_coin/price_amount/currency/display_price/region_codes/vip_days/sort/status/effective_at/expire_at`）、**已有 3 行种子数据**、C 端 `/app/orders/verify` 依赖 `store_product_id` 对齐商店商品（错误码 `200002 该商品未在后台配置` 就是为它留的）；但 admin-api 29 个 Controller 里**没有任何商品 CRUD 接口**（`grep` 只命中 `WalletAdminController /coins` 的发币补偿）→ 运营改商品只能改库。**PRD §09 明确要求「商品配置与价格分层」** |
-| 2 | **系统公告：有读没写** | `ops_notice` 表 **0 行**；E1 已交付 C 端 `GET /app/notices`（匿名只读）；契约 §2.7 原话「**系统公告 `ops_notice` 目前没有产出方，等有公告功能再接**」→ 后台没有公告管理接口，运营发不了公告 |
-
-> 除这两项外，admin-api 对照契约 §2.1–§2.10 全部已实现，**不要重做**。
-
-### 二、后端（FruitServer / admin-api）
-
-1. **契约先行**（依据 `12-上线检查清单` §一）：先在 `docs/api-phase1.md` 写清两个模块的接口、字段、错误码、权限点（放在 §2.6 订单与权益之后，或新增一节），**再动代码**。
-2. **商品配置 `/admin/products`**：
-   - `GET /admin/products/page`（筛选：`type` / `status` / `platform` / `keyword`，分页沿用既有口径）、`GET /admin/products/{id}`
-   - `POST /admin/products`、`PUT /admin/products/{id}`、`PUT /admin/products/{id}/status`（上下架）、`DELETE /admin/products/{id}`
-   - 字段按 `product` 表现有结构，**不要改表**
-   - **必须有校验**：`code` 在全局唯一、`store_product_id` 在**同一 `platform` 下唯一**（否则同一商店商品被重复配置 → 发币口径混乱）；`type=COIN` 时 `coin_amount > 0`；`type=VIP` 时 `vip_days > 0`
-   - ⚠️ **VIP 商品口径**：B1-1 已定「VIP 订阅本轮不做」→ 允许建但**不允许启用**（启用报明确错误）或直接拒绝创建，**二选一由你定，写进契约并在回执里说明**；拿不准就写「【待 Trae 协助】」
-   - 权限点命名沿用现有习惯（参考 `commerce:*`），并落 `sys_permission` + `sys_menu`
-3. **系统公告 `/admin/notices`**：
-   - `GET /admin/notices/page`、`GET /admin/notices/{id}`、`POST`、`PUT /admin/notices/{id}`、`PUT /admin/notices/{id}/status`（发布/下架）、`DELETE /admin/notices/{id}`
-   - 字段按 `ops_notice` 表现有结构，**不要改表**
-   - **与 C 端 `GET /app/notices` 的筛选口径必须严格对齐**（E1 已定：`status=1` 且 `target ∈ {ALL, USER}`、`publish_at <= now`、`expire_at` 为空或未过期、按 `publish_at desc, id desc`）—— 后台发布后 C 端能查到、过期/下架后查不到
-   - 权限点 + 菜单同上
-4. **菜单与权限点落库**：写进 `sql/data-phase1.sql`（**幂等**），注意**沿用既有保留段**、不要与现有 id 冲突（现有菜单到 id 30）。建议：商品配置挂 `订单与权益`(id 22) 下；系统公告可挂新的运营分组，具体由你按现有约定定。**超管必须可见且可授权**。
-5. Swagger 中文注解按 S1 规范补齐（`@Tag` / `@Operation`）。
-6. **门禁**：`mvn test` 存量 **91 条不得跑红** + 新增契约测试，至少覆盖：`store_product_id` 同平台唯一、`code` 唯一、`type` 校验、公告发布后 C 端可见 / 过期或下架后不可见、越权（无权限点被拒）。
-
-### 三、后台页面（ReelShortWeb）
-
-> **挂载机制（PM 已勘察）**：路由是**静态注册**在 `src/router/index.ts`（`component: () => import('@/views/...')`），而菜单树来自 DB `sys_menu`，其中 `component` 字段必须**与视图路径一致**（例：`views/contentManagement/DramaManagementView`）。两边都要加。
-
-1. 新增两个页面（放在与现有页面同级的目录，命名沿用 `XxxManagementView.vue` 风格）：
-   - **商品配置**：列表（分页/筛选）+ 新建/编辑弹窗 + 上下架 + 删除；表单字段按 `product` 表；金额/金币用数字输入并做前端校验
-   - **系统公告**：列表 + 新建/编辑（标题/正文/类型/目标/发布时间/失效时间）+ 发布/下架 + 删除
-2. **按现有约定写**：API 封装放 `src/api/admin/`（新增如 `product.ts` / `notice.ts`）；权限码走现有的 `can(code)`；**表格状态列用接口返回的 `status` / `statusText`，不要在前端写死中文**；大数值用 `formatCount`。
-3. `src/router/index.ts` 静态注册路由（`route_name` 与 DB `sys_menu.route_name` 一致，**注意不要与既有 route_name 重名** —— 之前踩过 `CreatorCenter` 重名导致白屏/404 的坑）。
-4. **不要改动已对接的既有页面**（避免与其他人正在做的改动冲突）。
-5. **门禁**：`pnpm build:pro` 通过 + eslint 零错误。
-
-### 四、git
-
-- **FruitServer**：在 `develop` 提交并推送；**不动 `main`**。
-- **ReelShortWeb**：现在是 `main` 分支且**与远端分叉**（本地 `4564aa8` 领先 1、远端 `1fd0b8b 全量补充作者标识` 领先 1）。请先 `git fetch` 并把远端合进来，**然后按 specs 的 `GIT_WORKFLOW` 新建 `develop` 分支，在 `develop` 上提交并 `git push origin develop`**；**不动 `main`**（合并走 PR、由用户操作）。远端是 `jianghaifeng/ReelShortWeb.git`（有写权限）。
-- 作者的署名规范：`// Author: fruit.com.cn`（Vue/TS 文件首行）。
-
-### 五、节奏（红线第 7 条）
-
-1. 先写计划文件 `docs/plans/2026-10-16-I1.md`（后端 + 前端两部分、步骤、风险、待确认）。
-2. 做，跑门禁。
-3. **停在干净交接点写回执**：逐项列出改了什么；**给你和用户可照做的验证步骤 + 每步预期结果**（含「后台登录 → 菜单里能看到这两个新页面 → 建一个商品 → 用该商品在 C 端 verify 能对上」这样的端到端链路）。
-4. **不要连着抢做下一批。**
-
----
-
-### 回执（Codex，2026-10-16）：I1 完成，停在干净交接点
-
-**提交**：FruitServer `8d19a0c`（develop，已推） + ReelShortWeb `db313f4`（develop，已推，含 husky 门禁）。
-**留痕**：`docs/plans/PROGRESS.md`（本轮新建，逐动作命令 + 原始输出 + 解读）；计划 `docs/plans/2026-10-16-I1.md`。
-**没碰 `main`**；01-08 冻结模块未改（改动只在 module-commerce / module-system / admin-api / app-api 的 `AppNoticeService`）。
-
-**门禁数字（原始输出见 PROGRESS 动作 3/6/10）**
-| 门禁 | 结果 |
-| --- | --- |
-| `mvn test` | **BUILD SUCCESS**，commerce 33 / admin-api 16 / app-api 49 / worker 12 = **110 条全过**（存量 91 + 新增 19，无跑红） |
-| `mvn -pl fruitshorts-app-api,fruitshorts-admin-api -am package -DskipTests` | BUILD SUCCESS |
-| `sql/data-phase1.sql` 幂等 | 连跑三遍，`sys_role_menu/permission/menu/role_permission` 行数 54/52/33/79 前后一致 |
-| `pnpm ts:check` | 0 错误 |
-| `eslint --ext .js,.ts,.vue ./src` | 0 error（首遍 1 个 prettier 折行，改后复跑为空） |
-| `pnpm build:pro` | Build successful |
-| `:3005` 真浏览器 | 两页渲染正常；1440/1280/1024 三档 `overflowX=false`；截图见下面步骤 |
-
-**交付内容**
-1. 后端：`/admin/products` 6 个接口（page/{id}/POST/PUT/{id}/status/DELETE）、`/admin/notices` 6 个接口；字段严格按 `product` / `ops_notice` 表现有结构，**未改表**。
-2. 校验：`code` 全局唯一、`storeProductId` **同 platform 唯一**、`COIN_PACK` 需 `coinAmount>0`、`VIP` 需 `vipDays>0`、新建默认下架。
-3. 公告可见性与 C 端**共用一份实现**：`OpsNoticeService.pageForApp(...)`，后台与 `/app/notices` 不再各写一套条件。
-4. 权限点 `product:list/product:update/notice:list/notice:update` + 菜单 31（商品配置，挂 22「订单与权益」）/ 32（运营管理）/ 33（系统公告），超管已授权，幂等。
-5. 前端：`src/api/admin/product.ts`、`src/api/admin/notice.ts`、`ProductManagementView.vue`、`NoticeManagementView.vue`；状态列只用接口 `statusText`，不写死中文。
-
-**两个自己拍的口径（请复核）**
-1. **VIP 商品：允许建档、不允许启用** —— `status=1` 时回 `400 会员商品在订阅功能上线前不能启用（可先建档，上线后再上下架）`。理由：上线日可以直接上下架，不必临时补商品数据；已写进契约 §2.11。
-2. **⚠️ 雪花 id 以字符串下发（本轮实测抓到的真缺陷）** —— UI 上点「下架」后端回 `200002 公告不存在`，根因是 S0 换雪花主键后 id 超过 JS 安全整数范围：DB 里 `2111011206851596290`，浏览器 `JSON.parse` 后变成 `2111011206851596300`，回查自然找不到。
-   修复限定在本轮两个模块（`ProductRespVO` / `NoticeRespVO` 的 `id` 加 `ToStringSerializer`，新建接口返回 `String`，前端 `id: string`），**没动全局序列化、没动 app-api**，避免影响 Flutter 客户端；并补了两条防回归测试。
-   - 遗留：admin-api 其它模块（订单/权益/短剧…）只要"新建后立刻用 id 操作"，同样会中招。**是否统一做"admin-api 的 Long → String"、app-api 要不要一起动（Flutter 解析 id 的地方会受影响）——这是平台级改动，请裁定**，我没自行铺开。
-3. **菜单挂载机制与条目描述有出入（如实报出）**：实测菜单来自 DB `sys_menu`，前端用 `import.meta.glob` 按 `component` 字符串动态解析；`src/router/index.ts` 的 `asyncRouterMap` 只静态声明 dashboard/content/user/system，commerce/governance/board 都不在里面。所以本轮**没有改 `src/router/index.ts`**，只建页面 + 落菜单（`component` 与视图路径一致）。若你要求"两边都登记"，我补一版。
-
-**用户可照做的验证步骤（每步都有预期结果）**
-
-准备（后端）：`cd FruitServer && mvn -pl fruitshorts-app-api,fruitshorts-admin-api -am package -DskipTests`，然后
-```
-java -jar fruitshorts-admin-api/target/fruitshorts-admin-api-1.0.0-SNAPSHOT.jar   # 8080
-java -jar fruitshorts-app-api/target/fruitshorts-app-api-1.0.0-SNAPSHOT.jar       # 8081
-curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8080/v3/api-docs        # 预期 200
-```
-数据库若在干净机器上：`psql -f sql/data-phase1.sql`（可重复执行）。
-
-1. **菜单**：`pnpm dev` → 打开 `http://127.0.0.1:3005/#/login` → `admin / admin123` 登录。
-   预期：左侧出现「订单与权益 → 商品配置」与「运营管理 → 系统公告」，其余菜单不变。
-2. **商品页**：进 `#/commerce/products`。预期：3 行种子（coin_100/550/1200），列 = 商品编码/名称/类型/平台/商店商品 id/到账金币/价格/排序/状态/创建时间/操作；状态显示「已上架」。
-3. **新建商品（正常路径）**：点「新建商品」→ 编码 `uitest_coin_500`、名称随意、平台选 Google Play、商店商品 id `UITEST_COIN_500`、金币 500、赠送 50、价格 9900 → 保存。
-   预期：toast「商品已创建（默认下架，请确认后再上架）」，列表新增一行且状态「已下架」（**id 是雪花 id，注意这是本轮修过的点**）。
-4. **异常路径**：再新建一个同编码商品 → 预期 toast「商品编码已存在：uitest_coin_500」；把类型改成「会员（第二阶段）」、天数 30 → 保存成功（**允许建档**），再点它的状态想上架 → 预期 toast「会员商品在订阅功能上线前不能启用（可先建档，上线后再上下架）」，状态不变。
-5. **C 端对齐（命令）**：把第 3 步的商品点上架，然后
-   ```
-   psql -c "select id, code, platform, store_product_id, status from product where store_product_id='UITEST_COIN_500';"
-   ```
-   预期：查到 1 行、`status=1` —— 这正是 `/app/orders/verify` 找商品的同一条件。
-   （`POST /app/orders/verify` 本机默认 `STORE_VERIFIER=disabled`，会先回 `200003 商店校验尚未配置`，这是 B1-1 的既定行为，不是商品没配上。）
-6. **公告页**：进 `#/operation/notices` → 「新建公告」填标题/正文（默认「全部用户/系统」、不填时间=立即发布）→ 保存。
-   预期：toast「公告已发布」，行内状态「已发布」、失效时间显示「-」。
-   ```
-   curl -s "http://127.0.0.1:8081/app/notices?pageIndex=1&pageSize=5"    # 预期 total 1，能看到刚发的标题
-   ```
-7. **下架（异常路径的对照组）**：点该行状态「已发布」→ 预期 toast「公告已下架」、行内变「已下架」；再跑上面的 curl → 预期 `total 0`。
-8. **越权**：用 `content.editor01 / admin123`（内容运营，无 `product:*`/`notice:*`）登录后直接敲 `#/commerce/products`。
-   预期：页面 403/无权限（后端 `{"code":403,"message":"无权限"}`）；不带 token 请求 `curl -s "http://127.0.0.1:8080/admin/products/page"` → `{"code":401,...}`。
-9. **清理**：把第 3/4 步的商品、第 6 步的公告删掉；核对 `select count(*) from product;` = 3、`select count(*) from ops_notice;` = 0。
-   （本轮自测数据我已清干净：`product` 3 行种子、`ops_notice` 0 行。）
-
-**门禁/流程说明**：本轮所有子步骤都在同一批内完成，未抢做下一批；`mvn test` 与 `package` 都是先停服务再打包、打包后重新起服务、**对着活着的服务**做的 curl 自测（不是对停掉的服务打）。
-服务当前状态：8080/8081 我这边是**已起的**（自测完成时仍在监听）；若你这边连不上就是被环境回收了，按上面「准备」两条命令起回来即可。
-
-**禅道同步（红线第 6 条，如实说明）**：我把 `水果短剧APP`（项目 2）的 4 个执行下的任务都拉了一遍，
-任务只有 S0/S1/S0-16、A1–A6、B1/B2、C1–C3 —— **没有 I1（后台管理端 商品配置 + 系统公告）这一条**，
-所以本轮没有可同步的任务号，我没有动任何既有任务的状态（避免误改 B1/C1/A* 这些别的批次）。
-下一步请给 I1 建任务并告知任务号，我补一次状态同步（`codex01` 的 token 已可用）。
-
----
-
-### 回执（Codex，2026-10-16）：J1 完成，停在干净交接点
-
-**提交**（三个仓库各自 `develop`，`main` 未动）
-- FruitServer `f35db2c`（develop，已推）：全局 Long→String + 契约 §0 + 测试
-- ReelShortWeb `3ec9ea6`（develop，已推）：4 处 id 数字语义适配
-- ReelShort `94ff9f1`（**新建 develop**，已推）：客户端 Long 计数兼容解析
-**留痕**：`docs/plans/PROGRESS.md`（本轮追加 J1 段，含原始输出）；计划 `docs/plans/2026-10-16-J1.md`。
-
-**门禁数字**
-| 门禁 | 结果 |
-| --- | --- |
-| `mvn test` | **BUILD SUCCESS** — commerce 33 / admin-api 21 / app-api 49 / worker 12 = **115 条全过**（存量 110 未跑红，新增 5） |
-| `mvn … package -DskipTests` | BUILD SUCCESS |
-| `pnpm ts:check` / eslint / `pnpm build:pro` | 0 错误 / 0 error / Build successful |
-| `dart analyze lib test` / `flutter test` | No issues found! / All tests passed!（+167） |
-
-**每个仓库改了什么**
-
-FruitServer（后端）
-- 新增 `fruitshorts-framework/.../web/JacksonLongToStringConfig.java`（`Long`/`long` → 字符串；
-  `PageResult.total` 用 mixin 保持数字；`PlainLongSerializer` 供 mixin 使用）
-- `docs/api-phase1.md`：§0 新增「ID 字段一律以字符串下发」总口径（含示例、边界、`total` 例外），
-  §2.11/§2.12 改为引用 §0
-- I1 的特例回退：`ProductRespVO` / `NoticeRespVO` 去掉 `@JsonSerialize`，
-  `ProductAdminController` / `NoticeAdminController` 的 `create` 回到 `Result<Long>`
-- 测试：新增 `admin-api/.../web/LongToStringSerializationTest.java`（5 条）；
-  `ControllerContractSupport`（admin + app 两处）挂上模块，避免契约测试假绿；
-  C 端 4 条 id 断言改成 `value("…") + isString()`
-
-ReelShortWeb（4 个文件）
-- `src/utils/creatorImpersonation.ts` — 代看创作者 id 全程字符串（原来 `Number(raw)`，19 位会被四舍五入）
-- `src/views/contentManagement/EpisodeManagementView.vue` — `Number(route.query.drama)` → 字符串比较
-- `src/views/creator-center/composables/useDramaEdit.js` — `Number(route.params.id)` → 字符串比较
-- `src/views/permission/composables/useMenuManagement.js` — 顶级菜单哨兵 `0` → `'0'`（与接口的 `"0"` 对齐）
-
-ReelShort（Flutter）逐文件清单（**只有这些，没夹带别的**）
-- `lib/core/data/models/json_numbers.dart`（新增）— `jsonToInt`：接受数字或数字字符串
-- `lib/core/data/models/auth_session.dart` — `expiresIn`（后端 `long`）改用 `jsonToInt`
-- `lib/core/data/models/drama.dart` — `viewCount`（后端 `Long`）两处改用 `jsonToInt`
-- `test/core/json_id_parsing_test.dart`（新增）— 8 条回归用例
-
-**三个需要你确认的口径**
-
-1. **`PageResult.total` 保持数字（唯一例外）** —— 它是条数不是 id，前端分页组件（el-pagination / Flutter 分页）
-   都要数字。实测 `total = 2 int`。若你要求"Long 一律字符串"，删掉 `JacksonLongToStringConfig` 里那一行 mixin 即可。
-2. **反向（请求方向）未做限制**：请求体 `"id":"…"`、路径变量、查询参数都接受字符串并转 `Long`（有测试）。
-   `Integer`/`int`（`pageIndex`/`pageSize`/`Result.code`/`totalEpisodes`/`durationSec`…）保持数字 —— 实测已确认。
-3. **客户端适配范围比"只改 id 解析"宽了一点点，原因是物理上必须**：客户端 id 本来就是
-   `(json['id'] ?? '').toString()`，不会崩；真正会崩的是被全局规则扫到的 **Long 计数**，
-   所以改了 `expiresIn` 与 `viewCount` 共 3 处（`json_numbers.dart` 是新增工具）。
-   其余 8 处 `as num?` 对应的 Java 字段都是 `Integer`/`int`，**按最小改动原则没动**。
-   ⚠️ **ReelShort 仓库原来只有 `main`**（无 develop），我按条目要求新建了 `develop` 并在上面提交。
-   客户端由另一位同事推进，若他继续在 `main` 上走，需要把这笔 `94ff9f1` 带过去。
-
-**用户可照做的验证步骤（每步都有预期结果）**
-
-准备：`cd FruitServer && mvn -pl fruitshorts-app-api,fruitshorts-admin-api -am package -DskipTests`，起两个 jar；
-`curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:8080/v3/api-docs` → 200。
-
-1. **复现 PM 那条（最直观）**：注册一个 C 端账号
-   ```
-   curl -s -X POST http://127.0.0.1:8081/app/auth/register -H 'Content-Type: application/json' \
-     -d '{"targetType":"EMAIL","target":"你的邮箱@example.com","password":"Passw0rd!23","nickname":"手测","deviceId":"manual-1"}'
-   ```
-   预期：`"expiresIn": "7200"`（字符串）。
-2. **用响应里的 user id 调后台**：`curl -s "http://127.0.0.1:8080/admin/app-users/page?pageSize=50" -H "Authorization: Bearer <admin token>"`，
-   拿新用户的 `id`（预期是 `"2111…"` 这种**带引号的字符串**、`total` 是**不带引号的数字**），再
-   `curl -s "http://127.0.0.1:8080/admin/app-users/<id>" -H "Authorization: Bearer <token>"` → 预期 `code=0`、`data.id` 与列表一致
-   （**修复前这里返回 `200002 数据不存在`**）。
-3. **JS 逐位一致**：把第 2 步的响应存成 `r.json`，然后
-   ```
-   node -e 'const d=JSON.parse(require("fs").readFileSync("r.json","utf8"));console.log(String(d.data.id))'
-   ```
-   预期与 `psql -c "select id::text from app_user where uid='<uid>'"` **逐位相同**。
-   对照：`node -e 'console.log(String(JSON.parse("2111015748376858626")))'` → `2111015748376858620` 附近（会被改写），说明精度问题真实存在。
-4. **后台界面（:3005）**：`admin/admin123` 登录 → 商品配置新建一个商品 → **点它那一行的状态/编辑**，
-   预期正常（toast 成功，不再"商品不存在"）；菜单管理编辑一个顶级菜单，预期父级下拉显示「顶级菜单」而不是 `0`。
-5. **短剧管理 → 剧集管理带参跳转**：从短剧管理点某剧的「剧集」，URL 带 `?drama=<id>`，
-   预期剧集页自动选中该剧（改成字符串比较前这里会选不中）。
-6. **客户端**：`cd ReelShort && flutter test`（预期 All tests passed）；有设备时 `flutter run` 打开首页看播放量/详情
-   不报解析异常（后端 `viewCount` 现在下发字符串）。
-7. **异常路径**：请求体里 id 传**数字**（老客户端行为）也应被接受：`PUT /admin/products/<id>/status?status=1` 用数字 id 路径同样 200。
-
-**禅道**：J1 在禅道里同样没有对应任务（项目 2 下仍是 S0/S1/S0-16、A1–A6、B1/B2、C1–C3），未动任何既有任务状态。
-**服务现状**：8080/8081 是我刚重建起回的新 jar（自测时在跑）；:3005 的 dev server 也在。若被环境回收，按上面「准备」起回来即可。
-
----
-
-### 回执（Codex，2026-10-16）：K1 完成，停在干净交接点
-
-**提交**：`ReelShort d7eff4c`（develop，已推；`main` 未动）。留痕：`docs/plans/PROGRESS.md`；计划：`docs/plans/2026-10-16-K1.md`。
-
-**门禁**：`dart analyze lib test` → No issues found!；`flutter test` → **All tests passed!（188 条，存量 27 个测试文件未跑红）**；真实后端联调（8081）见下方原始输出。
-
-**先纠正条目里的一处勘察**：客户端**详情接口早已接上**（`CatalogApi.dramaDetail` + `CatalogController.requireDetail`，详情页在用），
-票据调用 `CatalogApi.playTicket` 也存在但**没有任何页面调用**。所以本轮真正做的是：把票据接进播放链路、进度从本地换服务端、
-收藏换服务端、补三态 UI。
-
-**改了什么（ReelShort，只列这一批）**
-新增：`remote/playback_api.dart`、`remote/watch_api.dart`、`remote/library_api.dart`、`models/watch_progress.dart`、
-`repositories/playback_repository.dart`、`repositories/favorite_repository.dart`、`services/favorite_controller.dart`、
-`formatting/error_text.dart`。
-改：`app.dart`（注入三个仓库 + 收藏控制器 + 登录/登出联动）、`remote/api_client.dart`（补 `delete`）、
-`remote/catalog_api.dart` 与 `repositories/catalog_repository.dart`、`services/catalog_controller.dart`（票据职责搬走）、
-`models/play_ticket.dart`（补 dramaId/number/title/previewSeconds）、`repositories/watch_history_repository.dart`（换服务端模型）、
-`pages/{discover,drama_detail,mine,player}/*`、`l10n/app_{en,zh,id}.arb` + 4 个生成文件。
-测试：新增 5 个（含 live 联调），改 8 个（含 fake 与 widget_test 的离线仓库注入）。
-
-**怎么改的（要点）**
-1. **起播前取票**：`PlaybackRepository.ticketFor()` 带 TTL 缓存（默认 10 分钟 < 后端 15 分钟签名），过期或 `forceRefresh` 时重取；
-   回前台发现票据过期会重新取。**签名地址原样交给播放器**（`AppConfig.mediaUrl` 只补 host，path 与 `?e=&s=` 不动，有测试钉住）。
-2. **accessType 驱动 UI**：`COIN_REQUIRED/VIP_REQUIRED` → 锁定提示 + "金币解锁即将开放"；`NO_MEDIA` → 暂无片源；
-   前端不推断能不能播（契约 §1.4 的硬要求）。付费解锁仍属 B2。
-3. **进度**：服务端每剧一条记录，`POST /app/watch/progress` 节流从 5 秒改成**10 秒**，切集/退出/切后台各补一次，播完带 `finished`；
-   续看位置只在"记录里的那一集"生效（其它集从头播）；`demoProfileId` 与本地 SharedPreferences 实现**已删除**。
-4. **收藏**：`FavoriteController` 以服务端返回为准，乐观更新 + 失败回滚 + 失败提示；退出登录清空（不跨账号串联）。
-5. **三态**：详情页（加载 / 失败可重试 / 空剧集）；播放页（票据加载中 / 失败可重试 / 后端判定不可播）；
-   我的页（续看读取失败可重试 / 收藏列表加载中·失败·空 / 最近观看加载中·失败·空）。断网与超时文案走 l10n（en/zh/id 各 8 个新键）。
-
-**原始联调输出（8081）**
-```
-① /app/home/feed                       → dramaId=5
-② /app/dramas/5                        → episodes=3；第一集 id='7'
-     playUrl=/files/episode/202610/cec39d8e….mp4?e=1792144372&s=8791826a…
-③ /app/episodes/7/play                 → episodeId='7' dramaId='5' accessType=FREE accessible=True
-④ POST /app/watch/progress (42s)       → positionMs="42000" durationMs="228000" playCount=1
-⑤ GET  /app/watch/progress?dramaId=5   → episodeId='7' positionMs='42000'   ← 续看位置读得回来
-⑥ GET  /app/watch/recent?limit=20      → 条数=1（dramaId='5' episodeId='7'）
-⑦ POST /app/favorites/toggle           → true；GET /app/favorites → 1 条；DELETE → 0 条
-$ flutter test test/integration/live_watch_flow_test.dart → All tests passed!
-```
-自测数据已清干净：`app_user` 只剩 PM 那条（id=28）、`watch_progress` 0、`user_favorite` 0。
-
-**哪些页面现在走真数据、哪些还是假的**
-| 页面/能力 | 数据来源 | 状态 |
-| --- | --- | --- |
-| 首页 / 发现页 | `/app/home/feed`、`/app/discover/feed` | ✅ 真数据（本批未动） |
-| 登录 / 注册 / 刷新 / 登出 | `/app/auth/*` | ✅ 真数据（本批未动） |
-| **详情页（剧集列表、可播地址）** | `/app/dramas/{id}` | ✅ 真数据 |
-| **详情页"继续观看"与剧集进度条** | `/app/watch/progress?dramaId=` | ✅ 本批接上（原来读本机） |
-| **播放页（票据/签名地址/起播判定）** | `/app/episodes/{id}/play` + accessType | ✅ 本批接上 |
-| **播放页进度上报（10s 节流）** | `POST /app/watch/progress` | ✅ 本批接上（原来存本机） |
-| **我的页：收藏列表 + 收藏按钮** | `/app/favorites*` | ✅ 本批接上（原来存本机） |
-| **我的页：最近观看** | `/app/watch/recent` | ✅ 接上；**只渲染能在已加载目录里按 id 匹配到的剧**，匹配不到先不显示（见待确认 2） |
-| 我的页：点赞 | 本地 `EngagementController` | ❌ 仍是本地假状态（属 **K3** 互动） |
-| 播放页：评论 | 本地 `DramaCommentsSheet` | ❌ 仍是本地（属 **K3**） |
-| 播放页：解锁付费集 | — | ❌ 本批不做（属 **B2**，票据已按 `accessType` 提示） |
-| 记录页 / 收藏列表页 / 分类搜索 / 下载 | — | ❌ 属 **K2** |
-
-**用户可照做的验证步骤（每步预期结果）**
-准备：后端两个 jar 起着（`admin=200`、`app=200`）；`cd ReelShort && flutter run`（模拟器用
-`--dart-define=API_BASE_URL=http://10.0.2.2:8081`；iOS/桌面用默认 127.0.0.1）。
-
-1. **匿名可看**：不登录进首页 → 点任一剧 → 详情正常出剧集列表；点某集能起播（免费集）。
-   预期：起播前有一瞬"加载票据"，无白屏；付费集显示"第 N 集已锁定 + 金币解锁即将开放"。
-2. **登录后进度**：用「我的 → 登录」注册/登录一个邮箱账号 → 进一部剧 → 看 20~30 秒 → 返回详情。
-   预期：详情页的"继续观看"按钮下方出现进度条与"续看至 mm:ss / mm:ss"，剧集行上也有一条进度条。
-3. **跨进程续看（真数据验证）**：杀进程重开 → 进同一部剧 → 直接点"继续观看"。
-   预期：从上次的位置继续播（不是从头）。也可以直接查库：
-   `psql -c "select drama_id, episode_id, position_ms from watch_progress order by updated_at desc limit 3;"` 预期有该剧记录。
-4. **收藏**：播放页右侧点收藏（或详情页右上角）→ 打开「我的 → Watchlist」。
-   预期：该剧出现在收藏列表；再点一次取消 → 从列表消失。断网时点收藏 → 提示"收藏操作失败，请重试"且图标回到原状态。
-5. **异常路径**：把后端停掉（`lsof -tiTCP:8081 -sTCP:LSLISTEN | xargs kill`）后进详情/播放。
-   预期：详情页给"网络异常，请检查网络后重试"+ 重试按钮；播放页给"此视频暂时无法播放"+ 重试；
-   我的页收藏区给失败文案 + 重试；**都不白屏、也不假装成功**。恢复后端后点重试即可继续。
-6. **一套命令验证（不用模拟器）**：
-   `cd ReelShort && flutter test test/integration/live_watch_flow_test.dart` → 预期 All tests passed（服务没起会 skip）。
-
-**待确认 / 如实说明**
-1. **票据过期用的是客户端 TTL（10 分钟）**，因为契约里 `play` 响应没有 `expiresAt` 字段。后端若补上过期时间，改成按字段判断即可（一行）。
-2. **`/app/watch/recent` 只返回 dramaId/episodeId/位置，没有剧名封面**，所以"我的页最近观看"目前按 id 去已加载的目录卡片里匹配；
-   匹配不到的条目先不显示。**K2 的记录页**建议要么后端补卡片字段，要么做成独立请求（已在计划里记为风险 4）。
-3. **`WatchHistoryRepository` 的接口签名被改了**（服务端是"每剧一条续看记录"，没有 profile 概念），连带改了 4 个 logic 与 6 个测试文件——
-   这是接口模型决定的，不是顺手重构；`clampResumePosition` 等本地工具函数保留。
-4. **未登录时**进度与收藏接口一律不发（匿名浏览/试看不受影响），收藏按钮沿用"先引导登录"。
-5. 禅道里仍**没有 K1 任务**（项目 2 下只有 S0/S1、A1–A6、B1/B2、C1–C3），未动任何既有任务状态。
-
----
-
-### 回执（Codex，2026-10-16）：K1-verify —— **未验证（真机验证由用户执行，Codex 未执行）**
-
-**结论先说**：按用户 20:45 指令「codex 不用跑测试 我来执行」，本批的**真机验证状态 = 未验证**，
-由用户执行后以其结果为准。我**没有**执行任何最终真机验证，也**没有**用任何"开发机 curl"当作设备可达证据。
-
-**交付物（ReelShort `develop`，已推）**
-- `pubspec.yaml`：dev_dependencies 加 `integration_test`（sdk）—— 唯一的新依赖
-- `integration_test/app_backend_test.dart`（新增，首行 `// Author: fruit.com.cn`）：两个设备侧用例
-  1. 在手机进程里请求 `/app/home/feed` 与 `/app/dramas/{id}`，断言列表非空、详情 id 与卡片一致；
-  2. 用**真 App**（真网络、真目录控制器）启动，轮询到首页底部标签栏出现 —— 即"剧目列表加载成功"，
-     也就是用户在真机上遇到的「剧目列表加载失败」是否消失。
-- 该文件**按用户要求保持原样，不再改动**。
-
-**当前机器状态（交接前已清理）**
-- 我起的 `flutter run` / `xcodebuild` / lsof 轮询进程**已全部终止**（`pgrep -fl "flutter_tools|xcodebuild"` 只剩 IDE 常驻 daemon，非构建）。
-- `build/` 里留着我被叫停那次构建的半成品 → **用户从 `flutter clean && flutter pub get` 起跑即可清掉**。
-- 后端 8080 / 8081 仍在跑（`admin=200` / `app=200`）。
-
-**用户可直接复制执行的命令（⚠️ 本项目 iOS 用 SPM，没有 Podfile，不要跑 `pod install`）**
-```bash
-# 0) 起点：清掉残留构建产物（我被打断的那次留下的）
-cd /Users/jianghaifeng/Desktop/ReelShort/ReelShort
-flutter clean && flutter pub get
-
-# 1) 取开发机真实局域网地址（不要硬编码；换网络会变）
-IP=$(ipconfig getifaddr en0) && echo "API_BASE_URL=http://$IP:8081"
-
-# 2) 设备侧集成测试（最硬的证据，跑在手机进程里）
-flutter test integration_test -d 00008101-000875813E42001E --dart-define=API_BASE_URL=http://$IP:8081
-
-# 2b) 只想跑网络那一条
-flutter test integration_test/app_backend_test.dart -d 00008101-000875813E42001E \
-  --plain-name "should_fetch_home_feed_and_drama_detail_when_device_reaches_backend" \
-  --dart-define=API_BASE_URL=http://$IP:8081
-
-# 3) 真机手动看 App（可选，验证首页列表与交互）
-flutter run -d 00008101-000875813E42001E --dart-define=API_BASE_URL=http://$IP:8081
-```
-（本次实测 `ipconfig getifaddr en0` = **192.168.31.187**；若换网络请以命令输出为准。）
-
-**前置条件**
-1. 手机与开发机在**同一局域网**（例如都在 192.168.31.x）。
-2. iPhone 已授权「**本地网络**」权限：设置 → 隐私与安全性 → 本地网络 → 打开本项目（App 名 **FruitShorts**）。
-   没授权时 App 请求局域网会失败；`Info.plist` 里 `NSLocalNetworkUsageDescription` 与
-   `NSAllowsLocalNetworking` 都已配好（上一批加的），所以系统应当会弹权限询问。
-3. 同一时刻**只跑一个** flutter 构建（并发写同一个 `build/` 会互相破坏产物 —— 这正是本次
-   `video_player_avfoundation…bundle: No such file or directory` 的疑似成因）。
-
-**设备侧证据看什么（红线第 10 条）**
-- 测试输出里必须出现**由手机进程打印**的：
-  - `[device] API_BASE_URL=http://192.168.31.187:8081`（证明手机上用的是局域网地址，不是开发机环回/VPN 地址）
-  - `[device] 首页分区=4 剧目=3` / `[device] 详情 id=5 剧集=3`（证明设备真的拿到了数据）
-  - `[device] 首页剧目列表已渲染：API_BASE_URL=http://192.168.31.187:8081`（证明真 App 首页列表出内容）
-  - 最后一行 `All tests passed!`
-- 若失败：`reason` 里会带上 `API_BASE_URL=…`，据此区分"地址不对"还是"设备连不上/权限未授权"。
-
-**如实说明（失败与历史记录，详见 PROGRESS 的 K1-verify 段）**
-- 我在 17:56 跑过一次，**那次是设备侧输出且全过**（上面那几行 `[device]` 就是它的原始输出）。
-- 随后两次执行失败：17:59 那次 `The Dart VM Service was not discovered after 60 seconds`（app 没 attach，我也没抓到任何手机→8081 的连接）；
-  18:03 那次 `flutter run` 构建完成后 PM 报产物缺失（`video_player_avfoundation…bundle: No such file or directory`）并叫停。
-- 因此**在用户重跑之前，本批一律按「未验证」计**；上面那次的历史输出只作参考，不作为结论。
+- 先写计划 `docs/plans/2026-10-21-K100-episode-batch-upload.md`，再改代码
+- 每跑一个命令，把「命令 + 原始输出 + 解读」追加到 `docs/plans/PROGRESS.md`
+- 不改 FruitServer、不改 ReelShort 客户端、不改接口契约
+- 禁止 `git add -A`；不要操作真机
+- 完成后停住等 PM 验收，回执需贴门禁原始输出

fruitshorts-admin-api/src/main/java/com/fruitshorts/admin/controller/CommentAdminController.java

@@ -35,8 +35,8 @@ public class CommentAdminController {
 
     private final CommentService commentService;
 
-    /** 检索评论：默认按状态过滤，`status=pending` 即审核队列。 */
-    @Operation(summary = "评论检索（默认按状态过滤，待审队列）")
+    /** 检索评论：status 为空时返回全部状态，传 pending 即审核队列。 */
+    @Operation(summary = "评论检索（status 为空返回全部状态）")
     @GetMapping("/page")
     @PreAuthorize("@ss.hasPermission('comment:list')")
     public Result<PageResult<CommentRespVO>> page(CommentQueryReqVO req) {

fruitshorts-admin-api/src/main/java/com/fruitshorts/admin/controller/DramaController.java

@@ -6,12 +6,14 @@ import com.fruitshorts.common.pojo.PageResult;
 import com.fruitshorts.common.pojo.Result;
 import com.fruitshorts.content.dal.entity.DramaReviewRecord;
 import com.fruitshorts.content.service.DramaService;
+import com.fruitshorts.content.service.EpisodeService;
 import com.fruitshorts.content.vo.DramaPageReqVO;
 import com.fruitshorts.content.vo.DramaRespVO;
 import com.fruitshorts.content.vo.DramaSaveReqVO;
 import com.fruitshorts.content.vo.DramaStatusReqVO;
-import com.fruitshorts.framework.security.SecurityUtils;
 import com.fruitshorts.framework.log.OperationLog;
+import com.fruitshorts.framework.security.SecurityUtils;
+import com.fruitshorts.interaction.service.CommentService;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
@@ -27,6 +29,7 @@ import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
 
 import java.util.List;
+import java.util.Map;
 
 @Tag(name = "后台-短剧管理")
 @RestController
@@ -35,19 +38,25 @@ import java.util.List;
 public class DramaController {
 
     private final DramaService dramaService;
+    private final CommentService commentService;
+    private final EpisodeService episodeService;
 
     @Operation(summary = "短剧分页查询")
     @GetMapping("/page")
     @PreAuthorize("@ss.hasPermission('drama:list')")
     public Result<PageResult<DramaRespVO>> page(DramaPageReqVO req) {
-        return Result.ok(dramaService.page(req));
+        PageResult<DramaRespVO> page = dramaService.page(req);
+        fillInteractionCounts(page.getList());
+        return Result.ok(page);
     }
 
     @Operation(summary = "短剧详情")
     @GetMapping("/{id}")
     @PreAuthorize("@ss.hasPermission('drama:list')")
     public Result<DramaRespVO> get(@PathVariable Long id) {
-        return Result.ok(dramaService.get(id));
+        DramaRespVO drama = dramaService.get(id);
+        fillInteractionCounts(List.of(drama));
+        return Result.ok(drama);
     }
 
     @Operation(summary = "新建短剧")
@@ -133,4 +142,17 @@ public class DramaController {
         dramaService.changeStatus(id, action, req == null ? null : req.getReason(),
                 SecurityUtils.getUserId(), SecurityUtils.getUsername());
     }
+
+    private void fillInteractionCounts(List<DramaRespVO> dramas) {
+        if (dramas == null || dramas.isEmpty()) {
+            return;
+        }
+        List<Long> ids = dramas.stream().map(DramaRespVO::getId).toList();
+        Map<Long, Long> likeCounts = episodeService.sumLikeCountsByDramas(ids);
+        Map<Long, Long> commentCounts = commentService.countByDramas(ids);
+        dramas.forEach(drama -> {
+            drama.setLikeCount(likeCounts.getOrDefault(drama.getId(), 0L));
+            drama.setCommentCount(commentCounts.getOrDefault(drama.getId(), 0L));
+        });
+    }
 }

fruitshorts-admin-api/src/main/java/com/fruitshorts/admin/controller/EpisodeController.java

@@ -3,11 +3,14 @@
 package com.fruitshorts.admin.controller;
 
 import com.fruitshorts.common.pojo.Result;
+import com.fruitshorts.content.dal.entity.Drama;
+import com.fruitshorts.content.service.DramaService;
 import com.fruitshorts.content.service.EpisodeService;
 import com.fruitshorts.content.vo.EpisodeRespVO;
 import com.fruitshorts.content.vo.EpisodeSaveReqVO;
 import com.fruitshorts.content.vo.EpisodeSortReqVO;
 import com.fruitshorts.framework.log.OperationLog;
+import com.fruitshorts.interaction.service.CommentService;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
@@ -24,6 +27,7 @@ import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RestController;
 
 import java.util.List;
+import java.util.Map;
 
 @Tag(name = "后台-剧集管理")
 @RestController
@@ -32,13 +36,24 @@ import java.util.List;
 public class EpisodeController {
 
     private final EpisodeService episodeService;
+    private final CommentService commentService;
+    private final DramaService dramaService;
 
     @Operation(summary = "剧集列表")
     @GetMapping
     @PreAuthorize("@ss.hasPermission('episode:list')")
     public Result<List<EpisodeRespVO>> list(@RequestParam Long dramaId,
                                             @RequestParam(required = false) String status) {
-        return Result.ok(episodeService.listByDrama(dramaId, status));
+        List<EpisodeRespVO> episodes = episodeService.listByDrama(dramaId, status);
+        Map<Long, Long> commentCounts = commentService.countByEpisodes(
+                episodes.stream().map(EpisodeRespVO::getId).toList());
+        Drama drama = dramaService.getExisting(dramaId);
+        episodes.forEach(episode -> {
+            episode.setCommentCount(commentCounts.getOrDefault(episode.getId(), 0L));
+            episode.setFavoriteCount(drama.getFavoriteCount());
+            episode.setHeat(drama.getViewCount());
+        });
+        return Result.ok(episodes);
     }
 
     @Operation(summary = "新建剧集")

fruitshorts-admin-api/src/main/java/com/fruitshorts/admin/controller/ReportAdminController.java

@@ -2,11 +2,12 @@
 
 package com.fruitshorts.admin.controller;
 
+import com.fruitshorts.admin.service.ReportAdminService;
+import com.fruitshorts.admin.vo.AdminReportRespVO;
 import com.fruitshorts.common.pojo.PageResult;
 import com.fruitshorts.common.pojo.Result;
 import com.fruitshorts.framework.log.OperationLog;
 import com.fruitshorts.framework.security.SecurityUtils;
-import com.fruitshorts.interaction.dal.entity.ContentReport;
 import com.fruitshorts.interaction.service.ReportService;
 import com.fruitshorts.interaction.vo.ReportHandleReqVO;
 import com.fruitshorts.interaction.vo.ReportQueryReqVO;
@@ -28,13 +29,14 @@ import org.springframework.web.bind.annotation.RestController;
 @RequiredArgsConstructor
 public class ReportAdminController {
 
+    private final ReportAdminService reportAdminService;
     private final ReportService reportService;
 
     @Operation(summary = "举报工单分页查询")
     @GetMapping("/page")
     @PreAuthorize("@ss.hasPermission('report:list')")
-    public Result<PageResult<ContentReport>> page(ReportQueryReqVO req) {
-        return Result.ok(reportService.page(req));
+    public Result<PageResult<AdminReportRespVO>> page(ReportQueryReqVO req) {
+        return Result.ok(reportAdminService.page(req));
     }
 
     /** 处理工单：结论成立会联动驳回被举报评论，可选择同时封禁被举报用户。 */

fruitshorts-admin-api/src/main/java/com/fruitshorts/admin/controller/WatchHistoryAdminController.java

@@ -0,0 +1,33 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.admin.controller;
+
+import com.fruitshorts.admin.service.WatchHistoryAdminService;
+import com.fruitshorts.admin.vo.AdminWatchHistoryVO;
+import com.fruitshorts.admin.vo.WatchHistoryQueryReqVO;
+import com.fruitshorts.common.pojo.PageResult;
+import com.fruitshorts.common.pojo.Result;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import lombok.RequiredArgsConstructor;
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+/** 后台跨用户观看记录检索。 */
+@Tag(name = "后台-观看记录")
+@RestController
+@RequestMapping("/admin/watch-history")
+@RequiredArgsConstructor
+public class WatchHistoryAdminController {
+
+    private final WatchHistoryAdminService watchHistoryAdminService;
+
+    @Operation(summary = "观看记录分页查询")
+    @GetMapping("/page")
+    @PreAuthorize("@ss.hasPermission('watch-history:list')")
+    public Result<PageResult<AdminWatchHistoryVO>> page(WatchHistoryQueryReqVO req) {
+        return Result.ok(watchHistoryAdminService.page(req));
+    }
+}

fruitshorts-admin-api/src/main/java/com/fruitshorts/admin/service/ReportAdminService.java

@@ -0,0 +1,283 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.admin.service;
+
+import com.baomidou.mybatisplus.core.metadata.IPage;
+import com.baomidou.mybatisplus.core.toolkit.Wrappers;
+import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
+import com.fruitshorts.admin.vo.AdminReportRespVO;
+import com.fruitshorts.common.pojo.PageResult;
+import com.fruitshorts.content.dal.entity.Drama;
+import com.fruitshorts.content.dal.entity.DramaEpisode;
+import com.fruitshorts.content.dal.mapper.DramaEpisodeMapper;
+import com.fruitshorts.content.dal.mapper.DramaMapper;
+import com.fruitshorts.interaction.dal.entity.ContentComment;
+import com.fruitshorts.interaction.dal.entity.ContentReport;
+import com.fruitshorts.interaction.dal.mapper.ContentCommentMapper;
+import com.fruitshorts.interaction.dal.mapper.ContentReportMapper;
+import com.fruitshorts.interaction.service.CommentService;
+import com.fruitshorts.interaction.service.ReportService;
+import com.fruitshorts.interaction.vo.ReportQueryReqVO;
+import com.fruitshorts.user.dal.entity.AppUser;
+import com.fruitshorts.user.dal.mapper.AppUserMapper;
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Service;
+import org.springframework.util.StringUtils;
+
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+
+/**
+ * 后台举报工单分页与目标展示信息装配。
+ *
+ * <p>举报只保存目标类型和 id；该服务在当前页一次性加载评论、剧、集和用户，
+ * 避免列表逐行查询，同时保持原举报处理流程不变。
+ */
+@Service
+@RequiredArgsConstructor
+public class ReportAdminService {
+
+    private static final int DEFAULT_PAGE_INDEX = 1;
+    private static final int DEFAULT_PAGE_SIZE = 10;
+    private static final int DELETED_FLAG = 1;
+
+    private final ContentReportMapper reportMapper;
+    private final ContentCommentMapper commentMapper;
+    private final DramaMapper dramaMapper;
+    private final DramaEpisodeMapper episodeMapper;
+    private final AppUserMapper appUserMapper;
+
+    /** 按举报工单筛选条件分页查询，并补齐展示字段。 */
+    public PageResult<AdminReportRespVO> page(ReportQueryReqVO req) {
+        Page<ContentReport> page = new Page<>(
+                req.getPageIndex() == null || req.getPageIndex() < 1
+                        ? DEFAULT_PAGE_INDEX : req.getPageIndex(),
+                req.getPageSize() == null || req.getPageSize() < 1
+                        ? DEFAULT_PAGE_SIZE : req.getPageSize());
+        IPage<ContentReport> result = reportMapper.selectPage(page,
+                Wrappers.<ContentReport>lambdaQuery()
+                        .eq(StringUtils.hasText(req.getStatus()),
+                                ContentReport::getStatus, req.getStatus())
+                        .eq(StringUtils.hasText(req.getTargetType()),
+                                ContentReport::getTargetType, req.getTargetType())
+                        .eq(StringUtils.hasText(req.getReasonCode()),
+                                ContentReport::getReasonCode, req.getReasonCode())
+                        .eq(req.getReporterId() != null,
+                                ContentReport::getReporterId, req.getReporterId())
+                        .orderByDesc(ContentReport::getId));
+        return new PageResult<>(result.getTotal(), toVoList(result.getRecords()));
+    }
+
+    private List<AdminReportRespVO> toVoList(List<ContentReport> rows) {
+        if (rows.isEmpty()) {
+            return List.of();
+        }
+        Map<Long, ContentComment> comments = loadComments(rows);
+        Map<Long, Drama> dramas = loadDramas(rows, comments);
+        Map<Long, DramaEpisode> episodes = loadEpisodes(comments);
+        Map<Long, AppUser> users = loadUsers(rows);
+        List<AdminReportRespVO> list = new ArrayList<>(rows.size());
+        for (ContentReport row : rows) {
+            list.add(toVo(row, comments, dramas, episodes, users));
+        }
+        return list;
+    }
+
+    private Map<Long, ContentComment> loadComments(List<ContentReport> rows) {
+        List<Long> ids = rows.stream()
+                .filter(row -> ReportService.TYPE_COMMENT.equals(row.getTargetType()))
+                .map(ContentReport::getTargetId)
+                .filter(id -> id != null && id > 0L)
+                .distinct()
+                .toList();
+        Map<Long, ContentComment> result = new HashMap<>();
+        if (ids.isEmpty()) {
+            return result;
+        }
+        for (ContentComment comment : commentMapper.selectByIdsIncludingDeleted(ids)) {
+            result.put(comment.getId(), comment);
+        }
+        return result;
+    }
+
+    private Map<Long, Drama> loadDramas(List<ContentReport> rows,
+                                       Map<Long, ContentComment> comments) {
+        Set<Long> ids = new LinkedHashSet<>();
+        for (ContentReport row : rows) {
+            if (ReportService.TYPE_DRAMA.equals(row.getTargetType())) {
+                addPositive(ids, row.getTargetId());
+                continue;
+            }
+            if (ReportService.TYPE_COMMENT.equals(row.getTargetType())) {
+                ContentComment comment = comments.get(row.getTargetId());
+                if (!isDeleted(comment)) {
+                    addPositive(ids, comment.getDramaId());
+                }
+            }
+        }
+        Map<Long, Drama> result = new HashMap<>();
+        if (ids.isEmpty()) {
+            return result;
+        }
+        for (Drama drama : dramaMapper.selectBatchIds(ids)) {
+            result.put(drama.getId(), drama);
+        }
+        return result;
+    }
+
+    private Map<Long, DramaEpisode> loadEpisodes(Map<Long, ContentComment> comments) {
+        Set<Long> ids = new LinkedHashSet<>();
+        for (ContentComment comment : comments.values()) {
+            if (!isDeleted(comment)) {
+                addPositive(ids, comment.getEpisodeId());
+            }
+        }
+        Map<Long, DramaEpisode> result = new HashMap<>();
+        if (ids.isEmpty()) {
+            return result;
+        }
+        for (DramaEpisode episode : episodeMapper.selectBatchIds(ids)) {
+            result.put(episode.getId(), episode);
+        }
+        return result;
+    }
+
+    private Map<Long, AppUser> loadUsers(List<ContentReport> rows) {
+        Set<Long> ids = new LinkedHashSet<>();
+        for (ContentReport row : rows) {
+            addPositive(ids, row.getReporterId());
+            if (ReportService.TYPE_USER.equals(row.getTargetType())) {
+                addPositive(ids, row.getTargetId());
+            }
+        }
+        Map<Long, AppUser> result = new HashMap<>();
+        if (ids.isEmpty()) {
+            return result;
+        }
+        for (AppUser user : appUserMapper.selectBatchIds(ids)) {
+            result.put(user.getId(), user);
+        }
+        return result;
+    }
+
+    private AdminReportRespVO toVo(ContentReport report,
+                                   Map<Long, ContentComment> comments,
+                                   Map<Long, Drama> dramas,
+                                   Map<Long, DramaEpisode> episodes,
+                                   Map<Long, AppUser> users) {
+        AdminReportRespVO vo = new AdminReportRespVO();
+        copyReport(report, vo);
+        fillReporter(report, users.get(report.getReporterId()), vo);
+        if (ReportService.TYPE_COMMENT.equals(report.getTargetType())) {
+            fillCommentTarget(report, comments.get(report.getTargetId()), dramas, episodes, vo);
+        } else if (ReportService.TYPE_DRAMA.equals(report.getTargetType())) {
+            fillDramaTarget(report, dramas.get(report.getTargetId()), vo);
+        } else if (ReportService.TYPE_USER.equals(report.getTargetType())) {
+            fillUserTarget(report, users.get(report.getTargetId()), vo);
+        }
+        return vo;
+    }
+
+    private void copyReport(ContentReport report, AdminReportRespVO vo) {
+        vo.setId(report.getId());
+        vo.setReporterId(report.getReporterId());
+        vo.setTargetType(report.getTargetType());
+        vo.setTargetId(report.getTargetId());
+        vo.setReasonCode(report.getReasonCode());
+        vo.setDescription(report.getDescription());
+        vo.setStatus(report.getStatus());
+        vo.setHandleBy(report.getHandleBy());
+        vo.setHandleAt(report.getHandleAt());
+        vo.setHandleNote(report.getHandleNote());
+        vo.setCreatedAt(report.getCreatedAt());
+    }
+
+    private void fillReporter(ContentReport report, AppUser reporter, AdminReportRespVO vo) {
+        if (reporter != null) {
+            vo.setReporterNickname(reporter.getNickname());
+            vo.setReporterUid(reporter.getUid());
+        }
+    }
+
+    private void fillCommentTarget(ContentReport report, ContentComment comment,
+                                   Map<Long, Drama> dramas,
+                                   Map<Long, DramaEpisode> episodes,
+                                   AdminReportRespVO vo) {
+        if (isDeleted(comment)) {
+            vo.setTargetSummary("评论 #" + report.getTargetId());
+            return;
+        }
+        Drama drama = dramas.get(comment.getDramaId());
+        if (drama == null) {
+            vo.setTargetSummary("评论 #" + report.getTargetId());
+            return;
+        }
+        DramaEpisode episode = episodes.get(comment.getEpisodeId());
+        vo.setDramaId(comment.getDramaId());
+        vo.setDramaTitle(drama.getTitle());
+        vo.setEpisodeId(comment.getEpisodeId());
+        vo.setCommentContent(comment.getContent());
+        if (episode == null) {
+            vo.setTargetSummary(drama.getTitle());
+            return;
+        }
+        vo.setEpisodeNo(episode.getEpNo());
+        vo.setEpisodeTitle(episode.getTitle());
+        String summary = drama.getTitle() + " · 第 " + episode.getEpNo() + " 集";
+        if (StringUtils.hasText(episode.getTitle())) {
+            summary += " · " + episode.getTitle();
+        }
+        vo.setTargetSummary(summary);
+    }
+
+    private void fillDramaTarget(ContentReport report, Drama drama, AdminReportRespVO vo) {
+        vo.setDramaId(report.getTargetId());
+        if (drama == null) {
+            vo.setTargetSummary("短剧 #" + report.getTargetId());
+            return;
+        }
+        vo.setDramaTitle(drama.getTitle());
+        vo.setTargetSummary(drama.getTitle());
+    }
+
+    private void fillUserTarget(ContentReport report, AppUser user, AdminReportRespVO vo) {
+        if (user == null) {
+            vo.setTargetSummary("用户 #" + report.getTargetId());
+            return;
+        }
+        vo.setTargetNickname(user.getNickname());
+        vo.setTargetUid(user.getUid());
+        vo.setTargetSummary(formatUser(user, report.getTargetId()));
+    }
+
+    private String formatUser(AppUser user, Long fallbackId) {
+        boolean hasNickname = StringUtils.hasText(user.getNickname());
+        boolean hasUid = StringUtils.hasText(user.getUid());
+        if (hasNickname && hasUid) {
+            return user.getNickname() + "（" + user.getUid() + "）";
+        }
+        if (hasNickname) {
+            return user.getNickname();
+        }
+        if (hasUid) {
+            return user.getUid();
+        }
+        return "用户 #" + fallbackId;
+    }
+
+    private boolean isDeleted(ContentComment comment) {
+        return comment == null
+                || CommentService.STATUS_DELETED.equals(comment.getStatus())
+                || Integer.valueOf(DELETED_FLAG).equals(comment.getDeleted());
+    }
+
+    private void addPositive(Set<Long> ids, Long id) {
+        if (id != null && id > 0L) {
+            ids.add(id);
+        }
+    }
+}

fruitshorts-admin-api/src/main/java/com/fruitshorts/admin/service/WatchHistoryAdminService.java

@@ -0,0 +1,198 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.admin.service;
+
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.baomidou.mybatisplus.core.metadata.IPage;
+import com.baomidou.mybatisplus.core.toolkit.Wrappers;
+import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
+import com.fruitshorts.admin.vo.AdminWatchHistoryVO;
+import com.fruitshorts.admin.vo.WatchHistoryQueryReqVO;
+import com.fruitshorts.common.pojo.PageResult;
+import com.fruitshorts.content.dal.entity.Drama;
+import com.fruitshorts.content.dal.entity.DramaEpisode;
+import com.fruitshorts.content.dal.mapper.DramaEpisodeMapper;
+import com.fruitshorts.content.dal.mapper.DramaMapper;
+import com.fruitshorts.content.enums.ContentStatus;
+import com.fruitshorts.playback.dal.entity.WatchHistory;
+import com.fruitshorts.playback.dal.mapper.WatchHistoryMapper;
+import com.fruitshorts.user.dal.entity.AppUser;
+import com.fruitshorts.user.dal.mapper.AppUserMapper;
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Service;
+import org.springframework.util.StringUtils;
+
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * 后台观看记录分页与跨域装配。
+ *
+ * <p>观看流水是播放域的原始事件，用户、短剧与分集资料分别位于用户和内容域。
+ * 该服务位于 admin-api 聚合层，直接注入只读 Mapper，避免反向扩展业务模块依赖。
+ */
+@Service
+@RequiredArgsConstructor
+public class WatchHistoryAdminService {
+
+    private static final int DEFAULT_PAGE_INDEX = 1;
+    private static final int DEFAULT_PAGE_SIZE = 10;
+    private static final int MAX_PAGE_SIZE = 100;
+    private static final long FINISHED_TOLERANCE_MS = 1000L;
+
+    private final WatchHistoryMapper watchHistoryMapper;
+    private final AppUserMapper appUserMapper;
+    private final DramaMapper dramaMapper;
+    private final DramaEpisodeMapper dramaEpisodeMapper;
+
+    /** 按后台筛选条件分页查询观看记录。 */
+    public PageResult<AdminWatchHistoryVO> page(WatchHistoryQueryReqVO req) {
+        int pageIndex = req.getPageIndex() == null || req.getPageIndex() < 1
+                ? DEFAULT_PAGE_INDEX : req.getPageIndex();
+        int pageSize = req.getPageSize() == null || req.getPageSize() < 1
+                ? DEFAULT_PAGE_SIZE : Math.min(req.getPageSize(), MAX_PAGE_SIZE);
+        List<Long> matchedUserIds = StringUtils.hasText(req.getKeyword())
+                ? searchUserIds(req.getKeyword()) : null;
+        if (matchedUserIds != null && matchedUserIds.isEmpty()) {
+            return emptyPage();
+        }
+        List<Long> matchedDramaIds = StringUtils.hasText(req.getDramaTitle())
+                ? searchDramaIds(req.getDramaTitle()) : null;
+        if (matchedDramaIds != null && matchedDramaIds.isEmpty()) {
+            return emptyPage();
+        }
+        IPage<WatchHistory> result = watchHistoryMapper.selectPage(new Page<>(pageIndex, pageSize),
+                buildQuery(req, matchedUserIds, matchedDramaIds));
+        return new PageResult<>(result.getTotal(), toVoList(result.getRecords()));
+    }
+
+    private LambdaQueryWrapper<WatchHistory> buildQuery(WatchHistoryQueryReqVO req,
+                                                        List<Long> matchedUserIds,
+                                                        List<Long> matchedDramaIds) {
+        LambdaQueryWrapper<WatchHistory> wrapper = Wrappers.<WatchHistory>lambdaQuery()
+                .eq(req.getUserId() != null, WatchHistory::getUserId, req.getUserId())
+                .in(matchedUserIds != null, WatchHistory::getUserId, matchedUserIds)
+                .eq(req.getDramaId() != null, WatchHistory::getDramaId, req.getDramaId())
+                .in(matchedDramaIds != null, WatchHistory::getDramaId, matchedDramaIds)
+                .eq(req.getEpisodeId() != null, WatchHistory::getEpisodeId, req.getEpisodeId())
+                .eq(StringUtils.hasText(req.getSource()), WatchHistory::getSource, req.getSource())
+                .ge(req.getStartTime() != null, WatchHistory::getWatchedAt, req.getStartTime())
+                .le(req.getEndTime() != null, WatchHistory::getWatchedAt, req.getEndTime());
+        applyFinished(wrapper, req.getFinished());
+        return wrapper.orderByDesc(WatchHistory::getWatchedAt)
+                .orderByDesc(WatchHistory::getId);
+    }
+
+    private void applyFinished(LambdaQueryWrapper<WatchHistory> wrapper, Boolean finished) {
+        if (Boolean.TRUE.equals(finished)) {
+            wrapper.gt(WatchHistory::getDurationMs, 0L)
+                    .apply("position_ms + {0} >= duration_ms", FINISHED_TOLERANCE_MS);
+        } else if (Boolean.FALSE.equals(finished)) {
+            wrapper.and(query -> query.eq(WatchHistory::getDurationMs, 0L)
+                    .or()
+                    .apply("position_ms + {0} < duration_ms", FINISHED_TOLERANCE_MS));
+        }
+    }
+
+    private List<Long> searchUserIds(String keyword) {
+        String value = keyword.trim();
+        return appUserMapper.selectList(Wrappers.<AppUser>lambdaQuery()
+                        .select(AppUser::getId)
+                        .and(query -> query.like(AppUser::getUid, value)
+                                .or()
+                                .like(AppUser::getNickname, value)))
+                .stream()
+                .map(AppUser::getId)
+                .toList();
+    }
+
+    private List<Long> searchDramaIds(String dramaTitle) {
+        String value = dramaTitle.trim();
+        return dramaMapper.selectList(Wrappers.<Drama>lambdaQuery()
+                        .select(Drama::getId)
+                        .like(Drama::getTitle, value))
+                .stream()
+                .map(Drama::getId)
+                .toList();
+    }
+
+    private List<AdminWatchHistoryVO> toVoList(List<WatchHistory> rows) {
+        if (rows.isEmpty()) {
+            return List.of();
+        }
+        Map<Long, AppUser> users = loadUsers(rows);
+        Map<Long, Drama> dramas = loadDramas(rows);
+        Map<Long, DramaEpisode> episodes = loadEpisodes(rows);
+        List<AdminWatchHistoryVO> list = new ArrayList<>(rows.size());
+        for (WatchHistory row : rows) {
+            list.add(toVo(row, users.get(row.getUserId()), dramas.get(row.getDramaId()),
+                    episodes.get(row.getEpisodeId())));
+        }
+        return list;
+    }
+
+    private Map<Long, AppUser> loadUsers(List<WatchHistory> rows) {
+        Map<Long, AppUser> result = new HashMap<>();
+        List<Long> ids = rows.stream().map(WatchHistory::getUserId).distinct().toList();
+        for (AppUser user : appUserMapper.selectBatchIds(ids)) {
+            result.put(user.getId(), user);
+        }
+        return result;
+    }
+
+    private Map<Long, Drama> loadDramas(List<WatchHistory> rows) {
+        Map<Long, Drama> result = new HashMap<>();
+        List<Long> ids = rows.stream().map(WatchHistory::getDramaId).distinct().toList();
+        for (Drama drama : dramaMapper.selectBatchIds(ids)) {
+            result.put(drama.getId(), drama);
+        }
+        return result;
+    }
+
+    private Map<Long, DramaEpisode> loadEpisodes(List<WatchHistory> rows) {
+        Map<Long, DramaEpisode> result = new HashMap<>();
+        List<Long> ids = rows.stream().map(WatchHistory::getEpisodeId).distinct().toList();
+        for (DramaEpisode episode : dramaEpisodeMapper.selectBatchIds(ids)) {
+            result.put(episode.getId(), episode);
+        }
+        return result;
+    }
+
+    private AdminWatchHistoryVO toVo(WatchHistory row, AppUser user, Drama drama,
+                                     DramaEpisode episode) {
+        AdminWatchHistoryVO vo = new AdminWatchHistoryVO();
+        vo.setId(row.getId());
+        vo.setUserId(row.getUserId());
+        vo.setDramaId(row.getDramaId());
+        vo.setEpisodeId(row.getEpisodeId());
+        vo.setPositionMs(row.getPositionMs());
+        vo.setDurationMs(row.getDurationMs());
+        vo.setSource(row.getSource());
+        vo.setDeviceId(row.getDeviceId());
+        vo.setWatchedAt(row.getWatchedAt());
+        long position = row.getPositionMs() == null ? 0L : row.getPositionMs();
+        long duration = row.getDurationMs() == null ? 0L : row.getDurationMs();
+        vo.setFinished(duration > 0L && position + FINISHED_TOLERANCE_MS >= duration);
+        if (user != null) {
+            vo.setUid(user.getUid());
+            vo.setNickname(user.getNickname());
+        }
+        if (drama != null) {
+            vo.setDramaTitle(drama.getTitle());
+            vo.setDramaPublished(ContentStatus.PUBLISHED.getCode().equals(drama.getStatus()));
+        } else {
+            vo.setDramaPublished(false);
+        }
+        if (episode != null) {
+            vo.setEpisodeNo(episode.getEpNo());
+            vo.setEpisodeTitle(episode.getTitle());
+        }
+        return vo;
+    }
+
+    private PageResult<AdminWatchHistoryVO> emptyPage() {
+        return new PageResult<>(0L, List.of());
+    }
+}

fruitshorts-admin-api/src/main/java/com/fruitshorts/admin/vo/AdminReportRespVO.java

@@ -0,0 +1,35 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.admin.vo;
+
+import lombok.Data;
+
+import java.time.LocalDateTime;
+
+/** 后台举报工单视图，附带举报人与被举报目标的展示信息。 */
+@Data
+public class AdminReportRespVO {
+
+    private Long id;
+    private Long reporterId;
+    private String reporterNickname;
+    private String reporterUid;
+    private String targetType;
+    private Long targetId;
+    private String targetSummary;
+    private Long dramaId;
+    private String dramaTitle;
+    private Long episodeId;
+    private Integer episodeNo;
+    private String episodeTitle;
+    private String commentContent;
+    private String targetNickname;
+    private String targetUid;
+    private String reasonCode;
+    private String description;
+    private String status;
+    private Long handleBy;
+    private LocalDateTime handleAt;
+    private String handleNote;
+    private LocalDateTime createdAt;
+}

fruitshorts-admin-api/src/main/java/com/fruitshorts/admin/vo/AdminWatchHistoryVO.java

@@ -0,0 +1,33 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.admin.vo;
+
+import lombok.Data;
+
+import java.time.LocalDateTime;
+
+/**
+ * 后台观看记录行。
+ *
+ * <p>页面需要识别用户、短剧、分集与完播状态，因此由 admin-api 聚合流水与基础资料。
+ */
+@Data
+public class AdminWatchHistoryVO {
+
+    private Long id;
+    private Long userId;
+    private String uid;
+    private String nickname;
+    private Long dramaId;
+    private String dramaTitle;
+    private Boolean dramaPublished;
+    private Long episodeId;
+    private Integer episodeNo;
+    private String episodeTitle;
+    private Long positionMs;
+    private Long durationMs;
+    private Boolean finished;
+    private String source;
+    private String deviceId;
+    private LocalDateTime watchedAt;
+}

fruitshorts-admin-api/src/main/java/com/fruitshorts/admin/vo/WatchHistoryQueryReqVO.java

@@ -0,0 +1,31 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.admin.vo;
+
+import lombok.Data;
+import org.springframework.format.annotation.DateTimeFormat;
+
+import java.time.LocalDateTime;
+
+/** 后台观看记录分页检索条件。 */
+@Data
+public class WatchHistoryQueryReqVO {
+
+    private Integer pageIndex = 1;
+    private Integer pageSize = 10;
+    /** uid / 昵称模糊检索 */
+    private String keyword;
+    private Long userId;
+    /** 短剧名称模糊检索 */
+    private String dramaTitle;
+    private Long dramaId;
+    private Long episodeId;
+    private String source;
+    private Boolean finished;
+
+    @DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss")
+    private LocalDateTime startTime;
+
+    @DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss")
+    private LocalDateTime endTime;
+}

fruitshorts-admin-api/src/main/resources/application.yml

@@ -66,3 +66,15 @@ springdoc:
 logging:
   level:
     com.fruitshorts: debug
+
+management:
+  endpoints:
+    web:
+      exposure:
+        include: prometheus,health
+  endpoint:
+    health:
+      show-details: always
+  metrics:
+    tags:
+      application: ${spring.application.name}

fruitshorts-admin-api/src/test/java/com/fruitshorts/admin/controller/DramaControllerContractTest.java

@@ -0,0 +1,92 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.admin.controller;
+
+import com.fruitshorts.admin.support.ControllerContractSupport;
+import com.fruitshorts.common.pojo.PageResult;
+import com.fruitshorts.content.service.DramaService;
+import com.fruitshorts.content.service.EpisodeService;
+import com.fruitshorts.content.vo.DramaPageReqVO;
+import com.fruitshorts.content.vo.DramaRespVO;
+import com.fruitshorts.interaction.service.CommentService;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.test.web.servlet.MockMvc;
+
+import java.util.List;
+import java.util.Map;
+
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.BDDMockito.given;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+/** 后台短剧列表与详情的互动数量回填契约。 */
+class DramaControllerContractTest {
+
+    private DramaService dramaService;
+    private CommentService commentService;
+    private EpisodeService episodeService;
+    private MockMvc mockMvc;
+
+    @BeforeEach
+    void setUp() {
+        dramaService = mock(DramaService.class);
+        commentService = mock(CommentService.class);
+        episodeService = mock(EpisodeService.class);
+        mockMvc = ControllerContractSupport.mockMvcOf(
+                new DramaController(dramaService, commentService, episodeService));
+    }
+
+    @Test
+    void should_fill_comment_counts_in_batch_when_page_is_requested() throws Exception {
+        DramaRespVO first = drama(7L, 3200L, 1800L);
+        DramaRespVO second = drama(8L, 120L, 80L);
+        given(dramaService.page(any(DramaPageReqVO.class)))
+                .willReturn(new PageResult<>(2L, List.of(first, second)));
+        given(commentService.countByDramas(List.of(7L, 8L)))
+                .willReturn(Map.of(7L, 11L));
+        given(episodeService.sumLikeCountsByDramas(List.of(7L, 8L)))
+                .willReturn(Map.of(7L, 3200L, 8L, 120L));
+
+        mockMvc.perform(get("/admin/dramas/page"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(0))
+                .andExpect(jsonPath("$.data.list[0].likeCount").value("3200"))
+                .andExpect(jsonPath("$.data.list[0].favoriteCount").value("1800"))
+                .andExpect(jsonPath("$.data.list[0].dramaType").value("ANIME"))
+                .andExpect(jsonPath("$.data.list[0].commentCount").value("11"))
+                .andExpect(jsonPath("$.data.list[1].likeCount").value("120"))
+                .andExpect(jsonPath("$.data.list[1].favoriteCount").value("80"))
+                .andExpect(jsonPath("$.data.list[1].commentCount").value("0"));
+
+        verify(commentService).countByDramas(List.of(7L, 8L));
+    }
+
+    @Test
+    void should_fill_comment_count_when_detail_is_requested() throws Exception {
+        given(dramaService.get(7L)).willReturn(drama(7L, 3200L, 1800L));
+        given(commentService.countByDramas(List.of(7L))).willReturn(Map.of(7L, 11L));
+        given(episodeService.sumLikeCountsByDramas(List.of(7L))).willReturn(Map.of(7L, 3200L));
+
+        mockMvc.perform(get("/admin/dramas/7"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.data.likeCount").value("3200"))
+                .andExpect(jsonPath("$.data.favoriteCount").value("1800"))
+                .andExpect(jsonPath("$.data.dramaType").value("ANIME"))
+                .andExpect(jsonPath("$.data.commentCount").value("11"));
+    }
+
+    private DramaRespVO drama(Long id, Long likeCount, Long favoriteCount) {
+        DramaRespVO drama = new DramaRespVO();
+        drama.setId(id);
+        drama.setTitle("短剧" + id);
+        drama.setLikeCount(likeCount);
+        drama.setFavoriteCount(favoriteCount);
+        drama.setDramaType("ANIME");
+        return drama;
+    }
+}

fruitshorts-admin-api/src/test/java/com/fruitshorts/admin/controller/EpisodeControllerContractTest.java

@@ -0,0 +1,70 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.admin.controller;
+
+import com.fruitshorts.admin.support.ControllerContractSupport;
+import com.fruitshorts.content.dal.entity.Drama;
+import com.fruitshorts.content.service.DramaService;
+import com.fruitshorts.content.service.EpisodeService;
+import com.fruitshorts.content.vo.EpisodeRespVO;
+import com.fruitshorts.interaction.service.CommentService;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.test.web.servlet.MockMvc;
+
+import java.util.List;
+import java.util.Map;
+
+import static org.mockito.BDDMockito.given;
+import static org.mockito.Mockito.mock;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+/** K89：后台剧集列表按集回填点赞/评论，并带所属剧收藏/热度。 */
+class EpisodeControllerContractTest {
+
+    private EpisodeService episodeService;
+    private CommentService commentService;
+    private DramaService dramaService;
+    private MockMvc mockMvc;
+
+    @BeforeEach
+    void setUp() {
+        episodeService = mock(EpisodeService.class);
+        commentService = mock(CommentService.class);
+        dramaService = mock(DramaService.class);
+        mockMvc = ControllerContractSupport.mockMvcOf(
+                new EpisodeController(episodeService, commentService, dramaService));
+    }
+
+    @Test
+    void should_return_episode_and_drama_interaction_counts() throws Exception {
+        given(episodeService.listByDrama(5L, null)).willReturn(List.of(
+                episode(11L, 10L),
+                episode(12L, 20L)));
+        given(commentService.countByEpisodes(List.of(11L, 12L)))
+                .willReturn(Map.of(11L, 3L));
+        Drama drama = new Drama();
+        drama.setFavoriteCount(88L);
+        drama.setViewCount(1000L);
+        given(dramaService.getExisting(5L)).willReturn(drama);
+
+        mockMvc.perform(get("/admin/episodes").param("dramaId", "5"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.data[0].likeCount").value("10"))
+                .andExpect(jsonPath("$.data[0].commentCount").value("3"))
+                .andExpect(jsonPath("$.data[0].favoriteCount").value("88"))
+                .andExpect(jsonPath("$.data[0].heat").value("1000"))
+                .andExpect(jsonPath("$.data[1].likeCount").value("20"))
+                .andExpect(jsonPath("$.data[1].commentCount").value("0"));
+    }
+
+    private EpisodeRespVO episode(Long id, Long likeCount) {
+        EpisodeRespVO episode = new EpisodeRespVO();
+        episode.setId(id);
+        episode.setDramaId(5L);
+        episode.setLikeCount(likeCount);
+        return episode;
+    }
+}

fruitshorts-admin-api/src/test/java/com/fruitshorts/admin/service/CommentServiceTest.java

@@ -0,0 +1,123 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.admin.service;
+
+import com.baomidou.mybatisplus.core.MybatisConfiguration;
+import com.baomidou.mybatisplus.core.metadata.TableInfoHelper;
+import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
+import com.fruitshorts.common.pojo.PageResult;
+import com.fruitshorts.content.dal.entity.Drama;
+import com.fruitshorts.content.dal.entity.DramaEpisode;
+import com.fruitshorts.content.service.DramaService;
+import com.fruitshorts.content.service.EpisodeService;
+import com.fruitshorts.interaction.config.InteractionProperties;
+import com.fruitshorts.interaction.dal.entity.ContentComment;
+import com.fruitshorts.interaction.dal.mapper.ContentAuditRecordMapper;
+import com.fruitshorts.interaction.dal.mapper.ContentCommentMapper;
+import com.fruitshorts.interaction.dal.mapper.ContentLikeMapper;
+import com.fruitshorts.interaction.service.AuditRecorder;
+import com.fruitshorts.interaction.service.CommentService;
+import com.fruitshorts.interaction.service.SensitiveWordService;
+import com.fruitshorts.interaction.vo.CommentQueryReqVO;
+import com.fruitshorts.interaction.vo.CommentRespVO;
+import com.fruitshorts.user.dal.entity.AppUser;
+import com.fruitshorts.user.dal.mapper.AppUserMapper;
+import org.apache.ibatis.builder.MapperBuilderAssistant;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.BDDMockito.given;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+
+/** 后台评论页批量补充短剧与分集展示字段。 */
+class CommentServiceTest {
+
+    private ContentCommentMapper commentMapper;
+    private AppUserMapper appUserMapper;
+    private DramaService dramaService;
+    private EpisodeService episodeService;
+    private CommentService commentService;
+
+    @BeforeAll
+    static void initTableInfoCache() {
+        TableInfoHelper.initTableInfo(
+                new MapperBuilderAssistant(new MybatisConfiguration(), ""),
+                ContentComment.class);
+    }
+
+    @BeforeEach
+    void setUp() {
+        commentMapper = mock(ContentCommentMapper.class);
+        appUserMapper = mock(AppUserMapper.class);
+        dramaService = mock(DramaService.class);
+        episodeService = mock(EpisodeService.class);
+        commentService = new CommentService(
+                commentMapper,
+                mock(ContentLikeMapper.class),
+                mock(ContentAuditRecordMapper.class),
+                appUserMapper,
+                dramaService,
+                episodeService,
+                mock(SensitiveWordService.class),
+                mock(AuditRecorder.class),
+                mock(InteractionProperties.class));
+    }
+
+    @Test
+    void should_fill_drama_and_episode_metadata_when_admin_page_is_loaded() {
+        ContentComment withEpisode = comment(1L, 5L, 11L);
+        ContentComment legacy = comment(2L, 5L, 0L);
+        Page<ContentComment> page = new Page<>(1, 10);
+        page.setTotal(2L);
+        page.setRecords(List.of(withEpisode, legacy));
+        given(commentMapper.selectPage(any(), any())).willReturn(page);
+        AppUser user = new AppUser();
+        user.setId(7L);
+        user.setUid("uid-7");
+        user.setNickname("Viewer");
+        given(appUserMapper.selectBatchIds(any())).willReturn(List.of(user));
+        Drama drama = new Drama();
+        drama.setId(5L);
+        drama.setTitle("Signal");
+        given(dramaService.listByIds(any())).willReturn(List.of(drama));
+        DramaEpisode episode = new DramaEpisode();
+        episode.setId(11L);
+        episode.setEpNo(3);
+        episode.setTitle("The Call");
+        given(episodeService.listByIds(any())).willReturn(List.of(episode));
+
+        PageResult<CommentRespVO> result = commentService.adminPage(new CommentQueryReqVO());
+
+        assertThat(result.getList()).hasSize(2);
+        assertThat(result.getList().get(0).getDramaTitle()).isEqualTo("Signal");
+        assertThat(result.getList().get(0).getEpisodeNo()).isEqualTo(3);
+        assertThat(result.getList().get(0).getEpisodeTitle()).isEqualTo("The Call");
+        assertThat(result.getList().get(1).getDramaTitle()).isEqualTo("Signal");
+        assertThat(result.getList().get(1).getEpisodeNo()).isNull();
+        verify(dramaService).listByIds(List.of(5L));
+        verify(episodeService).listByIds(List.of(11L));
+    }
+
+    private ContentComment comment(Long id, Long dramaId, Long episodeId) {
+        ContentComment comment = new ContentComment();
+        comment.setId(id);
+        comment.setDramaId(dramaId);
+        comment.setEpisodeId(episodeId);
+        comment.setParentId(0L);
+        comment.setRootId(0L);
+        comment.setUserId(7L);
+        comment.setContent("comment");
+        comment.setStatus("published");
+        comment.setAuditReason("");
+        comment.setLikeCount(0);
+        comment.setReplyCount(0);
+        comment.setReportCount(0);
+        return comment;
+    }
+}

fruitshorts-admin-api/src/test/java/com/fruitshorts/admin/service/ReportAdminServiceTest.java

@@ -0,0 +1,209 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.admin.service;
+
+import com.baomidou.mybatisplus.core.MybatisConfiguration;
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.baomidou.mybatisplus.core.metadata.TableInfoHelper;
+import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
+import com.fruitshorts.admin.vo.AdminReportRespVO;
+import com.fruitshorts.common.pojo.PageResult;
+import com.fruitshorts.content.dal.entity.Drama;
+import com.fruitshorts.content.dal.entity.DramaEpisode;
+import com.fruitshorts.content.dal.mapper.DramaEpisodeMapper;
+import com.fruitshorts.content.dal.mapper.DramaMapper;
+import com.fruitshorts.interaction.dal.entity.ContentComment;
+import com.fruitshorts.interaction.dal.entity.ContentReport;
+import com.fruitshorts.interaction.dal.mapper.ContentCommentMapper;
+import com.fruitshorts.interaction.dal.mapper.ContentReportMapper;
+import com.fruitshorts.interaction.service.ReportService;
+import com.fruitshorts.interaction.vo.ReportQueryReqVO;
+import com.fruitshorts.user.dal.entity.AppUser;
+import com.fruitshorts.user.dal.mapper.AppUserMapper;
+import org.apache.ibatis.builder.MapperBuilderAssistant;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.mockito.ArgumentCaptor;
+
+import java.time.LocalDateTime;
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.BDDMockito.given;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.times;
+import static org.mockito.Mockito.verify;
+
+/** 后台举报工单目标摘要与批量装配。 */
+class ReportAdminServiceTest {
+
+    private ContentReportMapper reportMapper;
+    private ContentCommentMapper commentMapper;
+    private DramaMapper dramaMapper;
+    private DramaEpisodeMapper episodeMapper;
+    private AppUserMapper appUserMapper;
+    private ReportAdminService service;
+
+    @BeforeAll
+    static void initTableInfoCache() {
+        TableInfoHelper.initTableInfo(
+                new MapperBuilderAssistant(new MybatisConfiguration(), ""),
+                ContentReport.class);
+    }
+
+    @BeforeEach
+    void setUp() {
+        reportMapper = mock(ContentReportMapper.class);
+        commentMapper = mock(ContentCommentMapper.class);
+        dramaMapper = mock(DramaMapper.class);
+        episodeMapper = mock(DramaEpisodeMapper.class);
+        appUserMapper = mock(AppUserMapper.class);
+        service = new ReportAdminService(reportMapper, commentMapper, dramaMapper,
+                episodeMapper, appUserMapper);
+    }
+
+    @Test
+    void should_build_summary_and_batch_relations_for_all_report_types() {
+        List<ContentReport> rows = List.of(
+                report(1L, 7L, ReportService.TYPE_COMMENT, 101L),
+                report(2L, 8L, ReportService.TYPE_DRAMA, 5L),
+                report(3L, 7L, ReportService.TYPE_USER, 9L));
+        stubPage(rows);
+        given(commentMapper.selectByIdsIncludingDeleted(any()))
+                .willReturn(List.of(comment(101L, 5L, 11L, "bad comment", 0)));
+        given(dramaMapper.selectBatchIds(any())).willReturn(List.of(drama(5L, "Signal")));
+        given(episodeMapper.selectBatchIds(any())).willReturn(List.of(episode(11L, 3, "The Call")));
+        given(appUserMapper.selectBatchIds(any())).willReturn(List.of(
+                user(7L, "Alice", "u-7"),
+                user(8L, "Bob", "u-8"),
+                user(9L, "Target", "u-9")));
+
+        PageResult<AdminReportRespVO> result = service.page(new ReportQueryReqVO());
+
+        AdminReportRespVO commentReport = result.getList().get(0);
+        assertThat(commentReport.getTargetSummary())
+                .isEqualTo("Signal · 第 3 集 · The Call");
+        assertThat(commentReport.getDramaTitle()).isEqualTo("Signal");
+        assertThat(commentReport.getEpisodeNo()).isEqualTo(3);
+        assertThat(commentReport.getCommentContent()).isEqualTo("bad comment");
+        assertThat(commentReport.getReporterNickname()).isEqualTo("Alice");
+        assertThat(commentReport.getReporterUid()).isEqualTo("u-7");
+
+        AdminReportRespVO dramaReport = result.getList().get(1);
+        assertThat(dramaReport.getTargetSummary()).isEqualTo("Signal");
+        assertThat(dramaReport.getDramaId()).isEqualTo(5L);
+
+        AdminReportRespVO userReport = result.getList().get(2);
+        assertThat(userReport.getTargetSummary()).isEqualTo("Target（u-9）");
+        assertThat(userReport.getTargetNickname()).isEqualTo("Target");
+        assertThat(userReport.getTargetUid()).isEqualTo("u-9");
+        verify(commentMapper, times(1)).selectByIdsIncludingDeleted(List.of(101L));
+        verify(dramaMapper, times(1)).selectBatchIds(any());
+        verify(episodeMapper, times(1)).selectBatchIds(any());
+        verify(appUserMapper, times(1)).selectBatchIds(any());
+    }
+
+    @Test
+    void should_leave_all_filters_unset_when_status_and_filters_are_empty() {
+        stubPage(List.of());
+
+        PageResult<AdminReportRespVO> result = service.page(new ReportQueryReqVO());
+
+        assertThat(result.getTotal()).isZero();
+        assertThat(result.getList()).isEmpty();
+        ArgumentCaptor<LambdaQueryWrapper<ContentReport>> captor = queryCaptor();
+        verify(reportMapper).selectPage(any(), captor.capture());
+        assertThat(captor.getValue().getSqlSegment())
+                .doesNotContain("status")
+                .doesNotContain("target_type")
+                .doesNotContain("reason_code")
+                .doesNotContain("reporter_id");
+    }
+
+    @Test
+    void should_fallback_to_ids_when_targets_are_deleted_or_missing() {
+        List<ContentReport> rows = List.of(
+                report(1L, 7L, ReportService.TYPE_COMMENT, 101L),
+                report(2L, 7L, ReportService.TYPE_DRAMA, 5L),
+                report(3L, 7L, ReportService.TYPE_USER, 9L));
+        stubPage(rows);
+        given(commentMapper.selectByIdsIncludingDeleted(any()))
+                .willReturn(List.of(comment(101L, 5L, 11L, "removed", 1)));
+        given(dramaMapper.selectBatchIds(any())).willReturn(List.of());
+        given(appUserMapper.selectBatchIds(any()))
+                .willReturn(List.of(user(7L, "Alice", "u-7")));
+
+        PageResult<AdminReportRespVO> result = service.page(new ReportQueryReqVO());
+
+        assertThat(result.getList()).extracting(AdminReportRespVO::getTargetSummary)
+                .containsExactly("评论 #101", "短剧 #5", "用户 #9");
+        assertThat(result.getList().get(0).getCommentContent()).isNull();
+        verify(episodeMapper, never()).selectBatchIds(any());
+    }
+
+    private void stubPage(List<ContentReport> rows) {
+        Page<ContentReport> page = new Page<>(1, 10);
+        page.setTotal(rows.size());
+        page.setRecords(rows);
+        given(reportMapper.selectPage(any(Page.class), any())).willReturn(page);
+    }
+
+    @SuppressWarnings("unchecked")
+    private ArgumentCaptor<LambdaQueryWrapper<ContentReport>> queryCaptor() {
+        return ArgumentCaptor.forClass(LambdaQueryWrapper.class);
+    }
+
+    private ContentReport report(Long id, Long reporterId, String type, Long targetId) {
+        ContentReport report = new ContentReport();
+        report.setId(id);
+        report.setReporterId(reporterId);
+        report.setTargetType(type);
+        report.setTargetId(targetId);
+        report.setReasonCode("VIOLATION");
+        report.setDescription("description");
+        report.setStatus("pending");
+        report.setHandleBy(0L);
+        report.setHandleNote("");
+        report.setCreatedAt(LocalDateTime.of(2026, 10, 21, 12, 0));
+        return report;
+    }
+
+    private ContentComment comment(Long id, Long dramaId, Long episodeId, String content,
+                                   int deleted) {
+        ContentComment comment = new ContentComment();
+        comment.setId(id);
+        comment.setDramaId(dramaId);
+        comment.setEpisodeId(episodeId);
+        comment.setUserId(9L);
+        comment.setContent(content);
+        comment.setStatus(deleted == 1 ? "deleted" : "published");
+        comment.setDeleted(deleted);
+        return comment;
+    }
+
+    private Drama drama(Long id, String title) {
+        Drama drama = new Drama();
+        drama.setId(id);
+        drama.setTitle(title);
+        return drama;
+    }
+
+    private DramaEpisode episode(Long id, int no, String title) {
+        DramaEpisode episode = new DramaEpisode();
+        episode.setId(id);
+        episode.setEpNo(no);
+        episode.setTitle(title);
+        return episode;
+    }
+
+    private AppUser user(Long id, String nickname, String uid) {
+        AppUser user = new AppUser();
+        user.setId(id);
+        user.setNickname(nickname);
+        user.setUid(uid);
+        return user;
+    }
+}

fruitshorts-admin-api/src/test/java/com/fruitshorts/admin/service/WatchHistoryAdminServiceTest.java

@@ -0,0 +1,260 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.admin.service;
+
+import com.baomidou.mybatisplus.core.MybatisConfiguration;
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.baomidou.mybatisplus.core.metadata.TableInfoHelper;
+import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
+import com.fruitshorts.admin.vo.AdminWatchHistoryVO;
+import com.fruitshorts.admin.vo.WatchHistoryQueryReqVO;
+import com.fruitshorts.common.pojo.PageResult;
+import com.fruitshorts.content.dal.entity.Drama;
+import com.fruitshorts.content.dal.entity.DramaEpisode;
+import com.fruitshorts.content.dal.mapper.DramaEpisodeMapper;
+import com.fruitshorts.content.dal.mapper.DramaMapper;
+import com.fruitshorts.playback.dal.entity.WatchHistory;
+import com.fruitshorts.playback.dal.mapper.WatchHistoryMapper;
+import com.fruitshorts.user.dal.entity.AppUser;
+import com.fruitshorts.user.dal.mapper.AppUserMapper;
+import org.apache.ibatis.builder.MapperBuilderAssistant;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.mockito.ArgumentCaptor;
+
+import java.time.LocalDateTime;
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.BDDMockito.given;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+
+/** 后台观看记录分页条件与批量装配。 */
+class WatchHistoryAdminServiceTest {
+
+    private WatchHistoryMapper watchHistoryMapper;
+    private AppUserMapper appUserMapper;
+    private DramaMapper dramaMapper;
+    private DramaEpisodeMapper dramaEpisodeMapper;
+    private WatchHistoryAdminService service;
+
+    @BeforeAll
+    static void initTableInfoCache() {
+        MybatisConfiguration configuration = new MybatisConfiguration();
+        for (Class<?> type : List.of(AppUser.class, Drama.class, DramaEpisode.class,
+                WatchHistory.class)) {
+            TableInfoHelper.initTableInfo(new MapperBuilderAssistant(configuration, ""), type);
+        }
+    }
+
+    @BeforeEach
+    void setUp() {
+        watchHistoryMapper = mock(WatchHistoryMapper.class);
+        appUserMapper = mock(AppUserMapper.class);
+        dramaMapper = mock(DramaMapper.class);
+        dramaEpisodeMapper = mock(DramaEpisodeMapper.class);
+        service = new WatchHistoryAdminService(watchHistoryMapper, appUserMapper, dramaMapper,
+                dramaEpisodeMapper);
+    }
+
+    @Test
+    void should_use_default_page_and_newest_first_when_no_filters_are_given() {
+        WatchHistory row = history(100L, 7L, 5L, 11L);
+        stubPage(row);
+        stubBatchData();
+
+        PageResult<AdminWatchHistoryVO> result = service.page(new WatchHistoryQueryReqVO());
+
+        ArgumentCaptor<Page<WatchHistory>> pageCaptor = pageCaptor();
+        ArgumentCaptor<LambdaQueryWrapper<WatchHistory>> queryCaptor = queryCaptor();
+        verify(watchHistoryMapper).selectPage(pageCaptor.capture(), queryCaptor.capture());
+        assertThat(pageCaptor.getValue().getCurrent()).isEqualTo(1);
+        assertThat(pageCaptor.getValue().getSize()).isEqualTo(10);
+        assertThat(queryCaptor.getValue().getSqlSegment())
+                .contains("watched_at DESC")
+                .contains("id DESC");
+        assertThat(result.getTotal()).isEqualTo(1L);
+        assertThat(result.getList().get(0).getUid()).isEqualTo("user-7");
+        assertThat(result.getList().get(0).getDramaTitle()).isEqualTo("Signal");
+        assertThat(result.getList().get(0).getEpisodeNo()).isEqualTo(1);
+    }
+
+    @Test
+    void should_filter_by_matched_user_ids_when_keyword_is_present() {
+        WatchHistory row = history(100L, 7L, 5L, 11L);
+        given(appUserMapper.selectList(any())).willReturn(List.of(user(7L, "Alice")));
+        stubPage(row);
+        stubBatchData();
+        WatchHistoryQueryReqVO req = new WatchHistoryQueryReqVO();
+        req.setKeyword("Ali");
+
+        service.page(req);
+
+        LambdaQueryWrapper<WatchHistory> query = capturedQuery();
+        assertThat(query.getSqlSegment()).contains("user_id IN");
+        assertThat(query.getParamNameValuePairs().containsValue(7L)).isTrue();
+    }
+
+    @Test
+    void should_filter_by_matched_drama_ids_when_title_is_present() {
+        WatchHistory row = history(100L, 7L, 5L, 11L);
+        given(dramaMapper.selectList(any())).willReturn(List.of(drama(5L, "Signal")));
+        stubPage(row);
+        stubBatchData();
+        WatchHistoryQueryReqVO req = new WatchHistoryQueryReqVO();
+        req.setDramaTitle("Sig");
+
+        service.page(req);
+
+        LambdaQueryWrapper<WatchHistory> query = capturedQuery();
+        assertThat(query.getSqlSegment()).contains("drama_id IN");
+        assertThat(query.getParamNameValuePairs().containsValue(5L)).isTrue();
+    }
+
+    @Test
+    void should_return_empty_page_without_querying_history_when_keyword_has_no_user() {
+        given(appUserMapper.selectList(any())).willReturn(List.of());
+        WatchHistoryQueryReqVO req = new WatchHistoryQueryReqVO();
+        req.setKeyword("missing");
+
+        PageResult<AdminWatchHistoryVO> result = service.page(req);
+
+        assertThat(result.getTotal()).isZero();
+        assertThat(result.getList()).isEmpty();
+        verify(watchHistoryMapper, never()).selectPage(any(), any());
+    }
+
+    @Test
+    void should_apply_true_finished_condition_in_sql() {
+        WatchHistory row = history(100L, 7L, 5L, 11L);
+        row.setPositionMs(59000L);
+        row.setDurationMs(60000L);
+        stubPage(row);
+        stubBatchData();
+        WatchHistoryQueryReqVO req = new WatchHistoryQueryReqVO();
+        req.setFinished(true);
+
+        PageResult<AdminWatchHistoryVO> result = service.page(req);
+
+        LambdaQueryWrapper<WatchHistory> query = capturedQuery();
+        assertThat(query.getSqlSegment())
+                .contains("duration_ms >")
+                .contains("position_ms +");
+        assertThat(query.getParamNameValuePairs().containsValue(1000L)).isTrue();
+        assertThat(result.getList().get(0).getFinished()).isTrue();
+    }
+
+    @Test
+    void should_apply_false_finished_condition_in_sql() {
+        WatchHistory row = history(100L, 7L, 5L, 11L);
+        row.setPositionMs(1000L);
+        row.setDurationMs(60000L);
+        stubPage(row);
+        stubBatchData();
+        WatchHistoryQueryReqVO req = new WatchHistoryQueryReqVO();
+        req.setFinished(false);
+
+        PageResult<AdminWatchHistoryVO> result = service.page(req);
+
+        LambdaQueryWrapper<WatchHistory> query = capturedQuery();
+        assertThat(query.getSqlSegment())
+                .contains("duration_ms =")
+                .contains("OR")
+                .contains("position_ms +");
+        assertThat(result.getList().get(0).getFinished()).isFalse();
+    }
+
+    @Test
+    void should_apply_closed_time_range_and_clamp_page_size() {
+        WatchHistory row = history(100L, 7L, 5L, 11L);
+        stubPage(row);
+        stubBatchData();
+        LocalDateTime start = LocalDateTime.of(2026, 10, 1, 0, 0);
+        LocalDateTime end = LocalDateTime.of(2026, 10, 21, 23, 59, 59);
+        WatchHistoryQueryReqVO req = new WatchHistoryQueryReqVO();
+        req.setPageSize(500);
+        req.setStartTime(start);
+        req.setEndTime(end);
+
+        service.page(req);
+
+        ArgumentCaptor<Page<WatchHistory>> pageCaptor = pageCaptor();
+        ArgumentCaptor<LambdaQueryWrapper<WatchHistory>> queryCaptor = queryCaptor();
+        verify(watchHistoryMapper).selectPage(pageCaptor.capture(), queryCaptor.capture());
+        assertThat(pageCaptor.getValue().getSize()).isEqualTo(100);
+        assertThat(queryCaptor.getValue().getSqlSegment())
+                .contains("watched_at >=")
+                .contains("watched_at <=");
+    }
+
+    private void stubPage(WatchHistory row) {
+        Page<WatchHistory> page = new Page<>(1, 10);
+        page.setTotal(1L);
+        page.setRecords(List.of(row));
+        given(watchHistoryMapper.selectPage(any(Page.class), any())).willReturn(page);
+    }
+
+    private void stubBatchData() {
+        given(appUserMapper.selectBatchIds(any())).willReturn(List.of(user(7L, "Alice")));
+        given(dramaMapper.selectBatchIds(any())).willReturn(List.of(drama(5L, "Signal")));
+        given(dramaEpisodeMapper.selectBatchIds(any())).willReturn(List.of(episode(11L)));
+    }
+
+    @SuppressWarnings("unchecked")
+    private ArgumentCaptor<Page<WatchHistory>> pageCaptor() {
+        return ArgumentCaptor.forClass(Page.class);
+    }
+
+    @SuppressWarnings("unchecked")
+    private ArgumentCaptor<LambdaQueryWrapper<WatchHistory>> queryCaptor() {
+        return ArgumentCaptor.forClass(LambdaQueryWrapper.class);
+    }
+
+    private LambdaQueryWrapper<WatchHistory> capturedQuery() {
+        ArgumentCaptor<LambdaQueryWrapper<WatchHistory>> captor = queryCaptor();
+        verify(watchHistoryMapper).selectPage(any(), captor.capture());
+        return captor.getValue();
+    }
+
+    private WatchHistory history(Long id, Long userId, Long dramaId, Long episodeId) {
+        WatchHistory row = new WatchHistory();
+        row.setId(id);
+        row.setUserId(userId);
+        row.setDramaId(dramaId);
+        row.setEpisodeId(episodeId);
+        row.setPositionMs(1000L);
+        row.setDurationMs(60000L);
+        row.setSource("HOME");
+        row.setDeviceId("device-1");
+        row.setWatchedAt(LocalDateTime.of(2026, 10, 21, 12, 0));
+        return row;
+    }
+
+    private AppUser user(Long id, String nickname) {
+        AppUser user = new AppUser();
+        user.setId(id);
+        user.setUid("user-" + id);
+        user.setNickname(nickname);
+        return user;
+    }
+
+    private Drama drama(Long id, String title) {
+        Drama drama = new Drama();
+        drama.setId(id);
+        drama.setTitle(title);
+        drama.setStatus("published");
+        return drama;
+    }
+
+    private DramaEpisode episode(Long id) {
+        DramaEpisode episode = new DramaEpisode();
+        episode.setId(id);
+        episode.setEpNo(1);
+        episode.setTitle("Episode 1");
+        return episode;
+    }
+}

fruitshorts-app-api/src/main/java/com/fruitshorts/app/controller/AppAuthController.java

@@ -2,7 +2,9 @@
 
 package com.fruitshorts.app.controller;
 
+import com.fruitshorts.app.vo.GoogleLoginReqVO;
 import com.fruitshorts.common.pojo.Result;
+import com.fruitshorts.framework.redis.RateLimit;
 import com.fruitshorts.framework.security.SecurityUtils;
 import com.fruitshorts.framework.web.WebUtils;
 import com.fruitshorts.user.service.AppAuthService;
@@ -35,6 +37,7 @@ public class AppAuthController {
 
     /** 发送验证码。频控在服务端，客户端不需要自己限流。 */
     @Operation(summary = "发送验证码（频控在服务端）")
+    @RateLimit(limit = 20, windowSeconds = 60, key = "otp")
     @PostMapping("/otp")
     public Result<Void> sendOtp(@Valid @RequestBody OtpSendReqVO req, HttpServletRequest request) {
         otpService.send(req, WebUtils.getClientIp(request));
@@ -49,12 +52,19 @@ public class AppAuthController {
     }
 
     @Operation(summary = "登录（验证码或密码）")
+    @RateLimit(limit = 10, windowSeconds = 60, key = "login")
     @PostMapping("/login")
     public Result<TokenRespVO> login(@Valid @RequestBody LoginReqVO req,
                                      HttpServletRequest request) {
         return Result.ok(authService.login(req, WebUtils.getClientIp(request)));
     }
 
+    @Operation(summary = "Google 登录（未配置 clientId 时返回明确错误）")
+    @PostMapping("/google")
+    public Result<TokenRespVO> google(@Valid @RequestBody GoogleLoginReqVO req) {
+        return Result.ok(authService.googleLogin(req.getIdToken()));
+    }
+
     @Operation(summary = "刷新令牌（旧 refresh token 立即失效）")
     @PostMapping("/refresh")
     public Result<TokenRespVO> refresh(@Valid @RequestBody RefreshReqVO req) {

fruitshorts-app-api/src/main/java/com/fruitshorts/app/controller/AppCatalogController.java

@@ -5,12 +5,15 @@ package com.fruitshorts.app.controller;
 import com.fruitshorts.app.service.AppCatalogService;
 import com.fruitshorts.app.vo.AppCategoryVO;
 import com.fruitshorts.app.vo.AppFeedVO;
+import com.fruitshorts.app.vo.AppDramaCardVO;
+import com.fruitshorts.common.pojo.CursorResult;
 import com.fruitshorts.common.pojo.Result;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RestController;
 
 import java.util.List;
@@ -38,6 +41,16 @@ public class AppCatalogController {
         return Result.ok(appCatalogService.discoverFeed());
     }
 
+    @Operation(summary = "推荐流：支持内容类型、分类过滤与游标翻页")
+    @GetMapping("/feed")
+    public Result<CursorResult<AppDramaCardVO>> feed(
+            @RequestParam(required = false) String types,
+            @RequestParam(required = false) Long categoryId,
+            @RequestParam(required = false) Long cursor,
+            @RequestParam(required = false) Integer size) {
+        return Result.ok(appCatalogService.feed(types, categoryId, cursor, size));
+    }
+
     @Operation(summary = "分类列表")
     @GetMapping("/categories")
     public Result<List<AppCategoryVO>> categories() {

fruitshorts-app-api/src/main/java/com/fruitshorts/app/controller/AppCommentController.java

@@ -3,6 +3,8 @@
 package com.fruitshorts.app.controller;
 
 import com.fruitshorts.common.pojo.CursorResult;
+import com.fruitshorts.content.dal.entity.DramaEpisode;
+import com.fruitshorts.content.service.EpisodeService;
 import com.fruitshorts.common.pojo.Result;
 import com.fruitshorts.framework.security.SecurityUtils;
 import com.fruitshorts.framework.web.WebUtils;
@@ -24,6 +26,8 @@ import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RestController;
 
+import java.util.List;
+
 /**
  * 评论。
  *
@@ -38,6 +42,7 @@ import org.springframework.web.bind.annotation.RestController;
 public class AppCommentController {
 
     private final CommentService commentService;
+    private final EpisodeService episodeService;
 
     @Operation(summary = "发布评论")
     @PostMapping
@@ -63,6 +68,21 @@ public class AppCommentController {
         return Result.ok(commentService.page(SecurityUtils.getUserIdOrNull(), query));
     }
 
+    @Operation(summary = "评论总数：传 episodeId 按集统计，仅 dramaId 时全剧统计（可匿名访问）")
+    @GetMapping("/count")
+    public Result<Long> count(@RequestParam Long dramaId,
+                              @RequestParam(required = false) Long episodeId) {
+        if (episodeId != null) {
+            DramaEpisode episode = episodeService.getPublished(episodeId);
+            if (!dramaId.equals(episode.getDramaId())) {
+                return Result.ok(0L);
+            }
+            return Result.ok(commentService.countByEpisodes(List.of(episodeId))
+                    .getOrDefault(episodeId, 0L));
+        }
+        return Result.ok(commentService.countByDrama(dramaId));
+    }
+
     @Operation(summary = "删除自己的评论")
     @DeleteMapping("/{id}")
     public Result<Void> delete(@PathVariable Long id) {

fruitshorts-app-api/src/main/java/com/fruitshorts/app/controller/AppCommerceController.java

@@ -4,8 +4,10 @@ package com.fruitshorts.app.controller;
 
 import com.fruitshorts.commerce.dal.entity.Orders;
 import com.fruitshorts.commerce.service.OrderService;
+import com.fruitshorts.commerce.service.ProductService;
 import com.fruitshorts.commerce.service.UnlockService;
 import com.fruitshorts.commerce.service.WalletService;
+import com.fruitshorts.commerce.vo.ProductRespVO;
 import com.fruitshorts.common.pojo.Result;
 import com.fruitshorts.framework.security.SecurityUtils;
 import io.swagger.v3.oas.annotations.Operation;
@@ -16,6 +18,7 @@ import org.springframework.web.bind.annotation.PathVariable;
 import org.springframework.web.bind.annotation.PostMapping;
 import org.springframework.web.bind.annotation.RequestBody;
 import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RestController;
 
 import java.util.LinkedHashMap;
@@ -37,6 +40,7 @@ public class AppCommerceController {
     private final WalletService walletService;
     private final UnlockService unlockService;
     private final OrderService orderService;
+    private final ProductService productService;
 
     /** 我的钱包：余额 + 最近流水，客户端一处渲染。 */
     @Operation(summary = "我的钱包（余额 + 最近流水）")
@@ -49,6 +53,22 @@ public class AppCommerceController {
         return Result.ok(data);
     }
 
+    /** 充值商品列表：只返回上架商品，type 可选（COIN_PACK/VIP）。 */
+    @Operation(summary = "充值商品列表（只返回上架商品，type 可选 COIN_PACK/VIP）")
+    @GetMapping("/products")
+    public Result<List<ProductRespVO>> products(@RequestParam(required = false) String type) {
+        return Result.ok(productService.listForApp(type));
+    }
+
+    /** 创建充值订单：body 传 productId，返回 CREATED 状态的订单，等待后续支付。 */
+    @Operation(summary = "创建充值订单（body 传 productId）")
+    @PostMapping("/orders")
+    public Result<Orders> createOrder(@RequestBody Map<String, Object> body) {
+        Object productId = body.get("productId");
+        Long pid = productId == null ? null : Long.valueOf(productId.toString());
+        return Result.ok(orderService.createOrder(SecurityUtils.getAppUserId(), pid));
+    }
+
     /** 金币解锁分集：幂等，重复点击不会重复扣币。 */
     @Operation(summary = "金币解锁分集（幂等，重复点击不重复扣币）")
     @PostMapping("/episodes/{episodeId}/unlock")

fruitshorts-app-api/src/main/java/com/fruitshorts/app/controller/AppDramaController.java

@@ -5,14 +5,20 @@ package com.fruitshorts.app.controller;
 import com.fruitshorts.app.service.AppCatalogService;
 import com.fruitshorts.app.vo.AppDramaDetailVO;
 import com.fruitshorts.common.pojo.Result;
+import com.fruitshorts.content.dal.entity.DramaEpisode;
+import com.fruitshorts.content.service.EpisodeService;
 import com.fruitshorts.framework.security.SecurityUtils;
 import com.fruitshorts.framework.web.WebUtils;
+import com.fruitshorts.interaction.service.CommentService;
 import com.fruitshorts.playback.service.PlaybackService;
 import com.fruitshorts.playback.vo.PlayRespVO;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.servlet.http.HttpServletRequest;
 import lombok.RequiredArgsConstructor;
+
+import java.util.List;
+
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.PathVariable;
 import org.springframework.web.bind.annotation.RequestMapping;
@@ -26,6 +32,8 @@ public class AppDramaController {
 
     private final AppCatalogService appCatalogService;
     private final PlaybackService playbackService;
+    private final EpisodeService episodeService;
+    private final CommentService commentService;
 
     /** 详情：包含剧集列表，客户端进详情页一次请求即可渲染 */
     @Operation(summary = "短剧详情（含剧集列表，进详情页一次请求即可渲染）")
@@ -41,10 +49,14 @@ public class AppDramaController {
     @Operation(summary = "播放票据：判定权益后签发短时效播放地址")
     @GetMapping("/episodes/{id}/play")
     public Result<PlayRespVO> play(@PathVariable Long id, HttpServletRequest request) {
-        return Result.ok(playbackService.play(
+        PlayRespVO vo = playbackService.play(
                 SecurityUtils.getUserIdOrNull(),
                 id,
                 request.getHeader("X-Device-Id"),
-                WebUtils.getClientIp(request)));
+                WebUtils.getClientIp(request));
+        DramaEpisode episode = episodeService.getExisting(id);
+        vo.setLikeCount(episode.getLikeCount() == null ? 0L : episode.getLikeCount());
+        vo.setCommentCount(commentService.countByEpisodes(List.of(id)).getOrDefault(id, 0L));
+        return Result.ok(vo);
     }
 }

fruitshorts-app-api/src/main/java/com/fruitshorts/app/controller/AppEventController.java

@@ -0,0 +1,35 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.app.controller;
+
+import com.fruitshorts.app.service.AppEventService;
+import com.fruitshorts.app.vo.AppEventReqVO;
+import com.fruitshorts.common.pojo.Result;
+import com.fruitshorts.framework.security.SecurityUtils;
+import com.fruitshorts.framework.web.WebUtils;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.servlet.http.HttpServletRequest;
+import jakarta.validation.Valid;
+import lombok.RequiredArgsConstructor;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+/** 客户端埋点上报。 */
+@Tag(name = "埋点")
+@RestController
+@RequestMapping("/app")
+@RequiredArgsConstructor
+public class AppEventController {
+
+    private final AppEventService eventService;
+
+    @Operation(summary = "埋点事件批量上报")
+    @PostMapping("/events")
+    public Result<Void> report(@Valid @RequestBody AppEventReqVO req, HttpServletRequest request) {
+        eventService.save(req, SecurityUtils.getUserIdOrNull(), WebUtils.getClientIp(request));
+        return Result.ok();
+    }
+}

fruitshorts-app-api/src/main/java/com/fruitshorts/app/controller/AppSearchController.java

@@ -0,0 +1,33 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.app.controller;
+
+import com.fruitshorts.app.service.AppSearchService;
+import com.fruitshorts.app.vo.AppDramaCardVO;
+import com.fruitshorts.common.pojo.PageResult;
+import com.fruitshorts.common.pojo.Result;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import lombok.RequiredArgsConstructor;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+/** 客户端搜索：按标题或简介模糊匹配已上线短剧。 */
+@Tag(name = "客户端-搜索")
+@RestController
+@RequestMapping("/app")
+@RequiredArgsConstructor
+public class AppSearchController {
+
+    private final AppSearchService appSearchService;
+
+    @Operation(summary = "搜索短剧（按标题/简介模糊匹配，只返回已上线）")
+    @GetMapping("/search")
+    public Result<PageResult<AppDramaCardVO>> search(@RequestParam String keyword,
+                                                     @RequestParam(defaultValue = "1") int pageIndex,
+                                                     @RequestParam(defaultValue = "20") int pageSize) {
+        return Result.ok(appSearchService.search(keyword, pageIndex, pageSize));
+    }
+}

fruitshorts-app-api/src/main/java/com/fruitshorts/app/dal/entity/AppEventLog.java

@@ -0,0 +1,33 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.app.dal.entity;
+
+import com.baomidou.mybatisplus.annotation.FieldStrategy;
+import com.baomidou.mybatisplus.annotation.IdType;
+import com.baomidou.mybatisplus.annotation.TableField;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableName;
+import lombok.Data;
+
+import java.time.LocalDateTime;
+
+/** 埋点事件落库记录，为后续分析/漏斗预留原始数据。 */
+@Data
+@TableName("app_event_log")
+public class AppEventLog {
+
+    @TableId(type = IdType.ASSIGN_ID)
+    private Long id;
+    private String eventName;
+    private LocalDateTime eventTime;
+    private Long userId;
+    private String deviceId;
+    private String sessionId;
+    private String page;
+    private String properties;
+    private String clientIp;
+    private LocalDateTime createdAt;
+
+    @TableField(updateStrategy = FieldStrategy.NEVER)
+    private LocalDateTime updatedAt;
+}

fruitshorts-app-api/src/main/java/com/fruitshorts/app/dal/mapper/AppEventLogMapper.java

@@ -0,0 +1,10 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.app.dal.mapper;
+
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+import com.fruitshorts.app.dal.entity.AppEventLog;
+
+/** 埋点事件 Mapper。 */
+public interface AppEventLogMapper extends BaseMapper<AppEventLog> {
+}

fruitshorts-app-api/src/main/java/com/fruitshorts/app/service/AppCatalogService.java

@@ -9,6 +9,7 @@ import com.fruitshorts.app.vo.AppDramaDetailVO;
 import com.fruitshorts.app.vo.AppEpisodeVO;
 import com.fruitshorts.app.vo.AppFeedVO;
 import com.fruitshorts.app.vo.AppSectionVO;
+import com.fruitshorts.common.pojo.CursorResult;
 import com.fruitshorts.content.dal.entity.ContentBanner;
 import com.fruitshorts.content.dal.entity.Drama;
 import com.fruitshorts.content.dal.entity.DramaEpisode;
@@ -17,6 +18,7 @@ import com.fruitshorts.content.service.BannerService;
 import com.fruitshorts.content.service.DramaCategoryService;
 import com.fruitshorts.content.service.DramaService;
 import com.fruitshorts.content.service.EpisodeService;
+import com.fruitshorts.interaction.service.CommentService;
 import com.fruitshorts.media.service.PlaybackSigner;
 import com.fruitshorts.content.vo.DramaCategoryRespVO;
 import lombok.RequiredArgsConstructor;
@@ -26,6 +28,7 @@ import java.util.ArrayList;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.Arrays;
 
 /**
  * C 端目录聚合：把内容域的只读视图组装成客户端一次请求就能渲染的结构。
@@ -38,12 +41,15 @@ public class AppCatalogService {
     private static final int HOME_SECTION_SIZE = 6;
     private static final int DISCOVER_SECTION_SIZE = 10;
     private static final int MAX_CATEGORY_SECTIONS = 4;
+    private static final int DEFAULT_FEED_SIZE = 20;
+    private static final int MAX_FEED_SIZE = 50;
 
     private final DramaService dramaService;
     private final EpisodeService episodeService;
     private final BannerService bannerService;
     private final DramaCategoryService dramaCategoryService;
     private final PlaybackSigner playbackSigner;
+    private final CommentService commentService;
 
     public AppFeedVO homeFeed() {
         Map<Long, String> categoryNames = categoryNameMap();
@@ -68,6 +74,26 @@ public class AppCatalogService {
                 .toList();
     }
 
+    public CursorResult<AppDramaCardVO> feed(
+            String types, Long categoryId, Long cursor, Integer size) {
+        int pageSize = size == null ? DEFAULT_FEED_SIZE : Math.max(1, Math.min(size, MAX_FEED_SIZE));
+        List<String> dramaTypes = types == null
+                ? List.of()
+                : Arrays.stream(types.split(","))
+                        .map(String::trim)
+                        .filter(type -> !type.isEmpty())
+                        .toList();
+        List<Drama> rows = dramaService.listPublishedFeed(
+                dramaTypes, categoryId, cursor, pageSize + 1);
+        if (rows.isEmpty()) {
+            return CursorResult.empty();
+        }
+        boolean hasMore = rows.size() > pageSize;
+        List<Drama> pageRows = hasMore ? rows.subList(0, pageSize) : rows;
+        Long nextCursor = hasMore ? pageRows.get(pageRows.size() - 1).getId() : null;
+        return new CursorResult<>(cards(pageRows, categoryNameMap()), nextCursor, hasMore);
+    }
+
     /**
      * 供收藏、观看记录等列表复用卡片结构：字段与首页卡片完全一致，
      * 客户端可以用同一套渲染逻辑，不用为每个列表各写一份。
@@ -82,6 +108,8 @@ public class AppCatalogService {
     public AppDramaDetailVO dramaDetail(Long dramaId) {
         Drama drama = dramaService.getPublished(dramaId);
         List<DramaEpisode> episodes = episodeService.listPublishedByDrama(dramaId);
+        Map<Long, Long> episodeCommentCounts = commentService.countByEpisodes(
+                episodes.stream().map(DramaEpisode::getId).sorted().toList());
         String categoryName = categoryNameMap().getOrDefault(drama.getCategoryId(), "");
 
         AppDramaDetailVO detail = new AppDramaDetailVO();
@@ -96,7 +124,12 @@ public class AppCatalogService {
         detail.setUnlockCoin(drama.getUnlockCoin());
         detail.setIsHot(drama.getIsHot() != null && drama.getIsHot() == 1);
         detail.setViewCount(drama.getViewCount());
-        detail.setEpisodes(episodes.stream().map(this::toEpisode).toList());
+        detail.setLikeCount(drama.getLikeCount());
+        detail.setFavoriteCount(drama.getFavoriteCount());
+        detail.setCommentCount(commentService.countByDrama(dramaId));
+        detail.setEpisodes(episodes.stream()
+                .map(episode -> toEpisode(episode, episodeCommentCounts))
+                .toList());
         return detail;
     }
 
@@ -139,15 +172,18 @@ public class AppCatalogService {
 
     /** 整屏卡片共用一次剧集查询，取每部剧的首个可播免费集作为预览。 */
     private List<AppDramaCardVO> cards(List<Drama> dramas, Map<Long, String> categoryNames) {
-        Map<Long, DramaEpisode> previews = episodeService.firstPlayableByDramas(
-                dramas.stream().map(Drama::getId).toList());
+        List<Long> ids = dramas.stream().map(Drama::getId).toList();
+        Map<Long, DramaEpisode> previews = episodeService.firstPlayableByDramas(ids);
+        Map<Long, Long> commentCounts = commentService.countByEpisodes(
+                previews.values().stream().map(DramaEpisode::getId).sorted().toList());
         return dramas.stream()
-                .map(drama -> toCard(drama, categoryNames, previews.get(drama.getId())))
+                .map(drama -> toCard(
+                        drama, categoryNames, previews.get(drama.getId()), commentCounts))
                 .toList();
     }
 
     private AppDramaCardVO toCard(Drama drama, Map<Long, String> categoryNames,
-                                  DramaEpisode preview) {
+                                  DramaEpisode preview, Map<Long, Long> commentCounts) {
         AppDramaCardVO card = new AppDramaCardVO();
         card.setId(drama.getId());
         card.setTitle(drama.getTitle());
@@ -158,11 +194,18 @@ public class AppCatalogService {
         card.setTotalEpisodes(drama.getTotalEpisodes());
         card.setIsHot(drama.getIsHot() != null && drama.getIsHot() == 1);
         card.setViewCount(drama.getViewCount());
-        card.setPreview(preview == null ? null : toEpisode(preview));
+        card.setLikeCount(preview == null || preview.getLikeCount() == null
+                ? 0L : preview.getLikeCount());
+        card.setFavoriteCount(drama.getFavoriteCount());
+        card.setCommentCount(preview == null
+                ? 0L : commentCounts.getOrDefault(preview.getId(), 0L));
+        card.setLanguage(drama.getLanguage());
+        card.setDramaType(drama.getDramaType());
+        card.setPreview(preview == null ? null : toEpisode(preview, commentCounts));
         return card;
     }
 
-    private AppEpisodeVO toEpisode(DramaEpisode episode) {
+    private AppEpisodeVO toEpisode(DramaEpisode episode, Map<Long, Long> commentCounts) {
         AppEpisodeVO vo = new AppEpisodeVO();
         vo.setId(episode.getId());
         vo.setNumber(episode.getEpNo());
@@ -174,6 +217,8 @@ public class AppCatalogService {
         vo.setIsFree(free);
         vo.setLocked(!free);
         vo.setUnlockCoin(episode.getUnlockCoin());
+        vo.setLikeCount(episode.getLikeCount() == null ? 0L : episode.getLikeCount());
+        vo.setCommentCount(commentCounts.getOrDefault(episode.getId(), 0L));
         if (free) {
             // 播放地址统一在这里签名：客户端拿不到可长期复用的裸地址
             vo.setPlayUrl(playbackSigner.sign(playableSource(episode)));

fruitshorts-app-api/src/main/java/com/fruitshorts/app/service/AppEventService.java

@@ -0,0 +1,40 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.app.service;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fruitshorts.app.dal.entity.AppEventLog;
+import com.fruitshorts.app.dal.mapper.AppEventLogMapper;
+import com.fruitshorts.app.vo.AppEventReqVO;
+import lombok.RequiredArgsConstructor;
+import lombok.SneakyThrows;
+import org.springframework.stereotype.Service;
+
+import java.time.LocalDateTime;
+
+/** 埋点事件接收：批量落库，事件名与属性暂不校验、透传，口径后续与运营对齐。 */
+@Service
+@RequiredArgsConstructor
+public class AppEventService {
+
+    private final AppEventLogMapper eventLogMapper;
+    private final ObjectMapper objectMapper;
+
+    @SneakyThrows
+    public void save(AppEventReqVO req, Long userId, String clientIp) {
+        for (AppEventReqVO.EventItem item : req.getEvents()) {
+            AppEventLog log = new AppEventLog();
+            log.setEventName(item.getEventName());
+            log.setEventTime(item.getEventTime() == null ? LocalDateTime.now() : item.getEventTime());
+            log.setUserId(userId);
+            log.setDeviceId(req.getDeviceId());
+            log.setSessionId(req.getSessionId());
+            log.setPage(item.getPage());
+            log.setProperties(item.getProperties() == null ? null
+                    : objectMapper.writeValueAsString(item.getProperties()));
+            log.setClientIp(clientIp);
+            log.setCreatedAt(LocalDateTime.now());
+            eventLogMapper.insert(log);
+        }
+    }
+}

fruitshorts-app-api/src/main/java/com/fruitshorts/app/service/AppSearchService.java

@@ -0,0 +1,44 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.app.service;
+
+import com.baomidou.mybatisplus.core.toolkit.Wrappers;
+import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
+import com.fruitshorts.app.vo.AppDramaCardVO;
+import com.fruitshorts.common.pojo.PageResult;
+import com.fruitshorts.content.dal.entity.Drama;
+import com.fruitshorts.content.dal.mapper.DramaMapper;
+import com.fruitshorts.content.enums.ContentStatus;
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Service;
+import org.springframework.util.StringUtils;
+
+/**
+ * 客户端搜索：只搜已上线短剧，命中标题或简介。
+ * 结果复用 {@link AppCatalogService#toCards} 的卡片转换，保证与首页卡片字段一致。
+ */
+@Service
+@RequiredArgsConstructor
+public class AppSearchService {
+
+    private static final int MAX_PAGE_SIZE = 50;
+
+    private final DramaMapper dramaMapper;
+    private final AppCatalogService appCatalogService;
+
+    public PageResult<AppDramaCardVO> search(String keyword, int pageIndex, int pageSize) {
+        if (!StringUtils.hasText(keyword)) {
+            return PageResult.empty();
+        }
+        int safeIndex = Math.max(pageIndex, 1);
+        int safeSize = Math.min(Math.max(pageSize, 1), MAX_PAGE_SIZE);
+        Page<Drama> page = new Page<>(safeIndex, safeSize);
+        Page<Drama> result = dramaMapper.selectPage(page, Wrappers.<Drama>lambdaQuery()
+                .eq(Drama::getStatus, ContentStatus.PUBLISHED.getCode())
+                .and(w -> w.like(Drama::getTitle, keyword.trim())
+                        .or().like(Drama::getSynopsis, keyword.trim()))
+                .orderByDesc(Drama::getSort)
+                .orderByDesc(Drama::getId));
+        return new PageResult<>(result.getTotal(), appCatalogService.toCards(result.getRecords()));
+    }
+}

fruitshorts-app-api/src/main/java/com/fruitshorts/app/vo/AppDramaCardVO.java

@@ -2,6 +2,7 @@
 
 package com.fruitshorts.app.vo;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Data;
 
 /** 列表卡片，用于首页/发现页/分类分区 */
@@ -17,6 +18,17 @@ public class AppDramaCardVO {
     private Integer totalEpisodes;
     private Boolean isHot;
     private Long viewCount;
+    /** 短剧累计点赞数：drama.like_count */
+    private Long likeCount;
+    /** 短剧累计收藏数：drama.favorite_count */
+    private Long favoriteCount;
+    /** 该剧未删除评论数：content_comment 按 drama_id 统计 */
+    private Long commentCount;
+    /** 语种，供客户端按语言筛选（如 zh-CN / id）。 */
+    @Schema(description = "短剧语种，如 zh-CN / id")
+    private String language;
+    /** 内容类型：ANIME=漫剧，LIVE=真人剧 */
+    private String dramaType;
     /**
      * 首个可播免费集。首页竖屏播放需要在列表阶段就能起播，
      * 带上这一集可以省掉「点开→请求详情→再请求播放地址」的往返。

fruitshorts-app-api/src/main/java/com/fruitshorts/app/vo/AppDramaDetailVO.java

@@ -20,5 +20,11 @@ public class AppDramaDetailVO {
     private Integer unlockCoin;
     private Boolean isHot;
     private Long viewCount;
+    /** 短剧累计点赞数：drama.like_count */
+    private Long likeCount;
+    /** 短剧累计收藏数：drama.favorite_count */
+    private Long favoriteCount;
+    /** 该剧未删除评论数：content_comment 按 drama_id 统计 */
+    private Long commentCount;
     private List<AppEpisodeVO> episodes;
 }

fruitshorts-app-api/src/main/java/com/fruitshorts/app/vo/AppEpisodeVO.java

@@ -17,6 +17,8 @@ public class AppEpisodeVO {
     /** true 表示需要解锁后才能播放 */
     private Boolean locked;
     private Integer unlockCoin;
+    private Long likeCount;
+    private Long commentCount;
     /**
      * 可播放时的地址；锁定或不含片源时为空。
      * 详情页拿到就能直接播，不必按集再请求一次播放票据。

fruitshorts-app-api/src/main/java/com/fruitshorts/app/vo/AppEventReqVO.java

@@ -0,0 +1,48 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.app.vo;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import jakarta.validation.Valid;
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.NotEmpty;
+import jakarta.validation.constraints.Size;
+import lombok.Data;
+
+import java.time.LocalDateTime;
+import java.util.List;
+import java.util.Map;
+
+/** 埋点事件批量上报请求。 */
+@Data
+public class AppEventReqVO {
+
+    @Schema(description = "设备ID")
+    private String deviceId;
+
+    @Schema(description = "会话ID")
+    private String sessionId;
+
+    @Schema(description = "事件列表")
+    @NotEmpty(message = "事件列表不能为空")
+    @Size(max = 50, message = "单次最多上报 50 条事件")
+    @Valid
+    private List<EventItem> events;
+
+    @Data
+    public static class EventItem {
+
+        @Schema(description = "事件名，如 playback_start/playback_end/pay_success")
+        @NotBlank(message = "事件名不能为空")
+        private String eventName;
+
+        @Schema(description = "事件发生时间，缺省用服务端接收时间")
+        private LocalDateTime eventTime;
+
+        @Schema(description = "页面/场景标识")
+        private String page;
+
+        @Schema(description = "事件属性（key-value）")
+        private Map<String, Object> properties;
+    }
+}

fruitshorts-app-api/src/main/java/com/fruitshorts/app/vo/GoogleLoginReqVO.java

@@ -0,0 +1,14 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.app.vo;
+
+import jakarta.validation.constraints.NotBlank;
+import lombok.Data;
+
+/** Google 登录请求。 */
+@Data
+public class GoogleLoginReqVO {
+
+    @NotBlank(message = "缺少 Google idToken")
+    private String idToken;
+}

fruitshorts-app-api/src/main/resources/application.yml

@@ -18,6 +18,10 @@ spring:
   jackson:
     date-format: yyyy-MM-dd HH:mm:ss
     time-zone: Asia/Shanghai
+  data:
+    redis:
+      host: ${REDIS_HOST:127.0.0.1}
+      port: ${REDIS_PORT:6379}
 
 mybatis-plus:
   configuration:
@@ -43,6 +47,10 @@ springdoc:
     path: /v3/api-docs
 
 fruitshorts:
+  auth:
+    # 仅作 sys_config 缺失/非法时的兜底；运行时优先读取后台「系统配置」
+    register-max-per-ip-per-day: ${REGISTER_MAX_PER_IP_PER_DAY:5}
+    register-max-per-device-per-day: ${REGISTER_MAX_PER_DEVICE_PER_DAY:3}
   interaction:
     # MACHINE_FIRST：机审通过即发布，命中 REVIEW 级敏感词才转人工
     # PRE_REVIEW   ：全部先审后发（生产建议）
@@ -89,3 +97,15 @@ fruitshorts:
 logging:
   level:
     com.fruitshorts: info
+
+management:
+  endpoints:
+    web:
+      exposure:
+        include: prometheus,health
+  endpoint:
+    health:
+      show-details: always
+  metrics:
+    tags:
+      application: ${spring.application.name}

fruitshorts-app-api/src/test/java/com/fruitshorts/app/controller/AppCatalogControllerContractTest.java

@@ -5,11 +5,16 @@ import com.fruitshorts.app.service.AppCatalogService;
 import com.fruitshorts.app.support.ControllerContractSupport;
 import com.fruitshorts.app.vo.AppBannerVO;
 import com.fruitshorts.app.vo.AppCategoryVO;
+import com.fruitshorts.app.vo.AppDramaCardVO;
 import com.fruitshorts.app.vo.AppDramaDetailVO;
 import com.fruitshorts.app.vo.AppFeedVO;
+import com.fruitshorts.app.vo.AppSectionVO;
+import com.fruitshorts.common.pojo.CursorResult;
+import com.fruitshorts.content.service.EpisodeService;
 import com.fruitshorts.common.exception.ErrorCode;
 import com.fruitshorts.common.exception.ServiceException;
 import com.fruitshorts.playback.service.PlaybackService;
+import com.fruitshorts.interaction.service.CommentService;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 import org.springframework.test.web.servlet.MockMvc;
@@ -40,7 +45,8 @@ class AppCatalogControllerContractTest {
         catalogService = mock(AppCatalogService.class);
         catalogMvc = ControllerContractSupport.mockMvcOf(new AppCatalogController(catalogService));
         dramaMvc = ControllerContractSupport.mockMvcOf(
-                new AppDramaController(catalogService, mock(PlaybackService.class)));
+                new AppDramaController(catalogService, mock(PlaybackService.class),
+                        mock(EpisodeService.class), mock(CommentService.class)));
     }
 
     @Test
@@ -50,7 +56,15 @@ class AppCatalogControllerContractTest {
         banner.setImageUrl("/files/banner/9.png");
         banner.setLinkType("DRAMA");
         banner.setLinkValue("12");
-        AppFeedVO feed = new AppFeedVO(List.of(banner), List.of());
+        AppDramaCardVO card = new AppDramaCardVO();
+        card.setId(12L);
+        card.setTitle("命运的相遇");
+        card.setViewCount(12400L);
+        card.setLikeCount(3200L);
+        card.setFavoriteCount(1800L);
+        card.setCommentCount(96L);
+        AppSectionVO section = new AppSectionVO("hot", "热门推荐", List.of(card));
+        AppFeedVO feed = new AppFeedVO(List.of(banner), List.of(section));
         given(catalogService.homeFeed()).willReturn(feed);
 
         catalogMvc.perform(get("/app/home/feed"))
@@ -58,7 +72,11 @@ class AppCatalogControllerContractTest {
                 .andExpect(jsonPath("$.code").value(0))
                 .andExpect(jsonPath("$.data.banners[0].id").value(9))
                 .andExpect(jsonPath("$.data.banners[0].imageUrl").value("/files/banner/9.png"))
-                .andExpect(jsonPath("$.data.banners[0].linkType").value("DRAMA"));
+                .andExpect(jsonPath("$.data.banners[0].linkType").value("DRAMA"))
+                .andExpect(jsonPath("$.data.sections[0].dramas[0].viewCount").value("12400"))
+                .andExpect(jsonPath("$.data.sections[0].dramas[0].likeCount").value("3200"))
+                .andExpect(jsonPath("$.data.sections[0].dramas[0].favoriteCount").value("1800"))
+                .andExpect(jsonPath("$.data.sections[0].dramas[0].commentCount").value("96"));
     }
 
     @Test
@@ -72,6 +90,29 @@ class AppCatalogControllerContractTest {
                 .andExpect(jsonPath("$.data.sections").isArray());
     }
 
+    @Test
+    void should_return_typed_cursor_feed() throws Exception {
+        AppDramaCardVO card = new AppDramaCardVO();
+        card.setId(12L);
+        card.setTitle("漫剧卡片");
+        card.setDramaType("ANIME");
+        given(catalogService.feed("ANIME", 7L, null, 20))
+                .willReturn(new CursorResult<>(List.of(card), 12L, true));
+
+        catalogMvc.perform(get("/app/feed")
+                        .param("types", "ANIME")
+                        .param("categoryId", "7")
+                        .param("size", "20"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(0))
+                .andExpect(jsonPath("$.data.list[0].id").value("12"))
+                .andExpect(jsonPath("$.data.list[0].dramaType").value("ANIME"))
+                .andExpect(jsonPath("$.data.nextCursor").value("12"))
+                .andExpect(jsonPath("$.data.hasMore").value(true));
+
+        verify(catalogService).feed("ANIME", 7L, null, 20);
+    }
+
     @Test
     void should_return_category_list_when_categories_are_requested() throws Exception {
         AppCategoryVO category = new AppCategoryVO(3L, "都市");
@@ -89,6 +130,10 @@ class AppCatalogControllerContractTest {
         AppDramaDetailVO detail = new AppDramaDetailVO();
         detail.setId(42L);
         detail.setTitle("命运的相遇");
+        detail.setViewCount(12400L);
+        detail.setLikeCount(3200L);
+        detail.setFavoriteCount(1800L);
+        detail.setCommentCount(96L);
         detail.setEpisodes(List.of());
         given(catalogService.dramaDetail(42L)).willReturn(detail);
 
@@ -97,7 +142,11 @@ class AppCatalogControllerContractTest {
                 .andExpect(jsonPath("$.code").value(0))
                 .andExpect(jsonPath("$.data.id").value("42"))
                 .andExpect(jsonPath("$.data.id").isString())
-                .andExpect(jsonPath("$.data.title").value("命运的相遇"));
+                .andExpect(jsonPath("$.data.title").value("命运的相遇"))
+                .andExpect(jsonPath("$.data.viewCount").value("12400"))
+                .andExpect(jsonPath("$.data.likeCount").value("3200"))
+                .andExpect(jsonPath("$.data.favoriteCount").value("1800"))
+                .andExpect(jsonPath("$.data.commentCount").value("96"));
 
         verify(catalogService).dramaDetail(42L);
     }

fruitshorts-app-api/src/test/java/com/fruitshorts/app/controller/AppCommentControllerContractTest.java

@@ -0,0 +1,67 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.app.controller;
+
+import com.fruitshorts.app.support.ControllerContractSupport;
+import com.fruitshorts.content.dal.entity.DramaEpisode;
+import com.fruitshorts.content.service.EpisodeService;
+import com.fruitshorts.interaction.service.CommentService;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.test.web.servlet.MockMvc;
+
+import java.util.List;
+import java.util.Map;
+
+import static org.mockito.BDDMockito.given;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+/** 评论总数接口契约。 */
+class AppCommentControllerContractTest {
+
+    private CommentService commentService;
+    private EpisodeService episodeService;
+    private MockMvc mockMvc;
+
+    @BeforeEach
+    void setUp() {
+        commentService = mock(CommentService.class);
+        episodeService = mock(EpisodeService.class);
+        mockMvc = ControllerContractSupport.mockMvcOf(
+                new AppCommentController(commentService, episodeService));
+    }
+
+    @Test
+    void should_return_comment_count_as_string_when_requested() throws Exception {
+        given(commentService.countByDrama(7L)).willReturn(9L);
+
+        mockMvc.perform(get("/app/comments/count").param("dramaId", "7"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(0))
+                .andExpect(jsonPath("$.data").value("9"))
+                .andExpect(jsonPath("$.data").isString());
+
+        verify(commentService).countByDrama(7L);
+    }
+
+    @Test
+    void should_count_comments_by_episode_when_episode_id_is_given() throws Exception {
+        DramaEpisode episode = new DramaEpisode();
+        episode.setId(11L);
+        episode.setDramaId(7L);
+        given(episodeService.getPublished(11L)).willReturn(episode);
+        given(commentService.countByEpisodes(List.of(11L))).willReturn(Map.of(11L, 4L));
+
+        mockMvc.perform(get("/app/comments/count")
+                        .param("dramaId", "7")
+                        .param("episodeId", "11"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.data").value("4"));
+
+        verify(commentService).countByEpisodes(List.of(11L));
+    }
+}

fruitshorts-app-api/src/test/java/com/fruitshorts/app/controller/AppCommentCountAnonymousSecurityTest.java

@@ -0,0 +1,135 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.app.controller;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fruitshorts.app.service.AppCatalogService;
+import com.fruitshorts.common.pojo.CursorResult;
+import com.fruitshorts.content.service.EpisodeService;
+import com.fruitshorts.framework.log.AccessDeniedRecorder;
+import com.fruitshorts.framework.security.JwtAuthenticationFilter;
+import com.fruitshorts.framework.security.JwtTokenProvider;
+import com.fruitshorts.framework.security.RestAuthEntryPoint;
+import com.fruitshorts.framework.security.SecurityConfig;
+import com.fruitshorts.interaction.service.CommentService;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.Mockito;
+import org.springframework.beans.factory.ObjectProvider;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.context.annotation.Import;
+import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
+import org.springframework.security.web.FilterChainProxy;
+import org.springframework.test.context.ContextConfiguration;
+import org.springframework.test.context.junit.jupiter.SpringExtension;
+import org.springframework.test.context.web.WebAppConfiguration;
+import org.springframework.test.web.servlet.MockMvc;
+import org.springframework.test.web.servlet.setup.MockMvcBuilders;
+import org.springframework.web.context.WebApplicationContext;
+import org.springframework.web.servlet.config.annotation.EnableWebMvc;
+
+import java.util.List;
+
+import static org.mockito.BDDMockito.given;
+import static org.mockito.Mockito.mock;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+/** 客户端公开只读接口的安全链契约：匿名请求必须直接进入控制器。 */
+@ExtendWith(SpringExtension.class)
+@WebAppConfiguration
+@ContextConfiguration(classes = AppCommentCountAnonymousSecurityTest.TestConfig.class)
+class AppCommentCountAnonymousSecurityTest {
+
+    @Autowired
+    private MockMvc mockMvc;
+
+    @Autowired
+    private CommentService commentService;
+    @Autowired
+    private AppCatalogService catalogService;
+
+    @BeforeEach
+    void setUp() {
+        given(commentService.countByDrama(7L)).willReturn(9L);
+        given(catalogService.feed("ANIME", null, null, 20))
+                .willReturn(new CursorResult<>(List.of(), null, false));
+    }
+
+    @Test
+    void should_allow_anonymous_count_request_through_security_chain() throws Exception {
+        mockMvc.perform(get("/app/comments/count").param("dramaId", "7"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(0))
+                .andExpect(jsonPath("$.data").value(9));
+    }
+
+    @Test
+    void should_allow_anonymous_typed_feed_request_through_security_chain() throws Exception {
+        mockMvc.perform(get("/app/feed")
+                        .param("types", "ANIME")
+                        .param("size", "20"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(0))
+                .andExpect(jsonPath("$.data.list").isArray());
+    }
+
+    @Configuration
+    @EnableWebMvc
+    @EnableWebSecurity
+    @Import(SecurityConfig.class)
+    static class TestConfig {
+
+        @Bean
+        CommentService commentService() {
+            return mock(CommentService.class);
+        }
+
+        @Bean
+        AppCommentController appCommentController(CommentService commentService) {
+            return new AppCommentController(commentService, mock(EpisodeService.class));
+        }
+
+        @Bean
+        AppCatalogService appCatalogService() {
+            return mock(AppCatalogService.class);
+        }
+
+        @Bean
+        AppCatalogController appCatalogController(AppCatalogService appCatalogService) {
+            return new AppCatalogController(appCatalogService);
+        }
+
+        @Bean
+        JwtAuthenticationFilter jwtAuthenticationFilter() {
+            return new JwtAuthenticationFilter(
+                    mock(JwtTokenProvider.class),
+                    mock(ObjectProvider.class));
+        }
+
+        @Bean
+        RestAuthEntryPoint restAuthEntryPoint(ObjectMapper objectMapper) {
+            return new RestAuthEntryPoint(
+                    objectMapper,
+                    new AccessDeniedRecorder(mock(ObjectProvider.class)));
+        }
+
+        @Bean
+        ObjectMapper objectMapper() {
+            return new ObjectMapper();
+        }
+
+        @Bean
+        MockMvc mockMvc(WebApplicationContext context) {
+            FilterChainProxy securityFilter =
+                    context.getBean("springSecurityFilterChain", FilterChainProxy.class);
+            return MockMvcBuilders.webAppContextSetup(context)
+                    .addFilters(securityFilter)
+                    .build();
+        }
+    }
+}

fruitshorts-app-api/src/test/java/com/fruitshorts/app/controller/AppOrdersVerifyContractTest.java

@@ -69,7 +69,8 @@ class AppOrdersVerifyContractTest {
                 new ProductService(productMapper), storeReceiptMapper, verifier,
                 mock(WalletService.class), mock(EntitlementService.class));
         mockMvc = ControllerContractSupport.mockMvcOf(new AppCommerceController(
-                mock(WalletService.class), mock(UnlockService.class), orderService));
+                mock(WalletService.class), mock(UnlockService.class), orderService,
+                mock(ProductService.class)));
         SecurityContextHolder.getContext().setAuthentication(new UsernamePasswordAuthenticationToken(
                 new LoginUser(USER, "app-user", "APP_USER", List.of()), null, List.of()));
     }
@@ -136,7 +137,8 @@ class AppOrdersVerifyContractTest {
                 new ProductService(productMapper), storeReceiptMapper, new DisabledStoreVerifier(),
                 mock(WalletService.class), mock(EntitlementService.class));
         MockMvc disabledMvc = ControllerContractSupport.mockMvcOf(new AppCommerceController(
-                mock(WalletService.class), mock(UnlockService.class), disabled));
+                mock(WalletService.class), mock(UnlockService.class), disabled,
+                mock(ProductService.class)));
 
         String body = disabledMvc.perform(post("/app/orders/verify")
                         .contentType(MediaType.APPLICATION_JSON).content(BODY))

fruitshorts-app-api/src/test/java/com/fruitshorts/app/controller/AppPlaybackContractTest.java

@@ -3,6 +3,9 @@ package com.fruitshorts.app.controller;
 
 import com.fruitshorts.app.service.AppCatalogService;
 import com.fruitshorts.app.support.ControllerContractSupport;
+import com.fruitshorts.content.dal.entity.DramaEpisode;
+import com.fruitshorts.content.service.EpisodeService;
+import com.fruitshorts.interaction.service.CommentService;
 import com.fruitshorts.playback.service.PlaybackService;
 import com.fruitshorts.playback.vo.PlayRespVO;
 import org.junit.jupiter.api.BeforeEach;
@@ -10,6 +13,7 @@ import org.junit.jupiter.api.Test;
 import org.springframework.test.web.servlet.MockMvc;
 
 import java.util.List;
+import java.util.Map;
 
 import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.ArgumentMatchers.eq;
@@ -30,13 +34,22 @@ import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.
 class AppPlaybackContractTest {
 
     private PlaybackService playbackService;
+    private EpisodeService episodeService;
+    private CommentService commentService;
     private MockMvc mockMvc;
 
     @BeforeEach
     void setUp() {
         playbackService = mock(PlaybackService.class);
+        episodeService = mock(EpisodeService.class);
+        commentService = mock(CommentService.class);
+        DramaEpisode episode = new DramaEpisode();
+        episode.setLikeCount(88L);
+        given(episodeService.getExisting(any())).willReturn(episode);
+        given(commentService.countByEpisodes(any())).willReturn(Map.of());
         mockMvc = ControllerContractSupport.mockMvcOf(
-                new AppDramaController(mock(AppCatalogService.class), playbackService));
+                new AppDramaController(mock(AppCatalogService.class), playbackService,
+                        episodeService, commentService));
     }
 
     @Test
@@ -52,7 +65,9 @@ class AppPlaybackContractTest {
                 .andExpect(jsonPath("$.data.episodeId").isString())
                 .andExpect(jsonPath("$.data.accessible").value(true))
                 .andExpect(jsonPath("$.data.accessType").value(PlaybackService.ACCESS_FREE))
-                .andExpect(jsonPath("$.data.playUrl").value("/files/ep.mp4?s=1"));
+                .andExpect(jsonPath("$.data.playUrl").value("/files/ep.mp4?s=1"))
+                .andExpect(jsonPath("$.data.likeCount").value("88"))
+                .andExpect(jsonPath("$.data.commentCount").value("0"));
     }
 
     @Test

fruitshorts-app-api/src/test/java/com/fruitshorts/app/service/AppAuthServiceTest.java

@@ -4,6 +4,7 @@ package com.fruitshorts.app.service;
 import com.fruitshorts.common.exception.ErrorCode;
 import com.fruitshorts.common.exception.ServiceException;
 import com.fruitshorts.framework.security.JwtTokenProvider;
+import com.fruitshorts.system.service.ConfigService;
 import com.fruitshorts.user.dal.entity.AppUser;
 import com.fruitshorts.user.dal.entity.AppUserCredential;
 import com.fruitshorts.user.dal.entity.AppUserOtp;
@@ -18,6 +19,8 @@ import com.fruitshorts.user.enums.AppUserStatus;
 import com.fruitshorts.user.service.AppAuthService;
 import com.fruitshorts.user.service.AppOtpService;
 import com.fruitshorts.user.service.CredentialHasher;
+import com.fruitshorts.user.service.GoogleIdTokenVerifier;
+import com.fruitshorts.user.service.GoogleUser;
 import com.fruitshorts.user.service.OtpSender;
 import com.fruitshorts.user.vo.LoginReqVO;
 import com.fruitshorts.user.vo.RegisterReqVO;
@@ -25,6 +28,7 @@ import com.fruitshorts.user.vo.TokenRespVO;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 import org.springframework.security.crypto.password.PasswordEncoder;
+import org.springframework.test.util.ReflectionTestUtils;
 
 import java.time.Duration;
 import java.time.LocalDateTime;
@@ -57,6 +61,8 @@ class AppAuthServiceTest {
     private CredentialHasher hasher;
     private JwtTokenProvider tokenProvider;
     private PasswordEncoder passwordEncoder;
+    private ConfigService configService;
+    private GoogleIdTokenVerifier googleVerifier;
     private AppAuthService authService;
 
     @BeforeEach
@@ -70,8 +76,13 @@ class AppAuthServiceTest {
         hasher = mock(CredentialHasher.class);
         tokenProvider = mock(JwtTokenProvider.class);
         passwordEncoder = mock(PasswordEncoder.class);
+        configService = mock(ConfigService.class);
+        googleVerifier = mock(GoogleIdTokenVerifier.class);
+        given(configService.get(anyString(), anyString()))
+                .willAnswer(invocation -> invocation.getArgument(1));
         authService = new AppAuthService(userMapper, credentialMapper, sessionMapper, consentMapper,
-                deviceMapper, otpService, hasher, tokenProvider, passwordEncoder);
+                deviceMapper, otpService, hasher, tokenProvider, passwordEncoder, configService,
+                googleVerifier);
     }
 
     @Test
@@ -164,6 +175,7 @@ class AppAuthServiceTest {
 
     @Test
     void should_reject_register_when_ip_reaches_the_daily_limit() {
+        setRegisterLimits(5, 3);
         given(userMapper.selectCount(any())).willReturn(5L);
 
         assertThatThrownBy(() -> authService.register(emailRegister("abcd1234", null), "203.0.113.8"))
@@ -173,6 +185,62 @@ class AppAuthServiceTest {
                 .hasMessageContaining("当前网络注册过于频繁");
     }
 
+    @Test
+    void should_reject_register_when_device_reaches_the_daily_limit() {
+        setRegisterLimits(5, 3);
+        given(userMapper.selectCount(any())).willReturn(3L);
+
+        assertThatThrownBy(() -> authService.register(emailRegister("abcd1234", null), "203.0.113.8"))
+                .isInstanceOf(ServiceException.class)
+                .satisfies(ex -> assertThat(((ServiceException) ex).getCode())
+                        .isEqualTo(ErrorCode.TOO_MANY_REQUESTS.getCode()))
+                .hasMessage("该设备注册过于频繁，请稍后再试");
+    }
+
+    @Test
+    void should_fallback_to_default_limit_when_config_is_not_numeric() {
+        ReflectionTestUtils.setField(authService, "maxRegisterPerIpPerDay", 2);
+        given(configService.get("app.register.max-per-ip-per-day", "2")).willReturn("invalid");
+        given(userMapper.selectCount(any())).willReturn(2L);
+
+        assertThatThrownBy(() -> authService.register(emailRegister("abcd1234", null), "203.0.113.8"))
+                .isInstanceOf(ServiceException.class)
+                .satisfies(ex -> assertThat(((ServiceException) ex).getCode())
+                        .isEqualTo(ErrorCode.TOO_MANY_REQUESTS.getCode()))
+                .hasMessageContaining("当前网络注册过于频繁");
+    }
+
+    @Test
+    void should_fallback_to_default_limit_when_config_is_missing() {
+        given(userMapper.selectCount(any())).willReturn(5L);
+
+        assertThatThrownBy(() -> authService.register(emailRegister("abcd1234", null), "203.0.113.8"))
+                .isInstanceOf(ServiceException.class)
+                .satisfies(ex -> assertThat(((ServiceException) ex).getCode())
+                        .isEqualTo(ErrorCode.TOO_MANY_REQUESTS.getCode()))
+                .hasMessageContaining("当前网络注册过于频繁");
+    }
+
+    @Test
+    void should_not_limit_by_ip_when_ip_limit_is_zero() {
+        stubHappyRegister();
+        setRegisterLimits(0, 3);
+        given(userMapper.selectCount(any())).willReturn(2L);
+
+        assertThat(authService.register(emailRegister("abcd1234", null), "203.0.113.8").getAccessToken())
+                .isEqualTo("access-1");
+    }
+
+    @Test
+    void should_not_limit_by_device_when_device_limit_is_zero() {
+        stubHappyRegister();
+        setRegisterLimits(5, 0);
+        given(userMapper.selectCount(any())).willReturn(4L);
+
+        assertThat(authService.register(emailRegister("abcd1234", null), "203.0.113.8").getAccessToken())
+                .isEqualTo("access-1");
+    }
+
     @Test
     void should_return_tokens_when_password_matches() {
         stubLogin(credential("bcrypt-hash"), user(AppUserStatus.NORMAL));
@@ -219,6 +287,43 @@ class AppAuthServiceTest {
                         .isEqualTo(ErrorCode.ACCOUNT_DISABLED.getCode()));
     }
 
+    @Test
+    void should_auto_register_and_issue_tokens_when_google_login_first_time() {
+        given(googleVerifier.verify(anyString()))
+                .willReturn(new GoogleUser("sub-1", "Alice@Example.com", "Alice", "http://pic/a.png"));
+        given(credentialMapper.selectOne(any())).willReturn(null);
+        given(hasher.newUid()).willReturn("UAB12CD");
+        given(hasher.newRefreshToken()).willReturn("refresh-1");
+        given(hasher.sha256(anyString())).willReturn("hash-1");
+        given(tokenProvider.createAppToken(any(), anyString(), any())).willReturn("access-1");
+        given(tokenProvider.accessTtlSeconds()).willReturn(7200L);
+        given(tokenProvider.appRefreshTtl()).willReturn(Duration.ofDays(30));
+        AtomicReference<AppUser> inserted = new AtomicReference<>();
+        given(userMapper.insert(any(AppUser.class))).willAnswer(invocation -> {
+            AppUser saved = invocation.getArgument(0);
+            saved.setId(1001L);
+            inserted.set(saved);
+            return 1;
+        });
+        given(userMapper.selectById(any())).willAnswer(invocation -> inserted.get());
+
+        TokenRespVO resp = authService.googleLogin("google-id-token");
+
+        assertThat(resp.getAccessToken()).isEqualTo("access-1");
+        assertThat(resp.isNewUser()).isTrue();
+        verify(sessionMapper).insert(any(AppUserSession.class));
+    }
+
+    @Test
+    void should_reject_google_login_when_email_is_missing() {
+        given(googleVerifier.verify(anyString()))
+                .willReturn(new GoogleUser("sub-1", "", "Alice", ""));
+
+        assertThatThrownBy(() -> authService.googleLogin("google-id-token"))
+                .isInstanceOf(ServiceException.class)
+                .hasMessage("Google 账号未返回邮箱，无法登录");
+    }
+
     private void stubHappyRegister() {
         given(userMapper.selectCount(any())).willReturn(0L);
         given(credentialMapper.selectOne(any())).willReturn(null);
@@ -265,7 +370,15 @@ class AppAuthServiceTest {
         given(otpHasher.hashOtp(any())).willReturn("hash-of-something-else");
         AppOtpService realOtpService = new AppOtpService(otpMapper, mock(OtpSender.class), otpHasher);
         return new AppAuthService(userMapper, credentialMapper, sessionMapper, consentMapper,
-                deviceMapper, realOtpService, hasher, tokenProvider, passwordEncoder);
+                deviceMapper, realOtpService, hasher, tokenProvider, passwordEncoder, configService,
+                googleVerifier);
+    }
+
+    private void setRegisterLimits(int perIp, int perDevice) {
+        given(configService.get("app.register.max-per-ip-per-day", "5"))
+                .willReturn(String.valueOf(perIp));
+        given(configService.get("app.register.max-per-device-per-day", "3"))
+                .willReturn(String.valueOf(perDevice));
     }
 
     private RegisterReqVO emailRegister(String password, String code) {

fruitshorts-app-api/src/test/java/com/fruitshorts/app/service/AppCatalogServiceTest.java

@@ -0,0 +1,206 @@
+// Author: fruit.com.cn
+package com.fruitshorts.app.service;
+
+import com.fruitshorts.app.vo.AppDramaCardVO;
+import com.fruitshorts.app.vo.AppDramaDetailVO;
+import com.fruitshorts.common.pojo.CursorResult;
+import com.fruitshorts.content.dal.entity.Drama;
+import com.fruitshorts.content.dal.entity.DramaEpisode;
+import com.fruitshorts.content.service.BannerService;
+import com.fruitshorts.content.service.DramaCategoryService;
+import com.fruitshorts.content.service.DramaService;
+import com.fruitshorts.content.service.EpisodeService;
+import com.fruitshorts.interaction.service.CommentService;
+import com.fruitshorts.media.service.PlaybackSigner;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.BDDMockito.given;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+
+/**
+ * 目录聚合的互动数量装配：详情 VO 的点赞/收藏取短剧计数，评论数取互动域统计。
+ */
+class AppCatalogServiceTest {
+
+    private DramaService dramaService;
+    private EpisodeService episodeService;
+    private DramaCategoryService dramaCategoryService;
+    private CommentService commentService;
+    private AppCatalogService catalogService;
+
+    @BeforeEach
+    void setUp() {
+        dramaService = mock(DramaService.class);
+        episodeService = mock(EpisodeService.class);
+        BannerService bannerService = mock(BannerService.class);
+        dramaCategoryService = mock(DramaCategoryService.class);
+        PlaybackSigner playbackSigner = mock(PlaybackSigner.class);
+        commentService = mock(CommentService.class);
+        catalogService = new AppCatalogService(dramaService, episodeService, bannerService,
+                dramaCategoryService, playbackSigner, commentService);
+    }
+
+    @Test
+    void should_fill_interaction_counts_when_drama_detail_is_built() {
+        Drama drama = new Drama();
+        drama.setId(42L);
+        drama.setTitle("命运的相遇");
+        drama.setLikeCount(3200L);
+        drama.setFavoriteCount(1800L);
+        drama.setViewCount(12400L);
+        DramaEpisode firstEpisode = episode(11L, 42L, 55L);
+        DramaEpisode secondEpisode = episode(22L, 42L, 66L);
+        given(dramaService.getPublished(42L)).willReturn(drama);
+        given(episodeService.listPublishedByDrama(42L))
+                .willReturn(List.of(secondEpisode, firstEpisode));
+        given(dramaCategoryService.listBasic()).willReturn(List.of());
+        given(commentService.countByDrama(42L)).willReturn(96L);
+        given(commentService.countByEpisodes(List.of(11L, 22L)))
+                .willReturn(Map.of(11L, 2L, 22L, 4L));
+
+        AppDramaDetailVO detail = catalogService.dramaDetail(42L);
+
+        assertThat(detail.getViewCount()).isEqualTo(12400L);
+        assertThat(detail.getLikeCount()).isEqualTo(3200L);
+        assertThat(detail.getFavoriteCount()).isEqualTo(1800L);
+        assertThat(detail.getCommentCount()).isEqualTo(96L);
+        assertThat(detail.getEpisodes().get(0).getLikeCount()).isEqualTo(66L);
+        assertThat(detail.getEpisodes().get(0).getCommentCount()).isEqualTo(4L);
+        verify(commentService).countByDrama(42L);
+    }
+
+    @Test
+    void should_fill_card_counts_with_one_batch_comment_query() {
+        Drama first = new Drama();
+        first.setId(1L);
+        first.setTitle("第一部");
+        first.setViewCount(1200L);
+        first.setLikeCount(320L);
+        first.setFavoriteCount(180L);
+        Drama second = new Drama();
+        second.setId(2L);
+        second.setTitle("第二部");
+        second.setViewCount(800L);
+        second.setLikeCount(120L);
+        second.setFavoriteCount(80L);
+        DramaEpisode firstEpisode = episode(11L, 1L, 320L);
+        DramaEpisode secondEpisode = episode(22L, 2L, 120L);
+        Map<Long, DramaEpisode> previews = new LinkedHashMap<>();
+        previews.put(2L, secondEpisode);
+        previews.put(1L, firstEpisode);
+        given(episodeService.firstPlayableByDramas(List.of(1L, 2L))).willReturn(previews);
+        given(dramaCategoryService.listBasic()).willReturn(List.of());
+        given(commentService.countByEpisodes(List.of(11L, 22L)))
+                .willReturn(Map.of(11L, 9L));
+
+        List<AppDramaCardVO> cards = catalogService.toCards(List.of(first, second));
+
+        assertThat(cards).hasSize(2);
+        assertThat(cards.get(0).getLikeCount()).isEqualTo(320L);
+        assertThat(cards.get(0).getFavoriteCount()).isEqualTo(180L);
+        assertThat(cards.get(0).getCommentCount()).isEqualTo(9L);
+        assertThat(cards.get(1).getLikeCount()).isEqualTo(120L);
+        assertThat(cards.get(1).getFavoriteCount()).isEqualTo(80L);
+        assertThat(cards.get(1).getCommentCount()).isZero();
+        verify(commentService).countByEpisodes(List.of(11L, 22L));
+        verify(commentService, never()).countByDrama(any());
+    }
+
+    @Test
+    void should_filter_feed_by_drama_type_and_expose_it_on_card() {
+        Drama anime = drama(1L, "ANIME");
+        given(dramaService.listPublishedFeed(List.of("ANIME"), null, null, 21))
+                .willReturn(List.of(anime));
+        given(dramaCategoryService.listBasic()).willReturn(List.of());
+        DramaEpisode preview = episode(11L, 1L, 45L);
+        given(episodeService.firstPlayableByDramas(List.of(1L)))
+                .willReturn(Map.of(1L, preview));
+        given(commentService.countByEpisodes(List.of(11L))).willReturn(Map.of(11L, 3L));
+
+        CursorResult<AppDramaCardVO> result = catalogService.feed(
+                "ANIME", null, null, null);
+
+        assertThat(result.getList()).hasSize(1);
+        assertThat(result.getList().get(0).getDramaType()).isEqualTo("ANIME");
+        assertThat(result.getList().get(0).getCommentCount()).isEqualTo(3L);
+        assertThat(result.getList().get(0).getLikeCount()).isEqualTo(45L);
+        assertThat(result.isHasMore()).isFalse();
+        verify(dramaService).listPublishedFeed(List.of("ANIME"), null, null, 21);
+    }
+
+    @Test
+    void should_parse_multiple_feed_types() {
+        given(dramaService.listPublishedFeed(
+                List.of("ANIME", "LIVE"), null, null, 11))
+                .willReturn(List.of());
+
+        CursorResult<AppDramaCardVO> result = catalogService.feed(
+                "ANIME,LIVE", null, null, 10);
+
+        assertThat(result.getList()).isEmpty();
+        verify(dramaService).listPublishedFeed(
+                List.of("ANIME", "LIVE"), null, null, 11);
+    }
+
+    @Test
+    void should_filter_feed_by_category_id_only() {
+        given(dramaService.listPublishedFeed(List.of(), 7L, null, 21))
+                .willReturn(List.of());
+
+        CursorResult<AppDramaCardVO> result = catalogService.feed(
+                null, 7L, null, null);
+
+        assertThat(result.getList()).isEmpty();
+        verify(dramaService).listPublishedFeed(List.of(), 7L, null, 21);
+    }
+
+    @Test
+    void should_page_feed_with_cursor_without_duplicates() {
+        Drama first = drama(1L, "ANIME");
+        Drama second = drama(2L, "LIVE");
+        given(dramaService.listPublishedFeed(List.of(), null, null, 2))
+                .willReturn(List.of(first, second));
+        given(dramaService.listPublishedFeed(List.of(), null, 1L, 2))
+                .willReturn(List.of(second));
+        given(dramaCategoryService.listBasic()).willReturn(List.of());
+        given(episodeService.firstPlayableByDramas(any())).willReturn(Map.of());
+        given(commentService.countByEpisodes(any())).willReturn(Map.of());
+
+        CursorResult<AppDramaCardVO> firstPage = catalogService.feed(
+                null, null, null, 1);
+        CursorResult<AppDramaCardVO> secondPage = catalogService.feed(
+                null, null, firstPage.getNextCursor(), 1);
+
+        assertThat(firstPage.getList()).extracting(AppDramaCardVO::getId).containsExactly(1L);
+        assertThat(firstPage.getNextCursor()).isEqualTo(1L);
+        assertThat(firstPage.isHasMore()).isTrue();
+        assertThat(secondPage.getList()).extracting(AppDramaCardVO::getId).containsExactly(2L);
+        assertThat(secondPage.getNextCursor()).isNull();
+        assertThat(secondPage.isHasMore()).isFalse();
+    }
+
+    private Drama drama(Long id, String dramaType) {
+        Drama drama = new Drama();
+        drama.setId(id);
+        drama.setTitle("短剧" + id);
+        drama.setDramaType(dramaType);
+        return drama;
+    }
+
+    private DramaEpisode episode(Long id, Long dramaId, Long likeCount) {
+        DramaEpisode episode = new DramaEpisode();
+        episode.setId(id);
+        episode.setDramaId(dramaId);
+        episode.setLikeCount(likeCount);
+        return episode;
+    }
+}

fruitshorts-app-api/src/test/java/com/fruitshorts/app/service/CommentServiceCountTest.java

@@ -0,0 +1,131 @@
+// Author: fruit.com.cn
+package com.fruitshorts.app.service;
+
+import com.baomidou.mybatisplus.core.MybatisConfiguration;
+import com.baomidou.mybatisplus.core.conditions.AbstractWrapper;
+import com.baomidou.mybatisplus.core.conditions.Wrapper;
+import com.baomidou.mybatisplus.core.metadata.TableInfoHelper;
+import com.fruitshorts.content.service.DramaService;
+import com.fruitshorts.content.service.EpisodeService;
+import com.fruitshorts.interaction.config.InteractionProperties;
+import com.fruitshorts.interaction.dal.entity.ContentComment;
+import com.fruitshorts.interaction.dal.mapper.ContentAuditRecordMapper;
+import com.fruitshorts.interaction.dal.mapper.ContentCommentMapper;
+import com.fruitshorts.interaction.dal.mapper.ContentLikeMapper;
+import com.fruitshorts.interaction.service.AuditRecorder;
+import com.fruitshorts.interaction.service.CommentService;
+import com.fruitshorts.interaction.service.SensitiveWordService;
+import com.fruitshorts.user.dal.mapper.AppUserMapper;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.Test;
+import org.mockito.ArgumentCaptor;
+import org.apache.ibatis.builder.MapperBuilderAssistant;
+
+import java.util.Arrays;
+import java.util.List;
+import java.util.Map;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.BDDMockito.given;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+
+/**
+ * 评论计数口径：按剧统计，排除已删除评论。
+ */
+class CommentServiceCountTest {
+
+    private ContentCommentMapper commentMapper;
+    private CommentService commentService;
+
+    @BeforeAll
+    static void initTableInfo() {
+        TableInfoHelper.initTableInfo(
+                new MapperBuilderAssistant(new MybatisConfiguration(), ""), ContentComment.class);
+    }
+
+    @BeforeEach
+    void setUp() {
+        commentMapper = mock(ContentCommentMapper.class);
+        commentService = new CommentService(
+                commentMapper,
+                mock(ContentLikeMapper.class),
+                mock(ContentAuditRecordMapper.class),
+                mock(AppUserMapper.class),
+                mock(DramaService.class),
+                mock(EpisodeService.class),
+                mock(SensitiveWordService.class),
+                mock(AuditRecorder.class),
+                mock(InteractionProperties.class));
+    }
+
+    @Test
+    void should_count_comments_of_drama_and_exclude_deleted() {
+        ArgumentCaptor<Wrapper<ContentComment>> captor = ArgumentCaptor.forClass(Wrapper.class);
+        given(commentMapper.selectCount(captor.capture())).willReturn(5L);
+
+        long count = commentService.countByDrama(7L);
+
+        assertThat(count).isEqualTo(5L);
+        Wrapper<ContentComment> wrapper = captor.getValue();
+        assertThat(wrapper.getSqlSegment()).contains("drama_id").contains("status");
+        AbstractWrapper<ContentComment, ?, ?> lambda = (AbstractWrapper<ContentComment, ?, ?>) wrapper;
+        assertThat(lambda.getParamNameValuePairs().values()).contains(7L, "deleted");
+    }
+
+    @Test
+    void should_return_zero_without_query_when_drama_id_is_missing() {
+        assertThat(commentService.countByDrama(null)).isZero();
+        verify(commentMapper, never()).selectCount(any());
+    }
+
+    @Test
+    void should_return_empty_map_without_query_when_drama_ids_are_empty() {
+        assertThat(commentService.countByDramas(List.of())).isEmpty();
+        verify(commentMapper, never()).selectMaps(any());
+    }
+
+    @Test
+    void should_group_comment_counts_when_multiple_dramas_are_requested() {
+        ArgumentCaptor<Wrapper<ContentComment>> captor = ArgumentCaptor.forClass(Wrapper.class);
+        given(commentMapper.selectMaps(captor.capture())).willReturn(List.of(
+                Map.of("drama_id", 7L, "comment_count", 5L),
+                Map.of("drama_id", 8L, "comment_count", 2L)));
+
+        Map<Long, Long> counts = commentService.countByDramas(
+                Arrays.asList(7L, 8L, 8L, null));
+
+        assertThat(counts).containsEntry(7L, 5L).containsEntry(8L, 2L);
+        Wrapper<ContentComment> wrapper = captor.getValue();
+        assertThat(wrapper.getSqlSegment())
+                .contains("drama_id")
+                .contains("status")
+                .contains("deleted")
+                .contains("GROUP BY");
+        AbstractWrapper<ContentComment, ?, ?> lambda = (AbstractWrapper<ContentComment, ?, ?>) wrapper;
+        assertThat(lambda.getParamNameValuePairs().values())
+                .contains(7L, 8L, "deleted");
+    }
+
+    @Test
+    void should_group_comment_counts_by_episode() {
+        ArgumentCaptor<Wrapper<ContentComment>> captor = ArgumentCaptor.forClass(Wrapper.class);
+        given(commentMapper.selectMaps(captor.capture())).willReturn(List.of(
+                Map.of("episode_id", 11L, "comment_count", 4L),
+                Map.of("episode_id", 12L, "comment_count", 2L)));
+
+        Map<Long, Long> counts = commentService.countByEpisodes(
+                Arrays.asList(11L, 12L, 12L, null));
+
+        assertThat(counts).containsEntry(11L, 4L).containsEntry(12L, 2L);
+        Wrapper<ContentComment> wrapper = captor.getValue();
+        assertThat(wrapper.getSqlSegment())
+                .contains("episode_id")
+                .contains("status")
+                .contains("deleted")
+                .contains("GROUP BY");
+    }
+}

fruitshorts-app-api/src/test/java/com/fruitshorts/app/service/DramaServiceFavoriteCountTest.java

@@ -0,0 +1,57 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.app.service;
+
+import com.baomidou.mybatisplus.core.MybatisConfiguration;
+import com.baomidou.mybatisplus.core.conditions.Wrapper;
+import com.baomidou.mybatisplus.core.conditions.update.LambdaUpdateWrapper;
+import com.baomidou.mybatisplus.core.metadata.TableInfoHelper;
+import com.fruitshorts.content.dal.entity.Drama;
+import com.fruitshorts.content.dal.mapper.DramaEpisodeMapper;
+import com.fruitshorts.content.dal.mapper.DramaMapper;
+import com.fruitshorts.content.dal.mapper.DramaReviewRecordMapper;
+import com.fruitshorts.content.service.DramaCategoryService;
+import com.fruitshorts.content.service.DramaService;
+import org.apache.ibatis.builder.MapperBuilderAssistant;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.Test;
+import org.mockito.ArgumentCaptor;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.isNull;
+import static org.mockito.BDDMockito.given;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+
+/** 收藏数减操作必须使用不低于 0 的原子 SQL。 */
+class DramaServiceFavoriteCountTest {
+
+    @BeforeAll
+    static void initTableInfo() {
+        TableInfoHelper.initTableInfo(
+                new MapperBuilderAssistant(new MybatisConfiguration(), ""), Drama.class);
+    }
+
+    @Test
+    @SuppressWarnings("unchecked")
+    void should_use_greatest_zero_when_favorite_count_decrements() {
+        DramaMapper dramaMapper = mock(DramaMapper.class);
+        DramaService dramaService = new DramaService(
+                dramaMapper,
+                mock(DramaEpisodeMapper.class),
+                mock(DramaReviewRecordMapper.class),
+                mock(DramaCategoryService.class));
+        given(dramaMapper.update(isNull(), any())).willReturn(1);
+        ArgumentCaptor<Wrapper<Drama>> captor = ArgumentCaptor.forClass(Wrapper.class);
+
+        dramaService.adjustFavoriteCount(7L, -1);
+
+        verify(dramaMapper).update(isNull(), captor.capture());
+        Wrapper<Drama> wrapper = captor.getValue();
+        LambdaUpdateWrapper<Drama> update = (LambdaUpdateWrapper<Drama>) wrapper;
+        assertThat(update.getSqlSet())
+                .contains("GREATEST(favorite_count - 1, 0)");
+        assertThat(update.getSqlSegment()).contains("id");
+    }
+}

fruitshorts-app-api/src/test/java/com/fruitshorts/app/service/DramaServiceFeedTest.java

@@ -0,0 +1,159 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.app.service;
+
+import com.baomidou.mybatisplus.core.MybatisConfiguration;
+import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper;
+import com.baomidou.mybatisplus.core.metadata.TableInfoHelper;
+import com.fruitshorts.content.dal.entity.Drama;
+import com.fruitshorts.content.dal.mapper.DramaEpisodeMapper;
+import com.fruitshorts.content.dal.mapper.DramaMapper;
+import com.fruitshorts.content.dal.mapper.DramaReviewRecordMapper;
+import com.fruitshorts.content.service.DramaCategoryService;
+import com.fruitshorts.content.service.DramaService;
+import org.apache.ibatis.builder.MapperBuilderAssistant;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.mockito.ArgumentCaptor;
+
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.BDDMockito.given;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+
+/** K88 App 推荐流的类型过滤与三字段 keyset 游标。 */
+class DramaServiceFeedTest {
+
+    private DramaMapper dramaMapper;
+    private DramaService dramaService;
+
+    @BeforeAll
+    static void initTableInfo() {
+        TableInfoHelper.initTableInfo(
+                new MapperBuilderAssistant(new MybatisConfiguration(), ""), Drama.class);
+    }
+
+    @BeforeEach
+    void setUp() {
+        dramaMapper = mock(DramaMapper.class);
+        dramaService = new DramaService(
+                dramaMapper,
+                mock(DramaEpisodeMapper.class),
+                mock(DramaReviewRecordMapper.class),
+                mock(DramaCategoryService.class));
+    }
+
+    @Test
+    @SuppressWarnings("unchecked")
+    void should_filter_types_and_apply_recommendation_cursor() {
+        Drama marker = new Drama();
+        marker.setId(9L);
+        marker.setStatus("published");
+        marker.setDramaType("ANIME");
+        marker.setRecommendWeight(30);
+        marker.setViewCount(1200L);
+        given(dramaMapper.selectById(9L)).willReturn(marker);
+        given(dramaMapper.selectList(any())).willReturn(List.of());
+        ArgumentCaptor<QueryWrapper<Drama>> captor = ArgumentCaptor.forClass(QueryWrapper.class);
+
+        dramaService.listPublishedFeed(List.of("ANIME"), null, 9L, 5);
+
+        verify(dramaMapper).selectList(captor.capture());
+        QueryWrapper<Drama> query = captor.getValue();
+        assertThat(query.getSqlSegment())
+                .contains("status")
+                .contains("drama_type")
+                .contains("recommend_weight")
+                .contains("view_count")
+                .contains("id");
+        assertThat(query.getParamNameValuePairs().values())
+                .contains("published", "%,ANIME,%", 30, 1200L, 9L);
+    }
+
+    @Test
+    @SuppressWarnings("unchecked")
+    void should_handle_null_recommend_weight_in_cursor() {
+        Drama marker = new Drama();
+        marker.setId(9L);
+        marker.setStatus("published");
+        marker.setDramaType("LIVE");
+        marker.setViewCount(1200L);
+        given(dramaMapper.selectById(9L)).willReturn(marker);
+        given(dramaMapper.selectList(any())).willReturn(List.of());
+        ArgumentCaptor<QueryWrapper<Drama>> captor = ArgumentCaptor.forClass(QueryWrapper.class);
+
+        dramaService.listPublishedFeed(List.of("LIVE"), null, 9L, 5);
+
+        verify(dramaMapper).selectList(captor.capture());
+        assertThat(captor.getValue().getSqlSegment())
+                .contains("recommend_weight IS NULL")
+                .contains("view_count")
+                .contains("id");
+    }
+
+    @Test
+    @SuppressWarnings("unchecked")
+    void should_apply_category_and_type_tokens_together() {
+        given(dramaMapper.selectList(any())).willReturn(List.of());
+        ArgumentCaptor<QueryWrapper<Drama>> captor = ArgumentCaptor.forClass(QueryWrapper.class);
+
+        dramaService.listPublishedFeed(List.of("ANIME"), 7L, null, 5);
+
+        verify(dramaMapper).selectList(captor.capture());
+        QueryWrapper<Drama> query = captor.getValue();
+        assertThat(query.getSqlSegment())
+                .contains("drama_types")
+                .contains("category_ids")
+                .contains("recommend_weight");
+        assertThat(query.getParamNameValuePairs().values())
+                .contains("%,ANIME,%", "%,7,%");
+    }
+
+    @Test
+    @SuppressWarnings("unchecked")
+    void should_apply_category_cursor_for_matching_marker() {
+        Drama marker = new Drama();
+        marker.setId(9L);
+        marker.setStatus("published");
+        marker.setDramaType("ANIME");
+        marker.setCategoryId(7L);
+        marker.setCategoryIds("7,8");
+        marker.setRecommendWeight(30);
+        marker.setViewCount(1200L);
+        given(dramaMapper.selectById(9L)).willReturn(marker);
+        given(dramaMapper.selectList(any())).willReturn(List.of());
+        ArgumentCaptor<QueryWrapper<Drama>> captor = ArgumentCaptor.forClass(QueryWrapper.class);
+
+        dramaService.listPublishedFeed(List.of(), 7L, 9L, 5);
+
+        verify(dramaMapper).selectList(captor.capture());
+        QueryWrapper<Drama> query = captor.getValue();
+        assertThat(query.getSqlSegment())
+                .contains("category_ids")
+                .contains("recommend_weight")
+                .contains("id");
+        assertThat(query.getParamNameValuePairs().values())
+                .contains("%,7,%", 30, 1200L, 9L);
+    }
+
+    @Test
+    void should_return_empty_when_cursor_marker_does_not_match_category() {
+        Drama marker = new Drama();
+        marker.setId(9L);
+        marker.setStatus("published");
+        marker.setDramaType("ANIME");
+        marker.setCategoryId(8L);
+        marker.setCategoryIds("8");
+        given(dramaMapper.selectById(9L)).willReturn(marker);
+
+        List<Drama> rows = dramaService.listPublishedFeed(List.of("ANIME"), 7L, 9L, 5);
+
+        assertThat(rows).isEmpty();
+        verify(dramaMapper, never()).selectList(any());
+    }
+}

fruitshorts-app-api/src/test/java/com/fruitshorts/app/service/DramaServiceK88Test.java

@@ -0,0 +1,127 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.app.service;
+
+import com.baomidou.mybatisplus.core.MybatisConfiguration;
+import com.baomidou.mybatisplus.core.metadata.TableInfoHelper;
+import com.fruitshorts.common.exception.ErrorCode;
+import com.fruitshorts.common.exception.ServiceException;
+import com.fruitshorts.content.dal.entity.Drama;
+import com.fruitshorts.content.dal.mapper.DramaEpisodeMapper;
+import com.fruitshorts.content.dal.mapper.DramaMapper;
+import com.fruitshorts.content.dal.mapper.DramaReviewRecordMapper;
+import com.fruitshorts.content.service.DramaCategoryService;
+import com.fruitshorts.content.service.DramaService;
+import com.fruitshorts.content.vo.DramaSaveReqVO;
+import org.apache.ibatis.builder.MapperBuilderAssistant;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.mockito.ArgumentCaptor;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.BDDMockito.given;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+
+/** K88 后台短剧内容类型与互动数据编辑规则。 */
+class DramaServiceK88Test {
+
+    private DramaMapper dramaMapper;
+    private DramaService dramaService;
+
+    @BeforeAll
+    static void initTableInfo() {
+        TableInfoHelper.initTableInfo(
+                new MapperBuilderAssistant(new MybatisConfiguration(), ""), Drama.class);
+    }
+
+    @BeforeEach
+    void setUp() {
+        dramaMapper = mock(DramaMapper.class);
+        dramaService = new DramaService(
+                dramaMapper,
+                mock(DramaEpisodeMapper.class),
+                mock(DramaReviewRecordMapper.class),
+                mock(DramaCategoryService.class));
+    }
+
+    @Test
+    void should_update_only_requested_counts_and_preserve_drama_type() {
+        Drama existing = drama();
+        given(dramaMapper.selectById(7L)).willReturn(existing);
+        DramaSaveReqVO req = new DramaSaveReqVO();
+        req.setTitle("更新后的标题");
+        req.setFavoriteCount(99L);
+        req.setHeat(500L);
+
+        dramaService.update(7L, req);
+
+        ArgumentCaptor<Drama> captor = ArgumentCaptor.forClass(Drama.class);
+        verify(dramaMapper).updateById(captor.capture());
+        Drama updated = captor.getValue();
+        assertThat(updated.getFavoriteCount()).isEqualTo(99L);
+        assertThat(updated.getLikeCount()).isEqualTo(20L);
+        assertThat(updated.getViewCount()).isEqualTo(500L);
+        assertThat(updated.getDramaType()).isEqualTo("ANIME");
+    }
+
+    @Test
+    void should_reject_negative_interaction_count() {
+        given(dramaMapper.selectById(7L)).willReturn(drama());
+        DramaSaveReqVO req = new DramaSaveReqVO();
+        req.setTitle("更新后的标题");
+        req.setFavoriteCount(-1L);
+
+        assertThatThrownBy(() -> dramaService.update(7L, req))
+                .isInstanceOf(ServiceException.class)
+                .satisfies(error -> assertThat(((ServiceException) error).getCode())
+                        .isEqualTo(ErrorCode.BAD_REQUEST.getCode()));
+        verify(dramaMapper, never()).updateById(any(Drama.class));
+    }
+
+    @Test
+    void should_reject_invalid_drama_type() {
+        given(dramaMapper.selectById(7L)).willReturn(drama());
+        DramaSaveReqVO req = new DramaSaveReqVO();
+        req.setTitle("更新后的标题");
+        req.setDramaType("MOVIE");
+
+        assertThatThrownBy(() -> dramaService.update(7L, req))
+                .isInstanceOf(ServiceException.class)
+                .satisfies(error -> assertThat(((ServiceException) error).getCode())
+                        .isEqualTo(ErrorCode.BAD_REQUEST.getCode()));
+        verify(dramaMapper, never()).updateById(any(Drama.class));
+    }
+
+    @Test
+    void should_default_new_drama_to_live_and_zero_counts() {
+        DramaSaveReqVO req = new DramaSaveReqVO();
+        req.setTitle("新短剧");
+
+        dramaService.create(req, 1L);
+
+        ArgumentCaptor<Drama> captor = ArgumentCaptor.forClass(Drama.class);
+        verify(dramaMapper).insert(captor.capture());
+        Drama created = captor.getValue();
+        assertThat(created.getDramaType()).isEqualTo("LIVE");
+        assertThat(created.getFavoriteCount()).isZero();
+        assertThat(created.getLikeCount()).isZero();
+        assertThat(created.getViewCount()).isZero();
+    }
+
+    private Drama drama() {
+        Drama drama = new Drama();
+        drama.setId(7L);
+        drama.setTitle("原标题");
+        drama.setStatus("published");
+        drama.setDramaType("ANIME");
+        drama.setFavoriteCount(10L);
+        drama.setLikeCount(20L);
+        drama.setViewCount(30L);
+        return drama;
+    }
+}

fruitshorts-app-api/src/test/java/com/fruitshorts/app/service/DramaServiceMultiTagTest.java

@@ -0,0 +1,192 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.app.service;
+
+import com.baomidou.mybatisplus.core.MybatisConfiguration;
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper;
+import com.baomidou.mybatisplus.core.metadata.TableInfoHelper;
+import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
+import com.fruitshorts.content.dal.entity.Drama;
+import com.fruitshorts.content.dal.mapper.DramaEpisodeMapper;
+import com.fruitshorts.content.dal.mapper.DramaMapper;
+import com.fruitshorts.content.dal.mapper.DramaReviewRecordMapper;
+import com.fruitshorts.content.service.DramaCategoryService;
+import com.fruitshorts.content.service.DramaService;
+import com.fruitshorts.content.vo.DramaPageReqVO;
+import com.fruitshorts.content.vo.DramaRespVO;
+import com.fruitshorts.content.vo.DramaSaveReqVO;
+import org.apache.ibatis.builder.MapperBuilderAssistant;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.mockito.ArgumentCaptor;
+
+import java.util.Arrays;
+import java.util.List;
+import java.util.Map;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.BDDMockito.given;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.times;
+import static org.mockito.Mockito.verify;
+
+/** K93 短剧分类与内容类型多选。 */
+class DramaServiceMultiTagTest {
+
+    private DramaMapper dramaMapper;
+    private DramaCategoryService categoryService;
+    private DramaService dramaService;
+
+    @BeforeAll
+    static void initTableInfo() {
+        TableInfoHelper.initTableInfo(
+                new MapperBuilderAssistant(new MybatisConfiguration(), ""), Drama.class);
+    }
+
+    @BeforeEach
+    void setUp() {
+        dramaMapper = mock(DramaMapper.class);
+        categoryService = mock(DramaCategoryService.class);
+        dramaService = new DramaService(
+                dramaMapper,
+                mock(DramaEpisodeMapper.class),
+                mock(DramaReviewRecordMapper.class),
+                categoryService);
+    }
+
+    @Test
+    void should_save_distinct_multi_tags_and_write_first_value_as_primary() {
+        DramaSaveReqVO req = new DramaSaveReqVO();
+        req.setTitle("多标签短剧");
+        req.setDramaTypes(List.of("live", "ANIME", "LIVE", " anime "));
+        req.setCategoryIds(Arrays.asList(3L, 1L, 3L, 0L, null));
+        req.setGenre("类型三 / 类型一");
+
+        dramaService.create(req, 1L);
+
+        ArgumentCaptor<Drama> captor = ArgumentCaptor.forClass(Drama.class);
+        verify(dramaMapper).insert(captor.capture());
+        Drama created = captor.getValue();
+        assertThat(created.getDramaType()).isEqualTo("LIVE");
+        assertThat(created.getDramaTypes()).isEqualTo("LIVE,ANIME");
+        assertThat(created.getCategoryId()).isEqualTo(3L);
+        assertThat(created.getCategoryIds()).isEqualTo("3,1");
+    }
+
+    @Test
+    void should_keep_single_value_behavior_when_lists_are_absent() {
+        Drama existing = drama(7L);
+        existing.setDramaType("ANIME");
+        existing.setDramaTypes("ANIME");
+        existing.setCategoryId(2L);
+        existing.setCategoryIds("2");
+        given(dramaMapper.selectById(7L)).willReturn(existing);
+        DramaSaveReqVO req = new DramaSaveReqVO();
+        req.setTitle("单值更新");
+        req.setDramaType("live");
+        req.setCategoryId(4L);
+
+        dramaService.update(7L, req);
+
+        ArgumentCaptor<Drama> captor = ArgumentCaptor.forClass(Drama.class);
+        verify(dramaMapper).updateById(captor.capture());
+        assertThat(captor.getValue().getDramaType()).isEqualTo("LIVE");
+        assertThat(captor.getValue().getDramaTypes()).isEqualTo("LIVE");
+        assertThat(captor.getValue().getCategoryId()).isEqualTo(4L);
+        assertThat(captor.getValue().getCategoryIds()).isEqualTo("4");
+    }
+
+    @Test
+    @SuppressWarnings("unchecked")
+    void should_apply_token_filters_for_admin_page_multi_tags() {
+        Page<Drama> page = new Page<>(1, 10);
+        page.setRecords(List.of());
+        given(dramaMapper.selectPage(any(Page.class), any())).willReturn(page);
+        DramaPageReqVO req = new DramaPageReqVO();
+        req.setDramaTypes(List.of("ANIME", "LIVE"));
+        req.setCategoryIds(List.of(2L, 3L));
+        ArgumentCaptor<LambdaQueryWrapper<Drama>> captor =
+                ArgumentCaptor.forClass(LambdaQueryWrapper.class);
+
+        dramaService.page(req);
+
+        verify(dramaMapper).selectPage(any(), captor.capture());
+        assertThat(captor.getValue().getSqlSegment())
+                .contains("drama_types")
+                .contains("category_ids")
+                .contains("LIKE");
+        assertThat(captor.getValue().getParamNameValuePairs().values())
+                .contains("%,ANIME,%", "%,LIVE,%", "%,2,%", "%,3,%");
+    }
+
+    @Test
+    @SuppressWarnings("unchecked")
+    void should_allow_multi_tag_cursor_marker_for_each_filter_type() {
+        Drama marker = drama(9L);
+        marker.setDramaType("ANIME");
+        marker.setDramaTypes("ANIME,LIVE");
+        marker.setRecommendWeight(30);
+        marker.setViewCount(1200L);
+        given(dramaMapper.selectById(9L)).willReturn(marker);
+        given(dramaMapper.selectList(any())).willReturn(List.of());
+        ArgumentCaptor<QueryWrapper<Drama>> captor = ArgumentCaptor.forClass(QueryWrapper.class);
+
+        dramaService.listPublishedFeed(List.of("ANIME"), null, 9L, 5);
+        dramaService.listPublishedFeed(List.of("LIVE"), null, 9L, 5);
+
+        verify(dramaMapper, times(2)).selectList(captor.capture());
+        assertThat(captor.getAllValues()).allSatisfy(query ->
+                assertThat(query.getSqlSegment())
+                        .contains("drama_types")
+                        .contains("LIKE"));
+    }
+
+    @Test
+    @SuppressWarnings("unchecked")
+    void should_match_multi_category_when_loading_app_category_section() {
+        Page<Drama> page = new Page<>(1, 10);
+        page.setRecords(List.of());
+        given(dramaMapper.selectPage(any(Page.class), any())).willReturn(page);
+        ArgumentCaptor<LambdaQueryWrapper<Drama>> captor =
+                ArgumentCaptor.forClass(LambdaQueryWrapper.class);
+
+        dramaService.listPublished(3L, 10);
+
+        verify(dramaMapper).selectPage(any(), captor.capture());
+        assertThat(captor.getValue().getSqlSegment())
+                .contains("category_ids")
+                .contains("LIKE");
+        assertThat(captor.getValue().getParamNameValuePairs().values()).contains("%,3,%");
+    }
+
+    @Test
+    void should_parse_multi_values_and_keep_category_name_order_in_response() {
+        Drama drama = drama(7L);
+        drama.setDramaType("LIVE");
+        drama.setDramaTypes("LIVE,ANIME");
+        drama.setCategoryId(3L);
+        drama.setCategoryIds("3,1");
+        drama.setGenre("Fallback Genre");
+        given(dramaMapper.selectById(7L)).willReturn(drama);
+        given(categoryService.nameMap()).willReturn(Map.of(1L, "Type A", 3L, "Type B"));
+
+        DramaRespVO vo = dramaService.get(7L);
+
+        assertThat(vo.getDramaTypes()).containsExactly("LIVE", "ANIME");
+        assertThat(vo.getCategoryIds()).containsExactly(3L, 1L);
+        assertThat(vo.getCategoryNames()).containsExactly("Type B", "Type A");
+        assertThat(vo.getDramaType()).isEqualTo("LIVE");
+        assertThat(vo.getCategoryId()).isEqualTo(3L);
+    }
+
+    private Drama drama(Long id) {
+        Drama drama = new Drama();
+        drama.setId(id);
+        drama.setStatus("published");
+        drama.setViewCount(0L);
+        return drama;
+    }
+}

fruitshorts-app-api/src/test/java/com/fruitshorts/app/service/EpisodeServiceK89Test.java

@@ -0,0 +1,113 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.app.service;
+
+import com.baomidou.mybatisplus.core.MybatisConfiguration;
+import com.baomidou.mybatisplus.core.conditions.Wrapper;
+import com.baomidou.mybatisplus.core.conditions.update.LambdaUpdateWrapper;
+import com.baomidou.mybatisplus.core.metadata.TableInfoHelper;
+import com.fruitshorts.common.exception.ErrorCode;
+import com.fruitshorts.common.exception.ServiceException;
+import com.fruitshorts.content.dal.entity.DramaEpisode;
+import com.fruitshorts.content.dal.mapper.DramaEpisodeMapper;
+import com.fruitshorts.content.service.DramaService;
+import com.fruitshorts.content.service.EpisodeService;
+import com.fruitshorts.content.vo.EpisodeSaveReqVO;
+import org.apache.ibatis.builder.MapperBuilderAssistant;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.mockito.ArgumentCaptor;
+
+import java.util.List;
+import java.util.Map;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.isNull;
+import static org.mockito.BDDMockito.given;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+
+/** K89：剧集点赞编辑、原子增减与剧级批量汇总。 */
+class EpisodeServiceK89Test {
+
+    private DramaEpisodeMapper episodeMapper;
+    private EpisodeService episodeService;
+
+    @BeforeAll
+    static void initTableInfo() {
+        TableInfoHelper.initTableInfo(
+                new MapperBuilderAssistant(new MybatisConfiguration(), ""), DramaEpisode.class);
+    }
+
+    @BeforeEach
+    void setUp() {
+        episodeMapper = mock(DramaEpisodeMapper.class);
+        episodeService = new EpisodeService(episodeMapper, mock(DramaService.class));
+    }
+
+    @Test
+    @SuppressWarnings("unchecked")
+    void should_use_greatest_zero_when_episode_like_decrements() {
+        given(episodeMapper.update(isNull(), any())).willReturn(1);
+        ArgumentCaptor<Wrapper<DramaEpisode>> captor = ArgumentCaptor.forClass(Wrapper.class);
+
+        episodeService.adjustLikeCount(11L, -1);
+
+        verify(episodeMapper).update(isNull(), captor.capture());
+        LambdaUpdateWrapper<DramaEpisode> update =
+                (LambdaUpdateWrapper<DramaEpisode>) captor.getValue();
+        assertThat(update.getSqlSet()).contains("GREATEST(like_count - 1, 0)");
+    }
+
+    @Test
+    void should_update_episode_like_count_without_overwriting_when_null() {
+        DramaEpisode episode = new DramaEpisode();
+        episode.setId(11L);
+        episode.setDramaId(5L);
+        episode.setEpNo(1);
+        episode.setLikeCount(8L);
+        given(episodeMapper.selectById(11L)).willReturn(episode);
+        EpisodeSaveReqVO req = new EpisodeSaveReqVO();
+        req.setDramaId(5L);
+        req.setNumber(1);
+        req.setLikeCount(20L);
+
+        episodeService.update(11L, req);
+
+        assertThat(episode.getLikeCount()).isEqualTo(20L);
+    }
+
+    @Test
+    void should_reject_negative_episode_like_count() {
+        DramaEpisode episode = new DramaEpisode();
+        episode.setId(11L);
+        episode.setDramaId(5L);
+        episode.setEpNo(1);
+        given(episodeMapper.selectById(11L)).willReturn(episode);
+        EpisodeSaveReqVO req = new EpisodeSaveReqVO();
+        req.setDramaId(5L);
+        req.setNumber(1);
+        req.setLikeCount(-1L);
+
+        assertThatThrownBy(() -> episodeService.update(11L, req))
+                .isInstanceOf(ServiceException.class)
+                .satisfies(error -> assertThat(((ServiceException) error).getCode())
+                        .isEqualTo(ErrorCode.BAD_REQUEST.getCode()));
+        verify(episodeMapper, never()).updateById(any(DramaEpisode.class));
+    }
+
+    @Test
+    void should_sum_episode_likes_by_drama() {
+        given(episodeMapper.selectMaps(any())).willReturn(List.of(
+                Map.of("drama_id", 5L, "like_count", 120L),
+                Map.of("drama_id", 6L, "like_count", 30L)));
+
+        Map<Long, Long> sums = episodeService.sumLikeCountsByDramas(List.of(5L, 6L));
+
+        assertThat(sums).containsEntry(5L, 120L).containsEntry(6L, 30L);
+    }
+}

fruitshorts-app-api/src/test/java/com/fruitshorts/interaction/service/LikeServiceEpisodeTest.java

@@ -0,0 +1,112 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.interaction.service;
+
+import com.baomidou.mybatisplus.core.MybatisConfiguration;
+import com.baomidou.mybatisplus.core.metadata.TableInfoHelper;
+import com.fruitshorts.common.exception.ErrorCode;
+import com.fruitshorts.common.exception.ServiceException;
+import com.fruitshorts.content.dal.entity.Drama;
+import com.fruitshorts.content.dal.entity.DramaEpisode;
+import com.fruitshorts.content.service.DramaService;
+import com.fruitshorts.content.service.EpisodeService;
+import com.fruitshorts.interaction.dal.entity.ContentLike;
+import com.fruitshorts.interaction.dal.mapper.ContentCommentMapper;
+import com.fruitshorts.interaction.dal.mapper.ContentLikeMapper;
+import com.fruitshorts.interaction.vo.LikeToggleReqVO;
+import com.fruitshorts.interaction.vo.LikeToggleRespVO;
+import org.apache.ibatis.builder.MapperBuilderAssistant;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.BDDMockito.given;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+
+/** K89：点赞目标支持已上线的分集。 */
+class LikeServiceEpisodeTest {
+
+    private ContentLikeMapper likeMapper;
+    private EpisodeService episodeService;
+    private DramaService dramaService;
+    private LikeService likeService;
+
+    @BeforeAll
+    static void initTableInfo() {
+        TableInfoHelper.initTableInfo(
+                new MapperBuilderAssistant(new MybatisConfiguration(), ""), ContentLike.class);
+    }
+
+    @BeforeEach
+    void setUp() {
+        likeMapper = mock(ContentLikeMapper.class);
+        episodeService = mock(EpisodeService.class);
+        dramaService = mock(DramaService.class);
+        likeService = new LikeService(
+                likeMapper,
+                mock(ContentCommentMapper.class),
+                dramaService,
+                episodeService);
+    }
+
+    @Test
+    void should_increment_episode_like_and_return_latest_count() {
+        DramaEpisode published = episode(6L);
+        given(episodeService.getPublished(11L)).willReturn(published);
+        given(dramaService.getPublished(5L)).willReturn(new Drama());
+        given(likeMapper.selectOne(any())).willReturn(null);
+        given(episodeService.getExisting(11L)).willReturn(published);
+
+        LikeToggleRespVO result = likeService.toggle(9L, request(11L));
+
+        assertThat(result.getLiked()).isTrue();
+        assertThat(result.getCount()).isEqualTo(6L);
+        verify(episodeService).adjustLikeCount(11L, 1);
+    }
+
+    @Test
+    void should_decrement_episode_like_when_cancelled() {
+        DramaEpisode published = episode(5L);
+        given(episodeService.getPublished(11L)).willReturn(published);
+        given(dramaService.getPublished(5L)).willReturn(new Drama());
+        given(likeMapper.selectOne(any())).willReturn(new ContentLike());
+        given(episodeService.getExisting(11L)).willReturn(published);
+
+        LikeToggleRespVO result = likeService.toggle(9L, request(11L));
+
+        assertThat(result.getLiked()).isFalse();
+        assertThat(result.getCount()).isEqualTo(5L);
+        verify(likeMapper).physicalDelete(9L, LikeService.TYPE_EPISODE, 11L);
+        verify(episodeService).adjustLikeCount(11L, -1);
+    }
+
+    @Test
+    void should_reject_missing_or_unpublished_episode() {
+        given(episodeService.getPublished(11L))
+                .willThrow(new ServiceException(ErrorCode.DATA_NOT_FOUND, "剧集不存在或未上线"));
+
+        assertThatThrownBy(() -> likeService.toggle(9L, request(11L)))
+                .isInstanceOf(ServiceException.class);
+        verify(likeMapper, never()).insert(any(ContentLike.class));
+    }
+
+    private DramaEpisode episode(Long likeCount) {
+        DramaEpisode episode = new DramaEpisode();
+        episode.setId(11L);
+        episode.setDramaId(5L);
+        episode.setLikeCount(likeCount);
+        return episode;
+    }
+
+    private LikeToggleReqVO request(Long episodeId) {
+        LikeToggleReqVO req = new LikeToggleReqVO();
+        req.setTargetType(LikeService.TYPE_EPISODE);
+        req.setTargetId(episodeId);
+        return req;
+    }
+}

fruitshorts-app-api/src/test/java/com/fruitshorts/playback/service/FavoriteServiceTest.java

@@ -0,0 +1,80 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.playback.service;
+
+import com.fruitshorts.content.service.DramaService;
+import com.fruitshorts.playback.dal.entity.UserFavorite;
+import com.fruitshorts.playback.dal.mapper.UserFavoriteMapper;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import java.util.Arrays;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.BDDMockito.given;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+
+/** 收藏关系变化时同步维护短剧收藏数。 */
+class FavoriteServiceTest {
+
+    private UserFavoriteMapper favoriteMapper;
+    private DramaService dramaService;
+    private FavoriteService favoriteService;
+
+    @BeforeEach
+    void setUp() {
+        favoriteMapper = mock(UserFavoriteMapper.class);
+        dramaService = mock(DramaService.class);
+        favoriteService = new FavoriteService(favoriteMapper, dramaService);
+    }
+
+    @Test
+    void should_increment_favorite_count_when_new_favorite_is_created() {
+        given(favoriteMapper.selectOne(any())).willReturn(null);
+        given(favoriteMapper.insert(any(UserFavorite.class))).willReturn(1);
+
+        boolean favorite = favoriteService.toggle(1L, 7L);
+
+        assertThat(favorite).isTrue();
+        verify(dramaService).adjustFavoriteCount(7L, 1);
+    }
+
+    @Test
+    void should_decrement_favorite_count_when_toggle_removes_relation() {
+        given(favoriteMapper.selectOne(any())).willReturn(new UserFavorite());
+        given(favoriteMapper.physicalDelete(1L, 7L)).willReturn(1);
+
+        boolean favorite = favoriteService.toggle(1L, 7L);
+
+        assertThat(favorite).isFalse();
+        verify(dramaService).adjustFavoriteCount(7L, -1);
+    }
+
+    @Test
+    void should_only_decrement_when_remove_actually_deletes_relation() {
+        given(favoriteMapper.physicalDelete(1L, 7L)).willReturn(1);
+        given(favoriteMapper.physicalDelete(1L, 8L)).willReturn(0);
+
+        favoriteService.remove(1L, 7L);
+        favoriteService.remove(1L, 8L);
+
+        verify(dramaService).adjustFavoriteCount(7L, -1);
+        verify(dramaService, never()).adjustFavoriteCount(8L, -1);
+    }
+
+    @Test
+    void should_decrement_each_deleted_drama_when_batch_remove_is_called() {
+        given(favoriteMapper.physicalDelete(1L, 7L)).willReturn(1);
+        given(favoriteMapper.physicalDelete(1L, 8L)).willReturn(0);
+        given(favoriteMapper.physicalDelete(1L, 9L)).willReturn(1);
+
+        favoriteService.removeBatch(1L, Arrays.asList(7L, 8L, 9L, null));
+
+        verify(dramaService).adjustFavoriteCount(7L, -1);
+        verify(dramaService, never()).adjustFavoriteCount(8L, -1);
+        verify(dramaService).adjustFavoriteCount(9L, -1);
+    }
+}

fruitshorts-framework/pom.xml

@@ -66,5 +66,19 @@
             <groupId>org.springdoc</groupId>
             <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
         </dependency>
+
+        <!-- 监控：暴露 actuator 指标供 Prometheus 抓取 -->
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-actuator</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.micrometer</groupId>
+            <artifactId>micrometer-registry-prometheus</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-data-redis</artifactId>
+        </dependency>
     </dependencies>
 </project>