CLAUDE.md 7.31 KB

Edit Raw Blame History



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，不要在引擎/前端里硬编码订单/客户/商品字段。 若某能力必须加代码，应加"解释某类模型结构"的通用能力，而非某个具体聚合的分支。


运行 / 验证
./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 入参模拟审批。


约定


存储默认 H2 内存库（MySQL 兼容模式）；生产 profile 见 deploy/。
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 强校验。