D17 批 1：Human-in-Loop 老师傅经验反馈（数据 + 权限 + 写入 API）

新增 experience_feedback 表（32 表迁移，alembic head b7d1f4a92c3e），老师傅对系统推荐方案给出"采纳 / 调整 / 拒绝"反馈，按"产品指纹 + 工艺参数"为键跨任务匹配，下次同指纹产品分析自动消费。变更内容： - src/moldinsight/models/experience_feedback.py（new）ORM：Base 单点来源、跨模块裸 FK（user_id / processing_task_id / stp_file_id）、不建 ORM relationship；fingerprint JSON 列存跨任务匹配键 - src/moldinsight/models/__init__.py 导出 ExperienceFeedback - migrations/versions/b7d1f4a92c3e_add_experience_feedback.py（new）32 表迁移；fingerprint 列 PG 下加 GIN 索引（jsonb_path_query 支持） - src/shared/database/init_db.py 加 3 个权限码（view_experience_feedback / feedback_experience_hint / manage_experience_feedback）+ 新角色 process_engineer；admin 角色 permissions 同步补齐；init_permissions / init_roles 改为按 code 比对（新增保留已有 id，避免 FK 引用失效）—— 修复既有 DB 启动期漏掉新权限的幂等 bug - src/moldinsight/services/experience_feedback_service.py（new）service： compute_fingerprint 分桶（bbox_aspect / volume_bucket / face_bucket / undercut_class / material_family / is_foam）/ record_feedback（D9 边界： service.flush + 路由 commit；D17 衰减：同 stp_file_id 整体续期 90 天 TTL，无 celery beat 依赖）/ list_hints_for_task / resolve_for_process_params - src/moldinsight/api/experience_feedback_router.py（new）路由：Pydantic 模型写在路由文件内（项目硬规则）；POST /api/tasks/{task_id}/experience-feedback + GET /api/tasks/{task_id}/experience-hints；归属 TaskQueryService.ensure_task_access + User.has_permission 全仓首次调用点 - src/moldinsight/api/__init__.py ROUTE_MODULES 注册新路由 - tests/test_model_ownership.py EXPECTED_TABLES 加 experience_feedback （31→32） - tests/test_experience_feedback_fingerprint.py（new）分桶参数化覆盖 bbox / volume / face / undercut / material / is_foam 各边界值 - tests/test_experience_feedback_router.py（new）API 契约 9 例（401/403/422/200 路径 + 衰减续期 + 任务归属校验 + ORM 注册收口） - docs/STATUS.md 顶部加 2026-09-23 批 1 日志条目 - docs/TECH_DEBT.md D17 加批 1 已完成描述 + 剩余工作清单 - docs/API_CONTRACT.md §3.2 加 D17 端点表格测试基线：185 passed, 9 skipped（净增 59 测试）。 Co-Authored-By: Claude Code <noreply@anthropic.com>
2026-09-23 16:11:17 +08:00
parent 79441a8a87
commit 2c9ba9d6b3
13 changed files with 1338 additions and 26 deletions
@@ -54,6 +54,7 @@
 | 加工 | `/api/design-cam`、`/api/check-collision`、`/api/optimize-toolpath`、`/api/design-electrodes`、`/api/simulate-machining` | machining_router.py |
 | 导出 | `/api/export-mold`、`/api/export-download/{filepath}`、`/api/export-recommendations` | export_router.py |
 | 铝价（模拟数据） | `/api/aluminum-price/current`、`/api/aluminum-price/history` | aluminum_price_routes.py |
+| 老师傅经验反馈（D17） | `/api/tasks/{task_id}/experience-feedback`（写入：需登录 + 任务归属 + `feedback_experience_hint` 权限；body 含 `scheme_id` / `feedback_status ∈ {adopted, adjust, rejected}` / 可选 `feedback_reason` / `adjust_suggestion` / 上下文快照；写完调用 `TaskQueryService.invalidate_task_view`）；`/api/tasks/{task_id}/experience-hints`（读取：需登录 + 任务归属；返回同 stp_file_id + material_family + is_foam 锚定的历史 hints 聚合，按 scheme_axis 分组，含 adopted/rejected/adjust 计数 + 加权 confidence + sample_count + 回显 fingerprint） | experience_feedback_router.py |
 | 健康检查 | `/api/health`（有路由装载失败时 `status: degraded` 并列出失败清单；`pythonocc` 为真实探测） | health_router.py |
 | 调试（仅 DEBUG） | `/api/debug/tasks` | debug_router.py |

@@ -4,6 +4,8 @@
 > 维护规则：每完整完成一个需求，**倒序在本文顶部加一条**（日期 + 主题 + 关键事实）；其余主文档（架构 / 规划 / 技术债 / 部署）维护各自的"当前有效说法"，本文只记录"什么时候做到了哪一步"。维护规则出处见根目录 [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-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 项锁文件契约）。）
@@ -213,6 +213,27 @@

 ~~原现状 / 影响~~：`vue-tsc -b`（`npm run build` 的类型检查步）因既有 TS6133 失败，前端无法出生产包（与批次 3 改动无关的既有问题）。

+### D17. 算法成熟度距"老师傅经验"差距 + Human-in-Loop 闭环 —— 批 1 已清偿（2026-09-23）
+
+**背景**：现有算法（分模 / 倒扣 / 评分 / DFM 校验）是 OCC BREP 上的工程启发式，距模具师傅"看完就知道该咋改"的实战经验仍有结构性差距——倒扣邻接聚类缺失、滑块 / 斜顶设计是纯几何启发、DFM 规则库仅 4 条、评分权重拍脑袋（详见 2026-09-22 用户对话评估）。
+
+**方案**：引入 Human-in-Loop 闭环——老师傅对系统推荐方案给出"采纳 / 调整 / 拒绝"反馈，以"产品指纹 + 工艺参数"为索引跨任务匹配，**下次同指纹产品分析自动消费这些经验**（OCC worker payload 透传 → MultiSchemeMoldPlanner → PartingSchemeScorer 加成）。老师傅的经验以结构化数据沉淀，避免成为"知识库坟墓"。
+
+**批 1 已完成（数据 + 权限 + 写入 API）**：
+- 新增 `experience_feedback` 表（alembic head `b7d1f4a92c3e`，32 表迁移），含 fingerprint JSON 列（PG 下 GIN 索引支持 jsonb_path_query）
+- 3 个权限码（`view_experience_feedback` / `feedback_experience_hint` / `manage_experience_feedback`）+ 新角色 `process_engineer`；admin 角色 permissions 同步补齐
+- `init_db.py` 幂等 bug 修复——既有 DB 启动期不再跳过新增权限 / 角色补登（`init_permissions` / `init_roles` 改为按 code 比对，新增保留已有 id，避免 FK 引用失效）
+- 新增端点 `POST /api/tasks/{task_id}/experience-feedback`（提交方案级反馈；`TaskQueryService.ensure_task_access` 归属校验 + `User.has_permission` 全仓首次调用）+ `GET /api/tasks/{task_id}/experience-hints`（按 material_family + is_foam 锚定的历史聚合）
+- D9 边界遵守：service.flush + 路由 commit；D17 衰减机制：写新反馈时同 `stp_file_id` 整体续期 90 天 TTL（无 celery beat 依赖）
+- 测试基线：185 passed, 9 skipped（批 1 净增 59 测试）
+
+**剩余工作（按依赖顺序）**：
+- 批 2：算法接缝（PartingCandidateGenerator / PartingSchemeScorer / MultiSchemeMoldPlanner 透传 hints）+ OCC worker payload `experience_hints` 通道 + `processing_service._step_generate_cavity` 装配 hints
+- 批 3：前端按钮组（ResultView.vue `export-buttons-bar` 内联）+ `HumanFeedbackDialog.vue` 组件 + `moldinsightApi.getExperienceHints` / `submitExperienceFeedback` + 经验提示角标渲染
+- 批 4：衰减机制完善（与 DB 一致性定期核查）+ DFM 规则库独立模块化 + 经验冲突仲裁 UI
+
+~~原现状 / 影响~~：算法生成的方案与真实工程决策有差距，老师傅每次都要推翻系统建议重来，沉淀经验无结构化路径。
+
 ---

 ## 4. 当前推荐治理顺序