feat: 建立 DOCX 共享协议与准备服务

2026-07-30 11:04:18 +08:00
parent fb3ddada39
commit f7d4efeafc
10 changed files with 512 additions and 3 deletions
@@ -9,12 +9,14 @@
 src/
  document.ts       Markdown 文档、分页载荷、结果与耗时模型
  document-link.ts  跨端链接分类与 PDF 本地链接编码协议
+  docx.ts           DOCX 请求、能力、错误、结果与文件名协议
  export-config.ts  纸张、边距、页眉页脚、页码与图表配置
  theme.ts          主题清单、主题能力与 CSS 载荷模型
  index.ts          公共导出入口
 tests/
  document.test.ts
  document-link.test.ts
+  docx.test.ts
  export-config.test.ts
 ```

@@ -23,13 +25,20 @@ tests/
 ```ts
 import {
  classifyDocumentLink,
+  createDocxFileName,
  createPagedDocumentPayload,
  defaultExportConfig,
+  docxExportRequestSchema,
  exportConfigSchema
 } from "@md-to-pdf/core";

 const link = classifyDocumentLink("../docs/example.md");
 const config = exportConfigSchema.parse(defaultExportConfig);
+const docxRequest = docxExportRequestSchema.parse({
+  markdown: "# Example",
+  exportConfig: config
+});
+const docxFileName = createDocxFileName("example.md");
 const payload = createPagedDocumentPayload({
  document,
  fileName: "example.md",
@@ -38,6 +47,10 @@ const payload = createPagedDocumentPayload({
 });
 ```

+DOCX 协议固定 Pandoc `3.9.0.2`，并统一定义跨 HTTP/IPC 使用的请求、
+capability、错误码、结果、诊断和耗时类型。该包只描述数据协议，不启动
+Pandoc 或读写临时文件。
+
 `classifyDocumentLink()` 只负责稳定分类，不执行平台动作。Web 根据分类
 处理锚点和网络链接；Desktop 决定是否调用浏览器、系统程序或打开新的
 Markdown 窗口。精确 PDF 使用保留的 `.invalid` 地址暂存本地链接，
@@ -0,0 +1,149 @@
+import { z } from "zod";
+import { exportConfigSchema } from "./export-config.js";
+
+export const DOCX_PANDOC_VERSION = "3.9.0.2";
+export const DOCX_MIME_TYPE =
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
+export const DOCX_FILE_EXTENSION = ".docx";
+export const MAXIMUM_DOCX_MARKDOWN_LENGTH = 1_500_000;
+export const MAXIMUM_DOCX_FILE_NAME_LENGTH = 500;
+export const MAXIMUM_DOCX_RESOURCE_COUNT = 50;
+
+export const documentExportFormatSchema = z.enum(["pdf", "docx"]);
+export type DocumentExportFormat = z.infer<
+  typeof documentExportFormatSchema
+>;
+
+export const docxSourceResourceSchema = z.object({
+  path: z.string().min(1).max(1_000),
+  contentType: z.string().min(1).max(100).optional(),
+  data: z.string().min(1)
+});
+
+export type DocxSourceResource = z.infer<
+  typeof docxSourceResourceSchema
+>;
+
+export const docxExportRequestSchema = z.object({
+  markdown: z.string().max(MAXIMUM_DOCX_MARKDOWN_LENGTH),
+  fileName: z
+    .string()
+    .max(MAXIMUM_DOCX_FILE_NAME_LENGTH)
+    .default("文档.md"),
+  language: z.string().max(50).default("zh-CN"),
+  resources: z
+    .array(docxSourceResourceSchema)
+    .max(MAXIMUM_DOCX_RESOURCE_COUNT)
+    .default([]),
+  exportConfig: exportConfigSchema
+});
+
+export type DocxExportRequest = z.infer<
+  typeof docxExportRequestSchema
+>;
+export type DocxExportRequestInput = z.input<
+  typeof docxExportRequestSchema
+>;
+
+export const docxRuntimeStatusSchema = z.enum([
+  "available",
+  "not-found",
+  "version-mismatch",
+  "not-executable",
+  "probe-timeout"
+]);
+
+export type DocxRuntimeStatus = z.infer<
+  typeof docxRuntimeStatusSchema
+>;
+
+const availableDocxCapabilitySchema = z.object({
+  format: z.literal("docx"),
+  status: z.literal("available"),
+  expectedVersion: z.literal(DOCX_PANDOC_VERSION),
+  detectedVersion: z.literal(DOCX_PANDOC_VERSION)
+});
+
+const unavailableDocxCapabilitySchema = z.object({
+  format: z.literal("docx"),
+  status: docxRuntimeStatusSchema.exclude(["available"]),
+  expectedVersion: z.literal(DOCX_PANDOC_VERSION),
+  detectedVersion: z.string().max(100).optional(),
+  message: z.string().max(500)
+});
+
+export const docxCapabilitySchema = z.discriminatedUnion("status", [
+  availableDocxCapabilitySchema,
+  unavailableDocxCapabilitySchema
+]);
+
+export type DocxCapability = z.infer<typeof docxCapabilitySchema>;
+
+export const docxExportErrorCodeSchema = z.enum([
+  "INVALID_DOCX_REQUEST",
+  "INVALID_EXPORT_CONFIG",
+  "INVALID_FILE_NAME",
+  "INVALID_MARKDOWN",
+  "MARKDOWN_TOO_LARGE",
+  "INVALID_IMAGE_RESOURCES",
+  "IMAGE_RESOURCES_TOO_LARGE",
+  "THEME_NOT_FOUND",
+  "DOCX_RUNTIME_NOT_FOUND",
+  "DOCX_RUNTIME_VERSION_MISMATCH",
+  "DOCX_RUNTIME_NOT_EXECUTABLE",
+  "DOCX_RUNTIME_PROBE_TIMEOUT",
+  "DOCX_QUEUE_FULL",
+  "DOCX_RENDER_TIMEOUT",
+  "DOCX_GENERATION_FAILED",
+  "DOCX_OUTPUT_INVALID"
+]);
+
+export type DocxExportErrorCode = z.infer<
+  typeof docxExportErrorCodeSchema
+>;
+
+export const docxExportErrorResponseSchema = z.object({
+  error: docxExportErrorCodeSchema,
+  message: z.string().min(1).max(1_000),
+  retryable: z.boolean().default(false)
+});
+
+export type DocxExportErrorResponse = z.infer<
+  typeof docxExportErrorResponseSchema
+>;
+
+export interface DocxGenerationTimings {
+  probeMs: number;
+  prepareMs: number;
+  mediaMs: number;
+  referenceMs: number;
+  pandocMs: number;
+  validationMs: number;
+  totalMs: number;
+}
+
+export interface DocxExportDiagnostics {
+  warnings: string[];
+  echartsErrors: string[];
+  mermaidErrors: string[];
+}
+
+export interface DocxExportResult {
+  docx: Uint8Array;
+  fileName: string;
+  diagnostics: DocxExportDiagnostics;
+  timings: DocxGenerationTimings;
+}
+
+export function createDocxFileName(fileName: unknown) {
+  const source =
+    typeof fileName === "string"
+      ? fileName.split(/[\\/]/).at(-1) ?? ""
+      : "";
+  const stem = source
+    .replace(/\.(?:md|markdown|docx)$/i, "")
+    .replace(/[<>:"/\\|?*\u0000-\u001f]/g, "_")
+    .replace(/[.\s]+$/g, "")
+    .trim();
+  return `${stem || "文档"}${DOCX_FILE_EXTENSION}`;
+}
@@ -1,4 +1,5 @@
 export * from "./document.js";
+export * from "./docx.js";
 export * from "./document-profile.js";
 export * from "./document-link.js";
 export * from "./export-config.js";
@@ -0,0 +1,114 @@
+import { describe, expect, it } from "vitest";
+import {
+  DOCX_MIME_TYPE,
+  DOCX_PANDOC_VERSION,
+  MAXIMUM_DOCX_MARKDOWN_LENGTH,
+  createDocxFileName,
+  defaultExportConfig,
+  docxCapabilitySchema,
+  docxExportErrorResponseSchema,
+  docxExportRequestSchema
+} from "../src/index.js";
+
+describe("DOCX 共享协议", () => {
+  it("解析跨端导出请求并补齐稳定默认值", () => {
+    expect(
+      docxExportRequestSchema.parse({
+        markdown: "# 文档",
+        exportConfig: defaultExportConfig
+      })
+    ).toEqual({
+      markdown: "# 文档",
+      fileName: "文档.md",
+      language: "zh-CN",
+      resources: [],
+      exportConfig: defaultExportConfig
+    });
+  });
+
+  it("校验导出配置与请求资源结构", () => {
+    expect(
+      docxExportRequestSchema.safeParse({
+        markdown: "# 文档",
+        exportConfig: {}
+      }).success
+    ).toBe(false);
+    expect(
+      docxExportRequestSchema.safeParse({
+        markdown: "# 文档",
+        resources: [{ path: "", data: "" }],
+        exportConfig: defaultExportConfig
+      }).success
+    ).toBe(false);
+  });
+
+  it("拒绝超过共享协议上限的 Markdown", () => {
+    expect(
+      docxExportRequestSchema.safeParse({
+        markdown: "x".repeat(MAXIMUM_DOCX_MARKDOWN_LENGTH + 1),
+        exportConfig: defaultExportConfig
+      }).success
+    ).toBe(false);
+  });
+
+  it("生成跨平台安全的 DOCX 文件名", () => {
+    expect(createDocxFileName("C:\\资料\\项目报告.markdown")).toBe(
+      "项目报告.docx"
+    );
+    expect(createDocxFileName("../../非法:*?.md")).toBe("非法___.docx");
+    expect(createDocxFileName("   ")).toBe("文档.docx");
+    expect(createDocxFileName(undefined)).toBe("文档.docx");
+  });
+
+  it("只将精确版本识别为可用能力", () => {
+    expect(
+      docxCapabilitySchema.parse({
+        format: "docx",
+        status: "available",
+        expectedVersion: DOCX_PANDOC_VERSION,
+        detectedVersion: DOCX_PANDOC_VERSION
+      })
+    ).toEqual({
+      format: "docx",
+      status: "available",
+      expectedVersion: "3.9.0.2",
+      detectedVersion: "3.9.0.2"
+    });
+    expect(
+      docxCapabilitySchema.safeParse({
+        format: "docx",
+        status: "available",
+        expectedVersion: DOCX_PANDOC_VERSION,
+        detectedVersion: "3.8"
+      }).success
+    ).toBe(false);
+    expect(
+      docxCapabilitySchema.safeParse({
+        format: "docx",
+        status: "version-mismatch",
+        expectedVersion: DOCX_PANDOC_VERSION,
+        detectedVersion: "3.8",
+        message: "Pandoc 版本不匹配"
+      }).success
+    ).toBe(true);
+  });
+
+  it("暴露标准 DOCX MIME", () => {
+    expect(DOCX_MIME_TYPE).toBe(
+      "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
+    );
+  });
+
+  it("提供可跨 HTTP 与 IPC 传递的错误响应", () => {
+    expect(
+      docxExportErrorResponseSchema.parse({
+        error: "DOCX_RUNTIME_NOT_FOUND",
+        message: "未找到 Pandoc"
+      })
+    ).toEqual({
+      error: "DOCX_RUNTIME_NOT_FOUND",
+      message: "未找到 Pandoc",
+      retryable: false
+    });
+  });
+});