fix(backend): r3 七项缺陷修复——图片预算/neo4j normalized/超时分流/mineru 加固/检索降级/DOCX 同源/docgen 异步任务化

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs/API.md

@@ -164,7 +164,16 @@ event: raw        data: {<无法分类的上游原始 JSON>}
 
 ### POST /api/qa/search
 
-请求同 `/chat` 但 BFF **强制 `use_llm:false`**。响应：归一化响应但 `answer` 为空、`mode:"search"`。读超时 180s（实测单次检索约 92s，主要耗时在 native graph chain），不重试。
+请求同 `/chat` 但 BFF **强制 `use_llm:false` + `native_chain_enabled:false`**（缺陷 #28，2026-09-10：检索模式关闭图链，只走 Qdrant 向量检索——与 sse_relay 的 evidence_first 先例同法）。响应：归一化响应但 `answer` 为空、`mode:"search"`。
+
+超时降级（缺陷 #28）：上游读超时（180s 上限）时返回 **200 降级体**（不返回错误信封）：
+
+```json
+{ "mode": "search", "answer": "", "sources": [], "source_count": 0,
+  "degraded": true, "reason": "TIMEOUT" }
+```
+
+正常空结果（未超时但无命中）`degraded:false`——前端据此区分「检索超时」与「没有检索到有效回答」。
 
 ---
 
@@ -476,3 +485,48 @@ MinerU 不可用：502 降级信封，message 说明原因。读超时 600s。
 
 请求体新增 BFF 契约字段 `session_id`（BFF 剥离后注入上游 history/capabilities，
 不达 QA）。不传 session_id 时行为与既往一致。
+
+
+## 12. 文档生成 docgen（缺陷 #52，2026-09-10 起异步任务化）
+
+### POST /api/docgen/generate → 202
+
+请求体同现状（`description` / `session_id?` / `library_ids[]?` / `template_id?`）。
+快路径校验（description/意图护栏/配额/模板检索/资料快照）不变，通过后立即返回：
+
+```json
+{ "ok": true, "task_id": "<uuid4>", "status": "queued" }
+```
+
+生成主体在后台任务执行（并发上限 `DOCGEN_MAX_CONCURRENT_TASKS` 默认 2；
+满并发 → 429 `BUSY` 信封）。
+
+### GET /api/docgen/tasks/{task_id} → 200
+
+```json
+{ "ok": true, "task": {
+    "id": "<uuid4>",
+    "session_id": "s1",
+    "status": "queued|running|done|error",
+    "progress": [ { "section": 1, "title": "…", "state": "done|running|pending" } ],
+    "artifact": { "id": "…", "title": "…", "template_name": "…", "template_key": "…",
+                  "has_html": true, "letterhead": "…", "file_name": "…" },
+    "error": null } }
+```
+
+- `artifact`：done 时回填制品详情；其余状态为 null。
+- `error`：失败时中文可读文案（DOCGEN_LLM_* 不齐时写明缺哪个键）；
+  服务重启中断的 running/queued 任务启动时置 error「服务重启，任务中断，请重试」。
+- 任务不存在 → 404 `NOT_FOUND`。
+
+### GET /api/docgen/tasks?session_id={sid} → 200
+
+`{ "ok": true, "tasks": [ <task 对象列表，created_at 倒序，上限 100> ] }`。
+
+### POST /api/docgen/artifacts/{id}/export 的 docx 分支（缺陷 #47a）
+
+`format:"docx"` 与 PDF 同构：取 template_key/frozen_css/letterhead/template_name，
+bioflow 走 `render_bioflow_report`、其余 `render_html` 产 HTML →
+`docx_from_html_document`（红头红字居中 22pt 黑体、h1-h3 黑体分级、表格 Table
+Grid+表头灰底、图片内嵌失败落 alt）。转换异常回退 `md2docx` 旧路径
+（env `DOCGEN_DOCX_VIA_HTML=1` 默认开，置 0 直接走旧路径，记 warning 日志）。