cjw
6baa6b0d0a
更新两个权威文档与 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 <noreply@anthropic.com>
9.0 KiB
geMoldInsight 演进路线图（ROADMAP）
文档定位：未来演进路线与阶段计划的权威文档。 本文回答“下一步准备往哪里演进、按什么阶段推进”；不负责维护当前实现状态，当前状态见 STATUS.md。架构边界见 ARCHITECTURE.md，当前活跃技术债见 TECH_DEBT.md。 本文基于历史归档 archive/EVOLUTION_ROADMAP.md 收敛整理而来。
1. 演进背景
geMoldInsight 已从历史单体逐步演进为“双业务模块 + 共享平台层 + 独立前端”的结构，但要让后续迭代成本继续下降，仍需要在以下方向持续推进：
- 继续收敛模块边界
- 继续减少 shared 的历史耦合
- 让部署、文档、契约与代码结构保持一致
- 让 moldinsight 与 inventory 的协作关系更稳定、可维护
当前事实与最近完成项见 STATUS.md。
2. 当前演进主线
2.1 主线一：模块化架构收口
目标：
- 继续巩固
moldinsight / inventory / frontend / shared的边界 - 减少历史单体遗留语义
- 让 README、架构文档、部署文档与代码结构一致
重点方向：
- 继续收敛
shared的职责 - 逐步明确 identity / platform 的边界语义
- 收敛历史文档与旧部署叙事
2.2 主线二：moldinsight 工程化增强
目标：
- 让 STEP/STP 分析链路更稳定
- 让导出、批量分析、成本估算、任务状态等链路更可靠
- 继续提高 OCC 相关处理的可维护性与可测试性
重点方向：
advanced_router拆分与请求模型规范化D17 Human-in-Loop 老师傅经验反馈（2026-09-23~24 完成，3 个 commit：数据 + 权限 + 写入 API / 算法接缝 + OCC payload / 前端按钮 + Dialog + 经验角标；写入即消费闭环通；详见 TECH_DEBT.md D17）- 模具分析链路的结构继续收口
- OCC 依赖场景下的契约测试/集成测试继续补齐
2.3 主线三：inventory 业务层继续沉淀
目标：
- 让 inventory 从“可用”继续走向“可扩展”
- 继续将路由中的业务逻辑下沉为 service 层
- 保持与 moldinsight 的桥接模型清晰
重点方向：
- 业务 service 复用强化
- 数据模型归属进一步清晰化
- 前后端契约持续减少手写漂移
- 已完成第一批主数据收口（2026-09-21）：
customer / supplier / warehouse路由改为薄路由，CRUD 编排下沉至master_data_service - 已完成物料域第二批收口（2026-09-21）：
material_routes的价格历史、价格趋势、供应商关联查询/删除编排下沉至material_service - 已完成产品域第三批收口（2026-09-21）：
product_routes的常规 CRUD、BOM 与跨模块from-task编排均已下沉至product_service - 已完成 dashboard 聚合收口（2026-09-21）：
dashboard_routes的首页统计/低库存预警编排下沉至dashboard_service
2.4 主线四：部署与运维一致性
目标：
- 让推荐部署模式、Compose 入口、运维文档、Nginx/端口说明不再冲突
- 让前端、后端、异步任务链路在部署说明上形成单一叙事
重点方向：
- 继续收口部署文档
- 把历史部署迁移方案移入归档
- 保持同域前端 + unified backend 的默认认知清晰
3. 下一阶段优先项
P0：文档与边界对齐
- 建立
STATUS / ARCHITECTURE / ROADMAP / TECH_DEBT / DEPLOYMENT主骨架 - 将 README 收敛为唯一导航入口
- 收口部署重复文档并建立 archive
P1：moldinsight API 结构整理
拆分（2026-09-17 批次 3 完成）advanced_router为高频接口引入 Pydantic 请求模型（2026-09-17 批次 3 完成）- 继续减少
request.json()风格手动解析（存量端点已清零，新增接口守此约定）
P2：shared/platform 边界继续收敛
梳理共享 ORM 与业务模型的归属（2026-09-17 批次 4 完成：ORM 已按模块拆分，跨模块只许裸 FK）- 继续减少 shared 直接承担业务组合逻辑
- 为后续平台层命名与目录调整准备条件
P3：专项能力继续规范化
铝价模拟数据增加显式（2026-09-18 完成：后端响应带source: "simulated"source字段，前端按来源渲染标注，不再硬编码交易所名）- 补专题文档的定位/边界说明
- 清理历史 checklist / tasks / report 文档的展示层级
3.1 后端设计治理批次（2026-09 设计审查产出）
2026-09-15 完成 moldinsight 后端设计审查，产出的具体治理批次是当前下一阶段最具体的执行计划。 债务明细与逐项现状见 TECH_DEBT.md §3（D5–D14）；本小节只描述批次、顺序与每批归属。
| 批次 | 主题 | 内容 | 对应债务 |
|---|---|---|---|
| 批次 0 | 安全与诚实（0.5–1 天） | /api/status/{task_id} 补鉴权 + 任务归属校验；pythonocc_available 真实检测；bcrypt 超长密码拒绝；SECRET_KEY / RUSTFS_* 惰性校验补齐 |
D5 |
| 批次 1 | 部署正确性（1–2 天） | 主链路改走 RustFS（分派入参file_path → stp_file_id，worker 按 object_key 下载解析）；compose 共享卷兜底（过渡）；alembic 移出 startup（AUTO_MIGRATE 开关）；OCC 镜像引入方式修正 + 依赖锁文件 |
D6、D12、D13 |
| 批次 2 | 任务一致性模型（2–4 天） | PG 为单一事实源、Redis 仅热缓存；去掉多进程内存回退；批量元数据入库；型腔失败标 failed；持久化事务边界收口 | D7、D8、D9、D11 |
| 批次 3 | API 与代码结构（3–5 天） | _safe_include 失败显式化（/health 暴露缺失路由）；advanced_router 拆分 + Pydantic 请求模型；async 重计算统一 executor；StorageIntegrationService 拆分；配置治理 |
D1、D14 |
| 批次 4 | 架构演进（5 天+） | D3、D10 |
执行顺序建议：批次 0 与批次 1 的 D6（RustFS 主链路）先行——前者是确认的安全漏洞，后者是部署根本性缺陷，两者互不依赖、改动可控。其余按批次顺序推进，每批完成同步 STATUS / TECH_DEBT / API_CONTRACT。
进度：批次 0 / 1 / 2 已于 2026-09-16 完成、批次 3 / 4 已于 2026-09-17 完成，§3.1 批次计划全部执行完毕；批次 4 后续专项于 2026-09-18 完成——D11（HTML 报告 RustFS 单源 +
/html代理路由）与 OCC 方案 B（run_occ契约进程化 + 常驻进程池 kill-on-timeout）已清偿（部署参数方案 A 一并落地，见 TECH_DEBT.md D10 与 topics/performance/OCC_THROUGHPUT.md）。遗留：D13 的 pip 全量锁文件随下次镜像构建补齐。完成明细见 STATUS.md 与 TECH_DEBT.md §2.5–2.8。后续优先项回到 §3 P2 / P3 与主线方向。
4. 中长期方向
4.1 平台层语义收敛
长期仍建议将 shared 逐步收敛为更清晰的平台层语义，但这应建立在：
- 当前模块边界稳定
- 共享职责分层足够清晰
- 文档与部署已经同步收口
4.2 文档体系持续治理
后续文档治理原则：
- README 只做入口
- 当前状态只在 STATUS.md
- 历史材料统一入
docs/archive/ - 每个主题只有一篇默认权威文档
4.3 测试能力继续增强
重点继续放在：
- OCC 相关集成验证
- 跨模块关键链路回归测试
- 关键契约的自动化保护
4.4 专题文档持续分级
后续还会继续把专题文档区分为三类：
- 当前仍有参考价值的专题文档（保留并补定位）
- 纯阶段性任务/检查单/迁移计划（迁入 archive）
- 可被主骨架吸收的重复说明（逐步收口）
5. 与相关文档的边界
- 当前项目处于什么状态：看 STATUS.md
- 当前架构与边界是什么：看 ARCHITECTURE.md
- 当前有哪些技术债：看 TECH_DEBT.md
- 当前部署方式怎么做：看 DEPLOYMENT.md
- 更完整的模块化蓝图讨论：看 archive/BACKEND_MODULARIZATION_BLUEPRINT.md