Expose Studio cover rendering API and add three source-based layout tools
studio CI and deployment / verify-and-deploy (push) Successful in 3m51s

This commit is contained in:
2026-10-26 20:26:17 +08:00
parent 7f37aa4c93
commit 4ba7eb7db7
12 changed files with 455 additions and 21 deletions
+14 -1
View File
@@ -1,6 +1,19 @@
import type {NextApiRequest,NextApiResponse} from 'next';
const docs:Record<string,string>={
'/studio/api/export/{slug}': '# 导出创作方案\n\n方法:GET\n路径参数:slug,创作方案的稳定标识。\n查询参数:format=markdown 返回 Markdown;format=svg&slide=0 返回模板封面 SVG(slide 为从 0 开始的整数,默认 0);其他值或省略时返回方案 JSON,带附件文件名。普通方案 version:1;模板方案 version:2,包含 template 来源链接、画板比例、原图九个 slots 及 slides 文字和颜色。模板几何共用,图片位为占位色块。\n示例:GET /studio/api/export/{slug}\n错误:400 SVG 模板或 slide 参数无效;404 方案不存在;405 方法不支持。',
'/studio/api/export/{slug}': `# Studio 封面工具 API
方法:GET, POST
路径参数:slug 为 learning-skills-template(同一母版四张试版)或 layout-selection(三种不同构图);first-idea 仅提供 GET 内容导出。
GET 参数:省略 format 返回方案 JSON;format=markdown 返回说明;format=svg 返回初始封面。四张试版用 slide=0..3(默认 0),多模板工具用 layoutId=ref-01|ref-07|ref-26(默认 ref-01)。
JSON:普通方案 version:1;四张试版 version:2;多模板 version:3,layouts 包含源教程、画板、构件坐标及分层蒙版。文字、图位、装饰一一对应,图片位为色块占位。
POST:Content-Type: application/json。format=svg(默认)返回独立 SVG;format=json 返回渲染参数及模板信息。请求最大 32KB,无存储副作用。
learning-skills-template 参数:slide(整数 0–3,默认 0)、heading(1–6 字)、body(最多 360 字、3 行)、color、accent(#RRGGBB)、masthead(2 项数组,每项 1–8 个英文字母/空格);省略参数沿用初始值。
layout-selection 参数:layoutId(必填,ref-01/ref-07/ref-26)、fields(可选,以对应模板 T 构件 ID 为键;每项 1–120 字、最多 4 行)、color、accent(#RRGGBB)。省略文字沿用初始值;拒绝未知参数或构件 ID。
示例:POST /studio/api/export/learning-skills-template?format=svg
{"slide":1,"heading":"笔记复习","color":"#7a8b7e"}
POST /studio/api/export/layout-selection?format=svg
{"layoutId":"ref-01","fields":{"T01":"STUDY","T02":"笔记复习\\n主题说明占位"},"color":"#83918a"}
错误:400 参数/格式错误;404 方案不存在;405 方法不支持;413 请求过大。SVG 不含编辑辅助边界,文字经过 XML 转义;装饰位分层图片是原始低分辨率图层。`,
'/studio/api/health': '# 创作站健康检查\n\n方法:GET, HEAD\n无业务参数。GET 返回 200 JSON:{"status":"ok","service":"prompt-studio"};HEAD 无正文。\n示例:GET /studio/api/health\n错误:405 方法不支持。',
};
export function serveApiDocumentation(req:NextApiRequest,res:NextApiResponse,path:string){
+22
View File
@@ -0,0 +1,22 @@
import {createElement} from 'react';
import {ideas} from '../content/ideas';
import {Ref17Cover} from '../components/Ref17Cover';
import {SourceCover,selections} from '../components/SourceCover';
const record=(v:unknown):v is Record<string,unknown>=>!!v&&typeof v==='object'&&!Array.isArray(v);
function color(value:unknown,fallback:string){if(value===undefined)return fallback;if(typeof value!=='string'||!/^#[0-9a-f]{6}$/i.test(value))throw Error('颜色必须为 #RRGGBB');return value;}
function text(value:unknown,fallback:string,max:number,lines=1){if(value===undefined)return fallback;if(typeof value!=='string'||!value.trim()||Array.from(value).length>max||value.split('\n').length>lines)throw Error('文字长度或行数超限');return value;}
function keys(input:Record<string,unknown>,allowed:string[]){if(Object.keys(input).some(k=>!allowed.includes(k)))throw Error('包含不支持的参数');}
export function renderCover(slug:string,input:unknown){
if(!record(input))throw Error('需要 JSON 对象');
if(slug==='layout-selection'){
keys(input,['layoutId','fields','color','accent']);const layout=selections.find(l=>l.id===input.layoutId);if(!layout)throw Error('layoutId 必须为 ref-01、ref-07 或 ref-26');
if(input.fields!==undefined&&!record(input.fields))throw Error('fields 必须为对象');const supplied=(input.fields||{}) as Record<string,unknown>,defaults=Object.fromEntries(Object.entries(layout.fields).filter(([,v])=>v!==undefined)) as Record<string,string>;
keys(supplied,Object.keys(defaults));const fields=Object.fromEntries(Object.entries(defaults).map(([key,value])=>[key,text(supplied[key],value,120,4)]));
const values={fields,color:color(input.color,'#83918a'),accent:color(input.accent,'#c3cec5')};return {node:createElement(SourceCover,{layout,values}),data:{version:3,tool:slug,layoutId:layout.id,template:layout,...values}};
}
const idea=ideas.find(i=>i.slug===slug);if(!idea?.template)throw Error('这个方案不支持封面渲染');keys(input,['slide','heading','body','color','accent','masthead']);
const index=input.slide??0;if(typeof index!=='number'||!Number.isInteger(index)||!idea.slides[index])throw Error('slide 必须是 0–3 的整数');const initial=idea.slides[index];
const slide={...initial,heading:text(input.heading,initial.heading,6),body:text(input.body,initial.body,360,3),color:color(input.color,initial.color),accent:color(input.accent,initial.accent!)};
const masthead=input.masthead??idea.template.masthead;if(!Array.isArray(masthead)||masthead.length!==2||!masthead.every(v=>typeof v==='string'&&/^[A-Za-z ]{1,8}$/.test(v)&&v.trim()))throw Error('masthead 为两行、每行 1–8 个英文字母或空格');
return {node:createElement(Ref17Cover,{template:idea.template,slide,masthead}),data:{version:2,tool:slug,template:{...idea.template,masthead},slide}};
}