cjw/geMoldInsight
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
geMoldInsight/docs/ROADMAP.md
T
cjw 6baa6b0d0a docs：ARCHITECTURE / ROADMAP 同步 D17 Human-in-Loop 完成 
更新两个权威文档与 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>
2026-09-24 10:15:36 +08:00

179 lines
9.0 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# geMoldInsight 演进路线图（ROADMAP）
> 文档定位：**未来演进路线与阶段计划的权威文档**。
> 本文回答“下一步准备往哪里演进、按什么阶段推进”；不负责维护当前实现状态，当前状态见 [STATUS.md](STATUS.md)。架构边界见 [ARCHITECTURE.md](ARCHITECTURE.md)，当前活跃技术债见 [TECH_DEBT.md](TECH_DEBT.md)。
> 本文基于历史归档 [archive/EVOLUTION_ROADMAP.md](archive/EVOLUTION_ROADMAP.md) 收敛整理而来。
---
## 1. 演进背景
geMoldInsight 已从历史单体逐步演进为“双业务模块 + 共享平台层 + 独立前端”的结构，但要让后续迭代成本继续下降，仍需要在以下方向持续推进：
- 继续收敛模块边界
- 继续减少 shared 的历史耦合
- 让部署、文档、契约与代码结构保持一致
- 让 moldinsight 与 inventory 的协作关系更稳定、可维护
当前事实与最近完成项见 [STATUS.md](STATUS.md)。
---
## 2. 当前演进主线
### 2.1 主线一：模块化架构收口
目标：
- 继续巩固 `moldinsight / inventory / frontend / shared` 的边界
- 减少历史单体遗留语义
- 让 README、架构文档、部署文档与代码结构一致
重点方向：
- 继续收敛 `shared` 的职责
- 逐步明确 identity / platform 的边界语义
- 收敛历史文档与旧部署叙事
### 2.2 主线二：moldinsight 工程化增强
目标：
- 让 STEP/STP 分析链路更稳定
- 让导出、批量分析、成本估算、任务状态等链路更可靠
- 继续提高 OCC 相关处理的可维护性与可测试性
重点方向：
- ~~`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 依赖场景下的契约测试/集成测试继续补齐
### 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 结构整理
- ~~拆分 `advanced_router`~~（2026-09-17 批次 3 完成）
- ~~为高频接口引入 Pydantic 请求模型~~（2026-09-17 批次 3 完成）
- 继续减少 `request.json()` 风格手动解析（存量端点已清零，新增接口守此约定）
### P2：shared/platform 边界继续收敛
- ~~梳理共享 ORM 与业务模型的归属~~（2026-09-17 批次 4 完成：ORM 已按模块拆分，跨模块只许裸 FK）
- 继续减少 shared 直接承担业务组合逻辑
- 为后续平台层命名与目录调整准备条件
### P3：专项能力继续规范化
- ~~铝价模拟数据增加显式 `source: "simulated"`~~（2026-09-18 完成：后端响应带 `source` 字段，前端按来源渲染标注，不再硬编码交易所名）
- 补专题文档的定位/边界说明
- 清理历史 checklist / tasks / report 文档的展示层级
---
### 3.1 后端设计治理批次（2026-09 设计审查产出）
> 2026-09-15 完成 moldinsight 后端设计审查，产出的具体治理批次是当前下一阶段最具体的执行计划。
> 债务明细与逐项现状见 [TECH_DEBT.md](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 天+） | ~~共享 ORM 按模块拆分；OCC 吞吐方案设计先行；文档 / 契约同步~~（2026-09-17 完成） | 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](TECH_DEBT.md) D10 与 [topics/performance/OCC_THROUGHPUT.md](topics/performance/OCC_THROUGHPUT.md)）。遗留：D13 的 pip 全量锁文件随下次镜像构建补齐。完成明细见 [STATUS.md](STATUS.md) 与 [TECH_DEBT.md](TECH_DEBT.md) §2.5–2.8。后续优先项回到 §3 P2 / P3 与主线方向。
---
## 4. 中长期方向
### 4.1 平台层语义收敛
长期仍建议将 `shared` 逐步收敛为更清晰的平台层语义，但这应建立在：
- 当前模块边界稳定
- 共享职责分层足够清晰
- 文档与部署已经同步收口
### 4.2 文档体系持续治理
后续文档治理原则：
- README 只做入口
- 当前状态只在 [STATUS.md](STATUS.md)
- 历史材料统一入 `docs/archive/`
- 每个主题只有一篇默认权威文档
### 4.3 测试能力继续增强
重点继续放在：
- OCC 相关集成验证
- 跨模块关键链路回归测试
- 关键契约的自动化保护
---
### 4.4 专题文档持续分级
后续还会继续把专题文档区分为三类：
- 当前仍有参考价值的专题文档（保留并补定位）
- 纯阶段性任务/检查单/迁移计划（迁入 archive）
- 可被主骨架吸收的重复说明（逐步收口）
---
## 5. 与相关文档的边界
- 当前项目处于什么状态：看 [STATUS.md](STATUS.md)
- 当前架构与边界是什么：看 [ARCHITECTURE.md](ARCHITECTURE.md)
- 当前有哪些技术债：看 [TECH_DEBT.md](TECH_DEBT.md)
- 当前部署方式怎么做：看 [DEPLOYMENT.md](DEPLOYMENT.md)
- 更完整的模块化蓝图讨论：看 [archive/BACKEND_MODULARIZATION_BLUEPRINT.md](archive/BACKEND_MODULARIZATION_BLUEPRINT.md)
Reference in New Issue View Git Blame Copy Permalink