Publish reference layouts as API-authored text and image notes

apps/wiki/src/lib/api-documentation.ts

@@ -6,7 +6,7 @@ export const apiDocuments:Record<string,readonly string[]>={
     "统一内容流",
     "GET",
     "查询参数：q（可选，最多 200 字符）；category（可选，标签名称或命名空间）；cursor（可选，上一页 nextCursor）。",
-    "JSON：entries 数组与 nextCursor；没有更多结果时 nextCursor 为 null。静态内容仅出现在第一页。",
+    "JSON：entries 数组与 nextCursor；没有更多结果时 nextCursor 为 null。静态内容仅出现在第一页；已由相同 publicId 的数据库笔记接管时不重复展示。",
     "GET /api/explore-feed?q=排版",
     "503：素材库暂时无法连接。"
   ],
@@ -21,18 +21,18 @@ export const apiDocuments:Record<string,readonly string[]>={
   "/api/notes/{id}": [
     "读取与编辑笔记",
     "GET, PUT",
-    "路径参数：id，笔记稳定 ID。PUT 使用 application/json，所有字段必填：title（1–200 字符）、description（最多 1000 字符）、markdown（最多 100000 字符）、tags（最多 50 个标签 UUID）、revision（GET 返回的 entry.revision，64 位十六进制）。",
-    "GET 返回 {entry,tags}；PUT 返回更新后的 {entry}。先 GET 获取 revision，再 PUT；冲突后重新读取。",
+    "路径参数：id，笔记稳定 ID（publicId 或存储 UUID）。PUT 使用 application/json，以下字段必填：title（1–200 字符）、description（最多 1000 字符）、markdown（最多 100000 字符）、tags（最多 50 个标签 UUID）、revision（GET 返回的 entry.revision，64 位十六进制）。可选 assets（最多 100 项 {id:媒体 UUID,role:content|caption}，替换媒体关联，原二进制不删除）；coverAssetId（图片 UUID 或 null，必须为本笔记 content 图片；null 清除显式封面）。静态代码页须先通过创建接口保存为数据库笔记，才可更新媒体。",
+    "GET 返回 {entry,tags}，entry.assets 为媒体关联、entry.coverAssetId 为显式封面；PUT 返回更新后的 {entry}。先 GET 获取 revision，再 PUT；冲突后重新读取。",
     "GET /api/notes/{id}\nPUT /api/notes/{id}\n{\"title\":\"标题\",\"description\":\"简介\",\"markdown\":\"正文\",\"tags\":[],\"revision\":\"<GET 返回的 entry.revision>\"}",
     "400：输入错误；404：笔记不存在；409：版本冲突。"
   ],
   "/api/posts": [
     "创建笔记或素材包",
     "POST",
-    "application/json：kind（必填，image / video / audio / article / motion）、title（必填，1–200 字符）；slug（可选，最多 120 字符，以小写字母或数字开头，仅含小写字母、数字、连字符）；description（可选，最多 1000 字符）；text（可选，最多 100000 字符）；tags（可选，最多 50 个 UUID）；coverAssetId（可选，图片 UUID）；assets（可选，最多 100 项，{id: UUID,role: content | caption}，role 默认 content）。媒体类型必须引用至少一个对应类型的 content 素材。",
-    "201 JSON：{id,slug}。引用已有素材；不会在此接口上传二进制文件。",
+    "application/json：kind（必填，image / video / audio / article / motion）、title（必填，1–200 字符）；publicId（可选，唯一的 24 位小写十六进制稳定 ID，用于保留原页面地址）；slug（可选，最多 120 字符，以小写字母或数字开头，仅含小写字母、数字、连字符）；description（可选，最多 1000 字符）；text（可选，最多 100000 字符）；tags（可选，最多 50 个 UUID）；coverAssetId（可选，图片 UUID）；assets（可选，最多 100 项，{id: UUID,role: content | caption}，role 默认 content）。媒体类型必须引用至少一个对应类型的 content 素材。",
+    "201 JSON：{id,slug,url,publicId?}，url 为 /explore/<publicId 或 id>。id 仍为存储 UUID。引用已有素材；不会在此接口上传二进制文件。",
     "POST /api/posts\n{\"kind\":\"article\",\"title\":\"新笔记\",\"text\":\"正文\",\"tags\":[]}",
-    "400：输入或素材引用不合法；409：slug 已存在。"
+    "400：输入或素材引用不合法；409：slug 或 publicId 已存在。"
   ],
   "/api/tags": [
     "标签列表与创建",
@@ -43,10 +43,10 @@ export const apiDocuments:Record<string,readonly string[]>={
     "400：输入错误；409：slug 冲突。"
   ],
   "/api/upload": [
-    "上传媒体并创建素材包",
+    "上传媒体，可独立保存素材",
     "POST",
-    "multipart/form-data：kind（必填，image / video / audio）；title（必填，1–200 字符）；slug（可选，小写字母或数字组成的非空段，以连字符分隔，最多 120 字符）；description（可选，最多 100000 字符）；tags（可选，UUID 数组的 JSON 字符串，最多 50 项）；文件字段名任意，至少一个文件。最多 16 个文件，单个不超过 250 MB，总计不超过 1 GB。图片支持 JPG、PNG、WebP、GIF、AVIF；音频必须为独立声音文件。",
-    "201 JSON：{id,slug,url,assets}，assets 为素材 UUID 数组。视频会自动进入后台加工队列。",
+    "multipart/form-data：kind（必填，image / video / audio）；title（普通上传必填，1–200 字符；assetOnly=true 时可省略）；assetOnly（可选，字符串 true / false，默认 false；true 时只存媒体，不创建 post）；slug（可选，小写字母或数字组成的非空段，以连字符分隔，最多 120 字符）；description（可选，最多 100000 字符）；tags（可选，UUID 数组的 JSON 字符串，最多 50 项）；文件字段名任意，至少一个文件。最多 16 个文件，单个不超过 250 MB，总计不超过 1 GB。图片支持 JPG、PNG、WebP、GIF、AVIF；音频必须为独立声音文件。",
+    "201 JSON：普通上传为 {id,slug,url,assets}；assetOnly=true 为 {assets,files:[{id,filename,sha256}]}，不创建 post。assets 为素材 UUID 数组，之后可交给 /api/posts 组合；视频素材会自动进入后台加工队列。",
     "POST /api/upload\nContent-Type: multipart/form-data\nkind=image\ntitle=示例图片\ntags=[]\nfile=<图片文件>",
     "400：输入或媒体不合法；409：slug 冲突；413：上传超过限制。"
   ],