Keep retired document pages readable outside the catalog

Reviewed-on: #52

README.md

@@ -179,6 +179,18 @@ python3 scripts/documents-client.py save "$api_work_dir/document.json"
 
 客户端只自动重试一次临时网络或 `502/503/504` 错误，保持正文和请求 ID 不变；`409` 等业务错误不会自动覆盖。它不跟随 HTTP 重定向，避免将 Bearer 凭据转发到其他地址。正文和 Key 继续保存在数据库或私有文件中，不因使用 API 而进入 Git。
 
+### 上传正文图片
+
+使用前述 HTTPS 或 SSH 隧道配置以及 `read-write` 文档 API Key：
+
+```sh
+python3 scripts/documents-client.py upload-image ./diagram.png
+```
+
+客户端向 `POST /api/documents/images` 发送原始图片字节，`Content-Type` 为 `image/png`、`image/jpeg` 或 `image/webp`。服务端接受最大 8 MiB、2500 万像素的静态图，转换为最大 2000 × 4000 像素、2 MiB 的 WebP，并按处理后内容去重。
+
+把响应中的 `url` 放入 Markdown，例如 `![渲染流程图](/api/documents/images/<id>)`，然后通过章节 API 保存正文。登录读者和文档 API Key 均可读取图片。图片存入现有持久化 SQLite，同步纳入整库备份。仅导出正文的 `docs export` 保留图片引用，迁移时需使用包含图片的整库备份。
+
 ## 研究数据与检查
 
 研究工作台提供公司筛选、经营指标、原始证据、收费与交付模式、技术材料及核查记录。它区分公司披露、支付平台指标、第三方估算、融资和客户收益；未知收入不填零，材料可访问也不代表性能或商业效果已经验证。研究范围、样本限制和个案结论以工作台记录为准。

apps/docs/package.json

@@ -20,7 +20,8 @@
     "react": "19.3.1",
     "react-dom": "19.3.1",
     "react-markdown": "10.1.0",
-    "remark-gfm": "4.0.1"
+    "remark-gfm": "4.0.1",
+    "sharp": "0.35.5"
   },
   "devDependencies": {
     "@tailwindcss/postcss": "4.3.3",
@@ -33,7 +34,6 @@
     "eslint": "^9.39.5",
     "eslint-config-next": "16.4.3",
     "postcss": "8.5.31",
-    "sharp": "0.35.5",
     "tailwindcss": "4.3.3",
     "typescript": "~5.9.3"
   }

apps/docs/scripts/auth-cli.ts

@@ -200,11 +200,15 @@ async function main() {
   for (const doc of searchIndex as { slug: string; sourceSlug: string }[]) {
     assert.ok(!doc.slug.split("/").some((part) => /^\d+-/.test(part)), doc.slug);
     const legacy = await request(`/docs/${doc.sourceSlug}?from=legacy`, { headers });
-    assert.equal(legacy.status, 308, doc.sourceSlug);
-    const destination = new URL(legacy.headers.get("location")!, base);
-    assert.equal(destination.pathname, `/docs/${doc.slug}`);
-    assert.equal(destination.searchParams.get("from"), "legacy");
     assert.ok(legacy.headers.get("cache-control")?.includes("no-store"));
+    if (doc.sourceSlug === doc.slug) {
+      assert.equal(legacy.status, 200, doc.sourceSlug);
+    } else {
+      assert.equal(legacy.status, 308, doc.sourceSlug);
+      const destination = new URL(legacy.headers.get("location")!, base);
+      assert.equal(destination.pathname, `/docs/${doc.slug}`);
+      assert.equal(destination.searchParams.get("from"), "legacy");
+    }
   }
   const routes = ["/", ...searchIndex.map((doc: { slug: string }) => `/docs/${doc.slug}`)];
   const raw = await request("/api/documents/source?slug=endor/endor-purpose-draft", { headers });
@@ -254,6 +258,17 @@ async function main() {
       for (const id of ids) assert.ok(html.includes(`href="#${id}"`), `TOC anchor: ${route}#${id}`);
     }
   }
+  assert.ok(!home.includes('data-category="Endor"'), "Superseded Endor collection is absent from navigation");
+  if (searchIndex.some((doc: { collection: string }) => doc.collection === "Endorphin")) {
+    assert.equal([...home.matchAll(/data-category="([^"]+)"/g)][0]?.[1], "Endorphin", "Endorphin is the first category");
+    assert.ok(home.includes('/docs/endorphin/value-proposition'), "Endorphin opens at its value proposition");
+  }
+  // Retired documents remain reachable for historical links and gallery checks.
+  if (!purpose) {
+    const archived = await request("/docs/endor/endor-purpose-draft", { headers });
+    assert.equal(archived.status, 200);
+    purpose = await archived.text();
+  }
   assert.ok(home.includes("资料库"));
   assert.ok(home.includes("/docs/source-studies/pretext/overview"));
   // Inline preview and zoom dialog must both use the compressed browser asset.

apps/docs/src/lib/collections.ts

@@ -1,5 +1,11 @@
 import type { DocLink } from "@/lib/docs";
 
+// Keep superseded Endor pages addressable without offering them as current material.
+export function catalogDocuments<T extends DocLink>(docs: T[]): T[] {
+  return docs.filter((doc) => doc.collection !== "Endor 文档")
+    .sort((a, b) => Number(b.collection === "Endorphin") - Number(a.collection === "Endorphin"));
+}
+
 export function collectionLabel(name: string) {
   return name.replace(/ 文档$| 源码教程$|问题集$/g, "");
 }
@@ -15,10 +21,13 @@ export function collectionIcon(name?: string): "book" | "code" | "layers" | "nod
   if (name?.includes("垃圾回收")) return "nodes";
   return "book";
 }
-export function collectionEntries(docs: DocLink[]) {
+export function collectionEntries(documents: DocLink[]) {
+  const docs = catalogDocuments(documents);
   return [...new Set(docs.map((doc) => doc.collection))].map((name) => {
     const items = docs.filter((doc) => doc.collection === name);
-    const entry = items.find((doc) => doc.slug.endsWith("/overview")) ?? items[0];
+    const entry = items.find((doc) => doc.slug.endsWith("/overview"))
+      ?? (name === "Endorphin" ? items.find((doc) => doc.featured) : undefined)
+      ?? items[0];
     return { name, entry, count: items.length };
   });
 }

apps/docs/src/lib/docs.ts

@@ -1,4 +1,5 @@
 import { randomUUID, createHash } from "node:crypto";
+import { catalogDocuments } from "./collections";
 import { openSiteDatabase } from "./site-database";
 import { DocumentValidationError, DocumentConflictError } from "./document-errors";
 import { sectionSchema, loadSections, reconcileSections, persistSections, splitSections, outline,
@@ -188,7 +189,7 @@ export async function readDoc(slug: string): Promise<Doc> {
 }
 
 export async function listDocs(): Promise<DocLink[]> {
-  return allDocuments().map(({ content: _, ...doc }) => { void _; return doc; });
+  return catalogDocuments(allDocuments()).map(({ content: _, ...doc }) => { void _; return doc; });
 }
 
 // Explicit, atomic bootstrap only. Runtime reads never import repository data.

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

@@ -0,0 +1,39 @@
+import { createHash } from "node:crypto";
+import { openSiteDatabase } from "./site-database";
+
+function openImages() {
+  const db = openSiteDatabase();
+  try {
+    db.exec(`CREATE TABLE IF NOT EXISTS document_images (
+      id TEXT PRIMARY KEY,
+      bytes BLOB NOT NULL
+    )`);
+    return db;
+  } catch (error) {
+    db.close();
+    throw error;
+  }
+}
+
+export function saveDocumentImage(bytes: Buffer) {
+  const id = createHash("sha256").update(bytes).digest("hex");
+  const db = openImages();
+  try {
+    db.prepare("INSERT INTO document_images (id, bytes) VALUES (?, ?) ON CONFLICT(id) DO NOTHING").run(id, bytes);
+    return id;
+  } finally {
+    db.close();
+  }
+}
+
+export function readDocumentImage(id: string) {
+  const db = openImages();
+  try {
+    const row = db.prepare("SELECT bytes FROM document_images WHERE id = ?").get(id) as
+      | { bytes: Uint8Array }
+      | undefined;
+    return row ? Buffer.from(row.bytes) : undefined;
+  } finally {
+    db.close();
+  }
+}

apps/docs/src/pages/api/documents/images/[id].ts

@@ -0,0 +1,24 @@
+import type { NextApiRequest, NextApiResponse } from "next";
+import { documentApiError } from "@/lib/documents-api";
+import { readDocumentImage } from "@/lib/document-images";
+
+// The site proxy accepts a logged-in reader or a document API key on this route.
+export default function handler(request: NextApiRequest, response: NextApiResponse) {
+  try {
+    response.setHeader("Cache-Control", "private, no-store");
+    response.setHeader("X-Content-Type-Options", "nosniff");
+    if (request.method !== "GET" && request.method !== "HEAD") {
+      response.setHeader("Allow", "GET, HEAD");
+      return response.status(405).end();
+    }
+    const id = request.query.id;
+    if (typeof id !== "string" || !/^[a-f0-9]{64}$/.test(id)) return response.status(404).end();
+    const bytes = readDocumentImage(id);
+    if (!bytes) return response.status(404).end();
+    response.setHeader("Content-Type", "image/webp");
+    response.setHeader("Content-Length", bytes.length);
+    return request.method === "HEAD" ? response.status(200).end() : response.status(200).send(bytes);
+  } catch (error) {
+    return documentApiError(response, error);
+  }
+}

apps/docs/src/pages/api/documents/images/index.ts

@@ -0,0 +1,64 @@
+import type { NextApiRequest, NextApiResponse } from "next";
+import sharp from "sharp";
+import { authorizeDocuments, documentApiError } from "@/lib/documents-api";
+import { saveDocumentImage } from "@/lib/document-images";
+
+const maxUploadBytes = 8 * 1024 * 1024;
+const maxStoredBytes = 2 * 1024 * 1024;
+const imageTypes = new Set(["image/png", "image/jpeg", "image/webp"]);
+const imageFormats = new Set(["png", "jpeg", "webp"]);
+
+export const config = { api: { bodyParser: false } };
+
+export default async function handler(request: NextApiRequest, response: NextApiResponse) {
+  try {
+    if (request.method !== "POST") {
+      response.setHeader("Allow", "POST");
+      return response.status(405).end();
+    }
+    if (!authorizeDocuments(request, response, true)) return;
+
+    const type = request.headers["content-type"]?.split(";")[0].trim().toLowerCase();
+    if (!type || !imageTypes.has(type)) {
+      return response.status(415).json({ error: "请上传 PNG、JPEG 或 WebP 图片" });
+    }
+    if (Number(request.headers["content-length"]) > maxUploadBytes) {
+      return response.status(413).json({ error: "图片上传上限为 8 MiB" });
+    }
+
+    const chunks: Buffer[] = [];
+    let length = 0;
+    for await (const chunk of request.iterator({ destroyOnReturn: false })) {
+      const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      length += bytes.length;
+      if (length > maxUploadBytes) {
+        return response.status(413).json({ error: "图片上传上限为 8 MiB" });
+      }
+      chunks.push(bytes);
+    }
+
+    let encoded: Buffer;
+    try {
+      const input = sharp(Buffer.concat(chunks), { limitInputPixels: 25_000_000 });
+      const { format, pages } = await input.metadata();
+      if (!format || !imageFormats.has(format) || type !== `image/${format}` || (pages ?? 1) > 1) {
+        return response.status(415).json({ error: "图片格式需与声明一致，且只支持静态图片" });
+      }
+      encoded = await input.rotate()
+        .resize({ width: 2000, height: 4000, fit: "inside", withoutEnlargement: true })
+        .webp({ quality: 85 })
+        .toBuffer();
+    } catch {
+      return response.status(400).json({ error: "无法解码图片，或像素数量超过限制" });
+    }
+    if (encoded.length > maxStoredBytes) {
+      return response.status(413).json({ error: "处理后的图片超过 2 MiB，请缩小后重试" });
+    }
+
+    const id = saveDocumentImage(encoded);
+    const url = `/api/documents/images/${id}`;
+    return response.status(200).json({ id, url, contentType: "image/webp", size: encoded.length });
+  } catch (error) {
+    return documentApiError(response, error);
+  }
+}

apps/docs/src/pages/api/search.ts

@@ -1,4 +1,5 @@
 import type { NextApiRequest, NextApiResponse } from "next";
+import { catalogDocuments } from "@/lib/collections";
 import { allDocuments } from "@/lib/docs";
 
 // The proxy authenticates this endpoint, including index content.
@@ -9,7 +10,7 @@ export default async function handler(request: NextApiRequest, response: NextApi
     return response.status(405).end();
   }
   try {
-    const index = allDocuments().map(({ content, ...doc }) => ({ ...doc, searchText: content }));
+    const index = catalogDocuments(allDocuments()).map(({ content, ...doc }) => ({ ...doc, searchText: content }));
     return response.status(200).json(index);
   } catch {
     return response.status(503).json({ error: "文档数据库暂时不可用" });

apps/docs/src/pages/docs/[...slug].tsx

@@ -23,6 +23,10 @@ import { collectionEntries, collectionLabel } from "@/lib/collections";
 import { Icon } from "@/components/Icon";
 import { headingsFor } from "@/lib/navigation";
 
+function isZoomableFigure(source: string) {
+  return source.startsWith("/figures/endor-") || /^\/api\/documents\/images\/[a-f0-9]{64}$/.test(source);
+}
+
 type Props = { doc: Doc; docs: DocLink[] };
 const AICompanyResearch = dynamic(() => import("@/components/AICompanyResearch"));
 export const getServerSideProps: GetServerSideProps<Props> = async ({ params, res, resolvedUrl }) => {
@@ -54,7 +58,8 @@ export default function DocPage({
   const [active, setActive] = useState("");
   
   const siblings = docs.filter((d) => d.collection === doc.collection);
-  const collectionEntry = collectionEntries(docs).find((c) => c.name === doc.collection)!.entry;
+  // Historical pages remain readable even when their collection is outside the catalog.
+  const collectionEntry = collectionEntries(docs).find((c) => c.name === doc.collection)?.entry ?? doc;
   const index = siblings.findIndex((d) => d.slug === doc.slug);
   useEffect(() => {
     const observer = new IntersectionObserver(
@@ -120,14 +125,14 @@ export default function DocPage({
                     const slides = node?.children.flatMap((child) =>
                       child.type === "element" && child.tagName === "img" &&
                       typeof child.properties.src === "string" &&
-                      child.properties.src.startsWith("/figures/endor-")
+                      isZoomableFigure(child.properties.src)
                         ? [{ source: child.properties.src, alt: String(child.properties.alt ?? "") }]
                         : [],
                     ) ?? [];
                     const onlyImages = node?.children.every((child) =>
                       (child.type === "element" && child.tagName === "img" &&
                         typeof child.properties.src === "string" &&
-                        child.properties.src.startsWith("/figures/endor-")) ||
+                        isZoomableFigure(child.properties.src)) ||
                       (child.type === "text" && child.value.trim() === ""),
                     );
                     if (slides.length > 1 && onlyImages) return <FigureGallery slides={slides} />;
@@ -141,7 +146,7 @@ export default function DocPage({
                     );
                   },
                   img: ({ src, alt }) =>
-                    typeof src === "string" && src.startsWith("/figures/endor-") ? (
+                    typeof src === "string" && isZoomableFigure(src) ? (
                       <ArchitectureFigure source={src} alt={alt ?? "Endor 架构图"} />
                     ) : (
                       // eslint-disable-next-line @next/next/no-img-element

pnpm-lock.yaml

@@ -28,6 +28,9 @@ importers:
       remark-gfm:
         specifier: 4.0.1
         version: 4.0.1(supports-color@7.2.0)
+      sharp:
+        specifier: 0.35.5
+        version: 0.35.5(@types/node@22.20.5)
     devDependencies:
       '@tailwindcss/postcss':
         specifier: 4.3.3
@@ -59,9 +62,6 @@ importers:
       postcss:
         specifier: 8.5.31
         version: 8.5.31
-      sharp:
-        specifier: 0.35.5
-        version: 0.35.5(@types/node@22.20.5)
       tailwindcss:
         specifier: 4.3.3
         version: 4.3.3

scripts/documents-client.py

@@ -45,14 +45,15 @@ def read_token(filename):
     return value
 
 
-def request(base, token, method, path, payload=None, request_id=None):
+def request(base, token, method, path, payload=None, request_id=None, *, image_type=None):
-    data = None if payload is None else json.dumps(payload, ensure_ascii=False).encode()
+    data = payload if image_type else (None if payload is None else json.dumps(payload, ensure_ascii=False).encode())
     if data is not None and len(data) > 8 * 1024 * 1024:
         raise ValueError('Request exceeds 8 MiB; split into smaller atomic batches')
     headers = {'Authorization': 'Bearer ' + token, 'Accept': 'application/json'}
     if data is not None:
-        headers['Content-Type'] = 'application/json'
+        headers['Content-Type'] = image_type or 'application/json'
-        headers['Idempotency-Key'] = request_id
+        if request_id is not None:
+            headers['Idempotency-Key'] = request_id
     opener = urllib.request.build_opener(NoRedirect())
     for attempt in range(2):
         req = urllib.request.Request(base + path, data=data, method=method, headers=headers)
@@ -127,6 +128,8 @@ def main():
     editing.add_argument('slug')
     editing.add_argument('file')
     editing.add_argument('--request-id')
+    upload = sub.add_parser('upload-image', help='Upload a static image and print its Markdown URL')
+    upload.add_argument('file')
     saving = sub.add_parser('save')
     saving.add_argument('file', help='Private JSON file or - for stdin; one document or {documents: [...]}')
     saving.add_argument('--request-id', help='Reuse this id only with the same input when retrying')
@@ -136,7 +139,18 @@ def main():
     try:
         base = server_url(args.url)
         token = read_token(args.key_file)
-        if args.command == 'list':
+        if args.command == 'upload-image':
+            image = Path(args.file)
+            image_types = {'.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp'}
+            image_type = image_types.get(image.suffix.lower())
+            if not image_type:
+                raise ValueError('Use a PNG, JPEG or WebP image')
+            with image.open('rb') as source:
+                data = source.read(8 * 1024 * 1024 + 1)
+            if len(data) > 8 * 1024 * 1024:
+                raise ValueError('Image exceeds 8 MiB')
+            result = request(base, token, 'POST', '/api/documents/images', data, image_type=image_type)
+        elif args.command == 'list':
             result = request(base, token, 'GET', '/api/documents?' + urllib.parse.urlencode(
                 {'limit': args.limit, 'offset': args.offset}))
         elif args.command == 'get':