# FMS 计算公式设计 V1（评审修订版）

> **评审结论（2026-09-26）**：保留“公式属于表单配置、解析为 AST、依赖图拓扑重算、跨模块使用带入快照”的主方向；原稿不能直接实施。主要问题是把前端结果当成可信写入值、把不同作用域的字段编码放进同一张依赖图、未定义 `NULL`/覆盖保存语义，以及把尚未存在的子表运行时写成已可接入。本版将服务端校验与重算设为保存闭环的必要部分，并把 V1 的交付边界收窄到可验证的范围。

**本版必须满足的验收门槛**：

- 前端计算只负责即时反馈；服务端在同一保存事务内校验公式配置、计算结果和可覆盖权限，不能信任客户端提交的计算字段值。
- 依赖节点使用带作用域的 ID（至少区分主表字段、当前明细行字段、明细集合聚合），禁止仅用字段名建全局图。
- `NULL`、舍入、覆盖和历史快照语义在前后端共用一份规范；未实现服务端执行器前，不得宣称公式结果“可安全落库”。
- V1 先交付主表字段公式和引用带入快照；子表逐行公式、聚合及跨模块实时取数作为后续阶段，必须在关系标识和事务保存链路明确后接入。

## 1. 文档定位

本文是《FMS 新系统核心表结构设计》界面配置能力的补充设计，解决"单据字段由其它字段算出来"的问题：金额 = 数量 × 单价、税额 = 金额 × 税率、含税金额 = 金额 + 税额、表头合计 = 明细求和。

计算公式被设计成**界面配置的一部分**，不是数据库计算列，也不是可执行后端脚本；前后端各有一个受限求值器，服务端版本负责最终校验与重算：

```text
业务模块
  └── 表单配置（s_module_schema.edit）
        └── 字段节点 formula
              ├── 表达式（四则 / 函数 / 字段引用）
              ├── 依赖图（谁依赖谁，环路拒绝保存）
              └── 运行期求值（编辑弹窗内即时重算）

业务单据编辑
  └── 加载配置 + 建依赖图
        └── 依赖字段变更
              └── 按拓扑序重算计算字段
                    └── 提交预览值，由服务端校验/重算后落库
```

本文遵循以下已有设计：

- 《FMS 新系统核心表结构设计》6.2 节已明确：`readonly`、`required`、`disabled`、`visibleWhen`、`defaultValue`、`options`、`format` 和 `formula` 都属于**界面配置，不放入 `s_field`**；
- 计算字段若要参与 SQL、排序或筛选，写在模块的 `b_query_sql` 中，不依赖表单 JSON；
- 界面配置统一存 `s_module_schema.b_schema_json`，模块管理经通用接口 `/data/*` 读写，保存走逐表 diff；
- 不依赖数据库外键、触发器和 `CHECK` 约束表达业务规则；
- 前端组件自研优先，不轻易引入第三方依赖。

相关文档：

- [FMS 新系统核心表结构设计](./FMS新系统核心表结构设计.md)
- [FMS 工作流与审批设计](./FMS工作流与审批设计.md)

## 2. 设计目标与边界

### 2.1 设计目标

1. 表达式与字段绑定，配置一处生效一处，不需要为"公式"新建表；保存链路可复用现有数据接口，但必须增加公式处理钩子；
2. V1 覆盖主表字段间计算和跨模块带入快照；明细行内、明细汇总到表头、明细行引用表头先定义作用域契约，待子表保存链路具备后接入；
3. 语法可校验、可静态检查（字段存在性、类型、循环引用），不做"跑起来才知道错"；
4. 数值计算走十进制定点，杜绝 `0.1 + 0.2` 类浮点误差，金额落库精度确定；
5. 前端即时重算，用户改一个字段立刻看到结果，不需要保存后再刷新；
6. **依赖变更才重算**：打开旧单据不做静默改写，历史数据保持快照语义；
7. 计算结果经服务端校验/重算后随表单落库，列表显示、筛选、排序、合计、导出直接可用；
8. 允许按字段配置"可人工改写"，覆盖特价、手工调价等真实业务；
9. 引擎与作用域解耦（`ctx = { fields, rows, row }`），作用域信息进入依赖节点而不是依赖调用方猜测；
10. 解析、校验、求值规则可由前端和 Java 服务端共用测试向量，避免两套实现漂移。

### 2.2 设计边界

计算公式负责：

- 表达式解析、校验、求值；
- 依赖图构建、拓扑重算、循环检测；
- 编辑弹窗内的即时重算与覆写交互；
- 服务端保存事务中的公式校验、重算和精度检查。

计算公式不负责：

- 数据库计算列、视图、触发器等物理计算；
- 绕过模块保存策略的任意直写；所有会改变带公式模块数据的入口都必须经过服务端公式校验/重算；
- 跨模块**实时取数**（本期用"引用带入快照"，见 13 章）；
- 可视化公式拼装（本期为文本表达式 + 插入面板）；
- 替代业务领域的复杂结算逻辑（税率表、阶梯价、多币种折算等应沉淀在业务字段与带入值中）。

> 服务端公式执行属于 V1 的必要范围，不再列为“以后再做”。可以先只支持主表公式，但保存、导入、工作流回写必须共用同一个权威校验入口。

## 3. 现状与问题

### 3.1 现状

| 环节 | 现状 |
| --- | --- |
| 字段属性 | 表单 JSON 的字段节点现有属性：`field`、`span`、`visible`、`required`、`readonly`、`disabled`、`height`、`placeholder`、`defaultValue` |
| 编辑器适配层 | `design-editor/common/schemaModel.js` 通过 `row._node` 保留节点上的未知扩展属性，回写时展开，因此现在写入 `formula` 不会被编辑器吞掉（前向兼容） |
| 表单运行时 | `components/fms-module-edit/FmsModuleEditModal.vue` 按配置渲染、按默认值预填、按 `b_readonly` / `b_disabled` / 主键控制禁用 |
| 表达式能力 | 唯一已有的表达式是工作流条件（布尔 AST + `WorkflowConditionEvaluator`），只做判断不做计算，且不在本设计内复用 |
| 旧系统 | `s_expression` / `s_expressiongroupids`（《Fms旧系统表结构》）以"表达式组 + 序号 + 文本"保存，无类型、无校验、无作用域，仅作参考，不沿用 |

### 3.2 问题

| 现状 | 问题 |
| --- | --- |
| 金额、税额、合计靠人录入 | 口径依赖人的算术，错一行传一路 |
| 想在页面里写点计算 | 没有配置能力，只能改成业务定制代码，配置人员无法自助 |
| 若用数据库计算列 | 与"界面配置统一存 JSON"的既有设计冲突，且模块换表、字段调整都要动 DDL |
| 若用后端脚本 | 前端看不到即时结果，录入体验差；且引入了新的脚本安全面 |

## 4. 核心概念

### 4.1 计算公式

写在表单 JSON 字段节点上的字符串表达式，声明"这个字段的值由其它字段算出"。例如：

```text
ROUND(b_qty * b_price, 2)
IF(b_qty > 0, b_amount / b_qty, NULL)
SUM(lines.mx_amount)
```

其中最后一条仅是后续子表阶段示例，V1 不允许保存。

### 4.2 计算字段

挂了 `formula` 的字段。约定：**计算字段自动只读**，用户不能直接填；是否允许人工改写由 `overridable` 决定（见 11 章）。计算字段必须出现在表单配置中（不在表单里的字段没有节点，无处挂公式）。

### 4.3 作用域

表达式里的字段引用必须先解析为带作用域的引用，不能只保存一个字段名。V1 的解析范围按由近到远：

| 顺序 | 作用域 | 说明 |
| --- | --- | --- |
| 1 | 当前行 | 仅后续子表阶段启用；明细行公式内优先命中本行字段 |
| 2 | 主表 | 当前单据的主表字段（含带入字段、隐藏字段） |
| 3 | 带入字段 | 选择器写入的主表字段，本质同 2，但保留来源元数据 |

解析不到、作用域不唯一或引用停用字段：设计期阻断保存；运行期配置异常也必须由服务端拒绝保存，不能静默按空值落库。

### 4.4 依赖图

以字段为节点、以"公式引用"为边构成的图。两个用途：

- **保存配置时**：拓扑排序，剩余有入度的节点即环路 → 拒绝保存并指出环路；
- **运行期**：某字段变化 → 取其下游闭包 → 按拓扑序重算。

### 4.5 重算时机

**依赖变更才重算**：编辑旧单据时，依赖值未变则保留历史计算结果；依赖值变化时按当前公式重算。新增记录执行一次全量初算。服务端必须对客户端传入的计算字段做同样的判断和校验，不能仅依赖前端快照。

### 4.6 覆写

`overridable = true` 的字段，允许用户手工改写；改写后该字段在**当前编辑会话**内不再被公式覆盖，直到用户点"恢复公式"或关闭弹窗。覆写状态不持久化，跨会话的保留依赖"依赖变更才重算"语义（见 11 章）。

## 5. 总体架构

```text
配置期（模块管理 · 表单设计器）
  字段属性面板
    ├── 公式输入 + 插入字段/函数 + 实时校验 + 试算
    └── 可覆写开关
          ↓ 写入草稿
  s_module_schema.edit 的字段节点 { formula, overridable }
          ↓ 保存前校验（语法 / 字段 / 类型 / 循环 / 互斥）
  /data/saveobjt 落库

运行期（业务单据编辑弹窗）
  加载配置 → 解析表达式 → 建依赖图 → 建立值快照（不计算）
        ↓ 用户改动依赖字段
  快照对比 → 变更字段集 → 下游闭包 → 拓扑序重算 → 收敛 → 更新快照
        ↓ 提交
  提交用户输入 + 公式预览 → 服务端校验/重算 → 列表/筛选/排序/导出直接可用
```

## 6. 配置模型

### 6.1 字段节点扩展

在《FMS 新系统核心表结构设计》6.2 节表单节点的 FieldNode 上增加两个属性：

```json
{
  "field": "b_amount",
  "readonly": true,
  "formula": "ROUND(b_qty * b_price, 2)",
  "overridable": true
}
```

| 属性 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `formula` | string | 否 | 表达式文本。缺失或空串即普通字段；仅字段节点可挂，行节点与分组节点不允许 |
| `overridable` | boolean | 否 | 仅 `true` 时写出。缺省即严格只读，不写该属性 |
| `readonly` | boolean | — | 由设计器在挂公式时自动置 `true`；运行期以"有 `formula` 即只读"兜底，双保险 |

V1 仅允许 `data` 模块且公式目标字段必须存在于 `b_save_table` 的真实可写列中；`virtual` 模块、查询 SQL 别名和纯展示字段如果没有独立保存处理器，不能挂需要落库的公式。配置保存时同时校验目标列的 nullable、precision 和 scale。

### 6.2 存储约定

- 继续存 `s_module_schema(b_module_id, b_schema_type = 'edit').b_schema_json`，**不新建表、不新建公式专用接口**；现有保存接口需增加模块标识和公式处理元数据；
- 不写入 `s_field`：`s_field` 只表达业务元数据（字段编码、名称、类型、启用、顺序），公式属于界面行为；
- 不新增 `b_schema_type`：公式是表单配置的一部分，不单独成行；
- 编辑器适配层用 `row._node` 保留未知属性，因此**未升级的设计器不会破坏已存在的公式**；
- 服务端对规范化后的公式节点计算 `formulaRevision`（不新建表），记录/保存请求携带摘要用于防止编辑页面使用过期口径。
  - 实现说明：摘要是「规范化公式节点」的 FNV-1a 64（字段按编码升序，含 `formula` 与 `overridable`），前后端算法一致、客户端可自行计算，因此不需要额外接口下发；
  - 目标列的 `nullable` / `precision` / `scale` 不进摘要（客户端拿不到数据库元数据），由服务端在保存事务内直接校验（见 10.6）。

### 6.3 与相邻能力的关系

| 相邻能力 | 关系 |
| --- | --- |
| 自动编码（`s_autocode`） | 自动编码字段在表单中自动只读，**不允许挂公式**（设计器校验拦截） |
| 字段权限（`s_user_field_power`） | 严格计算字段不可编辑；允许覆写的字段仍必须同时满足字段权限的可编辑位和 `overridable=true`，不能用公式开关绕过权限 |
| `b_query_sql` | 列表筛选/排序直接读落库值，不需要在 SQL 里重复写公式；只有需要"查询期实时计算"（如按当前汇率折算）才用 SQL |
| 工作流条件 | 两套语法各司其职：条件做布尔判断，公式做数值/文本计算，不互相调用 |

## 7. 表达式语法

### 7.1 词法单元

| 类别 | 规则 | 示例 |
| --- | --- | --- |
| 字段引用 | `[a-z][a-z0-9_]*`，与 `s_field.b_field` 一致；后续聚合允许 `relationId.field` | `b_qty`、`mx_price`、`lines.mx_amount` |
| 函数名 | `[A-Z][A-Z0-9_]*`，**全大写** | `ROUND`、`IF`、`SUM` |
| 数字 | `123`、`1.5`；不支持千分位与科学计数法，负号走一元运算 | `12.5` |
| 字符串 | 单引号包裹，`\'` 转义 | `'含税'` |
| 布尔 | `TRUE` / `FALSE` | `TRUE` |
| 空值 | `NULL` | `NULL` |
| 运算符 | `+ - * / % & ( ) , > >= < <= == != ! AND OR NOT` | `a > 0 AND NOT(ISBLANK(b))` |
| 其它 | 空白忽略；不支持注释 | — |

字段用小写、函数用全大写，大小写敏感，天然无歧义，不需要 `{}` 之类定界符。

### 7.2 类型系统

由 `s_field.b_type` 映射到公式类型：

| `b_type` | 公式类型 | 说明 |
| --- | --- | --- |
| `number`、`money` | decimal | 十进制定点 |
| `checkbox` | boolean | 参与逻辑运算 |
| `date`、`datetime` | date | 日期运算 |
| `input`、`textarea`、`select` | text | `select` 取值为编码字符串 |

- 不做隐式类型转换（decimal 与整数字面量之间除外），避免"看起来很智能、出错很难查"；
- 提供显式转换：`TEXT(x)`、`NUMBER(x)`；
- 设计期能静态判断的类型不匹配（如文本字段参与乘法）直接报错。

### 7.3 运算符与优先级

由高到低：

| 优先级 | 运算符 | 说明 |
| --- | --- | --- |
| 1 | `( )` | 分组 |
| 2 | 一元 `-`、`!` | 取负、取非 |
| 3 | `*` `/` `%` | 乘、除、取模 |
| 4 | `+` `-` | 加减（仅数值，字符串拼接用 `&`） |
| 5 | `&` | 文本拼接 |
| 6 | `>` `>=` `<` `<=` `==` `!=` | 比较，结果为 boolean |
| 7 | `AND` | 逻辑与 |
| 8 | `OR` | 逻辑或 |

用 `&` 而非 `+` 做拼接，避免与算术混用产生歧义，符合表格软件的使用习惯。

### 7.4 字段引用与作用域解析

- V1 主表公式：只解析主表字段；出现明细字段或聚合函数直接报“不支持”；
- 后续明细行公式：先本行、再主表（`mx_qty * b_price` 即行内取表头值）；聚合必须带 `relationId`；
- 带入字段：作为主表字段直接引用（`b_discount_rate`）。

### 7.5 字面量

`NULL` 是合法值，可在 `IF` 分支中显式产出空值：`IF(b_qty > 0, b_amount / b_qty, NULL)`。`NULL` 不允许直接参加 `==` / `!=` 比较，统一使用 `ISBLANK(x)`；否则容易把空值误当成普通编码值。

### 7.6 空值、除零与错误值语义

| 情形 | 语义 |
| --- | --- |
| 空值参与算术 | 按 0 计算（业务直觉：没填就是没有） |
| 空值参与拼接 | 按空串 |
| 空值参与比较 | 结果为 `NULL`；`IF` 将 `NULL` 条件按 false 处理，`AND` / `OR` 使用三值逻辑 |
| 除数为 0 或空 | 结果为空值（`NULL`），**不落 0**，避免"0 元"误导 |
| 取模为 0 | 同上 |
| 预览期类型不匹配 | 显示错误态并阻止提交，不把空值伪装成合法结果 |
| 结果为 `NULL` | 落库为空值，不用 0 冒充 |

### 7.7 精度与舍入

- 内部一律十进制定点（字符串 + 缩放整数），不使用 JS 浮点；除法保留 20 位有效小数，最后按结果精度收敛；
- 落库精度以目标数据库列的真实 `precision/scale` 为准（`s_field` 当前不保存这两个属性），服务端保存前必须做溢出检查和统一舍入；不能把所有 `money` 固定成 2 位；
- `ROUND` 的舍入规则固定为 half-up，并在前后端测试向量中覆盖负数；未显式 `ROUND` 时只在落库边界按数据库列 scale 收敛；
- 展示格式沿用字段类型与 `format` 配置，不在公式层处理千分位等外观。

## 8. 函数库

### 8.1 数值

| 函数 | 说明 |
| --- | --- |
| `ROUND(x, n)` / `ROUNDUP` / `ROUNDDOWN` | 四舍五入 / 向上 / 向下舍入到 n 位 |
| `ABS(x)` | 绝对值 |
| `CEIL(x)` / `FLOOR(x)` | 向上 / 向下取整 |
| `MOD(a, b)` | 取模，b 为 0 时返回空值 |
| `POW(a, b)` / `SQRT(x)` | 乘方 / 平方根（负数开方返回空值） |
| `MIN(...)` / `MAX(...)` | 多参数取最小 / 最大 |

### 8.2 条件与空值

| 函数 | 说明 |
| --- | --- |
| `IF(cond, a, b)` | 条件取分支；只计算命中的分支 |
| `IFBLANK(x, fallback)` | x 为空时取 fallback |
| `COALESCE(...)` | 返回第一个非空值 |
| `ISBLANK(x)` | 是否为空 |
| `AND(...)` / `OR(...)` / `NOT(x)` | 逻辑运算的函数形式 |

### 8.3 文本

| 函数 | 说明 |
| --- | --- |
| `CONCAT(...)` / `&` | 拼接 |
| `LEN(x)` | 长度 |
| `LEFT(x, n)` / `RIGHT(x, n)` / `MID(x, start, n)` | 截取 |
| `UPPER(x)` / `LOWER(x)` / `TRIM(x)` | 大小写与去空白 |
| `REPLACE(x, from, to)` | 替换 |
| `TEXT(x)` / `NUMBER(x)` | 显式类型转换 |

### 8.4 日期

| 函数 | 说明 |
| --- | --- |
| `TODAY()` / `NOW()` | 当天 / 当前时刻；V1 禁止用于持久化公式（非确定性），后续需增加显式 `volatile` 重算策略 |
| `DATEADD(x, n, unit)` | 日期加减，unit 取 `day` / `month` / `year` |
| `DATEDIFF(a, b, unit)` | 日期差 |
| `YEAR(x)` / `MONTH(x)` / `DAY(x)` | 取年 / 月 / 日 |
| `FORMATDATE(x, format)` | 按格式输出文本 |

### 8.5 聚合（作用于明细/子表）

仅在**后续子表阶段的主表公式**中可用，参数必须带关系作用域；V1 保存校验暂不放行聚合函数：

| 函数 | 说明 |
| --- | --- |
| `SUM(field)` | 求和 |
| `AVG(field)` / `COUNT(field)` | 平均 / 计数（非空行） |
| `MIN(field)` / `MAX(field)` | 最小 / 最大 |

说明：聚合函数将使用 `relationId.field` 形式消除多个子表同名字段的歧义；聚合依赖、行增删和子表事务保存未落地前，配置保存必须报“V1 暂不支持”。条件形式（如 `SUM(lines.mx_amount, lines.mx_flag == 1)`）另行设计。空集合的 `SUM` 为 0，`AVG` / `MIN` / `MAX` 为空值。

### 8.6 取数（预留）

`LOOKUP(模块, 条件字段, 条件值, 取值字段)` 本期**不实现**：设计期遇到即报错并提示"暂不支持，请改用引用带入字段"。不保留可执行的“语法位”，避免前端能保存而服务端无法复核。

### 8.7 函数命名与未实现策略

- 函数名全大写、`snake` 之外无特殊字符；
- 未知函数：设计期报错；历史配置在运行期遇到未知函数时允许查看原值，但禁止覆盖保存并上报配置异常；
- 错误文案集中在 `formula/messages.js`，纳入 i18n 资源键管理。

## 9. 依赖与求值

### 9.1 求值上下文

```js
ctx = {
  fields: { b_qty: 3, b_price: '12.5', ... },  // 主表（含带入字段与静默加载的隐藏字段）
  rows: [ { mx_qty: 2, ... }, ... ],           // 明细行集合；无子表时为 null
  row: { mx_qty: 2, ... },                     // 当前行（明细行公式）
  meta: { moduleId, recordId, isNew, now }
}
```

求值是**同步纯函数**：`evaluate(ast, ctx) → { value, error }`。这正是"引用带入快照"取代实时取数的原因——引擎不必处理异步与缓存。

### 9.2 依赖抽取

`refsOf(ast) → { refs: [{ scope, relationId?, field }], aggregates: [{ fn, relationId, field }], usesRow: boolean }`

- `refs`：带作用域的直接引用；主表节点形如 `main:b_amount`，当前行节点形如 `row:<relationId>:mx_amount`，不得把同名字段合并；
- `aggregates`：带关系 ID 的聚合引用，用于把"明细行集合变化"也当作依赖；
- `usesRow`：是否依赖当前行，供子表接入时按行实例化。

### 9.3 拓扑重算

- 依赖图由各公式的 `refsOf` 结果构建，节点是 `scope + relationId + field`，不是裸字段名；
- 变更字段集合 → 计算下游闭包 → 拓扑排序 → 顺序求值；
- 链式公式（`main:a → main:b → main:c`）天然正确，因为重算按依赖方向推进；跨行聚合必须把行增删、行字段更新都转换成对应关系节点的变更。

### 9.4 循环引用检测

保存配置时对所有带作用域的公式节点执行拓扑排序；剩余节点即构成环路，报"检测到循环引用：main:a → row:lines:mx_b → main:a"。设计期也能实时提示，但以保存拦截为准。V1 遇到子表节点或聚合节点直接报不支持，不得以不完整图继续保存。

### 9.5 求值失败降级

| 阶段 | 失败类型 | 处理 |
| --- | --- | --- |
| 设计期 | 语法错误、字段不存在、循环引用、类型不匹配、函数不支持、互斥违规 | **阻断配置保存**，指出位置或环路 |
| 运行期预览 | 单个字段求值异常（类型不符、函数参数非法） | 前端显示错误态，不把空值伪装成合法结果 |
| 保存期 | 公式配置、依赖值或计算结果校验失败 | 服务端拒绝整个事务，返回字段和公式位置 |
| 历史数据 | 旧配置解析失败 | 允许查看原值，但禁止覆盖保存，提示管理员修复配置 |

## 10. 运行期集成

### 10.1 编辑弹窗重算管线

在 `FmsModuleEditModal.vue` 现有"加载配置 → 校验 → 构建表单数据"管线之后追加前端预览；真正写入由服务端公式保存处理器负责：

1. 解析：遍历表单字段节点，解析所有 `formula`，缓存 AST；
2. 建图：`refsOf` → 依赖图 + 拓扑序；发现环路即显示错误并阻止提交，不能跳过后继续保存；
3. 快照：记录当前所有字段值（**此时不计算**）；
4. 监听与重算（见 10.3）；
5. 提交：提交用户输入、公式配置摘要和临时覆盖声明；计算字段值仅作为预览，不是可信数据。

### 10.2 初始化不重算与新增初算

| 场景 | 行为 |
| --- | --- |
| 编辑已有记录 | 回填后只建快照、不计算；依赖未变时保留历史值，依赖变更时前端预览并由服务端按当前公式重算 |
| 新增记录 | 按默认值构建后执行一次全量初算；服务端保存时再次计算并以服务端结果为准 |

### 10.3 重算收敛（快照对比法）

不区分"用户输入"还是"程序写回"，避免脆弱的来源标记：

1. `watch(formData, { deep: true })` 触发后与快照逐字段比较，得到真实变化集；
2. 变化集为空 → 结束；
3. 非空 → 取下游闭包，按拓扑序重算，写回 formData；
4. 回到第 1 步，直到无变化（通常一轮收敛；链式公式最多两轮）。

同一轮输入用 `nextTick` 合并，避免逐字符触发。

### 10.4 隐藏依赖字段

现状：当前 `FmsModuleEditModal.vue` 按 `b_visible !== 1` 过滤字段，隐藏字段不会进入 `formData`；`collectRowData()` 还会跳过只读/禁用字段。因此原稿所说的“静默加载”和“计算字段落库”目前都未实现。

策略：加载配置后，把"被公式引用但不在可编辑行里"的字段纳入**静默字段集合**——只取值、不渲染：

- 参与求值：进 `ctx.fields` 与 formData；
- 不参与渲染与用户编辑；
- 保存时按基线 diff；计算字段由公式保存处理器单独处理，不能因 `readonly` 被前端 `collectRowData()` 丢弃。未改动的普通隐藏字段不提交，避免旧值回写造成并发覆盖。

### 10.5 提交与保存

- 计算字段与覆写态字段随请求提交供服务端校验，但不应被当作普通字段绕过公式保存处理器；
- 只读用 `readonly` 表达，**不用 `disabled`**——`disabled` 在部分控件下不参与提交；
- 提交值不是权威值。服务端保存处理器必须加载当前 `edit` 配置和数据库列元数据，在同一事务内执行：公式校验 → 依赖变更判断 → 严格公式重算/覆盖值校验 → 精度校验 → 写入。通用 `saveobjt` 需要增加 `moduleCode` 和公式处理元数据，或由模块保存服务包装调用；仅传 `table + key_field` 的直写请求不得写入带公式模块。

请求元数据示例（不写入业务表）：

```json
{
  "table": "b_order",
  "moduleCode": "b_order",
  "formulaRevision": "sha256:...",
  "key_field": "b_id",
  "formulaOverrides": ["b_amount"],
  "updates": [{ "b_id": "...", "b_qty": 3, "b_amount": "12.00" }]
}
```

`moduleCode` 必须由服务端校验其对应的保存表，不能由客户端借此扩大可写范围；`formulaRevision` 是服务端按规范化公式节点计算的摘要，变化时拒绝本次保存并要求刷新；`formulaOverrides` 只能列出当前请求实际修改且配置允许覆盖的字段。

### 10.6 服务端保存规则（V1 必须实现）

服务端以数据库旧值和本次请求合并出 `newRow`，按公式节点逐个处理：

1. 新增记录：所有严格计算字段均由公式计算；客户端传入值被忽略，覆写字段只有在声明临时覆盖且配置允许时才采用。
2. 编辑记录且依赖未变：严格计算字段保留旧值，但若请求显式改写该字段，必须验证其等于公式结果；不一致则拒绝或以公式结果替换，不能静默接受。
3. 编辑记录且依赖已变：严格计算字段由服务端重算。`overridable=true` 的字段只有在请求的 `formulaOverrides` 明确包含该字段时才接受人工值；该声明不落库，仅在本次事务有效。
4. 公式字段不得通过普通 `updates` 绕过上述流程；导入、工作流回写、批处理复用同一服务，否则直接拒绝写入并返回“需经公式保存处理器”。
5. 服务端计算结果必须按实际数据库列的 precision/scale 校验；任一公式失败时整个保存事务回滚。
6. 服务端读取旧行并写入新行必须使用乐观并发版本（优先 `b_updated_at`/ETag，或在事务内锁定目标行）；版本冲突时回滚，不能基于过期旧值计算后覆盖他人修改。

### 10.7 明细行与汇总（后续阶段）

引擎可以预留 `ctx.rows` / `ctx.row`，但 V1 不宣称已支持；主子表编辑和服务端事务保存就绪后：

- 明细行公式：每行一个上下文实例，按行重算；
- 主表汇总公式：`refsOf` 的 `aggregates` 使"行集合增删改"也构成依赖 → 触发主表重算；
- 表头变更影响明细行（`mx_qty * b_price`）→ 行内公式重算 → 若汇总又依赖行内计算字段，则继续推进，收敛逻辑天然支持。

## 11. 覆写策略

### 11.1 字段级开关

| `overridable` | 行为 |
| --- | --- |
| 缺省（false） | 严格只读，值恒等于公式结果 |
| `true` | 默认显示公式结果，字段旁提供"手工调整"入口；入口临时解除只读并产生 `formulaOverrides`，不是把 `readonly` 永久改成可编辑 |

### 11.2 会话内覆写

- 用户手工改写后，该字段进入"已覆写"态，**当前会话内不再被公式覆盖**（即使依赖字段再变）；
- 提供"恢复公式"：重算一次并退出覆写态；
- 覆写态在 UI 上有明确标识（如字段旁标记），避免"值看起来算错了"的困惑。
- 保存时通过请求元数据 `formulaOverrides: ["b_amount"]` 传递本次会话的覆写声明；该列表不是业务字段，不落库，由服务端校验字段的 `overridable` 后才接受人工值。

### 11.3 跨会话语义

不持久化覆写状态，重开单据依靠"依赖变更才重算"保留人工值；但服务端仍会校验显式提交值，防止通用接口伪造覆写：

| 场景 | 结果 |
| --- | --- |
| 重开旧单据、未改依赖字段 | 人工值保留 |
| 重开旧单据、改了依赖字段 | 公式重算并覆盖人工值（**公式优先**） |

这是有意为之：等价于"人工值是一次性快照，公式在输入变化时恢复主导"。若将来出现"人工值必须永久锁定"的硬需求，再引入覆写标记表（见 18 章），不提前加表和分支。

## 12. 配置端（设计器）

### 12.1 字段属性面板

在 `design-editor/form/FormInspector.vue`（纯展示、变更均 emit 上抛）新增「计算公式」区，仅字段节点可见：

- 表达式输入框（多行可展开）；
- 「插入字段」「插入函数」按钮，打开插入面板；
- 「允许人工改写」开关（对应 `overridable`）；
- 实时校验结果与错误定位（列位置）。

配套改动：`schemaModel.js` 的字段行草稿增加 `b_formula` / `b_overridable` 两个字段（加载、回写、默认值删除策略与其他属性一致：空值即删除属性），`FormDesignEditor.vue` 承接 emit 写入草稿。

### 12.2 插入面板与试算

- 字段列表：本模块字段（标注主表 / 明细）、带入字段；插入时写入字段编码；
- 函数列表：按 8 章分类展示，选中插入函数模板并聚焦到参数位置；
- 试算：用各字段的默认值（或手工填的示例值）执行一次求值，展示结果与中间错误，帮助配置人自查。

### 12.3 校验与拦截

- 实时：语法、字段存在性、类型不匹配；
- 保存配置前：`module-management/index.vue` 做交互校验；服务端保存配置时必须再次校验——语法、字段存在性、循环引用、自动编码互斥、聚合使用位置、明细字段裸用；
- 阻断保存并给出可读错误列表；循环引用需展示完整环路。

### 12.4 画布标识与引用清理

- 画布上计算字段显示 `fx` 角标（样式归属 design-editor 内部，走组件作用域样式）；
- 删除 / 停用被引用的字段时，提示"被 N 个公式引用（列出字段名）"，**不自动改写公式**——静默改语义比报错更危险，交由配置人决定；
- 字段改名（改 `b_field`）同理提示。

## 13. 跨模块取数

本期采用**引用带入快照**：

```text
选择客户（选择器）
  └── 把折扣率、结算方式等写入本地字段（带入字段，s_field 中登记）
        └── 公式只引用本地字段：b_amount * b_discount_rate
```

| 维度 | 结论 |
| --- | --- |
| 求值 | 同步可算，无需异步取数、缓存与失败降级 |
| 历史 | 快照稳定：主数据后续变更不回溯已保存单据 |
| 代价 | 主数据变更后需显式重选/重带才会更新 |
| 约束 | 带入字段必须在本模块 `s_field` 登记（可见或隐藏），否则设计期报错 |
| 演进 | 实时取数另立语法和权限设计；当前不接受 `LOOKUP` |

## 14. 与列表、查询、其它入口的关系

### 14.1 列表与查询

计算字段的值已落库，因此：

- 列表显示、筛选、排序、合计（`view` 的 `summary: sum/count`）、导出**直接可用**，不需要在 `b_query_sql` 里重复定义公式；
- 口径快照：公式后续修订**不回刷历史值**，历史行仍按旧口径。这是"依赖变更才重算"的必然结果，属有意设计；需要统一口径时走批量重算（见 18 章）。

### 14.2 非前端入口

接口直写、数据导入、工作流回写、批处理**必须经过同一个服务端公式保存处理器**，不能各自实现一套计算：

- 业务入口传入模块编码和完整变更上下文，由服务端加载公式配置并重算/校验；
- 不能识别模块或无法完成公式校验时，拒绝写入，而不是落空值或接受客户端结果；
- 当前 `DataController.saveObject()` / `DataSaveService` 只按 `table + key_field` 执行普通 SQL，尚无该钩子；在钩子完成前，本设计只能作为未交付能力，不能开放带公式模块的通用直写。

### 14.3 字段权限

严格计算字段在 `s_user_field_power` 中只保留可见性；允许覆写的字段还要校验可编辑权限，`formulaOverrides` 不能绕过字段权限。

## 15. 校验规则汇总

| # | 规则 | 时机 | 处理 |
| --- | --- | --- | --- |
| 1 | 表达式语法错误 | 实时 + 保存前 | 阻断 |
| 2 | 引用字段不存在 / 已停用 | 实时 + 保存前 | 阻断 |
| 3 | 循环引用 | 实时 + 保存前 | 阻断，展示环路 |
| 4 | 类型不匹配（可静态判断） | 实时 + 保存前 | 阻断 |
| 5 | 自动编码字段挂公式 | 保存前 | 阻断 |
| 6 | V1 使用聚合函数或明细行作用域 | 实时 + 保存前 | 阻断，提示等待子表阶段 |
| 7 | 主表公式裸用明细字段（未包关系聚合） | 保存前 | 阻断，提示使用带 `relationId` 的聚合 |
| 8 | 使用未实现函数（如 `LOOKUP`） | 实时 | 阻断并提示替代方案 |
| 9 | 依赖字段被隐藏 | 保存前 | 允许，但必须纳入静默字段集合；当前运行时未实现时阻断 |
| 10 | 带入字段未在 `s_field` 登记 | 保存前 | 阻断 |
| 11 | 仅 `table + key_field` 的普通直写 | 保存前 | 带公式模块阻断，必须经过公式保存处理器 |
| 12 | 客户端计算字段与服务端结果不一致 | 保存时 | 整个事务阻断并返回字段错误 |
| 13 | 使用 `TODAY()` / `NOW()` 等非确定性函数 | 配置保存前 | V1 阻断，提示使用显式业务日期字段 |
| 14 | 公式目标不是可写数据表真实字段，或目标列不允许为空但结果为空 | 配置/保存前 | 阻断 |
| 15 | 公式配置版本与编辑页面不一致 | 保存时 | 拒绝并提示刷新，避免按新旧口径静默保存 |
| 16 | 覆写字段没有字段编辑权限 | 保存时 | 拒绝 `formulaOverrides`，保持公式结果 |

## 16. 代码结构与接口

### 16.1 引擎模块

```text
fms-vue/src/components/fms-module-common/formula/
├── decimalMath.js   十进制定点运算（加 / 减 / 乘 / 除 / 比较 / 舍入）
├── values.js        值类型系统（decimal / boolean / text / date / null 与字段类型映射）
├── lexer.js         词法分析
├── parser.js        语法分析 → 带位置的 AST
├── functions.js     函数库（签名 + 实现 + 元信息，供插入面板复用）
├── evaluate.js      求值（作用域解析 / 空值 / 精度 / 降级）+ 静态类型推断
├── deps.js          依赖抽取（refsOf）
├── graph.js         依赖图、拓扑排序与循环检测
├── validate.js      设计期校验（语法 / 字段 / 类型 / 位置）
├── revision.js      配置摘要（FNV-1a 64，前后端算法一致）
├── messages.js      错误文案（i18n 资源键集中）
└── index.js         对外 API（含 createFormulaModel 运行模型）
```

Java 侧镜像实现位于 `fms-api/.../service/formula/`，与前端共用
`fms-vue/tests/fixtures/formula-vectors.json` 的测试向量，防止两套实现漂移。

### 16.2 对外 API

| API | 说明 |
| --- | --- |
| `parse(text) → { ast, errors }` | 解析表达式，错误带列位置 |
| `evaluate(ast, ctx) → { value, error }` | 同步求值 |
| `refsOf(ast) → { refs, aggregates, usesRow }` | 返回带作用域/关系 ID 的依赖 |
| `validateFormula(text, { fields, scope, phase }) → errors[]` | 设计期和服务端保存期共用校验（返回 `{ ast, errors, refs, type }`，`errors` 为可读错误列表） |
| `validateFormulas(nodes, { fields }) → { errors, graph, results }` | 整模块校验：逐条 + 依赖图 + 循环引用 |
| `buildGraph(formulas) → { order, cycles }` | 建图与拓扑序 |
| `createRecalculator(graph) → recalc(fields, ctx)` | 运行期重算器 |
| `createFormulaModel({ editSchema, fields })` | 运行模型：`affectedFields / evaluateField / recalculate / revision` |
| `formulaRevision(nodes) → 'fnv1a64:…'` | 配置摘要（前后端一致） |

### 16.3 改动文件清单

| 文件 | 改动 |
| --- | --- |
| `design-editor/common/schemaModel.js` | 字段行草稿增加 `b_formula` / `b_overridable`（加载、回写） |
| `design-editor/form/FormInspector.vue` | 新增「计算公式」区与 emit |
| `design-editor/form/FormDesignEditor.vue` | 承接公式变更写入草稿 |
| `design-editor/common/FormulaEditor.vue`（新增） | 表达式输入 + 插入面板 + 实时校验 + 试算 |
| `module-management/index.vue` | 保存前统一校验（含环路） |
| `components/fms-module-edit/FmsModuleEditModal.vue` | 重算管线、静默字段加载、覆写交互 |
| `components/fms-module-common/formula/*`（新增） | 引擎（含 values.js / revision.js）与单元测试 |
| `fms-vue/tests/fixtures/formula-vectors.json`（新增） | 前后端共享测试向量 |
| `fms-vue/tests/unit/formula-engine.spec.js` 等（新增） | 引擎 / 设计器 / 运行期集成测试 |
| `fms-api/.../formula/*`（新增） | Java 服务端解析/校验/求值；与前端共享语法和测试向量 |
| `DataSaveService` 或模块保存服务 | 在同一事务内接入公式校验、重算、覆盖声明和精度检查 |

## 17. 测试与验收清单

### 17.1 引擎单测

- 词法 / 语法：优先级、括号、一元负号、错误位置；
- 精度：`0.1 + 0.2`、乘除与舍入、20 位除法收敛、按数据库列 scale 的 half-up；
- 空值 / 除零 / `NULL` 字面量、禁止 `== NULL` 与 `IF` 分支；
- 函数：逐个覆盖正常与边界（负数开方、`MID` 越界、`DATEDIFF` 跨月跨年）；
- 依赖：`refsOf` 对带作用域的直接引用 / 关系聚合 / 当前行的识别；
- 图：链式拓扑序、自环与多节点环路检测；
- 校验：字段不存在、类型不匹配、自动编码互斥、聚合位置。

### 17.2 运行时组件测试

- 打开旧单据不重算；新增记录初算一次；
- 依赖字段变更触发重算、链式两轮收敛、无变化不重算；
- 覆写后不再被覆盖、恢复公式可回到计算结果；
- 隐藏依赖字段静默加载且未改动不提交。

### 17.3 服务端保存测试

- 直接调用 `saveobjt` 不能绕过带公式模块的校验；缺少 `moduleCode` 或公式上下文时拒绝；
- 新增和依赖变更时服务端结果覆盖客户端伪造值；依赖未变时历史值保持且显式不一致值被拒绝；
- `formulaOverrides` 只能覆盖 `overridable=true` 的字段，且不写入业务表；
- 前后端使用同一组 JSON 测试向量，覆盖精度溢出、循环、函数错误和事务回滚。

### 17.4 验收样例

| 场景 | 公式 |
| --- | --- |
| 主表金额 | `ROUND(b_qty * b_price, 2)` |
| 除零保护 | `IF(b_qty > 0, b_amount / b_qty, NULL)` |
| 表头合计（后续子表阶段） | `SUM(lines.mx_amount)` |
| 编号拼接 | `b_name & '-' & b_no` |
| 含税金额 | `b_amount + ROUND(b_amount * b_tax_rate, 2)` |

## 18. 后续演进

| 方向 | 说明 |
| --- | --- |
| 子表运行时接入 | 明确 `relationId`、逐行保存顺序、聚合依赖和事务边界后再实现 |
| 实时取数 | 另立设计；不在当前语法中保留未实现的 `LOOKUP` |
| 永久锁定覆写 | 引入覆写标记表（模块 + 记录主键 + 字段 + 覆写人/时间），保存同事务写入 |
| 批量重算历史数据 | 公式修订后按新口径重算存量记录（列表页动作 + 服务端执行） |

## 19. 决策记录

| # | 决策 | 结论 | 依据 |
| --- | --- | --- | --- |
| 1 | 存储位置 | `s_module_schema.edit` 字段节点 `formula` | 核心设计文档 6.2 已明确"公式属界面配置，不入 `s_field`"；不建新表、不建公式专用接口，现有保存请求需扩展公式元数据 |
| 2 | 计算范围 | V1 先交付主表字段与带入快照；子表场景后续接入 | 当前编辑器和保存链路尚无可靠的关系/明细事务上下文，先避免不可验证的“设计到位” |
| 3 | 求值位置 | 前端预览 + 服务端权威校验/重算，结果落库 | 录入即时反馈与数据完整性同时成立；所有入口共享同一口径 |
| 4 | 重算时机 | 依赖变更才重算，新增记录初算 | 历史数据快照语义，不做静默改写 |
| 5 | 引擎实现 | 自研轻量解析器 + 十进制定点 | 零第三方依赖，贴项目自研风格；语法与函数库完全可控 |
| 6 | 跨模块取数 | 引用带入快照 | 同步求值、历史稳定；实时取数另立设计，不保留未实现语法 |
| 7 | 人工覆写 | 字段级 `overridable` + 请求级 `formulaOverrides` | 覆写状态不入业务表，但必须让服务端能验证本次会话声明，避免普通直写绕过 |
| 8 | 配置界面 | 文本表达式 + 插入面板 + 实时校验 + 试算 | 配置人是管理员，表达式直接可读；可视化拼装收益低于成本 |