---
title: 公式能力扩展
version: 1.0
date_created: 2026-06-12
last_updated: 2026-06-12
tags: ['formula', 'business-object', 'computation', 'core']
status: done
complexity: 🜶 复杂
背景
ForgeAdmin 已具备 BusinessObject、LowcodeModel、Runtime、动态CRUD、对象关系能力，但缺少统一公式体系，无法支持金额自动计算、主从表汇总、条件表达式计算、自动字段赋值等场景。本次变更建立字段级公式能力，使业务对象的字段可通过公式自动计算值，减少手动赋值和数据不一致风险。
1. 目标与成功标准
- 用户价值: 业务对象字段值可通过配置公式自动计算，无需手写代码
- 业务目标: 消除金额计算、主从表汇总的手工维护，降低数据不一致风险
- 成功判定:
- 字段设计器中可配置公式（类型、表达式、计算模式）
- 配置公式后保存/查询时字段值自动计算
- 从表变更时主表聚合字段自动更新
- 发布时循环依赖和嵌套深度校验通过
2. 代码现状
2.1 关键入口
| 文件 |
说明 |
| orge-plugin-generator/.../domain/entity/AiBusinessObject.java |
业务对象实体，含 objectType、options(JSON) |
| orge-plugin-generator/.../domain/entity/AiBusinessObjectRelation.java |
对象关系，支持 REFERENCE/DETAIL/CHILD_LIST |
| orge-plugin-generator/.../domain/entity/AiLowcodeModel.java |
数据模型，modelSchema 存储字段定义 JSON |
| orge-plugin-generator/.../domain/entity/GenTableColumn.java |
字段定义实体，含 javaField、columnType、validateRule |
| orge-plugin-generator/.../service/businessapp/BusinessObjectPublishService.java |
对象发布服务 |
| orge-plugin-generator/.../service/businessapp/BusinessObjectCreateService.java |
业务对象创建服务 |
2.2 已知限制
- GenTableColumn 无公式配置字段，AiLowcodeModel.modelSchema 中无公式定义
- 运行时动态CRUD 无公式计算截入点
- 金额计算、主从表汇总全靠业务代码手写
3. 变更范围
会修改
- orge-plugin-generator: 字段定义实体、发布服务、DTO/VO 扩展
- orge-plugin-generator: 新增公式服务、控制器、Aviator 表达式引擎集成
- orge-app-server / orge-admin-server: 动态CRUD 入口增加公式计算截入
- orge-admin-ui: 字段设计器中新增公式配置界面
- orge-dependencies: 新增 Aviator 表达式引擎依赖
不会修改
- 条件引擎、审批表达式、流程表达式
- AI公式生成
- forge-flow 流程引擎
- forge-report-ui、forge-h5-ui
- 跨对象公式引用（V1 不支持）
4. Requirements, Constraints & Guidelines
功能需求
- REQ-001 (计算公式): 字段值由同对象其他字段表达式计算得出，如 otal = unit_price * quantity
- REQ-002 (聚合公式): 主表字段值由从表记录聚合计算，如 otal_amount = SUM(detail.amount)
- REQ-003 (条件公式): 字段值根据条件表达式动态赋值，如 discount = IF(amount > 1000, 0.1, 0)
- REQ-004 (VIRTUAL 模式): 读取时动态计算，不存储到数据库
- REQ-005 (STORED 模式): 保存时计算并持久化，读取时返回存储值
- REQ-006 (公式配置): 字段定义中新增 ormula_config JSON，支持公式类型、表达式、计算模式、依赖字段
- REQ-007 (循环依赖检测): 发布时使用 DAG 拓扑排序检测循环引用
- REQ-008 (公式错误处理): 计算失败时记录 ERROR 日志并降级处理
- REQ-009 (公式嵌套): V1 支持最大嵌套深度 3 层，发布时 DAG 分析 + 循环检测
约束条件
- CON-001: 公式字段不支持用户直接编辑，值由系统计算
- CON-002: 金额类公式计算结果使用 long 类型（单位：分）
- CON-003: STORED 公式在 Insert/Update 时触发重算
- CON-004: VIRTUAL 公式在查询记录时实时计算，不存储
- CON-005: 聚合公式依赖于对象关系 (DETAIL/CHILD_LIST)，无关系时报错
- CON-006: 聚合公式采用自动重算模式，不采用手动或定时触发
- CON-007: STORED 聚合公式采用自动维护模式，禁止脏数据
- CON-008: 公式嵌套最大深度 3 层
- CON-009: V1 不支持跨对象公式
编写约定
- GUD-001: 表达式引擎使用 Aviator，支持算术、逻辑、三元、内置函数
- GUD-002: 公式配置 JSON 格式统一：{ type, expression, mode, dependsOn, maxDepth }
- GUD-003: 公式服务注入点采用统一拦截器模式，不侵入具体 CRUD 业务代码
风险
- RISK-001 (金额一致性): STORED 聚合公式必须与从表同步更新，避免主从表金额不一致
- RISK-002 (循环依赖): 公式间循环引用必须在发布时拦截
- RISK-003 (性能): 聚合公式 N+1 查询需优化；从表批量操作时主表重算频率需控制
- RISK-004 (并发): STORED 公式并发写入时可能导致主表值过时
- RISK-005 (兼容性): 已有字段增加公式后历史数据需重算迁移
- RISK-006 (回滚): 公式配置回滚后已存储计算值需明确清理策略
5. Interfaces & Data Contracts
数据变更
| 表 |
字段 |
说明 |
| gen_table_column |
ormula_config TEXT |
新增公式配置 JSON |
| i_lowcode_model |
modelSchema JSON |
字段 schema 中新增 formula 节点 |
API 变更
| 方法 |
路径 |
说明 |
| POST |
/api/ai/business/formula/validate |
验证公式表达式语法 |
| POST |
/api/ai/business/formula/preview |
预览公式计算结果 |
| POST |
/api/ai/business/object/{objectCode}/publish |
发布时增加 DAG + 循环检测 + 深度校验 |
| POST/PUT/GET |
动态CRUD入口 |
新增/更新/查询时公式计算截入 |
| POST/PUT/DELETE |
动态CRUD入口（从表） |
从表变更后触发主表聚合重算 |
6. 测试与验证策略
- 公式解析测试: Aviator 表达式语法解析正确性
- 计算模式测试: STORED 保存持久化、VIRTUAL 查询实时计算
- 聚合重算测试: 从表 CRUD 后主表字段自动更新
- 循环依赖测试: DAG 拓扑排序拦截循环引用
- 嵌套深度测试: 超过 3 层嵌套时发布拦截
- 错误处理测试: 公式异常时日志记录 + 降级处理
- 覆盖率: 核心公式引擎 85%+，公式服务 80%+
7. 技术决策
| 决策项 |
方案 |
放弃方案 |
| 表达式引擎 |
Aviator |
MVEL（体积大）、自研（成本高） |
| 存储策略 |
字段扩展 JSON |
独立公式表（复杂度高） |
| 聚合触发 |
自动重算 |
手动触发、定时触发 |
| 循环检测 |
DAG 拓扑排序 |
— |
| 跨对象 |
V1 不支持 |
— |
| 嵌套深度 |
最大 3 层 |
— |
8. 待澄清项
全部 8 项已确认，无待澄清项。
9. 验收标准
- AC-001: Given 字段配置 STORED 计算公式 otal = price * qty, When 保存记录且 price=100, qty=3, Then total 持久化为 300
- AC-002: Given 字段配置 VIRTUAL 计算公式 otal = price * qty, When 查询记录且 price=100, qty=3, Then total 返回 300 且不存储
- AC-003: Given 主表字段配置聚合公式 SUM(detail.amount), When 从表新增一条 amount=50 的记录, Then 主表字段自动更新
- AC-004: Given 表单字段 A 引用 B, B 引用 C, C 引用 A, When 发布时, Then 检测循环依赖并禁止发布
- AC-005: Given 公式嵌套深度 4 层, When 发布时, Then 拦截并提示超限
- AC-006: Given 公式表达式语法错误, When 调用 validate 接口, Then 返回具体错误位置和原因
- AC-007: Given 配置公式的字段, When 用户在表单中编辑该字段, Then 字段不可编辑（只读）
- AC-008: Given 公式计算时抛出异常, When 查询/保存, Then 记录 ERROR 日志，公式字段保持原值或置 null
归档记录（HARD-GATE）
- 状态：done
- 归档时间：2026-06-27
- 归档人：yaomd（批量归档）
- 归档路径：code-copilot/changes/archive/2026-06-27-formula-capability-extension/
- 判定依据：任务清单全部完成，execution-log 验证通过（编译/构建/lint 闭环）。
