# CLAUDE.md — 本体驱动 DDD+EDA 元数据引擎

给未来在本仓库工作的 Claude Code 的说明。

## 这是什么

一个**元数据驱动**系统：`models/` 下 11 份 YAML 本体（M0–M8、MetaRule）是**唯一事实源**。
- 后端 `engine/`（Java 21 / Spring Boot 3.5）是**通用解释引擎**——不含订单专用业务代码，加载 YAML 后通用执行命令。
- 前端 `web/`（React 18 / antd 5 / Vite）是**通用渲染引擎**——读 M8 模板动态生成页面。

**铁律：改需求改 `models/*.yaml`，不要在引擎/前端里硬编码订单/客户/商品字段。** 若某能力必须加代码，应加"解释某类模型结构"的通用能力，而非某个具体聚合的分支。

## 运行 / 验证

```bash
./start.sh                 # 一键起后端(8080)+前端(5173/顺延)
cd engine && ./mvnw spring-boot:run   # 仅后端（./mvnw 包装器，无需预装 Maven）
cd web && npm run dev                 # 仅前端
bash tests/verify-model-change.sh     # 验证"改模型→改行为"（reload 需 X-Principal: backend_admin）
```

改完模型：点页面右上「热重载模型」或 `curl -X POST localhost:8080/api/meta/reload`，无需重启。

## 关键文件

- `engine/.../model/ModelRepository.java` —— 元模型加载与按 M0-M8 语义的类型化查询（所有下游只读它）。
- `engine/.../command/CommandEngine.java` —— ★ 通用命令执行器（M4 flowSteps + M2 + MetaRule + M3 + ME）。
- `engine/.../meta/SceneSchemaService.java` —— 合成前端渲染 Schema（M8+M1+M2+M3+M5+MetaRule）。`select` 绑定到「聚合根自身标识」或「带 M1 `refAggregate` 的引用字段」时，通用地据被引用聚合给出下拉选项（如订单审核的审核人=员工下拉，值回填 `auditorId`）。
- `engine/.../persist/SchemaInitializer.java` —— 据 M3+M1 自动建表 + 写演示数据。
- `web/src/engine/SceneForm.tsx` / `FieldControl.tsx` —— 通用渲染引擎与组件注册表。

## 结构化元数据约定（2026-07-20 审计整改后新增，引擎据此通用执行）

- **M1 属性 `constraints`**：`{min, max, exclusiveMin, exclusiveMax, pattern, patternMessage, unique}` —— 通用校验，勿在引擎里写具体字段/中文子串。`unique:true` 会在 create/update 前按 M3 列查重（update 排除自身；加密字段用确定性密文比对）。
- **M2 命令 `commandType`**：`create|update|cancel` —— 决定合成默认程序 + create 超卖回滚策略；缺省 create。
- **M2 命令 `bizSteps`（命令级"闭指令集"程序，`CommandEngine.runProgram`/`runInstructions` 逐条通用解释，替代旧的硬编码 create/update/cancel）**：
  每步 `{stepNo, desc, instruction:{type, params}}`，`type` **只能取以下 10 个 opcode 之一**（闭集合，M0 `M2_BizStep.enum` 锁定，AI 转换产物可静态校验）：
  `LOAD_AGGREGATE`(按 `idSource` 加载既有根→update/cancel 语义) / `SET_FIELD`(`targetField` ← `source`(input.*/root.*/字面量) 或 `value`) /
  `AUTO_FILL_FIELD`(`func`: `now_datetime|now_date|gen_id`) / `REMOTE_QUERY_SET_FIELD`(`remoteAggregate/queryKey/sourceField/targetField`) /
  `CONDITION_SET_FIELD`(`conditions:[{when, value}]`，when 走 Aviator) / `CALL_OTHER_COMMAND`(`targetAggregate/targetCommand/paramMap/forEach/onFailure`，复用目标命令 `effect`) /
  `COMMIT_TRANSACTION`(未 LOAD→insert 根+组合子实体；已 LOAD→update) /
  `IF`(`{when, then:[子指令], else:[子指令]}`，when 走 Aviator，**命令级判断分支**，类比 M4 `condition`，`then/else` 内可嵌套任意 opcode) /
  `REMOTE_SET_FIELD`(`remoteAggregate/keySource/targetField/source|value`，覆盖写回被引用聚合根字段) /
  `REMOTE_INCREMENT_FIELD`(`remoteAggregate/keySource/targetField/amount`，原子 +N 被引用聚合根数值字段；被增字段须非空，见 seed 初始化)。
  缺省或仍是字符串描述的命令，按 `commandType` 合成规范程序，仍走同一台解释器。
  落库后统一：发 `emitEvents` → 跨聚合一致(ME 规则 + 指令内 CALL/REMOTE) → create 超卖回滚。表达式里 `input.`(命令入参)/`root.`(聚合现值) 命名空间由引擎改写后交 Aviator。
  演示命令 `AuditOrder`（`SCENE_AUDIT_ORDER`）即范例：按 `root.totalAmount>100` 用 `IF`+`REMOTE_SET_FIELD` 覆盖审核人备注，按 `input.auditResult` 用 `REMOTE_INCREMENT_FIELD` 累加审核人通过/驳回数；`REMOTE_QUERY` 查 `EmployeeAggregate`。
- **M2 命令 `effect`**：`{op: increment|decrement, targetField, keyParam, amountParam, guardField}` —— 跨聚合副作用由此通用执行。
- **M2 命令 `derivations`**：`[{targetField, sourceEntity, aggregate: sum, expression}]` —— 服务端重算字段（防篡改）。
- **ME `crossAggConsistencyRules`**：需带 `sourceItemEntity` + `paramMap{目标命令参数: 子实体字段}`。
- 后端 execute 返回稳定键 `rootId` / `rootIdField`；前端只读这两个，勿读 `orderId`。
- 校验/风控变量解析走 **M1 `refAggregate`**（`ModelRepository.refInfo`）；不要在引擎写 CustomerAggregate/customerLevel/stockNum 之类字面量。
- **M4 场景 `stepType` 全集（`CommandEngine.runStep` 递归通用解释，枚举见 M0 `M4_SceneStep`）**：
  起止 `start|return|end|errorEnd`；数据 `readOnlyCheck|validate|derive|assign|transform|script`；
  命令/事件 `bindCommand|callScene|callService|emitEvent|waitEvent`；控制流 `condition|switch|parallel|while|loopItems`；
  Saga/可靠性 `retry|compensate|timer|userTask`。子步骤放 `then/else/body/branches[].steps/cases[].steps/default`；
  表达式（`when`/`switchOn`/`assignments[].expression`/`script.expression`）走 Aviator（`RuleEngine.evalValue/evalBool`），变量取 master+M1 引用+循环行。
  **switch 的分派键叫 `switchOn` 不叫 `on`**（YAML 1.1 把 `on/off/yes/no` 当布尔，`on:` 会变成 `true` 键）。
  `bindCommand` 可带 `compensateAggregate/compensateCommand` 登记逆向补偿，失败时逆序触发（`SCENE_DEMO_STEPTYPES` 为可删演示场景）。
  演示简化：`parallel` 顺序执行后汇合、`timer/waitEvent/callService` 不真阻塞/外呼、`retry` 无瞬时故障注入、`userTask` 用 `approveParam` 入参模拟审批。

## 约定

- 存储默认 **MySQL8**（本机 Docker 容器，端口 3307；env 覆盖 `DB_HOST/DB_PORT/DB_NAME/DB_USER/DB_PASS`）。无 MySQL 环境可 `--spring.profiles.active=h2` 切回 H2 内存库（`application-h2.yml`，零外部依赖）；生产 profile 见 `deploy/`。建表 DDL 已做 H2/MySQL 双兼容（`SchemaInitializer` 用元数据判断列是否存在，勿再用 `ADD COLUMN IF NOT EXISTS` 方言）。
- Java 编译目标 21（`maven.compiler.release=21`），可在更高 JDK 上运行。
- 新增原子组件类型：在 `FieldControl.tsx` 注册表登记即可，业务页面零改动。
- 演示引导数据在 `engine/src/main/resources/seed-data.yaml`（非本体的一部分）。
- 订单审核场景 `SCENE_AUDIT_ORDER` 由 M8 `template_order_audit` 渲染：选订单 + 选审核人（员工引用下拉）+ 审核结论/备注，端到端演示 `AuditOrder` 的 7 opcode 程序。`auditResult` 为 M1 上的**瞬态字段**（无 M3 列，不落库，仅派生 `orderStatus`）。
- 未绑定 M8 模板的场景（如 `SCENE_DEMO_STEPTYPES`，字段为合成变量非 M1 字段）：前端提供「无表单直接运行」入口，以空 payload 调 execute，引擎逐条通用解释 flowSteps 产出 trace。
- M5 `encryptRules.storageEncrypt` 字段由 `EncryptService` 落库加密/读时解密；热重载仅管理员（M8 dragRolePermission）。
- 审计整改逐条见 `docs/审计整改说明.md`。仍为演示简化：真实认证/幂等/M0 强校验。