first commit

2026-09-02 11:44:52 +08:00
commit 0c8fa2653e
309 changed files with 57278 additions and 0 deletions
@@ -0,0 +1,243 @@
+# 视图配置（view get/update <attr>）
+
+按属性局部读/写视图配置。每个属性独立子命令，typed flag 友好，agent 不必拼 JSON。
+向后兼容：`view update --config '{...}'` 一次多属性入口仍可用。
+
+## viewType × 支持矩阵
+
+| viewType | card | timebar | aggregate | filter / sort / group | visible-fields | field-widths | name |
+|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
+| Grid     |     |     | ✅ |  ✅ | ✅ | ✅ | ✅ |
+| Kanban   | ✅ |     |     |  ✅ | ✅ |    | ✅ |
+| Gallery  | ✅ |     |     |  ✅ | ✅ |    | ✅ |
+| Gantt    |     | ✅ |     |  ✅ | ✅ |    | ✅ |
+| Calendar |     |     |     |  ✅ | ✅ |    | ✅ |
+| FormDesigner | （走 `form` 系列命令） | | | | | | |
+
+> card 在 Kanban 走 `kanbanCard`，在 Gallery 走 `galleryCard`，CLI 自动按 viewType dispatch（preflight 1 次 `get_views`）。timebar 仅 Gantt 支持；Calendar 服务端未暴露任何 timebar 配置。
+
+> **Gantt 视图必须两步创建**：`view create --view-type Gantt` 只创建空壳（`ganttTimebar: {}`），**必须**紧跟 `view update timebar --start-field <日期字段ID>` 绑定时间轴字段，否则视图打开是空白。`view create --config` 不接受 `ganttTimebar`，请在创建后使用专属子命令。
+
+## 创建：view create
+
+`--view-type` 支持 `Grid`、`Kanban`、`Gantt`、`Calendar`、`Gallery`、`FormDesigner`。创建时通过 `--config` JSON 设置可见字段：
+
+```bash
+# --config JSON：可同时配置可见字段、筛选、排序和分组；主字段必须排第一
+dws aitable view create --base-id BASE_ID --table-id TABLE_ID \
+  --view-type Grid --name "任务视图" \
+  --config '{"visibleFieldIds":["fldPrimary","fldStatus","fldOwner"],"sort":[{"fieldId":"fldStatus","direction":"asc"}]}'
+```
+
+创建阶段的 `--config` 是 JSON 对象，并且只接受以下 4 个 key：
+
+| key | 类型 | 说明 |
+|---|---|---|
+| `visibleFieldIds` | `string[]` | fieldId 数组，不接受字段名；至少一个，主字段必须排第一 |
+| `filter` | `object[]` | 筛选规则数组；兼容单个 object，CLI 会自动包装为数组 |
+| `sort` | `object[]` | 排序规则数组；兼容单个 object，CLI 会自动包装为数组 |
+| `group` | `object[]` | 分组规则数组；兼容单个 object，CLI 会自动包装为数组 |
+
+描述使用独立的 `--desc '{"content":[]}'`；`description`、`fieldWidths`、`aggregate`、`kanbanCard`、`ganttTimebar`、`galleryCard` 等其他 key 会在调用服务端前被拒绝，并提示对应的 `view update` 子命令。
+
+## 读取：view get <attr>
+
+所有 `view get <attr>` 共用 `--base-id` / `--table-id` / `--view-id`，输出是该属性子块的 JSON（不存在时输出 `{}`）。viewType 不匹配会报错并指明应该选哪种视图。
+
+```bash
+dws aitable view get card --view-id VIEW_ID --format json            # Kanban / Gallery
+dws aitable view get timebar --view-id VIEW_ID --format json         # Gantt
+dws aitable view get aggregate --view-id VIEW_ID --format json       # Grid
+dws aitable view get filter --view-id VIEW_ID --format json          # 所有
+dws aitable view get sort --view-id VIEW_ID --format json
+dws aitable view get group --view-id VIEW_ID --format json
+dws aitable view get visible-fields --view-id VIEW_ID --format json
+dws aitable view get field-widths --view-id VIEW_ID --format json    # Grid
+```
+
+## 写入：view update <attr>
+
+所有 `view update <attr>` 共用 `--base-id` / `--table-id` / `--view-id`。
+**typed flag + `--json` 可混用**；冲突时 typed flag 优先并 stderr 提示。
+card / timebar / aggregate 三类写入有 viewType 校验（preflight 1 次 get_views）。
+
+### view update card（Kanban / Gallery）
+
+服务端按 viewType 分发到 `kanbanCard` 或 `galleryCard`。typed flag 共享。
+
+| flag | 类型 | 说明 |
+|------|------|------|
+| `--cover-field-id` | string | 封面字段 ID（Kanban / Gallery 通用），与 `--no-cover` 互斥 |
+| `--no-cover` | bool | 清除封面（等价 `coverFieldId="NONE"`） |
+| `--cover-resize-mode` | string | `cover` / `contain` / `stretch` |
+| `--hidden-field-title` | bool | 隐藏字段名标题（仅 Kanban 生效） |
+| `--cover-mode` | string | `none` / `auto` / `custom`（仅 Gallery 生效） |
+| `--display-field-name` | bool | 是否显示字段名（仅 Gallery 生效） |
+| `--json` | JSON | 完整 card 子块对象 |
+
+```bash
+dws aitable view update card --view-id KANBAN_ID --cover-field-id fldAttachment --cover-resize-mode contain
+dws aitable view update card --view-id KANBAN_ID --no-cover
+dws aitable view update card --view-id GALLERY_ID --cover-mode auto
+dws aitable view update card --view-id GALLERY_ID --json '{"coverMode":"custom","coverFieldId":"fldX","displayFieldName":true}'
+```
+
+### view update timebar（仅 Gantt）
+
+| flag | 类型 | 说明 |
+|------|------|------|
+| `--start-field` | string (date fieldId) | 开始日期字段 |
+| `--end-field` | string (date fieldId) | 结束日期字段 |
+| `--display-field-id` | string | 时间条上显示的标题字段 |
+| `--timeline-scale` | string | `year` / `quarter` / `month` / `weeks` |
+| `--color-configs` | JSON 数组 | 颜色配置数组（结构由下游协议定义；清空传 `[]`） |
+| `--official-holiday` | bool | 是否标注法定节假日 |
+| `--json` | JSON | 完整 ganttTimebar 子块 |
+
+```bash
+dws aitable view update timebar --view-id GANTT_ID --start-field fldStart --end-field fldEnd --timeline-scale month
+dws aitable view update timebar --view-id GANTT_ID --official-holiday=true
+```
+
+### view update aggregate（仅 Grid）
+
+值是 `map[fieldId]→AggregateAction string`；传 null 清除某个字段聚合。
+
+| flag | 类型 | 说明 |
+|------|------|------|
+| `--field-id` | string | 配合 `--action` 设置**单字段**聚合 |
+| `--action` | string | `SUM`/`AVG`/`MAX`/`MIN`/`MEDIAN`/`RANGE`/`TOTAL`/`DISTINCT`/`EXIST`/`UN_EXIST`/`CHECKED`/`EARLIEST_DATE` 等（按字段类型可用） |
+| `--clear-field-id` | string (CSV) | 一/多个字段 ID，清除其聚合 |
+| `--json` | JSON | 完整 aggregate map |
+
+```bash
+dws aitable view update aggregate --view-id GRID_ID --field-id fldX --action SUM
+dws aitable view update aggregate --view-id GRID_ID --clear-field-id fldA,fldB
+dws aitable view update aggregate --view-id GRID_ID --json '{"fldX":"AVG","fldY":null}'
+```
+
+### view update field-widths（仅 Grid）
+
+| flag | 类型 |
+|------|------|
+| `--field-id` + `--width` | string + int（单字段） |
+| `--json` | `{fldId: width, ...}` |
+
+```bash
+dws aitable view update field-widths --view-id GRID_ID --field-id fldX --width 200
+dws aitable view update field-widths --view-id GRID_ID --json '{"fldA":120,"fldB":200}'
+```
+
+### view update visible-fields（通用）
+
+整组替换可见字段列表与顺序。`field get` 返回的第一个字段是系统行索引/主字段；无论它显示为 text 还是 primaryDoc，都必须保留在数组第一位，且不能隐藏。不要仅凭字段类型猜主字段。
+
+> ⚠️ 注意：服务端**只接受 reorder，不接受真"隐藏字段"**——如果传入的列表比当前 columns 短，缺失的字段不会被隐藏。需要真正隐藏字段请到 AI 表格 Web UI。
+
+| flag | 类型 |
+|------|------|
+| `--field-ids` | string (CSV) |
+| `--json` | string 数组 JSON（与 `--field-ids` 同传时 `--json` 优先） |
+
+```bash
+dws aitable view update visible-fields --view-id VIEW_ID --field-ids fldPrimary,fldA,fldB
+dws aitable view update visible-fields --view-id VIEW_ID --json '["fldPrimary","fldA","fldB"]'
+```
+
+### 列顺序最短闭环
+
+用户说“客户名称最左、状态在金额前”时，不要用通用 `+view-update --config` 探索：
+
+1. `dws aitable field get --base-id <B> --table-id <T> --format json` 取字段有序列表；第一个 fieldId 固定为数组第 1 项。目标 viewId 从真实上下文或 `view get` 返回中取得。
+2. `dws aitable view get visible-fields ...` 取当前完整列数组；必须保留全部现有字段，因为该接口只支持 reorder，不是真隐藏。
+3. 只重排目标：`[主字段, 客户名称, ..., 状态, 金额, ...]`，其他字段保持相对顺序；一次执行 `view update visible-fields`。
+4. 再次 `view get visible-fields`，数组完全一致才算完成。遇到 `PRIMARY_FIELD_CANNOT_BE_MOVED/HIDDEN` 立即停止，重新按步骤 1 构造一次；禁止继续猜排列。
+
+“固定/冻结左侧列”与“放到最左边”不是同一操作。只有 Grid 支持冻结；若要冻结主字段后的目标列，需要冻结前 N 列（例如目标位于第 2 列则 count=2）：
+
+```bash
+dws aitable +view-set-frozen-cols --base-id <B> --table-id <T> --view-id <V> --count <N>
+dws aitable +view-get-frozen-cols --base-id <B> --table-id <T> --view-id <V>
+```
+
+Kanban/Gallery 等视图只调整列顺序，不尝试冻结。
+
+### view update filter / sort / group（通用，纯 --json）
+
+```bash
+dws aitable view update filter --view-id VIEW_ID --json '[{"operator":"and","operands":[{"operator":"eq","operands":["fldX","value"]}]}]'
+dws aitable view update sort   --view-id VIEW_ID --json '[{"fieldId":"fldX","direction":"asc"}]'
+dws aitable view update group  --view-id VIEW_ID --json '[{"fieldId":"fldX","direction":"asc"}]'
+```
+
+> filter/sort/group 入参格式与 `record query --filters`（对象格式）**不同**：view config 这边外层必须是数组。传对象 CLI 会自动 wrap，建议直接用数组。详见 [aitable-filter-sort.md](./aitable-filter-sort.md)。
+
+### view update name（重命名）
+
+```bash
+dws aitable view update name --view-id VIEW_ID --name "新视图名"
+```
+
+等价于 `dws aitable view update --view-id VIEW_ID --name "新视图名"`，无 `config` 参数。
+
+## 服务端字段速查（与 dws CLI 关系）
+
+| dws 子命令 | 服务端 `update_view.config` 子键 | 服务端 Java 模型 |
+|---|---|---|
+| `view update card`（Kanban） | `kanbanCard` | `KanbanCardUpdateInput` |
+| `view update card`（Gallery） | `galleryCard` | `GalleryCardUpdateInput` |
+| `view update timebar` | `ganttTimebar` | `GanttTimebarUpdateInput` |
+| `view update aggregate` | `aggregate` | `Map<fieldId, AggregateAction>` |
+| `view update visible-fields` | `visibleFieldIds` | `List<String>` |
+| `view update filter / sort / group` | `filter` / `sort` / `group` | `List<Object>` |
+| `view update field-widths` | `fieldWidths` | `Map<String, Object>` |
+| `view update name` | （不在 config 内）`newViewName` 顶层 | — |
+
+## 典型工作流
+
+### 排查"Kanban 卡片为啥不显示封面"
+
+```bash
+dws aitable view get card --view-id KANBAN_ID --format json
+# → 看 coverFieldId 是不是 "NONE" 或缺失；不是再看 coverResizeMode 是不是 contain 导致裁掉
+```
+
+### 创建可用的 Gantt 视图（必须两步）
+
+```bash
+# 第 1 步：创建 Gantt 视图
+dws aitable view create --base-id BASE_ID --table-id TABLE_ID \
+  --view-type Gantt --name "项目甘特图" -f json
+# → 记录返回的 viewId
+
+# 第 2 步（必须）：绑定日期字段，否则视图为空
+dws aitable view update timebar --base-id BASE_ID --table-id TABLE_ID \
+  --view-id VIEW_ID --start-field fldDateStart
+# 可选：加结束日期、标题字段、时间尺度
+#   --end-field fldDateEnd --display-field-id fldName --timeline-scale month
+```
+
+### 把 Gantt 时间轴改成季度尺度并加节假日
+
+```bash
+dws aitable view update timebar --view-id GANTT_ID \
+  --timeline-scale quarter --official-holiday=true
+```
+
+### 用 dws 脚本批量替换 Kanban 封面字段
+
+```bash
+for v in viw1 viw2 viw3; do
+  dws aitable view update card --view-id $v --cover-field-id fldNewCover --cover-resize-mode cover --format json | jq .status
+done
+```
+
+### 一次性多属性更新（仍走 legacy --config）
+
+```bash
+dws aitable view update --view-id VIEW_ID --config '{
+  "visibleFieldIds":["fldPrimary","fldA","fldB"],
+  "filter":[{"operator":"and","operands":[]}],
+  "kanbanCard":{"coverFieldId":"fldImg","coverResizeMode":"contain"}
+}'
+```