docs(plans): 记录 K19 账号中心交付回执

背景：1-3/1-4 的真机验证用了错地址 10.157.242.1（开发机 VPN 网卡、手机不可达），
且当时的证据是本机 curl 本机网卡地址返回 200 —— 假阳性，已导致真机首页加载失败。
本条目要求用正确地址（ipconfig getifaddr en0 取）重做，且证据必须产自设备侧
（首选：integration_test 在手机进程里真请求并断言），拿不到就如实标「未验证」。
红线新增第 10 条，防止再犯。

.dockerignore

@@ -0,0 +1,13 @@
+# Author: fruit.com.cn
+#
+# 构建上下文里不需要的东西：产物、IDE、本地上传的媒资、日志。
+# 注意别把 pom.xml / src / sql 排掉，镜像构建要用。
+**/target/
+.git/
+.gitignore
+.idea/
+*.iml
+*.log
+data/
+docs/
+node_modules/

.env.example

@@ -0,0 +1,36 @@
+# Author: fruit.com.cn
+#
+# 环境变量样例：复制成 .env 后填真实值（.env 不要提交，已在 .gitignore 里）。
+# 生产用 prod profile 时，下面标「必填」的项缺失/仍是 dev 默认值/长度不足 32 位 → 启动直接失败。
+# 详细说明见 DEPLOY.md。
+
+# ── 数据库 ─────────────────────────────────────────────
+# Docker Compose 单机部署：db 是 compose 里的服务名，保持默认即可；
+# 若数据库在别的主机/用云托管，把 DB_URL 换成外部地址。
+DB_NAME=fruitshorts
+DB_URL=jdbc:postgresql://db:5432/fruitshorts
+DB_USER=fruitshorts
+DB_PASSWORD=
+
+# ── 密钥（必填，各 32 位以上，且不能用代码里的 dev 默认值）──
+# 生成：openssl rand -base64 48
+JWT_ADMIN_SECRET=
+JWT_APP_SECRET=
+MEDIA_SIGNATURE_SECRET=
+
+# ── 生产开关 ───────────────────────────────────────────
+# prod profile 会强制 true（缺了签名则启动失败）
+MEDIA_SIGNATURE_REQUIRED=true
+# 后台前端来源，逗号分隔；生产不许用 *
+CORS_ALLOWED_ORIGINS=https://admin.example.com
+# 媒资根目录：容器里是挂载点
+MEDIA_ROOT_DIR=/data/uploads
+# 是否开放在线接口文档（**/doc.html 与 /v3/api-docs 一起开关**，没有"只留一个"的中间态）
+#   true  = 前端联调能看到 /doc.html（测试/联调环境建议 true，10-19 前端联调需要它）
+#   false = 两个都关闭（生产若不希望暴露 UI 就设 false，机器可读契约也一并关闭）
+SWAGGER_ENABLED=true
+
+# ── 可选：Google Play 商店票据校验（不配则保持 disabled）──
+STORE_VERIFIER=disabled
+GOOGLE_PLAY_PACKAGE_NAME=
+GOOGLE_PLAY_SERVICE_ACCOUNT_JSON=

.gitignore

@@ -16,3 +16,6 @@ logs/
 # 运行期上传的媒资（图片、视频，几百 MB）不入库，只保留目录
 data/uploads/*
 !data/uploads/.gitkeep
+
+# 部署用的真实环境变量（含密钥），只提交 .env.example
+.env

DEPLOY-CHECKLIST.md

@@ -0,0 +1,256 @@
+# Author: fruit.com.cn
+#
+# DEPLOY-CHECKLIST —— 部署合规视角（specs 约束逐条结论 + 上线检查清单对照 + 风险/待确认）
+#
+# 这份文档回答两个问题：
+#   1) `docs/04-部署架构`、`docs/08-备份恢复方案`、`docs/10-安全方案`、`docs/11-发布与回滚方案`、
+#      `docs/12-上线检查清单`、`docs/07-监控告警方案`、`GIT_WORKFLOW.md`、`CODING_STANDARDS.md`
+#      这些 specs 里跟部署有关的要求，**我们现在满足到哪一步**；
+#   2) 上线前**必须补什么**、谁来补。
+#
+# 操作层面的"怎么部署/怎么回滚命令"在 `DEPLOY.md`（本文件只做结论与对照，避免两份口径分叉）。
+# 结论用三态：✅ 已满足 ｜ ⚠️ 部分满足（能用但有差距）｜ ❌ 未满足（上线前必补）
+
+## 一、环境映射（对应 `04-部署架构`§一）
+
+`04-部署架构`§一把环境分成四级：
+
+| 环境 | 用途 | 数据 | 访问 |
+| --- | --- | --- | --- |
+| dev | 本地开发 | 本地 PostgreSQL | 内网 |
+| test | 测试/联调 | 独立测试库 | 内网/VPN |
+| pre | 预发（生产镜像演练） | 接近生产 | 受限 |
+| prod | 生产 | 生产库 | 公网 |
+
+**当前这台办公室主机 = `test` 环境**，依据三条：
+
+1. 用途是"给前端联调 + 内部验收"，不是对外生产（`04-部署架构`§一 test = 测试/联调）；
+2. 访问方式计划是内网/办公网（`admin-api` 只绑 `127.0.0.1`），而不是公网；
+3. 用的是独立的开发库（`fruitshorts`，含种子数据），不是生产库。
+
+规范要求与我们的对应：
+
+- `docker-compose.yml` 用 **Docker Compose 单机编排** → 对应 §五「第一阶段（dev/test）：Docker Compose 单机编排」，✅。
+- 一台机器上合并 app/api/DB/Redis + worker 独立容器 → 对应 §三「精简方案：test 环境可将 app/api/DB/Redis 合并到 1 台 8C32G，转码 worker 独立 1 台」，✅（worker 是独立容器，但**与在线服务同机**：资源隔离靠容器限额，真正的分机留到生产）。
+- **差距**：`pre` 环境（生产镜像演练）**尚未建立** —— 上线前建议在目标机用同一份 compose 跑一次"预发演练"，即用生产镜像 + 接近生产的数据走一遍发布流程。状态：❌（流程未建立，不阻塞 test 联调）。
+
+## 二、域名 / HTTPS / 反向代理（对应 `04-部署架构`§四 + `10-安全方案`§二）
+
+**specs 原文**：`04-部署架构`§四「域名/SSL：管理端、客户端 API、媒资**分别域名**；**HTTPS 强制**」；
+`10-安全方案`§二「传输安全：HTTPS 强制；密钥环境变量注入」。
+
+**当前状态：❌ 未满足**。现在的形态是 `IP:端口 + HTTP`：
+
+| 需要的域名 | 现状 | 上线前必须做 |
+| --- | --- | --- |
+| 管理端（后台 Web + `/admin/**`） | 无域名；`admin-api` 绑 `127.0.0.1:8080`，靠内网/SSH 隧道访问 | 申请域名（如 `admin.<domain>`）+ 证书；nginx 反代 → `127.0.0.1:8080`；**并保持只允许内网/VPN 来源**（见 §三） |
+| 客户端 API（`/app/**`） | 无域名；`app-api` 监听 `8081`（HTTP） | 申请域名（如 `api.<domain>`）+ 证书；nginx 反代 → `8081`，只暴露 `/app/**`；**强制 HTTP→HTTPS 跳转** |
+| 媒资（`/files/**`） | 无域名；与 app-api 同一端口 | 申请域名（如 `media.<domain>`）或直接走 CDN 域名；**播放地址已带签名参数**，CDN 需按签名做缓存策略（`04-部署架构`§四） |
+
+**测试环境（本机）可以先用内网 HTTP 联调**（`04-部署架构`§一 test 是内网/VPN 访问），
+但**上线（pre/prod）前必须满足上述三条 HTTPS + 独立域名**，否则不满足 `12-上线检查清单`§三「传输安全」。
+
+### nginx + 证书的建议做法（上线前照做）
+
+```nginx
+# /etc/nginx/conf.d/fruitshorts.conf（示意；域名与证书路径按实际替换）
+server {                      # 客户端 API
+    listen 443 ssl http2;
+    server_name api.example.com;
+    ssl_certificate     /etc/letsencrypt/live/api.example.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/api.example.com/privkey.pem;
+    client_max_body_size 20m;     # 分片上传，与 admin-api 的 multipart 上限一致
+    location / { proxy_pass http://127.0.0.1:8081; proxy_set_header Host $host;
+                 proxy_set_header X-Forwarded-For $remote_addr;
+                 proxy_set_header X-Forwarded-Proto $scheme; }
+}
+server {                      # 管理端：只允许内网/VPN 网段
+    listen 443 ssl http2;
+    server_name admin.example.com;
+    allow 10.0.0.0/8; allow 192.168.0.0/16; deny all;    # 按实际内网段调整
+    location / { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host;
+                 proxy_set_header X-Forwarded-For $remote_addr;
+                 proxy_set_header X-Forwarded-Proto $scheme; }
+}
+server {                      # HTTP 强制跳 HTTPS
+    listen 80;
+    server_name api.example.com admin.example.com;
+    return 301 https://$host$request_uri;
+}
+```
+
+证书建议用 **Let's Encrypt（certbot）** 自动续期（`certbot --nginx -d api.example.com -d admin.example.com`），
+或公司自有证书；无论哪种，**到期前必须能自动续**，否则接口会整体不可用。
+反代配置文件需与本仓库一起纳入版本管理（放目标机的 `/etc/nginx/conf.d/`，另存一份到运维仓库）。
+
+## 三、网络分区（对应 `04-部署架构`§四）
+
+**specs 原文**：「网络分区：管理后台仅内网/VPN 可访问；客户端 API 公网。」
+
+| 要求 | 现状 | 上线前必须做 |
+| --- | --- | --- |
+| 管理后台仅内网/VPN | ✅ 已满足：`docker-compose.yml` 里 admin-api 端口映射为 `127.0.0.1:8080:8080`（只绑本机，公网访问不到） | 上公网后仍要保证：只经 nginx + `allow/deny` 内网段暴露（见 §二示例） |
+| 客户端 API 公网 | ⚠️ 部分满足：`app-api` 监听 `0.0.0.0:8081`，同网段可访问；**但还没有反代/域名，也没限制只暴露 `/app/**`** | 反代只放行 `/app/**`（`/files/**` 走媒资域名/CDN）；不要把 `/v3/api-docs`、`/healthz` 直接暴露到公网（`/healthz` 可留给内网监控） |
+
+**注意**：`/doc.html` 与 `/v3/api-docs` 由 `SWAGGER_ENABLED` 控制（见 `DEPLOY.md`）。
+**联调环境建议 `true`**（前端要看），**公网生产建议 `false`**（不暴露接口清单）。
+
+## 四、发布与回滚规范（对应 `11-发布与回滚方案`§一/§四 + `GIT_WORKFLOW.md`§四）
+
+**specs 原文**：
+
+- `11-发布与回滚方案`§一：「语义化版本 `v<major>.<minor>.<patch>`；分支 `main`（生产）← `release/*` ← `develop` ← `feature/*`；每次 `release`/`hotfix` 合并 `main` 必须打 tag，tag 不可移动/删除。」
+- `GIT_WORKFLOW.md`§四：「`major` 破坏性变更、`minor` 新功能、`patch` 修复；发布后 tag 不可移动、不可删除（错误版本发新 tag 修正，不覆盖旧 tag）。」
+- `11-发布与回滚方案`§四：「回滚演练：**上线前演练回滚**，确保可执行。」「数据库迁移脚本必须可回滚（向前兼容，避免破坏性变更）。」
+
+| 要求 | 现状 | 上线前必须做 |
+| --- | --- | --- |
+| 语义化 tag `v<x.y.z>` | ⚠️ 部分满足：`DEPLOY.md` 里只是示例式地提到"每次发版打 tag"，**没有命名规范** | 按 §四 规则打：首个上线版本 `v1.0.0`；之后功能 `v1.1.0`、修复 `v1.0.1`；**错误版本发新 tag，绝不移动/删除旧 tag** |
+| release/hotfix 合并 main | ⚠️ 流程未走过：目前工作都在 `develop`，`main` 未动 | 上线时：`develop` → 建 `release/v1.0.0` → 在 test 环境验证 → 合并 `main` + 打 tag `v1.0.0`（**由用户操作，Codex 不碰 main**） |
+| 回滚可执行 | ✅ 技术路径已写全（`DEPLOY.md`§七：切回上一个镜像 tag / git 回上一个 release tag + `up -d --build` + 重跑冒烟） | **上线前演练一次**（在 test 环境故意回滚到上一版本并跑 `tools/smoke.sh`），把演练记录留档 |
+| 数据库迁移可回滚 | ⚠️ 部分满足：`sql/*.sql` 全是幂等增量（`ADD COLUMN IF NOT EXISTS`、`CREATE TABLE IF NOT EXISTS`），**没有破坏性变更**；`upsert` 语义的种子脚本也在 | 上线前确认：本次发布**不包含** `DROP/ALTER TYPE` 类破坏性语句（当前没有）；如将来有，必须先写"回滚脚本 + 备份"再发 |
+| 灰度/放量 | ❌ 未满足（单机 Compose 无灰度能力） | 上线首日按"先内测 → 再小流量（如有网关可切）"；正式灰度需要 K8s/网关，属后续阶段（`04-部署架构`§五：生产上 K8s） |
+
+## 五、备份与恢复（对应 `08-备份恢复方案`§二/§三）
+
+**specs 目标**：全量每日 × 保持 30 天；**WAL 归档（实时）**；可选增量；**备份加密 + 异地存储**；
+**RPO ≤ 5 分钟、RTO ≤ 30 分钟**；**每季度至少一次恢复演练**。
+
+| 项 | specs 要求 | 现状 | 差距 / 上线前必须补 |
+| --- | --- | --- | --- |
+| 全量备份 | 每日 1 次，保留 30 天 | ⚠️ `DEPLOY.md`§七 给了**手动** `pg_dump` 命令；**没有定时任务、没有保留策略** | 目标机加 cron（或 compose 侧容器）每日 `pg_dump`，按日期命名保留 30 天；脚本可放 `tools/backup.sh`（本轮未写，属运维脚本） |
+| WAL 归档 | 实时，用于 PITR | ❌ 未配置（PG 默认 `archive_mode=off`） | `postgresql.conf`：`wal_level=replica`、`archive_mode=on`、`archive_command` 推到异地；这是达成 **RPO≤5min** 的唯一途径 |
+| 增量 | 可选 | ❌ 未做 | 有了 WAL 归档即可满足 RPO，增量备份可后补 |
+| 加密 | 备份加密 | ❌ 未做 | `pg_dump` 管道给 `age`/`gpg`，或落到加密卷；密钥单独保管（与备份分开） |
+| 异地 | 与生产不同可用区/账号 | ❌ 未做（本机 dump 还在同一台机器上） | 推到对象存储（另一账号/另一区）；**"备份和数据库在同一台机器上"等于没备份** |
+| 恢复演练 | 每季度 ≥ 1 次，记录归档 | ❌ 从未做过 | 首次上线前做一次"恢复到新库 + 起服务 + 冒烟"，记录耗时（验 RTO）与丢失窗口（验 RPO） |
+
+**结论：备份恢复这一项与 specs 差距最大，是上线前必须补的硬缺口（❌）。**
+当前只有"能手动 dump"，距离「RPO≤5min / RTO≤30min / 加密 / 异地 / 季度演练」还差整套机制。
+建议排期：**上线前**至少做到「每日全量 + 异机保存 + 一次恢复演练」；**上线后两周内**补 WAL 归档与加密。
+
+## 六、监控与告警现状（对应 `07-监控告警方案`§七）
+
+**specs 原文**：`07-监控告警`§七「Prometheus/Loki/Grafana 尚未部署，**第一阶段先用日志 + `SlowRequestLogger` 兜底**」；
+§六「告警渠道：飞书/钉钉/邮件 + 值班轮转」；§六「值班表与 Runbook 见 `docs/plans/`（上线前补）」。
+
+| 项 | 现状 | 上线前必须补 |
+| --- | --- | --- |
+| 指标（Prometheus） | ❌ 未部署；**项目也没引 actuator**（`/actuator/health` 一直是未映射，见 `DEPLOY.md`§五说明） | 按 §七 的既定路线部署；要暴露指标需先给两个入口加 `spring-boot-starter-actuator` + `micrometer-registry-prometheus`（**属代码改动，需立项**） |
+| 日志聚合（Loki） | ❌ 未部署；现在日志在容器 stdout（`docker compose logs`） | 部署 Loki + Promtail 采集容器日志 |
+| 大盘（Grafana） | ❌ 未部署 | 按 §五 大盘定义建面板 |
+| 第一阶段兜底 | ✅ 已具备：应用结构化日志（转码耗时/失败原因、业务异常、`SlowRequestLogger` 慢请求告警都在代码里）+ 容器级 `healthcheck`（`/healthz`） | 至少把"容器 unhealthy"接到人的手机上（可用 `docker compose events` + 简单脚本/飞书机器人） |
+| 告警渠道 + 值班 + Runbook | ❌ 未定 | 定渠道（飞书/钉钉/邮件）、排值班表、把 `DEPLOY.md`§九「故障速查」扩成 Runbook |
+
+**结论：监控告警 ❌ 未满足**，但按 specs §七 的既定节奏，**第一阶段允许先用日志兜底** ——
+前提是"告警能到达人"。上线前最低要求：**容器 unhealthy / 冒烟失败能被发现**（哪怕先是人工每天跑一次 `tools/smoke.sh`）。
+
+## 七、密钥托管与轮换（对应 `10-安全方案`§五）
+
+**specs 原文**：§五「密钥托管：生产密钥**集中托管**，**最小权限**」；`12-上线检查清单`§三「JWT/签名密钥走环境变量，未硬编码/入库」「生产密钥集中托管」。
+
+| 要求 | 现状 | 上线前必须补 |
+| --- | --- | --- |
+| 密钥走环境变量、未硬编码/入库 | ✅ 已满足：三个可运行件的密钥全部 `${ENV:...}` 注入；`.env` 已 gitignore；`.env.example` 只有占位；镜像里不含密钥 | 继续保持；**代码审查时禁止把密钥写回 yml** |
+| 缺失即启动失败 | ✅ 已满足：`ProdSecretGuard` 在 `prod` profile 下校验三个密钥 + 签名开关 + DB_URL + CORS，缺失/仍是 dev 默认值/不足 32 位 → 退出码 1 | — |
+| **集中托管** | ⚠️ 部分满足：现在是"目标机的 `.env` 文件"（文件权限 600），**没有密钥管理系统** | 短期：`.env` 权限 600、只有运维账号可读、**不进任何 git 仓库**、单独备份（加密）；中期：迁到 K8s Secret / 云 KMS / Vault（`04-部署架构`§五 生产路线也是 K8s Secret） |
+| 最小权限 | ⚠️ 部分满足：DB 用单一 `fruitshorts` 账号（读写全库） | 拆账号：应用用 `fruitshorts_app`（DML 权限、无 DDL）；备份用只读账号；DDL 只留给运维 |
+| 轮换 | ❌ 未做（也没有流程） | 定义轮换周期（建议 90 天或按事件）：**先加新密钥 → 双密钥并行验证期 → 再下线旧密钥**；JWT 轮换会导致存量 token 失效，需选低峰并公告（`10-安全方案`§一 token 有效期 120min，影响窗口可控） |
+
+## 八、上线检查清单对照表（逐条映射 `docs/12-上线检查清单.md`）
+
+> 三态：✅ 已满足 ｜ ⚠️ 部分满足 / 有条件满足 ｜ ❌ 未满足（上线前必补）
+> 「责任方」列区分：**Codex**（我能做的）/ **用户或运维**（需要账号、域名、外部资源）。
+
+### 一、代码与门禁
+
+| 检查项 | 状态 | 依据 / 缺口 | 责任方 |
+| --- | --- | --- | --- |
+| 三端门禁全绿 | ⚠️ | **后端 ✅**：`mvn test` 83 条全过；**前端（Flutter/Web）不在本工程范围**，由另一同事的 AI 负责，需其提供门禁结果 | 用户/前端 |
+| 接口契约 `api-phase1.md` 已同步 | ✅ | 本轮 B1-1/B1-2 的 verify / reconcile 改动都已同步进契约 | Codex |
+| 作者标识齐全 | ✅ | 远端已做全量补齐（`35be37c`），本轮新增文件也都带 `// Author: fruit.com.cn` | Codex |
+| 代码规模红线、无关键路径 TODO | ⚠️ | 未做静态检查工具（后端无 checkstyle/pmd），**存量未逐文件核对**；无 TODO 扫描证据 | Codex（需立项） |
+
+### 二、功能与测试
+
+| 检查项 | 状态 | 依据 / 缺口 | 责任方 |
+| --- | --- | --- | --- |
+| 核心用例通过、P0 清零 | ⚠️ | 后端 83 条（含真实 ffmpeg smoke）全过；**前端与端到端用例不在本工程** | Codex/用户 |
+| 支付闭环端到端 | ⚠️ | 票据校验/幂等/退款回收/对账**已实现并有单测**；**真实 Google Play 未联调**（缺 packageName + service account JSON，属付费凭据） | 用户（凭据）+ Codex（联调） |
+| 播放长稳 + 弱网测试 | ❌ | 未做（需真机 + 网络模拟） | 前端/用户 |
+| 多端（iOS/Android）回归 | ❌ | 未做（Android 无可用模拟器，iOS 有真机） | 前端/用户 |
+
+### 三、安全
+
+| 检查项 | 状态 | 依据 / 缺口 | 责任方 |
+| --- | --- | --- | --- |
+| 播放签名 `signature-required=true`（生产必开） | ✅ | `application-prod.yml` 写死 `true`，`ProdSecretGuard` 再校验一次，缺了直接拒启 | Codex |
+| JWT/签名密钥走环境变量，未硬编码/入库 | ✅ | 三件全 `${ENV:...}`；`.env` gitignore；镜像不含密钥 | Codex |
+| 越权/注入/敏感数据专项测试 | ⚠️ | **越权**：创作者中心有专项用例（B 批）；**注入/SQL 注入**：全部走 MyBatis-Plus 参数绑定，无字符串拼接 SQL（人工核对），**无自动化用例**；敏感数据脱敏有实现（`AppIdentifier.mask`）但无专项测试 | Codex（需立项） |
+| 生产密钥集中托管 | ⚠️ | 见 §七：现为 `.env` 文件权限隔离，未接 KMS/Vault | 用户/运维 |
+
+### 四、基础设施
+
+| 检查项 | 状态 | 依据 / 缺口 | 责任方 |
+| --- | --- | --- | --- |
+| 数据库分区已生效 | ✅ | `watch_history`/`playback_ticket`/`order_event` 均为声明式月分区，`partition-maintenance` 启动时+每日补齐。**实测证据**：`select tableoid::regclass, count(*) from playback_ticket group by 1` → `playback_ticket_202610 \| 1`（落月分区，不是 `_default`）；`select count(*) from watch_history_default` → `0` | Codex |
+| Redis/缓存（如接入）配置正确 | ⚠️ | compose 已备 Redis 容器，**代码尚未接入（C2 待做）**；当前不依赖 Redis | Codex（C2） |
+| 媒资已迁 OSS/S3 + CDN（生产） | ❌ | **仍是本地磁盘 `./data/uploads`，与在线服务同机**；`MediaStorageService` 已把存储收敛到一处，切换 OSS 只需改它 + 转码产物上传路径 | 用户（账号）+ Codex |
+| 备份恢复已配置并演练 | ❌ | 见 §五，差距最大 | 用户/运维 + Codex（脚本） |
+| 监控告警已接入、告警可达 | ❌ | 见 §六 | 用户/运维 |
+
+### 五、商店与合规
+
+| 检查项 | 状态 | 依据 / 缺口 | 责任方 |
+| --- | --- | --- | --- |
+| 应用名称/截图/文案/隐私标签一致 | ❌ | 未办（客户端上架材料） | 用户 |
+| App Privacy / Data Safety / SDK 清单 | ❌ | 未办 | 用户 |
+| 隐私政策、用户协议已上线 | ❌ | 未办（后端有 `app_user_consent` 落库能力，文案与页面需法务/前端） | 用户 |
+| 版权/素材/商标授权台账 | ❌ | 未办 | 用户 |
+| 商店账号/证书/包名有效 | ❌ | 未办；**并且包名仍不一致**（Android `com.stormg.lumadrama` / iOS `com.stormg.lumadramv`，见 C 端回执） | 用户（建议上架前统一） |
+
+### 六、发布与回滚
+
+| 检查项 | 状态 | 依据 / 缺口 | 责任方 |
+| --- | --- | --- | --- |
+| 版本号 + tag 冻结（`v1.0.0`） | ❌ | 尚未打 tag（规范见 §四） | 用户（合并 main 时打） |
+| 回滚方案已演练 | ❌ | 方案已写（`DEPLOY.md`§七），**未演练** | 用户/运维 |
+| 值班表 + 告警 Runbook 就绪 | ⚠️ | `DEPLOY.md`§九「故障速查」可作为 Runbook 初稿；**值班表未定** | 用户 |
+| 灰度/放量计划明确 | ❌ | 单机 Compose 无灰度能力；生产上 K8s 后再做 | 用户 |
+
+### 七、观察窗口（上线后）
+
+| 检查项 | 状态 | 依据 / 缺口 | 责任方 |
+| --- | --- | --- | --- |
+| 核心链路监控 | ❌ | 监控未接；**上线首日建议人工每 30 分钟跑一次 `tools/smoke.sh` + 看 `docker compose logs`** 作为过渡 | 用户/运维 |
+| 支付/订单对账数据回看 | ⚠️ | 对账能力已在（`/admin/reconcile/run`，`storeAmountSum` 无数据源时返回 null + notes），**真实商店数据要等凭据** | Codex/用户 |
+| 崩溃率/错误率观察 | ❌ | 未接监控；容器日志可人工查 | 用户/运维 |
+| 问题复盘归档 | ⚠️ | 本工程有 PROGRESS/回执留痕习惯，可沿用 | Codex/用户 |
+
+## 九、风险 / 待确认（`CODING_STANDARDS`§7 要求：技术决策必须留痕）
+
+| # | 风险 / 待确认 | 影响 | 建议与责任方 |
+| --- | --- | --- | --- |
+| R1 | **媒资仍在本机磁盘**（`./data/uploads`），未迁 OSS/CDN | 单机磁盘满/机器损坏即媒资全丢；播放无法借 CDN 扛量 | `12-上线检查清单`§四把"迁 OSS/CDN"列为上线项，**属上线前必补**；`MediaStorageService` 已是唯一替换点，切换工作量可控（Codex 可做，需 OSS 账号） |
+| R2 | **单点无高可用**：一台办公室主机跑全栈 | 机器/网络故障 = 服务全停；无灰度能力 | test 阶段可接受；**生产必须按 `04-部署架构`§三 生产规格（应用 2+、DB 主备）+ §五 上 K8s** |
+| R3 | **备份未演练、无 WAL 归档、备份与库同机** | 真出事时可能既恢复不了也丢得多（RPO 远大于 5 分钟） | 上线前至少"每日全量 + 异机保存 + 一次恢复演练"；两周内补 WAL 归档与加密（见 §五） |
+| R4 | **监控与告警未接** | 故障靠人发现；上线首日风险最高的窗口无自动告警 | 短期用"人工冒烟 + 容器 healthcheck"；随后按 `07-监控告警方案`部署（需先给服务加 actuator，属代码改动） |
+| R5 | **商店合规未办**（隐私政策/Data Safety/SDK 清单/版权台账/包名） | 无法上架；印尼还涉及 Kominfo PSE 注册（未注册可能被整体封锁，见 `docs/08`/PRD 合规节） | 全部为用户侧工作；其中"包名统一"建议在上架前完成（一旦上架不可改） |
+| R6 | **真实 Google Play 联调未做**（缺 packageName + service account JSON） | 支付闭环在真机/商店侧未验证；`STORE_VERIFIER=disabled` 时对外明确返回"尚未配置"，不会产生假订单 | 用户提供凭据后，Codex 用沙盒测试购买联调（`STORE_VERIFIER=google-play`） |
+| R7 | **HTTPS/域名未就绪**，当前 IP+HTTP | 不满足 `04-部署架构`§四与 `10-安全方案`§二；公网明文传输不可接受 | 上线前按 §二 配域名 + 证书 + nginx（用户/运维） |
+| R8 | **DB 账号未做最小权限**（单账号读写全库） | 应用被攻破即拥有 DDL 能力 | 拆 `fruitshorts_app`（仅 DML）与备份只读账号（见 §七） |
+| R9 | **`/swagger-ui/**` 静态资源在 `SWAGGER_ENABLED=false` 时仍可访问** | 不泄露接口信息（spec 与 config 都已 404），但严格合规环境下应彻底关闭 | 可选加固：`spring.web.resources` 排除 webjar；需你点头再改（Codex） |
+| R10 | 转码 worker 与在线服务**同机**（虽为独立容器） | 大批量转码会抢 CPU，影响播放稳定性 | `04-部署架构`§三 的完整方案是 worker 独立 1 台；上线前如有第二台机器就拆开，否则给 worker 容器加 CPU 限额（Codex 可改 compose） |
+
+## 十、上线前必补清单（按优先级）
+
+| 优先级 | 事项 | 依赖 | 责任方 |
+| --- | --- | --- | --- |
+| P0 | HTTPS + 独立域名 + nginx 反代（§二） | 域名、证书 | 用户/运维 |
+| P0 | 每日全量备份 + 异机保存 + 一次恢复演练（§五） | 目标机 + 异地存储 | 用户/运维（Codex 可提供脚本） |
+| P0 | 媒资迁 OSS/CDN（R1） | 云账号 | 用户 + Codex |
+| P1 | tag 规范落地 + 回滚演练（§四） | — | 用户（合并 main 时）/ Codex 配合 |
+| P1 | 监控告警最低可用（§六：容器 unhealthy 能到人） | 通知渠道 | 用户/运维 |
+| P1 | 真实 Google Play 联调（R6） | 付费凭据 | 用户 → Codex |
+| P2 | DB 最小权限账号（R8）、密钥集中托管（§七） | 运维 | 用户/运维 |
+| P2 | K8s 生产化（R2）、灰度能力、WAL 归档与加密 | 生产资源 | 后续阶段 |

DEPLOY.md

@@ -0,0 +1,208 @@
+# FruitShorts 后端部署与回滚（DEPLOY）
+
+> 依据：`docs/04-部署架构.md`（第一阶段 **Docker Compose 单机**、镜像即交付物；生产才上 K8s）、
+> `docs/11-发布与回滚方案.md`、`docs/12-上线检查清单.md`（**播放签名生产必开**、密钥走环境变量）。
+> 目标机形态：**办公室一台主机**（§三 精简方案：app/api/DB/Redis 合并 1 台 8C32G，转码 worker 独立进程）。
+
+> **本文只讲"怎么部署/怎么回滚"**。要回答"我们离 specs 还差什么、上线前必补什么"，
+> 看 **[DEPLOY-CHECKLIST.md](./DEPLOY-CHECKLIST.md)**（环境映射、域名/HTTPS、备份恢复、监控、发布与回滚规范、
+> `docs/12-上线检查清单` 逐条对照表、风险/待确认）。
+
+**这台办公室主机属于 `test` 环境**（`04-部署架构`§一：测试/联调、独立测试库、内网/VPN 访问）；
+`pre`/`prod` 的规格与前置条件见 `DEPLOY-CHECKLIST.md` §一。
+
+## 一、两条部署路径（先选一条）
+
+| 路径 | 适用 | 命令主线 |
+| --- | --- | --- |
+| **A. Docker Compose（推荐，文档口径）** | 目标主机装了 Docker + Compose；一条命令起全栈（含 PG 18 与 Redis） | 见 §三 |
+| **B. 裸 jar（兜底）** | 主机没有 Docker，或只想起单个进程调试 | 见 §四 |
+
+> 两条路径的**配置完全相同**（同一批环境变量），只是"谁来跑进程"不同。
+
+## 二、环境变量清单
+
+复制 `.env.example` 为 `.env` 填值（`.env` 已在 `.gitignore`，**不要提交**）。
+使用 `--spring.profiles.active=prod`（Compose 里已默认）时，下表标 🔴 的项**缺失/仍是 dev 默认值/长度不足 32 位 → 启动直接失败**（fail-fast，见 §五）。
+
+| 变量 | 必填 | 缺失后果 | 说明 |
+| --- | --- | --- | --- |
+| `DB_URL` | ✅ | 用默认 `jdbc:postgresql://127.0.0.1:5432/fruitshorts`，连不上就启动失败 | Compose 里默认指向 `db` 服务 |
+| `DB_USER` / `DB_PASSWORD` | ✅ | 连库失败 | Compose 的 db 容器用同一组值创建库 |
+| `DB_NAME` | Compose 必填 | 默认 `fruitshorts` | 只在 compose 里用到 |
+| `JWT_ADMIN_SECRET` | 🔴 | **prod 拒绝启动** | 管理端令牌密钥，≥32 位，生成：`openssl rand -base64 48` |
+| `JWT_APP_SECRET` | 🔴 | **prod 拒绝启动** | 客户端令牌密钥。**过去这个键没外置，一直用代码里的 dev 默认值**，务必注入 |
+| `MEDIA_SIGNATURE_SECRET` | 🔴 | **prod 拒绝启动** | 播放地址签名密钥（`docs/12-上线检查清单`） |
+| `MEDIA_SIGNATURE_REQUIRED` | 🔴 | prod 下不是 `true` 就拒绝启动 | 生产必须开；本地调试保持 false |
+| `CORS_ALLOWED_ORIGINS` | 🔴 | prod 下为空则拒绝启动 | 逗号分隔的正式来源，**生产不许用 `*`** |
+| `MEDIA_ROOT_DIR` | 建议 | 默认 `./data/uploads`，容器里必须为 `/data/uploads` | 媒资根目录（挂载卷） |
+| `SERVER_PORT` | Compose 已设 | 默认 8081/8080 | app-api 8081 / admin-api 8080 |
+| `SWAGGER_ENABLED` | 可选 | 默认 false（**测试/联调请在 `.env` 里设 `true`**，前端要看 `/doc.html`） | **一次开关两个**：`true` = `/doc.html` + `/v3/api-docs` 都开；`false` = 两个都关（生产不想暴露 UI 就设 false，机器可读契约也一并关闭） |
+| `STORE_VERIFIER` / `GOOGLE_PLAY_*` | 可选 | 默认 `disabled` | 商店票据校验，没凭据就保持 disabled（对外返回"尚未配置"） |
+
+**密钥怎么生成**：`openssl rand -base64 48`（每个密钥单独生成，别复用）。
+
+## 三、路径 A：办公室单机 + Docker Compose（主线）
+
+目标主机前置：**Docker + Docker Compose**（`docker compose version` 有输出即可），建议 8C32G。
+
+```bash
+# 0) 取代码（或拿打包好的目录）并进入 FruitServer
+cd FruitServer
+
+# 1) 配置环境变量
+cp .env.example .env
+openssl rand -base64 48        # 生成三个密钥，分别填进 JWT_ADMIN_SECRET / JWT_APP_SECRET / MEDIA_SIGNATURE_SECRET
+vi .env                        # 还要填 DB_PASSWORD、CORS_ALLOWED_ORIGINS
+
+# 2) 构建并启动（首次会自动建表 + 造种子数据）
+docker compose up -d --build
+
+# 3) 看状态与日志
+docker compose ps                 # 预期：db/redis healthy，app-api/admin-api healthy，transcode-worker running
+docker compose logs -f app-api    # 预期：出现 "生产配置校验通过" 与 "Started AppApiApplication"
+
+# 4) 冒烟
+tools/smoke.sh                    # 预期：全部 PASS，退出码 0
+```
+
+**端口与访问**：app-api `8081`（对客户端开放）、admin-api **只绑 `127.0.0.1:8080`**（管理端仅内网，公网通过 SSH 隧道或反代访问）、PG/Redis 不对宿主暴露。
+
+**数据库初始化**：`sql/*.sql` 已挂进 `docker-entrypoint-initdb.d`（schema → schema-phase1 → partition → data → data-phase1），
+**只在数据卷为空时执行**。改 SQL 后要重来：`docker compose down -v`（**会删数据**）再 `up`。
+
+**日常操作**
+
+```bash
+docker compose ps                     # 状态
+docker compose logs -f --tail=200     # 全部日志
+docker compose restart app-api        # 重启单个服务
+docker compose up -d --build app-api  # 只重建单个镜像
+docker compose down                   # 停（保留数据卷）
+```
+
+## 四、路径 B：裸 jar（兜底）
+
+目标主机前置：**JDK 21**；转码进程额外需要 **ffmpeg/ffprobe**（`brew install ffmpeg` 或 `apt install ffmpeg`）。
+数据库：自己装 PostgreSQL 18 并导入 `sql/*.sql`（顺序同上）。
+
+```bash
+cd FruitServer
+mvn -pl fruitshorts-app-api,fruitshorts-admin-api,fruitshorts-transcode-worker -am package -DskipTests
+
+# 导出环境变量（示例；密钥务必换真实值）
+export DB_URL=jdbc:postgresql://127.0.0.1:5432/fruitshorts DB_USER=fruitshorts DB_PASSWORD='***'
+export JWT_ADMIN_SECRET="$(openssl rand -base64 48)"       # 生产请固定保存，不要每次重新生成
+export JWT_APP_SECRET="$(openssl rand -base64 48)"
+export MEDIA_SIGNATURE_SECRET="$(openssl rand -base64 48)"
+export MEDIA_SIGNATURE_REQUIRED=true CORS_ALLOWED_ORIGINS='https://admin.example.com'
+export MEDIA_ROOT_DIR="$PWD/data/uploads"
+
+# 起三个进程（生产用 prod profile；本地调试去掉 --spring.profiles.active=prod 即可）
+nohup java -jar fruitshorts-admin-api/target/fruitshorts-admin-api-1.0.0-SNAPSHOT.jar \
+  --spring.profiles.active=prod > /tmp/admin.log 2>&1 &
+nohup java -jar fruitshorts-app-api/target/fruitshorts-app-api-1.0.0-SNAPSHOT.jar \
+  --spring.profiles.active=prod > /tmp/app.log 2>&1 &
+nohup java -jar fruitshorts-transcode-worker/target/fruitshorts-transcode-worker-1.0.0-SNAPSHOT.jar \
+  --spring.profiles.active=prod > /tmp/worker.log 2>&1 &
+```
+
+> ⚠️ **重新打包必须重启进程**：`spring-boot:repackage` 会原地替换 jar，运行中的进程再去加载"没加载过的类"
+> 会抛 `NoClassDefFoundError`，表现为**请求挂住**（S1 记录过这个坑）。顺序永远是"改完 → 打包 → 重启 → 验证"。
+
+## 五、prod fail-fast 是什么、长什么样
+
+`prod` profile 下 `ProdSecretGuard` 会校验：JWT 双密钥 + 媒体签名密钥（非空、不是 dev 默认值、≥32 位）、
+`signature-required=true`、`DB_URL` 非空、CORS 非空。任一不满足 → **打印全部问题并终止启动**：
+
+```
+ERROR c.f.framework.config.ProdSecretGuard : 生产配置校验未通过，拒绝启动（prod profile）：
+  - fruitshorts.jwt.admin-secret（环境变量 JWT_ADMIN_SECRET） 仍是代码里的 dev 默认值，必须换成生产密钥
+  - fruitshorts.jwt.app-secret（环境变量 JWT_APP_SECRET） 仍是代码里的 dev 默认值，必须换成生产密钥
+  - fruitshorts.media.signature-secret（环境变量 MEDIA_SIGNATURE_SECRET） 仍是代码里的 dev 默认值，必须换成生产密钥
+  - fruitshorts.cors.allowed-origins 为空（环境变量 CORS_ALLOWED_ORIGINS）—— 生产不允许用通配 *，必须显式列出来源
+请按 FruitServer/DEPLOY.md 的环境变量清单补齐后重启。
+```
+
+exit code = **1**（部署脚本可以直接判失败）。**没有 prod profile 时这套校验不生效**，本地开发照旧开箱即用。
+
+## 六、发布后验证（每次发版都做）
+
+1. `docker compose ps`：三个应用容器 `Up (healthy)`（worker 是 `Up`）。
+2. `tools/smoke.sh`：全 PASS、退出码 0。它检查 `/healthz`、`/app/categories`、`/app/home/feed`、
+   两个 `/v3/api-docs`、`/doc.html`，以及未授权路径是否按统一信封拒绝。
+   **关于在线文档那三项**：脚本会按 `SWAGGER_ENABLED` 自适应 —— `true` 时断言 200；
+   `false` 时打印 **SKIP**（不算失败），因为 `/doc.html` 与 `/v3/api-docs` 都被配置关掉了。
+   没设这个变量时脚本自动探测（"200 且含 openapi"算开，"统一信封 code=404"算关，其它响应→FAIL）。
+   联调环境想强制要求文档在线：`SWAGGER_REQUIRED=true tools/smoke.sh`（不满足直接失败）。
+3. `curl -s http://127.0.0.1:8081/healthz`：（从容器里或宿主机）应返回 `{"code":0,...,"status":"UP"}`。
+4. 业务抽查：`curl -s http://127.0.0.1:8081/app/home/feed | head -c 200`（有内容）；
+   后台 `http://127.0.0.1:8080/doc.html`（**需要 `.env` 里 `SWAGGER_ENABLED=true`**，联调环境请打开）。
+5. 登录一个后台账号，确认能进后台首页（连通数据库与权限体系）。
+
+## 七、回滚
+
+**镜像/代码回滚**
+
+```bash
+# 用上一个版本的 tag（每次发版都打 tag：fruitshorts/app-api:2026-10-16-1）
+docker compose stop app-api admin-api transcode-worker
+docker tag fruitshorts/app-api:2026-10-15-2 fruitshorts/app-api:latest
+docker compose up -d app-api admin-api transcode-worker
+tools/smoke.sh
+```
+
+或用 git 回到上一个 tag 重新 `up -d --build`：
+
+```bash
+git fetch --tags && git checkout <上一个 release tag>
+docker compose up -d --build
+```
+
+**数据库回滚（谨慎）**：schema 脚本是幂等增量（`ADD COLUMN IF NOT EXISTS` 等），**一般不需要回滚表结构**；
+真要回滚数据用备份：`docker compose exec -T db pg_dump -U fruitshorts fruitshorts > backup.sql`。
+**发布前先备份**是硬要求：
+
+```bash
+docker compose exec -T db pg_dump -U "${DB_USER:-fruitshorts}" "${DB_NAME:-fruitshorts}" > backup-$(date +%F-%H%M).sql
+```
+
+**回滚后必须重跑** `tools/smoke.sh`，并确认转码队列状态正常（后台「数据看板 → 转码看板」）。
+
+## 八、未在本机验证的部分（如实说明）
+
+本机**没有 Docker / colima / podman**（`docker` 命令不存在），所以：
+
+- `Dockerfile`、`.dockerignore`、`docker-compose.yml` **未经本机构建与运行验证**（只做了语法与配置项静态检查）。
+- 本机真实验证过的是：**裸 jar 路径**（两个入口 + worker 起停、`/healthz`、冒烟脚本）、
+  **prod fail-fast**（缺密钥时退出码 1 + 明确报错）、配置外置（`DB_URL` 等改动后仍能起）。
+- 目标主机上有 Docker 之后，请**先跑 §三 的 1)–4) 步**确认；如报错把 `docker compose logs` 贴回来。
+
+## 八之二、上线前必须补的（治理类，详见 DEPLOY-CHECKLIST.md）
+
+以下四条**不是**"部署命令"层面的问题，但 `docs/12-上线检查清单` 把它们列为上线条件，此处给出醒目提示：
+
+1. **HTTPS + 独立域名 + 反向代理**（管理端/客户端 API/媒资分域名，`04-部署架构`§四 + `10-安全方案`§二）—— 现在只有 IP:HTTP；
+2. **备份恢复**：specs 要求每日全量×30 天 + WAL 归档 + 加密 + 异地 + **RPO≤5min / RTO≤30min** + 季度演练，
+   现在只有手动 `pg_dump`，且**备份与数据库在同一台机器上**（等于没备份）；
+3. **监控告警**：Prometheus/Grafana/Loki 未部署；第一阶段按 specs 允许用日志兜底，但"容器 unhealthy 要能通知到人"；
+4. **商店与合规**：隐私政策/Data Safety/SDK 清单/版权台账/包名统一，均未办（印尼还涉及 Kominfo PSE 注册）。
+
+**逐条状态与"上线前必补清单（按优先级）"见 [DEPLOY-CHECKLIST.md](./DEPLOY-CHECKLIST.md)。**
+
+## 九、故障速查
+
+| 现象 | 先看 | 处理 |
+| --- | --- | --- |
+| 容器起不来，日志有"生产配置校验未通过" | §五 | 补 `.env` 里对应变量；密钥用 `openssl rand -base64 48` |
+| `/healthz` 超时（不是快速 404/200） | 是不是刚重新打包没重启？ | 重启进程（§四 的注意事项） |
+| `app-api` healthy 但 `/app/*` 报连库失败 | `docker compose logs db` | 确认 `DB_URL` 指向 `db:5432`，`DB_PASSWORD` 与 db 容器一致 |
+| 转码任务一直 `QUEUED` | worker 日志 | 确认 `transcode-worker` 在跑、`MEDIA_ROOT_DIR` 与 API 相同、镜像里装了 ffmpeg |
+
+## 十、本地开发（不上 Docker）
+
+```bash
+mvn -pl fruitshorts-app-api,fruitshorts-admin-api -am package -DskipTests
+java -jar fruitshorts-app-api/target/fruitshorts-app-api-1.0.0-SNAPSHOT.jar     # 不带 prod profile，开箱即用
+tools/smoke.sh                                                                  # 本机一键冒烟
+```

Dockerfile

@@ -0,0 +1,72 @@
+# Author: fruit.com.cn
+#
+# 多阶段构建：maven 构建 fat jar -> JRE 运行（非 root、tini 做 1 号进程）。
+# 三个可运行件共用一份 Dockerfile，用 MODULE 构建参数区分。
+#
+# 构建（在 FruitServer 目录下执行）：
+#   docker build -t fruitshorts/app-api:latest          --build-arg MODULE=fruitshorts-app-api .
+#   docker build -t fruitshorts/admin-api:latest        --build-arg MODULE=fruitshorts-admin-api .
+#   docker build -t fruitshorts/transcode-worker:latest --build-arg MODULE=fruitshorts-transcode-worker \
+#     --build-arg INSTALL_FFMPEG=true .
+#
+# 注意：本机当前没有 Docker（见 DEPLOY.md），这份 Dockerfile 未经本机构建验证。
+
+# ---------- 1. 构建阶段 ----------
+FROM maven:3.9-eclipse-temurin-21 AS build
+WORKDIR /build
+
+# 先只拷各模块 pom 再拉依赖：依赖层可复用，改业务代码不会重新下载依赖
+COPY pom.xml .
+COPY fruitshorts-common/pom.xml fruitshorts-common/
+COPY fruitshorts-framework/pom.xml fruitshorts-framework/
+COPY fruitshorts-module-system/pom.xml fruitshorts-module-system/
+COPY fruitshorts-module-content/pom.xml fruitshorts-module-content/
+COPY fruitshorts-module-media/pom.xml fruitshorts-module-media/
+COPY fruitshorts-module-user/pom.xml fruitshorts-module-user/
+COPY fruitshorts-module-playback/pom.xml fruitshorts-module-playback/
+COPY fruitshorts-module-interaction/pom.xml fruitshorts-module-interaction/
+COPY fruitshorts-module-commerce/pom.xml fruitshorts-module-commerce/
+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
+
+COPY . .
+ARG MODULE=fruitshorts-app-api
+RUN mvn -B -DskipTests -pl ${MODULE} -am package \
+    && cp ${MODULE}/target/*.jar /build/app.jar
+
+# ---------- 2. 运行阶段 ----------
+FROM eclipse-temurin:21-jre
+
+# ffmpeg 只有转码 worker 需要，用构建参数控制，避免把 80MB 装进两个 API 镜像
+ARG INSTALL_FFMPEG=false
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends tini curl \
+    && if [ "$INSTALL_FFMPEG" = "true" ]; then \
+         apt-get install -y --no-install-recommends ffmpeg; \
+       fi \
+    && rm -rf /var/lib/apt/lists/*
+
+# 非 root 运行；/data/uploads 预留给媒资挂载卷
+RUN groupadd -r fruitshorts \
+    && useradd -r -g fruitshorts -d /app -s /sbin/nologin fruitshorts \
+    && mkdir -p /app /data/uploads \
+    && chown -R fruitshorts:fruitshorts /app /data/uploads
+
+WORKDIR /app
+COPY --from=build --chown=fruitshorts:fruitshorts /build/app.jar /app/app.jar
+
+USER fruitshorts
+
+ENV JAVA_OPTS="-XX:MaxRAMPercentage=75 -XX:+UseG1GC -Duser.timezone=Asia/Shanghai" \
+    SPRING_PROFILES_ACTIVE=prod \
+    MEDIA_ROOT_DIR=/data/uploads
+
+# 健康检查打 /healthz（不依赖 actuator，见 HealthController）
+HEALTHCHECK --interval=30s --timeout=5s --start-period=40s --retries=3 \
+    CMD curl -fsS http://127.0.0.1:${SERVER_PORT:-8080}/healthz || exit 1
+
+ENTRYPOINT ["/usr/bin/tini", "--"]
+CMD ["sh", "-c", "exec java $JAVA_OPTS -jar /app/app.jar"]

README.md

@@ -7,7 +7,7 @@
 | --- | --- |
 | [docs/prd-phase1.md](docs/prd-phase1.md) | 第一阶段 PRD：范围、验收口径、里程碑 |
 | [docs/backend-design-phase1.md](docs/backend-design-phase1.md) | 后端设计：1 万并发观看的容量推导、成本、部署 |
-| [docs/api-phase1.md](docs/api-phase1.md) | **接口清单：后台管理 + 客户端，标注已实现 / 下一批** |
+| [docs/api-phase1.md](docs/api-phase1.md) | **接口契约：后台管理 + 客户端；文末含「契约与实现状态对照」（逐模块标注已实现 / 未完成）** |
 | [docs/architecture-design.md](docs/architecture-design.md) | 早期架构设计文档 |
 
 | 项 | 版本 |
@@ -44,6 +44,7 @@ FruitServer/
 | JDK | OpenJDK 21.0.12.1 | `brew install openjdk@21`，`JAVA_HOME` 已写入 `~/.zshrc` |
 | Maven | 3.10.0 | `brew install maven`，命令为 `/opt/homebrew/bin/mvn` |
 | PostgreSQL | 18.6 | `brew install postgresql@18`，`brew services start postgresql@18` 启动 |
+| ffmpeg | 9.0.2（Homebrew 当前稳定版） | `brew install ffmpeg`；**只有转码 worker 需要**，两个在线入口（8080/8081）不依赖它 |
 
 > `postgresql@18` 是 keg-only，命令行工具在 `/opt/homebrew/opt/postgresql@18/bin`，
 > 用之前把它加到 PATH：`export PATH="/opt/homebrew/opt/postgresql@18/bin:$PATH"`。
@@ -51,8 +52,13 @@ FruitServer/
 ```sh
 java -version   # openjdk 21.0.12.1
 mvn -v          # Maven 3.10.0 / Java 21.0.12.1
+ffmpeg -version # 转码 worker 用；没装也能跑在线服务，只是转码任务会一直排队
 ```
 
+> **ffmpeg 只被 `fruitshorts-transcode-worker` 使用**：`backend-design-phase1.md` §8.5 要求转码与在线服务隔离，
+> 所以 app-api / admin-api 里 `fruitshorts.media.transcode.worker-enabled` 默认 false，转码要单独起 worker 进程
+> （`java -jar fruitshorts-transcode-worker/target/fruitshorts-transcode-worker-1.0.0-SNAPSHOT.jar`）。
+
 说明：
 
 - 工程编译目标为 Java 17（`maven.compiler.release=17`），在 JDK 21 上构建与运行。
@@ -185,18 +191,43 @@ java -jar fruitshorts-app-api/target/fruitshorts-app-api-1.0.0-SNAPSHOT.jar
 
 ## 第一阶段实现进度
 
+> 最后更新：2026-10-16（后端 `develop` 分支 `4418a84`）。**未完成清单见文末「尚未完成」。**
+
 | 模块 | 状态 | 说明 |
 | --- | --- | --- |
-| 01 基础与交付准备 | 已实现 | 多模块骨架、接口契约、双密钥鉴权、分区维护 |
+| 01 基础与交付准备 | 已实现 | 多模块骨架、接口契约、双密钥鉴权、分区维护；**雪花主键（S0）**、**Swagger 在线文档 `/doc.html`（S1）** |
 | 02 用户账号与登录 | 已实现 | 手机号/邮箱注册登录、验证码反刷、令牌轮换、资料、注销、封禁即时生效 |
-| 03 内容发现与详情 | 已实现 | 首页/发现/分类/详情；补内容分级、可播区域、版权窗口、标签字段 |
-| 04 播放器与播放控制 | 部分 | 播放票据 + 签名地址 + 进度已实现；多码率片源待转码 worker |
-| 05 记录、收藏与下载 | 部分 | 进度、观看流水、收藏已实现；离线下载授权待做 |
-| 06 评论、点赞与分享 | 待做 | 表已建，接口与实现待补 |
-| 07 创作者中心 | 待做 | 表已建；转码任务与多码率产物记账已实现 |
-| 08 平台运营后台 | 部分 | App 用户管理已实现；内容治理、订单、看板待做 |
-| 09 分集收费与支付 | 待做 | 表已建；播放入口的权益判定端口已预留，接上即生效 |
-| 10 质量、数据与上线 | 待做 | 压测、埋点、对账待做 |
+| 03 内容发现与详情 | 已实现 | 首页/发现/分类/详情；内容分级、可播区域、版权窗口、标签字段 |
+| 04 播放器与播放控制 | 已实现 | 播放票据 + 签名地址 + 进度；多码率 HLS 由转码 worker 产出（见 10） |
+| 05 记录、收藏与下载 | 已实现 | 进度、观看流水、收藏、离线下载授权与任务 |
+| 06 评论、点赞与分享 | 已实现 | 评论（游标翻页/审核/删除）、点赞、举报、敏感词；**分享埋点待 C3** |
+| 07 创作者中心 | 已实现 | **在后台管理（Web 端 `ReelShortWeb`）**：工作台、内容编辑、分片上传与断点续传、提交审核与上下架、分集收费与试看、数据看板；不含提现/结算。**App 客户端不提供创作者中心**（口径 2026-10-16） |
+| 08 平台运营后台 | 已实现 | 用户管理、内容治理、订单与权益、创作者与内容审核、数据看板 + 四个后台页面 |
+| 09 分集收费与支付 | 部分 | **Google Play 票据校验闭环已实现**（校验→建单→发权益、幂等与防重放、恢复购买、退款拒付回收、对账）；**Apple IAP 只留端口未实现**（印尼 iOS 占比低，文档口径为"预留"） |
+| 10 质量、数据与上线 | 部分 | **转码 worker（C1）已实现**；**Redis 缓存与限流（C2）、埋点（C3）、压测未做** |
+
+### 已完成批次（按提交顺序）
+
+| 批次 | 内容 | 提交 |
+| --- | --- | --- |
+| S0 | 主键改雪花（58 表 / 52 实体 / 存量库幂等迁移脚本） | `37c9a14` `84aa0e1` |
+| S1 | 接口文档在线化（39 个 Controller / 172 个接口中文注解 + `/doc.html`） | `c6fcfcc` |
+| 契约补遗 | 补全接口契约遗漏（系统管理 / 内容 / watch-history / creators 账号 / media 详情） | `efe8af6` |
+| M2 | 后端契约测试补齐（**0 → 37 条**） | `fafadfc` |
+| B1-1 | Google Play 票据校验闭环（校验→建单→发权益） | `db897d5` |
+| B1-2 | 恢复购买 / 退款拒付回收 / 对账真实比对 + Apple 端口预留 | `1dc97b4` |
+| C1 | 转码 worker（独立进程消费 `transcode_task`，四档 HLS + 封面） | `9f76302` |
+| D1 | 部署就绪（配置外置 + prod fail-fast + 自包含 Compose + 冒烟/回滚） | `b567365` |
+| D1-fix | 冒烟脚本与 prod Swagger 开关解耦 | `cbb9961` |
+| D2 | 部署文档按 specs 约束补全（新增 `DEPLOY-CHECKLIST.md`） | `7dd4b15` |
+| 部署修复 | PG18 数据卷挂载路径 + worker 的 prod 密钥/CORS 映射（PR #1） | `8b46e53` `4c4f643` |
+| E1 | 补 5 个 C 端接口（`/app/creator/apply`、`/app/config`、`/app/notices`） | `14b5e41` |
+| 契约修正 | 移除 `/app/creator/works`、`/app/creator/stats` 的 C 端定义 | `bb21920` |
+| E1-rollback | 撤除上述两条接口对应代码（创作者中心归 Web 端） | `4418a84` |
+
+**门禁现状**：`mvn test` **91 条全过**（app-api 49 / commerce 27 / worker 12 / admin-api 3）。
+
+> 客户端仓库 `ReelShort`（Flutter）另有已完成批次：网络层换 `dio`（`1853e18`）、客户端改名 `nontonki → FruitShorts` + 印尼语 `id-ID` 文案（`61454e3`）。
 
 ## 默认账号
 
@@ -393,15 +424,54 @@ public Result<Long> create(@Valid @RequestBody DramaCategorySaveReqVO req) { ...
 6. 表格状态列改用接口返回的 `status` / `statusText`，
    大数值用 `src/utils/format.js` 的 `formatCount` 格式化。
 
-## 尚未实现
+## 尚未完成
 
-评论点赞分享、订单与钱包权益（IAP / Google Play Billing 票据校验、对账、退款回收）、
-创作者中心、内容治理与经营看板、转码 worker（消费 `transcode_task`，产出多码率 HLS）、
-Redis 缓存与限流、离线下载授权、埋点与数据看板。
+> 最后更新：2026-10-16。完成后请同步本表与 [docs/api-phase1.md](docs/api-phase1.md)。
 
-这些模块的表结构、接口契约、状态机与权限点都已经冻结，见
-[docs/api-phase1.md](docs/api-phase1.md) 里标注「下一批」的部分 —— 接下来是照契约填代码，
-不会再有结构性改动。
+### 一、后端研发（剩余）
+
+| # | 项 | 内容 | 依据 |
+| --- | --- | --- | --- |
+| 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 待确认 |
+
+### 二、上线前必补（P0 / Go-No-Go：非研发，但阻塞上线）
+
+| # | 项 | 当前状态 | 目标 |
+| --- | --- | --- | --- |
+| 1 | 生产密钥集中托管 + 轮换 | 仅 `.env`（权限 600），无托管、无轮换流程 | 密钥集中托管、最小权限、可轮换（`10-安全方案` §五） |
+| 2 | 安全专项测试 | 未做 | 越权/注入/敏感数据专项，高危上线前清零（`12-上线检查清单` §三） |
+| 3 | 备份与恢复演练 | 仅手动 `pg_dump`，且与数据库**同机** | **RPO ≤ 5min / RTO ≤ 30min**；全量 + WAL 归档 + 加密 + 异地 + 季度演练（`08-备份恢复`） |
+| 4 | 监控告警接入 | 未部署，仅日志 + `SlowRequestLogger` 兜底 | Prometheus / Grafana / Loki + P0/P1 告警规则（`07-监控告警`；**需先加 actuator 指标端点**） |
+| 5 | HTTPS + 域名 + 反代 | 无 | 管理端 / 客户端 API / 媒资**分别域名**，HTTPS 强制（`04-部署架构` §四、`10-安全方案` §二） |
+| 6 | 媒资迁 OSS/S3 + CDN | 本地磁盘 `./data/uploads` | 生产必须换 OSS/S3 + CDN（`08-备份恢复` §六、`12-上线检查清单` §四） |
+
+### 三、基础设施
+
+- **CI/CD 流水线**：当前手动跑门禁，未接流水线（`06-CI-CD方案`）
+- **多实例 / 高可用**：当前单点部署；文档要求应用 `8C16G × 3~4`、转码 worker `8C16G × 2~3`，生产用 K8s（`14-生产资源规划`）
+- **短信 / 邮件真实通道**：开发走 log，生产待接通道（`05-中间件清单`）
+- **分区保留策略**：`partition.retention-enabled=false`，待合规确认后打开（`03-数据架构`）
+- **`watch_history` 异步落库**：Kafka 异步通道为 Phase 2 预留（`13-容量与扩展规划` §四）
+- 备份存储位置与成本待定（`08-备份恢复` §六）
+
+### 四、不在后端范围（另有分工）
+
+- **客户端 Flutter（`ReelShort`）**：A2~A6 与后端联调、B2 Google Play Billing 购买流程、秒开基线（需低端安卓设备）；网络层 `dio`、改名与印尼语文案已完成
+- **Web 后台（`ReelShortWeb`）**：由另一位同事侧负责
+
+### 五、文档待同步（供文档维护人）
+
+`docs/api-phase1.md` 与 specs `docs/` 下仍有 20+ 处**过期陈述**（例：`api-phase1` §3 仍把 09 支付标"下一批"；specs `17-风险评估` 的 R-01/R-03/R-04/R-09 仍标"未开始"）。
+**遇到冲突以本表与本仓库 `api-phase1.md` 正文为准。**
+
+> **已作废的方案**：曾提议新建 `fruitshorts-module-analytics` 收敛"两份创作者看板"。
+> 因 2026-10-16 口径变更（**创作者中心由 Web 端承载**）撤除了 App 侧 `/app/creator/works`、`/app/creator/stats`，
+> **两份看板问题已从根上消失，该方案不再需要**。
 
 ## 常见问题
 

docker-compose.yml

@@ -0,0 +1,148 @@
+# Author: fruit.com.cn
+#
+# 办公室单机部署（docs/04-部署架构.md §三 精简方案 + §五 第一阶段用 Compose）：
+#   app-api(8081) + admin-api(8080，只绑本机) + transcode-worker + PostgreSQL 18 + Redis
+#   转码 worker 与在线服务**同机但独立进程/容器**（§8.5 隔离要求：不抢在线服务资源）。
+#
+# 用法（目标主机需要 Docker + Compose）：
+#   cp .env.example .env    # 填密钥与数据库密码
+#   docker compose up -d --build
+#   tools/smoke.sh
+#
+# 本文件在本机**未验证**（本机没有 Docker），见 DEPLOY.md「未在本机验证的部分」。
+services:
+
+  # ─────────── 基础设施 ───────────
+  db:
+    image: postgres:18-alpine
+    container_name: fruitshorts-db
+    restart: unless-stopped
+    environment:
+      POSTGRES_DB: ${DB_NAME:-fruitshorts}
+      POSTGRES_USER: ${DB_USER:-fruitshorts}
+      POSTGRES_PASSWORD: ${DB_PASSWORD:?数据库密码必填，见 .env.example}
+      # 中文与印尼语内容需要 UTF-8（镜像默认已是 UTF8，这里显式一次）
+      POSTGRES_INITDB_ARGS: "--encoding=UTF8 --locale=C"
+    volumes:
+      # PostgreSQL 18 起镜像把数据放在 /var/lib/postgresql/<major>/，卷必须挂到父目录
+      - db-data:/var/lib/postgresql
+      # 首次启动自动建表 + 造种子数据；顺序即文件名顺序（脚本本身幂等，可重复执行）
+      - ./sql/schema.sql:/docker-entrypoint-initdb.d/01-schema.sql:ro
+      - ./sql/schema-phase1.sql:/docker-entrypoint-initdb.d/02-schema-phase1.sql:ro
+      - ./sql/partition-maintenance.sql:/docker-entrypoint-initdb.d/03-partition-maintenance.sql:ro
+      - ./sql/data.sql:/docker-entrypoint-initdb.d/04-data.sql:ro
+      - ./sql/data-phase1.sql:/docker-entrypoint-initdb.d/05-data-phase1.sql:ro
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${DB_USER:-fruitshorts} -d ${DB_NAME:-fruitshorts}"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+      start_period: 20s
+    # 不映射端口：只有同网络的容器需要访问；本机要连库时再放开 5432
+    expose:
+      - "5432"
+
+  redis:
+    # 第一阶段还没有代码依赖 Redis（C2 才接缓存与限流），先把基础设施就位，
+    # 免得上线时再改编排。要持久化就留 volume，纯缓存场景可去掉。
+    image: redis:7-alpine
+    container_name: fruitshorts-redis
+    restart: unless-stopped
+    command: ["redis-server", "--appendonly", "yes"]
+    volumes:
+      - redis-data:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      timeout: 3s
+      retries: 10
+    expose:
+      - "6379"
+
+  # ─────────── 应用 ───────────
+  app-api:
+    build:
+      context: .
+      args:
+        MODULE: fruitshorts-app-api
+    image: fruitshorts/app-api:latest
+    container_name: fruitshorts-app-api
+    restart: unless-stopped
+    env_file: .env
+    environment:
+      SERVER_PORT: "8081"
+      # 默认连编排里的 db；要连外部库就在 .env 里覆盖 DB_URL
+      DB_URL: ${DB_URL:-jdbc:postgresql://db:5432/${DB_NAME:-fruitshorts}}
+    ports:
+      - "8081:8081"
+    volumes:
+      # 媒资落盘：三个服务共享同一个卷
+      - ./data/uploads:/data/uploads
+    depends_on:
+      db:
+        condition: service_healthy
+    healthcheck:
+      test: ["CMD-SHELL", "curl -fsS http://127.0.0.1:8081/healthz || exit 1"]
+      interval: 30s
+      timeout: 5s
+      start_period: 40s
+      retries: 3
+
+  admin-api:
+    build:
+      context: .
+      args:
+        MODULE: fruitshorts-admin-api
+    image: fruitshorts/admin-api:latest
+    container_name: fruitshorts-admin-api
+    restart: unless-stopped
+    env_file: .env
+    environment:
+      SERVER_PORT: "8080"
+      DB_URL: ${DB_URL:-jdbc:postgresql://db:5432/${DB_NAME:-fruitshorts}}
+    ports:
+      # docs/12-上线检查清单「管理端仅内网」：只绑本机，公网不直接暴露
+      - "127.0.0.1:8080:8080"
+    volumes:
+      - ./data/uploads:/data/uploads
+    depends_on:
+      db:
+        condition: service_healthy
+    healthcheck:
+      test: ["CMD-SHELL", "curl -fsS http://127.0.0.1:8080/healthz || exit 1"]
+      interval: 30s
+      timeout: 5s
+      start_period: 40s
+      retries: 3
+
+  transcode-worker:
+    build:
+      context: .
+      args:
+        MODULE: fruitshorts-transcode-worker
+        # worker 镜像里装 ffmpeg，两个 API 镜像不装（省 80MB）
+        INSTALL_FFMPEG: "true"
+    image: fruitshorts/transcode-worker:latest
+    container_name: fruitshorts-transcode-worker
+    restart: unless-stopped
+    env_file: .env
+    environment:
+      DB_URL: ${DB_URL:-jdbc:postgresql://db:5432/${DB_NAME:-fruitshorts}}
+    volumes:
+      # 与两个入口同一个媒资根，否则找不到源文件
+      - ./data/uploads:/data/uploads
+    depends_on:
+      db:
+        condition: service_healthy
+    healthcheck:
+      # worker 不监听端口（server.port=0），用进程存活判断
+      test: ["CMD-SHELL", "pgrep -f app.jar >/dev/null || exit 1"]
+      interval: 60s
+      timeout: 5s
+      start_period: 40s
+      retries: 3
+
+volumes:
+  # 命名卷：跟着 compose 项目走，`docker compose down -v` 才会删
+  db-data:
+  redis-data:

docs/api-phase1.md

@@ -16,6 +16,29 @@
 
 `code = 0` 成功；非 0 时 `message` 可直接展示给用户。分页统一为 `{ total, list }`。
 
+**ID 字段一律以字符串下发（2026-10-16 J1 起，全局生效）**
+
+所有 ID 字段（主键与外键，例如 `id` / `dramaId` / `episodeId` / `userId` / `orderId` …）
+在 JSON 里都是**字符串**，不是数字：
+
+```json
+{ "code": 0, "message": "ok", "data": { "id": "2111012753262120962", "dramaId": "5" } }
+```
+
+原因：S0 之后主键是雪花 id，19 位十进制数已超过 JS 的 `Number.MAX_SAFE_INTEGER`
+（`9007199254740991`）。裸数字下发会被浏览器/IEEE754 客户端四舍五入
+（实测库里的 `2111012753262120962` 在浏览器里变成 `2111012753262121000`），
+页面再拿它回查就是 `200002 数据不存在`。
+
+约定与边界：
+
+- **id 回传时按字符串传**（路径变量 / 查询参数 / 请求体都接受字符串，服务端自己转 `Long`）；
+- 实现方式：服务端**全局**把 `Long` / `long` 序列化成字符串（`fruitshorts-framework` 的
+  `JacksonLongToStringConfig`），**各模块不再逐字段加注解**；
+- **例外：分页 `total` 仍是数字** —— 它是条数不是 id，前端分页组件要数字；
+  `Integer` / `int` 字段（`pageIndex` / `pageSize` / 各类计数如 `totalEpisodes`、状态码 `code`）
+  也**保持数字**。
+
 **鉴权**：`Authorization: Bearer <token>`。
 管理端与客户端用**两套独立密钥**签发，管理端 token 打到客户端接口会直接被拒。
 客户端 `access token` 默认 2 小时，`refresh token` 30 天且每次刷新轮换。
@@ -74,6 +97,44 @@ POST /app/auth/register
 }
 ```
 
+**邮箱 + 密码注册（C 端第一批口径）**
+
+```json
+POST /app/auth/register
+{
+  "targetType": "EMAIL", "target": "User@Example.com ", "password": "nonton2026",
+  "deviceId": "d-1", "countryCode": "ID", "agreementVersion": "2026-10-01"
+}
+```
+
+| 规则 | 口径 |
+| --- | --- |
+| `targetType=EMAIL` | **`code` 可以不传**（邮箱+密码直接注册）；传了就走一次验证码校验（邮箱验证能力保留） |
+| `targetType=PHONE` | 维持原状：`code` **必填** |
+| 邮箱规范化 | 去空格 + 转小写（`batch1@Example.com ` → `batch1@example.com`）；格式不合法直接 `400 邮箱格式不正确` |
+| 密码强度 | 8–64 位，且**同时包含字母与数字**（不强制特殊字符：低端机输入成本高，拦机器注册靠频控） |
+| 注册频控 | 同 IP / 同设备 24h 默认上限分别为 5 / 3 个，超出返回 `429`（`TOO_MANY_REQUESTS`） |
+| 邮箱验证状态 | 免码注册时 `app_user_credential.verified = 0`（保留"待验证"），**不阻塞登录**；只有**验证码登录**会把 `verified` 置 1，密码登录不改变该状态 |
+
+频控口径落库在 `app_user.register_ip` / `app_user.register_device_id` 上（按 24h 计数，不新建计数表）。
+
+注册频控阈值存储在 `sys_config`，可在后台「系统配置」修改：
+
+```text
+app.register.max-per-ip-per-day
+app.register.max-per-device-per-day
+```
+
+运行时优先读取 `sys_config`。键缺失或值不是整数时，回退 `application.yml`
+中的 `fruitshorts.auth.register-max-per-ip-per-day` /
+`fruitshorts.auth.register-max-per-device-per-day`，缺省为 5 / 3；
+值小于等于 0 表示对应维度不限制。
+开发种子配置为 0 / 0，生产建议恢复为 5 / 3。
+
+**残留风险**：IP 取自 `X-Forwarded-For`、设备号由客户端上报，都能伪造，只能挡脚本批量；
+真要防住需要接图形/行为验证码或风控服务，本阶段未做。验证码通道目前是 `LogOtpSender`（只写日志不发信），
+所以邮箱**可达性**未验证 —— 这也是"不阻塞注册"的前提。
+
 响应（登录、刷新同结构）：
 
 ```json
@@ -197,23 +258,146 @@ POST /app/auth/register
 | GET | `/app/wallet` | 金币余额 + 最近流水 |
 | POST | `/app/episodes/{id}/unlock` | 金币解锁分集；幂等键 `unlock:{userId}:{episodeId}`，重复调用不重复扣币 |
 | GET | `/app/orders` | 我的订单 |
-| POST | `/app/orders/verify` | 提交 IAP / Google Play 票据。**本轮只留端口不接商店**，会返回 `200003 尚未配置` |
+| POST | `/app/orders/verify` | 提交 Google Play 票据：服务端校验 → 建单 → 发权益（详见下方说明） |
 
 解锁后播放入口与下载入口会同时放行 —— 权益判定由交易模块的 `EntitlementPort` 实现提供，
 播放域与下载域都不需要改代码。金币变动一律带幂等键并写 `coin_ledger`，钱包余额与流水同事务。
 
-### 1.9 创作者（下一批）
+**`POST /app/orders/verify`（B1-1：Google Play 票据校验闭环）**
 
-| 方法 | 路径 | 说明 |
+请求体：
+
+```json
+{ "platform": "GOOGLE_PLAY", "productId": "coin_550", "receipt": "<purchaseToken>" }
+```
+
+| 字段 | 说明 |
+| --- | --- |
+| `platform` | `GOOGLE` / `GOOGLE_PLAY`（两者等价，入库统一记 `GOOGLE`）；Apple 走 B1-2 |
+| `productId` | 商店商品 id（Google Play 的 `purchases.products.get` 必需），与本平台 `product.store_product_id` 对得上才发权益 |
+| `receipt` | Google Play 的 `purchaseToken` |
+
+行为与错误码：
+
+| 场景 | 返回 |
+| --- | --- |
+| 校验通过 | `code=0`，`data` 是订单（`status=DELIVERED`、`coinAmount`=商品金币+赠送、`storeTransactionId`=Google `orderId`） |
+| 同一票据**重复**提交（同用户） | `code=0` 返回**既有订单**，不重复发币、不重复建单 |
+| 票据已绑定**其他账号** | `403 该票据已绑定其他账号，不能重复使用`（防跨用户重放） |
+| 票据无效 / 未购买 / 商品不一致 / 缺 orderId | `200003` + 具体原因；**不产生订单、不发权益** |
+| 商品未在后台配置 | `200002 该商品未在后台配置` |
+| 平台不在支持范围 | `400 不支持的商店平台` |
+| 商店未配置（默认 `verifier=disabled`） | `200003 Apple / Google 商店校验尚未配置`（与 B1-1 之前的行为一致） |
+
+幂等键是 `(platform, store_transaction_id)`（DB 唯一索引 `uk_orders_store_txn`），
+重复/并发提交由数据库兜底；票据审计写 `store_receipt`（唯一索引 `uk_store_receipt(platform, transaction_id)`），
+B1-2 的退款/拒付复验依赖它。服务端凭据（`packageName` + service account JSON）走配置/环境变量，不入库。
+
+**恢复购买**：客户端换设备后重新提交同一个 `purchaseToken`（或调用 `GET /app/orders` 拉已购列表），
+服务端按 `(platform, storeTransactionId)` 识别"权益已发过"，**返回既有订单、不重复发币**；
+若商店侧有购买而本地没有订单（例如换机前没同步），会**按校验结果补单落库**再发放，不需要人工介入。
+
+### 1.9 创作者入驻、启动配置与公告（C 端，已实现）
+
+> 说明 1：本节原来把 `/app/orders`、`/app/wallet`、`/app/episodes/{id}/unlock` 也列在这里，
+> 那三条**属「金币与订单」，已在 §1.8 实现并冻结**，因此已从本节移出。
+>
+> 说明 2（**口径变更 2026-10-16**）：**创作者中心（工作台 / 作品管理 / 数据看板）由 Web 端承载** ——
+> 创作者登录后台管理使用，见 §2.10；**App 客户端不提供创作者中心**。
+> 因此本节**已移除** `GET /app/creator/works`、`GET /app/creator/stats` 两条原定义。
+> C 端只保留「入驻申请」+「启动配置」+「系统公告」，下面三条即全部。
+
+| 方法 | 路径 | 鉴权 | 说明 |
+| --- | --- | --- | --- |
+| POST | `/app/creator/apply` | 登录 | 创作者入驻申请（**幂等**：重复提交返回当前状态，不重复建档） |
+| GET | `/app/config` | **匿名** | 启动配置（协议版本、最低版本、开关；**只下发白名单键**） |
+| GET | `/app/notices` | **匿名** | 系统公告（无数据返回空列表，不是 404） |
+
+#### 1.9.1 `GET /app/config`（匿名）
+
+客户端**登录前**就要拿，用于：协议版本校验、强制更新判断、功能开关。
+
+```json
+{
+  "code": 0, "message": "ok",
+  "data": {
+    "agreementVersion": "2026-10-01",
+    "minAppVersion": "1.0.0",
+    "forceUpdate": false,
+    "noticeEnabled": true,
+    "coinUnlockEnabled": true,
+    "downloadEnabled": true
+  }
+}
+```
+
+| 键（对客户端字段） | 后台配置键 | 契约默认值 | 说明 |
+| --- | --- | --- | --- |
+| `agreementVersion` | `app.agreement.version` | `2026-10-01` | 当前协议版本；`/app/creator/apply` 必须与它一致 |
+| `minAppVersion` | `app.min.version` | `1.0.0` | 低于它客户端应提示升级 |
+| `forceUpdate` | `app.force.update` | `false` | 是否强制更新 |
+| `noticeEnabled` | `app.notice.enabled` | `true` | 公告入口开关 |
+| `coinUnlockEnabled` | `app.coin.unlock.enabled` | `true` | 金币解锁开关 |
+| `downloadEnabled` | `app.download.enabled` | `true` | 离线下载开关 |
+
+**口径**：**只下发上述白名单键**（服务端硬编码白名单），后台配置里的其它键（可能含内部开关）
+**一律不下发**；库里缺键时用「契约默认值」兜底，**不返回 null 让客户端自己猜默认值**。
+
+#### 1.9.2 `GET /app/notices`（匿名）
+
+```
+GET /app/notices?pageIndex=1&pageSize=20
+```
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `pageIndex` | int | 否 | 默认 1 |
+| `pageSize` | int | 否 | 默认 20，最大 50 |
+
+```json
+{
+  "code": 0, "message": "ok",
+  "data": {
+    "total": 1,
+    "list": [
+      { "id": 2110123456789, "title": "开服公告", "content": "…", "type": "SYSTEM",
+        "publishAt": "2026-10-16 10:00:00", "expireAt": null }
+    ]
+  }
+}
+```
+
+**口径**：只返回 `status=1`（启用）且 `target ∈ {ALL, USER}`、`publish_at <= 现在`、
+`expire_at` 为空或未过期的公告；按 `publish_at desc, id desc` 排序。
+**表里没有数据时返回 `total=0, list=[]`（HTTP 与 code 都是成功），不是 404。**
+
+#### 1.9.3 `POST /app/creator/apply`（登录）
+
+```json
+{
+  "name": "星野工作室", "type": "COMPANY",
+  "contactName": "张三", "contactMobile": "08123456789", "contactEmail": "creator@example.com",
+  "countryCode": "ID", "agreementVersion": "2026-10-01"
+}
+```
+
+| 字段 | 必填 | 校验 |
 | --- | --- | --- |
-| GET | `/app/orders` | 我的订单 |
-| GET | `/app/wallet` | 金币余额与流水 |
-| POST | `/app/episodes/{id}/unlock` | 金币解锁分集 |
-| POST | `/app/creator/apply` | 创作者入驻 |
-| GET | `/app/creator/works` | 我的作品与审核状态 |
-| GET | `/app/creator/stats` | 创作者数据看板 |
-| GET | `/app/config` | 启动配置（协议版本、开关、最低版本） |
-| GET | `/app/notices` | 系统公告 |
+| `name` | ✅ | 1–128 字 |
+| `type` | 否 | `INDIVIDUAL`（默认）/ `COMPANY` |
+| `contactName` / `contactMobile` / `contactEmail` | 否 | 只是联系方式，不参与鉴权 |
+| `countryCode` | 否 | 默认 `ID` |
+| `agreementVersion` | ✅ | **必须等于 `/app/config` 的 `agreementVersion`**，否则 `400` |
+
+**幂等口径（硬要求）**：以「**C 端账号唯一**」防重（DB 唯一索引 `uk_creator_user(user_id) where user_id > 0`）：
+
+| 情况 | 行为 |
+| --- | --- |
+| 首次申请 | 建档，`status=pending`，返回 `{id, code, status, statusText, auditNote, appliedAt}` |
+| 已申请（pending） | **返回当前状态**，不重复建档、不改动已有记录 |
+| 已通过（approved） | 返回 `status=approved`（**创作者工作台在 Web 端**，见 §2.10；App 端只提示"已通过，请到创作者后台使用"） |
+| 被驳回 / 冻结 | 返回当前状态与 `auditNote`（是否允许重新申请由运营在后台处理，本期不做二次申请） |
+| 并发重复提交 | 唯一索引兜底：捕获冲突后**读回已有记录返回**，不报 500 |
 
 ## 2. 后台管理接口（/admin/**）
 
@@ -363,6 +547,23 @@ POST /app/auth/register
 | POST | `/admin/wallets/coins` | `wallet:update` | 人工补币/扣回，必须带幂等键，先校验用户存在 |
 | POST | `/admin/reconcile/run` · GET `/admin/reconcile/page` | `reconcile:run` / `order:list` | 手动对账与历史（默认每天 04:20 自动跑前一天） |
 
+**对账口径（B1-2 起生效，字段名不变，新增两个字段）**
+
+| 字段 | 含义 |
+| --- | --- |
+| `totalCount` | 当期本地有效订单数（排除 `CREATED`/`CLOSED`） |
+| `matchedCount` | 其中能在 `store_receipt` 找到同一 `(platform, transaction_id)` 的笔数 |
+| `diffCount` | 差异笔数 = 本地缺票据 + 票据无本地订单 + **商店已作废但本地无单** |
+| `amountSum` | 本地订单金额合计（**本地口径**，不是商店结算口径） |
+| `storeAmountSum` | 商店侧结算金额。Developer API 不提供（要向 Play Console 财务报告取）→ **无数据源时为 `null`** |
+| `notes` | 说明差异构成、本次退款回收情况、以及"缺哪些数据源"。**契约强制：取不到的指标用 `null` + `notes` 说明，不许用 0 冒充** |
+| `status` | 商店侧调用失败时为 `FAILED`（不会写成 `SUCCESS` + 一堆 0） |
+
+`POST /admin/reconcile/run` 同时会**拉取商店已作废交易并回收权益与金币**（退款/拒付回收），
+回收是幂等的：同一笔作废交易重复出现在时间窗里，只回收一次。
+口径细节：Google 一次性商品的作废是**整笔**，拿不到部分金额，因此按整单回收；
+找不到本地订单的作废交易会计入 `diffCount` 并在 `notes` 里点名。
+
 ### 2.7 创作者与内容审核（已实现）
 
 | 方法 | 路径 | 权限点 | 说明 |
@@ -578,17 +779,93 @@ POST /app/auth/register
 | --- | --- | --- | --- |
 | GET | `/admin/creator-center/impersonation/targets` | `creator-center:impersonate` | 代看目标下拉的数据源（id / 名称 / 状态） |
 
+### 2.11 商品（金币包）配置（已实现）
+
+> 背景：`product` 表 16 个字段早就建好，但后台一直没有入口，运营只能改库；而 C 端 `/app/orders/verify`
+> 依赖 `store_product_id` 对齐商店商品（对不上就是 `200002 该商品未在后台配置`）。本节补齐 CRUD。
+> **不改表结构。**
+
+| 方法 | 路径 | 权限点 | 说明 |
+| --- | --- | --- | --- |
+| GET | `/admin/products/page` | `product:list` | 分页检索（`type` / `status` / `platform` / `keyword`，分页沿用 `{total,list}`） |
+| GET | `/admin/products/{id}` | `product:list` | 商品详情 |
+| POST | `/admin/products` | `product:update` | 新建 |
+| PUT | `/admin/products/{id}` | `product:update` | 编辑 |
+| PUT | `/admin/products/{id}/status` | `product:update` | 上架 / 下架（`status`：1 上架、0 下架） |
+| DELETE | `/admin/products/{id}` | `product:update` | 删除（逻辑删除） |
+
+**字段**（与表一致，响应里额外带 `statusText` / `typeText`，前端不再写死中文）：
+
+| 字段 | 说明 |
+| --- | --- |
+| `code` | 商品编码，**全局唯一** |
+| `name` | 展示名 |
+| `type` | `COIN_PACK`（金币包）/ `VIP`（会员，第二阶段） |
+| `platform` | `ALL` / `GOOGLE` / `APPLE` |
+| `storeProductId` | 商店商品 id，**同一 `platform` 下唯一**（空串表示未绑定，允许多个） |
+| `coinAmount` / `bonusCoin` | 金币数与赠送（`type=COIN_PACK` 时 `coinAmount > 0`） |
+| `priceAmount` / `currency` / `displayPrice` | 价格与展示价 |
+| `regionCodes` | 生效区域，逗号分隔，空=全区域 |
+| `vipDays` | 会员天数（`type=VIP` 时 `> 0`） |
+| `sort` / `status` | 排序 / 上下架 |
+| `effectiveAt` / `expireAt` | 生效与失效时间（可空） |
+
+> `id` 以字符串下发：见 **§0「ID 字段一律以字符串下发」**（本节不再单独规定）。
+
+**校验与错误码**：
+
+| 场景 | 结果 |
+| --- | --- |
+| `code` 已存在 | `200001 商品编码已存在：{code}` |
+| `storeProductId` 在同 `platform` 下已存在 | `200001 该平台下商店商品 id 已被占用：{id}` |
+| `type=COIN_PACK` 但 `coinAmount <= 0` | `400 金币包的金币数量必须大于 0` |
+| `type=VIP` 但 `vipDays <= 0` | `400 会员商品的会员天数必须大于 0` |
+| **`type=VIP` 且要启用**（`status=1`） | `400 会员商品在订阅功能上线前不能启用（可先建档，上线后再上下架）` |
+| 商品不存在 | `200002 商品不存在` |
+
+> **VIP 口径（2026-10-16 定，与 B1-1「VIP 订阅本轮不做」一致）**：**允许创建、不允许启用**。
+> 运营可以先录好商品与商店 product id，等 B2 上线后直接上下架；**启用**才是会误导客户端的动作，拦在这里。
+
+### 2.12 系统公告管理（已实现）
+
+> 背景：`ops_notice` 表 0 行、契约原先写着"没有产出方"；E1 已交付 C 端 `GET /app/notices`（匿名只读）。
+> 本节补齐后台写入。**不改表结构。**
+
+| 方法 | 路径 | 权限点 | 说明 |
+| --- | --- | --- | --- |
+| GET | `/admin/notices/page` | `notice:list` | 分页检索（`status` / `target` / `type` / `keyword`） |
+| GET | `/admin/notices/{id}` | `notice:list` | 公告详情 |
+| POST | `/admin/notices` | `notice:update` | 新建 |
+| PUT | `/admin/notices/{id}` | `notice:update` | 编辑 |
+| PUT | `/admin/notices/{id}/status` | `notice:update` | 发布（`status=1`）/ 下架（`status=0`） |
+| DELETE | `/admin/notices/{id}` | `notice:update` | 删除（逻辑删除） |
+
+**字段**：`title` / `content` / `target`（`ALL` / `USER` / `CREATOR`）/ `type`（`SYSTEM` / `AUDIT` / `PAYMENT` / `ACTIVITY`）/
+`status` / `publishAt` / `expireAt`；响应另带 `statusText` / `targetText` / `typeText`。
+
+> `id` 以字符串下发：见 **§0「ID 字段一律以字符串下发」**。
+
+**与 C 端口径严格对齐（同一条查询实现）**：C 端 `GET /app/notices` 只返回
+`status=1` 且 `target ∈ {ALL, USER}`、`publish_at` 为空或 `<= now`、`expire_at` 为空或未过期的公告，
+按 `publish_at desc, id desc` 排序。**后台发布即 C 端可见；下架或过期后 C 端不可见。**
+（实现上收敛在 `OpsNoticeService.pageForApp(...)` 一处，避免两端条件漂移。）
+
+**筛选与错误码**：`title` 必填（1–128）；`content` 最长 2000；公告不存在 → `200002 公告不存在`；
+`status` 只接受 0/1，其他值 → `400`。
+
 ## 3. 契约与实现状态对照
 
+> 最后更新：2026-10-16（`develop` 分支）。未完成项汇总见仓库根 `README.md`「尚未完成」。
+
 | 模块 | 表结构 | 接口 | 代码 |
 | --- | --- | --- | --- |
-| 01 基础与交付准备 | 已就绪 | 约定已冻结 | 脚手架 / 契约 / 签名 / 转码骨架 已实现 |
+| 01 基础与交付准备 | 已就绪 | 约定已冻结 | 脚手架 / 契约 / 签名 / 转码骨架 已实现；**S0 雪花主键**、**S1 Swagger 在线文档** 已完成 |
 | 02 用户账号与登录 | 已建 | 已冻结 | **已实现**（手机号/邮箱，第三方登录走同一凭证表） |
 | 03 内容发现与详情 | 已建 | 已冻结 | 已实现（补了分级、区域、版权、标签字段） |
-| 04 播放器与播放控制 | 已建 | 已冻结 | 票据 + 签名 + 进度 已实现；多码率依赖转码 worker |
+| 04 播放器与播放控制 | 已建 | 已冻结 | **已实现**：票据 + 签名 + 进度；多码率 HLS 由转码 worker（C1）产出 |
 | 05 记录、收藏与下载 | 已建 | 已冻结 | **已实现**：进度、观看流水、收藏、离线下载授权与任务 |
-| 06 评论、点赞与分享 | 已建 | 已冻结 | **已实现**：评论（游标翻页/审核/删除）、点赞、举报、敏感词；分享埋点在下一批 |
-| 07 创作者中心 | 已建 | 已冻结 | **已实现**：创作者工作台（我的作品 / 审核进度 / 通知）、内容编辑与分集管理、分片上传与断点续传、提交审核与上下架、分集收费与试看、数据看板；Web 端页面见 2.10，不含提现 / 结算 |
+| 06 评论、点赞与分享 | 已建 | 已冻结 | **已实现**：评论（游标翻页/审核/删除）、点赞、举报、敏感词；**分享埋点待 C3** |
+| 07 创作者中心 | 已建 | 已冻结 | **已实现**（**在后台管理 Web 端**）：创作者工作台（我的作品 / 审核进度 / 通知）、内容编辑与分集管理、分片上传与断点续传、提交审核与上下架、分集收费与试看、数据看板；Web 端页面见 2.10，不含提现 / 结算。**App 客户端不提供创作者中心**（口径 2026-10-16） |
 | 08 平台运营后台 | 已建 | 已冻结 | **已实现**：后台接口（用户管理、内容治理、订单与权益、创作者与内容审核、数据看板）与后台页面（内容治理 / 订单与权益 / 创作者审核 / 数据看板，见 2.9）全部落地 |
-| 09 分集收费与支付 | 已建 | 已冻结 | 下一批（权益判定端口已预留，接上即生效） |
-| 10 质量、数据与上线 | 已建 | 已冻结 | 压测与埋点 下一批 |
+| 09 分集收费与支付 | 已建 | 已冻结 | **Google Play 票据校验闭环已实现**（校验→建单→发权益、幂等与防重放、恢复购买、退款拒付回收、对账）；**Apple IAP 只留端口未实现**（印尼 iOS 占比低，口径为"预留"） |
+| 10 质量、数据与上线 | 已建 | 已冻结 | **转码 worker（C1）已实现**；**Redis 缓存与限流（C2）、埋点（C3）、压测 未做** |

docs/plans/2026-10-16-I1.md

@@ -0,0 +1,68 @@
+# I1 后台管理端：商品（金币包）配置 + 系统公告管理 —— 计划（2026-10-16）
+
+> 依据：`FruitServer/docs/plans/INBOX.md` 17:30 条目。用户口径「现在做后台管理端，规范还是按照 specs」。
+> **本轮=后端接口 + ReelShortWeb 页面一起做**。指令通道已迁到本仓库（`FruitServer/docs/plans/`），
+> 留痕写 `FruitServer/docs/plans/PROGRESS.md`（本轮新建）；**specs 只读、不再写入**。
+
+## 一、两个缺口（PM 已勘察，直接用）
+
+1. **商品/金币包配置后台无入口**：`product` 表 16 字段已建、3 行种子、C 端 verify 依赖 `store_product_id` 对齐商店商品，但 admin-api 没有任何商品 CRUD。
+2. **公告有读没写**：`ops_notice` 表 0 行，E1 交付了 C 端读，后台没有写入口。
+
+## 二、勘察补充（影响做法，已实测）
+
+1. **前端挂载机制**（与条目描述略有出入，已核实）：`src/utils/routerHelper.ts` 用
+   `import.meta.glob('../views/**/*.{vue,tsx}')` + 后端菜单的 `component` 字符串**动态解析**；
+   `src/router/index.ts` 的 `asyncRouterMap` 只静态声明了 dashboard/content/user/system 等早期分组，
+   commerce/governance/board 这些都没有静态登记。→ 所以新增页面**只需**：① 新建 `.vue`；
+   ② `sql/data-phase1.sql` 里加菜单且 `component` 与视图路径一致。**静态路由不必改**（改了也无害）。
+   真正的坑是 `route_name` 唯一（曾因 `CreatorCenter` 重名导致 404），本轮命名会避开。
+2. **id 保留段**：权限点已用到 1155、菜单已用到 30 → 权限点用 **1160-1163**、菜单用 **31/32/33**。
+3. **前端既有约定**：api 封装在 `src/api/admin/*`（`import request from '@/axios'` + `PageResult`），
+   页面用 `useRbac().can(code)` 控权、`dateCell` 格式化日期、`PageHeading` 标题；金额/金币这类大数值本项目
+   没有 `formatCount`，实际用的是 `src/utils/format.js`，**我会用其中的数值格式化工具或 `toLocaleString`**，
+   并在回执说明（不新造 util）。
+
+## 三、口径决定（需在回执与契约里写清）
+
+**VIP 商品**：**允许创建、不允许启用**（`PUT /{id}/status` 把 `type=VIP` 置为启用 → `400`）。
+理由：运营可以先把 VIP 商品与商店 product id 录好，等 B2 订阅上线后一键启用；直接拒绝创建会让上线日重新补数据。
+B1-1 已定「VIP 订阅本轮不做」，所以**启用**才是会产生误导的动作，拦在这里。
+
+## 四、后端做法
+
+1. **契约先行**：`docs/api-phase1.md` 新增一节（放在 §2.6 订单与权益之后的新编号），写清两个模块的
+   接口、字段、校验、错误码、权限点。
+2. **商品**（module-commerce 加 service/VO，admin-api 加 controller）：
+   `GET /admin/products/page`（type/status/platform/keyword + 分页）、`GET /{id}`、`POST`、`PUT /{id}`、
+   `PUT /{id}/status`、`DELETE /{id}`；字段按表结构；校验：`code` 全局唯一、`store_product_id` 同 `platform` 唯一、
+   `type=COIN → coin_amount>0`、`type=VIP → vip_days>0`、**VIP 不可启用**。响应带 `statusText/typeText`（前端不写死中文）。
+3. **公告**（module-system 加 `OpsNoticeService` + VO，admin-api 加 controller）：
+   `GET /admin/notices/page`、`GET /{id}`、`POST`、`PUT /{id}`、`PUT /{id}/status`、`DELETE /{id}`。
+   **筛选逻辑收敛到 `OpsNoticeService.pageForApp()` 一处**，C 端 `AppNoticeService` 改为委托它
+   （改我自己 E1 写的文件），这样"后台发布 → C 端可见 / 过期或下架 → 不可见"用的是同一段条件，不会漂移。
+4. **菜单与权限点**：`sql/data-phase1.sql` 幂等追加（权限点 1160-1163、菜单 31/32/33 与超管授权）。
+   商品挂「订单与权益」(id 22) 下；公告新建「运营管理」(id 32) 分组 + 子菜单 (33)。
+5. **Swagger**：两个新控制器按 S1 规范加 `@Tag`/`@Operation`，并把分组补进 admin-api 的 `@OpenAPIDefinition`。
+
+## 五、前端做法（ReelShortWeb，develop 分支）
+
+- `src/api/admin/product.ts`、`src/api/admin/notice.ts`（按 `commerce.ts` 的写法）
+- `src/views/commerce/ProductManagementView.vue`（列表/筛选/新建编辑弹窗/上下架/删除）
+- `src/views/operation/NoticeManagementView.vue`（列表/新建编辑/发布下架/删除）
+- `sql/data-phase1.sql` 的菜单 `component` 写 `views/commerce/ProductManagementView`、`views/operation/NoticeManagementView`
+- **不改既有页面**；`route_name` 用 `commerce-products` / `operation-notices`（先 grep 确认不重名）
+
+## 六、门禁
+
+- 后端：`mvn test` 存量 **91 条不得跑红** + 新增测试（商品三类校验、公告可见性委托、
+  两个控制器的接入层契约、权限点注解检查）
+- 前端：`pnpm build:pro` 通过 + eslint 零错误
+- 端到端：后台登录 → 菜单出现两个新页面 → 建商品 → 用该商品在 C 端 `verify` 能对上
+  （`store_product_id` 命中，不再是 `200002 该商品未在后台配置`）；公告发布 → C 端 `/app/notices` 可见 → 下架/过期 → 不可见
+
+## 七、风险 / 待确认
+
+1. **不新增静态路由**是否与条目"两边都要加"冲突：我按实测的加载机制做，若你要求同时静态登记，我再补（不影响正确性）。
+2. `/app/orders/verify` 走真实 Google Play 才有完整链路；本机无商店凭据，端到端验证到"200002 消失、进入校验环节"为止。
+3. 公告"发布时间"语义：`publish_at` 为空视为立即生效（C 端条件里已按"为空或 <= now"处理）。

docs/plans/2026-10-16-J1.md

@@ -0,0 +1,91 @@
+# J1 全局 ID 字符串化（Long → String）+ 契约统一 —— 计划（2026-10-16）
+
+> 依据：`docs/plans/INBOX.md` 18:30 条目。用户裁定：雪花 id 精度问题**按方案 (a) 全局修改、统一契约**。
+> 起因：I1 实测「UI 点下架 → `200002 公告不存在`」，根因是 19 位雪花 id 超出 JS `Number.MAX_SAFE_INTEGER`
+> （9007199254740991），浏览器 `JSON.parse` 会把它四舍五入。
+
+## 一、方案
+
+### 1. 后端：fruitshorts-framework 里注册全局序列化模块
+
+- 新增 `com.fruitshorts.framework.web.JacksonLongToStringConfig`：
+  - `SimpleModule` 把 **`Long.class` 与 `Long.TYPE`（`long`）→ `ToStringSerializer`**；
+  - 通过 `Jackson2ObjectMapperBuilderCustomizer` 挂进 Spring Boot 自动配置的 `ObjectMapper`。
+- 两个入口（admin-api / app-api）都是 `scanBasePackages = "com.fruitshorts"`，framework 在扫描范围内，
+  一处生效即两端生效；**不改任何 yml**。
+- **不动 `Integer` / `int`**：`pageIndex` / `pageSize` / `Result.code` / `quantity` / `durationSec` …
+  仍是数字。
+- **序列化方向**：`Long` 值一律输出成 JSON 字符串（含普通字段、嵌套对象、`List`、`Map` 值、分页 list 元素）。
+- **反序列化方向**：Jackson 默认允许 `"123"` → `Long` 的标量强转，所以**请求体里 id 传字符串可以直接绑定**；
+  路径变量 `/…/{id}` 与查询参数走 Spring 的 `ConversionService`，本来就是 String → Long，不受影响。
+  这两条都要有测试兜住。
+
+### 2. 一个刻意的例外：`PageResult.total` 保持数字
+
+`PageResult.total` 是 `long` 计数，不是 id。放行它会让后台 ~13 处 `el-pagination :total=` 与 C 端分页全部变成
+字符串，收益为零、风险不小。所以给这个字段加 `@JsonSerialize(using = NumberSerializer.class)` 显式保持数字，
+并在契约 §0 里写明「**id 一律字符串；分页 total 是计数，仍是数字**」。
+⚠️ 这是我自己拍的口径，已单独列进回执，若要求"Long 一律字符串"我再把这一行去掉。
+
+### 3. 契约统一（`docs/api-phase1.md`）
+
+- §0 通用约定新增「**所有 ID 字段（主键与外键）一律以字符串下发**」+ 示例 + `total` 例外说明。
+- §2.11 / §2.12（I1 商品/公告）里逐模块写的 "id 以字符串下发" 改成引用 §0。
+- **代码侧**：I1 给 `ProductRespVO` / `NoticeRespVO` 加的 `@JsonSerialize` 与 `Result<String>` 新建返回
+  **回退成自然写法**（全局生效后它们就是冗余的特例），保持"所有模块一个口径"。
+
+### 4. ReelShortWeb 适配（审计结果见 §二）
+
+把 id 当数字用的地方逐处改成字符串语义。**不建议**的写法（`Number(id)` / `id === 数字`）全部清掉。
+
+### 5. ReelShort（Flutter）适配（最小改动）
+
+**先说结论：客户端 model 里的 id 已经是 `(json['id'] ?? '').toString()` —— id 方向本来就是字符串，不会崩。**
+会崩的是被全局规则扫到的 **Long 计数**（`as num?` 在收到字符串时直接抛异常）。逐个 Java 字段核过类型后，
+只有两个字段真正会崩：
+
+| Dart 位置 | 字段 | Java 类型 | 处理 |
+| --- | --- | --- | --- |
+| `lib/core/data/models/auth_session.dart:41` | `expiresIn` | `TokenRespVO.expiresIn` = `long` | 改成兼容解析 |
+| `lib/core/data/models/drama.dart:101,117` | `viewCount` | `AppDramaCardVO/AppDramaDetailVO.viewCount` = `Long` | 改成兼容解析 |
+| 其余 8 处 `as num?`（`durationSec`/`unlockCoin`/`number`/`totalEpisodes`/`freeEpisodes`/`code`…） | — | `Integer`/`int` | 不动（Java 侧不会被字符串化） |
+
+做法：加一个兼容解析小工具（接受 `num` 或数字字符串），替换上面 3 处。**不做模型改造、不碰业务逻辑**，
+避免和正在推进客户端的另一位同事冲突。
+
+## 二、影响面清单（审计结果）
+
+### ReelShortWeb（id 当数字用 → 必须改）
+
+| 文件 | 问题 | 改法 |
+| --- | --- | --- |
+| `src/utils/creatorImpersonation.ts` | `Number(raw)` 读 localStorage 里的代看创作者 id → 19 位 id 被四舍五入，`X-Creator-Id` 头会带错值 | 存/读都按字符串 |
+| `src/views/contentManagement/EpisodeManagementView.vue:58` | `Number(route.query.drama)` 与 `item.id ===` 比较 → 从短剧管理带 `?drama=` 跳过来选不中 | 按字符串比较 |
+| `src/views/creator-center/composables/useDramaEdit.js:45` | `Number(route.params.id)` 与 `item.id ===` 比较 → 作品编辑找不到自己那条 | 按字符串比较 |
+| `src/views/permission/composables/useMenuManagement.js:50,76,97,117` | 顶级菜单哨兵值是数字 `0`，而 `raw.parentId` 会变成字符串 `"0"` → 下拉回显错 | 哨兵统一成字符串 `'0'` |
+
+### ReelShortWeb（核过不需要改）
+
+- `total.value = res.data.total`（13 处）→ `total` 保持数字，无需改。
+- `role.id === selectedRoleId`、`detail.id === row.id`、`useDramaEdit#findIndex`、`useCreatorPrice#find`
+  → 两侧都来自接口，同为字符串，仍然相等。
+- `formatCount(row.views)` → 内部 `Number(value)`，吃到字符串也正常。
+- 全局 `parseInt`/`Number(`/id 算术/id 当数组下标/`a.id - b.id`：审计后**没有命中**。
+
+### FruitServer（会跟着变化、需确认消费方）
+
+- admin-api：所有 `Long` id、`viewCount`、`likeCount`、`memberCount` 等计数器 → 字符串。
+- app-api：C 端 `id/dramaId/episodeId/userId`、`viewCount`、`positionMs/durationMs`、
+  `downloadedBytes/totalBytes`、`TokenRespVO.expiresIn` → 字符串；`Result.code`、`PageResult.total`、
+  `Integer` 字段 → 仍是数字。
+
+## 三、风险 / 待确认
+
+1. **`PageResult.total` 的例外**（见 §一.2）—— 我自己拍的，一句话可回退。
+2. **契约测试的 standalone MockMvc 自带 mapper**：它本来是手搓的 `JsonMapper`，不含全局模块，
+   会让"字符串化"在测试里**假绿**。所以本轮把模块也挂进 `ControllerContractSupport`，让测试与生产一致；
+   代价是几条老断言（id 断数字）要改成断字符串。
+3. **Flutter 仓库当前只有 `main`**（无 develop）。按条目要求在 develop 提交推送，会新建分支；
+   客户端由另一位同事推进，若他在 main 上继续，需要把这笔改动带过去 —— 回执里会写清。
+4. `Map<Long, X>` 的 **key** 不在本次范围（只要求 Map 值）；当前也没有接口返回 `Map<Long, ?>` 给前端。
+5. 大 id 只在"新建后立刻用 id 操作"时暴露；老页面用种子小 id，所以**回归要靠端到端实测**，不能只看单测。

docs/plans/2026-10-16-K1.md

@@ -0,0 +1,95 @@
+# K1 客户端对接：详情 + 播放 + 进度续看 + 收藏（看剧闭环）+ UI 调整 —— 计划（2026-10-16）
+
+> 依据：`docs/plans/INBOX.md` 19:40 条目。用户指令：「现在你要做的事对接客户端接口及 UI 调整，
+> 仍然严格按照 specs 执行」→ 本轮做客户端 `ReelShort`（Flutter），目标是一条完整看剧闭环：
+> **首页点进剧 → 详情正确 → 能起播 → 进度能续看 → 能收藏**，全链路走真接口。
+> 契约以 `FruitServer/docs/api-phase1.md` §1.4 / §1.5 为准。
+
+## 一、勘察更正（先说清，免得后面对不上）
+
+条目里写「客户端只调了 6 个接口、没有详情和票据」—— 这条**不准确**，实测：
+
+| 接口 | 现状 |
+| --- | --- |
+| `GET /app/dramas/{id}` | **已接**：`CatalogApi.dramaDetail` + `CatalogController.requireDetail`，详情页在用 |
+| `GET /app/episodes/{id}/play` | **半接**：`CatalogApi.playTicket` + `CatalogController.resolvePlay` 存在，但**没有任何页面调用**；详情下发的 `playUrl`（免费集已带签名）被直接使用 |
+| `/app/watch/*` | **没接**：`WatchHistoryRepository` 是 `SharedPreferences` 本地实现，`demoProfileId` 假身份 |
+| `/app/favorites/*` | **没接**：收藏走本地 `EngagementController`（SharedPreferences），点赞也是本地（点赞属 K3，不动） |
+
+所以本轮真正要做的是：**播放票据接上并带过期重取**、**进度从本地换远程**、**收藏换服务端**、
+**三态 UI**，以及把详情页已有的加载/失败态补齐（空态、续看进度条）。
+
+## 二、方案（分层：api → repository → logic → view）
+
+### 1. 新增 api 类（`lib/core/data/remote/`）
+
+| 文件 | 方法 | 对应接口 |
+| --- | --- | --- |
+| `playback_api.dart`（新增） | `ticket(episodeId)` | `GET /app/episodes/{id}/play` |
+| `watch_api.dart`（新增） | `saveProgress` / `progressOfDrama` / `recent` | `POST /app/watch/progress`、`GET /app/watch/progress?dramaId=`、`GET /app/watch/recent?limit=` |
+| `library_api.dart`（新增） | `toggleFavorite` / `favorites` / `removeFavorite` | `POST /app/favorites/toggle`、`GET /app/favorites`、`DELETE /app/favorites/{dramaId}` |
+
+票据调用从 `CatalogApi` **搬**到 `PlaybackApi`（条目要求新增 playback_api），
+`CatalogRepository.resolvePlay` 随之移到新的 `PlaybackRepository`——这是本轮唯一"动到既有目录层"的地方，最小接线。
+
+### 2. repository（保留抽象，测试注入假实现）
+
+- `playback_repository.dart`（新增）：`ticketFor(episodeId, {forceRefresh})`。
+  `HttpPlaybackRepository` 内含**短时缓存**：默认 TTL 10 分钟（签名有效期契约是 15 分钟，留余量），
+  **时钟与 TTL 可注入** → 过期自动重取，测试用假时钟钉死。
+- `watch_history_repository.dart`（**改签名**）：服务端按 `(user, drama)` 存一条续看记录，
+  所以接口从 `(profileId, dramaId, episodeId)` 变成
+  `progressFor(dramaId)` / `save({episodeId, position, duration, finished})` / `recent(limit)`；
+  `HttpWatchHistoryRepository` + `InMemoryWatchHistoryRepository`（测试用）；
+  `demoProfileId` 删除；`clampResumePosition` 保留（续看钳位规则不变）。
+- `favorite_repository.dart`（新增）：`toggle` / `list` / `remove`；HTTP + 内存实现。
+
+### 3. controller / logic
+
+- `favorite_controller.dart`（新增）：`savedIds` + `cards` + `loading/error`，
+  `toggle(dramaId)` **乐观更新 → 失败回滚**（`DELETE`/`toggle` 任一失败都回到原状态）。
+- `DramaDetailLogic` / `MineLogic` / `PlayerLogic`：改用新的 `WatchHistoryRepository`，
+  续看点从 `WatchProgress(episodeId, positionMs)` 来（不再是本地 episodeId 字符串）。
+- `PlayerLogic`：
+  - 起播前 `ticketFor(episode)`，把签名地址写回 session 的剧集对象；**地址原样交给播放器**
+    （`AppConfig.mediaUrl` 只补 host，不动 path/query —— 新增测试钉住 `?e=&s=` 原样保留）；
+  - 票据拿不到 / `accessType=COIN_REQUIRED|NO_MEDIA` → 由**后端返回值**驱动 UI（锁定/无片源提示 + 重试）；
+  - 进度上报**节流 10 秒**（原实现是 5 秒），切集/退出/切后台各补一次，`finished` 在播完时上报。
+
+### 4. UI
+
+- 详情页：加载中 / 失败（可重试）/ 空剧集三态；续看位置在"继续观看"按钮与对应剧集行上给进度条。
+- 播放页：票据加载中 / 失败（可重试）/ 锁定（`accessType` 驱动）三态；收藏按钮真实状态 + 回滚 +
+  失败提示（未登录先引导登录，沿用现有 `ensureSignedIn`）。
+- 我的页：最近观看卡片三态（服务端续看位置驱动）、收藏列表三态，去掉 `demoProfileId` 假身份。
+- 文案：新增键写进 `app_en.arb` / `app_zh.arb` / `app_id.arb`，`flutter gen-l10n` 重新生成。
+
+## 三、影响面清单
+
+新增：`playback_api.dart`、`watch_api.dart`、`library_api.dart`、`watch_progress.dart`（模型）、
+`playback_repository.dart`、`favorite_repository.dart`、`favorite_controller.dart`。
+
+改：`watch_history_repository.dart`（签名）、`catalog_api.dart`（去掉 playTicket）、
+`catalog_repository.dart`（去掉 resolvePlay）、`catalog_controller.dart`（同步）、
+`play_ticket.dart`（补 dramaId/number/previewSeconds）、`app.dart`（注入三个仓库 + FavoriteController）、
+`drama_detail_{logic,view,binding}.dart`、`mine_{logic,view,binding}.dart`、
+`player_{logic,view,binding}.dart`、`discover_{logic,binding}.dart`（续看点来源）、
+`app_{en,zh,id}.arb` + 生成的 4 个 l10n 文件。
+
+测试：改 `test/support/fake_watch_history.dart`、`test/playback/watch_history_test.dart`、
+`test/catalog/catalog_controller_test.dart`、`test/support/fake_catalog.dart`、
+`test/{discover,mine,drama_detail,player}/…`（续看点改签名）；新增
+`playback_ticket_expiry_test.dart`、`progress_throttle_test.dart`、`watch_history_remote_test.dart`、
+`favorite_controller_test.dart`、`player_ticket_gate_test.dart`、`integration/live_watch_flow_test.dart`。
+
+## 四、风险 / 待确认
+
+1. **改动面比"只加接口"大**：`WatchHistoryRepository` 的签名必须改（服务端是"每剧一条续看记录"，
+   没有 profile 概念），这会连带改 4 个 logic + 6 个测试文件。这是接口模型决定的，不是顺手重构。
+2. **未登录的边界**：`/app/watch/*` 与 `/app/favorites/*` 需要登录态。客户端策略：
+   未登录时**不发**这些请求（浏览/试看仍可匿名），收藏按钮沿用"先引导登录"。
+3. **票据过期无法从响应判断**（契约里没有 expiresAt 字段），所以用**客户端 TTL（10 分钟）**保守失效重取；
+   若后端后续补 `expiresAt`，直接换成按字段判断即可（口径已写进计划）。
+4. **`/app/watch/recent` 只给 dramaId/episodeId/位置**，没有剧名封面 —— K1 里"我的"页用
+   已加载的首页/发现卡片按 id 映射显示；映射不到就不显示（K2 的记录页再做成独立请求）。
+5. 联调测试需要登录态：新增的 live 测试会**注册一个一次性邮箱账号**，跑完在库里清掉（回执写明）。

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

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,170 @@
+# K2 客户端第二批：分类 + 观看记录 + 收藏列表 + 下载授权管理
+
+> 依据：`docs/plans/INBOX.md` 2026-10-17 `[待处理] K2` 条目。
+> 客户端基线：`ReelShort` `develop` / `00280ca`。
+> 接口唯一权威：`FruitServer/docs/api-phase1.md` §0、§1.3、§1.5、§1.6。
+> 本批只做 K2，完成后停下写回执，不连做 K3/K4。
+
+## 一、范围与完成口径
+
+### K2-A 分类
+
+- 接 `GET /app/categories`，分类 id 全程按字符串处理。
+- 发现页分类条改为服务端分类；保留现有分类条样式。
+- 分类内容只从 `GET /app/discover/feed` 的 `sections[]` 中读取
+  `code == "category-{id}"` 的分区，不在客户端拼装分类请求。
+- 分类在发现 feed 中没有对应分区时显示空态。
+- 保留 `hot` / `new` 入口与既有样式；其内容同样只按发现 feed 中对应 `code`
+  分区读取，缺失时显示空态。
+
+### K2-B 观看记录页
+
+- 接 `GET /app/watch/recent?limit=20`、`DELETE /app/watch/progress/{dramaId}`、
+  `DELETE /app/watch/progress`。
+- 最近记录先去重 `dramaId`，再按 id 补 `GET /app/dramas/{id}` 卡片数据。
+- 详情补取并发上限 4，同页按 `dramaId` 只请求一次。
+- 单条详情失败只影响该条：显示“加载失败”占位与单项重试，其余记录正常渲染。
+- 独立“观看记录”页：封面、剧名、集号、进度、更新时间；点击详情并续看；
+  单条删除、清空均有二次确认；删除采用乐观更新，失败回滚并提示。
+- 加载 / 空 / 失败可重试三态；未登录使用现有登录引导。
+
+### K2-C 收藏列表页
+
+- 复用 `GET /app/favorites`、`DELETE /app/favorites/{dramaId}`、
+  `POST /app/favorites/toggle`，不增加分页参数。
+- 独立“我的收藏”页，复用卡片数据模型与列表卡片视觉；点击进详情。
+- 取消收藏采用乐观更新，失败回滚并提示。
+- 加载 / 空 / 失败可重试三态；未登录使用现有登录引导。
+
+### K2-D 下载授权管理
+
+- 接契约 §1.6 全部 8 个接口：
+  `GET /app/downloads/policy`、`PUT /app/downloads/settings`、
+  `POST /app/downloads`、`GET /app/downloads`、
+  `GET /app/downloads/{episodeId}/url`、`POST /app/downloads/{episodeId}/progress`、
+  `DELETE /app/downloads/{episodeId}`、`DELETE /app/downloads`。
+- 详情页与播放页增加下载入口；后端拒绝时直接展示后端 `message`。
+- 独立“我的下载”页：策略卡、授权列表、单条删除、清空、仅 Wi-Fi、最高清晰度。
+- 授权状态与任务状态完全使用后端字符串，客户端不新增状态枚举、不自行判断付费/配额。
+- 加载 / 空 / 失败可重试三态；未登录使用现有登录引导。
+- 明确不做：文件分片落盘、断点续传、离线播放、`licenseKey` 本地校验。
+  `url` 与 `progress` 本批只提供并测试 API 方法，不驱动实际下载任务。
+
+## 二、实施顺序与 TDD
+
+1. 基线：从 `ReelShort/develop` 建 `feature/flutter-k2-library`。
+2. K2-A：先写分类解析、`category-{id}` 映射、无分区空态和筛选状态测试，
+   确认红灯后实现；再跑该块门禁。
+3. K2-B：先写控制器测试覆盖详情去重、并发上限 4、单条失败降级、
+   删除/清空乐观更新与回滚；确认红灯后实现 API、repository、controller、页面；
+   再跑门禁。
+4. K2-C：先写独立收藏页取消收藏失败回滚、三态与登录引导测试，
+   确认红灯后实现页面与导航；再跑门禁。
+5. K2-D：先写 DTO 字符串 ID/时间解析、策略/列表渲染、授权失败透传、
+   设置更新、删除/清空和未登录测试；确认红灯后实现；
+   `ApiClient` 仅补契约所需的 `PUT` 能力；再跑门禁。
+6. 三份 ARB 一次补齐并生成 l10n；全量跑
+   `dart analyze lib test`、`flutter test`、`flutter build apk --debug`。
+7. 门禁全绿后合并回 `develop` 并 push；不动 `main`。
+8. 在 `PROGRESS.md` 与 INBOX K2 条目追加回执；真机验证交用户执行。
+
+## 三、预计影响文件
+
+### 数据层
+
+- 修改：`lib/core/data/remote/api_client.dart`（补 `put`）
+- 修改：`lib/core/data/models/watch_progress.dart`（补 `updatedAt`）
+- 修改：`lib/core/data/remote/watch_api.dart`（补清空）
+- 修改：`lib/core/data/repositories/watch_history_repository.dart`（补清空）
+- 新增：`lib/core/data/models/content_category.dart`
+- 新增：`lib/core/data/remote/category_api.dart`
+- 新增：`lib/core/data/repositories/category_repository.dart`
+- 新增：`lib/core/data/services/category_controller.dart`
+- 新增：`lib/core/data/models/watch_record.dart`
+- 新增：`lib/core/data/services/watch_records_controller.dart`
+- 新增：`lib/core/data/models/download_policy.dart`
+- 新增：`lib/core/data/models/download_license.dart`
+- 新增：`lib/core/data/remote/download_api.dart`
+- 新增：`lib/core/data/repositories/download_repository.dart`
+- 新增：`lib/core/data/services/download_controller.dart`
+
+### 页面与共享 UI
+
+- 修改：`lib/app.dart`（新仓库/控制器注入）
+- 修改：`lib/core/widgets/auth_gate.dart`（页面级登录引导复用）
+- 修改：`lib/pages/discover/discover_logic.dart`
+- 修改：`lib/pages/discover/discover_view.dart`
+- 修改：`lib/pages/home/home_view.dart`（我的页入口接线）
+- 修改：`lib/pages/mine/mine_view.dart`（观看记录、收藏、下载入口）
+- 修改：`lib/pages/drama_detail/drama_detail_view.dart`（下载入口）
+- 修改：`lib/pages/player/player_view.dart`（当前集下载入口）
+- 新增：`lib/pages/watch_records/watch_records_binding.dart`
+- 新增：`lib/pages/watch_records/watch_records_view.dart`
+- 新增：`lib/pages/favorites/favorites_binding.dart`
+- 新增：`lib/pages/favorites/favorites_view.dart`
+- 新增：`lib/pages/downloads/downloads_binding.dart`
+- 新增：`lib/pages/downloads/downloads_view.dart`
+- 视复用需要新增列表卡片/状态组件，预计位于 `lib/core/widgets/` 或各页面 `widgets/`。
+
+### 文案
+
+- 修改：`lib/l10n/app_en.arb`
+- 修改：`lib/l10n/app_zh.arb`
+- 修改：`lib/l10n/app_id.arb`
+- 重新生成：`lib/l10n/app_localizations*.dart`
+
+### 测试
+
+- 修改：`test/catalog/catalog_controller_test.dart` 及分类筛选相关测试
+- 修改：`test/discover/discover_logic_test.dart`
+- 修改：`test/mine/mine_logic_test.dart`
+- 修改：`test/library/favorite_controller_test.dart`
+- 新增：分类 API/控制器与 section 映射测试
+- 新增：观看记录 API、并发加载、单项降级、删除/清空回滚和页面三态测试
+- 新增：收藏独立页、取消收藏回滚、三态和登录引导测试
+- 新增：下载 DTO/API/controller/page 测试
+- 新增：未登录 `AuthGate` 页面测试
+
+## 四、契约缺口（本批登记，不改契约/后端）
+
+1. `GET /app/watch/recent` 未返回剧名与封面，客户端只能先取最近记录，
+   再对去重后的 `dramaId` 调详情补齐卡片；代价是 N+1 请求。
+   建议后续在 `ProgressRespVO` 补卡片字段（需 specs 负责人改契约）。
+2. `GET /app/favorites` 没有分页参数并返回全量数组，与
+   `TC-RECORD-04` 的“分页正确”不一致。本批按全量列表实现，
+   不自造 `page/size`。
+3. `api-phase1.md` 没有搜索接口，本批不做搜索，也不以本地模糊匹配冒充搜索接口。
+
+## 五、风险与控制
+
+1. 记录页 N+1 详情请求可能放大流量和延迟：严格去重、并发上限 4、页内缓存，
+   单项失败降级，不在失败后自动无限重试。
+2. 页面销毁时异步详情仍可能返回：controller 的 `notify` 做 disposed 保护，
+   不把迟到结果写回已退出页面。
+3. `updatedAt` 为后端 `LocalDateTime` 字符串，解析失败只能显示占位，
+   不能让整条记录解析失败。
+4. 下载契约里授权与任务状态均为字符串，客户端只原样展示/映射现有文案，
+   不根据未知值猜测业务状态。
+5. 下载地址字段 `playUrl` 后端当前未填充，本批不做实际下载；不能据此宣称
+   “可离线播放”。
+6. 本机可能缺少 Android SDK，`flutter build apk --debug` 若失败将保留原始输出，
+   回执标记“未验证”，不静默跳过。
+7. 真机/模拟器可达性由用户验证；开发机 `curl` 不作为设备证据。
+
+## 六、待确认（不阻塞本批）
+
+1. 发现页 `hot` / `new` 入口保留，但当前后端 `discoverFeed()` 只生成
+   `category-{id}` 分区。若后续要展示热门/最新内容，需要后端在发现 feed 下发
+   对应分区；在此之前按契约显示空态。
+2. 收藏分页与观看记录卡片字段待契约负责人后续补足；本批按 INBOX 降级方案执行。
+3. 下载真实落盘、断点续传与离线播放需要存储、权限、加密播放方案，另立批次。
+
+## 七、完成定义
+
+- 四块均有“红 → 绿”测试证据。
+- `dart analyze lib test` 零告警，`flutter test` 全过。
+- `flutter build apk --debug` 通过，或保留缺 SDK 的原始失败输出并标记未验证。
+- 三语言 ARB 齐全且生成物已更新。
+- 独立记录、收藏、下载页和分类条均接契约接口；未登录入口可完成登录引导。
+- 不改 `main`、不改 specs、不改 FruitServer 后端、不做搜索。
+- `PROGRESS.md` 与 INBOX K2 回执包含验证步骤、预期结果、提交号与原始门禁输出。

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

@@ -0,0 +1,92 @@
+# 2026-10-17 K3 客户端第三批：互动
+
+## 一、目标与边界
+
+本轮只完成 Flutter 客户端互动能力的真实接口接入：
+
+- K3-A 评论：匿名游标列表、顶层评论与一层回复、发布、敏感词三档、删除、三态与重试。
+- K3-B 点赞：剧集与评论点赞、乐观更新、失败回滚、未登录拦截、防连点。
+- K3-C 举报：举报评论与短剧、固定原因单选、可选描述、成功与失败提示。
+- K3-D 分享回归：沿用现有系统分享，核对标题、简介与 footer 的三语文案。
+
+不做 K4、拉黑、举报用户、后台治理、图片/表情/@提及、无限嵌套、我的评论列表和并发压测。
+后端代码、后台 Web、specs 仓库均不改；接口只使用 `FruitServer/docs/api-phase1.md` §1.7。
+
+## 一之一、实测基线
+
+- ReelShort：`develop` / `feature/flutter-k3-interaction` 均为 `45f5f25`，功能分支从 K2 合并点派生。
+- FruitServer：`develop` 为 `a0156ee`，比 `origin/develop` 多 1 个仅包含 INBOX 的派单提交。
+- 本计划文件在开工前的 FruitServer 工作区中已存在且尚未提交，本轮仅增量补充，不覆盖既有内容。
+
+## 二、契约与数据口径
+
+| 能力 | 接口 | 客户端处理 |
+| --- | --- | --- |
+| 评论列表 | `GET /app/comments?dramaId=&episodeId=&rootId=&cursor=&size=` | 首屏 20 条，按 `nextCursor` 续拉，用 `hasMore` 控制加载更多 |
+| 发布评论 | `POST /app/comments` | 顶层传 `dramaId/content`，回复额外传 `parentId` |
+| 删除评论 | `DELETE /app/comments/{id}` | 仅 `mine=true` 可操作，二次确认，失败恢复列表 |
+| 点赞切换 | `POST /app/likes/toggle` | `DRAMA` / `COMMENT`，以响应 `{liked,count}` 为最终态 |
+| 举报 | `POST /app/reports` | `COMMENT` / `DRAMA`，`reasonCode` 必填 |
+| 系统分享 | 无后端接口 | 保持 `PlatformShareService` |
+
+评论字段按 `CommentRespVO` 解析，ID 全部使用字符串。所有新增用户可见文案进入
+`lib/l10n/app_{en,zh,id}.arb` 并重新生成。
+
+## 三、已确认的契约缺口与降级
+
+1. `AppDramaDetailVO` / `AppDramaCardVO` 没有 `likeCount` / `liked`。
+   降级：不展示剧集点赞数字，只维护当前会话内的 liked 状态。
+   建议：后端详情与卡片补 `likeCount` / `liked`，需 specs 负责人变更契约。
+2. §1.7 没有定义 `reasonCode` 枚举，后端当前不校验。
+   降级：客户端固定 `SPAM / ABUSE / PORN / AD / OTHER` 五项，文案进三语 arb。
+   建议：后端补 `reasonCode` 枚举与后台工单映射。
+3. §1.7 没有拉黑接口。
+   降级：本批不做拉黑，不提供入口。
+
+## 四、预计影响文件
+
+FruitServer 文档：
+
+- `docs/plans/2026-10-17-K3.md`
+- `docs/plans/PROGRESS.md`
+- `docs/plans/INBOX.md`
+
+ReelShort 客户端：
+
+- `lib/core/data/remote/comment_api.dart`
+- `lib/core/data/remote/interaction_api.dart`
+- `lib/core/data/repositories/comment_repository.dart`
+- `lib/core/data/repositories/interaction_repository.dart`
+- `lib/core/data/services/comment_controller.dart`
+- 互动相关模型、Provider 注入与页面/组件
+- `lib/pages/player/widgets/drama_comments_sheet.dart`
+- `lib/pages/player/player_view.dart`
+- 详情页举报入口及互动弹窗
+- `lib/l10n/app_{en,zh,id}.arb` 与生成文件
+- 对应 `test/**/*_test.dart`
+
+实际文件以现有 K1/K2 分层和注入方式为准，避免无关重构。
+
+## 五、TDD 与执行顺序
+
+1. 只读核对 `ReelShort` 与 `FruitServer` 的 `develop` 基线、工作区状态与提交。
+2. 从 `develop` 建 `feature/flutter-k3-interaction`。
+3. K3-A：先写评论分页、发布、敏感词、删除、失败回滚和未登录测试并确认红灯，再实现并转绿。
+4. K3-B：先写剧集/评论点赞成功、计数、乐观更新、回滚和未登录测试并确认红灯，再实现并转绿。
+5. K3-C：先写举报成功、重复举报 message 透传和未登录测试并确认红灯，再实现并转绿。
+6. K3-D：补充分享文案回归检查，确认三语资源完整。
+7. 每块执行定向测试和 `dart analyze lib test`。
+8. 全量执行 `dart analyze lib test`、`flutter test`、`flutter build apk --debug`。
+9. 分块提交，`--no-ff` 合并回 `develop` 并 push；文档单独提交并 push。
+10. 在 `PROGRESS.md` 与 INBOX 写回执，列出用户真机验证步骤，并明确设备侧取证未由 Codex 执行。
+
+## 六、风险与待确认
+
+- 评论游标的实际响应字段以已实现后端 VO 为准；若与任务书 `nextCursor/hasMore` 不一致，先停止并在 INBOX 顶部登记待协助，不自行扩契约。
+- 剧集点赞没有初始查询接口，页面重建后会话内状态可能丢失；本批按降级方案不伪造初始值。
+- 匿名列表可见，但发布、点赞、举报必须登录；需确保 AuthGate 在发起业务请求前拦截。
+- 举报重复与举报自己依赖后端 message，客户端只原样展示，不自行判断。
+- 敏感词 `REVIEW` 的 pending 评论仅自己可见，客户端必须保留发布成功返回内容并显示“审核中”。
+- 现有互动控制器为本地演示数据，移除时不得破坏 K2 的分类、记录、收藏、下载和播放进度逻辑。
+- 全量构建可能受本机 Flutter/Android SDK 环境影响；若失败会记录原始输出，不以开发机接口请求代替设备证据。
+- 当前没有待确认的产品问题；若执行中出现契约与实现不一致，按任务书先停并登记。

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

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

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

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

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

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

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

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

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

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

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

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

fruitshorts-admin-api/src/main/java/com/fruitshorts/FruitShortsApplication.java

@@ -5,7 +5,50 @@ package com.fruitshorts;
 import org.mybatis.spring.annotation.MapperScan;
 import org.springframework.boot.SpringApplication;
 import org.springframework.boot.autoconfigure.SpringBootApplication;
+import io.swagger.v3.oas.annotations.OpenAPIDefinition;
+import io.swagger.v3.oas.annotations.info.Info;
+import io.swagger.v3.oas.annotations.tags.Tag;
 
+@OpenAPIDefinition(
+        info = @Info(
+                title = "FruitShorts 运营后台接口（/admin/**）",
+                version = "1.0.0",
+                description = "接口契约以 FruitServer/docs/api-phase1.md 为准"
+        ),
+        tags = {
+                @Tag(name = "后台-管理员账号", description = "后台管理员账号管理"),
+                @Tag(name = "后台-App 用户", description = "App 用户查询与处置"),
+                @Tag(name = "后台-登录与个人", description = "管理端登录、菜单、个人资料与改密"),
+                @Tag(name = "后台-轮播图管理", description = "轮播图维护与排序"),
+                @Tag(name = "后台-评论审核", description = "评论检索与审核"),
+                @Tag(name = "后台-系统配置", description = "系统参数配置"),
+                @Tag(name = "后台-创作者管理", description = "创作者入驻审核与账号开通"),
+                @Tag(name = "创作者中心", description = "创作者工作台（作品、通知、看板）"),
+                @Tag(name = "创作者中心-内容与收费", description = "创作者内容编辑、提交审核与分集收费"),
+                @Tag(name = "后台-数据看板", description = "运营大盘与转码看板"),
+                @Tag(name = "后台-字典", description = "分类与状态字典"),
+                @Tag(name = "后台-离线下载管理", description = "下载授权查询、吊销与清理"),
+                @Tag(name = "后台-短剧分类", description = "短剧分类维护"),
+                @Tag(name = "后台-短剧管理", description = "短剧 CRUD 与审核发布流转"),
+                @Tag(name = "后台-权益管理", description = "权益补发与回收"),
+                @Tag(name = "后台-剧集管理", description = "剧集 CRUD 与排序"),
+                @Tag(name = "后台-媒资管理", description = "分片上传与媒资详情"),
+                @Tag(name = "后台-菜单管理", description = "菜单树维护"),
+                @Tag(name = "后台-操作日志", description = "操作日志检索"),
+                @Tag(name = "后台-订单管理", description = "订单检索、补发与退款"),
+                @Tag(name = "后台-商品配置", description = "商品（金币包）配置与上下架"),
+                @Tag(name = "后台-系统公告", description = "系统公告发布与管理（与 C 端口径一致）"),
+                @Tag(name = "后台-权限点", description = "权限点查询"),
+                @Tag(name = "后台-分集收费", description = "分集价格配置"),
+                @Tag(name = "后台-对账", description = "对账任务与手动对账"),
+                @Tag(name = "后台-举报工单", description = "举报工单处理"),
+                @Tag(name = "后台-角色分类", description = "角色分类维护"),
+                @Tag(name = "后台-角色管理", description = "角色与角色权限"),
+                @Tag(name = "后台-敏感词库", description = "敏感词维护"),
+                @Tag(name = "后台-内容提交审核", description = "创作者内容提交审核"),
+                @Tag(name = "后台-金币钱包", description = "金币流水与人工补币"),
+        }
+)
 @SpringBootApplication
 @MapperScan("com.fruitshorts.**.dal.mapper")
 public class FruitShortsApplication {

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

@@ -10,6 +10,8 @@ import com.fruitshorts.framework.log.OperationLog;
 import com.fruitshorts.system.vo.AdminUserPageReqVO;
 import com.fruitshorts.system.vo.AdminUserRespVO;
 import com.fruitshorts.system.vo.AdminUserSaveReqVO;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import lombok.RequiredArgsConstructor;
 import org.springframework.security.access.prepost.PreAuthorize;
@@ -25,6 +27,7 @@ import org.springframework.web.bind.annotation.RestController;
 
 import java.util.Map;
 
+@Tag(name = "后台-管理员账号")
 @RestController
 @RequestMapping("/admin/admin-users")
 @RequiredArgsConstructor
@@ -32,18 +35,21 @@ public class AdminUserController {
 
     private final AdminUserService adminUserService;
 
+    @Operation(summary = "管理员分页查询")
     @GetMapping("/page")
     @PreAuthorize("@ss.hasPermission('system:admin-user')")
     public Result<PageResult<AdminUserRespVO>> page(AdminUserPageReqVO req) {
         return Result.ok(adminUserService.page(req));
     }
 
+    @Operation(summary = "管理员详情")
     @GetMapping("/{id}")
     @PreAuthorize("@ss.hasPermission('system:admin-user')")
     public Result<AdminUserRespVO> get(@PathVariable Long id) {
         return Result.ok(adminUserService.get(id));
     }
 
+    @Operation(summary = "新建管理员")
     @PostMapping
     @PreAuthorize("@ss.hasPermission('system:admin-user')")
     @OperationLog(module = "后台管理", action = "新增管理员")
@@ -51,6 +57,7 @@ public class AdminUserController {
         return Result.ok(adminUserService.create(req));
     }
 
+    @Operation(summary = "编辑管理员")
     @PutMapping("/{id}")
     @PreAuthorize("@ss.hasPermission('system:admin-user')")
     @OperationLog(module = "后台管理", action = "编辑管理员")
@@ -59,6 +66,7 @@ public class AdminUserController {
         return Result.ok();
     }
 
+    @Operation(summary = "删除管理员")
     @DeleteMapping("/{id}")
     @PreAuthorize("@ss.hasPermission('system:admin-user')")
     @OperationLog(module = "后台管理", action = "删除管理员")
@@ -67,6 +75,7 @@ public class AdminUserController {
         return Result.ok();
     }
 
+    @Operation(summary = "启用 / 停用管理员")
     @PutMapping("/{id}/status")
     @PreAuthorize("@ss.hasPermission('system:admin-user')")
     @OperationLog(module = "后台管理", action = "修改管理员状态")
@@ -75,6 +84,7 @@ public class AdminUserController {
         return Result.ok();
     }
 
+    @Operation(summary = "重置管理员密码")
     @PutMapping("/{id}/password")
     @PreAuthorize("@ss.hasPermission('system:admin-user')")
     @OperationLog(module = "后台管理", action = "重置管理员密码")

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

@@ -18,6 +18,8 @@ import com.fruitshorts.user.dal.entity.AppUserBanRecord;
 import com.fruitshorts.user.service.AppUserAdminService;
 import com.fruitshorts.user.vo.AppUserQueryReqVO;
 import com.fruitshorts.user.vo.AppUserAdminRespVO;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.security.access.prepost.PreAuthorize;
 import org.springframework.web.bind.annotation.GetMapping;
@@ -32,6 +34,7 @@ import java.util.Map;
 import java.util.stream.Collectors;
 
 /** 后台用户管理。 */
+@Tag(name = "后台-App 用户")
 @RestController
 @RequestMapping("/admin/app-users")
 @RequiredArgsConstructor
@@ -42,18 +45,21 @@ public class AppUserAdminController {
     private final DramaService dramaService;
     private final EpisodeService episodeService;
 
+    @Operation(summary = "App 用户分页查询")
     @GetMapping("/page")
     @PreAuthorize("@ss.hasPermission('app-user:list')")
     public Result<PageResult<AppUserAdminRespVO>> page(AppUserQueryReqVO req) {
         return Result.ok(appUserAdminService.page(req));
     }
 
+    @Operation(summary = "App 用户详情")
     @GetMapping("/{id}")
     @PreAuthorize("@ss.hasPermission('app-user:list')")
     public Result<AppUserAdminRespVO> detail(@PathVariable Long id) {
         return Result.ok(appUserAdminService.detail(id));
     }
 
+    @Operation(summary = "封禁 / 处置记录")
     @GetMapping("/{id}/ban-records")
     @PreAuthorize("@ss.hasPermission('app-user:list')")
     public Result<List<AppUserBanRecord>> banRecords(@PathVariable Long id) {
@@ -61,6 +67,7 @@ public class AppUserAdminController {
     }
 
     /** 观看流水明细：客服核对"用户说看了但没记录"这类问题时用，带上剧名与集号。 */
+    @Operation(summary = "观看流水明细（客服核对用）")
     @GetMapping("/{id}/watch-history")
     @PreAuthorize("@ss.hasPermission('app-user:list')")
     public Result<List<AppUserWatchHistoryVO>> watchHistory(@PathVariable Long id,
@@ -108,6 +115,7 @@ public class AppUserAdminController {
     }
 
     /** 状态处置：normal/limited/banned。封禁会立即吊销该用户全部会话。 */
+    @Operation(summary = "处置用户状态（封禁会立即吊销全部会话）")
     @PutMapping("/{id}/status")
     @PreAuthorize("@ss.hasPermission('app-user:update')")
     @OperationLog(module = "用户管理", action = "修改用户状态")

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

@@ -12,6 +12,8 @@ import com.fruitshorts.system.vo.LoginRespVO;
 import com.fruitshorts.system.vo.MenuVO;
 import com.fruitshorts.system.vo.PasswordChangeReqVO;
 import com.fruitshorts.system.vo.ProfileRespVO;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.servlet.http.HttpServletRequest;
 import jakarta.validation.Valid;
 import lombok.RequiredArgsConstructor;
@@ -23,6 +25,7 @@ import org.springframework.web.bind.annotation.RestController;
 
 import java.util.List;
 
+@Tag(name = "后台-登录与个人")
 @RestController
 @RequestMapping("/admin/auth")
 @RequiredArgsConstructor
@@ -30,6 +33,7 @@ public class AuthController {
 
     private final AuthService authService;
 
+    @Operation(summary = "管理端登录")
     @PostMapping("/login")
     @OperationLog(module = "认证", action = "登录")
     public Result<LoginRespVO> login(@Valid @RequestBody LoginReqVO req, HttpServletRequest request) {
@@ -37,23 +41,27 @@ public class AuthController {
     }
 
     /** 当前用户的菜单路由树，结构与前端 element-plus-admin 的动态路由一致。 */
+    @Operation(summary = "当前用户菜单路由树")
     @GetMapping("/menus")
     public Result<List<MenuVO>> menus() {
         return Result.ok(authService.listMenus(SecurityUtils.getUserId()));
     }
 
+    @Operation(summary = "当前用户资料")
     @GetMapping("/profile")
     public Result<ProfileRespVO> profile() {
         return Result.ok(authService.profile(SecurityUtils.getUserId()));
     }
 
     /** JWT 无状态，登出由前端清除 token 即可。 */
+    @Operation(summary = "登出")
     @PostMapping("/logout")
     @OperationLog(module = "认证", action = "退出登录")
     public Result<Void> logout() {
         return Result.ok();
     }
 
+    @Operation(summary = "修改自己的登录密码")
     @PostMapping("/password")
     @OperationLog(module = "认证", action = "修改密码")
     public Result<Void> changePassword(@Valid @RequestBody PasswordChangeReqVO req) {

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

@@ -9,6 +9,8 @@ import com.fruitshorts.content.vo.BannerRespVO;
 import com.fruitshorts.content.vo.BannerSaveReqVO;
 import com.fruitshorts.framework.security.SecurityUtils;
 import com.fruitshorts.framework.log.OperationLog;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import lombok.RequiredArgsConstructor;
 import org.springframework.security.access.prepost.PreAuthorize;
@@ -25,6 +27,7 @@ import org.springframework.web.bind.annotation.RestController;
 import java.util.List;
 import java.util.Map;
 
+@Tag(name = "后台-轮播图管理")
 @RestController
 @RequestMapping("/admin/banners")
 @RequiredArgsConstructor
@@ -32,6 +35,7 @@ public class BannerController {
 
     private final BannerService bannerService;
 
+    @Operation(summary = "轮播图分页查询")
     @GetMapping("/page")
     @PreAuthorize("@ss.hasPermission('banner:list')")
     public Result<PageResult<BannerRespVO>> page(@RequestParam(required = false) String position,
@@ -41,12 +45,14 @@ public class BannerController {
         return Result.ok(bannerService.page(position, status, pageIndex, pageSize));
     }
 
+    @Operation(summary = "轮播图详情")
     @GetMapping("/{id}")
     @PreAuthorize("@ss.hasPermission('banner:list')")
     public Result<BannerRespVO> get(@PathVariable Long id) {
         return Result.ok(bannerService.get(id));
     }
 
+    @Operation(summary = "新建轮播图")
     @PostMapping
     @PreAuthorize("@ss.hasPermission('banner:create')")
     @OperationLog(module = "内容管理", action = "新增轮播图")
@@ -54,6 +60,7 @@ public class BannerController {
         return Result.ok(bannerService.create(req, SecurityUtils.getUserId()));
     }
 
+    @Operation(summary = "编辑轮播图")
     @PutMapping("/{id}")
     @PreAuthorize("@ss.hasPermission('banner:update')")
     @OperationLog(module = "内容管理", action = "编辑轮播图")
@@ -62,6 +69,7 @@ public class BannerController {
         return Result.ok();
     }
 
+    @Operation(summary = "删除轮播图")
     @DeleteMapping("/{id}")
     @PreAuthorize("@ss.hasPermission('banner:delete')")
     @OperationLog(module = "内容管理", action = "删除轮播图")
@@ -70,6 +78,7 @@ public class BannerController {
         return Result.ok();
     }
 
+    @Operation(summary = "上架 / 下架轮播图")
     @PutMapping("/{id}/status")
     @PreAuthorize("@ss.hasPermission('banner:update')")
     @OperationLog(module = "内容管理", action = "修改轮播图状态")
@@ -78,6 +87,7 @@ public class BannerController {
         return Result.ok();
     }
 
+    @Operation(summary = "调整轮播排序")
     @PutMapping("/sort")
     @PreAuthorize("@ss.hasPermission('banner:update')")
     public Result<Void> sort(@RequestBody Map<String, List<Long>> body) {

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

@@ -11,6 +11,8 @@ import com.fruitshorts.interaction.service.CommentService;
 import com.fruitshorts.interaction.vo.CommentAuditReqVO;
 import com.fruitshorts.interaction.vo.CommentQueryReqVO;
 import com.fruitshorts.interaction.vo.CommentRespVO;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import lombok.RequiredArgsConstructor;
 import org.springframework.security.access.prepost.PreAuthorize;
@@ -25,6 +27,7 @@ import org.springframework.web.bind.annotation.RestController;
 import java.util.List;
 
 /** 后台评论审核。 */
+@Tag(name = "后台-评论审核")
 @RestController
 @RequestMapping("/admin/comments")
 @RequiredArgsConstructor
@@ -33,6 +36,7 @@ public class CommentAdminController {
     private final CommentService commentService;
 
     /** 检索评论：默认按状态过滤，`status=pending` 即审核队列。 */
+    @Operation(summary = "评论检索（默认按状态过滤，待审队列）")
     @GetMapping("/page")
     @PreAuthorize("@ss.hasPermission('comment:list')")
     public Result<PageResult<CommentRespVO>> page(CommentQueryReqVO req) {
@@ -40,12 +44,14 @@ public class CommentAdminController {
     }
 
     /** 审核留证：机审与人审的完整链路。 */
+    @Operation(summary = "评论审核留证（机审 + 人审链路）")
     @GetMapping("/{id}/audit-records")
     @PreAuthorize("@ss.hasPermission('comment:list')")
     public Result<List<ContentAuditRecord>> auditRecords(@PathVariable Long id) {
         return Result.ok(commentService.auditRecords(id));
     }
 
+    @Operation(summary = "审核评论（通过 / 驳回）")
     @PutMapping("/{id}/audit")
     @PreAuthorize("@ss.hasPermission('comment:audit')")
     @OperationLog(module = "内容治理", action = "审核评论")
@@ -54,6 +60,7 @@ public class CommentAdminController {
         return Result.ok();
     }
 
+    @Operation(summary = "删除评论")
     @DeleteMapping("/{id}")
     @PreAuthorize("@ss.hasPermission('comment:audit')")
     @OperationLog(module = "内容治理", action = "删除评论")

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

@@ -6,6 +6,8 @@ import com.fruitshorts.common.pojo.Result;
 import com.fruitshorts.system.service.ConfigService;
 import com.fruitshorts.framework.log.OperationLog;
 import com.fruitshorts.system.vo.ConfigItemVO;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.security.access.prepost.PreAuthorize;
 import org.springframework.web.bind.annotation.GetMapping;
@@ -17,6 +19,7 @@ import org.springframework.web.bind.annotation.RestController;
 import java.util.List;
 import java.util.Map;
 
+@Tag(name = "后台-系统配置")
 @RestController
 @RequestMapping("/admin/configs")
 @RequiredArgsConstructor
@@ -24,12 +27,14 @@ public class ConfigController {
 
     private final ConfigService configService;
 
+    @Operation(summary = "系统配置列表")
     @GetMapping
     @PreAuthorize("@ss.hasAnyPermission('system:role','system:menu')")
     public Result<List<ConfigItemVO>> list() {
         return Result.ok(configService.list());
     }
 
+    @Operation(summary = "保存系统配置")
     @PutMapping
     @PreAuthorize("@ss.hasPermission('system:role')")
     @OperationLog(module = "后台管理", action = "修改系统设置")

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

@@ -15,6 +15,8 @@ import com.fruitshorts.creator.vo.CreatorAuditReqVO;
 import com.fruitshorts.creator.vo.CreatorQueryReqVO;
 import com.fruitshorts.framework.log.OperationLog;
 import com.fruitshorts.framework.security.SecurityUtils;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import lombok.RequiredArgsConstructor;
 import org.springframework.security.access.prepost.PreAuthorize;
@@ -29,6 +31,7 @@ import org.springframework.web.bind.annotation.RestController;
 import java.util.List;
 
 /** 后台创作者：检索、详情、资质、入驻审核。 */
+@Tag(name = "后台-创作者管理")
 @RestController
 @RequestMapping("/admin/creators")
 @RequiredArgsConstructor
@@ -37,12 +40,14 @@ public class CreatorAdminController {
     private final CreatorService creatorService;
     private final CreatorAccountService creatorAccountService;
 
+    @Operation(summary = "创作者分页查询")
     @GetMapping("/page")
     @PreAuthorize("@ss.hasPermission('creator:list')")
     public Result<PageResult<Creator>> page(CreatorQueryReqVO req) {
         return Result.ok(creatorService.page(req));
     }
 
+    @Operation(summary = "创作者详情")
     @GetMapping("/{id}")
     @PreAuthorize("@ss.hasPermission('creator:list')")
     public Result<Creator> detail(@PathVariable Long id) {
@@ -50,12 +55,14 @@ public class CreatorAdminController {
     }
 
     /** 资质文件：审核前要看证件原件。 */
+    @Operation(summary = "创作者资质文件")
     @GetMapping("/{id}/documents")
     @PreAuthorize("@ss.hasPermission('creator:list')")
     public Result<List<CreatorDocument>> documents(@PathVariable Long id) {
         return Result.ok(creatorService.documents(id));
     }
 
+    @Operation(summary = "创作者入驻审核")
     @PutMapping("/{id}/audit")
     @PreAuthorize("@ss.hasPermission('creator:audit')")
     @OperationLog(module = "创作者管理", action = "入驻审核")
@@ -64,6 +71,7 @@ public class CreatorAdminController {
     }
 
     /** 手工录入创作者主体（C 端申请入驻还没实现，先用它打通链路）。 */
+    @Operation(summary = "手工录入创作者主体")
     @PostMapping
     @PreAuthorize("@ss.hasPermission('creator:audit')")
     @OperationLog(module = "创作者管理", action = "新增创作者")
@@ -72,6 +80,7 @@ public class CreatorAdminController {
     }
 
     /** 开通创作者账号：仅审核通过可开；已开通则幂等返回，不重复建号。 */
+    @Operation(summary = "开通创作者账号（仅审核通过可开通，幂等）")
     @PostMapping("/{id}/account")
     @PreAuthorize("@ss.hasPermission('creator:account')")
     @OperationLog(module = "创作者管理", action = "开通创作者账号")
@@ -81,6 +90,7 @@ public class CreatorAdminController {
     }
 
     /** 重置创作者账号密码：一次性明文返回，旧密码立即失效。 */
+    @Operation(summary = "重置创作者账号密码（一次性明文返回）")
     @PostMapping("/{id}/account/reset-password")
     @PreAuthorize("@ss.hasPermission('creator:account')")
     @OperationLog(module = "创作者管理", action = "重置创作者密码")

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

@@ -11,6 +11,8 @@ import com.fruitshorts.creator.vo.CreatorCenterNoticeVO;
 import com.fruitshorts.creator.vo.CreatorCenterProfileVO;
 import com.fruitshorts.creator.vo.CreatorCenterTargetVO;
 import com.fruitshorts.admin.service.CreatorDashboardService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.security.access.prepost.PreAuthorize;
 import org.springframework.web.bind.annotation.GetMapping;
@@ -28,6 +30,7 @@ import java.util.Map;
  * 归属由 {@link CreatorCenterService#requireCurrentCreator()} 从登录态解析，
  * 查询强制带 `where creator_id = 当前创作者`；访问他人作品统一 403。
  */
+@Tag(name = "创作者中心")
 @RestController
 @RequestMapping("/admin/creator-center")
 @RequiredArgsConstructor
@@ -37,6 +40,7 @@ public class CreatorCenterController {
     private final CreatorDashboardService creatorDashboardService;
 
     /** 当前创作者的主体信息与入驻状态。 */
+    @Operation(summary = "我的创作者资料与入驻状态")
     @GetMapping("/profile")
     @PreAuthorize("@ss.hasPermission('creator-center:view')")
     public Result<CreatorCenterProfileVO> profile() {
@@ -44,6 +48,7 @@ public class CreatorCenterController {
     }
 
     /** 我的作品列表（含最近一次提交的审核进度）。 */
+    @Operation(summary = "我的作品列表（含最近一次审核进度）")
     @GetMapping("/dramas/page")
     @PreAuthorize("@ss.hasPermission('creator-center:view')")
     public Result<PageResult<CreatorCenterDramaVO>> pageMyDramas(CreatorCenterDramaQueryReqVO req) {
@@ -51,6 +56,7 @@ public class CreatorCenterController {
     }
 
     /** 我的作品详情：id 是别人的作品时返回 403，不区分"不存在"。 */
+    @Operation(summary = "我的作品详情")
     @GetMapping("/dramas/{id}")
     @PreAuthorize("@ss.hasPermission('creator-center:view')")
     public Result<CreatorCenterDramaVO> myDrama(@PathVariable Long id) {
@@ -58,6 +64,7 @@ public class CreatorCenterController {
     }
 
     /** 我的通知：入驻审核结果 + 我提交内容的审核结果。 */
+    @Operation(summary = "我的通知（入驻与内容审核结果）")
     @GetMapping("/notices")
     @PreAuthorize("@ss.hasPermission('creator-center:view')")
     public Result<List<CreatorCenterNoticeVO>> notices() {
@@ -65,6 +72,7 @@ public class CreatorCenterController {
     }
 
     /** 我的数据看板：播放 / 完播 / 收藏 / 评论 / 解锁收入概览（只读，只含自己的作品）。 */
+    @Operation(summary = "我的数据看板（播放 / 完播 / 收藏 / 评论 / 解锁收入）")
     @GetMapping("/dashboard")
     @PreAuthorize("@ss.hasPermission('creator-center:stat:view')")
     public Result<Map<String, Object>> dashboard() {
@@ -75,6 +83,7 @@ public class CreatorCenterController {
      * 代看目标下拉的数据源：只有带 `creator-center:impersonate` 的账号（第一阶段 = 超管）能调。
      * 前端拿它渲染顶部的「当前创作者」下拉；没权限的账号不显示下拉，也不会请求这个接口。
      */
+    @Operation(summary = "代看可选创作者列表")
     @GetMapping("/impersonation/targets")
     @PreAuthorize("@ss.hasPermission('creator-center:impersonate')")
     public Result<List<CreatorCenterTargetVO>> impersonationTargets() {

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

@@ -14,6 +14,8 @@ import com.fruitshorts.creator.vo.CreatorDramaEditReqVO;
 import com.fruitshorts.creator.vo.CreatorEpisodeReqVO;
 import com.fruitshorts.creator.vo.CreatorSubmitReqVO;
 import com.fruitshorts.framework.log.OperationLog;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import lombok.RequiredArgsConstructor;
 import org.springframework.security.access.prepost.PreAuthorize;
@@ -34,6 +36,7 @@ import java.util.List;
  * 与 {@link CreatorCenterController} 一样**不接收 creatorId**：归属由登录态解析，
  * 服务层强制 `where creator_id = 当前创作者`，改别人的剧或分集一律 403。
  */
+@Tag(name = "创作者中心-内容与收费")
 @RestController
 @RequestMapping("/admin/creator-center")
 @RequiredArgsConstructor
@@ -42,6 +45,7 @@ public class CreatorContentController {
     private final CreatorContentService creatorContentService;
 
     /** 新建草稿。 */
+    @Operation(summary = "新建作品草稿")
     @PostMapping("/dramas")
     @PreAuthorize("@ss.hasPermission('creator-center:drama:edit')")
     @OperationLog(module = "创作者中心", action = "新建作品")
@@ -50,6 +54,7 @@ public class CreatorContentController {
     }
 
     /** 编辑作品信息（仅草稿 / 已下线可改）。 */
+    @Operation(summary = "编辑作品信息（仅草稿 / 已下线可改）")
     @PutMapping("/dramas/{id}")
     @PreAuthorize("@ss.hasPermission('creator-center:drama:edit')")
     @OperationLog(module = "创作者中心", action = "编辑作品")
@@ -59,6 +64,7 @@ public class CreatorContentController {
     }
 
     /** 分集列表。 */
+    @Operation(summary = "分集列表")
     @GetMapping("/dramas/{id}/episodes")
     @PreAuthorize("@ss.hasPermission('creator-center:view')")
     public Result<List<EpisodeRespVO>> listEpisodes(@PathVariable Long id) {
@@ -66,6 +72,7 @@ public class CreatorContentController {
     }
 
     /** 新增分集（集号不传自动排到最后）。 */
+    @Operation(summary = "新增分集")
     @PostMapping("/dramas/{id}/episodes")
     @PreAuthorize("@ss.hasPermission('creator-center:drama:edit')")
     @OperationLog(module = "创作者中心", action = "新增分集")
@@ -74,6 +81,7 @@ public class CreatorContentController {
     }
 
     /** 编辑分集（时长 / 封面 / 片源 / 排序）。 */
+    @Operation(summary = "编辑分集（时长 / 封面 / 片源）")
     @PutMapping("/dramas/{id}/episodes/{episodeId}")
     @PreAuthorize("@ss.hasPermission('creator-center:drama:edit')")
     @OperationLog(module = "创作者中心", action = "编辑分集")
@@ -84,6 +92,7 @@ public class CreatorContentController {
     }
 
     /** 删除分集。 */
+    @Operation(summary = "删除分集")
     @DeleteMapping("/dramas/{id}/episodes/{episodeId}")
     @PreAuthorize("@ss.hasPermission('creator-center:drama:edit')")
     @OperationLog(module = "创作者中心", action = "删除分集")
@@ -93,6 +102,7 @@ public class CreatorContentController {
     }
 
     /** 批量排序：body 里按新顺序给出分集 id。 */
+    @Operation(summary = "分集批量排序")
     @PutMapping("/dramas/{id}/episodes/sort")
     @PreAuthorize("@ss.hasPermission('creator-center:drama:edit')")
     @OperationLog(module = "创作者中心", action = "调整分集顺序")
@@ -102,6 +112,7 @@ public class CreatorContentController {
     }
 
     /** 提交审核：CREATE / UPDATE / PUBLISH / OFFLINE。 */
+    @Operation(summary = "提交审核（CREATE / UPDATE / PUBLISH / OFFLINE）")
     @PostMapping("/dramas/{id}/submit")
     @PreAuthorize("@ss.hasPermission('creator-center:drama:edit')")
     @OperationLog(module = "创作者中心", action = "提交审核")
@@ -110,6 +121,7 @@ public class CreatorContentController {
     }
 
     /** 撤回自己的提交（撤回后作品退回草稿，可继续编辑）。 */
+    @Operation(summary = "撤回自己的提交")
     @PostMapping("/submissions/{id}/withdraw")
     @PreAuthorize("@ss.hasPermission('creator-center:drama:edit')")
     @OperationLog(module = "创作者中心", action = "撤回提交")
@@ -118,6 +130,7 @@ public class CreatorContentController {
     }
 
     /** 我的提交历史（审核进度）。 */
+    @Operation(summary = "我的提交历史")
     @GetMapping("/dramas/{id}/submissions")
     @PreAuthorize("@ss.hasPermission('creator-center:view')")
     public Result<List<ContentSubmission>> listSubmissions(@PathVariable Long id) {
@@ -125,6 +138,7 @@ public class CreatorContentController {
     }
 
     /** 把上传好的视频产物挂到自己的分集上（产物必须是本人上传的）。 */
+    @Operation(summary = "把上传产物挂到自己的分集上")
     @PostMapping("/dramas/{id}/episodes/{episodeId}/attach")
     @PreAuthorize("@ss.hasPermission('creator-center:upload')")
     @OperationLog(module = "创作者中心", action = "挂载分集视频")
@@ -135,6 +149,7 @@ public class CreatorContentController {
     }
 
     /** 分集收费与试看秒数：读现状。 */
+    @Operation(summary = "分集收费与试看秒数（读）")
     @GetMapping("/dramas/{id}/prices")
     @PreAuthorize("@ss.hasPermission('creator-center:view')")
     public Result<PriceRespVO> priceDetail(@PathVariable Long id) {
@@ -142,6 +157,7 @@ public class CreatorContentController {
     }
 
     /** 分集收费与试看秒数：保存（复用后台同一套 PriceService，改完立即影响付费判定）。 */
+    @Operation(summary = "分集收费与试看秒数（保存）")
     @PutMapping("/dramas/{id}/prices")
     @PreAuthorize("@ss.hasPermission('creator-center:price:update')")
     @OperationLog(module = "创作者中心", action = "配置分集价格")

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

@@ -4,6 +4,8 @@ package com.fruitshorts.admin.controller;
 
 import com.fruitshorts.admin.service.DashboardService;
 import com.fruitshorts.common.pojo.Result;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.security.access.prepost.PreAuthorize;
 import org.springframework.web.bind.annotation.GetMapping;
@@ -18,6 +20,7 @@ import java.util.Map;
  * 指标口径写在 DashboardService 的类注释与 docs/api-phase1.md 里；
  * 取不到数据源的指标返回 null 并在 notes 里说明，不用 0 冒充。
  */
+@Tag(name = "后台-数据看板")
 @RestController
 @RequestMapping("/admin/dashboard")
 @RequiredArgsConstructor
@@ -26,6 +29,7 @@ public class DashboardAdminController {
     private final DashboardService dashboardService;
 
     /** 总览：用户 / 内容 / 播放 / 收入 / 成本。 */
+    @Operation(summary = "运营大盘总览（用户 / 内容 / 播放 / 收入 / 成本）")
     @GetMapping("/overview")
     @PreAuthorize("@ss.hasPermission('dashboard:view')")
     public Result<Map<String, Object>> overview() {
@@ -33,6 +37,7 @@ public class DashboardAdminController {
     }
 
     /** 转码看板：队列积压与失败任务明细。 */
+    @Operation(summary = "转码看板（队列积压与失败任务）")
     @GetMapping("/transcode")
     @PreAuthorize("@ss.hasPermission('dashboard:view')")
     public Result<Map<String, Object>> transcode() {

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

@@ -6,6 +6,8 @@ import com.fruitshorts.common.pojo.Result;
 import com.fruitshorts.content.enums.ContentStatus;
 import com.fruitshorts.content.service.DramaCategoryService;
 import com.fruitshorts.content.vo.DramaCategoryRespVO;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.security.access.prepost.PreAuthorize;
 import org.springframework.web.bind.annotation.GetMapping;
@@ -19,6 +21,7 @@ import java.util.Map;
 /**
  * 字典接口：题材、内容状态等下拉数据。
  */
+@Tag(name = "后台-字典")
 @RestController
 @RequestMapping("/admin/dicts")
 @RequiredArgsConstructor
@@ -26,12 +29,14 @@ public class DictController {
 
     private final DramaCategoryService dramaCategoryService;
 
+    @Operation(summary = "短剧分类字典")
     @GetMapping("/drama-category")
     @PreAuthorize("@ss.hasPermission('drama:list')")
     public Result<List<DramaCategoryRespVO>> dramaCategories() {
         return Result.ok(dramaCategoryService.list());
     }
 
+    @Operation(summary = "内容状态字典")
     @GetMapping("/content-status")
     @PreAuthorize("@ss.hasPermission('drama:list')")
     public Result<List<Map<String, String>>> contentStatus() {

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

@@ -8,6 +8,8 @@ import com.fruitshorts.framework.log.OperationLog;
 import com.fruitshorts.playback.service.DownloadService;
 import com.fruitshorts.playback.vo.DownloadLicenseRespVO;
 import com.fruitshorts.playback.vo.DownloadQueryReqVO;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.security.access.prepost.PreAuthorize;
 import org.springframework.web.bind.annotation.GetMapping;
@@ -20,6 +22,7 @@ import org.springframework.web.bind.annotation.RestController;
 import java.util.Map;
 
 /** 后台下载授权管理。 */
+@Tag(name = "后台-离线下载管理")
 @RestController
 @RequestMapping("/admin/downloads")
 @RequiredArgsConstructor
@@ -27,12 +30,14 @@ public class DownloadAdminController {
 
     private final DownloadService downloadService;
 
+    @Operation(summary = "下载授权分页查询")
     @GetMapping("/page")
     @PreAuthorize("@ss.hasPermission('download:list')")
     public Result<PageResult<DownloadLicenseRespVO>> page(DownloadQueryReqVO req) {
         return Result.ok(downloadService.page(req));
     }
 
+    @Operation(summary = "下载统计")
     @GetMapping("/stats")
     @PreAuthorize("@ss.hasPermission('download:list')")
     public Result<Map<String, Object>> stats() {
@@ -40,6 +45,7 @@ public class DownloadAdminController {
     }
 
     /** 吊销单条授权：用户侧下次联网即失效。 */
+    @Operation(summary = "吊销单条下载授权")
     @PutMapping("/{id}/revoke")
     @PreAuthorize("@ss.hasPermission('download:revoke')")
     @OperationLog(module = "下载管理", action = "吊销下载授权")
@@ -49,6 +55,7 @@ public class DownloadAdminController {
     }
 
     /** 手动触发过期清理，正常情况下由定时任务每天执行。 */
+    @Operation(summary = "手动触发过期授权清理")
     @PostMapping("/cleanup")
     @PreAuthorize("@ss.hasPermission('download:revoke')")
     @OperationLog(module = "下载管理", action = "清理过期下载授权")

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

@@ -8,6 +8,8 @@ import com.fruitshorts.content.vo.DramaCategoryRespVO;
 import com.fruitshorts.content.vo.DramaCategorySaveReqVO;
 import com.fruitshorts.framework.security.SecurityUtils;
 import com.fruitshorts.framework.log.OperationLog;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import lombok.RequiredArgsConstructor;
 import org.springframework.security.access.prepost.PreAuthorize;
@@ -25,6 +27,7 @@ import java.util.List;
 /**
  * 短剧类型管理。类型属于短剧域，权限沿用 drama:*，不再单开权限点。
  */
+@Tag(name = "后台-短剧分类")
 @RestController
 @RequestMapping("/admin/drama-categories")
 @RequiredArgsConstructor
@@ -32,12 +35,14 @@ public class DramaCategoryController {
 
     private final DramaCategoryService dramaCategoryService;
 
+    @Operation(summary = "分类列表")
     @GetMapping
     @PreAuthorize("@ss.hasPermission('drama:list')")
     public Result<List<DramaCategoryRespVO>> list() {
         return Result.ok(dramaCategoryService.list());
     }
 
+    @Operation(summary = "新建分类")
     @PostMapping
     @PreAuthorize("@ss.hasPermission('drama:create')")
     @OperationLog(module = "内容管理", action = "新增短剧类型")
@@ -45,6 +50,7 @@ public class DramaCategoryController {
         return Result.ok(dramaCategoryService.create(req));
     }
 
+    @Operation(summary = "编辑分类")
     @PutMapping("/{id}")
     @PreAuthorize("@ss.hasPermission('drama:update')")
     @OperationLog(module = "内容管理", action = "编辑短剧类型")
@@ -53,6 +59,7 @@ public class DramaCategoryController {
         return Result.ok();
     }
 
+    @Operation(summary = "删除分类")
     @DeleteMapping("/{id}")
     @PreAuthorize("@ss.hasPermission('drama:delete')")
     @OperationLog(module = "内容管理", action = "删除短剧类型")

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

@@ -12,6 +12,8 @@ import com.fruitshorts.content.vo.DramaSaveReqVO;
 import com.fruitshorts.content.vo.DramaStatusReqVO;
 import com.fruitshorts.framework.security.SecurityUtils;
 import com.fruitshorts.framework.log.OperationLog;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import lombok.RequiredArgsConstructor;
 import org.springframework.security.access.prepost.PreAuthorize;
@@ -26,6 +28,7 @@ import org.springframework.web.bind.annotation.RestController;
 
 import java.util.List;
 
+@Tag(name = "后台-短剧管理")
 @RestController
 @RequestMapping("/admin/dramas")
 @RequiredArgsConstructor
@@ -33,18 +36,21 @@ public class DramaController {
 
     private final DramaService dramaService;
 
+    @Operation(summary = "短剧分页查询")
     @GetMapping("/page")
     @PreAuthorize("@ss.hasPermission('drama:list')")
     public Result<PageResult<DramaRespVO>> page(DramaPageReqVO req) {
         return Result.ok(dramaService.page(req));
     }
 
+    @Operation(summary = "短剧详情")
     @GetMapping("/{id}")
     @PreAuthorize("@ss.hasPermission('drama:list')")
     public Result<DramaRespVO> get(@PathVariable Long id) {
         return Result.ok(dramaService.get(id));
     }
 
+    @Operation(summary = "新建短剧")
     @PostMapping
     @PreAuthorize("@ss.hasPermission('drama:create')")
     @OperationLog(module = "内容管理", action = "新建短剧")
@@ -52,6 +58,7 @@ public class DramaController {
         return Result.ok(dramaService.create(req, SecurityUtils.getUserId()));
     }
 
+    @Operation(summary = "编辑短剧")
     @PutMapping("/{id}")
     @PreAuthorize("@ss.hasPermission('drama:update')")
     @OperationLog(module = "内容管理", action = "编辑短剧")
@@ -60,6 +67,7 @@ public class DramaController {
         return Result.ok();
     }
 
+    @Operation(summary = "删除短剧")
     @DeleteMapping("/{id}")
     @PreAuthorize("@ss.hasPermission('drama:delete')")
     @OperationLog(module = "内容管理", action = "删除短剧")
@@ -69,6 +77,7 @@ public class DramaController {
     }
 
     /** 提交审核：内容运营即可操作。 */
+    @Operation(summary = "提交审核")
     @PostMapping("/{id}/submit")
     @PreAuthorize("@ss.hasAnyPermission('drama:review','drama:update')")
     @OperationLog(module = "内容管理", action = "提交审核")
@@ -77,6 +86,7 @@ public class DramaController {
         return Result.ok();
     }
 
+    @Operation(summary = "审核通过")
     @PostMapping("/{id}/approve")
     @PreAuthorize("@ss.hasPermission('drama:review')")
     @OperationLog(module = "内容管理", action = "审核通过")
@@ -85,6 +95,7 @@ public class DramaController {
         return Result.ok();
     }
 
+    @Operation(summary = "审核驳回")
     @PostMapping("/{id}/reject")
     @PreAuthorize("@ss.hasPermission('drama:review')")
     @OperationLog(module = "内容管理", action = "驳回短剧")
@@ -93,6 +104,7 @@ public class DramaController {
         return Result.ok();
     }
 
+    @Operation(summary = "上线")
     @PostMapping("/{id}/publish")
     @PreAuthorize("@ss.hasPermission('drama:review')")
     @OperationLog(module = "内容管理", action = "短剧上线")
@@ -101,6 +113,7 @@ public class DramaController {
         return Result.ok();
     }
 
+    @Operation(summary = "下线")
     @PostMapping("/{id}/offline")
     @PreAuthorize("@ss.hasPermission('drama:review')")
     @OperationLog(module = "内容管理", action = "短剧下线")
@@ -109,6 +122,7 @@ public class DramaController {
         return Result.ok();
     }
 
+    @Operation(summary = "审核记录")
     @GetMapping("/{id}/review-records")
     @PreAuthorize("@ss.hasPermission('drama:list')")
     public Result<List<DramaReviewRecord>> reviewRecords(@PathVariable Long id) {

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

@@ -8,6 +8,8 @@ import com.fruitshorts.commerce.vo.EntitlementGrantReqVO;
 import com.fruitshorts.common.pojo.PageResult;
 import com.fruitshorts.common.pojo.Result;
 import com.fruitshorts.framework.log.OperationLog;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import lombok.RequiredArgsConstructor;
 import org.springframework.security.access.prepost.PreAuthorize;
@@ -21,6 +23,7 @@ import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RestController;
 
 /** 后台权益：检索、人工补发、回收。 */
+@Tag(name = "后台-权益管理")
 @RestController
 @RequestMapping("/admin/entitlements")
 @RequiredArgsConstructor
@@ -28,6 +31,7 @@ public class EntitlementAdminController {
 
     private final EntitlementService entitlementService;
 
+    @Operation(summary = "权益分页查询")
     @GetMapping("/page")
     @PreAuthorize("@ss.hasPermission('entitlement:list')")
     public Result<PageResult<Entitlement>> page(@RequestParam(required = false) Long userId,
@@ -39,6 +43,7 @@ public class EntitlementAdminController {
     }
 
     /** 客服补偿：直接给用户某集/整剧的播放权益。 */
+    @Operation(summary = "补发权益（客服补偿）")
     @PostMapping
     @PreAuthorize("@ss.hasPermission('entitlement:update')")
     @OperationLog(module = "订单管理", action = "人工补发权益")
@@ -50,6 +55,7 @@ public class EntitlementAdminController {
     }
 
     /** 回收权益：退款、违规处置后用。 */
+    @Operation(summary = "回收权益（退款 / 违规处置）")
     @PutMapping("/{id}/revoke")
     @PreAuthorize("@ss.hasPermission('entitlement:update')")
     @OperationLog(module = "订单管理", action = "回收权益")

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

@@ -8,6 +8,8 @@ import com.fruitshorts.content.vo.EpisodeRespVO;
 import com.fruitshorts.content.vo.EpisodeSaveReqVO;
 import com.fruitshorts.content.vo.EpisodeSortReqVO;
 import com.fruitshorts.framework.log.OperationLog;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import lombok.RequiredArgsConstructor;
 import org.springframework.security.access.prepost.PreAuthorize;
@@ -23,6 +25,7 @@ import org.springframework.web.bind.annotation.RestController;
 
 import java.util.List;
 
+@Tag(name = "后台-剧集管理")
 @RestController
 @RequestMapping("/admin/episodes")
 @RequiredArgsConstructor
@@ -30,6 +33,7 @@ public class EpisodeController {
 
     private final EpisodeService episodeService;
 
+    @Operation(summary = "剧集列表")
     @GetMapping
     @PreAuthorize("@ss.hasPermission('episode:list')")
     public Result<List<EpisodeRespVO>> list(@RequestParam Long dramaId,
@@ -37,6 +41,7 @@ public class EpisodeController {
         return Result.ok(episodeService.listByDrama(dramaId, status));
     }
 
+    @Operation(summary = "新建剧集")
     @PostMapping
     @PreAuthorize("@ss.hasPermission('episode:upload')")
     @OperationLog(module = "内容管理", action = "新增剧集")
@@ -44,6 +49,7 @@ public class EpisodeController {
         return Result.ok(episodeService.create(req));
     }
 
+    @Operation(summary = "编辑剧集")
     @PutMapping("/{id}")
     @PreAuthorize("@ss.hasPermission('episode:upload')")
     @OperationLog(module = "内容管理", action = "编辑剧集")
@@ -52,6 +58,7 @@ public class EpisodeController {
         return Result.ok();
     }
 
+    @Operation(summary = "删除剧集")
     @DeleteMapping("/{id}")
     @PreAuthorize("@ss.hasPermission('episode:upload')")
     @OperationLog(module = "内容管理", action = "删除剧集")
@@ -60,6 +67,7 @@ public class EpisodeController {
         return Result.ok();
     }
 
+    @Operation(summary = "剧集排序")
     @PutMapping("/sort")
     @PreAuthorize("@ss.hasPermission('episode:sort')")
     @OperationLog(module = "内容管理", action = "调整剧集顺序")

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

@@ -11,6 +11,8 @@ import com.fruitshorts.media.vo.UploadCompleteReqVO;
 import com.fruitshorts.media.vo.UploadInitReqVO;
 import com.fruitshorts.media.vo.UploadInitRespVO;
 import com.fruitshorts.media.vo.UploadProgressRespVO;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import lombok.RequiredArgsConstructor;
 import org.springframework.security.access.prepost.PreAuthorize;
@@ -26,6 +28,7 @@ import org.springframework.web.multipart.MultipartFile;
 /**
  * 媒资上传（本地存储版）：init 建会话 → chunk 传分片 → complete 合并出地址。
  */
+@Tag(name = "后台-媒资管理")
 @RestController
 @RequestMapping("/admin/media")
 @RequiredArgsConstructor
@@ -33,6 +36,7 @@ public class MediaController {
 
     private final MediaService mediaService;
 
+    @Operation(summary = "初始化分片上传")
     @PostMapping("/upload/init")
     @PreAuthorize("@ss.hasAnyPermission('cover:upload','episode:upload')")
     public Result<UploadInitRespVO> init(@Valid @RequestBody UploadInitReqVO req) {
@@ -41,6 +45,7 @@ public class MediaController {
         return Result.ok(mediaService.init(req, SecurityUtils.getUserId()));
     }
 
+    @Operation(summary = "上传分片")
     @PostMapping("/upload/chunk")
     @PreAuthorize("@ss.hasAnyPermission('cover:upload','episode:upload')")
     public Result<Integer> uploadChunk(@RequestParam String uploadId,
@@ -51,6 +56,7 @@ public class MediaController {
         return Result.ok(index);
     }
 
+    @Operation(summary = "完成上传")
     @PostMapping("/upload/complete")
     @PreAuthorize("@ss.hasAnyPermission('cover:upload','episode:upload')")
     public Result<MediaAssetRespVO> complete(@Valid @RequestBody UploadCompleteReqVO req) {
@@ -59,12 +65,14 @@ public class MediaController {
     }
 
     /** 断点续传：查上传会话进度（只能查自己发起的会话）。 */
+    @Operation(summary = "查询上传进度（断点续传）")
     @GetMapping("/upload/{uploadId}")
     @PreAuthorize("@ss.hasAnyPermission('cover:upload','episode:upload')")
     public Result<UploadProgressRespVO> progress(@PathVariable String uploadId) {
         return Result.ok(mediaService.progress(uploadId, SecurityUtils.getUserId()));
     }
 
+    @Operation(summary = "媒资详情")
     @GetMapping("/{id}")
     @PreAuthorize("@ss.hasAnyPermission('cover:upload','episode:upload')")
     public Result<MediaAssetRespVO> get(@PathVariable Long id) {

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

@@ -7,6 +7,8 @@ import com.fruitshorts.system.service.MenuService;
 import com.fruitshorts.framework.log.OperationLog;
 import com.fruitshorts.system.vo.MenuSaveReqVO;
 import com.fruitshorts.system.vo.MenuVO;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import lombok.RequiredArgsConstructor;
 import org.springframework.security.access.prepost.PreAuthorize;
@@ -21,6 +23,7 @@ import org.springframework.web.bind.annotation.RestController;
 
 import java.util.List;
 
+@Tag(name = "后台-菜单管理")
 @RestController
 @RequestMapping("/admin/menus")
 @RequiredArgsConstructor
@@ -28,12 +31,14 @@ public class MenuController {
 
     private final MenuService menuService;
 
+    @Operation(summary = "菜单树")
     @GetMapping("/tree")
     @PreAuthorize("@ss.hasPermission('system:menu')")
     public Result<List<MenuVO>> tree() {
         return Result.ok(menuService.listAll());
     }
 
+    @Operation(summary = "新建菜单")
     @PostMapping
     @PreAuthorize("@ss.hasPermission('system:menu')")
     @OperationLog(module = "后台管理", action = "新增菜单")
@@ -41,6 +46,7 @@ public class MenuController {
         return Result.ok(menuService.create(req));
     }
 
+    @Operation(summary = "编辑菜单")
     @PutMapping("/{id}")
     @PreAuthorize("@ss.hasPermission('system:menu')")
     @OperationLog(module = "后台管理", action = "编辑菜单")
@@ -49,6 +55,7 @@ public class MenuController {
         return Result.ok();
     }
 
+    @Operation(summary = "删除菜单")
     @DeleteMapping("/{id}")
     @PreAuthorize("@ss.hasPermission('system:menu')")
     @OperationLog(module = "后台管理", action = "删除菜单")

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

@@ -0,0 +1,90 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.admin.controller;
+
+import com.fruitshorts.common.pojo.PageResult;
+import com.fruitshorts.common.pojo.Result;
+import com.fruitshorts.framework.log.OperationLog;
+import com.fruitshorts.system.service.OpsNoticeService;
+import com.fruitshorts.system.vo.NoticeQueryReqVO;
+import com.fruitshorts.system.vo.NoticeRespVO;
+import com.fruitshorts.system.vo.NoticeSaveReqVO;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.validation.Valid;
+import lombok.RequiredArgsConstructor;
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.validation.annotation.Validated;
+import org.springframework.web.bind.annotation.DeleteMapping;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.PutMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+/**
+ * 后台系统公告管理。
+ *
+ * <p>发布后的可见性与 C 端 `GET /app/notices` **共用同一套筛选实现**
+ * （`OpsNoticeService.pageForApp`）：`status=1` + `target ∈ {ALL, USER}` + 已到发布时间 + 未过期。
+ */
+@Tag(name = "后台-系统公告")
+@RestController
+@RequestMapping("/admin/notices")
+@RequiredArgsConstructor
+public class NoticeAdminController {
+
+    private final OpsNoticeService opsNoticeService;
+
+    @Operation(summary = "公告分页查询")
+    @GetMapping("/page")
+    @PreAuthorize("@ss.hasPermission('notice:list')")
+    public Result<PageResult<NoticeRespVO>> page(@Validated NoticeQueryReqVO req) {
+        return Result.ok(opsNoticeService.pageForAdmin(req));
+    }
+
+    @Operation(summary = "公告详情")
+    @GetMapping("/{id}")
+    @PreAuthorize("@ss.hasPermission('notice:list')")
+    public Result<NoticeRespVO> detail(@PathVariable Long id) {
+        return Result.ok(opsNoticeService.detail(id));
+    }
+
+    @Operation(summary = "新建公告（默认发布，C 端立即可见；返回新公告 id，按 §0 以字符串下发）")
+    @PostMapping
+    @PreAuthorize("@ss.hasPermission('notice:update')")
+    @OperationLog(module = "系统公告", action = "新建公告")
+    public Result<Long> create(@Valid @RequestBody NoticeSaveReqVO req) {
+        return Result.ok(opsNoticeService.create(req));
+    }
+
+    @Operation(summary = "编辑公告")
+    @PutMapping("/{id}")
+    @PreAuthorize("@ss.hasPermission('notice:update')")
+    @OperationLog(module = "系统公告", action = "编辑公告")
+    public Result<Void> update(@PathVariable Long id, @Valid @RequestBody NoticeSaveReqVO req) {
+        opsNoticeService.update(id, req);
+        return Result.ok();
+    }
+
+    @Operation(summary = "发布 / 下架（下架后 C 端立即不可见）")
+    @PutMapping("/{id}/status")
+    @PreAuthorize("@ss.hasPermission('notice:update')")
+    @OperationLog(module = "系统公告", action = "公告上下架")
+    public Result<Void> updateStatus(@PathVariable Long id, @RequestParam Integer status) {
+        opsNoticeService.updateStatus(id, status);
+        return Result.ok();
+    }
+
+    @Operation(summary = "删除公告")
+    @DeleteMapping("/{id}")
+    @PreAuthorize("@ss.hasPermission('notice:update')")
+    @OperationLog(module = "系统公告", action = "删除公告")
+    public Result<Void> delete(@PathVariable Long id) {
+        opsNoticeService.delete(id);
+        return Result.ok();
+    }
+}

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

@@ -7,6 +7,8 @@ import com.fruitshorts.common.pojo.Result;
 import com.fruitshorts.system.service.OperationLogService;
 import com.fruitshorts.system.vo.OperationLogPageReqVO;
 import com.fruitshorts.system.vo.OperationLogRespVO;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.security.access.prepost.PreAuthorize;
 import org.springframework.web.bind.annotation.GetMapping;
@@ -14,6 +16,7 @@ import org.springframework.web.bind.annotation.PathVariable;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
 
+@Tag(name = "后台-操作日志")
 @RestController
 @RequestMapping("/admin/operation-logs")
 @RequiredArgsConstructor
@@ -21,12 +24,14 @@ public class OperationLogController {
 
     private final OperationLogService operationLogService;
 
+    @Operation(summary = "操作日志分页查询")
     @GetMapping("/page")
     @PreAuthorize("@ss.hasPermission('log:list')")
     public Result<PageResult<OperationLogRespVO>> page(OperationLogPageReqVO req) {
         return Result.ok(operationLogService.page(req));
     }
 
+    @Operation(summary = "操作日志详情")
     @GetMapping("/{id}")
     @PreAuthorize("@ss.hasPermission('log:list')")
     public Result<OperationLogRespVO> get(@PathVariable Long id) {

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

@@ -10,6 +10,8 @@ import com.fruitshorts.common.pojo.PageResult;
 import com.fruitshorts.common.pojo.Result;
 import com.fruitshorts.framework.log.OperationLog;
 import com.fruitshorts.framework.security.SecurityUtils;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.security.access.prepost.PreAuthorize;
 import org.springframework.web.bind.annotation.GetMapping;
@@ -24,6 +26,7 @@ import java.util.List;
 import java.util.Map;
 
 /** 后台订单：检索、补发、退款回收。 */
+@Tag(name = "后台-订单管理")
 @RestController
 @RequestMapping("/admin/orders")
 @RequiredArgsConstructor
@@ -31,12 +34,14 @@ public class OrderAdminController {
 
     private final OrderService orderService;
 
+    @Operation(summary = "订单分页查询")
     @GetMapping("/page")
     @PreAuthorize("@ss.hasPermission('order:list')")
     public Result<PageResult<Orders>> page(OrderQueryReqVO req) {
         return Result.ok(orderService.page(req));
     }
 
+    @Operation(summary = "订单详情")
     @GetMapping("/{orderNo}")
     @PreAuthorize("@ss.hasPermission('order:list')")
     public Result<Orders> detail(@PathVariable String orderNo) {
@@ -44,6 +49,7 @@ public class OrderAdminController {
     }
 
     /** 订单状态流转流水：支付争议时的证据链。 */
+    @Operation(summary = "订单状态流转流水")
     @GetMapping("/{orderNo}/events")
     @PreAuthorize("@ss.hasPermission('order:list')")
     public Result<List<OrderEvent>> events(@PathVariable String orderNo) {
@@ -51,6 +57,7 @@ public class OrderAdminController {
     }
 
     /** 补发：已支付未交付的订单重新交付；已交付时幂等返回。 */
+    @Operation(summary = "补发订单（已支付未交付重新交付，幂等）")
     @PostMapping("/{orderNo}/compensate")
     @PreAuthorize("@ss.hasPermission('order:update')")
     @OperationLog(module = "订单管理", action = "补发订单")
@@ -59,6 +66,7 @@ public class OrderAdminController {
     }
 
     /** 退款/撤销：回收权益并扣回金币。 */
+    @Operation(summary = "退款 / 撤销（回收权益并扣回金币）")
     @PostMapping("/{orderNo}/refund")
     @PreAuthorize("@ss.hasPermission('order:update')")
     @OperationLog(module = "订单管理", action = "订单退款")

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

@@ -5,6 +5,8 @@ package com.fruitshorts.admin.controller;
 import com.fruitshorts.common.pojo.Result;
 import com.fruitshorts.system.service.PermissionService;
 import com.fruitshorts.system.vo.PermissionGroupVO;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.security.access.prepost.PreAuthorize;
 import org.springframework.web.bind.annotation.GetMapping;
@@ -13,6 +15,7 @@ import org.springframework.web.bind.annotation.RestController;
 
 import java.util.List;
 
+@Tag(name = "后台-权限点")
 @RestController
 @RequestMapping("/admin/permissions")
 @RequiredArgsConstructor
@@ -21,6 +24,7 @@ public class PermissionController {
     private final PermissionService permissionService;
 
     /** 按分组返回权限点，直接喂给前端的角色权限配置页。 */
+    @Operation(summary = "权限点列表（按分组返回）")
     @GetMapping
     @PreAuthorize("@ss.hasPermission('system:role')")
     public Result<List<PermissionGroupVO>> groups() {

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

@@ -7,6 +7,8 @@ import com.fruitshorts.content.service.PriceService;
 import com.fruitshorts.content.vo.PriceRespVO;
 import com.fruitshorts.content.vo.PriceSaveReqVO;
 import com.fruitshorts.framework.log.OperationLog;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.security.access.prepost.PreAuthorize;
 import org.springframework.web.bind.annotation.PutMapping;
@@ -17,6 +19,7 @@ import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RestController;
 
 /** 后台分集价格与免费集配置。 */
+@Tag(name = "后台-分集收费")
 @RestController
 @RequestMapping("/admin/prices")
 @RequiredArgsConstructor
@@ -25,12 +28,14 @@ public class PriceAdminController {
     private final PriceService priceService;
 
     /** 当前价格配置：整剧默认 + 分集明细。 */
+    @Operation(summary = "分集价格配置（整剧默认 + 分集明细）")
     @GetMapping
     @PreAuthorize("@ss.hasPermission('price:update')")
     public Result<PriceRespVO> detail(@RequestParam Long dramaId) {
         return Result.ok(priceService.detail(dramaId));
     }
 
+    @Operation(summary = "保存分集价格配置")
     @PutMapping
     @PreAuthorize("@ss.hasPermission('price:update')")
     @OperationLog(module = "定价管理", action = "配置分集价格")

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

@@ -0,0 +1,90 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.admin.controller;
+
+import com.fruitshorts.commerce.service.ProductService;
+import com.fruitshorts.commerce.vo.ProductQueryReqVO;
+import com.fruitshorts.commerce.vo.ProductRespVO;
+import com.fruitshorts.commerce.vo.ProductSaveReqVO;
+import com.fruitshorts.common.pojo.PageResult;
+import com.fruitshorts.common.pojo.Result;
+import com.fruitshorts.framework.log.OperationLog;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.validation.Valid;
+import lombok.RequiredArgsConstructor;
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.validation.annotation.Validated;
+import org.springframework.web.bind.annotation.DeleteMapping;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.PutMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+/**
+ * 后台商品（金币包）配置。
+ *
+ * <p>商品是 C 端 `POST /app/orders/verify` 的发币依据（按 `store_product_id` 对齐商店商品），
+ * 所以 `code` 与"同平台 store_product_id"的唯一性、以及 type 与金额的匹配都在服务端强校验。
+ */
+@Tag(name = "后台-商品配置")
+@RestController
+@RequestMapping("/admin/products")
+@RequiredArgsConstructor
+public class ProductAdminController {
+
+    private final ProductService productService;
+
+    @Operation(summary = "商品分页查询")
+    @GetMapping("/page")
+    @PreAuthorize("@ss.hasPermission('product:list')")
+    public Result<PageResult<ProductRespVO>> page(@Validated ProductQueryReqVO req) {
+        return Result.ok(productService.page(req));
+    }
+
+    @Operation(summary = "商品详情")
+    @GetMapping("/{id}")
+    @PreAuthorize("@ss.hasPermission('product:list')")
+    public Result<ProductRespVO> detail(@PathVariable Long id) {
+        return Result.ok(productService.detail(id));
+    }
+
+    @Operation(summary = "新建商品（默认下架，需显式上架；返回新商品 id，按 §0 以字符串下发）")
+    @PostMapping
+    @PreAuthorize("@ss.hasPermission('product:update')")
+    @OperationLog(module = "商品配置", action = "新建商品")
+    public Result<Long> create(@Valid @RequestBody ProductSaveReqVO req) {
+        return Result.ok(productService.create(req));
+    }
+
+    @Operation(summary = "编辑商品")
+    @PutMapping("/{id}")
+    @PreAuthorize("@ss.hasPermission('product:update')")
+    @OperationLog(module = "商品配置", action = "编辑商品")
+    public Result<Void> update(@PathVariable Long id, @Valid @RequestBody ProductSaveReqVO req) {
+        productService.update(id, req);
+        return Result.ok();
+    }
+
+    @Operation(summary = "上架 / 下架（会员商品在订阅上线前不能启用）")
+    @PutMapping("/{id}/status")
+    @PreAuthorize("@ss.hasPermission('product:update')")
+    @OperationLog(module = "商品配置", action = "商品上下架")
+    public Result<Void> updateStatus(@PathVariable Long id, @RequestParam Integer status) {
+        productService.updateStatus(id, status);
+        return Result.ok();
+    }
+
+    @Operation(summary = "删除商品")
+    @DeleteMapping("/{id}")
+    @PreAuthorize("@ss.hasPermission('product:update')")
+    @OperationLog(module = "商品配置", action = "删除商品")
+    public Result<Void> delete(@PathVariable Long id) {
+        productService.delete(id);
+        return Result.ok();
+    }
+}

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

@@ -7,6 +7,8 @@ import com.fruitshorts.commerce.service.ReconcileService;
 import com.fruitshorts.common.pojo.PageResult;
 import com.fruitshorts.common.pojo.Result;
 import com.fruitshorts.framework.log.OperationLog;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.security.access.prepost.PreAuthorize;
 import org.springframework.web.bind.annotation.GetMapping;
@@ -18,6 +20,7 @@ import org.springframework.web.bind.annotation.RestController;
 import java.time.LocalDate;
 
 /** 后台对账：手动触发与历史查看。 */
+@Tag(name = "后台-对账")
 @RestController
 @RequestMapping("/admin/reconcile")
 @RequiredArgsConstructor
@@ -25,6 +28,7 @@ public class ReconcileAdminController {
 
     private final ReconcileService reconcileService;
 
+    @Operation(summary = "对账任务列表")
     @GetMapping("/page")
     @PreAuthorize("@ss.hasPermission('order:list')")
     public Result<PageResult<ReconcileTask>> page(@RequestParam(defaultValue = "1") Integer pageIndex,
@@ -33,6 +37,7 @@ public class ReconcileAdminController {
     }
 
     /** 手动对账：默认前一天，可指定日期与渠道。 */
+    @Operation(summary = "手动触发对账")
     @PostMapping("/run")
     @PreAuthorize("@ss.hasPermission('reconcile:run')")
     @OperationLog(module = "订单管理", action = "手动对账")

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

@@ -10,6 +10,8 @@ import com.fruitshorts.interaction.dal.entity.ContentReport;
 import com.fruitshorts.interaction.service.ReportService;
 import com.fruitshorts.interaction.vo.ReportHandleReqVO;
 import com.fruitshorts.interaction.vo.ReportQueryReqVO;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.security.access.prepost.PreAuthorize;
 import org.springframework.web.bind.annotation.GetMapping;
@@ -20,6 +22,7 @@ import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
 
 /** 后台举报工单。 */
+@Tag(name = "后台-举报工单")
 @RestController
 @RequestMapping("/admin/reports")
 @RequiredArgsConstructor
@@ -27,6 +30,7 @@ public class ReportAdminController {
 
     private final ReportService reportService;
 
+    @Operation(summary = "举报工单分页查询")
     @GetMapping("/page")
     @PreAuthorize("@ss.hasPermission('report:list')")
     public Result<PageResult<ContentReport>> page(ReportQueryReqVO req) {
@@ -34,6 +38,7 @@ public class ReportAdminController {
     }
 
     /** 处理工单：结论成立会联动驳回被举报评论，可选择同时封禁被举报用户。 */
+    @Operation(summary = "处理举报工单（可联动驳回评论与封禁用户）")
     @PutMapping("/{id}/handle")
     @PreAuthorize("@ss.hasPermission('report:handle')")
     @OperationLog(module = "内容治理", action = "处理举报")

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

@@ -7,6 +7,8 @@ import com.fruitshorts.system.service.RoleCategoryService;
 import com.fruitshorts.framework.log.OperationLog;
 import com.fruitshorts.system.vo.RoleCategoryRespVO;
 import com.fruitshorts.system.vo.RoleCategorySaveReqVO;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import lombok.RequiredArgsConstructor;
 import org.springframework.security.access.prepost.PreAuthorize;
@@ -21,6 +23,7 @@ import org.springframework.web.bind.annotation.RestController;
 
 import java.util.List;
 
+@Tag(name = "后台-角色分类")
 @RestController
 @RequestMapping("/admin/role-categories")
 @RequiredArgsConstructor
@@ -28,12 +31,14 @@ public class RoleCategoryController {
 
     private final RoleCategoryService roleCategoryService;
 
+    @Operation(summary = "角色分类列表")
     @GetMapping
     @PreAuthorize("@ss.hasPermission('system:role-category')")
     public Result<List<RoleCategoryRespVO>> list() {
         return Result.ok(roleCategoryService.list());
     }
 
+    @Operation(summary = "新建角色分类")
     @PostMapping
     @PreAuthorize("@ss.hasPermission('system:role-category')")
     @OperationLog(module = "后台管理", action = "新增角色分类")
@@ -41,6 +46,7 @@ public class RoleCategoryController {
         return Result.ok(roleCategoryService.create(req));
     }
 
+    @Operation(summary = "编辑角色分类")
     @PutMapping("/{id}")
     @PreAuthorize("@ss.hasPermission('system:role-category')")
     @OperationLog(module = "后台管理", action = "编辑角色分类")
@@ -49,6 +55,7 @@ public class RoleCategoryController {
         return Result.ok();
     }
 
+    @Operation(summary = "删除角色分类")
     @DeleteMapping("/{id}")
     @PreAuthorize("@ss.hasPermission('system:role-category')")
     @OperationLog(module = "后台管理", action = "删除角色分类")

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

@@ -9,6 +9,8 @@ import com.fruitshorts.framework.log.OperationLog;
 import com.fruitshorts.system.vo.RolePermissionSaveReqVO;
 import com.fruitshorts.system.vo.RoleRespVO;
 import com.fruitshorts.system.vo.RoleSaveReqVO;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import lombok.RequiredArgsConstructor;
 import org.springframework.security.access.prepost.PreAuthorize;
@@ -24,6 +26,7 @@ import org.springframework.web.bind.annotation.RestController;
 
 import java.util.List;
 
+@Tag(name = "后台-角色管理")
 @RestController
 @RequestMapping("/admin/roles")
 @RequiredArgsConstructor
@@ -31,6 +34,7 @@ public class RoleController {
 
     private final RoleService roleService;
 
+    @Operation(summary = "角色分页查询")
     @GetMapping("/page")
     @PreAuthorize("@ss.hasPermission('system:role')")
     public Result<PageResult<RoleRespVO>> page(@RequestParam(required = false) String keyword,
@@ -39,17 +43,20 @@ public class RoleController {
         return Result.ok(roleService.page(keyword, pageIndex, pageSize));
     }
 
+    @Operation(summary = "角色下拉列表")
     @GetMapping("/list")
     public Result<List<RoleRespVO>> list() {
         return Result.ok(roleService.listAll());
     }
 
+    @Operation(summary = "角色详情")
     @GetMapping("/{id}")
     @PreAuthorize("@ss.hasPermission('system:role')")
     public Result<RoleRespVO> get(@PathVariable Long id) {
         return Result.ok(roleService.get(id));
     }
 
+    @Operation(summary = "新建角色")
     @PostMapping
     @PreAuthorize("@ss.hasPermission('system:role')")
     @OperationLog(module = "后台管理", action = "新增角色")
@@ -57,6 +64,7 @@ public class RoleController {
         return Result.ok(roleService.create(req));
     }
 
+    @Operation(summary = "编辑角色")
     @PutMapping("/{id}")
     @PreAuthorize("@ss.hasPermission('system:role')")
     @OperationLog(module = "后台管理", action = "编辑角色")
@@ -65,6 +73,7 @@ public class RoleController {
         return Result.ok();
     }
 
+    @Operation(summary = "删除角色")
     @DeleteMapping("/{id}")
     @PreAuthorize("@ss.hasPermission('system:role')")
     @OperationLog(module = "后台管理", action = "删除角色")
@@ -73,12 +82,14 @@ public class RoleController {
         return Result.ok();
     }
 
+    @Operation(summary = "角色已授权限")
     @GetMapping("/{id}/permissions")
     @PreAuthorize("@ss.hasPermission('system:role')")
     public Result<List<String>> permissions(@PathVariable Long id) {
         return Result.ok(roleService.listCodesByRoleId(id));
     }
 
+    @Operation(summary = "保存角色权限")
     @PutMapping("/{id}/permissions")
     @PreAuthorize("@ss.hasPermission('system:role')")
     @OperationLog(module = "后台管理", action = "修改角色权限")

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

@@ -8,6 +8,8 @@ import com.fruitshorts.framework.log.OperationLog;
 import com.fruitshorts.interaction.dal.entity.SensitiveWord;
 import com.fruitshorts.interaction.service.SensitiveWordService;
 import com.fruitshorts.interaction.vo.SensitiveWordReqVO;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import lombok.RequiredArgsConstructor;
 import org.springframework.security.access.prepost.PreAuthorize;
@@ -22,6 +24,7 @@ import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RestController;
 
 /** 后台敏感词库。改动即时生效（服务端词库缓存会失效重建）。 */
+@Tag(name = "后台-敏感词库")
 @RestController
 @RequestMapping("/admin/sensitive-words")
 @RequiredArgsConstructor
@@ -29,6 +32,7 @@ public class SensitiveWordAdminController {
 
     private final SensitiveWordService sensitiveWordService;
 
+    @Operation(summary = "敏感词分页查询")
     @GetMapping("/page")
     @PreAuthorize("@ss.hasPermission('sensitive-word:list')")
     public Result<PageResult<SensitiveWord>> page(@RequestParam(required = false) String keyword,
@@ -39,6 +43,7 @@ public class SensitiveWordAdminController {
         return Result.ok(sensitiveWordService.page(keyword, category, level, pageIndex, pageSize));
     }
 
+    @Operation(summary = "新增敏感词")
     @PostMapping
     @PreAuthorize("@ss.hasPermission('sensitive-word:update')")
     @OperationLog(module = "内容治理", action = "新增敏感词")
@@ -46,6 +51,7 @@ public class SensitiveWordAdminController {
         return Result.ok(sensitiveWordService.create(req));
     }
 
+    @Operation(summary = "编辑敏感词")
     @PutMapping("/{id}")
     @PreAuthorize("@ss.hasPermission('sensitive-word:update')")
     @OperationLog(module = "内容治理", action = "修改敏感词")
@@ -54,6 +60,7 @@ public class SensitiveWordAdminController {
         return Result.ok();
     }
 
+    @Operation(summary = "删除敏感词")
     @DeleteMapping("/{id}")
     @PreAuthorize("@ss.hasPermission('sensitive-word:update')")
     @OperationLog(module = "内容治理", action = "删除敏感词")

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

@@ -10,6 +10,8 @@ import com.fruitshorts.creator.vo.SubmissionAuditReqVO;
 import com.fruitshorts.creator.vo.SubmissionQueryReqVO;
 import com.fruitshorts.framework.log.OperationLog;
 import com.fruitshorts.framework.security.SecurityUtils;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.security.access.prepost.PreAuthorize;
 import org.springframework.web.bind.annotation.GetMapping;
@@ -20,6 +22,7 @@ import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
 
 /** 后台内容提交审核：检索、详情、审核（通过 / 驳回 / 撤回）。 */
+@Tag(name = "后台-内容提交审核")
 @RestController
 @RequestMapping("/admin/submissions")
 @RequiredArgsConstructor
@@ -27,18 +30,21 @@ public class SubmissionAdminController {
 
     private final ContentSubmissionService submissionService;
 
+    @Operation(summary = "内容提交分页查询")
     @GetMapping("/page")
     @PreAuthorize("@ss.hasPermission('submission:list')")
     public Result<PageResult<ContentSubmission>> page(SubmissionQueryReqVO req) {
         return Result.ok(submissionService.page(req));
     }
 
+    @Operation(summary = "内容提交详情")
     @GetMapping("/{id}")
     @PreAuthorize("@ss.hasPermission('submission:list')")
     public Result<ContentSubmission> detail(@PathVariable Long id) {
         return Result.ok(submissionService.getExisting(id));
     }
 
+    @Operation(summary = "内容提交审核")
     @PutMapping("/{id}/audit")
     @PreAuthorize("@ss.hasPermission('submission:audit')")
     @OperationLog(module = "内容审核", action = "提交审核")

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

@@ -11,6 +11,8 @@ import com.fruitshorts.common.pojo.Result;
 import com.fruitshorts.framework.log.OperationLog;
 import com.fruitshorts.framework.security.SecurityUtils;
 import com.fruitshorts.user.dal.mapper.AppUserMapper;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import lombok.RequiredArgsConstructor;
 import org.springframework.security.access.prepost.PreAuthorize;
@@ -25,6 +27,7 @@ import org.springframework.web.bind.annotation.RestController;
 import java.util.List;
 
 /** 后台钱包：人工补币/扣回，全部进流水且必须带幂等键。 */
+@Tag(name = "后台-金币钱包")
 @RestController
 @RequestMapping("/admin/wallets")
 @RequiredArgsConstructor
@@ -33,6 +36,7 @@ public class WalletAdminController {
     private final WalletService walletService;
     private final AppUserMapper appUserMapper;
 
+    @Operation(summary = "金币流水")
     @GetMapping("/{userId}/ledger")
     @PreAuthorize("@ss.hasPermission('order:list')")
     public Result<List<CoinLedger>> ledger(@PathVariable Long userId,
@@ -40,6 +44,7 @@ public class WalletAdminController {
         return Result.ok(walletService.recentLedger(userId, limit));
     }
 
+    @Operation(summary = "人工补币")
     @PostMapping("/coins")
     @PreAuthorize("@ss.hasPermission('wallet:update')")
     @OperationLog(module = "订单管理", action = "人工补币")

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

@@ -0,0 +1,29 @@
+# Author: fruit.com.cn
+#
+# 生产 profile（--spring.profiles.active=prod）：
+#   1) 集中生产开关，不在这里写任何密钥 —— 密钥一律环境变量注入；
+#   2) 密钥缺失/还是 dev 默认值/签名没开 → ProdSecretGuard 直接让启动失败（fail-fast）。
+server:
+  port: ${SERVER_PORT:8080}
+  tomcat:
+    # 生产前置反代，真实 IP 从 X-Forwarded-* 取
+    remoteip:
+      remote-ip-header: X-Forwarded-For
+      protocol-header: X-Forwarded-Proto
+
+spring:
+  lifecycle:
+    timeout-per-shutdown-phase: 30s
+
+fruitshorts:
+  media:
+    # 生产必须开启播放地址签名（docs/12-上线检查清单）
+    signature-required: true
+  cors:
+    # 后台只允许显式配置的来源（本地开发用 base 里的 localhost:3005）
+    allowed-origins: ${CORS_ALLOWED_ORIGINS:}
+
+logging:
+  level:
+    root: info
+    com.fruitshorts: info

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

@@ -10,7 +10,8 @@ spring:
     exclude: org.springframework.boot.autoconfigure.security.servlet.UserDetailsServiceAutoConfiguration
   datasource:
     driver-class-name: org.postgresql.Driver
-    url: jdbc:postgresql://127.0.0.1:5432/fruitshorts
+    # 地址外置：生产用 DB_URL 注入（prod profile 会校验非空）
+    url: ${DB_URL:jdbc:postgresql://127.0.0.1:5432/fruitshorts}
     username: ${DB_USER:fruitshorts}
     password: ${DB_PASSWORD:fruitshorts}
   jackson:
@@ -28,23 +29,35 @@ mybatis-plus:
   global-config:
     banner: false
     db-config:
-      id-type: auto
+      # 主键由应用侧雪花算法生成（S0），数据库不再自增
+      id-type: assign_id
       logic-delete-field: deleted
       logic-delete-value: 1
       logic-not-delete-value: 0
+    sequence:
+      # 单机开发用固定值；上多实例前必须改成按实例分配（环境变量注入），否则会撞 ID
+      worker-id: 1
+      datacenter-id: 1
 
 fruitshorts:
   media:
-    # 本地媒资目录（相对应用启动目录），通过 /files/** 访问
-    root-dir: ./data/uploads
+    # 媒资目录：容器里指向挂载卷；本地默认 ./data/uploads
+    root-dir: ${MEDIA_ROOT_DIR:./data/uploads}
     public-prefix: /files
     chunk-size: 5242880
     max-file-size: 2147483648
+    signature-secret: ${MEDIA_SIGNATURE_SECRET:fruitshorts-media-dev-secret-change-me-in-production-32b}
+    signature-required: ${MEDIA_SIGNATURE_REQUIRED:false}
+    signature-ttl-minutes: 15
   jwt:
+    # 双密钥都要外置：只配 admin 而漏配 app，生产会静默用 dev 默认值（prod fail-fast 会拦住）
     admin-secret: ${JWT_ADMIN_SECRET:fruitshorts-admin-dev-secret-change-me-in-production-32b}
     admin-ttl-hours: 12
+    app-secret: ${JWT_APP_SECRET:fruitshorts-app-dev-secret-change-me-in-production-32bytes}
+    app-access-ttl-minutes: 120
+    app-refresh-ttl-days: 30
   cors:
-    allowed-origins: http://localhost:3005,http://127.0.0.1:3005
+    allowed-origins: ${CORS_ALLOWED_ORIGINS:http://localhost:3005,http://127.0.0.1:3005}
 
 springdoc:
   swagger-ui:

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

@@ -0,0 +1,61 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.admin.controller;
+
+import org.junit.jupiter.api.Test;
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.web.bind.annotation.DeleteMapping;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.PutMapping;
+
+import java.lang.reflect.Method;
+import java.util.ArrayList;
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/**
+ * 权限点注解检查：新增的写接口必须带 `@PreAuthorize`，且权限点与契约一致。
+ *
+ * <p>为什么用反射而不是起 Spring 上下文：{@code @PreAuthorize} 靠方法代理生效，
+ * 切片测试（standalone MockMvc）不会走代理，跑出来是"永远通过"的假绿；
+ * 直接检查注解，能真正确认"忘写权限点"这类问题（无权限点被拒的前提是**有**权限点）。
+ */
+class AdminPermissionAnnotationTest {
+
+    @Test
+    void should_declare_expected_permissions_when_checking_new_admin_endpoints() {
+        assertThat(permissionsOf(ProductAdminController.class))
+                .containsExactlyInAnyOrder("product:list", "product:list",
+                        "product:update", "product:update", "product:update", "product:update");
+        assertThat(permissionsOf(NoticeAdminController.class))
+                .containsExactlyInAnyOrder("notice:list", "notice:list",
+                        "notice:update", "notice:update", "notice:update", "notice:update");
+    }
+
+    /** 收集控制器里所有映射方法的 @PreAuthorize 权限点（缺失则记为 MISSING，便于断言直接看到）。 */
+    private List<String> permissionsOf(Class<?> controller) {
+        List<String> permissions = new ArrayList<>();
+        for (Method method : controller.getDeclaredMethods()) {
+            if (!isEndpoint(method)) {
+                continue;
+            }
+            PreAuthorize annotation = method.getAnnotation(PreAuthorize.class);
+            permissions.add(annotation == null ? "MISSING" : extract(annotation.value()));
+        }
+        return permissions;
+    }
+
+    private boolean isEndpoint(Method method) {
+        return method.isAnnotationPresent(GetMapping.class) || method.isAnnotationPresent(PostMapping.class)
+                || method.isAnnotationPresent(PutMapping.class) || method.isAnnotationPresent(DeleteMapping.class);
+    }
+
+    /** 从 `@ss.hasPermission('product:list')` 里取出权限码。 */
+    private String extract(String expression) {
+        int start = expression.indexOf('\'');
+        int end = expression.lastIndexOf('\'');
+        return start >= 0 && end > start ? expression.substring(start + 1, end) : expression;
+    }
+}

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

@@ -0,0 +1,117 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.admin.controller;
+
+import com.fruitshorts.admin.support.ControllerContractSupport;
+import com.fruitshorts.common.exception.ErrorCode;
+import com.fruitshorts.common.exception.ServiceException;
+import com.fruitshorts.common.pojo.PageResult;
+import com.fruitshorts.system.service.OpsNoticeService;
+import com.fruitshorts.system.vo.NoticeRespVO;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.http.MediaType;
+import org.springframework.test.web.servlet.MockMvc;
+
+import java.util.List;
+
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.BDDMockito.given;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.put;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+/** `/admin/notices` 接入层契约。 */
+class NoticeAdminControllerContractTest {
+
+    private OpsNoticeService opsNoticeService;
+    private MockMvc mockMvc;
+
+    @BeforeEach
+    void setUp() {
+        opsNoticeService = mock(OpsNoticeService.class);
+        mockMvc = ControllerContractSupport.mockMvcOf(new NoticeAdminController(opsNoticeService));
+    }
+
+    @Test
+    void should_return_paged_notices_when_page_is_requested() throws Exception {
+        NoticeRespVO vo = new NoticeRespVO();
+        vo.setId(1L);
+        vo.setTitle("开服公告");
+        vo.setTarget("ALL");
+        vo.setTargetText("全部用户");
+        vo.setType("SYSTEM");
+        vo.setTypeText("系统");
+        vo.setStatus(1);
+        vo.setStatusText("已发布");
+        given(opsNoticeService.pageForAdmin(any())).willReturn(new PageResult<>(1L, List.of(vo)));
+
+        mockMvc.perform(get("/admin/notices/page").param("status", "1"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(0))
+                .andExpect(jsonPath("$.data.list[0].title").value("开服公告"))
+                .andExpect(jsonPath("$.data.list[0].statusText").value("已发布"))
+                .andExpect(jsonPath("$.data.list[0].targetText").value("全部用户"));
+    }
+
+    @Test
+    void should_return_new_id_when_creating_notice() throws Exception {
+        given(opsNoticeService.create(any())).willReturn(66L);
+
+        mockMvc.perform(post("/admin/notices")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"title\":\"开服公告\",\"content\":\"欢迎\",\"target\":\"ALL\"}"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(0))
+                // id 以字符串回：雪花 id 直接下发数字会被浏览器四舍五入
+                .andExpect(jsonPath("$.data").value("66"))
+                .andExpect(jsonPath("$.data").isString());
+    }
+
+    @Test
+    void should_send_string_id_when_notice_id_exceeds_js_safe_integer() throws Exception {
+        NoticeRespVO vo = new NoticeRespVO();
+        vo.setId(2111011206851596290L);
+        vo.setTitle("开服公告");
+        given(opsNoticeService.pageForAdmin(any())).willReturn(new PageResult<>(1L, List.of(vo)));
+
+        mockMvc.perform(get("/admin/notices/page"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.data.list[0].id").value("2111011206851596290"))
+                .andExpect(jsonPath("$.data.list[0].id").isString());
+    }
+
+    @Test
+    void should_return_bad_request_when_title_is_missing() throws Exception {
+        mockMvc.perform(post("/admin/notices")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"content\":\"没有标题\"}"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(ErrorCode.BAD_REQUEST.getCode()));
+    }
+
+    @Test
+    void should_map_not_found_when_notice_does_not_exist() throws Exception {
+        given(opsNoticeService.detail(any())).willThrow(
+                new ServiceException(ErrorCode.DATA_NOT_FOUND, "公告不存在"));
+
+        mockMvc.perform(get("/admin/notices/404"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(ErrorCode.DATA_NOT_FOUND.getCode()))
+                .andExpect(jsonPath("$.message").value("公告不存在"));
+    }
+
+    @Test
+    void should_pass_status_when_publishing_or_taking_down_notice() throws Exception {
+        mockMvc.perform(put("/admin/notices/9/status").param("status", "0"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(0));
+
+        verify(opsNoticeService).updateStatus(eq(9L), eq(0));
+    }
+}

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

@@ -0,0 +1,123 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.admin.controller;
+
+import com.fruitshorts.admin.support.ControllerContractSupport;
+import com.fruitshorts.commerce.service.ProductService;
+import com.fruitshorts.commerce.vo.ProductRespVO;
+import com.fruitshorts.common.exception.ErrorCode;
+import com.fruitshorts.common.exception.ServiceException;
+import com.fruitshorts.common.pojo.PageResult;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.http.MediaType;
+import org.springframework.test.web.servlet.MockMvc;
+
+import java.util.List;
+
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.BDDMockito.given;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.put;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+/** `/admin/products` 接入层契约：路由、参数绑定、统一响应体、错误码映射。 */
+class ProductAdminControllerContractTest {
+
+    private ProductService productService;
+    private MockMvc mockMvc;
+
+    @BeforeEach
+    void setUp() {
+        productService = mock(ProductService.class);
+        mockMvc = ControllerContractSupport.mockMvcOf(new ProductAdminController(productService));
+    }
+
+    @Test
+    void should_return_paged_products_when_page_is_requested() throws Exception {
+        ProductRespVO vo = new ProductRespVO();
+        vo.setId(1L);
+        vo.setCode("coin_100");
+        vo.setName("100 金币");
+        vo.setType("COIN_PACK");
+        vo.setTypeText("金币包");
+        vo.setStatus(1);
+        vo.setStatusText("已上架");
+        vo.setTotalCoin(100L);
+        given(productService.page(any())).willReturn(new PageResult<>(1L, List.of(vo)));
+
+        mockMvc.perform(get("/admin/products/page").param("type", "COIN_PACK"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(0))
+                .andExpect(jsonPath("$.data.total").value(1))
+                .andExpect(jsonPath("$.data.list[0].code").value("coin_100"))
+                // 状态中文由服务端给（前端不写死）
+                .andExpect(jsonPath("$.data.list[0].statusText").value("已上架"))
+                .andExpect(jsonPath("$.data.list[0].typeText").value("金币包"));
+    }
+
+    @Test
+    void should_return_new_id_when_creating_product() throws Exception {
+        given(productService.create(any())).willReturn(88L);
+
+        mockMvc.perform(post("/admin/products")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"code\":\"coin_100\",\"name\":\"100 金币\",\"coinAmount\":100}"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(0))
+                // id 以字符串回：雪花 id 直接下发数字会被浏览器四舍五入
+                .andExpect(jsonPath("$.data").value("88"))
+                .andExpect(jsonPath("$.data").isString());
+    }
+
+    @Test
+    void should_send_string_id_when_product_id_exceeds_js_safe_integer() throws Exception {
+        ProductRespVO vo = new ProductRespVO();
+        // 一个真实量级的雪花 id（> 2^53-1），前端按字符串原样回传才不会被四舍五入
+        vo.setId(2111010131922784257L);
+        vo.setCode("coin_big_id");
+        given(productService.page(any())).willReturn(new PageResult<>(1L, List.of(vo)));
+
+        mockMvc.perform(get("/admin/products/page"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.data.list[0].id").value("2111010131922784257"))
+                .andExpect(jsonPath("$.data.list[0].id").isString());
+    }
+
+    @Test
+    void should_return_bad_request_when_code_is_missing() throws Exception {
+        // @NotBlank 校验失败 → 全局异常处理器给出 400 信封
+        mockMvc.perform(post("/admin/products")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"name\":\"没有编码\"}"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(ErrorCode.BAD_REQUEST.getCode()));
+    }
+
+    @Test
+    void should_map_data_exists_when_store_product_id_is_duplicated() throws Exception {
+        given(productService.create(any())).willThrow(
+                new ServiceException(ErrorCode.DATA_EXISTS, "该平台下商店商品 id 已被占用：coin_100"));
+
+        mockMvc.perform(post("/admin/products")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"code\":\"coin_x\",\"name\":\"X\",\"storeProductId\":\"coin_100\",\"coinAmount\":100}"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(ErrorCode.DATA_EXISTS.getCode()))
+                .andExpect(jsonPath("$.message").value("该平台下商店商品 id 已被占用：coin_100"));
+    }
+
+    @Test
+    void should_pass_status_when_updating_product_status() throws Exception {
+        mockMvc.perform(put("/admin/products/8/status").param("status", "1"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(0));
+
+        verify(productService).updateStatus(eq(8L), eq(1));
+    }
+}

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

@@ -0,0 +1,99 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.admin.controller;
+
+import com.fruitshorts.admin.support.ControllerContractSupport;
+import com.fruitshorts.commerce.dal.entity.ReconcileTask;
+import com.fruitshorts.commerce.service.ReconcileService;
+import com.fruitshorts.common.pojo.PageResult;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.test.web.servlet.MockMvc;
+
+import java.math.BigDecimal;
+import java.time.LocalDate;
+import java.util.List;
+
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.BDDMockito.given;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+/**
+ * `/admin/reconcile/*` 接入层契约（api-phase1.md §2.6 已冻结）：路由、参数绑定、统一响应体，
+ * 以及"取不到的指标是 null 而不是 0"这条硬口径在 JSON 里确实体现出来。
+ */
+class ReconcileAdminControllerContractTest {
+
+    private ReconcileService reconcileService;
+    private MockMvc mockMvc;
+
+    @BeforeEach
+    void setUp() {
+        reconcileService = mock(ReconcileService.class);
+        mockMvc = ControllerContractSupport.mockMvcOf(new ReconcileAdminController(reconcileService));
+    }
+
+    @Test
+    void should_pass_date_and_platform_when_manual_reconcile_is_triggered() throws Exception {
+        given(reconcileService.run(eq(LocalDate.of(2026, 10, 15)), eq("GOOGLE")))
+                .willReturn(task());
+
+        mockMvc.perform(post("/admin/reconcile/run")
+                        .param("bizDate", "2026-10-15")
+                        .param("platform", "GOOGLE"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(0))
+                .andExpect(jsonPath("$.data.bizDate").value("2026-10-15"))
+                .andExpect(jsonPath("$.data.platform").value("GOOGLE"))
+                .andExpect(jsonPath("$.data.diffCount").value(2))
+                // 契约强制：商店侧结算金额无数据源 → null（不是 0）
+                .andExpect(jsonPath("$.data.storeAmountSum").value(org.hamcrest.Matchers.nullValue()))
+                .andExpect(jsonPath("$.data.notes").value(org.hamcrest.Matchers.containsString("财务报告")));
+
+        verify(reconcileService).run(LocalDate.of(2026, 10, 15), "GOOGLE");
+    }
+
+    @Test
+    void should_default_to_yesterday_when_biz_date_is_absent() throws Exception {
+        given(reconcileService.run(any(), any())).willReturn(task());
+
+        mockMvc.perform(post("/admin/reconcile/run"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(0));
+
+        // 不传 bizDate → 传 null 给 service（由 service 决定"默认前一天"）
+        verify(reconcileService).run(eq(null), eq(null));
+    }
+
+    @Test
+    void should_return_paged_history_when_page_is_requested() throws Exception {
+        given(reconcileService.page(1, 10)).willReturn(new PageResult<>(1L, List.of(task())));
+
+        mockMvc.perform(get("/admin/reconcile/page").param("pageIndex", "1").param("pageSize", "10"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(0))
+                .andExpect(jsonPath("$.data.total").value(1))
+                .andExpect(jsonPath("$.data.list[0].status").value("SUCCESS"));
+    }
+
+    private ReconcileTask task() {
+        ReconcileTask task = new ReconcileTask();
+        task.setId(1L);
+        task.setBizDate(LocalDate.of(2026, 10, 15));
+        task.setPlatform("GOOGLE");
+        task.setTotalCount(3);
+        task.setMatchedCount(1);
+        task.setDiffCount(2);
+        task.setAmountSum(new BigDecimal("14.97"));
+        task.setStoreAmountSum(null);
+        task.setStatus(ReconcileService.STATUS_SUCCESS);
+        task.setNotes("商店结算金额/手续费/税需从 Play Console 财务报告获取，故 storeAmountSum 为 null。");
+        return task;
+    }
+}

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

@@ -0,0 +1,46 @@
+// Author: fruit.com.cn
+package com.fruitshorts.admin.support;
+
+import com.fruitshorts.framework.log.AccessDeniedRecorder;
+import com.fruitshorts.framework.web.JacksonLongToStringConfig;
+import com.fruitshorts.framework.web.GlobalExceptionHandler;
+import com.fasterxml.jackson.databind.SerializationFeature;
+import com.fasterxml.jackson.databind.json.JsonMapper;
+import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule;
+import org.mockito.Mockito;
+import org.springframework.beans.factory.ObjectProvider;
+import org.springframework.http.converter.json.MappingJackson2HttpMessageConverter;
+import org.springframework.test.web.servlet.MockMvc;
+import org.springframework.test.web.servlet.setup.MockMvcBuilders;
+
+/**
+ * 控制器契约测试的公共装配：真控制器 + 真全局异常处理器 + 真校验器，**不启 Spring 容器**。
+ *
+ * <p>为什么不用 {@code @WebMvcTest}：{@code AppApiApplication} 上挂着
+ * {@code @MapperScan("com.fruitshorts.**.dal.mapper")}，而切片测试不装配 DataSource / MyBatis，
+ * 扫描出的 Mapper 工厂会因为缺少 {@code SqlSessionFactory} 直接报错；要绕开就得再加一套测试专用的
+ * 引导配置。这里的 standaloneSetup 同样只装 Web 层（路由、参数绑定、消息转换、异常处理），
+ * 覆盖面不变而更轻、更稳。
+ */
+public final class ControllerContractSupport {
+
+    private ControllerContractSupport() {
+    }
+
+    /** 组装一个只含指定控制器与全局异常处理的 MockMvc。 */
+    @SuppressWarnings("unchecked")
+    public static MockMvc mockMvcOf(Object controller) {
+        AccessDeniedRecorder recorder = new AccessDeniedRecorder(Mockito.mock(ObjectProvider.class));
+        return MockMvcBuilders.standaloneSetup(controller)
+                .setControllerAdvice(new GlobalExceptionHandler(recorder))
+                // 与 Spring Boot 的 Jackson 配置对齐：时间按 ISO 字符串输出而不是数组，
+                // 否则契约测试断言 LocalDate/LocalDateTime 时会看到 [2026,10,15] 这种形态。
+                .setMessageConverters(new MappingJackson2HttpMessageConverter(JsonMapper.builder()
+                        .addModule(new JavaTimeModule())
+                        // 与生产一致：Long/long 一律输出成字符串（见 JacksonLongToStringConfig）
+                        .addModule(JacksonLongToStringConfig.longToStringModule())
+                        .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS)
+                        .build()))
+                .build();
+    }
+}

fruitshorts-admin-api/src/test/java/com/fruitshorts/admin/web/LongToStringSerializationTest.java

@@ -0,0 +1,132 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.admin.web;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fruitshorts.admin.controller.ProductAdminController;
+import com.fruitshorts.admin.support.ControllerContractSupport;
+import com.fruitshorts.commerce.service.ProductService;
+import com.fruitshorts.common.pojo.PageResult;
+import com.fruitshorts.framework.web.JacksonLongToStringConfig;
+import lombok.Data;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.http.converter.json.Jackson2ObjectMapperBuilder;
+import org.springframework.test.web.servlet.MockMvc;
+
+import java.util.List;
+import java.util.Map;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.put;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+/**
+ * J1 全局 ID 字符串化：Long/long 一律以 JSON 字符串下发，覆盖普通字段 / 嵌套对象 / List / Map 值 / 分页 list；
+ * 同时保证 Integer/int 与分页 total 仍是数字，且**字符串形式的 id 能反序列化回 Long**。
+ */
+class LongToStringSerializationTest {
+
+    /** 雪花量级的 id（> 2^53-1），裸数字下发会被 JS 四舍五入 */
+    private static final long SNOWFLAKE_ID = 2111012753262120962L;
+
+    private ObjectMapper mapper;
+    private ProductService productService;
+    private MockMvc mockMvc;
+
+    @BeforeEach
+    void setUp() {
+        // 用生产同一套装配（Jackson2ObjectMapperBuilder + 我们的 customizer），而不是手搓一个 mapper，
+        // 否则这条测试可能"测的是测试自己"
+        Jackson2ObjectMapperBuilder builder = new Jackson2ObjectMapperBuilder();
+        new JacksonLongToStringConfig().longToStringCustomizer().customize(builder);
+        mapper = builder.build();
+
+        productService = mock(ProductService.class);
+        mockMvc = ControllerContractSupport.mockMvcOf(new ProductAdminController(productService));
+    }
+
+    @Test
+    void should_render_long_as_string_when_field_is_long() throws Exception {
+        JsonNode json = mapper.readTree(mapper.writeValueAsString(new Sample(SNOWFLAKE_ID, 7)));
+
+        assertThat(json.get("id").isTextual()).isTrue();
+        assertThat(json.get("id").asText()).isEqualTo("2111012753262120962");
+        // Integer 字段不受影响：分页参数这类必须还是数字
+        assertThat(json.get("sort").isNumber()).isTrue();
+    }
+
+    @Test
+    void should_render_long_as_string_when_it_is_nested_list_or_map_value() throws Exception {
+        Nested nested = new Nested();
+        nested.setInner(new Sample(SNOWFLAKE_ID, 1));
+        nested.setList(List.of(new Sample(SNOWFLAKE_ID + 1, 1)));
+        nested.setMap(Map.of("drama", new Sample(SNOWFLAKE_ID + 2, 1)));
+
+        JsonNode json = mapper.readTree(mapper.writeValueAsString(nested));
+
+        assertThat(json.get("inner").get("id").isTextual()).isTrue();
+        assertThat(json.get("list").get(0).get("id").isTextual()).isTrue();
+        assertThat(json.get("map").get("drama").get("id").isTextual()).isTrue();
+        assertThat(json.get("list").get(0).get("id").asText()).isEqualTo("2111012753262120963");
+        assertThat(json.get("map").get("drama").get("id").asText()).isEqualTo("2111012753262120964");
+    }
+
+    @Test
+    void should_keep_total_as_number_and_list_ids_as_string_when_serializing_page() throws Exception {
+        PageResult<Sample> page = new PageResult<>(SNOWFLAKE_ID, List.of(new Sample(SNOWFLAKE_ID, 1)));
+
+        JsonNode json = mapper.readTree(mapper.writeValueAsString(page));
+
+        // total 是计数不是 id：保持数字，否则前端分页组件全部要改
+        assertThat(json.get("total").isNumber()).isTrue();
+        assertThat(json.get("total").asLong()).isEqualTo(SNOWFLAKE_ID);
+        assertThat(json.get("list").get(0).get("id").isTextual()).isTrue();
+    }
+
+    @Test
+    void should_read_long_from_string_when_request_body_sends_string_id() throws Exception {
+        Sample sample = mapper.readValue("{\"id\":\"2111012753262120962\",\"sort\":3}", Sample.class);
+
+        assertThat(sample.getId()).isEqualTo(SNOWFLAKE_ID);
+        assertThat(sample.getSort()).isEqualTo(3);
+    }
+
+    @Test
+    void should_bind_long_when_path_variable_is_a_19_digit_string() throws Exception {
+        mockMvc.perform(put("/admin/products/2111012753262120962/status").param("status", "1"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(0));
+
+        // 路径变量按字符串传来，必须原样绑定成 Long（不能被截断）
+        verify(productService).updateStatus(eq(SNOWFLAKE_ID), eq(1));
+    }
+
+    /** 普通字段 */
+    @Data
+    public static class Sample {
+        private Long id;
+        private Integer sort;
+
+        public Sample() {
+        }
+
+        public Sample(Long id, Integer sort) {
+            this.id = id;
+            this.sort = sort;
+        }
+    }
+
+    /** 嵌套容器 */
+    @Data
+    public static class Nested {
+        private Sample inner;
+        private List<Sample> list;
+        private Map<String, Sample> map;
+    }
+}

fruitshorts-app-api/pom.xml

@@ -41,6 +41,22 @@
             <groupId>com.fruitshorts</groupId>
             <artifactId>fruitshorts-module-commerce</artifactId>
         </dependency>
+        <!-- C 端创作者入驻/我的作品（module-creator 只读复用，未改其既有行为） -->
+        <dependency>
+            <groupId>com.fruitshorts</groupId>
+            <artifactId>fruitshorts-module-creator</artifactId>
+        </dependency>
+        <!-- 启动配置白名单读 sys_config、系统公告读 ops_notice -->
+        <dependency>
+            <groupId>com.fruitshorts</groupId>
+            <artifactId>fruitshorts-module-system</artifactId>
+        </dependency>
+        <!-- 契约测试用：MockMvc + Mockito + JUnit5，test scope，不进运行态依赖 -->
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-test</artifactId>
+            <scope>test</scope>
+        </dependency>
     </dependencies>
 
     <build>

fruitshorts-app-api/src/main/java/com/fruitshorts/app/AppApiApplication.java

@@ -5,12 +5,36 @@ package com.fruitshorts.app;
 import org.mybatis.spring.annotation.MapperScan;
 import org.springframework.boot.SpringApplication;
 import org.springframework.boot.autoconfigure.SpringBootApplication;
+import io.swagger.v3.oas.annotations.OpenAPIDefinition;
+import io.swagger.v3.oas.annotations.info.Info;
+import io.swagger.v3.oas.annotations.tags.Tag;
 
 /**
  * 客户端接口服务，只暴露 /app/** 与静态媒资 /files/**。
  * 与 fruitshorts-admin-api 共用同一套领域模块和数据库，但入口、鉴权和限流策略独立。
  */
 /* 显式指定扫描根包：本类在 com.fruitshorts.app 下，默认扫不到 content/system/framework 模块的 Bean */
+@OpenAPIDefinition(
+        info = @Info(
+                title = "FruitShorts 客户端接口（/app/**）",
+                version = "1.0.0",
+                description = "接口契约以 FruitServer/docs/api-phase1.md 为准"
+        ),
+        tags = {
+                @Tag(name = "客户端-账号", description = "验证码、注册、登录、令牌刷新与登出"),
+                @Tag(name = "客户端-内容浏览", description = "首页 / 发现 / 分类聚合接口"),
+                @Tag(name = "客户端-评论", description = "评论发布、列表与删除"),
+                @Tag(name = "客户端-金币与订单", description = "钱包、金币解锁与订单票据"),
+                @Tag(name = "客户端-离线下载", description = "下载授权、下载偏好与断点续传"),
+                @Tag(name = "客户端-短剧与播放", description = "短剧详情与播放票据"),
+                @Tag(name = "客户端-收藏", description = "收藏切换与列表"),
+                @Tag(name = "客户端-点赞与举报", description = "点赞与举报提报"),
+                @Tag(name = "客户端-个人中心", description = "资料、设备、数据导出与注销"),
+                @Tag(name = "客户端-创作者", description = "创作者入驻申请、我的作品与数据看板（C 端账号）"),
+                @Tag(name = "客户端-启动配置与公告", description = "启动配置（白名单键）与系统公告，均匿名可访问"),
+                @Tag(name = "客户端-观看进度", description = "观看进度上报与续看位置"),
+        }
+)
 @SpringBootApplication(scanBasePackages = "com.fruitshorts")
 @MapperScan("com.fruitshorts.**.dal.mapper")
 public class AppApiApplication {

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

@@ -13,6 +13,8 @@ import com.fruitshorts.user.vo.OtpSendReqVO;
 import com.fruitshorts.user.vo.RefreshReqVO;
 import com.fruitshorts.user.vo.RegisterReqVO;
 import com.fruitshorts.user.vo.TokenRespVO;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.servlet.http.HttpServletRequest;
 import jakarta.validation.Valid;
 import lombok.RequiredArgsConstructor;
@@ -22,6 +24,7 @@ import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
 
 /** 客户端账号：验证码、注册、登录、刷新、登出。 */
+@Tag(name = "客户端-账号")
 @RestController
 @RequestMapping("/app/auth")
 @RequiredArgsConstructor
@@ -31,30 +34,35 @@ public class AppAuthController {
     private final AppAuthService authService;
 
     /** 发送验证码。频控在服务端，客户端不需要自己限流。 */
+    @Operation(summary = "发送验证码（频控在服务端）")
     @PostMapping("/otp")
     public Result<Void> sendOtp(@Valid @RequestBody OtpSendReqVO req, HttpServletRequest request) {
         otpService.send(req, WebUtils.getClientIp(request));
         return Result.ok();
     }
 
+    @Operation(summary = "注册账号（邮箱免验证码 / 手机号需验证码）")
     @PostMapping("/register")
     public Result<TokenRespVO> register(@Valid @RequestBody RegisterReqVO req,
                                         HttpServletRequest request) {
         return Result.ok(authService.register(req, WebUtils.getClientIp(request)));
     }
 
+    @Operation(summary = "登录（验证码或密码）")
     @PostMapping("/login")
     public Result<TokenRespVO> login(@Valid @RequestBody LoginReqVO req,
                                      HttpServletRequest request) {
         return Result.ok(authService.login(req, WebUtils.getClientIp(request)));
     }
 
+    @Operation(summary = "刷新令牌（旧 refresh token 立即失效）")
     @PostMapping("/refresh")
     public Result<TokenRespVO> refresh(@Valid @RequestBody RefreshReqVO req) {
         return Result.ok(authService.refresh(req.getRefreshToken()));
     }
 
     /** 登出：默认只吊销当前设备的会话，allDevices=true 时吊销全部。 */
+    @Operation(summary = "登出（默认当前设备，allDevices 吊销全部）")
     @PostMapping("/logout")
     public Result<Void> logout(@RequestBody(required = false) LogoutReqVO req) {
         authService.logout(SecurityUtils.getUserIdOrNull(), req == null ? new LogoutReqVO() : req);

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

@@ -6,6 +6,8 @@ import com.fruitshorts.app.service.AppCatalogService;
 import com.fruitshorts.app.vo.AppCategoryVO;
 import com.fruitshorts.app.vo.AppFeedVO;
 import com.fruitshorts.common.pojo.Result;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RequestMapping;
@@ -16,6 +18,7 @@ import java.util.List;
 /**
  * 客户端目录接口：首页与发现页各一次请求拿全量聚合数据。
  */
+@Tag(name = "客户端-内容浏览")
 @RestController
 @RequestMapping("/app")
 @RequiredArgsConstructor
@@ -23,16 +26,19 @@ public class AppCatalogController {
 
     private final AppCatalogService appCatalogService;
 
+    @Operation(summary = "首页聚合：轮播 + 分区，一次请求渲染整页")
     @GetMapping("/home/feed")
     public Result<AppFeedVO> homeFeed() {
         return Result.ok(appCatalogService.homeFeed());
     }
 
+    @Operation(summary = "发现页聚合：分区列表")
     @GetMapping("/discover/feed")
     public Result<AppFeedVO> discoverFeed() {
         return Result.ok(appCatalogService.discoverFeed());
     }
 
+    @Operation(summary = "分类列表")
     @GetMapping("/categories")
     public Result<List<AppCategoryVO>> categories() {
         return Result.ok(appCatalogService.categories());

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

@@ -10,6 +10,8 @@ import com.fruitshorts.interaction.service.CommentService;
 import com.fruitshorts.interaction.vo.CommentPublishReqVO;
 import com.fruitshorts.interaction.vo.CommentQueryReqVO;
 import com.fruitshorts.interaction.vo.CommentRespVO;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.servlet.http.HttpServletRequest;
 import jakarta.validation.Valid;
 import lombok.RequiredArgsConstructor;
@@ -29,6 +31,7 @@ import org.springframework.web.bind.annotation.RestController;
  * 不传 `rootId` 时返回顶层评论，传了则返回该楼层的回复。
  * 列表允许匿名浏览；发布与删除需要登录。
  */
+@Tag(name = "客户端-评论")
 @RestController
 @RequestMapping("/app/comments")
 @RequiredArgsConstructor
@@ -36,6 +39,7 @@ public class AppCommentController {
 
     private final CommentService commentService;
 
+    @Operation(summary = "发布评论")
     @PostMapping
     public Result<CommentRespVO> publish(@Valid @RequestBody CommentPublishReqVO req,
                                          HttpServletRequest request) {
@@ -43,6 +47,7 @@ public class AppCommentController {
                 WebUtils.getClientIp(request), request.getHeader("X-Device-Id")));
     }
 
+    @Operation(summary = "评论列表（游标翻页，可匿名浏览）")
     @GetMapping
     public Result<CursorResult<CommentRespVO>> page(@RequestParam Long dramaId,
                                                     @RequestParam(required = false) Long episodeId,
@@ -58,6 +63,7 @@ public class AppCommentController {
         return Result.ok(commentService.page(SecurityUtils.getUserIdOrNull(), query));
     }
 
+    @Operation(summary = "删除自己的评论")
     @DeleteMapping("/{id}")
     public Result<Void> delete(@PathVariable Long id) {
         commentService.delete(SecurityUtils.getAppUserId(), id);

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

@@ -8,6 +8,8 @@ import com.fruitshorts.commerce.service.UnlockService;
 import com.fruitshorts.commerce.service.WalletService;
 import com.fruitshorts.common.pojo.Result;
 import com.fruitshorts.framework.security.SecurityUtils;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.PathVariable;
@@ -26,6 +28,7 @@ import java.util.Map;
  * 金币解锁是第一阶段真实的收费方式；真实商店购买走 {@code /app/orders/verify}，
  * 本轮只预留接口（商店未接入时返回明确业务提示，不会产生假订单）。
  */
+@Tag(name = "客户端-金币与订单")
 @RestController
 @RequestMapping("/app")
 @RequiredArgsConstructor
@@ -36,6 +39,7 @@ public class AppCommerceController {
     private final OrderService orderService;
 
     /** 我的钱包：余额 + 最近流水，客户端一处渲染。 */
+    @Operation(summary = "我的钱包（余额 + 最近流水）")
     @GetMapping("/wallet")
     public Result<Map<String, Object>> wallet() {
         Long userId = SecurityUtils.getAppUserId();
@@ -46,20 +50,31 @@ public class AppCommerceController {
     }
 
     /** 金币解锁分集：幂等，重复点击不会重复扣币。 */
+    @Operation(summary = "金币解锁分集（幂等，重复点击不重复扣币）")
     @PostMapping("/episodes/{episodeId}/unlock")
     public Result<Map<String, Object>> unlock(@PathVariable Long episodeId) {
         return Result.ok(unlockService.unlock(SecurityUtils.getAppUserId(), episodeId));
     }
 
+    @Operation(summary = "我的订单列表")
     @GetMapping("/orders")
     public Result<List<Orders>> orders() {
         return Result.ok(orderService.listByUser(SecurityUtils.getAppUserId()));
     }
 
-    /** 提交商店票据。第一阶段商店未接入，会返回明确的"尚未配置"。 */
+    /**
+     * 提交商店票据：服务端校验 → 建单 → 发权益。
+     *
+     * <p>body：`platform`（GOOGLE/GOOGLE_PLAY）、`productId`（商店商品 id）、`receipt`（purchaseToken）。
+     * 同一票据重复提交只交付一次；票据已绑定其他账号、或校验不通过时返回明确业务码且不产生订单。
+     * 商店未配置（默认）时返回 `200003 尚未配置`，与第一阶段行为一致。
+     */
+    @Operation(summary = "提交商店票据（校验后建单并发权益，重复提交幂等）")
     @PostMapping("/orders/verify")
     public Result<Orders> verify(@RequestBody Map<String, String> body) {
         return Result.ok(orderService.verifyAndDeliver(SecurityUtils.getAppUserId(),
-                body.getOrDefault("platform", ""), body.getOrDefault("receipt", "")));
+                body.getOrDefault("platform", ""),
+                body.getOrDefault("productId", ""),
+                body.getOrDefault("receipt", "")));
     }
 }

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

@@ -0,0 +1,53 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.app.controller;
+
+import com.fruitshorts.app.service.AppConfigService;
+import com.fruitshorts.app.service.AppNoticeService;
+import com.fruitshorts.app.vo.AppNoticeVO;
+import com.fruitshorts.common.pojo.PageResult;
+import com.fruitshorts.common.pojo.Result;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import lombok.RequiredArgsConstructor;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.util.Map;
+
+/**
+ * 启动配置与系统公告：**两个匿名接口**（客户端登录前就要拿到）。
+ *
+ * <p>放在一起是因为它们同属"进入 App 前的公共数据"，且都不依赖登录态。
+ */
+@Tag(name = "客户端-启动配置与公告")
+@RestController
+@RequestMapping("/app")
+@RequiredArgsConstructor
+public class AppConfigController {
+
+    private final AppConfigService appConfigService;
+    private final AppNoticeService appNoticeService;
+
+    /**
+     * 启动配置：协议版本 / 最低版本 / 功能开关。
+     * **只下发白名单键**，库里缺键用契约默认值兜底。
+     */
+    @Operation(summary = "启动配置（匿名，只下发白名单键）")
+    @GetMapping("/config")
+    public Result<Map<String, Object>> config() {
+        return Result.ok(appConfigService.appConfig());
+    }
+
+    /** 系统公告：无数据返回空列表（不是 404）。 */
+    @Operation(summary = "系统公告（匿名，无数据返回空列表）")
+    @GetMapping("/notices")
+    public Result<PageResult<AppNoticeVO>> notices(
+            @RequestParam(defaultValue = "1") Integer pageIndex,
+            @RequestParam(defaultValue = "20") Integer pageSize) {
+        return Result.ok(appNoticeService.page(pageIndex == null ? 1 : pageIndex,
+                pageSize == null ? 20 : pageSize));
+    }
+}

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

@@ -0,0 +1,42 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.app.controller;
+
+import com.fruitshorts.app.service.AppConfigService;
+import com.fruitshorts.common.pojo.Result;
+import com.fruitshorts.creator.service.CreatorAppService;
+import com.fruitshorts.creator.vo.CreatorApplyReqVO;
+import com.fruitshorts.creator.vo.CreatorApplyRespVO;
+import com.fruitshorts.framework.security.SecurityUtils;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.validation.Valid;
+import lombok.RequiredArgsConstructor;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+/**
+ * C 端创作者：**只有入驻申请一条**。
+ *
+ * <p>口径（2026-10-16 变更）：**创作者中心（工作台 / 作品管理 / 数据看板）由 Web 端承载**（后端契约 §2.10），
+ * App 客户端不再提供 `works` / `stats`。归属一律取当前登录的 C 端账号，接口**不接收 creatorId**。
+ */
+@Tag(name = "客户端-创作者")
+@RestController
+@RequestMapping("/app/creator")
+@RequiredArgsConstructor
+public class AppCreatorController {
+
+    private final CreatorAppService creatorAppService;
+    private final AppConfigService appConfigService;
+
+    /** 入驻申请：幂等，重复提交返回当前状态（不重复建档）。 */
+    @Operation(summary = "创作者入驻申请（幂等，重复提交返回当前状态）")
+    @PostMapping("/apply")
+    public Result<CreatorApplyRespVO> apply(@Valid @RequestBody CreatorApplyReqVO req) {
+        return Result.ok(creatorAppService.apply(SecurityUtils.getAppUserId(), req,
+                appConfigService.agreementVersion()));
+    }
+}

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

@@ -10,6 +10,8 @@ import com.fruitshorts.playback.vo.DownloadLicenseRespVO;
 import com.fruitshorts.playback.vo.DownloadPolicyRespVO;
 import com.fruitshorts.playback.vo.DownloadProgressReqVO;
 import com.fruitshorts.playback.vo.DownloadSettingReqVO;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.servlet.http.HttpServletRequest;
 import jakarta.validation.Valid;
 import lombok.RequiredArgsConstructor;
@@ -31,6 +33,7 @@ import java.util.List;
  * <p>服务端只发授权与地址，分片由客户端向 CDN 拉取；进度上报用于断点续传与跨端展示。
  * 设备标识优先取请求体，其次取请求头 X-Device-Id。
  */
+@Tag(name = "客户端-离线下载")
 @RestController
 @RequestMapping("/app/downloads")
 @RequiredArgsConstructor
@@ -39,6 +42,7 @@ public class AppDownloadController {
     private final DownloadService downloadService;
 
     /** 申请下载授权（同一剧集重复申请幂等，只刷新有效期）。 */
+    @Operation(summary = "申请下载授权（同一剧集幂等，只刷新有效期）")
     @PostMapping
     public Result<DownloadLicenseRespVO> grant(@Valid @RequestBody DownloadGrantReqVO req,
                                                HttpServletRequest request) {
@@ -46,17 +50,20 @@ public class AppDownloadController {
                 request.getHeader("X-Device-Id")));
     }
 
+    @Operation(summary = "我的下载授权列表")
     @GetMapping
     public Result<List<DownloadLicenseRespVO>> list(@RequestParam(required = false) String deviceId) {
         return Result.ok(downloadService.list(SecurityUtils.getAppUserId(), deviceId));
     }
 
+    @Operation(summary = "下载规则（设备上限 / 仅 Wi-Fi / 清晰度上限）")
     @GetMapping("/policy")
     public Result<DownloadPolicyRespVO> policy(@RequestParam(required = false) String deviceId) {
         return Result.ok(downloadService.policy(SecurityUtils.getAppUserId(), deviceId));
     }
 
     /** 仅 Wi-Fi 下载、清晰度上限等偏好。 */
+    @Operation(summary = "更新下载偏好设置")
     @PutMapping("/settings")
     public Result<Void> updateSettings(@RequestBody DownloadSettingReqVO req) {
         downloadService.updateSettings(SecurityUtils.getAppUserId(), req);
@@ -64,6 +71,7 @@ public class AppDownloadController {
     }
 
     /** 断点续传前重新取一次地址：授权不变，只有地址是短时效的。 */
+    @Operation(summary = "重新获取下载地址（断点续传前刷新短时效地址）")
     @GetMapping("/{episodeId}/url")
     public Result<DownloadLicenseRespVO> refreshUrl(@PathVariable Long episodeId,
                                                     HttpServletRequest request) {
@@ -71,6 +79,7 @@ public class AppDownloadController {
                 request.getHeader("X-Device-Id")));
     }
 
+    @Operation(summary = "上报下载进度")
     @PostMapping("/{episodeId}/progress")
     public Result<DownloadLicenseRespVO> reportProgress(@PathVariable Long episodeId,
                                                         @RequestBody DownloadProgressReqVO req,
@@ -79,6 +88,7 @@ public class AppDownloadController {
                 request.getHeader("X-Device-Id")));
     }
 
+    @Operation(summary = "吊销某集的下载授权")
     @DeleteMapping("/{episodeId}")
     public Result<Void> revoke(@PathVariable Long episodeId,
                                @RequestParam(required = false) String deviceId,
@@ -89,6 +99,7 @@ public class AppDownloadController {
     }
 
     /** 清空当前设备的全部下载授权。 */
+    @Operation(summary = "清空当前设备的全部下载授权")
     @DeleteMapping
     public Result<Integer> clear(@RequestParam(required = false) String deviceId,
                                  HttpServletRequest request) {

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

@@ -9,6 +9,8 @@ import com.fruitshorts.framework.security.SecurityUtils;
 import com.fruitshorts.framework.web.WebUtils;
 import com.fruitshorts.playback.service.PlaybackService;
 import com.fruitshorts.playback.vo.PlayRespVO;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.servlet.http.HttpServletRequest;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.GetMapping;
@@ -16,6 +18,7 @@ import org.springframework.web.bind.annotation.PathVariable;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
 
+@Tag(name = "客户端-短剧与播放")
 @RestController
 @RequestMapping("/app")
 @RequiredArgsConstructor
@@ -25,6 +28,7 @@ public class AppDramaController {
     private final PlaybackService playbackService;
 
     /** 详情：包含剧集列表，客户端进详情页一次请求即可渲染 */
+    @Operation(summary = "短剧详情（含剧集列表，进详情页一次请求即可渲染）")
     @GetMapping("/dramas/{id}")
     public Result<AppDramaDetailVO> detail(@PathVariable Long id) {
         return Result.ok(appCatalogService.dramaDetail(id));
@@ -34,6 +38,7 @@ public class AppDramaController {
      * 播放票据：服务端判定权益后签发短时效播放地址。
      * 未登录也能播免费集；付费集未解锁时只返回需要多少金币。
      */
+    @Operation(summary = "播放票据：判定权益后签发短时效播放地址")
     @GetMapping("/episodes/{id}/play")
     public Result<PlayRespVO> play(@PathVariable Long id, HttpServletRequest request) {
         return Result.ok(playbackService.play(

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

@@ -8,6 +8,8 @@ import com.fruitshorts.common.pojo.Result;
 import com.fruitshorts.framework.security.SecurityUtils;
 import com.fruitshorts.playback.service.FavoriteService;
 import com.fruitshorts.playback.vo.FavoriteToggleReqVO;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.DeleteMapping;
@@ -21,6 +23,7 @@ import org.springframework.web.bind.annotation.RestController;
 import java.util.List;
 
 /** 收藏。 */
+@Tag(name = "客户端-收藏")
 @RestController
 @RequestMapping("/app/favorites")
 @RequiredArgsConstructor
@@ -30,18 +33,21 @@ public class AppFavoriteController {
     private final AppCatalogService appCatalogService;
 
     /** 切换收藏，返回切换后的状态：true 为已收藏。 */
+    @Operation(summary = "切换收藏（返回切换后的状态）")
     @PostMapping("/toggle")
     public Result<Boolean> toggle(@Valid @RequestBody FavoriteToggleReqVO req) {
         return Result.ok(favoriteService.toggle(SecurityUtils.getAppUserId(), req.getDramaId()));
     }
 
     /** 收藏列表，卡片结构与首页一致。 */
+    @Operation(summary = "我的收藏列表")
     @GetMapping
     public Result<List<AppDramaCardVO>> list() {
         return Result.ok(appCatalogService.toCards(
                 favoriteService.listDramas(SecurityUtils.getAppUserId())));
     }
 
+    @Operation(summary = "取消收藏")
     @DeleteMapping("/{dramaId}")
     public Result<Void> remove(@PathVariable Long dramaId) {
         favoriteService.remove(SecurityUtils.getAppUserId(), dramaId);

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

@@ -9,6 +9,8 @@ import com.fruitshorts.interaction.service.ReportService;
 import com.fruitshorts.interaction.vo.LikeToggleReqVO;
 import com.fruitshorts.interaction.vo.LikeToggleRespVO;
 import com.fruitshorts.interaction.vo.ReportCreateReqVO;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.PostMapping;
@@ -17,6 +19,7 @@ import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
 
 /** 点赞与举报。 */
+@Tag(name = "客户端-点赞与举报")
 @RestController
 @RequestMapping("/app")
 @RequiredArgsConstructor
@@ -26,12 +29,14 @@ public class AppInteractionController {
     private final ReportService reportService;
 
     /** 点赞/取消点赞，返回切换后的状态与最新计数。 */
+    @Operation(summary = "点赞 / 取消点赞")
     @PostMapping("/likes/toggle")
     public Result<LikeToggleRespVO> toggleLike(@Valid @RequestBody LikeToggleReqVO req) {
         return Result.ok(likeService.toggle(SecurityUtils.getAppUserId(), req));
     }
 
     /** 提交举报：同一用户对同一目标只保留一条待处理工单。 */
+    @Operation(summary = "提交举报（同一目标只保留一条待处理工单）")
     @PostMapping("/reports")
     public Result<Long> report(@Valid @RequestBody ReportCreateReqVO req) {
         return Result.ok(reportService.create(SecurityUtils.getAppUserId(), req));

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

@@ -9,6 +9,8 @@ import com.fruitshorts.user.service.AppUserService;
 import com.fruitshorts.user.vo.AppUserRespVO;
 import com.fruitshorts.user.vo.DeactivateReqVO;
 import com.fruitshorts.user.vo.ProfileUpdateReqVO;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.GetMapping;
@@ -23,6 +25,7 @@ import java.util.List;
 import java.util.Map;
 
 /** 客户端个人中心：资料、设备、注销、数据导出。 */
+@Tag(name = "客户端-个人中心")
 @RestController
 @RequestMapping("/app/me")
 @RequiredArgsConstructor
@@ -30,33 +33,39 @@ public class AppMeController {
 
     private final AppUserService userService;
 
+    @Operation(summary = "我的资料")
     @GetMapping
     public Result<AppUserRespVO> me() {
         return Result.ok(userService.me(SecurityUtils.getAppUserId()));
     }
 
+    @Operation(summary = "修改资料（昵称 / 头像 / 语言等）")
     @PutMapping
     public Result<AppUserRespVO> update(@Valid @RequestBody ProfileUpdateReqVO req) {
         return Result.ok(userService.updateProfile(SecurityUtils.getAppUserId(), req));
     }
 
+    @Operation(summary = "我的登录设备列表")
     @GetMapping("/devices")
     public Result<List<AppUserDevice>> devices() {
         return Result.ok(userService.devices(SecurityUtils.getAppUserId()));
     }
 
     /** 商店与隐私法规要求的数据导出，返回账号侧数据；内容侧数据由客户端自行下载。 */
+    @Operation(summary = "数据导出（合规要求）")
     @GetMapping("/export")
     public Result<Map<String, Object>> export() {
         return Result.ok(userService.exportAccount(SecurityUtils.getAppUserId()));
     }
 
     /** 申请注销：立即登出全部设备，进入冷静期，期间可撤销。 */
+    @Operation(summary = "申请注销（进入冷静期并登出全部设备）")
     @PostMapping("/deactivate")
     public Result<LocalDateTime> deactivate(@RequestBody(required = false) DeactivateReqVO req) {
         return Result.ok(userService.requestDeactivation(SecurityUtils.getAppUserId(), req));
     }
 
+    @Operation(summary = "撤销注销申请")
     @PostMapping("/deactivate/cancel")
     public Result<Void> cancelDeactivate() {
         userService.cancelDeactivation(SecurityUtils.getAppUserId());

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

@@ -7,6 +7,8 @@ import com.fruitshorts.framework.security.SecurityUtils;
 import com.fruitshorts.playback.service.WatchProgressService;
 import com.fruitshorts.playback.vo.ProgressRespVO;
 import com.fruitshorts.playback.vo.ProgressSaveReqVO;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.DeleteMapping;
@@ -21,6 +23,7 @@ import org.springframework.web.bind.annotation.RestController;
 import java.util.List;
 
 /** 观看进度与观看记录。 */
+@Tag(name = "客户端-观看进度")
 @RestController
 @RequestMapping("/app/watch")
 @RequiredArgsConstructor
@@ -29,28 +32,33 @@ public class AppWatchController {
     private final WatchProgressService progressService;
 
     /** 上报进度：客户端每 10 秒一次，切集时立即上报一次。 */
+    @Operation(summary = "上报观看进度（客户端每 10 秒一次）")
     @PostMapping("/progress")
     public Result<ProgressRespVO> save(@Valid @RequestBody ProgressSaveReqVO req) {
         return Result.ok(progressService.save(SecurityUtils.getAppUserId(), req));
     }
 
     /** 某部剧的续看位置，进详情页时用它决定"续看第 N 集"。 */
+    @Operation(summary = "某部剧的续看位置")
     @GetMapping("/progress")
     public Result<ProgressRespVO> ofDrama(@RequestParam Long dramaId) {
         return Result.ok(progressService.ofDrama(SecurityUtils.getAppUserId(), dramaId));
     }
 
+    @Operation(summary = "最近观看列表")
     @GetMapping("/recent")
     public Result<List<ProgressRespVO>> recent(@RequestParam(defaultValue = "20") int limit) {
         return Result.ok(progressService.recent(SecurityUtils.getAppUserId(), limit));
     }
 
+    @Operation(summary = "删除某部剧的观看记录")
     @DeleteMapping("/progress/{dramaId}")
     public Result<Void> remove(@PathVariable Long dramaId) {
         progressService.remove(SecurityUtils.getAppUserId(), dramaId);
         return Result.ok();
     }
 
+    @Operation(summary = "清空观看记录")
     @DeleteMapping("/progress")
     public Result<Void> clear() {
         progressService.clear(SecurityUtils.getAppUserId());

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

@@ -0,0 +1,76 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.app.service;
+
+import com.baomidou.mybatisplus.core.toolkit.Wrappers;
+import com.fruitshorts.system.dal.entity.SysConfig;
+import com.fruitshorts.system.dal.mapper.SysConfigMapper;
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Service;
+import org.springframework.util.StringUtils;
+
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * C 端启动配置（`GET /app/config`，匿名）。
+ *
+ * <p><b>只下发白名单键</b>：`sys_config` 是后台配置表，里面可能有内部开关，
+ * 整表下发等于把内部配置暴露给客户端 —— 所以这里用**硬编码白名单**（{@link #KEYS}），
+ * 且库里缺键时用**契约默认值**兜底（契约见 `docs/api-phase1.md` §1.9.1），
+ * 不返回 null 让客户端自己猜默认值。
+ */
+@Service
+@RequiredArgsConstructor
+public class AppConfigService {
+
+    /** 白名单：契约里的 6 个键 → 后台配置键 + 默认值。顺序即响应字段顺序。 */
+    private static final Map<String, KeySpec> KEYS = new LinkedHashMap<>();
+
+    static {
+        KEYS.put("agreementVersion", new KeySpec("app.agreement.version", "2026-10-01"));
+        KEYS.put("minAppVersion", new KeySpec("app.min.version", "1.0.0"));
+        KEYS.put("forceUpdate", new KeySpec("app.force.update", "false"));
+        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"));
+    }
+
+    private final SysConfigMapper sysConfigMapper;
+
+    /** 当前协议版本（`/app/creator/apply` 用它校验客户端提交的版本）。 */
+    public String agreementVersion() {
+        return valueOf("app.agreement.version", KEYS.get("agreementVersion").defaultValue());
+    }
+
+    /** 只含白名单键的配置；布尔项按布尔返回，避免客户端到处写字符串比较。 */
+    public Map<String, Object> appConfig() {
+        Map<String, Object> data = new LinkedHashMap<>();
+        KEYS.forEach((field, spec) -> {
+            String raw = valueOf(spec.configKey(), spec.defaultValue());
+            data.put(field, isBooleanField(field) ? Boolean.parseBoolean(raw) : raw);
+        });
+        return data;
+    }
+
+    /** 只查这一个键（不 select *）：即使表里有别的键也不会被读出来。 */
+    private String valueOf(String configKey, String fallback) {
+        List<SysConfig> rows = sysConfigMapper.selectList(Wrappers.<SysConfig>lambdaQuery()
+                .eq(SysConfig::getConfigKey, configKey)
+                .last("limit 1"));
+        if (rows.isEmpty() || !StringUtils.hasText(rows.get(0).getConfigValue())) {
+            return fallback;
+        }
+        return rows.get(0).getConfigValue().trim();
+    }
+
+    private boolean isBooleanField(String field) {
+        return "forceUpdate".equals(field) || "noticeEnabled".equals(field)
+                || "coinUnlockEnabled".equals(field) || "downloadEnabled".equals(field);
+    }
+
+    /** 一个白名单项：后台键 + 契约默认值。 */
+    private record KeySpec(String configKey, String defaultValue) {
+    }
+}

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

@@ -0,0 +1,41 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.app.service;
+
+import com.fruitshorts.app.vo.AppNoticeVO;
+import com.fruitshorts.common.pojo.PageResult;
+import com.fruitshorts.system.dal.entity.OpsNotice;
+import com.fruitshorts.system.service.OpsNoticeService;
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Service;
+
+/**
+ * C 端系统公告（`GET /app/notices`，匿名，只读）。
+ *
+ * <p>筛选口径**不在本类实现**：统一走 `OpsNoticeService.pageForApp(...)` ——
+ * 后台公告管理（`/admin/notices`）用的是同一套条件，避免"后台发布后 C 端到底能不能看到"两处条件漂移。
+ *
+ * <p>没有数据返回空列表（不是 404）；本类只负责把实体转成 C 端字段（不暴露后台字段）。
+ */
+@Service
+@RequiredArgsConstructor
+public class AppNoticeService {
+
+    private final OpsNoticeService opsNoticeService;
+
+    public PageResult<AppNoticeVO> page(int pageIndex, int pageSize) {
+        PageResult<OpsNotice> page = opsNoticeService.pageForApp(pageIndex, pageSize);
+        return new PageResult<>(page.getTotal(), page.getList().stream().map(this::toVO).toList());
+    }
+
+    private AppNoticeVO toVO(OpsNotice notice) {
+        AppNoticeVO vo = new AppNoticeVO();
+        vo.setId(notice.getId());
+        vo.setTitle(notice.getTitle());
+        vo.setContent(notice.getContent());
+        vo.setType(notice.getType());
+        vo.setPublishAt(notice.getPublishAt());
+        vo.setExpireAt(notice.getExpireAt());
+        return vo;
+    }
+}

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

@@ -0,0 +1,22 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.app.vo;
+
+import lombok.Data;
+
+import java.time.LocalDateTime;
+
+/** C 端系统公告（`GET /app/notices`）。 */
+@Data
+public class AppNoticeVO {
+
+    private Long id;
+    private String title;
+    private String content;
+
+    /** SYSTEM / AUDIT / PAYMENT / ACTIVITY。 */
+    private String type;
+
+    private LocalDateTime publishAt;
+    private LocalDateTime expireAt;
+}

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

@@ -0,0 +1,37 @@
+# Author: fruit.com.cn
+#
+# 生产 profile（--spring.profiles.active=prod）：
+#   1) 集中生产开关，不在这里写任何密钥 —— 密钥一律环境变量注入；
+#   2) 密钥缺失/还是 dev 默认值/签名没开 → ProdSecretGuard 直接让启动失败（fail-fast）。
+server:
+  # 容器里由编排再映射；保持 8081 便于与 runbook 一致
+  port: ${SERVER_PORT:8081}
+  tomcat:
+    # 生产前置反代，真实 IP 从 X-Forwarded-* 取
+    remoteip:
+      remote-ip-header: X-Forwarded-For
+      protocol-header: X-Forwarded-Proto
+
+spring:
+  lifecycle:
+    timeout-per-shutdown-phase: 30s
+
+fruitshorts:
+  media:
+    # 生产必须开启播放地址签名（docs/12-上线检查清单）
+    signature-required: true
+  cors:
+    # 生产只允许显式配置的来源；没配就等于空，浏览器侧会被拦住（比"*"安全）
+    allowed-origins: ${CORS_ALLOWED_ORIGINS:}
+
+springdoc:
+  # 生产只留机器可读契约，关掉 UI（doc.html 不对外开放）
+  swagger-ui:
+    enabled: ${SWAGGER_ENABLED:false}
+  api-docs:
+    enabled: ${SWAGGER_ENABLED:false}
+
+logging:
+  level:
+    root: info
+    com.fruitshorts: info

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

@@ -10,7 +10,9 @@ spring:
     exclude: org.springframework.boot.autoconfigure.security.servlet.UserDetailsServiceAutoConfiguration
   datasource:
     driver-class-name: org.postgresql.Driver
-    url: jdbc:postgresql://127.0.0.1:5432/fruitshorts
+    # 地址必须外置：不同环境（本机 / 测试 / 生产）连的库不一样，
+    # 生产请用 DB_URL 注入（prod profile 会校验它非空）
+    url: ${DB_URL:jdbc:postgresql://127.0.0.1:5432/fruitshorts}
     username: ${DB_USER:fruitshorts}
     password: ${DB_PASSWORD:fruitshorts}
   jackson:
@@ -23,11 +25,17 @@ mybatis-plus:
   global-config:
     banner: false
     db-config:
-      id-type: auto
+      # 主键由应用侧雪花算法生成（S0），数据库不再自增
+      id-type: assign_id
       logic-delete-field: deleted
       logic-delete-value: 1
       logic-not-delete-value: 0
+    sequence:
+      # 单机开发用固定值；上多实例前必须改成按实例分配（环境变量注入），否则会撞 ID
+      worker-id: 1
+      datacenter-id: 1
 
+# 接口文档：/doc.html 打开 Swagger UI，/v3/api-docs 是机器可读契约（前端联调按它写）
 springdoc:
   swagger-ui:
     path: /doc.html
@@ -35,6 +43,10 @@ springdoc:
     path: /v3/api-docs
 
 fruitshorts:
+  auth:
+    # 仅作 sys_config 缺失/非法时的兜底；运行时优先读取后台「系统配置」
+    register-max-per-ip-per-day: ${REGISTER_MAX_PER_IP_PER_DAY:5}
+    register-max-per-device-per-day: ${REGISTER_MAX_PER_DEVICE_PER_DAY:3}
   interaction:
     # MACHINE_FIRST：机审通过即发布，命中 REVIEW 级敏感词才转人工
     # PRE_REVIEW   ：全部先审后发（生产建议）
@@ -47,16 +59,36 @@ fruitshorts:
     license-days: 30
     wifi-only-default: true
     max-quality: AUTO
+  commerce:
+    store:
+      # 商店票据校验实现：disabled = 明确报"未配置"（默认，无凭据时对外行为不变）
+      #                    google-play = 走 Google Play Developer API
+      verifier: ${STORE_VERIFIER:disabled}
+      # 下面两项属付费凭据：只从环境变量/配置注入，不入库、不提交、不打进镜像
+      google-play-package-name: ${GOOGLE_PLAY_PACKAGE_NAME:}
+      # 服务账号 JSON：文件路径 \| JSON 内容 \| base64（建议用环境变量给 base64）
+      google-play-service-account-json: ${GOOGLE_PLAY_SERVICE_ACCOUNT_JSON:}
+      google-play-timeout-seconds: 10
   media:
-    root-dir: ./data/uploads
+    # 媒体根目录：容器里指向挂载卷；本地默认 ./data/uploads
+    root-dir: ${MEDIA_ROOT_DIR:./data/uploads}
     public-prefix: /files
     chunk-size: 5242880
     max-file-size: 2147483648
+    # 播放地址签名：生产必开（docs/12-上线检查清单），prod profile 里强制为 true
+    signature-secret: ${MEDIA_SIGNATURE_SECRET:fruitshorts-media-dev-secret-change-me-in-production-32b}
+    signature-required: ${MEDIA_SIGNATURE_REQUIRED:false}
+    signature-ttl-minutes: 15
   jwt:
+    # 双密钥：管理端与客户端物理隔离，token 不能互换（AGENTS.md 强制约束 2）
+    # 注意 app-secret 以前没写在这里，一直用代码里的 dev 默认值 —— 生产必须注入 JWT_APP_SECRET
     admin-secret: ${JWT_ADMIN_SECRET:fruitshorts-admin-dev-secret-change-me-in-production-32b}
     admin-ttl-hours: 12
+    app-secret: ${JWT_APP_SECRET:fruitshorts-app-dev-secret-change-me-in-production-32bytes}
+    app-access-ttl-minutes: 120
+    app-refresh-ttl-days: 30
   cors:
-    allowed-origins: "*"
+    allowed-origins: ${CORS_ALLOWED_ORIGINS:*}
 
 logging:
   level:

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

@@ -0,0 +1,140 @@
+// Author: fruit.com.cn
+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.user.service.AppAuthService;
+import com.fruitshorts.user.service.AppOtpService;
+import com.fruitshorts.user.vo.TokenRespVO;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.http.MediaType;
+import org.springframework.test.web.servlet.MockMvc;
+
+import static org.hamcrest.Matchers.containsString;
+import static org.hamcrest.Matchers.nullValue;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.BDDMockito.given;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+/**
+ * `/app/auth/**` 的接入层契约：路由、请求体绑定、统一响应包 `{code,message,data}`、错误码映射。
+ *
+ * <p>业务规则（免码、密码强度、频控）在 {@code AppAuthServiceTest} / {@code AppOtpServiceTest} 里用真服务验证，
+ * 这里只钉"接口长什么样"。
+ */
+class AppAuthControllerContractTest {
+
+    private AppOtpService otpService;
+    private AppAuthService authService;
+    private MockMvc mockMvc;
+
+    @BeforeEach
+    void setUp() {
+        otpService = mock(AppOtpService.class);
+        authService = mock(AppAuthService.class);
+        mockMvc = ControllerContractSupport.mockMvcOf(new AppAuthController(otpService, authService));
+    }
+
+    @Test
+    void should_return_access_token_when_email_register_succeeds() throws Exception {
+        given(authService.register(any(), any())).willReturn(tokens("access-1", "refresh-1"));
+
+        mockMvc.perform(post("/app/auth/register")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"targetType\":\"EMAIL\",\"target\":\"a@b.com\",\"password\":\"abcd1234\"}"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(0))
+                .andExpect(jsonPath("$.message").value("ok"))
+                .andExpect(jsonPath("$.data.accessToken").value("access-1"))
+                .andExpect(jsonPath("$.data.tokenType").value("Bearer"))
+                .andExpect(jsonPath("$.data.newUser").value(true));
+    }
+
+    @Test
+    void should_return_data_exists_code_when_email_is_already_registered() throws Exception {
+        given(authService.register(any(), any())).willThrow(
+                new ServiceException(ErrorCode.DATA_EXISTS, "该账号已注册，请直接登录"));
+
+        mockMvc.perform(post("/app/auth/register")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"targetType\":\"EMAIL\",\"target\":\"a@b.com\",\"password\":\"abcd1234\"}"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(ErrorCode.DATA_EXISTS.getCode()))
+                .andExpect(jsonPath("$.message").value("该账号已注册，请直接登录"))
+                .andExpect(jsonPath("$.data").value(nullValue()));
+    }
+
+    @Test
+    void should_map_otp_required_error_when_phone_register_has_no_code() throws Exception {
+        given(authService.register(any(), any())).willThrow(
+                new ServiceException(ErrorCode.BAD_REQUEST, "请先获取验证码"));
+
+        mockMvc.perform(post("/app/auth/register")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"targetType\":\"PHONE\",\"target\":\"08123456789\"}"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(ErrorCode.BAD_REQUEST.getCode()))
+                .andExpect(jsonPath("$.message").value("请先获取验证码"));
+    }
+
+    @Test
+    void should_return_bad_request_code_when_register_body_has_no_target() throws Exception {
+        mockMvc.perform(post("/app/auth/register")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"targetType\":\"EMAIL\"}"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(ErrorCode.BAD_REQUEST.getCode()))
+                .andExpect(jsonPath("$.message").value(containsString("请输入手机号或邮箱")));
+    }
+
+    @Test
+    void should_return_access_token_when_password_login_succeeds() throws Exception {
+        given(authService.login(any(), any())).willReturn(tokens("access-2", "refresh-2"));
+
+        mockMvc.perform(post("/app/auth/login")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"targetType\":\"EMAIL\",\"target\":\"a@b.com\",\"password\":\"abcd1234\"}"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(0))
+                .andExpect(jsonPath("$.data.accessToken").value("access-2"));
+    }
+
+    @Test
+    void should_return_login_failed_code_when_password_is_wrong() throws Exception {
+        given(authService.login(any(), any())).willThrow(new ServiceException(ErrorCode.LOGIN_FAILED));
+
+        mockMvc.perform(post("/app/auth/login")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"targetType\":\"EMAIL\",\"target\":\"a@b.com\",\"password\":\"wrongpass1\"}"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(ErrorCode.LOGIN_FAILED.getCode()))
+                .andExpect(jsonPath("$.message").value("账号或密码错误"));
+    }
+
+    @Test
+    void should_return_ok_envelope_when_otp_send_succeeds() throws Exception {
+        mockMvc.perform(post("/app/auth/otp")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"scene\":\"REGISTER\",\"targetType\":\"PHONE\",\"target\":\"08123456789\",\"deviceId\":\"d-1\"}"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(0))
+                .andExpect(jsonPath("$.data").value(nullValue()));
+
+        verify(otpService).send(any(), any());
+    }
+
+    private TokenRespVO tokens(String accessToken, String refreshToken) {
+        TokenRespVO vo = new TokenRespVO();
+        vo.setAccessToken(accessToken);
+        vo.setRefreshToken(refreshToken);
+        vo.setExpiresIn(7200);
+        vo.setNewUser(true);
+        return vo;
+    }
+}

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

@@ -0,0 +1,115 @@
+// Author: fruit.com.cn
+package com.fruitshorts.app.controller;
+
+import com.fruitshorts.app.service.AppCatalogService;
+import com.fruitshorts.app.support.ControllerContractSupport;
+import com.fruitshorts.app.vo.AppBannerVO;
+import com.fruitshorts.app.vo.AppCategoryVO;
+import com.fruitshorts.app.vo.AppDramaDetailVO;
+import com.fruitshorts.app.vo.AppFeedVO;
+import com.fruitshorts.common.exception.ErrorCode;
+import com.fruitshorts.common.exception.ServiceException;
+import com.fruitshorts.playback.service.PlaybackService;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.test.web.servlet.MockMvc;
+
+import java.util.List;
+
+import static org.hamcrest.Matchers.nullValue;
+import static org.mockito.BDDMockito.given;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+/**
+ * 目录接口的接入层契约：`/app/home/feed`、`/app/discover/feed`、`/app/categories`、`/app/dramas/{id}`。
+ *
+ * <p>关注三件事：路由通不通、路径参数有没有绑对、响应壳是不是 `{code,message,data}`。
+ */
+class AppCatalogControllerContractTest {
+
+    private AppCatalogService catalogService;
+    private MockMvc catalogMvc;
+    private MockMvc dramaMvc;
+
+    @BeforeEach
+    void setUp() {
+        catalogService = mock(AppCatalogService.class);
+        catalogMvc = ControllerContractSupport.mockMvcOf(new AppCatalogController(catalogService));
+        dramaMvc = ControllerContractSupport.mockMvcOf(
+                new AppDramaController(catalogService, mock(PlaybackService.class)));
+    }
+
+    @Test
+    void should_return_banners_and_sections_when_home_feed_is_requested() throws Exception {
+        AppBannerVO banner = new AppBannerVO();
+        banner.setId(9L);
+        banner.setImageUrl("/files/banner/9.png");
+        banner.setLinkType("DRAMA");
+        banner.setLinkValue("12");
+        AppFeedVO feed = new AppFeedVO(List.of(banner), List.of());
+        given(catalogService.homeFeed()).willReturn(feed);
+
+        catalogMvc.perform(get("/app/home/feed"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(0))
+                .andExpect(jsonPath("$.data.banners[0].id").value(9))
+                .andExpect(jsonPath("$.data.banners[0].imageUrl").value("/files/banner/9.png"))
+                .andExpect(jsonPath("$.data.banners[0].linkType").value("DRAMA"));
+    }
+
+    @Test
+    void should_return_sections_when_discover_feed_is_requested() throws Exception {
+        AppFeedVO feed = new AppFeedVO(List.of(), List.of());
+        given(catalogService.discoverFeed()).willReturn(feed);
+
+        catalogMvc.perform(get("/app/discover/feed"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(0))
+                .andExpect(jsonPath("$.data.sections").isArray());
+    }
+
+    @Test
+    void should_return_category_list_when_categories_are_requested() throws Exception {
+        AppCategoryVO category = new AppCategoryVO(3L, "都市");
+        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].name").value("都市"));
+    }
+
+    @Test
+    void should_bind_path_variable_when_drama_detail_is_requested() throws Exception {
+        AppDramaDetailVO detail = new AppDramaDetailVO();
+        detail.setId(42L);
+        detail.setTitle("命运的相遇");
+        detail.setEpisodes(List.of());
+        given(catalogService.dramaDetail(42L)).willReturn(detail);
+
+        dramaMvc.perform(get("/app/dramas/42"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(0))
+                .andExpect(jsonPath("$.data.id").value("42"))
+                .andExpect(jsonPath("$.data.id").isString())
+                .andExpect(jsonPath("$.data.title").value("命运的相遇"));
+
+        verify(catalogService).dramaDetail(42L);
+    }
+
+    @Test
+    void should_return_data_not_found_code_when_drama_does_not_exist() throws Exception {
+        given(catalogService.dramaDetail(404L))
+                .willThrow(new ServiceException(ErrorCode.DATA_NOT_FOUND, "短剧不存在"));
+
+        dramaMvc.perform(get("/app/dramas/404"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(ErrorCode.DATA_NOT_FOUND.getCode()))
+                .andExpect(jsonPath("$.data").value(nullValue()));
+    }
+}

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

@@ -0,0 +1,171 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.app.controller;
+
+import com.fruitshorts.app.service.AppConfigService;
+import com.fruitshorts.app.service.AppNoticeService;
+import com.fruitshorts.app.support.ControllerContractSupport;
+import com.fruitshorts.common.exception.ErrorCode;
+import com.fruitshorts.common.exception.ServiceException;
+import com.fruitshorts.common.pojo.PageResult;
+import com.fruitshorts.creator.dal.entity.Creator;
+import com.fruitshorts.creator.service.CreatorAppService;
+import com.fruitshorts.creator.service.CreatorCenterService;
+import com.fruitshorts.creator.service.CreatorService;
+import com.fruitshorts.creator.vo.CreatorApplyReqVO;
+import com.fruitshorts.creator.vo.CreatorApplyRespVO;
+import com.fruitshorts.creator.vo.CreatorCenterDramaVO;
+import com.fruitshorts.framework.security.LoginUser;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.http.MediaType;
+import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
+import org.springframework.security.core.context.SecurityContextHolder;
+import org.springframework.test.web.servlet.MockMvc;
+
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.BDDMockito.given;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+/**
+ * E1 五个 C 端接口的接入层契约。
+ *
+ * <p>覆盖（对应条目门禁）：匿名可达 config/notices、未登录访问 creator 被拒、
+ * 重复 apply 幂等、非创作者看 works 被拒（200007）、`/app/config` 只回白名单键。
+ */
+class AppCreatorAndConfigContractTest {
+
+    private static final Long USER = 1001L;
+
+    private AppConfigService appConfigService;
+    private AppNoticeService appNoticeService;
+    private CreatorAppService creatorAppService;
+    private MockMvc configMvc;
+    private MockMvc creatorMvc;
+
+    @BeforeEach
+    void setUp() {
+        appConfigService = mock(AppConfigService.class);
+        appNoticeService = mock(AppNoticeService.class);
+        creatorAppService = mock(CreatorAppService.class);
+        configMvc = ControllerContractSupport.mockMvcOf(
+                new AppConfigController(appConfigService, appNoticeService));
+        creatorMvc = ControllerContractSupport.mockMvcOf(new AppCreatorController(
+                creatorAppService, appConfigService));
+    }
+
+    @AfterEach
+    void tearDown() {
+        SecurityContextHolder.clearContext();
+    }
+
+    private void login() {
+        SecurityContextHolder.getContext().setAuthentication(new UsernamePasswordAuthenticationToken(
+                new LoginUser(USER, "app-user", "APP_USER", List.of()), null, List.of()));
+    }
+
+    // ─────────── /app/config（匿名 + 白名单） ───────────
+
+    @Test
+    void should_return_only_whitelisted_keys_when_config_is_requested_anonymously() throws Exception {
+        // 服务层按白名单组装；这里再钉一遍"响应体里只有白名单键"
+        Map<String, Object> whitelist = new LinkedHashMap<>();
+        whitelist.put("agreementVersion", "2026-10-01");
+        whitelist.put("minAppVersion", "1.0.0");
+        whitelist.put("forceUpdate", false);
+        whitelist.put("noticeEnabled", true);
+        whitelist.put("coinUnlockEnabled", true);
+        whitelist.put("downloadEnabled", true);
+        given(appConfigService.appConfig()).willReturn(whitelist);
+
+        String body = configMvc.perform(get("/app/config"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(0))
+                .andExpect(jsonPath("$.data.agreementVersion").value("2026-10-01"))
+                .andExpect(jsonPath("$.data.forceUpdate").value(false))
+                .andReturn().getResponse().getContentAsString(java.nio.charset.StandardCharsets.UTF_8);
+
+        // 没登录也能拿到（匿名）
+        assertThat(SecurityContextHolder.getContext().getAuthentication()).isNull();
+        assertThat(body).doesNotContain("password").doesNotContain("secret").doesNotContain("token");
+    }
+
+    @Test
+    void should_return_empty_list_when_no_notice_exists() throws Exception {
+        given(appNoticeService.page(1, 20)).willReturn(new PageResult<>(0L, List.of()));
+
+        configMvc.perform(get("/app/notices"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(0))
+                .andExpect(jsonPath("$.data.total").value(0))
+                .andExpect(jsonPath("$.data.list").isArray());
+    }
+
+    // ─────────── /app/creator/**（需登录） ───────────
+
+    @Test
+    void should_reject_creator_apply_when_not_logged_in() throws Exception {
+        // 未设置 SecurityContext：控制器取不到 C 端用户 → 统一 401 信封
+        creatorMvc.perform(post("/app/creator/apply")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"name\":\"星野工作室\",\"agreementVersion\":\"2026-10-01\"}"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(ErrorCode.UNAUTHORIZED.getCode()));
+
+        verify(creatorAppService, never()).apply(any(), any(), anyString());
+    }
+
+    @Test
+    void should_return_current_status_when_applying_twice() throws Exception {
+        login();
+        given(appConfigService.agreementVersion()).willReturn("2026-10-01");
+        CreatorApplyRespVO first = applyResp(7L, CreatorService.STATUS_PENDING, true);
+        CreatorApplyRespVO second = applyResp(7L, CreatorService.STATUS_PENDING, false);
+        given(creatorAppService.apply(eq(USER), any(CreatorApplyReqVO.class), eq("2026-10-01")))
+                .willReturn(first, second);
+
+        String payload = "{\"name\":\"星野工作室\",\"type\":\"COMPANY\",\"agreementVersion\":\"2026-10-01\"}";
+        creatorMvc.perform(post("/app/creator/apply").contentType(MediaType.APPLICATION_JSON).content(payload))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.data.id").value("7"))
+                .andExpect(jsonPath("$.data.id").isString())
+                .andExpect(jsonPath("$.data.status").value(CreatorService.STATUS_PENDING))
+                .andExpect(jsonPath("$.data.created").value(true));
+
+        // 第二次提交：同一条记录、created=false（幂等）
+        creatorMvc.perform(post("/app/creator/apply").contentType(MediaType.APPLICATION_JSON).content(payload))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.data.id").value("7"))
+                .andExpect(jsonPath("$.data.id").isString())
+                .andExpect(jsonPath("$.data.created").value(false));
+    }
+
+
+
+
+
+    private CreatorApplyRespVO applyResp(Long id, String status, boolean created) {
+        CreatorApplyRespVO vo = new CreatorApplyRespVO();
+        vo.setId(id);
+        vo.setCode("CR20261016001");
+        vo.setName("星野工作室");
+        vo.setStatus(status);
+        vo.setStatusText(CreatorService.statusText(status));
+        vo.setCreated(created);
+        return vo;
+    }
+}

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

@@ -0,0 +1,179 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.app.controller;
+
+import com.fruitshorts.app.support.ControllerContractSupport;
+import com.fruitshorts.commerce.dal.entity.Orders;
+import com.fruitshorts.commerce.dal.entity.Product;
+import com.fruitshorts.commerce.dal.mapper.OrderEventMapper;
+import com.fruitshorts.commerce.dal.mapper.OrdersMapper;
+import com.fruitshorts.commerce.dal.mapper.ProductMapper;
+import com.fruitshorts.commerce.dal.mapper.StoreReceiptMapper;
+import com.fruitshorts.commerce.service.DisabledStoreVerifier;
+import com.fruitshorts.commerce.service.EntitlementService;
+import com.fruitshorts.commerce.service.OrderService;
+import com.fruitshorts.commerce.service.ProductService;
+import com.fruitshorts.commerce.service.StoreVerifier;
+import com.fruitshorts.commerce.service.UnlockService;
+import com.fruitshorts.commerce.service.WalletService;
+import com.fruitshorts.common.exception.ErrorCode;
+import com.fruitshorts.framework.security.LoginUser;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.http.MediaType;
+import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
+import org.springframework.security.core.context.SecurityContextHolder;
+import org.springframework.test.web.servlet.MockMvc;
+
+import java.math.BigDecimal;
+import java.nio.charset.StandardCharsets;
+import java.time.LocalDateTime;
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.BDDMockito.given;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+/**
+ * `/app/orders/verify` 的接入层契约：统一响应体 + 错误码 + "默认 disabled 行为不变"。
+ *
+ * <p>业务规则在 `fruitshorts-module-commerce` 的 `OrderServiceVerifyTest` 里测；
+ * 这里只钉"客户端会看到的 HTTP 表现"，用替身 verifier，不连库、不联网。
+ */
+class AppOrdersVerifyContractTest {
+
+    private static final Long USER = 1001L;
+    private static final String BODY = """
+            {"platform":"GOOGLE_PLAY","productId":"coin_550","receipt":"purchase-token-1"}""";
+
+    private OrdersMapper ordersMapper;
+    private ProductMapper productMapper;
+    private StoreReceiptMapper storeReceiptMapper;
+    private StubStoreVerifier verifier;
+    private MockMvc mockMvc;
+
+    @BeforeEach
+    void setUp() {
+        ordersMapper = mock(OrdersMapper.class);
+        productMapper = mock(ProductMapper.class);
+        storeReceiptMapper = mock(StoreReceiptMapper.class);
+        verifier = new StubStoreVerifier();
+        OrderService orderService = new OrderService(ordersMapper, mock(OrderEventMapper.class),
+                new ProductService(productMapper), storeReceiptMapper, verifier,
+                mock(WalletService.class), mock(EntitlementService.class));
+        mockMvc = ControllerContractSupport.mockMvcOf(new AppCommerceController(
+                mock(WalletService.class), mock(UnlockService.class), orderService));
+        SecurityContextHolder.getContext().setAuthentication(new UsernamePasswordAuthenticationToken(
+                new LoginUser(USER, "app-user", "APP_USER", List.of()), null, List.of()));
+    }
+
+    @AfterEach
+    void tearDown() {
+        SecurityContextHolder.clearContext();
+    }
+
+    @Test
+    void should_return_delivered_order_when_receipt_is_valid() throws Exception {
+        given(ordersMapper.selectOne(any())).willReturn(null);
+        given(productMapper.selectList(any())).willReturn(List.of(coinPack()));
+        verifier.result = new StoreVerifier.StoreReceiptResult(true, "GPA.3311-00001", "", "coin_550",
+                990000L, "IDR", LocalDateTime.now(), "Google Play 校验通过");
+
+        mockMvc.perform(post("/app/orders/verify").contentType(MediaType.APPLICATION_JSON).content(BODY))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(0))
+                .andExpect(jsonPath("$.data.status").value(OrderService.STATUS_DELIVERED))
+                .andExpect(jsonPath("$.data.coinAmount").value("550"))
+                .andExpect(jsonPath("$.data.coinAmount").isString())
+                .andExpect(jsonPath("$.data.platform").value("GOOGLE"))
+                .andExpect(jsonPath("$.data.storeTransactionId").value("GPA.3311-00001"));
+
+        verify(ordersMapper).insert(any(Orders.class));
+    }
+
+    @Test
+    void should_reject_with_operation_not_allowed_when_receipt_is_invalid() throws Exception {
+        verifier.result = StoreVerifier.StoreReceiptResult.failed("Google Play 购买状态不是已购买");
+
+        mockMvc.perform(post("/app/orders/verify").contentType(MediaType.APPLICATION_JSON).content(BODY))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(ErrorCode.OPERATION_NOT_ALLOWED.getCode()))
+                .andExpect(jsonPath("$.message").value("Google Play 购买状态不是已购买"));
+
+        verify(ordersMapper, never()).insert(any(Orders.class));
+    }
+
+    @Test
+    void should_reject_with_forbidden_when_receipt_belongs_to_another_user() throws Exception {
+        Orders others = new Orders();
+        others.setId(1L);
+        others.setOrderNo("FS202610161200000001");
+        others.setUserId(2002L);
+        others.setPlatform("GOOGLE");
+        others.setStoreTransactionId("GPA.3311-00001");
+        others.setStatus(OrderService.STATUS_DELIVERED);
+        given(ordersMapper.selectOne(any())).willReturn(others);
+        verifier.result = new StoreVerifier.StoreReceiptResult(true, "GPA.3311-00001", "", "coin_550",
+                990000L, "IDR", LocalDateTime.now(), "Google Play 校验通过");
+
+        mockMvc.perform(post("/app/orders/verify").contentType(MediaType.APPLICATION_JSON).content(BODY))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(ErrorCode.FORBIDDEN.getCode()))
+                .andExpect(jsonPath("$.message").value("该票据已绑定其他账号，不能重复使用"));
+    }
+
+    @Test
+    void should_keep_disabled_behaviour_when_store_is_not_configured() throws Exception {
+        // 默认实现（未配凭据）：对外仍是"尚未配置"，不产生订单
+        OrderService disabled = new OrderService(ordersMapper, mock(OrderEventMapper.class),
+                new ProductService(productMapper), storeReceiptMapper, new DisabledStoreVerifier(),
+                mock(WalletService.class), mock(EntitlementService.class));
+        MockMvc disabledMvc = ControllerContractSupport.mockMvcOf(new AppCommerceController(
+                mock(WalletService.class), mock(UnlockService.class), disabled));
+
+        String body = disabledMvc.perform(post("/app/orders/verify")
+                        .contentType(MediaType.APPLICATION_JSON).content(BODY))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(ErrorCode.OPERATION_NOT_ALLOWED.getCode()))
+                // MockMvc 的 getContentAsString() 在无 charset 时按 ISO-8859-1 解，中文会变乱码，
+                // 这里显式按 UTF-8 解码，断言才是真的在断言中文文案
+                .andReturn().getResponse().getContentAsString(StandardCharsets.UTF_8);
+
+        assertThat(body).contains("尚未配置");
+        verify(ordersMapper, never()).insert(any(Orders.class));
+    }
+
+    private Product coinPack() {
+        Product product = new Product();
+        product.setId(9L);
+        product.setCode("coin_550");
+        product.setName("550 金币");
+        product.setType("COIN_PACK");
+        product.setPlatform("ALL");
+        product.setStoreProductId("coin_550");
+        product.setCoinAmount(500L);
+        product.setBonusCoin(50L);
+        product.setPriceAmount(new BigDecimal("4.99"));
+        product.setCurrency("IDR");
+        product.setVipDays(0);
+        product.setStatus(1);
+        return product;
+    }
+
+    /** 替身 verifier：喂什么判定就返回什么。 */
+    private static final class StubStoreVerifier implements StoreVerifier {
+        private StoreReceiptResult result = StoreReceiptResult.failed("未设置");
+
+        @Override
+        public StoreReceiptResult verify(String platform, String productId, String receipt) {
+            return result;
+        }
+    }
+}

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

@@ -0,0 +1,98 @@
+// Author: fruit.com.cn
+package com.fruitshorts.app.controller;
+
+import com.fruitshorts.app.service.AppCatalogService;
+import com.fruitshorts.app.support.ControllerContractSupport;
+import com.fruitshorts.playback.service.PlaybackService;
+import com.fruitshorts.playback.vo.PlayRespVO;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.test.web.servlet.MockMvc;
+
+import java.util.List;
+
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.ArgumentMatchers.isNull;
+import static org.mockito.BDDMockito.given;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+/**
+ * 播放票据接口的接入层契约：`/app/episodes/{id}/play` 的免费/付费两种形态与参数透传。
+ *
+ * <p>免费 / 付费的**判定规则**在 {@code PlaybackServiceTest} 里用真服务验证；
+ * 这里钉的是"下发给客户端的字段长什么样"（客户端 Flutter 依赖这些字段名）。
+ */
+class AppPlaybackContractTest {
+
+    private PlaybackService playbackService;
+    private MockMvc mockMvc;
+
+    @BeforeEach
+    void setUp() {
+        playbackService = mock(PlaybackService.class);
+        mockMvc = ControllerContractSupport.mockMvcOf(
+                new AppDramaController(mock(AppCatalogService.class), playbackService));
+    }
+
+    @Test
+    void should_return_free_access_when_episode_is_free() throws Exception {
+        given(playbackService.play(isNull(), eq(11L), any(), any()))
+                .willReturn(ticket(11L, true, PlaybackService.ACCESS_FREE, "/files/ep.mp4?s=1"));
+
+        mockMvc.perform(get("/app/episodes/11/play").header("X-Device-Id", "device-9"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(0))
+                // §0：「ID 一律以字符串下发」——用 isString 钉住，避免"数字也能过"的宽松比较
+                .andExpect(jsonPath("$.data.episodeId").value("11"))
+                .andExpect(jsonPath("$.data.episodeId").isString())
+                .andExpect(jsonPath("$.data.accessible").value(true))
+                .andExpect(jsonPath("$.data.accessType").value(PlaybackService.ACCESS_FREE))
+                .andExpect(jsonPath("$.data.playUrl").value("/files/ep.mp4?s=1"));
+    }
+
+    @Test
+    void should_return_coin_required_when_episode_is_locked_and_not_entitled() throws Exception {
+        PlayRespVO locked = ticket(12L, false, PlaybackService.ACCESS_COIN_REQUIRED, "");
+        locked.setUnlockCoin(60);
+        given(playbackService.play(isNull(), eq(12L), any(), any())).willReturn(locked);
+
+        mockMvc.perform(get("/app/episodes/12/play"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.data.accessible").value(false))
+                .andExpect(jsonPath("$.data.accessType").value(PlaybackService.ACCESS_COIN_REQUIRED))
+                .andExpect(jsonPath("$.data.playUrl").value(""))
+                .andExpect(jsonPath("$.data.unlockCoin").value(60));
+    }
+
+    @Test
+    void should_pass_episode_id_and_device_header_when_play_is_requested() throws Exception {
+        given(playbackService.play(isNull(), eq(13L), eq("device-9"), any()))
+                .willReturn(ticket(13L, true, PlaybackService.ACCESS_FREE, "/files/ep13.mp4?s=1"));
+
+        mockMvc.perform(get("/app/episodes/13/play").header("X-Device-Id", "device-9"))
+                .andExpect(status().isOk());
+
+        verify(playbackService).play(isNull(), eq(13L), eq("device-9"), any());
+    }
+
+    private PlayRespVO ticket(Long episodeId, boolean accessible, String accessType, String playUrl) {
+        PlayRespVO vo = new PlayRespVO();
+        vo.setEpisodeId(episodeId);
+        vo.setDramaId(7L);
+        vo.setNumber(1);
+        vo.setTitle("第 1 集");
+        vo.setDurationSec(120);
+        vo.setAccessible(accessible);
+        vo.setAccessType(accessType);
+        vo.setPlayUrl(playUrl);
+        vo.setQualities(List.of("AUTO"));
+        vo.setUnlockCoin(0);
+        vo.setPreviewSeconds(0);
+        return vo;
+    }
+}

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

@@ -0,0 +1,390 @@
+// Author: fruit.com.cn
+package com.fruitshorts.app.service;
+
+import com.fruitshorts.common.exception.ErrorCode;
+import com.fruitshorts.common.exception.ServiceException;
+import com.fruitshorts.framework.security.JwtTokenProvider;
+import com.fruitshorts.system.service.ConfigService;
+import com.fruitshorts.user.dal.entity.AppUser;
+import com.fruitshorts.user.dal.entity.AppUserCredential;
+import com.fruitshorts.user.dal.entity.AppUserOtp;
+import com.fruitshorts.user.dal.entity.AppUserSession;
+import com.fruitshorts.user.dal.mapper.AppUserConsentMapper;
+import com.fruitshorts.user.dal.mapper.AppUserCredentialMapper;
+import com.fruitshorts.user.dal.mapper.AppUserDeviceMapper;
+import com.fruitshorts.user.dal.mapper.AppUserMapper;
+import com.fruitshorts.user.dal.mapper.AppUserOtpMapper;
+import com.fruitshorts.user.dal.mapper.AppUserSessionMapper;
+import com.fruitshorts.user.enums.AppUserStatus;
+import com.fruitshorts.user.service.AppAuthService;
+import com.fruitshorts.user.service.AppOtpService;
+import com.fruitshorts.user.service.CredentialHasher;
+import com.fruitshorts.user.service.OtpSender;
+import com.fruitshorts.user.vo.LoginReqVO;
+import com.fruitshorts.user.vo.RegisterReqVO;
+import com.fruitshorts.user.vo.TokenRespVO;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.security.crypto.password.PasswordEncoder;
+import org.springframework.test.util.ReflectionTestUtils;
+
+import java.time.Duration;
+import java.time.LocalDateTime;
+import java.util.concurrent.atomic.AtomicReference;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.BDDMockito.given;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+
+/**
+ * C 端注册 / 登录的**业务规则**测试：真 `AppAuthService` + 替身 Mapper，不连库。
+ *
+ * <p>覆盖几件接入层测不到的事：EMAIL 免码到底走没走验证码、密码强度、注册频控、
+ * 账号重复、密码比对与封禁判断。验证码本身的校验规则在 `AppOtpServiceTest`。
+ */
+class AppAuthServiceTest {
+
+    private AppUserMapper userMapper;
+    private AppUserCredentialMapper credentialMapper;
+    private AppUserSessionMapper sessionMapper;
+    private AppUserConsentMapper consentMapper;
+    private AppUserDeviceMapper deviceMapper;
+    private AppOtpService otpService;
+    private CredentialHasher hasher;
+    private JwtTokenProvider tokenProvider;
+    private PasswordEncoder passwordEncoder;
+    private ConfigService configService;
+    private AppAuthService authService;
+
+    @BeforeEach
+    void setUp() {
+        userMapper = mock(AppUserMapper.class);
+        credentialMapper = mock(AppUserCredentialMapper.class);
+        sessionMapper = mock(AppUserSessionMapper.class);
+        consentMapper = mock(AppUserConsentMapper.class);
+        deviceMapper = mock(AppUserDeviceMapper.class);
+        otpService = mock(AppOtpService.class);
+        hasher = mock(CredentialHasher.class);
+        tokenProvider = mock(JwtTokenProvider.class);
+        passwordEncoder = mock(PasswordEncoder.class);
+        configService = mock(ConfigService.class);
+        given(configService.get(anyString(), anyString()))
+                .willAnswer(invocation -> invocation.getArgument(1));
+        authService = new AppAuthService(userMapper, credentialMapper, sessionMapper, consentMapper,
+                deviceMapper, otpService, hasher, tokenProvider, passwordEncoder, configService);
+    }
+
+    @Test
+    void should_register_without_otp_when_target_type_is_email() {
+        stubHappyRegister();
+        AtomicReference<AppUserCredential> saved = captureCredential();
+
+        TokenRespVO resp = authService.register(emailRegister("abcd1234", null), "203.0.113.8");
+
+        assertThat(resp.getAccessToken()).isEqualTo("access-1");
+        assertThat(resp.getRefreshToken()).isEqualTo("refresh-1");
+        assertThat(resp.isNewUser()).isTrue();
+        // 免码注册不等于"已验证"：邮箱可达性没验证过，所以先记 0，等日后点验证链接再置 1
+        assertThat(saved.get().getVerified()).isZero();
+        verify(otpService, never()).consume(anyString(), anyString(), anyString(), any());
+    }
+
+    @Test
+    void should_consume_otp_when_email_register_carries_a_code() {
+        stubHappyRegister();
+
+        authService.register(emailRegister("abcd1234", "654321"), "203.0.113.8");
+
+        verify(otpService).consume(eq("REGISTER"), eq("EMAIL"), eq("a@b.com"), eq("654321"));
+    }
+
+    @Test
+    void should_consume_otp_when_target_type_is_phone() {
+        stubHappyRegister();
+
+        authService.register(phoneRegister("+628123456789", "654321"), "203.0.113.8");
+
+        verify(otpService).consume(eq("REGISTER"), eq("PHONE"), eq("+628123456789"), eq("654321"));
+    }
+
+    @Test
+    void should_reject_phone_register_when_no_code_was_requested() {
+        AppAuthService serviceWithRealOtp = serviceWithRealOtpService(null);
+
+        assertThatThrownBy(() -> serviceWithRealOtp.register(phoneRegister("+628123456789", ""), "203.0.113.8"))
+                .isInstanceOf(ServiceException.class)
+                .hasMessage("请先获取验证码");
+    }
+
+    @Test
+    void should_reject_phone_register_when_code_is_wrong() {
+        AppUserOtp issued = new AppUserOtp();
+        issued.setCodeHash("hash-of-654321");
+        issued.setExpireAt(LocalDateTime.now().plusMinutes(5));
+        issued.setFailCount(0);
+        AppAuthService serviceWithRealOtp = serviceWithRealOtpService(issued);
+
+        assertThatThrownBy(() -> serviceWithRealOtp.register(phoneRegister("+628123456789", "000000"), "203.0.113.8"))
+                .isInstanceOf(ServiceException.class)
+                .hasMessage("验证码不正确");
+    }
+
+    @Test
+    void should_reject_email_register_when_password_is_weak() {
+        RegisterReqVO req = emailRegister("abcdefgh", null);
+
+        assertThatThrownBy(() -> authService.register(req, "203.0.113.8"))
+                .isInstanceOf(ServiceException.class)
+                .hasMessageContaining("密码需同时包含字母和数字");
+    }
+
+    @Test
+    void should_reject_email_register_when_format_is_invalid() {
+        RegisterReqVO req = emailRegister("abcd1234", null);
+        req.setTarget("not-an-email");
+
+        assertThatThrownBy(() -> authService.register(req, "203.0.113.8"))
+                .isInstanceOf(ServiceException.class)
+                .hasMessage("邮箱格式不正确");
+    }
+
+    @Test
+    void should_return_data_exists_when_email_is_already_registered() {
+        given(userMapper.selectCount(any())).willReturn(0L);
+        AppUserCredential existing = new AppUserCredential();
+        existing.setUserId(1001L);
+        given(credentialMapper.selectOne(any())).willReturn(existing);
+
+        assertThatThrownBy(() -> authService.register(emailRegister("abcd1234", null), "203.0.113.8"))
+                .isInstanceOf(ServiceException.class)
+                .satisfies(ex -> assertThat(((ServiceException) ex).getCode())
+                        .isEqualTo(ErrorCode.DATA_EXISTS.getCode()))
+                .hasMessage("该账号已注册，请直接登录");
+    }
+
+    @Test
+    void should_reject_register_when_ip_reaches_the_daily_limit() {
+        setRegisterLimits(5, 3);
+        given(userMapper.selectCount(any())).willReturn(5L);
+
+        assertThatThrownBy(() -> authService.register(emailRegister("abcd1234", null), "203.0.113.8"))
+                .isInstanceOf(ServiceException.class)
+                .satisfies(ex -> assertThat(((ServiceException) ex).getCode())
+                        .isEqualTo(ErrorCode.TOO_MANY_REQUESTS.getCode()))
+                .hasMessageContaining("当前网络注册过于频繁");
+    }
+
+    @Test
+    void should_reject_register_when_device_reaches_the_daily_limit() {
+        setRegisterLimits(5, 3);
+        given(userMapper.selectCount(any())).willReturn(3L);
+
+        assertThatThrownBy(() -> authService.register(emailRegister("abcd1234", null), "203.0.113.8"))
+                .isInstanceOf(ServiceException.class)
+                .satisfies(ex -> assertThat(((ServiceException) ex).getCode())
+                        .isEqualTo(ErrorCode.TOO_MANY_REQUESTS.getCode()))
+                .hasMessage("该设备注册过于频繁，请稍后再试");
+    }
+
+    @Test
+    void should_fallback_to_default_limit_when_config_is_not_numeric() {
+        ReflectionTestUtils.setField(authService, "maxRegisterPerIpPerDay", 2);
+        given(configService.get("app.register.max-per-ip-per-day", "2")).willReturn("invalid");
+        given(userMapper.selectCount(any())).willReturn(2L);
+
+        assertThatThrownBy(() -> authService.register(emailRegister("abcd1234", null), "203.0.113.8"))
+                .isInstanceOf(ServiceException.class)
+                .satisfies(ex -> assertThat(((ServiceException) ex).getCode())
+                        .isEqualTo(ErrorCode.TOO_MANY_REQUESTS.getCode()))
+                .hasMessageContaining("当前网络注册过于频繁");
+    }
+
+    @Test
+    void should_fallback_to_default_limit_when_config_is_missing() {
+        given(userMapper.selectCount(any())).willReturn(5L);
+
+        assertThatThrownBy(() -> authService.register(emailRegister("abcd1234", null), "203.0.113.8"))
+                .isInstanceOf(ServiceException.class)
+                .satisfies(ex -> assertThat(((ServiceException) ex).getCode())
+                        .isEqualTo(ErrorCode.TOO_MANY_REQUESTS.getCode()))
+                .hasMessageContaining("当前网络注册过于频繁");
+    }
+
+    @Test
+    void should_not_limit_by_ip_when_ip_limit_is_zero() {
+        stubHappyRegister();
+        setRegisterLimits(0, 3);
+        given(userMapper.selectCount(any())).willReturn(2L);
+
+        assertThat(authService.register(emailRegister("abcd1234", null), "203.0.113.8").getAccessToken())
+                .isEqualTo("access-1");
+    }
+
+    @Test
+    void should_not_limit_by_device_when_device_limit_is_zero() {
+        stubHappyRegister();
+        setRegisterLimits(5, 0);
+        given(userMapper.selectCount(any())).willReturn(4L);
+
+        assertThat(authService.register(emailRegister("abcd1234", null), "203.0.113.8").getAccessToken())
+                .isEqualTo("access-1");
+    }
+
+    @Test
+    void should_return_tokens_when_password_matches() {
+        stubLogin(credential("bcrypt-hash"), user(AppUserStatus.NORMAL));
+        given(passwordEncoder.matches("abcd1234", "bcrypt-hash")).willReturn(true);
+
+        TokenRespVO resp = authService.login(emailLogin("abcd1234"), "203.0.113.8");
+
+        assertThat(resp.getAccessToken()).isEqualTo("access-1");
+        assertThat(resp.getUser().getUid()).isEqualTo("UAB12CD");
+        verify(sessionMapper).insert(any(AppUserSession.class));
+    }
+
+    @Test
+    void should_reject_login_when_password_does_not_match() {
+        stubLogin(credential("bcrypt-hash"), user(AppUserStatus.NORMAL));
+        given(passwordEncoder.matches("wrongpass1", "bcrypt-hash")).willReturn(false);
+
+        assertThatThrownBy(() -> authService.login(emailLogin("wrongpass1"), "203.0.113.8"))
+                .isInstanceOf(ServiceException.class)
+                .satisfies(ex -> assertThat(((ServiceException) ex).getCode())
+                        .isEqualTo(ErrorCode.LOGIN_FAILED.getCode()))
+                .hasMessage("账号或密码错误");
+    }
+
+    @Test
+    void should_reject_login_when_account_does_not_exist() {
+        given(credentialMapper.selectOne(any())).willReturn(null);
+
+        assertThatThrownBy(() -> authService.login(emailLogin("abcd1234"), "203.0.113.8"))
+                .isInstanceOf(ServiceException.class)
+                .satisfies(ex -> assertThat(((ServiceException) ex).getCode())
+                        .isEqualTo(ErrorCode.LOGIN_FAILED.getCode()))
+                .hasMessage("账号不存在，请先注册");
+    }
+
+    @Test
+    void should_reject_login_when_account_is_banned() {
+        stubLogin(credential("bcrypt-hash"), user(AppUserStatus.BANNED));
+        given(passwordEncoder.matches("abcd1234", "bcrypt-hash")).willReturn(true);
+
+        assertThatThrownBy(() -> authService.login(emailLogin("abcd1234"), "203.0.113.8"))
+                .isInstanceOf(ServiceException.class)
+                .satisfies(ex -> assertThat(((ServiceException) ex).getCode())
+                        .isEqualTo(ErrorCode.ACCOUNT_DISABLED.getCode()));
+    }
+
+    private void stubHappyRegister() {
+        given(userMapper.selectCount(any())).willReturn(0L);
+        given(credentialMapper.selectOne(any())).willReturn(null);
+        given(hasher.newUid()).willReturn("UAB12CD");
+        given(hasher.newRefreshToken()).willReturn("refresh-1");
+        given(hasher.sha256(anyString())).willReturn("hash-1");
+        given(passwordEncoder.encode(anyString())).willReturn("bcrypt-hash");
+        given(tokenProvider.createAppToken(any(), anyString(), any())).willReturn("access-1");
+        given(tokenProvider.accessTtlSeconds()).willReturn(7200L);
+        given(tokenProvider.appRefreshTtl()).willReturn(Duration.ofDays(30));
+        AtomicReference<AppUser> inserted = new AtomicReference<>();
+        given(userMapper.insert(any(AppUser.class))).willAnswer(invocation -> {
+            AppUser saved = invocation.getArgument(0);
+            saved.setId(1001L);
+            inserted.set(saved);
+            return 1;
+        });
+        given(userMapper.selectById(any())).willAnswer(invocation -> inserted.get());
+    }
+
+    private AtomicReference<AppUserCredential> captureCredential() {
+        AtomicReference<AppUserCredential> saved = new AtomicReference<>();
+        given(credentialMapper.insert(any(AppUserCredential.class))).willAnswer(invocation -> {
+            saved.set(invocation.getArgument(0));
+            return 1;
+        });
+        return saved;
+    }
+
+    private void stubLogin(AppUserCredential credential, AppUser user) {
+        given(credentialMapper.selectOne(any())).willReturn(credential);
+        given(userMapper.selectById(any())).willReturn(user);
+        given(hasher.newRefreshToken()).willReturn("refresh-1");
+        given(hasher.sha256(anyString())).willReturn("hash-1");
+        given(tokenProvider.createAppToken(any(), anyString(), any())).willReturn("access-1");
+        given(tokenProvider.accessTtlSeconds()).willReturn(7200L);
+        given(tokenProvider.appRefreshTtl()).willReturn(Duration.ofDays(30));
+    }
+
+    private AppAuthService serviceWithRealOtpService(AppUserOtp issued) {
+        AppUserOtpMapper otpMapper = mock(AppUserOtpMapper.class);
+        CredentialHasher otpHasher = mock(CredentialHasher.class);
+        given(otpMapper.selectOne(any())).willReturn(issued);
+        given(otpHasher.hashOtp(any())).willReturn("hash-of-something-else");
+        AppOtpService realOtpService = new AppOtpService(otpMapper, mock(OtpSender.class), otpHasher);
+        return new AppAuthService(userMapper, credentialMapper, sessionMapper, consentMapper,
+                deviceMapper, realOtpService, hasher, tokenProvider, passwordEncoder, configService);
+    }
+
+    private void setRegisterLimits(int perIp, int perDevice) {
+        given(configService.get("app.register.max-per-ip-per-day", "5"))
+                .willReturn(String.valueOf(perIp));
+        given(configService.get("app.register.max-per-device-per-day", "3"))
+                .willReturn(String.valueOf(perDevice));
+    }
+
+    private RegisterReqVO emailRegister(String password, String code) {
+        RegisterReqVO req = new RegisterReqVO();
+        req.setTargetType("EMAIL");
+        req.setTarget("a@b.com");
+        req.setPassword(password);
+        req.setCode(code);
+        req.setDeviceId("device-9");
+        req.setAgreementVersion("2026-10-01");
+        return req;
+    }
+
+    private RegisterReqVO phoneRegister(String target, String code) {
+        RegisterReqVO req = new RegisterReqVO();
+        req.setTargetType("PHONE");
+        req.setTarget(target);
+        req.setCode(code);
+        req.setDeviceId("device-9");
+        req.setAgreementVersion("2026-10-01");
+        return req;
+    }
+
+    private LoginReqVO emailLogin(String password) {
+        LoginReqVO req = new LoginReqVO();
+        req.setTargetType("EMAIL");
+        req.setTarget("a@b.com");
+        req.setPassword(password);
+        req.setDeviceId("device-9");
+        return req;
+    }
+
+    private AppUserCredential credential(String passwordHash) {
+        AppUserCredential credential = new AppUserCredential();
+        credential.setId(1L);
+        credential.setUserId(1001L);
+        credential.setType("EMAIL");
+        credential.setIdentifier("a@b.com");
+        credential.setPasswordHash(passwordHash);
+        return credential;
+    }
+
+    private AppUser user(String status) {
+        AppUser user = new AppUser();
+        user.setId(1001L);
+        user.setUid("UAB12CD");
+        user.setNickname("UserAB12CD");
+        user.setStatus(status);
+        user.setCountryCode("ID");
+        return user;
+    }
+}

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

@@ -0,0 +1,104 @@
+// Author: fruit.com.cn
+package com.fruitshorts.app.service;
+
+import com.fruitshorts.common.exception.ErrorCode;
+import com.fruitshorts.common.exception.ServiceException;
+import com.fruitshorts.user.dal.entity.AppUserOtp;
+import com.fruitshorts.user.dal.mapper.AppUserOtpMapper;
+import com.fruitshorts.user.service.AppOtpService;
+import com.fruitshorts.user.service.CredentialHasher;
+import com.fruitshorts.user.service.OtpSender;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import java.time.LocalDateTime;
+import java.util.concurrent.atomic.AtomicReference;
+
+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;
+
+/**
+ * 验证码**校验规则**测试：真 `AppOtpService` + 替身 Mapper。
+ *
+ * <p>注册/登录链路"PHONE 必须带验证码"的拒绝对外表现，靠这里的真规则 + `AppAuthServiceTest`
+ * 里的"必须调用 consume"两条一起钉住，避免两边都用替身导致互相假装。
+ */
+class AppOtpServiceTest {
+
+    private AppUserOtpMapper otpMapper;
+    private CredentialHasher hasher;
+    private AppOtpService otpService;
+
+    @BeforeEach
+    void setUp() {
+        otpMapper = mock(AppUserOtpMapper.class);
+        hasher = mock(CredentialHasher.class);
+        otpService = new AppOtpService(otpMapper, mock(OtpSender.class), hasher);
+    }
+
+    @Test
+    void should_reject_consume_when_no_code_was_requested() {
+        given(otpMapper.selectOne(any())).willReturn(null);
+
+        assertThatThrownBy(() -> otpService.consume("REGISTER", "PHONE", "+628123456789", "123456"))
+                .isInstanceOf(ServiceException.class)
+                .satisfies(ex -> assertThat(((ServiceException) ex).getCode())
+                        .isEqualTo(ErrorCode.BAD_REQUEST.getCode()))
+                .hasMessage("请先获取验证码");
+    }
+
+    @Test
+    void should_reject_consume_when_code_is_wrong() {
+        AppUserOtp issued = issuedOtp("hash-of-123456");
+        given(otpMapper.selectOne(any())).willReturn(issued);
+        given(hasher.hashOtp("000000")).willReturn("hash-of-000000");
+
+        assertThatThrownBy(() -> otpService.consume("REGISTER", "PHONE", "+628123456789", "000000"))
+                .isInstanceOf(ServiceException.class)
+                .hasMessage("验证码不正确");
+        // 失败要计数，连续错 5 次就作废（防爆破）
+        assertThat(issued.getFailCount()).isEqualTo(1);
+    }
+
+    @Test
+    void should_reject_consume_when_code_is_expired() {
+        AppUserOtp issued = issuedOtp("hash-of-123456");
+        issued.setExpireAt(LocalDateTime.now().minusMinutes(1));
+        given(otpMapper.selectOne(any())).willReturn(issued);
+
+        assertThatThrownBy(() -> otpService.consume("REGISTER", "PHONE", "+628123456789", "123456"))
+                .isInstanceOf(ServiceException.class)
+                .hasMessage("验证码已过期");
+    }
+
+    @Test
+    void should_mark_code_used_when_code_matches() {
+        AppUserOtp issued = issuedOtp("hash-of-123456");
+        AtomicReference<AppUserOtp> updated = new AtomicReference<>();
+        given(otpMapper.selectOne(any())).willReturn(issued);
+        given(hasher.hashOtp("123456")).willReturn("hash-of-123456");
+        given(otpMapper.updateById(any(AppUserOtp.class))).willAnswer(invocation -> {
+            updated.set(invocation.getArgument(0));
+            return 1;
+        });
+
+        otpService.consume("REGISTER", "PHONE", "+628123456789", "123456");
+
+        assertThat(updated.get().getUsedAt()).isNotNull();
+    }
+
+    private AppUserOtp issuedOtp(String codeHash) {
+        AppUserOtp otp = new AppUserOtp();
+        otp.setId(1L);
+        otp.setScene("REGISTER");
+        otp.setTargetType("PHONE");
+        otp.setTarget("+628123456789");
+        otp.setCodeHash(codeHash);
+        otp.setExpireAt(LocalDateTime.now().plusMinutes(5));
+        otp.setFailCount(0);
+        return otp;
+    }
+}

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

@@ -0,0 +1,145 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.app.service;
+
+import com.baomidou.mybatisplus.core.MybatisConfiguration;
+import com.baomidou.mybatisplus.core.metadata.TableInfoHelper;
+import com.fruitshorts.common.exception.ErrorCode;
+import com.fruitshorts.common.exception.ServiceException;
+import com.fruitshorts.creator.dal.entity.Creator;
+import com.fruitshorts.creator.dal.mapper.CreatorMapper;
+import com.fruitshorts.creator.service.CreatorAppService;
+import com.fruitshorts.creator.service.CreatorService;
+import com.fruitshorts.creator.vo.CreatorApplyReqVO;
+import com.fruitshorts.creator.vo.CreatorApplyRespVO;
+import org.apache.ibatis.builder.MapperBuilderAssistant;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.dao.DuplicateKeyException;
+
+import java.util.concurrent.atomic.AtomicReference;
+
+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;
+
+/**
+ * C 端创作者入驻的**业务规则**（真 service + 替身 Mapper）：幂等防重靠 DB、状态机报错口径。
+ *
+ * <p>契约层的 HTTP 表现见 `AppCreatorAndConfigContractTest`；这里钉的是"服务端真的只建一次"。
+ */
+class CreatorAppServiceTest {
+
+    private static final Long USER = 1001L;
+    private static final String AGREEMENT = "2026-10-01";
+
+    private CreatorMapper creatorMapper;
+    private CreatorAppService creatorAppService;
+
+    @BeforeAll
+    static void initTableInfoCache() {
+        // MyBatis-Plus 的 lambda 条件构造器需要实体的 TableInfo 缓存（纯单测没有 MP 上下文）
+        TableInfoHelper.initTableInfo(
+                new MapperBuilderAssistant(new MybatisConfiguration(), ""), Creator.class);
+    }
+
+    @BeforeEach
+    void setUp() {
+        creatorMapper = mock(CreatorMapper.class);
+        creatorAppService = new CreatorAppService(creatorMapper);
+    }
+
+    @Test
+    void should_insert_pending_creator_when_applying_for_the_first_time() {
+        given(creatorMapper.selectOne(any())).willReturn(null);
+        given(creatorMapper.selectCount(any())).willReturn(0L);
+        AtomicReference<Creator> saved = captureInsert();
+
+        CreatorApplyRespVO resp = creatorAppService.apply(USER, req(AGREEMENT), AGREEMENT);
+
+        assertThat(resp.isCreated()).isTrue();
+        assertThat(resp.getStatus()).isEqualTo(CreatorService.STATUS_PENDING);
+        assertThat(saved.get().getUserId()).isEqualTo(USER);
+        assertThat(saved.get().getCode()).startsWith("CR");
+        assertThat(saved.get().getStatus()).isEqualTo(CreatorService.STATUS_PENDING);
+    }
+
+    @Test
+    void should_return_existing_without_inserting_when_applying_again() {
+        Creator existing = creator(CreatorService.STATUS_PENDING);
+        given(creatorMapper.selectOne(any())).willReturn(existing);
+
+        CreatorApplyRespVO resp = creatorAppService.apply(USER, req(AGREEMENT), AGREEMENT);
+
+        assertThat(resp.isCreated()).isFalse();
+        assertThat(resp.getId()).isEqualTo(existing.getId());
+        // 关键的幂等保证：第二次提交不产生新的插入
+        verify(creatorMapper, never()).insert(any(Creator.class));
+    }
+
+    @Test
+    void should_return_existing_when_concurrent_insert_hits_the_unique_index() {
+        // 第一次查不到（并发对手还没提交完），插入时被唯一索引挡住 → 必须读回既有记录，不能报 500
+        given(creatorMapper.selectOne(any()))
+                .willReturn(null, creator(CreatorService.STATUS_PENDING));
+        given(creatorMapper.selectCount(any())).willReturn(0L);
+        given(creatorMapper.insert(any(Creator.class)))
+                .willThrow(new DuplicateKeyException("uk_creator_user"));
+
+        CreatorApplyRespVO resp = creatorAppService.apply(USER, req(AGREEMENT), AGREEMENT);
+
+        assertThat(resp.isCreated()).isFalse();
+        assertThat(resp.getStatus()).isEqualTo(CreatorService.STATUS_PENDING);
+    }
+
+
+
+
+
+    private AtomicReference<Creator> captureInsert() {
+        AtomicReference<Creator> saved = new AtomicReference<>();
+        given(creatorMapper.insert(any(Creator.class))).willAnswer(invocation -> {
+            Creator creator = invocation.getArgument(0);
+            creator.setId(7L);
+            saved.set(creator);
+            return 1;
+        });
+        return saved;
+    }
+
+    @Test
+    void should_reject_when_agreement_version_is_not_the_current_one() {
+        // 协议版本必须等于 /app/config 下发的当前版本（保留用例：apply 的协议校验）
+        assertThatThrownBy(() -> creatorAppService.apply(USER, req("2026-09-01"), AGREEMENT))
+                .isInstanceOf(ServiceException.class)
+                .satisfies(ex -> assertThat(((ServiceException) ex).getCode())
+                        .isEqualTo(ErrorCode.BAD_REQUEST.getCode()))
+                .hasMessageContaining("请先同意最新版协议");
+        verify(creatorMapper, never()).insert(any(Creator.class));
+    }
+
+    private CreatorApplyReqVO req(String agreementVersion) {
+        CreatorApplyReqVO req = new CreatorApplyReqVO();
+        req.setName("星野工作室");
+        req.setType("COMPANY");
+        req.setContactEmail("creator@example.com");
+        req.setAgreementVersion(agreementVersion);
+        return req;
+    }
+
+    private Creator creator(String status) {
+        Creator creator = new Creator();
+        creator.setId(7L);
+        creator.setCode("CR20261016001");
+        creator.setName("星野工作室");
+        creator.setUserId(USER);
+        creator.setStatus(status);
+        creator.setAuditNote("");
+        return creator;
+    }
+}

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

@@ -0,0 +1,146 @@
+// Author: fruit.com.cn
+package com.fruitshorts.app.service;
+
+import com.fruitshorts.content.dal.entity.Drama;
+import com.fruitshorts.content.dal.entity.DramaEpisode;
+import com.fruitshorts.content.service.DramaService;
+import com.fruitshorts.content.service.EpisodeService;
+import com.fruitshorts.media.service.PlaybackSigner;
+import com.fruitshorts.media.service.TranscodeService;
+import com.fruitshorts.playback.dal.entity.PlaybackTicket;
+import com.fruitshorts.playback.dal.mapper.PlaybackTicketMapper;
+import com.fruitshorts.playback.service.EntitlementPort;
+import com.fruitshorts.playback.service.PlaybackService;
+import com.fruitshorts.playback.vo.PlayRespVO;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyLong;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.ArgumentMatchers.isNull;
+import static org.mockito.BDDMockito.given;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+
+/**
+ * 播放票据的**判定规则**测试：真 `PlaybackService` + 替身依赖，不连库。
+ *
+ * <p>两条关键分支（接入层只验证字段形态，判定在这里）：免费集一律给签名地址；
+ * 付费集在没权益时**不给地址**，只回 `COIN_REQUIRED` 与所需金币。
+ */
+class PlaybackServiceTest {
+
+    private EpisodeService episodeService;
+    private DramaService dramaService;
+    private PlaybackTicketMapper ticketMapper;
+    private PlaybackSigner signer;
+    private EntitlementPort entitlementPort;
+    private TranscodeService transcodeService;
+    private PlaybackService playbackService;
+
+    @BeforeEach
+    void setUp() {
+        episodeService = mock(EpisodeService.class);
+        dramaService = mock(DramaService.class);
+        ticketMapper = mock(PlaybackTicketMapper.class);
+        signer = mock(PlaybackSigner.class);
+        entitlementPort = mock(EntitlementPort.class);
+        transcodeService = mock(TranscodeService.class);
+        playbackService = new PlaybackService(episodeService, dramaService, ticketMapper, signer,
+                entitlementPort, transcodeService);
+        given(dramaService.getPublished(anyLong())).willReturn(drama());
+        given(transcodeService.listRenditions(anyLong())).willReturn(List.of());
+        given(signer.sign(anyString())).willReturn("/files/episode/1.mp4?e=1&s=sig");
+    }
+
+    @Test
+    void should_return_free_access_when_episode_is_free() {
+        given(episodeService.getPublished(11L)).willReturn(episode(11L, 1, 0, "/files/episode/1.mp4"));
+
+        PlayRespVO resp = playbackService.play(null, 11L, "device-9", "203.0.113.8");
+
+        assertThat(resp.getAccessible()).isTrue();
+        assertThat(resp.getAccessType()).isEqualTo(PlaybackService.ACCESS_FREE);
+        assertThat(resp.getPlayUrl()).isEqualTo("/files/episode/1.mp4?e=1&s=sig");
+        // 未登录不记票据（票据是"已登录用户"的签发审计）
+        verify(ticketMapper, never()).insert(any(PlaybackTicket.class));
+    }
+
+    @Test
+    void should_return_coin_required_when_episode_is_locked_and_not_entitled() {
+        given(episodeService.getPublished(12L)).willReturn(episode(12L, 0, 60, "/files/episode/2.mp4"));
+        given(entitlementPort.isUnlocked(anyLong(), anyLong(), anyLong())).willReturn(false);
+
+        PlayRespVO resp = playbackService.play(1001L, 12L, "device-9", "203.0.113.8");
+
+        assertThat(resp.getAccessible()).isFalse();
+        assertThat(resp.getAccessType()).isEqualTo(PlaybackService.ACCESS_COIN_REQUIRED);
+        assertThat(resp.getPlayUrl()).isEmpty();
+        assertThat(resp.getUnlockCoin()).isEqualTo(60);
+        verify(ticketMapper, never()).insert(any(PlaybackTicket.class));
+    }
+
+    @Test
+    void should_return_entitled_access_when_entitlement_port_confirms_unlock() {
+        given(episodeService.getPublished(13L)).willReturn(episode(13L, 0, 60, "/files/episode/3.mp4"));
+        given(entitlementPort.isUnlocked(eq(1001L), anyLong(), eq(13L))).willReturn(true);
+
+        PlayRespVO resp = playbackService.play(1001L, 13L, "device-9", "203.0.113.8");
+
+        assertThat(resp.getAccessible()).isTrue();
+        assertThat(resp.getAccessType()).isEqualTo(PlaybackService.ACCESS_ENTITLED);
+        assertThat(resp.getPlayUrl()).isEqualTo("/files/episode/1.mp4?e=1&s=sig");
+        verify(ticketMapper).insert(any(PlaybackTicket.class));
+    }
+
+    @Test
+    void should_return_no_media_when_episode_has_no_source() {
+        given(episodeService.getPublished(14L)).willReturn(episode(14L, 1, 0, ""));
+
+        PlayRespVO resp = playbackService.play(isNull(), 14L, "device-9", "203.0.113.8");
+
+        assertThat(resp.getAccessible()).isFalse();
+        assertThat(resp.getAccessType()).isEqualTo(PlaybackService.ACCESS_NO_MEDIA);
+        assertThat(resp.getPlayUrl()).isEmpty();
+    }
+
+    @Test
+    void should_prefer_hls_url_when_the_episode_has_multi_bitrate_renditions() {
+        DramaEpisode episode = episode(15L, 1, 0, "/files/episode/origin.mp4");
+        episode.setHlsUrl("/files/episode/15/master.m3u8");
+        given(episodeService.getPublished(15L)).willReturn(episode);
+
+        PlayRespVO resp = playbackService.play(null, 15L, "device-9", "203.0.113.8");
+
+        assertThat(resp.getPlayUrl()).isEqualTo("/files/episode/1.mp4?e=1&s=sig");
+        verify(signer).sign("/files/episode/15/master.m3u8");
+    }
+
+    private DramaEpisode episode(Long id, int isFree, int unlockCoin, String videoUrl) {
+        DramaEpisode episode = new DramaEpisode();
+        episode.setId(id);
+        episode.setDramaId(7L);
+        episode.setEpNo(1);
+        episode.setTitle("第 1 集");
+        episode.setDurationSec(120);
+        episode.setIsFree(isFree);
+        episode.setUnlockCoin(unlockCoin);
+        episode.setPreviewSeconds(0);
+        episode.setVideoUrl(videoUrl);
+        episode.setStatus("published");
+        return episode;
+    }
+
+    private Drama drama() {
+        Drama drama = new Drama();
+        drama.setId(7L);
+        drama.setTitle("命运的相遇");
+        return drama;
+    }
+}

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

@@ -0,0 +1,46 @@
+// Author: fruit.com.cn
+package com.fruitshorts.app.support;
+
+import com.fruitshorts.framework.log.AccessDeniedRecorder;
+import com.fruitshorts.framework.web.JacksonLongToStringConfig;
+import com.fruitshorts.framework.web.GlobalExceptionHandler;
+import com.fasterxml.jackson.databind.SerializationFeature;
+import com.fasterxml.jackson.databind.json.JsonMapper;
+import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule;
+import org.mockito.Mockito;
+import org.springframework.beans.factory.ObjectProvider;
+import org.springframework.http.converter.json.MappingJackson2HttpMessageConverter;
+import org.springframework.test.web.servlet.MockMvc;
+import org.springframework.test.web.servlet.setup.MockMvcBuilders;
+
+/**
+ * 控制器契约测试的公共装配：真控制器 + 真全局异常处理器 + 真校验器，**不启 Spring 容器**。
+ *
+ * <p>为什么不用 {@code @WebMvcTest}：{@code AppApiApplication} 上挂着
+ * {@code @MapperScan("com.fruitshorts.**.dal.mapper")}，而切片测试不装配 DataSource / MyBatis，
+ * 扫描出的 Mapper 工厂会因为缺少 {@code SqlSessionFactory} 直接报错；要绕开就得再加一套测试专用的
+ * 引导配置。这里的 standaloneSetup 同样只装 Web 层（路由、参数绑定、消息转换、异常处理），
+ * 覆盖面不变而更轻、更稳。
+ */
+public final class ControllerContractSupport {
+
+    private ControllerContractSupport() {
+    }
+
+    /** 组装一个只含指定控制器与全局异常处理的 MockMvc。 */
+    @SuppressWarnings("unchecked")
+    public static MockMvc mockMvcOf(Object controller) {
+        AccessDeniedRecorder recorder = new AccessDeniedRecorder(Mockito.mock(ObjectProvider.class));
+        return MockMvcBuilders.standaloneSetup(controller)
+                .setControllerAdvice(new GlobalExceptionHandler(recorder))
+                // 与 Spring Boot 的 Jackson 配置对齐：时间按 ISO 字符串输出而不是数组，
+                // 否则契约测试断言 LocalDate/LocalDateTime 时会看到 [2026,10,15] 这种形态。
+                .setMessageConverters(new MappingJackson2HttpMessageConverter(JsonMapper.builder()
+                        .addModule(new JavaTimeModule())
+                        // 与生产一致：Long/long 一律输出成字符串（见 JacksonLongToStringConfig）
+                        .addModule(JacksonLongToStringConfig.longToStringModule())
+                        .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS)
+                        .build()))
+                .build();
+    }
+}

fruitshorts-framework/src/main/java/com/fruitshorts/framework/config/ProdSecretGuard.java

@@ -0,0 +1,88 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.framework.config;
+
+import jakarta.annotation.PostConstruct;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.context.annotation.Profile;
+import org.springframework.core.env.Environment;
+import org.springframework.stereotype.Component;
+import org.springframework.util.StringUtils;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * 生产环境密钥把关：`prod` profile 下，密钥缺失、仍等于代码里的 dev 默认值、
+ * 或长度不足 32 位（以及"播放签名没开"）→ **启动直接失败**。
+ *
+ * <p>为什么要有它：`docs/12-上线检查清单` 要求密钥一律走环境变量、播放签名生产必开，
+ * 但属性类里为了本地开箱即用带了 dev 默认值 —— 一旦生产漏配，服务会**安静地**用 dev 密钥跑起来，
+ * 后果是令牌/播放地址可被伪造。这里把"安静失败"改成"启动即报错"。
+ *
+ * <p>用 {@link Environment} 读**解析后**的属性（含 yml 里的默认值），而不是注入各模块的属性类：
+ * framework 不该反向依赖 media 模块，这样三个可运行件都能复用同一份校验。
+ * 只校验"配置是否可上线"，不碰任何业务逻辑；非 prod profile 完全不受影响。
+ */
+@Slf4j
+@Component
+@Profile("prod")
+@RequiredArgsConstructor
+public class ProdSecretGuard {
+
+    /** 代码里为本地开发准备的默认值，生产出现即视为未配置。 */
+    private static final List<String> DEV_DEFAULTS = List.of(
+            "fruitshorts-admin-dev-secret-change-me-in-production-32b",
+            "fruitshorts-app-dev-secret-change-me-in-production-32bytes",
+            "fruitshorts-media-dev-secret-change-me-in-production-32b");
+
+    private static final int MIN_SECRET_LENGTH = 32;
+
+    private final Environment environment;
+
+    @PostConstruct
+    public void verify() {
+        List<String> problems = new ArrayList<>();
+        check(problems, "fruitshorts.jwt.admin-secret（环境变量 JWT_ADMIN_SECRET）",
+                environment.getProperty("fruitshorts.jwt.admin-secret"));
+        check(problems, "fruitshorts.jwt.app-secret（环境变量 JWT_APP_SECRET）",
+                environment.getProperty("fruitshorts.jwt.app-secret"));
+        check(problems, "fruitshorts.media.signature-secret（环境变量 MEDIA_SIGNATURE_SECRET）",
+                environment.getProperty("fruitshorts.media.signature-secret"));
+        if (!environment.getProperty("fruitshorts.media.signature-required", Boolean.class, false)) {
+            problems.add("fruitshorts.media.signature-required 必须为 true"
+                    + "（docs/12-上线检查清单：生产必开播放地址签名）");
+        }
+        if (!StringUtils.hasText(environment.getProperty("spring.datasource.url"))) {
+            problems.add("spring.datasource.url 为空（环境变量 DB_URL）");
+        }
+        if (environment.getProperty("fruitshorts.cors.allowed-origins", "").isBlank()) {
+            problems.add("fruitshorts.cors.allowed-origins 为空（环境变量 CORS_ALLOWED_ORIGINS）"
+                    + "—— 生产不允许用通配 *，必须显式列出来源");
+        }
+        if (!problems.isEmpty()) {
+            String message = "生产配置校验未通过，拒绝启动（prod profile）：\n  - "
+                    + String.join("\n  - ", problems)
+                    + "\n请按 FruitServer/DEPLOY.md 的环境变量清单补齐后重启。";
+            log.error(message);
+            throw new IllegalStateException(message);
+        }
+        log.info("生产配置校验通过：JWT 双密钥 + 媒体签名密钥均已注入，播放签名已强制开启");
+    }
+
+    private void check(List<String> problems, String name, String value) {
+        if (!StringUtils.hasText(value)) {
+            problems.add(name + " 未配置（空）");
+            return;
+        }
+        if (DEV_DEFAULTS.contains(value.trim())) {
+            problems.add(name + " 仍是代码里的 dev 默认值，必须换成生产密钥");
+            return;
+        }
+        if (value.trim().length() < MIN_SECRET_LENGTH) {
+            problems.add(name + " 长度不足 " + MIN_SECRET_LENGTH + " 位（当前 "
+                    + value.trim().length() + " 位）");
+        }
+    }
+}

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

@@ -41,6 +41,9 @@ public class SecurityConfig {
             "/app/dramas/**",
             "/app/episodes/*/play",
             "/app/config/**",
+            /* 启动配置与公告：客户端登录前就要拿（POST /app/creator/apply 等仍要登录） */
+            "/app/config",
+            "/app/notices",
             /* 媒资：封面与视频用 <img>/<video> 直接访问，无法带请求头。
                片源的防盗链由 fruitshorts.media.signature-required 控制。 */
             "/files/**",
@@ -48,6 +51,8 @@ public class SecurityConfig {
             "/swagger-ui/**",
             "/swagger-ui.html",
             "/v3/api-docs/**",
+            /* 健康检查：给容器编排与冒烟脚本用（本项目没引 actuator，见 HealthController 注释） */
+            "/healthz",
             "/actuator/health"
     };
 

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

@@ -0,0 +1,45 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.framework.web;
+
+import com.fruitshorts.common.pojo.Result;
+import lombok.RequiredArgsConstructor;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.core.env.Environment;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.time.LocalDateTime;
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+/**
+ * 轻量健康检查端点：`GET /healthz`。
+ *
+ * <p>为什么不直接用 `/actuator/health`：本项目**没有引入 actuator 依赖**（jar 里 0 个 actuator 类），
+ * 那个路径一直是"未映射"状态 —— 早期观察到的"超时"是另一回事（旧 jar 未重启，见 `docs/plans/INBOX.md` S1 条目）。
+ * 部署需要的只是一个"进程活着、能响应 HTTP"的信号，这个端点足够，且不引新依赖。
+ *
+ * <p>要换成 actuator（带 DB/Redis 健康指示器）时：加依赖 + 把 actuator 路径加进
+ * {@code SecurityConfig.PUBLIC_PATHS}（那里已经预留了 `/actuator/health`）。
+ */
+@RestController
+@RequiredArgsConstructor
+public class HealthController {
+
+    private final Environment environment;
+
+    @Value("${spring.application.name:unknown}")
+    private String applicationName;
+
+    /** 返回统一响应体，便于与其它接口共用同一套客户端解包逻辑。 */
+    @GetMapping("/healthz")
+    public Result<Map<String, Object>> health() {
+        Map<String, Object> data = new LinkedHashMap<>();
+        data.put("status", "UP");
+        data.put("app", applicationName);
+        data.put("profiles", String.join(",", environment.getActiveProfiles()));
+        data.put("time", LocalDateTime.now().toString());
+        return Result.ok(data);
+    }
+}

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

@@ -0,0 +1,78 @@
+// Author: fruit.com.cn
+
+package com.fruitshorts.framework.web;
+
+import com.fasterxml.jackson.core.JsonGenerator;
+import com.fasterxml.jackson.databind.JsonSerializer;
+import com.fasterxml.jackson.databind.SerializerProvider;
+import com.fasterxml.jackson.databind.annotation.JsonSerialize;
+import com.fasterxml.jackson.databind.module.SimpleModule;
+import com.fasterxml.jackson.databind.ser.std.ToStringSerializer;
+import com.fruitshorts.common.pojo.PageResult;
+import org.springframework.boot.autoconfigure.jackson.Jackson2ObjectMapperBuilderCustomizer;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+import java.io.IOException;
+
+/**
+ * 全局把 {@link Long} / {@code long} 序列化成 JSON 字符串。
+ *
+ * <p>为什么需要它：S0 把主键换成雪花 id 之后，id 是 19 位十进制数（例如 {@code 2111012753262120962}），
+ * 而 JS 的 {@code Number.MAX_SAFE_INTEGER} 只有 {@code 9007199254740991}。裸数字下发会被浏览器
+ * （以及任何用 IEEE754 double 解析 JSON 的客户端）四舍五入，页面拿这个 id 回查就是"数据不存在" ——
+ * 后台"新建一条记录再点编辑/下架"必然踩中。
+ *
+ * <p>所以：**所有 ID 字段一律以字符串下发**（见 `docs/api-phase1.md` §0）。注意两点：
+ * <ul>
+ *   <li>只动 {@code Long}/{@code long}，**不动 {@code Integer}/{@code int}**（分页 pageIndex/pageSize、
+ *       {@code Result.code} 等保持数字）；</li>
+ *   <li>反序列化方向不受影响：Jackson 默认允许把 {@code "123"} 标量强转成 {@code Long}，
+ *       路径变量与查询参数本来就走 String→Long 转换，所以前端把 id 当字符串回传没问题。</li>
+ * </ul>
+ *
+ * <p>放在 framework 模块，admin-api 与 app-api 都扫得到（两个入口都是
+ * {@code scanBasePackages = "com.fruitshorts"}），一处生效两端一致。
+ */
+@Configuration
+public class JacksonLongToStringConfig {
+
+    /** 供测试直接复用：拿到挂了 Long→String 的模块。 */
+    public static SimpleModule longToStringModule() {
+        SimpleModule module = new SimpleModule("LongToStringModule");
+        module.addSerializer(Long.class, ToStringSerializer.instance);
+        module.addSerializer(Long.TYPE, ToStringSerializer.instance);
+        // 唯一的例外：分页 total 是计数不是 id，保持数字（前端分页组件要数字）
+        module.setMixInAnnotation(PageResult.class, PageResultTotalAsNumber.class);
+        return module;
+    }
+
+    /**
+     * 把 {@code PageResult.total} 的序列化钉成数字的混入声明。
+     *
+     * <p>用 mixin 而不是给实体加注解，是为了让"例外"跟"规则"写在同一个文件里，
+     * 也避免给 fruitshorts-common 引入 jackson 依赖。
+     */
+    abstract static class PageResultTotalAsNumber {
+        @JsonSerialize(using = PlainLongSerializer.class)
+        abstract long getTotal();
+    }
+
+    /** 把 long 原样写成 JSON 数字（全局规则把它们都变成字符串了，这里显式还原）。 */
+    public static final class PlainLongSerializer extends JsonSerializer<Long> {
+        @Override
+        public void serialize(Long value, JsonGenerator gen, SerializerProvider serializers)
+                throws IOException {
+            if (value == null) {
+                gen.writeNull();
+            } else {
+                gen.writeNumber(value.longValue());
+            }
+        }
+    }
+
+    @Bean
+    public Jackson2ObjectMapperBuilderCustomizer longToStringCustomizer() {
+        return builder -> builder.modulesToInstall(longToStringModule());
+    }
+}