www_site/docs/phase-4-report.md

Phase 4 CMS 基础与管理后台报告

日期：2026-09-10 范围：P4-01 至 P4-07 状态：CMS 数据边界、模型、公共内容 API、可复现迁移、受控管理员、访问控制与真实内容闭环，以及用户/VIP/额度/TTS/审计管理后台均已验收通过。

1. 已完成

数据边界与模型

• 新增独立 Payload CMS 应用：apps/cms。
• CMS 使用独立 PostgreSQL 数据库 kaotings_cms 和独立数据库账号，不读取业务 API 用户表。
• 已配置 systemd 服务 kaotings-cms，仅监听 127.0.0.1:3001。
• Caddy 保留 /cms 外部边界，不向公网开放 CMS 回环端口。
• 建立模型：Users、Products、Media、SiteSettings、HomeContent。
• Product 支持 draft、published、unpublished，slug、分类、摘要、描述、媒体、features、specs、SEO 和排序字段。
• Media 为受控上传集合，普通访客只读媒体，写入需要 CMS 用户。

公共内容 API 与 Caddy 前缀

• Next.js basePath 为 /cms，Caddy 用 handle /cms/* 原样透传给 CMS 服务（不剥离前缀），避免资源地址/重定向丢失 /cms。
• /cms/admin、/cms/admin/create-first-user 可正常渲染 Payload 管理界面（200），资源以 /cms/_next/... 加载正常，无重定向循环。
• 公共 Products API GET /cms/api/products 返回 200 和空集合，未泄露草稿。
• Website 内容适配器已切换到 CMS 公共 API；lib/content.ts 的 getProducts 以 ?where[status][equals]=published 拉取，cache: no-store，CMS 未发布产品时显示明确空状态。

数据库初始化固化（P4-01）

• 核对执行记录：payload_migrations 仅含 20260909_100120_initial（batch 1），与现有 kaotings_cms 结构一致。
• 已重新生成初始迁移并修正类型导入，命名为 20260909_100120_initial 以对齐已应用记录，避免重复应用。
• 迁移文件提交进仓库：apps/cms/src/migrations/20260909_100120_initial.ts。
• 使用独立临时库 kaotings_cms_verify 从仓库 payload migrate 重建，得到 14 张表，列类型比对 SCHEMA_IDENTICAL；随后删除临时库，现有 kaotings_cms 未清空。
• 迁移类型导入已修正（MigrateUpArgs/MigrateDownArgs 用 import type，sql 用值导入），本地与服务端构建均通过。

受控初始化 CMS 管理员（P4-02）

• 通过一次性受控路由 apps/cms/src/app/api/seed-admin/route.ts 初始化管理员，凭据来自 /etc/kaotings/cms-admin.secrets（root-only 0600），未写入 Git/报告/日志。
• 路由以 x-cms-seed-token 守卫，且仅在用户表为空时创建；已存在用户时返回 409 {"ok":false,"error":"user exists"}，防止重复初始化。
• 管理员：tech@kaotings.com（displayName: CMS Admin）。登录验证 200 {"message":"Authentication Passed"}。
• 修正：seed 路由不得在 Next 运行时调用 payload.destroy()（会销毁共享数据库连接池，导致后续请求 500）。

访问控制验证（P4-02）

• 匿名 POST /cms/api/users/first-register → 403（已有用户后 create-first-user 失效）。
• 匿名 POST /cms/api/users（注册）→ 403。
• 匿名 GET /cms/api/users、GET /cms/api/users/1（读取用户资料）→ 403。
• 匿名 PATCH /cms/api/users/1（提权/修改）→ 403。
• 匿名 GET /cms/api/access：canAccessAdmin:false（枚举到字段级权限，非仅状态码）。
• 管理员 GET /cms/api/access：canAccessAdmin:true。
• 普通网站用户属独立数据库 kaotings（角色 kaotings_app），CMS 使用 kaotings_cms 且签发自有 payload-token JWT，网站 kaotings_session cookie 不会被 CMS 接受，跨库无法获取 CMS 管理会话。

真实内容闭环（P4-03）

• 以管理员登录后创建明确标注的测试产品（slug p4-test-draft-product）：
  • 草稿：公共列表/API docs:[]，官网 /products 与详情不显示。
  • 发布：GET /cms/api/products 返回该产品；官网 /products 列表显示，详情页渲染正确。
  • 修改：更新 summary/name 后，公共列表与官网详情立即反映新内容（no-store，无缓存陈旧）。
  • 下架：status:unpublished 后，公共列表/API 为空，官网详情 404 Not Found。
• 测试产品已下架（当前 status:unpublished），不对公网提供内容。

2. 修复的集成问题

• /cms/admin 前缀重定向/404：Next 恢复 basePath: "/cms"，Caddy 改用 handle /cms/* 透传，不再由 Caddy 剥离前缀。
• Website CMS_PUBLIC_API_URL 需指向 http://127.0.0.1:3001/cms（此前缺 /cms 前缀导致官网 /products 500）：已更新 kaotings-web.service 环境变量。
• Payload Admin 的 serverFunction/importMap 接线：改用生成的真实 importMap 和 @payloadcms/next/layouts 的 handleServerFunctions。
• 产品 slug 查询统一使用已验证的筛选方式：GET /cms/api/products?where[slug][equals]=<slug>（返回 200）。Payload 的 GET /cms/api/products/:slug 是按 id 处理的路由，不是 slug 路由，任何单产品按 slug 取数都必须用 where[slug][equals]= 筛选，不得把按 id 的路由当作按 slug 使用。

管理后台（P4-04 至 P4-07）

• 复用既有 FastAPI 管理接口，不新建用户或会员体系，全部基于 services/api 与 kaotings 库。
• P4-04 用户管理：GET /admin/users 支持分页 + 邮箱/手机号/状态筛选（ILIKE），GET /admin/users/{id} 返回详情（用户、有效 Plan、当前会员、额度、会员历史、调整记录）。PATCH /admin/users/{id}/status 支持禁用/恢复，禁用时撤销该用户全部会话（sessions_revoked），并保留最后一个可用管理员保护（LAST_ADMIN_PROTECTED）。
• P4-05 VIP 与额度：GET /admin/users/{id}/membership 返回有效 Plan 与当前授予（含生效/到期时间）；PUT 授予/变更（校验有效期）；POST /membership/revoke 撤销 VIP 并回退为 free。GET /admin/users/{id}/quota 返回额度周期、上限、已用、冻结、调整、可用与调整记录；POST /admin/users/{id}/quota-adjustments 要求原因、幂等（重复提交 409）、且不允许调整后低于已用（QUOTA_BALANCE_INVALID）。
• P4-06 TTS 与审计：GET /admin/tts/tasks 按用户/状态/时间范围分页查询，返回计量（text_length）、耗时（duration_ms）、错误（error_code）、结算（consumed/released/pending）；GET /admin/usage/summary 汇总额度与任务，账本合计与 quota_accounts.used 口径一致；GET /admin/audit-logs 分页返回审计，默认不含完整用户文本，也未暴露任何密钥/令牌/密码字段。
• 移除了一次性 seed-admin 路由，初始化令牌 CMS_SEED_TOKEN 已撤销；管理员恢复流程见 docs/cms-admin-recovery.md。
• 产品 slug 查询统一使用已验证的 where[slug][equals]= 筛选；不把 Payload 的按 id 路由当作按 slug 路由（见下）。

3. 范围边界

• CMS 不管理业务用户、Role/Plan、额度、TTS 任务或认证会话（这些由 services/api 管理）。
• P4-04 至 P4-07 面向业务 API 的管理后台已完成；CMS 管理界面（用户/VIP/额度/TTS）不重复实现于 CMS。
• 旧 Big-TTS Web 不参与 CMS，推理服务继续由新网站 API 调用。
• 本轮不修改 TTS 与 Worker，不新增未经规划的强制重试/取消/上游配置功能。

4. 验证记录

空库初始化 / 迁移（P4-01）

• 迁移 20260909_100120_initial 已入库并命名与原执行记录一致，避免重复应用。
• 独立临时库 kaotings_cms_verify 从仓库 payload migrate 重建得出 14 张表，列类型 SCHEMA_IDENTICAL；随后删除临时库，现有 kaotings_cms 未清空。

管理员访问控制（P4-02）

• 匿名 first-register / POST users / GET users / GET users/1 / PATCH users/1 → 全部 403。
• 匿名 GET /cms/api/access → canAccessAdmin:false；管理员 → true。
• 普通网站用户属独立库 kaotings，CMS 用自有 payload-token JWT，跨库无法拿 CMS 会话。

真实内容闭环（P4-03）

• 测试产品 p4-test-draft-product：草稿不可读、发布可读、修改即时、下架后详情 404；完成后已下架（当前 unpublished）。

管理后台 API 与浏览器（P4-04 至 P4-07）

• services/api/tests/phase4_admin.py：分页/筛选/详情、禁用+会话失效、最后管理员保护、VIP 授予/撤销、额度调整幂等与余额约束、TTS 任务筛选、用量汇总一致、审计不泄密、普通用户越权拦截——全部通过。
• services/api/tests/phase4_browser.py（Playwright headless Chromium）：admin_login、admin_dashboard、users_table_renders、users_empty_state、tts_tasks_renders、audit_renders、mobile_users_paginates、normal_user_denied、entitlement_vip_reflected、entitlement_tts_202——全部通过。
• 受控测试账户 p4.controlled@example.com（only in server secrets）验证：授予 VIP 后账户页显示 VIP，且 TTS 提交受权益约束；测试结束后已禁用。

5. 后续

• 本命中遗留的按 slug 详情 REST 500（/cms/api/products/:slug）已确认是 Payload 把该路径当作按 id 处理所致；公网产品展示闭环走 where[status][equals]=published 列表与按 slug 筛选，不受影响，后续不得引入按 id 路由取 slug。
• 迁移、seed 路由与集成修复已提交仓库并通过本地/服务端构建；CMS 现有数据库未清空，有受控备份（infra/scripts/backup-cms-db.sh）。
• 管理后台需 root-only 的 /etc/kaotings/p4-ops.secrets 与 /etc/kaotings/p4-ctrl.secrets 注入管理员与受控账户（0600），未写入仓库。Phase 3 尚未通过的异常矩阵继续保留，不因 Phase 4 完成而关闭。

6. 实际通过项与遗留项

实际通过项

• P4-01：迁移固化、仓库可复现重建、未清空现有库。
• P4-02：受控管理员初始化、匿名无法创建首个管理员、匿名无法注册/读/改用户、canAccessAdmin 权限枚举、跨库会话隔离。
• P4-03：草稿/发布/修改/下架内容闭环，测试产品已下架。
• P4-04：用户分页/筛选/详情、禁用恢复+会话撤销、最后管理员保护、普通用户越权拦截。
• P4-05：VIP 授予/撤销（含有效期）、额度明细、调整记录+原因+幂等+余额约束。
• P4-06：TTS 任务按用户/状态/时间筛选并显示计量/耗时/错误/结算、用量汇总与流水一致、审计不含用户文本且不显示秘密。
• P4-07：真实浏览器（桌面 1440x900 / 移动 390x844）完成查用户、禁用/恢复、授予/撤销 VIP、调整额度、查询任务与审计；普通用户页面与接口均无权限；受控测试账户验证 VIP 权益反映到账户并约束 TTS 提交。

遗留项

• /cms/api/products/:slug 按 id 路径查询返回 500（Payload 行为）；公网展示走 where[status][equals]=published 与 where[slug][equals]=，不受影响，但未提供按 slug 的 REST 详情路由。
• CMS 未配置邮件适配器，管理员密码恢复依赖本地受控脚本（docs/cms-admin-recovery.md），SMTP 通道未接入。
• Phase 3 异常矩阵（并发争用、Worker 重启恢复、存储失败、上游超时等）仍为部分完成，未关闭；无公网 HTTP 上游与音频保留/备份的运营决策。
• 管理后台未做浏览器截图留档；本命中以 Playwright 无头 Chromium 的功能断言为准。移动端已覆盖表单/分页/空状态/错误反馈，但未针对每个页面单独截图。
• 前后端 tests 目录下的 playwright 依赖安装于测试机（root 运行需 PLAYWRIGHT_BROWSERS_PATH=/home/flym/.cache/ms-playwright），未纳入仓库依赖管理。