Merge branch 'develop' of https://git.reelshort2.com:80/jianghaifeng/FruitServer into develop

- JwtProperties.adminSecret/appSecret 默认值从 dev 密钥改为空字符串
- MediaProperties.signatureSecret 默认值从 dev 密钥改为空字符串
- app-api/admin-api application.yml 三处密钥回退值均改为空
- docker-compose.yml CORS_ALLOWED_ORIGINS 追加 ymb-site 3007 端口白名单
- .gitignore 追加 *.secrets.env / SSL 证书 / nginx 部署目录忽略规则

.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=

.gitea/workflows/ci.yml

@@ -0,0 +1,25 @@
+# Author: fruit.com.cn
+# FruitServer 后端 CI：编译 + 测试门禁
+name: backend-ci
+
+on:
+  push:
+    branches: [develop, main]
+  pull_request:
+    branches: [develop, main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: "21"
+          cache: maven
+      - name: 编译 + 单测
+        run: mvn -B -T 1C test -DfailIfNoTests=false
+      - name: 打包（跳过测试）
+        if: success()
+        run: mvn -B package -DskipTests -q

.gitignore

@@ -19,3 +19,19 @@ data/uploads/*
 
 # 部署用的真实环境变量（含密钥），只提交 .env.example
 .env
+*.secrets.env
+dump.rdb
+
+# 看门狗飞书告警 Webhook，只存在于部署机
+deploy/feishu-webhook.txt
+
+# SSL 证书与私钥（.crt/.cer/.pem/.key/.p12/.jks）—— 部署机本地文件，禁止入库
+*.crt
+*.cer
+*.pem
+*.key
+*.p12
+*.jks
+
+# 部署用 nginx 配置目录（挂载卷的本地配置，随环境而异）
+nginx/

Dockerfile

@@ -15,6 +15,20 @@
 FROM maven:3.9-eclipse-temurin-21 AS build
 WORKDIR /build
 
+# Maven Central 在国内网络下拉依赖不稳定（构建时曾出现 maven-filtering:3.3.1 解析失败），
+# 构建阶段固定走阿里云 central 镜像；其它仓库仍直连。
+RUN mkdir -p /root/.m2 \
+    && printf '%s\n' \
+       '<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0">' \
+       '  <mirrors>' \
+       '    <mirror>' \
+       '      <id>aliyun-central</id>' \
+       '      <mirrorOf>central</mirrorOf>' \
+       '      <url>https://maven.aliyun.com/repository/central</url>' \
+       '    </mirror>' \
+       '  </mirrors>' \
+       '</settings>' > /root/.m2/settings.xml
+
 # 先只拷各模块 pom 再拉依赖：依赖层可复用，改业务代码不会重新下载依赖
 COPY pom.xml .
 COPY fruitshorts-common/pom.xml fruitshorts-common/
@@ -30,7 +44,7 @@ COPY fruitshorts-module-creator/pom.xml fruitshorts-module-creator/
 COPY fruitshorts-admin-api/pom.xml fruitshorts-admin-api/
 COPY fruitshorts-app-api/pom.xml fruitshorts-app-api/
 COPY fruitshorts-transcode-worker/pom.xml fruitshorts-transcode-worker/
-RUN mvn -B -q -DskipTests dependency:go-offline || true
+RUN mvn -B -q -DskipTests dependency:go-offline
 
 COPY . .
 ARG MODULE=fruitshorts-app-api

README.md

@@ -191,7 +191,7 @@ java -jar fruitshorts-app-api/target/fruitshorts-app-api-1.0.0-SNAPSHOT.jar
 
 ## 第一阶段实现进度
 
-> 最后更新：2026-10-16（后端 `develop` 分支 `4418a84`）。**未完成清单见文末「尚未完成」。**
+> 最后更新：2026-10-24（拉取 `develop` 最新代码后）。**未完成清单见文末「尚未完成」。**
 
 | 模块 | 状态 | 说明 |
 | --- | --- | --- |
@@ -200,11 +200,11 @@ java -jar fruitshorts-app-api/target/fruitshorts-app-api-1.0.0-SNAPSHOT.jar
 | 03 内容发现与详情 | 已实现 | 首页/发现/分类/详情；内容分级、可播区域、版权窗口、标签字段 |
 | 04 播放器与播放控制 | 已实现 | 播放票据 + 签名地址 + 进度；多码率 HLS 由转码 worker 产出（见 10） |
 | 05 记录、收藏与下载 | 已实现 | 进度、观看流水、收藏、离线下载授权与任务 |
-| 06 评论、点赞与分享 | 已实现 | 评论（游标翻页/审核/删除）、点赞、举报、敏感词；**分享埋点待 C3** |
+| 06 评论、点赞与分享 | 已实现 | 评论（游标翻页/审核/删除）、点赞、举报、敏感词、分享 |
 | 07 创作者中心 | 已实现 | **在后台管理（Web 端 `ReelShortWeb`）**：工作台、内容编辑、分片上传与断点续传、提交审核与上下架、分集收费与试看、数据看板；不含提现/结算。**App 客户端不提供创作者中心**（口径 2026-10-16） |
 | 08 平台运营后台 | 已实现 | 用户管理、内容治理、订单与权益、创作者与内容审核、数据看板 + 四个后台页面 |
 | 09 分集收费与支付 | 部分 | **Google Play 票据校验闭环已实现**（校验→建单→发权益、幂等与防重放、恢复购买、退款拒付回收、对账）；**Apple IAP 只留端口未实现**（印尼 iOS 占比低，文档口径为"预留"） |
-| 10 质量、数据与上线 | 部分 | **转码 worker（C1）已实现**；**Redis 缓存与限流（C2）、埋点（C3）、压测未做** |
+| 10 质量、数据与上线 | 部分 | **转码 worker（C1）、Redis 缓存与限流（C2）、埋点（C3）均已实现**；**压测未做** |
 
 ### 已完成批次（按提交顺序）
 
@@ -426,18 +426,18 @@ public Result<Long> create(@Valid @RequestBody DramaCategorySaveReqVO req) { ...
 
 ## 尚未完成
 
-> 最后更新：2026-10-16。完成后请同步本表与 [docs/api-phase1.md](docs/api-phase1.md)。
+> 最后更新：2026-10-24。完成后请同步本表与 [docs/api-phase1.md](docs/api-phase1.md)。
 
 ### 一、后端研发（剩余）
 
+> 已完成的项（不再列出）：**C2 Redis 缓存与限流**（`framework/redis` 的 `RedisService` + `RateLimit` 切面）、**C3 埋点**（客户端埋点 SDK），均于 10-20 ~ 10-23 落地。
+
 | # | 项 | 内容 | 依据 |
 | --- | --- | --- | --- |
-| 1 | **C2 Redis 缓存与限流** | 首页/发现/分类等热点接口缓存（Cache-Aside）+ 验证码/注册/登录限流；生产 Redis 规格 `4C16G 主从 2~3 哨兵` | 任务清单 C2、`17-风险评估` R-10、`10-安全方案` §三 |
+| 1 | **Apple IAP 票据校验** | 目前只留端口与枚举，未做真实校验（印尼 iOS 占比低，文档口径为"预留"） | `api-phase1` §1.8 |
-| 2 | **C3 埋点** | 播放/支付/转化事件 + 数据字典对齐（含 06 的分享埋点） | 任务清单 C3、`api-phase1` §3 |
+| 2 | **压测** | 目标 `P95 < 50ms`（预热后）；容量口径文档里有两套（"1 万并发"与"2 万并发 + 3000 QPS"），需定稿 | `09-测试计划` §五、`13/14-容量` |
-| 3 | **Apple IAP 票据校验** | 目前只留端口与枚举，未做真实校验（印尼 iOS 占比低，文档口径为"预留"） | `api-phase1` §1.8 |
+| 3 | **对账数据源** | 结算金额/手续费/税只能从 Play Console 财务报告取（需报表权限）；当前 `storeAmountSum` 恒为 `null` + `notes` 说明 | B1-2 待确认 |
-| 4 | **压测** | 目标 `P95 < 50ms`（预热后）；容量口径文档里有两套（"1 万并发"与"2 万并发 + 3000 QPS"），需定稿 | `09-测试计划` §五、`13/14-容量` |
+| 4 | **退款口径完善** | 部分退款按比例回收、退款实时性（当前由每日对账 + 手动驱动，未接 RTDN 推送） | B1-2 待确认 |
-| 5 | **对账数据源** | 结算金额/手续费/税只能从 Play Console 财务报告取（需报表权限）；当前 `storeAmountSum` 恒为 `null` + `notes` 说明 | B1-2 待确认 |
-| 6 | **退款口径完善** | 部分退款按比例回收、退款实时性（当前由每日对账 + 手动驱动，未接 RTDN 推送） | B1-2 待确认 |
 
 ### 二、上线前必补（P0 / Go-No-Go：非研发，但阻塞上线）
 

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

deploy/backend-watchdog-task.xml

@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="UTF-16"?>
+<Task version="1.3" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+  <RegistrationInfo>
+    <Description>FruitShorts backend watchdog: health check every 2 minutes and restart unhealthy services.</Description>
+  </RegistrationInfo>
+  <Principals>
+    <Principal id="Author">
+      <UserId>S-1-5-18</UserId>
+      <RunLevel>HighestAvailable</RunLevel>
+    </Principal>
+  </Principals>
+  <Settings>
+    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
+    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
+    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
+    <StartWhenAvailable>true</StartWhenAvailable>
+    <ExecutionTimeLimit>PT10M</ExecutionTimeLimit>
+  </Settings>
+  <Triggers>
+    <!-- BootTrigger 上挂 <Repetition> 在 Windows 计划任务里不生效（导入后 Next Run Time 为 N/A，
+         实际只在开机跑一次）。改成 TimeTrigger + 无限重复，配合 StartWhenAvailable
+         保证开机后若错过也会立即补跑；这样才真正做到每 2 分钟巡检一次。 -->
+    <TimeTrigger>
+      <StartBoundary>2026-01-01T00:00:00</StartBoundary>
+      <Repetition>
+        <Interval>PT2M</Interval>
+        <Duration>P3650D</Duration>
+        <StopAtDurationEnd>false</StopAtDurationEnd>
+      </Repetition>
+    </TimeTrigger>
+  </Triggers>
+  <Actions Context="Author">
+    <Exec>
+      <Command>powershell.exe</Command>
+      <Arguments>-NoProfile -ExecutionPolicy Bypass -File "C:\Users\Administrator\Desktop\ReelShorts\FruitServer\deploy\watchdog.ps1" -ComposeDir "C:\Users\Administrator\Desktop\ReelShorts\FruitServer" -LogDir "C:\Users\Administrator\Desktop\ReelShorts\FruitServer\logs"</Arguments>
+    </Exec>
+  </Actions>
+</Task>

deploy/watchdog.ps1

@@ -0,0 +1,232 @@
+# Author: fruit.com.cn
+#
+# 服务看门狗：每 2 分钟检查一次，挂了自动拉起，连续失败发飞书告警。
+# 注册为 Windows 计划任务后无人值守运行。
+
+param(
+    [string]$ComposeDir = "C:\FruitServer",
+    [string]$LogDir = "C:\FruitServer\logs",
+    [string]$FeishuWebhook = "",
+    [int]$MaxRestarts = 3,
+    [string]$FrontendTask = "FruitShorts-Web-3005"
+)
+
+$ErrorActionPreference = "Continue"
+$ComposeFile = Join-Path $ComposeDir "docker-compose.yml"
+$LogFile = Join-Path $LogDir "watchdog-$(Get-Date -Format 'yyyy-MM-dd').log"
+# 连续失败计数落盘文件：计划任务每 2 分钟起一个新进程，计数只放进程内永远累积不到
+# $MaxRestarts，告警会静默哑火。
+$StateFile = Join-Path $LogDir "watchdog-state.json"
+
+function Write-Log($msg) {
+    $line = "$(Get-Date -Format 'yyyy-MM-dd HH:mm:ss') $msg"
+    Add-Content -Path $LogFile -Value $line -ErrorAction SilentlyContinue
+}
+
+function Send-Alert($title, $msg) {
+    if (-not $FeishuWebhook) { return }
+    $json = @{
+        msg_type = "text"
+        content  = @{ text = "[$title] $msg" }
+    } | ConvertTo-Json -Depth 3
+    try {
+        # PS5 的 Invoke-RestMethod 对字符串 body 默认按 Latin-1 编码，中文会变成 ???，
+        # 必须手动转 UTF-8 字节数组发送
+        $bytes = [System.Text.Encoding]::UTF8.GetBytes($json)
+        Invoke-RestMethod -Uri $FeishuWebhook -Method Post -Body $bytes -ContentType "application/json; charset=utf-8" -TimeoutSec 10
+    } catch {
+        Write-Log "飞书告警发送失败: $_"
+    }
+}
+
+# 连续失败计数的读写：JSON 落盘，跨进程保留
+function Import-FailCounts {
+    $counts = @{}
+    if (-not (Test-Path $StateFile)) { return $counts }
+    try {
+        $saved = Get-Content -Path $StateFile -Raw | ConvertFrom-Json
+        foreach ($prop in $saved.PSObject.Properties) {
+            $counts[$prop.Name] = [int]$prop.Value
+        }
+    } catch {
+        Write-Log "看门狗计数文件解析失败，各服务按 0 重新计数: $_"
+    }
+    return $counts
+}
+
+function Export-FailCounts($counts) {
+    try {
+        $counts | ConvertTo-Json | Set-Content -Path $StateFile -Encoding UTF8
+    } catch {
+        Write-Log "看门狗计数文件写入失败: $_"
+    }
+}
+
+function Test-Docker {
+    docker info --format "{{.ServerVersion}}" 2>$null | Out-Null
+    return ($LASTEXITCODE -eq 0)
+}
+
+function Test-Http([string]$url) {
+    try {
+        $response = Invoke-WebRequest -Uri $url -TimeoutSec 10 -UseBasicParsing -ErrorAction Stop
+        return ($response.StatusCode -ge 200 -and $response.StatusCode -lt 400)
+    } catch {
+        return $false
+    }
+}
+
+function Test-Container([string]$container) {
+    $status = docker inspect -f "{{.State.Status}}" $container 2>$null
+    return ($status -eq "running")
+}
+
+function Invoke-Compose([string[]]$composeArgs) {
+    & docker compose -f $ComposeFile @composeArgs 2>&1 | Out-Null
+    return $LASTEXITCODE
+}
+
+# 确保日志目录存在
+New-Item -ItemType Directory -Force -Path $LogDir | Out-Null
+
+# 告警 Webhook：命令行参数 > 环境变量 > deploy 目录下的 feishu-webhook.txt。
+# 计划任务注册命令里不写密钥（密钥不该进版本库），由部署机本地放文件或配环境变量。
+if (-not $FeishuWebhook) { $FeishuWebhook = $env:FRUITSHORTS_FEISHU_WEBHOOK }
+if (-not $FeishuWebhook) {
+    $webhookFile = Join-Path $PSScriptRoot "feishu-webhook.txt"
+    if (Test-Path $webhookFile) {
+        $FeishuWebhook = (Get-Content -Path $webhookFile -Raw -ErrorAction SilentlyContinue)
+        if ($FeishuWebhook) { $FeishuWebhook = $FeishuWebhook.Trim() }
+    }
+}
+if (-not $FeishuWebhook) {
+    Write-Log "未配置飞书 Webhook（参数/环境变量/feishu-webhook.txt 均为空），告警只写本地日志"
+}
+
+# Docker Desktop 登录后偶尔尚未就绪，先等待并尝试拉起。
+# 注意：本脚本以 SYSTEM 身份运行，绝不能直接 Start-Process Docker Desktop.exe。
+# WSL 不支持本地系统账户运行（WSL_E_LOCAL_SYSTEM_NOT_SUPPORTED），
+# 以 SYSTEM 启动会把 docker-desktop 发行版搞成僵死状态（VHD 已挂载无法终止），
+# 结果是登录用户会话里的 Docker Desktop 也永远起不来。
+# 因此改为触发以登录用户身份运行的 FruitShorts-DockerDesktop 计划任务。
+if (-not (Test-Docker)) {
+    Write-Log "Docker 未就绪，尝试通过用户会话启动 Docker Desktop"
+    $desktopTask = "FruitShorts-DockerDesktop"
+    try {
+        # Docker Desktop.exe 是任务进程树的一部分，GUI 活着时任务一直是 Running，
+        # 直接 Start-ScheduledTask 会被 IgnoreNew 忽略，所以先结束旧实例再拉起。
+        $t = Get-ScheduledTask -TaskName $desktopTask -ErrorAction Stop
+        if ($t.State -eq "Running") {
+            Stop-ScheduledTask -TaskName $desktopTask -ErrorAction SilentlyContinue
+            Start-Sleep -Seconds 5
+        }
+        Start-ScheduledTask -TaskName $desktopTask -ErrorAction Stop
+    } catch {
+        Write-Log "触发 Docker Desktop 启动任务失败: $_"
+    }
+
+    for ($i = 0; $i -lt 18; $i++) {
+        Start-Sleep -Seconds 5
+        if (Test-Docker) { break }
+    }
+}
+
+if (-not (Test-Docker)) {
+    Write-Log "Docker 在 90 秒内未就绪，跳过本轮检查"
+    Send-Alert "服务异常" "Docker Desktop 无法启动，请人工检查桌面机。"
+    exit 1
+}
+
+# 健康检查定义：名称 → 检查方式
+$checks = @(
+    @{ Name = "app-api";    Type = "http";     Url = "http://127.0.0.1:8081/healthz"; Service = "app-api"; Container = "fruitshorts-app-api" },
+    @{ Name = "admin-api";  Type = "http";     Url = "http://127.0.0.1:8080/healthz"; Service = "admin-api"; Container = "fruitshorts-admin-api" },
+    @{ Name = "frontend";   Type = "frontend"; Url = "http://127.0.0.1:3005/dist-dev/" },
+    @{ Name = "Grafana";    Type = "http";     Url = "http://127.0.0.1:3000/api/health"; Service = "grafana"; Container = "fruitshorts-grafana" },
+    @{ Name = "PostgreSQL"; Type = "docker";   Service = "db"; Container = "fruitshorts-db" },
+    @{ Name = "Redis";      Type = "docker";   Service = "redis"; Container = "fruitshorts-redis" },
+    @{ Name = "Prometheus"; Type = "http";     Url = "http://127.0.0.1:9090/-/healthy"; Service = "prometheus"; Container = "fruitshorts-prometheus" }
+)
+
+# 跟踪每个服务的连续失败次数（跨进程从状态文件恢复）
+$failCounts = Import-FailCounts
+
+foreach ($check in $checks) {
+    $name = $check.Name
+    $healthy = $false
+
+    if ($check.Type -eq "http") {
+        $healthy = Test-Http $check.Url
+    } elseif ($check.Type -eq "frontend") {
+        $healthy = Test-Http $check.Url
+    } else {
+        $healthy = Test-Container $check.Container
+    }
+
+    if ($healthy) {
+        if ($failCounts[$name] -gt 0) {
+            Write-Log "$name 恢复正常（此前连续失败 $($failCounts[$name]) 次）"
+            Send-Alert "服务恢复" "$name 已恢复正常"
+        }
+        $failCounts[$name] = 0
+    } else {
+        if ($null -eq $failCounts[$name]) {
+            $failCounts[$name] = 0
+        }
+        $failCounts[$name] = $failCounts[$name] + 1
+        $count = $failCounts[$name]
+        Write-Log "$name 不健康（第 $count 次）"
+
+        if ($check.Type -eq "frontend") {
+            Write-Log "$name 重启计划任务 $FrontendTask"
+            Stop-ScheduledTask -TaskName $FrontendTask -ErrorAction SilentlyContinue
+            Start-Sleep -Seconds 2
+            Start-ScheduledTask -TaskName $FrontendTask -ErrorAction SilentlyContinue
+            Start-Sleep -Seconds 6
+            $healthy = Test-Http $check.Url
+        } elseif ($check.Type -eq "http") {
+            Write-Log "$name 重启 Compose 服务 $($check.Service)"
+            Invoke-Compose @("restart", $check.Service) | Out-Null
+            Start-Sleep -Seconds 12
+            $healthy = Test-Http $check.Url
+
+            if (-not $healthy) {
+                Write-Log "$name 重启后仍不健康，执行 compose up -d"
+                Invoke-Compose @("up", "-d", $check.Service) | Out-Null
+            }
+        } else {
+            Write-Log "$name 拉起容器 $($check.Container)"
+            docker start $check.Container 2>&1 | Out-Null
+            Start-Sleep -Seconds 5
+            $healthy = Test-Container $check.Container
+
+            if (-not $healthy) {
+                Write-Log "$name 启动失败，执行 compose up -d"
+                Invoke-Compose @("up", "-d", $check.Service) | Out-Null
+            }
+        }
+
+        # 连续失败达到上限 → 告警。计数会跨进程累积，所以只在首次达阈值和
+        # 之后每 30 轮（约 1 小时）提醒一次，避免每 2 分钟刷屏。
+        if (-not $healthy -and $count -ge $MaxRestarts -and
+                ($count -eq $MaxRestarts -or $count % 30 -eq 0)) {
+            Send-Alert "服务异常" "$name 已连续 $count 次不健康，已尝试重启。请人工介入检查。"
+            Write-Log "$name 连续 $count 次失败，已发告警"
+        } elseif ($healthy) {
+            Write-Log "$name 已自动恢复"
+        }
+    }
+}
+
+# 磁盘检查：超过 85% 告警
+$drive = (Get-PSDrive C -ErrorAction SilentlyContinue)
+if ($drive) {
+    $pct = [math]::Round(($drive.Used / ($drive.Used + $drive.Free)) * 100)
+    if ($pct -gt 85) {
+        Write-Log "磁盘使用率 ${pct}%（超过 85%）"
+        Send-Alert "磁盘告警" "C 盘使用率 ${pct}%，请清理日志或扩容"
+    }
+}
+
+# 本轮结果落盘，供下一轮（2 分钟后的新进程）继续累加
+Export-FailCounts $failCounts

docker-compose.yml

@@ -71,8 +71,16 @@ services:
     env_file: .env
     environment:
       SERVER_PORT: "8081"
-      # 默认连编排里的 db；要连外部库就在 .env 里覆盖 DB_URL
+      # 默认连编排里的 db；要连外部库就在 .env 里覆盖 DB_URL。
-      DB_URL: ${DB_URL:-jdbc:postgresql://db:5432/${DB_NAME:-fruitshorts}}
+      # reWriteBatchedInserts=true：pgjdbc 把 JDBC 批内多条 INSERT 重写成多值
+      # INSERT，观看进度缓冲落库（watch:pg:dirty 消费任务）依赖它跑满吞吐。
+      DB_URL: ${DB_URL:-jdbc:postgresql://db:5432/${DB_NAME:-fruitshorts}?reWriteBatchedInserts=true}
+      # 限流/缓存用 Redis；容器内 127.0.0.1 是容器自身，必须指向编排里的 redis
+      REDIS_HOST: ${REDIS_HOST:-redis}
+      REDIS_PORT: ${REDIS_PORT:-6379}
+      # CORS：公网入口 nginx 把 SSL 跑在 80 端口上（腾讯云安全组只放 80），
+      # 浏览器 fetch 带 Origin 时端口不匹配会被 Spring CORS 拒（必须精确字符串匹配）。
+      CORS_ALLOWED_ORIGINS: "https://api.frostgiant.vip:80,https://api.frostgiant.vip,http://api.frostgiant.vip,https://39.162.50.99:8081,http://localhost:3005,http://127.0.0.1:3005,http://39.162.50.99:3007,http://192.168.31.250:3007"
     ports:
       - "8081:8081"
     volumes:
@@ -81,6 +89,8 @@ services:
     depends_on:
       db:
         condition: service_healthy
+      redis:
+        condition: service_healthy
     healthcheck:
       test: ["CMD-SHELL", "curl -fsS http://127.0.0.1:8081/healthz || exit 1"]
       interval: 30s
@@ -99,10 +109,19 @@ services:
     env_file: .env
     environment:
       SERVER_PORT: "8080"
+      SPRING_SERVLET_MULTIPART_MAX_FILE_SIZE: "2GB"
+      SPRING_SERVLET_MULTIPART_MAX_REQUEST_SIZE: "2GB"
+      # 浏览后台时 Origin 是实际访问地址，必须精确列全：本机、局域网、公网 IP、域名。
+      CORS_ALLOWED_ORIGINS: "http://localhost:3005,http://127.0.0.1:3005,http://39.162.50.99:3005,http://192.168.31.250:3005,https://api.frostgiant.vip,https://admin.frostgiant.vip"
       DB_URL: ${DB_URL:-jdbc:postgresql://db:5432/${DB_NAME:-fruitshorts}}
+      # 管理端仅内网，页面上直接播放/下载裸媒资地址（不签播放签名），
+      # 因此这里不启用 /files/episode/** 的签名校验；公开的 app-api 仍保持开启。
+      FRUITSHORTS_MEDIA_PROTECTED_PREFIXES: ""
+      REDIS_HOST: ${REDIS_HOST:-redis}
+      REDIS_PORT: ${REDIS_PORT:-6379}
     ports:
-      # docs/12-上线检查清单「管理端仅内网」：只绑本机，公网不直接暴露
+      # docs/12-上线检查清单「管理端仅内网」：只对局域网开放；不在路由器做端口转发，公网访问不到
-      - "127.0.0.1:8080:8080"
+      - "8080:8080"
     volumes:
       - ./data/uploads:/data/uploads
     depends_on:
@@ -128,12 +147,16 @@ services:
     env_file: .env
     environment:
       DB_URL: ${DB_URL:-jdbc:postgresql://db:5432/${DB_NAME:-fruitshorts}}
+      REDIS_HOST: ${REDIS_HOST:-redis}
+      REDIS_PORT: ${REDIS_PORT:-6379}
     volumes:
       # 与两个入口同一个媒资根，否则找不到源文件
       - ./data/uploads:/data/uploads
     depends_on:
       db:
         condition: service_healthy
+      redis:
+        condition: service_healthy
     healthcheck:
       # worker 不监听端口（server.port=0），用进程存活判断
       test: ["CMD-SHELL", "pgrep -f app.jar >/dev/null || exit 1"]
@@ -142,7 +165,103 @@ 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"
+      # 新用户默认界面语言：简体中文
+      GF_USERS_LANGUAGE: "zh-Hans"
+      TZ: Asia/Shanghai
+    depends_on:
+      - prometheus
+      - loki
+
+  # ─────────── 日志（Loki + Promtail）───────────
+  # Loki：日志存储与查询引擎；Promtail：采集容器 stdout/stderr 推给 Loki。
+  # Grafana 里通过 Loki 数据源可直接搜索/过滤各容器的请求日志。
+  loki:
+    image: grafana/loki:latest
+    container_name: fruitshorts-loki
+    restart: unless-stopped
+    command: -config.file=/etc/loki/local-config.yaml
+    volumes:
+      - ./loki-config.yml:/etc/loki/local-config.yaml:ro
+      - loki-data:/loki
+    expose:
+      - "3100"
+    # 镜像为 distroless（无 shell/wget），无法在容器内做 HTTP 探活；
+    # 靠 restart: unless-stopped 自动拉起，Grafana 数据源状态可反映可用性。
+
+  promtail:
+    image: grafana/promtail:latest
+    container_name: fruitshorts-promtail
+    restart: unless-stopped
+    command: -config.file=/etc/promtail/config.yml
+    volumes:
+      - ./promtail-config.yml:/etc/promtail/config.yml:ro
+      # 读取容器日志需要 Docker socket
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+    depends_on:
+      - loki
+
+  # 黑盒探活：从外部探测接口可用性与耗时
+  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:
+  loki-data:

docs/api-phase1.md

@@ -115,6 +115,8 @@ POST /app/auth/register
 | 密码强度 | 8–64 位，且**同时包含字母与数字**（不强制特殊字符：低端机输入成本高，拦机器注册靠频控） |
 | 注册频控 | 同 IP / 同设备 24h 默认上限分别为 5 / 3 个，超出返回 `429`（`TOO_MANY_REQUESTS`） |
 | 邮箱验证状态 | 免码注册时 `app_user_credential.verified = 0`（保留"待验证"），**不阻塞登录**；只有**验证码登录**会把 `verified` 置 1，密码登录不改变该状态 |
+| 国家 / 语言 / 时区 / 币种 | 优先按客户端 IP（`X-Forwarded-For` / `X-Real-IP`，离线 ip2region）解析国家；内网或解析失败才用请求体 `countryCode`（ISO-2），最后兜底 `ID`。`language` / `timezone` / `currency` 随国家映射，不再写死 `id-ID` / `IDR` |
+| 登录时修正国家 | `/app/auth/login`、`/app/auth/google` 会用 IP 重新解析国家并更新 `country_code` / `region_code`（历史账号下次登录即自愈）；`language` / `timezone` / `currency` 只在仍是旧国家映射值时才同步，用户自己改过就保留 |
 
 频控口径落库在 `app_user.register_ip` / `app_user.register_device_id` 上（按 24h 计数，不新建计数表）。
 
@@ -165,16 +167,156 @@ app.register.max-per-device-per-day
 
 | 方法 | 路径 | 说明 |
 | --- | --- | --- |
-| GET | `/app/home/feed` | 首页：轮播 + 分区，卡片带 `preview` 可播预览集 |
+| GET | `/app/home/feed` | 首页：轮播 + 分区，卡片带 `preview` 可播预览集与 `language` 语种 |
 | GET | `/app/discover/feed` | 发现页分区 |
-| GET | `/app/categories` | 分类列表 |
+| GET | `/app/feed?types=ANIME,LIVE&categoryId=7&cursor=&size=20` | 推荐流；支持内容类型与分类叠加过滤，游标翻页 |
+| GET | `/app/categories` | 已启用首页分类。名称在 `locales`；另带 `code`、`layoutType`（`GRID` / `RANKING`）、`revision` |
+| GET | `/app/categories/{id}/dramas?pageIndex=&pageSize=` | 分类下已上线短剧，分页。`pageIndex` 默认 1，`pageSize` 默认 20、最大 50 |
+| GET | `/app/categories/{id}/ranking` | 推荐榜快照；只接受 `layoutType=RANKING` 的已启用分类，按后台位置返回连续排名 |
+| GET | `/app/drama-categories` | 已启用类型。`locales` 为 `{zh,en,id}` |
+| GET | `/app/tags` | 已启用标签。`locales` 为 `{zh,en,id}` |
+| POST | `/app/dramas/page` | 全部短剧分页。请求体 `pageIndex`（默认 1）、`pageSize`（默认 20、最大 50）、`categoryIds`、`classificationIds`、`tagIds`。id 用 JSON 数组，不放查询串。同一组多选为或，组与组之间为且 |
+| GET | `/app/playlists?pageIndex=&pageSize=` | 已启用剧单列表，分页。`pageIndex` 默认 1，`pageSize` 默认 10、最大 20 |
+| GET | `/app/playlists/{id}?pageIndex=&pageSize=` | 剧单详情。短剧按页返回。`pageIndex` 默认 1，`pageSize` 默认 20、最大 50。下架或不存在返回 `200002` |
 | GET | `/app/dramas/{id}` | 详情（含剧集列表，免费集带**已签名**播放地址） |
+| GET | `/app/search?keyword=&pageIndex=&pageSize=` | **匿名**。搜索已上线短剧：按标题/简介模糊匹配，分页返回卡片列表 |
+
+`POST /app/dramas/page` 请求体：
+
+```json
+{
+  "pageIndex": 1,
+  "pageSize": 20,
+  "categoryIds": ["2112443900437336065"],
+  "classificationIds": ["2112807182243336193"],
+  "tagIds": ["2113500000000000002"]
+}
+```
+
+省略的 id 数组表示这一组不筛选。`pageIndex` 小于 1 按 1，`pageSize` 小于 1 按 1，大于 50 按 50。响应仍是 `{total, list}`，卡片结构与首页一致。
+
+> 卡片（`AppDramaCardVO`）统一新增 `language` 字段（取值如 `zh-CN` / `id`），
+> 首页、发现页、分类、收藏、搜索等所有下发卡片的场景都带该字段，客户端可据此做语言筛选。
+>
+> 卡片同时下发 `likeCount` / `favoriteCount` / `commentCount`（均为 JSON 字符串）。
+> `favoriteCount` 取整部剧；`likeCount` / `commentCount` 取卡片 `preview` 当前集的
+> `drama_episode.like_count` 与 `content_comment.episode_id` 统计（排除逻辑删除与 `status = 'deleted'`）；
+> `viewCount` 热度仍取整部剧。首页、发现、分类、收藏、搜索等列表卡片结构一致。
+>
+> 卡片文案只放语言表：`titleLocales`、`synopsisLocales`、`types`、`tagLocales`。
+> `tagColor` 是标签背景色。中文取各表的 `zh`。
+>
+> `tagCode` 是标签语义码（如 `NEW_ARRIVAL`），来自 `content_tag.code`。
+> 客户端按码判断板块（推荐页「上新」横滑），`tagLocales` 只用于展示；
+> 码为空时客户端才退回按文案匹配。后台标签管理可配置该码。
+>
+> 卡片新增 `dramaType`：`ANIME` 表示漫剧，`LIVE` 表示真人剧。
+> 客户端字段仍返回主内容类型；后台多选值保存在 `drama.drama_types`，
+> App 类型筛选按逗号列整词匹配，因此 `ANIME,LIVE` 多标签剧可被任一类型命中。
+>
+> `GET /app/playlists` 与 `GET /app/playlists/{id}` 匿名可访问。列表返回 `{total, list}`。
+> 列表项与详情的名称在 `locales`，描述在 `descriptionLocales`，key 为 `zh` / `en` / `id`。
+> `name` 与 `description` 等于中文。客户端按当前语言取对应 key，没有则用 `zh`。
+> 其余字段：`id`、`dramaCount`（已上线短剧条数），
+> 列表里每条剧单的 `list` 只是短剧第 1 页、每页 10 条。短剧翻页走详情：
+> `pageIndex`、`pageSize` 会原样回在详情里，`dramaCount` 是短剧总数，`list` 是当前页卡片。
+> 只返回 `status = 1` 的剧单，排序与后台剧单排序一致，卡片顺序与后台关联顺序一致。
+> 剧单列表越界页返回空 `list`，`total` 仍是全部剧单数。详情越界页同样返回空 `list`。
+
+#### 推荐榜（`GET /app/categories/{id}/ranking`）
+
+- 分类列表中的 `layoutType=RANKING` 表示客户端必须使用榜单布局，禁止按分类名称判断。
+- 榜单内容与顺序以 `drama_classification_drama.position asc` 为准；客户端不得按播放量重新排序。
+- 已下架、未发布或不存在的短剧会被过滤，剩余项目的 `rank` 从 1 连续补齐。
+- 最多返回 50 部；`revision` 在后台保存内容或顺序后递增，供缓存与曝光埋点使用。
+- 响应 `list` 项结构为 `{rank, drama}`，其中 `drama` 沿用 `AppDramaCardVO`。
+
+```json
+{
+  "id": "2112807182243336193",
+  "code": "RECOMMEND_RANKING",
+  "locales": {"zh": "推荐榜", "en": "Top Picks", "id": "Pilihan Teratas"},
+  "revision": "8",
+  "generatedAt": "2026-11-02T10:00:00",
+  "total": 1,
+  "list": [
+    {"rank": 1, "drama": {"id": "2112807182243336194", "titleLocales": {"zh": "短剧 A"}}}
+  ]
+}
+```
+
+#### 推荐类型流（`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...",
+        "thumbnailsUrl": "/files/transcoded/88/thumbnails/thumbnails.vtt?e=1760000000&s=8a1d..."
+      }
+    ]
+  }
+}
+```
+
+详情里的互动数量：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `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` 统计 |
+| `episodes[].thumbnailsUrl` | String / null | 本集雪碧图 WebVTT 时间轴签名地址；没有 READY 产物时为 `null` |
+
+计数是只读快照：互动操作完成后客户端重新拉取详情即可刷新；`Long` 字段一律按字符串下发，
+客户端需要转成数字再展示（与 `viewCount` 相同）。
 
 ### 1.4 播放（已实现，链路已重做）
 
 | 方法 | 路径 | 鉴权 | 说明 |
 | --- | --- | --- | --- |
-| GET | `/app/episodes/{id}/play` | 可选 | 签发播放票据与签名地址 |
+| GET | `/app/episodes/{id}/play` | 免费集可选；锁定集必须登录 | 签发播放票据与签名地址 |
+| GET | `/app/episodes/{id}/stats` | 可选 | 播放页轻量计数快照，不签发地址、不写票据缓存 |
 
 ```json
 {
@@ -184,35 +326,198 @@ app.register.max-per-device-per-day
     "accessible": true,
     "accessType": "FREE",
     "playUrl": "/files/episode/202610/xxx.mp4?e=1760000000&s=9f2c...",
-    "qualities": ["AUTO"],
+    "qualities": ["AUTO", "720p", "1080p"],
+    "tracks": [
+      {"quality": "AUTO", "playUrl": "/files/transcoded/88/master.m3u8?e=1760000000&s=9f2c..."},
+      {"quality": "720p", "playUrl": "/files/transcoded/88/720p/index.m3u8?e=1760000000&s=a1b2..."}
+    ],
+    "thumbnailsUrl": "/files/transcoded/88/thumbnails/thumbnails.vtt?e=1760000000&s=8a1d...",
     "unlockCoin": 0,
-    "previewSeconds": 0
+    "previewSeconds": 0,
+    "likeCount": "45",
+    "commentCount": "8"
   }
 }
 ```
 
-`accessType` 取值：`FREE`（免费集）、`ENTITLED`（已购权益）、`COIN_REQUIRED`（需解锁，
+`accessType` 取值：`FREE`（免费集）、`ENTITLED`（已购权益）、`COIN_REQUIRED`（已登录但
-此时 `playUrl` 为空、`unlockCoin` 有值）、`NO_MEDIA`（还没上传片源或未转码完成）。
+尚未解锁，此时 `playUrl` 为空、`unlockCoin` 有值）、`NO_MEDIA`（已登录用户访问的剧集还
+没上传片源或未转码完成）。未登录请求锁定集在查询片源前直接返回 `UNAUTHORIZED`，不会
+按设备身份取票或降级为匿名播放。
 
 **判定顺序由服务端决定，客户端不得自行推断可否播放。** 签名默认 15 分钟有效；
 开启 `fruitshorts.media.signature-required` 后，`/files/episode/**` 没带有效签名会返回 403。
 
+`thumbnailsUrl` 指向 WebVTT：cue 链接为同目录相对雪碧图
+`sprite_XXX.jpg#xywh=x,y,w,h`。有 READY `media_thumbnail` 时返回签名地址，
+无产物时为 `null`；该字段不影响 `playUrl`、`qualities` 和 HLS/原文件回落。
+
+**`GET /app/episodes/{id}/stats`（播放页计数刷新）**
+
+只读返回本集点赞数、本集未删除评论数、所属剧收藏数，以及当前用户对
+本集/所属剧的互动状态。已登录时按账号读取；匿名请求时按 `X-Device-Id`
+读取设备互动状态，未带设备号时 `liked`、`favorited` 均为 `false`。
+接口不生成播放签名地址、不写 `playback_ticket` 缓存，计数变化后立即可读。
+
+```json
+{
+  "code": 0,
+  "message": "ok",
+  "data": {
+    "episodeId": "12",
+    "dramaId": "5",
+    "likeCount": "45",
+    "commentCount": "8",
+    "favoriteCount": "1800",
+    "liked": true,
+    "favorited": false
+  }
+}
+```
+
+`likeCount`、`commentCount`、`favoriteCount` 与其他计数一样按 Long 字符串下发。
+
 ### 1.5 观看记录与收藏（已实现）
 
-| 方法 | 路径 | 说明 |
+| 方法 | 路径 | 鉴权 | 说明 |
-| --- | --- | --- |
+| --- | --- | --- | --- |
-| POST | `/app/watch/progress` | 上报进度（建议每 10s 一次，切集时补一次） |
+| POST | `/app/watch/progress` | 可选登录 | 上报进度；匿名按 `X-Device-Id`，建议每 10s 一次，切集时补一次 |
-| GET | `/app/watch/progress?dramaId=` | 某剧续看位置 |
+| GET | `/app/watch/progress?dramaId=` | 可选登录 | 某剧续看位置，匿名按设备读取 |
-| GET | `/app/watch/recent?limit=20` | 最近观看 |
+| GET | `/app/watch/recent` | 可选登录 | 最近观看分页；`pageIndex` 默认 1，`pageSize` 默认 20、上限 100 |
-| DELETE | `/app/watch/progress/{dramaId}` | 删除某剧记录 |
+| DELETE | `/app/watch/progress/{dramaId}` | 可选登录 | 删除当前账号或设备的某剧记录 |
-| DELETE | `/app/watch/progress` | 清空记录 |
+| DELETE | `/app/watch/progress` | 可选登录 | 清空当前账号或设备的记录 |
-| POST | `/app/favorites/toggle` | 收藏/取消收藏，返回切换后状态 |
+| POST | `/app/favorites/toggle` | 可选登录 | 收藏/取消收藏，返回切换后状态；匿名按 `X-Device-Id` |
-| GET | `/app/favorites` | 收藏列表（卡片结构与首页一致） |
+| GET | `/app/favorites` | 可选登录 | 收藏分页；匿名按设备读取，`pageIndex` 默认 1，`pageSize` 默认 20、上限 100 |
-| DELETE | `/app/favorites/{dramaId}` | 取消收藏 |
+| DELETE | `/app/favorites/{dramaId}` | 可选登录 | 取消收藏；匿名按 `X-Device-Id` |
+| POST | `/app/favorites/remove` | 可选登录 | 批量取消收藏；匿名按 `X-Device-Id`，返回实际删除数量 |
 
 进度合并规则：同一集内只前进不后退；换集直接采纳新集；`finished` 只在接近片尾或客户端显式上报时置位。
 这样用户换设备不会看到进度倒退。
 
+收藏与观看数据的身份解析顺序统一为登录 `userId` → `X-Device-Id` → 请求参数或请求体
+`deviceId`，全部缺失时返回业务码 `200007`。匿名读取不按设备限流；上报、删除和清空等写操作
+沿用设备级限流。登录或注册成功后，同一事务会把设备收藏、观看进度和观看流水合并到账号：
+同一部剧的进度先比较集号，同集再比较播放位置，最后用更新时间兜底，只保留更靠前的一条；
+观看流水按剧集去重并保留更靠后的位置。`playCount` 只取最终保留记录，不重复累加。
+
+#### 批量取消收藏
+
+`POST /app/favorites/remove`
+
+```json
+{
+  "dramaIds": ["12", "15"],
+  "deviceId": "optional-device-id"
+}
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `dramaIds` | array&lt;Long&gt; | 是 | 待取消的短剧 ID，最多 200 条，服务端去重后删除 |
+| `deviceId` | string | 否 | 未登录且未携带 `X-Device-Id` 时的设备号兜底 |
+
+身份解析优先登录用户，其次 `X-Device-Id`，最后请求体 `deviceId`。登录用户按
+`user_id` 删除，匿名用户按 `device_id` 删除；匿名写操作沿用设备级限流。
+所有删除和剧级收藏数回退在单一事务内完成，其中任一步失败会整体回滚。
+
+响应 `data` 为实际删除的收藏关系数：
+
+```json
+{
+  "code": 0,
+  "message": "ok",
+  "data": 2
+}
+```
+
+空列表返回业务码 `400`；超过 200 条同样返回 `400`。
+
+#### 收藏分页
+
+`GET /app/favorites?pageIndex=1&pageSize=20`
+
+请求参数：
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| `pageIndex` | int | 否 | 1 | 页码，小于 1 按 1 处理 |
+| `pageSize` | int | 否 | 20 | 每页数量，上限 100，小于 1 按 1 处理 |
+
+响应 `data` 为 `PageResult<AppDramaCardVO>`：
+
+```json
+{
+  "total": "23",
+  "list": [
+    {
+      "id": "12",
+      "title": "替嫁新娘：总裁的掌心宠",
+      "cover": "/files/drama_cover/12.jpg",
+      "preview": {}
+    }
+  ]
+}
+```
+
+排序固定为收藏时间倒序 `created_at DESC`，收藏时间相同时按 `drama_id DESC`。
+仅统计和返回仍处于已上线状态的短剧。
+
+#### 最近观看分页
+
+`GET /app/watch/recent?pageIndex=1&pageSize=20`
+
+请求参数：
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| `pageIndex` | int | 否 | 1 | 页码，小于 1 按 1 处理 |
+| `pageSize` | int | 否 | 20 | 每页数量，上限 100，小于 1 按 1 处理 |
+
+分页响应 `data` 为 `PageResult<ProgressRespVO>`：
+
+```json
+{
+  "total": "18",
+  "list": [
+    {
+      "dramaId": "12",
+      "episodeId": "88",
+      "dramaTitle": "替嫁新娘：总裁的掌心宠",
+      "titleLocales": {
+        "zh": "替嫁新娘：总裁的掌心宠",
+        "en": "The Stand-in Bride: The CEO's Beloved",
+        "id": "Pengantin Pengganti: Kesayangan Presiden Direktur"
+      },
+      "dramaCover": "/files/drama_cover/12.jpg",
+      "dramaCoverLandscape": "/files/drama_cover/12-wide.jpg",
+      "episodeNumber": 6,
+      "totalEpisodes": 68,
+      "viewCount": "1800",
+      "positionMs": "80000",
+      "durationMs": "120000",
+      "finished": false,
+      "playCount": 3,
+      "updatedAt": "2026-10-22 10:00:00"
+    }
+  ]
+}
+```
+
+排序固定为 `updated_at DESC, id DESC`。每页记录通过批量 IN 查询装配短剧和分集，
+不逐条访问数据库。越界页返回空 `list` 且 `total` 保持正确。
+
+`ProgressRespVO` 展示字段：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `dramaTitle` | string / null | 短剧中文标题，旧客户端回退用 |
+| `titleLocales` | object / null | 短剧标题语言表，key 为 `zh` / `en` / `id`。客户端按当前语言取，没有对应语言时回退 `zh` |
+| `dramaCover` | string / null | 短剧竖版封面 |
+| `dramaCoverLandscape` | string / null | 短剧横版封面，供继续观看横幅等横向位使用；为空时客户端回退 `dramaCover` |
+| `episodeNumber` | int / null | 当前续看集号 `ep_no` |
+| `totalEpisodes` | int / null | 短剧总集数 |
+| `viewCount` | Long（JSON 字符串）/ null | 短剧热度，取 `drama.view_count`。`playCount` 是用户自己的播放次数 |
+
 ### 1.6 离线下载（已实现）
 
 服务端只发**授权**与**短时效地址**，分片由客户端直接向 CDN 拉取 ——
@@ -238,12 +543,22 @@ app.register.max-per-device-per-day
 
 | 方法 | 路径 | 鉴权 | 说明 |
 | --- | --- | --- | --- |
-| POST | `/app/comments` | 登录 | 发表评论/回复：过敏感词后按策略发布或转待审 |
+| POST | `/app/comments` | 可选登录 | 发表评论/回复；匿名按 `X-Device-Id`，过敏感词后按策略发布或转待审 |
 | GET | `/app/comments?dramaId=&cursor=&size=` | 匿名 | 游标翻页；不传 `rootId` 返回顶层评论，传了返回该楼层回复 |
-| DELETE | `/app/comments/{id}` | 登录 | 删除自己的评论（逻辑置为 `deleted`） |
+| GET | `/app/comments/count?dramaId=&episodeId=` | 匿名 | 传 `episodeId` 返回该集评论数；仅传 `dramaId` 返回全剧兼容汇总 |
-| POST | `/app/likes/toggle` | 登录 | 点赞/取消点赞，`targetType` 支持 `DRAMA` / `COMMENT` |
+| DELETE | `/app/comments/{id}` | 可选登录 | 删除自己的评论（匿名按设备）；逻辑置为 `deleted` |
+| POST | `/app/likes/toggle` | 可选登录 | 点赞/取消点赞，`targetType` 支持 `DRAMA` / `EPISODE` / `COMMENT`；匿名按 `X-Device-Id` |
 | POST | `/app/reports` | 登录 | 举报评论/用户/短剧；同一目标只保留一条待处理工单 |
 
+**非付费互动身份与合并**：点赞、收藏、评论的身份解析顺序为登录 `userId` →
+`X-Device-Id` → 请求体 `deviceId`。三者都没有时返回业务码 `200007`。匿名写入按设备号
+每分钟限流；评论同时做长度、空白、短时间重复内容和频率校验。登录或注册成功后，服务端
+在同一登录事务内把该设备未归属的点赞、收藏、评论、观看进度和观看流水迁移到账号；
+账号已有同内容时保留账号记录并删除设备重复记录，计数同步回退，不重复累加。
+
+匿名评论展示为「游客」，头像为空占位。解锁、金币/VIP 权益、锁定集正片票据不在本规则内，
+仍必须登录。
+
 **敏感词三档处置**：`BLOCK` 直接拒绝并返回原因、`REPLACE` 替换后放行、`REVIEW` 转人工待审。
 审核策略由 `fruitshorts.interaction.comment-audit-mode` 控制：
 `MACHINE_FIRST`（机审通过即发布，当前默认）或 `PRE_REVIEW`（全部先审后发，生产建议）。
@@ -257,12 +572,67 @@ app.register.max-per-device-per-day
 | --- | --- | --- |
 | 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`，钱包余额与流水同事务。
 
+### 1.8.1 奖励中心（已实现）
+
+奖励中心复用钱包和金币流水，首发时区固定为 `Asia/Jakarta`。任务配置、奖励金币、任务文案、动作、周期和上下线状态均由后台维护；客户端不能直接提交任务进度，观看进度由服务端在 `/app/watch/progress` 校验成功后累计。
+
+| 方法 | 路径 | 鉴权 | 说明 |
+| --- | --- | --- | --- |
+| GET | `/app/rewards/overview` | 匿名 | 返回任务配置、任务分组、签到规则和活动卡片；未登录时余额为 `0`、用户进度为 `0`、签到状态为未签到；登录后补充用户数据；`locale` 可选 `id/en/zh` |
+| GET | `/app/rewards/activities` | 匿名 | 返回当前生效活动卡片，活动一期只展示和跳转 |
+| GET | `/app/rewards/check-in` | 登录 | 返回今日是否签到、连续天数、7 天规则 |
+| POST | `/app/rewards/check-in` | 登录 | 按服务端日期和连续签到规则发放金币；同用户同日期幂等 |
+| POST | `/app/rewards/tasks/{taskId}/claim` | 登录 | 领取已完成任务；同任务同周期幂等 |
+
+总览响应核心字段：
+
+```json
+{
+  "serverDate": "2026-11-05",
+  "timezone": "Asia/Jakarta",
+  "coinBalance": "135",
+  "checkin": {
+    "taskId": "202611050001",
+    "checkedInToday": false,
+    "streak": 2,
+    "currentDay": 3,
+    "days": [{"dayIndex": 1, "rewardCoin": "35", "checked": true, "current": false}]
+  },
+  "sections": [{
+    "code": "DAILY",
+    "title": "Tugas harian",
+    "tasks": [{
+      "id": "202611050002",
+      "code": "watch_5_minutes",
+      "type": "WATCH_DURATION",
+      "progressValue": "120",
+      "targetValue": "300",
+      "rewardCoin": "20",
+      "status": "IN_PROGRESS"
+    }]
+  }],
+  "activities": []
+}
+```
+
+一期任务类型为 `DAILY_CHECK_IN`、`WATCH_DURATION`、`WATCH_EPISODES`、`COMPLETE_PROFILE`、`FIRST_PURCHASE`；`FIRST_LOGIN` 预留给登录事件接入。任务状态为 `IN_PROGRESS`、`COMPLETED`、`CLAIMED`。奖励发放使用 `coin_ledger.biz_type=REWARD`，任务领取幂等键为 `reward:{taskCode}:{userId}:{cycleKey}`，签到幂等键为 `reward:checkin:{userId}:{date}`。重复请求返回既有发放结果，不重复增加钱包余额。
+
+失败场景：任务未完成或已停用返回 `200003`；任务、签到规则不存在返回 `200002`；奖励金币为 0 或请求参数非法返回 `400`；钱包余额和发放单不一致时整笔事务回滚。
+
 **`POST /app/orders/verify`（B1-1：Google Play 票据校验闭环）**
 
 请求体：
@@ -339,6 +709,7 @@ B1-2 的退款/拒付复验依赖它。服务端凭据（`packageName` + service
 | `noticeEnabled` | `app.notice.enabled` | `true` | 公告入口开关 |
 | `coinUnlockEnabled` | `app.coin.unlock.enabled` | `true` | 金币解锁开关 |
 | `downloadEnabled` | `app.download.enabled` | `true` | 离线下载开关 |
+| `loginBackgroundUrl` | `app.login.background.url` | `""` | 登录页全屏海报背景；留空 App 用内置默认图。**建议尺寸 1170×2532**（iPhone 14 Pro Max 3× 整屏竖图），后台走 `/admin/media/upload/` 任意 bizType 上传后把返回的相对路径（`/files/login_bg/xxx.jpg`）写入即可 |
 
 **口径**：**只下发上述白名单键**（服务端硬编码白名单），后台配置里的其它键（可能含内部开关）
 **一律不下发**；库里缺键时用「契约默认值」兜底，**不返回 null 让客户端自己猜默认值**。
@@ -371,6 +742,17 @@ GET /app/notices?pageIndex=1&pageSize=20
 `expire_at` 为空或未过期的公告；按 `publish_at desc, id desc` 排序。
 **表里没有数据时返回 `total=0, list=[]`（HTTP 与 code 都是成功），不是 404。**
 
+#### 1.9.2a 协议公开页（匿名 HTML）
+
+客户端按当前界面语言打开，不走 `{code,message,data}` 包装。正文在后台「协议设置」用 Markdown 维护，页面不另加标题。
+
+| 方法 | 路径 | 说明 |
+| --- | --- | --- |
+| GET | `/privacy/{lang}` | 隐私协议。`lang` 为 `zh` / `en` / `id` |
+| GET | `/terms/{lang}` | 服务条款。语言同上 |
+
+响应 `Content-Type: text/html;charset=UTF-8`。语言或路径不在上表时 HTTP 404。库里还没有该语言时返回内置缺省文案，不返回空页。
+
 #### 1.9.3 `POST /app/creator/apply`（登录）
 
 ```json
@@ -432,6 +814,8 @@ GET /app/notices?pageIndex=1&pageSize=20
 | 角色分类 | PUT · DELETE | `/admin/role-categories/{id}` | `system:role-category` |
 | 系统配置 | GET | `/admin/configs` | `system:role` / `system:menu` |
 | 系统配置 | PUT | `/admin/configs` | `system:role` |
+| 协议 | GET | `/admin/legal-documents` | `system:role` / `system:menu` |
+| 协议 | PUT | `/admin/legal-documents` | `system:role` |
 | 操作日志 | GET | `/admin/operation-logs/page` · `/{id}` | `log:list` |
 | 字典 | GET | `/admin/dicts/drama-category` · `/content-status` | `drama:list` |
 
@@ -444,10 +828,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` | 新建短剧 |
+| POST | `/admin/dramas` | `drama:create` | 新建短剧；优先接收 `dramaTypes[]` / `categoryIds[]` |
-| PUT | `/admin/dramas/{id}` | `drama:update` | 编辑短剧 |
+| 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` | 审核通过 |
@@ -456,6 +840,25 @@ 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,%'` 整词匹配。
+- 短剧另有单选标签 `tagId`。不传保持原值，传 `0` 清空。列表返回 `tagId`、`tagName`、`tagNameEn`、`tagNameId`。后台编辑不再提交内容类型。
+
+**标签**
+
+| 方法 | 路径 | 权限点 | 说明 |
+| --- | --- | --- | --- |
+| GET | `/admin/content-tags?enabledOnly=` | `drama:list` | 标签列表。`enabledOnly=true` 只返回启用项 |
+| POST | `/admin/content-tags` | `drama:create` | 新建。`locales` 勾选语言，中文必填，英文和印尼语可选 |
+| PUT | `/admin/content-tags/{id}` | `drama:update` | 编辑 |
+| DELETE | `/admin/content-tags/{id}` | `drama:delete` | 删除，并清空已选该标签的短剧 |
+
 **剧集**
 
 | 方法 | 路径 | 权限点 | 说明 |
@@ -499,18 +902,76 @@ GET /app/notices?pageIndex=1&pageSize=20
 **上传会话归属**：`uploadId` 相当于上传凭证，`chunk` / `complete` / 进度查询都校验会话发起人，
 别人拿到 `uploadId` 也塞不进分片（`{"code":403,"message":"无权操作该上传会话"}`）。
 
+**转码档位配置**
+
+| 方法 | 路径 | 权限点 | 说明 |
+| --- | --- | --- | --- |
+| GET | `/admin/media/transcode-profile` | `episode:upload` | 读取当前配置；缺省返回四档默认值 |
+| PUT | `/admin/media/transcode-profile` | `episode:upload` | 保存配置并记录操作日志 |
+
+配置保存在 `sys_config` 的 `media.transcode.profile`，JSON 结构：
+
+```json
+{
+  "enabled": true,
+  "segmentSeconds": 6,
+  "ladder": [
+    {
+      "quality": "360p",
+      "width": 640,
+      "height": 360,
+      "videoBitrateKbps": 400,
+      "audioBitrateKbps": 64,
+      "enabled": true
+    }
+  ],
+  "sprite": {
+    "enabled": true,
+    "intervalSeconds": 1,
+    "columns": 10,
+    "thumbWidth": 160
+  }
+}
+```
+
+`quality` 必须唯一且非空，宽高必须为大于 0 的偶数，音视频码率必须大于 0，
+至少启用一档；`segmentSeconds` 2–10、`intervalSeconds` 1–10、`columns` 5–20、
+`thumbWidth` 120–240。非法请求返回统一错误码 `400` 且不写库。
+
 ### 2.3 App 用户管理（已实现）
 
 | 方法 | 路径 | 权限点 | 说明 |
 | --- | --- | --- | --- |
-| GET | `/admin/app-users/page` | `app-user:list` | 检索：keyword（uid/昵称/手机号/邮箱）、status、countryCode、registerSource |
+| GET | `/admin/app-users/page` | `app-user:list` | 检索：keyword（uid/昵称/手机号/邮箱）、status、countryCode、registerSource、platform（ANDROID/IOS，按用户**最近一次**会话平台筛选） |
 | 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、platform（ANDROID/IOS，按**最近一次会话**） |
+| GET | `/admin/favorites/page` | `favorite:list` | 收藏只读分页，含游客；支持 platform 筛选（ANDROID/IOS，按**最近一次会话**） |
+| GET | `/admin/likes/page` | `like:list` | 点赞只读分页，含游客及多态目标；支持 platform 筛选（ANDROID/IOS，按**最近一次会话**） |
 | PUT | `/admin/app-users/{id}/status` | `app-user:update` | 改状态：normal/limited/banned |
 
 状态处置会**立即吊销该用户全部会话**并写入封禁记录，避免"封了还能用"。
 
+收藏和点赞分页参数：`pageIndex` 默认 1，`pageSize` 默认 10、最大 100；
+`keyword` 模糊匹配 uid/昵称，`userId`、`deviceId`、`dramaId` 精确匹配，
+`dramaTitle` 模糊匹配；`startTime/endTime` 按创建时间闭区间过滤，
+格式 `yyyy-MM-dd HH:mm:ss`。点赞另支持 `targetType`（DRAMA/EPISODE/COMMENT）、
+`targetId` 和 `episodeId` 精确过滤，短剧和剧集过滤会解析评论及剧集所属关系。
+按 `createdAt DESC, id DESC` 排序，用户/短剧预检索无结果返回 total=0、list=[]。
+
+点赞的三种目标语义：客户端点赞按钮作用于当前播放剧集，落库为 `targetType=EPISODE`；
+`DRAMA` 是早期按整部剧点赞的历史数据；`COMMENT` 为评论点赞。筛选行为：
+`dramaTitle` / `dramaId` 同时命中「该剧本身的点赞」与「该剧下各集的点赞」，
+`episodeId` 只命中「该集本身的点赞」与该集下的评论点赞，**不包含对短剧本身的点赞**；
+不传 `episodeId` 时不受此限制。
+
+收藏行字段：`id,userId,uid,nickname,deviceId,anonymous,dramaId,dramaTitle,dramaCover,
+dramaStatus,dramaPublished,createdAt`。点赞行字段：`id,userId,uid,nickname,deviceId,
+anonymous,targetType,targetId,dramaId,dramaTitle,dramaCover,episodeId,episodeNo,episodeTitle,
+commentSummary,createdAt`。游客的 userId 为空、anonymous 为 true；评论摘要最多 30 字。
+关联资料逻辑删除后展示字段为空，不排除原始互动记录。
+
 ### 2.4 下载管理（已实现）
 
 | 方法 | 路径 | 权限点 | 说明 |
@@ -524,15 +985,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 订单与权益（已实现）
 
 | 方法 | 路径 | 权限点 | 说明 |
@@ -586,6 +1050,7 @@ GET /app/notices?pageIndex=1&pageSize=20
 | --- | --- | --- | --- |
 | GET | `/admin/dashboard/overview` | `dashboard:view` | 总览：用户 / 内容 / 播放 / 收入 / 成本 |
 | GET | `/admin/dashboard/transcode` | `dashboard:view` | 转码队列积压与失败任务明细（含 `errorMsg` / `retryCount`） |
+| GET | `/admin/notifications/transcode` | `drama:list` | 转码通知：`running` / `success` / `failed` 角标，以及各状态最近 20 条（含 `dramaTitle`、`episodeNo`、`episodeTitle`） |
 
 **口径（与代码注释一致，前端 tooltip 可直接复用）**
 
@@ -593,6 +1058,8 @@ GET /app/notices?pageIndex=1&pageSize=20
 | --- | --- | --- |
 | 用户 | `total` / `newToday` / `new7d` | `app_user` 未删除总数；按 `created_at` 落在当天 / 近 7 天 |
 | 用户 | `active7d` | `last_login_at` 在近 7 天内。**不是 DAU**，日活需要逐日登录快照，当前无产出 |
+| 用户 | `androidActive7d` / `iosActive7d` | `app_user_device` 中 `status=active` 且 `last_seen_at` 在近 7 天的去重设备，平台分别为 `ANDROID` / `IOS` |
+| 用户 | `retention1d` / `retention7d` | 次日留存：昨日注册且今天仍登录的比例。7 日留存：8 至 14 天前注册、近 7 天仍登录的比例。队列为空返回 `null`，取值 0 到 1 |
 | 用户 | `banned` / `limited` / `deactivated` | 按 `status` 计数 |
 | 内容 | `drama*` | 短剧按 `status` 计数（`reviewing` 为待审、`published` 为已上线） |
 | 内容 | `episodeTotal` / `Published` / `WithMedia` | 剧集总数 / 已上线数 / `video_url` 非空数（均排除逻辑删除） |
@@ -709,8 +1176,9 @@ GET /app/notices?pageIndex=1&pageSize=20
 只接受 `bizType=EPISODE` 且状态为 `ready` / `uploaded` 的产物。
 
 **收费配置**：`previewSeconds` 落在 `drama_episode.preview_seconds`（0 = 不限制），
-与 `is_free` / `unlock_coin` 一起就是播放与下载付费判定读的字段，**改完立即生效**（实测：未登录请求付费集返回
+与 `is_free` / `unlock_coin` 一起就是播放与下载付费判定读的字段，**改完立即生效**（实测：未登录请求锁定集直接
-`{"accessType":"COIN_REQUIRED","unlockCoin":50,"previewSeconds":15}`；免费集直接返回签名播放地址）。
+返回 `UNAUTHORIZED`；已登录未解锁用户返回 `{"accessType":"COIN_REQUIRED","unlockCoin":50,"previewSeconds":15}`；
+免费集直接返回签名播放地址）。
 定价沿用「可编辑状态」口径：`draft` / `offline` 可改，已上线要改价需先申请下线（避免创作者悄悄改已上线内容的价格）；
 `dramaId` 以路径为准，body 里传别人的剧 id 无效，列表里带别人的 `episodeId` 会被忽略（只作用于自己剧的分集）。
 
@@ -812,6 +1280,24 @@ GET /app/notices?pageIndex=1&pageSize=20
 
 > `id` 以字符串下发：见 **§0「ID 字段一律以字符串下发」**（本节不再单独规定）。
 
+### 2.11.1 奖励中心管理（已实现）
+
+| 方法 | 路径 | 权限点 | 说明 |
+| --- | --- | --- | --- |
+| GET | `/admin/rewards/tasks/page` · `/tasks/{id}` | `reward:list` | 奖励任务分页与详情 |
+| POST | `/admin/rewards/tasks` | `reward:update` | 新建任务，默认下线 |
+| PUT | `/admin/rewards/tasks/{id}` · `/{id}/status` | `reward:update` | 编辑、上线 / 下线；编辑会递增版本 |
+| GET | `/admin/rewards/activities/page` · `/activities/{id}` | `reward:list` | 奖励活动分页与详情 |
+| POST | `/admin/rewards/activities` | `reward:update` | 新建活动，默认下线 |
+| PUT | `/admin/rewards/activities/{id}` · `/{id}/status` | `reward:update` | 编辑、上线 / 下线 |
+| GET · PUT | `/admin/rewards/check-in/rules` | `reward:checkin` | 查看 / 保存签到每日奖励规则，天数不能重复 |
+| GET | `/admin/rewards/grants/page` | `reward:grant` | 用户、任务、来源、状态筛选发放记录 |
+| POST | `/admin/rewards/grants/manual` | `reward:grant` | 人工补发；仍写 `REWARD` 钱包流水并要求幂等键 |
+
+后台任务保存字段包括 `code`、`sectionCode`、`type`、`verifyMode`、`targetValue`、`rewardCoin`、`cycleType`、`cycleLimit`、三语言文案、动作、排序和生效时间。任务配置不允许后台写任意脚本，扩展字段只能放在 `configJson`。
+
+后台活动保存字段包括 `code`、`coverUrl`、`actionType`、`actionUrl`、三语言标题、三语言摘要、三语言按钮文案、排序和生效时间。活动与任务共用 `reward:update` 权限，新建活动默认下线。
+
 **校验与错误码**：
 
 | 场景 | 结果 |
@@ -853,6 +1339,211 @@ GET /app/notices?pageIndex=1&pageSize=20
 **筛选与错误码**：`title` 必填（1–128）；`content` 最长 2000；公告不存在 → `200002 公告不存在`；
 `status` 只接受 0/1，其他值 → `400`。
 
+### 2.13 运营分类管理（已实现）
+
+> 「分类」是运营自定义的分组，与短剧**类型**（`/admin/drama-categories`，写 `drama_category`）是两套独立概念。
+> 分类存在 `drama_classification`，通过 `drama_classification_drama` 关联任意多部短剧。
+> 后台页面：菜单 **分类管理**（`/content/category-dramas` → `CategoryDramaView.vue`）。
+
+**接口清单**（前缀 `/admin/drama-classifications`）
+
+| 方法 | 路径 | 权限点 | 说明 |
+| --- | --- | --- | --- |
+| GET | `/admin/drama-classifications` | `drama:list` | 分类列表（带关联短剧数量） |
+| POST | `/admin/drama-classifications` | `drama:create` | 新建分类，返回新分类 id |
+| PUT | `/admin/drama-classifications/{id}` | `drama:update` | 编辑分类 |
+| DELETE | `/admin/drama-classifications/{id}` | `drama:delete` | 删除分类（级联删关联，短剧本身保留） |
+| GET | `/admin/drama-classifications/{id}/dramas` | `drama:list` | 分类下已关联的短剧（分页） |
+| GET | `/admin/drama-classifications/{id}/dramas/candidates` | `drama:list` | 尚未关联到该分类的短剧（分页，供多选） |
+| POST | `/admin/drama-classifications/{id}/dramas` | `drama:update` | 批量关联短剧，返回实际新增数量 |
+| DELETE | `/admin/drama-classifications/{id}/dramas/{dramaId}` | `drama:update` | 从分类移出短剧（幂等） |
+| PUT | `/admin/drama-classifications/{id}/ranking-items` | `drama:update` | 原子保存推荐榜完整顺序，最多 50 部；空数组表示清空 |
+
+**列表响应**
+
+```json
+{
+  "code": 0,
+  "message": "ok",
+  "data": [
+    {
+      "id": "2112807182243336193",
+      "name": "本周必看",
+      "code": "CLASSIFICATION_2112807182243336193",
+      "layoutType": "GRID",
+      "revision": "1",
+      "sort": 1,
+      "status": 1,
+      "dramaCount": 12,
+      "updatedAt": "2026-10-22T19:41:02"
+    }
+  ]
+}
+```
+
+排序规则固定为 `sort asc, id desc`；`dramaCount` 是关联表按分类聚合的实时数量。
+时间字段为 `LocalDateTime` 的 ISO 字符串（`yyyy-MM-ddTHH:mm:ss`，秒级），前端按需替换 `T` 为空格。
+
+**新建 / 编辑请求体**
+
+```json
+{
+  "name": "推荐榜",
+  "code": "RECOMMEND_RANKING",
+  "layoutType": "RANKING",
+  "sort": 1,
+  "status": 1
+}
+```
+
+| 字段 | 必填 | 说明 |
+| --- | --- | --- |
+| `name` | 是 | 去首尾空格后保存，全局唯一；`@NotBlank` 提示「请填写分类名称」 |
+| `code` | 否 | 稳定语义码，只允许大写字母、数字、下划线；不传时生成 `CLASSIFICATION_{id}` |
+| `layoutType` | 否 | `GRID` 普通分类 / `RANKING` 推荐榜；默认 `GRID` |
+| `sort` | 否 | 新建不传时取 `现有条数 + 1`；编辑不传（null）时保持原值 |
+| `status` | 否 | `1` 启用 / `0` 停用；新建默认 `1`，编辑不传保持原值 |
+
+**关联短剧**
+
+```json
+POST /admin/drama-classifications/2112807182243336193/dramas
+{ "dramaIds": ["2112807182243336194", "2112807182243336195"] }
+```
+
+返回 `data` 为实际新增条数（整数）。已关联的、以及不存在的 `dramaId` 会被静默跳过，不报错；
+全部跳过时返回 `0`。`dramaIds` 为空数组 → `400 请选择短剧`。
+
+推荐榜应使用 `PUT /{id}/ranking-items` 一次提交完整有序 `dramaIds`。接口会去重、校验短剧存在，
+按数组顺序写入 `position=1..N` 并递增分类 `revision`；`dramaIds` 必须显式传数组，空数组表示清空。
+普通分类调用该接口返回 `200003`；推荐榜调用旧的 `POST /{id}/dramas` 或
+`DELETE /{id}/dramas/{dramaId}` 同样返回 `200003`，防止绕过版本与排序更新。
+
+**短剧列表项（`GET /{id}/dramas` 与 `/dramas/candidates` 共用）**
+
+```json
+{
+  "total": 12,
+  "list": [
+    {
+      "id": "2112807182243336194",
+      "title": "闪婚后首富老公竟是我老板",
+      "cover": "https://.../cover.jpg",
+      "status": "published",
+      "totalEpisodes": 80,
+      "sort": 100,
+      "updatedAt": "2026-10-22T18:00:00"
+    }
+  ]
+}
+```
+
+- 查询参数：`keyword`（按 `title` 模糊匹配，可空）、`pageIndex`（默认 1）、`pageSize`（默认 10，上限 100）
+- 排序：`sort desc, id desc`
+- `status` 取值：`draft` 草稿 / `reviewing` 审核中 / `approved` 待发布 / `published` 已上线 / `offline` 已下线
+- `cover` 取自短剧 `cover_url`
+
+**错误码**
+
+| 场景 | 返回 |
+| --- | --- |
+| 分类名称重复（新建或改名撞已有） | `200001 分类名称已存在` |
+| 分类 id 不存在（编辑/删除/查询/关联/移出） | `200002 分类不存在` |
+| `name` 为空 | `400 请填写分类名称` |
+| `dramaIds` 为空 | `400 请选择短剧` |
+
+> 所有写操作带 `@OperationLog(module = "内容管理")` 操作日志。ID 下发口径见 **§0**。
+
+### 2.14 剧单管理（已实现）
+
+> 剧单使用**自己的一套分类**（`drama_playlist_category`），与「分类管理」和「类型」都没有关系。
+> **没有「剧单」这一层实体**：分类直接挂短剧，关联表 `drama_playlist_category_drama(category_id, drama_id)`。
+> 后台页面：菜单 **剧单管理**（`/content/drama-playlists` → `DramaPlaylistView.vue`）。
+
+**接口清单**（前缀 `/admin/drama-playlist-categories`）
+
+| 方法 | 路径 | 权限点 | 说明 |
+| --- | --- | --- | --- |
+| GET | `/admin/drama-playlist-categories` | `drama:list` | 剧单分类列表（带短剧数量） |
+| POST | `/admin/drama-playlist-categories` | `drama:create` | 新建剧单分类，返回新分类 id |
+| PUT | `/admin/drama-playlist-categories/{id}` | `drama:update` | 编辑剧单分类 |
+| DELETE | `/admin/drama-playlist-categories/{id}` | `drama:delete` | 删除剧单分类（级联删关联，短剧本身保留） |
+| GET | `/admin/drama-playlist-categories/{id}/dramas` | `drama:list` | 分类下已关联的短剧（分页） |
+| GET | `/admin/drama-playlist-categories/{id}/dramas/candidates` | `drama:list` | 尚未关联到该分类的短剧（分页，供多选） |
+| POST | `/admin/drama-playlist-categories/{id}/dramas` | `drama:update` | 批量把短剧加入分类，返回实际新增数量 |
+| DELETE | `/admin/drama-playlist-categories/{id}/dramas/{dramaId}` | `drama:update` | 从分类移出短剧（幂等） |
+
+**列表响应**
+
+```json
+{
+  "code": 0,
+  "message": "ok",
+  "data": [
+    {
+      "id": "2112807182243336196",
+      "name": "高甜先婚后爱",
+      "description": "站内投放位使用，按周更新",
+      "sort": 1,
+      "status": 1,
+      "dramaCount": 8
+    }
+  ]
+}
+```
+
+排序规则 `sort asc, id desc`；`dramaCount` 为该分类下已关联短剧数量。
+
+**新建 / 编辑请求体**
+
+```json
+{
+  "name": "高甜先婚后爱",
+  "description": "站内投放位使用，按周更新",
+  "sort": 1,
+  "status": 1
+}
+```
+
+| 字段 | 必填 | 说明 |
+| --- | --- | --- |
+| `name` | 是 | 去首尾空格后保存，全局唯一；`@NotBlank` 提示「请填写剧单分类名称」 |
+| `description` | 否 | 最长 255 字符（超长 → `400 描述最多 255 个字符`）；新建不传存空串，编辑不传保持原值 |
+| `sort` | 否 | 新建不传取 `现有条数 + 1`；编辑不传保持原值 |
+| `status` | 否 | `1` 启用 / `0` 停用；新建默认 `1` |
+
+**关联短剧**
+
+```json
+POST /admin/drama-playlist-categories/2112807182243336196/dramas
+{ "dramaIds": ["2112807182243336194"] }
+```
+
+返回实际新增条数；已关联或不存在的短剧自动跳过；`dramaIds` 为空 → `400 请选择短剧`。
+`GET /{id}/dramas` 与 `GET /{id}/dramas/candidates` 的查询参数和响应结构与 **§2.13** 完全一致
+（`keyword` / `pageIndex` / `pageSize`，响应 `{ total, list }`，列表项含
+`id` / `title` / `cover` / `status` / `totalEpisodes` / `sort` / `updatedAt`）。
+
+**错误码**
+
+| 场景 | 返回 |
+| --- | --- |
+| 剧单分类名称重复 | `200001 剧单分类名称已存在` |
+| 剧单分类 id 不存在 | `200002 剧单分类不存在` |
+| `name` 为空 | `400 请填写剧单分类名称` |
+| `description` 超过 255 | `400 描述最多 255 个字符` |
+| `dramaIds` 为空 | `400 请选择短剧` |
+
+**与「分类管理」的差异**
+
+| 项 | 运营分类（2.13） | 剧单分类（2.14） |
+| --- | --- | --- |
+| 数据表 | `drama_classification` + `drama_classification_drama` | `drama_playlist_category` + `drama_playlist_category_drama` |
+| 描述字段 | 无 | 有（`description`，≤255） |
+| 列表返回 | 含 `updatedAt` | 含 `description`，不含 `updatedAt` |
+| 菜单 | 分类管理（`/content/category-dramas`） | 剧单管理（`/content/drama-playlists`） |
+| 用途 | 内容侧分组 | 运营侧投放/剧单位分组 |
+
 ## 3. 契约与实现状态对照
 
 > 最后更新：2026-10-16（`develop` 分支）。未完成项汇总见仓库根 `README.md`「尚未完成」。

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/2026-10-22-app-library-paging.md

@@ -0,0 +1,24 @@
+# 客户端收藏与观看历史分页
+
+## 目标
+
+- `/app/favorites` 改为 `PageResult<AppDramaCardVO>`，默认第 1 页、每页 20，最大 100。
+- `/app/watch/recent` 默认返回 `PageResult<ProgressRespVO>`；请求带 `limit` 时保留一版旧
+  `List<ProgressRespVO>` 响应。
+- 观看历史补充短剧标题、封面、集号和总集数，剧/集均批量查询。
+
+## 实现步骤
+
+1. 收藏关系使用 `selectPage`，按 `created_at DESC, drama_id DESC` 稳定排序；
+   只统计已上线短剧收藏，再按当前页 ID 批量加载短剧。
+2. 观看进度使用 `selectPage`，按 `updated_at DESC, drama_id DESC` 稳定排序。
+3. 当前页的 dramaId / episodeId 去重排序后，分别执行一次 IN 查询并装配展示字段。
+4. Controller 归一化 pageIndex/pageSize；观看历史根据是否传 `limit` 分流新旧响应。
+5. 更新 API 契约 §1.5，补 service/controller 测试。
+
+## 风险与约束
+
+- `limit` 分支仅用于旧客户端兼容，新分页响应与旧 List 响应不能混用。
+- 已下线短剧不计入收藏 total，也不出现在收藏页。
+- 观看历史展示字段找不到对应剧或集时保持 null，不影响历史记录返回。
+- 不修改客户端、不改表结构、不启停服务、不操作真机。

docs/plans/2026-10-22-media-transcode-output-api.md

@@ -0,0 +1,38 @@
+# 转码产物查询接口
+
+## 目标
+
+- 媒体维度查询 rendition 与帧图产物。
+- 分集维度聚合转码任务、rendition、帧图状态。
+- `/admin/dashboard/transcode` 改为明确 VO，OpenAPI 不再出现匿名 Object。
+
+## 设计
+
+1. `MediaTranscodeOutputService` 统一读取媒体、任务、rendition 与 thumbnail。
+2. rendition 按高度、视频码率、质量倒序，id 正序保证稳定。
+3. thumbnail 优先读取 `thumbnails.vtt`，解析 cue 后分页；无记录返回 `EMPTY`，
+   记录失败返回 `FAILED`，不把缺产物当服务错误。
+4. 分集聚合对不存在、无视频、无媒资、无任务返回明确 status 和空列表。
+5. dashboard 使用强类型 queue/failed task VO，保留现有字段语义并补 total。
+
+## 接口
+
+- `GET /admin/media/{id}/renditions`
+- `GET /admin/media/{id}/thumbnails?pageIndex=1&pageSize=100`
+- `GET /admin/episodes/{id}/transcode`
+- `GET /admin/dashboard/transcode`（响应类型由 Map 收敛为 VO）
+
+缩略图响应内嵌 `PageResult<MediaThumbnailFrameVO>`，同时返回 sprite/VTT 元数据；
+空产物 status 为 `EMPTY`，无绑定分集为 `NO_EPISODE`，损坏 VTT 为 `INVALID`。
+
+## TDD
+
+- 先提交媒体有/无产物、不存在、VTT 解析与分页边界测试。
+- 再提交接口、VO、聚合服务和 dashboard 类型收敛实现。
+- 门禁：`mvn -pl fruitshorts-module-media test`。
+
+## 红线
+
+- 不改 `/app` 契约、specs、ReelShortWeb、Flutter。
+- 不改 P1 入队与手动重转逻辑。
+- 不启停服务，不操作真机。

docs/plans/2026-10-22-media-transcode-pipeline.md

@@ -0,0 +1,40 @@
+# 后台转码链路打通
+
+## 现状取证
+
+- 上传完成时 `MediaService.complete` 已为视频调用 `TranscodeService.enqueue`。
+- 分集创建/替换视频地址时 `EpisodeService` 已调用
+  `EpisodeTranscodeBindingService.bind`，会复用并绑定同一媒体的未完成任务。
+- 转码失败原因已写入 `transcode_task.error_msg`，最终状态写入 `status`。
+- 缺口是后台手动触发/重转接口，以及对应幂等和链路测试。
+
+## 实现
+
+1. 保留上传完成和改片自动入队逻辑，补测试锁定行为。
+2. `TranscodeService` 增加手动触发：
+   - QUEUED/RUNNING 直接返回现有任务；
+   - FAILED 重置原任务为 QUEUED；
+   - SUCCESS 才创建新任务，紧接着重复触发会复用新 QUEUED 任务。
+3. 新增 `POST /admin/media/{id}/transcode`，校验媒资存在，复用 `episode:upload`。
+4. 返回任务 id 与状态，便于后台提示。
+
+实现时对同一媒资行使用 `FOR UPDATE`，让重复请求在事务内串行判定；
+平台不存在的媒资保持 `DATA_NOT_FOUND`，不产生任务或 500。
+
+## TDD 测试矩阵
+
+| 场景 | 断言 |
+| --- | --- |
+| 视频上传完成 | `MediaService.complete` 调用一次 `enqueue(assetId, 0, 0, sourceUrl)` |
+| 图片上传完成 | 不创建转码任务 |
+| 手动触发成功媒资 | 新建一个 QUEUED 任务，重复调用复用同一任务 |
+| 手动触发进行中媒资 | 直接返回 QUEUED/RUNNING 任务，不新增记录 |
+| 手动触发失败媒资 | 原任务重置为 QUEUED，保留任务 id |
+| 媒资不存在 | 返回既有 `DATA_NOT_FOUND`，控制器不产生 500 |
+| worker 最终失败 | 任务状态 FAILED，`error_msg` 保留 ffmpeg 原因 |
+
+## 验证
+
+- 先提交失败测试，再提交实现。
+- `mvn -pl fruitshorts-module-media,fruitshorts-transcode-worker test`
+- 不启停任何服务，不执行数据库变更，不改 Web/Flutter/specs/API 文档。

docs/plans/2026-10-22-media-transcode-profile-sprite.md

@@ -0,0 +1,53 @@
+# 转码档位配置、雪碧图与播放缩略图轴
+
+## 目标
+
+1. 后台可配置转码档位与雪碧图参数，worker 对之后的新任务在 30 秒内自动生效。
+2. 转码成功后生成雪碧图与 VTT，登记到 `media_thumbnail`。
+3. 播放接口与详情剧集返回 `thumbnailsUrl`，无产物时为 `null`。
+
+## 配置模型
+
+- `sys_config.config_key = media.transcode.profile`，值为 JSON。
+- 配置包含总开关、分片秒数、码率阶梯与雪碧图参数。
+- 缺省配置等价于现有 360p/480p/720p/1080p 四档。
+- 后台 GET 缺省或历史配置非法时返回 yml 等价默认值；PUT 非法时返回统一 400，且不写库。
+- worker 读取配置缓存 30 秒；缺省、解析失败或校验失败时回退 yml 默认阶梯。
+
+## 权限取舍
+
+现有权限点没有 `media:transcode`。本次两个接口复用最小可用的
+`episode:upload`，避免新增权限点导致已有角色需要补授权；不新增菜单或权限 SQL。
+
+## 数据与产物
+
+- 新增 `media_thumbnail`，按 `episode_id` 唯一，记录 VTT、雪碧图前缀、采样参数、
+  尺寸、帧数、时长、状态、错误与总大小。
+- 雪碧图目录固定在 `transcoded/{taskId}/thumbnails/`：
+  `thumbnails.vtt` + `sprite_001.jpg` 等多张图。
+- VTT cue 链接使用相对路径 `sprite_XXX.jpg#xywh=x,y,w,h`，同一 VTT 目录下可直接解析。
+- 缩略图失败只把 `media_thumbnail.status` 置 `FAILED` 并记录错误；主 HLS 仍成功。
+
+## 播放
+
+- `PlayRespVO` 和 `AppEpisodeVO` 增加 `thumbnailsUrl`。
+- 查询 `media_thumbnail` 仅读取 `READY` 产物；objectKey 经
+  `MediaStorageService.toPublicUrl` 后使用现有 `PlaybackSigner` 签名。
+- 详情剧集列表批量查询缩略图，禁止 N+1。
+- 不改变现有 HLS/原文件回落与 qualities 列表。
+
+## 测试
+
+- worker：配置解析、非法配置回退 yml、30 秒缓存、VTT 坐标、多雪碧图索引、
+  缩略图失败不阻断主转码。
+- admin：GET 默认值、PUT 非法不落库、PUT 成功落库。
+- playback：有 READY 缩略图返回签名 `thumbnailsUrl`，无产物返回 `null`。
+- 门禁：`mvn -pl fruitshorts-transcode-worker,fruitshorts-admin-api,fruitshorts-app-api -am test`。
+
+## 风险 / 边界
+
+- 本次只对合并后的新转码任务生效，不回跑历史任务。
+- 配置中的顶层 `enabled` 会持久化并返回；本单不改变既有队列消费开关语义，
+  worker 仍以 `worker-enabled` 决定是否消费任务。
+- 雪碧图生成依赖 ffmpeg `tile` 滤镜；真实产物由 worker 门禁和 PM 后续环境验收，
+  本任务不启动服务、不改客户端。

docs/plans/2026-10-22-transcode-binding-fix.md

@@ -0,0 +1,38 @@
+# 转码分集绑定与运行态修复
+
+## 已确认现场
+
+admin-api/app-api/worker 均运行旧包；worker 未运行；`media_thumbnail` 表缺失；
+新上传任务 drama_id/episode_id 为 0；旧 worker jar 缺 MediaThumbnail。
+
+## 代码修复
+
+1. 分集保存后按视频 URL 的 objectKey 查找 `media_asset`。
+2. media 域新增绑定服务：
+   - 将 dramaId/episodeId 回填到对应 `transcode_task`；
+   - QUeued/RUNNING/SUCCESS 任务复用，不重复入队；
+   - FAILED/CANCELED 或不存在时新建任务；
+   - 已成功但 episodeId=0 的 rendition 同步回填。
+3. `claimNext` 只认领 `episode_id > 0`，零绑定任务保留 QUEUED。
+4. 缩略图登记使用 REQUIRES_NEW 独立事务；生成或登记失败只记 warn/error_msg，
+   主任务仍 SUCCESS。
+5. 对 episode_id=0 且源文件不存在的明显测试垃圾标记 CANCELED，不删除。
+
+## 迁移与运行
+
+1. 确认 `media_thumbnail` 不存在后执行幂等 patch。
+2. `mvn -DskipTests package` 全量重建。
+3. 检查三个 jar 分别含：
+   - admin-api：MediaTranscodeProfile；
+   - app-api：PlayRespVO.thumbnailsUrl 对应新类；
+   - worker：MediaThumbnail / MediaThumbnailMapper。
+4. 重启 8080/8081/worker，日志写 `logs/*.log`。
+5. 冒烟 admin 配置、App 详情 thumbnailsUrl、worker 轮询。
+6. 上传真实视频，创建绑定分集，等待 worker 消费，验证任务、四档 HLS、
+   media_thumbnail、VTT 与 sprite HTTP 200。
+
+## 风险
+
+- 旧 QUEUED 中无法绑定且源文件不存在的测试任务将被取消并记录 id。
+- 真实视频端到端验证会写入运行数据库和媒资目录。
+- 不修改 Web/Flutter，不操作真机。

docs/plans/2026-10-22-transcode-claim-fix.md

@@ -0,0 +1,24 @@
+# 转码任务认领与媒资 ID 校验
+
+## 现场结论
+
+- `media_asset.id=21` 确实存在，source_url 对应分集 id=13。
+- 分集 13 的 video_asset_id=0，旧手动触发只拿媒资，不知道分集绑定，
+  因而创建了 media_asset_id=21、episode_id=0 的 QUEUED 任务。
+- claim 只筛选 episode_id>0，因此该任务永久跳过且没有原因日志。
+
+## 修复
+
+1. POST /admin/media/{id}/transcode 严格只按 media_asset.id 查询；
+   不再把候选 id 当分集 id 兜底或补登记。
+2. 媒资存在时按 source_url 反查分集；找到后绑定 drama_id/episode_id。
+3. 找不到分集时拒绝建任务，避免生成永远无法认领的 episode_id=0 记录。
+4. claim 增加 media_asset_id/source_url 条件，并记录被跳过任务 id 与原因。
+5. RUNNING 无更新阈值收敛到 5 分钟，覆盖 worker 重启后的孤儿任务。
+6. 一次性 patch 将 media_asset_id 不存在且 episode_id=0 的 QUEUED/RUNNING 标记 FAILED。
+
+## 验证
+
+- 非法 media id 拒绝、未绑定分集拒绝、合法 URL 自动绑定。
+- claim 跳过原因、进度更新、僵尸任务恢复。
+- `mvn -pl fruitshorts-module-media,fruitshorts-transcode-worker test`。

docs/plans/2026-10-22-transcode-media-id-fix.md

@@ -0,0 +1,28 @@
+# 转码媒资 ID 精度与存量兜底修复
+
+## 取证
+
+- 示例分集 `2113150431755636737` 的 `video_asset_id` 为
+  `2113150398670966786`，与 `media_asset.id` 完全一致。
+- JS `Number('2113150398670966786')` 序列化为 `2113150398670966800`，
+  超出安全整数后发生精度丢失，导致手动转码查询了错误 ID。
+
+## 修复
+
+1. 聚合响应的 episodeId/mediaAssetId/taskId 使用字符串。
+2. 手动转码仍由后端 Long 接收精确路径 ID。
+3. 媒资不存在时通过 content 模块的端口按候选 ID 查找分集：
+   - 分集 id；
+   - video_asset_id；
+   - transcode_task.id。
+4. 找到分集后按 video_url/source_url/objectKey 反查媒资；
+   文件存在但媒资缺失时补登记并回填分集 video_asset_id。
+5. 无可用视频时保持明确空态/错误语义。
+
+## 验证
+
+- 超 2^53 ID 字符串契约。
+- 聚合无媒资空态。
+- video_url 反查命中。
+- 文件存在时补登记。
+- `mvn -pl fruitshorts-module-media,fruitshorts-transcode-worker test`。

docs/plans/2026-10-22-transcode-preserve-aspect.md

@@ -0,0 +1,27 @@
+# 转码保持原始宽高比
+
+## 目标
+
+- 横屏源按档位短边作为高度，竖屏源按档位短边作为宽度。
+- 源短边小于档位短边时按源短边输出，不放大。
+- 输出宽高均为偶数，SAR 固定为 1。
+- rendition 的 width/height 使用 ffprobe 探测到的实际值。
+
+## 实施
+
+1. ffprobe 读取源显示方向尺寸，旋转 90/270 度时交换宽高。
+2. `effectiveShort = min(sourceShort, rungShort)` 并向下取偶数。
+3. 横屏使用 `scale=-2:<effectiveShort>:flags=lanczos,setsar=1`；
+   竖屏使用 `scale=<effectiveShort>:-2:flags=lanczos,setsar=1`。
+4. 转码完成后 ffprobe variant playlist，写入实际输出尺寸。
+5. master playlist 的 RESOLUTION 同步使用实际尺寸。
+
+## 不放大策略
+
+选用“用源尺寸输出”：高于源短边的档位仍保留原 quality 标识和码率，
+但分辨率封顶到源短边，避免所有档位都被跳过导致无产物。
+
+## 验证
+
+- 先补横屏、竖屏、小源码片、偶数、SAR=1 与实际尺寸回写测试。
+- 门禁：`mvn -pl fruitshorts-module-media,fruitshorts-transcode-worker test`。

docs/plans/2026-10-22-transcode-progress-fix.md

@@ -0,0 +1,29 @@
+# 转码错误截断与进度上报
+
+## 问题
+
+- ffmpeg 错误输出超过 `error_msg varchar(500)`，失败回写 UPDATE 再次失败，
+  任务停在 RUNNING/0。
+- worker 未解析 ffmpeg progress，前端只能看到 0。
+- 缺少 RUNNING 超时收口。
+
+## 修复
+
+1. SQL patch 将 transcode_task/media_thumbnail 的 error_msg 改为 TEXT，可重复执行。
+2. 新增统一错误消息截断，最多保留 500 字符并附总长度；即使补丁尚未执行，
+   也不会超过旧 varchar(500) 限制。
+3. ffmpeg 使用 `-progress` 临时文件，worker 节流为约 1 秒写 transcode_task.progress。
+4. rendition 阶段映射 0-90%，封面/缩略图 90-99%，成功后 100。
+5. 失败保留最后进度；RUNNING 超过 10 分钟无 updated_at 变化标记 FAILED。
+6. 手动重转复用最新任务，SUCCESS/FAILED/CANCELED 原地重置为 QUEUED、progress=0。
+7. 成功写 rendition 前替换同媒资旧产物，避免重复重转唯一键冲突。
+
+## 风险
+
+- 进度写入只允许 RUNNING 状态，避免覆盖已完成/失败状态。
+- 历史僵尸任务由 worker 下一轮自动收口，无需手工 SQL。
+
+## 验证
+
+- 错误截断、进度更新、僵尸重置、重复触发幂等测试。
+- `mvn -pl fruitshorts-module-media,fruitshorts-transcode-worker test`。

docs/plans/2026-10-22-transcode-rendition-upsert.md

@@ -0,0 +1,24 @@
+# 转码 rendition 幂等与失败落库
+
+## 根因
+
+- 成功事务只按 media_asset_id 删除旧 rendition。
+- 同一分集替换视频后 media_asset_id 改变、episode_id 不变，
+  旧行未被删除，触发 uk_rendition(episode_id, quality, format)。
+- rendition 插入异常后任务未被可靠置为 FAILED。
+
+## 修复
+
+1. 成功事务删除条件分组为：
+   `media_asset_id = 本次媒体 OR (episode_id > 0 AND episode_id = 本次分集)`。
+2. 缩略图登记按 episode_id 删除旧行后重新插入。
+3. 主流程异常调用 failFinal，直接写 FAILED、错误、finished_at，保留 progress。
+4. failFinal 自身异常在 worker 中 catch 并打印 ERROR，不静默。
+5. error 截断同时保留头部与尾部，长度仍 <= 500。
+
+## 验证
+
+- 不同 media_asset_id、同 episode_id 的重复转码清理条件。
+- thumbnail 旧行替换。
+- 失败落库字段与尾段错误保留。
+- `mvn -q -DskipTests=false test -pl ... -am`。

docs/plans/2026-10-24-content-tag.md

@@ -0,0 +1,19 @@
+# 标签管理（替换短剧内容类型）
+
+## 决定
+
+不做「语言开关」总控。分类和剧单已经用 `name` / `nameEn` / `nameId` 三列。标签沿用同一套，避免两套国际化。语言总控要改短剧标题、简介、剧集标题，单独开一轮。
+
+## 本轮
+
+- 短剧编辑去掉「内容类型」。库里的 `drama_type` 先留着，推荐流的 `ANIME` / `LIVE` 筛选不受影响，后台不再改它。
+- 内容管理下新增「标签管理」。
+- 标签字段：中文名、英文名、印尼语名、排序、启用状态。三个名称都必填。
+- 短剧 `tag_id` 单选，可空。编辑页用下拉，只列出启用中的标签。
+- 已有短剧按原内容类型回填：`ANIME` → 漫剧，`LIVE` → 真人剧。
+
+## 接口
+
+- `GET/POST /admin/content-tags`，`PUT/DELETE /admin/content-tags/{id}`，权限沿用 `drama:list` / `create` / `update` / `delete`。
+- 短剧保存增加 `tagId`。不传则保持原值；传 `0` 表示清空。
+- 短剧列表返回 `tagId`、`tagName`、`tagNameEn`、`tagNameId`。

fruitshorts-admin-api/src/main/java/com/fruitshorts/admin/config/AdminJacksonTimeConfig.java

@@ -0,0 +1,28 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.admin.config;
+
+import com.fasterxml.jackson.datatype.jsr310.ser.LocalDateTimeSerializer;
+import org.springframework.boot.autoconfigure.jackson.Jackson2ObjectMapperBuilderCustomizer;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+import java.time.format.DateTimeFormatter;
+
+/**
+ * 后台接口的时间格式统一成 `yyyy-MM-dd HH:mm:ss`。
+ *
+ * <p>application.yml 里的 `spring.jackson.date-format` 只作用于 java.util.Date，
+ * LocalDateTime 仍会输出 ISO 的 `2026-10-27T14:14:12.644`，后台表格里会露出一串带 T 的原文。
+ * 该配置只放在 admin-api，C 端保持 ISO，避免影响客户端解析。
+ */
+@Configuration
+public class AdminJacksonTimeConfig {
+
+    private static final DateTimeFormatter DATE_TIME = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
+
+    @Bean
+    public Jackson2ObjectMapperBuilderCustomizer adminLocalDateTimeFormat() {
+        return builder -> builder.serializers(new LocalDateTimeSerializer(DATE_TIME));
+    }
+}

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

@@ -4,6 +4,7 @@ package com.fruitshorts.admin.controller;
 
 import com.fruitshorts.common.pojo.PageResult;
 import com.fruitshorts.common.pojo.Result;
+import com.fruitshorts.admin.service.AppSessionSystemService;
 import com.fruitshorts.admin.vo.AppUserWatchHistoryVO;
 import com.fruitshorts.content.dal.entity.Drama;
 import com.fruitshorts.content.dal.entity.DramaEpisode;
@@ -13,6 +14,7 @@ import com.fruitshorts.content.service.EpisodeService;
 import com.fruitshorts.framework.log.OperationLog;
 import com.fruitshorts.framework.security.SecurityUtils;
 import com.fruitshorts.playback.dal.entity.WatchHistory;
+import com.fruitshorts.user.dal.entity.AppUserSession;
 import com.fruitshorts.playback.service.WatchProgressService;
 import com.fruitshorts.user.dal.entity.AppUserBanRecord;
 import com.fruitshorts.user.service.AppUserAdminService;
@@ -44,6 +46,7 @@ public class AppUserAdminController {
     private final WatchProgressService watchProgressService;
     private final DramaService dramaService;
     private final EpisodeService episodeService;
+    private final AppSessionSystemService sessionSystem;
 
     @Operation(summary = "App 用户分页查询")
     @GetMapping("/page")
@@ -83,11 +86,15 @@ public class AppUserAdminController {
         Map<Long, DramaEpisode> episodes = episodeService
                 .listByIds(rows.stream().map(WatchHistory::getEpisodeId).distinct().toList())
                 .stream().collect(Collectors.toMap(DramaEpisode::getId, item -> item, (a, b) -> a));
-        return Result.ok(rows.stream().map(row -> toVo(row, dramas, episodes)).toList());
+        List<AppUserSession> sessions = sessionSystem.groupByUser(List.of(id))
+                .getOrDefault(id, List.of());
+        return Result.ok(rows.stream()
+                .map(row -> toVo(row, dramas, episodes, sessionSystem.match(sessions, row.getDeviceId())))
+                .toList());
     }
 
     private AppUserWatchHistoryVO toVo(WatchHistory row, Map<Long, Drama> dramas,
-                                       Map<Long, DramaEpisode> episodes) {
+                                       Map<Long, DramaEpisode> episodes, AppUserSession session) {
         AppUserWatchHistoryVO vo = new AppUserWatchHistoryVO();
         vo.setId(row.getId());
         vo.setDramaId(row.getDramaId());
@@ -100,6 +107,10 @@ public class AppUserAdminController {
         long position = row.getPositionMs() == null ? 0L : row.getPositionMs();
         long duration = row.getDurationMs() == null ? 0L : row.getDurationMs();
         vo.setFinished(duration > 0 && position + 1000L >= duration);
+        if (session != null) {
+            vo.setPlatform(session.getPlatform());
+            vo.setOsVersion(session.getOsVersion());
+        }
         Drama drama = dramas.get(row.getDramaId());
         if (drama != null) {
             vo.setDramaTitle(drama.getTitle());

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

@@ -0,0 +1,98 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.admin.controller;
+
+import com.fruitshorts.common.pojo.PageResult;
+import com.fruitshorts.common.pojo.Result;
+import com.fruitshorts.framework.log.OperationLog;
+import com.fruitshorts.system.service.AppVersionService;
+import com.fruitshorts.system.vo.AppVersionQueryReqVO;
+import com.fruitshorts.system.vo.AppVersionRespVO;
+import com.fruitshorts.system.vo.AppVersionSaveReqVO;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.validation.Valid;
+import jakarta.validation.constraints.NotEmpty;
+import jakarta.validation.constraints.Size;
+import lombok.RequiredArgsConstructor;
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.validation.annotation.Validated;
+import org.springframework.web.bind.annotation.DeleteMapping;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.PutMapping;
+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;
+
+/** 后台 - App 版本管理。 */
+@Tag(name = "后台-App 版本")
+@RestController
+@RequestMapping("/admin/app-versions")
+@RequiredArgsConstructor
+public class AppVersionAdminController {
+
+    private final AppVersionService appVersionService;
+
+    @Operation(summary = "版本分页查询")
+    @GetMapping("/page")
+    @PreAuthorize("@ss.hasPermission('app-version:list')")
+    public Result<PageResult<AppVersionRespVO>> page(@Validated AppVersionQueryReqVO req) {
+        return Result.ok(appVersionService.page(req));
+    }
+
+    @Operation(summary = "版本详情")
+    @GetMapping("/{id}")
+    @PreAuthorize("@ss.hasPermission('app-version:list')")
+    public Result<AppVersionRespVO> detail(@PathVariable Long id) {
+        return Result.ok(appVersionService.detail(id));
+    }
+
+    @Operation(summary = "新建版本（默认发布）")
+    @PostMapping
+    @PreAuthorize("@ss.hasPermission('app-version:create')")
+    @OperationLog(module = "版本管理", action = "新建版本")
+    public Result<Long> create(@Valid @RequestBody AppVersionSaveReqVO req) {
+        return Result.ok(appVersionService.create(req));
+    }
+
+    @Operation(summary = "批量新建版本（一次事务）")
+    @PostMapping("/batch")
+    @PreAuthorize("@ss.hasPermission('app-version:create')")
+    @OperationLog(module = "版本管理", action = "批量新建版本")
+    public Result<java.util.List<Long>> batchCreate(
+            @NotEmpty(message = "请至少传一条")
+            @Size(max = 16, message = "单次不超过 16 条")
+            @Valid @RequestBody java.util.List<@Valid AppVersionSaveReqVO> reqs) {
+        return Result.ok(appVersionService.batchCreate(reqs));
+    }
+
+    @Operation(summary = "编辑版本")
+    @PutMapping("/{id}")
+    @PreAuthorize("@ss.hasPermission('app-version:update')")
+    @OperationLog(module = "版本管理", action = "编辑版本")
+    public Result<Void> update(@PathVariable Long id, @Valid @RequestBody AppVersionSaveReqVO req) {
+        appVersionService.update(id, req);
+        return Result.ok();
+    }
+
+    @Operation(summary = "发布 / 下架")
+    @PutMapping("/{id}/status")
+    @PreAuthorize("@ss.hasPermission('app-version:update')")
+    @OperationLog(module = "版本管理", action = "版本上下架")
+    public Result<Void> updateStatus(@PathVariable Long id, @RequestParam Integer status) {
+        appVersionService.updateStatus(id, status);
+        return Result.ok();
+    }
+
+    @Operation(summary = "删除版本")
+    @DeleteMapping("/{id}")
+    @PreAuthorize("@ss.hasPermission('app-version:delete')")
+    @OperationLog(module = "版本管理", action = "删除版本")
+    public Result<Void> delete(@PathVariable Long id) {
+        appVersionService.delete(id);
+        return Result.ok();
+    }
+}

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

@@ -32,12 +32,13 @@ import java.util.List;
 public class AuthController {
 
     private final AuthService authService;
+    private final WebUtils webUtils;
 
     @Operation(summary = "管理端登录")
     @PostMapping("/login")
     @OperationLog(module = "认证", action = "登录")
     public Result<LoginRespVO> login(@Valid @RequestBody LoginReqVO req, HttpServletRequest request) {
-        return Result.ok(authService.login(req, WebUtils.getClientIp(request)));
+        return Result.ok(authService.login(req, webUtils.clientIp(request)));
     }
 
     /** 当前用户的菜单路由树，结构与前端 element-plus-admin 的动态路由一致。 */

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` 即审核队列。 */
+    /** 检索评论：status 为空时返回全部状态，传 pending 即审核队列。 */
-    @Operation(summary = "评论检索（默认按状态过滤，待审队列）")
+    @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/ContentTagController.java

@@ -0,0 +1,72 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.admin.controller;
+
+import com.fruitshorts.common.pojo.Result;
+import com.fruitshorts.content.service.ContentTagService;
+import com.fruitshorts.content.vo.ContentTagRespVO;
+import com.fruitshorts.content.vo.ContentTagSaveReqVO;
+import com.fruitshorts.framework.log.OperationLog;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.validation.Valid;
+import lombok.RequiredArgsConstructor;
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.web.bind.annotation.DeleteMapping;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.PutMapping;
+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.List;
+
+/** 短剧标签管理。短剧编辑时单选其中一个启用标签。 */
+@Tag(name = "后台-标签")
+@RestController
+@RequestMapping("/admin/content-tags")
+@RequiredArgsConstructor
+public class ContentTagController {
+
+    private final ContentTagService contentTagService;
+
+    @Operation(summary = "标签列表")
+    @GetMapping
+    @PreAuthorize("@ss.hasPermission('drama:list')")
+    public Result<List<ContentTagRespVO>> list(
+            @RequestParam(required = false) Boolean enabledOnly) {
+        if (Boolean.TRUE.equals(enabledOnly)) {
+            return Result.ok(contentTagService.listEnabled());
+        }
+        return Result.ok(contentTagService.list());
+    }
+
+    @Operation(summary = "新建标签")
+    @PostMapping
+    @PreAuthorize("@ss.hasPermission('drama:create')")
+    @OperationLog(module = "内容管理", action = "新增标签")
+    public Result<Long> create(@Valid @RequestBody ContentTagSaveReqVO req) {
+        return Result.ok(contentTagService.create(req));
+    }
+
+    @Operation(summary = "编辑标签")
+    @PutMapping("/{id}")
+    @PreAuthorize("@ss.hasPermission('drama:update')")
+    @OperationLog(module = "内容管理", action = "编辑标签")
+    public Result<Void> update(@PathVariable Long id, @Valid @RequestBody ContentTagSaveReqVO req) {
+        contentTagService.update(id, req);
+        return Result.ok();
+    }
+
+    @Operation(summary = "删除标签")
+    @DeleteMapping("/{id}")
+    @PreAuthorize("@ss.hasPermission('drama:delete')")
+    @OperationLog(module = "内容管理", action = "删除标签")
+    public Result<Void> delete(@PathVariable Long id) {
+        contentTagService.delete(id);
+        return Result.ok();
+    }
+}

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

@@ -70,8 +70,8 @@ public class CreatorAdminController {
         return Result.ok(creatorService.audit(id, req, SecurityUtils.getUserId()));
     }
 
-    /** 手工录入创作者主体（C 端申请入驻还没实现，先用它打通链路）。 */
+    /** 手工录入创作者主体：录入即通过，可直接开号。 */
-    @Operation(summary = "手工录入创作者主体")
+    @Operation(summary = "手工录入创作者主体（录入即通过）")
     @PostMapping
     @PreAuthorize("@ss.hasPermission('creator:audit')")
     @OperationLog(module = "创作者管理", action = "新增创作者")
@@ -79,8 +79,8 @@ public class CreatorAdminController {
         return Result.ok(creatorService.create(req));
     }
 
-    /** 开通创作者账号：仅审核通过可开；已开通则幂等返回，不重复建号。 */
+    /** 开通创作者账号：不再校验入驻审核，仅冻结状态拒绝；已开通则幂等返回。 */
-    @Operation(summary = "开通创作者账号（仅审核通过可开通，幂等）")
+    @Operation(summary = "开通创作者账号（仅冻结状态拒绝，幂等）")
     @PostMapping("/{id}/account")
     @PreAuthorize("@ss.hasPermission('creator:account')")
     @OperationLog(module = "创作者管理", action = "开通创作者账号")

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

@@ -12,6 +12,8 @@ import com.fruitshorts.creator.service.CreatorContentService;
 import com.fruitshorts.creator.vo.CreatorAttachReqVO;
 import com.fruitshorts.creator.vo.CreatorDramaEditReqVO;
 import com.fruitshorts.creator.vo.CreatorEpisodeReqVO;
+import com.fruitshorts.creator.vo.CreatorPublishReqVO;
+import com.fruitshorts.creator.vo.CreatorPublishRespVO;
 import com.fruitshorts.creator.vo.CreatorSubmitReqVO;
 import com.fruitshorts.framework.log.OperationLog;
 import io.swagger.v3.oas.annotations.Operation;
@@ -53,6 +55,15 @@ public class CreatorContentController {
         return Result.ok(creatorContentService.createDrama(req));
     }
 
+    /** 一键发布：建作品 + 建分集 + 绑定视频（可选同时提交审核），一个事务完成。 */
+    @Operation(summary = "一键发布（建作品 / 分集 / 绑定视频 / 可选提交审核）")
+    @PostMapping("/publish")
+    @PreAuthorize("@ss.hasPermission('creator-center:drama:edit')")
+    @OperationLog(module = "创作者中心", action = "一键发布作品")
+    public Result<CreatorPublishRespVO> publish(@Valid @RequestBody CreatorPublishReqVO req) {
+        return Result.ok(creatorContentService.publish(req));
+    }
+
     /** 编辑作品信息（仅草稿 / 已下线可改）。 */
     @Operation(summary = "编辑作品信息（仅草稿 / 已下线可改）")
     @PutMapping("/dramas/{id}")
@@ -101,6 +112,15 @@ public class CreatorContentController {
         return Result.ok();
     }
 
+    @Operation(summary = "删除作品")
+    @DeleteMapping("/dramas/{id}")
+    @PreAuthorize("@ss.hasPermission('creator-center:drama:edit')")
+    @OperationLog(module = "创作者中心", action = "删除作品")
+    public Result<Void> deleteDrama(@PathVariable Long id) {
+        creatorContentService.deleteDrama(id);
+        return Result.ok();
+    }
+
     /** 批量排序：body 里按新顺序给出分集 id。 */
     @Operation(summary = "分集批量排序")
     @PutMapping("/dramas/{id}/episodes/sort")

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

@@ -3,6 +3,9 @@
 package com.fruitshorts.admin.controller;
 
 import com.fruitshorts.admin.service.DashboardService;
+import com.fruitshorts.admin.vo.DashboardDistributionRespVO;
+import com.fruitshorts.admin.vo.DashboardTrendRespVO;
+import com.fruitshorts.admin.vo.TranscodeDashboardRespVO;
 import com.fruitshorts.common.pojo.Result;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.tags.Tag;
@@ -40,7 +43,23 @@ public class DashboardAdminController {
     @Operation(summary = "转码看板（队列积压与失败任务）")
     @GetMapping("/transcode")
     @PreAuthorize("@ss.hasPermission('dashboard:view')")
-    public Result<Map<String, Object>> transcode() {
+    public Result<TranscodeDashboardRespVO> transcode() {
         return Result.ok(dashboardService.transcode());
     }
+
+    /** 近 7 天每日趋势（用户注册 / 播放事件 / 转码任务）。 */
+    @Operation(summary = "大盘趋势（近 7 天每日数据，给折线图用）")
+    @GetMapping("/trend")
+    @PreAuthorize("@ss.hasPermission('dashboard:view')")
+    public Result<DashboardTrendRespVO> trend() {
+        return Result.ok(dashboardService.trend());
+    }
+
+    /** 分布：短剧状态 / 转码状态 / 片源覆盖 / 待处理审核。 */
+    @Operation(summary = "大盘分布（给饼图用）")
+    @GetMapping("/distribution")
+    @PreAuthorize("@ss.hasPermission('dashboard:view')")
+    public Result<DashboardDistributionRespVO> distribution() {
+        return Result.ok(dashboardService.distribution());
+    }
 }

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

@@ -31,14 +31,14 @@ public class DictController {
 
     @Operation(summary = "短剧分类字典")
     @GetMapping("/drama-category")
-    @PreAuthorize("@ss.hasPermission('drama:list')")
+    @PreAuthorize("@ss.hasAnyPermission('drama:list','creator-center:view')")
     public Result<List<DramaCategoryRespVO>> dramaCategories() {
         return Result.ok(dramaCategoryService.list());
     }
 
     @Operation(summary = "内容状态字典")
     @GetMapping("/content-status")
-    @PreAuthorize("@ss.hasPermission('drama:list')")
+    @PreAuthorize("@ss.hasAnyPermission('drama:list','creator-center:view')")
     public Result<List<Map<String, String>>> contentStatus() {
         return Result.ok(Arrays.stream(ContentStatus.values())
                 .map(status -> Map.of("code", status.getCode(), "text", status.getText()))

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

@@ -0,0 +1,126 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.admin.controller;
+
+import com.fruitshorts.common.pojo.PageResult;
+import com.fruitshorts.common.pojo.Result;
+import com.fruitshorts.content.service.DramaClassificationService;
+import com.fruitshorts.content.vo.DramaBriefVO;
+import com.fruitshorts.content.vo.DramaClassificationRespVO;
+import com.fruitshorts.content.vo.DramaClassificationSaveReqVO;
+import com.fruitshorts.content.vo.DramaIdsReqVO;
+import com.fruitshorts.content.vo.DramaRankingItemsReqVO;
+import com.fruitshorts.framework.log.OperationLog;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.validation.Valid;
+import lombok.RequiredArgsConstructor;
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.web.bind.annotation.DeleteMapping;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.PutMapping;
+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.List;
+
+/**
+ * 运营分类管理。分类与短剧类型（drama-categories）是两套独立概念，
+ * 分类可自定义增删，并关联任意多部短剧。
+ */
+@Tag(name = "后台-运营分类")
+@RestController
+@RequestMapping("/admin/drama-classifications")
+@RequiredArgsConstructor
+public class DramaClassificationController {
+
+    private final DramaClassificationService classificationService;
+
+    @Operation(summary = "分类列表（带关联数量）")
+    @GetMapping
+    @PreAuthorize("@ss.hasPermission('drama:list')")
+    public Result<List<DramaClassificationRespVO>> list() {
+        return Result.ok(classificationService.list());
+    }
+
+    @Operation(summary = "新建分类")
+    @PostMapping
+    @PreAuthorize("@ss.hasPermission('drama:create')")
+    @OperationLog(module = "内容管理", action = "新增分类")
+    public Result<Long> create(@Valid @RequestBody DramaClassificationSaveReqVO req) {
+        return Result.ok(classificationService.create(req));
+    }
+
+    @Operation(summary = "编辑分类")
+    @PutMapping("/{id}")
+    @PreAuthorize("@ss.hasPermission('drama:update')")
+    @OperationLog(module = "内容管理", action = "编辑分类")
+    public Result<Void> update(@PathVariable Long id,
+                               @Valid @RequestBody DramaClassificationSaveReqVO req) {
+        classificationService.update(id, req);
+        return Result.ok();
+    }
+
+    @Operation(summary = "删除分类")
+    @DeleteMapping("/{id}")
+    @PreAuthorize("@ss.hasPermission('drama:delete')")
+    @OperationLog(module = "内容管理", action = "删除分类")
+    public Result<Void> delete(@PathVariable Long id) {
+        classificationService.delete(id);
+        return Result.ok();
+    }
+
+    @Operation(summary = "分类下已关联的短剧")
+    @GetMapping("/{id}/dramas")
+    @PreAuthorize("@ss.hasPermission('drama:list')")
+    public Result<PageResult<DramaBriefVO>> dramas(
+            @PathVariable Long id,
+            @RequestParam(required = false) String keyword,
+            @RequestParam(defaultValue = "1") int pageIndex,
+            @RequestParam(defaultValue = "10") int pageSize) {
+        return Result.ok(classificationService.pageDramas(id, keyword, pageIndex, pageSize));
+    }
+
+    @Operation(summary = "尚未关联到该分类的短剧")
+    @GetMapping("/{id}/dramas/candidates")
+    @PreAuthorize("@ss.hasPermission('drama:list')")
+    public Result<PageResult<DramaBriefVO>> candidates(
+            @PathVariable Long id,
+            @RequestParam(required = false) String keyword,
+            @RequestParam(defaultValue = "1") int pageIndex,
+            @RequestParam(defaultValue = "10") int pageSize) {
+        return Result.ok(classificationService.pageCandidates(id, keyword, pageIndex, pageSize));
+    }
+
+    @Operation(summary = "批量关联短剧")
+    @PostMapping("/{id}/dramas")
+    @PreAuthorize("@ss.hasPermission('drama:update')")
+    @OperationLog(module = "内容管理", action = "分类关联短剧")
+    public Result<Integer> bindDramas(@PathVariable Long id,
+                                      @Valid @RequestBody DramaIdsReqVO req) {
+        return Result.ok(classificationService.bindDramas(id, req.getDramaIds()));
+    }
+
+    @Operation(summary = "保存推荐榜完整内容与顺序")
+    @PutMapping("/{id}/ranking-items")
+    @PreAuthorize("@ss.hasPermission('drama:update')")
+    @OperationLog(module = "内容管理", action = "保存推荐榜顺序")
+    public Result<Void> saveRankingItems(@PathVariable Long id,
+                                         @Valid @RequestBody DramaRankingItemsReqVO req) {
+        classificationService.saveRankingItems(id, req.getDramaIds());
+        return Result.ok();
+    }
+
+    @Operation(summary = "移除分类下的短剧")
+    @DeleteMapping("/{id}/dramas/{dramaId}")
+    @PreAuthorize("@ss.hasPermission('drama:update')")
+    @OperationLog(module = "内容管理", action = "分类移除短剧")
+    public Result<Void> unbindDrama(@PathVariable Long id, @PathVariable Long dramaId) {
+        classificationService.unbindDrama(id, dramaId);
+        return Result.ok();
+    }
+}

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 = "新建短剧")
@@ -104,6 +113,15 @@ public class DramaController {
         return Result.ok();
     }
 
+    @Operation(summary = "审核通过并上线")
+    @PostMapping("/{id}/approve-publish")
+    @PreAuthorize("@ss.hasPermission('drama:review')")
+    @OperationLog(module = "内容管理", action = "审核通过并上线")
+    public Result<Void> approvePublish(@PathVariable Long id, @RequestBody(required = false) DramaStatusReqVO req) {
+        changeStatus(id, "APPROVE_PUBLISH", req);
+        return Result.ok();
+    }
+
     @Operation(summary = "上线")
     @PostMapping("/{id}/publish")
     @PreAuthorize("@ss.hasPermission('drama:review')")
@@ -133,4 +151,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/DramaPlaylistCategoryController.java

@@ -0,0 +1,115 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.admin.controller;
+
+import com.fruitshorts.common.pojo.PageResult;
+import com.fruitshorts.common.pojo.Result;
+import com.fruitshorts.content.service.DramaPlaylistCategoryService;
+import com.fruitshorts.content.vo.DramaBriefVO;
+import com.fruitshorts.content.vo.DramaIdsReqVO;
+import com.fruitshorts.content.vo.DramaPlaylistCategoryRespVO;
+import com.fruitshorts.content.vo.DramaPlaylistCategorySaveReqVO;
+import com.fruitshorts.framework.log.OperationLog;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.validation.Valid;
+import lombok.RequiredArgsConstructor;
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.web.bind.annotation.DeleteMapping;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.PutMapping;
+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.List;
+
+/**
+ * 剧单分类管理：分类直接关联短剧，没有「剧单」这一层。
+ * 与「类型」「分类管理」均无关。
+ */
+@Tag(name = "后台-剧单分类")
+@RestController
+@RequestMapping("/admin/drama-playlist-categories")
+@RequiredArgsConstructor
+public class DramaPlaylistCategoryController {
+
+    private final DramaPlaylistCategoryService categoryService;
+
+    @Operation(summary = "剧单分类列表")
+    @GetMapping
+    @PreAuthorize("@ss.hasPermission('drama:list')")
+    public Result<List<DramaPlaylistCategoryRespVO>> list() {
+        return Result.ok(categoryService.list());
+    }
+
+    @Operation(summary = "新建剧单分类")
+    @PostMapping
+    @PreAuthorize("@ss.hasPermission('drama:create')")
+    @OperationLog(module = "内容管理", action = "新增剧单分类")
+    public Result<Long> create(@Valid @RequestBody DramaPlaylistCategorySaveReqVO req) {
+        return Result.ok(categoryService.create(req));
+    }
+
+    @Operation(summary = "编辑剧单分类")
+    @PutMapping("/{id}")
+    @PreAuthorize("@ss.hasPermission('drama:update')")
+    @OperationLog(module = "内容管理", action = "编辑剧单分类")
+    public Result<Void> update(@PathVariable Long id,
+                               @Valid @RequestBody DramaPlaylistCategorySaveReqVO req) {
+        categoryService.update(id, req);
+        return Result.ok();
+    }
+
+    @Operation(summary = "删除剧单分类")
+    @DeleteMapping("/{id}")
+    @PreAuthorize("@ss.hasPermission('drama:delete')")
+    @OperationLog(module = "内容管理", action = "删除剧单分类")
+    public Result<Void> delete(@PathVariable Long id) {
+        categoryService.delete(id);
+        return Result.ok();
+    }
+
+    @Operation(summary = "分类下已关联的短剧")
+    @GetMapping("/{id}/dramas")
+    @PreAuthorize("@ss.hasPermission('drama:list')")
+    public Result<PageResult<DramaBriefVO>> dramas(
+            @PathVariable Long id,
+            @RequestParam(required = false) String keyword,
+            @RequestParam(defaultValue = "1") int pageIndex,
+            @RequestParam(defaultValue = "10") int pageSize) {
+        return Result.ok(categoryService.pageDramas(id, keyword, pageIndex, pageSize));
+    }
+
+    @Operation(summary = "尚未关联到该分类的短剧")
+    @GetMapping("/{id}/dramas/candidates")
+    @PreAuthorize("@ss.hasPermission('drama:list')")
+    public Result<PageResult<DramaBriefVO>> candidates(
+            @PathVariable Long id,
+            @RequestParam(required = false) String keyword,
+            @RequestParam(defaultValue = "1") int pageIndex,
+            @RequestParam(defaultValue = "10") int pageSize) {
+        return Result.ok(categoryService.pageCandidates(id, keyword, pageIndex, pageSize));
+    }
+
+    @Operation(summary = "批量关联短剧")
+    @PostMapping("/{id}/dramas")
+    @PreAuthorize("@ss.hasPermission('drama:update')")
+    @OperationLog(module = "内容管理", action = "剧单分类关联短剧")
+    public Result<Integer> bindDramas(@PathVariable Long id,
+                                      @Valid @RequestBody DramaIdsReqVO req) {
+        return Result.ok(categoryService.bindDramas(id, req.getDramaIds()));
+    }
+
+    @Operation(summary = "移除分类下的短剧")
+    @DeleteMapping("/{id}/dramas/{dramaId}")
+    @PreAuthorize("@ss.hasPermission('drama:update')")
+    @OperationLog(module = "内容管理", action = "剧单分类移除短剧")
+    public Result<Void> unbindDrama(@PathVariable Long id, @PathVariable Long dramaId) {
+        categoryService.unbindDrama(id, dramaId);
+        return Result.ok();
+    }
+}

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

@@ -2,12 +2,16 @@
 
 package com.fruitshorts.admin.controller;
 
+import com.fruitshorts.common.pojo.PageResult;
 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 +28,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 +37,27 @@ import java.util.List;
 public class EpisodeController {
 
     private final EpisodeService episodeService;
+    private final CommentService commentService;
+    private final DramaService dramaService;
 
-    @Operation(summary = "剧集列表")
+    @Operation(summary = "剧集列表（分页）")
     @GetMapping
     @PreAuthorize("@ss.hasPermission('episode:list')")
-    public Result<List<EpisodeRespVO>> list(@RequestParam Long dramaId,
+    public Result<PageResult<EpisodeRespVO>> list(@RequestParam Long dramaId,
-                                            @RequestParam(required = false) String status) {
+                                                  @RequestParam(required = false) String status,
-        return Result.ok(episodeService.listByDrama(dramaId, status));
+                                                  @RequestParam(required = false) Integer pageIndex,
+                                                  @RequestParam(required = false) Integer pageSize) {
+        PageResult<EpisodeRespVO> page = episodeService.pageByDrama(dramaId, status, pageIndex, pageSize);
+        List<EpisodeRespVO> episodes = page.getList();
+        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(new PageResult<>(page.getTotal(), episodes));
     }
 
     @Operation(summary = "新建剧集")

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

@@ -0,0 +1,32 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.admin.controller;
+
+import com.fruitshorts.admin.service.EpisodeTranscodeAdminService;
+import com.fruitshorts.admin.vo.EpisodeTranscodeRespVO;
+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.PathVariable;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+/** 后台剧集转码聚合查询。 */
+@Tag(name = "后台-剧集转码")
+@RestController
+@RequestMapping("/admin/episodes")
+@RequiredArgsConstructor
+public class EpisodeTranscodeController {
+
+    private final EpisodeTranscodeAdminService service;
+
+    @Operation(summary = "查询分集转码聚合信息")
+    @GetMapping("/{id}/transcode")
+    @PreAuthorize("@ss.hasPermission('episode:list')")
+    public Result<EpisodeTranscodeRespVO> detail(@PathVariable Long id) {
+        return Result.ok(service.detail(id));
+    }
+}

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

@@ -0,0 +1,34 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.admin.controller;
+
+import com.fruitshorts.admin.service.FavoriteAdminService;
+import com.fruitshorts.admin.vo.AdminFavoriteVO;
+import com.fruitshorts.admin.vo.FavoriteQueryReqVO;
+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 jakarta.validation.Valid;
+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/favorites")
+@RequiredArgsConstructor
+public class FavoriteAdminController {
+    private final FavoriteAdminService service;
+
+    /** 按用户、设备、内容和时间分页查询收藏。 */
+    @Operation(summary = "收藏列表分页查询")
+    @GetMapping("/page")
+    @PreAuthorize("@ss.hasPermission('favorite:list')")
+    public Result<PageResult<AdminFavoriteVO>> page(@Valid FavoriteQueryReqVO req) {
+        return Result.ok(service.page(req));
+    }
+}

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

@@ -0,0 +1,47 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.admin.controller;
+
+import com.fruitshorts.common.pojo.Result;
+import com.fruitshorts.framework.log.OperationLog;
+import com.fruitshorts.system.service.LegalDocumentService;
+import com.fruitshorts.system.vo.LegalDocumentVO;
+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.PutMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.util.List;
+
+/**
+ * 后台维护服务条款和隐私协议。公开页面由客户端服务按语言输出。
+ */
+@Tag(name = "后台-协议")
+@RestController
+@RequestMapping("/admin/legal-documents")
+@RequiredArgsConstructor
+public class LegalDocumentAdminController {
+
+    private final LegalDocumentService legalDocumentService;
+
+    @Operation(summary = "协议列表（服务条款、隐私协议，各含中英印尼语）")
+    @GetMapping
+    @PreAuthorize("@ss.hasAnyPermission('system:role','system:menu')")
+    public Result<List<LegalDocumentVO>> list() {
+        return Result.ok(legalDocumentService.list());
+    }
+
+    @Operation(summary = "保存协议")
+    @PutMapping
+    @PreAuthorize("@ss.hasPermission('system:role')")
+    @OperationLog(module = "后台管理", action = "修改服务条款或隐私协议")
+    public Result<Void> save(@RequestBody List<LegalDocumentVO> items) {
+        legalDocumentService.save(items);
+        return Result.ok();
+    }
+}

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

@@ -0,0 +1,34 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.admin.controller;
+
+import com.fruitshorts.admin.service.LikeAdminService;
+import com.fruitshorts.admin.vo.AdminLikeVO;
+import com.fruitshorts.admin.vo.LikeQueryReqVO;
+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 jakarta.validation.Valid;
+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/likes")
+@RequiredArgsConstructor
+public class LikeAdminController {
+    private final LikeAdminService service;
+
+    /** 按用户、设备、内容和时间分页查询点赞。 */
+    @Operation(summary = "点赞列表分页查询")
+    @GetMapping("/page")
+    @PreAuthorize("@ss.hasPermission('like:list')")
+    public Result<PageResult<AdminLikeVO>> page(@Valid LikeQueryReqVO req) {
+        return Result.ok(service.page(req));
+    }
+}

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

@@ -5,12 +5,18 @@ package com.fruitshorts.admin.controller;
 import com.fruitshorts.common.pojo.Result;
 import com.fruitshorts.framework.security.SecurityUtils;
 import com.fruitshorts.framework.security.ImpersonationGuard;
+import com.fruitshorts.framework.log.OperationLog;
+import com.fruitshorts.media.config.MediaTranscodeProfile;
 import com.fruitshorts.media.service.MediaService;
+import com.fruitshorts.media.service.MediaTranscodeProfileService;
 import com.fruitshorts.media.vo.MediaAssetRespVO;
+import com.fruitshorts.media.vo.TranscodeTriggerRespVO;
 import com.fruitshorts.media.vo.UploadCompleteReqVO;
 import com.fruitshorts.media.vo.UploadInitReqVO;
 import com.fruitshorts.media.vo.UploadInitRespVO;
 import com.fruitshorts.media.vo.UploadProgressRespVO;
+import com.fruitshorts.admin.service.TranscodeBackfillAdminService;
+import com.fruitshorts.admin.vo.TranscodeBackfillRespVO;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
@@ -19,6 +25,7 @@ import org.springframework.security.access.prepost.PreAuthorize;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.PathVariable;
 import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.PutMapping;
 import org.springframework.web.bind.annotation.RequestBody;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RequestParam;
@@ -35,6 +42,8 @@ import org.springframework.web.multipart.MultipartFile;
 public class MediaController {
 
     private final MediaService mediaService;
+    private final MediaTranscodeProfileService profileService;
+    private final TranscodeBackfillAdminService backfillAdminService;
 
     @Operation(summary = "初始化分片上传")
     @PostMapping("/upload/init")
@@ -78,4 +87,40 @@ public class MediaController {
     public Result<MediaAssetRespVO> get(@PathVariable Long id) {
         return Result.ok(mediaService.get(id));
     }
+
+    @Operation(summary = "手动触发或重转媒资")
+    @PostMapping("/{id}/transcode")
+    @PreAuthorize("@ss.hasPermission('episode:upload')")
+    @OperationLog(module = "后台管理", action = "触发媒资转码")
+    public Result<TranscodeTriggerRespVO> transcode(@PathVariable Long id) {
+        ImpersonationGuard.rejectWrite();
+        return Result.ok(mediaService.triggerTranscode(id));
+    }
+
+    @Operation(summary = "读取转码档位配置")
+    @GetMapping("/transcode-profile")
+    @PreAuthorize("@ss.hasPermission('episode:upload')")
+    public Result<MediaTranscodeProfile> transcodeProfile() {
+        return Result.ok(profileService.readConfiguredProfile());
+    }
+
+    @Operation(summary = "保存转码档位配置")
+    @PutMapping("/transcode-profile")
+    @PreAuthorize("@ss.hasPermission('episode:upload')")
+    @OperationLog(module = "后台管理", action = "修改转码设置")
+    public Result<MediaTranscodeProfile> saveTranscodeProfile(
+            @Valid @RequestBody MediaTranscodeProfile profile) {
+        ImpersonationGuard.rejectWrite();
+        return Result.ok(profileService.save(profile));
+    }
+
+    @Operation(summary = "手动补齐转码：扫描缺产物/帧图的分集并入队")
+    @PostMapping("/transcode/backfill")
+    @PreAuthorize("@ss.hasPermission('episode:upload')")
+    @OperationLog(module = "后台管理", action = "补齐转码")
+    public Result<TranscodeBackfillRespVO> backfill(
+            @RequestParam(value = "batchSize", required = false) Integer batchSize) {
+        ImpersonationGuard.rejectWrite();
+        return Result.ok(backfillAdminService.runOnce(batchSize));
+    }
 }

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

@@ -0,0 +1,46 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.admin.controller;
+
+import com.fruitshorts.common.pojo.Result;
+import com.fruitshorts.media.service.MediaTranscodeOutputService;
+import com.fruitshorts.media.vo.MediaRenditionRespVO;
+import com.fruitshorts.media.vo.MediaThumbnailRespVO;
+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.PathVariable;
+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;
+
+/** 后台媒资转码产物只读查询。 */
+@Tag(name = "后台-媒资转码产物")
+@RestController
+@RequestMapping("/admin/media")
+@RequiredArgsConstructor
+public class MediaTranscodeOutputController {
+
+    private final MediaTranscodeOutputService outputService;
+
+    @Operation(summary = "查询媒资清晰度产物")
+    @GetMapping("/{id}/renditions")
+    @PreAuthorize("@ss.hasPermission('episode:upload')")
+    public Result<List<MediaRenditionRespVO>> renditions(@PathVariable Long id) {
+        return Result.ok(outputService.renditions(id));
+    }
+
+    @Operation(summary = "分页查询媒资帧图产物")
+    @GetMapping("/{id}/thumbnails")
+    @PreAuthorize("@ss.hasPermission('episode:upload')")
+    public Result<MediaThumbnailRespVO> thumbnails(
+            @PathVariable Long id,
+            @RequestParam(defaultValue = "1") Integer pageIndex,
+            @RequestParam(defaultValue = "100") Integer pageSize) {
+        return Result.ok(outputService.thumbnails(id, pageIndex, pageSize));
+    }
+}

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) {
+    public Result<PageResult<AdminReportRespVO>> page(ReportQueryReqVO req) {
-        return Result.ok(reportService.page(req));
+        return Result.ok(reportAdminService.page(req));
     }
 
     /** 处理工单：结论成立会联动驳回被举报评论，可选择同时封禁被举报用户。 */

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

@@ -0,0 +1,171 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.admin.controller;
+
+import com.fruitshorts.commerce.reward.service.RewardCheckinService;
+import com.fruitshorts.commerce.reward.service.RewardActivityAdminService;
+import com.fruitshorts.commerce.reward.service.RewardGrantService;
+import com.fruitshorts.commerce.reward.service.RewardTaskService;
+import com.fruitshorts.commerce.reward.vo.RewardActivityQueryReqVO;
+import com.fruitshorts.commerce.reward.vo.RewardActivityRespVO;
+import com.fruitshorts.commerce.reward.vo.RewardActivitySaveReqVO;
+import com.fruitshorts.commerce.reward.vo.RewardCheckinRuleSaveReqVO;
+import com.fruitshorts.commerce.reward.vo.RewardGrantQueryReqVO;
+import com.fruitshorts.commerce.reward.vo.RewardGrantRespVO;
+import com.fruitshorts.commerce.reward.vo.RewardManualGrantReqVO;
+import com.fruitshorts.commerce.reward.vo.RewardRuleDayVO;
+import com.fruitshorts.commerce.reward.vo.RewardTaskQueryReqVO;
+import com.fruitshorts.commerce.reward.vo.RewardTaskRespVO;
+import com.fruitshorts.commerce.reward.vo.RewardTaskSaveReqVO;
+import com.fruitshorts.common.exception.ErrorCode;
+import com.fruitshorts.common.exception.ServiceException;
+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.user.dal.mapper.AppUserMapper;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.validation.Valid;
+import lombok.RequiredArgsConstructor;
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.validation.annotation.Validated;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.PutMapping;
+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.List;
+
+/** 后台奖励任务、签到规则和发放记录管理。 */
+@Tag(name = "后台-奖励中心")
+@RestController
+@RequestMapping("/admin/rewards")
+@RequiredArgsConstructor
+public class RewardAdminController {
+
+    private final RewardTaskService taskService;
+    private final RewardActivityAdminService activityService;
+    private final RewardCheckinService checkinService;
+    private final RewardGrantService grantService;
+    private final AppUserMapper appUserMapper;
+
+    @Operation(summary = "奖励任务分页")
+    @GetMapping("/tasks/page")
+    @PreAuthorize("@ss.hasPermission('reward:list')")
+    public Result<PageResult<RewardTaskRespVO>> page(@Validated RewardTaskQueryReqVO req) {
+        return Result.ok(taskService.page(req));
+    }
+
+    @Operation(summary = "奖励任务详情")
+    @GetMapping("/tasks/{id}")
+    @PreAuthorize("@ss.hasPermission('reward:list')")
+    public Result<RewardTaskRespVO> detail(@PathVariable Long id) {
+        return Result.ok(taskService.detail(id));
+    }
+
+    @Operation(summary = "新建奖励任务")
+    @PostMapping("/tasks")
+    @PreAuthorize("@ss.hasPermission('reward:update')")
+    @OperationLog(module = "奖励中心", action = "新建奖励任务")
+    public Result<Long> create(@Valid @RequestBody RewardTaskSaveReqVO req) {
+        return Result.ok(taskService.create(req));
+    }
+
+    @Operation(summary = "编辑奖励任务")
+    @PutMapping("/tasks/{id}")
+    @PreAuthorize("@ss.hasPermission('reward:update')")
+    @OperationLog(module = "奖励中心", action = "编辑奖励任务")
+    public Result<Void> update(@PathVariable Long id, @Valid @RequestBody RewardTaskSaveReqVO req) {
+        taskService.update(id, req);
+        return Result.ok();
+    }
+
+    @Operation(summary = "奖励任务上下线")
+    @PutMapping("/tasks/{id}/status")
+    @PreAuthorize("@ss.hasPermission('reward:update')")
+    @OperationLog(module = "奖励中心", action = "奖励任务上下线")
+    public Result<Void> updateStatus(@PathVariable Long id, @RequestParam Integer status) {
+        taskService.updateStatus(id, status);
+        return Result.ok();
+    }
+
+    @Operation(summary = "奖励活动分页")
+    @GetMapping("/activities/page")
+    @PreAuthorize("@ss.hasPermission('reward:list')")
+    public Result<PageResult<RewardActivityRespVO>> activityPage(@Validated RewardActivityQueryReqVO req) {
+        return Result.ok(activityService.page(req));
+    }
+
+    @Operation(summary = "奖励活动详情")
+    @GetMapping("/activities/{id}")
+    @PreAuthorize("@ss.hasPermission('reward:list')")
+    public Result<RewardActivityRespVO> activityDetail(@PathVariable Long id) {
+        return Result.ok(activityService.detail(id));
+    }
+
+    @Operation(summary = "新建奖励活动")
+    @PostMapping("/activities")
+    @PreAuthorize("@ss.hasPermission('reward:update')")
+    @OperationLog(module = "奖励中心", action = "新建奖励活动")
+    public Result<Long> createActivity(@Valid @RequestBody RewardActivitySaveReqVO req) {
+        return Result.ok(activityService.create(req));
+    }
+
+    @Operation(summary = "编辑奖励活动")
+    @PutMapping("/activities/{id}")
+    @PreAuthorize("@ss.hasPermission('reward:update')")
+    @OperationLog(module = "奖励中心", action = "编辑奖励活动")
+    public Result<Void> updateActivity(@PathVariable Long id, @Valid @RequestBody RewardActivitySaveReqVO req) {
+        activityService.update(id, req);
+        return Result.ok();
+    }
+
+    @Operation(summary = "奖励活动上下线")
+    @PutMapping("/activities/{id}/status")
+    @PreAuthorize("@ss.hasPermission('reward:update')")
+    @OperationLog(module = "奖励中心", action = "奖励活动上下线")
+    public Result<Void> updateActivityStatus(@PathVariable Long id, @RequestParam Integer status) {
+        activityService.updateStatus(id, status);
+        return Result.ok();
+    }
+
+    @Operation(summary = "签到规则")
+    @GetMapping("/check-in/rules")
+    @PreAuthorize("@ss.hasPermission('reward:checkin')")
+    public Result<List<RewardRuleDayVO>> rules() {
+        return Result.ok(checkinService.rulesForAdmin());
+    }
+
+    @Operation(summary = "保存签到规则")
+    @PutMapping("/check-in/rules")
+    @PreAuthorize("@ss.hasPermission('reward:checkin')")
+    @OperationLog(module = "奖励中心", action = "保存签到规则")
+    public Result<Void> saveRules(@Valid @RequestBody RewardCheckinRuleSaveReqVO req) {
+        checkinService.saveRules(req);
+        return Result.ok();
+    }
+
+    @Operation(summary = "奖励发放记录分页")
+    @GetMapping("/grants/page")
+    @PreAuthorize("@ss.hasPermission('reward:grant')")
+    public Result<PageResult<RewardGrantRespVO>> grants(@Validated RewardGrantQueryReqVO req) {
+        return Result.ok(grantService.page(req));
+    }
+
+    @Operation(summary = "人工补发奖励")
+    @PostMapping("/grants/manual")
+    @PreAuthorize("@ss.hasPermission('reward:grant')")
+    @OperationLog(module = "奖励中心", action = "人工补发奖励")
+    public Result<RewardGrantRespVO> manualGrant(@Valid @RequestBody RewardManualGrantReqVO req) {
+        if (appUserMapper.selectById(req.getUserId()) == null) {
+            throw new ServiceException(ErrorCode.DATA_NOT_FOUND, "用户不存在，无法补发奖励");
+        }
+        return Result.ok(grantService.manualGrant(req.getUserId(), req.getTaskId(), req.getAmount(),
+                req.getIdempotentKey(), SecurityUtils.getUserId()));
+    }
+}

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

@@ -0,0 +1,33 @@
+// Author: fruit.com.cn
+// 后台转码通知接口。
+
+package com.fruitshorts.admin.controller;
+
+import com.fruitshorts.admin.service.TranscodeNoticeService;
+import com.fruitshorts.admin.vo.TranscodeNoticeRespVO;
+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/notifications")
+@RequiredArgsConstructor
+public class TranscodeNoticeController {
+
+    private final TranscodeNoticeService transcodeNoticeService;
+
+    /** 转码中、成功、失败的角标和最近任务，含短剧与集数。 */
+    @Operation(summary = "转码通知（角标与最近任务）")
+    @GetMapping("/transcode")
+    @PreAuthorize("@ss.hasPermission('drama:list')")
+    public Result<TranscodeNoticeRespVO> transcode() {
+        return Result.ok(transcodeNoticeService.notices());
+    }
+}

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/AppSessionSystemService.java

@@ -0,0 +1,113 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.admin.service;
+
+import com.baomidou.mybatisplus.core.toolkit.Wrappers;
+import com.fruitshorts.user.dal.entity.AppDeviceProfile;
+import com.fruitshorts.user.dal.entity.AppUserSession;
+import com.fruitshorts.user.dal.mapper.AppDeviceProfileMapper;
+import com.fruitshorts.user.dal.mapper.AppUserSessionMapper;
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Service;
+import org.springframework.util.StringUtils;
+
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+
+/**
+ * 按设备画像解析系统，缺画像时回退到用户最近会话。
+ * 设备画像不依赖登录态，游客行为也能显示系统。
+ */
+@Service
+@RequiredArgsConstructor
+public class AppSessionSystemService {
+
+    private final AppUserSessionMapper sessionMapper;
+    private final AppDeviceProfileMapper profileMapper;
+
+    /** 按用户分组，组内按最近活跃倒序。 */
+    public Map<Long, List<AppUserSession>> groupByUser(Collection<Long> userIds) {
+        Map<Long, List<AppUserSession>> grouped = new HashMap<>();
+        if (userIds == null || userIds.isEmpty()) {
+            return grouped;
+        }
+        List<AppUserSession> sessions = sessionMapper.selectList(Wrappers.<AppUserSession>lambdaQuery()
+                .select(AppUserSession::getId, AppUserSession::getUserId, AppUserSession::getDeviceId,
+                        AppUserSession::getPlatform, AppUserSession::getOsVersion,
+                        AppUserSession::getRevokedAt, AppUserSession::getLastActiveAt)
+                .in(AppUserSession::getUserId, userIds)
+                .orderByDesc(AppUserSession::getLastActiveAt)
+                .orderByDesc(AppUserSession::getId));
+        for (AppUserSession session : sessions) {
+            grouped.computeIfAbsent(session.getUserId(), key -> new ArrayList<>()).add(session);
+        }
+        return grouped;
+    }
+
+    /** 按 device_id 批量取设备画像，未建档的设备不出现在结果里。 */
+    public Map<String, AppDeviceProfile> deviceProfiles(Collection<String> deviceIds) {
+        Map<String, AppDeviceProfile> result = new HashMap<>();
+        if (deviceIds == null || deviceIds.isEmpty()) {
+            return result;
+        }
+        List<String> keys = deviceIds.stream()
+                .filter(StringUtils::hasText).map(String::trim).distinct().toList();
+        if (keys.isEmpty()) {
+            return result;
+        }
+        for (AppDeviceProfile profile : profileMapper.selectList(
+                Wrappers.<AppDeviceProfile>lambdaQuery().in(AppDeviceProfile::getDeviceId, keys))) {
+            result.put(profile.getDeviceId(), profile);
+        }
+        return result;
+    }
+
+    /**
+     * 平台筛选的命中范围：设备平台直接给 device_id；登录用户的行为行不带 device_id，
+     * 只能按该用户登录会话的平台判定，两者取并集。
+     */
+    public record PlatformScope(List<String> deviceIds, List<Long> userIds) {
+        public boolean empty() {
+            return deviceIds.isEmpty() && userIds.isEmpty();
+        }
+    }
+
+    /** 按平台解析命中范围；未传平台返回 null 表示不限制。 */
+    public PlatformScope platformScope(String platform) {
+        if (!StringUtils.hasText(platform)) {
+            return null;
+        }
+        String value = platform.trim().toUpperCase(Locale.ROOT);
+        List<String> deviceIds = profileMapper.selectList(Wrappers.<AppDeviceProfile>lambdaQuery()
+                        .select(AppDeviceProfile::getDeviceId)
+                        .eq(AppDeviceProfile::getPlatform, value))
+                .stream().map(AppDeviceProfile::getDeviceId).toList();
+        // 只认「最近一次登录」的平台，与列表里展示的系统保持一致
+        List<Long> userIds = sessionMapper.selectUserIdsByLatestPlatform(value);
+        return new PlatformScope(deviceIds, userIds);
+    }
+
+    /** 观看记录优先匹配同一设备，其次取未吊销会话。 */
+    public AppUserSession match(List<AppUserSession> sessions, String deviceId) {
+        if (sessions == null || sessions.isEmpty()) {
+            return null;
+        }
+        if (StringUtils.hasText(deviceId)) {
+            for (AppUserSession session : sessions) {
+                if (deviceId.equals(session.getDeviceId())) {
+                    return session;
+                }
+            }
+        }
+        for (AppUserSession session : sessions) {
+            if (session.getRevokedAt() == null) {
+                return session;
+            }
+        }
+        return sessions.get(0);
+    }
+}

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

@@ -3,6 +3,9 @@
 package com.fruitshorts.admin.service;
 
 import com.baomidou.mybatisplus.core.toolkit.Wrappers;
+import com.fruitshorts.admin.vo.DashboardDistributionRespVO;
+import com.fruitshorts.admin.vo.DashboardTrendRespVO;
+import com.fruitshorts.admin.vo.TranscodeDashboardRespVO;
 import com.fruitshorts.commerce.dal.entity.CoinLedger;
 import com.fruitshorts.commerce.dal.entity.Entitlement;
 import com.fruitshorts.commerce.dal.entity.Orders;
@@ -21,6 +24,8 @@ import com.fruitshorts.interaction.dal.entity.ContentReport;
 import com.fruitshorts.interaction.dal.mapper.ContentCommentMapper;
 import com.fruitshorts.interaction.dal.mapper.ContentReportMapper;
 import com.fruitshorts.media.service.TranscodeService;
+import com.fruitshorts.media.vo.TranscodeQueueStatsVO;
+import com.fruitshorts.media.vo.TranscodeTaskRespVO;
 import com.fruitshorts.playback.dal.entity.WatchHistory;
 import com.fruitshorts.playback.dal.entity.WatchProgress;
 import com.fruitshorts.playback.dal.mapper.WatchHistoryMapper;
@@ -41,6 +46,8 @@ import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
 
+import org.springframework.jdbc.core.JdbcTemplate;
+
 /**
  * 运营大盘（只读聚合）。
  *
@@ -51,7 +58,11 @@ import java.util.Map;
  * <ul>
  *   <li>用户：`total` = app_user 未删除总数；`newToday`/`new7d` = 按 created_at 落在当天 / 近 7 天；
  *       `active7d` = last_login_at 在近 7 天内（**不是 DAU**：真正的日活需要按天留存登录快照，
- *       当前没有逐日快照数据源，见 notes）；`banned`/`limited` = 按 status 计数。</li>
+ *       当前没有逐日快照数据源，见 notes）；`androidActive7d`/`iosActive7d` =
+ *       `app_user_device` 中状态为 active、近 7 天有心跳的去重设备数；
+ *       `retention1d` = 昨日注册用户中今天仍登录的比例，分母为 0 时返回 null；
+ *       `retention7d` = 8 至 14 天前注册的用户中，近 7 天仍登录的比例，分母为 0 时返回 null；
+ *       `banned`/`limited` = 按 status 计数。</li>
  *   <li>内容：短剧按 status 计数（`reviewing` 视为待审、`published` 视为已上线）；
  *       剧集总数与已上线数；`episodeWithMedia` = video_url 非空的剧集数。</li>
  *   <li>播放：`viewTotal`/`playTotal` = 短剧表上累计计数列的求和（累计口径，不限定时间范围）；
@@ -69,6 +80,9 @@ import java.util.Map;
 public class DashboardService {
 
     private static final int ACTIVE_WINDOW_DAYS = 7;
+    private static final int RETENTION_WINDOW_DAYS = 7;
+    private static final String PLATFORM_ANDROID = "ANDROID";
+    private static final String PLATFORM_IOS = "IOS";
 
     private final AppUserMapper appUserMapper;
     private final AppUserOtpMapper appUserOtpMapper;
@@ -83,6 +97,7 @@ public class DashboardService {
     private final CoinLedgerMapper coinLedgerMapper;
     private final EntitlementMapper entitlementMapper;
     private final TranscodeService transcodeService;
+    private final JdbcTemplate jdbcTemplate;
 
     public Map<String, Object> overview() {
         LocalDateTime now = LocalDateTime.now();
@@ -101,17 +116,71 @@ public class DashboardService {
     }
 
     /** 转码看板：队列积压与失败明细。 */
-    public Map<String, Object> transcode() {
+    public TranscodeDashboardRespVO transcode() {
-        Map<String, Object> data = new LinkedHashMap<>();
+        TranscodeDashboardRespVO data = new TranscodeDashboardRespVO();
-        data.put("generatedAt", LocalDateTime.now());
+        data.setGeneratedAt(LocalDateTime.now());
-        data.put("queue", transcodeService.stats());
+        data.setQueue(transcodeService.stats());
-        data.put("failedTasks", transcodeService.failedTasks(20));
+        data.setFailedTasks(transcodeService.failedTasks(20).stream()
-        data.put("notes", List.of(
+                .map(TranscodeTaskRespVO::from)
+                .toList());
+        data.setNotes(List.of(
                 "queue 为累计口径（不限时间），反映当前积压与历史成败分布",
                 "failedTasks 最多返回 20 条，按 id 倒序"));
         return data;
     }
 
+    /** 近 7 天每日趋势，给折线图用。 */
+    public DashboardTrendRespVO trend() {
+        int days = 7;
+        LocalDate today = LocalDate.now();
+        List<String> dates = new ArrayList<>(days);
+        List<Long> newUsers = new ArrayList<>(days);
+        List<Long> playEvents = new ArrayList<>(days);
+        List<Long> newTranscodes = new ArrayList<>(days);
+        List<Long> transcodeSuccess = new ArrayList<>(days);
+        for (int i = days - 1; i >= 0; i--) {
+            LocalDate d = today.minusDays(i);
+            dates.add(d.toString());
+            newUsers.add(countForDate("SELECT COUNT(*) FROM app_user WHERE deleted = 0 AND DATE(created_at) = ?", d));
+            playEvents.add(countForDate("SELECT COUNT(*) FROM watch_history WHERE DATE(watched_at) = ?", d));
+            newTranscodes.add(countForDate("SELECT COUNT(*) FROM transcode_task WHERE DATE(created_at) = ?", d));
+            transcodeSuccess.add(countForDate("SELECT COUNT(*) FROM transcode_task WHERE status = 'SUCCESS' AND DATE(created_at) = ?", d));
+        }
+        return new DashboardTrendRespVO(dates, newUsers, playEvents, newTranscodes, transcodeSuccess);
+    }
+
+    /** 各域状态分布，给饼图用。 */
+    public DashboardDistributionRespVO distribution() {
+        DashboardDistributionRespVO vo = new DashboardDistributionRespVO();
+        vo.setDramaStatus(groupBy("SELECT status, COUNT(*) FROM drama WHERE deleted = 0 GROUP BY status"));
+        vo.setTranscodeStatus(groupBy("SELECT status, COUNT(*) FROM transcode_task GROUP BY status"));
+        vo.setEpisodeMedia(groupBy("""
+            SELECT CASE WHEN video_url IS NOT NULL AND video_url <> '' THEN '有片源' ELSE '无片源' END AS bucket,
+                   COUNT(*) FROM drama_episode WHERE deleted = 0 GROUP BY bucket"""));
+        List<DashboardDistributionRespVO.Item> pending = new ArrayList<>();
+        pending.add(new DashboardDistributionRespVO.Item("评论待审", orZero(commentMapper.selectCount(
+                Wrappers.<ContentComment>lambdaQuery().eq(ContentComment::getStatus, "pending")))));
+        pending.add(new DashboardDistributionRespVO.Item("举报待处理", orZero(reportMapper.selectCount(
+                Wrappers.<ContentReport>lambdaQuery().eq(ContentReport::getStatus, "pending")))));
+        vo.setPendingModeration(pending);
+        return vo;
+    }
+
+    /** 按日期查计数，空结果返回 0。 */
+    private long countForDate(String sql, LocalDate date) {
+        Long count = jdbcTemplate.queryForObject(sql, Long.class, date);
+        return count == null ? 0L : count;
+    }
+
+    /** 两列 GROUP BY 查询返回 Map<key, count>。 */
+    private Map<String, Long> groupBy(String sql) {
+        Map<String, Long> result = new LinkedHashMap<>();
+        jdbcTemplate.query(sql, rs -> {
+            result.put(rs.getString(1), rs.getLong(2));
+        });
+        return result;
+    }
+
     private Map<String, Object> userMetrics(LocalDateTime todayStart, LocalDateTime sevenDaysAgo) {
         Map<String, Object> user = new LinkedHashMap<>();
         user.put("total", countUser(Wrappers.<AppUser>lambdaQuery()));
@@ -125,9 +194,47 @@ public class DashboardService {
         user.put("limited", countUser(Wrappers.<AppUser>lambdaQuery().eq(AppUser::getStatus, "limited")));
         user.put("deactivated", countUser(Wrappers.<AppUser>lambdaQuery()
                 .eq(AppUser::getStatus, "deactivated")));
+        putActiveDevices(user, sevenDaysAgo);
+        user.put("retention1d", retentionRate(todayStart.minusDays(1), todayStart, todayStart));
+        user.put("retention7d", retentionRate(
+                todayStart.minusDays(RETENTION_WINDOW_DAYS * 2L),
+                todayStart.minusDays(RETENTION_WINDOW_DAYS),
+                sevenDaysAgo));
         return user;
     }
 
+    /** 近 7 天仍活跃的安卓、iOS 设备，按设备号去重。 */
+    private void putActiveDevices(Map<String, Object> user, LocalDateTime since) {
+        Map<String, Long> counts = new LinkedHashMap<>();
+        jdbcTemplate.query("""
+                SELECT UPPER(platform), COUNT(DISTINCT device_id)
+                FROM app_user_device
+                WHERE deleted = 0 AND status = 'active' AND last_seen_at >= ?
+                GROUP BY UPPER(platform)
+                """, rs -> {
+            counts.put(rs.getString(1), rs.getLong(2));
+        }, since);
+        user.put("androidActive7d", counts.getOrDefault(PLATFORM_ANDROID, 0L));
+        user.put("iosActive7d", counts.getOrDefault(PLATFORM_IOS, 0L));
+    }
+
+    /** 队列留存率。注册队列为空时返回 null，避免把没有样本显示成 0%。 */
+    private Double retentionRate(LocalDateTime cohortStart, LocalDateTime cohortEnd, LocalDateTime returnedSince) {
+        Long cohort = jdbcTemplate.queryForObject("""
+                SELECT COUNT(*) FROM app_user
+                WHERE deleted = 0 AND created_at >= ? AND created_at < ?
+                """, Long.class, cohortStart, cohortEnd);
+        if (cohort == null || cohort == 0L) {
+            return null;
+        }
+        Long returned = jdbcTemplate.queryForObject("""
+                SELECT COUNT(*) FROM app_user
+                WHERE deleted = 0 AND created_at >= ? AND created_at < ? AND last_login_at >= ?
+                """, Long.class, cohortStart, cohortEnd, returnedSince);
+        long back = returned == null ? 0L : returned;
+        return Math.round(back * 1000.0 / cohort) / 1000.0;
+    }
+
     private Map<String, Object> contentMetrics() {
         Map<String, Object> content = new LinkedHashMap<>();
         content.put("dramaTotal", dramaMapper.selectCount(null));
@@ -205,12 +312,12 @@ public class DashboardService {
 
     private Map<String, Object> costMetrics(LocalDateTime sevenDaysAgo) {
         Map<String, Object> cost = new LinkedHashMap<>();
-        Map<String, Object> queue = transcodeService.stats();
+        TranscodeQueueStatsVO queue = transcodeService.stats();
-        cost.put("transcodeQueued", queue.get("queued"));
+        cost.put("transcodeQueued", queue.getQueued());
-        cost.put("transcodeRunning", queue.get("running"));
+        cost.put("transcodeRunning", queue.getRunning());
-        cost.put("transcodeFailed", queue.get("failed"));
+        cost.put("transcodeFailed", queue.getFailed());
-        cost.put("transcodeSuccess", queue.get("success"));
+        cost.put("transcodeSuccess", queue.getSuccess());
-        cost.put("renditions", queue.get("renditions"));
+        cost.put("renditions", queue.getRenditions());
         cost.put("otpSent7d", appUserOtpMapper.selectCount(Wrappers.<AppUserOtp>lambdaQuery()
                 .ge(AppUserOtp::getCreatedAt, sevenDaysAgo)));
         cost.put("cdnTrafficBytes", null);
@@ -222,6 +329,8 @@ public class DashboardService {
         List<String> notes = new ArrayList<>();
         notes.add("DAU 暂无数据源：需要按天留存登录快照（ops_daily_stat 已建表但当前无产出），"
                 + "现以 active7d（近 7 天登录过）近似");
+        notes.add("androidActive7d / iosActive7d 是近 7 天 last_seen_at 仍活跃的去重设备，不是安装量");
+        notes.add("retention1d 是昨日注册且今天仍登录的比例；retention7d 是 8 至 14 天前注册、近 7 天仍登录的比例；队列为空时为 null");
         notes.add("CDN 流量与带宽成本暂无数据源：需接入 CDN 账单或访问日志，cdnTrafficBytes 恒为 null");
         notes.add("收入金额在商店未接入前恒为 0：订单表无真实商店订单，金币解锁收入请参考 coinConsumed");
         notes.add("viewTotal/playTotal 是短剧表上的累计计数，与 playEvents7d 的流水口径不可相加");

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

@@ -0,0 +1,147 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.admin.service;
+
+import com.baomidou.mybatisplus.core.toolkit.Wrappers;
+import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
+import com.fruitshorts.admin.vo.EngagementQueryReqVO;
+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.DramaMapper;
+import com.fruitshorts.user.dal.entity.AppDeviceProfile;
+import com.fruitshorts.user.dal.entity.AppUser;
+import com.fruitshorts.user.dal.entity.AppUserSession;
+import com.fruitshorts.user.dal.mapper.AppDeviceProfileMapper;
+import com.fruitshorts.user.dal.mapper.AppUserMapper;
+import com.fruitshorts.user.dal.mapper.AppUserSessionMapper;
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Component;
+import org.springframework.util.StringUtils;
+import java.util.Collection;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+import java.util.Objects;
+import java.util.function.Function;
+import java.util.stream.Collectors;
+
+/** 后台互动列表的分页、预检索及批量资料读取。 */
+@Component
+@RequiredArgsConstructor
+public class EngagementAdminLookup {
+    private static final int DEFAULT_PAGE_SIZE = 10;
+    private static final int MAX_PAGE_SIZE = 100;
+    /**
+     * 关键词预检索的 ID 上限：命中过多时 IN 列表会超出数据库参数上限，
+     * 也说明关键词过于宽泛，直接提示使用者补充条件而不是截断结果。
+     */
+    private static final int MAX_LOOKUP_SIZE = 2000;
+    private static final int LOOKUP_PROBE = MAX_LOOKUP_SIZE + 1;
+    private final AppUserMapper userMapper;
+    private final DramaMapper dramaMapper;
+    private final AppDeviceProfileMapper deviceProfileMapper;
+    private final AppUserSessionMapper sessionMapper;
+    private final AppSessionSystemService sessionSystem;
+
+    /** 规范化页码和页大小。 */
+    public <T> Page<T> page(EngagementQueryReqVO req) {
+        int index = req.getPageIndex() == null ? 1 : Math.max(1, req.getPageIndex());
+        int size = req.getPageSize() == null || req.getPageSize() < 1
+                ? DEFAULT_PAGE_SIZE : Math.min(MAX_PAGE_SIZE, req.getPageSize());
+        return new Page<>(index, size);
+    }
+
+    /** 按 uid 或昵称预检索，未传关键词时不限制用户。 */
+    public List<Long> userIds(String keyword) {
+        if (!StringUtils.hasText(keyword)) {
+            return null;
+        }
+        String value = keyword.trim();
+        List<Long> ids = userMapper.selectList(Wrappers.<AppUser>lambdaQuery().select(AppUser::getId)
+                .and(q -> q.like(AppUser::getUid, value).or().like(AppUser::getNickname, value))
+                .last("LIMIT " + LOOKUP_PROBE))
+                .stream().map(AppUser::getId).toList();
+        return ensureLookupSize(ids, "uid / 昵称");
+    }
+
+    /** 按剧名预检索，未传剧名时不限制短剧。 */
+    public List<Long> dramaIds(String title) {
+        if (!StringUtils.hasText(title)) {
+            return null;
+        }
+        List<Long> ids = dramaMapper.selectList(Wrappers.<Drama>lambdaQuery().select(Drama::getId)
+                .like(Drama::getTitle, title.trim())
+                .last("LIMIT " + LOOKUP_PROBE)).stream().map(Drama::getId).toList();
+        return ensureLookupSize(ids, "短剧名称");
+    }
+
+    /** 命中数量超限时给出可操作的提示，避免把整张表拉进 IN 条件。 */
+    private List<Long> ensureLookupSize(List<Long> ids, String field) {
+        if (ids.size() > MAX_LOOKUP_SIZE) {
+            throw new ServiceException(ErrorCode.BAD_REQUEST,
+                    field + "命中超过 " + MAX_LOOKUP_SIZE + " 条，请使用更精确的筛选条件");
+        }
+        return ids;
+    }
+
+    /** 区分无筛选和有筛选但无匹配。 */
+    public boolean noMatch(List<Long> ids) {
+        return ids != null && ids.isEmpty();
+    }
+
+    /** 按非空去重 ID 批量读取用户，避免游客触发空 IN。 */
+    public Map<Long, AppUser> users(Collection<Long> ids) {
+        List<Long> keys = keys(ids);
+        return keys.isEmpty() ? Map.of() : userMapper.selectBatchIds(keys).stream()
+                .collect(Collectors.toMap(AppUser::getId, Function.identity()));
+    }
+
+    /** 按非空去重 ID 批量读取短剧。 */
+    public Map<Long, Drama> dramas(Collection<Long> ids) {
+        List<Long> keys = keys(ids);
+        return keys.isEmpty() ? Map.of() : dramaMapper.selectBatchIds(keys).stream()
+                .collect(Collectors.toMap(Drama::getId, Function.identity()));
+    }
+
+    /** 按 device_id 批量读取设备画像；游客也有记录，没建档的不返回。 */
+    public Map<String, AppDeviceProfile> deviceProfiles(Collection<String> deviceIds) {
+        List<String> keys = deviceIds.stream().filter(StringUtils::hasText)
+                .map(String::trim).distinct().toList();
+        return keys.isEmpty() ? Map.of() : deviceProfileMapper.selectList(
+                        Wrappers.<AppDeviceProfile>lambdaQuery().in(AppDeviceProfile::getDeviceId, keys))
+                .stream().collect(Collectors.toMap(AppDeviceProfile::getDeviceId,
+                        Function.identity(), (first, second) -> first));
+    }
+
+    /**
+     * 每个用户取最近一次登录会话。
+     * 已登录用户的互动行 device_id 为空（写入时会清空），只能退回会话取系统。
+     */
+    public Map<Long, AppUserSession> latestSessions(Collection<Long> userIds) {
+        List<Long> keys = keys(userIds);
+        if (keys.isEmpty()) {
+            return Map.of();
+        }
+        Map<Long, AppUserSession> result = new HashMap<>();
+        for (AppUserSession session : sessionMapper.selectList(Wrappers.<AppUserSession>lambdaQuery()
+                .select(AppUserSession::getId, AppUserSession::getUserId,
+                        AppUserSession::getPlatform)
+                .in(AppUserSession::getUserId, keys)
+                .orderByDesc(AppUserSession::getLastActiveAt)
+                .orderByDesc(AppUserSession::getId))) {
+            result.putIfAbsent(session.getUserId(), session);
+        }
+        return result;
+    }
+
+    /** 按平台解析命中范围；未传平台返回 null 表示不限制。 */
+    public AppSessionSystemService.PlatformScope platformScope(String platform) {
+        return sessionSystem.platformScope(platform);
+    }
+
+    private List<Long> keys(Collection<Long> ids) {
+        return ids.stream().filter(Objects::nonNull).distinct().toList();
+    }
+}

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

@@ -0,0 +1,103 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.admin.service;
+
+import com.fruitshorts.admin.vo.EpisodeTranscodeRespVO;
+import com.fruitshorts.content.dal.entity.DramaEpisode;
+import com.fruitshorts.content.dal.mapper.DramaEpisodeMapper;
+import com.fruitshorts.media.service.MediaTranscodeOutputService;
+import com.fruitshorts.media.vo.MediaThumbnailRespVO;
+import com.fruitshorts.media.vo.TranscodeTaskRespVO;
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Service;
+import org.springframework.util.StringUtils;
+
+import java.util.List;
+import java.util.Locale;
+
+/** 聚合剧集与媒资转码产物，供后台编辑页一次读取。 */
+@Service
+@RequiredArgsConstructor
+public class EpisodeTranscodeAdminService {
+
+    private static final String STATUS_EPISODE_NOT_FOUND = "EPISODE_NOT_FOUND";
+    private static final String STATUS_NO_VIDEO = "NO_VIDEO";
+    private static final String STATUS_NO_MEDIA_ASSET = "NO_MEDIA_ASSET";
+    private static final String STATUS_NO_TASK = "NO_TASK";
+    private static final String REASON_EPISODE_NOT_FOUND = "分集不存在或已删除";
+    private static final String REASON_NO_VIDEO = "分集未配置视频";
+    private static final String REASON_NO_MEDIA_ASSET = "未找到分集视频对应的媒资";
+    private static final int THUMBNAIL_PAGE_INDEX = 1;
+    private static final int THUMBNAIL_PAGE_SIZE = 100;
+
+    private final DramaEpisodeMapper episodeMapper;
+    private final MediaTranscodeOutputService outputService;
+
+    public EpisodeTranscodeRespVO detail(Long episodeId) {
+        DramaEpisode episode = episodeId == null ? null : episodeMapper.selectById(episodeId);
+        if (episode == null) {
+            return empty(episodeId, STATUS_EPISODE_NOT_FOUND, REASON_EPISODE_NOT_FOUND);
+        }
+        boolean hasVideoAsset = episode.getVideoAssetId() != null
+                && episode.getVideoAssetId() > 0;
+        if (!StringUtils.hasText(episode.getVideoUrl()) && !hasVideoAsset) {
+            return empty(episodeId, STATUS_NO_VIDEO, REASON_NO_VIDEO);
+        }
+        Long mediaAssetId = outputService.resolveMediaAssetId(episode.getVideoUrl());
+        if ((mediaAssetId == null || mediaAssetId <= 0) && hasVideoAsset
+                && outputService.mediaAssetExists(episode.getVideoAssetId())) {
+            mediaAssetId = episode.getVideoAssetId();
+        }
+        if (mediaAssetId == null || mediaAssetId <= 0) {
+            return empty(episodeId, STATUS_NO_MEDIA_ASSET, REASON_NO_MEDIA_ASSET);
+        }
+
+        EpisodeTranscodeRespVO result = new EpisodeTranscodeRespVO();
+        result.setEpisodeId(idString(episodeId));
+        result.setMediaAssetId(idString(mediaAssetId));
+        result.setRenditions(outputService.renditionsForMediaAssetId(mediaAssetId));
+        result.setThumbnails(outputService.thumbnailForEpisode(
+                episodeId, mediaAssetId, THUMBNAIL_PAGE_INDEX, THUMBNAIL_PAGE_SIZE));
+
+        TranscodeTaskRespVO task = outputService.latestTask(mediaAssetId);
+        if (task == null) {
+            result.setStatus(taskStatusOf(episode));
+            result.setProgress(0);
+            result.setRetryCount(0);
+            result.setErrorMsg("");
+            result.setUpdatedAt(episode.getUpdatedAt());
+            return result;
+        }
+        result.setTaskId(idString(task.getId()));
+        result.setStatus(task.getStatus());
+        result.setProgress(task.getProgress());
+        result.setRetryCount(task.getRetryCount());
+        result.setErrorMsg(task.getErrorMsg());
+        result.setUpdatedAt(task.getUpdatedAt());
+        return result;
+    }
+
+    private EpisodeTranscodeRespVO empty(Long episodeId, String status, String reason) {
+        EpisodeTranscodeRespVO result = new EpisodeTranscodeRespVO();
+        result.setEpisodeId(idString(episodeId));
+        result.setStatus(status);
+        result.setProgress(0);
+        result.setRetryCount(0);
+        result.setErrorMsg(reason);
+        result.setRenditions(List.of());
+        result.setThumbnails(MediaThumbnailRespVO.empty(
+                null, episodeId, MediaThumbnailRespVO.STATUS_EMPTY,
+                THUMBNAIL_PAGE_INDEX, THUMBNAIL_PAGE_SIZE));
+        return result;
+    }
+
+    private String idString(Long id) {
+        return id == null ? null : String.valueOf(id);
+    }
+
+    private String taskStatusOf(DramaEpisode episode) {
+        return StringUtils.hasText(episode.getTranscodeStatus())
+                ? episode.getTranscodeStatus().toUpperCase(Locale.ROOT)
+                : STATUS_NO_TASK;
+    }
+}

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

@@ -0,0 +1,117 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.admin.service;
+
+import com.baomidou.mybatisplus.core.toolkit.Wrappers;
+import com.fruitshorts.admin.vo.AdminFavoriteVO;
+import com.fruitshorts.admin.vo.FavoriteQueryReqVO;
+import com.fruitshorts.common.pojo.PageResult;
+import com.fruitshorts.content.dal.entity.Drama;
+import com.fruitshorts.content.enums.ContentStatus;
+import com.fruitshorts.playback.dal.entity.UserFavorite;
+import com.fruitshorts.playback.dal.mapper.UserFavoriteMapper;
+import com.fruitshorts.user.dal.entity.AppDeviceProfile;
+import com.fruitshorts.user.dal.entity.AppUser;
+import com.fruitshorts.user.dal.entity.AppUserSession;
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Service;
+import org.springframework.util.StringUtils;
+import java.util.List;
+import java.util.Map;
+
+/** 后台收藏只读分页及跨域资料装配。 */
+@Service
+@RequiredArgsConstructor
+public class FavoriteAdminService {
+    private final UserFavoriteMapper favoriteMapper;
+    private final EngagementAdminLookup lookup;
+
+    /** 分页查询收藏，预检索无匹配时直接返回空页。 */
+    public PageResult<AdminFavoriteVO> page(FavoriteQueryReqVO req) {
+        List<Long> userIds = lookup.userIds(req.getKeyword());
+        if (lookup.noMatch(userIds)) {
+            return PageResult.empty();
+        }
+        List<Long> dramaIds = lookup.dramaIds(req.getDramaTitle());
+        if (lookup.noMatch(dramaIds)) {
+            return PageResult.empty();
+        }
+        var scope = lookup.platformScope(req.getPlatform());
+        if (scope != null && scope.empty()) {
+            return PageResult.empty();
+        }
+        var query = Wrappers.<UserFavorite>lambdaQuery()
+                .eq(req.getUserId() != null, UserFavorite::getUserId, req.getUserId())
+                .in(userIds != null, UserFavorite::getUserId, userIds)
+                .eq(StringUtils.hasText(req.getDeviceId()), UserFavorite::getDeviceId, req.getDeviceId())
+                .eq(req.getDramaId() != null, UserFavorite::getDramaId, req.getDramaId())
+                .in(dramaIds != null, UserFavorite::getDramaId, dramaIds)
+                .ge(req.getStartTime() != null, UserFavorite::getCreatedAt, req.getStartTime())
+                .le(req.getEndTime() != null, UserFavorite::getCreatedAt, req.getEndTime());
+        // orderBy 必须最后追加，否则条件会被拼到 ORDER BY 后面
+        if (scope != null) {
+            query.and(inner -> {
+                if (!scope.deviceIds().isEmpty()) {
+                    inner.in(UserFavorite::getDeviceId, scope.deviceIds());
+                }
+                if (!scope.userIds().isEmpty()) {
+                    if (!scope.deviceIds().isEmpty()) {
+                        inner.or();
+                    }
+                    inner.in(UserFavorite::getUserId, scope.userIds());
+                }
+            });
+        }
+        query.orderByDesc(UserFavorite::getCreatedAt, UserFavorite::getId);
+        var result = favoriteMapper.selectPage(lookup.page(req), query);
+        return new PageResult<>(result.getTotal(), assemble(result.getRecords()));
+    }
+
+    private List<AdminFavoriteVO> assemble(List<UserFavorite> rows) {
+        if (rows.isEmpty()) {
+            return List.of();
+        }
+        Map<Long, AppUser> users = lookup.users(rows.stream().map(UserFavorite::getUserId).toList());
+        Map<Long, Drama> dramas = lookup.dramas(rows.stream().map(UserFavorite::getDramaId).toList());
+        Map<String, AppDeviceProfile> profiles =
+                lookup.deviceProfiles(rows.stream().map(UserFavorite::getDeviceId).toList());
+        Map<Long, AppUserSession> sessions =
+                lookup.latestSessions(rows.stream().map(UserFavorite::getUserId).toList());
+        return rows.stream().map(row -> toVo(row, row.getUserId() == null ? null : users.get(row.getUserId()),
+                        row.getDramaId() == null ? null : dramas.get(row.getDramaId()),
+                        row.getDeviceId() == null ? null : profiles.get(row.getDeviceId()),
+                        row.getUserId() == null ? null : sessions.get(row.getUserId())))
+                .toList();
+    }
+
+    private AdminFavoriteVO toVo(UserFavorite row, AppUser user, Drama drama,
+                                 AppDeviceProfile profile, AppUserSession session) {
+        AdminFavoriteVO vo = new AdminFavoriteVO();
+        vo.setId(row.getId());
+        vo.setUserId(row.getUserId());
+        vo.setDeviceId(row.getDeviceId());
+        vo.setAnonymous(row.getUserId() == null);
+        if (profile != null) {
+            vo.setPlatform(profile.getPlatform());
+        }
+        // 已登录用户的互动行不带 device_id，设备平台查不到时退回最近一次登录会话
+        if (!StringUtils.hasText(vo.getPlatform()) && session != null) {
+            vo.setPlatform(session.getPlatform());
+        }
+        vo.setDramaId(row.getDramaId());
+        vo.setCreatedAt(row.getCreatedAt());
+        if (user != null) {
+            vo.setUid(user.getUid());
+            vo.setNickname(user.getNickname());
+        }
+        if (drama != null) {
+            vo.setDramaTitle(drama.getTitle());
+            vo.setDramaCover(drama.getCoverUrl());
+            vo.setDramaStatus(drama.getStatus());
+            vo.setDramaPublished(ContentStatus.PUBLISHED.getCode().equals(drama.getStatus()));
+        }
+        // 短剧读不到（已删除或数据异常）时保持 dramaPublished 为 null，
+        // 与「未发布」区分开，前端只在明确 false 时才展示未发布标记。
+        return vo;
+    }
+}

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

@@ -0,0 +1,210 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.admin.service;
+
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.baomidou.mybatisplus.core.toolkit.Wrappers;
+import com.fruitshorts.admin.vo.AdminLikeVO;
+import com.fruitshorts.admin.vo.LikeQueryReqVO;
+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.interaction.dal.entity.ContentComment;
+import com.fruitshorts.interaction.dal.entity.ContentLike;
+import com.fruitshorts.interaction.dal.mapper.ContentCommentMapper;
+import com.fruitshorts.interaction.dal.mapper.ContentLikeMapper;
+import com.fruitshorts.user.dal.entity.AppDeviceProfile;
+import com.fruitshorts.user.dal.entity.AppUser;
+import com.fruitshorts.user.dal.entity.AppUserSession;
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Service;
+import org.springframework.util.StringUtils;
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+import java.util.function.Function;
+import java.util.stream.Collectors;
+
+/** 后台点赞只读分页及多态目标批量装配。 */
+@Service
+@RequiredArgsConstructor
+public class LikeAdminService {
+    private static final String DRAMA = "DRAMA";
+    private static final String EPISODE = "EPISODE";
+    private static final String COMMENT = "COMMENT";
+    private static final int SUMMARY_LENGTH = 30;
+    /**
+     * 点赞目标是多态列（target_type + target_id），按短剧/剧集筛选必须跨表回溯，
+     * 无法用 LambdaQueryWrapper 表达，只能写原生片段。
+     * 维护约定：表名、逻辑删除列与 {@code drama_episode} / {@code content_comment}
+     * 实体上的 @TableName / @TableLogic 保持一致，改表结构时需要同步修改这里。
+     */
+    private static final String DRAMA_MATCH =
+            "(target_type = 'DRAMA' AND target_id = {0}) OR "
+            + "(target_type = 'EPISODE' AND EXISTS (SELECT 1 FROM drama_episode e "
+            + "WHERE e.id = target_id AND e.deleted = 0 AND e.drama_id = {0})) OR "
+            + "(target_type = 'COMMENT' AND EXISTS (SELECT 1 FROM content_comment c "
+            + "WHERE c.id = target_id AND c.deleted = 0 AND c.drama_id = {0}))";
+    private static final String EPISODE_MATCH =
+            "(target_type = 'EPISODE' AND target_id = {0}) OR "
+            + "(target_type = 'COMMENT' AND EXISTS (SELECT 1 FROM content_comment c "
+            + "WHERE c.id = target_id AND c.deleted = 0 AND c.episode_id = {0}))";
+
+    private final ContentLikeMapper likeMapper;
+    private final ContentCommentMapper commentMapper;
+    private final DramaEpisodeMapper episodeMapper;
+    private final EngagementAdminLookup lookup;
+
+    /** 分页查询点赞；短剧及剧集条件在分页之前作用于各类目标。 */
+    public PageResult<AdminLikeVO> page(LikeQueryReqVO req) {
+        List<Long> users = lookup.userIds(req.getKeyword());
+        if (lookup.noMatch(users)) {
+            return PageResult.empty();
+        }
+        List<Long> dramas = lookup.dramaIds(req.getDramaTitle());
+        if (lookup.noMatch(dramas)) {
+            return PageResult.empty();
+        }
+        var query = buildQuery(req, users);
+        var scope = lookup.platformScope(req.getPlatform());
+        if (scope != null && scope.empty()) {
+            return PageResult.empty();
+        }
+        if (scope != null) {
+            query.and(inner -> {
+                if (!scope.deviceIds().isEmpty()) {
+                    inner.in(ContentLike::getDeviceId, scope.deviceIds());
+                }
+                if (!scope.userIds().isEmpty()) {
+                    if (!scope.deviceIds().isEmpty()) {
+                        inner.or();
+                    }
+                    inner.in(ContentLike::getUserId, scope.userIds());
+                }
+            });
+        }
+        if (req.getDramaId() != null) {
+            query.and(q -> q.apply(DRAMA_MATCH, req.getDramaId()));
+        }
+        if (dramas != null) {
+            query.and(q -> {
+                for (Long id : dramas) {
+                    q.or().apply(DRAMA_MATCH, id);
+                }
+            });
+        }
+        if (req.getEpisodeId() != null) {
+            query.and(q -> q.apply(EPISODE_MATCH, req.getEpisodeId()));
+        }
+        // orderBy 必须最后追加，否则条件会被拼到 ORDER BY 后面
+        query.orderByDesc(ContentLike::getCreatedAt, ContentLike::getId);
+        var result = likeMapper.selectPage(lookup.page(req), query);
+        return new PageResult<>(result.getTotal(), assemble(result.getRecords()));
+    }
+
+    private LambdaQueryWrapper<ContentLike> buildQuery(LikeQueryReqVO req, List<Long> users) {
+        return Wrappers.<ContentLike>lambdaQuery()
+                .eq(req.getUserId() != null, ContentLike::getUserId, req.getUserId())
+                .in(users != null, ContentLike::getUserId, users)
+                .eq(StringUtils.hasText(req.getDeviceId()), ContentLike::getDeviceId, req.getDeviceId())
+                .eq(StringUtils.hasText(req.getTargetType()), ContentLike::getTargetType, req.getTargetType())
+                .eq(req.getTargetId() != null, ContentLike::getTargetId, req.getTargetId())
+                .ge(req.getStartTime() != null, ContentLike::getCreatedAt, req.getStartTime())
+                .le(req.getEndTime() != null, ContentLike::getCreatedAt, req.getEndTime());
+    }
+
+    private List<AdminLikeVO> assemble(List<ContentLike> rows) {
+        if (rows.isEmpty()) {
+            return List.of();
+        }
+        Map<Long, AppUser> users = lookup.users(rows.stream().map(ContentLike::getUserId).toList());
+        Map<Long, ContentComment> comments = comments(targetIds(rows, COMMENT));
+        List<Long> episodeIds = new ArrayList<>(targetIds(rows, EPISODE));
+        comments.values().stream().map(ContentComment::getEpisodeId).filter(Objects::nonNull)
+                .forEach(episodeIds::add);
+        Map<Long, DramaEpisode> episodes = episodes(episodeIds);
+        List<Long> dramaIds = new ArrayList<>(targetIds(rows, DRAMA));
+        comments.values().stream().map(ContentComment::getDramaId).filter(Objects::nonNull).forEach(dramaIds::add);
+        episodes.values().stream().map(DramaEpisode::getDramaId).filter(Objects::nonNull).forEach(dramaIds::add);
+        Map<Long, Drama> dramas = lookup.dramas(dramaIds);
+        Map<String, AppDeviceProfile> profiles =
+                lookup.deviceProfiles(rows.stream().map(ContentLike::getDeviceId).toList());
+        Map<Long, AppUserSession> sessions =
+                lookup.latestSessions(rows.stream().map(ContentLike::getUserId).toList());
+        return rows.stream()
+                .map(row -> toVo(row, users, comments, episodes, dramas, profiles, sessions))
+                .toList();
+    }
+
+    private List<Long> targetIds(List<ContentLike> rows, String type) {
+        return rows.stream().filter(row -> type.equals(row.getTargetType())).map(ContentLike::getTargetId)
+                .filter(Objects::nonNull).distinct().toList();
+    }
+
+    private Map<Long, ContentComment> comments(Collection<Long> ids) {
+        return ids.isEmpty() ? Map.of() : commentMapper.selectBatchIds(ids).stream()
+                .collect(Collectors.toMap(ContentComment::getId, Function.identity()));
+    }
+
+    private Map<Long, DramaEpisode> episodes(Collection<Long> ids) {
+        List<Long> keys = ids.stream().filter(Objects::nonNull).distinct().toList();
+        return keys.isEmpty() ? Map.of() : episodeMapper.selectBatchIds(keys).stream()
+                .collect(Collectors.toMap(DramaEpisode::getId, Function.identity()));
+    }
+
+    private AdminLikeVO toVo(ContentLike row, Map<Long, AppUser> users, Map<Long, ContentComment> comments,
+                             Map<Long, DramaEpisode> episodes, Map<Long, Drama> dramas,
+                             Map<String, AppDeviceProfile> profiles,
+                             Map<Long, AppUserSession> sessions) {
+        AdminLikeVO vo = new AdminLikeVO();
+        vo.setId(row.getId());
+        vo.setUserId(row.getUserId());
+        vo.setDeviceId(row.getDeviceId());
+        vo.setAnonymous(row.getUserId() == null);
+        AppDeviceProfile profile = row.getDeviceId() == null ? null : profiles.get(row.getDeviceId());
+        if (profile != null) {
+            vo.setPlatform(profile.getPlatform());
+        }
+        // 已登录用户的互动行不带 device_id，设备平台查不到时退回最近一次登录会话
+        if (!StringUtils.hasText(vo.getPlatform()) && row.getUserId() != null) {
+            AppUserSession session = sessions.get(row.getUserId());
+            if (session != null) {
+                vo.setPlatform(session.getPlatform());
+            }
+        }
+        vo.setTargetType(row.getTargetType());
+        vo.setTargetId(row.getTargetId());
+        vo.setCreatedAt(row.getCreatedAt());
+        AppUser user = row.getUserId() == null ? null : users.get(row.getUserId());
+        if (user != null) {
+            vo.setUid(user.getUid());
+            vo.setNickname(user.getNickname());
+        }
+        ContentComment comment = COMMENT.equals(row.getTargetType()) ? comments.get(row.getTargetId()) : null;
+        Long episodeId = EPISODE.equals(row.getTargetType()) ? row.getTargetId()
+                : comment == null ? null : comment.getEpisodeId();
+        DramaEpisode episode = episodeId == null ? null : episodes.get(episodeId);
+        Long dramaId = DRAMA.equals(row.getTargetType()) ? row.getTargetId()
+                : comment != null ? comment.getDramaId() : episode == null ? null : episode.getDramaId();
+        vo.setEpisodeId(episodeId);
+        vo.setDramaId(dramaId);
+        if (comment != null && comment.getContent() != null) {
+            String content = comment.getContent();
+            int count = content.codePointCount(0, content.length());
+            vo.setCommentSummary(content.substring(0, content.offsetByCodePoints(0, Math.min(count, SUMMARY_LENGTH))));
+        }
+        if (episode != null) {
+            vo.setEpisodeNo(episode.getEpNo());
+            vo.setEpisodeTitle(episode.getTitle());
+        }
+        Drama drama = dramaId == null ? null : dramas.get(dramaId);
+        if (drama != null) {
+            vo.setDramaTitle(drama.getTitle());
+            vo.setDramaCover(drama.getCoverUrl());
+        }
+        return vo;
+    }
+}

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/TranscodeBackfillAdminService.java

@@ -0,0 +1,112 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.admin.service;
+
+import com.fruitshorts.admin.vo.TranscodeBackfillRespVO;
+import com.fruitshorts.content.dal.entity.DramaEpisode;
+import com.fruitshorts.content.dal.mapper.DramaEpisodeMapper;
+import com.fruitshorts.media.config.MediaTranscodeProfile;
+import com.fruitshorts.media.dal.entity.MediaAsset;
+import com.fruitshorts.media.dal.entity.TranscodeTask;
+import com.fruitshorts.media.dal.mapper.MediaAssetMapper;
+import com.fruitshorts.media.service.MediaTranscodeOutputService;
+import com.fruitshorts.media.service.MediaTranscodeProfileService;
+import com.fruitshorts.media.service.TranscodeService;
+import com.fruitshorts.media.vo.TranscodeTriggerRespVO;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Service;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * 手动触发一轮转码补齐巡检：找出"有片源但缺少码率产物或缩略图"的分集并入队。
+ *
+ * <p>与 worker 的定时巡检（TranscodeBackfillScanner）共用同一条候选 SQL 与 trigger 语义；
+ * 区别在于手动触发允许重试最近一次 FAILED 的任务——运营点按钮就是要补齐，包括失败重跑。
+ */
+@Slf4j
+@Service
+@RequiredArgsConstructor
+public class TranscodeBackfillAdminService {
+
+    private static final int MIN_BATCH_SIZE = 1;
+    private static final int MAX_BATCH_SIZE = 100;
+    private static final int DEFAULT_BATCH_SIZE = 20;
+
+    private final DramaEpisodeMapper episodeMapper;
+    private final TranscodeService transcodeService;
+    private final MediaAssetMapper mediaAssetMapper;
+    private final MediaTranscodeOutputService outputService;
+    private final MediaTranscodeProfileService profileService;
+
+    /**
+     * 扫描一批缺产物的分集并入队。
+     *
+     * @param requestedBatchSize 单轮上限，超出范围时收敛到默认值
+     * @return 入队结果与明细
+     */
+    public TranscodeBackfillRespVO runOnce(Integer requestedBatchSize) {
+        int batchSize = normalizeBatchSize(requestedBatchSize);
+        List<DramaEpisode> candidates = episodeMapper.selectTranscodeBackfillCandidates(
+                0L, batchSize, framesRequired());
+        List<TranscodeBackfillRespVO.Item> items = new ArrayList<>();
+        if (candidates == null || candidates.isEmpty()) {
+            return new TranscodeBackfillRespVO(0, items);
+        }
+        for (DramaEpisode episode : candidates) {
+            triggerIfNeeded(episode, items);
+        }
+        log.info("后台手动补齐转码：候选 {} 个，实际入队 {} 个",
+                candidates.size(), items.size());
+        return new TranscodeBackfillRespVO(items.size(), items);
+    }
+
+    private void triggerIfNeeded(DramaEpisode episode,
+                                 List<TranscodeBackfillRespVO.Item> items) {
+        Long mediaAssetId = resolveMediaAssetId(episode);
+        if (mediaAssetId == null) {
+            log.warn("分集 {} 找不到对应媒资，跳过补齐转码", episode.getId());
+            return;
+        }
+        TranscodeTask latest = transcodeService.findLatestTaskByMediaAssetId(mediaAssetId);
+        if (latest != null && (TranscodeService.STATUS_QUEUED.equals(latest.getStatus())
+                || TranscodeService.STATUS_RUNNING.equals(latest.getStatus()))) {
+            return;
+        }
+        MediaAsset asset = mediaAssetMapper.selectById(mediaAssetId);
+        if (asset == null) {
+            log.warn("分集 {} 绑定的媒资 {} 不存在，跳过补齐转码",
+                    episode.getId(), mediaAssetId);
+            return;
+        }
+        TranscodeTriggerRespVO result = transcodeService.trigger(
+                mediaAssetId, asset.getSourceUrl(), episode.getDramaId(), episode.getId());
+        items.add(new TranscodeBackfillRespVO.Item(
+                String.valueOf(episode.getId()),
+                result == null ? "" : String.valueOf(result.getTaskId())));
+    }
+
+    /** 优先用分集已绑定的媒资，老数据没有绑定则按视频地址反查。 */
+    private Long resolveMediaAssetId(DramaEpisode episode) {
+        Long videoAssetId = episode.getVideoAssetId();
+        if (videoAssetId != null && videoAssetId > 0) {
+            return videoAssetId;
+        }
+        return outputService.resolveMediaAssetId(episode.getVideoUrl());
+    }
+
+    /** 关闭雪碧图时不会产出缩略图，此时只看码率产物，避免误判重复转码。 */
+    private boolean framesRequired() {
+        MediaTranscodeProfile profile = profileService.currentProfile();
+        return profile != null && profile.getSprite() != null && profile.getSprite().isEnabled();
+    }
+
+    private int normalizeBatchSize(Integer requestedBatchSize) {
+        if (requestedBatchSize == null || requestedBatchSize <= 0) {
+            return DEFAULT_BATCH_SIZE;
+        }
+        return Math.min(requestedBatchSize, MAX_BATCH_SIZE);
+    }
+}

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

@@ -0,0 +1,84 @@
+// Author: fruit.com.cn
+// 转码通知：按状态计数，并带出短剧与集数。
+
+package com.fruitshorts.admin.service;
+
+import com.fruitshorts.admin.vo.TranscodeNoticeRespVO;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.stereotype.Service;
+
+import java.util.List;
+
+/**
+ * 转码通知。
+ * 转码中、成功、失败分别计数，列表带出短剧名和集数。
+ */
+@Service
+public class TranscodeNoticeService {
+
+    private static final int NOTICE_LIMIT = 20;
+    private static final String STATUS_RUNNING = "RUNNING";
+    private static final String STATUS_SUCCESS = "SUCCESS";
+    private static final String STATUS_FAILED = "FAILED";
+    private static final String UNKNOWN_DRAMA = "未关联短剧";
+
+    private final JdbcTemplate jdbcTemplate;
+
+    public TranscodeNoticeService(JdbcTemplate jdbcTemplate) {
+        this.jdbcTemplate = jdbcTemplate;
+    }
+
+    /** 角标数量和最近 20 条转码中、成功、失败任务。 */
+    public TranscodeNoticeRespVO notices() {
+        TranscodeNoticeRespVO data = new TranscodeNoticeRespVO();
+        fillCounts(data);
+        data.setRunningList(latest(STATUS_RUNNING));
+        data.setSuccessList(latest(STATUS_SUCCESS));
+        data.setFailedList(latest(STATUS_FAILED));
+        return data;
+    }
+
+    private void fillCounts(TranscodeNoticeRespVO data) {
+        jdbcTemplate.query("""
+                SELECT status, COUNT(*)
+                FROM transcode_task
+                WHERE deleted = 0 AND status IN (?, ?, ?)
+                GROUP BY status
+                """, rs -> {
+            long count = rs.getLong(2);
+            switch (rs.getString(1)) {
+                case STATUS_RUNNING -> data.setRunning(count);
+                case STATUS_SUCCESS -> data.setSuccess(count);
+                case STATUS_FAILED -> data.setFailed(count);
+                default -> {
+                }
+            }
+        }, STATUS_RUNNING, STATUS_SUCCESS, STATUS_FAILED);
+    }
+
+    private List<TranscodeNoticeRespVO.Item> latest(String status) {
+        return jdbcTemplate.query("""
+                SELECT t.id, t.status, t.progress, t.error_msg, t.updated_at,
+                       COALESCE(NULLIF(d.title, ''), NULLIF(d2.title, ''), ?) AS drama_title,
+                       e.ep_no, e.title
+                FROM transcode_task t
+                LEFT JOIN drama_episode e ON e.id = t.episode_id AND e.deleted = 0
+                LEFT JOIN drama d ON d.id = t.drama_id AND d.deleted = 0
+                LEFT JOIN drama d2 ON d2.id = e.drama_id AND d2.deleted = 0
+                WHERE t.deleted = 0 AND t.status = ?
+                ORDER BY t.updated_at DESC
+                LIMIT ?
+                """, (rs, row) -> {
+            TranscodeNoticeRespVO.Item item = new TranscodeNoticeRespVO.Item();
+            item.setId(rs.getLong("id"));
+            item.setStatus(rs.getString("status"));
+            item.setProgress(rs.getInt("progress"));
+            item.setErrorMsg(rs.getString("error_msg"));
+            item.setUpdatedAt(rs.getTimestamp("updated_at").toLocalDateTime());
+            item.setDramaTitle(rs.getString("drama_title"));
+            item.setEpisodeNo((Integer) rs.getObject("ep_no"));
+            item.setEpisodeTitle(rs.getString("title"));
+            return item;
+        }, UNKNOWN_DRAMA, status, NOTICE_LIMIT);
+    }
+}

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

@@ -0,0 +1,268 @@
+// 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.exception.ErrorCode;
+import com.fruitshorts.common.exception.ServiceException;
+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.AppDeviceProfile;
+import com.fruitshorts.user.dal.entity.AppUser;
+import com.fruitshorts.user.dal.entity.AppUserSession;
+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;
+import java.util.Objects;
+
+/**
+ * 后台观看记录分页与跨域装配。
+ *
+ * <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 static final int MAX_LOOKUP_SIZE = 2000;
+    private static final int LOOKUP_PROBE = MAX_LOOKUP_SIZE + 1;
+
+    private final WatchHistoryMapper watchHistoryMapper;
+    private final AppUserMapper appUserMapper;
+    private final DramaMapper dramaMapper;
+    private final DramaEpisodeMapper dramaEpisodeMapper;
+    private final AppSessionSystemService sessionSystem;
+
+    /** 按后台筛选条件分页查询观看记录。 */
+    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();
+        }
+        var scope = sessionSystem.platformScope(req.getPlatform());
+        if (scope != null && scope.empty()) {
+            return emptyPage();
+        }
+        IPage<WatchHistory> result = watchHistoryMapper.selectPage(new Page<>(pageIndex, pageSize),
+                buildQuery(req, matchedUserIds, matchedDramaIds, scope));
+        return new PageResult<>(result.getTotal(), toVoList(result.getRecords()));
+    }
+
+    private LambdaQueryWrapper<WatchHistory> buildQuery(WatchHistoryQueryReqVO req,
+                                                        List<Long> matchedUserIds,
+                                                        List<Long> matchedDramaIds,
+                                                        AppSessionSystemService.PlatformScope scope) {
+        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());
+        if (scope != null) {
+            wrapper.and(inner -> {
+                if (!scope.deviceIds().isEmpty()) {
+                    inner.in(WatchHistory::getDeviceId, scope.deviceIds());
+                }
+                if (!scope.userIds().isEmpty()) {
+                    if (!scope.deviceIds().isEmpty()) {
+                        inner.or();
+                    }
+                    inner.in(WatchHistory::getUserId, scope.userIds());
+                }
+            });
+        }
+        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();
+        List<Long> ids = appUserMapper.selectList(Wrappers.<AppUser>lambdaQuery()
+                        .select(AppUser::getId)
+                        .and(query -> query.like(AppUser::getUid, value)
+                                .or()
+                                .like(AppUser::getNickname, value))
+                        .last("LIMIT " + LOOKUP_PROBE))
+                .stream()
+                .map(AppUser::getId)
+                .toList();
+        return ensureLookupSize(ids, "uid / 昵称");
+    }
+
+    private List<Long> searchDramaIds(String dramaTitle) {
+        String value = dramaTitle.trim();
+        List<Long> ids = dramaMapper.selectList(Wrappers.<Drama>lambdaQuery()
+                        .select(Drama::getId)
+                        .like(Drama::getTitle, value)
+                        .last("LIMIT " + LOOKUP_PROBE))
+                .stream()
+                .map(Drama::getId)
+                .toList();
+        return ensureLookupSize(ids, "短剧名称");
+    }
+
+    /** 关键词命中过多时直接提示收窄条件，避免把整张表塞进 IN。 */
+    private List<Long> ensureLookupSize(List<Long> ids, String field) {
+        if (ids.size() > MAX_LOOKUP_SIZE) {
+            throw new ServiceException(ErrorCode.BAD_REQUEST,
+                    field + "命中超过 " + MAX_LOOKUP_SIZE + " 条，请使用更精确的筛选条件");
+        }
+        return ids;
+    }
+
+    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);
+        Map<Long, List<AppUserSession>> sessions = sessionSystem.groupByUser(
+                rows.stream().map(WatchHistory::getUserId).distinct().toList());
+        Map<String, AppDeviceProfile> profiles = sessionSystem.deviceProfiles(
+                rows.stream().map(WatchHistory::getDeviceId).toList());
+        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()),
+                    sessionSystem.match(sessions.get(row.getUserId()), row.getDeviceId()),
+                    profiles.get(row.getDeviceId())));
+        }
+        return list;
+    }
+
+    private Map<Long, AppUser> loadUsers(List<WatchHistory> rows) {
+        Map<Long, AppUser> result = new HashMap<>();
+        List<Long> ids = rows.stream().map(WatchHistory::getUserId).filter(Objects::nonNull).distinct().toList();
+        if (ids.isEmpty()) {
+            return result;
+        }
+        // 列表只需要身份展示字段，避免把整行用户资料拉回来
+        for (AppUser user : appUserMapper.selectList(Wrappers.<AppUser>lambdaQuery()
+                .select(AppUser::getId, AppUser::getUid, AppUser::getNickname)
+                .in(AppUser::getId, 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).filter(Objects::nonNull).distinct().toList();
+        if (ids.isEmpty()) {
+            return result;
+        }
+        for (Drama drama : dramaMapper.selectList(Wrappers.<Drama>lambdaQuery()
+                .select(Drama::getId, Drama::getTitle, Drama::getStatus)
+                .in(Drama::getId, 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).filter(Objects::nonNull).distinct().toList();
+        if (ids.isEmpty()) {
+            return result;
+        }
+        for (DramaEpisode episode : dramaEpisodeMapper.selectList(Wrappers.<DramaEpisode>lambdaQuery()
+                .select(DramaEpisode::getId, DramaEpisode::getDramaId,
+                        DramaEpisode::getEpNo, DramaEpisode::getTitle)
+                .in(DramaEpisode::getId, ids))) {
+            result.put(episode.getId(), episode);
+        }
+        return result;
+    }
+
+    private AdminWatchHistoryVO toVo(WatchHistory row, AppUser user, Drama drama,
+                                     DramaEpisode episode, AppUserSession session,
+                                     AppDeviceProfile profile) {
+        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());
+        // 设备平台不依赖登录态，优先；没有记录（老数据）再回退到登录会话
+        if (profile != null && StringUtils.hasText(profile.getPlatform())) {
+            vo.setPlatform(profile.getPlatform());
+        } else if (session != null) {
+            vo.setPlatform(session.getPlatform());
+            vo.setOsVersion(session.getOsVersion());
+        }
+        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/AdminFavoriteVO.java

@@ -0,0 +1,26 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.admin.vo;
+
+import lombok.Data;
+import java.time.LocalDateTime;
+
+/** 后台收藏只读列表行，保留游客设备信息。 */
+@Data
+public class AdminFavoriteVO {
+    private Long id;
+    private Long userId;
+    private String uid;
+    private String nickname;
+    private String deviceId;
+    /** 客户端平台：ANDROID / IOS / WEB，来自设备平台记录，游客同样有值。 */
+    private String platform;
+    private Boolean anonymous;
+    private Long dramaId;
+    private String dramaTitle;
+    private String dramaCover;
+    private String dramaStatus;
+    /** true=已发布，false=未发布，null=短剧已不存在（不代表未发布）。 */
+    private Boolean dramaPublished;
+    private LocalDateTime createdAt;
+}

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

@@ -0,0 +1,29 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.admin.vo;
+
+import lombok.Data;
+import java.time.LocalDateTime;
+
+/** 后台点赞只读列表行，保留游客设备信息。 */
+@Data
+public class AdminLikeVO {
+    private Long id;
+    private Long userId;
+    private String uid;
+    private String nickname;
+    private String deviceId;
+    /** 客户端平台：ANDROID / IOS / WEB，来自设备平台记录，游客同样有值。 */
+    private String platform;
+    private Boolean anonymous;
+    private Long dramaId;
+    private String dramaTitle;
+    private String dramaCover;
+    private String targetType;
+    private Long targetId;
+    private Long episodeId;
+    private Integer episodeNo;
+    private String episodeTitle;
+    private String commentSummary;
+    private LocalDateTime createdAt;
+}

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,37 @@
+// 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;
+    /** ANDROID / IOS / WEB，来自该次设备的登录会话。 */
+    private String platform;
+    /** 系统版本，例如 Android 16。 */
+    private String osVersion;
+    private LocalDateTime watchedAt;
+}

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

@@ -28,5 +28,9 @@ public class AppUserWatchHistoryVO {
     private Boolean finished;
     private String source;
     private String deviceId;
+    /** ANDROID / IOS / WEB，来自该次设备的登录会话。 */
+    private String platform;
+    /** 系统版本。 */
+    private String osVersion;
     private LocalDateTime watchedAt;
 }

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

@@ -0,0 +1,39 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.admin.vo;
+
+import lombok.AllArgsConstructor;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+import java.util.List;
+import java.util.Map;
+
+/** 运营大盘分布（给饼图用）。 */
+@Data
+@NoArgsConstructor
+@AllArgsConstructor
+public class DashboardDistributionRespVO {
+
+    /** 短剧状态分布：key = 状态码，value = 数量；含 total 汇总。 */
+    private Map<String, Long> dramaStatus;
+
+    /** 转码任务状态分布。 */
+    private Map<String, Long> transcodeStatus;
+
+    /** 有片源 / 无片源剧集分布。 */
+    private Map<String, Long> episodeMedia;
+
+    /** 互动待处理：评论待审、举报待审。 */
+    private List<Item> pendingModeration;
+
+    @Data
+    @NoArgsConstructor
+    @AllArgsConstructor
+    public static class Item {
+
+        private String label;
+
+        private Long value;
+    }
+}

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

@@ -0,0 +1,31 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.admin.vo;
+
+import lombok.AllArgsConstructor;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+import java.util.List;
+
+/** 运营大盘趋势（近 N 天每日数据，给折线图用）。 */
+@Data
+@NoArgsConstructor
+@AllArgsConstructor
+public class DashboardTrendRespVO {
+
+    /** 日期标签，格式 yyyy-MM-dd，从最早到最新。 */
+    private List<String> dates;
+
+    /** 每日新增用户数（与 dates 对齐）。 */
+    private List<Long> newUsers;
+
+    /** 每日播放事件数（watch_history 行数，与 dates 对齐）。 */
+    private List<Long> playEvents;
+
+    /** 每日新增转码任务数（transcode_task 行数，与 dates 对齐）。 */
+    private List<Long> newTranscodes;
+
+    /** 每日转码成功数（与 dates 对齐）。 */
+    private List<Long> transcodeSuccess;
+}

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

@@ -0,0 +1,27 @@
+// 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 EngagementQueryReqVO {
+    private static final int DEFAULT_PAGE_SIZE = 10;
+    private static final String TIME_PATTERN = "yyyy-MM-dd HH:mm:ss";
+    private Integer pageIndex = 1;
+    private Integer pageSize = DEFAULT_PAGE_SIZE;
+    private String keyword;
+    private Long userId;
+    private String deviceId;
+    /** 客户端平台筛选：ANDROID / IOS / WEB，留空不限制。 */
+    private String platform;
+    private String dramaTitle;
+    private Long dramaId;
+    @DateTimeFormat(pattern = TIME_PATTERN)
+    private LocalDateTime startTime;
+    @DateTimeFormat(pattern = TIME_PATTERN)
+    private LocalDateTime endTime;
+}

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

@@ -0,0 +1,28 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.admin.vo;
+
+import com.fruitshorts.media.vo.MediaRenditionRespVO;
+import com.fruitshorts.media.vo.MediaThumbnailRespVO;
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.Data;
+
+import java.time.LocalDateTime;
+import java.util.List;
+
+/** 后台剧集编辑页一次性获取的转码状态。 */
+@Data
+@Schema(description = "分集转码聚合信息")
+public class EpisodeTranscodeRespVO {
+
+    private String episodeId;
+    private String mediaAssetId;
+    private String taskId;
+    private String status;
+    private Integer progress;
+    private Integer retryCount;
+    private String errorMsg;
+    private LocalDateTime updatedAt;
+    private List<MediaRenditionRespVO> renditions = List.of();
+    private MediaThumbnailRespVO thumbnails;
+}

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

@@ -0,0 +1,12 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.admin.vo;
+
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+
+/** 后台收藏分页检索条件。 */
+@Data
+@EqualsAndHashCode(callSuper = true)
+public class FavoriteQueryReqVO extends EngagementQueryReqVO {
+}