# 2026-09 后端设计治理批次实施流水账（归档）

> 文档定位：**2026-09 设计审查产出的批次 0–4 与后续专项的完整实施流水账**。
> 主骨架权威文档见：
> - [../STATUS.md](../STATUS.md)（每批次完成的时间点与产物）
> - [../TECH_DEBT.md](../TECH_DEBT.md)（活跃债务 / 已清偿项的当前位置）
> - [../ROADMAP.md](../ROADMAP.md)（批次计划与执行顺序）
> - [../ARCHITECTURE.md](../ARCHITECTURE.md)（平台 / 模块边界当前定稿）

## 批次 0（2026-09-16，安全与诚实）

- `/api/status/{task_id}` 补 JWT 鉴权 + 任务归属校验（无 token 401 / 他人或无主任务 403 / 不存在 404）
- 归属校验收敛为 `TaskQueryService.ensure_task_access` 供 task_router 与 advanced_router 共用（原 D5）
- 上传预检 `pythonocc_available` 从硬编码 true 改为惰性真实探测
- bcrypt 口令治理：创建侧超 72 字节显式拒绝、验证侧截断比较
- `SECRET_KEY` 未配置 / `RUSTFS_*` 缺失时惰性校验抛明确错误
- 完成态任务未持久化 `analysis_metrics` 时 `/api/status` 组装视图 500 修复
- 测试基线：96 passed
- 回归测试：`tests/test_status_endpoint_auth.py` 8 项
- 接口行为变化已同步 [../API_CONTRACT.md](../API_CONTRACT.md) §3.2

## 批次 1（2026-09-16，部署正确性）

- 主处理链路改走 RustFS：分派入参 `file_path` → `stp_file_id`（原 D6）
- 处理方按 PG 元数据从 RustFS 下载源文件到任务专属临时目录（保留原始文件名，下游产物命名不变），任务结束即清理
- RustFS 不可用时回退 `STPFile.file_path` 节点本地路径；compose 为 backend / celery 增加共享卷 `uploads_data` / `html_data` 作过渡兜底
- `AUTO_MIGRATE` 开关（settings / .env.example / compose 透传），默认 `true` 保持单机开发行为（原 D12）
- 迁移目录 `alembic/` → `migrations/`（修复 `import alembic` 命中本地目录遮蔽真实包的命名冲突）+ Docker 镜像补 `COPY migrations/` + `COPY alembic.ini`
- Dockerfile.moldinsight 改为 conda 运行时原生执行，基础镜像 tag 锁定（原 D13 主体）
- compose 关键项去弱默认：`SECRET_KEY` / `ADMIN_PASSWORD` 改 `${VAR:?}` 强制显式配置；`create_admin_user` 对空口令显式报错
- 测试基线：98 passed, 1 skipped
- 回归测试：`tests/test_deployment_config.py`

## 批次 2（2026-09-16，任务一致性模型）

- Redis 进程内存回退彻底删除（写 no-op / 读 None，Redis 仅热缓存），PG 为任务状态单一事实源（原 D7）
- 批量元数据入库：`processing_tasks` 新增 `batch_id` 列（迁移 `a3f8c2d91e47`），`GET /api/batch/{batch_id}` 改为 PG 聚合查询 + `STPFile.user_id` 归属校验
- 删除 Redis batch key 与进程内 dict 双通道
- `TaskQueryService` PG 视图与 batch 聚合响应补 `progress` / `current_step`
- 型腔分模失败不再吞异常 → 任务 failed（原 D8）
- 持久化事务边界收口：数据本体写方法只 flush，编排层分阶段原子收口（阶段 A 几何+网格、阶段 B 型腔+HTML+特征+指标+验证），失败先 rollback 再置 failed（原 D9）
- 进度/状态更新保留即时 commit（长任务进度可见性）
- 测试基线：105 passed, 1 skipped
- 回归测试：`tests/test_batch_status_pg.py` 4 项 + `tests/test_redis_no_fallback.py` 3 项

## 批次 3（2026-09-17，API 与代码结构）

- `advanced_router` 按职责拆为 design / cost / machining / export 四个子路由，端点路径不变（原 D1）
- 全部请求体改 Pydantic 模型（`request.json()` 手动解析退役），校验失败统一 422
- `_get_cached_import` 上提为 `core_modules.py` 共用
- 路由装载失败显式化：`ROUTE_MODULES` 清单 + `route_registry`，失败经 `/api/health` 呈现 degraded（`pythonocc` 真实探测），DEBUG 下 fail fast
- 纯 Python 重计算端点统一 `asyncio.to_thread` 投放线程池，不再阻塞事件循环
- `StorageIntegrationService`（867 行）按职责拆为 TaskStorage / AnalysisStorage / FileHistory 三服务（原 D14 部分）
- `MAX_FILE_SIZE` 接线生效、celery_app 复用 `Settings.redis_url`（原 D14 收尾）
- 连带修复：管理员重置密码改 JSON body（原裸 str 参数被解析为 query param，前端发 body 必 422）；Dockerfile.celery 的 FROM tag 与实际构建 tag 对齐
- 接口变更三件套随批完成：openapi.json 重导出（76 paths）+ 前端 `gen:api`
- 测试基线：122 passed, 2 skipped
- 回归测试：4 个测试文件共 17 项（`test_advanced_split_contract` / `test_route_load_status` / `test_config_governance` / `test_auth_password_reset`）

## 批次 4（2026-09-17，架构演进）

- 共享 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.md](../ARCHITECTURE.md) §5.1）
- 约 45 处 import 全量改写，无兼容 facade
- 全量注册点收敛为 migrations/env.py 与 tests/conftest.py
- 零调用方的死方法 `db_manager.create_tables` 一并删除
- `_reset_occ_executor` 补 `cancel_futures=True`（旧实现下"慢恢复"的旧线程会继续消化旧队列，与新 executor **并发操作非线程安全的 OCC**，属数据竞争而非单纯泄漏，原 D10 短期治理）
- 吞吐路线定稿于 `topics/performance/OCC_THROUGHPUT.md`（短期 A：celery prefork 伸缩 + max-tasks-per-child 兜底；中期 B：run_occ 接口进程化 + kill-on-timeout 根治）
- 顺手清偿 D15：`vite.config.ts` 删除未用的 `mode` 参数，`vue-tsc -b` 恢复通过
- 回归测试：`tests/test_model_ownership.py`（31 表全量注册 / 单模块独立 mapper 配置 / 旧模块无 facade）
- 测试基线：125 passed, 2 skipped
- 接口面零变化（无 openapi 重导出）

## 批次 4 后续专项（2026-09-18）

- D11 清偿：可视化报告 RustFS 单源化
  - 写侧 HTMLGenerator 每任务写临时目录，`.html`/`_summary.json`/`_data.json` 三件统一裸传 RustFS 报告键 `html/reports/{filename}`
  - 读侧 `/html` StaticFiles 本地挂载删除，新增代理路由 `html_report_router.py`（报告键直取 → 遗留 `html/{hash}.json` JSON 包装解析 → 本地卷存量兜底 → 404）
  - 防路径穿越（单段文件名校验），URL 形状 `/html/{filename}` 不变
  - 部署：celery 服务摘除 `html_data` 卷；Dockerfile.moldinsight 删除 `COPY html_output/`
  - 已知约束：报告路由不做认证（iframe 无法携带 Authorization 头）
  - 删除 `get_stp_file_with_data` 的死数据块
- OCC 方案 A 部署参数落地：`CELERY_CONCURRENCY` / `CELERY_MAX_TASKS_PER_CHILD` 进 Dockerfile.celery + compose + .env.example
- D2 清偿：铝价响应带 `source: "simulated"`；前端按来源渲染"模拟数据 · 参考走势"标注；死代码 `getAluminumPrice` 删除
- D10 方案 B 实施：`run_occ(fn, *args)` → `run_occ(op_name, payload)`；常驻 OCC 进程池 + kill-on-timeout 根治残留线程泄漏
- CI 门禁：`.gitea/workflows/ci.yml` 三 job（pytest / 前端构建 / openapi 漂移检测）
- 接口变更三件套随批完成：openapi.json 重导出（76→77 paths，新增 `/html/{filename}`）+ 前端 `gen:api` 再生
- 测试基线：143 passed, 0 skipped

## 后续小步治理（2026-09-21 ~ 2026-09-22）

- 2026-09-21 inventory 业务层继续沉淀批次（4 批）：
  - `customer / supplier / warehouse` → `master_data_service`
  - `material_routes`（价格历史 / 趋势 / 供应商关联）→ `material_service`
  - `product_routes`（CRUD / BOM / from-task 跨模块桥接）→ `product_service`
  - `dashboard_routes`（首页统计 / 低库存预警）→ `dashboard_service`
- 2026-09-22 schema / datetime 现代化弃用清零（D12）：
  - 全仓 14 处 `class Config:` + auth_routes 三处全部迁移到 `model_config = ConfigDict(from_attributes=True)`
  - `auth_service.py` 中 `datetime.utcnow()` 改用 `datetime.now(timezone.utc)`
- 测试基线最终落点：126 passed, 4 skipped，零 deprecation warning