Harden XML round trips, author namespaces and publishing feedback
waterfall-wiki CI and deployment / verify-and-deploy (pull_request) Has been cancelled

This commit is contained in:
2026-10-29 17:03:55 +08:00
parent 0e47bae606
commit 5c89d27528
11 changed files with 36 additions and 20 deletions
@@ -1,5 +1,5 @@
BEGIN;
CREATE TABLE guidance_documents(id text PRIMARY KEY CHECK(id ~ '^user-[a-z0-9-]{1,74}$'), owner_id uuid NOT NULL REFERENCES account_users(id), latest integer NOT NULL DEFAULT 0, deleted_at timestamptz);
CREATE TABLE guidance_documents(id text PRIMARY KEY CHECK(id ~ '^user-[a-z0-9-]{1,74}$'), owner_id uuid NOT NULL REFERENCES account_users(id), latest integer NOT NULL DEFAULT 0, deleted_at timestamptz, CHECK(id LIKE 'user-' || owner_id::text || '-%'));
CREATE TABLE guidance_revisions(document_id text NOT NULL REFERENCES guidance_documents(id), revision integer NOT NULL CHECK(revision>0), content jsonb NOT NULL, created_at timestamptz NOT NULL DEFAULT now(), PRIMARY KEY(document_id,revision));
CREATE FUNCTION guidance_immutable() RETURNS trigger LANGUAGE plpgsql AS $$ BEGIN RAISE EXCEPTION 'Published revisions are immutable'; END $$;
CREATE TRIGGER guidance_immutable BEFORE UPDATE OR DELETE ON guidance_revisions FOR EACH ROW EXECUTE FUNCTION guidance_immutable();
@@ -7,4 +7,4 @@ export const guides:Guidance[]=[
];
export function findGuide(id:string,revision?:number){return guides.find(g=>g.id===id&&(revision===undefined||g.revision===revision));}
const esc=(s:string)=>s.replace(/[<>&"']/g,c=>({'<':'&lt;','>':'&gt;','&':'&amp;','"':'&quot;',"'":'&apos;'}[c]!));
export function guidanceXml(g:Guidance){const t=(tag:string,s:string)=>` <${tag}>${esc(s)}</${tag}>`;return `<?xml version="1.0" encoding="UTF-8"?>\n<guidance xmlns="urn:linked-guidance:0.1" id="${esc(g.id)}" revision="${g.revision}" kind="${g.kind}" lang="zh-CN">\n${[t('title',g.title),t('summary',g.summary),t('applies',g.applies),t('body',g.body),...g.steps.map(s=>t('step',s)),...g.links.map(l=>` <link target="${esc(l.target)}" revision="${l.revision}" relation="${l.relation}" when="${esc(l.when)}">${esc(l.label)}</link>`),...g.checks.map(s=>t('check',s))].join('\n')}\n</guidance>\n`;}
export function guidanceXml(g:Guidance){const t=(tag:string,s:string)=>` <${tag}>${esc(s)}</${tag}>`;return `<?xml version="1.0" encoding="UTF-8"?>\n<guidance xmlns="urn:linked-guidance:0.1" id="${esc(g.id)}" revision="${g.revision}" kind="${g.kind}" lang="zh-CN">\n${[t('title',g.title),t('summary',g.summary),t('applies',g.applies),t('body',g.body),...g.steps.map(s=>t('step',s)),...g.links.map(l=>` <link target="${esc(l.target)}" revision="${l.revision}" relation="${l.relation}" when="${esc(l.when)}">${esc(l.label)}</link>`),...g.checks.map(s=>t('check',s)),...g.tags.map(s=>t('tag',s))].join('\n')}\n</guidance>\n`;}
@@ -1,19 +1,22 @@
import { z } from 'zod';
const kind=z.enum(['guide','context','evidence']);
const text=z.string().trim().min(1).max(20000).refine(s=>!/[\u0000-\u0008\u000b\u000c\u000e-\u001f\ufffe\uffff]/.test(s),'非法 XML 字符');
export const validXmlText=(value:string)=>!/[\u0000-\u0008\u000b\u000c\u000e-\u001f\ufffe\uffff]/.test(value)&&!/[\ud800-\udfff]/u.test(value);
const text=z.string().refine(validXmlText,'非法 XML 字符').trim().min(1).max(20000);
export const documentInput=z.object({id:z.string().regex(/^user-[a-z0-9-]{1,74}$/),revision:z.number().int().min(1).max(2147483647),kind,title:text.max(200),summary:text.max(1000),applies:text,body:text,steps:z.array(text).max(100),checks:z.array(text).max(100),links:z.array(z.object({target:z.string().regex(/^[a-z0-9-]{1,79}$/),revision:z.number().int().min(1).max(2147483647),relation:kind,when:text.max(1000),label:text.max(200)}).strict()).max(100),tags:z.array(text.max(80)).max(20)}).strict();
// Deliberately narrow XML 1.0 grammar: no DTD, comments, CDATA, nested markup or arbitrary entities.
export function parseDocumentXml(source:string){
if(!validXmlText(source)||source.includes(']]>'))throw Error('非法 XML 字符');
if(Buffer.byteLength(source)>131072)throw Error('XML 过大');
let s=source.replace(/^<\?xml version="1.0" encoding="UTF-8"\?>\s*/, '');
const trimXml=(v:string)=>v.replace(/^[ \t\r\n]+|[ \t\r\n]+$/g,'');
let s=source.replace(/^<\?xml version="1.0" encoding="UTF-8"\?>[ \t\r\n]*/, '');
if(/<\?|<!/.test(s))throw Error('不支持 XML 声明或嵌入');
const decode=(v:string)=>{if(/&(?!amp;|lt;|gt;|quot;|apos;)/.test(v))throw Error('非法实体');return v.replace(/&(amp|lt|gt|quot|apos);/g,(_,k)=>({amp:'&',lt:'<',gt:'>',quot:'"',apos:"'"}[k as 'amp'|'lt'|'gt'|'quot'|'apos'] as string));};
const attrs=(v:string)=>{const result:Record<string,string>={};while(v.trim()){const m=/^\s+([a-z]+)="([^"<]*)"/.exec(v);if(!m||m[1] in result)throw Error('非法或重复属性');result[m[1]]=decode(m[2]);v=v.slice(m[0].length);}return result;};
const root=/^<guidance(\s[^>]*)>([\s\S]*)<\/guidance>\s*$/.exec(s);if(!root)throw Error('非法根元素');const a=attrs(root[1]);
const attrs=(v:string)=>{const result:Record<string,string>={};while(trimXml(v)){const m=/^[ \t\r\n]+([a-z]+)="([^"<]*)"/.exec(v);if(!m||m[1] in result)throw Error('非法或重复属性');result[m[1]]=decode(m[2]);v=v.slice(m[0].length);}return result;};
const root=/^<guidance((?:[ \t\r\n]+[a-z]+="[^"<]*")+[ \t\r\n]*)>([\s\S]*)<\/guidance>[ \t\r\n]*$/.exec(s);if(!root)throw Error('非法根元素');const a=attrs(root[1]);
if(Object.keys(a).sort().join(',')!=='id,kind,lang,revision,xmlns'||a.xmlns!=='urn:linked-guidance:0.1'||a.lang!=='zh-CN'||! /^[1-9][0-9]*$/.test(a.revision))throw Error('不支持的协议或属性');
const result:Record<string,unknown>={id:a.id,kind:a.kind,revision:Number(a.revision),steps:[],checks:[],links:[],tags:[]};s=root[2];
while(s.trim()){const m=/^\s*<(title|summary|applies|body|step|check|link)([^>]*)>([^<]*)<\/\1>/.exec(s);if(!m)throw Error('非法子元素');const [,tag,raw,value]=m;const at=attrs(raw);const v=decode(value);
while(trimXml(s)){const m=/^[ \t\r\n]*<(title|summary|applies|body|step|check|tag|link)((?:[ \t\r\n]+[a-z]+="[^"<]*")*[ \t\r\n]*)>([^<]*)<\/\1>/.exec(s);if(!m)throw Error('非法子元素');const [,tag,raw,value]=m;const at=attrs(raw);const v=decode(value);
if(tag==='link'){if(Object.keys(at).sort().join(',')!=='relation,revision,target,when'||! /^[1-9][0-9]*$/.test(at.revision))throw Error('非法链接');(result.links as unknown[]).push({...at,revision:Number(at.revision),label:v});}
else {if(Object.keys(at).length)throw Error('非法属性');if(tag==='step'||tag==='check')(result[tag==='step'?'steps':'checks'] as string[]).push(v);else{if(tag in result)throw Error('重复元素');result[tag]=v;}}s=s.slice(m[0].length);}
else {if(Object.keys(at).length)throw Error('非法属性');if(tag==='step'||tag==='check'||tag==='tag')(result[tag==='step'?'steps':tag==='tag'?'tags':'checks'] as string[]).push(v);else{if(tag in result)throw Error('重复元素');result[tag]=v;}}s=s.slice(m[0].length);}
return documentInput.parse(result);
}
@@ -5,7 +5,7 @@ export async function resolveDocument(id:string,revision?:number):Promise<Guidan
if(!id.startsWith('user-'))return findGuide(id,revision)||null;
const r=await db().query(`SELECT r.content FROM guidance_documents d JOIN guidance_revisions r ON r.document_id=d.id AND r.revision=COALESCE($2,d.latest) WHERE d.id=$1 AND ($2::integer IS NOT NULL OR d.deleted_at IS NULL)`,[id,revision??null]);return r.rows[0]?.content||null;
}
export async function publishDocument(owner:string,value:unknown){const content=documentInput.parse(value);return transaction(async c=>{
export async function publishDocument(owner:string,value:unknown){const content=documentInput.parse(value);if(!content.id.startsWith('user-'+owner+'-'))throw Error('INVALID_ID');return transaction(async c=>{
await c.query('INSERT INTO guidance_documents(id,owner_id) VALUES($1,$2) ON CONFLICT DO NOTHING',[content.id,owner]);
const d=(await c.query('SELECT * FROM guidance_documents WHERE id=$1 FOR UPDATE',[content.id])).rows[0];
if(d.owner_id!==owner)throw Error('FORBIDDEN');if(d.deleted_at||content.revision!==d.latest+1)throw Error('CONFLICT');
@@ -1,3 +1,4 @@
import { ZodError } from 'zod';
import type { NextApiRequest,NextApiResponse } from 'next';
import { currentAccount } from '@/lib/account';
import { trustedOrigin } from '@/lib/account-crypto';
@@ -21,6 +22,6 @@ export default async function handler(req:NextApiRequest,res:NextApiResponse){
if(id==='preview'){const links=await Promise.all(input.links.map(async l=>({...l,resolved:!!await resolveDocument(l.target,l.revision)})));return res.json({document:input,xml:guidanceXml(input),links});}
if(id&&id!==input.id)return res.status(400).json({error:'文档 ID 不匹配'});
return res.status(201).json({document:await publishDocument(user.id,input)});
}catch(e){const message=e instanceof Error?e.message:'';if(message==='FORBIDDEN')return res.status(403).json({error:'仅作者可编辑'});if(message==='CONFLICT'||(e as {code?:string}).code==='23505')return res.status(409).json({error:'版本冲突:请加载最新版本,已发布版本不可修改'});if(e instanceof Error&&(e.name==='ZodError'||/XML|实体|元素|属性|协议|链接/.test(message)))return res.status(400).json({error:'输入不符合协议'});return res.status(503).json({error:'文档服务暂不可用'});}
}catch(e){if(e instanceof ZodError)return res.status(400).json({error:'输入不符合协议,请检查以下字段',fields:e.issues.slice(0,12).map(i=>i.path.join('.')||'文档')});const message=e instanceof Error?e.message:'';if(message==='INVALID_ID')return res.status(400).json({error:'文档 ID 必须以 user-你的账户ID- 开头,请使用编辑器生成的前缀'});if(message==='FORBIDDEN')return res.status(403).json({error:'仅作者可编辑'});if(message==='CONFLICT'||(e as {code?:string}).code==='23505')return res.status(409).json({error:'版本冲突:请加载最新版本,已发布版本不可修改'});if(e instanceof Error&&(e.name==='ZodError'||/XML|实体|元素|属性|协议|链接/.test(message)))return res.status(400).json({error:'输入不符合协议'});return res.status(503).json({error:'文档服务暂不可用'});}
}
export const config={api:{bodyParser:{sizeLimit:'128kb'}}};
@@ -2,5 +2,5 @@ import type { GetServerSideProps } from 'next';
import type { Guidance } from '@/content/guides/catalog';
import styles from '@/styles/documents.module.css';
type Props={canEdit:boolean;versions:number[];doc:Guidance;links:(Guidance['links'][number]&{resolved:boolean})[]};
export default function Read({doc,links,canEdit,versions}:Props){return <main className={styles.page}><nav><a href="/documents">用户文档</a> · <a href="/write">{canEdit?'编辑我的文档':'发布文档'}</a></nav><h1>{doc.title}</h1><p>{doc.kind} · {doc.id} · 固定版本 {doc.revision}</p><p>版本:{versions.map(v=><a key={v} href={'/documents/'+doc.id+'?revision='+v}> v{v} </a>)}</p><p>{doc.summary}</p><h2>适用条件</h2><p>{doc.applies}</p><p className={styles.body}>{doc.body}</p><ol>{doc.steps.map((s,i)=><li key={i}>{s}</li>)}</ol><h2>条件链接</h2>{links.map((l,i)=><article key={i}><p>条件:{l.when} · {l.relation}</p>{l.resolved?<a href={(l.target.startsWith('user-')?'/documents/':'/guide/')+l.target+'?revision='+l.revision}>{l.label} · v{l.revision}</a>:<p>{l.label}:精确版本缺失,请跳过</p>}</article>)}<h2>检查项</h2><ul>{doc.checks.map((s,i)=><li key={i}>{s}</li>)}</ul><a href={'/api/documents/'+doc.id+'?revision='+doc.revision+'&format=xml'}>读取规范 XML</a>{canEdit&&<p><button onClick={async()=>{if(!confirm('撤下后仍保留固定历史版本,确定撤下?'))return;const r=await fetch('/api/documents/'+doc.id,{method:'DELETE'});alert(r.ok?'已撤下,历史版本仍可访问':(await r.json()).error);}}>作者撤下文档</button></p>}</main>;}
export default function Read({doc,links,canEdit,versions}:Props){return <main className={styles.page}><nav><a href="/documents">用户文档</a> · <a href={canEdit?'/write?id='+doc.id:'/write'}>{canEdit?'编辑我的文档':'发布文档'}</a></nav><h1>{doc.title}</h1><p>{doc.kind} · {doc.id} · 固定版本 {doc.revision}</p><p>版本:{versions.map(v=><a key={v} href={'/documents/'+doc.id+'?revision='+v}> v{v} </a>)}</p><p>{doc.summary}</p><h2>适用条件</h2><p>{doc.applies}</p><p className={styles.body}>{doc.body}</p><ol>{doc.steps.map((s,i)=><li key={i}>{s}</li>)}</ol><h2>条件链接</h2>{links.map((l,i)=><article key={i}><p>条件:{l.when} · {l.relation}</p>{l.resolved?<a href={(l.target.startsWith('user-')?'/documents/':'/guide/')+l.target+'?revision='+l.revision}>{l.label} · v{l.revision}</a>:<p>{l.label}:精确版本缺失,请跳过</p>}</article>)}<h2>检查项</h2><ul>{doc.checks.map((s,i)=><li key={i}>{s}</li>)}</ul><a href={'/api/documents/'+doc.id+'?revision='+doc.revision+'&format=xml'}>读取规范 XML</a>{canEdit&&<p><button onClick={async()=>{if(!confirm('撤下后仍保留固定历史版本,确定撤下?'))return;const r=await fetch('/api/documents/'+doc.id,{method:'DELETE'});alert(r.ok?'已撤下,历史版本仍可访问':(await r.json()).error);}}>作者撤下文档</button></p>}</main>;}
export const getServerSideProps:GetServerSideProps<Props>=async({params,query,res,req})=>{res.setHeader('Cache-Control','no-store');const revision=query.revision;if(revision!==undefined&&(typeof revision!=='string'||! /^[1-9][0-9]{0,9}$/.test(revision)||Number(revision)>2147483647))return {notFound:true};const {resolveDocument}=await import('@/lib/guidance-store');const doc=await resolveDocument(String(params?.id),revision===undefined?undefined:Number(revision));if(!doc)return {notFound:true};const links=await Promise.all(doc.links.map(async l=>({...l,resolved:!!await resolveDocument(l.target,l.revision)})));const {db}=await import('@/lib/db');const {currentAccount}=await import('@/lib/account');const user=await currentAccount(new Request('http://internal',{headers:{cookie:req.headers.cookie||''}}));const owner=await db().query('SELECT owner_id FROM guidance_documents WHERE id=$1',[doc.id]);const rows=await db().query('SELECT revision FROM guidance_revisions WHERE document_id=$1 ORDER BY revision DESC',[doc.id]);return {props:{doc,links,canEdit:!!user&&owner.rows[0]?.owner_id===user.id,versions:rows.rows.map(r=>r.revision)}};};
+8 -4
View File
@@ -1,10 +1,14 @@
import { useState } from 'react';
import { useEffect,useState } from 'react';
import type { Guidance } from '@/content/guides/catalog';
import styles from '@/styles/documents.module.css';
const blank:Guidance={id:'user-',revision:1,kind:'guide',title:'',summary:'',applies:'',body:'',steps:[],checks:[],links:[],tags:[]};
export default function Write(){
const [busy,setBusy]=useState(false),[published,setPublished]=useState<{id:string;revision:number}|null>(null);
const [doc,setDoc]=useState(blank),[xml,setXml]=useState(''),[mode,setMode]=useState(false),[message,setMessage]=useState(''),[preview,setPreview]=useState<{document:Guidance;xml:string;links:{label:string;when:string;resolved:boolean}[]}|null>(null);
async function load(){const r=await fetch('/api/documents/'+encodeURIComponent(doc.id));const b=await r.json();if(r.ok){setDoc({...b.document,revision:b.document.revision+1});setPreview(null);setMessage('已加载,保存将创建新版本');}else setMessage(b.error);}
async function submit(action:string){setMessage('处理中…');const r=await fetch('/api/documents'+(action==='preview'?'/preview':''),{method:'POST',headers:{'Content-Type':mode?'application/xml':'application/json'},body:mode?xml:JSON.stringify(doc)});const b=await r.json();if(!r.ok)return setMessage(b.error);if(action==='preview'){setPreview(b);setMessage('预览成功,尚未发布');}else{setDoc({...b.document,revision:b.document.revision+1});setMessage('已发布版本 '+b.document.revision);setPreview(null);}}
return <main className={styles.page}><nav><a href="/">首页</a> · <a href="/documents">用户文档</a> · <a href="/account">邮箱账户</a></nav><h1>发布独立文档</h1><p>需要已验证邮箱。每次发布创建不可变版本;只有原作者可以更新或撤下。</p><label><input type="checkbox" checked={mode} onChange={e=>{setMode(e.target.checked);setPreview(null);}}/> 使用协议 XML(zh-CN)</label>{mode?<label>XML 输入<textarea rows={22} value={xml} onChange={e=>{setXml(e.target.value);setPreview(null);}}/></label>:<><label>文档 ID<input value={doc.id} onChange={e=>setDoc({...doc,id:e.target.value})}/></label><button onClick={load}>加载最新版本以编辑</button><label>待发布版本<input type="number" min={1} value={doc.revision} onChange={e=>setDoc({...doc,revision:Number(e.target.value)})}/></label><label>种类<select value={doc.kind} onChange={e=>setDoc({...doc,kind:e.target.value as Guidance['kind']})}><option>guide</option><option>context</option><option>evidence</option></select></label>{(['title','summary','applies','body'] as const).map(k=><label key={k}>{{title:'标题',summary:'摘要',applies:'适用条件',body:'正文'}[k]}<textarea value={doc[k]} onChange={e=>{setDoc({...doc,[k]:e.target.value});setPreview(null);}}/></label>)}{(['steps','checks'] as const).map(k=><label key={k}>{k==='steps'?'步骤':'检查项'}(每行一项)<textarea value={doc[k].join('\n')} onChange={e=>setDoc({...doc,[k]:e.target.value.split('\n').filter(Boolean)})}/></label>)}<h2>条件链接</h2>{doc.links.map((l,i)=><fieldset key={i}>{(['target','revision','relation','when','label'] as const).map(k=><label key={k}>{k}<input value={l[k]} onChange={e=>setDoc({...doc,links:doc.links.map((v,j)=>j===i?{...v,[k]:k==='revision'?Number(e.target.value):e.target.value}:v)})}/></label>)}<button onClick={()=>setDoc({...doc,links:doc.links.filter((_,j)=>j!==i)})}>移除链接</button></fieldset>)}<button onClick={()=>setDoc({...doc,links:[...doc.links,{target:'',revision:1,relation:'context',when:'',label:''}]})}>添加精确版本链接</button></>}<p><button onClick={()=>submit('preview')}>校验并预览</button> <button onClick={()=>submit('publish')}>发布新版本</button></p><p role="status">{message}</p>{preview&&<article><h2>{preview.document.title}</h2><p>{preview.document.summary}</p><p>适用:{preview.document.applies}</p><p className={styles.body}>{preview.document.body}</p>{preview.document.steps.map((s,i)=><p key={i}>{i+1}. {s}</p>)}{preview.links.map((l,i)=><p key={i}>{l.label} · 条件:{l.when} · {l.resolved?'精确版本可用':'目标缺失,读取时需跳过'}</p>)}<pre>{preview.xml}</pre></article>}</main>;
useEffect(()=>{setPreview(null);},[doc,xml,mode]);
useEffect(()=>{fetch('/api/account/session').then(r=>r.json()).then(b=>{if(b.user){const id=new URLSearchParams(window.location.search).get('id');if(id)fetch('/api/documents/'+encodeURIComponent(id)).then(responseBody).then(b=>setDoc({...b.document,revision:b.document.revision+1})).catch(e=>setMessage(e.message));else setDoc(d=>({...d,id:'user-'+b.user.id+'-'}));}else setMessage('请先登录并验证邮箱,再发布文档。');}).catch(()=>setMessage('账户服务暂不可用,请稍后重试。'));},[]);
async function responseBody(r:Response){const b=await r.json().catch(()=>({error:'服务返回异常,请稍后重试'}));if(!r.ok)throw Error((b.error||'请求失败')+(b.fields?.length?':'+b.fields.join('、'):''));return b;}
async function load(){setBusy(true);setPreview(null);try{const b=await responseBody(await fetch('/api/documents/'+encodeURIComponent(doc.id)));setDoc({...b.document,revision:b.document.revision+1});setMessage('已加载,保存将创建新版本');}catch(e){setMessage(e instanceof Error?e.message:'加载失败');}finally{setBusy(false);}}
async function submit(action:string){setBusy(true);setMessage('处理中…');setPreview(null);setPublished(null);try{const b=await responseBody(await fetch('/api/documents'+(action==='preview'?'/preview':''),{method:'POST',headers:{'Content-Type':mode?'application/xml':'application/json'},body:mode?xml:JSON.stringify(doc)}));if(action==='preview'){setPreview(b);setMessage('预览成功,尚未发布');}else{setDoc({...b.document,revision:b.document.revision+1});setPublished({id:b.document.id,revision:b.document.revision});if(mode)setXml(xml.replace(/revision="[1-9][0-9]*"/,`revision="${b.document.revision+1}"`));setMessage('已发布版本 '+b.document.revision);}}catch(e){setMessage(e instanceof Error?e.message:'请求失败,请稍后重试');}finally{setBusy(false);}}
return <main className={styles.page}><nav><a href="/">首页</a> · <a href="/documents">用户文档</a> · <a href="/account">邮箱账户</a></nav><h1>发布独立文档</h1><p>需要已验证邮箱。每次发布创建不可变版本;只有原作者可以更新或撤下。</p><fieldset disabled={busy}><label><input type="checkbox" checked={mode} onChange={e=>{setMode(e.target.checked);setPreview(null);}}/> 使用协议 XML(zh-CN)</label>{mode?<label>XML 输入<textarea rows={22} value={xml} onChange={e=>{setXml(e.target.value);setPreview(null);}}/></label>:<><label>文档 ID(保留账户前缀,在末尾填写短名)<input value={doc.id} onChange={e=>setDoc({...doc,id:e.target.value})}/></label><button disabled={busy} onClick={load}>加载最新版本以编辑</button><label>待发布版本<input type="number" min={1} value={doc.revision} onChange={e=>setDoc({...doc,revision:Number(e.target.value)})}/></label><label>种类<select value={doc.kind} onChange={e=>setDoc({...doc,kind:e.target.value as Guidance['kind']})}><option>guide</option><option>context</option><option>evidence</option></select></label>{(['title','summary','applies','body'] as const).map(k=><label key={k}>{{title:'标题',summary:'摘要',applies:'适用条件',body:'正文'}[k]}<textarea value={doc[k]} onChange={e=>{setDoc({...doc,[k]:e.target.value});setPreview(null);}}/></label>)}{(['steps','checks'] as const).map(k=><label key={k}>{k==='steps'?'步骤':'检查项'}(每行一项)<textarea value={doc[k].join('\n')} onChange={e=>setDoc({...doc,[k]:e.target.value.split('\n').filter(Boolean)})}/></label>)}<h2>条件链接</h2>{doc.links.map((l,i)=><fieldset key={i}>{(['target','revision','relation','when','label'] as const).map(k=><label key={k}>{k}<input value={l[k]} onChange={e=>setDoc({...doc,links:doc.links.map((v,j)=>j===i?{...v,[k]:k==='revision'?Number(e.target.value):e.target.value}:v)})}/></label>)}<button onClick={()=>setDoc({...doc,links:doc.links.filter((_,j)=>j!==i)})}>移除链接</button></fieldset>)}<button onClick={()=>setDoc({...doc,links:[...doc.links,{target:'',revision:1,relation:'context',when:'',label:''}]})}>添加精确版本链接</button></>}<p><button disabled={busy} onClick={()=>submit('preview')}>校验并预览</button> <button disabled={busy} onClick={()=>submit('publish')}>发布新版本</button></p></fieldset><p role="status">{message}</p>{published&&<p><a href={'/documents/'+published.id+'?revision='+published.revision}>打开已发布文档 v{published.revision} ↗</a></p>}{preview&&<article><h2>{preview.document.title}</h2><p>{preview.document.summary}</p><p>适用:{preview.document.applies}</p><p className={styles.body}>{preview.document.body}</p>{preview.document.steps.map((s,i)=><p key={i}>{i+1}. {s}</p>)}{preview.links.map((l,i)=><p key={i}>{l.label} · 条件:{l.when} · {l.resolved?'精确版本可用':'目标缺失,读取时需跳过'}</p>)}<pre>{preview.xml}</pre></article>}</main>;
}
@@ -3,11 +3,13 @@ import {randomUUID} from 'node:crypto';
import {db} from '../src/lib/db';
import {publishDocument,resolveDocument,withdrawDocument,discoverDocuments} from '../src/lib/guidance-store';
export async function verifyGuidancePublishing(){
const owner=randomUUID(),other=randomUUID(),id='user-'+randomUUID();
const owner=randomUUID(),other=randomUUID(),id='user-'+owner+'-document';
for(const uid of [owner,other])await db().query("INSERT INTO account_users(id,email,password_hash,verified_at) VALUES($1,$2,'test',now())",[uid,uid+'@example.com']);
const doc={id,revision:1,kind:'context',title:'实际数据库文档',summary:'摘要',applies:'条件',body:'正文',steps:[],checks:[],links:[],tags:[]};
await assert.rejects(()=>publishDocument(other,doc),/INVALID_ID/);
await publishDocument(other,{...doc,id:'user-'+other+'-document'});
await publishDocument(owner,doc);assert.equal((await resolveDocument(id,1))?.title,doc.title);
await assert.rejects(()=>publishDocument(other,{...doc,revision:2}),/FORBIDDEN/);
await assert.rejects(()=>publishDocument(other,{...doc,revision:2}),/INVALID_ID/);
const concurrent=await Promise.allSettled([publishDocument(owner,{...doc,revision:2,body:'新正文'}),publishDocument(owner,{...doc,revision:2})]);assert.equal(concurrent.filter(r=>r.status==='fulfilled').length,1);
assert.equal((await resolveDocument(id,1))?.body,'正文');assert.equal(await resolveDocument(id,999),null);
await assert.rejects(()=>db().query('UPDATE guidance_revisions SET content=$2 WHERE document_id=$1',[id,{}]),/immutable/);
@@ -4,3 +4,7 @@ import {parseDocumentXml,documentInput} from '../src/lib/guidance-input';
import {guidanceXml} from '../src/content/guides/catalog';
const doc={id:'user-test',revision:1,kind:'guide' as const,title:'A & B',summary:'摘要',applies:'适用',body:'<正文>',steps:['一步'],checks:[],links:[],tags:[]};
test('XML canonical round trip and strict rejection',()=>{const xml=guidanceXml(doc);assert.deepEqual(parseDocumentXml(xml),doc);for(const bad of [xml.replace('<title>','<title extra="1">'),xml.replace('</body>','</body><title>duplicate</title>'),xml.replace('urn:linked-guidance:0.1','urn:linked-guidance:0.2'),xml.replace('&amp;','&unknown;'),xml.replace('<guidance','<!DOCTYPE guidance><guidance'),xml.replace('revision="1"','revision="1" revision="2"'),xml.replace('<body>','<body><script>')])assert.throws(()=>parseDocumentXml(bad));assert.throws(()=>documentInput.parse({...doc,admin:true}));assert.throws(()=>documentInput.parse({...doc,id:'review-changes'}));});
test('XML rejects forbidden Unicode, CDATA terminator and non-XML whitespace',()=>{const xml=guidanceXml(doc);for(const bad of [xml.replace('摘要','bad]]>value'),xml.replace('摘要','bad\u0000value'),xml.replace('摘要','bad\ud800value'),xml+'\u00a0',xml.replace(' id=', '\u00a0id=')])assert.throws(()=>parseDocumentXml(bad));assert.throws(()=>documentInput.parse({...doc,body:'\u000b正文'}));assert.equal(parseDocumentXml(xml.replace('摘要','😀摘要')).summary,'😀摘要');});
test('tags round trip and quoted attribute greater-than remains text',()=>{const value={...doc,tags:['标签'],links:[{target:'source-trust',revision:1,relation:'context' as const,when:'a > b',label:'来源'}]};const xml=guidanceXml(value);assert.deepEqual(parseDocumentXml(xml),value);assert.deepEqual(parseDocumentXml(xml.replace('a &gt; b','a > b')),value);assert.throws(()=>parseDocumentXml(xml.replace('when="a &gt; b"','when="a < b"')));});
+1 -1
View File
@@ -19,7 +19,7 @@
</guidance>
```
根元素必需属性:命名空间、id(小写字母、数字与短横线)、正整数 revision、kind(guide/context/evidence)、lang。必需单值子元素:title、summary、applies、body。step、link、check 可重复。未知版本必须明确拒绝,不能猜测执行。正文只提供文本,展示层的 HTML 不属于协议。
根元素必需属性:命名空间、id(小写字母、数字与短横线)、正整数 revision、kind(guide/context/evidence)、lang。必需单值子元素:title、summary、applies、body。step、link、check、tag 可重复;tag 为纯文本发现标签,不授予执行语义。未知版本必须明确拒绝,不能猜测执行。正文只提供文本,展示层的 HTML 不属于协议。
## 链接与读取
+4 -2
View File
@@ -5,10 +5,12 @@
- `/write`:已验证邮箱账户创建、加载并发布下一版本,支持结构化表单和受限 XML;预览通过 `/api/documents/preview` 校验并解析条件链接,不写数据库。
- `/documents` 与 `/documents/:id?revision=N`:真实用户文档列表与固定版本阅读。主页可链接这两个入口,现有 `/guide` 可对 `user-` ID 委托 `resolveDocument` 或链接 `/documents/:id`。首页与导航已接入真实发布入口;原型阅读页保留独立样例。
- `/api/documents` GET 列表,POST 创建/发布;`/api/documents/:id` GET 单篇、POST 下一版、DELETE 作者撤下;`?format=xml&revision=N` 返回规范 XML。未指定版本为发现用途,实际采用需固定 revision。
- `user-` 前缀独立于静态 catalog。条件链接可引用静态样例或真实文档;缺失版本明确展示,不自动请求外站、不静默换最新版。撤下后列表及 latest 不再展示,历史固定版本仍然公开可读。
- 邮箱会话仅由新接口校验,不授予管理员 API 权限。发布是公开行为;目前没有草稿服务、私有文档、恢复撤下或账户删除功能。tags 是 JSON 元数据,XML 0.1 没有 tags 字段,XML 导入为无标签文档。
- `user-<author UUID>-<slug>` 命名空间独立于静态 catalog,服务端和数据库均校验作者前缀,同一短名可由不同作者分别发布。条件链接可引用静态样例或真实文档;缺失版本明确展示,不自动请求外站、不静默换最新版。撤下后列表及 latest 不再展示,历史固定版本仍然公开可读。
- 邮箱会话仅由新接口校验,不授予管理员 API 权限。发布是公开行为;目前没有草稿服务、私有文档、恢复撤下或账户删除功能。tags 是发现元数据,通过 XML 可重复的 tag 元素往返保存。
- 数据库通过行锁分配下一版本并拒绝过时编辑,触发器禁止修改/删除已发布内容。数据库所有者仍可执行数据库维护,触发器不是对数据库管理员的安全隔离。
验证由 ces-control PR CI 执行:严格 XML 单元测试;PostgreSQL 真实发布、所有权、并发版本冲突、不可变内容和撤下保留历史的集成测试。PR 不自动部署,服务器视觉验收须主 chat 人工合并后的部署成功再执行。
首页现已通过 `/api/documents` 加载真实发布摘要,并在 GuidanceShell 提供用户文档与发布入口。`/guide` 继续只读取静态协议样例,不覆盖主 chat 的阅读实现。
编辑器自动加载已验证账户前缀。发布成功提供精确版本链接;网络或服务失败保留输入并显示错误,XML 模式成功后推进待编辑版本。严格 XML 校验另拒绝无效 Unicode、CDATA 终止符和非 XML 空白。