# datasource — 数据源同步管理

将外部数据源（当前仅支持 OA 审批）同步到 AI 表格。完整链路：list-sources → (OA) 选择模板 → get-fields → create → sync-status → sync / update / get-config。

## 命令一览

| 命令 | 用途 | 读/写 |
|------|------|-------|
| `+datasource-list-sources` | 列出可用数据源条目，获取 processCode/name/iconUrl/url | 读 |
| `+datasource-get-fields` | 获取可同步字段列表，用于决定 field-ids | 读 |
| `+datasource-create` | 创建数据源表并触发首次全量同步 | 写 |
| `+datasource-update` | 更新已有数据源表的同步配置 | 写 |
| `+datasource-sync` | 手动触发一次同步（最多 5 张表） | 写 |
| `+datasource-sync-status` | 查询同步任务状态（RUNNING/FINISHED/FAILED） | 读 |
| `+datasource-get-config` | 获取数据源表当前同步配置 | 读 |

## 典型工作流

```
Step 0    列出可用来源         +datasource-list-sources --base-id <B> --datasource-type OA
                              → 返回 approvals 数组（通常含多个审批模板）

Step 0.5  (OA 审批) 选择模板  list-sources 返回的 approvals 数组通常含多个审批模板，需确定目标：
                              - 用户已指定名称（如"采购申请"）→ 按 name 精确/模糊匹配
                                · 唯一命中 → 提取该条的 processCode/name/iconUrl/url，继续
                                · 多候选 → 列出匹配项让用户消歧
                                · 零命中 → 停止，提示用户确认名称或从完整列表选择
                              - 用户未指定 → 列出候选模板清单（name + processCode），等用户选择
                              - 禁止：未匹配直接选第一项、或凭记忆猜 processCode
                              注：此步骤针对 OA 审批数据源（多模板场景）；其他数据源类型的
                              list-sources 返回结构可能不同，按实际 result 解析即可，
                              不一定需要选择步骤。

Step 1    (可选) 获取可同步字段  +datasource-get-fields --base-id <B> --datasource-type OA --source-config '<JSON>'
                              → 决定需要同步哪些字段，得到 field-ids

Step 2    创建数据源           +datasource-create --base-id <B> --datasource-type OA --source-config '<JSON>'
                              → sourceConfig 中的 processCode/name/iconUrl/url 来自 Step 0.5 选中的模板
                              → 返回 tableId + taskId

Step 3    查询同步结果         +datasource-sync-status --base-id <B> --table-id <T> --task-ids <TASK_ID>
                              → FINISHED=完成，FAILED=看 errorCode 排查，RUNNING=轮询

Step 4    (后续) 手动触发同步   +datasource-sync --base-id <B> --table-ids <T1>,<T2>
                              → 返回新 taskId，再用 sync-status 查结果

Step 5    (后续) 更新配置       +datasource-update --base-id <B> --table-id <T> --source-config '<JSON>' --auto
                              → 更新后自动触发一次同步

查看当前配置                  +datasource-get-config --base-id <B> --table-id <T>
```

## sourceConfig 字段协议

以下字段协议仅适用于 OA 审批数据源（datasourceType=OA），其他数据源类型待后续开放。

### 须从 list-sources 原样透传（必填）

| 字段 | 类型 | 说明 |
|------|------|------|
| processCode | String | OA 审批流程编码 |
| name | String | 展示名称 |
| iconUrl | String | 图标 URL |
| url | String | 跳转链接 |

### 调用方自行设置

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| dataType | String | 是 | 数据范围类型：`time_range` / `start_time` / `recent_time` |
| recentDays | String | 条件 | dataType=recent_time 时有效，取值 `7d`/`30d`/`1y`，默认 `30d` |
| startDate | String | 条件 | dataType=time_range 或 start_time 时有效，`yyyy-MM-dd`，默认 30 天前 |
| endDate | String | 条件 | dataType=time_range 时有效，`yyyy-MM-dd`，默认当天 |
| keepRemovedFields | Boolean | 否 | 是否保留已删除字段，默认 false |
| splitParentTableField | Boolean | 否 | 是否拆分父表字段 |

> list-sources 返回的 keepRemovedFields / splitParentTableField / enableDataSyncOaDetailList 不要透传，由调用方按需设置。

### 三种 dataType 最小示例

```json
// recent_time — 最近一段时间
{"processCode":"PROC-xxxx","name":"采购申请","dataType":"recent_time","recentDays":"30d","iconUrl":"...","url":"..."}

// time_range — 指定起止日期
{"processCode":"PROC-xxxx","name":"采购申请","dataType":"time_range","startDate":"2025-01-01","endDate":"2025-12-31","iconUrl":"...","url":"..."}

// start_time — 从某日期至今
{"processCode":"PROC-xxxx","name":"采购申请","dataType":"start_time","startDate":"2025-06-01","iconUrl":"...","url":"..."}
```

## autoSyncSetting 频率配置

仅在 `--auto=true` 时生效。不传时使用下游默认自动同步策略。

| 字段 | 必填 | 说明 |
|------|------|------|
| syncType | 是 | `hourly`（按小时间隔）/ `scheduled`（定时触发） |
| hourlyInterval | hourly 时 | 正整数，小时间隔 |
| scheduleType | scheduled 时 | `daily` / `weekly` / `monthly` |
| timeValue | scheduled 时 | `HH:mm` 触发时间 |
| selectedMonthDays | monthly 时必填 | 每月几号触发，1-31 |
| selectedWeekdays | weekly 时必填 | 每周哪几天触发，1=周一…7=周日 |
| skipNonWorkingDay | 否 | 是否跳过非工作日，默认 false |

示例：`{"syncType":"scheduled","scheduleType":"daily","timeValue":"09:00"}`

## 命令详情

### +datasource-list-sources — 列出可用数据源条目

```bash
dws aitable +datasource-list-sources --base-id BASE_ID --datasource-type OA --format json
```

| flag | 必填 | 说明 |
|------|------|------|
| `--base-id` | 是 | 目标 Base ID |
| `--datasource-type` | 是 | 数据源类型，当前仅支持 `OA` |

返回每条条目包含 `result`（下游原始 JSON 字符串）和 `sourceType`（OA 审批对应 2）。OA 审批场景下 result 为 approvals 数组：

```json
{
  "approvals": [
    {
      "processCode": "PROC-xxxx",
      "name": "采购申请",
      "iconUrl": "https://...",
      "url": "https://...",
      "keepRemovedFields": false,
      "splitParentTableField": false,
      "enableDataSyncOaDetailList": false
    }
  ]
}
```

调用方应自行解析 result，提取目标模板字段后构造 sourceConfig。

### +datasource-get-fields — 获取可同步字段列表

```bash
dws aitable +datasource-get-fields --base-id BASE_ID --datasource-type OA \
  --source-config '{"processCode":"PROC-xxxx","name":"采购申请","dataType":"recent_time","recentDays":"30d","iconUrl":"...","url":"..."}' \
  --format json
```

| flag | 必填 | 说明 |
|------|------|------|
| `--base-id` | 是 | 目标 Base ID |
| `--datasource-type` | 是 | 数据源类型，当前仅支持 `OA` |
| `--source-config` | 是 | 源配置 JSON 字符串，结构同 create 的 --source-config |

返回字段列表（字段 ID、名称、类型等），用于在 create/update 中指定 `--field-ids`。

### +datasource-create — 创建数据源表

```bash
dws aitable +datasource-create --base-id BASE_ID --datasource-type OA \
  --source-config '{"processCode":"PROC-xxxx","name":"采购申请","dataType":"recent_time","recentDays":"30d","iconUrl":"...","url":"..."}' \
  --format json

# 开启自动同步 + 自定义频率
dws aitable +datasource-create --base-id BASE_ID --datasource-type OA \
  --source-config '...' --auto \
  --auto-sync-setting '{"syncType":"scheduled","scheduleType":"daily","timeValue":"09:00"}' \
  --format json
```

| flag | 必填 | 说明 |
|------|------|------|
| `--base-id` | 是 | 目标 Base ID |
| `--datasource-type` | 是 | 数据源类型，当前仅支持 `OA` |
| `--source-config` | 是 | 源配置 JSON 字符串（见上方字段协议） |
| `--auto` | 否 | 是否开启自动同步，默认 false；无论是否传入，CLI 都会把该字段下发给下游 |
| `--auto-sync-setting` | 否 | 自动同步频率配置 JSON 字符串，仅 --auto=true 时生效 |
| `--field-ids` | 否 | 需要同步的字段 ID 列表，不传时同步全部字段 |

返回新建数据源表 tableId 和同步任务 taskId。创建后自动触发一次全量同步，需用 `+datasource-sync-status` 查最终结果。

### +datasource-update — 更新数据源配置

```bash
# 仅开启自动同步
dws aitable +datasource-update --base-id BASE_ID --table-id TABLE_ID --auto --format json

# 更新源配置
dws aitable +datasource-update --base-id BASE_ID --table-id TABLE_ID \
  --source-config '{"processCode":"PROC-yyyy","name":"出差申请","dataType":"recent_time","recentDays":"30d","iconUrl":"...","url":"..."}' \
  --format json
```

| flag | 必填 | 说明 |
|------|------|------|
| `--base-id` | 是 | 目标 Base ID |
| `--table-id` | 是 | 已有数据源表 ID（sync=true） |
| `--source-config` | 否 | 新的源配置 JSON 字符串，不传时保持原配置；传入时整体覆盖 |
| `--auto` | 否 | 是否开启自动同步，不传时保持原设置 |
| `--auto-sync-setting` | 否 | 自动同步频率配置 JSON 字符串，仅 --auto=true 时生效；不传时保持原频率配置 |
| `--field-ids` | 否 | 需要同步的字段 ID 列表，不传时保持现有字段配置 |

更新后自动触发一次全量同步，返回新 taskId。

### +datasource-sync — 手动触发同步

```bash
dws aitable +datasource-sync --base-id BASE_ID --table-ids TBL1,TBL2 --format json
```

| flag | 必填 | 说明 |
|------|------|------|
| `--base-id` | 是 | 目标 Base ID |
| `--table-ids` | 是 | 待同步的数据源表 ID 列表（sync=true），1-5 个 |

返回结果包含文档链接，可打开查看同步进度。每张表独立提交，部分失败不影响其他表。

### +datasource-sync-status — 按任务 ID 查询同步状态

```bash
dws aitable +datasource-sync-status --base-id BASE_ID --table-id TABLE_ID --task-ids TASK1,TASK2 --format json
```

| flag | 必填 | 说明 |
|------|------|------|
| `--base-id` | 是 | 目标 Base ID |
| `--table-id` | 是 | 数据源表 ID（sync=true） |
| `--task-ids` | 是 | 同步任务 ID 列表（由 create/update/sync 返回），1-5 个 |

任务状态：`RUNNING`（进行中）、`FINISHED`（完成）、`FAILED`（失败，含 errorCode + errorMessage）。

### +datasource-get-config — 获取数据源配置

```bash
dws aitable +datasource-get-config --base-id BASE_ID --table-id TABLE_ID --format json
```

| flag | 必填 | 说明 |
|------|------|------|
| `--base-id` | 是 | 目标 Base ID |
| `--table-id` | 是 | 数据源表 ID（sync=true） |

返回当前同步配置详情（sourceConfig、是否自动同步、同步状态等）。仅适用于数据源表，普通表会报错。

## 错误码与排查

| 场景 | 表现 | 排查 |
|------|------|------|
| 同步运行中重复触发 | errorCode=4014，status=FAILED | 幂等冲突，稍后重试即可 |
| 非数据源表触发 sync | 参数错误返回 | 确认 table 的 sync=true，用 `+base-get` / `+table-list` 检查 |
| sourceConfig 缺必填字段 | 创建/更新失败 | 检查 processCode/name/iconUrl/url 是否从 list-sources 原样透传 |
| dataType 与时间字段不匹配 | 创建失败 | recent_time 需 recentDays；time_range 需 startDate+endDate；start_time 需 startDate |

## 能力边界

| 能力 | 状态 |
|------|------|
| OA 审批数据源 | 已支持 |
| 其他数据源类型 | 待后续开放 |
| 全量同步 | 已支持 |
| 增量同步 | 待后续开放 |
| 自动同步 | 已支持（--auto + autoSyncSetting） |
| 删除数据源表 | 走普通表删除，不走 datasource 命令 |

## 注意事项

- sourceConfig 是 **JSON 字符串**（不是 JSON 对象），CLI flag 传入时需要用单引号包裹
- list-sources 返回的 keepRemovedFields / splitParentTableField / enableDataSyncOaDetailList 不要透传，由调用方按需设置
- create/update 后自动触发一次同步，返回 taskId；用 sync-status 查最终结果
- sync 单次最多 5 张表，超出拆分多次调用
- sync-status 单次最多 5 个 taskId，超出拆分多次调用
- get-config 仅适用于数据源表（sync=true），普通表会报错