Kaotings/www_site
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: record Phase 4 CMS acceptance results

Browse Source
This commit is contained in:
flym 2026-09-10 01:30:47 +08:00
parent e5492ceccb
commit 3af0a03da2
1 changed files with 46 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

57
docs/phase-4-report.md
View File

@ -2,10 +2,11 @@
日期：2026-09-09 日期：2026-09-09
范围：P4-01 至 P4-03 范围：P4-01 至 P4-03
状态：CMS 数据边界、模型和公共内容 API 已部署；CMS 管理入口前缀集成仍受阻，草稿/发布/下架尚未验收通过。 状态：CMS 数据边界、模型、公共内容 API、可复现迁移、受控管理员、访问控制与真实内容闭环均已验收通过。
## 1. 已完成 ## 1. 已完成
### 数据边界与模型
- 新增独立 Payload CMS 应用：`apps/cms`。 - 新增独立 Payload CMS 应用：`apps/cms`。
- CMS 使用独立 PostgreSQL 数据库 `kaotings_cms` 和独立数据库账号，不读取业务 API 用户表。 - CMS 使用独立 PostgreSQL 数据库 `kaotings_cms` 和独立数据库账号，不读取业务 API 用户表。
- 已配置 systemd 服务 `kaotings-cms`，仅监听 `127.0.0.1:3001`。 - 已配置 systemd 服务 `kaotings-cms`，仅监听 `127.0.0.1:3001`。
@ -13,16 +14,49 @@
- 建立模型：`Users`、`Products`、`Media`、`SiteSettings`、`HomeContent`。 - 建立模型：`Users`、`Products`、`Media`、`SiteSettings`、`HomeContent`。
- Product 支持 `draft`、`published`、`unpublished`，slug、分类、摘要、描述、媒体、features、specs、SEO 和排序字段。 - Product 支持 `draft`、`published`、`unpublished`，slug、分类、摘要、描述、媒体、features、specs、SEO 和排序字段。
- Media 为受控上传集合，普通访客只读媒体，写入需要 CMS 用户。 - Media 为受控上传集合，普通访客只读媒体，写入需要 CMS 用户。
- Website 内容适配器已从集中占位数据切换为 CMS 公共 Products API；CMS 未发布产品时显示明确空状态。
- 公共 Products API 已验证返回 `200` 和空集合，未泄露草稿。
## 2. 尚未通过 ### 公共内容 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 未发布产品时显示明确空状态。
- `/cms/admin` 当前仍发生前缀重定向/404，Payload Admin 的 Next basePath 与 Caddy 前缀集成尚未稳定。 ### 数据库初始化固化（P4-01）
- 因管理入口未通过，尚未建立 CMS 管理员、创建 Product、上传 Media 或执行发布/下架验收。 - 核对执行记录：`payload_migrations` 仅含 `20260909_100120_initial`（batch 1），与现有 `kaotings_cms` 结构一致。
- 草稿不可读、发布可读、下架失效的完整端到端矩阵待 Admin 路由修复后执行。 - 已重新生成初始迁移并修正类型导入，命名为 `20260909_100120_initial` 以对齐已应用记录，避免重复应用。
- 当前没有把 CMS 生成的运行时迁移文件提交进仓库，测试数据库迁移已执行但交付还需固化迁移产物。 - 迁移文件提交进仓库：`apps/cms/src/migrations/20260909_100120_initial.ts`。
- 当前 `kaotings_cms` 已生成受控 custom-format 备份，备份脚本为 `infra/scripts/backup-cms-db.sh`；现有数据库未清空。 - 使用独立临时库 `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`。
- 已知遗留：CMS REST 按 slug 的详情查询（`/cms/api/products/:slug`）会因 Payload 以数值 id 处理返回 `500`；官网详情页走列表而非该路径，不受影响。
## 3. 范围边界 ## 3. 范围边界
@ -30,6 +64,7 @@
- P4-04 至 P4-07 的用户、VIP、额度、TTS 管理界面尚未开始。 - P4-04 至 P4-07 的用户、VIP、额度、TTS 管理界面尚未开始。
- 旧 Big-TTS Web 不参与 CMS，推理服务继续由新网站 API 调用。 - 旧 Big-TTS Web 不参与 CMS，推理服务继续由新网站 API 调用。
## 4. 当前阻断 ## 4. 后续
需要先修复 Payload Admin 的 `/cms/admin` 外部路径和可复现迁移产物，再执行 P4-02/P4-03 的真实内容操作验收。该阻断不影响 Phase 3 已部署的认证、TTS、额度和音频服务，也不涉及旧推理工程修改。 - 本命中遗留的按 slug 详情 REST `500` 可后续在 CMS 侧提供按 slug 查询端点或文档化；当前不影响公网产品展示闭环。
- 迁移、seed 路由与集成修复已提交仓库并通过本地/服务端构建；CMS 现有数据库未清空，有受控备份（`infra/scripts/backup-cms-db.sh`）。