37 lines
4.0 KiB
TypeScript
37 lines
4.0 KiB
TypeScript
import type {NextApiRequest,NextApiResponse} from 'next';
|
||
export const designDocs=`# Studio 页面与 Wiki post API
|
||
所有相对地址均位于当前站点。需要现有 PROMPT 登录 Cookie 或 Authorization: Bearer <JWT>；浏览器写请求必须携带同源 Origin。JWT 不能放 URL，也不能写入示例或公开日志。
|
||
|
||
## 发现与读取
|
||
GET /studio/api/layouts：27 套布局目录。
|
||
GET /studio/api/layouts/ref-01：元素 ID、类型、位置与参数契约（T 为文字、I 为图片、D 为装饰）。
|
||
GET /api/studio/designs?layoutId=ref-01&limit=20：列举保存页面，nextCursor 用 before 继续。
|
||
GET /api/studio/designs/{id}：读取 {design}。
|
||
design 含 id/layoutId/name/parameters/revision/url/schemaUrl/postId/postUrl/createdAt/updatedAt。
|
||
url 是确定的原生页面 /studio/layouts/{layoutId}?id={id}；postUrl 是 Wiki 入口 /explore/{postId}。
|
||
不带 ID 的 /studio/layouts/ref-01 .. ref-27 展示原生默认排版；ID 不存在或与布局不匹配返回404。旧 /studio/designs/{id} 自动跳转。
|
||
|
||
## 创建与编辑（用户和 agent 操作同一条记录）
|
||
POST /api/studio/designs：{layoutId,name,parameters}，201 {design}。
|
||
每次创建独立页面 ID，并在同一数据库事务内自动创建一篇 Wiki post；失败整体回滚，不产生孤立页面。
|
||
示例：{"layoutId":"ref-01","name":"第一版","parameters":{"texts":{"T01":{"value":"STUDY"}},"images":{"I01":{"color":"#788880"}},"decorations":{}}}
|
||
PATCH /api/studio/designs/{id}：{name,parameters,revision}，200 {design}。
|
||
parameters 是整体替换，不是局部合并。agent 应先 GET，保留未修改的参数，再改目标字段后 PATCH。revision 必须为刚读到的版本；冲突409时重新读取合并，不能盲目重试旧版本。
|
||
更新同一页面复用原 Wiki post，不重复发帖；另存副本使用 POST 生成新页面和新 post。没有手动编辑过的 Wiki post 会跟随页面名称更新；手动编辑过的 Wiki 笔记保留正文、标题、标签和封面。
|
||
POST /api/studio/designs/{id}/post：为旧保存页面补建 Wiki 入口，201 {design,created:true}；已有入口返回200 {design,created:false}。可重复调用，不改变页面 revision。GET 不产生写入。
|
||
|
||
## 图片与参数
|
||
通过 POST /api/upload（multipart/form-data，kind=image、assetOnly=true、files=文件）上传图片，取返回 assets[0] 作为 assetId。上传只建素材；保存页面时才创建 Wiki post。
|
||
参数形状：{texts:{T01:{value:"标题",color:"#26362f",scale:1,align:"start"}},images:{I01:{color:"#788880",assetId:"已上传图片UUID",fit:"cover"}},decorations:{D01:{color:"#53645b",hidden:false}},paper:"#f4f2eb"}。全部可省略，具体元素必须来自当前布局。
|
||
value 最多500字/8行；scale 0.25–2；align start/middle/end；fit cover/contain；颜色 #RRGGBB。最大请求64KB。不接受任意图片 URL 或注入的 HTML/SVG。
|
||
|
||
## agent 最短工作流
|
||
1. GET /api/studio/designs/{id}，读取 design。
|
||
2. 修改 design.parameters.texts.T01.value（先用 schemaUrl 确认元素存在）。
|
||
3. PATCH /api/studio/designs/{id}，body 只发 {name:design.name,parameters:design.parameters,revision:design.revision}，不能把返回的整个 design 对象直接提交。
|
||
4. 读取返回的新 revision、url 和 postUrl；打开 url 检查实际页面。
|
||
|
||
兼容导出：renderUrl / legacySvgUrl 仍是旧的原图图层 SVG 导出，不是原生页面截图；不可把它当作原生页面的所见即所得证明。保存页面使用 POST/PATCH designs，无需先调用 SVG 渲染。
|
||
错误：400 参数、构件、图片 ID 不合法；401 未登录；404 页面不存在；409 修订冲突；413 请求过大。`;
|
||
export function studioDesignDocumentation(req:NextApiRequest,res:NextApiResponse){if(!['GET','HEAD'].includes(req.method||'')||String(req.query.agent_mode).toLowerCase()!=='true')return false;res.setHeader('Content-Type','text/plain; charset=utf-8');res.setHeader('Cache-Control','no-store');if(req.method==='HEAD')res.status(200).end();else res.status(200).send(designDocs);return true}
|