Add persistent author-owned guidance publishing and immutable revisions

This commit is contained in:
2026-10-29 16:47:21 +08:00
parent e141de05fe
commit d5807aa298
15 changed files with 125 additions and 2 deletions
@@ -0,0 +1,19 @@
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 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(Buffer.byteLength(source)>131072)throw Error('XML 过大');
let s=source.replace(/^<\?xml version="1.0" encoding="UTF-8"\?>\s*/, '');
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 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]);
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);
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);}
return documentInput.parse(result);
}
@@ -0,0 +1,15 @@
import { db,transaction } from './db';
import { documentInput } from './guidance-input';
import { findGuide,type Guidance } from '../content/guides/catalog';
export async function resolveDocument(id:string,revision?:number):Promise<Guidance|null>{
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=>{
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');
await c.query('INSERT INTO guidance_revisions(document_id,revision,content) VALUES($1,$2,$3)',[content.id,content.revision,content]);await c.query('UPDATE guidance_documents SET latest=$2 WHERE id=$1',[content.id,content.revision]);return content;
});}
export async function withdrawDocument(owner:string,id:string){const r=await db().query('UPDATE guidance_documents SET deleted_at=COALESCE(deleted_at,now()) WHERE id=$1 AND owner_id=$2 RETURNING id',[id,owner]);return !!r.rowCount;}
export async function discoverDocuments(){const r=await db().query(`SELECT d.id,d.latest AS revision,r.content->>'title' AS title,r.content->>'summary' AS summary,r.content->>'kind' AS kind,d.owner_id AS author FROM guidance_documents d JOIN guidance_revisions r ON r.document_id=d.id AND r.revision=d.latest WHERE d.deleted_at IS NULL ORDER BY r.created_at DESC LIMIT 100`);return r.rows;}
@@ -0,0 +1,26 @@
import type { NextApiRequest,NextApiResponse } from 'next';
import { currentAccount } from '@/lib/account';
import { trustedOrigin } from '@/lib/account-crypto';
import { documentInput,parseDocumentXml } from '@/lib/guidance-input';
import { discoverDocuments,publishDocument,resolveDocument,withdrawDocument } from '@/lib/guidance-store';
import { guidanceXml } from '@/content/guides/catalog';
export default async function handler(req:NextApiRequest,res:NextApiResponse){
res.setHeader('Cache-Control','no-store');const path=req.query.path||[];if(!Array.isArray(path)||path.length>1)return res.status(404).end();const id=path[0];
try{
if(req.method==='GET'){
if(!id)return res.json({documents:await discoverDocuments()});
const revision=req.query.revision;if(revision!==undefined&&(typeof revision!=='string'||! /^[1-9][0-9]{0,9}$/.test(revision)||Number(revision)>2147483647))return res.status(400).json({error:'版本无效'});
const doc=await resolveDocument(id,revision===undefined?undefined:Number(revision));if(!doc)return res.status(404).json({error:'文档或精确版本不存在'});
if(req.query.format==='xml'){res.setHeader('Content-Type','application/xml; charset=utf-8');return res.send(guidanceXml(doc));}return res.json({document:doc});}
if(!['POST','DELETE'].includes(req.method||'')){res.setHeader('Allow','GET, POST, DELETE');return res.status(405).end();}
const request=new Request(new URL(req.url||'/',process.env.ACCOUNT_PUBLIC_ORIGIN||'http://'+req.headers.host),{headers:new Headers(Object.entries(req.headers).filter(([,v])=>typeof v==='string') as [string,string][])});
if(!trustedOrigin(request))return res.status(403).json({error:'请求来源不受信任'});
const user=await currentAccount(request);if(!user)return res.status(401).json({error:'请先登录已验证邮箱账户'});
if(req.method==='DELETE')return id&&await withdrawDocument(user.id,id)?res.json({ok:true}):res.status(404).json({error:'无权删除或不存在'});
const input=typeof req.body==='string'?parseDocumentXml(req.body):documentInput.parse(req.body);
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:'文档服务暂不可用'});}
}
export const config={api:{bodyParser:{sizeLimit:'128kb'}}};
@@ -0,0 +1,6 @@
import type { GetServerSideProps } from 'next';
import type { Guidance } from '@/content/guides/catalog';
import styles from '@/styles/documents.module.css';
type Props={doc:Guidance;links:(Guidance['links'][number]&{resolved:boolean})[]};
export default function Read({doc,links}:Props){return <main className={styles.page}><nav><a href="/documents">用户文档</a> · <a href="/write">编辑 / 发布</a></nav><h1>{doc.title}</h1><p>{doc.kind} · {doc.id} · 固定版本 {doc.revision}</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><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})=>{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)})));return {props:{doc,links}};};
@@ -0,0 +1,3 @@
import { useEffect,useState } from 'react';
import styles from '@/styles/documents.module.css';
export default function Documents(){const [docs,setDocs]=useState<{id:string;revision:number;title:string;summary:string;kind:string}[]>([]),[error,setError]=useState('');useEffect(()=>{fetch('/api/documents').then(async r=>{const b=await r.json();if(!r.ok)throw Error(b.error);setDocs(b.documents);}).catch(e=>setError(e.message));},[]);return <main className={styles.page}><nav><a href="/">首页</a> · <a href="/write">发布文档</a></nav><h1>用户发布的文档</h1><p>{error}</p>{docs.map(d=><article key={d.id}><h2><a href={'/documents/'+d.id+'?revision='+d.revision}>{d.title}</a></h2><p>{d.kind} · v{d.revision}</p><p>{d.summary}</p></article>)}</main>;}
+10
View File
@@ -0,0 +1,10 @@
import { 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 [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>;
}
+1 -1
View File
@@ -5,7 +5,7 @@ export function proxy(request: NextRequest) {
const responseHeaders = {'Cache-Control':'private, no-store', 'Referrer-Policy':'same-origin'};
// Public knowledge pages are read-only. Account handlers enforce their own origin and session checks.
const publicRead = ['GET','HEAD'].includes(request.method) && (path === '/' || path === '/protocol' || path.startsWith('/guide/') || path.startsWith('/api/guides/'));
if (publicRead || path === '/account' || path.startsWith('/api/account/')) return NextResponse.next({headers:{...responseHeaders,'Referrer-Policy':'no-referrer'}});
if (path === '/write' || path === '/documents' || path.startsWith('/documents/') || path === '/api/documents' || path.startsWith('/api/documents/') || publicRead || path === '/account' || path.startsWith('/api/account/')) return NextResponse.next({headers:{...responseHeaders,'Referrer-Policy':'no-referrer'}});
if (path === '/brand-mark.svg' || path === '/login' || path === '/api/auth/login' || path === '/api/auth/logout' || path === '/api/health' || path === '/api/ready' || path.startsWith('/_next/static/')) return NextResponse.next({headers:responseHeaders});
let config;
try { config = authConfig(); } catch { return NextResponse.json({error:'登录服务配置不可用'}, {status:503,headers:responseHeaders}); }
@@ -0,0 +1 @@
.page{max-width:850px;margin:0 auto;padding:40px 24px 100px;color:#202326;font-family:system-ui,sans-serif;line-height:1.7}.page nav{margin-bottom:32px}.page a{color:#276750}.page h1{font-size:36px;letter-spacing:-1px}.page label{display:block;margin:18px 0}.page input:not([type=checkbox]),.page textarea,.page select{display:block;width:100%;padding:12px;border:1px solid #d8ded8;border-radius:8px;background:#fff;color:inherit;font:inherit;box-sizing:border-box}.page button{padding:10px 18px;background:#264e40;color:#fff;border:0;border-radius:7px;cursor:pointer}.page article{border-top:1px solid #d8ded8;padding:22px 0}.page pre{white-space:pre-wrap;overflow-wrap:anywhere;background:#f1f4ef;padding:18px}.body{white-space:pre-wrap}.page fieldset{border:1px solid #d8ded8;border-radius:8px;margin:14px 0}