geMoldInsight/docs/STATUS.md

# geMoldInsight 项目状态（STATUS）

> 文档定位：**唯一的「现在到哪了」**。README / AGENTS / 各主文档只链接到这里，不复制状态内容。
> 维护规则：每完整完成一个需求，**倒序在本文顶部加一条**（日期 + 主题 + 关键事实）；其余主文档（架构 / 规划 / 技术债 / 部署）维护各自的"当前有效说法"，本文只记录"什么时候做到了哪一步"。维护规则出处见根目录 [AGENTS.md](../AGENTS.md)。
> 早期条目（2026-09-17 之前）已精简为锚点，完整流水见 [archive/2026-09_governance_batches.md](archive/2026-09_governance_batches.md) 与 [archive/2026-09_status_history.md](archive/2026-09_status_history.md)。

> 2026-09-26（**端口默认值统一 10003 / 10004**：约定"容器内部端口无所谓，重要的是映射到宿主机的端口；前端页面 = 10003"。① [.env.example](../.env.example) 端口段重写：移除冗余的 `HOST` / `PORT`（uvicorn 命令硬编码，未读取）+ 移除误导性的"应用内部监听端口"注释；新增端口段约定（`FRONTEND_PORT=10003` 浏览器入口、`BACKEND_PORT=10003` 同端口供调试直连、`MOLDINSIGHT_PORT=10003` / `INVENTORY_PORT=10004` 独立模式）；② [docker-compose.yml](../docker-compose.yml) frontend 默认端口回退 `80→10003`、backend 默认 `8000→10003`、删除 backend service 内冗余的 `HOST/PORT` env（uvicorn `--host/--port` 已是单一事实源，env 无代码读）；③ [docker-compose.moldinsight.yml](../docker-compose.moldinsight.yml) / [docker-compose.inventory.yml](../docker-compose.inventory.yml) `MOLDINSIGHT_PORT/INVENTORY_PORT` 默认 `8000/8001→10003/10004`；④ [docs/deployment/DEPLOY_PORT.md](../docs/deployment/DEPLOY_PORT.md) §3 / [docs/deployment/PORT_CONFIG.md](../docs/deployment/PORT_CONFIG.md) §1 §2 端口映射示例同步。**验证**：yaml 渲染后端口映射 `[unified] frontend 10003→80 / backend 10003→8000`、`[moldinsight] 10003→8000`、`[inventory] 10004→8001`，与约定一致。**遗留**：服务器 `.env` 与新版 `.env.example` 对齐（已有字段名一致，仅注释差异，不需要重设值）。
>
> 2026-09-26（**Compose 拆分部署机端到端复验：3 个收尾修复 + 1 处文档澄清**——① `--workdir` 误用修复：[docker-compose.yml](../docker-compose.yml) / [docker-compose.moldinsight.yml](../docker-compose.moldinsight.yml) 中 `moldinsight-celery` 的 `command:` 原照搬旧 Dockerfile.celery 的 `celery worker --workdir=/app/src ...`，celery 5.x 已移除 `--workdir` 选项（部署机实测报 `No such option '--workdir'`），改为 `cd /app/src && exec celery -A celery_app worker ...`——celery_app.py 内 `include=["celery_tasks"]` 为裸模块名，必须在 `src/` 下启动 worker，与是否支持 `--workdir` 解耦，跨 celery 版本稳定；② **裸 `up` 不重建已有镜像**澄清：部署机复用旧 gemold-backend 镜像起容器（旧 miniconda base + 旧代码），`docker compose up -d` 仅在本地无同名镜像时构建，DEPLOYMENT §1.2 / README / OPERATIONS §4 / LINUX_SETUP §11 同步补一句"更新代码后须 `up -d --build` 或先 `docker compose build`"；③ build.sh 步骤由"四步（base→backend→celery→frontend）"修正为"三步（base→backend→frontend，celery 复用 backend 镜像）"——`Dockerfile.celery` 早已删除但 build.sh 与 README 的描述未跟改，三处文档统一收口。**遗留**：服务器 `docker compose up -d --build` 重建验证新 base + 新 celery 启动命令端到端可用。）
>
> 2026-09-24（**Compose 按部署模式拆分为三个一键文件 + 文档全量同步**：① 单文件 profile 编排拆为"模式 ↔ 文件名"一一对应的三文件——[docker-compose.yml](../docker-compose.yml)（unified 默认入口：frontend + backend + moldinsight-celery，`docker compose up -d` 即起）+ [docker-compose.moldinsight.yml](../docker-compose.moldinsight.yml)（moldinsight-only：独立 API + celery）+ [docker-compose.inventory.yml](../docker-compose.inventory.yml)（inventory-only：仅 inventory，不声明任何命名卷避免空卷）；② **服务不再声明 `profiles`**——compose 规则是声明了 profiles 的服务在裸 `up` 下不会被选中（拆分首版保留 profiles 导致裸 `up` / 裸 `-f` 均报 `no service selected`，部署机实测暴露后移除），模式切换唯一入口是 `-f` 文件名，历史 `--profile full/moldinsight/inventory` 写法随拆分失效（其目标服务本就已移出默认文件，兼容无意义）；③ **顺手修复两个既有部署隐患**——moldinsight-only 场景 celery 的 `depends_on` 悬空（原指向被 profile 过滤掉的 `backend`，现各文件内分别指向 `backend` / `moldinsight`），以及 `gemold-moldinsight:latest` 与 `gemold-backend:latest` 双 tag 漂移（moldinsight service 的 image 统一为 `gemold-backend:latest`，与 [Dockerfile.celery](../deploy/Dockerfile.celery) 的 FROM 对齐，干净环境单跑 moldinsight-only 不再构建失败）；④ `gemold_network` / `uploads_data` / `html_data` 加 `name:` 固定命名，跨文件 / 跨模式可复用；每文件内部以 YAML anchor（`x-base-env`）收敛 35+ 行重复 environment，`SECRET_KEY` / `ADMIN_PASSWORD` 的 `${VAR:?}` fail-fast 校验保留；⑤ 文档同步 11 文件：[DEPLOYMENT.md](DEPLOYMENT.md) §1.1 新增一键部署总表 + §2 三模式各附文件名与一键命令，[deployment/LINUX_SETUP.md](deployment/LINUX_SETUP.md) §6/§11 重写，[README.md](../README.md) 快速开始与 Compose 入口、[OPERATIONS.md](OPERATIONS.md) §4、[deploy/build.sh](../deploy/build.sh) / [.bat](../deploy/build.bat) 末尾提示、PORT_CONFIG / DEPLOY_PORT / STORAGE_SETUP / frontend/README 链接全部对齐（`AGENTS.md` §4.1 部署方式→DEPLOYMENT 同步规则满足）；⑥ **部署机首次实测再暴露并修复两个干净机器构建必挂点**——(a) [.dockerignore](../.dockerignore) 自"重写独立dockerfile"起排除整个 `deploy/`，而 Dockerfile.frontend 要 COPY `deploy/nginx/frontend.conf`、Dockerfile.moldinsight 要 COPY `deploy/requirements-*.txt`（历史一直有旧镜像兜底未暴露；BuildKit 不支持重包含被排除目录的子文件，直接移除该行，deploy/ 仅几 KB 无上下文负担）；(b) `Dockerfile.celery` `FROM gemold-backend:latest` 在 compose 并行构建下引用尚不存在的本地镜像必挂——**删除 Dockerfile.celery**，`moldinsight-celery` 改为与 API 服务**同一 build 声明 + 同一 `gemold-backend:latest` tag**（compose 去重只构建一次），celery 仅以 `command:` 覆盖启动 worker（`--concurrency` / `--max-tasks-per-child` 参数经 compose 命令与 `.env` 透传，语义不变），build.sh/.bat 移除 gemold-celery 构建步骤，OPERATIONS / OCC_THROUGHPUT / TECH_DEBT / .env.example 的 Dockerfile.celery 指向同步改写；⑦ **镜像 base 由 miniconda 切换 Miniforge**——[Dockerfile.moldinsight](../deploy/Dockerfile.moldinsight) FROM `continuumio/miniconda3:24.7.1-0` → `condaforge/miniforge3:24.7.1-2`（conda-forge 默认且唯一渠道，无 defaults 渠道与 Anaconda ToS 顾虑；与 CI 已用的 Miniforge 安装、开发机 Miniforge 同源；tag 经 Docker Hub 社区用例确认存在；conda create 步骤与 python=3.12 / pythonocc-core=7.9.0 锁定不变），[TECH_DEBT.md](TECH_DEBT.md) D13 锁定记录同步。**验证**：三文件 YAML 解析 + 结构静态校验通过（services / depends_on / 卷声明 / anchor 合并 / 网络命名 / 无 profiles 残留 / celery 与 API 服务 build 声明一致性）；5 个 service 的 environment 键与拆分前逐一比对（YAML 展开合并键后 39/39、34/34、39/39、34/34、20/20）零丢失。**遗留**：部署机 `git pull` 后裸 `docker compose up -d` 端到端复验；base 镜像（miniconda3 / node / nginx）拉取依赖 docker.io 连通性，不通时需配镜像加速。
>
> 2026-09-24（**D17 Human-in-Loop 老师傅经验反馈批 3 上线（前端按钮 + Dialog + 经验角标）——闭环可视**：① [ResultView.vue:35-47](frontend/src/modules/moldinsight/ResultView.vue#L35-L47) 方案卡片 summary-header 加 `t-tag theme="success" variant="light"` 经验角标（"📚 历史经验 N 条"），从 `hintsByAxis[currentAxisHint]` 读取，按 scheme_axis 索引，无 hints 时不渲染；② [ResultView.vue:131-138](frontend/src/modules/moldinsight/ResultView.vue#L131-L138) `export-buttons-bar` 加 `👍 老师傅反馈` 按钮（`v-if="canGiveFeedback"` 角色门控：admin 或 process_engineer）；③ 新建 [components/HumanFeedbackDialog.vue](frontend/src/modules/moldinsight/components/HumanFeedbackDialog.vue)：t-dialog + t-form + t-radio-group 三选一（采纳 / 建议调整 / 拒绝）+ t-textarea 原因 + 调整建议（仅 adjust 模式显隐）；提交走 `moldinsightApi.submitExperienceFeedback`，成功后 emit `submitted` 让父组件重拉 hints 刷新角标；④ [shared/api-client.ts:407-444](frontend/src/shared/api-client.ts#L407-L444) `moldinsightApi` 新增 `getExperienceHints` / `submitExperienceFeedback` 两个方法（生成类型由 openapi-typescript 自动产出）；⑤ [ResultView.vue](frontend/src/modules/moldinsight/ResultView.vue) `onMounted` 调 `loadExperienceHints` 拉一次 + 反馈提交后 `onFeedbackSubmitted` 再拉一次（写入即消费前端可见）；`canGiveFeedback` 走 `is_superuser || roles 含 process_engineer` 表达式（项目硬规则"前端不要破坏 ResultView.vue 视觉一致性"：按钮与既有 6 个 t-button 同一 `export-buttons-bar`，theme/size 一致；角标 theme="success" variant="light" 与既有 t-tag theme="primary" / "warning" 同款）。**接口变更三件套随批完成**：openapi.json 重导出（2 个新 path，含 ExperienceFeedbackCreate / ExperienceHintItem / ExperienceHintsResponse 三个新 schema）→ `npm run gen:api` 再生 types/api.ts → `npm run build` 通过。**后端基线**：**192 passed, 13 skipped**（批 3 不改后端）；**前端构建**：vue-tsc + vite 通过，ResultView 包大小 37.18 kB / 11.91 kB gzip。**D17 闭环端到端可用**：admin / process_engineer 在 ResultView 点"👍 老师傅反馈" → Dialog 选"采纳"+ 写原因 → 提交 → 角标即时刷新（重拉 hints）；下次同指纹 STP 分析，`PartingCandidateGenerator` 候选方向加成 + `PartingSchemeScorer` total_score 加成 + method 标签升级 `human_experience_primary`。**下一步**：批 4（衰减机制完善 + DFM 规则库独立模块化 + 经验冲突仲裁 UI）按需排期。）

> 2026-09-23（**D17 Human-in-Loop 老师傅经验反馈批 2 上线（算法接缝 + OCC payload 通道）——闭环通**：① 算法层 4 个核心文件加 `hints` 形参透传链：[parting_candidate_generator.py:13-66](src/moldinsight/core/parting_candidate_generator.py#L13-L66) `_build_axis_metrics` 末尾按 hints 加成（`weight × 20` 上限，`sample_count ≥ 2 + weight ≥ 0.5` → method 标签升级 `human_experience_primary`）；[parting_scheme_scorer.py:8-46](src/moldinsight/core/parting_scheme_scorer.py#L8-L46) `_score_scheme` 新增 `human_hint_bonus` 字段（weight × 12 上限，sample_count < 2 时 ×0.5 折半），纳入 total_score；[multi_scheme_planner.py:26-86](src/moldinsight/core/multi_scheme_planner.py#L26-L86) `generate_plan` 透传 hints 到下两层，`global_summary.applied_hints` 注入返回；② [processing_service.py:531-595](src/moldinsight/services/processing_service.py#L531-L595) `_step_generate_cavity` 调 `experience_feedback_service.resolve_for_process_params` 拿同指纹 hints，装进 run_occ payload 顶层 `experience_hints` 字段（普通 dict 透传，pickle 安全，满足 [occ_worker.py:7-8](src/moldinsight/core/occ_worker.py#L7-L8) 硬规则）；③ [occ_worker.py:117-140](src/moldinsight/core/occ_worker.py#L117-L140) `_op_generate_cavity` 读 `payload.get("experience_hints") or {}` 透传给 `planner.generate_plan(..., hints=...)`；④ D17 闭环验证：老师傅写一条同指纹 `adopted` → 同 X 通道下次分析 `priority_score` +18，`score_breakdown.human_hint_bonus` +12（sample_count=3），method 标签升级 `human_experience_primary`。**接口面零变化**（路径 / schema 不动；仅 OCC 子进程内部响应含 `global_summary.applied_hints`，由前端 ResultView 渲染角标——批 3 实现）。**测试基线**：**192 passed, 13 skipped**（批 2 净增 7 通过 + 4 OCC-gated skip：candidate_generator 3 例 / scheme_scorer 4 例在无 OCC 环境跑通，multi_scheme_planner + processing_service 4 例 OCC-gated 待 conda `gemold` 镜像验证）。**接口变更三件套执行节点**：openapi.json 重导出与前端 `gen:api` 待批 3 完成后一并执行（前端调用两 path + ResultView 渲染一并改）。**下一步**：批 3 前端（ResultView 按钮组 + `HumanFeedbackDialog.vue` + `moldinsightApi` 两个方法 + 经验角标）。）

> 2026-09-23（**D17 Human-in-Loop 老师傅经验反馈批 1 上线（数据 + 权限 + 写入 API）**：① 新增 `experience_feedback` 表（32 表迁移，alembic head `b7d1f4a92c3e`）——老师傅对系统推荐方案给出"采纳 / 调整 / 拒绝"反馈，按"产品指纹 + 工艺参数"为键跨任务匹配，下次同指纹产品分析自动消费；② 新增 3 个权限码（`view_experience_feedback` / `feedback_experience_hint` / `manage_experience_feedback`）+ 新角色 `process_engineer`（含 view + feedback 权限，admin 角色 permissions 同步补齐）；③ 新增 2 个端点（`POST /api/tasks/{task_id}/experience-feedback` 提交反馈 + `GET /api/tasks/{task_id}/experience-hints` 拉取同指纹历史 hints 摘要）；④ `init_db.py` 幂等 bug 修复——既有 DB 启动期不再跳过新增权限 / 角色补登（`init_permissions` / `init_roles` 改为按 code 比对，新增保留已有 id）；⑤ ORM / 迁移 / service / router / api 注册均落位：D9 边界（service.flush + 路由 commit）；D17 衰减（写新反馈时同 `stp_file_id` 整体续期 90 天 TTL）；`User.has_permission` 全仓首次调用点（[src/shared/models/identity.py:38](src/shared/models/identity.py#L38) 此前仅定义零调用）。**接口面新增 2 path**（openapi.json 重导出随批 3 一并执行——批 2 OCC payload 接缝改了 `/api/status/{task_id}` 实际响应结构需等到 OCC 集成落地再重导出）。**测试基线**：**185 passed, 9 skipped**（批 1 净增 59 测试，含 `compute_fingerprint` 分桶参数化覆盖 bbox / volume / face / undercut / material / is_foam 各边界值 + API 契约 401/403/422/200 路径 + 衰减续期 + 任务归属校验 + ORM 注册收口）。**下一步**：批 2 算法接缝（PartingCandidateGenerator / PartingSchemeScorer / MultiSchemeMoldPlanner 透传 hints + OCC worker payload `experience_hints` 通道）+ 批 3 前端按钮 + 反馈 Dialog + 经验角标渲染。）

> 2026-09-22（**Pydantic v2 schema 配置升级 + `datetime.utcnow()` 弃用清零**：① 全仓 14 处 `class Config`（[src/inventory/schemas](../src/inventory/schemas/)）+ [src/shared/services/auth_routes.py](../src/shared/services/auth_routes.py) 三处全部迁移到 `model_config = ConfigDict(from_attributes=True)`；② [src/shared/services/auth_service.py](../src/shared/services/auth_service.py) 中 `datetime.utcnow()` 改用 `datetime.now(timezone.utc)`，消除遗留 `DeprecationWarning`；③ 一次跑通 `pytest tests/ -q` 全量无 deprecation 警告，全仓 `from_attributes=True` 语义保持不变，未触发 OpenAPI 漂移。**测试基线**：**126 passed, 4 skipped**（与上一批次一致，无回归）。）
>
> 2026-09-22（**D13 锁文件流程固化：镜像引入已清偿 + 落锁流程就绪**：① 新增 [deploy/generate_lockfiles.sh](../deploy/generate_lockfiles.sh) / [.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` 启用 fail-fast。**遗留**：锁文件本身尚未落盘——本机 Miniforge 装的是跨项目开发栈混装环境，污染严重不能直接用 `pip freeze`；须等 CI / 生产机器首次构建 moldinsight 镜像后按流程落锁。**测试基线**：**126 passed, 9 skipped**（默认 4 个原有 skip + D13 新增 5 个 skip；启用 `--run-lockfile-check` 时严格断言 2 项锁文件契约）。）
>
> 2026-09-02 起（含 09-17 之前基线条目）的完整内容见 [archive/2026-09_status_history.md](archive/2026-09_status_history.md)。
>
> 2026-09-21（**inventory 仪表盘聚合服务下沉完成：dashboard 薄路由化**：① 新增 [dashboard_service.py](../src/inventory/services/dashboard_service.py)，将仪表盘首页所需的基础主数据统计、物料库存总量/总值、待处理采购/销售单数、低库存预警列表等聚合查询从路由层下沉到 service；② [dashboard_routes.py](../src/inventory/api/dashboard_routes.py) 改为单行委托薄路由，inventory 主要业务域路由已基本完成 service orchestration 收口；③ 新增 [test_api_dashboard_service.py](../tests/test_api_dashboard_service.py)，覆盖 seeded summary 与低库存预警两条 API 回归。**接口面零变化**（无 openapi 漂移）。**测试基线**：**126 passed, 4 skipped**；新增 dashboard 回归 **2 passed**。）
>
> 2026-09-21（**inventory 产品域跨模块桥接收口完成：`/api/products/from-task/{task_id}` 下沉至 `product_service`**：① [product_service.py](../src/inventory/services/product_service.py) 新增 `create_product_from_task`，将 ProcessingTask / STPFile 查询、已绑定成品幂等返回、`MI{stp_file_id}` SKU 冲突递增、分析结果摘要拼装、成品创建与 `stp_files.product_id` 回写从路由层下沉到 service；② [product_routes.py](../src/inventory/api/product_routes.py) 现已全量薄路由化，产品域 CRUD / BOM / from-task 三类接口统一改为 service orchestration；③ 扩展 [test_api_product_service.py](../tests/test_api_product_service.py) 与 [tests/conftest.py](../tests/conftest.py)，补 `STPFile` / `ProcessingTask` 种子及 from-task 创建、重复调用幂等、任务不存在 404 回归。**接口面零变化**（无 openapi 漂移）。**测试基线**：**124 passed, 4 skipped**；product 域回归现为 **14 passed**。）
>
> 2026-09-21（**inventory 产品域第二批服务下沉完成：product CRUD / BOM 薄路由化，`from-task` 保持独立**：① 新增 [product_service.py](../src/inventory/services/product_service.py)，将产品列表、创建、更新、软删除、BOM 查询与 BOM 替换编排从 [product_routes.py](../src/inventory/api/product_routes.py) 下沉到 service 层；② `product_routes` 中除跨模块的 `/api/products/from-task/{task_id}` 仍保留在路由层外，其余端点已改为薄路由委托，inventory 侧形成 `master_data / material / product / purchase_order / sales_order` 一致的 service orchestration 结构；③ 新增 [test_api_product_service.py](../tests/test_api_product_service.py) 覆盖成品物料成本聚合、创建成品库存上下限归零、重复 SKU 校验、软删除、BOM 明细/重建及多条语义校验路径。**接口面零变化**（无 openapi 漂移）。**测试基线**：**122 passed, 4 skipped**；新增 product 回归 **12 passed**。下一刀再处理 `from-task` 与更深的 moldinsight/BOM 交叉编排。）
>
> 2026-09-21（**inventory 物料域服务下沉完成：price-history / price-trend / material-supplier 薄路由化**：① 新增 [material_service.py](../src/inventory/services/material_service.py)，将物料价格历史、价格趋势、物料-供应商关联与按供应商反查物料的业务编排从路由层下沉到 service 层；② [material_routes.py](../src/inventory/api/material_routes.py) 改为薄路由，仅保留依赖注入、参数校验与 service 调用，inventory 侧继续延续 `inventory_service` / `master_data_service` / `purchase_order_service` / `sales_order_service` 的结构收口方向；③ 新增 [test_api_material_service.py](../tests/test_api_material_service.py) 覆盖价格历史新增、趋势汇总、缺历史 404、供应商关联查询/删除、重复关联与非法物料/供应商校验等回归；④ 顺手修复该链路的两个既有结构问题：`PriceHistoryItem` 未从 [inventory.schemas](../src/inventory/schemas/__init__.py) 导出导致 service 导入失败；异步 ORM 读路径原本依赖 `ph.supplier` / `ms.supplier` / `ms.product` 懒加载，测试环境下触发 `MissingGreenlet`，现统一改为显式 join 构造响应。**接口面零变化**（无 openapi 漂移）。**测试基线**：**110 passed, 4 skipped**；新增物料域回归 **10 passed**。）
>
> 2026-09-21（**inventory 主数据第一批服务下沉完成：customer / supplier / warehouse 薄路由化**：① 新增 [master_data_service.py](../src/inventory/services/master_data_service.py)，将客户/供应商/仓库的列表查询、自动编码（`C`/`S`/`W`）、更新、软删除等 CRUD 编排从路由层下沉到 service 层；② [customer_routes.py](../src/inventory/api/customer_routes.py)、[supplier_routes.py](../src/inventory/api/supplier_routes.py)、[warehouse_routes.py](../src/inventory/api/warehouse_routes.py) 改为薄路由，仅保留依赖注入、参数校验与 service 调用，inventory 侧延续既有 `inventory_service` / `purchase_order_service` / `sales_order_service` 的结构收口方向；③ 新增 [test_api_inventory_master_data.py](../tests/test_api_inventory_master_data.py) 覆盖 customer/supplier/warehouse 的搜索、自动编码、更新回包、软删除与默认仓排序回归；④ 顺手修复 inventory 主数据链路两个既有问题：此前 create/update/delete 只 `flush` 不 `commit`，跨请求 session 下后续读写看不到刚创建实体；时间戳到秒的自动编码在同秒连续创建时会撞唯一约束，现改为微秒粒度编码。**接口面零变化**（无 openapi 漂移）。**测试基线**：**100 passed, 4 skipped**；新增主数据回归 **10 passed**。）

> 2026-09-18（**批次 4 后续专项五项完成：D11 清偿 + 部署参数 + D2 诚实标注 + CI 门禁 + OCC 方案 B 实施**：① **D11 清偿**（TECH_DEBT P2）——可视化报告 RustFS 单源化：写侧 HTMLGenerator 每任务写临时目录，`.html`/`_summary.json`/`_data.json` 三件统一裸传 RustFS 报告键 `html/reports/{filename}`（文件名寻址），`/html` StaticFiles 本地挂载删除，新增 [html_report_router.py](../src/moldinsight/api/html_report_router.py) 根路径代理（报告键直取 → 遗留 `html/{hash}.json` JSON 包装解析 → 本地卷存量兜底 → 404；URL 形状 `/html/{filename}` 不变，持久化 cavity JSON 与前端 iframe 引用零迁移）；celery 服务摘除 `html_data` 卷，Dockerfile.moldinsight 删除 `COPY html_output/`（构建机陈旧报告不再进镜像）；已知约束：报告路由不做认证（iframe 无法携带 Authorization 头，沿用 StaticFiles 时代既定姿态，文档已声明）；顺带删除 `get_stp_file_with_data` 的死数据块（`html_content` 组装零消费方，此前每次完成任务查询白下载数 MB 正文）。② **OCC 方案 A 参数落地**——`CELERY_CONCURRENCY`/`CELERY_MAX_TASKS_PER_CHILD` 进 [Dockerfile.celery](../deploy/Dockerfile.celery) ENV + compose 透传 + `.env.example`。③ **D2 清偿**——铝价响应带 `source: "simulated"`，[HomeView.vue](../frontend/src/modules/home/HomeView.vue) 按来源渲染"模拟数据 · 参考走势"标注（原硬编码"上海期货交易所"属虚假声明），死代码 `getAluminumPrice` 删除。④ **CI 门禁**——[.gitea/workflows/ci.yml](.gitea/workflows/ci.yml) 三 job：pytest 全量 / 前端构建（含 vue-tsc）/ openapi 漂移检测（conda pythonocc 环境重导出比对；已实测 pytest 与导出均不依赖 .env）。⑤ **OCC 方案 B 实施**（TECH_DEBT D10 清偿）——`run_occ(fn, *args)` → `run_occ(op_name, payload)`，执行器由线程池替换为常驻工作进程池 [occ_process_pool.py](../src/moldinsight/services/occ_process_pool.py) + 操作注册表 [occ_worker.py](../src/moldinsight/core/occ_worker.py)：超时/崩溃 terminate 换新补位、任务级超时 recover 整体重建，**残留线程泄漏根治**（进程边界回收 C++ 栈）；TopoDS 形状不跨进程（`generate_cavity` 分模 + 方案 STEP 持久化导出全在子进程内，返回 export_manifest）；调用点全量迁移（解析/网格/型腔/分析/倒扣/STEP 转换），删除内存形状缓存链（`_cache_export_shapes`/`get_export_shapes`/`_persist_step_exports`）、`CADExporter.export_mold_results`（零调用方）、shape_loader（→ [stp_materializer.py](../src/moldinsight/services/stp_materializer.py)）；回归测试 [test_occ_process_pool.py](../tests/test_occ_process_pool.py)（OCC-gated，6 例含真实盒体 STP 解析/分模端到端）。**接口变更三件套随批完成**：openapi.json 重导出（76→77 paths，新增 `/html/{filename}`）+ 前端 `gen:api` 再生 + 前端构建通过（方案 B 接口面零变化，无路由/schema 变更）。**测试基线**：**143 passed, 0 skipped**（D11 8 项 + 铝价 2 项 + OCC 进程池 6 项；基线 129 中原 2 个 skip 已随本地环境补齐 celery/alembic 转为执行）。**下一步**：回到 §3 主线 P2/P3 长期方向——D3 剩余收敛（app_factory 参数收敛、identity/platform 语义）、inventory 服务下沉、D13 pip 锁文件随下次镜像构建补齐，见 [ROADMAP.md](ROADMAP.md) §3。）

> 2026-09-17（**批次 4（架构演进）完成，§3.1 治理批次全部执行完毕**：① D3 主体清偿——891 行的旧 `shared/models/database.py`（31 模型类三类同居，已删除）按归属拆为 [shared/models/base.py](../src/shared/models/base.py)（唯一 Base）+ [shared/models/identity.py](../src/shared/models/identity.py)（身份权限 7 表）+ [moldinsight/models/](../src/moldinsight/models/)（分析域 9 表）+ [inventory/models/](../src/inventory/models/)（进销存 15 表，catalog/warehouse/trading/finance 四文件）；**三条跨模块 ORM relationship（`User.stp_files` / `STPFile.user` / `STPFile.product`）经全仓核实零使用，直接删除**——跨模块桥接收敛为裸 FK 硬规则（[ARCHITECTURE.md](ARCHITECTURE.md) §5.1），单模块部署 mapper 可独立配置；约 45 处 import 全量改写（含 migrations/env.py 全量注册、scripts/ 两个一次性脚本），旧模块物理删除无兼容 facade；零调用方死方法 `db_manager.create_tables` 一并删除（拆分后会静默建残缺 schema）；② D10 治理——`_reset_occ_executor` 补 `cancel_futures=True`（旧实现下"慢恢复"的旧线程会继续消化旧队列，与新 executor **并发操作非线程安全的 OCC**，属数据竞争而非单纯泄漏）；吞吐方案设计先行定稿 [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` 契约进程化 + kill-on-timeout，待独立排期）；③ 新增 [tests/test_model_ownership.py](../tests/test_model_ownership.py) 锁定归属边界（31 表全量注册 / 单模块独立 mapper 配置 / 旧模块无 facade）；④ 顺手清偿 D15——[vite.config.ts](../frontend/vite.config.ts) 删除未用的 `mode` 参数，`vue-tsc -b` 恢复通过，前端生产构建链路解除阻断。**接口面零变化**（无路由与 schema 变更，openapi.json 不触发重导出）。**测试基线**：**125 passed, 2 skipped**（基线 122 + 新增归属测试 3 项）。**下一步**：治理批次收尾后回到主线方向；遗留项 D11（HTML RustFS 单源）、D13（pip 锁文件）、OCC 方案 B 独立批次。）

> 2026-09-17（**批次 3（API 与代码结构）完成**：① D1 清偿——592 行 advanced_router 拆为 [design_router](../src/moldinsight/api/design_router.py) / [cost_router](../src/moldinsight/api/cost_router.py) / [machining_router](../src/moldinsight/api/machining_router.py) / [export_router](../src/moldinsight/api/export_router.py) 四个子路由（端点路径不变），请求体全量 Pydantic 模型化（`request.json()` 手动解析退役，校验统一 422）；② 路由装载失败显式化：`ROUTE_MODULES` 清单 + [route_registry](../src/moldinsight/api/route_registry.py)，失败经 `/api/health` 呈现 `degraded` 并列出清单（`pythonocc` 改真实探测），DEBUG 下 fail fast——此前失败仅 WARNING 后静默跳过，进程带病启动不可感知；③ 纯 Python 重计算端点（设计/加工/CAM 打包）统一 `asyncio.to_thread` 投放线程池，不再阻塞事件循环（OCC 仍走单线程 executor，D10 留批次 4）；④ `StorageIntegrationService`（867 行）按职责拆为 [task_storage](../src/moldinsight/services/task_storage_service.py) / [analysis_storage](../src/moldinsight/services/analysis_storage_service.py) / [file_history](../src/moldinsight/services/file_history_service.py) 三服务，无调用方死代码 `log_user_activity` 删除；⑤ D14 收尾清偿——`MAX_FILE_SIZE` 接线生效（默认上限 50MB→100MB，以 .env 为准）、celery_app 复用 `Settings.redis_url`（连接串唯一拼装点）。**连带修复**：管理员重置密码改 JSON body `{ new_password }`（原裸 str 参数被解析为 query param，前端两个调用点均发 body，功能端到端断裂）+ [UsersView.vue](../frontend/src/modules/users/UsersView.vue) 同步；Dockerfile.celery 的 FROM 对齐 `gemold-backend:latest`（此前引用不存在的 tag，干净环境 celery 镜像必构建失败）。**接口变更三件套随批完成**：openapi.json 重导出（76 paths）+ 前端 `gen:api` 再生。**连带发现**：`npm run build` 因 vite.config.ts 既有 TS6133 失败（与本项目改动无关，登记 D15）。**测试基线**：**122 passed, 2 skipped**（新增 4 个测试文件共 17 项：[test_advanced_split_contract](../tests/test_advanced_split_contract.py) / [test_route_load_status](../tests/test_route_load_status.py) / [test_config_governance](../tests/test_config_governance.py) / [test_auth_password_reset](../tests/test_auth_password_reset.py)；skips 为 alembic / celery 缺失环境）。**下一步**：批次 4（架构演进：共享 ORM 拆分、OCC 吞吐方案，见 [ROADMAP.md](ROADMAP.md) §3.1）。）

> 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`。）

> 上一条：2026-09-02（**模块化收口 + 文档主骨架建立（基线条目）**：代码侧完成 moldinsight 技术债治理——安全收口（debug/history 权限补齐、任务访问控制收紧）、静默失败修复（`detect-undercuts` 基于真实 shape 重建）、OCC 超时后 executor 重建防毒化全队列、后台任务统一分派、Redis 任务状态改 Hash 原子更新、完成态任务视图缓存、导出缓存与持久化收口、旧入口与死代码删除、Generator 公共接口提取 + 契约测试；详见 [TECH_DEBT.md](TECH_DEBT.md) §2。结构侧完成 `src/entrypoints/` 三入口拆分（moldinsight / inventory / unified）、`shared` 平台能力集中、前端独立 `frontend/` 工程。文档侧建立 `STATUS / ARCHITECTURE / ROADMAP / TECH_DEBT / DEPLOYMENT` 主骨架，README 收敛为唯一导航入口，历史材料迁入 [archive/](archive/README.md)。**测试基线**：本地 pip 环境 **47 passed, 1 skipped**（pythonocc 缺失自动 skip）；moldinsight conda + OCC 环境 **88 passed**。inventory 侧少量既有 deprecation warnings 不影响通过。）

> 此前：2026-09-01（**文档体系专项整理启动**：明确「README 只做导航、每类信息单一归属、历史材料进 archive」的文档治理原则；建立 deployment/ 主题目录与 archive/ 归档目录；部署文档收口为 DEPLOYMENT（入口）+ deployment/LINUX_SETUP（操作）+ deployment/DEPLOY_PORT / PORT_CONFIG（端口补充）三层。）