27 lines
2.4 KiB
Markdown
27 lines
2.4 KiB
Markdown
# 原图排版：通过 API 发布普通 post
|
||
|
||
本组内容是 27 张设计 post + 1 篇 Router，保留原有 `/explore/<id>` 地址。素材、封面、构件清单和 HTML/React/Next.js 示例均为 API 上传的数据，不再注册为 Wiki 的代码内容。
|
||
|
||
## 通用 API 工作流
|
||
|
||
1. `POST /api/upload`，multipart `assetOnly=true`，独立存储图像，不创建素材包。
|
||
2. `POST /api/posts`，传入 `publicId`（可选的 24 位稳定 ID）、图片关联、正文、标签与封面，创建普通数据库 post。
|
||
3. 后续 `GET /api/notes/{id}` 获取 revision，再 `PUT` 更新文字、媒体关联及 `coverAssetId`。普通 UUID 与稳定 publicId 都可读取和编辑。
|
||
4. 图片通过 `/api/media/{id}`，正文通过原 post 的 `?agent_mode=True` 读取。
|
||
|
||
publicId 是通用迁移能力，不包含任何排版 ID 特判。数据库 post 可以接管同 ID 的代码条目，内容流按稳定 ID 去重。媒体和封面参与 revision，防止并发修改覆盖。替换素材关联只改引用，不删除原二进制或其他 post 的引用。
|
||
|
||
## 本地创作数据与封面
|
||
|
||
`content/layout-reference/` 是 Wiki 应用之外的本地创作输入；不会被应用编译或挂载到 public。27 张原图、217 个文字/图位/装饰构件及识别证据保留在这里。`scripts/publish-layout-reference.mjs` 通过上述通用 API 上传资料，使用检查点保证可继续发布。
|
||
|
||
新封面由 27 张实际裁片组成，使用 ref-01…ref-27 标签，并标出文字 113、图位 51、装饰 53。封面经媒体 API 上传并设置为 Router 的普通 coverAssetId。
|
||
|
||
旧 `/layout-reference/...` 检查器、HTML 演示、JSON 静态文件及 ZIP 资源已从站点移除。构件表与清单直接写在 post 正文中；代码是可复制文本，不在 Wiki 内执行。原有 12 类近似方案的代码重定向特判也移除。
|
||
|
||
## 验证
|
||
|
||
本地执行类型检查和单元测试。Docker 集成测试验证独立上传不创建 post、stable publicId 接管与去重、正文及 JSON/TSX 的纯文本可读性、封面更新及并发冲突、媒体引用替换、重复 ID 拒绝，以及旧自定义目录返回 404。
|
||
|
||
部署成功后运行 API 发布客户端，核对 28 个标准 post、媒体文件、Router 封面、纯文本入口和正文中的全部链接。图像识别与构件合成属于本地创作校验，不作为 Wiki 的页面实现。
|