| name | table-modeling |
| description | 多维表建模——设计表结构、决策单表或双表 link、规划字段并创建关联表。 用户已有字段清单，或提到关联表格、一对多、主表+明细、电影+演员、 商品+SKU、订单+明细时调用。网页采集并落表的整链改走 app:tabdata/collect-to-table，本 skill 只负责数据形态。
|
| metadata | {"version":"0.3.0","tabtin":{"category":"data","displayName":"Table Modeling","autoActivateFor":["tabdata"],"tools":["run_terminal_command"]}} |
Table Modeling
这份 SKILL 只回答两个问题：该建一张表还是两张表？字段怎么挑？
所有执行统一走 tabtin table CLI。
一、先确认交付范围
| 交付范围 | 完成标准 |
|---|
| 只创建结构 | 真正建表并拿到 table_id；明确本次写入 0 条业务数据 |
| 创建结构并写入数据 | 建表后写入；以回执里的成功 / 失败条数为准 |
字段值只允许来自可靠来源或确定性换算。来源没有的字段留空、设为可选，或不创建；
不要为了表格看起来完整而估算或编造。
二、两种产品形态
| 形态 | 适合场景 | 不适合 |
|---|
| 单表 | 一条记录的内容主要是标量；相关清单只需当文本展示 | 子项要独立查询、去重、复用或反向查 |
| 双表 + link | 子项是独立实体，需要跨主记录复用、单独查询或反向查 | 用户只要临时扫一眼的简单清单 |
同表内的任务/子任务、部门层级等树形关系走 tabtin table sub-record *，不要拆成跨表关联。
人话解释
- link：「在这一格挂上另一张表的一行或多行，点一下能跳过去看。」
- 双向 link：「电影挂了演员后，演员那边也会出现『参演电影』，两边都能反查。」
三、决策规则
- 用户明确要简单、扁平、临时使用，或字段都是单实体标量：建单表。
- 同一个子项会出现在多条主记录里，或用户需要从子项反查主项：建双表 + link。
- 子项只是附属明细、不需要独立查询：把摘要放在
long_text，或按业务需要拆成双表；不要创建已下线字段。
- 需求含糊且两种形态会明显改变使用方式时，只问一次：更在意一张表快速浏览，还是两张表互相跳转和反查？
四、执行顺序
双表形态固定按以下顺序：
- 先建被关联的表。
- 再建主表。
- 用
tabtin table link create 创建关联字段。
- 子表按业务键
record upsert 去重。
- 重拉子表，建立「业务键 → record_id」映射。
- 主表写 link 值：
[{"id":"<目标 record UUID>"}]。
- 用
link list 或记录详情读回核对。
具体命令
references/form-recipes.md：单表、双表 link 和同表树形配方examples/form-c-douban-walkthrough.md：电影 + 演员双表完整示例scripts/build-record-index.sh：建立业务键到 record_id 的索引skills_read("app:tabdata/table-association")：挂、解绑、查询关联边skills_read("app:tabdata/table-import-export")：批量写入和导入导出
五、完成后的复述
双表完成后，用产品语言告诉用户：
- 两张表分别叫什么、各有多少条记录；
- 哪一列可以点开跳转；
- 反向关联列在哪里；
- 哪些字段因没有可靠来源而留空。
六、常见反模式
| 反模式 | 正确做法 |
|---|
| 用 select 保存会变化的外部实体 | 改成双表 + link |
| link 值写显示名 | 先取得目标 record_id，再写 [{"id":"..."}] |
| 先建主表，导致目标表 id 不存在 | 先建被关联表，再建主表和 link |
| 为去重先 DELETE 再 INSERT | 用 record upsert --upsert-on |
| 建完双表只说“完成了” | 说明两张表如何跳转和反查 |
七、原则
- TabData 建模、建表、写入和查询全程走 CLI。
- 形态决策完成后再执行，不把已下线字段写进 schema。
- 没有读回证据，不宣称创建或写入成功。
