批次6：D4文档治理收口 + D13锁文件流程固化
D4 文档/规划/历史混放收口：
- docs/TECH_DEBT.md §2 由'按批次回顾'精简为'按主题摘要'，
与§3重复内容（批次0-4详细展开）整体迁入
docs/archive/2026-09_governance_batches.md
- docs/STATUS.md 顶部 2026-09-17 之前条目迁入
docs/archive/2026-09_status_history.md，仅保留指针
- D2 历史口径补齐为 2026-09-18 批次4后续专项清偿
- D4 标已清偿
- AGENTS.md / docs/archive/README.md 同步导航
D13 锁文件流程固化（镜像引入主体已清偿，仅剩锁文件落盘）：
- 新增 deploy/generate_lockfiles.{sh,bat}：在 moldinsight conda
环境（仅项目依赖）执行 pip freeze --exclude pythonocc-core，
产出 deploy/requirements-{base,moldinsight}.lock.txt
- deploy/Dockerfile.moldinsight 注释改为指向生成脚本
- docs/OPERATIONS.md §2.1 增加完整流程说明
- tests/test_lockfile_generation.py 加锁文件存在性+体积契约；
tests/conftest.py 注册 --run-lockfile-check 选项，
默认 skip（仓库单测不阻塞），CI 镜像构建 job 显式启用 fail-fast
遗留：锁文件本身尚未落盘（本机Miniforge跨项目开发栈混装，
污染严重不能直接 pip freeze）；待 CI / 生产首次构建时按流程落锁。
测试基线：126 passed, 9 skipped（默认4原有skip + D13新增5skip；
启用 --run-lockfile-check 时严格断言2项锁文件契约）
Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
+37
-70
@@ -18,59 +18,33 @@
|
||||
|
||||
---
|
||||
|
||||
## 2. 已完成的重要治理（摘要）
|
||||
## 2. 已完成的重要治理（主题摘要）
|
||||
|
||||
以下高价值治理已完成：
|
||||
按主题归类的高价值治理已完成项。每项的具体修复清单 / 迁移号 / 回归测试 / 测试基线见归档：
|
||||
|
||||
- [archive/2026-09_governance_batches.md](archive/2026-09_governance_batches.md)：批次 0–4 + 后续专项 + 2026-09-21 inventory 服务下沉 + 2026-09-22 schema/datetime 弃用清零 的完整流水账
|
||||
- [archive/MOLDINSIGHT_TECH_DEBT_PLAN.md](archive/MOLDINSIGHT_TECH_DEBT_PLAN.md)：更早的设计审查原始计划
|
||||
|
||||
### 2.1 安全与权限
|
||||
- debug/history 路由补鉴权
|
||||
- 任务访问控制收紧
|
||||
- 无主数据不再默认放行
|
||||
- `/api/status/{task_id}` 补 JWT 鉴权与归属校验（原 D5，2026-09-16 清偿，见 D5 条目）
|
||||
- bcrypt 创建口令超 72 字节显式拒绝、验证侧截断比较；`SECRET_KEY` / `RUSTFS_*` 缺失时明确报错，代码侧弱默认移除（D14 部分，2026-09-16）
|
||||
- debug / history 路由补鉴权；任务访问控制收紧；无主数据不再默认放行
|
||||
- `/api/status/{task_id}` 补 JWT 鉴权与归属校验（原 D5 → §3 D5）
|
||||
- bcrypt 超 72 字节显式拒绝 + 截断比较；`SECRET_KEY` / `RUSTFS_*` 缺失明确报错
|
||||
|
||||
### 2.2 静默失败与可用性
|
||||
- `detect-undercuts` 改为基于真实 shape 分析
|
||||
- OCC 超时后重建 executor，避免全队列永久堵死
|
||||
- OCC 超时后重建 executor（短期）→ D10 方案 B 进程化彻底替换
|
||||
- 后台任务统一分派，补强引用与并发控制
|
||||
|
||||
### 2.3 状态存储与缓存
|
||||
- Redis 任务状态改为 Hash 字段级更新，兼容旧格式
|
||||
- 完成态任务视图增加缓存
|
||||
- 导出缓存与持久化链路收口，支持重启后再导出
|
||||
- 内存回退彻底删除，PG 为任务状态单一事实源（原 D7）
|
||||
- 完成态任务视图缓存；导出缓存与持久化链路收口
|
||||
|
||||
### 2.4 架构与代码清理
|
||||
- 删除旧单体入口与死代码
|
||||
- 设置惰性配置校验，提升可测试性
|
||||
- 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 单一来源留待后续批次
|
||||
|
||||
### 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）
|
||||
|
||||
详细历史过程保留在原始技术债文档中，后续将转入归档。
|
||||
- 删除旧单体入口与死代码（`db_manager.create_tables` / `log_user_activity` / `CADExporter.export_mold_results` / `getAluminumPrice` 等）
|
||||
- 惰性配置校验，提升可测试性
|
||||
- Generator 公共接口提取 + 契约测试
|
||||
- 共享 ORM 按模块拆分，跨模块桥接收敛为裸 FK 硬规则（ARCHITECTURE §5.1）
|
||||
|
||||
---
|
||||
|
||||
@@ -86,24 +60,19 @@
|
||||
|
||||
~~原现状 / 影响~~：导出/估算/设计接口混在单文件，边界不清晰、OpenAPI 可读性差、参数校验不统一。
|
||||
|
||||
### D2. 铝价模拟数据未显式标注来源
|
||||
### D2. 铝价模拟数据未显式标注来源 —— 已清偿（2026-09-18，批次 4 后续专项）
|
||||
|
||||
现状：
|
||||
- 铝价服务返回的是模拟/参考数据，但接口层未明确表达
|
||||
修复内容（保留编号以维持引用稳定）：
|
||||
- [src/moldinsight/services/aluminum_price_service.py](../src/moldinsight/services/aluminum_price_service.py)：`get_aluminum_current_price` 响应补 `source: "simulated"`，`get_aluminum_price_history` 逐项补同字段
|
||||
- [frontend/src/modules/home/HomeView.vue](../frontend/src/modules/home/HomeView.vue)：按 `source` 字段渲染"模拟数据 · 参考走势，非实时行情"标注（不再硬编码"上海期货交易所"等虚假来源）
|
||||
- 死代码 `getAluminumPrice` 删除（前端此前保留了一份本地硬编码函数，已无调用方）
|
||||
|
||||
影响：
|
||||
- 容易误导前端与业务使用者，把模拟数据理解为实时行情
|
||||
|
||||
建议：
|
||||
- 响应增加 `source: "simulated"`
|
||||
- 前端界面同步标注“模拟/参考数据”
|
||||
|
||||
优先级：**P2**
|
||||
~~原现状 / 影响~~：铝价接口返回走势数据但无来源声明，前端原硬编码"上海期货交易所"字样，与实际模拟数据不一致，属虚假来源声明。
|
||||
|
||||
### D3. shared/platform 边界仍需继续收敛 —— 主体已清偿（2026-09-17 批次 4 + 2026-09-18 后续）
|
||||
|
||||
已完成部分：
|
||||
- 共享 ORM（原最强耦合点）按模块拆分：base / identity（shared）+ moldinsight/models + inventory/models；跨模块只允许裸 FK，单模块部署 mapper 可独立配置（详见 §2.8 与 [ARCHITECTURE.md](ARCHITECTURE.md) §6.1）
|
||||
已完成部分（修复文件清单见 [archive/2026-09_governance_batches.md](archive/2026-09_governance_batches.md) 批次 4 / 后续专项）：
|
||||
- 共享 ORM（原最强耦合点）按模块拆分：base / identity（shared）+ moldinsight/models + inventory/models；跨模块只允许裸 FK，单模块部署 mapper 可独立配置（详见 [ARCHITECTURE.md](ARCHITECTURE.md) §6.1）
|
||||
- 旧 `shared/models/database.py` 物理删除，无兼容 facade；归属边界由 [tests/test_model_ownership.py](../tests/test_model_ownership.py) 锁定
|
||||
- **app_factory 组合职责收敛**（2026-09-18）：平台工厂只做纯平台引导，`connect_rustfs` 参数移除；moldinsight 专属接线（RustFS 启动钩子 [init_storage.py](../src/moldinsight/storage/init_storage.py) `rustfs_startup_hook`、路由单点聚合 [moldinsight/api/__init__.py](../src/moldinsight/api/__init__.py) `register_moldinsight_routers`）收敛回模块层，入口退化为纯组装（ARCHITECTURE §6.2）
|
||||
|
||||
@@ -112,21 +81,14 @@
|
||||
|
||||
优先级：**P3**（仅剩 identity/platform 语义注释口径）
|
||||
|
||||
### D4. 文档现状 / 规划 / 历史混放
|
||||
### D4. 文档现状 / 规划 / 历史混放 —— 已清偿（2026-09-22）
|
||||
|
||||
现状：
|
||||
- 文档存在部署说明重叠、计划/总结/权威文档混放
|
||||
- README 承担过多职责
|
||||
修复内容（保留编号以维持引用稳定）：
|
||||
- 已建立 `STATUS / ARCHITECTURE / ROADMAP / TECH_DEBT / DEPLOYMENT` 主骨架，每类信息单一归属；历史材料归档至 `docs/archive/`
|
||||
- 本文档 §2 由"按批次回顾"精简为"按主题摘要"，修复文件清单 / 迁移号 / 回归测试 / 测试基线等详细流水账整体迁入 [archive/2026-09_governance_batches.md](archive/2026-09_governance_batches.md)（避免与 §3 重复膨胀）
|
||||
- §3 中对历史批次的引用（如 D3 → §2.8）改为 archive 指针；D2 等已清偿项补齐时间戳
|
||||
|
||||
影响：
|
||||
- 新成员难以判断“哪篇才是当前有效说法”
|
||||
- 状态、部署、规划容易发生漂移
|
||||
|
||||
建议：
|
||||
- 建立 `STATUS / ARCHITECTURE / ROADMAP / DEPLOYMENT` 主骨架
|
||||
- 历史材料迁入 `docs/archive/`
|
||||
|
||||
优先级：**P1**
|
||||
~~原现状 / 影响~~：TECH_DEBT §2 与 §3 内容重复膨胀，文档目录结构清晰度受新成员评估影响。
|
||||
|
||||
### D5. `/api/status/{task_id}` 未鉴权（安全缺口）—— 已清偿（2026-09-16，批次 0）
|
||||
|
||||
@@ -222,13 +184,18 @@
|
||||
- 语义保持：仅切换 Pydantic v2 配置语法 + UTC 时区语义，字段 / OpenAPI / JWT 行为零变化
|
||||
- 验证：`pytest tests/ -q` **126 passed, 4 skipped**，deprecation warning 全部清零
|
||||
|
||||
### D13. PythonOCC 镜像引入方式脆弱 + 依赖无版本锁（主体已清偿，锁文件遗留）
|
||||
### D13. PythonOCC 镜像引入方式脆弱 + 依赖无版本锁（镜像引入已清偿；锁文件流程已固化，待首次构建落盘）
|
||||
|
||||
现状：
|
||||
- ~~从 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 内）
|
||||
- 锁文件流程已固化（2026-09-22）：
|
||||
- 新增 [deploy/generate_lockfiles.sh](../deploy/generate_lockfiles.sh) / [generate_lockfiles.bat](../deploy/generate_lockfiles.bat)：在 moldinsight conda 环境（仅项目依赖，**不能**在混装开发栈跑）执行 `pip freeze --exclude pythonocc-core`，产出 `deploy/requirements-{base,moldinsight}.lock.txt`
|
||||
- [Dockerfile.moldinsight](../deploy/Dockerfile.moldinsight) 注释改为指向生成脚本
|
||||
- [docs/OPERATIONS.md](../docs/OPERATIONS.md) §2.1 增加完整流程说明（生成时机 / 命令 / 产物 / 消费方 / 提交策略）
|
||||
- [tests/test_lockfile_generation.py](../tests/test_lockfile_generation.py) 加锁文件存在性 + 体积契约；默认 skip（仓库单测不阻塞），CI 镜像构建 job 显式 `pytest --run-lockfile-check` 启用
|
||||
- **遗留**：锁文件本身尚未落盘——本机 Miniforge 装的是跨项目开发栈混装环境，污染严重不能直接用 `pip freeze`；须等 CI / 生产机器首次构建 moldinsight 镜像后，按流程跑 `bash deploy/generate_lockfiles.sh` 落锁并提交。已存在护栏：CI 镜像构建 job 跑 `--run-lockfile-check` 后若未落盘会 fail-fast，强制流程走通
|
||||
|
||||
优先级：**P2**（剩余锁文件部分）
|
||||
优先级：**P2**（流程已固化，剩"首次构建后落盘"一次性产物）
|
||||
|
||||
### D14. 配置漂移：弱默认 / 死配置 / 重复解析 —— 已清偿（2026-09-16 ~ 09-17，批次 1 / 3）
|
||||
|
||||
|
||||
Reference in New Issue
Block a user