feat(catalog): 新增分类推荐榜快照接口

- Drama/DramaSaveReqVO/DramaRespVO 新增 horizontalCover，打通后台上传链路
- AppDramaCardVO/AppDramaDetailVO 新增 coverLandscape
- ProgressRespVO 新增 dramaCoverLandscape，继续观看横幅可直接取横版图

.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,7 @@ data/uploads/*
 
 # 部署用的真实环境变量（含密钥），只提交 .env.example
 .env
+dump.rdb
+
+# 看门狗飞书告警 Webhook，只存在于部署机
+deploy/feishu-webhook.txt

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-安全方案` §三 |
-| 2 | **C3 埋点** | 播放/支付/转化事件 + 数据字典对齐（含 06 的分享埋点） | 任务清单 C3、`api-phase1` §3 |
-| 3 | **Apple IAP 票据校验** | 目前只留端口与枚举，未做真实校验（印尼 iOS 占比低，文档口径为"预留"） | `api-phase1` §1.8 |
-| 4 | **压测** | 目标 `P95 < 50ms`（预热后）；容量口径文档里有两套（"1 万并发"与"2 万并发 + 3000 QPS"），需定稿 | `09-测试计划` §五、`13/14-容量` |
-| 5 | **对账数据源** | 结算金额/手续费/税只能从 Play Console 财务报告取（需报表权限）；当前 `storeAmountSum` 恒为 `null` + `notes` 说明 | B1-2 待确认 |
-| 6 | **退款口径完善** | 部分退款按比例回收、退款实时性（当前由每日对账 + 手动驱动，未接 RTDN 推送） | B1-2 待确认 |
+| 1 | **Apple IAP 票据校验** | 目前只留端口与枚举，未做真实校验（印尼 iOS 占比低，文档口径为"预留"） | `api-phase1` §1.8 |
+| 2 | **压测** | 目标 `P95 < 50ms`（预热后）；容量口径文档里有两套（"1 万并发"与"2 万并发 + 3000 QPS"），需定稿 | `09-测试计划` §五、`13/14-容量` |
+| 3 | **对账数据源** | 结算金额/手续费/税只能从 Play Console 财务报告取（需报表权限）；当前 `storeAmountSum` 恒为 `null` + `notes` 说明 | B1-2 待确认 |
+| 4 | **退款口径完善** | 部分退款按比例回收、退款实时性（当前由每日对账 + 手动驱动，未接 RTDN 推送） | B1-2 待确认 |
 
 ### 二、上线前必补（P0 / Go-No-Go：非研发，但阻塞上线）
 

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,229 @@
+# 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 }
+    $body = @{
+        msg_type = "text"
+        content  = @{ text = "[$title] $msg" }
+    } | ConvertTo-Json -Depth 3
+    try {
+        Invoke-RestMethod -Uri $FeishuWebhook -Method Post -Body $body -ContentType "application/json" -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,10 @@ services:
     env_file: .env
     environment:
       SERVER_PORT: "8081"
-      # 默认连编排里的 db；要连外部库就在 .env 里覆盖 DB_URL
-      DB_URL: ${DB_URL:-jdbc:postgresql://db:5432/${DB_NAME:-fruitshorts}}
+      # 默认连编排里的 db；要连外部库就在 .env 里覆盖 DB_URL。
+      # 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}
@@ -197,9 +199,40 @@ services:
       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:
@@ -227,3 +260,4 @@ volumes:
   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 计数，不新建计数表）。
 
@@ -168,8 +170,9 @@ app.register.max-per-device-per-day
 | GET | `/app/home/feed` | 首页：轮播 + 分区，卡片带 `preview` 可播预览集与 `language` 语种 |
 | GET | `/app/discover/feed` | 发现页分区 |
 | GET | `/app/feed?types=ANIME,LIVE&categoryId=7&cursor=&size=20` | 推荐流；支持内容类型与分类叠加过滤，游标翻页 |
-| GET | `/app/categories` | 已启用首页分类。`name` 为中文，`locales` 为 `{zh,en,id}` |
+| 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 数组，不放查询串。同一组多选为或，组与组之间为且 |
@@ -203,6 +206,10 @@ app.register.max-per-device-per-day
 > 卡片文案只放语言表：`titleLocales`、`synopsisLocales`、`types`、`tagLocales`。
 > `tagColor` 是标签背景色。中文取各表的 `zh`。
 >
+> `tagCode` 是标签语义码（如 `NEW_ARRIVAL`），来自 `content_tag.code`。
+> 客户端按码判断板块（推荐页「上新」横滑），`tagLocales` 只用于展示；
+> 码为空时客户端才退回按文案匹配。后台标签管理可配置该码。
+>
 > 卡片新增 `dramaType`：`ANIME` 表示漫剧，`LIVE` 表示真人剧。
 > 客户端字段仍返回主内容类型；后台多选值保存在 `drama.drama_types`，
 > App 类型筛选按逗号列整词匹配，因此 `ANIME,LIVE` 多标签剧可被任一类型命中。
@@ -216,6 +223,28 @@ app.register.max-per-device-per-day
 > 只返回 `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`；不传或空值返回全部已上线内容。
@@ -460,6 +489,7 @@ app.register.max-per-device-per-day
         "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",
@@ -482,7 +512,8 @@ app.register.max-per-device-per-day
 | --- | --- | --- |
 | `dramaTitle` | string / null | 短剧中文标题，旧客户端回退用 |
 | `titleLocales` | object / null | 短剧标题语言表，key 为 `zh` / `en` / `id`。客户端按当前语言取，没有对应语言时回退 `zh` |
-| `dramaCover` | string / null | 短剧封面 |
+| `dramaCover` | string / null | 短剧竖版封面 |
+| `dramaCoverLandscape` | string / null | 短剧横版封面，供继续观看横幅等横向位使用；为空时客户端回退 `dramaCover` |
 | `episodeNumber` | int / null | 当前续看集号 `ep_no` |
 | `totalEpisodes` | int / null | 短剧总集数 |
 | `viewCount` | Long（JSON 字符串）/ null | 短剧热度，取 `drama.view_count`。`playCount` 是用户自己的播放次数 |
@@ -631,6 +662,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 让客户端自己猜默认值**。
@@ -863,13 +895,13 @@ GET /app/notices?pageIndex=1&pageSize=20
 
 | 方法 | 路径 | 权限点 | 说明 |
 | --- | --- | --- | --- |
-| 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 |
-| GET | `/admin/favorites/page` | `favorite:list` | 收藏只读分页，含游客 |
-| GET | `/admin/likes/page` | `like: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 |
 
 状态处置会**立即吊销该用户全部会话**并写入封禁记录，避免"封了还能用"。
@@ -1260,6 +1292,7 @@ commentSummary,createdAt`。游客的 userId 为空、anonymous 为 true；评
 | 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 部；空数组表示清空 |
 
 **列表响应**
 
@@ -1271,6 +1304,9 @@ commentSummary,createdAt`。游客的 userId 为空、anonymous 为 true；评
     {
       "id": "2112807182243336193",
       "name": "本周必看",
+      "code": "CLASSIFICATION_2112807182243336193",
+      "layoutType": "GRID",
+      "revision": "1",
       "sort": 1,
       "status": 1,
       "dramaCount": 12,
@@ -1286,12 +1322,20 @@ commentSummary,createdAt`。游客的 userId 为空、anonymous 为 true；评
 **新建 / 编辑请求体**
 
 ```json
-{ "name": "本周必看", "sort": 1, "status": 1 }
+{
+  "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`，编辑不传保持原值 |
 
@@ -1305,6 +1349,11 @@ POST /admin/drama-classifications/2112807182243336193/dramas
 返回 `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

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

@@ -9,6 +9,7 @@ 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;
@@ -104,6 +105,16 @@ public class DramaClassificationController {
         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')")

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

@@ -3,7 +3,9 @@
 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;
@@ -13,16 +15,19 @@ 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) {
@@ -31,6 +36,9 @@ public class AppSessionSystemService {
             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));
@@ -40,6 +48,49 @@ public class AppSessionSystemService {
         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()) {

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

@@ -9,13 +9,19 @@ 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;
@@ -35,6 +41,9 @@ public class EngagementAdminLookup {
     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) {
@@ -96,6 +105,42 @@ public class EngagementAdminLookup {
                 .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/FavoriteAdminService.java

@@ -10,7 +10,9 @@ 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;
@@ -34,6 +36,10 @@ public class FavoriteAdminService {
         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)
@@ -41,8 +47,22 @@ public class FavoriteAdminService {
                 .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())
-                .orderByDesc(UserFavorite::getCreatedAt, UserFavorite::getId);
+                .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()));
     }
@@ -53,17 +73,31 @@ public class FavoriteAdminService {
         }
         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.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) {
+    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) {

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

@@ -14,7 +14,9 @@ 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;
@@ -67,6 +69,23 @@ public class LikeAdminService {
             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()));
         }
@@ -80,6 +99,8 @@ public class LikeAdminService {
         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()));
     }
@@ -92,8 +113,7 @@ public class LikeAdminService {
                 .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())
-                .orderByDesc(ContentLike::getCreatedAt, ContentLike::getId);
+                .le(req.getEndTime() != null, ContentLike::getCreatedAt, req.getEndTime());
     }
 
     private List<AdminLikeVO> assemble(List<ContentLike> rows) {
@@ -110,7 +130,13 @@ public class LikeAdminService {
         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);
-        return rows.stream().map(row -> toVo(row, users, comments, episodes, dramas)).toList();
+        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) {
@@ -130,12 +156,25 @@ public class LikeAdminService {
     }
 
     private AdminLikeVO toVo(ContentLike row, Map<Long, AppUser> users, Map<Long, ContentComment> comments,
-                             Map<Long, DramaEpisode> episodes, Map<Long, Drama> dramas) {
+                             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());

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

@@ -8,6 +8,8 @@ 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;
@@ -16,6 +18,7 @@ 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;
@@ -27,6 +30,7 @@ import java.util.ArrayList;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.Objects;
 
 /**
  * 后台观看记录分页与跨域装配。
@@ -42,6 +46,8 @@ public class WatchHistoryAdminService {
     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;
@@ -65,14 +71,19 @@ public class WatchHistoryAdminService {
         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));
+                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) {
+                                                        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)
@@ -82,6 +93,19 @@ public class WatchHistoryAdminService {
                 .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);
@@ -100,24 +124,37 @@ public class WatchHistoryAdminService {
 
     private List<Long> searchUserIds(String keyword) {
         String value = keyword.trim();
-        return appUserMapper.selectList(Wrappers.<AppUser>lambdaQuery()
+        List<Long> ids = appUserMapper.selectList(Wrappers.<AppUser>lambdaQuery()
                         .select(AppUser::getId)
                         .and(query -> query.like(AppUser::getUid, value)
                                 .or()
-                                .like(AppUser::getNickname, value)))
+                                .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();
-        return dramaMapper.selectList(Wrappers.<Drama>lambdaQuery()
+        List<Long> ids = dramaMapper.selectList(Wrappers.<Drama>lambdaQuery()
                         .select(Drama::getId)
-                        .like(Drama::getTitle, value))
+                        .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) {
@@ -129,19 +166,28 @@ public class WatchHistoryAdminService {
         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())));
+                    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).distinct().toList();
-        for (AppUser user : appUserMapper.selectBatchIds(ids)) {
+        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;
@@ -149,8 +195,13 @@ public class WatchHistoryAdminService {
 
     private Map<Long, Drama> loadDramas(List<WatchHistory> rows) {
         Map<Long, Drama> result = new HashMap<>();
-        List<Long> ids = rows.stream().map(WatchHistory::getDramaId).distinct().toList();
-        for (Drama drama : dramaMapper.selectBatchIds(ids)) {
+        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;
@@ -158,15 +209,22 @@ public class WatchHistoryAdminService {
 
     private Map<Long, DramaEpisode> loadEpisodes(List<WatchHistory> rows) {
         Map<Long, DramaEpisode> result = new HashMap<>();
-        List<Long> ids = rows.stream().map(WatchHistory::getEpisodeId).distinct().toList();
-        for (DramaEpisode episode : dramaEpisodeMapper.selectBatchIds(ids)) {
+        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) {
+                                     DramaEpisode episode, AppUserSession session,
+                                     AppDeviceProfile profile) {
         AdminWatchHistoryVO vo = new AdminWatchHistoryVO();
         vo.setId(row.getId());
         vo.setUserId(row.getUserId());
@@ -177,7 +235,10 @@ public class WatchHistoryAdminService {
         vo.setSource(row.getSource());
         vo.setDeviceId(row.getDeviceId());
         vo.setWatchedAt(row.getWatchedAt());
-        if (session != null) {
+        // 设备平台不依赖登录态，优先；没有记录（老数据）再回退到登录会话
+        if (profile != null && StringUtils.hasText(profile.getPlatform())) {
+            vo.setPlatform(profile.getPlatform());
+        } else if (session != null) {
             vo.setPlatform(session.getPlatform());
             vo.setOsVersion(session.getOsVersion());
         }

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

@@ -13,6 +13,8 @@ public class AdminFavoriteVO {
     private String uid;
     private String nickname;
     private String deviceId;
+    /** 客户端平台：ANDROID / IOS / WEB，来自设备平台记录，游客同样有值。 */
+    private String platform;
     private Boolean anonymous;
     private Long dramaId;
     private String dramaTitle;

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

@@ -13,6 +13,8 @@ public class AdminLikeVO {
     private String uid;
     private String nickname;
     private String deviceId;
+    /** 客户端平台：ANDROID / IOS / WEB，来自设备平台记录，游客同样有值。 */
+    private String platform;
     private Boolean anonymous;
     private Long dramaId;
     private String dramaTitle;

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

@@ -16,6 +16,8 @@ public class EngagementQueryReqVO {
     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)

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

@@ -20,6 +20,8 @@ public class WatchHistoryQueryReqVO {
     private String dramaTitle;
     private Long dramaId;
     private Long episodeId;
+    /** 客户端平台筛选：ANDROID / IOS / WEB，留空不限制。 */
+    private String platform;
     private String source;
     private Boolean finished;
 

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

@@ -14,6 +14,12 @@ spring:
     url: ${DB_URL:jdbc:postgresql://127.0.0.1:5432/fruitshorts}
     username: ${DB_USER:fruitshorts}
     password: ${DB_PASSWORD:fruitshorts}
+  data:
+    redis:
+      # 与 app-api 共用同一个 Redis 实例；容器内必须显式指定 host，
+      # 否则 Spring Boot 默认连 127.0.0.1（容器内即自身）导致健康检查报 DOWN。
+      host: ${REDIS_HOST:127.0.0.1}
+      port: ${REDIS_PORT:6379}
   jackson:
     date-format: yyyy-MM-dd HH:mm:ss
     time-zone: Asia/Shanghai
@@ -40,6 +46,11 @@ mybatis-plus:
       datacenter-id: 1
 
 fruitshorts:
+  web:
+    # 可信代理 CIDR 列表（逗号分隔）。默认空 = 永不解析 XFF，直接用 request.getRemoteAddr()。
+    # 配了反代（Nginx/K8s ingress）时填上其 IP 段，才会从 XFF 取最右侧可信一跳。
+    # 生产若开启了 Tomcat RemoteIpValve（prod profile 已配），保持空即可。
+    trusted-proxies: ${FRUITSHORTS_TRUSTED_PROXIES:}
   media:
     # 媒资目录：容器里指向挂载卷；本地默认 ./data/uploads
     root-dir: ${MEDIA_ROOT_DIR:./data/uploads}

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

@@ -13,7 +13,7 @@ import static org.assertj.core.api.Assertions.assertThat;
 /** 观看记录匹配登录系统。 */
 class AppSessionSystemServiceTest {
 
-    private final AppSessionSystemService service = new AppSessionSystemService(null);
+    private final AppSessionSystemService service = new AppSessionSystemService(null, null);
 
     @Test
     void should_use_same_device_session_when_watch_history_has_device() {

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

@@ -199,9 +199,10 @@ class WatchHistoryAdminServiceTest {
     }
 
     private void stubBatchData() {
-        given(appUserMapper.selectBatchIds(any())).willReturn(List.of(user(7L, "Alice")));
-        given(dramaMapper.selectBatchIds(any())).willReturn(List.of(drama(5L, "Signal")));
-        given(dramaEpisodeMapper.selectBatchIds(any())).willReturn(List.of(episode(11L)));
+        // 装配阶段按需列查询，而不是 selectBatchIds，桩法要跟着改
+        given(appUserMapper.selectList(any())).willReturn(List.of(user(7L, "Alice")));
+        given(dramaMapper.selectList(any())).willReturn(List.of(drama(5L, "Signal")));
+        given(dramaEpisodeMapper.selectList(any())).willReturn(List.of(episode(11L)));
     }
 
     @SuppressWarnings("unchecked")

fruitshorts-admin-api/src/test/java/com/fruitshorts/admin/support/ControllerContractSupport.java

@@ -30,7 +30,9 @@ public final class ControllerContractSupport {
     /** 组装一个只含指定控制器与全局异常处理的 MockMvc。 */
     @SuppressWarnings("unchecked")
     public static MockMvc mockMvcOf(Object controller) {
-        AccessDeniedRecorder recorder = new AccessDeniedRecorder(Mockito.mock(ObjectProvider.class));
+        AccessDeniedRecorder recorder = new AccessDeniedRecorder(
+                Mockito.mock(ObjectProvider.class),
+                Mockito.mock(ObjectProvider.class));
         return MockMvcBuilders.standaloneSetup(controller)
                 .setControllerAdvice(new GlobalExceptionHandler(recorder))
                 // 与 Spring Boot 的 Jackson 配置对齐：时间按 ISO 字符串输出而不是数组，

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

@@ -35,13 +35,14 @@ public class AppAuthController {
 
     private final AppOtpService otpService;
     private final AppAuthService authService;
+    private final WebUtils webUtils;
 
     /** 发送验证码。频控在服务端，客户端不需要自己限流。 */
     @Operation(summary = "发送验证码（频控在服务端）")
     @RateLimit(limit = 20, windowSeconds = 60, key = "otp")
     @PostMapping("/otp")
     public Result<Void> sendOtp(@Valid @RequestBody OtpSendReqVO req, HttpServletRequest request) {
-        otpService.send(req, WebUtils.getClientIp(request));
+        otpService.send(req, webUtils.clientIp(request));
         return Result.ok();
     }
 
@@ -50,7 +51,7 @@ public class AppAuthController {
     public Result<TokenRespVO> register(@Valid @RequestBody RegisterReqVO req,
                                         HttpServletRequest request) {
         applyHeaderDeviceId(req, request);
-        return Result.ok(authService.register(req, WebUtils.getClientIp(request)));
+        return Result.ok(authService.register(req, webUtils.clientIp(request)));
     }
 
     @Operation(summary = "登录（验证码或密码）")
@@ -59,7 +60,7 @@ public class AppAuthController {
     public Result<TokenRespVO> login(@Valid @RequestBody LoginReqVO req,
                                      HttpServletRequest request) {
         applyHeaderDeviceId(req, request);
-        return Result.ok(authService.login(req, WebUtils.getClientIp(request)));
+        return Result.ok(authService.login(req, webUtils.clientIp(request)));
     }
 
     @Operation(summary = "Google 登录（未配置 clientId 时返回明确错误）")
@@ -69,7 +70,8 @@ public class AppAuthController {
         String headerDeviceId = request.getHeader("X-Device-Id");
         String deviceId = StringUtils.hasText(headerDeviceId)
                 ? headerDeviceId : req.getDeviceId();
-        return Result.ok(authService.googleLogin(req.getIdToken(), deviceId));
+        return Result.ok(authService.googleLogin(req.getIdToken(), deviceId,
+                webUtils.clientIp(request)));
     }
 
     @Operation(summary = "刷新令牌（旧 refresh token 立即失效）")

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

@@ -3,11 +3,13 @@
 package com.fruitshorts.app.controller;
 
 import com.fruitshorts.app.service.AppCatalogService;
+import com.fruitshorts.app.service.AppRankingService;
 import com.fruitshorts.app.vo.AppCategoryVO;
 import com.fruitshorts.app.vo.AppDramaPageReqVO;
 import com.fruitshorts.app.vo.AppFeedVO;
 import com.fruitshorts.app.vo.AppDramaCardVO;
 import com.fruitshorts.app.vo.AppPlaylistDetailVO;
+import com.fruitshorts.app.vo.AppRankingVO;
 import com.fruitshorts.common.pojo.CursorResult;
 import com.fruitshorts.common.pojo.PageResult;
 import com.fruitshorts.common.pojo.Result;
@@ -37,6 +39,7 @@ public class AppCatalogController {
     private static final int DRAMA_PAGE_SIZE = 20;
 
     private final AppCatalogService appCatalogService;
+    private final AppRankingService appRankingService;
 
     @Operation(summary = "首页聚合：轮播 + 分区，一次请求渲染整页")
     @GetMapping("/home/feed")
@@ -75,6 +78,12 @@ public class AppCatalogController {
         return Result.ok(appCatalogService.categoryDramas(id, pageIndex, pageSize));
     }
 
+    @Operation(summary = "推荐榜：按后台配置顺序返回榜单快照")
+    @GetMapping("/categories/{id}/ranking")
+    public Result<AppRankingVO> categoryRanking(@PathVariable Long id) {
+        return Result.ok(appRankingService.ranking(id));
+    }
+
     @Operation(summary = "已启用类型")
     @GetMapping("/drama-categories")
     public Result<List<AppCategoryVO>> dramaCategories() {

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

@@ -48,6 +48,7 @@ public class AppCommentController {
     private final EpisodeService episodeService;
     private final InteractionIdentityResolver identityResolver;
     private final AnonymousInteractionRateLimiter anonymousRateLimiter;
+    private final WebUtils webUtils;
 
     @Operation(summary = "发布评论")
     @PostMapping
@@ -59,7 +60,7 @@ public class AppCommentController {
                 req.getDeviceId());
         anonymousRateLimiter.check(identity, "comment");
         return Result.ok(commentService.publish(
-                identity, req, WebUtils.getClientIp(request)));
+                identity, req, webUtils.clientIp(request)));
     }
 
     @Operation(summary = "评论列表（游标翻页，可匿名浏览）")

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

@@ -37,6 +37,7 @@ public class AppDramaController {
     private final EpisodeService episodeService;
     private final CommentService commentService;
     private final AppEpisodeStatsService appEpisodeStatsService;
+    private final WebUtils webUtils;
 
     /** 详情：包含剧集列表，客户端进详情页一次请求即可渲染 */
     @Operation(summary = "短剧详情（含剧集列表，进详情页一次请求即可渲染）")
@@ -56,7 +57,7 @@ public class AppDramaController {
                 SecurityUtils.getUserIdOrNull(),
                 id,
                 request.getHeader("X-Device-Id"),
-                WebUtils.getClientIp(request));
+                webUtils.clientIp(request));
         DramaEpisode episode = episodeService.getExisting(id);
         vo.setLikeCount(episode.getLikeCount() == null ? 0L : episode.getLikeCount());
         vo.setCommentCount(commentService.countByEpisodes(List.of(id)).getOrDefault(id, 0L));

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

@@ -25,11 +25,12 @@ import org.springframework.web.bind.annotation.RestController;
 public class AppEventController {
 
     private final AppEventService eventService;
+    private final WebUtils webUtils;
 
     @Operation(summary = "埋点事件批量上报")
     @PostMapping("/events")
     public Result<Void> report(@Valid @RequestBody AppEventReqVO req, HttpServletRequest request) {
-        eventService.save(req, SecurityUtils.getUserIdOrNull(), WebUtils.getClientIp(request));
+        eventService.save(req, SecurityUtils.getUserIdOrNull(), webUtils.clientIp(request));
         return Result.ok();
     }
 }

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

@@ -34,7 +34,6 @@ import org.springframework.stereotype.Service;
 
 import java.util.ArrayList;
 import java.util.HashMap;
-import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
 import java.util.Arrays;
@@ -93,6 +92,11 @@ public class AppCatalogService {
                             c.getNameLocales(), c.getName(), c.getNameEn(), c.getNameId());
                     AppCategoryVO vo = new AppCategoryVO(c.getId(), ContentLocaleTexts.value(locales, ContentLocaleTexts.ZH));
                     vo.setLocales(locales);
+                    vo.setCode(c.getCode());
+                    vo.setLayoutType(c.getLayoutType() == null
+                            ? DramaClassificationService.LAYOUT_GRID
+                            : c.getLayoutType());
+                    vo.setRevision(c.getRevision() == null ? 1L : c.getRevision());
                     return vo;
                 })
                 .toList();
@@ -206,6 +210,7 @@ public class AppCatalogService {
         detail.setTitleLocales(titles);
         detail.setSynopsisLocales(synopses);
         detail.setCover(drama.getCoverUrl());
+        detail.setCoverLandscape(drama.getHorizontalCoverUrl());
         detail.setTypes(types);
         fillDetailTag(detail, drama);
         detail.setTotalEpisodes(drama.getTotalEpisodes());
@@ -348,7 +353,8 @@ public class AppCatalogService {
                 drama.getSynopsisLocales(), drama.getSynopsis(), null, null);
         card.setTitleLocales(titles);
         card.setCover(drama.getCoverUrl());
-        card.setSynopsisLocales(shortLocales(synopses));
+        card.setCoverLandscape(drama.getHorizontalCoverUrl());
+        card.setSynopsisLocales(synopses);
         card.setTypes(types);
         fillTag(card, drama, tags);
         card.setTotalEpisodes(drama.getTotalEpisodes());
@@ -411,6 +417,7 @@ public class AppCatalogService {
         ContentTag tag = tagOf(drama, tags);
         Map<String, String> locales = tagLocales(tag);
         card.setTagLocales(locales);
+        card.setTagCode(tagCode(tag));
         card.setTagColor(tag == null ? "" : tag.getBgColor());
     }
 
@@ -418,9 +425,18 @@ public class AppCatalogService {
         ContentTag tag = tagOf(drama, loadTags(List.of(drama)));
         Map<String, String> locales = tagLocales(tag);
         detail.setTagLocales(locales);
+        detail.setTagCode(tagCode(tag));
         detail.setTagColor(tag == null ? "" : tag.getBgColor());
     }
 
+    /** 语义码直接下发，客户端据此判断板块；未配置时给空串，由客户端按文案兜底。 */
+    private String tagCode(ContentTag tag) {
+        if (tag == null || tag.getCode() == null) {
+            return "";
+        }
+        return tag.getCode().trim();
+    }
+
     private ContentTag tagOf(Drama drama, Map<Long, ContentTag> tags) {
         if (drama.getTagId() == null || drama.getTagId() <= 0L) {
             return null;
@@ -439,20 +455,4 @@ public class AppCatalogService {
         return dramaCategoryService.localeMap();
     }
 
-    /** 卡片只带一句简介，避免列表响应体过大 */
-    private Map<String, String> shortLocales(Map<String, String> locales) {
-        Map<String, String> result = new LinkedHashMap<>();
-        if (locales == null) {
-            return result;
-        }
-        locales.forEach((code, text) -> result.put(code, shortSynopsis(text)));
-        return result;
-    }
-
-    private String shortSynopsis(String synopsis) {
-        if (synopsis == null) {
-            return "";
-        }
-        return synopsis.length() <= 60 ? synopsis : synopsis.substring(0, 60);
-    }
 }

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

@@ -35,6 +35,7 @@ public class AppConfigService {
         KEYS.put("noticeEnabled", new KeySpec("app.notice.enabled", "true"));
         KEYS.put("coinUnlockEnabled", new KeySpec("app.coin.unlock.enabled", "true"));
         KEYS.put("downloadEnabled", new KeySpec("app.download.enabled", "true"));
+        KEYS.put("loginBackgroundUrl", new KeySpec("app.login.background.url", ""));
     }
 
     private final SysConfigMapper sysConfigMapper;

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

@@ -0,0 +1,79 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.app.service;
+
+import com.fruitshorts.app.vo.AppDramaCardVO;
+import com.fruitshorts.app.vo.AppRankingEntryVO;
+import com.fruitshorts.app.vo.AppRankingVO;
+import com.fruitshorts.common.exception.ErrorCode;
+import com.fruitshorts.common.exception.ServiceException;
+import com.fruitshorts.content.dal.entity.Drama;
+import com.fruitshorts.content.service.ContentLocaleTexts;
+import com.fruitshorts.content.service.DramaClassificationService;
+import com.fruitshorts.content.service.DramaService;
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Service;
+
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+/** C 端推荐榜快照组装。 */
+@Service
+@RequiredArgsConstructor
+public class AppRankingService {
+
+    private static final int MAX_RANKING_ITEMS = 50;
+
+    private final DramaClassificationService classificationService;
+    private final DramaService dramaService;
+    private final AppCatalogService catalogService;
+
+    /** 过滤未上线短剧后保持后台位置，排名连续补齐。 */
+    public AppRankingVO ranking(Long classificationId) {
+        var classification = classificationService.getEnabledById(classificationId);
+        if (!DramaClassificationService.LAYOUT_RANKING.equals(classification.getLayoutType())) {
+            throw new ServiceException(ErrorCode.OPERATION_NOT_ALLOWED, "该分类不是推荐榜");
+        }
+        List<Long> ids = classificationService.listDramaIdsByClassification(classificationId);
+        List<Drama> ordered = orderedPublished(ids).stream().limit(MAX_RANKING_ITEMS).toList();
+        List<AppDramaCardVO> cards = catalogService.toCards(ordered);
+        List<AppRankingEntryVO> entries = entries(cards);
+        Map<String, String> locales = ContentLocaleTexts.read(
+                classification.getNameLocales(), classification.getName(),
+                classification.getNameEn(), classification.getNameId());
+        AppRankingVO ranking = new AppRankingVO();
+        ranking.setId(classification.getId());
+        ranking.setCode(classification.getCode());
+        ranking.setLocales(locales);
+        ranking.setRevision(classification.getRevision() == null ? 1L : classification.getRevision());
+        ranking.setGeneratedAt(classification.getUpdatedAt());
+        ranking.setTotal(entries.size());
+        ranking.setList(entries);
+        return ranking;
+    }
+
+    private List<AppRankingEntryVO> entries(List<AppDramaCardVO> cards) {
+        List<AppRankingEntryVO> entries = new ArrayList<>();
+        for (int index = 0; index < cards.size(); index++) {
+            entries.add(new AppRankingEntryVO(index + 1, cards.get(index)));
+        }
+        return entries;
+    }
+
+    private List<Drama> orderedPublished(List<Long> ids) {
+        if (ids.isEmpty()) {
+            return List.of();
+        }
+        Map<Long, Integer> positions = new HashMap<>();
+        for (int index = 0; index < ids.size(); index++) {
+            positions.put(ids.get(index), index);
+        }
+        return dramaService.listPublishedByIds(ids).stream()
+                .sorted((left, right) -> Integer.compare(
+                        positions.getOrDefault(left.getId(), Integer.MAX_VALUE),
+                        positions.getOrDefault(right.getId(), Integer.MAX_VALUE)))
+                .toList();
+    }
+}

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

@@ -11,10 +11,15 @@ import java.util.Map;
 public class AppCategoryVO {
 
     private Long id;
+    private String code;
+    private String layoutType;
+    private Long revision;
     private Map<String, String> locales;
 
     public AppCategoryVO(Long id, String name) {
         this.id = id;
+        this.layoutType = "GRID";
+        this.revision = 1L;
         this.locales = name == null || name.isBlank() ? Map.of() : Map.of("zh", name);
     }
 }

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

@@ -15,11 +15,15 @@ public class AppDramaCardVO {
     private Long id;
     private Map<String, String> titleLocales;
     private String cover;
+    /** 横版封面（16:9），横幅等横向位优先用它；空串表示未上传，客户端回退竖版。 */
+    private String coverLandscape;
     private Map<String, String> synopsisLocales;
     /** 短剧选中的全部类型，每项是一份语言表。 */
     private List<Map<String, String>> types;
     /** 标签语言表，key 为 zh / en / id。 */
     private Map<String, String> tagLocales;
+    /** 标签语义码，如 NEW_ARRIVAL；客户端按码判断板块，文案仅用于展示。 */
+    private String tagCode;
     /** 标签角标背景色，#RRGGBB。 */
     private String tagColor;
     private Integer totalEpisodes;

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

@@ -14,8 +14,12 @@ public class AppDramaDetailVO {
     private Map<String, String> titleLocales;
     private Map<String, String> synopsisLocales;
     private String cover;
+    /** 横版封面（16:9）；空串表示未上传。 */
+    private String coverLandscape;
     private List<Map<String, String>> types;
     private Map<String, String> tagLocales;
+    /** 标签语义码，如 NEW_ARRIVAL；空表示未配置。 */
+    private String tagCode;
     private String tagColor;
     private Integer totalEpisodes;
     private Integer freeEpisodes;

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

@@ -0,0 +1,15 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.app.vo;
+
+import lombok.AllArgsConstructor;
+import lombok.Data;
+
+/** 推荐榜单项，排名由服务端确定。 */
+@Data
+@AllArgsConstructor
+public class AppRankingEntryVO {
+
+    private Integer rank;
+    private AppDramaCardVO drama;
+}

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

@@ -0,0 +1,22 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.app.vo;
+
+import lombok.Data;
+
+import java.time.LocalDateTime;
+import java.util.List;
+import java.util.Map;
+
+/** 推荐榜快照。 */
+@Data
+public class AppRankingVO {
+
+    private Long id;
+    private String code;
+    private Map<String, String> locales;
+    private Long revision;
+    private LocalDateTime generatedAt;
+    private Integer total;
+    private List<AppRankingEntryVO> list;
+}

fruitshorts-app-api/src/main/java/com/fruitshorts/app/web/DeviceProfileFilter.java

@@ -0,0 +1,66 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.app.web;
+
+import com.fruitshorts.user.service.DeviceProfileService;
+import jakarta.servlet.FilterChain;
+import jakarta.servlet.ServletException;
+import jakarta.servlet.http.HttpServletRequest;
+import jakarta.servlet.http.HttpServletResponse;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Component;
+import org.springframework.util.StringUtils;
+import org.springframework.web.filter.OncePerRequestFilter;
+
+import java.io.IOException;
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+
+/**
+ * 收集客户端上报的平台（iOS / Android）。
+ *
+ * <p>客户端在请求头带 `X-Client-Platform`，这里按 device_id 建档，
+ * 后台列表据此区分两端；游客请求同样入库，这是与旧会话方案的关键差异。
+ * 同一设备 60 秒内只写一次，避免每个请求都打库。
+ */
+@Slf4j
+@Component
+@RequiredArgsConstructor
+public class DeviceProfileFilter extends OncePerRequestFilter {
+
+    private static final long THROTTLE_MS = 60_000L;
+    private static final int MAX_TRACKED_DEVICES = 20_000;
+
+    private final DeviceProfileService deviceProfileService;
+    private final Map<String, Long> lastWriteAt = new ConcurrentHashMap<>();
+
+    @Override
+    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response,
+                                    FilterChain filterChain) throws ServletException, IOException {
+        try {
+            collect(request);
+        } catch (RuntimeException ex) {
+            // 画像只服务于后台展示，任何异常都不能影响业务请求
+            log.warn("device-profile collect failed reason={}", ex.getMessage());
+        }
+        filterChain.doFilter(request, response);
+    }
+
+    private void collect(HttpServletRequest request) {
+        String deviceId = request.getHeader("X-Device-Id");
+        if (!StringUtils.hasText(deviceId)) {
+            return;
+        }
+        long now = System.currentTimeMillis();
+        Long last = lastWriteAt.get(deviceId);
+        if (last != null && now - last < THROTTLE_MS) {
+            return;
+        }
+        if (lastWriteAt.size() > MAX_TRACKED_DEVICES) {
+            lastWriteAt.clear();
+        }
+        lastWriteAt.put(deviceId, now);
+        deviceProfileService.touch(deviceId, request.getHeader("X-Client-Platform"));
+    }
+}

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

@@ -23,6 +23,13 @@ fruitshorts:
   cors:
     # 生产只允许显式配置的来源；没配就等于空，浏览器侧会被拦住（比"*"安全）
     allowed-origins: ${CORS_ALLOWED_ORIGINS:}
+  watch-progress:
+    # 观看进度写缓冲：POST 先写 Redis 立即返回，后台任务批量合并进 watch_progress。
+    # 消化能力 = batch-size / interval ≈ 5000 条/秒，覆盖 30 万 DAU 峰值 ~3700 条/秒上报。
+    # 关掉（false）即回退同步写库，接口契约不变。
+    buffer: true
+    flush-interval-ms: 2000
+    flush-batch-size: 10000
 
 springdoc:
   # 生产只留机器可读契约，关掉 UI（doc.html 不对外开放）

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

@@ -11,13 +11,22 @@ spring:
   datasource:
     driver-class-name: org.postgresql.Driver
     # 地址必须外置：不同环境（本机 / 测试 / 生产）连的库不一样，
-    # 生产请用 DB_URL 注入（prod profile 会校验它非空）
-    url: ${DB_URL:jdbc:postgresql://127.0.0.1:5432/fruitshorts}
+    # 生产请用 DB_URL 注入（prod profile 会校验它非空）。
+    # reWriteBatchedInserts：pgjdbc 把批内多条 INSERT 重写成多值 INSERT，
+    # 观看进度缓冲落库依赖它才能跑满批量吞吐。
+    url: ${DB_URL:jdbc:postgresql://127.0.0.1:5432/fruitshorts?reWriteBatchedInserts=true}
     username: ${DB_USER:fruitshorts}
     password: ${DB_PASSWORD:fruitshorts}
   jackson:
     date-format: yyyy-MM-dd HH:mm:ss
     time-zone: Asia/Shanghai
+  task:
+    scheduling:
+      # 默认调度池只有 1 条线程：观看进度落库（每 2s）会和其他定时任务互相排队，
+      # 落库一旦拖慢就会连带推迟对时延敏感的任务，必须给池子多几条线程。
+      pool:
+        size: 4
+      thread-name-prefix: fruitshorts-sched-
   data:
     redis:
       host: ${REDIS_HOST:127.0.0.1}
@@ -47,6 +56,11 @@ springdoc:
     path: /v3/api-docs
 
 fruitshorts:
+  web:
+    # 可信代理 CIDR 列表（逗号分隔）。默认空 = 永不解析 XFF，直接用 request.getRemoteAddr()。
+    # 配了反代（Nginx/K8s ingress）时填上其 IP 段，才会从 XFF 取最右侧可信一跳。
+    # 生产若开启了 Tomcat RemoteIpValve（prod profile 已配），保持空即可。
+    trusted-proxies: ${FRUITSHORTS_TRUSTED_PROXIES:}
   auth:
     # 仅作 sys_config 缺失/非法时的兜底；运行时优先读取后台「系统配置」
     register-max-per-ip-per-day: ${REGISTER_MAX_PER_IP_PER_DAY:5}

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

@@ -4,6 +4,7 @@ package com.fruitshorts.app.controller;
 import com.fruitshorts.app.support.ControllerContractSupport;
 import com.fruitshorts.common.exception.ErrorCode;
 import com.fruitshorts.common.exception.ServiceException;
+import com.fruitshorts.framework.web.WebUtils;
 import com.fruitshorts.user.service.AppAuthService;
 import com.fruitshorts.user.service.AppOtpService;
 import com.fruitshorts.user.vo.TokenRespVO;
@@ -32,13 +33,15 @@ class AppAuthControllerContractTest {
 
     private AppOtpService otpService;
     private AppAuthService authService;
+    private WebUtils webUtils;
     private MockMvc mockMvc;
 
     @BeforeEach
     void setUp() {
         otpService = mock(AppOtpService.class);
         authService = mock(AppAuthService.class);
-        mockMvc = ControllerContractSupport.mockMvcOf(new AppAuthController(otpService, authService));
+        webUtils = mock(WebUtils.class);
+        mockMvc = ControllerContractSupport.mockMvcOf(new AppAuthController(otpService, authService, webUtils));
     }
 
     @Test

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

@@ -3,6 +3,7 @@ package com.fruitshorts.app.controller;
 
 import com.fruitshorts.app.service.AppCatalogService;
 import com.fruitshorts.app.service.AppEpisodeStatsService;
+import com.fruitshorts.app.service.AppRankingService;
 import com.fruitshorts.app.support.ControllerContractSupport;
 import com.fruitshorts.app.vo.AppBannerVO;
 import com.fruitshorts.app.vo.AppCategoryVO;
@@ -10,6 +11,8 @@ import com.fruitshorts.app.vo.AppDramaCardVO;
 import com.fruitshorts.app.vo.AppDramaDetailVO;
 import com.fruitshorts.app.vo.AppFeedVO;
 import com.fruitshorts.app.vo.AppSectionVO;
+import com.fruitshorts.app.vo.AppRankingEntryVO;
+import com.fruitshorts.app.vo.AppRankingVO;
 import com.fruitshorts.common.pojo.CursorResult;
 import com.fruitshorts.content.service.EpisodeService;
 import com.fruitshorts.common.exception.ErrorCode;
@@ -41,17 +44,21 @@ import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.
 class AppCatalogControllerContractTest {
 
     private AppCatalogService catalogService;
+    private AppRankingService rankingService;
     private MockMvc catalogMvc;
     private MockMvc dramaMvc;
 
     @BeforeEach
     void setUp() {
         catalogService = mock(AppCatalogService.class);
-        catalogMvc = ControllerContractSupport.mockMvcOf(new AppCatalogController(catalogService));
+        rankingService = mock(AppRankingService.class);
+        catalogMvc = ControllerContractSupport.mockMvcOf(
+                new AppCatalogController(catalogService, rankingService));
         dramaMvc = ControllerContractSupport.mockMvcOf(
                 new AppDramaController(catalogService, mock(PlaybackService.class),
                         mock(EpisodeService.class), mock(CommentService.class),
-                        mock(AppEpisodeStatsService.class)));
+                        mock(AppEpisodeStatsService.class),
+                        mock(com.fruitshorts.framework.web.WebUtils.class)));
     }
 
     @Test
@@ -121,15 +128,44 @@ class AppCatalogControllerContractTest {
     @Test
     void should_return_category_list_when_categories_are_requested() throws Exception {
         AppCategoryVO category = new AppCategoryVO(3L, "都市");
+        category.setCode("RECOMMEND_RANKING");
+        category.setLayoutType("RANKING");
+        category.setRevision(7L);
         given(catalogService.categories()).willReturn(List.of(category));
 
         catalogMvc.perform(get("/app/categories"))
                 .andExpect(status().isOk())
                 .andExpect(jsonPath("$.code").value(0))
                 .andExpect(jsonPath("$.data[0].id").value(3))
+                .andExpect(jsonPath("$.data[0].code").value("RECOMMEND_RANKING"))
+                .andExpect(jsonPath("$.data[0].layoutType").value("RANKING"))
+                .andExpect(jsonPath("$.data[0].revision").value("7"))
                 .andExpect(jsonPath("$.data[0].locales.zh").value("都市"));
     }
 
+    @Test
+    void should_return_server_rank_when_ranking_is_requested() throws Exception {
+        AppDramaCardVO card = new AppDramaCardVO();
+        card.setId(12L);
+        card.setTitleLocales(Map.of("zh", "榜首短剧"));
+        AppRankingVO ranking = new AppRankingVO();
+        ranking.setId(3L);
+        ranking.setCode("RECOMMEND_RANKING");
+        ranking.setRevision(8L);
+        ranking.setTotal(1);
+        ranking.setList(List.of(new AppRankingEntryVO(1, card)));
+        given(rankingService.ranking(3L)).willReturn(ranking);
+
+        catalogMvc.perform(get("/app/categories/3/ranking"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(0))
+                .andExpect(jsonPath("$.data.revision").value("8"))
+                .andExpect(jsonPath("$.data.list[0].rank").value(1))
+                .andExpect(jsonPath("$.data.list[0].drama.id").value("12"));
+
+        verify(rankingService).ranking(3L);
+    }
+
     @Test
     void should_bind_path_variable_when_drama_detail_is_requested() throws Exception {
         AppDramaDetailVO detail = new AppDramaDetailVO();

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

@@ -38,7 +38,8 @@ class AppCommentControllerContractTest {
                         commentService,
                         episodeService,
                         mock(InteractionIdentityResolver.class),
-                        mock(AnonymousInteractionRateLimiter.class)));
+                        mock(AnonymousInteractionRateLimiter.class),
+                        mock(com.fruitshorts.framework.web.WebUtils.class)));
     }
 
     @Test

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

@@ -234,7 +234,8 @@ class AppCommentCountAnonymousSecurityTest {
                     commentService,
                     episodeService,
                     identityResolver,
-                    rateLimiter);
+                    rateLimiter,
+                    mock(com.fruitshorts.framework.web.WebUtils.class));
         }
 
         @Bean
@@ -303,7 +304,8 @@ class AppCommentCountAnonymousSecurityTest {
                     mock(PlaybackService.class),
                     episodeService,
                     commentService,
-                    appEpisodeStatsService);
+                    appEpisodeStatsService,
+                    mock(com.fruitshorts.framework.web.WebUtils.class));
         }
 
         @Bean
@@ -326,7 +328,9 @@ class AppCommentCountAnonymousSecurityTest {
 
         @Bean
         AppCatalogController appCatalogController(AppCatalogService appCatalogService) {
-            return new AppCatalogController(appCatalogService);
+            return new AppCatalogController(
+                    appCatalogService,
+                    mock(com.fruitshorts.app.service.AppRankingService.class));
         }
 
         @Bean
@@ -340,7 +344,7 @@ class AppCommentCountAnonymousSecurityTest {
         RestAuthEntryPoint restAuthEntryPoint(ObjectMapper objectMapper) {
             return new RestAuthEntryPoint(
                     objectMapper,
-                    new AccessDeniedRecorder(mock(ObjectProvider.class)));
+                    new AccessDeniedRecorder(mock(ObjectProvider.class), mock(ObjectProvider.class)));
         }
 
         @Bean

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

@@ -90,6 +90,7 @@ class AppCreatorAndConfigContractTest {
         whitelist.put("noticeEnabled", true);
         whitelist.put("coinUnlockEnabled", true);
         whitelist.put("downloadEnabled", true);
+        whitelist.put("loginBackgroundUrl", "");
         given(appConfigService.appConfig()).willReturn(whitelist);
 
         String body = configMvc.perform(get("/app/config"))
@@ -97,6 +98,7 @@ class AppCreatorAndConfigContractTest {
                 .andExpect(jsonPath("$.code").value(0))
                 .andExpect(jsonPath("$.data.agreementVersion").value("2026-10-01"))
                 .andExpect(jsonPath("$.data.forceUpdate").value(false))
+                .andExpect(jsonPath("$.data.loginBackgroundUrl").value(""))
                 .andReturn().getResponse().getContentAsString(java.nio.charset.StandardCharsets.UTF_8);
 
         // 没登录也能拿到（匿名）

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

@@ -54,7 +54,8 @@ class AppPlaybackContractTest {
         given(commentService.countByEpisodes(any())).willReturn(Map.of());
         mockMvc = ControllerContractSupport.mockMvcOf(
                 new AppDramaController(mock(AppCatalogService.class), playbackService,
-                        episodeService, commentService, episodeStatsService));
+                        episodeService, commentService, episodeStatsService,
+                        mock(com.fruitshorts.framework.web.WebUtils.class)));
     }
 
     @Test

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

@@ -22,6 +22,7 @@ import com.fruitshorts.user.service.AppOtpService;
 import com.fruitshorts.user.service.CredentialHasher;
 import com.fruitshorts.user.service.GoogleIdTokenVerifier;
 import com.fruitshorts.user.service.GoogleUser;
+import com.fruitshorts.user.service.IpRegionService;
 import com.fruitshorts.user.service.OtpSender;
 import com.fruitshorts.user.vo.LoginReqVO;
 import com.fruitshorts.user.vo.RegisterReqVO;
@@ -67,6 +68,7 @@ class AppAuthServiceTest {
     private ConfigService configService;
     private GoogleIdTokenVerifier googleVerifier;
     private ApplicationEventPublisher eventPublisher;
+    private IpRegionService ipRegionService;
     private AppAuthService authService;
 
     @BeforeEach
@@ -83,11 +85,14 @@ class AppAuthServiceTest {
         configService = mock(ConfigService.class);
         googleVerifier = mock(GoogleIdTokenVerifier.class);
         eventPublisher = mock(ApplicationEventPublisher.class);
+        ipRegionService = mock(IpRegionService.class);
         given(configService.get(anyString(), anyString()))
                 .willAnswer(invocation -> invocation.getArgument(1));
+        // 单测里默认解析不出国家，走客户端区域 / 印尼兜底
+        given(ipRegionService.resolveCountry(any())).willReturn("");
         authService = new AppAuthService(userMapper, credentialMapper, sessionMapper, consentMapper,
                 deviceMapper, otpService, hasher, tokenProvider, passwordEncoder, configService,
-                googleVerifier, eventPublisher);
+                googleVerifier, eventPublisher, ipRegionService);
     }
 
     @Test
@@ -264,6 +269,41 @@ class AppAuthServiceTest {
         assertThat(event.deviceId()).isEqualTo("device-9");
     }
 
+    @Test
+    void should_sync_country_from_ip_on_login() {
+        stubLogin(credential("bcrypt-hash"), user(AppUserStatus.NORMAL));
+        given(passwordEncoder.matches("abcd1234", "bcrypt-hash")).willReturn(true);
+        given(ipRegionService.resolveCountry(any())).willReturn("TH");
+
+        authService.login(emailLogin("abcd1234"), "49.237.8.1");
+
+        ArgumentCaptor<AppUser> captor = ArgumentCaptor.forClass(AppUser.class);
+        verify(userMapper).updateById(captor.capture());
+        AppUser saved = captor.getValue();
+        assertThat(saved.getCountryCode()).isEqualTo("TH");
+        assertThat(saved.getRegionCode()).isEqualTo("TH");
+        assertThat(saved.getLanguage()).isEqualTo("en-US");
+        assertThat(saved.getTimezone()).isEqualTo("Asia/Bangkok");
+        assertThat(saved.getCurrency()).isEqualTo("THB");
+    }
+
+    @Test
+    void should_keep_user_customized_language_when_syncing_country() {
+        AppUser user = user(AppUserStatus.NORMAL);
+        user.setLanguage("zh-CN");
+        stubLogin(credential("bcrypt-hash"), user);
+        given(passwordEncoder.matches("abcd1234", "bcrypt-hash")).willReturn(true);
+        given(ipRegionService.resolveCountry(any())).willReturn("TH");
+
+        authService.login(emailLogin("abcd1234"), "49.237.8.1");
+
+        ArgumentCaptor<AppUser> captor = ArgumentCaptor.forClass(AppUser.class);
+        verify(userMapper).updateById(captor.capture());
+        assertThat(captor.getValue().getCountryCode()).isEqualTo("TH");
+        // 用户自己改过的语言不被 IP 覆盖
+        assertThat(captor.getValue().getLanguage()).isEqualTo("zh-CN");
+    }
+
     @Test
     void should_reject_login_when_password_does_not_match() {
         stubLogin(credential("bcrypt-hash"), user(AppUserStatus.NORMAL));
@@ -318,7 +358,7 @@ class AppAuthServiceTest {
         });
         given(userMapper.selectById(any())).willAnswer(invocation -> inserted.get());
 
-        TokenRespVO resp = authService.googleLogin("google-id-token", "device-9");
+        TokenRespVO resp = authService.googleLogin("google-id-token", "device-9", "203.0.113.9");
 
         assertThat(resp.getAccessToken()).isEqualTo("access-1");
         assertThat(resp.isNewUser()).isTrue();
@@ -333,7 +373,7 @@ class AppAuthServiceTest {
         given(googleVerifier.verify(anyString()))
                 .willReturn(new GoogleUser("sub-1", "", "Alice", ""));
 
-        assertThatThrownBy(() -> authService.googleLogin("google-id-token", "device-9"))
+        assertThatThrownBy(() -> authService.googleLogin("google-id-token", "device-9", "203.0.113.9"))
                 .isInstanceOf(ServiceException.class)
                 .hasMessage("Google 账号未返回邮箱，无法登录");
     }
@@ -392,7 +432,7 @@ class AppAuthServiceTest {
         AppOtpService realOtpService = new AppOtpService(otpMapper, mock(OtpSender.class), otpHasher);
         return new AppAuthService(userMapper, credentialMapper, sessionMapper, consentMapper,
                 deviceMapper, realOtpService, hasher, tokenProvider, passwordEncoder, configService,
-                googleVerifier, eventPublisher);
+                googleVerifier, eventPublisher, ipRegionService);
     }
 
     private void setRegisterLimits(int perIp, int perDevice) {

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

@@ -130,6 +130,25 @@ class AppCatalogServiceTest {
         verify(commentService, never()).countByDrama(any());
     }
 
+    @Test
+    void should_keep_full_synopsis_on_card_when_text_exceeds_card_length() {
+        String longSynopsis = "一纸婚约，开启了甜蜜又心动的同居生活。"
+                + "真相只有一个，而她亲手揭开迷雾。一场意外替嫁，让她成为冷面总裁的契约新娘。";
+        Drama drama = new Drama();
+        drama.setId(1L);
+        drama.setTitle("第一部");
+        drama.setSynopsis(longSynopsis);
+        given(episodeService.firstPlayableByDramas(List.of(1L))).willReturn(Map.of());
+        given(dramaCategoryService.listBasic()).willReturn(List.of());
+        given(commentService.countByEpisodes(List.of())).willReturn(Map.of());
+
+        List<AppDramaCardVO> cards = catalogService.toCards(List.of(drama));
+
+        assertThat(cards).hasSize(1);
+        assertThat(cards.get(0).getSynopsisLocales())
+                .containsEntry("zh", longSynopsis);
+    }
+
     @Test
     void should_filter_feed_by_drama_type_and_expose_it_on_card() {
         Drama anime = drama(1L, "ANIME");

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

@@ -0,0 +1,75 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.app.service;
+
+import com.fruitshorts.app.vo.AppDramaCardVO;
+import com.fruitshorts.app.vo.AppRankingVO;
+import com.fruitshorts.content.dal.entity.Drama;
+import com.fruitshorts.content.dal.entity.DramaClassification;
+import com.fruitshorts.content.service.DramaClassificationService;
+import com.fruitshorts.content.service.DramaService;
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+import java.util.Map;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.BDDMockito.given;
+import static org.mockito.Mockito.mock;
+
+/** 推荐榜快照顺序与排名测试。 */
+class AppRankingServiceTest {
+
+    @Test
+    void should_preserve_server_order_and_compact_rank_when_offline_items_are_filtered() {
+        DramaClassificationService classificationService = mock(DramaClassificationService.class);
+        DramaService dramaService = mock(DramaService.class);
+        AppCatalogService catalogService = mock(AppCatalogService.class);
+        AppRankingService service = new AppRankingService(
+                classificationService, dramaService, catalogService);
+        DramaClassification classification = rankingClassification();
+        Drama second = drama(22L);
+        Drama first = drama(11L);
+        given(classificationService.getEnabledById(3L)).willReturn(classification);
+        given(classificationService.listDramaIdsByClassification(3L))
+                .willReturn(List.of(11L, 99L, 22L));
+        given(dramaService.listPublishedByIds(List.of(11L, 99L, 22L)))
+                .willReturn(List.of(second, first));
+        AppDramaCardVO firstCard = card(11L);
+        AppDramaCardVO secondCard = card(22L);
+        given(catalogService.toCards(List.of(first, second)))
+                .willReturn(List.of(firstCard, secondCard));
+
+        AppRankingVO result = service.ranking(3L);
+
+        assertThat(result.getRevision()).isEqualTo(7L);
+        assertThat(result.getList()).extracting(item -> item.getDrama().getId())
+                .containsExactly(11L, 22L);
+        assertThat(result.getList()).extracting(item -> item.getRank())
+                .containsExactly(1, 2);
+    }
+
+    private DramaClassification rankingClassification() {
+        DramaClassification classification = new DramaClassification();
+        classification.setId(3L);
+        classification.setCode("RECOMMEND_RANKING");
+        classification.setName("推荐榜");
+        classification.setNameLocales("{\"zh\":\"推荐榜\"}");
+        classification.setLayoutType(DramaClassificationService.LAYOUT_RANKING);
+        classification.setRevision(7L);
+        return classification;
+    }
+
+    private Drama drama(Long id) {
+        Drama drama = new Drama();
+        drama.setId(id);
+        return drama;
+    }
+
+    private AppDramaCardVO card(Long id) {
+        AppDramaCardVO card = new AppDramaCardVO();
+        card.setId(id);
+        card.setTitleLocales(Map.of("zh", "短剧" + id));
+        return card;
+    }
+}

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

@@ -0,0 +1,42 @@
+// Author: fruit.com.cn
+package com.fruitshorts.app.service;
+
+import com.fruitshorts.user.enums.CountryProfile;
+import org.junit.jupiter.api.Test;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/** 国家解析与映射：IP 库文本 → ISO-2，再据此选语言/时区/币种。 */
+class CountryProfileTest {
+
+    @Test
+    void should_map_ip_region_text_to_iso_code() {
+        assertThat(CountryProfile.fromIpRegion("中国|0|广东省|深圳市|电信")).isEqualTo("CN");
+        assertThat(CountryProfile.fromIpRegion("中国|0|台湾省|0|中华电信")).isEqualTo("TW");
+        assertThat(CountryProfile.fromIpRegion("中国|0|香港|0|0")).isEqualTo("HK");
+        assertThat(CountryProfile.fromIpRegion("中国|0|澳门|0|澳门电讯")).isEqualTo("MO");
+        assertThat(CountryProfile.fromIpRegion("美国|0|0|0|Level3")).isEqualTo("US");
+        assertThat(CountryProfile.fromIpRegion("印度尼西亚|0|大雅加达|雅加达|0")).isEqualTo("ID");
+    }
+
+    @Test
+    void should_return_empty_for_private_ip_and_unknown_country() {
+        assertThat(CountryProfile.fromIpRegion("0|0|0|内网IP|内网IP")).isEmpty();
+        assertThat(CountryProfile.fromIpRegion("")).isEmpty();
+        // 未收录的国家交给上层回退到客户端区域
+        assertThat(CountryProfile.fromIpRegion("津巴布韦|0|0|0|0")).isEmpty();
+    }
+
+    @Test
+    void should_normalize_client_region_and_fallback_to_default() {
+        assertThat(CountryProfile.normalizeClientCode(" id ")).isEqualTo("ID");
+        assertThat(CountryProfile.normalizeClientCode("us")).isEqualTo("US");
+        assertThat(CountryProfile.normalizeClientCode("XX")).isEmpty();
+        assertThat(CountryProfile.normalizeClientCode("")).isEmpty();
+
+        assertThat(CountryProfile.of("US").currency()).isEqualTo("USD");
+        assertThat(CountryProfile.of("US").language()).isEqualTo("en-US");
+        assertThat(CountryProfile.of("").code()).isEqualTo("ID");
+        assertThat(CountryProfile.of("").currency()).isEqualTo("IDR");
+    }
+}

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

@@ -0,0 +1,49 @@
+// Author: fruit.com.cn
+package com.fruitshorts.app.service;
+
+import com.fruitshorts.user.service.IpRegionService;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/**
+ * IpRegionService 集成测试：真实 xdb 文件 + 真实 resolve。
+ *
+ * <p>xdb 在 fruitshorts-module-user 的 resources/ip2region/ip2region.xdb 下（11MB），
+ * 打包后会进 app-api 的 classpath。这个测试验证 Service 层调 ip2region 库的行为——
+ * 合法公网 IP → ISO-2 国家码，内网/保留地址/空 → 空串。
+ */
+class IpRegionServiceTest {
+
+    private IpRegionService service;
+
+    @BeforeEach
+    void setUp() {
+        service = new IpRegionService();
+    }
+
+    @Test
+    void should_resolve_known_public_ips() {
+        assertThat(service.resolveCountry("8.8.8.8")).isEqualTo("US");
+        assertThat(service.resolveCountry("114.114.114.114")).isEqualTo("CN");
+    }
+
+    @Test
+    void should_return_empty_for_private_loopback_and_reserved() {
+        assertThat(service.resolveCountry("127.0.0.1")).isEmpty();
+        assertThat(service.resolveCountry("0.0.0.0")).isEmpty();
+        assertThat(service.resolveCountry("10.0.0.1")).isEmpty();
+        assertThat(service.resolveCountry("192.168.1.1")).isEmpty();
+        assertThat(service.resolveCountry("172.16.0.1")).isEmpty();
+        assertThat(service.resolveCountry("169.254.1.1")).isEmpty();
+    }
+
+    @Test
+    void should_return_empty_for_invalid_inputs() {
+        assertThat(service.resolveCountry("")).isEmpty();
+        assertThat(service.resolveCountry(null)).isEmpty();
+        assertThat(service.resolveCountry("not-an-ip")).isEmpty();
+        assertThat(service.resolveCountry("999.999.999.999")).isEmpty();
+    }
+}

fruitshorts-app-api/src/test/java/com/fruitshorts/app/support/ControllerContractSupport.java

@@ -2,6 +2,7 @@
 package com.fruitshorts.app.support;
 
 import com.fruitshorts.framework.log.AccessDeniedRecorder;
+import com.fruitshorts.framework.web.WebUtils;
 import com.fruitshorts.framework.web.JacksonLongToStringConfig;
 import com.fruitshorts.framework.web.GlobalExceptionHandler;
 import com.fasterxml.jackson.databind.SerializationFeature;
@@ -30,7 +31,9 @@ public final class ControllerContractSupport {
     /** 组装一个只含指定控制器与全局异常处理的 MockMvc。 */
     @SuppressWarnings("unchecked")
     public static MockMvc mockMvcOf(Object controller) {
-        AccessDeniedRecorder recorder = new AccessDeniedRecorder(Mockito.mock(ObjectProvider.class));
+        AccessDeniedRecorder recorder = new AccessDeniedRecorder(
+                Mockito.mock(ObjectProvider.class),
+                Mockito.mock(ObjectProvider.class));
         return MockMvcBuilders.standaloneSetup(controller)
                 .setControllerAdvice(new GlobalExceptionHandler(recorder))
                 // 与 Spring Boot 的 Jackson 配置对齐：时间按 ISO 字符串输出而不是数组，

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

@@ -20,18 +20,28 @@ import com.fruitshorts.playback.vo.ProgressRespVO;
 import com.fruitshorts.playback.vo.ProgressSaveReqVO;
 import org.apache.ibatis.builder.MapperBuilderAssistant;
 import org.apache.ibatis.annotations.Select;
+import org.apache.ibatis.session.ExecutorType;
+import org.apache.ibatis.session.SqlSession;
+import org.apache.ibatis.session.SqlSessionFactory;
 import org.junit.jupiter.api.BeforeAll;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 import org.mockito.ArgumentCaptor;
+import org.mockito.InOrder;
+import org.springframework.beans.factory.ObjectProvider;
+import org.springframework.transaction.PlatformTransactionManager;
+import org.springframework.transaction.support.TransactionTemplate;
 
 import java.time.LocalDateTime;
 import java.lang.reflect.Method;
 import java.util.List;
+import java.util.Map;
 
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.eq;
 import static org.mockito.BDDMockito.given;
+import static org.mockito.Mockito.inOrder;
 import static org.mockito.Mockito.mock;
 import static org.mockito.Mockito.never;
 import static org.mockito.Mockito.times;
@@ -58,11 +68,18 @@ class WatchProgressServiceTest {
         historyMapper = mock(WatchHistoryMapper.class);
         dramaService = mock(DramaService.class);
         episodeService = mock(EpisodeService.class);
+        // 测试统一走缓冲关闭（同步写库）路径：getIfAvailable 返回 null
+        @SuppressWarnings("unchecked")
+        ObjectProvider<WatchProgressBuffer> bufferProvider = mock(ObjectProvider.class);
+        given(bufferProvider.getIfAvailable()).willReturn(null);
         progressService = new WatchProgressService(
                 progressMapper,
                 historyMapper,
                 dramaService,
-                episodeService);
+                episodeService,
+                bufferProvider,
+                mock(SqlSessionFactory.class),
+                new TransactionTemplate(mock(PlatformTransactionManager.class)));
     }
 
     @Test
@@ -319,6 +336,123 @@ class WatchProgressServiceTest {
         verify(progressMapper).deleteById(1L);
     }
 
+    @Test
+    void should_delete_buffer_state_when_removing_or_clearing_history() {
+        WatchProgressBuffer buffer = mock(WatchProgressBuffer.class);
+        WatchProgressService service = serviceWithBuffer(buffer);
+
+        service.remove(new InteractionIdentity(9L, ""), 5L);
+        service.clear(new InteractionIdentity(9L, ""));
+
+        verify(buffer).remove(any(InteractionIdentity.class), eq(5L));
+        verify(buffer).clear(any(InteractionIdentity.class));
+        verify(progressMapper, times(2)).delete(any());
+    }
+
+    @Test
+    void should_not_bring_back_deleted_drama_from_buffer_in_recent_page() {
+        WatchProgressBuffer buffer = mock(WatchProgressBuffer.class);
+        WatchProgressService service = serviceWithBuffer(buffer);
+        Page<WatchProgress> emptyPage = new Page<>(1, 20, 0);
+        emptyPage.setRecords(List.of());
+        given(progressMapper.selectPage(any(Page.class), any())).willReturn(emptyPage);
+        given(buffer.getAll(any(InteractionIdentity.class))).willReturn(Map.of(
+                5L, new WatchProgressBuffer.BufferedProgress(
+                        5L, 88L, 1_000L, 2_000L, false, "feed", "", 1_700_000_000_000L)));
+        // 库里该剧只剩逻辑删除行：缓冲状态不得再把它读回列表
+        WatchProgress hidden = progress(5L, 88L);
+        hidden.setDeleted(1);
+        given(progressMapper.selectAnyForIdentityIn(9L, "", List.of(5L)))
+                .willReturn(List.of(hidden));
+
+        PageResult<ProgressRespVO> result =
+                service.recentPage(new InteractionIdentity(9L, ""), 1, 20);
+
+        assertThat(result.getList()).isEmpty();
+        assertThat(result.getTotal()).isZero();
+    }
+
+    @Test
+    void should_drop_buffered_refs_whose_state_is_gone_instead_of_requeue() {
+        WatchProgressBuffer buffer = mock(WatchProgressBuffer.class);
+        WatchProgressService service = serviceWithBuffer(buffer);
+        given(buffer.drain(10)).willReturn(
+                List.of(new WatchProgressBuffer.IdentityRef("u:9", 9L, "", 5L)));
+        given(buffer.getAllBatch(List.of("u:9"))).willReturn(Map.of());
+
+        int flushed = service.flushBuffered(10);
+
+        // 状态已消失（用户删除/清空历史或 TTL 过期）：必须丢弃，退回队列会变成永不消失的僵尸条目
+        assertThat(flushed).isZero();
+        verify(buffer, never()).requeue(any());
+        verify(progressMapper, never()).selectBatchForPairs(any());
+    }
+
+    @Test
+    void should_flush_device_buffer_before_merging_and_clear_it_after() {
+        WatchProgressBuffer buffer = mock(WatchProgressBuffer.class);
+        given(buffer.getAll(any(InteractionIdentity.class))).willReturn(Map.of());
+        WatchProgressService service = serviceWithBuffer(buffer);
+        given(progressMapper.selectList(any())).willReturn(List.of());
+        given(historyMapper.selectList(any())).willReturn(List.of());
+
+        service.mergeDeviceIntoUser(9L, "device-a");
+
+        // 合并前先把缓冲落库，合并完再清掉设备侧缓冲
+        InOrder order = inOrder(buffer);
+        order.verify(buffer).getAll(any(InteractionIdentity.class));
+        order.verify(buffer).clear(any(InteractionIdentity.class));
+    }
+
+    @Test
+    void should_drop_late_buffered_ref_when_row_is_already_deleted() {
+        WatchProgressBuffer buffer = mock(WatchProgressBuffer.class);
+        SqlSessionFactory sessionFactory = mock(SqlSessionFactory.class);
+        SqlSession session = mock(SqlSession.class);
+        WatchProgressMapper batchProgress = mock(WatchProgressMapper.class);
+        WatchHistoryMapper batchHistory = mock(WatchHistoryMapper.class);
+        given(sessionFactory.openSession(ExecutorType.BATCH, false)).willReturn(session);
+        given(session.getMapper(WatchProgressMapper.class)).willReturn(batchProgress);
+        given(session.getMapper(WatchHistoryMapper.class)).willReturn(batchHistory);
+        WatchProgressService service = serviceWithBuffer(buffer, sessionFactory);
+
+        given(buffer.drain(10)).willReturn(
+                List.of(new WatchProgressBuffer.IdentityRef("u:9", 9L, "", 5L)));
+        given(buffer.getAllBatch(List.of("u:9"))).willReturn(Map.of("u:9", Map.of(
+                5L, new WatchProgressBuffer.BufferedProgress(
+                        5L, 88L, 1_000L, 2_000L, false, "feed", "", 1_700_000_000_000L))));
+        // 库里是逻辑删除行，且删除时刻晚于该条缓冲的上报时刻
+        WatchProgress hidden = progress(5L, 88L);
+        hidden.setUserId(9L);
+        hidden.setDeleted(1);
+        hidden.setUpdatedAt(LocalDateTime.of(2026, 10, 28, 12, 0));
+        given(progressMapper.selectBatchForPairs(any())).willReturn(List.of(hidden));
+
+        service.flushBuffered(10);
+
+        verify(batchProgress, never()).updateRowAny(any());
+        verify(batchHistory, never()).insert(any(WatchHistory.class));
+    }
+
+    private WatchProgressService serviceWithBuffer(WatchProgressBuffer buffer) {
+        return serviceWithBuffer(buffer, mock(SqlSessionFactory.class));
+    }
+
+    private WatchProgressService serviceWithBuffer(
+            WatchProgressBuffer buffer, SqlSessionFactory sessionFactory) {
+        @SuppressWarnings("unchecked")
+        ObjectProvider<WatchProgressBuffer> provider = mock(ObjectProvider.class);
+        given(provider.getIfAvailable()).willReturn(buffer);
+        return new WatchProgressService(
+                progressMapper,
+                historyMapper,
+                dramaService,
+                episodeService,
+                provider,
+                sessionFactory,
+                new TransactionTemplate(mock(PlatformTransactionManager.class)));
+    }
+
     private Drama drama(Long id, String title, int totalEpisodes) {
         Drama drama = new Drama();
         drama.setId(id);

fruitshorts-framework/src/main/java/com/fruitshorts/framework/log/AccessDeniedRecorder.java

@@ -22,6 +22,7 @@ import org.springframework.web.context.request.ServletRequestAttributes;
 public class AccessDeniedRecorder {
 
     private final ObjectProvider<OperationLogSink> sinkProvider;
+    private final ObjectProvider<WebUtils> webUtilsProvider;
 
     public void record(HttpServletRequest request) {
         OperationLogSink sink = sinkProvider.getIfAvailable();
@@ -47,10 +48,16 @@ public class AccessDeniedRecorder {
                 .status("FAIL")
                 .errorMsg("无权限")
                 .durationMs(0)
-                .ip(request == null ? "" : WebUtils.getClientIp(request))
+                .ip(request == null ? "" : clientIp(request))
                 .build());
     }
 
+    /** 优先用 Spring 注入的 WebUtils（尊重可信代理配置），拿不到回退静态方法。 */
+    private String clientIp(HttpServletRequest request) {
+        WebUtils webUtils = webUtilsProvider.getIfAvailable();
+        return webUtils != null ? webUtils.clientIp(request) : WebUtils.getClientIp(request);
+    }
+
     /** 从当前线程取出请求，供全局异常处理使用。 */
     public void recordCurrentRequest() {
         if (RequestContextHolder.getRequestAttributes() instanceof ServletRequestAttributes attributes) {

fruitshorts-framework/src/main/java/com/fruitshorts/framework/log/OperationLogAspect.java

@@ -43,6 +43,7 @@ public class OperationLogAspect {
 
     private final ObjectMapper objectMapper;
     private final ObjectProvider<OperationLogSink> sinkProvider;
+    private final ObjectProvider<WebUtils> webUtilsProvider;
 
     @Around("@annotation(operationLog)")
     public Object around(ProceedingJoinPoint point, OperationLog operationLog) throws Throwable {
@@ -86,10 +87,16 @@ public class OperationLogAspect {
                 .status(error == null ? "SUCCESS" : "FAIL")
                 .errorMsg(error == null ? "" : truncate(error.getMessage()))
                 .durationMs(durationMs)
-                .ip(request == null ? "" : WebUtils.getClientIp(request))
+                .ip(request == null ? "" : clientIp(request))
                 .build());
     }
 
+    /** 优先用 Spring 注入的 WebUtils（尊重可信代理配置），拿不到回退静态方法。 */
+    private String clientIp(HttpServletRequest request) {
+        WebUtils webUtils = webUtilsProvider.getIfAvailable();
+        return webUtils != null ? webUtils.clientIp(request) : WebUtils.getClientIp(request);
+    }
+
     /** 把方法入参整理成 JSON，文件只记名称和大小。 */
     private String body(ProceedingJoinPoint point) {
         Object[] args = point.getArgs();

fruitshorts-framework/src/main/java/com/fruitshorts/framework/security/ImpersonationGuard.java

@@ -62,6 +62,8 @@ public final class ImpersonationGuard {
 
     public static String clientIp() {
         HttpServletRequest request = currentRequest();
+        // 这里走静态 getClientIp——等价于 trusted-proxies 为空时的逻辑（只用 remoteAddr，不解析 XFF）。
+        // 这个类是纯静态工具（无 Spring 注入），且只在 Creator 代看场景用，安全影响低。
         return request == null ? "" : com.fruitshorts.framework.web.WebUtils.getClientIp(request);
     }
 

fruitshorts-framework/src/main/java/com/fruitshorts/framework/web/WebUtils.java

@@ -3,25 +3,146 @@
 package com.fruitshorts.framework.web;
 
 import jakarta.servlet.http.HttpServletRequest;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.stereotype.Component;
 import org.springframework.util.StringUtils;
 
-public final class WebUtils {
+import java.net.InetAddress;
+import java.net.UnknownHostException;
+import java.util.Arrays;
+import java.util.List;
+
+/**
+ * 取真实客户端 IP。
+ *
+ * <p>安全策略：默认信任 {@link HttpServletRequest#getRemoteAddr()} 本身，只有当
+ * 它属于配置的可信代理 CIDR 时才解析 X-Forwarded-For / X-Real-IP 等头。
+ * 这样客户端伪造的 XFF 不会生效，只有经 Nginx / K8s ingress 等前置代理转发的请求
+ * 才能带上可信的 XFF 链。
+ *
+ * <p>生产建议：同时开启 Tomcat RemoteIpValve（prod profile 已配置），让
+ * {@code getRemoteAddr()} 在经过代理后直接就是客户端真实 IP。此时可信代理列表
+ * 配成空即可，Valve 已经帮我们做了 XFF 解析。
+ */
+@Slf4j
+@Component
+public class WebUtils {
 
     private static final String UNKNOWN = "unknown";
+    private static final String[] PROXY_HEADERS = {"X-Forwarded-For", "X-Real-IP",
+            "Proxy-Client-IP", "WL-Proxy-Client-IP"};
 
-    private WebUtils() {
+    /** 可信代理 CIDR 列表，逗号分隔；空表示永不解析 XFF，直接用 remoteAddr。 */
+    @Value("${fruitshorts.web.trusted-proxies:}")
+    private String trustedProxies = "";
+
+    /** 纯静态调用路径（不依赖 Spring），供测试或无 IoC 场景使用。 */
+    public static String getClientIp(HttpServletRequest request) {
+        return resolve(request, List.of());
     }
 
-    /** 取真实客户端 IP，兼容 Nginx 反向代理。 */
-    public static String getClientIp(HttpServletRequest request) {
-        String[] headers = {"X-Forwarded-For", "X-Real-IP", "Proxy-Client-IP", "WL-Proxy-Client-IP"};
-        for (String header : headers) {
-            String value = request.getHeader(header);
-            if (StringUtils.hasText(value) && !UNKNOWN.equalsIgnoreCase(value)) {
-                int comma = value.indexOf(',');
-                return comma > 0 ? value.substring(0, comma).trim() : value.trim();
+    /** Spring 注入版：自动按配置解析 XFF。 */
+    public String clientIp(HttpServletRequest request) {
+        List<String> cidrs = StringUtils.hasText(trustedProxies)
+                ? Arrays.asList(trustedProxies.split(","))
+                : List.of();
+        return resolve(request, cidrs);
+    }
+
+    private static String resolve(HttpServletRequest request, List<String> trustedCidrs) {
+        String remoteAddr = request.getRemoteAddr();
+        if (isTrustedProxy(remoteAddr, trustedCidrs)) {
+            String fromHeader = readProxyHeader(request);
+            if (StringUtils.hasText(fromHeader)) {
+                return fromHeader;
             }
         }
-        return request.getRemoteAddr();
+        return remoteAddr;
+    }
+
+    private static String readProxyHeader(HttpServletRequest request) {
+        for (String header : PROXY_HEADERS) {
+            String value = request.getHeader(header);
+            if (StringUtils.hasText(value) && !UNKNOWN.equalsIgnoreCase(value)) {
+                // XFF 链格式：client, proxy1, proxy2 —— 最左侧是原始客户端 IP
+                String[] parts = value.split(",");
+                return parts[0].trim();
+            }
+        }
+        return "";
+    }
+
+    /**
+     * 判断 remoteAddr 是否属于可信代理。
+     *
+     * <p>CIDR 简化实现：只支持单个 IP 或 "/24" 这类前缀掩码，不支持复杂区间。
+     * 生产反代一般就是 127.0.0.1、10.0.0.0/8 这类，够用。
+     */
+    static boolean isTrustedProxy(String remoteAddr, List<String> trustedCidrs) {
+        if (!StringUtils.hasText(remoteAddr) || trustedCidrs.isEmpty()) {
+            return false;
+        }
+        try {
+            InetAddress remote = InetAddress.getByName(remoteAddr.trim());
+            for (String cidr : trustedCidrs) {
+                if (cidrMatches(remote, cidr.trim())) {
+                    return true;
+                }
+            }
+        } catch (UnknownHostException ex) {
+            log.debug("无法解析 remoteAddr {} 为 IP，跳过 XFF 信任判定", remoteAddr);
+        }
+        return false;
+    }
+
+    private static boolean cidrMatches(InetAddress target, String cidr) {
+        if (!cidr.contains("/")) {
+            // 单 IP 精确匹配
+            InetAddress trusted;
+            try {
+                trusted = InetAddress.getByName(cidr);
+            } catch (UnknownHostException ex) {
+                return false;
+            }
+            return trusted.equals(target);
+        }
+        String[] parts = cidr.split("/", 2);
+        String netPart = parts[0];
+        int prefixLen;
+        try {
+            prefixLen = Integer.parseInt(parts[1]);
+        } catch (NumberFormatException ex) {
+            return false;
+        }
+        InetAddress net;
+        try {
+            net = InetAddress.getByName(netPart);
+        } catch (UnknownHostException ex) {
+            return false;
+        }
+        byte[] targetBytes = target.getAddress();
+        byte[] netBytes = net.getAddress();
+        if (targetBytes.length != netBytes.length) {
+            return false;
+        }
+        int fullBytes = prefixLen / 8;
+        int remainingBits = prefixLen % 8;
+        for (int i = 0; i < fullBytes; i++) {
+            if (targetBytes[i] != netBytes[i]) {
+                return false;
+            }
+        }
+        if (remainingBits > 0 && fullBytes < targetBytes.length) {
+            int mask = (0xFF << (8 - remainingBits)) & 0xFF;
+            if ((targetBytes[fullBytes] & mask) != (netBytes[fullBytes] & mask)) {
+                return false;
+            }
+        }
+        return true;
+    }
+
+    /** Spring 直接实例化；保留 package-private 方便单测 new。 */
+    WebUtils() {
     }
 }

fruitshorts-module-content/src/main/java/com/fruitshorts/content/dal/entity/ContentTag.java

@@ -24,6 +24,8 @@ public class ContentTag {
     private String nameLocales;
     /** 角标背景色，#RRGGBB。 */
     private String bgColor;
+    /** 语义码，如 NEW_ARRIVAL；客户端按码判断板块，不解析文案。空表示未配置。 */
+    private String code;
     private Integer sort;
     private Integer status;
     private LocalDateTime createdAt;

fruitshorts-module-content/src/main/java/com/fruitshorts/content/dal/entity/DramaClassification.java

@@ -18,10 +18,16 @@ public class DramaClassification {
     private Long id;
     /** 中文名称。 */
     private String name;
+    /** 稳定语义码，不随展示名称变化。 */
+    private String code;
     private String nameEn;
     private String nameId;
     /** 已选语言的名称。 */
     private String nameLocales;
+    /** 客户端布局：GRID / RANKING。 */
+    private String layoutType;
+    /** 内容或顺序版本。 */
+    private Long revision;
     private Integer sort;
     private Integer status;
     private LocalDateTime createdAt;

fruitshorts-module-content/src/main/java/com/fruitshorts/content/dal/entity/DramaClassificationDrama.java

@@ -18,5 +18,7 @@ public class DramaClassificationDrama {
     private Long id;
     private Long classificationId;
     private Long dramaId;
+    /** 分类内展示位置，从 1 开始。 */
+    private Integer position;
     private LocalDateTime createdAt;
 }

fruitshorts-module-content/src/main/java/com/fruitshorts/content/service/ContentTagService.java

@@ -49,9 +49,12 @@ public class ContentTagService {
     public Long create(ContentTagSaveReqVO req) {
         Map<String, String> locales = namesOf(req);
         ensureNameAvailable(locales.get(ContentLocaleTexts.ZH), null);
+        String code = normalizeCode(req.getCode());
+        ensureCodeAvailable(code, null);
         ContentTag entity = new ContentTag();
         writeNames(entity, locales);
         entity.setBgColor(normalizeColor(req.getBgColor()));
+        entity.setCode(code);
         Long count = tagMapper.selectCount(null);
         entity.setSort(req.getSort() == null
                 ? (count == null ? 0 : count.intValue()) + 1
@@ -69,6 +72,11 @@ public class ContentTagService {
         if (req.getBgColor() != null) {
             entity.setBgColor(normalizeColor(req.getBgColor()));
         }
+        if (req.getCode() != null) {
+            String code = normalizeCode(req.getCode());
+            ensureCodeAvailable(code, id);
+            entity.setCode(code);
+        }
         if (req.getSort() != null) {
             entity.setSort(req.getSort());
         }
@@ -115,6 +123,23 @@ public class ContentTagService {
         return color.trim().toUpperCase();
     }
 
+    /** 语义码统一大写；空字符串表示不配置。 */
+    private String normalizeCode(String code) {
+        return code == null ? "" : code.trim().toUpperCase();
+    }
+
+    private void ensureCodeAvailable(String code, Long excludeId) {
+        if (code.isEmpty()) {
+            return;
+        }
+        Long count = tagMapper.selectCount(Wrappers.<ContentTag>lambdaQuery()
+                .eq(ContentTag::getCode, code)
+                .ne(excludeId != null, ContentTag::getId, excludeId));
+        if (count != null && count > 0) {
+            throw new ServiceException(ErrorCode.DATA_EXISTS, "语义码已存在");
+        }
+    }
+
     private ContentTag getExisting(Long id) {
         ContentTag entity = id == null ? null : tagMapper.selectById(id);
         if (entity == null) {
@@ -142,6 +167,7 @@ public class ContentTagService {
         vo.setNameId(ContentLocaleTexts.value(locales, ContentLocaleTexts.ID));
         vo.setLocales(locales);
         vo.setBgColor(tag.getBgColor() == null || tag.getBgColor().isBlank() ? "#E5484D" : tag.getBgColor());
+        vo.setCode(tag.getCode() == null ? "" : tag.getCode());
         vo.setSort(tag.getSort());
         vo.setStatus(tag.getStatus());
         return vo;

fruitshorts-module-content/src/main/java/com/fruitshorts/content/service/DramaClassificationService.java

@@ -27,7 +27,6 @@ import org.springframework.util.StringUtils;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
-import java.util.stream.Collectors;
 
 /**
  * 运营分类服务。分类是独立于「短剧类型（drama_category）」的一套概念，
@@ -37,9 +36,15 @@ import java.util.stream.Collectors;
 @RequiredArgsConstructor
 public class DramaClassificationService {
 
+    public static final String LAYOUT_GRID = "GRID";
+    public static final String LAYOUT_RANKING = "RANKING";
+    private static final long INITIAL_REVISION = 1L;
+    private static final String DEFAULT_CODE_PREFIX = "CLASSIFICATION_";
+
     private final DramaClassificationMapper classificationMapper;
     private final DramaClassificationDramaMapper classificationDramaMapper;
     private final DramaMapper dramaMapper;
+    private final DramaRankingService rankingService;
 
     public List<DramaClassificationRespVO> list() {
         Map<Long, Integer> counts = countDramas();
@@ -49,12 +54,15 @@ public class DramaClassificationService {
                 .stream().map(item -> {
                     DramaClassificationRespVO vo = new DramaClassificationRespVO();
                     vo.setId(item.getId());
+                    vo.setCode(codeOf(item));
                     Map<String, String> locales = ContentLocaleTexts.read(
                             item.getNameLocales(), item.getName(), item.getNameEn(), item.getNameId());
                     vo.setName(locales.get(ContentLocaleTexts.ZH));
                     vo.setNameEn(ContentLocaleTexts.value(locales, ContentLocaleTexts.EN));
                     vo.setNameId(ContentLocaleTexts.value(locales, ContentLocaleTexts.ID));
                     vo.setLocales(locales);
+                    vo.setLayoutType(layoutOf(item));
+                    vo.setRevision(revisionOf(item));
                     vo.setSort(item.getSort());
                     vo.setStatus(item.getStatus());
                     vo.setUpdatedAt(item.getUpdatedAt());
@@ -68,12 +76,18 @@ public class DramaClassificationService {
         ensureNameAvailable(locales.get(ContentLocaleTexts.ZH), null);
         DramaClassification entity = new DramaClassification();
         writeNames(entity, locales);
+        writeClassificationSettings(entity, req);
         Long count = classificationMapper.selectCount(null);
         entity.setSort(req.getSort() == null
                 ? (count == null ? 0 : count.intValue()) + 1
                 : req.getSort());
         entity.setStatus(req.getStatus() == null ? 1 : req.getStatus());
+        entity.setRevision(INITIAL_REVISION);
         classificationMapper.insert(entity);
+        if (!StringUtils.hasText(entity.getCode())) {
+            entity.setCode(DEFAULT_CODE_PREFIX + entity.getId());
+            classificationMapper.updateById(entity);
+        }
         return entity.getId();
     }
 
@@ -82,6 +96,7 @@ public class DramaClassificationService {
         Map<String, String> locales = namesOf(req);
         ensureNameAvailable(locales.get(ContentLocaleTexts.ZH), id);
         writeNames(entity, locales);
+        writeClassificationSettings(entity, req);
         if (req.getSort() != null) {
             entity.setSort(req.getSort());
         }
@@ -114,7 +129,7 @@ public class DramaClassificationService {
     /** 批量关联短剧；已关联的自动跳过。 */
     @Transactional(rollbackFor = Exception.class)
     public int bindDramas(Long id, List<Long> dramaIds) {
-        getExisting(id);
+        ensureGridMutation(getExisting(id));
         if (dramaIds == null || dramaIds.isEmpty()) {
             return 0;
         }
@@ -133,6 +148,7 @@ public class DramaClassificationService {
             DramaClassificationDrama relation = new DramaClassificationDrama();
             relation.setClassificationId(id);
             relation.setDramaId(dramaId);
+            relation.setPosition(rankingService.nextPosition(id));
             classificationDramaMapper.insert(relation);
             added++;
         }
@@ -141,15 +157,24 @@ public class DramaClassificationService {
 
     /** 移出分类；短剧本身不受影响。 */
     public void unbindDrama(Long id, Long dramaId) {
-        getExisting(id);
+        ensureGridMutation(getExisting(id));
         classificationDramaMapper.delete(Wrappers.<DramaClassificationDrama>lambdaQuery()
                 .eq(DramaClassificationDrama::getClassificationId, id)
                 .eq(DramaClassificationDrama::getDramaId, dramaId));
     }
 
+    /** 原子替换推荐榜内容与顺序，成功后递增版本。 */
+    @Transactional(rollbackFor = Exception.class)
+    public void saveRankingItems(Long id, List<Long> dramaIds) {
+        rankingService.saveItems(id, dramaIds);
+    }
+
     private PageResult<DramaBriefVO> pageDramas(Long id, String keyword,
                                                 int pageIndex, int pageSize, boolean bound) {
-        getExisting(id);
+        DramaClassification classification = getExisting(id);
+        if (bound && LAYOUT_RANKING.equals(layoutOf(classification))) {
+            return rankingService.page(id, keyword, pageIndex, pageSize);
+        }
         Page<Drama> page = new Page<>(Math.max(1, pageIndex), Math.max(1, Math.min(pageSize, 100)));
         LambdaQueryWrapper<Drama> wrapper = Wrappers.<Drama>lambdaQuery()
                 .like(StringUtils.hasText(keyword), Drama::getTitle, keyword)
@@ -228,8 +253,12 @@ public class DramaClassificationService {
         return entity;
     }
 
-    /** C 端：分类下关联的全部 dramaId（按关联创建时间 desc）。 */
+    /** C 端：普通分类保留历史倒序，推荐榜严格按 position 升序。 */
     public List<Long> listDramaIdsByClassification(Long classificationId) {
+        DramaClassification classification = getExisting(classificationId);
+        if (LAYOUT_RANKING.equals(layoutOf(classification))) {
+            return rankingService.orderedDramaIds(classificationId);
+        }
         return classificationDramaMapper.selectList(
                         Wrappers.<DramaClassificationDrama>lambdaQuery()
                                 .eq(DramaClassificationDrama::getClassificationId, classificationId)
@@ -237,10 +266,14 @@ public class DramaClassificationService {
                                 .orderByDesc(DramaClassificationDrama::getId))
                 .stream()
                 .map(DramaClassificationDrama::getDramaId)
-                .collect(Collectors.toList());
+                .toList();
     }
 
     private DramaBriefVO toBrief(Drama drama) {
+        return toBrief(drama, null);
+    }
+
+    private DramaBriefVO toBrief(Drama drama, Integer position) {
         DramaBriefVO vo = new DramaBriefVO();
         vo.setId(drama.getId());
         vo.setTitle(drama.getTitle());
@@ -248,7 +281,54 @@ public class DramaClassificationService {
         vo.setStatus(drama.getStatus());
         vo.setTotalEpisodes(drama.getTotalEpisodes());
         vo.setSort(drama.getSort());
+        vo.setPosition(position);
         vo.setUpdatedAt(drama.getUpdatedAt());
         return vo;
     }
+
+    private void writeClassificationSettings(DramaClassification entity,
+                                             DramaClassificationSaveReqVO req) {
+        if (StringUtils.hasText(req.getCode())) {
+            String code = req.getCode().trim();
+            ensureCodeAvailable(code, entity.getId());
+            entity.setCode(code);
+        }
+        if (StringUtils.hasText(req.getLayoutType())) {
+            entity.setLayoutType(req.getLayoutType());
+        } else if (!StringUtils.hasText(entity.getLayoutType())) {
+            entity.setLayoutType(LAYOUT_GRID);
+        }
+    }
+
+    private void ensureCodeAvailable(String code, Long excludeId) {
+        Long count = classificationMapper.selectCount(Wrappers.<DramaClassification>lambdaQuery()
+                .eq(DramaClassification::getCode, code)
+                .ne(excludeId != null, DramaClassification::getId, excludeId));
+        if (count != null && count > 0) {
+            throw new ServiceException(ErrorCode.DATA_EXISTS, "分类编码已存在");
+        }
+    }
+
+    private String codeOf(DramaClassification classification) {
+        return StringUtils.hasText(classification.getCode())
+                ? classification.getCode()
+                : DEFAULT_CODE_PREFIX + classification.getId();
+    }
+
+    private String layoutOf(DramaClassification classification) {
+        return StringUtils.hasText(classification.getLayoutType())
+                ? classification.getLayoutType()
+                : LAYOUT_GRID;
+    }
+
+    private long revisionOf(DramaClassification classification) {
+        return classification.getRevision() == null ? INITIAL_REVISION : classification.getRevision();
+    }
+
+    private void ensureGridMutation(DramaClassification classification) {
+        if (LAYOUT_RANKING.equals(layoutOf(classification))) {
+            throw new ServiceException(ErrorCode.OPERATION_NOT_ALLOWED,
+                    "推荐榜请使用完整排序接口维护内容");
+        }
+    }
 }

fruitshorts-module-content/src/main/java/com/fruitshorts/content/service/DramaRankingService.java

@@ -0,0 +1,161 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.content.service;
+
+import com.baomidou.mybatisplus.core.toolkit.Wrappers;
+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.DramaClassification;
+import com.fruitshorts.content.dal.entity.DramaClassificationDrama;
+import com.fruitshorts.content.dal.mapper.DramaClassificationDramaMapper;
+import com.fruitshorts.content.dal.mapper.DramaClassificationMapper;
+import com.fruitshorts.content.dal.mapper.DramaMapper;
+import com.fruitshorts.content.vo.DramaBriefVO;
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+import org.springframework.util.StringUtils;
+
+import java.util.LinkedHashSet;
+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 DramaRankingService {
+
+    private static final int MAX_RANKING_ITEMS = 50;
+    private static final long INITIAL_REVISION = 1L;
+
+    private final DramaClassificationMapper classificationMapper;
+    private final DramaClassificationDramaMapper relationMapper;
+    private final DramaMapper dramaMapper;
+
+    /** 原子替换推荐榜内容与顺序，成功后递增版本。 */
+    @Transactional(rollbackFor = Exception.class)
+    public void saveItems(Long classificationId, List<Long> dramaIds) {
+        DramaClassification classification = getRanking(classificationId);
+        List<Long> orderedIds = orderedIds(dramaIds);
+        ensureDramasExist(orderedIds);
+        relationMapper.delete(Wrappers.<DramaClassificationDrama>lambdaQuery()
+                .eq(DramaClassificationDrama::getClassificationId, classificationId));
+        for (int index = 0; index < orderedIds.size(); index++) {
+            relationMapper.insert(relation(classificationId, orderedIds.get(index), index + 1));
+        }
+        long revision = classification.getRevision() == null
+                ? INITIAL_REVISION
+                : classification.getRevision();
+        classification.setRevision(revision + 1);
+        classificationMapper.updateById(classification);
+    }
+
+    /** 推荐榜后台分页，严格按持久化位置返回。 */
+    public PageResult<DramaBriefVO> page(Long classificationId, String keyword,
+                                         int pageIndex, int pageSize) {
+        List<DramaClassificationDrama> relations = orderedRelations(classificationId);
+        if (relations.isEmpty()) {
+            return PageResult.empty();
+        }
+        List<Long> ids = relations.stream().map(DramaClassificationDrama::getDramaId).toList();
+        Map<Long, Drama> dramas = dramaMapper.selectBatchIds(ids).stream()
+                .collect(Collectors.toMap(Drama::getId, Function.identity()));
+        List<DramaBriefVO> all = relations.stream()
+                .filter(item -> dramas.containsKey(item.getDramaId()))
+                .map(item -> toBrief(dramas.get(item.getDramaId()), item.getPosition()))
+                .filter(item -> !StringUtils.hasText(keyword) || item.getTitle().contains(keyword))
+                .toList();
+        return pageOf(all, pageIndex, pageSize);
+    }
+
+    /** 分类内全部短剧 id，严格按 position 升序。 */
+    public List<Long> orderedDramaIds(Long classificationId) {
+        return orderedRelations(classificationId).stream()
+                .map(DramaClassificationDrama::getDramaId)
+                .toList();
+    }
+
+    /** 新增关联时使用的末尾位置。 */
+    public int nextPosition(Long classificationId) {
+        return orderedRelations(classificationId).stream()
+                .map(DramaClassificationDrama::getPosition)
+                .filter(Objects::nonNull)
+                .max(Integer::compareTo)
+                .orElse(0) + 1;
+    }
+
+    private DramaClassification getRanking(Long id) {
+        DramaClassification classification = id == null ? null : classificationMapper.selectById(id);
+        if (classification == null) {
+            throw new ServiceException(ErrorCode.DATA_NOT_FOUND, "分类不存在");
+        }
+        if (!DramaClassificationService.LAYOUT_RANKING.equals(classification.getLayoutType())) {
+            throw new ServiceException(ErrorCode.OPERATION_NOT_ALLOWED, "只有推荐榜分类可以保存榜单顺序");
+        }
+        return classification;
+    }
+
+    private List<Long> orderedIds(List<Long> dramaIds) {
+        LinkedHashSet<Long> unique = new LinkedHashSet<>();
+        if (dramaIds != null) {
+            dramaIds.stream().filter(Objects::nonNull).forEach(unique::add);
+        }
+        if (unique.size() > MAX_RANKING_ITEMS) {
+            throw new ServiceException(ErrorCode.BAD_REQUEST, "推荐榜最多 50 部短剧");
+        }
+        return List.copyOf(unique);
+    }
+
+    private void ensureDramasExist(List<Long> dramaIds) {
+        if (dramaIds.isEmpty()) {
+            return;
+        }
+        if (dramaMapper.selectBatchIds(dramaIds).size() != dramaIds.size()) {
+            throw new ServiceException(ErrorCode.DATA_NOT_FOUND, "榜单中包含不存在的短剧");
+        }
+    }
+
+    private List<DramaClassificationDrama> orderedRelations(Long classificationId) {
+        return relationMapper.selectList(Wrappers.<DramaClassificationDrama>lambdaQuery()
+                .eq(DramaClassificationDrama::getClassificationId, classificationId)
+                .orderByAsc(DramaClassificationDrama::getPosition)
+                .orderByDesc(DramaClassificationDrama::getId));
+    }
+
+    private DramaClassificationDrama relation(Long classificationId, Long dramaId, int position) {
+        DramaClassificationDrama relation = new DramaClassificationDrama();
+        relation.setClassificationId(classificationId);
+        relation.setDramaId(dramaId);
+        relation.setPosition(position);
+        return relation;
+    }
+
+    private DramaBriefVO toBrief(Drama drama, Integer position) {
+        DramaBriefVO vo = new DramaBriefVO();
+        vo.setId(drama.getId());
+        vo.setTitle(drama.getTitle());
+        vo.setCover(drama.getCoverUrl());
+        vo.setStatus(drama.getStatus());
+        vo.setTotalEpisodes(drama.getTotalEpisodes());
+        vo.setSort(drama.getSort());
+        vo.setPosition(position);
+        vo.setUpdatedAt(drama.getUpdatedAt());
+        return vo;
+    }
+
+    private PageResult<DramaBriefVO> pageOf(List<DramaBriefVO> items, int pageIndex, int pageSize) {
+        int safeIndex = Math.max(1, pageIndex);
+        int safeSize = Math.max(1, Math.min(pageSize, 100));
+        int fromIndex = (safeIndex - 1) * safeSize;
+        if (fromIndex >= items.size()) {
+            return new PageResult<>(items.size(), List.of());
+        }
+        int toIndex = Math.min(fromIndex + safeSize, items.size());
+        return new PageResult<>(items.size(), items.subList(fromIndex, toIndex));
+    }
+}

fruitshorts-module-content/src/main/java/com/fruitshorts/content/service/DramaService.java

@@ -464,10 +464,13 @@ public class DramaService {
         if (isNew || req.getCover() != null) {
             drama.setCoverUrl(req.getCover() == null ? "" : req.getCover());
         }
+        if (isNew || req.getHorizontalCover() != null) {
+            drama.setHorizontalCoverUrl(
+                    req.getHorizontalCover() == null ? "" : req.getHorizontalCover());
+        }
         if (isNew || req.getTrailerUrl() != null) {
             drama.setTrailerUrl(req.getTrailerUrl() == null ? "" : req.getTrailerUrl());
         }
-        drama.setHorizontalCoverUrl(drama.getHorizontalCoverUrl() == null ? "" : drama.getHorizontalCoverUrl());
         if (isNew || req.getLanguage() != null) {
             drama.setLanguage(req.getLanguage() == null ? "zh-CN" : req.getLanguage());
         }
@@ -530,6 +533,7 @@ public class DramaService {
             vo.setSynopsisLocales(synopses);
             vo.setSubtitle(drama.getSubtitle());
             vo.setCover(drama.getCoverUrl());
+            vo.setHorizontalCover(drama.getHorizontalCoverUrl());
             vo.setTrailerUrl(drama.getTrailerUrl());
             vo.setLanguage(drama.getLanguage());
             vo.setDramaType(dramaTypes.get(0));

fruitshorts-module-content/src/main/java/com/fruitshorts/content/vo/ContentTagRespVO.java

@@ -14,6 +14,8 @@ public class ContentTagRespVO {
     private String nameId;
     private java.util.Map<String, String> locales;
     private String bgColor;
+    /** 语义码，如 NEW_ARRIVAL；空表示未配置。 */
+    private String code;
     private Integer sort;
     private Integer status;
 }

fruitshorts-module-content/src/main/java/com/fruitshorts/content/vo/ContentTagSaveReqVO.java

@@ -21,6 +21,10 @@ public class ContentTagSaveReqVO {
     @Pattern(regexp = "^$|^#[0-9A-Fa-f]{6}$", message = "背景色格式应为 #RRGGBB")
     private String bgColor;
 
+    /** 语义码，如 NEW_ARRIVAL；客户端按码判断板块，留空表示按文案兜底。 */
+    @Pattern(regexp = "^$|^[A-Z][A-Z0-9_]{0,31}$", message = "语义码需为大写字母、数字或下划线")
+    private String code;
+
     private Integer sort;
     private Integer status;
 }

fruitshorts-module-content/src/main/java/com/fruitshorts/content/vo/DramaBriefVO.java

@@ -16,5 +16,7 @@ public class DramaBriefVO {
     private String status;
     private Integer totalEpisodes;
     private Integer sort;
+    /** 分类内展示位置。 */
+    private Integer position;
     private LocalDateTime updatedAt;
 }

fruitshorts-module-content/src/main/java/com/fruitshorts/content/vo/DramaClassificationRespVO.java

@@ -12,9 +12,12 @@ public class DramaClassificationRespVO {
 
     private Long id;
     private String name;
+    private String code;
     private String nameEn;
     private String nameId;
     private java.util.Map<String, String> locales;
+    private String layoutType;
+    private Long revision;
     private Integer sort;
     private Integer status;
     private Integer dramaCount;

fruitshorts-module-content/src/main/java/com/fruitshorts/content/vo/DramaClassificationSaveReqVO.java

@@ -3,6 +3,7 @@
 package com.fruitshorts.content.vo;
 
 import jakarta.validation.constraints.Size;
+import jakarta.validation.constraints.Pattern;
 import lombok.Data;
 
 /** 分类新增/编辑请求体。 */
@@ -17,6 +18,13 @@ public class DramaClassificationSaveReqVO {
     /** 勾选的语言名称，key 为 zh / en / id。 */
     private java.util.Map<String, String> locales;
 
+    @Size(max = 64, message = "分类编码最多 64 个字符")
+    @Pattern(regexp = "^[A-Z0-9_]*$", message = "分类编码只能包含大写字母、数字和下划线")
+    private String code;
+
+    @Pattern(regexp = "^(GRID|RANKING)$", message = "展示类型只支持 GRID 或 RANKING")
+    private String layoutType;
+
     private Integer sort;
     private Integer status;
 }

fruitshorts-module-content/src/main/java/com/fruitshorts/content/vo/DramaRankingItemsReqVO.java

@@ -0,0 +1,18 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.content.vo;
+
+import jakarta.validation.constraints.NotNull;
+import jakarta.validation.constraints.Size;
+import lombok.Data;
+
+import java.util.List;
+
+/** 推荐榜完整有序短剧列表。 */
+@Data
+public class DramaRankingItemsReqVO {
+
+    @NotNull(message = "请提交推荐榜短剧列表")
+    @Size(max = 50, message = "推荐榜最多 50 部短剧")
+    private List<Long> dramaIds;
+}

fruitshorts-module-content/src/main/java/com/fruitshorts/content/vo/DramaRespVO.java

@@ -27,6 +27,8 @@ public class DramaRespVO {
     private String description;
     private java.util.Map<String, String> synopsisLocales;
     private String cover;
+    /** 横版封面（16:9）。 */
+    private String horizontalCover;
     /** 整剧预告片地址 */
     private String trailerUrl;
     private String language;

fruitshorts-module-content/src/main/java/com/fruitshorts/content/vo/DramaSaveReqVO.java

@@ -26,6 +26,8 @@ public class DramaSaveReqVO {
     /** 勾选语言的简介。 */
     private java.util.Map<String, String> synopsisLocales;
     private String cover;
+    /** 横版封面（16:9），用于横幅等横向位；不传则保持原值。 */
+    private String horizontalCover;
     /** 整剧预告片地址（复用已有的 drama.trailer_url 列） */
     private String trailerUrl;
     private String language;

fruitshorts-module-content/src/test/java/com/fruitshorts/content/service/DramaClassificationServiceTest.java

@@ -0,0 +1,82 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.content.service;
+
+import com.fruitshorts.common.exception.ServiceException;
+import com.fruitshorts.content.dal.entity.DramaClassification;
+import com.fruitshorts.content.dal.entity.DramaClassificationDrama;
+import com.fruitshorts.content.dal.mapper.DramaClassificationDramaMapper;
+import com.fruitshorts.content.dal.mapper.DramaClassificationMapper;
+import com.fruitshorts.content.dal.mapper.DramaMapper;
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.BDDMockito.given;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+
+/** 运营分类布局隔离测试。 */
+class DramaClassificationServiceTest {
+
+    @Test
+    void should_keep_legacy_relation_order_when_classification_is_grid() {
+        Fixture fixture = fixture(DramaClassificationService.LAYOUT_GRID);
+        given(fixture.relationMapper().selectList(any())).willReturn(List.of(
+                relation(21L), relation(13L)));
+
+        List<Long> ids = fixture.service().listDramaIdsByClassification(7L);
+
+        assertThat(ids).containsExactly(21L, 13L);
+        verify(fixture.rankingService(), never()).orderedDramaIds(any());
+    }
+
+    @Test
+    void should_use_position_order_when_classification_is_ranking() {
+        Fixture fixture = fixture(DramaClassificationService.LAYOUT_RANKING);
+        given(fixture.rankingService().orderedDramaIds(7L)).willReturn(List.of(13L, 21L));
+
+        List<Long> ids = fixture.service().listDramaIdsByClassification(7L);
+
+        assertThat(ids).containsExactly(13L, 21L);
+        verify(fixture.relationMapper(), never()).selectList(any());
+    }
+
+    @Test
+    void should_reject_legacy_bind_when_classification_is_ranking() {
+        Fixture fixture = fixture(DramaClassificationService.LAYOUT_RANKING);
+
+        assertThatThrownBy(() -> fixture.service().bindDramas(7L, List.of(13L)))
+                .isInstanceOf(ServiceException.class)
+                .hasMessageContaining("推荐榜请使用完整排序接口");
+    }
+
+    private Fixture fixture(String layoutType) {
+        DramaClassificationMapper classificationMapper = mock(DramaClassificationMapper.class);
+        DramaClassificationDramaMapper relationMapper = mock(DramaClassificationDramaMapper.class);
+        DramaMapper dramaMapper = mock(DramaMapper.class);
+        DramaRankingService rankingService = mock(DramaRankingService.class);
+        DramaClassification classification = new DramaClassification();
+        classification.setId(7L);
+        classification.setLayoutType(layoutType);
+        given(classificationMapper.selectById(7L)).willReturn(classification);
+        DramaClassificationService service = new DramaClassificationService(
+                classificationMapper, relationMapper, dramaMapper, rankingService);
+        return new Fixture(service, relationMapper, rankingService);
+    }
+
+    private DramaClassificationDrama relation(Long dramaId) {
+        DramaClassificationDrama relation = new DramaClassificationDrama();
+        relation.setDramaId(dramaId);
+        return relation;
+    }
+
+    private record Fixture(DramaClassificationService service,
+                           DramaClassificationDramaMapper relationMapper,
+                           DramaRankingService rankingService) {
+    }
+}

fruitshorts-module-content/src/test/java/com/fruitshorts/content/service/DramaRankingServiceTest.java

@@ -0,0 +1,60 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.content.service;
+
+import com.fruitshorts.content.dal.entity.Drama;
+import com.fruitshorts.content.dal.entity.DramaClassification;
+import com.fruitshorts.content.dal.entity.DramaClassificationDrama;
+import com.fruitshorts.content.dal.mapper.DramaClassificationDramaMapper;
+import com.fruitshorts.content.dal.mapper.DramaClassificationMapper;
+import com.fruitshorts.content.dal.mapper.DramaMapper;
+import org.junit.jupiter.api.Test;
+import org.mockito.ArgumentCaptor;
+
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.BDDMockito.given;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.times;
+import static org.mockito.Mockito.verify;
+
+/** 推荐榜内容保存与版本测试。 */
+class DramaRankingServiceTest {
+
+    @Test
+    void should_replace_items_in_request_order_and_increment_revision() {
+        DramaClassificationMapper classificationMapper = mock(DramaClassificationMapper.class);
+        DramaClassificationDramaMapper relationMapper = mock(DramaClassificationDramaMapper.class);
+        DramaMapper dramaMapper = mock(DramaMapper.class);
+        DramaRankingService service = new DramaRankingService(
+                classificationMapper, relationMapper, dramaMapper);
+        DramaClassification classification = new DramaClassification();
+        classification.setId(7L);
+        classification.setLayoutType(DramaClassificationService.LAYOUT_RANKING);
+        classification.setRevision(4L);
+        given(classificationMapper.selectById(7L)).willReturn(classification);
+        given(dramaMapper.selectBatchIds(List.of(22L, 11L)))
+                .willReturn(List.of(drama(11L), drama(22L)));
+
+        service.saveItems(7L, List.of(22L, 11L, 22L));
+
+        ArgumentCaptor<DramaClassificationDrama> captor =
+                ArgumentCaptor.forClass(DramaClassificationDrama.class);
+        verify(relationMapper, times(2)).insert(captor.capture());
+        assertThat(captor.getAllValues()).extracting(DramaClassificationDrama::getDramaId)
+                .containsExactly(22L, 11L);
+        assertThat(captor.getAllValues()).extracting(DramaClassificationDrama::getPosition)
+                .containsExactly(1, 2);
+        assertThat(classification.getRevision()).isEqualTo(5L);
+        verify(classificationMapper).updateById(classification);
+        verify(relationMapper).delete(any());
+    }
+
+    private Drama drama(Long id) {
+        Drama drama = new Drama();
+        drama.setId(id);
+        return drama;
+    }
+}

fruitshorts-module-playback/pom.xml

@@ -33,5 +33,10 @@
             <groupId>com.fruitshorts</groupId>
             <artifactId>fruitshorts-module-user</artifactId>
         </dependency>
+        <!-- 进度上报路径的剧集/短剧进程内缓存（版本由 Spring Boot BOM 管理） -->
+        <dependency>
+            <groupId>com.github.ben-manes.caffeine</groupId>
+            <artifactId>caffeine</artifactId>
+        </dependency>
     </dependencies>
 </project>

fruitshorts-module-playback/src/main/java/com/fruitshorts/playback/dal/mapper/WatchProgressMapper.java

@@ -8,6 +8,8 @@ import org.apache.ibatis.annotations.Param;
 import org.apache.ibatis.annotations.Select;
 import org.apache.ibatis.annotations.Update;
 
+import java.util.List;
+
 public interface WatchProgressMapper extends BaseMapper<WatchProgress> {
 
     /** 按登录用户或匿名设备读取同一部剧的记录，包含逻辑删除行。 */
@@ -40,4 +42,64 @@ public interface WatchProgressMapper extends BaseMapper<WatchProgress> {
             WHERE id = #{id}
             """)
     int updateAny(WatchProgress progress);
+
+    /** 固定形状的全字段按 id 更新（绕过逻辑删除过滤）。SQL 不随字段空值变化，
+     * 缓冲落库时连续调用可被 MyBatis BATCH 执行器合成一个 JDBC batch。 */
+    @Update("""
+            UPDATE watch_progress SET
+              episode_id = #{et.episodeId},
+              position_ms = #{et.positionMs},
+              duration_ms = #{et.durationMs},
+              finished = #{et.finished},
+              play_count = #{et.playCount},
+              device_id = #{et.deviceId},
+              source = #{et.source},
+              deleted = #{et.deleted}
+            WHERE id = #{et.id}
+            """)
+    int updateRowAny(@Param("et") WatchProgress et);
+
+    /** 批量读取同一身份下多部剧的记录（含逻辑删除行），供缓冲落库合并使用。 */
+    @Select("""
+            <script>
+            SELECT * FROM watch_progress
+            WHERE
+              <choose>
+                <when test="userId != null">user_id = #{userId,jdbcType=BIGINT}</when>
+                <otherwise>user_id IS NULL AND device_id = #{deviceId}</otherwise>
+              </choose>
+              AND drama_id IN
+              <foreach collection="dramaIds" item="d" open="(" separator="," close=")">#{d}</foreach>
+            </script>
+            """)
+    List<WatchProgress> selectAnyForIdentityIn(
+            @Param("userId") Long userId,
+            @Param("deviceId") String deviceId,
+            @Param("dramaIds") List<Long> dramaIds);
+
+    /** 落库合并的查询参数：身份（登录用户或匿名设备）+ drama。 */
+    @lombok.Data
+    @lombok.NoArgsConstructor
+    @lombok.AllArgsConstructor
+    class IdentityDramaPair {
+        private Long userId;
+        private String deviceId;
+        private long dramaId;
+    }
+
+    /** 按多组「身份 + drama」批量读取记录（含逻辑删除行），一组一条索引条件，单次往返。 */
+    @Select("""
+            <script>
+            SELECT * FROM watch_progress WHERE
+            <foreach collection="pairs" item="p" separator=" OR ">
+              (
+                (#{p.userId,jdbcType=BIGINT} IS NOT NULL AND user_id = #{p.userId,jdbcType=BIGINT})
+                OR
+                (#{p.userId,jdbcType=BIGINT} IS NULL AND user_id IS NULL AND device_id = #{p.deviceId})
+              )
+              AND drama_id = #{p.dramaId}
+            </foreach>
+            </script>
+            """)
+    List<WatchProgress> selectBatchForPairs(@Param("pairs") List<IdentityDramaPair> pairs);
 }

fruitshorts-module-playback/src/main/java/com/fruitshorts/playback/service/WatchProgressBuffer.java

@@ -0,0 +1,355 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.playback.service;
+
+import com.fruitshorts.common.interaction.InteractionIdentity;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.data.redis.core.SessionCallback;
+import org.springframework.data.redis.core.StringRedisTemplate;
+import org.springframework.data.redis.core.script.DefaultRedisScript;
+import org.springframework.stereotype.Component;
+
+import java.time.Duration;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * 观看进度 Redis 缓冲（write-behind）。
+ *
+ * <p>高并发上报的落地形态：POST 只写 Redis（Lua 脚本一次往返完成写状态与入队），由
+ * {@link WatchProgressFlusher} 定时把缓冲按「账号或设备 + drama」合并后批量 UPSERT
+ * 进权威表 watch_progress。Redis 不可用时 put 返回 false，调用方回退同步写库。
+ *
+ * <p>Redis 结构：
+ * <ul>
+ *   <li>{@code watch:pg:buf:u:{userId}} / {@code watch:pg:buf:d:{deviceId}}：
+ *       HASH，field=dramaId，value=进度状态，作为读接口的「读己之写」覆盖层，TTL 12h；</li>
+ *   <li>{@code watch:pg:dirty}：LIST，value={identityKey}|{dramaId}，待落库队列，
+ *       定时任务 RPOP 消费；重复条目靠幂等合并消化。</li>
+ * </ul>
+ */
+@Slf4j
+@Component
+@RequiredArgsConstructor
+@ConditionalOnProperty(name = "fruitshorts.watch-progress.buffer", havingValue = "true")
+public class WatchProgressBuffer {
+
+    private static final String BUF_KEY_PREFIX = "watch:pg:buf:";
+    private static final String DIRTY_KEY = "watch:pg:dirty";
+    /** 待落库队列长度上限，防止 Redis 在落库停滞时无限膨胀。 */
+    private static final long MAX_DIRTY = 200_000;
+    /** 每个身份最多缓冲 30 部剧（续看列表第一页用不完，同时限制 HGETALL 大小）。 */
+    private static final int MAX_DRAMAS_PER_IDENTITY = 30;
+    private static final Duration TTL = Duration.ofHours(12);
+
+    /**
+     * 上报热路径的单次往返脚本：写状态、续 TTL、入待落库队列、截断队列一次做完。
+     * 拆成多条命令时进程若死在「写状态」与「入队」之间，该剧进度只留在 HASH 里、
+     * 永远不会落库，12 小时后被 TTL 清掉。返回 1 表示该身份的剧数超限，需要补充裁剪。
+     */
+    private static final DefaultRedisScript<Long> PUT_SCRIPT = new DefaultRedisScript<>("""
+            redis.call('HSET', KEYS[1], ARGV[1], ARGV[2])
+            redis.call('EXPIRE', KEYS[1], ARGV[3])
+            redis.call('LPUSH', KEYS[2], ARGV[4])
+            redis.call('LTRIM', KEYS[2], 0, ARGV[5])
+            if redis.call('HLEN', KEYS[1]) > tonumber(ARGV[6]) then
+              return 1
+            end
+            return 0
+            """, Long.class);
+
+    private final StringRedisTemplate redis;
+
+    /**
+     * 缓冲中的一条进度状态。ts 为客户端上报时刻（服务端毫秒），用于判断
+     * 缓冲值是否比数据库行新，以及合并时丢弃乱序旧值。
+     */
+    public record BufferedProgress(
+            long dramaId,
+            long episodeId,
+            long positionMs,
+            long durationMs,
+            boolean finished,
+            String source,
+            String deviceId,
+            long ts) {
+    }
+
+    /** dirty 队列弹出的一条待落库引用。 */
+    public record IdentityRef(String key, Long userId, String deviceId, long dramaId) {
+
+        public InteractionIdentity toIdentity() {
+            return userId != null
+                    ? new InteractionIdentity(userId, "")
+                    : new InteractionIdentity(null, deviceId);
+        }
+    }
+
+    /** 上报进度入缓冲。成功返回 true；Redis 异常返回 false，调用方回退同步写库。 */
+    public boolean put(InteractionIdentity identity, long dramaId, long episodeId,
+                       long positionMs, long durationMs, boolean finished,
+                       String source, String deviceId) {
+        try {
+            String key = identityKey(identity);
+            String hashKey = BUF_KEY_PREFIX + key;
+            String field = Long.toString(dramaId);
+            Long overflow = redis.execute(PUT_SCRIPT,
+                    List.of(hashKey, DIRTY_KEY),
+                    field,
+                    encode(episodeId, positionMs, durationMs, finished, source, deviceId),
+                    Long.toString(TTL.toSeconds()),
+                    key + "|" + field,
+                    Long.toString(MAX_DIRTY - 1),
+                    Integer.toString(MAX_DRAMAS_PER_IDENTITY));
+            if (overflow != null && overflow > 0) {
+                // 超出 30 部才做一次 HGETALL + HDEL 裁剪，热路径保持单次往返
+                trimIdentity(hashKey);
+            }
+            return true;
+        } catch (Exception e) {
+            log.warn("观看进度写入 Redis 缓冲失败，本次回退同步写库: {}", e.getMessage());
+            return false;
+        }
+    }
+
+    /**
+     * 删除某部剧的缓冲状态，用于用户删除单条观看记录。
+     *
+     * <p>缓冲是读接口的权威来源，删库行必须同步删缓冲，否则会被读覆盖层读回；
+     * 同时缓冲状态消失后，dirty 队列里该条引用在落库时会被丢弃（见
+     * {@code WatchProgressService#flushRefs}），不会再被写回库。
+     */
+    public boolean remove(InteractionIdentity identity, long dramaId) {
+        try {
+            redis.opsForHash().delete(BUF_KEY_PREFIX + identityKey(identity), Long.toString(dramaId));
+            return true;
+        } catch (Exception e) {
+            log.warn("观看进度缓冲删除失败: {}", e.getMessage());
+            return false;
+        }
+    }
+
+    /** 清空某身份的全部缓冲状态，用于用户清空观看历史。 */
+    public boolean clear(InteractionIdentity identity) {
+        try {
+            redis.delete(BUF_KEY_PREFIX + identityKey(identity));
+            return true;
+        } catch (Exception e) {
+            log.warn("观看进度缓冲清空失败: {}", e.getMessage());
+            return false;
+        }
+    }
+
+    /** 读单个剧的缓冲状态；无缓冲或解码失败返回 null。 */
+    public BufferedProgress get(InteractionIdentity identity, long dramaId) {
+        return get(identityKey(identity), dramaId);
+    }
+
+    public BufferedProgress get(String identityKey, long dramaId) {
+        try {
+            Object value = redis.opsForHash().get(BUF_KEY_PREFIX + identityKey, Long.toString(dramaId));
+            return value == null ? null : decode(dramaId, value.toString());
+        } catch (Exception e) {
+            log.warn("观看进度读取 Redis 缓冲失败: {}", e.getMessage());
+            return null;
+        }
+    }
+
+    /** 读某身份全部缓冲状态（≤30 部剧），读接口覆盖层用。 */
+    public Map<Long, BufferedProgress> getAll(InteractionIdentity identity) {
+        return getAll(identityKey(identity));
+    }
+
+    public Map<Long, BufferedProgress> getAll(String identityKey) {
+        try {
+            return decodeAll(redis.opsForHash().entries(BUF_KEY_PREFIX + identityKey));
+        } catch (Exception e) {
+            log.warn("观看进度读取 Redis 缓冲失败: {}", e.getMessage());
+            return Map.of();
+        }
+    }
+
+    /** 批量读取多个身份的缓冲状态（pipeline 单次往返），落库任务用。 */
+    @SuppressWarnings("unchecked")
+    public Map<String, Map<Long, BufferedProgress>> getAllBatch(List<String> identityKeys) {
+        if (identityKeys.isEmpty()) {
+            return Map.of();
+        }
+        try {
+            List<Object> results = redis.executePipelined(new SessionCallback<>() {
+                @Override
+                public Object execute(org.springframework.data.redis.core.RedisOperations operations) {
+                    for (String key : identityKeys) {
+                        operations.opsForHash().entries(BUF_KEY_PREFIX + key);
+                    }
+                    return null;
+                }
+            });
+            Map<String, Map<Long, BufferedProgress>> result = new LinkedHashMap<>();
+            for (int i = 0; i < identityKeys.size(); i++) {
+                Object raw = results.get(i);
+                result.put(identityKeys.get(i),
+                        raw instanceof Map<?, ?> map ? decodeAll((Map<Object, Object>) map) : Map.of());
+            }
+            return result;
+        } catch (Exception e) {
+            log.warn("观看进度批量读取 Redis 缓冲失败: {}", e.getMessage());
+            throw new IllegalStateException("Redis 缓冲批量读取失败", e);
+        }
+    }
+
+    /** 落库任务从 dirty 队头弹出最多 max 条（按 identity+drama 去重，保留顺序）。 */
+    public List<IdentityRef> drain(int max) {
+        List<String> raw;
+        try {
+            raw = redis.opsForList().leftPop(DIRTY_KEY, Math.max(1, max));
+        } catch (Exception e) {
+            log.warn("观看进度 dirty 队列弹出失败: {}", e.getMessage());
+            return List.of();
+        }
+        if (raw == null || raw.isEmpty()) {
+            return List.of();
+        }
+        LinkedHashMap<String, IdentityRef> dedup = new LinkedHashMap<>();
+        for (String value : raw) {
+            int split = value.lastIndexOf('|');
+            if (split <= 0) {
+                continue;
+            }
+            String key = value.substring(0, split);
+            long dramaId;
+            try {
+                dramaId = Long.parseLong(value.substring(split + 1));
+            } catch (NumberFormatException ignore) {
+                continue;
+            }
+            dedup.putIfAbsent(key + "|" + dramaId, toRef(key, dramaId));
+        }
+        return new ArrayList<>(dedup.values());
+    }
+
+    /** 落库失败的条目退回队列，等待下个周期重试。 */
+    public void requeue(List<IdentityRef> refs) {
+        try {
+            List<String> raw = refs.stream()
+                    .map(r -> r.key() + "|" + r.dramaId())
+                    .toList();
+            redis.opsForList().rightPushAll(DIRTY_KEY, raw);
+            redis.opsForList().trim(DIRTY_KEY, 0, MAX_DIRTY - 1);
+        } catch (Exception e) {
+            log.error("观看进度缓冲条目退回队列失败，这批进度将丢失: {}", e.getMessage());
+        }
+    }
+
+    /** 身份的 Redis 键：登录用 u:{userId}，匿名用 d:{deviceId}。 */
+    public String identityKey(InteractionIdentity identity) {
+        return identity.authenticated()
+                ? "u:" + identity.userId()
+                : "d:" + cleanToken(identity.deviceId());
+    }
+
+    private IdentityRef toRef(String key, long dramaId) {
+        int split = key.indexOf(':');
+        if (split <= 0) {
+            return new IdentityRef(key, null, key, dramaId);
+        }
+        String scope = key.substring(0, split);
+        String id = key.substring(split + 1);
+        if ("u".equals(scope)) {
+            try {
+                return new IdentityRef(key, Long.valueOf(id), "", dramaId);
+            } catch (NumberFormatException ignore) {
+                // 落到匿名分支
+            }
+        }
+        return new IdentityRef(key, null, id, dramaId);
+    }
+
+    private String encode(long episodeId, long positionMs, long durationMs,
+                          boolean finished, String source, String deviceId) {
+        return episodeId + "|" + positionMs + "|" + durationMs + "|" + (finished ? 1 : 0)
+                + "|" + cleanToken(source) + "|" + cleanToken(deviceId) + "|" + System.currentTimeMillis();
+    }
+
+    private BufferedProgress decode(long dramaId, String value) {
+        try {
+            String[] parts = value.split("\\|", -1);
+            if (parts.length != 7) {
+                return null;
+            }
+            return new BufferedProgress(
+                    dramaId,
+                    Long.parseLong(parts[0]),
+                    Long.parseLong(parts[1]),
+                    Long.parseLong(parts[2]),
+                    "1".equals(parts[3]),
+                    parts[4],
+                    parts[5],
+                    Long.parseLong(parts[6]));
+        } catch (NumberFormatException e) {
+            log.debug("观看进度缓冲值解码失败，忽略: {}", value);
+            return null;
+        }
+    }
+
+    private Map<Long, BufferedProgress> decodeAll(Map<Object, Object> raw) {
+        if (raw == null || raw.isEmpty()) {
+            return Map.of();
+        }
+        Map<Long, BufferedProgress> result = new LinkedHashMap<>();
+        for (Map.Entry<Object, Object> e : raw.entrySet()) {
+            long dramaId;
+            try {
+                dramaId = Long.parseLong(e.getKey().toString());
+            } catch (NumberFormatException ignore) {
+                continue;
+            }
+            BufferedProgress state = decode(dramaId, e.getValue().toString());
+            if (state != null) {
+                result.put(dramaId, state);
+            }
+        }
+        return result;
+    }
+
+    /** 限制单身份缓冲的剧数：超出时淘汰最旧条目，保证 HGETALL 与读覆盖层开销有界。 */
+    private void trimIdentity(String hashKey) {
+        Long size = redis.opsForHash().size(hashKey);
+        if (size == null || size <= MAX_DRAMAS_PER_IDENTITY) {
+            return;
+        }
+        Map<Object, Object> all = redis.opsForHash().entries(hashKey);
+        List<Map.Entry<Object, Long>> byTs = new ArrayList<>(all.size());
+        for (Map.Entry<Object, Object> e : all.entrySet()) {
+            long ts = 0;
+            if (e.getValue() != null) {
+                String[] parts = e.getValue().toString().split("\\|", -1);
+                try {
+                    ts = Long.parseLong(parts[parts.length - 1]);
+                } catch (NumberFormatException ignore) {
+                    // ts 取不到当最旧，优先淘汰
+                }
+            }
+            byTs.add(Map.entry(e.getKey(), ts));
+        }
+        byTs.sort(Map.Entry.comparingByValue());
+        int toRemove = Math.max(0, byTs.size() - MAX_DRAMAS_PER_IDENTITY);
+        if (toRemove > 0) {
+            redis.opsForHash().delete(hashKey,
+                    byTs.subList(0, toRemove).stream().map(Map.Entry::getKey).toArray());
+        }
+    }
+
+    /** value 中的 source/deviceId 不允许出现分隔符 | 与换行，统一清洗；长度截到 128。 */
+    private String cleanToken(String token) {
+        if (token == null) {
+            return "";
+        }
+        String cleaned = token.replace("|", "").replace("\n", "").replace("\r", "").trim();
+        return cleaned.length() > 128 ? cleaned.substring(0, 128) : cleaned;
+    }
+}

fruitshorts-module-playback/src/main/java/com/fruitshorts/playback/service/WatchProgressFlusher.java

@@ -0,0 +1,43 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.playback.service;
+
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.scheduling.annotation.Scheduled;
+import org.springframework.stereotype.Component;
+
+/**
+ * 观看进度缓冲落库任务：定时把 Redis 缓冲里的进度按身份分组合并进 watch_progress。
+ *
+ * <p>只在开启缓冲（fruitshorts.watch-progress.buffer=true）的应用内生效，
+ * app-api 的 prod profile 开启，admin-api 与测试环境不受影响。
+ * fixedDelay 串行执行，同一时刻只有一个落库批次在跑。
+ */
+@Slf4j
+@Component
+@RequiredArgsConstructor
+@ConditionalOnProperty(name = "fruitshorts.watch-progress.buffer", havingValue = "true")
+public class WatchProgressFlusher {
+
+    private final WatchProgressService watchProgressService;
+
+    @Value("${fruitshorts.watch-progress.flush-batch-size:10000}")
+    private int batchSize;
+
+    @Scheduled(
+            fixedDelayString = "${fruitshorts.watch-progress.flush-interval-ms:2000}",
+            initialDelayString = "${fruitshorts.watch-progress.flush-initial-delay-ms:15000}")
+    public void flush() {
+        try {
+            int flushed = watchProgressService.flushBuffered(batchSize);
+            if (flushed > 0) {
+                log.debug("观看进度缓冲落库完成，本批次 {} 条", flushed);
+            }
+        } catch (Exception e) {
+            log.warn("观看进度缓冲落库失败，等待下个周期重试: {}", e.getMessage());
+        }
+    }
+}

fruitshorts-module-playback/src/main/java/com/fruitshorts/playback/service/WatchProgressService.java

@@ -19,29 +19,47 @@ import com.fruitshorts.playback.dal.mapper.WatchHistoryMapper;
 import com.fruitshorts.playback.dal.mapper.WatchProgressMapper;
 import com.fruitshorts.playback.vo.ProgressRespVO;
 import com.fruitshorts.playback.vo.ProgressSaveReqVO;
+import com.github.benmanes.caffeine.cache.Cache;
+import com.github.benmanes.caffeine.cache.Caffeine;
 import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.apache.ibatis.session.ExecutorType;
+import org.apache.ibatis.session.SqlSession;
+import org.apache.ibatis.session.SqlSessionFactory;
+import org.springframework.beans.factory.ObjectProvider;
 import org.springframework.dao.DuplicateKeyException;
 import org.springframework.stereotype.Service;
 import org.springframework.transaction.annotation.Transactional;
+import org.springframework.transaction.support.TransactionTemplate;
 import org.springframework.util.StringUtils;
 
+import java.time.Duration;
+import java.time.Instant;
 import java.time.LocalDateTime;
+import java.time.ZoneId;
 import java.util.ArrayList;
+import java.util.Comparator;
 import java.util.HashMap;
+import java.util.HashSet;
 import java.util.List;
 import java.util.Map;
 import java.util.Objects;
+import java.util.Set;
+import java.util.stream.Collectors;
 
 /**
  * 观看进度。
  *
- * <p>每次上报都写库在高并发下会成为瓶颈（1 万并发 × 每 10 秒一次 ≈ 1000 写/秒），
- * 所以生产形态是「先写 Redis，后台任务按登录账号或设备 + drama 合并后批量 UPSERT」。
- * 这里先落地权威表与合并规则，缓存层在接入 Redis 时补齐，接口契约不变。
+ * <p>生产形态（fruitshorts.watch-progress.buffer=true，prod 已开启）：
+ * POST 只写 Redis 缓冲（{@link WatchProgressBuffer}）立即返回，
+ * {@link WatchProgressFlusher} 定时把缓冲按「账号或设备 + drama」合并后
+ * 批量 UPSERT 进权威表，读接口用缓冲覆盖保证读己之写。
+ * 缓冲关闭或 Redis 异常时自动回退同步写库，接口契约不变。
  *
  * <p>合并规则：以客户端上报的 positionMs 为准，但只在「更靠后」时覆盖，
  * 避免用户换设备后进度倒退。
  */
+@Slf4j
 @Service
 @RequiredArgsConstructor
 public class WatchProgressService {
@@ -53,68 +71,101 @@ public class WatchProgressService {
     private final WatchHistoryMapper historyMapper;
     private final DramaService dramaService;
     private final EpisodeService episodeService;
+    private final ObjectProvider<WatchProgressBuffer> bufferProvider;
+    private final SqlSessionFactory sqlSessionFactory;
+    private final TransactionTemplate transactionTemplate;
+
+    /** 已发布剧集/短剧的短 TTL 进程内缓存：上报路径的热点校验，免去每次两条 DB 查询。 */
+    private final Cache<Long, DramaEpisode> episodeCache = Caffeine.newBuilder()
+            .maximumSize(50_000)
+            .expireAfterWrite(Duration.ofMinutes(5))
+            .build();
+    private final Cache<Long, Drama> dramaCache = Caffeine.newBuilder()
+            .maximumSize(50_000)
+            .expireAfterWrite(Duration.ofMinutes(5))
+            .build();
 
-    @Transactional(rollbackFor = Exception.class)
     public ProgressRespVO save(Long userId, ProgressSaveReqVO req) {
         return save(new InteractionIdentity(userId, ""), req);
     }
 
-    @Transactional(rollbackFor = Exception.class)
     public ProgressRespVO save(InteractionIdentity identity, ProgressSaveReqVO req) {
-        DramaEpisode episode = episodeService.getPublished(req.getEpisodeId());
-        Drama drama = dramaService.getPublished(episode.getDramaId());
+        DramaEpisode episode = publishedEpisode(req.getEpisodeId());
+        Drama drama = publishedDrama(episode.getDramaId());
         long position = req.getPositionMs() == null ? 0L : Math.max(0L, req.getPositionMs());
         long duration = req.getDurationMs() == null ? 0L : Math.max(0L, req.getDurationMs());
         boolean finished = Boolean.TRUE.equals(req.getFinished())
                 || (duration > 0 && position + FINISH_THRESHOLD_MS >= duration);
 
-        LoadedProgress loaded = loadForSave(identity, drama.getId(), episode, position, duration,
-                finished, req);
-        WatchProgress existing = loaded.progress();
-        if (loaded.created()) {
-            appendHistory(identity, drama.getId(), episode.getId(), position, duration,
-                    existing.getSource(), existing.getDeviceId());
-            return toResp(progressMapper.selectById(existing.getId()));
+        // 高并发形态：写 Redis 缓冲立即返回，落库任务稍后合并进权威表
+        WatchProgressBuffer buffer = bufferProvider.getIfAvailable();
+        if (buffer != null && buffer.put(identity, drama.getId(), episode.getId(),
+                position, duration, finished, req.getSource(), req.getDeviceId())) {
+            ProgressRespVO vo = new ProgressRespVO();
+            vo.setDramaId(drama.getId());
+            vo.setEpisodeId(episode.getId());
+            vo.setPositionMs(position);
+            vo.setDurationMs(duration);
+            vo.setFinished(finished);
+            vo.setUpdatedAt(LocalDateTime.now());
+            return vo;
         }
+        return saveToDb(identity, drama, episode, position, duration, finished, req);
+    }
 
-        boolean hidden = existing.getDeleted() != null && existing.getDeleted() != 0;
-        boolean sameEpisode = existing.getEpisodeId() != null
-                && existing.getEpisodeId().equals(episode.getId());
-        if (hidden && sameEpisode) {
-            existing.setPlayCount((existing.getPlayCount() == null ? 0 : existing.getPlayCount()) + 1);
-            appendHistory(identity, drama.getId(), episode.getId(), position, duration,
-                    req.getSource(), existing.getDeviceId());
-        }
-        if (!sameEpisode) {
-            // 换集：直接采纳新集与新的播放位置
-            existing.setEpisodeId(episode.getId());
-            existing.setPositionMs(position);
-            existing.setDurationMs(duration);
-            existing.setFinished(finished ? 1 : 0);
-            existing.setPlayCount((existing.getPlayCount() == null ? 0 : existing.getPlayCount()) + 1);
-            appendHistory(identity, drama.getId(), episode.getId(), position, duration,
-                    req.getSource(), existing.getDeviceId());
-        } else {
-            existing.setDurationMs(Math.max(existing.getDurationMs() == null ? 0L : existing.getDurationMs(),
-                    duration));
-            if (position >= (existing.getPositionMs() == null ? 0L : existing.getPositionMs())) {
+    /** 同步写库路径：缓冲关闭或 Redis 异常时的回退，合并规则与缓冲落库一致。 */
+    private ProgressRespVO saveToDb(InteractionIdentity identity, Drama drama, DramaEpisode episode,
+                                    long position, long duration, boolean finished,
+                                    ProgressSaveReqVO req) {
+        return transactionTemplate.execute(status -> {
+            LoadedProgress loaded = loadForSave(identity, drama.getId(), episode, position, duration,
+                    finished, req);
+            WatchProgress existing = loaded.progress();
+            if (loaded.created()) {
+                appendHistory(identity, drama.getId(), episode.getId(), position, duration,
+                        existing.getSource(), existing.getDeviceId());
+                return toResp(progressMapper.selectById(existing.getId()));
+            }
+
+            boolean hidden = existing.getDeleted() != null && existing.getDeleted() != 0;
+            boolean sameEpisode = existing.getEpisodeId() != null
+                    && existing.getEpisodeId().equals(episode.getId());
+            if (hidden && sameEpisode) {
+                existing.setPlayCount((existing.getPlayCount() == null ? 0 : existing.getPlayCount()) + 1);
+                appendHistory(identity, drama.getId(), episode.getId(), position, duration,
+                        req.getSource(), existing.getDeviceId());
+            }
+            if (!sameEpisode) {
+                // 换集：直接采纳新集与新的播放位置
+                existing.setEpisodeId(episode.getId());
                 existing.setPositionMs(position);
+                existing.setDurationMs(duration);
+                existing.setFinished(finished ? 1 : 0);
+                existing.setPlayCount((existing.getPlayCount() == null ? 0 : existing.getPlayCount()) + 1);
+                appendHistory(identity, drama.getId(), episode.getId(), position, duration,
+                        req.getSource(), existing.getDeviceId());
+            } else {
+                existing.setDurationMs(Math.max(existing.getDurationMs() == null ? 0L : existing.getDurationMs(),
+                        duration));
+                if (position >= (existing.getPositionMs() == null ? 0L : existing.getPositionMs())) {
+                    existing.setPositionMs(position);
+                }
+                if (finished) {
+                    existing.setFinished(1);
+                }
             }
-            if (finished) {
-                existing.setFinished(1);
+            existing.setDeviceId(identity.authenticated()
+                    ? (req.getDeviceId() == null ? "" : req.getDeviceId())
+                    : identity.deviceId());
+            existing.setSource(req.getSource() == null ? "" : req.getSource());
+            if (hidden) {
+                existing.setDeleted(0);
+                progressMapper.updateAny(existing);
+            } else {
+                progressMapper.updateById(existing);
             }
-        }
-        existing.setDeviceId(identity.authenticated()
-                ? (req.getDeviceId() == null ? "" : req.getDeviceId())
-                : identity.deviceId());
-        existing.setSource(req.getSource() == null ? "" : req.getSource());
-        if (hidden) {
-            existing.setDeleted(0);
-            progressMapper.updateAny(existing);
-        } else {
-            progressMapper.updateById(existing);
-        }
-        return toResp(progressMapper.selectById(existing.getId()));
+            return toResp(progressMapper.selectById(existing.getId()));
+        });
     }
 
     private LoadedProgress loadForSave(InteractionIdentity identity, Long dramaId,
@@ -169,6 +220,16 @@ public class WatchProgressService {
         WatchProgress progress = progressMapper.selectOne(identityQuery(identity)
                 .eq(WatchProgress::getDramaId, dramaId)
                 .last("limit 1"));
+        // 读己之写：缓冲里有比库行更新的状态时以缓冲为准
+        WatchProgressBuffer buffer = bufferProvider.getIfAvailable();
+        if (buffer != null) {
+            WatchProgressBuffer.BufferedProgress buffered = buffer.get(identity, dramaId);
+            if (buffered != null
+                    && (progress == null
+                    || buffered.ts() > toMillis(progress.getUpdatedAt()))) {
+                return toResp(buffered, progress);
+            }
+        }
         return progress == null ? null : toResp(progress);
     }
 
@@ -186,7 +247,59 @@ public class WatchProgressService {
                 identityQuery(identity)
                         .orderByDesc(WatchProgress::getUpdatedAt)
                         .orderByDesc(WatchProgress::getId));
-        return new PageResult<>(result.getTotal(), enrichDisplay(result.getRecords()));
+
+        // 缓冲的条目都是最近上报的，只会出现在第一页；缓冲关闭时走原逻辑
+        WatchProgressBuffer buffer = bufferProvider.getIfAvailable();
+        if (buffer == null || safeIndex > 1) {
+            return new PageResult<>(result.getTotal(), enrichDisplay(result.getRecords()));
+        }
+        Map<Long, WatchProgressBuffer.BufferedProgress> states = buffer.getAll(identity);
+        if (states.isEmpty()) {
+            return new PageResult<>(result.getTotal(), enrichDisplay(result.getRecords()));
+        }
+
+        List<WatchProgress> merged = new ArrayList<>();
+        Set<Long> pageDramas = new HashSet<>();
+        for (WatchProgress row : result.getRecords()) {
+            pageDramas.add(row.getDramaId());
+            WatchProgressBuffer.BufferedProgress buffered = row.getDramaId() == null
+                    ? null
+                    : states.get(row.getDramaId());
+            merged.add(overlayRow(row, buffered));
+        }
+        long total = result.getTotal();
+        // 缓冲里有、页里没有的剧补进第一页（刚上报首集、库里还没落的场景）
+        List<WatchProgressBuffer.BufferedProgress> extra = states.entrySet().stream()
+                .filter(e -> !pageDramas.contains(e.getKey()))
+                .map(Map.Entry::getValue)
+                .sorted(Comparator.comparingLong(WatchProgressBuffer.BufferedProgress::ts).reversed())
+                .toList();
+        if (!extra.isEmpty()) {
+            List<Long> extraDramaIds = extra.stream()
+                    .map(WatchProgressBuffer.BufferedProgress::dramaId)
+                    .toList();
+            Map<Long, WatchProgress> rowByDrama = progressMapper.selectAnyForIdentityIn(
+                            identity.userId(), identity.deviceId(), extraDramaIds)
+                    .stream()
+                    .collect(Collectors.toMap(WatchProgress::getDramaId, row -> row, (a, b) -> a));
+            for (WatchProgressBuffer.BufferedProgress buffered : extra) {
+                WatchProgress existing = rowByDrama.get(buffered.dramaId());
+                // 用户已删除该剧（库里是逻辑删除行）：缓冲状态不能被读覆盖层再读回来
+                if (existing != null && existing.getDeleted() != null && existing.getDeleted() != 0) {
+                    continue;
+                }
+                merged.add(transientRow(buffered));
+                if (existing == null) {
+                    total++;
+                }
+            }
+        }
+        merged.sort(Comparator.comparing(WatchProgress::getUpdatedAt,
+                Comparator.nullsFirst(Comparator.naturalOrder())).reversed());
+        List<WatchProgress> page = merged.size() > safeSize
+                ? merged.subList(0, safeSize)
+                : merged;
+        return new PageResult<>(total, enrichDisplay(page));
     }
 
     @Transactional(rollbackFor = Exception.class)
@@ -196,6 +309,12 @@ public class WatchProgressService {
 
     @Transactional(rollbackFor = Exception.class)
     public void remove(InteractionIdentity identity, Long dramaId) {
+        // 缓冲是读接口的权威来源：先删缓冲再删库行，否则删掉的记录会被读覆盖层读回、
+        // 并被下一次落库把行复活。
+        WatchProgressBuffer buffer = bufferProvider.getIfAvailable();
+        if (buffer != null && dramaId != null) {
+            buffer.remove(identity, dramaId);
+        }
         progressMapper.delete(identityQuery(identity)
                 .eq(WatchProgress::getDramaId, dramaId));
     }
@@ -207,9 +326,198 @@ public class WatchProgressService {
 
     @Transactional(rollbackFor = Exception.class)
     public void clear(InteractionIdentity identity) {
+        WatchProgressBuffer buffer = bufferProvider.getIfAvailable();
+        if (buffer != null) {
+            buffer.clear(identity);
+        }
         progressMapper.delete(identityQuery(identity));
     }
 
+    /**
+     * 缓冲落库：由 {@link WatchProgressFlusher} 定时调用。
+     * 消费 dirty 队列，pipeline 读状态、分块成对查行，先在内存里合并出
+     * 「新增进度 / 新增流水 / 更新行」三组，再在一个 JDBC batch 会话内
+     * 按类型连续攒批执行、一次提交（交替提交会退化成逐条往返，吞吐只有约 200 行/秒）。
+     *
+     * @return 本批次合并的进度条数
+     */
+    public int flushBuffered(int batchSize) {
+        WatchProgressBuffer buffer = bufferProvider.getIfAvailable();
+        if (buffer == null) {
+            return 0;
+        }
+        List<WatchProgressBuffer.IdentityRef> refs = buffer.drain(batchSize);
+        if (refs.isEmpty()) {
+            return 0;
+        }
+        try {
+            return flushRefs(buffer, refs);
+        } catch (Exception ex) {
+            log.warn("观看进度缓冲合并失败，整批退回队列稍后重试: {}", ex.getMessage());
+            buffer.requeue(refs);
+            return 0;
+        }
+    }
+
+    private int flushRefs(WatchProgressBuffer buffer, List<WatchProgressBuffer.IdentityRef> refs) {
+        // 1) pipeline 批量读缓冲状态，key -> (dramaId -> state)
+        List<String> identityKeys = refs.stream()
+                .map(WatchProgressBuffer.IdentityRef::key)
+                .distinct()
+                .toList();
+        Map<String, Map<Long, WatchProgressBuffer.BufferedProgress>> statesByIdentity =
+                buffer.getAllBatch(identityKeys);
+
+        // 2) 组装待合并条目；状态读不到视为异常（ref 必然来自 put），整批退回
+        List<WatchProgressBuffer.IdentityRef> pendingRefs = new ArrayList<>(refs.size());
+        List<WatchProgressBuffer.BufferedProgress> pendingStates = new ArrayList<>(refs.size());
+        List<WatchProgressMapper.IdentityDramaPair> pairs = new ArrayList<>(refs.size());
+        for (WatchProgressBuffer.IdentityRef ref : refs) {
+            WatchProgressBuffer.BufferedProgress state =
+                    statesByIdentity.getOrDefault(ref.key(), Map.of()).get(ref.dramaId());
+            if (state == null) {
+                continue;
+            }
+            pendingRefs.add(ref);
+            pendingStates.add(state);
+            pairs.add(new WatchProgressMapper.IdentityDramaPair(
+                    ref.userId(), ref.deviceId(), ref.dramaId()));
+        }
+        if (pendingRefs.isEmpty()) {
+            // 缓冲状态已消失（用户清空/删除历史，或 HASH 12h TTL 到期）。此时 ref 已无
+            // 可落库的内容，必须丢弃：退回队列会在下个周期被原样弹出、再清空、再退回，
+            // 这批僵尸条目将永久占住 dirty 队列配额。
+            log.debug("观看进度缓冲条目已无对应状态，丢弃 {} 条", refs.size());
+            return 0;
+        }
+
+        // 3) 分块成对查询已有行（每块 100 组 OR 索引条件）
+        Map<String, WatchProgress> rowByPair = new HashMap<>(pendingRefs.size());
+        for (int i = 0; i < pairs.size(); i += 100) {
+            List<WatchProgressMapper.IdentityDramaPair> chunk =
+                    pairs.subList(i, Math.min(i + 100, pairs.size()));
+            for (WatchProgress row : progressMapper.selectBatchForPairs(chunk)) {
+                rowByPair.put(rowKey(row.getUserId(), row.getDeviceId(), row.getDramaId()), row);
+            }
+        }
+
+        // 4) 计算阶段：纯内存合并出「新增进度 / 新增流水 / 更新行」三组
+        List<WatchProgress> insertProgress = new ArrayList<>(pendingRefs.size());
+        List<WatchHistory> insertHistory = new ArrayList<>(pendingRefs.size());
+        List<WatchProgress> updateRows = new ArrayList<>(pendingRefs.size());
+        for (int i = 0; i < pendingRefs.size(); i++) {
+            WatchProgress row = rowByPair.get(rowKey(
+                    pendingRefs.get(i).userId(),
+                    pendingRefs.get(i).deviceId(),
+                    pendingStates.get(i).dramaId()));
+            planOne(pendingRefs.get(i).toIdentity(), pendingStates.get(i), row,
+                    insertProgress, insertHistory, updateRows);
+        }
+
+        // 5) 执行阶段：同一个 batch 会话按类型连续执行，最后一次提交。
+        //    MyBatis BATCH 执行器只合并「连续同形状」的语句，进度/流水交替提交会
+        //    退化成逐条网络往返（实测只有约 200 行/秒），必须分组攒批。
+        try (SqlSession session = sqlSessionFactory.openSession(ExecutorType.BATCH, false)) {
+            WatchProgressMapper batchProgress = session.getMapper(WatchProgressMapper.class);
+            WatchHistoryMapper batchHistory = session.getMapper(WatchHistoryMapper.class);
+            for (WatchProgress created : insertProgress) {
+                batchProgress.insert(created);
+            }
+            for (WatchHistory history : insertHistory) {
+                batchHistory.insert(history);
+            }
+            for (WatchProgress row : updateRows) {
+                batchProgress.updateRowAny(row);
+            }
+            session.commit();
+        }
+        return pendingRefs.size();
+    }
+
+    /** 计算单条缓冲的合并动作：只改内存对象不触库，产出归入三组待执行列表。 */
+    private void planOne(InteractionIdentity identity,
+                         WatchProgressBuffer.BufferedProgress state,
+                         WatchProgress row,
+                         List<WatchProgress> insertProgress,
+                         List<WatchHistory> insertHistory,
+                         List<WatchProgress> updateRows) {
+        if (row == null) {
+            WatchProgress created = new WatchProgress();
+            created.setUserId(identity.userId());
+            created.setDramaId(state.dramaId());
+            created.setEpisodeId(state.episodeId());
+            created.setPositionMs(state.positionMs());
+            created.setDurationMs(state.durationMs());
+            created.setFinished(state.finished() ? 1 : 0);
+            created.setPlayCount(1);
+            created.setDeviceId(identity.authenticated()
+                    ? state.deviceId()
+                    : identity.deviceId());
+            created.setSource(state.source());
+            insertProgress.add(created);
+            insertHistory.add(historyOf(identity, state, created.getDeviceId()));
+            return;
+        }
+        boolean hidden = row.getDeleted() != null && row.getDeleted() != 0;
+        long rowTs = toMillis(row.getUpdatedAt());
+        if (hidden && rowTs > 0 && state.ts() <= rowTs) {
+            // 逻辑删除会刷新 updated_at：上报时间早于它的条目是删除前排队的迟到数据，
+            // 丢弃即可，否则会把已删记录重新写活。
+            return;
+        }
+        boolean sameEpisode = row.getEpisodeId() != null
+                && row.getEpisodeId().equals(state.episodeId());
+        if (hidden && sameEpisode) {
+            row.setPlayCount((row.getPlayCount() == null ? 0 : row.getPlayCount()) + 1);
+            insertHistory.add(historyOf(identity, state, row.getDeviceId()));
+        } else if (!sameEpisode) {
+            // 换集：直接采纳新集与新的播放位置
+            row.setEpisodeId(state.episodeId());
+            row.setPositionMs(state.positionMs());
+            row.setDurationMs(state.durationMs());
+            row.setFinished(state.finished() ? 1 : 0);
+            row.setPlayCount((row.getPlayCount() == null ? 0 : row.getPlayCount()) + 1);
+            insertHistory.add(historyOf(identity, state, row.getDeviceId()));
+        } else {
+            row.setDurationMs(Math.max(row.getDurationMs() == null ? 0L : row.getDurationMs(),
+                    state.durationMs()));
+            if (state.positionMs() >= (row.getPositionMs() == null ? 0L : row.getPositionMs())) {
+                row.setPositionMs(state.positionMs());
+            }
+            if (state.finished()) {
+                row.setFinished(1);
+            }
+        }
+        row.setDeviceId(identity.authenticated() ? state.deviceId() : identity.deviceId());
+        row.setSource(state.source());
+        if (hidden) {
+            row.setDeleted(0);
+        }
+        updateRows.add(row);
+    }
+
+    /** 组装一条观看流水（首次观剧/换集各记一条）。 */
+    private WatchHistory historyOf(InteractionIdentity identity,
+                                   WatchProgressBuffer.BufferedProgress state,
+                                   String deviceId) {
+        WatchHistory history = new WatchHistory();
+        history.setUserId(identity.userId());
+        history.setDramaId(state.dramaId());
+        history.setEpisodeId(state.episodeId());
+        history.setPositionMs(state.positionMs());
+        history.setDurationMs(state.durationMs());
+        history.setSource(state.source() == null ? "" : state.source());
+        history.setDeviceId(identity.authenticated()
+                ? (deviceId == null ? "" : deviceId)
+                : identity.deviceId());
+        return history;
+    }
+
+    /** 行定位键：登录身份用 userId，匿名用 deviceId。 */
+    private String rowKey(Long userId, String deviceId, Long dramaId) {
+        return (userId != null ? "u:" + userId : "d:" + deviceId) + ":" + dramaId;
+    }
+
     private ProgressRespVO toResp(WatchProgress progress) {
         ProgressRespVO vo = new ProgressRespVO();
         vo.setDramaId(progress.getDramaId());
@@ -222,6 +530,68 @@ public class WatchProgressService {
         return vo;
     }
 
+    /** 以缓冲状态为主、库行 playCount 兜底构建续看响应。 */
+    private ProgressRespVO toResp(WatchProgressBuffer.BufferedProgress buffered, WatchProgress row) {
+        ProgressRespVO vo = new ProgressRespVO();
+        vo.setDramaId(buffered.dramaId());
+        vo.setEpisodeId(buffered.episodeId());
+        vo.setPositionMs(buffered.positionMs());
+        vo.setDurationMs(buffered.durationMs());
+        vo.setFinished(buffered.finished());
+        vo.setPlayCount(row == null || row.getPlayCount() == null ? 1 : row.getPlayCount());
+        vo.setUpdatedAt(fromMillis(buffered.ts()));
+        return vo;
+    }
+
+    /** 库行被缓冲覆盖时返回覆盖后的瞬态行；缓冲不比库行新时原样返回。 */
+    private WatchProgress overlayRow(WatchProgress row, WatchProgressBuffer.BufferedProgress buffered) {
+        if (buffered == null || row.getUpdatedAt() == null
+                || buffered.ts() <= toMillis(row.getUpdatedAt())) {
+            return row;
+        }
+        WatchProgress overlaid = transientRow(buffered);
+        overlaid.setPlayCount(row.getPlayCount());
+        return overlaid;
+    }
+
+    private WatchProgress transientRow(WatchProgressBuffer.BufferedProgress buffered) {
+        WatchProgress row = new WatchProgress();
+        row.setDramaId(buffered.dramaId());
+        row.setEpisodeId(buffered.episodeId());
+        row.setPositionMs(buffered.positionMs());
+        row.setDurationMs(buffered.durationMs());
+        row.setFinished(buffered.finished() ? 1 : 0);
+        row.setPlayCount(1);
+        row.setUpdatedAt(fromMillis(buffered.ts()));
+        return row;
+    }
+
+    private long toMillis(LocalDateTime time) {
+        return time == null ? 0L : time.atZone(ZoneId.systemDefault()).toInstant().toEpochMilli();
+    }
+
+    private LocalDateTime fromMillis(long epochMillis) {
+        return LocalDateTime.ofInstant(Instant.ofEpochMilli(epochMillis), ZoneId.systemDefault());
+    }
+
+    private DramaEpisode publishedEpisode(Long episodeId) {
+        DramaEpisode episode = episodeCache.getIfPresent(episodeId);
+        if (episode == null) {
+            episode = episodeService.getPublished(episodeId);
+            episodeCache.put(episodeId, episode);
+        }
+        return episode;
+    }
+
+    private Drama publishedDrama(Long dramaId) {
+        Drama drama = dramaCache.getIfPresent(dramaId);
+        if (drama == null) {
+            drama = dramaService.getPublished(dramaId);
+            dramaCache.put(dramaId, drama);
+        }
+        return drama;
+    }
+
     private List<ProgressRespVO> enrichDisplay(List<WatchProgress> records) {
         if (records.isEmpty()) {
             return List.of();
@@ -256,6 +626,7 @@ public class WatchProgressService {
                 vo.setTitleLocales(titles);
                 vo.setDramaTitle(ContentLocaleTexts.value(titles, ContentLocaleTexts.ZH));
                 vo.setDramaCover(drama.getCoverUrl());
+                vo.setDramaCoverLandscape(drama.getHorizontalCoverUrl());
                 vo.setTotalEpisodes(drama.getTotalEpisodes());
                 vo.setViewCount(drama.getViewCount());
             }
@@ -296,6 +667,36 @@ public class WatchProgressService {
         historyMapper.insert(history);
     }
 
+    /**
+     * 把某个身份缓冲里尚未落库的进度立即写进权威表。
+     * 登录合并前必须先调用：合并只扫库表，缓冲里的设备进度会被漏掉，
+     * 随后定时落库又会生成一条登录用户看不到的匿名孤儿行。
+     *
+     * @return 本次合并的条目数
+     */
+    public int flushIdentity(InteractionIdentity identity) {
+        WatchProgressBuffer buffer = bufferProvider.getIfAvailable();
+        if (buffer == null) {
+            return 0;
+        }
+        Map<Long, WatchProgressBuffer.BufferedProgress> states = buffer.getAll(identity);
+        if (states.isEmpty()) {
+            return 0;
+        }
+        String key = buffer.identityKey(identity);
+        List<WatchProgressBuffer.IdentityRef> refs = states.keySet().stream()
+                .map(dramaId -> new WatchProgressBuffer.IdentityRef(
+                        key, identity.userId(), identity.deviceId(), dramaId))
+                .toList();
+        try {
+            return flushRefs(buffer, refs);
+        } catch (Exception ex) {
+            // 预写失败不影响合并本身：dirty 队列里的引用还在，下个周期会再落库
+            log.warn("观看进度缓冲立即落库失败，跳过预写: {}", ex.getMessage());
+            return 0;
+        }
+    }
+
     /**
      * 登录时合并设备进度和观看流水。
      *
@@ -307,6 +708,9 @@ public class WatchProgressService {
         if (userId == null || !StringUtils.hasText(deviceId)) {
             return new MergeResult(0, 0, 0, 0);
         }
+        InteractionIdentity deviceIdentity = new InteractionIdentity(null, deviceId);
+        // 缓冲里可能还有没落库的设备进度，先落库再合并，否则这段进度会被漏掉
+        flushIdentity(deviceIdentity);
         List<WatchProgress> deviceProgress = progressMapper.selectList(
                 Wrappers.<WatchProgress>lambdaQuery()
                         .isNull(WatchProgress::getUserId)
@@ -366,6 +770,11 @@ public class WatchProgressService {
             }
             historyMapper.deleteById(device.getId());
         }
+        // 设备侧进度已迁走或淘汰，缓冲留着只会让读覆盖层把已删行读回来
+        WatchProgressBuffer buffer = bufferProvider.getIfAvailable();
+        if (buffer != null) {
+            buffer.clear(deviceIdentity);
+        }
         return new MergeResult(
                 progressMigrated, progressIgnored, historyMigrated, historyIgnored);
     }

fruitshorts-module-playback/src/main/java/com/fruitshorts/playback/vo/ProgressRespVO.java

@@ -19,6 +19,8 @@ public class ProgressRespVO {
     private Map<String, String> titleLocales;
     /** 短剧封面，仅列表类接口批量装配。 */
     private String dramaCover;
+    /** 短剧横版封面，仅列表类接口批量装配；为空时客户端回退 dramaCover。 */
+    private String dramaCoverLandscape;
     /** 当前续看集号。 */
     private Integer episodeNumber;
     /** 短剧总集数；短剧不存在时为空。 */

fruitshorts-module-user/pom.xml

@@ -25,5 +25,10 @@
             <groupId>com.fruitshorts</groupId>
             <artifactId>fruitshorts-module-system</artifactId>
         </dependency>
+        <!-- 离线 IP → 国家解析，xdb 数据在 src/main/resources/ip2region 下 -->
+        <dependency>
+            <groupId>org.lionsoul</groupId>
+            <artifactId>ip2region</artifactId>
+        </dependency>
     </dependencies>
 </project>

fruitshorts-module-user/src/main/java/com/fruitshorts/user/dal/entity/AppDeviceProfile.java

@@ -0,0 +1,32 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.user.dal.entity;
+
+import com.baomidou.mybatisplus.annotation.IdType;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableLogic;
+import com.baomidou.mybatisplus.annotation.TableName;
+import lombok.Data;
+
+import java.time.LocalDateTime;
+
+/**
+ * 设备平台：按 device_id 记录客户端是 iOS 还是 Android。
+ * 与会话不同，它不依赖用户身份，游客请求也会建档。
+ */
+@Data
+@TableName("app_device_profile")
+public class AppDeviceProfile {
+
+    @TableId(type = IdType.ASSIGN_ID)
+    private Long id;
+    private String deviceId;
+    private String platform;
+    private LocalDateTime firstSeenAt;
+    private LocalDateTime lastSeenAt;
+    private LocalDateTime createdAt;
+    private LocalDateTime updatedAt;
+
+    @TableLogic
+    private Integer deleted;
+}

fruitshorts-module-user/src/main/java/com/fruitshorts/user/dal/mapper/AppDeviceProfileMapper.java

@@ -0,0 +1,28 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.user.dal.mapper;
+
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+import com.fruitshorts.user.dal.entity.AppDeviceProfile;
+import org.apache.ibatis.annotations.Insert;
+import org.apache.ibatis.annotations.Param;
+
+public interface AppDeviceProfileMapper extends BaseMapper<AppDeviceProfile> {
+
+    /**
+     * 按 device_id 建档或刷新平台。
+     * 空平台不覆盖已有值：老版本客户端不带平台头，不能把已记录的值抹掉。
+     */
+    @Insert("""
+            INSERT INTO app_device_profile (id, device_id, platform,
+                                            first_seen_at, last_seen_at, created_at, updated_at, deleted)
+            VALUES (#{p.id}, #{p.deviceId}, #{p.platform},
+                    CURRENT_TIMESTAMP, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP, 0)
+            ON CONFLICT (device_id) DO UPDATE SET
+                platform = CASE WHEN EXCLUDED.platform <> '' THEN EXCLUDED.platform
+                                ELSE app_device_profile.platform END,
+                last_seen_at = CURRENT_TIMESTAMP,
+                updated_at = CURRENT_TIMESTAMP
+            """)
+    int upsert(@Param("p") AppDeviceProfile profile);
+}

fruitshorts-module-user/src/main/java/com/fruitshorts/user/dal/mapper/AppUserSessionMapper.java

@@ -4,6 +4,27 @@ package com.fruitshorts.user.dal.mapper;
 
 import com.baomidou.mybatisplus.core.mapper.BaseMapper;
 import com.fruitshorts.user.dal.entity.AppUserSession;
+import org.apache.ibatis.annotations.Param;
+import org.apache.ibatis.annotations.Select;
+
+import java.util.List;
 
 public interface AppUserSessionMapper extends BaseMapper<AppUserSession> {
+
+    /**
+     * 最近一次登录会话平台等于指定值的用户。
+     * 必须取「最近一次」而不是「存在过」：否则同一用户在 Android 登录过、
+     * 后来又换 iOS，会被两端都命中，筛选结果与实际展示的系统不一致。
+     */
+    @Select("""
+            SELECT t.user_id
+            FROM (
+                SELECT DISTINCT ON (user_id) user_id, platform
+                FROM app_user_session
+                WHERE deleted = 0
+                ORDER BY user_id, last_active_at DESC NULLS LAST, id DESC
+            ) t
+            WHERE t.platform = #{platform}
+            """)
+    List<Long> selectUserIdsByLatestPlatform(@Param("platform") String platform);
 }

fruitshorts-module-user/src/main/java/com/fruitshorts/user/enums/CountryProfile.java

@@ -0,0 +1,219 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.user.enums;
+
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.util.StringUtils;
+
+import java.util.HashMap;
+import java.util.Locale;
+import java.util.Map;
+
+/**
+ * 国家/地区 → 语言、时区、币种。
+ *
+ * <p>App 目前只内置 en / id / zh 三种语言，除印尼、中国及台港澳外的市场统一落到 en-US；
+ * 时区与币种按国家真实值写入，避免所有用户都变成 IDR。
+ *
+ * <p>未收录的国家按 {@link #DEFAULT}（印尼）处理，与历史行为保持一致。
+ */
+@Slf4j
+public enum CountryProfile {
+
+    ID("id-ID", "Asia/Jakarta", "IDR"),
+    MY("en-US", "Asia/Kuala_Lumpur", "MYR"),
+    SG("en-US", "Asia/Singapore", "SGD"),
+    TH("en-US", "Asia/Bangkok", "THB"),
+    VN("en-US", "Asia/Ho_Chi_Minh", "VND"),
+    PH("en-US", "Asia/Manila", "PHP"),
+    KH("en-US", "Asia/Phnom_Penh", "KHR"),
+    MM("en-US", "Asia/Yangon", "MMK"),
+    LA("en-US", "Asia/Vientiane", "LAK"),
+    BN("en-US", "Asia/Brunei", "BND"),
+    CN("zh-CN", "Asia/Shanghai", "CNY"),
+    TW("zh-TW", "Asia/Taipei", "TWD"),
+    HK("zh-HK", "Asia/Hong_Kong", "HKD"),
+    MO("zh-HK", "Asia/Macau", "MOP"),
+    JP("en-US", "Asia/Tokyo", "JPY"),
+    KR("en-US", "Asia/Seoul", "KRW"),
+    IN("en-US", "Asia/Kolkata", "INR"),
+    PK("en-US", "Asia/Karachi", "PKR"),
+    BD("en-US", "Asia/Dhaka", "BDT"),
+    LK("en-US", "Asia/Colombo", "LKR"),
+    NP("en-US", "Asia/Kathmandu", "NPR"),
+    US("en-US", "America/New_York", "USD"),
+    CA("en-US", "America/Toronto", "CAD"),
+    MX("en-US", "America/Mexico_City", "MXN"),
+    BR("en-US", "America/Sao_Paulo", "BRL"),
+    AR("en-US", "America/Argentina/Buenos_Aires", "ARS"),
+    CL("en-US", "America/Santiago", "CLP"),
+    CO("en-US", "America/Bogota", "COP"),
+    PE("en-US", "America/Lima", "PEN"),
+    VE("en-US", "America/Caracas", "VES"),
+    EC("en-US", "America/Guayaquil", "USD"),
+    GT("en-US", "America/Guatemala", "GTQ"),
+    DO("en-US", "America/Santo_Domingo", "DOP"),
+    GB("en-US", "Europe/London", "GBP"),
+    DE("en-US", "Europe/Berlin", "EUR"),
+    FR("en-US", "Europe/Paris", "EUR"),
+    ES("en-US", "Europe/Madrid", "EUR"),
+    IT("en-US", "Europe/Rome", "EUR"),
+    NL("en-US", "Europe/Amsterdam", "EUR"),
+    PL("en-US", "Europe/Warsaw", "PLN"),
+    RU("en-US", "Europe/Moscow", "RUB"),
+    UA("en-US", "Europe/Kyiv", "UAH"),
+    TR("en-US", "Europe/Istanbul", "TRY"),
+    SA("en-US", "Asia/Riyadh", "SAR"),
+    AE("en-US", "Asia/Dubai", "AED"),
+    IL("en-US", "Asia/Jerusalem", "ILS"),
+    EG("en-US", "Africa/Cairo", "EGP"),
+    NG("en-US", "Africa/Lagos", "NGN"),
+    ZA("en-US", "Africa/Johannesburg", "ZAR"),
+    KE("en-US", "Africa/Nairobi", "KES"),
+    MA("en-US", "Africa/Casablanca", "MAD"),
+    AU("en-US", "Australia/Sydney", "AUD"),
+    NZ("en-US", "Pacific/Auckland", "NZD");
+
+    public static final CountryProfile DEFAULT = ID;
+
+    /** ip2region 返回的中文国家名 → ISO-2，只收录上面配置过的国家。 */
+    private static final Map<String, String> IP_COUNTRY_NAMES = Map.ofEntries(
+            Map.entry("印度尼西亚", "ID"),
+            Map.entry("马来西亚", "MY"),
+            Map.entry("新加坡", "SG"),
+            Map.entry("泰国", "TH"),
+            Map.entry("越南", "VN"),
+            Map.entry("菲律宾", "PH"),
+            Map.entry("柬埔寨", "KH"),
+            Map.entry("缅甸", "MM"),
+            Map.entry("老挝", "LA"),
+            Map.entry("文莱", "BN"),
+            Map.entry("中国", "CN"),
+            Map.entry("日本", "JP"),
+            Map.entry("韩国", "KR"),
+            Map.entry("印度", "IN"),
+            Map.entry("巴基斯坦", "PK"),
+            Map.entry("孟加拉国", "BD"),
+            Map.entry("斯里兰卡", "LK"),
+            Map.entry("尼泊尔", "NP"),
+            Map.entry("美国", "US"),
+            Map.entry("加拿大", "CA"),
+            Map.entry("墨西哥", "MX"),
+            Map.entry("巴西", "BR"),
+            Map.entry("阿根廷", "AR"),
+            Map.entry("智利", "CL"),
+            Map.entry("哥伦比亚", "CO"),
+            Map.entry("秘鲁", "PE"),
+            Map.entry("委内瑞拉", "VE"),
+            Map.entry("厄瓜多尔", "EC"),
+            Map.entry("危地马拉", "GT"),
+            Map.entry("多米尼加", "DO"),
+            Map.entry("英国", "GB"),
+            Map.entry("德国", "DE"),
+            Map.entry("法国", "FR"),
+            Map.entry("西班牙", "ES"),
+            Map.entry("意大利", "IT"),
+            Map.entry("荷兰", "NL"),
+            Map.entry("波兰", "PL"),
+            Map.entry("俄罗斯", "RU"),
+            Map.entry("乌克兰", "UA"),
+            Map.entry("土耳其", "TR"),
+            Map.entry("沙特阿拉伯", "SA"),
+            Map.entry("阿联酋", "AE"),
+            Map.entry("以色列", "IL"),
+            Map.entry("埃及", "EG"),
+            Map.entry("尼日利亚", "NG"),
+            Map.entry("南非", "ZA"),
+            Map.entry("肯尼亚", "KE"),
+            Map.entry("摩洛哥", "MA"),
+            Map.entry("澳大利亚", "AU"),
+            Map.entry("新西兰", "NZ"));
+
+    private static final Map<String, CountryProfile> BY_CODE = new HashMap<>();
+
+    static {
+        for (CountryProfile profile : values()) {
+            BY_CODE.put(profile.name(), profile);
+        }
+    }
+
+    private final String language;
+    private final String timezone;
+    private final String currency;
+
+    CountryProfile(String language, String timezone, String currency) {
+        this.language = language;
+        this.timezone = timezone;
+        this.currency = currency;
+    }
+
+    public String code() {
+        return name();
+    }
+
+    public String language() {
+        return language;
+    }
+
+    public String timezone() {
+        return timezone;
+    }
+
+    public String currency() {
+        return currency;
+    }
+
+    /** 未收录的国家统一回退到印尼。 */
+    public static CountryProfile of(String countryCode) {
+        CountryProfile profile = BY_CODE.get(normalize(countryCode));
+        return profile == null ? DEFAULT : profile;
+    }
+
+    /** 客户端上报的区域：只接受两位字母且已收录的国家，其余返回空串。 */
+    public static String normalizeClientCode(String raw) {
+        String code = normalize(raw);
+        return BY_CODE.containsKey(code) ? code : "";
+    }
+
+    /**
+     * 把 ip2region 的 `国家|区域|省份|城市|运营商` 转成 ISO-2。
+     * 台港澳在库里的国家字段都是「中国」，需要看省份区分。
+     */
+    public static String fromIpRegion(String region) {
+        if (!StringUtils.hasText(region)) {
+            return "";
+        }
+        String[] parts = region.split("\\|", -1);
+        String country = parts[0].trim();
+        if (!StringUtils.hasText(country) || "0".equals(country)) {
+            return "";
+        }
+        if ("中国".equals(country)) {
+            String province = parts.length > 2 ? parts[2].trim() : "";
+            if (province.contains("台湾")) {
+                return "TW";
+            }
+            if (province.contains("香港")) {
+                return "HK";
+            }
+            if (province.contains("澳门")) {
+                return "MO";
+            }
+            return "CN";
+        }
+        String result = IP_COUNTRY_NAMES.getOrDefault(country, "");
+        if (!StringUtils.hasText(result) && StringUtils.hasText(country)) {
+            // ip2region 库里有但我们没收录的国家，debug 日志方便排查
+            log.debug("ip2region 返回未收录的国家 '{}'，回退到默认值（印尼）", country);
+        }
+        return result;
+    }
+
+    private static String normalize(String raw) {
+        if (!StringUtils.hasText(raw)) {
+            return "";
+        }
+        String code = raw.trim().toUpperCase(Locale.ROOT);
+        return code.length() == 2 ? code : "";
+    }
+}

fruitshorts-module-user/src/main/java/com/fruitshorts/user/service/AppAuthService.java

@@ -18,6 +18,7 @@ import com.fruitshorts.user.dal.mapper.AppUserDeviceMapper;
 import com.fruitshorts.user.dal.mapper.AppUserMapper;
 import com.fruitshorts.user.dal.mapper.AppUserSessionMapper;
 import com.fruitshorts.user.enums.AppUserStatus;
+import com.fruitshorts.user.enums.CountryProfile;
 import com.fruitshorts.user.enums.CredentialType;
 import com.fruitshorts.user.enums.OtpScene;
 import com.fruitshorts.user.vo.AppUserRespVO;
@@ -66,6 +67,7 @@ public class AppAuthService {
     private final ConfigService configService;
     private final GoogleIdTokenVerifier googleVerifier;
     private final ApplicationEventPublisher eventPublisher;
+    private final IpRegionService ipRegionService;
 
     /** 后台 sys_config 缺失或非法时使用；小于等于 0 表示不限制。 */
     @Value("${fruitshorts.auth.register-max-per-ip-per-day:5}")
@@ -178,6 +180,7 @@ public class AppAuthService {
 
         user.setLastLoginAt(LocalDateTime.now());
         user.setLastLoginIp(AppIdentifier.nullSafe(clientIp));
+        syncCountryByIp(user, clientIp);
         appUserMapper.updateById(user);
         touchDevice(user.getId(), req.getDeviceId(), req.getPlatform(), req.getDeviceModel());
 
@@ -194,7 +197,7 @@ public class AppAuthService {
      * 再落一条 GOOGLE 凭证用于下次直接登录；已有邮箱账号时只补 GOOGLE 凭证，不重复建号。
      */
     @Transactional(rollbackFor = Exception.class)
-    public TokenRespVO googleLogin(String idToken, String deviceId) {
+    public TokenRespVO googleLogin(String idToken, String deviceId, String clientIp) {
         GoogleUser googleUser = googleVerifier.verify(idToken);
         String email = requireEmail(googleUser);
         AppUserCredential googleCredential = findCredential(CredentialType.GOOGLE.name(), email);
@@ -203,7 +206,7 @@ public class AppAuthService {
         if (googleCredential == null) {
             AppUserCredential emailCredential = findCredential(CredentialType.EMAIL.name(), email);
             if (emailCredential == null) {
-                AppUser user = createGoogleUser(googleUser);
+                AppUser user = createGoogleUser(googleUser, clientIp);
                 insertCredential(user.getId(), CredentialType.EMAIL.name(), email, "");
                 userId = user.getId();
                 newUser = true;
@@ -219,10 +222,11 @@ public class AppAuthService {
         googleCredential.setLastUsedAt(LocalDateTime.now());
         credentialMapper.updateById(googleCredential);
         user.setLastLoginAt(LocalDateTime.now());
-        user.setLastLoginIp("");
+        user.setLastLoginIp(AppIdentifier.nullSafe(clientIp));
+        syncCountryByIp(user, clientIp);
         appUserMapper.updateById(user);
         touchDevice(user.getId(), deviceId, null, null);
-        TokenRespVO resp = issueTokens(user, googleCredential, deviceId, null, null, null, null, null);
+        TokenRespVO resp = issueTokens(user, googleCredential, deviceId, null, null, null, null, clientIp);
         resp.setNewUser(newUser);
         requestInteractionMerge(user.getId(), deviceId);
         return resp;
@@ -238,7 +242,7 @@ public class AppAuthService {
     }
 
     /** 创建 Google 用户：邮箱已验证，昵称与头像直接取 Google 返回。 */
-    private AppUser createGoogleUser(GoogleUser googleUser) {
+    private AppUser createGoogleUser(GoogleUser googleUser, String clientIp) {
         AppUser user = new AppUser();
         user.setUid(hasher.newUid());
         String nickname = StringUtils.hasText(googleUser.name())
@@ -246,11 +250,13 @@ public class AppAuthService {
         user.setNickname(nickname);
         user.setAvatarUrl(AppIdentifier.nullSafe(googleUser.picture()));
         user.setGender("");
-        user.setCountryCode("ID");
-        user.setRegionCode("ID");
-        user.setLanguage("id-ID");
-        user.setTimezone("Asia/Jakarta");
-        user.setCurrency("IDR");
+        String country = resolveCountry(clientIp, "");
+        CountryProfile profile = CountryProfile.of(country);
+        user.setCountryCode(country);
+        user.setRegionCode(country);
+        user.setLanguage(profile.language());
+        user.setTimezone(profile.timezone());
+        user.setCurrency(profile.currency());
         user.setStatus(AppUserStatus.NORMAL);
         user.setRegisterSource("APP");
         user.setRegisterChannel("");
@@ -527,12 +533,13 @@ public class AppAuthService {
                 : "User" + user.getUid().substring(1, 7));
         user.setAvatarUrl("");
         user.setGender("");
-        String country = StringUtils.hasText(req.getCountryCode()) ? req.getCountryCode() : "ID";
+        String country = resolveCountry(clientIp, req.getCountryCode());
+        CountryProfile profile = CountryProfile.of(country);
         user.setCountryCode(country);
         user.setRegionCode(country);
-        user.setLanguage("id-ID");
-        user.setTimezone("Asia/Jakarta");
-        user.setCurrency("IDR");
+        user.setLanguage(profile.language());
+        user.setTimezone(profile.timezone());
+        user.setCurrency(profile.currency());
         user.setStatus(AppUserStatus.NORMAL);
         user.setRegisterSource("APP");
         user.setRegisterChannel("");
@@ -549,6 +556,49 @@ public class AppAuthService {
         return user;
     }
 
+    /**
+     * 国家判定优先级：服务端 IP 解析 → 客户端上报的设备区域 → 印尼（历史默认）。
+     * IP 在本地开发/内网环境解析不出来，这时才用客户端区域。
+     */
+    private String resolveCountry(String clientIp, String clientCountryCode) {
+        String byIp = ipRegionService.resolveCountry(clientIp);
+        if (StringUtils.hasText(byIp)) {
+            return byIp;
+        }
+        String byClient = CountryProfile.normalizeClientCode(clientCountryCode);
+        return StringUtils.hasText(byClient) ? byClient : CountryProfile.DEFAULT.code();
+    }
+
+    /**
+     * 登录时按 IP 修正国家，解决历史账号被统一写成 ID 的问题（老用户下次登录即自愈）。
+     *
+     * <p>regionCode / 语言 / 时区 / 币种 只在它们仍是「旧国家映射值」时才跟着改，
+     * 用户自己在资料页改过就保留，不被 IP 覆盖。countryCode 始终用 IP 结果覆盖
+     * （它是国家判断的权威来源，不涉及用户偏好）。
+     */
+    private void syncCountryByIp(AppUser user, String clientIp) {
+        String byIp = ipRegionService.resolveCountry(clientIp);
+        if (!StringUtils.hasText(byIp) || byIp.equalsIgnoreCase(user.getCountryCode())) {
+            return;
+        }
+        CountryProfile before = CountryProfile.of(user.getCountryCode());
+        CountryProfile after = CountryProfile.of(byIp);
+        user.setCountryCode(byIp);
+        // regionCode 与 countryCode 永远同时写入（注册时就是这样），所以保护条件和语言一致
+        if (!StringUtils.hasText(user.getRegionCode()) || user.getRegionCode().equalsIgnoreCase(before.code())) {
+            user.setRegionCode(byIp);
+        }
+        if (!StringUtils.hasText(user.getLanguage()) || user.getLanguage().equals(before.language())) {
+            user.setLanguage(after.language());
+        }
+        if (!StringUtils.hasText(user.getTimezone()) || user.getTimezone().equals(before.timezone())) {
+            user.setTimezone(after.timezone());
+        }
+        if (!StringUtils.hasText(user.getCurrency()) || user.getCurrency().equals(before.currency())) {
+            user.setCurrency(after.currency());
+        }
+    }
+
     private void recordConsent(Long userId, String scene, String version, String clientIp, String deviceId) {
         AppUserConsent consent = new AppUserConsent();
         consent.setUserId(userId);

fruitshorts-module-user/src/main/java/com/fruitshorts/user/service/AppUserAdminService.java

@@ -2,6 +2,7 @@
 
 package com.fruitshorts.user.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;
@@ -30,6 +31,7 @@ import java.time.LocalDateTime;
 import java.util.ArrayList;
 import java.util.HashMap;
 import java.util.List;
+import java.util.Locale;
 import java.util.Map;
 
 /**
@@ -52,33 +54,36 @@ public class AppUserAdminService {
                 req.getPageIndex() == null || req.getPageIndex() < 1 ? 1 : req.getPageIndex(),
                 req.getPageSize() == null || req.getPageSize() < 1 ? 10 : req.getPageSize());
 
-        IPage<AppUser> result;
+        List<Long> platformUserIds = null;
+        if (StringUtils.hasText(req.getPlatform())) {
+            // 与列表展示保持一致：取每个用户最近一次会话的平台
+            platformUserIds = sessionMapper.selectUserIdsByLatestPlatform(
+                    req.getPlatform().trim().toUpperCase(Locale.ROOT));
+            if (platformUserIds.isEmpty()) {
+                return new PageResult<>(0L, List.of());
+            }
+        }
+
+        LambdaQueryWrapper<AppUser> wrapper = Wrappers.lambdaQuery();
         if (StringUtils.hasText(req.getKeyword())) {
             // uid / 昵称 直接查；手机号与邮箱要先在凭证表命中 userId
             List<Long> matchedUserIds = userIdsByCredential(req.getKeyword());
-            result = appUserMapper.selectPage(page, Wrappers.<AppUser>lambdaQuery()
-                    .and(wrapper -> {
-                        wrapper.like(AppUser::getUid, req.getKeyword())
-                                .or().like(AppUser::getNickname, req.getKeyword());
-                        if (!matchedUserIds.isEmpty()) {
-                            wrapper.or().in(AppUser::getId, matchedUserIds);
-                        }
-                    })
-                    .eq(StringUtils.hasText(req.getStatus()), AppUser::getStatus, req.getStatus())
-                    .eq(StringUtils.hasText(req.getCountryCode()), AppUser::getCountryCode,
-                            req.getCountryCode())
-                    .eq(StringUtils.hasText(req.getRegisterSource()), AppUser::getRegisterSource,
-                            req.getRegisterSource())
-                    .orderByDesc(AppUser::getId));
-        } else {
-            result = appUserMapper.selectPage(page, Wrappers.<AppUser>lambdaQuery()
-                    .eq(StringUtils.hasText(req.getStatus()), AppUser::getStatus, req.getStatus())
-                    .eq(StringUtils.hasText(req.getCountryCode()), AppUser::getCountryCode,
-                            req.getCountryCode())
-                    .eq(StringUtils.hasText(req.getRegisterSource()), AppUser::getRegisterSource,
-                            req.getRegisterSource())
-                    .orderByDesc(AppUser::getId));
+            wrapper.and(nested -> {
+                nested.like(AppUser::getUid, req.getKeyword())
+                        .or().like(AppUser::getNickname, req.getKeyword());
+                if (!matchedUserIds.isEmpty()) {
+                    nested.or().in(AppUser::getId, matchedUserIds);
+                }
+            });
         }
+        wrapper.eq(StringUtils.hasText(req.getStatus()), AppUser::getStatus, req.getStatus())
+                .eq(StringUtils.hasText(req.getCountryCode()), AppUser::getCountryCode,
+                        req.getCountryCode())
+                .eq(StringUtils.hasText(req.getRegisterSource()), AppUser::getRegisterSource,
+                        req.getRegisterSource())
+                .in(platformUserIds != null, AppUser::getId, platformUserIds)
+                .orderByDesc(AppUser::getId);
+        IPage<AppUser> result = appUserMapper.selectPage(page, wrapper);
         List<AppUserAdminRespVO> list = toRespList(result.getRecords());
         fillLatestSystem(list);
         return new PageResult<>(result.getTotal(), list);
@@ -164,7 +169,7 @@ public class AppUserAdminService {
         return vo;
     }
 
-    /** 用最近一次未吊销会话上的系统信息，供后台用户列表展示。 */
+    /** 用最近一次会话上的系统信息，供后台用户列表展示；排序需与平台筛选一致。 */
     private void fillLatestSystem(List<AppUserAdminRespVO> list) {
         if (list.isEmpty()) {
             return;
@@ -180,7 +185,6 @@ public class AppUserAdminService {
         }
         List<AppUserSession> sessions = sessionMapper.selectList(Wrappers.<AppUserSession>lambdaQuery()
                 .in(AppUserSession::getUserId, ids)
-                .isNull(AppUserSession::getRevokedAt)
                 .orderByDesc(AppUserSession::getLastActiveAt)
                 .orderByDesc(AppUserSession::getId));
         Map<Long, AppUserSession> latest = new HashMap<>();

fruitshorts-module-user/src/main/java/com/fruitshorts/user/service/DeviceProfileService.java

@@ -0,0 +1,51 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.user.service;
+
+import com.baomidou.mybatisplus.core.toolkit.IdWorker;
+import com.fruitshorts.user.dal.entity.AppDeviceProfile;
+import com.fruitshorts.user.dal.mapper.AppDeviceProfileMapper;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Service;
+import org.springframework.util.StringUtils;
+
+import java.util.Locale;
+
+/** 设备平台写入：按 device_id 建档，匿名请求也记录。 */
+@Slf4j
+@Service
+@RequiredArgsConstructor
+public class DeviceProfileService {
+
+    private static final int DEVICE_ID_MAX = 128;
+    private static final int PLATFORM_MAX = 16;
+
+    private final AppDeviceProfileMapper mapper;
+
+    /** 记录或刷新设备平台；平台为空时直接跳过，避免产生无意义记录。 */
+    public void touch(String deviceId, String platform) {
+        String cleanPlatform = sanitize(platform, PLATFORM_MAX).toUpperCase(Locale.ROOT);
+        if (!StringUtils.hasText(deviceId) || cleanPlatform.isEmpty()) {
+            return;
+        }
+        AppDeviceProfile profile = new AppDeviceProfile();
+        profile.setId(IdWorker.getId());
+        profile.setDeviceId(sanitize(deviceId, DEVICE_ID_MAX));
+        profile.setPlatform(cleanPlatform);
+        try {
+            mapper.upsert(profile);
+        } catch (RuntimeException ex) {
+            // 平台只用于后台展示，写失败不能影响正常业务请求
+            log.warn("device-platform upsert failed deviceId={} reason={}", profile.getDeviceId(), ex.getMessage());
+        }
+    }
+
+    private String sanitize(String value, int maxLength) {
+        if (!StringUtils.hasText(value)) {
+            return "";
+        }
+        String trimmed = value.trim().replaceAll("[\\p{Cntrl}]", "");
+        return trimmed.length() <= maxLength ? trimmed : trimmed.substring(0, maxLength);
+    }
+}

fruitshorts-module-user/src/main/java/com/fruitshorts/user/service/IpRegionService.java

@@ -0,0 +1,60 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.user.service;
+
+import com.fruitshorts.user.enums.CountryProfile;
+import lombok.extern.slf4j.Slf4j;
+import org.lionsoul.ip2region.xdb.Searcher;
+import org.springframework.core.io.ClassPathResource;
+import org.springframework.stereotype.Service;
+import org.springframework.util.StringUtils;
+
+import java.io.InputStream;
+
+/**
+ * 把登录/注册请求的客户端 IP 解析成国家码。
+ *
+ * <p>用离线 ip2region（xdb 随包发布），不依赖外部接口；内网、保留地址与未收录国家返回空串，
+ * 由调用方回退到客户端上报的设备区域。数据加载失败也不阻断启动，只是 IP 解析不生效。
+ */
+@Slf4j
+@Service
+public class IpRegionService {
+
+    private static final String DB_PATH = "ip2region/ip2region.xdb";
+
+    private volatile Searcher searcher;
+    private volatile boolean loaded;
+
+    /** 返回 ISO-2 国家码；解析不出来返回空串。 */
+    public String resolveCountry(String ip) {
+        Searcher current = searcher();
+        if (current == null || !StringUtils.hasText(ip)) {
+            return "";
+        }
+        try {
+            return CountryProfile.fromIpRegion(current.search(ip.trim()));
+        } catch (Exception ex) {
+            // 非法 IP（本地开发、测试桩）不当作错误，交给客户端区域兜底
+            return "";
+        }
+    }
+
+    private Searcher searcher() {
+        if (loaded) {
+            return searcher;
+        }
+        synchronized (this) {
+            if (!loaded) {
+                try (InputStream in = new ClassPathResource(DB_PATH).getInputStream()) {
+                    searcher = Searcher.newWithBuffer(in.readAllBytes());
+                } catch (Exception ex) {
+                    log.warn("ip2region 数据加载失败，IP 国家解析不可用: {}", ex.getMessage());
+                } finally {
+                    loaded = true;
+                }
+            }
+        }
+        return searcher;
+    }
+}

fruitshorts-module-user/src/main/java/com/fruitshorts/user/vo/AppUserQueryReqVO.java

@@ -13,6 +13,8 @@ public class AppUserQueryReqVO {
     private String status;
     private String countryCode;
     private String registerSource;
+    /** 客户端平台筛选：ANDROID / IOS / WEB，留空不限制；按最近一次会话的平台判定 */
+    private String platform;
     private Integer pageIndex = 1;
     private Integer pageSize = 10;
 }

fruitshorts-module-user/src/main/java/com/fruitshorts/user/vo/RegisterReqVO.java

@@ -25,6 +25,7 @@ public class RegisterReqVO {
     private String password;
 
     private String nickname;
+    /** 客户端上报的设备区域（ISO-2），仅在服务端 IP 解析失败时作为兜底 */
     private String countryCode;
     private String deviceId;
     private String deviceModel;

fruitshorts-module-user/src/main/resources/ip2region/VERSION

@@ -0,0 +1,12 @@
+# Author: fruit.com.cn
+# ip2region 离线库数据版本追踪
+# 每次替换 ip2region.xdb 时更新此文件
+
+version: 2.7.0
+updated: 2026-10-21
+source: org.lionsoul:ip2region:2.7.0
+xdb-path: fruitshorts-module-user/src/main/resources/ip2region/ip2region.xdb
+
+# 覆盖范围：国家 + 省份 + 城市 + 运营商（IPv4）
+# 生产请留意：xdb 随 jar 打包约 11MB，admin-api 不解析 IP 但也会带上这份数据。
+# 后续可考虑用 Spring Profile + 条件装配，让 admin-api 不带 ip2region。

grafana/provisioning/alerting/rules.yml

@@ -0,0 +1,128 @@
+# Author: fruit.com.cn
+# Grafana 告警规则：服务下线 / 响应慢 / 磁盘满 自动通知。
+# 需要在 Grafana UI 里配一个 Contact Point（飞书 webhook）并绑定到这些规则。
+
+apiVersion: 1
+
+groups:
+  - orgId: 1
+    name: fruitshorts-health
+    folder: FruitShorts
+    interval: 30s
+    rules:
+      # ── 服务下线 ──
+      - uid: fruitshorts-app-down
+        title: "app-api 下线"
+        condition: C
+        data:
+          - refId: A
+            relativeTimeRange: { from: 120, to: 0 }
+            datasourceUid: prometheus
+            model:
+              expr: 'probe_success{instance=~"http://app-api:8081/.*"} == 0'
+              refId: A
+          - refId: C
+            relativeTimeRange: { from: 0, to: 0 }
+            datasourceUid: __expr__
+            model:
+              conditions:
+                - evaluator: { params: [0.5], type: gt }
+                  operator: { type: and }
+                  query: { params: [A] }
+                  reducer: { type: last }
+                  type: query
+              refId: C
+        noDataState: Alerting
+        for: 2m
+        annotations:
+          summary: "app-api (8081) 已下线超过 2 分钟"
+        labels:
+          severity: critical
+          team: backend
+
+      - uid: fruitshorts-admin-down
+        title: "admin-api 下线"
+        condition: C
+        data:
+          - refId: A
+            relativeTimeRange: { from: 120, to: 0 }
+            datasourceUid: prometheus
+            model:
+              expr: 'probe_success{instance=~"http://admin-api:8080/.*"} == 0'
+              refId: A
+          - refId: C
+            relativeTimeRange: { from: 0, to: 0 }
+            datasourceUid: __expr__
+            model:
+              conditions:
+                - evaluator: { params: [0.5], type: gt }
+                  operator: { type: and }
+                  query: { params: [A] }
+                  reducer: { type: last }
+                  type: query
+              refId: C
+        noDataState: Alerting
+        for: 2m
+        annotations:
+          summary: "admin-api (8080) 已下线超过 2 分钟"
+        labels:
+          severity: critical
+          team: backend
+
+      # ── 响应慢 ──
+      - uid: fruitshorts-slow-response
+        title: "接口响应过慢"
+        condition: C
+        data:
+          - refId: A
+            relativeTimeRange: { from: 300, to: 0 }
+            datasourceUid: prometheus
+            model:
+              expr: 'histogram_quantile(0.95, rate(probe_duration_seconds_bucket[5m])) > 2'
+              refId: A
+          - refId: C
+            relativeTimeRange: { from: 0, to: 0 }
+            datasourceUid: __expr__
+            model:
+              conditions:
+                - evaluator: { params: [0.5], type: gt }
+                  operator: { type: and }
+                  query: { params: [A] }
+                  reducer: { type: last }
+                  type: query
+              refId: C
+        for: 5m
+        annotations:
+          summary: "接口 P95 响应时间超过 2 秒"
+        labels:
+          severity: warning
+          team: backend
+
+      # ── 容器重启频繁 ──
+      - uid: fruitshorts-container-restart
+        title: "容器频繁重启"
+        condition: C
+        data:
+          - refId: A
+            relativeTimeRange: { from: 600, to: 0 }
+            datasourceUid: prometheus
+            model:
+              expr: 'increase(container_start_time_seconds[10m]) > 3'
+              refId: A
+          - refId: C
+            relativeTimeRange: { from: 0, to: 0 }
+            datasourceUid: __expr__
+            model:
+              conditions:
+                - evaluator: { params: [0.5], type: gt }
+                  operator: { type: and }
+                  query: { params: [A] }
+                  reducer: { type: last }
+                  type: query
+              refId: C
+        for: 1m
+        annotations:
+          summary: "有容器在 10 分钟内重启超过 3 次"
+        labels:
+          severity: warning
+          team: infra

grafana/provisioning/datasources/loki.yml

@@ -0,0 +1,14 @@
+# Author: fruit.com.cn
+# Grafana 数据源：Loki 日志
+apiVersion: 1
+
+datasources:
+  - name: Loki
+    uid: loki
+    type: loki
+    access: proxy
+    url: http://loki:3100
+    isDefault: false
+    editable: false
+    jsonData:
+      maxLines: 1000

loki-config.yml

@@ -0,0 +1,55 @@
+# Author: fruit.com.cn
+# Loki 单机配置：文件系统存储，7 天保留，供 Grafana 查询容器日志。
+auth_enabled: false
+
+server:
+  http_listen_port: 3100
+  grpc_listen_port: 9096
+
+common:
+  instance_addr: 127.0.0.1
+  path_prefix: /loki
+  storage:
+    filesystem:
+      chunks_directory: /loki/chunks
+      rules_directory: /loki/rules
+  replication_factor: 1
+  ring:
+    kvstore:
+      store: inmemory
+
+query_range:
+  results_cache:
+    cache:
+      embedded_cache:
+        enabled: true
+        max_size_mb: 100
+
+schema_config:
+  configs:
+    - from: 2024-01-01
+      store: tsdb
+      object_store: filesystem
+      schema: v13
+      index:
+        prefix: index_
+        period: 24h
+
+# 7 天保留，避免磁盘无限增长
+limits_config:
+  retention_period: 168h
+  max_query_series: 1000
+  # 允许采集历史日志（容器启动时的旧日志也能入库），靠 retention_period 控制总量
+  reject_old_samples: false
+  ingestion_rate_mb: 20
+  ingestion_burst_size_mb: 40
+  per_stream_rate_limit: 10MB
+  per_stream_rate_limit_burst: 40MB
+
+compactor:
+  working_directory: /loki/compactor
+  compaction_interval: 10m
+  retention_enabled: true
+  retention_delete_delay: 2h
+  retention_delete_worker_count: 150
+  delete_request_store: filesystem

pom.xml

@@ -44,6 +44,7 @@
         <mybatis-plus.version>3.5.7</mybatis-plus.version>
         <jjwt.version>0.12.5</jjwt.version>
         <springdoc.version>2.5.0</springdoc.version>
+        <ip2region.version>2.7.0</ip2region.version>
         <!-- Spring Boot 3.2 默认的 1.18.32 在 JDK 23+ 上会编译失败，这里提升到支持新 JDK 的版本 -->
         <lombok.version>1.18.48</lombok.version>
     </properties>
@@ -130,6 +131,12 @@
                 <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
                 <version>${springdoc.version}</version>
             </dependency>
+
+            <dependency>
+                <groupId>org.lionsoul</groupId>
+                <artifactId>ip2region</artifactId>
+                <version>${ip2region.version}</version>
+            </dependency>
         </dependencies>
     </dependencyManagement>
 

promtail-config.yml

@@ -0,0 +1,34 @@
+# Author: fruit.com.cn
+# Promtail：通过 Docker 服务发现自动采集所有容器的 stdout/stderr 日志，推送到 Loki。
+server:
+  http_listen_port: 9080
+  grpc_listen_port: 0
+
+positions:
+  filename: /tmp/positions.yaml
+
+clients:
+  - url: http://loki:3100/loki/api/v1/push
+    batchwait: 1s
+    batchsize: 1048576
+
+scrape_configs:
+  - job_name: docker-containers
+    docker_sd_configs:
+      - host: unix:///var/run/docker.sock
+        refresh_interval: 5s
+    relabel_configs:
+      # 容器名（去掉开头的 /）
+      - source_labels: ['__meta_docker_container_name']
+        regex: '/(.*)'
+        target_label: container
+      # 日志流：stdout / stderr
+      - source_labels: ['__meta_docker_container_log_stream']
+        target_label: stream
+      # 容器 ID 前 12 位
+      - source_labels: ['__meta_docker_container_id']
+        target_label: container_id
+        regex: '(.{12}).*'
+      # 镜像名
+      - source_labels: ['__meta_docker_container_image']
+        target_label: image

sql/data-sensitive-words-id.sql

@@ -0,0 +1,113 @@
+-- Author: fruit.com.cn
+
+-- FruitShorts 短剧服务 · 印尼语（id-ID）敏感词库增量补全（PostgreSQL 18）
+--
+-- 续接基线：sensitive_word 已有 id 9000001~9000053（zh-CN/en-US/id-ID 三语初版）。
+-- 本文件只补 id-ID 缺失/不足的分类，id 从 9000054 续接，避免与现有雪花 ID 冲突。
+--
+-- 分类（category）：POLITICS 政治 / PORN 色情 / ABUSE 辱骂 / AD 广告导流 / RELIGION 宗教
+-- 级别（level）：
+--   BLOCK   直接拒绝发布
+--   REVIEW  命中转人工审核（歧义词、可能误伤的业务词放这里）
+--   REPLACE 替换后放行（轻度脏话，用 replace_text 打码）
+--
+-- 幂等：唯一索引 uk_sensitive_word(language, word)，重复执行靠 ON CONFLICT DO NOTHING 跳过。
+-- 说明：词库内容需印尼运营/合规方复核后启用，本文件仅提供开发联调可用的初始基线。
+
+-- ============ 辱骂 / 脏话（ABUSE）· 补全 ============
+INSERT INTO sensitive_word (id, word, category, level, replace_text, language, status) VALUES
+  (9000054, 'babi',      'ABUSE', 'BLOCK',   '*',   'id-ID', 1),
+  (9000055, 'brengsek',  'ABUSE', 'BLOCK',   '*',   'id-ID', 1),
+  (9000056, 'kampret',   'ABUSE', 'BLOCK',   '*',   'id-ID', 1),
+  (9000057, 'keparat',   'ABUSE', 'BLOCK',   '*',   'id-ID', 1),
+  (9000058, 'sundal',    'ABUSE', 'BLOCK',   '*',   'id-ID', 1),
+  (9000059, 'lonte',     'ABUSE', 'BLOCK',   '*',   'id-ID', 1),
+  (9000060, 'pelacur',   'ABUSE', 'BLOCK',   '*',   'id-ID', 1),
+  (9000061, 'jancok',    'ABUSE', 'BLOCK',   '*',   'id-ID', 1),
+  (9000062, 'asu',       'ABUSE', 'BLOCK',   '*',   'id-ID', 1),
+  (9000063, 'sialan',    'ABUSE', 'REPLACE', '***', 'id-ID', 1),
+  (9000064, 'tolol',     'ABUSE', 'REPLACE', '***', 'id-ID', 1),
+  (9000065, 'goblok',    'ABUSE', 'REPLACE', '***', 'id-ID', 1),
+  (9000066, 'bodoh',     'ABUSE', 'REPLACE', '***', 'id-ID', 1),
+  (9000067, 'bego',      'ABUSE', 'REPLACE', '***', 'id-ID', 1),
+  (9000068, 'kirik',     'ABUSE', 'REPLACE', '***', 'id-ID', 1),
+  (9000069, 'tai',       'ABUSE', 'REPLACE', '***', 'id-ID', 1),
+  (9000070, 'bejat',     'ABUSE', 'REPLACE', '***', 'id-ID', 1)
+ON CONFLICT (language, word) DO NOTHING;
+
+-- ============ 色情（PORN）· 少量补全 ============
+INSERT INTO sensitive_word (id, word, category, level, replace_text, language, status) VALUES
+  (9000071, 'ngewe',        'PORN', 'BLOCK',  '*', 'id-ID', 1),
+  (9000072, 'toket',        'PORN', 'BLOCK',  '*', 'id-ID', 1),
+  (9000073, 'onani',        'PORN', 'BLOCK',  '*', 'id-ID', 1),
+  (9000074, 'perkosa',      'PORN', 'BLOCK',  '*', 'id-ID', 1),
+  (9000075, 'pemerkosaan',  'PORN', 'BLOCK',  '*', 'id-ID', 1),
+  (9000076, 'jembut',       'PORN', 'BLOCK',  '*', 'id-ID', 1),
+  (9000077, 'pepek',        'PORN', 'BLOCK',  '*', 'id-ID', 1),
+  (9000078, 'selingkuh',    'PORN', 'REVIEW', '*', 'id-ID', 1),
+  (9000079, 'gairah',       'PORN', 'REVIEW', '*', 'id-ID', 1)
+ON CONFLICT (language, word) DO NOTHING;
+
+-- ============ 政治（POLITICS）· 新增（基线缺失） ============
+INSERT INTO sensitive_word (id, word, category, level, replace_text, language, status) VALUES
+  (9000080, 'PKI',              'POLITICS', 'BLOCK',  '*', 'id-ID', 1),
+  (9000081, 'komunis',          'POLITICS', 'BLOCK',  '*', 'id-ID', 1),
+  (9000082, 'Papua Merdeka',    'POLITICS', 'BLOCK',  '*', 'id-ID', 1),
+  (9000083, 'OPM',              'POLITICS', 'BLOCK',  '*', 'id-ID', 1),
+  (9000084, 'GAM',              'POLITICS', 'BLOCK',  '*', 'id-ID', 1),
+  (9000085, 'separatis',        'POLITICS', 'BLOCK',  '*', 'id-ID', 1),
+  (9000086, 'separatisme',      'POLITICS', 'BLOCK',  '*', 'id-ID', 1),
+  (9000087, 'teroris',          'POLITICS', 'BLOCK',  '*', 'id-ID', 1),
+  (9000088, 'terorisme',        'POLITICS', 'BLOCK',  '*', 'id-ID', 1),
+  (9000089, 'ISIS',             'POLITICS', 'BLOCK',  '*', 'id-ID', 1),
+  (9000090, 'jihadis',          'POLITICS', 'BLOCK',  '*', 'id-ID', 1),
+  (9000091, 'radikalisme',      'POLITICS', 'BLOCK',  '*', 'id-ID', 1),
+  (9000092, 'kudeta',           'POLITICS', 'BLOCK',  '*', 'id-ID', 1),
+  (9000093, 'makar',            'POLITICS', 'BLOCK',  '*', 'id-ID', 1),
+  (9000094, 'pemberontak',      'POLITICS', 'BLOCK',  '*', 'id-ID', 1),
+  (9000095, 'pemberontakan',    'POLITICS', 'BLOCK',  '*', 'id-ID', 1),
+  (9000096, 'kerusuhan',        'POLITICS', 'BLOCK',  '*', 'id-ID', 1),
+  (9000097, 'penjarahan',       'POLITICS', 'BLOCK',  '*', 'id-ID', 1),
+  (9000098, 'radikal',          'POLITICS', 'REVIEW', '*', 'id-ID', 1),
+  (9000099, 'jihad',            'POLITICS', 'REVIEW', '*', 'id-ID', 1),
+  (9000100, 'anti-pemerintah',  'POLITICS', 'REVIEW', '*', 'id-ID', 1),
+  (9000101, 'bubarkan',         'POLITICS', 'REVIEW', '*', 'id-ID', 1)
+ON CONFLICT (language, word) DO NOTHING;
+
+-- ============ 宗教（RELIGION）· 补全 ============
+INSERT INTO sensitive_word (id, word, category, level, replace_text, language, status) VALUES
+  (9000102, 'penistaan agama', 'RELIGION', 'BLOCK',  '*', 'id-ID', 1),
+  (9000103, 'menghina agama',  'RELIGION', 'BLOCK',  '*', 'id-ID', 1),
+  (9000104, 'menghina Nabi',   'RELIGION', 'BLOCK',  '*', 'id-ID', 1),
+  (9000105, 'menghina Allah',  'RELIGION', 'BLOCK',  '*', 'id-ID', 1),
+  (9000106, 'menghina Kristen','RELIGION', 'BLOCK',  '*', 'id-ID', 1),
+  (9000107, 'menghina Katolik','RELIGION', 'BLOCK',  '*', 'id-ID', 1),
+  (9000108, 'menghina Hindu',  'RELIGION', 'BLOCK',  '*', 'id-ID', 1),
+  (9000109, 'menghina Buddha', 'RELIGION', 'BLOCK',  '*', 'id-ID', 1),
+  (9000110, 'kafir',           'RELIGION', 'BLOCK',  '*', 'id-ID', 1),
+  (9000111, 'murtad',          'RELIGION', 'BLOCK',  '*', 'id-ID', 1),
+  (9000112, 'sara',            'RELIGION', 'BLOCK',  '*', 'id-ID', 1),
+  (9000113, 'provokasi agama', 'RELIGION', 'BLOCK',  '*', 'id-ID', 1),
+  (9000114, 'konflik agama',   'RELIGION', 'REVIEW', '*', 'id-ID', 1)
+ON CONFLICT (language, word) DO NOTHING;
+
+-- ============ 广告导流 / 非法（AD）· 补全 ============
+INSERT INTO sensitive_word (id, word, category, level, replace_text, language, status) VALUES
+  (9000115, 'judi online',      'AD', 'BLOCK',  '*', 'id-ID', 1),
+  (9000116, 'slot online',      'AD', 'BLOCK',  '*', 'id-ID', 1),
+  (9000117, 'casino',           'AD', 'BLOCK',  '*', 'id-ID', 1),
+  (9000118, 'poker online',     'AD', 'BLOCK',  '*', 'id-ID', 1),
+  (9000119, 'situs judi',       'AD', 'BLOCK',  '*', 'id-ID', 1),
+  (9000120, 'deposit slot',     'AD', 'BLOCK',  '*', 'id-ID', 1),
+  (9000121, 'link alternatif',  'AD', 'BLOCK',  '*', 'id-ID', 1),
+  (9000122, 'pinjol',           'AD', 'BLOCK',  '*', 'id-ID', 1),
+  (9000123, 'rentenir',         'AD', 'BLOCK',  '*', 'id-ID', 1),
+  (9000124, 'scam',             'AD', 'BLOCK',  '*', 'id-ID', 1),
+  (9000125, 'penipuan',         'AD', 'BLOCK',  '*', 'id-ID', 1),
+  (9000126, 'investasi bodong', 'AD', 'BLOCK',  '*', 'id-ID', 1),
+  (9000127, 'arisan berantai',  'AD', 'BLOCK',  '*', 'id-ID', 1),
+  (9000128, 'money game',       'AD', 'BLOCK',  '*', 'id-ID', 1),
+  (9000129, 'pinjaman online',  'AD', 'REVIEW', '*', 'id-ID', 1),
+  (9000130, 'hack',             'AD', 'REVIEW', '*', 'id-ID', 1),
+  (9000131, 'jual akun',        'AD', 'REVIEW', '*', 'id-ID', 1)
+ON CONFLICT (language, word) DO NOTHING;

sql/migrate-k109-legacy-drama-like-cleanup.sql

@@ -0,0 +1,23 @@
+-- Author: fruit.com.cn
+-- K109 清理历史遗留的「按整部剧点赞」数据。
+-- 产品口径：收藏按剧，点赞与评论按集。客户端点赞入口只作用于当前剧集
+-- （targetType = EPISODE），以下 DRAMA 记录均为 2026-10-21 15:49 之前的旧模型遗留。
+BEGIN;
+
+UPDATE content_like
+SET deleted = 1
+WHERE target_type = 'DRAMA' AND deleted = 0;
+
+-- 剧级点赞数由这些行累加而来，随软删一并按实际剩余行数校准，避免详情页展示虚高数字。
+UPDATE drama d
+SET like_count = sub.cnt
+FROM (
+    SELECT d2.id, COUNT(l.id) AS cnt
+    FROM drama d2
+    LEFT JOIN content_like l
+           ON l.target_type = 'DRAMA' AND l.target_id = d2.id AND l.deleted = 0
+    GROUP BY d2.id
+) sub
+WHERE d.id = sub.id AND d.like_count IS DISTINCT FROM sub.cnt;
+
+COMMIT;