first commit

2026-09-02 11:44:52 +08:00
commit 0c8fa2653e
309 changed files with 57278 additions and 0 deletions
@@ -0,0 +1,89 @@
+# 行记录 Upsert（record upsert）
+
+按 `recordId` 是否存在，自动把入参拆分到 update 链路或 create 链路：批次混合"已存在改 + 新出现建"时用，省掉客户端按 ID 分批的逻辑。
+
+## 命令
+
+```
+dws aitable record upsert \
+  --base-id BASE_ID --table-id TABLE_ID \
+  --records '[{"recordId":"<可选>","cells":{...}}, ...]'
+```
+
+| flag | 说明 |
+|------|------|
+| `--base-id` | 必填（可用 `--base` 别名） |
+| `--table-id` | 必填 |
+| `--records` | 待 upsert 的记录 JSON 数组，**单次最多 100 条**（必填）|
+| `--records-file` | 从文件读入（命令行 JSON 太长时用），与 `--records` 互斥优先级更高 |
+
+## --records 结构
+
+每项 JSON：
+
+```jsonc
+{
+  "recordId": "rec1",                  // 可选；带 → update，缺省 → create
+  "cells": {                            // 必填；key 是 fieldId，value 按字段类型
+    "fldTitleId": "新标题",
+    "fldNumberId": 42
+  }
+}
+```
+
+`cells` 写入格式与 `record create` / `record update` **完全一致**（key 必须是 fieldId 不是字段名；按字段类型见 [aitable-cell-value.md](./aitable-cell-value.md)）。
+
+## 返回结构
+
+```jsonc
+{
+  "data": {
+    "createdRecordIds": ["recX", "recY"],   // 不带 recordId 的项产出
+    "updatedRecordIds": ["recA", "recB"]    // 带 recordId 的项产出
+  }
+}
+```
+
+`createdRecordIds` 顺序对应入参里**不带 recordId**的项（按出现顺序汇总），同理 `updatedRecordIds` 对应**带 recordId**的项。
+
+## 典型用法
+
+```bash
+# 1) 全部新建：所有项都不带 recordId
+dws aitable record upsert --base-id BASE --table-id TBL --records '[
+  {"cells":{"fldTitleId":"任务1","fldStatusId":"待办"}},
+  {"cells":{"fldTitleId":"任务2","fldStatusId":"待办"}}
+]'
+
+# 2) 全部更新：所有项都带 recordId
+dws aitable record upsert --base-id BASE --table-id TBL --records '[
+  {"recordId":"rec1","cells":{"fldStatusId":"已完成"}},
+  {"recordId":"rec2","cells":{"fldStatusId":"已完成"}}
+]'
+
+# 3) 混合：第 1 条更新（带 recordId），第 2 条创建（不带）
+dws aitable record upsert --base-id BASE --table-id TBL --records '[
+  {"recordId":"rec1","cells":{"fldStatusId":"已完成"}},
+  {"cells":{"fldTitleId":"新增任务","fldStatusId":"待办"}}
+]'
+
+# 4) 长 JSON 用文件
+dws aitable record upsert --base-id BASE --table-id TBL --records-file ./batch.json
+```
+
+## 与 record create / record update 的关系
+
+| 场景 | 命令 |
+|------|------|
+| 确定全是新增 | `record create` |
+| 确定全是更新（每条独立 cells） | `record update` |
+| 确定全是更新（共享同一 cells） | `record batch-update` |
+| **不确定有没有，按 recordId 自动分流** | `record upsert`（本命令） |
+
+`record upsert` 的 `--records` 入参格式与 `record update` 完全相同，唯一差别是 `recordId` 字段在 upsert 里是可选的。如果批次确定全是更新或全是新建，用专用命令更清晰；批次混合时（典型场景：定时同步外部数据，源里既有已存在的也有新出现的），用 upsert。
+
+## 注意事项
+
+- **单次最多 100 条**（创建 + 更新合计），超出请客户端拆批。
+- `cells` 的 key 必须是 fieldId 不是字段名（先用 `record query` 或 `field get` 拿 fieldId）。
+- 只读字段（formula / lookup / 系统字段）不能写入 — upsert 链路与 update 链路同样限制。