fix(export): 为函数图像与导出产物增加资源上限

针对 PR 审阅「函数数量没有限制，可能生成数百 MB 的 SVG」： - parser: 单块 function-plot 表达式上限 _MAX_EXPRESSIONS=16，超限整块回退 - html: 单篇文档函数图像上限 _MAX_FUNCTION_PLOTS=16，超出回退源码占位 - service: 输入源 MAX_MARKDOWN_CHARS、产物 MAX_EXPORT_BYTES，超限分别拒绝创建或标记 failed（EXPORT_OUTPUT_TOO_LARGE） - 补充 4 条回归测试与文档说明 Co-Authored-By: Claude Code <noreply@anthropic.com>
2026-09-05 23:31:53 +08:00
parent b87f94551b
commit 124024a547
7 changed files with 121 additions and 4 deletions
@@ -1,6 +1,6 @@
 # Export 开发说明

-> 所属模块：Export Service（后端，负责人 yxx）。本次交付「多格式文档导出」第一步：Markdown → HTML 的完整生命周期；PDF/DOCX 与函数图像静态渲染在后续 PR 补齐。契约对应 [第二阶段接口契约 §10](../contracts/第二阶段接口契约-开发版.md)。
+> 所属模块：Export Service（后端，负责人 yxx）。交付「多格式文档导出」：Markdown → HTML 的完整生命周期与 function-plot 静态 SVG 渲染；PDF/DOCX 在后续 PR 补齐。契约对应 [第二阶段接口契约 §10](../contracts/第二阶段接口契约-开发版.md)。

 ## 定位

@@ -41,7 +41,7 @@ fenced code 按语言分流：`mermaid` → `mermaid` 节点、`function_plot`/`

 ## HtmlExporter

-递归渲染 Document AST 为完整 HTML5 文档（`<!doctype html>` + `<head>` 内嵌基础 CSS + `<body>`），标题/正文/元信息文本一律 `html.escape`。`mermaid` 与 `function_plot` 无法静态表达，渲染为占位 `<pre class="mermaid">`/`<pre class="function-plot">` 并记 warning，不静默丢失；`code_theme` 仅作为代码容器 class，不引入 JS 高亮库。无法表示的节点统一 `warnings.append(...)` 跳过。
+递归渲染 Document AST 为完整 HTML5 文档（`<!doctype html>` + `<head>` 内嵌基础 CSS + `<body>`），标题/正文/元信息文本一律 `html.escape`。`function_plot` 解析为静态 SVG 内嵌（解析/渲染失败或超限时回退 `<pre class="function-plot">` 占位并记 warning），`mermaid` 无法静态表达，渲染为占位 `<pre class="mermaid">` 并记 warning，均不静默丢失；`code_theme` 仅作为代码容器 class，不引入 JS 高亮库。无法表示的节点统一 `warnings.append(...)` 跳过。

 ## 运行生命周期

@@ -56,6 +56,15 @@ fenced code 按语言分流：`mermaid` → `mermaid` 节点、`function_plot`/`

 产物写入 `settings.exports_path`（默认 `backend/data/exports/`，可通过 `APP_EXPORTS_PATH` 覆盖，已加入 `.gitignore`），文件名为 `{job_id}.html`，下载 `Content-Disposition` 用 `_safe_download_name` 清洗标题得到。`ExportFile` 记录 `sha256`、`size` 与 `expires_at`（`completed_at + 24h`），过期返回 `EXPORT_FILE_EXPIRED`（410）。

+## 资源上限
+
+为防止超大输入或海量函数图像耗尽内存/线程，导出链路内置以下上限：
+
+- 输入源（`note` 与 `markdown`）统一限制 `MAX_MARKDOWN_CHARS = 200_000` 字符，超限返回 `EXPORT_OPTIONS_INVALID`。
+- 单个 `function-plot` 图块最多 16 条表达式，超限整块回退占位并记结构化诊断 `FUNCTION_PLOT_TOO_MANY_EXPRESSIONS`。
+- 单篇文档最多 16 个函数图像，超出部分回退占位并记 warning。
+- 最终产物大小上限 `MAX_EXPORT_BYTES = 20 MB`，超限任务标记 failed 并返回 `EXPORT_OUTPUT_TOO_LARGE`。
+
 ## 错误码

 ```text
@@ -67,6 +76,7 @@ EXPORT_UNSUPPORTED_CONTENT   422
 EXPORT_JOB_NOT_FOUND         404
 EXPORT_FILE_EXPIRED          410
 EXPORT_CAPACITY_EXCEEDED     429
+EXPORT_OUTPUT_TOO_LARGE      413
 ```

 ## 测试
@@ -81,5 +91,5 @@ uv run pytest -q
 ## 范围外（后续 PR）

 - PDF / DOCX 导出（`python-docx` 等底层库在 PoC 后冻结，封装在 Exporter Adapter 内）。
- 函数图像绘制（FunctionPlot 结构化模型 + 白名单表达式解析器 + SVG 静态渲染，契约 §10.4/§12）。
+- 函数图像交互预览与缩放（前端 JS Renderer 负责，后端仅提供静态 SVG）。
 - 代码语法高亮（当前仅 CSS class 占位）。