first commit

2026-09-02 11:44:52 +08:00
commit 0c8fa2653e
309 changed files with 57278 additions and 0 deletions
@@ -0,0 +1,49 @@
+# attachment — 附件上传
+
+> **STOP — 不要使用钉盘 (drive) 上传！** 钉盘 fileId 无法写入 attachment 字段。必须使用以下流程。
+>
+> **STOP — 严禁在 record create/update 的 cells 里直接传图片 URL！** 直传 `{"url":"https://..."}` 会导致服务端同步下载图片，批量写入时触发 TIMEOUT_ERROR。正确做法：先 `attachment upload` 获取 `fileToken`，再用 `{"fileToken":"ft_xxx"}` 写入。
+
+## 准备附件上传
+
+```
+Usage:
+  dws aitable attachment upload [flags]
+Example:
+  dws aitable attachment upload --base-id <BASE_ID> --file-name report.xlsx --size 204800
+  dws aitable attachment upload --base-id <BASE_ID> --file-name photo.png --size 1024 --mime-type image/png
+Flags:
+      --base-id string     Base ID (必填)
+      --file-name string   文件名，必须含扩展名 (必填)
+      --size int           文件大小（字节），>0 (必填)
+      --mime-type string   MIME type（不传时根据扩展名推断）
+```
+
+## 附件上传完整流程（推荐：使用脚本，2 步完成）
+
+```bash
+# 步骤 1: 使用脚本一键上传（内部自动完成 prepare + PUT）
+python3 scripts/upload_attachment.py <BASE_ID> /path/to/report.pdf
+# 输出: { "fileToken": "ft_xxx", "fileName": "report.pdf", "size": 204800 }
+
+# 步骤 2: 在 record create/update 中使用 fileToken 写入
+dws aitable record create --base-id <BASE_ID> --table-id <TABLE_ID> \
+  --records '[{"cells":{"fldAttachId":[{"fileToken":"ft_xxx"}]}}]' --format json
+```
+
+> `uploadUrl` 有时效性（`expiresAt`），脚本会自动在获取后立即上传。
+
+## 手动流程（不使用脚本）
+
+```bash
+# 1. 获取上传凭证
+dws aitable attachment upload --base-id <BASE_ID> --file-name report.pdf --size 204800 --format json
+# → 返回 uploadUrl、fileToken
+
+# 2. PUT 上传（Content-Type 必须是文件的具体 MIME type）
+curl -X PUT "<uploadUrl>" -H "Content-Type: application/pdf" --data-binary @report.pdf
+
+# 3. 写入记录
+dws aitable record update --base-id <BASE_ID> --table-id <TABLE_ID> \
+  --records '[{"recordId":"recXXX","cells":{"fldAttachId":[{"fileToken":"ft_xxx"}]}}]' --format json
+```