优化

docs/API_CONTRACT.md

@@ -44,8 +44,8 @@
 | 域 | 端点 | 文件 |
 |---|---|---|
 | 上传 | `/api/upload` | upload_router.py |
-| 批量分析 | `/api/batch-upload`、`/api/batch/{batch_id}` | batch_router.py |
-| 任务状态 | `/api/status/{task_id}` | task_router.py |
+| 批量分析 | `/api/batch-upload`、`/api/batch/{batch_id}`（聚合状态以 PG 为准；响应含 `current_step`；他人批次 403、不存在 404） | batch_router.py |
+| 任务状态 | `/api/status/{task_id}`（需登录；仅任务所有者可访问，他人/无主任务 403，不存在 404） | task_router.py |
 | 历史结果 | `/api/history`、`/api/history/{filename}` | history_router.py |
 | CAM | `/api/cam/plan` | cam_router.py |
 | 铝价（模拟数据） | `/api/aluminum-price/current`、`/api/aluminum-price/history` | aluminum_price_routes.py |

docs/ARCHITECTURE.md

@@ -96,7 +96,7 @@ geMoldInsight/
 │   ├── celery_app.py
 │   └── celery_tasks.py
 ├── frontend/
-├── alembic/
+├── migrations/
 ├── deploy/
 ├── docs/
 └── tests/

docs/OPERATIONS.md

@@ -12,6 +12,7 @@
 - **Compose 运行**：compose 文件用 `${VAR}` 从同目录 `.env` 注入容器环境变量（见 [docker-compose.yml](../docker-compose.yml)）。
 - **键值约定**：
   - `DB_HOST / DB_PORT / DB_NAME / DB_USER / DB_PASSWORD`：**惰性校验、无代码默认**——缺失时 import 不报错（便于测试/静态分析），真正连库时才失败。生产必须显式配置。
+  - `AUTO_MIGRATE`：应用启动时是否自动执行 alembic 迁移，默认 `true`（单机开发语义）；**多副本 / 容器编排部署应设 `false`**，改由部署流程单点执行 `alembic upgrade head` 或 `python -m shared.database.init_db`（迁移脚本已随镜像分发于 `/app/migrations/`）。
   - `SECRET_KEY`：JWT 签名密钥，**无默认**；生产必须 ≥32 字符强随机。
   - `ADMIN_PASSWORD`：初始管理员密码，**无默认**；首次建库前必须设置。
   - `RUSTFS_*`：对象存储（兼容 `MINIO_*` 别名写法）；本地开发缺省值仅为占位，连不上会在用到存储的链路报错。
@@ -26,7 +27,7 @@
 - 后端依赖：`pip install -r requirements.txt`。
 - **OCC 几何能力**：PythonOCC 不走 pip 主路径，通过 conda 环境提供（本项目实践环境名 `gemold`）。无 OCC 环境时项目可启动，但几何分析契约测试自动 skip。
 - 前端：`cd frontend && npm install`。
-- 数据库迁移：`alembic/`（`alembic.ini` 在仓库根）；数据修复类一次性脚本在 `scripts/migrations/` 与 `scripts/db/`，**不是运行时代码**，勿在服务内引用。
+- 数据库迁移：`migrations/`（`alembic.ini` 在仓库根；2026-09-16 由 `alembic/` 改名——原目录名与 alembic 包重名，应用内 import 会被遮蔽导致启动期迁移静默失败）；数据修复类一次性脚本在 `scripts/migrations/` 与 `scripts/db/`，**不是运行时代码**，勿在服务内引用。
 
 ## 3. 本地启动
 

docs/ROADMAP.md

@@ -24,11 +24,13 @@ geMoldInsight 已从历史单体逐步演进为“双业务模块 + 共享平台
 ### 2.1 主线一：模块化架构收口
 
 目标：
+
 - 继续巩固 `moldinsight / inventory / frontend / shared` 的边界
 - 减少历史单体遗留语义
 - 让 README、架构文档、部署文档与代码结构一致
 
 重点方向：
+
 - 继续收敛 `shared` 的职责
 - 逐步明确 identity / platform 的边界语义
 - 收敛历史文档与旧部署叙事
@@ -36,11 +38,13 @@ geMoldInsight 已从历史单体逐步演进为“双业务模块 + 共享平台
 ### 2.2 主线二：moldinsight 工程化增强
 
 目标：
+
 - 让 STEP/STP 分析链路更稳定
 - 让导出、批量分析、成本估算、任务状态等链路更可靠
 - 继续提高 OCC 相关处理的可维护性与可测试性
 
 重点方向：
+
 - `advanced_router` 拆分与请求模型规范化
 - 模具分析链路的结构继续收口
 - OCC 依赖场景下的契约测试/集成测试继续补齐
@@ -48,11 +52,13 @@ geMoldInsight 已从历史单体逐步演进为“双业务模块 + 共享平台
 ### 2.3 主线三：inventory 业务层继续沉淀
 
 目标：
+
 - 让 inventory 从“可用”继续走向“可扩展”
 - 继续将路由中的业务逻辑下沉为 service 层
 - 保持与 moldinsight 的桥接模型清晰
 
 重点方向：
+
 - 业务 service 复用强化
 - 数据模型归属进一步清晰化
 - 前后端契约持续减少手写漂移
@@ -60,10 +66,12 @@ geMoldInsight 已从历史单体逐步演进为“双业务模块 + 共享平台
 ### 2.4 主线四：部署与运维一致性
 
 目标：
+
 - 让推荐部署模式、Compose 入口、运维文档、Nginx/端口说明不再冲突
 - 让前端、后端、异步任务链路在部署说明上形成单一叙事
 
 重点方向：
+
 - 继续收口部署文档
 - 把历史部署迁移方案移入归档
 - 保持同域前端 + unified backend 的默认认知清晰
@@ -103,16 +111,18 @@ geMoldInsight 已从历史单体逐步演进为“双业务模块 + 共享平台
 > 2026-09-15 完成 moldinsight 后端设计审查，产出的具体治理批次是当前下一阶段最具体的执行计划。
 > 债务明细与逐项现状见 [TECH_DEBT.md](TECH_DEBT.md) §3（D5–D14）；本小节只描述批次、顺序与每批归属。
 
-| 批次 | 主题 | 内容 | 对应债务 |
-|------|------|------|---------|
-| 批次 0 | 安全与诚实（0.5–1 天） | `/api/status/{task_id}` 补鉴权 + 任务归属校验；`pythonocc_available` 真实检测；bcrypt 超长密码拒绝；SECRET_KEY / RUSTFS_* 惰性校验补齐 | D5 |
-| 批次 1 | 部署正确性（1–2 天） | 主链路改走 RustFS（分派入参 `file_path` → `stp_file_id`，worker 按 object_key 下载解析）；compose 共享卷兜底（过渡）；alembic 移出 startup（`AUTO_MIGRATE` 开关）；OCC 镜像引入方式修正 + 依赖锁文件 | D6、D12、D13 |
-| 批次 2 | 任务一致性模型（2–4 天） | PG 为单一事实源、Redis 仅热缓存；去掉多进程内存回退；批量元数据入库；型腔失败标 failed；持久化事务边界收口 | D7、D8、D9、D11 |
-| 批次 3 | API 与代码结构（3–5 天） | `_safe_include` 失败显式化（/health 暴露缺失路由）；advanced_router 拆分 + Pydantic 请求模型；async 重计算统一 executor；StorageIntegrationService 拆分；配置治理 | D1、D14 |
-| 批次 4 | 架构演进（5 天+） | 共享 ORM 按模块拆分；OCC 吞吐方案设计先行；文档 / 契约同步 | D3、D10 |
+| 批次   | 主题                      | 内容                                                                                                                                                                                                       | 对应债务        |
+| ------ | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- |
+| 批次 0 | 安全与诚实（0.5–1 天）   | `/api/status/{task_id}` 补鉴权 + 任务归属校验；`pythonocc_available` 真实检测；bcrypt 超长密码拒绝；SECRET_KEY / RUSTFS_* 惰性校验补齐                                                                 | D5              |
+| 批次 1 | 部署正确性（1–2 天）     | 主链路改走 RustFS（分派入参`file_path` → `stp_file_id`，worker 按 object_key 下载解析）；compose 共享卷兜底（过渡）；alembic 移出 startup（`AUTO_MIGRATE` 开关）；OCC 镜像引入方式修正 + 依赖锁文件 | D6、D12、D13    |
+| 批次 2 | 任务一致性模型（2–4 天） | PG 为单一事实源、Redis 仅热缓存；去掉多进程内存回退；批量元数据入库；型腔失败标 failed；持久化事务边界收口                                                                                                 | D7、D8、D9、D11 |
+| 批次 3 | API 与代码结构（3–5 天） | `_safe_include` 失败显式化（/health 暴露缺失路由）；advanced_router 拆分 + Pydantic 请求模型；async 重计算统一 executor；StorageIntegrationService 拆分；配置治理                                        | D1、D14         |
+| 批次 4 | 架构演进（5 天+）         | 共享 ORM 按模块拆分；OCC 吞吐方案设计先行；文档 / 契约同步                                                                                                                                                 | D3、D10         |
 
 **执行顺序建议**：批次 0 与批次 1 的 D6（RustFS 主链路）先行——前者是确认的安全漏洞，后者是部署根本性缺陷，两者互不依赖、改动可控。其余按批次顺序推进，每批完成同步 STATUS / TECH_DEBT / API_CONTRACT。
 
+> 进度：批次 0 / 1 / 2 已于 2026-09-16 完成（D13 的 pip 全量锁文件为批次 1 遗留项，随下次镜像构建补齐；D11 留待后续批次，正确性已由批次 1 共享卷兜底）；完成明细见 [STATUS.md](STATUS.md) 与 [TECH_DEBT.md](TECH_DEBT.md) §2.5–2.6。
+
 ---
 
 ## 4. 中长期方向
@@ -120,6 +130,7 @@ geMoldInsight 已从历史单体逐步演进为“双业务模块 + 共享平台
 ### 4.1 平台层语义收敛
 
 长期仍建议将 `shared` 逐步收敛为更清晰的平台层语义，但这应建立在：
+
 - 当前模块边界稳定
 - 共享职责分层足够清晰
 - 文档与部署已经同步收口
@@ -127,6 +138,7 @@ geMoldInsight 已从历史单体逐步演进为“双业务模块 + 共享平台
 ### 4.2 文档体系持续治理
 
 后续文档治理原则：
+
 - README 只做入口
 - 当前状态只在 [STATUS.md](STATUS.md)
 - 历史材料统一入 `docs/archive/`
@@ -135,6 +147,7 @@ geMoldInsight 已从历史单体逐步演进为“双业务模块 + 共享平台
 ### 4.3 测试能力继续增强
 
 重点继续放在：
+
 - OCC 相关集成验证
 - 跨模块关键链路回归测试
 - 关键契约的自动化保护
@@ -144,6 +157,7 @@ geMoldInsight 已从历史单体逐步演进为“双业务模块 + 共享平台
 ### 4.4 专题文档持续分级
 
 后续还会继续把专题文档区分为三类：
+
 - 当前仍有参考价值的专题文档（保留并补定位）
 - 纯阶段性任务/检查单/迁移计划（迁入 archive）
 - 可被主骨架吸收的重复说明（逐步收口）

docs/STATUS.md

@@ -3,6 +3,12 @@
 > 文档定位：**唯一的「现在到哪了」**。README / AGENTS / 各主文档只链接到这里，不复制状态内容。
 > 维护规则：每完整完成一个需求，**倒序在本文顶部加一条**（日期 + 主题 + 关键事实）；其余主文档（架构 / 规划 / 技术债 / 部署）维护各自的"当前有效说法"，本文只记录"什么时候做到了哪一步"。维护规则出处见根目录 [AGENTS.md](../AGENTS.md)。
 
+> 2026-09-16（**批次 2（任务一致性模型）完成**：① D7 清偿——Redis 进程内存回退**彻底删除**（写 no-op / 读 None，查询路径自然落 PG），PG 为任务状态单一事实源；批量元数据入库：`processing_tasks` 新增 `batch_id` 列（迁移 `a3f8c2d91e47`，**升级后首次启动自动执行**），`GET /api/batch/{batch_id}` 改为 PG 聚合查询 + `STPFile.user_id` 归属校验，删除 Redis batch key 与内存 dict 双通道；`TaskQueryService` PG 视图与 batch 聚合响应补 `progress` / `current_step`（Redis 不可用时前端仍能看到进度）；② D8 清偿——型腔分模失败不再吞异常，任务标 failed 并带明确错误（已提交的几何/网格保留）；③ D9 清偿——数据本体写方法只 flush，编排层分阶段原子收口（阶段 A 几何+网格、阶段 B 型腔+HTML+特征+指标+验证、完成时参数随状态一并提交），失败先 rollback 再置 failed；进度/状态更新保留即时 commit（长任务进度可见性）；upload/batch/advanced 调用方补显式 commit，STPFile + ProcessingTask 原子落库消除孤儿文件记录。D11 未动（共享卷已兜正确性，留后续批次）。**测试基线**：**105 passed, 1 skipped**（新增 [tests/test_batch_status_pg.py](../tests/test_batch_status_pg.py) 4 项 + [tests/test_redis_no_fallback.py](../tests/test_redis_no_fallback.py) 3 项）。**下一步**：批次 3（API 与代码结构：`_safe_include` 失败显式化、advanced_router 拆分 + Pydantic 请求模型、配置治理，见 [ROADMAP.md](ROADMAP.md) §3.1）。）
+
+> 2026-09-16（**批次 1（部署正确性）完成**：① D6 清偿——分派入参 `file_path` → `stp_file_id`，处理方按 PG 元数据从 RustFS 下载源文件到任务专属临时目录（RustFS 异常时回退节点本地路径），compose 增 `uploads_data` / `html_data` 共享卷过渡兜底；② D12 清偿——新增 `AUTO_MIGRATE` 开关（默认 true 保持单机行为；多副本设 false 改部署流程单点迁移），迁移脚本与 alembic.ini 补进镜像。**连带发现并修复**：迁移目录 `alembic/` 与 alembic 包重名，应用内 `import alembic` 被遮蔽——启动期自动迁移自引入 alembic 起**从未真正生效**（异常被 init_database 吞掉只打日志），且镜像原本未打包迁移脚本；目录已改名 `migrations/`（alembic.ini + 4 处文档引用同步）；③ D13 主体——Dockerfile.moldinsight 改为 conda 运行时原生执行（不再跨镜像拷贝 site-packages），基础镜像 tag 锁定；pip 全量锁文件遗留，随下次镜像构建 `pip freeze` 生成；④ compose 关键项去弱默认：`SECRET_KEY` / `ADMIN_PASSWORD` 改 `${VAR:?}` 强制显式配置（与 OPERATIONS「无默认」声明对齐），`create_admin_user` 对空口令显式报错。**测试基线**：**98 passed, 1 skipped**（新增 [tests/test_deployment_config.py](../tests/test_deployment_config.py)；alembic 缺失环境 skip）。**遗留**：D13 pip 锁文件；既有问题待查——Dockerfile.celery `FROM gemold-moldinsight:latest`，而 build.sh 只构建 `gemold-backend` tag，干净机器上 build.sh 的 celery 步骤会失败。**下一步**：批次 2（任务一致性模型，见 [ROADMAP.md](ROADMAP.md) §3.1）。）
+
+> 2026-09-16（**批次 0（安全与诚实）完成**：① `/api/status/{task_id}` 补 JWT 鉴权 + 任务归属校验（无 token 401 / 他人或无主任务 403 / 不存在 404），归属校验收敛为 `TaskQueryService.ensure_task_access` 供 task_router 与 advanced_router 共用——技术债 [D5 清偿](TECH_DEBT.md)；② 上传预检 `pythonocc_available` 从硬编码 true 改为惰性真实探测；③ bcrypt 口令治理：创建侧超 72 字节显式拒绝（此前静默截断改变有效密码），验证侧截断比较（兼容历史哈希 + 避免超长登录 500）；④ `SECRET_KEY` 未配置 / `RUSTFS_*` 缺失时惰性校验抛明确错误，代码侧不再有占位弱默认。**顺带修复**：完成态任务未持久化 `analysis_metrics` 时 `/api/status` 组装视图 500（值为 None 时 `.get(key, {})` 默认值不生效）。**测试基线**：pip 无 OCC 环境 **96 passed**（新增 [tests/test_status_endpoint_auth.py](../tests/test_status_endpoint_auth.py) 8 项回归）。status 端点鉴权为接口行为变化，已同步 [API_CONTRACT.md](API_CONTRACT.md) §3.2；openapi.json 重导出仍按既有待办随下次接口变更一并执行。**下一步**：批次 1（D6 RustFS 主链路 + D12 alembic 移出 startup + D13 OCC 镜像，见 [ROADMAP.md](ROADMAP.md) §3.1）。）
+
 > 2026-09-15（**后端设计审查完成 → 治理计划入文档**：完成 moldinsight 后端设计审查（部署 / 任务一致性 / API / 代码结构），产出治理批次计划入 [ROADMAP.md](ROADMAP.md) §3.1（批次 0–4：安全→部署→一致性→结构→架构）；新识别技术债 D5–D14 入 [TECH_DEBT.md](TECH_DEBT.md) §3——含确认安全缺口 `/api/status/{task_id}` 无鉴权、主处理链路依赖节点本地文件路径（API 与 Celery worker 容器无共享卷）等。**下一步**：按批次 0 + 批次 1 的 D6（RustFS 主链路）启动实施。）
 
 > 最后更新：2026-09-15（**项目规范体系对齐 ipc-chat-cortex**——参考 `ipc-chat-cortex` 的 AGENTS.md + docs 规范重整本文档体系：① [AGENTS.md](../AGENTS.md) 重写——硬约束速览（新增：接口变更三件套 Pydantic→openapi.json→gen:api、配置只走 .env 且关键项不兜底、单数据库刻意设计）+ 代码地图逐文件化 + 开发约定映射表（改什么→同步什么文档）；② 新增 [OPERATIONS.md](OPERATIONS.md)（配置来源与优先级 / 本地启动 / Compose / 运维硬性要求）与 [API_CONTRACT.md](API_CONTRACT.md)（端点总览 / 统一约定 / OpenAPI 类型生成流程）；③ 本文件改为日志体，原静态内容分流到各归属文档（推荐部署模式→DEPLOYMENT §1，未完成项→ROADMAP/TECH_DEBT）。**验证**：openapi 导出命令实测可用（conda gemold 环境，unified app 76 paths）；**待办**：checked-in `openapi.json`（2026-07-27，70 paths）已落后当前代码，下次接口变更时按 [API_CONTRACT.md](API_CONTRACT.md) §4 重导出并 `npm run gen:api`。）

docs/TECH_DEBT.md

@@ -25,6 +25,8 @@
 - debug/history 路由补鉴权
 - 任务访问控制收紧
 - 无主数据不再默认放行
+- `/api/status/{task_id}` 补 JWT 鉴权与归属校验（原 D5，2026-09-16 清偿，见 D5 条目）
+- bcrypt 创建口令超 72 字节显式拒绝、验证侧截断比较；`SECRET_KEY` / `RUSTFS_*` 缺失时明确报错，代码侧弱默认移除（D14 部分，2026-09-16）
 
 ### 2.2 静默失败与可用性
 - `detect-undercuts` 改为基于真实 shape 分析
@@ -41,6 +43,18 @@
 - 设置惰性配置校验，提升可测试性
 - Generator 公共接口提取完成，补充契约测试
 
+### 2.5 部署正确性（2026-09-16，批次 0/1）
+- `/api/status/{task_id}` 补鉴权与归属校验（原 D5）
+- 主处理链路改走 RustFS：分派入参 `stp_file_id` 化，源文件按 object_key 下载；compose 共享卷过渡兜底（原 D6）
+- `AUTO_MIGRATE` 开关 + 迁移脚本随镜像分发 + `alembic/`→`migrations/` 改名修复包遮蔽（原 D12）
+- OCC 镜像改 conda 运行时原生执行、基础镜像 tag 锁定（D13 主体）；compose 关键项去弱默认（D14 部分）
+
+### 2.6 任务一致性模型（2026-09-16，批次 2）
+- Redis 内存回退彻底删除，PG 为任务状态单一事实源（原 D7）；批量元数据入库（`processing_tasks.batch_id`，迁移 `a3f8c2d91e47`）
+- 型腔生成失败任务标 failed，不再静默 completed（原 D8）
+- 持久化事务边界收口：数据本体分阶段原子提交、失败先回滚再置 failed（原 D9）
+- D11（HTML 双写双读）本批未动：正确性已由共享卷兜底，RustFS 单一来源留待后续批次
+
 详细历史过程保留在原始技术债文档中，后续将转入归档。
 
 ---
@@ -111,74 +125,51 @@
 
 优先级：**P1**
 
-### D5. `/api/status/{task_id}` 未鉴权（安全缺口）
+### D5. `/api/status/{task_id}` 未鉴权（安全缺口）—— 已清偿（2026-09-16，批次 0）
 
-现状：
-- [src/moldinsight/api/task_router.py](../src/moldinsight/api/task_router.py) 的 `/api/status/{task_id}` 未挂 `get_current_active_user`，也无任务归属校验
-- 匿名可枚举任务号拉取完整分析视图（几何 / 型腔方案 / LLM 报告 / 服务器本地路径）
+修复内容（保留编号以维持 D6–D14 引用稳定）：
+- 端点补 `Depends(get_current_active_user)`；归属校验收敛为 `TaskQueryService.ensure_task_access`，task_router 与 advanced_router 共用（advanced_router 原私有 `_ensure_task_access` 改为委托）
+- 语义：无 token 401、他人/无主任务 403（无主不等于公共）、任务不存在 404
+- 回归测试：[tests/test_status_endpoint_auth.py](../tests/test_status_endpoint_auth.py)
+- 接口行为变化已同步 [API_CONTRACT.md](API_CONTRACT.md) §3.2
 
-影响：
-- 与"任务访问控制已收紧"的既有结论矛盾；任务号可经批量/历史接口关联到真实用户
-- 属确认的安全漏洞，应最先修复
+~~原现状 / 影响~~：端点未挂鉴权，匿名可枚举任务号拉取完整分析视图。
 
-建议：
-- 补 `Depends(get_current_active_user)` 并复用 `_ensure_task_access` 归属校验
+### D6. 主处理链路依赖节点本地文件路径 —— 已清偿（2026-09-16，批次 1）
 
-优先级：**P0**
+修复内容（保留编号以维持引用稳定）：
+- 分派入参收敛为 `stp_file_id`（`dispatch_processing` 与 Celery 任务签名同步变更）：处理方按 PG 元数据从 RustFS 下载源文件到任务专属临时目录（保留原始文件名，下游产物命名不变），任务结束即清理（[processing_service.py](../src/moldinsight/services/processing_service.py) `_materialize_source_file`）
+- RustFS 不可用时回退 `STPFile.file_path` 节点本地路径；compose 为 backend / celery 增加共享卷 `uploads_data` / `html_data` 作过渡兜底（HTML 产物跨容器写读同源问题一并兜住，正式修复在 D11）
 
-### D6. 主处理链路依赖节点本地文件路径
+~~原现状 / 影响~~：worker 直读 API 节点本地路径，双容器部署必然 `FileNotFoundError`。
 
-现状：
-- 上传保存到本地目录，任务处理直接 `load_step_file(Path(file_path))`（[processing_service.py](../src/moldinsight/services/processing_service.py)）
-- docker-compose 中 backend 与 moldinsight-celery 为独立容器且无共享 volume，worker 读不到 API 节点写入的本地文件
+### D7. Redis 降级为进程内 dict，多副本状态不一致 —— 已清偿（2026-09-16，批次 2）
 
-影响：
-- 双容器部署下主流程必然 `FileNotFoundError`；代码已有从 RustFS 重建几何的 [shape_loader.py](../src/moldinsight/services/shape_loader.py)，主链路却未复用
+修复内容（比原建议更彻底：完全删除内存回退，而非仅限 DEBUG）：
+- [redis_task_manager.py](../src/shared/services/redis_task_manager.py) 删除全部 `_fallback_*` 进程内存存储：Redis 不可用时写 no-op、读返回 None（Redis 仅热缓存，任务状态事实源在 PG，缓存缺失不影响正确性）
+- 批量元数据入库：`processing_tasks` 新增 `batch_id` 列（迁移 `a3f8c2d91e47`），`GET /api/batch/{batch_id}` 改为按列聚合查询 + `STPFile.user_id` 归属校验，删除 Redis batch key 与进程内 dict 双通道
+- `TaskQueryService` 的 PG 组装视图补 `progress` / `current_step`（Redis 不可用时前端轮询仍能看到进度）；batch 聚合响应同步补 `current_step`
 
-建议：
-- 分派入参由 `file_path` 改为 `stp_file_id`，worker 端按 `object_key` 从 RustFS 下载后解析
+~~原现状 / 影响~~：Redis 故障时状态静默降级各进程内存，多副本互不可见、同任务不同副本读到不同状态。
 
-优先级：**P0**
+### D8. 型腔生成失败被静默标记为 completed —— 已清偿（2026-09-16，批次 2）
 
-### D7. Redis 降级为进程内 dict，多副本状态不一致
+修复内容：
+- [processing_service.py](../src/moldinsight/services/processing_service.py) `_step_generate_cavity` 不再吞异常：分模失败直接向编排层传播 → 任务 failed（error_message 说明型腔阶段失败）；已提交的几何/网格数据保留，用户可凭失败原因重新分析
+- 未采用 `completed_with_fallback`：多一个状态值会扩散到前端所有状态分支，failed + 明确错误更诚实且成本低
 
-现状：
-- Redis 不可用时任务状态 / 批量元数据 / 任务视图缓存静默降级到各进程内存（[redis_task_manager.py](../src/shared/services/redis_task_manager.py) / [batch_router.py](../src/moldinsight/api/batch_router.py) / [task_query_service.py](../src/moldinsight/services/task_query_service.py)）
+~~原现状 / 影响~~：型腔失败被吞掉继续主流程，最终 completed，"完成"状态不可信。
 
-影响：
-- 多 worker + 多 API 副本下各进程内存互相不可见：同一任务在不同副本读到不同状态
+### D9. 持久化事务边界破碎 —— 已清偿（2026-09-16，批次 2）
 
-建议：
-- PG 作为单一事实源、Redis 仅热缓存；内存回退仅限单进程 DEBUG 模式
+修复内容（进度可见性与原子性折中设计）：
+- **数据本体写方法只 flush 不 commit**：`save_stp_file` / `save_geometry_data` / `save_mesh_data` / `save_mold_cavity_data` / `save_html_file` / `save_features_and_recommendations` / `update_task_parameters` / `update_stp_file_analysis_summary` / `_save_analysis_metrics` / `_save_verification_metrics`
+- **编排层分阶段收口**（[processing_service.py](../src/moldinsight/services/processing_service.py)）：阶段 A = 几何+网格（解析后确定成果，原子提交）；阶段 B = 型腔+HTML+特征+指标+摘要+验证（结果包原子提交）；完成时先 flush 任务参数、完成状态提交时一并落库（completed 即完整）
+- **失败路径先 rollback 再置 failed**：未提交半成品回滚，失败状态单独提交，不出现"completed 但数据残缺"
+- **保留即时 commit**：`update_task_status` / `update_stp_file_status`（处理中进度需跨事务对外可见，分钟级长任务不能憋在一个大事务里）
+- 调用方补显式 commit：upload_router / batch_router（分派前置事务，STPFile + ProcessingTask 原子，消除孤儿文件记录）、advanced_router 导出两处
 
-优先级：**P1**
-
-### D8. 型腔生成失败被静默标记为 completed
-
-现状：
-- `_step_generate_cavity` 异常时置 `plan_result=None` 继续主流程，最终任务标记 completed（[processing_service.py](../src/moldinsight/services/processing_service.py)）
-
-影响：
-- 核心能力失败却对外呈现"成功"，"完成"状态可信度低
-
-建议：
-- 型腔失败 → 任务 failed，或显式 `completed_with_fallback` 并前端标注
-
-优先级：**P1**
-
-### D9. 持久化事务边界破碎
-
-现状：
-- [storage_integration_rustfs.py](../src/moldinsight/services/storage_integration_rustfs.py) 各方法内部自行 `session.commit()`，编排层上下文又 commit
-- 型腔保存失败时几何/网格等前期数据已提交落库
-
-影响：
-- 失败后留下已提交的半成品数据，无对账补偿
-
-建议：
-- 各方法不再自提交，由编排层统一提交；明确 RustFS 与 PG 写入顺序
-
-优先级：**P1**
+~~原现状 / 影响~~：各存储方法内部自行 commit，型腔保存失败留半成品数据且任务仍 completed。
 
 ### D10. OCC 全局单线程串行 + 超时重建泄漏线程
 
@@ -209,35 +200,26 @@
 
 ### D12. 应用启动时自动执行 alembic 迁移
 
-现状：
-- [init_db.py](../src/shared/database/init_db.py) 在 web 进程 startup 中执行 `alembic upgrade head`
+### D12. 应用启动时自动执行 alembic 迁移 —— 已清偿（2026-09-16，批次 1）
 
-影响：
-- 多副本并发迁移有竞态，且迁移阻塞服务就绪
+修复内容：
+- 新增 `AUTO_MIGRATE` 开关（settings / .env.example / compose 透传）：默认 `true` 保持单机开发行为；多副本部署设 `false`，由部署流程单点执行 alembic CLI 或 `python -m shared.database.init_db`
+- **连带发现并修复两个使自动迁移从未真正生效的缺陷**：
+  1. 迁移目录 `alembic/` 与 alembic 包重名——应用内 `import alembic` 命中本地目录（namespace package）遮蔽真实包，启动期迁移异常被 `init_database` 吞掉只打日志；已改名 `migrations/`（alembic.ini `script_location` 与 4 处文档引用同步）
+  2. 镜像未打包迁移脚本与 alembic.ini，容器内迁移必然失败——Dockerfile.base / Dockerfile.moldinsight 已补 `COPY migrations/` + `COPY alembic.ini`
 
-建议：
-- 迁移移出 web 进程，作为独立部署步骤（`AUTO_MIGRATE` 开关）
-
-优先级：**P1**
-
-### D13. PythonOCC 镜像引入方式脆弱 + 依赖无版本锁
+### D13. PythonOCC 镜像引入方式脆弱 + 依赖无版本锁（主体已清偿，锁文件遗留）
 
 现状：
-- [Dockerfile.moldinsight](../deploy/Dockerfile.moldinsight) 从 conda env 拷贝 site-packages 进 python:3.12-slim
-- [requirements.txt](../requirements.txt) 全部为 `>=` 下限，无锁文件
+- ~~从 conda env 拷贝 site-packages 进 python:3.12-slim~~（2026-09-16 已修正：[Dockerfile.moldinsight](../deploy/Dockerfile.moldinsight) 改为 conda 运行时原生执行，不再跨镜像拷贝；基础镜像 tag 锁定 `continuumio/miniconda3:24.7.1-0`、`python:3.12-slim-bookworm`；tag 可用性随下次镜像构建验证）
+- [requirements.txt](../requirements.txt) 全部为 `>=` 下限，无锁文件（**遗留**：首次镜像构建成功后 `pip freeze` 生成锁文件，命令已注释在 Dockerfile 内）
 
-影响：
-- slim 缺 libstdc++/libgomp 等运行时库，跨发行版拷二进制纯靠运气；构建不可复现
-
-建议：
-- 基础镜像改用完整 conda 环境；依赖以 pip-compile 锁文件固化
-
-优先级：**P2**
+优先级：**P2**（剩余锁文件部分）
 
 ### D14. 配置漂移：弱默认 / 死配置 / 重复解析
 
 现状：
-- RUSTFS_* 带 `localhost:8080` / `your-secret-key` 弱默认；compose 给 SECRET_KEY / ADMIN_PASSWORD 弱默认
+- ~~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 两份实现