朱子纯 / onto-demo

README.md 8.36 KB

本体驱动 DDD+EDA · 元数据解释引擎（可运行 Demo）

一份完整的前后端，一个能运行的网页：网页上可操作「新增订单」，且该操作完全由 models/ 下的 YAML 本体模型驱动——改了模型文件，前端表单与后端执行的操作定义同时改变，无需改一行代码。

本项目按 request.txt 的 11 层本体模型（M0–M8、MetaRule）落地为一个元数据驱动系统：

  • 后端 = 架构解释引擎（Java 21 + Spring Boot 3.5）：启动时加载 YAML，构建内存元模型，用通用命令执行器解释执行 CreateOrder（无任何订单专用业务代码）。
  • 前端 = 通用渲染引擎（React 18 + Ant Design 5 + Vite）：读取 M8 模板 + 后端合成的元数据，动态渲染「新增订单」页并提交到通用命令 API。

一、快速运行

前置：Java 21+、Node 18+、npm（Maven 无需预装——项目内含 ./mvnw 包装器，首次运行自动下载 Maven 3.9.9 与全部依赖；本机实测 Java 25 + Node 26 亦可）。

./start.sh

脚本会：启动后端(8080) → 等待就绪 → 安装前端依赖 → 启动前端(Vite)。 浏览器打开 Vite 提示的 Local 地址（默认 http://localhost:5173，被占用则顺延如 5174），进入「用户创建订单完整流程」页即可操作新增订单。

分别启动（调试用）：

# 终端 A —— 后端（用包装器，无需预装 Maven）
cd engine && ./mvnw spring-boot:run
# 终端 B —— 前端
cd web && npm install && npm run dev

默认存储为 H2 内存库（MySQL 兼容模式），零外部依赖开箱即跑；H2 控制台 http://localhost:8080/h2-console（JDBC URL: jdbc:h2:mem:trade_db，用户 sa，空密码）。

二、验证「改了模型文件 → 操作定义随之改变」（核心验收点）

系统的关键在于行为源于模型、而非代码。三种典型验证（改完点页面右上「热重载模型」或 curl -X POST localhost:8080/api/meta/reload -H 'X-Principal: backend_admin'，无需重启；热重载仅管理员可触发）：

  1. 改前端表单（M8）：编辑 models/M8-front-schema.yaml，把某组件 compType: input 改成 select、改 formLabel、增删组件或改 span → 热重载 → 「新增订单」页对应字段的控件类型/标签/布局立即改变。
  2. 改风控规则（MetaRule）：编辑 models/MetaRule-business.yaml，把 single_order_max_amount 由 50000 改成 100 → 热重载 → 普通用户下单金额超 100 即被 REJECT（同一笔请求从通过变为拦截）。
  3. 改领域字段类型（M1）：编辑 models/M1-domain.yaml，把某字段 type: string 改成 int → 热重载 → 该字段的输入控件类型随之改变（配合 M3 增列后即可落库）。

curl 复现规则 2：见 tests/verify-model-change.sh。

三、目录结构

onto-implementation/
├── models/                     # ★ 唯一事实源：11 份本体 YAML（M0–M8、MetaRule）
├── engine/                     # 后端解释引擎（Spring Boot）
│   └── src/main/java/com/onto/engine/
│       ├── model/              # 元模型加载与类型化查询 (ModelRepository)
│       ├── meta/               # 场景渲染 Schema 合成 (SceneSchemaService)
│       ├── command/            # ★ 通用命令执行器 (CommandEngine)
│       ├── rule/               # Aviator MetaRule 引擎 (RuleEngine)
│       ├── persist/            # 据 M3 动态建表/读写 (SchemaInitializer/DynamicRepository)
│       ├── event/              # Outbox + 跨聚合最终一致 (EventEngine)
│       ├── security/           # M5 脱敏 (MaskService)
│       └── web/                # REST 控制器
├── web/                        # 前端通用渲染引擎（React + Vite）
│   └── src/
│       ├── engine/             # ★ SchemaRenderer / FieldControl（组件注册表）
│       ├── panels.tsx          # 执行追踪 / 溯源 / 模型查看器 / 订单事件
│       └── App.tsx
├── templates/                  # 代码生成模板（M1→DDL、M2→命令、M8→React 组件）
├── deploy/                     # 生产部署（docker-compose：MySQL8 + RocketMQ + Nginx）
├── docs/                       # 场景推演文档（架构运行原理）
├── tests/                      # 验证脚本
└── start.sh

四、架构分层与引擎如何"解释执行"

层 职责 引擎如何使用
M0 meta-schema 全域校验根规范 描述所有层的 JSON Schema，CI 可据此校验 YAML
M1 domain DDD 聚合唯一数据源 字段类型、组合子实体结构 → 前端控件类型 / DDL / 值转换
M2 command 聚合命令入参/校验/事件 通用执行器据此校验入参、决定发何事件
ME event EDA 事件与跨聚合一致性 Outbox 事件定义 + OrderCreated→StockDeduct
M3 deploy 实体↔表/字段映射、命令 API 自动建表、动态 SQL、前端命令 URL
M4 scene Saga 流程编排 通用执行器逐 flowSteps 解释：readOnlyCheck→bindCommand→return
M5 security 权限/脱敏 权限校验、敏感字段掩码渲染
M6 monitor 监控告警 指标/告警规范（文档态）
M7 sla 流量/熔断 SLA 规范（文档态）
MetaRule 前后端统一动态规则 Aviator 实时执行：REJECT/ALERT，前后端同源
M8 front-schema React 拖拽页面模板 ★ 前端渲染引擎读取它动态生成整页

「新增订单」端到端（SCENE_CREATE_ORDER）： 权限(M5) → readOnlyCheck 客户存在(M4/M1) → 入参校验(M2/M8) → 风控(MetaRule) → 落库(M3) → 发事件(ME/Outbox) → 跨聚合扣库存(ME 最终一致)。 页面右侧「执行追踪」把每一步及其来源层实时可视化。

详见 docs/场景推演.md。

五、主要 API

方法 路径 说明
GET /api/meta/scenes 场景列表（M4）
GET /api/meta/scene/{sceneId} 场景渲染 Schema（M8+M1+M2+M3+M5+MetaRule 合成）
GET /api/meta/model/{code} 查看某层模型解析内容（M0..M8/MetaRule）
POST /api/meta/reload 热重载全部 YAML（改模型即时生效）
GET /api/data/{aggregateId} 引用下拉数据源（客户/商品，含脱敏）
POST /api/scene/{sceneId}/precheck 提交前预检（校验+MetaRule 风控，不落库）
POST /api/scene/{sceneId}/execute 通用执行场景命令（完整解释执行）

六、通用性与安全边界（诚实说明）

经 2026-07-20 审计后本轮"全面改造"：把原先散落在 Java/TS 里的业务字面量上移为可机器读的本体元数据 （M1 constraints、M2 commandType/effect/derivations、ME sourceItemEntity/paramMap）， 使校验、风控、跨聚合一致性、落库分派全部模型驱动。因此新增第二个聚合/场景（如已内置的"新增客户"） 或重命名字段，通常只改 YAML。逐条整改见 docs/审计整改说明.md。

仍为演示简化（未做成生产级，明确标注）：

  • 认证：未接入 OAuth2/JWT；主体来自 X-Principal 头（可伪造），仅演示 M5 权限"通过/拒绝"分支。热重载/新增客户已要求管理员主体。生产必须换真实认证。
  • 幂等：命令未加请求幂等键。
  • M0 校验：M0 仍为规范文档，未在加载时对各层做 JSON-Schema 强校验。

M8 补全后四个场景（新增订单/新增客户/修改地址/取消订单）均可渲染并端到端可用：update 命令含子实体更新、cancel 走通用 StockReturn 回补库存（均有测试）。

七、生产化部署（本机为轻量可跑版）

为保证"本机开箱即跑"，Demo 采用 H2 内存库 + 进程内 Outbox/事件总线 + 真实 Aviator 规则引擎 + 真实字段加密。 生产映射（真 MySQL8 + RocketMQ + Nginx）见 deploy/：docker-compose up 拉起完整栈，后端切 prod profile 连真中间件、收紧 CORS、禁用 H2 控制台、要求经环境/密管注入 DB 口令与加密密钥；YAML 驱动逻辑与规则引擎完全一致、无需改动。