643 lines
25 KiB
Markdown
643 lines
25 KiB
Markdown
# FMS 通用保存接口（saveobjt）使用说明
|
||
|
||
> 配套文档：《FMS通用保存接口条件更新设计》（机制与取舍）
|
||
> 本文只讲**怎么用**：请求怎么写、服务端生成什么 SQL、各种情况下返回什么。
|
||
> 示例表沿用设计文档附录 A 的 `demo_order`（报销单主表）/ `demo_order_fee`（费用明细）。
|
||
|
||
---
|
||
|
||
## 0. 一句话
|
||
|
||
`saveobjt` 原本是**按主键盲写**。现在可以给写入附加两类东西：
|
||
|
||
| 附加物 | 作用 | 位置 |
|
||
| --- | --- | --- |
|
||
| `guards` | 业务前置条件（"只有草拟状态才能改"） | 表块级，按动作分开 |
|
||
| `$original` | 并发冲突检测（"改的时候它还得是我看到的那个值"） | 更新行内 |
|
||
|
||
**两者都是 opt-in。不传，行为与以前完全一致。**
|
||
|
||
---
|
||
|
||
## 1. 请求格式速查
|
||
|
||
```jsonc
|
||
[
|
||
{
|
||
"table": "demo_order_fee", // 必填
|
||
"key_field": "b_id", // 必填，复合键用逗号分隔
|
||
"guards": { // 可选
|
||
"inserts": [ { "condition": "...", "message": "...", "retryable": true, "refs": [] } ],
|
||
"updates": [ { "condition": "...", "message": "..." } ],
|
||
"deletes": [ { "condition": "...", "message": "..." } ] // 支持，但有两条约束，见 §3.4
|
||
},
|
||
"inserts": [ { ... } ], // 原有
|
||
"updates": [ { "b_id": "...", "b_amount": 220.00, "$original": { "b_amount": 200.00 } } ],
|
||
"deletes": [ { ... } ] // 原有，不带 guards
|
||
}
|
||
]
|
||
```
|
||
|
||
### 1.1 元字段一览
|
||
|
||
| 元字段 | 位置 | 作用 |
|
||
| --- | --- | --- |
|
||
| `$original` | **updates 行内** | 声明改动前的原值，进 `WHERE` 不进 `SET` |
|
||
| `$expr` | updates 行的**某个值**上 | 表达式值（账本自增），见 §4 |
|
||
| `guards` | 表块 | 业务前置条件 |
|
||
|
||
`$` 前缀 = 保留元字段，业务列一律 `b_` 前缀，不可能撞名。
|
||
|
||
审计列（`b_created_by` / `b_created_at` / `b_updated_by` / `b_updated_at`）**由服务端补**，
|
||
前端不要传、传了也会被丢弃（核心表结构设计 §1.6）。所以示例 SQL 里看不到它们，实际语句会有。
|
||
|
||
---
|
||
|
||
## 2. `$original`：字段级冲突检测
|
||
|
||
### 2.1 基本用法
|
||
|
||
```json
|
||
{
|
||
"b_id": "D001",
|
||
"b_amount": 220.00,
|
||
"$original": { "b_amount": 200.00 }
|
||
}
|
||
```
|
||
|
||
生成（**实际语句**）：
|
||
|
||
```sql
|
||
UPDATE t SET [b_amount] = ?
|
||
FROM dbo.demo_order AS t
|
||
WHERE t.[b_id] = ? AND t.[b_amount] = ?;
|
||
-- 参数：220.00（新值）, 'D001'（主键）, 200.00（原值）
|
||
```
|
||
|
||
命中 1 行 → 成功；命中 0 行 → 服务端回查后返回 2003。
|
||
|
||
### 2.2 规则
|
||
|
||
- **只对变化字段带原值**，不要提交整行快照。带得越多，越容易把无关字段的改动误判成冲突。
|
||
- 原值为 `null` 生成 `IS NULL`，**不能**写 `= NULL`：
|
||
```json
|
||
{ "b_id": "F001", "b_fee_name": "打车费", "$original": { "b_fee_name": null } }
|
||
```
|
||
```sql
|
||
... WHERE t.[b_id] = ? AND t.[b_fee_name] IS NULL
|
||
```
|
||
- 字段名必须是表里真实存在的列，否则在写库**之前**就报参数错误（不会写一半再失败）。
|
||
- `inserts` 行**不支持** `$original`（新增的行没有原值可比），传了报参数错误。
|
||
|
||
### 2.3 整行版本锁
|
||
|
||
`$original` 里放 `b_row_version` 即切换为整行语义：
|
||
|
||
```json
|
||
{
|
||
"b_id": "D001",
|
||
"b_status": "审核通过",
|
||
"$original": { "b_row_version": 7 }
|
||
}
|
||
```
|
||
|
||
```sql
|
||
UPDATE t SET [b_status] = ?, [b_row_version] = t.[b_row_version] + 1
|
||
FROM dbo.demo_order AS t
|
||
WHERE t.[b_id] = ? AND t.[b_row_version] = ?;
|
||
```
|
||
|
||
| `$original` 内容 | 粒度 |
|
||
| --- | --- |
|
||
| 业务字段 `{ "b_amount": 200.00 }` | 字段级，不同字段可并行修改 |
|
||
| 版本列 `{ "b_row_version": 7 }` | 整行，任一字段变更都冲突 |
|
||
|
||
要求目标表存在**可写**的 `b_row_version` 列（不能是 `rowversion` / `timestamp` 类型）。
|
||
版本列由服务端 `+1`，请求里在行上直接带 `b_row_version` 不生效。
|
||
|
||
**只用于整单提交 / 批量导入 / 不可拆分的状态迁移**——普通编辑用它会把无关字段的修改也判成冲突。
|
||
|
||
---
|
||
|
||
## 3. `guards`：业务前置条件
|
||
|
||
### 3.1 基本用法
|
||
|
||
```json
|
||
{
|
||
"table": "demo_order_fee",
|
||
"key_field": "b_id",
|
||
"guards": {
|
||
"inserts": [
|
||
{
|
||
"condition": "not exists (select 1 from dbo.demo_order p where p.b_id = {b_order_id} and p.b_status = N'审核通过')",
|
||
"refs": ["demo_order"],
|
||
"message": "该单据已审核通过，不能新增费用"
|
||
}
|
||
]
|
||
},
|
||
"inserts": [ { "b_id": "F010", "b_order_id": "D002", "b_fee_name": "停车费", "b_amount": 30.00 } ]
|
||
}
|
||
```
|
||
|
||
生成：
|
||
|
||
```sql
|
||
INSERT INTO dbo.demo_order_fee ([b_id],[b_order_id],[b_fee_name],[b_amount])
|
||
SELECT ?,?,?,?
|
||
WHERE (not exists (select 1 from dbo.demo_order p
|
||
where p.b_id = ? and p.b_status = N'审核通过'));
|
||
-- 参数：'F010','D002',N'停车费',30.00, 'D002'（占位符取自请求行）
|
||
```
|
||
|
||
**判定与写入在同一条语句里**——这是它能防并发的原因，不要拆成"先查再写"。
|
||
|
||
### 3.2 占位符 `{列名}` 的落地方式
|
||
|
||
| 动作 | 占位符变成 | 原因 |
|
||
| --- | --- | --- |
|
||
| inserts | `?`，值**取自当前请求行** | 行还不存在，没有列可引用 |
|
||
| updates | `t.[列]` | 行已存在，可直接引用 |
|
||
|
||
推论：**insert 的条件只能引用请求行里有的列**；update 的条件可以引用请求行里没带的列（用库里的当前值比）。
|
||
|
||
insert 行缺少被引用的列 → 报参数错误，不会静默当空值。
|
||
|
||
### 3.3 `message` 与 `retryable`
|
||
|
||
失败文案由服务端拼成：`{message}，本次操作未生效。{请刷新后重试。}`
|
||
|
||
| retryable | 文案 | 适用 |
|
||
| --- | --- | --- |
|
||
| `true`（默认） | `该单据已审核通过，不能新增费用，本次操作未生效。请刷新后重试。` | 状态随时会变，刷新有用 |
|
||
| `false` | `该费用已核销，本次操作未生效。` | **刷新也改变不了**的终态条件 |
|
||
|
||
把"请刷新后重试"挂在不该挂的地方，会误导用户反复刷新。写条件时务必判断。
|
||
|
||
没写 `message` 时用通用话术「该数据已被更新或不满足操作条件」。
|
||
|
||
### 3.4 deletes 的两条约束
|
||
|
||
`guards.deletes` **支持**，但有两条硬约束，违反了报参数错误（`1000`）：
|
||
|
||
1. **删除行必须只携带完整主键**。复合键要齐全，不能混入业务列做成批量条件——
|
||
批量删除带 guard 时「部分行满足该删哪些」没有合理语义，0 行时也无从归因到具体行。
|
||
```json
|
||
"deletes": [ { "b_id": "F004" } ] // ✓ 只有主键
|
||
```
|
||
2. **不能同时走删除旁路**。带 `guards.deletes` 时，`delete_target` 非空 或 声明了 `dependent_deletes`
|
||
都会直接报错——那两条路走 `DataDeleteService`，拿不到 guards，混用会让条件**被静默忽略**。
|
||
|
||
> 删子表明细时不会触发依赖删除：依赖删除的语义是「删本表时连带删**引用它**的行」，
|
||
> 方向是父 → 子（删主表才连带删子表）。所以「删明细时校验主表状态」与旁路天然不冲突。
|
||
|
||
另外条件里**不允许注释**（`--` / `/* */`），有注释直接报参数错误。
|
||
|
||
---
|
||
|
||
## 4. `$expr`：账本自增
|
||
|
||
账本字段（`b_fee_count` / `b_amount` 这类**汇总值**）不能用"读旧值 → 算新值 → 写新值"的方式更新：
|
||
|
||
- **直接写新值** → 并发时**静默丢失一次更新**（账本停在错的值且不报错）
|
||
- **用 `$original` 做 CAS** → 会产生**假冲突**（两笔费用互不影响，却有一方失败）
|
||
|
||
表达式值把「读 → 算 → 写」三步压成数据库端的一步，两个问题一起解决（完整推演见 §6.9）：
|
||
|
||
```json
|
||
{ "b_id": "D001", "b_fee_count": { "$expr": "b_fee_count + 1" } }
|
||
```
|
||
|
||
```sql
|
||
UPDATE t SET [b_fee_count] = t.[b_fee_count] + ?
|
||
FROM dbo.demo_order AS t
|
||
WHERE t.[b_id] = ?;
|
||
```
|
||
|
||
必须**显式包装**。裸字符串 `"b_fee_count + 1"` 会被当普通值，直接报类型错。
|
||
|
||
限制：只允许 `被赋值的列 ± 数值常量`，列必须是数值类型且可写。不支持函数、子查询、引用其他列、多个运算符。
|
||
|
||
**什么时候需要它**：新值是**依赖旧值算出来**的（累加 / 递减）。整块替换的字段（比如把备注从"差旅"改成"差旅（补录）"）直接写新值就行，不需要 `$expr`，详见 §6.9。
|
||
|
||
---
|
||
|
||
## 5. 错误码
|
||
|
||
| code | 含义 | 触发条件 | `data` |
|
||
| --- | --- | --- | --- |
|
||
| `0` | 成功 | — | `null` |
|
||
| `1000` | 参数错误 | 结构不合法、占位符列名不存在、不支持的用法 | — |
|
||
| `2001` | 普通保存失败 | **目标行不存在**（或原 SQL 异常） | `table`/`action`/`index`/`cause` |
|
||
| `2002` | guard 不成立 | 目标行在，但条件不满足 | `table`/`action`/`index` |
|
||
| `2003` | 并发冲突 | `$original` 原值或 `b_row_version` 不匹配 | `table`/`action`/`index`/`fields` |
|
||
|
||
**2001 vs 2002 的区分是服务端回查得出的**，不是猜的：0 行时先查目标行在不在，不在就是 2001。
|
||
|
||
---
|
||
|
||
## 6. 各种情况的 Demo
|
||
|
||
以下都用 `demo_order` / `demo_order_fee`，初始数据见设计文档附录 A.2。
|
||
|
||
### 6.1 普通编辑，什么都不带
|
||
|
||
```json
|
||
[{ "table": "demo_order_fee", "key_field": "b_id",
|
||
"updates": [ { "b_id": "F001", "b_fee_name": "打车费（往返）" } ] }]
|
||
```
|
||
|
||
```sql
|
||
UPDATE dbo.demo_order_fee SET [b_fee_name] = ? WHERE [b_id] = ?
|
||
```
|
||
|
||
→ `{"code": 0, "message": "保存成功", "data": null}`
|
||
|
||
这就是**老行为**，不带 guards / `$original` / `$expr` 的行走的还是原来的 SQL 生成路径。
|
||
|
||
### 6.2 防同字段覆盖
|
||
|
||
甲、乙同时打开 D001 的金额编辑（都是 1200.00）：
|
||
|
||
```json
|
||
[{ "table": "demo_order", "key_field": "b_id",
|
||
"updates": [ { "b_id": "D001", "b_amount": 1500.00,
|
||
"$original": { "b_amount": 1200.00 } } ] }]
|
||
```
|
||
|
||
甲先提交 → 1 行 → 成功。
|
||
乙后提交 → `WHERE b_amount = 1200.00` 已不成立 → 0 行 → 回查：目标行在、`b_amount` 不匹配 →
|
||
|
||
```json
|
||
{
|
||
"code": 2003,
|
||
"message": "该数据已被其他操作修改，本次操作未生效，请刷新后重试。",
|
||
"data": { "table": "demo_order", "action": "update", "index": 0, "fields": ["b_amount"] }
|
||
}
|
||
```
|
||
|
||
`fields` 告诉前端**是哪个字段**冲突，用于重新拉取后高亮。
|
||
|
||
### 6.3 甲改金额、乙改备注 → 都成功
|
||
|
||
```json
|
||
// 甲
|
||
{ "b_id": "D001", "b_amount": 1500.00, "$original": { "b_amount": 1200.00 } }
|
||
// 乙
|
||
{ "b_id": "D001", "b_no": "BX-2026-001-R", "$original": { "b_no": "BX-2026-001" } }
|
||
```
|
||
|
||
各自只对自己改的字段做原值比较，互不干扰 → **两个请求都成功**。
|
||
|
||
这正是"只对变化字段带原值"的意义；如果两边都提交整行快照，就会互相误伤。
|
||
|
||
### 6.4 原值是 NULL
|
||
|
||
```json
|
||
{ "b_id": "F001", "b_fee_name": "打车费", "$original": { "b_fee_name": null } }
|
||
```
|
||
|
||
```sql
|
||
... WHERE t.[b_id] = ? AND t.[b_fee_name] IS NULL
|
||
```
|
||
|
||
传 `null` 生成 `IS NULL`。**不要用空字符串 `""` 表示"原来是空"**——库里很可能是 `NULL`，`= ''` 匹配不到，会误报 2003。
|
||
|
||
### 6.5 明细新增：主表已审核则拦下
|
||
|
||
D002 是"审核通过"：
|
||
|
||
```json
|
||
{
|
||
"table": "demo_order_fee", "key_field": "b_id",
|
||
"guards": { "inserts": [
|
||
{ "condition": "not exists (select 1 from dbo.demo_order p where p.b_id = {b_order_id} and p.b_status = N'审核通过')",
|
||
"refs": ["demo_order"],
|
||
"message": "该单据已审核通过，不能新增费用" }
|
||
] },
|
||
"inserts": [ { "b_id": "F010", "b_order_id": "D002", "b_fee_name": "停车费", "b_amount": 30.00 } ]
|
||
}
|
||
```
|
||
|
||
→ 0 行 → 回查定位到这条 guard →
|
||
|
||
```json
|
||
{
|
||
"code": 2002,
|
||
"message": "该单据已审核通过，不能新增费用，本次操作未生效。请刷新后重试。",
|
||
"data": { "table": "demo_order_fee", "action": "insert", "index": 0 }
|
||
}
|
||
```
|
||
|
||
同样是这条 guard，给 D001（草拟）加费用 → 1 行 → 成功。
|
||
|
||
### 6.6 多条 guard：定位到具体是哪条
|
||
|
||
D004 是"送审"但没有任何明细：
|
||
|
||
```json
|
||
{
|
||
"table": "demo_order", "key_field": "b_id",
|
||
"guards": { "updates": [
|
||
{ "condition": "{b_status} = N'送审'", "message": "单据状态已变更，请刷新后重试" },
|
||
{ "condition": "{b_fee_count} > 0",
|
||
"message": "该单据没有任何费用明细，不能通过审批", "retryable": false }
|
||
] },
|
||
"updates": [ { "b_id": "D004", "b_status": "审核通过" } ]
|
||
}
|
||
```
|
||
|
||
```sql
|
||
UPDATE t SET [b_status] = ? FROM dbo.demo_order AS t
|
||
WHERE t.[b_id] = ? AND (t.[b_status] = N'送审') AND (t.[b_fee_count] > 0)
|
||
```
|
||
|
||
→ 0 行 → 回查：第 1 条成立、第 2 条不成立 →
|
||
|
||
```json
|
||
{ "code": 2002,
|
||
"message": "该单据没有任何费用明细，不能通过审批，本次操作未生效。",
|
||
"data": { "table": "demo_order", "action": "update", "index": 0 } }
|
||
```
|
||
|
||
注意 `retryable: false` 去掉了"请刷新后重试"——这个条件刷新一万次也还是没有明细。
|
||
|
||
### 6.7 guard + `$original` 组合
|
||
|
||
明细行既要求主表状态，又要求本行金额没被别人改过：
|
||
|
||
```json
|
||
{
|
||
"table": "demo_order_fee", "key_field": "b_id",
|
||
"guards": { "updates": [
|
||
{ "condition": "not exists (select 1 from dbo.demo_order p where p.b_id = {b_order_id} and p.b_status = N'审核通过')",
|
||
"refs": ["demo_order"], "message": "该单据已审核通过，不能修改费用" }
|
||
] },
|
||
"updates": [ { "b_id": "F004", "b_order_id": "D003", "b_amount": 4500.00,
|
||
"$original": { "b_amount": 4000.00 } } ]
|
||
}
|
||
```
|
||
|
||
```sql
|
||
UPDATE t SET [b_amount] = ? FROM dbo.demo_order_fee AS t
|
||
WHERE t.[b_id] = ? AND t.[b_amount] = ?
|
||
AND (not exists (select 1 from dbo.demo_order p
|
||
where p.b_id = t.[b_order_id] and p.b_status = N'审核通过'))
|
||
```
|
||
|
||
0 行时**按固定顺序归因**：目标行不存在 → 2001；`$original` 不匹配 → 2003；再逐条回查 guard → 2002。
|
||
|
||
### 6.8 删除明细：主表已审核 / 已生成发票则拦下
|
||
|
||
删 F004（属于 D003，送审中），要求主表未审核、且该费用没生成过发票：
|
||
|
||
```json
|
||
{
|
||
"table": "demo_order_fee", "key_field": "b_id",
|
||
"guards": { "deletes": [
|
||
{ "condition": "not exists (select 1 from dbo.demo_order p where p.b_id = {b_order_id} and p.b_status = N'审核通过')",
|
||
"refs": ["demo_order"], "message": "该单据已审核通过，不能删除费用" },
|
||
{ "condition": "not exists (select 1 from dbo.demo_invoice d where d.b_fee_id = {b_id})",
|
||
"refs": ["demo_invoice"], "message": "该费用已生成发票，不能删除", "retryable": false }
|
||
] },
|
||
"deletes": [ { "b_id": "F004", "b_order_id": "D003" } ]
|
||
}
|
||
```
|
||
|
||
> ⚠️ 上面这行**不对**：`deletes` 里多带了 `b_order_id`，会触发 §3.4 的唯一定位校验。
|
||
> 正确写法是只给主键，条件里的 `{b_order_id}` 由服务端解析成 `t.[b_order_id]` 去库里取：
|
||
> ```json
|
||
> "deletes": [ { "b_id": "F004" } ]
|
||
> ```
|
||
|
||
生成：
|
||
|
||
```sql
|
||
DELETE t FROM dbo.demo_order_fee AS t
|
||
WHERE t.[b_id] = ?
|
||
AND (not exists (select 1 from dbo.demo_order p
|
||
where p.b_id = t.[b_order_id] and p.b_status = N'审核通过'))
|
||
AND (not exists (select 1 from dbo.demo_invoice d where d.b_fee_id = t.[b_id]))
|
||
```
|
||
|
||
- 主表是"送审"且没发票 → 1 行 → 删除成功
|
||
- 主表已审核 → 0 行 → 回查定位到第 1 条 → `2002`，"该单据已审核通过，不能删除费用，本次操作未生效。请刷新后重试。"
|
||
- 已生成发票 → 第 1 条通过、第 2 条不成立 → `2002`，"该费用已生成发票，不能删除，本次操作未生效。"（`retryable: false`，刷新也没用）
|
||
|
||
**为什么 `{b_order_id}` 不用写在 deletes 行里**：delete 的占位符解析成 `t.[列]`，用的是**库里那一行的当前值**，不需要请求方重复传一遍。
|
||
|
||
### 6.9 账本自增：为什么不能直接写 3
|
||
|
||
D001 有 2 条明细，`b_fee_count = 2`。甲加机票、乙加餐费，**同时**提交。
|
||
|
||
#### 直接写 3 会静默丢一次更新
|
||
|
||
```json
|
||
{ "b_id": "D001", "b_fee_count": 3 }
|
||
```
|
||
|
||
| 时刻 | 甲 | 乙 | 库里 `b_fee_count` |
|
||
| --- | --- | --- | --- |
|
||
| t0 | | | **2** |
|
||
| t1 | 读到 2，算 2+1 = **3** | 读到 2，算 2+1 = **3** | 2 |
|
||
| t2 | 写入 3 | | **3** |
|
||
| t3 | | 写入 3 | **3** ← 应该是 4 |
|
||
|
||
两条明细都插进去了（明细表实际 4 条），但 `b_fee_count` 停在 3——**账本跟明细对不上**，
|
||
而且**没有任何报错**，甲和乙都看到"保存成功"。
|
||
|
||
这就是丢失更新：各自的 `2 + 1 = 3` 单看都对，合并起来就错了。
|
||
|
||
> 类比：账户余额 100，两笔并发存款各 50。都"读 100 → 算 150 → 写 150"，
|
||
> 结果是 150 而不是 200。必须是 `balance = balance + 50`。
|
||
|
||
#### 三种写法对比
|
||
|
||
| 写法 | 两次并发结果 | 问题 |
|
||
| --- | --- | --- |
|
||
| `b_fee_count: 3` | **3（错）** | 静默错，账本漂移，没人知道 |
|
||
| `b_fee_count: 3` + `$original: { "b_fee_count": 2 }` | 3（对），**乙方 2003 失败** | 假冲突：甲乙各加一笔、互不影响，却有一方要重试 |
|
||
| `b_fee_count: { "$expr": "b_fee_count + 1" }` | **4（对），都成功** | 要求列是数值类型且可写 |
|
||
|
||
#### 用 `$expr`
|
||
|
||
```json
|
||
[{ "table": "demo_order", "key_field": "b_id",
|
||
"updates": [ { "b_id": "D001", "b_fee_count": { "$expr": "b_fee_count + 1" } } ] }]
|
||
```
|
||
|
||
```sql
|
||
UPDATE t SET [b_fee_count] = t.[b_fee_count] + ? FROM dbo.demo_order AS t WHERE t.[b_id] = ?
|
||
```
|
||
|
||
两次执行各自在**当前值**上加 1，谁也不覆盖谁 → 结果 4，两人都成功。
|
||
|
||
#### 什么时候可以直接写新值
|
||
|
||
判断标准是：**新值是不是依赖旧值算出来的**。
|
||
|
||
- **依赖**（累加 / 递减）→ 账本字段，用 `$expr`
|
||
- **不依赖**（整块替换）→ 直接写。比如把备注从"差旅"改成"差旅（补录）"，
|
||
不存在"累加丢失"的问题，加 `$original` 也只是防止别人同时改了它
|
||
|
||
#### 账本还要能对账
|
||
|
||
即使用了 `$expr`，也建议定期核对——历史脏数据、或绕过统一入口的写入仍会造成漂移：
|
||
|
||
```sql
|
||
select o.b_id, o.b_fee_count, count(f.b_id) as real_count
|
||
from dbo.demo_order o
|
||
left join dbo.demo_order_fee f on f.b_order_id = o.b_id
|
||
group by o.b_id, o.b_fee_count
|
||
having o.b_fee_count <> count(f.b_id);
|
||
```
|
||
|
||
**账本能被信任的前提是它能被核对。**
|
||
|
||
### 6.10 目标行不存在 → 2001
|
||
|
||
```json
|
||
{ "b_id": "F999", "b_amount": 100.00, "$original": { "b_amount": 90.00 } }
|
||
```
|
||
|
||
→ 0 行 → 回查发现目标行根本不在 →
|
||
|
||
```json
|
||
{ "code": 2001, "message": "保存失败: 目标行不存在",
|
||
"data": { "table": "demo_order_fee", "action": "update", "index": 0, "cause": "目标行不存在" } }
|
||
```
|
||
|
||
**不会误报成 guard 失败**，也不会带 guard 文案。
|
||
|
||
### 6.11 多行中途失败 → 整体回滚
|
||
|
||
```json
|
||
"updates": [
|
||
{ "b_id": "F001", "b_amount": 300.00 }, // 能成
|
||
{ "b_id": "F004", "b_amount": 9999.00, "$original": { "b_amount": 1.00 } } // 原值不对
|
||
]
|
||
```
|
||
|
||
第 2 行失败 → **整个请求回滚**，第 1 行的改动也不落库。异常 `data.index = 1` 指向失败的那一行。
|
||
|
||
### 6.12 参数错误：写库前就拒绝
|
||
|
||
以下都是 `code: 1000`，**一行都不会写**：
|
||
|
||
| 写法 | 报错 |
|
||
| --- | --- |
|
||
| `"guards": { "deletes": [...] }` 同时又传了 `delete_target` | 带 guards.deletes 时不能使用 delete_target，两条路径互斥 |
|
||
| `"guards": { "deletes": [...] }` 同时又传了 `dependent_deletes` | 带 guards.deletes 时不能同时声明 dependent_deletes，两条路径互斥 |
|
||
| deletes 行多带业务列：`{ "b_id": "F004", "b_order_id": "D003" }` | 带 guards 的删除行必须只携带完整主键 |
|
||
| `"guards": { "inserts": "..." }`（不是数组） | guards.inserts 必须是数组 |
|
||
| `"guards": { "insert": [...] }`（拼错） | guards 不支持的动作: insert |
|
||
| 条件里写 `{b_not_exist}` | guard 占位符字段不存在 |
|
||
| 条件里带 `--` 注释 | guard condition 不允许包含注释 |
|
||
| insert 行带 `$original` | insert 行不支持 $original |
|
||
| `$original: { "b_not_exist": 1 }` | $original 字段不存在 |
|
||
| `{ "b_fee_count": "b_fee_count + 1" }` 裸字符串 | （按普通值绑定，报类型错） |
|
||
| `{ "b_fee_count": { "$expr": "b_amount + 1" } }` | 表达式只能引用被赋值的列 |
|
||
|
||
参数错误前置是为了不出现"前几行已写入、第 N 行才报错"。
|
||
|
||
### 6.13 并发窗口：三种都不是
|
||
|
||
目标行在、`$original` 也匹配、所有 guard 回查都成立，但更新仍是 0 行——说明回查期间数据又变了。
|
||
|
||
这种情况**不声称某条 guard 失败**，统一给 2003 通用冲突文案。归因是 best-effort，最坏情况是文案不够精确，**不影响数据正确性**。
|
||
|
||
---
|
||
|
||
## 7. 前端集成
|
||
|
||
### 7.1 错误码怎么处理
|
||
|
||
| code | 处理 |
|
||
| --- | --- |
|
||
| `2002` | `http.js` 已自动弹服务端拼好的完整文案并打 `toasted`。**调用点不要再拼前缀**（`Message.error('保存失败：' + ...)` 会造成双重前缀）；检查 `error.toasted` 的调用点不会再弹一次。**展示后自动重新拉取当前状态**——用户的本能是再点一次，不刷新会反复失败。 |
|
||
| `2003` | `http.js` **不自动弹**。按并发冲突处理：重新拉取当前行、按 `data.fields` 标记冲突字段、保留用户输入，**不自动覆盖也不自动重试**。 |
|
||
| `2001` | 普通保存失败，沿用现有提示。 |
|
||
|
||
### 7.2 `$original` 怎么生成
|
||
|
||
**必须用与提交值同一个口径**，否则会误报 2003。这是最容易踩的坑。
|
||
|
||
以 `views/base/othercompany/detail.vue` 为例：表单里时间字段保持本地墙钟串、空串表示空，
|
||
`toSubmitRow()` 才把它们转成 UTC 串和 `null`。所以原值也要过一遍同样的转换：
|
||
|
||
```js
|
||
function buildSaveData() {
|
||
const { isNew: creating, row } = saveCtx
|
||
if (!row) return null
|
||
const request = { table: saveTableName(), key_field: keyField.value }
|
||
|
||
if (creating) {
|
||
request.inserts = [toSubmitRow(row)]
|
||
return [request]
|
||
}
|
||
|
||
const changes = diffRow({
|
||
current: row,
|
||
original: maindata_org.value,
|
||
primaryKey: keyField.value,
|
||
})
|
||
if (!changes.hasChanges) return null
|
||
|
||
// 原值必须走与提交值相同的口径转换（UTC / '' → null / checkbox → 0/1）：
|
||
// 界面口径的旧值跟库里的值比不上，必然误报 2003
|
||
const submitted = toSubmitRow(changes.updates[0])
|
||
const original = toSubmitRow(maindata_org.value)
|
||
// 只给「本次提交的字段」带原值：主键不参与比较，无关字段带了只会误伤
|
||
const expected = {}
|
||
for (const field of Object.keys(submitted)) {
|
||
if (field !== keyField.value) expected[field] = original[field]
|
||
}
|
||
request.updates = [{ ...submitted, $original: expected }]
|
||
return [request]
|
||
}
|
||
```
|
||
|
||
要点：
|
||
|
||
1. 只给**变化的字段**带原值（`diffRow` 已经算出了差异）
|
||
2. 原值过 `toSubmitRow` 与提交值同口径
|
||
3. 排除主键（主键不参与原值比较）
|
||
4. 公式字段、审计字段（`b_updated_at` 等）、账本字段**不要**带——服务端会改写它们，带了必然误冲突
|
||
|
||
> `diffRow` 目前还没有自动产出 `$original`（它的 `original` 参数是界面口径，直接拿去用会踩上面的坑）。
|
||
> 要自动生成得先把口径统一，不能简单把 `original[key]` 塞进去。
|
||
|
||
### 7.3 guards 怎么组织
|
||
|
||
条件文案是业务语义，**收敛到一个函数**，不要散在页面里拼：
|
||
|
||
```js
|
||
// 例：某模块的费用明细动作
|
||
export function buildActionRequest(action, row, order) {
|
||
const guard = {
|
||
condition:
|
||
"not exists (select 1 from dbo.demo_order p where p.b_id = {b_order_id} and p.b_status = N'审核通过')",
|
||
refs: ['demo_order'],
|
||
message: `该单据已审核通过，不能${ACTION_TEXT[action]}费用`,
|
||
}
|
||
return {
|
||
table: 'demo_order_fee',
|
||
key_field: 'b_id',
|
||
guards: { [`${action}s`]: [guard] },
|
||
[`${action}s`]: [row],
|
||
}
|
||
}
|
||
```
|
||
|
||
**为什么必须收敛**：guards 是纯 opt-in，服务端不会替调用方补条件。漏传就等于放弃保护，而且**不会有任何提示**。散在页面里迟早会漏。
|
||
|
||
---
|
||
|
||
## 8. 边界（用了也拦不住的情况）
|
||
|
||
1. **不提供单据级串行**。guards 保证的是「写入那一刻条件成立」，不保证整个事务期间状态不变，也不保证两个事务按固定顺序完成。需要严格顺序的场景走专用服务。
|
||
2. **快照隔离下 insert 的 guard 可能读到旧值**。`INSERT ... SELECT ... WHERE (子查询)` 的子查询在 RCSI / SNAPSHOT 下读语句快照、不加锁，可能放过已被别人改写的状态。`UPDATE` 不受影响。**上线前先确认数据库隔离级别。**
|
||
3. **guards 不解决重复提交**。同一个请求原样重放两次，guard 两次都可能成立。幂等要另做（§1.3）。
|
||
4. **删除的 guards 只走唯一定位路径**。删除行必须只带完整主键，且不能与 `delete_target` / `dependent_deletes` 同用（§3.4）；删除服务本身不支持 guards。
|
||
5. **跨行 / 聚合条件要先物化**。`count(*)`、`sum()` 这类现算的判据没有行可锁，guard 拦不住；要先物化成表上的一个字段（设计 §8.2）。
|