批次4后续专项完成：D11清偿 + OCC方案B实施 + 部署参数 + D2诚实标注 + CI门禁

① D11 HTML 报告 RustFS 单源化（TECH_DEBT P2 清偿）：可视化产物写任务临时目录后
   裸传报告键 html/reports/{filename}（文件名寻址），/html StaticFiles 挂载删除，
   新增 html_report_router 根路径代理（报告键→遗留 JSON 包装→本地卷兜底→404，
   防穿越）；URL 形状 /html/{filename} 不变，持久化引用零迁移；celery 摘除
   html_data 卷，镜像不再烤入陈旧报告；顺带删除 get_stp_file_with_data 死数据块
② OCC 方案 B（D10 清偿）：run_occ(op_name, payload) 契约 + 常驻工作进程池
   （occ_process_pool + occ_worker 操作注册表），超时/崩溃 terminate 换新补位、
   任务级超时 recover 整体重建，残留线程泄漏根治；TopoDS 不跨进程（generate_cavity
   分模 + 方案 STEP 持久化全在子进程内，返回 export_manifest）；删除内存形状缓存链、
   CADExporter.export_mold_results、shape_loader（→ stp_materializer）
③ OCC 方案 A 部署参数：CELERY_CONCURRENCY / CELERY_MAX_TASKS_PER_CHILD 进
   Dockerfile.celery + compose + .env.example
④ D2 诚实标注：铝价响应带 source: "simulated"，前端按来源渲染标注（原硬编码
   "上海期货交易所"属虚假声明），死代码 getAluminumPrice 删除
⑤ CI 门禁：.gitea/workflows/ci.yml 三 job（pytest / 前端构建含 vue-tsc /
   openapi 漂移检测）

接口变更三件套随批完成（openapi 76→77 paths + gen:api + 前端构建通过；方案 B
接口面零变化）。测试基线 143 passed, 0 skipped（新增 16 项）。文档六处同步。

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

docs/topics/performance/OCC_THROUGHPUT.md

@@ -10,9 +10,10 @@
 
 ### 1.1 运行时事实
 
-- 所有 OCC 操作（STEP 解析 / 布尔运算 / 三角化 / 倒扣检测等）统一经 [processing_service.py](../../../src/moldinsight/services/processing_service.py) 的 `run_occ` 投入 **进程内 `ThreadPoolExecutor(max_workers=1)`** 串行执行——OCC 非线程安全，串行是正确性要求，不是实现偷懒。
-- Celery worker 为 prefork 模式，`processing_service` 是模块级单例：**每个 worker 子进程各持一个串行 OCC 通道**。因此 OCC 并行度 = worker 子进程数，与 web 进程数无关（web 侧 `run_occ` 仅服务于轻量同步调用，如倒扣检测）。
-- 型腔生成超时后 `_reset_occ_executor` 重建 executor；已在运行的 C++ 线程在 Python 层**不可杀**，每次超时滞留 1 个线程（2026-09-17 起排队任务随 `cancel_futures=True` 丢弃，见 §4）。
+- 所有 OCC 操作（STEP 解析 / 布尔运算 / 三角化 / 倒扣检测 / STEP 转换等）统一经 [processing_service.py](../../../src/moldinsight/services/processing_service.py) 的 `run_occ(op_name, payload)` 投入 **常驻 OCC 工作进程池**（[occ_process_pool.py](../../../src/moldinsight/services/occ_process_pool.py)，默认 1 进程 = 1 串行通道）——OCC 非线程安全，通道内串行是正确性要求，不是实现偷懒。
+- 操作在 [occ_worker.py](../../../src/moldinsight/core/occ_worker.py) 以注册表形式实现（parse_stp / generate_mesh / generate_cavity / analyze_mold_design / detect_undercuts / convert_component_step 等）；输入输出全部是**文件路径 + 普通字典**，TopoDS_Shape 不跨进程传输（方案 B 硬约束，见 §1.2）。
+- Celery worker 为 prefork 模式，`processing_service` 是模块级单例：**每个 worker 子进程各持一个常驻 OCC 工作进程**。因此 OCC 并行度 = worker 子进程数，与 web 进程数无关（web 侧 `run_occ` 仅服务于轻量同步调用，如倒扣检测）。
+- 超时/崩溃 = `terminate()` 该工作进程并换新补位——进程边界干净回收，无线程滞留。
 
 ### 1.2 硬约束（决定方案边界）
 
@@ -61,10 +62,25 @@
 
 | 阶段 | 动作 | 状态 |
 |---|---|---|
-| 短期 | 方案 A：`--concurrency` 伸缩 + `--max-tasks-per-child` 兜底回收；`cancel_futures=True` 修复重建并发风险 | ✅ 代码侧 2026-09-17 完成；部署参数随下次 compose/镜像评审落地 |
-| 中期 | 方案 B：`run_occ(op_name, payload)` 接口演进 + 常驻进程池，kill-on-timeout 根治泄漏 | 待排期（独立批次，工作量集中在调用点迁移与序列化设计） |
+| 短期 | 方案 A：`--concurrency` 伸缩 + `--max-tasks-per-child` 兜底回收；`cancel_futures=True` 修复重建并发风险 | ✅ 部署参数 2026-09-18 落地（`CELERY_CONCURRENCY` / `CELERY_MAX_TASKS_PER_CHILD` 进 Dockerfile.celery + compose + .env.example） |
+| 中期 | 方案 B：`run_occ(op_name, payload)` 接口演进 + 常驻进程池，kill-on-timeout 根治泄漏 | ✅ 2026-09-18 实施完成（见 §5；回归测试 [tests/test_occ_process_pool.py](../../../tests/test_occ_process_pool.py)） |
 | 长期 | 方案 C：sidecar，仅在出现独立伸缩需求时启动 | 暂不启动 |
 
-## 4. 本次已落地的缓解（2026-09-17，批次 4）
+## 4. 已落地的缓解（2026-09-17，批次 4）
 
 `_reset_occ_executor` 的 `shutdown(wait=False)` 补 `cancel_futures=True`。这不只是卫生问题：旧实现下旧 executor 的**排队任务不会消失**——若挂死线程后来"慢恢复"，旧线程会继续消化旧队列，与新 executor **并发操作非线程安全的 OCC**（数据竞争 / 崩溃风险）。补参后排队任务即被丢弃，残留问题收敛为"运行中线程滞留 1 个"，由方案 A 的进程回收兜底。
+
+## 5. 方案 B 实施记录（2026-09-18）
+
+**接口**：`run_occ(fn, *args)` → `run_occ(op_name, payload)`；执行器由进程内线程池替换为常驻进程池。
+
+- **新增** [occ_process_pool.py](../../../src/moldinsight/services/occ_process_pool.py)：`OccProcessPool`（默认 size=1）。每个 `_OccWorker` 是一个 spawn 出的常驻子进程 + 双工管道 + 独立 `asyncio.Lock`（通道串行）；阻塞收发经 `asyncio.to_thread` 不卡事件循环。操作超时或进程死亡 → `terminate()` + 换新补位；任务级整体超时（`process_file_with_storage` 外层 wait_for）→ `recover()` 整体重建。`shutdown()` 供应用退出/测试清理。
+- **新增** [occ_worker.py](../../../src/moldinsight/core/occ_worker.py)：操作注册表 + `worker_main` 消息循环。OCC 模块在 handler 内惰性导入（父进程 pip 环境无 OCC 也可 import），进程内单例缓存（parser/planner/analyzer/mesh_gen 等）。全部操作输入输出为**文件路径 + 普通字典**，TopoDS 不跨进程。
+- **调用点迁移**（processing_service）：
+  - `parse_stp` = 原 load_step_file + analyze_geometry 两步合一（形状在子进程内即生即用）
+  - `generate_mesh` / `analyze_mold_design` / `detect_undercuts` / `convert_component_step` 同名对位
+  - `generate_cavity` = 分模 + 方案形状持久化 STEP 导出全在子进程内；`_export_shapes`（TopoDS）不再回主进程，返回 export_manifest（与旧 `_persist_step_exports` 结构一致，主进程原样存 export_artifacts）
+  - 旧 `_cache_export_shapes` / `get_export_shapes` / `_persist_step_exports` / `_export_shapes_cache` 及线程 executor / `_reset_occ_executor` 全部删除（跨进程本就不存在内存形状缓存，export_router 相应移除 `export_mold_results` 内存分支）
+  - [shape_loader.py](../../../src/moldinsight/services/shape_loader.py) → [stp_materializer.py](../../../src/moldinsight/services/stp_materializer.py)：只把 STP 原件落盘临时文件，OCC 解析交给子进程操作
+- **成本确认**：每个 spawn 子进程首次操作需 import OCC（秒级）；进程常驻后后续操作复用缓存实例。每个操作从 STP 原件重新加载形状（STEP 重载成本，见 §1.2）——原线程方案跨步骤共享 shape 的内存优势让位于进程隔离，符合方案 B 设计取舍。
+- **测试**：[tests/test_occ_process_pool.py](../../../tests/test_occ_process_pool.py)（OCC-gated，6 例）：spawn+管道往返 / 未知操作错误回传 / 子进程异常浮出 / 超时换新补位 / 真实盒体 STP 解析端到端 / generate_cavity 分模+STEP 落盘端到端。