Teable 1.10 功能验证手册
Teable 1.10.0 核心功能 24 项逐条实测：注册/登录/令牌、空间项目表、6 类字段与公式实时计算、记录增删改查与历史评论、视图/分享/表单匿名提交、附件两步上传落盘、协作邀请、自动化 402 许可限制与 PostgreSQL 直连对账，附结论汇总表与 FAQ。
Teable 1.10 功能验证手册
目标：对 Teable 1.10.0（Standalone 自托管）核心功能逐项实测——每项给出「操作（实测命令）→ 实测回显（逐字照录）→ 预期比对结论」。验证方式以 REST API 为主（等价于网页端操作），覆盖认证、空间/项目/表、字段类型、记录增删改查、视图、分享、表单、附件、评论、协作、自动化与 PostgreSQL 直连核对。本手册不删除任何实测资源，可作为升级后的回归检查清单。
一、环境信息
- 操作系统：Ubuntu 22.04.4 LTS
- Teable：1.10.0（发布件构建
release.2026-10-16T07-06-34Z.3445） - 部署形态：Standalone（应用 + PostgreSQL 15.4 + Redis 7.2.4），部署过程见《Teable Docker Compose 部署指南》
- 访问入口：
http://127.0.0.1:8105（PUBLIC_ORIGIN一致） - 验证账号：
admin@teable.local/q1w2e3r4（首个注册用户，实例管理员，角色 owner）member@teable.local/q1w2e3r4（验证中途注册的普通用户，邀请为空间 editor）
- 验证日期：2026-10-18
- API 调用方式：会话 Cookie 认证为主（登录后沿用），个人访问令牌（Bearer）为辅；OpenAPI 规范实测地址
GET /docs-json（749 个端点，规范 servers 指向http://127.0.0.1:8105/api）
二、验证结论汇总表
| # | 功能项 | 关键操作 | 实测结果 | 结论 |
|---|---|---|---|---|
| 1 | 用户注册（首个=管理员） | POST /api/auth/signup | 返回 isAdmin: true | ✅ 通过 |
| 2 | 密码登录/错误密码 | POST /api/auth/signin | 正确 200+Cookie；错误 400 invalid_credentials（含 attempts 计数） | ✅ 通过 |
| 3 | 个人访问令牌 | POST /api/access-token | 必须显式 expiredTime；teable_<id>_<key> 格式 | ✅ 通过 |
| 4 | 令牌鉴权与作用域 | Bearer 调用 | 用户级接口 200；表级资源 403（需单独授权） | ✅ 通过（有条件） |
| 5 | 空间创建 | POST /api/space | spc4MStcbvUDneupBHN | ✅ 通过 |
| 6 | 项目创建 | POST /api/base/ | bseDnZ2ZGYocXpPptgh | ✅ 通过 |
| 7 | 建表（含多字段类型） | POST /api/base/{id}/table | 6 字段+2 记录一次成型；字段选项校验严格 | ✅ 通过 |
| 8 | 字段类型扩展 | POST /api/table/{id}/field/ | user/formula 创建成功；公式必须用字段 ID | ✅ 通过 |
| 9 | 公式实时计算 | 更新源字段后读记录 | 工时 3.5→6，公式列 7→12 | ✅ 通过 |
| 10 | 记录批量创建 | POST …/record/ | 3 条一次成功 | ✅ 通过 |
| 11 | 记录查询（过滤） | GET …/record/?filter= | 过滤「优先级=高」命中 2 条 | ✅ 通过 |
| 12 | 记录更新 | PATCH …/record/{id} | 字段级更新回显正确 | ✅ 通过 |
| 13 | 记录删除 | DELETE …/record/?recordIds[]= | 返回删除快照，计数 5→4 | ✅ 通过 |
| 14 | 记录历史 | GET …/record/{id}/history | 字段级 before/after（3.5→6） | ✅ 通过 |
| 15 | 记录评论 | POST /api/comment/.../create | 富文本结构写入成功，count=1 | ✅ 通过 |
| 16 | 视图创建 | POST …/view/ | kanban/form 视图创建成功 | ✅ 通过 |
| 17 | 视图分享 | POST …/enable-share | shareId=shrr2eaNc31pAjqpxKk | ✅ 通过 |
| 18 | 匿名读分享数据 | GET /api/share/{id}/view/records | 无认证返回 4 条记录 | ✅ 通过 |
| 19 | 表单匿名提交 | POST /api/share/{id}/view/form-submit | 匿名写入记录成功 | ✅ 通过 |
| 20 | 附件上传（本地存储） | signature→upload 两步 | 文件落盘 uploads/private/table/ | ✅ 通过 |
| 21 | 空间协作邀请 | POST /api/space/{id}/collaborator | member 受邀为 editor | ✅ 通过 |
| 22 | 自动化（工作流） | POST /api/base/{id}/workflow | 402 未激活许可 | ⚠️ 商业许可限制 |
| 23 | PostgreSQL 直连核对 | psql 查业务表 | 记录即真实表（5 行、公式列已物化） | ✅ 通过 |
| 24 | 健康检查 | GET /health | {"status":"ok", ...} | ✅ 通过 |
总体结论：23/24 项通过；唯一受限项是自动化（需付费许可激活），详见 11.1。
三、认证与会话验证
3.1 首个用户注册自动成为管理员
操作（注册第一个账号）：
curl -s -X POST "http://127.0.0.1:8105/api/auth/signup" \
-H "Content-Type: application/json" \
-d '{"email":"admin@teable.local","password":"q1w2e3r4"}'
实测回显：
{"id":"usrmBbQTvZwObJ4ugW8","name":"admin","phone":null,"email":"admin@teable.local","isAdmin":true,"lang":"en","notifyMeta":{"email":true},"avatar":"http://127.0.0.1:8105/api/attachments/read/public/avatar/usrmBbQTvZwObJ4ugW8","hasPassword":true}
预期比对：isAdmin: true ✅（首个注册用户自动成为实例管理员）；头像 URL 前缀与 PUBLIC_ORIGIN 一致 ✅。
3.2 登录与错误密码
操作（错误密码登录）：
curl -s -X POST "http://127.0.0.1:8105/api/auth/signin" \
-H "Content-Type: application/json" \
-d '{"email":"admin@teable.local","password":"wrongpass123"}'
实测回显：
{"message":"Email or password is incorrect","status":400,"code":"invalid_credentials","data":{"attempts":1,"localization":{"i18nKey":"httpErrors.auth.emailOrPasswordIncorrect"}}}
预期比对：错误密码返回 400 invalid_credentials ✅，且携带 attempts 连续失败计数（有防爆破计数机制）。
正确密码登录（实测回显关键头）：
HTTP/1.1 200 OK
Set-Cookie: auth_session=s%3AfPNBo8DvYDPbnAEeeMOlMB_CYD215DZN.kULZwnWun4CiX5yUjo2jd9T8CJn89HiEF%2ByIOAzSBwU; Path=/; Expires=Mon, 18 Oct 2027 18:11:20 GMT; HttpOnly; SameSite=Lax
预期比对：Cookie HttpOnly + SameSite=Lax ✅（安全属性符合预期）。
3.3 个人访问令牌创建与作用域
操作（创建令牌；注意 expiredTime 必填）：
curl -s -b /tmp/c1-cookie.txt -X POST "http://127.0.0.1:8105/api/access-token" \
-H "Content-Type: application/json" \
-d '{"name":"c1-expiry-test","scopes":["table|read"],"expiredTime":"2026-11-17T12:25:32.000Z"}'
实测回显：
{"id":"accXduBQVn9TPgLCycI","name":"c1-expiry-test","scopes":["table|read"],"expiredTime":"2026-11-17T12:25:32.000Z","createdTime":"2026-10-18T12:25:32.287Z","token":"teable_accXduBQVn9TPgLCycI_BcElAUIKV0lDfSxCEdW2yVYRh44mikBVrPCSWHkBoSc="}
预期比对：令牌格式 teable_<id>_<key> ✅；缺省 expiredTime 时返回 400 校验错误（实测 Invalid input: expected string, received undefined at "expiredTime"）✅。
令牌调用用户级接口（GET /api/auth/user，Authorization: Bearer <token>）：实测 200 返回用户信息 ✅。
令牌调用表级资源（GET /api/table/{tableId}/record/）：实测返回 403：
{"message":"You are not allowed to access table tblNXuCPolP9Qv9xUvK","status":403,"code":"restricted_resource"}
预期比对与结论：令牌即使具备 table|read 作用域，仍需在具体资源（项目/表）上单独授权才能读写；作用域只是能力上限，不是资源授权本身。这是最容易踩坑的点：API 调用 403 时先检查令牌的资源授权，而不是怀疑令牌失效。
四、空间与项目验证
4.1 创建空间
curl -s -b /tmp/c1-cookie.txt -X POST "http://127.0.0.1:8105/api/space" \
-H "Content-Type: application/json" -d '{"name":"功能验证空间"}'
实测回显：
{"id":"spc4MStcbvUDneupBHN","name":"功能验证空间"}
预期比对：空间 ID 前缀 spc ✅。
4.2 创建项目
curl -s -b /tmp/c1-cookie.txt -X POST "http://127.0.0.1:8105/api/base/" \
-H "Content-Type: application/json" \
-d '{"spaceId":"spc4MStcbvUDneupBHN","name":"验证项目"}'
实测回显：
{"id":"bseDnZ2ZGYocXpPptgh","name":"验证项目","icon":null,"spaceId":"spc4MStcbvUDneupBHN"}
预期比对：项目归属空间正确 ✅；项目 ID 前缀 bse ✅。
五、表与字段类型验证
5.1 建表（6 类字段 + 初始记录）
操作（POST /api/base/{baseId}/table，一次带 6 类字段与 2 条记录）：
curl -s -b /tmp/c1-cookie.txt -X POST "http://127.0.0.1:8105/api/base/bseDnZ2ZGYocXpPptgh/table" \
-H "Content-Type: application/json" -d '{
"name":"任务清单",
"fields":[
{"type":"singleLineText","name":"任务名称"},
{"type":"longText","name":"描述"},
{"type":"number","name":"工时","options":{"formatting":{"type":"decimal","precision":1}}},
{"type":"singleSelect","name":"优先级","options":{"choices":[{"name":"高"},{"name":"中"},{"name":"低"}]}},
{"type":"checkbox","name":"完成"},
{"type":"date","name":"截止日期","options":{"formatting":{"date":"ISO","time":"None","timeZone":"Asia/Shanghai"}}}
],
"records":[
{"fields":{"任务名称":"部署验证","工时":3.5,"优先级":"高","截止日期":"2026-10-20"}},
{"fields":{"任务名称":"编写文档","工时":2,"优先级":"中","完成":true}}
]}'
实测回显（关键字段）：
table id: tblNXuCPolP9Qv9xUvK | name: 任务清单 | dbTableName: bseDnZ2ZGYocXpPptgh.tblNXuCPolP9Qv9xUvK
defaultViewId: viwP2XIeWpn4lUNkDJE
fields:
singleLineText | 任务名称 | fldGQWDqOgoU5f9WBfk
longText | 描述 | fldA941jQjeCk4TNbsF
number | 工时 | fldhT8P0IRZYM96wZiF
singleSelect | 优先级 | fldNXYLM8MTxfCn3UK4
checkbox | 完成 | fldgI0cpX0yPCBqjfNE
date | 截止日期 | fldFStcsbQZrX0h2SmK
records: 2
预期比对：6 类字段全部创建成功 ✅；dbTableName 形如 <项目ID>.<表ID>（每个项目对应 PostgreSQL 一个 schema）✅。
过程中的校验实测（预期比对的重要补充——字段选项校验非常严格，三处常见错误实测）：
- 单选颜色名必须是官方枚举（实测
"redDark"报错：Invalid option: expected one of "blueLight2"|"blueLight1"|"blueBright"|"blue"|...）； - date 字段
formatting必填（实测缺省报expected object, received undefined at "formatting"）； - date 字段
timeZone必填且不能为 null（实测Datetime formatting requires "timeZone" field）。
💡 建议：不熟悉选项结构时，先在网页端建一个样例字段，用
GET /api/table/{tableId}/field/读取其options作为模板。
5.2 扩展字段：用户与公式
创建用户字段：
curl -s -b /tmp/c1-cookie.txt -X POST "http://127.0.0.1:8105/api/table/tblNXuCPolP9Qv9xUvK/field/" \
-H "Content-Type: application/json" \
-d '{"type":"user","name":"负责人","options":{"isMultiple":false}}'
实测回显：
{"id":"fldtf9lOI8soznZ49xx","name":"负责人","dbFieldName":"Fu_Ze_Ren","unique":false,"cellValueType":"string","dbFieldType":"TEXT","type":"user","options":{"isMultiple":false,"shouldNotify":false}}
创建公式字段（必须引用字段 ID）：
curl -s -b /tmp/c1-cookie.txt -X POST "http://127.0.0.1:8105/api/table/tblNXuCPolP9Qv9xUvK/field/" \
-H "Content-Type: application/json" \
-d '{"type":"formula","name":"工时翻倍","options":{"expression":"{fldhT8P0IRZYM96wZiF}*2"}}'
实测回显：
{"id":"fldMAm3cOhdnurquyfc","type":"formula","cellValueType":"number","dbFieldName":"Gong_Shi_Fan_Bei","options":{"expression":"{fldhT8P0IRZYM96wZiF}*2","timeZone":"Asia/Shanghai","formatting":{"type":"decimal","precision":2}}}
预期比对：公式字段创建成功 ✅。重要实测：用字段名 {工时} 报错 Formula references not found: 工时. Formulas must use field IDs (fldXXXXXXXXXXXXXXXX format), not field names.——公式表达式必须用字段 ID 引用。
5.3 公式实时计算验证
操作：把「部署验证」记录的工时从 3.5 改为 6，再读记录。
实测回显（更新后单条记录）：
{"id":"recrrfQ8HxS3kPOTWkK","fields":{"任务名称":"部署验证(已复盘)","工时":6,"优先级":"高","完成":true,"截止日期":"2026-10-19T16:00:00.000Z","工时翻倍":12}}
预期比对：公式列 工时翻倍 由 7 实时重算为 12 ✅；日期按 Asia/Shanghai 时区转换为 UTC 存储（2026-10-20 00:00+08 → 2026-10-19T16:00:00Z）✅。
六、记录增删改查验证
6.1 批量创建
curl -s -b /tmp/c1-cookie.txt -X POST "http://127.0.0.1:8105/api/table/tblNXuCPolP9Qv9xUvK/record/" \
-H "Content-Type: application/json" \
-d '{"records":[{"fields":{"任务名称":"联调测试","工时":5,"优先级":"低","描述":"与前端联调接口","完成":false}},{"fields":{"任务名称":"性能压测","工时":8,"优先级":"高"}},{"fields":{"任务名称":"上线检查","完成":true,"优先级":"中"}}]}'
实测回显（3 条全部成功）：
rec9KV8E5fyHcxpC98a | 联调测试
recaZWPLXOLS5jw3B4c | 性能压测
recoytlv79Lml56ZgCh | 上线检查
created: 3
6.2 列表与过滤查询
列表读取（注意实测路由需要尾斜杠 /record/，不带斜杠返回 404——路由怪癖，见 13.1 FAQ）：
curl -s -b /tmp/c1-cookie.txt "http://127.0.0.1:8105/api/table/tblNXuCPolP9Qv9xUvK/record/?take=10"
实测回显（节选）：
{"records":[{"id":"recrrfQ8HxS3kPOTWkK","fields":{"任务名称":"部署验证","工时":3.5,"优先级":"高","截止日期":"2026-10-19T16:00:00.000Z"},"name":"部署验证","autoNumber":1,"createdTime":"2026-10-18T12:40:24.160Z","lastModifiedTime":"2026-10-18T12:40:24.160Z","createdBy":"usrmBbQTvZwObJ4ugW8","lastModifiedBy":"usrmBbQTvZwObJ4ugW8"}, ...]}
过滤查询（「优先级=高」，filter 为 JSON URL 编码）：
GET /api/table/tblNXuCPolP9Qv9xUvK/record/?take=10&filter={"conjunction":"and","filterSet":[{"fieldId":"fldNXYLM8MTxfCn3UK4","operator":"is","value":"高"}]}
实测回显：命中 2 条（部署验证、性能压测，均为高优先级）✅。orderBy（排序）与 search 参数同接口支持（规范 GET /table/{tableId}/record 参数表）。
6.3 更新记录
curl -s -b /tmp/c1-cookie.txt -X PATCH \
"http://127.0.0.1:8105/api/table/tblNXuCPolP9Qv9xUvK/record/recrrfQ8HxS3kPOTWkK" \
-H "Content-Type: application/json" \
-d '{"record":{"fields":{"工时":6,"完成":true,"任务名称":"部署验证(已复盘)"}}}'
实测回显：
{"id":"recrrfQ8HxS3kPOTWkK","fields":{"任务名称":"部署验证(已复盘)","工时":6,"优先级":"高","截止日期":"2026-10-19T16:00:00.000Z","完成":true}}
预期比对：三个字段同时更新成功，未更新字段保持不变 ✅。
6.4 删除记录
curl -s -b /tmp/c1-cookie.txt -X DELETE \
"http://127.0.0.1:8105/api/table/tblNXuCPolP9Qv9xUvK/record/?recordIds%5B0%5D=recaZWPLXOLS5jw3B4c"
实测回显（返回被删记录快照）：
{"records":[{"id":"recaZWPLXOLS5jw3B4c","fields":{"fldGQWDqOgoU5f9WBfk":"性能压测","fldhT8P0IRZYM96wZiF":8,"fldNXYLM8MTxfCn3UK4":"高"}}]}
预期比对：删除后列表计数 5→4 ✅。注意：请求体方式（{"recordIds":[...]}）实测报 400 expected array, received undefined，需用查询参数 recordIds[0]=... 形式——以实测为准。实测本版本删除记录未进入回收站（GET /api/trash?resourceType=space&resourceId=... 返回空列表）。
6.5 记录历史（字段级审计）
curl -s -b /tmp/c1-cookie.txt \
"http://127.0.0.1:8105/api/table/tblNXuCPolP9Qv9xUvK/record/recrrfQ8HxS3kPOTWkK/history"
实测回显（节选，工时字段变更）：
{"historyList":[{"id":"rhicd0c368cbe1167288b4e9b64","tableId":"tblNXuCPolP9Qv9xUvK","recordId":"recrrfQ8HxS3kPOTWkK","fieldId":"fldhT8P0IRZYM96wZiF","before":{"meta":{"type":"number","name":"工时"},"data":3.5},"after":...
预期比对：字段级 before/after 完整记录（3.5→6）✅，可追溯修改人。
6.6 记录评论
curl -s -b /tmp/c1-cookie.txt -X POST \
"http://127.0.0.1:8105/api/comment/tblNXuCPolP9Qv9xUvK/recrrfQ8HxS3kPOTWkK/create" \
-H "Content-Type: application/json" \
-d '{"content":[{"type":"p","children":[{"type":"span","value":"部署验证已完成复盘，工时调整为 6 小时"}]}]}'
实测回显：
{"id":"comhjPQBZK8wrq2RCqh","recordId":"recrrfQ8HxS3kPOTWkK","content":[{"type":"p","children":[{"type":"span","value":"部署验证已完成复盘，工时调整为 6 小时"}]}]}
评论计数（GET /api/comment/{tableId}/{recordId}/count）实测：{"count":1} ✅。
💡 说明：评论正文是结构化富文本（
type:"p"→children→type:"span"+value），传纯字符串会 400 校验失败（实测），结构按实测样例构造。
七、视图验证
7.1 视图创建与列表
curl -s -b /tmp/c1-cookie.txt -X POST "http://127.0.0.1:8105/api/table/tblNXuCPolP9Qv9xUvK/view/" \
-H "Content-Type: application/json" -d '{"type":"kanban","name":"按优先级看板"}'
实测回显：
{"id":"viwE6LgWZW18kyr2nFe","type":"kanban","name":"按优先级看板","options":{}}
同法创建表单视图（type=form）实测成功：viewId: viw91uXJO0QG2tJDbOM。视图列表（GET …/view/）实测：
viwP2XIeWpn4lUNkDJE | grid | Grid view
viwE6LgWZW18kyr2nFe | kanban | 按优先级看板
viw91uXJO0QG2tJDbOM | form | 任务提交表单
预期比对：Grid 默认视图 + Kanban/Form 自定义视图 ✅。
八、分享与表单验证
8.1 开启视图分享
curl -s -b /tmp/c1-cookie.txt -X POST \
"http://127.0.0.1:8105/api/table/tblNXuCPolP9Qv9xUvK/view/viwP2XIeWpn4lUNkDJE/enable-share"
实测回显：
{"shareId":"shrr2eaNc31pAjqpxKk"}
分享状态核对（GET …/view/{viewId}）实测：shareId: shrr2eaNc31pAjqpxKk | enableShare: True ✅。
8.2 匿名读取分享数据
操作（无任何认证）：
curl -s "http://127.0.0.1:8105/api/share/shrr2eaNc31pAjqpxKk/view/records?take=10"
实测回显：返回 4 条记录（部署验证(已复盘)/编写文档/联调测试/上线检查）✅。
⚠️ 实测现象：分享视图的页面路由（
/share/{shareId}及变体）在本环境返回 404，而分享数据 API 与分享元信息（GET /api/share/{shareId}/view）完全正常——按 API 链路验证分享功能可用；若页面打不开，优先核对PUBLIC_ORIGIN与前端路由（SPA 深链）。
8.3 表单匿名提交（端到端）
操作（无认证，向表单视图分享提交一条记录）：
curl -s -X POST "http://127.0.0.1:8105/api/share/shr5C9ny148mV6GnD5z/view/form-submit" \
-H "Content-Type: application/json" \
-d '{"fields":{"fldGQWDqOgoU5f9WBfk":"匿名表单提交测试"},"submissionTimes":1}'
实测回显：
{"id":"rec3l7KHK9w3Ebvk8qs","fields":{"fldGQWDqOgoU5f9WBfk":"匿名表单提交测试","fldMAm3cOhdnurquyfc":0}}
预期比对：匿名提交成功且记录 ID 已生成（rec3l7KHK9w3Ebvk8qs）✅；表中记录数随之 +1（第九章直查可见 5 行）✅。表单视图自身不展示记录列表（分享 records 返回空属预期行为）。
九、PostgreSQL 直连核对（架构级验证）
操作（直连主库，查询业务表——表名即 dbTableName）：
docker compose exec -T teable-db psql -U teable -d teable \
-c 'SELECT "__auto_number" AS 序号, "Ren_Wu_Ming_Cheng" AS 任务名称, "Gong_Shi" AS 工时, "You_Xian_Ji" AS 优先级, "Gong_Shi_Fan_Bei" AS 工时翻倍 FROM "bseDnZ2ZGYocXpPptgh"."tblNXuCPolP9Qv9xUvK" ORDER BY "__auto_number";'
实测回显：
序号 | 任务名称 | 工时 | 优先级 | 工时翻倍
------+------------------+------+--------+----------
1 | 部署验证(已复盘) | 6 | 高 | 12
2 | 编写文档 | 2 | 中 | 4
3 | 联调测试 | 5 | 低 | 10
5 | 上线检查 | | 中 | 0
6 | 匿名表单提交测试 | | | 0
(5 rows)
预期比对结论：
- 记录即真实 PostgreSQL 表：界面里的 6 条操作（2 初始 + 3 批量 + 1 匿名表单 − 1 删除）与库中 5 行完全对账 ✅；
- 公式列已物化：
Gong_Shi_Fan_Bei（工时翻倍）是数据库真实列，值随记录物化存储 ✅； - 字段列名自动转换：中文字段名转为拼音 slug 列名（
Ren_Wu_Ming_Cheng），另有系统列__id、__auto_number、__created_time、__last_modified_time、__created_by、__last_modified_by、__version✅； - 每个 Project 对应一个独立 schema（实测
bseDnZ2ZGYocXpPptghschema 内含 2 张业务表）✅。
⚠️ 注意：查询时 schema/表名/列名都要用双引号保留大小写；已删除记录行号（4）不回补，
__auto_number保持递增。
十、附件与本地存储验证
操作分两步（先取上传签名，再传文件）：
# 1. 获取上传签名（须带实际字节数）
curl -s -b /tmp/c1-cookie.txt -X POST "http://127.0.0.1:8105/api/attachments/signature" \
-H "Content-Type: application/json" \
-d '{"contentType":"text/plain","contentLength":72,"type":1,"expiresIn":3600,"baseId":"bseDnZ2ZGYocXpPptgh"}'
实测回显：
{"token":"5CrfXTdRfYyG","path":"table/5CrfXTdRfYyG","url":"/api/attachments/upload/5CrfXTdRfYyG","uploadMethod":"PUT","requestHeaders":{"Content-Type":"text/plain","Content-Length":72}}
# 2. 按签名 PUT 上传
curl -s -b /tmp/c1-cookie.txt -X PUT "http://127.0.0.1:8105/api/attachments/upload/5CrfXTdRfYyG" \
-H "Content-Type: text/plain" --data-binary @/tmp/c4-attach.txt
实测回显：HTTP 200（空响应体）。落盘核对（本地存储卷内）：
/app/.assets/uploads/private/table/5CrfXTdRfYyG # 内容与上传文件一致（grep 核对通过）
预期比对：
- 两步签名上传流程 ✅；
contentLength与实际字节数不一致时报 400Size mismatch（实测）✅； - 默认
BACKEND_STORAGE_PROVIDER=local时文件落在uploads/private/table/<token>，与《Teable 1.10 配置参数详解》9.1 一致 ✅； type枚举 1~21（实测 1=Table 场景须带baseId，否则报The baseId is required when type is Table）。
十一、协作与自动化验证
11.1 空间协作邀请
注册普通用户 member@teable.local（实测回显 isAdmin: null，非管理员 ✅），随后邀请：
curl -s -b /tmp/c1-cookie.txt -X POST \
"http://127.0.0.1:8105/api/space/spc4MStcbvUDneupBHN/collaborator" \
-H "Content-Type: application/json" \
-d '{"collaborators":[{"principalType":"user","principalId":"usrqnUm9BiC5MqleZhl"}],"role":"editor"}'
实测回显：HTTP 200（空响应体）。成员列表核对（GET …/collaborators?take=10）：
{"total":2, "collaborators":[
{"userName":"member","email":"member@teable.local","role":"editor", ...},
{"userName":"admin","email":"admin@teable.local","role":"owner", ...}]}
预期比对：邀请成功、角色 editor 生效 ✅。角色枚举实测为 owner|creator|editor|commenter|viewer；请求结构要点：role 是顶层字段（不是每个 collaborator 内嵌），被邀请人用 principalId（用户 ID）+ principalType（实测报错回显枚举 user|department）标识。
11.2 自动化（工作流）——未激活许可实测
curl -s -b /tmp/c1-cookie.txt -X POST "http://127.0.0.1:8105/api/base/bseDnZ2ZGYocXpPptgh/workflow" \
-H "Content-Type: application/json" -d '{"name":"新记录通知"}'
实测回显：
{"message":"Need to upgrade the subscription to use this feature","status":402,"code":"payment_required","data":{"feature":"automationEnable","localization":{"i18nKey":"httpErrors.billing.upgradeRequired"}}}
预期比对与结论：未激活商业许可的自托管实例，自动化能力（API 中称 workflow）返回 402 payment_required（feature=automationEnable） ⚠️。即：Standalone 部署默认不含自动化，需要按官方定价购买许可（license key）就地解锁；评估自动化能力时必须先确认许可状态。
十二、健康与版本回归
curl -s http://127.0.0.1:8105/health
实测回显：
{"status":"ok","info":{"metaDatabase":{"responseTime":2,"status":"up"}},"error":{},"details":{"metaDatabase":{"responseTime":2,"status":"up"}}}
OpenAPI 规范自检（GET /docs-json）：openapi: 3.0.0 | title: Teable App | version: 1.0.0，共 749 个端点路径（automation 相关端点未在 Standalone 规范中暴露，与 11.2 的 402 行为一致）。Swagger UI 入口 GET /docs 实测 200。
十三、常见问题（FAQ）
Q1：GET /api/table/{tableId}/record 返回 404？
实测路由需要尾斜杠：GET /api/table/{tableId}/record/ 返回 200。这是本版本路由实现的真实行为（规范 servers 指向 /api、路径为 /table/{tableId}/record，实测不带斜杠 404）。同理记录删除等接口按实测路径写。
Q2：API 返回 402 payment_required？
该功能需要商业许可（实测 feature=automationEnable，自动化/工作流全组）。Standalone 未激活许可时创建/查询工作流均 402。处理：购买许可按官方流程激活，或评估期跳过自动化项。
Q3：个人访问令牌调用表接口 403？
令牌作用域（scopes）只定义能力上限，资源访问还要在项目/表上对令牌单独授权（实测 table|read 令牌读表仍 403 restricted_resource）。处理：在网页端把令牌加入对应项目的协作者，或改用会话 Cookie 调用。
Q4：字段选项校验报错怎么办？
1.10.0 对字段选项校验严格（实测三例：单选颜色枚举、date 的 formatting 必填、timeZone 必填且不可 null）。建议先用网页端建样例字段再读回 options 作为模板；公式表达式必须用字段 ID（{fldXXXX}），用字段名报 Formula references not found。
Q5：删除记录为什么没进回收站？
实测本版本记录删除不产生 trash 项（/api/trash 返回空）；回收站实测作用于空间/项目级删除（接口参数 resourceType=space|base）。重要记录删除前先做项目备份（《Teable Docker Compose 部署指南》5.4）。
Q6：表单提交接口返回的字段 ID 是什么？
表单提交（form-submit）按字段 ID 写入（实测 fldGQWDqOgoU5f9WBfk 对应「任务名称」）。先从建表/字段接口拿到字段 ID 映射再构造提交体。
十四、参考链接
- 官方 API 文档（749 端点规范同源）：https://help.teable.ai/en/api-doc/token （查询日期 2026-10-18）
- 本实例 OpenAPI 规范：
GET http://<服务器>:8105/docs-json（Swagger UI：/docs） - 官方字段类型参考：https://help.teable.ai/en/basic/field/field （查询日期 2026-10-18）
- 官方自动化文档：https://help.teable.ai/en/basic/automation/ （查询日期 2026-10-18；自托管需许可）
- 关联文档：《Teable Docker Compose 部署指南》（环境与部署）、《Teable 1.10 配置参数详解》（参数与故障行为）、《Teable 1.10 介绍与选型指南》（版本与架构）