后端设计治理：批次 0-4 全部完成（安全/部署/一致性/结构/架构）

按 ROADMAP §3.1 治理批次推进的后端设计审查整改：

- 批次 0（安全）：/api/status/{task_id} 补 JWT 鉴权与任务归属校验；
  pythonocc_available 真实探测；bcrypt 超 72 字节显式拒绝；
  SECRET_KEY/RUSTFS_* 惰性校验，代码侧弱默认移除
- 批次 1（部署正确性）：主处理链路改走 RustFS（分派入参 stp_file_id 化，
  worker 按 object_key 下载）；AUTO_MIGRATE 开关 + 迁移目录 alembic/→migrations/
  修复包遮蔽（自动迁移此前从未真正生效）；OCC 镜像改 conda 原生执行 +
  基础镜像 tag 锁定；compose 关键项改 ${VAR:?} 强制显式配置
- 批次 2（任务一致性）：删除 Redis 进程内存回退，PG 为任务状态单一事实源；
  批量元数据入库（processing_tasks.batch_id，迁移 a3f8c2d91e47）；
  型腔失败任务标 failed 不再静默 completed；事务边界收口
  （数据本体写 flush-only、失败先回滚再置 failed、进度更新保留即时 commit）
- 批次 3（API 与代码结构）：592 行 advanced_router 拆为 design/cost/machining/
  export 四子路由，请求体全量 Pydantic 化；ROUTE_MODULES + route_registry
  （/api/health 呈现 degraded，DEBUG fail fast）；纯计算端点统一 to_thread；
  StorageIntegrationService 按职责三拆；MAX_FILE_SIZE 接线生效、
  celery 复用 Settings.redis_url；管理员重置密码改 JSON body（端到端断裂修复）；
  openapi.json 重导出（76 paths）+ 前端 gen:api
- 批次 4（架构演进）：共享 ORM 按模块拆分（shared/models/base.py + identity.py、
  moldinsight/models/、inventory/models/，删除三条无使用方的跨模块
  relationship，跨模块桥接收敛为裸 FK 硬规则，无兼容 facade）；
  OCC executor 重建补 cancel_futures=True（消除旧队列被慢恢复线程
  并行消化的数据竞争）；OCC 吞吐方案设计先行
  （docs/topics/performance/OCC_THROUGHPUT.md）；顺手清偿 D15
  （vite.config.ts 未用参数致 npm run build 失败）

测试基线：125 passed, 2 skipped（pytest + sqlite+aiosqlite；归属边界、
路由契约、配置治理、鉴权回归等随批新增）
文档同步：STATUS / TECH_DEBT / ROADMAP / ARCHITECTURE / API_CONTRACT /
OPERATIONS / AGENTS

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

docs/TECH_DEBT.md

@@ -55,29 +55,35 @@
 - 持久化事务边界收口：数据本体分阶段原子提交、失败先回滚再置 failed（原 D9）
 - D11（HTML 双写双读）本批未动：正确性已由共享卷兜底，RustFS 单一来源留待后续批次
 
+### 2.7 API 与代码结构（2026-09-17，批次 3）
+- `advanced_router` 按职责拆为 design / cost / machining / export 四个子路由，端点路径不变，请求体全量 Pydantic 化（原 D1）
+- 路由装载失败显式化：`ROUTE_MODULES` 清单 + route_registry，失败经 `/api/health` 呈现 degraded（含真实 pythonocc 探测），DEBUG 下 fail fast
+- 纯 Python 重计算端点（设计/加工/CAM 打包）统一 `asyncio.to_thread` 投放线程池，不再阻塞事件循环；OCC 操作仍走单线程 executor（D10 不变，批次 4）
+- `StorageIntegrationService`（867 行）按职责拆为 TaskStorage / AnalysisStorage / FileHistory 三服务；无调用方的 `log_user_activity` 死代码删除
+- 配置治理收尾：`MAX_FILE_SIZE` 接线生效、celery_app 复用 `Settings.redis_url`（原 D14）
+- 连带修复：管理员重置密码改 JSON body（原裸 str 参数被解析为 query param，前端发 body 必 422，功能端到端断裂）；Dockerfile.celery 的 FROM tag 与 compose/build.sh 实际构建的 `gemold-backend:latest` 对齐（此前干净环境 celery 镜像必构建失败）
+- 接口变更三件套随批完成：openapi.json 重导出（76 paths）+ 前端 `gen:api`
+
+### 2.8 架构演进（2026-09-17，批次 4）
+- 共享 ORM 按模块拆分（原 D3 主体）：891 行 `shared/models/database.py`（31 模型类三类同居）拆为 `shared/models/base.py`（唯一 Base + 归属约定）/ `shared/models/identity.py`（7 表）/ `moldinsight/models/`（9 表）/ `inventory/models/`（catalog/warehouse/trading/finance 15 表）；**三条跨模块 ORM relationship（`User.stp_files`、`STPFile.user`、`STPFile.product`）经全仓核实均无使用方，直接删除**——跨模块桥接收敛为裸 FK 硬规则（ARCHITECTURE §5.1），单模块部署不再依赖另一侧模型注册；约 45 处 import 全量改写，无兼容 facade；全量注册点收敛为 migrations/env.py 与 tests/conftest.py；零调用方的死方法 `db_manager.create_tables` 一并删除（拆分后会静默建残缺 schema）
+- OCC 泄漏治理 + 吞吐方案设计先行（原 D10）：`_reset_occ_executor` 补 `cancel_futures=True`——不止卫生问题：旧实现下"慢恢复"的旧线程会继续消化旧队列，与新 executor **并发操作非线程安全的 OCC**（数据竞争）；吞吐路线定稿于 [topics/performance/OCC_THROUGHPUT.md](topics/performance/OCC_THROUGHPUT.md)（短期 A：celery prefork 伸缩 + max-tasks-per-child 兜底；中期 B：run_occ 接口进程化 + kill-on-timeout 根治）
+- 归属边界回归测试：[tests/test_model_ownership.py](../tests/test_model_ownership.py)（31 表全量注册、单模块独立 mapper 配置、旧模块无 facade）
+
 详细历史过程保留在原始技术债文档中，后续将转入归档。
 
 ---
 
 ## 3. 当前活跃技术债
 
-### D1. `advanced_router` 过大，职责混杂
+### D1. `advanced_router` 过大，职责混杂 —— 已清偿（2026-09-17，批次 3）
 
-现状：
-- 导出、估算、设计/分析相关接口仍混在同一个 router 中
-- 请求体仍有较多手动解析逻辑
+修复内容：
+- 592 行的 advanced_router 按职责拆为四个子路由，端点路径全部不变：[design_router.py](../src/moldinsight/api/design_router.py)（布局/冷浇/模架/倒扣）、[cost_router.py](../src/moldinsight/api/cost_router.py)、[machining_router.py](../src/moldinsight/api/machining_router.py)（CAM/碰撞/刀路/电极/仿真）、[export_router.py](../src/moldinsight/api/export_router.py)（导出/下载/建议）
+- 全部请求体改 Pydantic 模型（`request.json()` 手动解析退役），校验失败统一 422；`_get_cached_import` 上提为 [core_modules.py](../src/moldinsight/api/core_modules.py) 共用
+- 契约测试：[tests/test_advanced_split_contract.py](../tests/test_advanced_split_contract.py)（路径不丢、鉴权不丢、422 语义、纯计算端点冒烟）
+- openapi.json 重导出 + 前端 `gen:api`（接口变更三件套随批完成）
 
-影响：
-- 路由边界不清晰
-- OpenAPI 可读性差
-- 接口参数校验不统一
-- 后续继续扩展时维护成本高
-
-建议：
-- 拆分为 export / design / cost 等子路由
-- 高优先级请求体改为 Pydantic 模型
-
-优先级：**P1**
+~~原现状 / 影响~~：导出/估算/设计接口混在单文件，边界不清晰、OpenAPI 可读性差、参数校验不统一。
 
 ### D2. 铝价模拟数据未显式标注来源
 
@@ -93,21 +99,17 @@
 
 优先级：**P2**
 
-### D3. shared/platform 边界仍需继续收敛
+### D3. shared/platform 边界仍需继续收敛 —— ORM 归属已清偿（2026-09-17，批次 4）
 
-现状：
-- `shared` 同时承担平台基础能力与部分历史耦合职责
-- 共享 ORM 与 app factory 仍是主要耦合点
+已完成部分：
+- 共享 ORM（原最强耦合点）按模块拆分：base / identity（shared）+ moldinsight/models + inventory/models；跨模块只允许裸 FK，单模块部署 mapper 可独立配置（详见 §2.8 与 [ARCHITECTURE.md](ARCHITECTURE.md) §6.1）
+- 旧 `shared/models/database.py` 物理删除，无兼容 facade；归属边界由 [tests/test_model_ownership.py](../tests/test_model_ownership.py) 锁定
 
-影响：
-- 模块边界认知成本较高
-- 新增逻辑容易继续堆入 shared
+仍保留的收敛方向（低优先级，随实际重构推进）：
+- [app_factory.py](../src/shared/app_factory.py) 组合职责偏重（ARCHITECTURE §6.2）
+- identity / platform 的边界语义（ROADMAP §2.1）
 
-建议：
-- 继续从文档、目录语义、职责边界上推进收敛
-- 在后续实际重构中优先避免把业务逻辑继续沉入 shared
-
-优先级：**P2**
+优先级：**P3**（剩余部分）
 
 ### D4. 文档现状 / 规划 / 历史混放
 
@@ -171,19 +173,17 @@
 
 ~~原现状 / 影响~~：各存储方法内部自行 commit，型腔保存失败留半成品数据且任务仍 completed。
 
-### D10. OCC 全局单线程串行 + 超时重建泄漏线程
+### D10. OCC 全局单线程串行 + 超时重建泄漏线程 —— 泄漏治理已落地，吞吐方案设计先行（2026-09-17，批次 4）
 
-现状：
-- 所有 OCC 操作经 `max_workers=1` executor 串行（[processing_service.py](../src/moldinsight/services/processing_service.py)），celery 并发无法扩展 OCC 吞吐
-- 超时重建 executor 每次泄漏 1 个线程，长期运行只涨不降
+已完成：
+- `_reset_occ_executor` 补 `cancel_futures=True`：排队任务随重建丢弃——旧实现下"慢恢复"的旧线程会继续消化旧队列，与新 executor 并发操作非线程安全的 OCC；修复后残留收敛为"运行中线程滞留 1 个"（C++ 栈 Python 层不可杀，属客观边界）
+- 吞吐与隔离方案定稿：[topics/performance/OCC_THROUGHPUT.md](topics/performance/OCC_THROUGHPUT.md)——短期方案 A（celery `--concurrency` 伸缩 + `--max-tasks-per-child` 进程回收兜底，零新代码，启动参数见 [OPERATIONS.md](OPERATIONS.md) §3）；中期方案 B（`run_occ` 改操作名+payload 契约、常驻 OCC 进程池 kill-on-timeout 根治泄漏，待独立批次）
 
-影响：
-- 一个长耗时型腔生成阻塞全部几何处理；线程随故障累积
+保留为已知约束（非待修缺陷）：
+- 单进程内 OCC 串行是正确性要求（OCC 非线程安全），吞吐扩展走多进程（方案 A/B）
+- 线程级超时的滞留线程由进程边界回收，根治依赖方案 B 落地
 
-建议：
-- 记录吞吐上限为已知约束；线程泄漏治理方案设计先行（见 [ROADMAP.md](ROADMAP.md) §3.1 批次 4）
-
-优先级：**P2**
+优先级：**P3**（中期方案 B 实施前维持观察）
 
 ### D11. HTML 报告本地磁盘与 RustFS 双写双读
 
@@ -216,20 +216,21 @@
 
 优先级：**P2**（剩余锁文件部分）
 
-### D14. 配置漂移：弱默认 / 死配置 / 重复解析
+### D14. 配置漂移：弱默认 / 死配置 / 重复解析 —— 已清偿（2026-09-16 ~ 09-17，批次 1 / 3）
 
-现状：
-- ~~RUSTFS_* 弱默认~~（2026-09-16 代码侧已去除）；~~compose 侧 SECRET_KEY / ADMIN_PASSWORD 弱默认~~（2026-09-16 已去除：改用 `${VAR:?}` 强制显式配置，`create_admin_user` 对空 ADMIN_PASSWORD 显式报错）
-- MAX_FILE_SIZE 配置项未被使用（[file_handler.py](../src/shared/utils/file_handler.py) 硬编码 50MB）
-- [celery_app.py](../src/celery_app.py) 重新 load_dotenv 并手拼 REDIS URL，与 settings 两份实现
+修复内容：
+- ~~RUSTFS_* 弱默认~~（批次 0 代码侧去除）；~~compose 侧 SECRET_KEY / ADMIN_PASSWORD 弱默认~~（批次 1 改 `${VAR:?}` 强制显式配置）
+- ~~MAX_FILE_SIZE 死配置~~（批次 3）：upload/batch 路由的 `FileHandler` 接 `settings.UPLOAD_DIR / settings.MAX_FILE_SIZE`（此前处理器硬编码 50MB；接线后默认上限变为 100MB，以 .env 为准）
+- ~~celery_app 重复拼装~~（批次 3）：删除自行 load_dotenv + 手拼 REDIS URL，broker/backend 复用 `Settings.redis_url`（新增 property，连接串唯一拼装点）
 
-影响：
-- 违背"关键项不兜底"硬约束；配置行为与文档不一致
+优先级：已清偿
 
-建议：
-- 去掉弱默认、对齐或删除死配置、celery_app 复用 settings
+### D15. 前端 `npm run build` 因既有 TS 错误失败（批次 3 连带发现）—— 已清偿（2026-09-17，批次 4）
 
-优先级：**P2**
+修复内容：
+- [vite.config.ts](../frontend/vite.config.ts) 删除未使用的回调参数 `mode`（TS6133 源头，一行修复）；`vue-tsc -b` 实测通过，生产构建链路恢复
+
+~~原现状 / 影响~~：`vue-tsc -b`（`npm run build` 的类型检查步）因既有 TS6133 失败，前端无法出生产包（与批次 3 改动无关的既有问题）。
 
 ---
 
@@ -238,14 +239,14 @@
 > 注：2026-09-15 后端设计审查后，治理**执行顺序**以 [ROADMAP.md](ROADMAP.md) §3.1 批次计划为准（批次 0–4）；D5–D14 的批次归属见该表。本节保留原有优先项作为补充说明。
 
 ### 第一优先级
-1. `advanced_router` 拆分
-2. 高优先级接口补 Pydantic 请求模型
+1. ~~`advanced_router` 拆分~~（2026-09-17 批次 3 完成，见 D1）
+2. ~~高优先级接口补 Pydantic 请求模型~~（2026-09-17 批次 3 完成）
 3. 文档主骨架收口并减少重复说明
 
 ### 第二优先级
 4. 铝价模拟数据来源显式化
 5. 部署历史文档归档
-6. shared/platform 语义继续收敛
+6. shared/platform 语义继续收敛（共享 ORM 归属已于批次 4 清偿，剩余为 app_factory 组合职责等，见 D3）
 
 ---