From 6baa6b0d0ac35b1068a12c62c34e7baeb555f144 Mon Sep 17 00:00:00 2001 From: chenjw28 <792430652@qq.com> Date: Thu, 24 Sep 2026 10:15:36 +0800 Subject: [PATCH] =?UTF-8?q?docs=EF=BC=9AARCHITECTURE=20/=20ROADMAP=20?= =?UTF-8?q?=E5=90=8C=E6=AD=A5=20D17=20Human-in-Loop=20=E5=AE=8C=E6=88=90?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 更新两个权威文档与 D17 端到端闭环对齐： - docs/ROADMAP.md §2.2 主线二"moldinsight 工程化增强"重点方向 加一条 D17 已完成条目（2026-09-23~24，3 个 commit：数据 + 权限 + 写入 API / 算法接缝 + OCC payload / 前端按钮 + Dialog + 经验角标； 详见 TECH_DEBT.md D17），与既有 ~~XXX~~（YYYY-MM-DD 完成）格式一致 - docs/ARCHITECTURE.md 新增 §6.4 D17 Human-in-Loop 老师傅经验反馈闭环 —— 已完成段：用 ASCII 数据流图展示老师傅点反馈按钮 → 路由层 → service 写入 → 续期衰减 → 上传新 STP 触发 resolve_for_process_params → OCC payload 透传 → planner 算法加成 → ResultView 渲染的端到端链路 段内列出"硬规则遵守"（跨模块 FK 守 §5.1、OCC payload 守 occ_worker.py:7-8、D9 边界不破、init_db.py 幂等修复已落）和 "重量级约束"（weight 仅正向、sample_count<2 时 ×0.5、graceful 退化、 角色门控），最后给测试基线指针 放在 §6.3"文档与结构尚未完全同步"之后作为"已完成端到端闭环" 对照示例，便于新成员理解 D17 在系统中的位置 文档侧仅变更，无代码改动；按 AGENTS.md §4.1 映射表，模块边界 （ARCHITECTURE.md）/ 演进路线（ROADMAP.md）相关变更同步。 Co-Authored-By: Claude Code --- docs/ARCHITECTURE.md | 78 ++++++++++++++++++++++++++++++++++++++++++++ docs/ROADMAP.md | 1 + 2 files changed, 79 insertions(+) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 8027453..1d64bc7 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -205,6 +205,84 @@ geMoldInsight/ 代码结构已明显模块化，但历史文档中仍保留不少阶段性叙述、旧部署语义与重复说明，这也是本轮文档整理要解决的问题之一。 +### 6.4 D17 Human-in-Loop 老师傅经验反馈闭环 —— 已完成（2026-09-23~24，3 个 commit） + +算法演进由老师傅经验驱动：通过方案级整体反馈（采纳 / 建议调整 / 拒绝）按"产品指纹 + 工艺参数"为键跨任务匹配，下次同指纹产品分析自动消费老师傅沉淀的经验。这是少数"算法层由用户在线学习样本持续校准"的端到端闭环。 + +**端到端数据流**： + +``` +┌─────────────────────────────────────────────────────────────┐ +│ 老师傅在 ResultView 点 👍 老师傅反馈按钮 │ +│ → HumanFeedbackDialog 三选一（采纳 / 建议调整 / 拒绝） │ +└──────────────────────────────┬──────────────────────────────┘ + │ POST /api/tasks/{id}/experience-feedback + ▼ +┌──────────────────────────────────────────────────────────────┐ +│ experience_feedback_router (src/moldinsight/api/) │ +│ - ensure_task_access 归属校验 │ +│ - current_user.has_permission("feedback_experience_hint") │ +│ - service.record_feedback (flush; commit + invalidate) │ +└──────────────────────────────┬───────────────────────────────┘ + ▼ +┌──────────────────────────────────────────────────────────────┐ +│ experience_feedback_service.record_feedback │ +│ - compute_fingerprint (bbox_aspect / volume_bucket / │ +│ face_bucket / undercut_class / material_family / is_foam) │ +│ - 写 experience_feedback 表（D9 边界 / D17 衰减 90d TTL） │ +│ - 同 stp_file_id 整体续期 expires_at │ +└──────────────────────────────┬───────────────────────────────┘ + │ 同 stp_file_id 上传新 STP 自动消费 + ▼ +┌──────────────────────────────────────────────────────────────┐ +│ processing_service._step_generate_cavity │ +│ - experience_feedback_service.resolve_for_process_params │ +│ → hints (List[{scheme_axis, weight, sample_count, ...}]) │ +│ - hints 装进 run_occ payload 顶层 experience_hints │ +└──────────────────────────────┬───────────────────────────────┘ + │ OCC 子进程（spawn 隔离） + ▼ +┌──────────────────────────────────────────────────────────────┐ +│ occ_worker._op_generate_cavity │ +│ - payload.get("experience_hints") or {} → planner.generate_plan(hints=...) │ +└──────────────────────────────┬───────────────────────────────┘ + ▼ +┌──────────────────────────────────────────────────────────────┐ +│ MultiSchemeMoldPlanner.generate_plan(..., hints=None) │ +│ - candidate_generator.generate_candidates(..., hints) │ +│ * priority_score += weight × 20 │ +│ * sample_count ≥ 2 + weight ≥ 0.5 → method="human_experience_primary" │ +│ - scheme_scorer.score_schemes(schemes, *, hints) │ +│ * score_breakdown["human_hint_bonus"] = weight × 12 │ +│ （sample_count < 2 时 ×0.5 折半） │ +│ - global_summary.applied_hints 注入返回 │ +└──────────────────────────────┬───────────────────────────────┘ + ▼ +┌──────────────────────────────────────────────────────────────┐ +│ ResultView 渲染： │ +│ - summary-header 加 t-tag theme="success" 📚 历史经验 N 条 │ +│ - 反馈提交后 onFeedbackSubmitted → loadExperienceHints 即刷 │ +└──────────────────────────────────────────────────────────────┘ +``` + +**硬规则遵守**： + +- 跨模块 FK 仍守 §5.1（`experience_feedback.user_id` / `processing_task_id` / `stp_file_id` 全用字符串表名，无 ORM relationship） +- OCC 跨进程守 [occ_worker.py:7-8](../src/moldinsight/core/occ_worker.py#L7-L8) "杜绝 pickle OCC 对象"——payload 普通 dict 透传 +- D9 边界不破：service.flush + 路由 commit（无 service 内 commit） +- 现有 `init_db.py` 幂等修复：按 code 补登权限/角色 + +**重量级约束**： + +- `weight = max(0, (adopted-rejected)/total)`：仅正向有效，老师傅拒绝不"扣分"老算法 +- `sample_count < 2` 时 bonus ×0.5：信号不足折半，但 priority_score 仍加成（候选方向仍偏向） +- 解析失败回退空 list：graceful，主流程不因下游错误退化 +- `canGiveFeedback` 角色门控：`is_superuser || roles 含 process_engineer` + +**测试基线**：192 passed, 13 skipped（批 3 净增 +4 OCC-gated：candidate_generator 3 / scheme_scorer 4 / multi_scheme_planner 2 / processing_service 2）；前端 vue-tsc + vite 通过。 + +详见 [TECH_DEBT.md](TECH_DEBT.md) D17 + [STATUS.md](STATUS.md) 2026-09-23~24 日志。 + --- ## 7. 专题文档与主骨架的关系 diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 0ac3410..174eef3 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -46,6 +46,7 @@ geMoldInsight 已从历史单体逐步演进为“双业务模块 + 共享平台 重点方向： - ~~`advanced_router` 拆分与请求模型规范化~~（2026-09-17 批次 3 完成） +- ~~D17 Human-in-Loop 老师傅经验反馈~~（2026-09-23~24 完成，3 个 commit：数据 + 权限 + 写入 API / 算法接缝 + OCC payload / 前端按钮 + Dialog + 经验角标；写入即消费闭环通；详见 [TECH_DEBT.md](TECH_DEBT.md) D17） - 模具分析链路的结构继续收口 - OCC 依赖场景下的契约测试/集成测试继续补齐