README.md
本体驱动 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'，无需重启；热重载仅管理员可触发）：
-
改前端表单（M8）：编辑
models/M8-front-schema.yaml，把某组件compType: input改成select、改formLabel、增删组件或改span→ 热重载 → 「新增订单」页对应字段的控件类型/标签/布局立即改变。 -
改风控规则（MetaRule）：编辑
models/MetaRule-business.yaml，把single_order_max_amount由50000改成100→ 热重载 → 普通用户下单金额超 100 即被 REJECT（同一笔请求从通过变为拦截）。 -
改领域字段类型（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 驱动逻辑与规则引擎完全一致、无需改动。