文档

docs/TECH_DEBT.md

@@ -111,10 +111,150 @@
 
 优先级：**P1**
 
+### D5. `/api/status/{task_id}` 未鉴权（安全缺口）
+
+现状：
+- [src/moldinsight/api/task_router.py](../src/moldinsight/api/task_router.py) 的 `/api/status/{task_id}` 未挂 `get_current_active_user`，也无任务归属校验
+- 匿名可枚举任务号拉取完整分析视图（几何 / 型腔方案 / LLM 报告 / 服务器本地路径）
+
+影响：
+- 与"任务访问控制已收紧"的既有结论矛盾；任务号可经批量/历史接口关联到真实用户
+- 属确认的安全漏洞，应最先修复
+
+建议：
+- 补 `Depends(get_current_active_user)` 并复用 `_ensure_task_access` 归属校验
+
+优先级：**P0**
+
+### D6. 主处理链路依赖节点本地文件路径
+
+现状：
+- 上传保存到本地目录，任务处理直接 `load_step_file(Path(file_path))`（[processing_service.py](../src/moldinsight/services/processing_service.py)）
+- docker-compose 中 backend 与 moldinsight-celery 为独立容器且无共享 volume，worker 读不到 API 节点写入的本地文件
+
+影响：
+- 双容器部署下主流程必然 `FileNotFoundError`；代码已有从 RustFS 重建几何的 [shape_loader.py](../src/moldinsight/services/shape_loader.py)，主链路却未复用
+
+建议：
+- 分派入参由 `file_path` 改为 `stp_file_id`，worker 端按 `object_key` 从 RustFS 下载后解析
+
+优先级：**P0**
+
+### D7. Redis 降级为进程内 dict，多副本状态不一致
+
+现状：
+- 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)）
+
+影响：
+- 多 worker + 多 API 副本下各进程内存互相不可见：同一任务在不同副本读到不同状态
+
+建议：
+- PG 作为单一事实源、Redis 仅热缓存；内存回退仅限单进程 DEBUG 模式
+
+优先级：**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**
+
+### D10. OCC 全局单线程串行 + 超时重建泄漏线程
+
+现状：
+- 所有 OCC 操作经 `max_workers=1` executor 串行（[processing_service.py](../src/moldinsight/services/processing_service.py)），celery 并发无法扩展 OCC 吞吐
+- 超时重建 executor 每次泄漏 1 个线程，长期运行只涨不降
+
+影响：
+- 一个长耗时型腔生成阻塞全部几何处理；线程随故障累积
+
+建议：
+- 记录吞吐上限为已知约束；线程泄漏治理方案设计先行（见 [ROADMAP.md](ROADMAP.md) §3.1 批次 4）
+
+优先级：**P2**
+
+### D11. HTML 报告本地磁盘与 RustFS 双写双读
+
+现状：
+- 可视化 HTML/摘要同时写本地 `html_output/`（/html 静态挂载）与 RustFS
+
+影响：
+- 多副本下 /html 命中结果取决于负载均衡，跨副本文件不共享；同一份报告两套来源
+
+建议：
+- 统一 RustFS 为唯一来源，本地仅作按需缓存
+
+优先级：**P2**
+
+### D12. 应用启动时自动执行 alembic 迁移
+
+现状：
+- [init_db.py](../src/shared/database/init_db.py) 在 web 进程 startup 中执行 `alembic upgrade head`
+
+影响：
+- 多副本并发迁移有竞态，且迁移阻塞服务就绪
+
+建议：
+- 迁移移出 web 进程，作为独立部署步骤（`AUTO_MIGRATE` 开关）
+
+优先级：**P1**
+
+### D13. PythonOCC 镜像引入方式脆弱 + 依赖无版本锁
+
+现状：
+- [Dockerfile.moldinsight](../deploy/Dockerfile.moldinsight) 从 conda env 拷贝 site-packages 进 python:3.12-slim
+- [requirements.txt](../requirements.txt) 全部为 `>=` 下限，无锁文件
+
+影响：
+- slim 缺 libstdc++/libgomp 等运行时库，跨发行版拷二进制纯靠运气；构建不可复现
+
+建议：
+- 基础镜像改用完整 conda 环境；依赖以 pip-compile 锁文件固化
+
+优先级：**P2**
+
+### D14. 配置漂移：弱默认 / 死配置 / 重复解析
+
+现状：
+- RUSTFS_* 带 `localhost:8080` / `your-secret-key` 弱默认；compose 给 SECRET_KEY / 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 两份实现
+
+影响：
+- 违背"关键项不兜底"硬约束；配置行为与文档不一致
+
+建议：
+- 去掉弱默认、对齐或删除死配置、celery_app 复用 settings
+
+优先级：**P2**
+
 ---
 
 ## 4. 当前推荐治理顺序
 
+> 注：2026-09-15 后端设计审查后，治理**执行顺序**以 [ROADMAP.md](ROADMAP.md) §3.1 批次计划为准（批次 0–4）；D5–D14 的批次归属见该表。本节保留原有优先项作为补充说明。
+
 ### 第一优先级
 1. `advanced_router` 拆分
 2. 高优先级接口补 Pydantic 请求模型