# 本体驱动 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 亦可）。

```bash
./start.sh
```

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

分别启动（调试用）：

```bash
# 终端 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`](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`](docs/审计整改说明.md)。

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

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

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

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