tabtin-ai/tabtin/table-modeling

Table Modeling

这份 SKILL 只回答两个问题：该建一张表还是两张表？字段怎么挑？ 所有执行统一走 tabtin table CLI。

一、先确认交付范围

字段值只允许来自可靠来源或确定性换算。来源没有的字段留空、设为可选，或不创建； 不要为了表格看起来完整而估算或编造。

二、两种产品形态

同表内的任务/子任务、部门层级等树形关系走 tabtin table sub-record *，不要拆成跨表关联。

人话解释

• link：「在这一格挂上另一张表的一行或多行，点一下能跳过去看。」
• 双向 link：「电影挂了演员后，演员那边也会出现『参演电影』，两边都能反查。」

三、决策规则

1. 用户明确要简单、扁平、临时使用，或字段都是单实体标量：建单表。
2. 同一个子项会出现在多条主记录里，或用户需要从子项反查主项：建双表 + link。
3. 子项只是附属明细、不需要独立查询：把摘要放在 long_text，或按业务需要拆成双表；不要创建已下线字段。
4. 需求含糊且两种形态会明显改变使用方式时，只问一次：更在意一张表快速浏览，还是两张表互相跳转和反查？

四、执行顺序

双表形态固定按以下顺序：

1. 先建被关联的表。
2. 再建主表。
3. 用 tabtin table link create 创建关联字段。
4. 子表按业务键 record upsert 去重。
5. 重拉子表，建立「业务键 → record_id」映射。
6. 主表写 link 值：[{"id":"<目标 record UUID>"}]。
7. 用 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")：批量写入和导入导出

五、完成后的复述

双表完成后，用产品语言告诉用户：

• 两张表分别叫什么、各有多少条记录；
• 哪一列可以点开跳转；
• 反向关联列在哪里；
• 哪些字段因没有可靠来源而留空。

六、常见反模式

七、原则

• TabData 建模、建表、写入和查询全程走 CLI。
• 形态决策完成后再执行，不把已下线字段写进 schema。
• 没有读回证据，不宣称创建或写入成功。