Merge pull request '支持基于内部摘要的章节级文章编辑' (#30) from codex/document-sections into main

Reviewed-on: #30

apps/docs/src/lib/docs.ts

@@ -1,5 +1,9 @@
 import { randomUUID, createHash } from "node:crypto";
 import { openSiteDatabase } from "./site-database";
+import { DocumentValidationError, DocumentConflictError } from "./document-errors";
+import { sectionSchema, loadSections, reconcileSections, persistSections, splitSections, outline,
+  applySectionOperations, parseSectionEdit, type DocumentSection } from "./document-sections";
+export { DocumentValidationError, DocumentConflictError } from "./document-errors";
 
 export type DocLink = {
   slug: string; sourceSlug: string; category: string; title: string; searchText?: string;
@@ -9,8 +13,6 @@ export type DocLink = {
 export type Doc = DocLink & { content: string };
 export type DocInput = Omit<Doc, "revision" | "searchText">;
 export type DocumentExport = { format: "tabularium-documents-v1"; documents: Doc[] };
-export class DocumentValidationError extends Error {}
-export class DocumentConflictError extends Error {}
 export type DocumentReceipt = Pick<Doc, "slug" | "sourceSlug" | "revision">;
 export const validSlug = /^[a-z0-9]+(?:-[a-z0-9]+)*(?:\/[a-z0-9]+(?:-[a-z0-9]+)*)*$/;
 
@@ -36,6 +38,7 @@ function database() {
       digest TEXT PRIMARY KEY, document_count INTEGER NOT NULL, created_at TEXT NOT NULL
     );
   `);
+  sectionSchema(db);
   return db;
 }
 
@@ -57,12 +60,13 @@ export function validateDocument(input: DocInput): void {
     throw new DocumentValidationError("Use compressed WebP images instead of original rasters");
 }
 
-function write(db: ReturnType<typeof database>, input: DocInput, expectedRevision: number): Doc {
+function write(db: ReturnType<typeof database>, input: DocInput, expectedRevision: number, editedSections?: DocumentSection[]): Doc {
   validateDocument(input);
-  const existing = db.prepare("SELECT id, revision FROM documents WHERE source_slug=?")
-    .get(input.sourceSlug) as { id: string; revision: number } | undefined;
+  const existing = db.prepare("SELECT id, revision, payload FROM documents WHERE source_slug=?")
+    .get(input.sourceSlug) as { id: string; revision: number; payload: string } | undefined;
   if ((existing?.revision ?? 0) !== expectedRevision) throw new DocumentConflictError("Document revision conflict");
   const id = existing?.id ?? randomUUID();
+  const previous = existing ? loadSections(db, id, (JSON.parse(existing.payload) as Doc).content) : [];
   const doc: Doc = { slug: input.slug, sourceSlug: input.sourceSlug, category: input.category,
     title: input.title, group: input.group, collection: input.collection, description: input.description,
     draft: input.draft, featured: input.featured, content: input.content, revision: expectedRevision + 1 };
@@ -80,9 +84,75 @@ function write(db: ReturnType<typeof database>, input: DocInput, expectedRevisio
     db.prepare("INSERT OR IGNORE INTO document_aliases VALUES (?,?)").run(alias, id);
   db.prepare("INSERT INTO document_revisions VALUES (?,?,?,?)")
     .run(id, doc.revision, payload, new Date().toISOString());
+  persistSections(db, id, doc.revision, editedSections ?? reconcileSections(doc.content, previous));
   return doc;
 }
 
+// Internal summaries never enter Doc, catalog, search or browser page props.
+export function readDocumentSections(slug: string, revision?: number) {
+  if (!validSlug.test(slug)) throw new DocumentValidationError("Invalid document slug");
+  if (revision !== undefined && (!Number.isSafeInteger(revision) || revision < 1)) throw new DocumentValidationError("Invalid revision");
+  const db = database();
+  try {
+    db.exec("BEGIN");
+    const row = db.prepare(`SELECT d.id,d.payload FROM documents d JOIN document_aliases a
+      ON a.document_id=d.id WHERE a.alias=?`).get(slug) as { id: string; payload: string } | undefined;
+    if (!row) { db.exec("COMMIT"); return null; }
+    let doc = JSON.parse(row.payload) as Doc;
+    let sections: DocumentSection[];
+    if (revision === undefined || revision === doc.revision) sections = loadSections(db, row.id, doc.content);
+    else {
+      const prior = db.prepare("SELECT payload FROM document_revisions WHERE document_id=? AND revision=?")
+        .get(row.id, revision) as { payload: string } | undefined;
+      if (!prior) { db.exec("COMMIT"); return null; }
+      doc = JSON.parse(prior.payload) as Doc;
+      const snapshot = db.prepare("SELECT payload FROM document_section_revisions WHERE document_id=? AND revision=?")
+        .get(row.id, revision) as { payload: string } | undefined;
+      sections = snapshot ? JSON.parse(snapshot.payload) as DocumentSection[] : splitSections(doc.content);
+    }
+    db.exec("COMMIT");
+    return { slug: doc.slug, sourceSlug: doc.sourceSlug, title: doc.title, revision: doc.revision, sections };
+  } finally { db.close(); }
+}
+
+export function editDocumentSections(slug: string, value: unknown, request?: { namespace: string; id: string }) {
+  if (!validSlug.test(slug)) throw new DocumentValidationError("Invalid document slug");
+  const edit = parseSectionEdit(value);
+  if (request && (!request.namespace || !/^[A-Za-z0-9._:-]{1,128}$/.test(request.id))) throw new DocumentValidationError("Invalid Idempotency-Key");
+  const digest = createHash("sha256").update(JSON.stringify({ slug, edit })).digest("hex");
+  const namespace = request ? request.namespace + ":sections" : undefined;
+  const db = database();
+  try {
+    db.exec("BEGIN IMMEDIATE");
+    try {
+      if (request) {
+        const prior = db.prepare("SELECT digest,response FROM document_write_requests WHERE namespace=? AND request_id=?")
+          .get(namespace!, request.id) as { digest: string; response: string } | undefined;
+        if (prior) {
+          if (prior.digest !== digest) throw new DocumentConflictError("Idempotency-Key was used with different content");
+          db.exec("COMMIT");
+          return { ...JSON.parse(prior.response) as { slug: string; sourceSlug: string; revision: number; sections: ReturnType<typeof outline> }, replayed: true };
+        }
+      }
+      const row = db.prepare(`SELECT d.id,d.payload FROM documents d JOIN document_aliases a
+        ON a.document_id=d.id WHERE a.alias=?`).get(slug) as { id: string; payload: string } | undefined;
+      if (!row) { db.exec("COMMIT"); return null; }
+      const doc = JSON.parse(row.payload) as Doc;
+      if (doc.revision !== edit.revision) throw new DocumentConflictError("Document revision conflict");
+      const previous = loadSections(db, row.id, doc.content);
+      const sections = applySectionOperations(previous, edit.operations);
+      // Preserve the initial outline when upgrading an existing document for the first time.
+      db.prepare("INSERT OR IGNORE INTO document_section_revisions VALUES (?,?,?)").run(row.id, doc.revision, JSON.stringify(previous));
+      const saved = write(db, { ...doc, content: sections.map((s) => s.content).join("") }, doc.revision, sections);
+      const receipt = { slug: saved.slug, sourceSlug: saved.sourceSlug, revision: saved.revision, sections: outline(sections) };
+      if (request) db.prepare("INSERT INTO document_write_requests VALUES (?,?,?,?)")
+        .run(namespace!, request.id, digest, JSON.stringify(receipt));
+      db.exec("COMMIT");
+      return { ...receipt, replayed: false };
+    } catch (error) { db.exec("ROLLBACK"); throw error; }
+  } finally { db.close(); }
+}
+
 export function saveDocument(input: DocInput, expectedRevision: number): Doc {
   if (!Number.isSafeInteger(expectedRevision) || expectedRevision < 0) throw new DocumentValidationError("Provide expected revision");
   const db = database();

apps/docs/src/lib/document-errors.ts

@@ -0,0 +1,2 @@
+export class DocumentValidationError extends Error {}
+export class DocumentConflictError extends Error {}

apps/docs/src/lib/document-sections.ts

@@ -0,0 +1,144 @@
+import { createHash, randomUUID } from "node:crypto";
+import type { DatabaseSync } from "node:sqlite";
+import { DocumentValidationError } from "./document-errors";
+
+export type DocumentSection = {
+  id: string; title: string; content: string; summary: string;
+};
+export type SectionOperation =
+  | { op: "update"; id: string; content?: string; summary?: string }
+  | { op: "insert"; after: string; content: string; summary: string }
+  | { op: "delete"; id: string }
+  | { op: "move"; id: string; after: string };
+export type SectionEdit = { revision: number; operations: SectionOperation[] };
+const hash = (text: string) => createHash("sha256").update(text).digest("hex");
+
+// Preserve every byte, including CRLF and separators. H3-H6 belong to their H2 chapter.
+export function splitSections(content: string): DocumentSection[] {
+  const starts: { offset: number; title: string }[] = [{ offset: 0, title: "导言" }];
+  let offset = 0;
+  let fence: { marker: string; length: number } | undefined;
+  for (const line of content.match(/[^\n]*\n|[^\n]+$/g) ?? []) {
+    const opening = line.match(/^ {0,3}(`{3,}|~{3,})(.*?)(?:\r?\n)?$/);
+    if (fence) {
+      if (new RegExp(`^ {0,3}${fence.marker}{${fence.length},}[ \\t]*\\r?\\n?$`).test(line)) fence = undefined;
+    } else if (opening && !(opening[1][0] === "`" && opening[2].includes("`"))) {
+      fence = { marker: opening[1][0], length: opening[1].length };
+    } else {
+      const heading = line.match(/^##(?:[ \t]+(.*?))?[ \t]*\r?\n?$/);
+      if (heading) starts.push({ offset, title: (heading[1] ?? "").replace(/[ \t]+#+[ \t]*$/, "").trim() });
+    }
+    offset += line.length;
+  }
+  const seen = new Map<string, number>();
+  return starts.map((start, index) => {
+    const occurrence = seen.get(start.title) ?? 0;
+    seen.set(start.title, occurrence + 1);
+    return { id: index === 0 ? "preamble" : "s_" + hash(`${start.title}\0${occurrence}`).slice(0, 24),
+      title: start.title, content: content.slice(start.offset, starts[index + 1]?.offset), summary: "" };
+  });
+}
+
+export function sectionSchema(db: DatabaseSync) {
+  db.exec(`CREATE TABLE IF NOT EXISTS document_sections (
+    document_id TEXT PRIMARY KEY REFERENCES documents(id), payload TEXT NOT NULL
+  );
+  CREATE TABLE IF NOT EXISTS document_section_revisions (
+    document_id TEXT NOT NULL REFERENCES documents(id), revision INTEGER NOT NULL,
+    payload TEXT NOT NULL, PRIMARY KEY(document_id, revision)
+  );`);
+}
+
+export function loadSections(db: DatabaseSync, documentId: string, content: string): DocumentSection[] {
+  const row = db.prepare("SELECT payload FROM document_sections WHERE document_id=?")
+    .get(documentId) as { payload: string } | undefined;
+  if (!row) return splitSections(content);
+  const sections = JSON.parse(row.payload) as DocumentSection[];
+  // A legacy writer must not leave an apparently current outline over different Markdown.
+  return sections.map((s) => s.content).join("") === content ? sections : reconcileSections(content, sections);
+}
+
+export function reconcileSections(content: string, previous: DocumentSection[]): DocumentSection[] {
+  const unused = new Set(previous);
+  return splitSections(content).map((section) => {
+    const prior = section.id === "preamble" ? previous.find((p) => p.id === "preamble") :
+      previous.find((p) => p.id !== "preamble" && unused.has(p) && p.content === section.content) ??
+      previous.find((p) => p.id !== "preamble" && unused.has(p) && p.title === section.title);
+    if (prior) unused.delete(prior);
+    return { ...section, id: prior?.id ?? (section.id === "preamble" ? "preamble" : "s_" + randomUUID()),
+      summary: prior?.content === section.content ? prior.summary : "" };
+  });
+}
+
+export function persistSections(db: DatabaseSync, documentId: string, revision: number, sections: DocumentSection[]) {
+  const payload = JSON.stringify(sections);
+  db.prepare(`INSERT INTO document_sections VALUES (?,?) ON CONFLICT(document_id)
+    DO UPDATE SET payload=excluded.payload`).run(documentId, payload);
+  db.prepare("INSERT INTO document_section_revisions VALUES (?,?,?)").run(documentId, revision, payload);
+}
+
+export function outline(sections: DocumentSection[]) {
+  return sections.map(({ content, ...section }, position) => ({ ...section, position,
+    contentHash: hash(content), summaryStatus: section.summary.trim() ? "current" : "missing" }));
+}
+
+export function parseSectionEdit(value: unknown): SectionEdit {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new DocumentValidationError("Expected section edit object");
+  const row = value as Record<string, unknown>;
+  if (Object.keys(row).some((key) => !["revision", "operations"].includes(key)) ||
+      !Number.isSafeInteger(row.revision) || (row.revision as number) < 1 || !Array.isArray(row.operations) ||
+      !row.operations.length || row.operations.length > 100) throw new DocumentValidationError("Provide revision and 1 to 100 operations");
+  for (const raw of row.operations) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new DocumentValidationError("Invalid operation");
+    const op = raw as Record<string, unknown>;
+    const fields: Record<string, string[]> = { update: ["op", "id", "content", "summary"],
+      insert: ["op", "after", "content", "summary"], delete: ["op", "id"], move: ["op", "id", "after"] };
+    if (typeof op.op !== "string" || !Object.hasOwn(fields, op.op) || Object.keys(op).some((key) => !fields[op.op as string].includes(key)))
+      throw new DocumentValidationError("Unknown operation or field");
+    for (const key of fields[op.op].filter((key) => !["content", "summary", "op"].includes(key)))
+      if (typeof op[key] !== "string" || !(op[key] as string).length) throw new DocumentValidationError("Missing section identifier");
+    for (const key of ["content", "summary"])
+      if (op[key] !== undefined && typeof op[key] !== "string") throw new DocumentValidationError(`Invalid ${key}`);
+    if (op.op === "update" && op.content === undefined && op.summary === undefined) throw new DocumentValidationError("Empty update");
+    if (op.op === "insert" && (typeof op.content !== "string" || typeof op.summary !== "string" || !op.summary.trim()))
+      throw new DocumentValidationError("Insert requires content and summary");
+    if (typeof op.summary === "string" && (!op.summary.trim() || op.summary.length > 8000))
+      throw new DocumentValidationError("Summary must contain 1 to 8000 characters");
+  }
+  return { revision: row.revision as number, operations: row.operations as SectionOperation[] };
+}
+
+export function applySectionOperations(previous: DocumentSection[], operations: SectionOperation[]) {
+  const sections = previous.map((section) => ({ ...section }));
+  function index(id: string) {
+    const result = sections.findIndex((s) => s.id === id);
+    if (result < 0) throw new DocumentValidationError("Unknown section id");
+    return result;
+  }
+  for (const op of operations) {
+    if (op.op === "insert") {
+      sections.splice(index(op.after) + 1, 0, { id: "s_" + randomUUID(), title: "", content: op.content, summary: op.summary });
+    } else {
+      const at = index(op.id);
+      if (op.op === "update") {
+        if (op.content !== undefined && op.content !== sections[at].content) sections[at].summary = "";
+        if (op.content !== undefined) sections[at].content = op.content;
+        if (op.summary !== undefined) sections[at].summary = op.summary;
+      } else {
+        if (op.id === "preamble") throw new DocumentValidationError("Cannot delete or move the preamble");
+        if (op.op === "delete") sections.splice(at, 1);
+        else {
+          if (op.id === op.after) throw new DocumentValidationError("Cannot move section after itself");
+          index(op.after);
+          const [section] = sections.splice(at, 1);
+          sections.splice(index(op.after) + 1, 0, section);
+        }
+      }
+    }
+  }
+  const content = sections.map((s) => s.content).join("");
+  const parsed = splitSections(content);
+  if (parsed.length !== sections.length || parsed.some((s, i) => s.content !== sections[i].content))
+    throw new DocumentValidationError("Each chapter must start with one H2 heading; preserve newline boundaries and balanced fences");
+  return sections.map((s, i) => ({ ...s, title: parsed[i].title }));
+}

apps/docs/src/pages/api/documents/sections/[...slug].ts

@@ -0,0 +1,37 @@
+import type { NextApiRequest, NextApiResponse } from "next";
+import { DocumentValidationError, readDocumentSections, editDocumentSections } from "@/lib/docs";
+import { outline } from "@/lib/document-sections";
+import { authorizeDocuments, documentApiError, idempotency } from "@/lib/documents-api";
+
+export const config = { api: { bodyParser: { sizeLimit: "8mb" } } };
+export default function handler(request: NextApiRequest, response: NextApiResponse) {
+  try {
+    const key = authorizeDocuments(request, response, request.method === "POST");
+    if (!key) return;
+    if (request.method !== "GET" && request.method !== "POST") {
+      response.setHeader("Allow", "GET, POST");
+      return response.status(405).end();
+    }
+    if (!Array.isArray(request.query.slug)) throw new DocumentValidationError("Invalid document slug");
+    const slug = request.query.slug.join("/");
+    if (Object.keys(request.query).some((k) => !["slug", "section", "revision"].includes(k)))
+      throw new DocumentValidationError("Unknown section query");
+    if (request.method === "POST") {
+      if (request.query.section !== undefined || request.query.revision !== undefined)
+        throw new DocumentValidationError("POST uses revision and operations in the body");
+      const saved = editDocumentSections(slug, request.body, idempotency(request, key.id));
+      return saved ? response.status(200).json(saved) : response.status(404).json({ code: "not_found" });
+    }
+    const revision = request.query.revision;
+    if (revision !== undefined && (typeof revision !== "string" || !/^[1-9]\d*$/.test(revision)))
+      throw new DocumentValidationError("Invalid revision");
+    const doc = readDocumentSections(slug, revision === undefined ? undefined : Number(revision));
+    if (!doc) return response.status(404).json({ code: "not_found" });
+    const selected = request.query.section;
+    if (selected === undefined) return response.status(200).json({ ...doc, sections: outline(doc.sections) });
+    const ids = typeof selected === "string" ? [selected] : selected;
+    if (!ids.length || ids.length > 100 || ids.some((id) => !id)) throw new DocumentValidationError("Select 1 to 100 sections");
+    if (ids.some((id) => !doc.sections.some((s) => s.id === id))) return response.status(404).json({ code: "not_found" });
+    return response.status(200).json({ ...doc, sections: doc.sections.filter((s) => ids.includes(s.id)) });
+  } catch (error) { return documentApiError(response, error); }
+}