表结构 → 企业本体 · 使用说明与示例

客户给了一堆业务系统的表,怎么变成业务对象清单(本体)——不是「一表一对象」照搬。

v1.0 FDE 线 适用:已有系统的逆向建模 收件人:康凯

① 一分钟看懂:这事错在哪、对在哪

库表只是证据,不是结构。表名、字段名、外键、字典码值都只能告诉你「系统怎么存的」, 不能直接告诉你「业务世界里有哪几种东西」。我们要做的是把前者翻译成后者。

✗ 反面:一表一对象(最常见的错)

  • 13 张表 → 出 13 个对象,客户一看 60 个对象,直接不用了
  • 字典表「客户等级表」被建成对象,AI 答不出「这个客户什么级别」
  • 日志表、统计表、中间表全变成对象,噪音挤满语义层
  • 外键列既当属性又当关系,同一事实两处表达,改一处漏一处
  • create_time、is_deleted、tenant_id 进了属性,AI 的注意力被技术列带走

✓ 正面:先归类,再定对象

  • 逐张表判类型(主表 / 明细 / 中间 / 字典 / 日志 / 统计…),按类型决定处置
  • 该合的合(客户 + 客户扩展表 → 一个对象),该拆的拆,该丢的丢
  • 字典 → 枚举属性;外键列 → 关系 + 挂钩列;技术列 → 全部排除
  • 13 张表压到 8 个对象,客户一看就懂
  • 每个对象都能答出三问:谁问它 / 谁写它 / 参与什么判断

判断口诀

东西是对象,特征是属性,连接是关系,可以做的是动作,发生过的是事件, 当前情况是状态,必须遵守的是规则,谁能看/做是权限,必须让人决定的是人工介入。

② 包文件结构:每个文件是干什么的

解压你收到的那个 zip 之后,得到的是下面这一个文件夹。整体只有 13 个文件,其中真正要动手的只有 3 个(下表标 ⭐ 的)。

DB2Ontology-Kangkai\
├─ ⭐ table-to-ontology.zip              ← 导入 WorkBuddy 就选它(20 秒装好)
├─ ⭐ templates\ontology-4tables-blank.xlsx   ← 填四表用这个空白模板
├─ ⭐ tools\check_ontology.py           ← 四表自检脚本(跑出 PASS/FAIL)
│
├─ 表结构转本体_使用说明与示例_v1.0.html   ← 本页(离线可开,也是给客户的说明页)
├─ README.md                            ← 同一份说明的 Markdown 版
├─ install-to-workbuddy.bat             ← 备用:双击即装,不用界面导入时用
│
├─ skills\table-to-ontology\            ← 技能源文件(导入包就是从这里打的)
│   ├─ SKILL.md                         ← 技能主文件:三条铁律 + 五步流程 + 常见错误
│   └─ references\
│       ├─ 01-input-and-mapping.md      ← 12 种表类型→本体映射表、列排除清单、合并/拆分判据
│       ├─ 02-checklist.md              ← 交付前自检清单(机械 A 类 + 判据 B 类)
│       └─ 03-example.md                ← 13 表→8 对象的完整走查
│
├─ templates\input-schema-template.csv  ← 表结构输入模板(让客户/开发按这个填)
├─ example\example-4tables.xlsx         ← 填好的示例四表(对着看格式)
└─ tools\build_templates.py             ← 重新生成模板/示例(改了数据重跑用)
文件 / 文件夹是什么什么时候用
table-to-ontology.zip ⭐打好的技能包:根层就是 SKILL.md + references/,符合 WorkBuddy 导入窗口「需包含 SKILL.md」的要求装技能时选它。⛔ 不要选外层总包
templates\ontology-4tables-blank.xlsx ⭐四表空白模板:对象 / 属性 / 关系 / 动作,带下拉校验、枚举白名单、填表说明页每做一次建模就复制一份来填
tools\check_ontology.py ⭐四表机械自检脚本:查列是否齐、枚举是否合法、有没有悬空引用、关系有没有挂钩列四表填完必跑:python tools\check_ontology.py 你的四表.xlsx
表结构转本体_使用说明与示例_v1.0.html本页。单文件自包含,断网能开,也能直接发给客户看(不含客户数据)给人看流程与示例时
README.md同一份说明的 Markdown 版想在编辑器/仓库里看,或要改说明文字
install-to-workbuddy.bat一键安装脚本:把技能拷到 %USERPROFILE%\.workbuddy\skills\WorkBuddy 里找不到导入入口时的备用路径
skills\table-to-ontology\技能源文件目录(导入包就是从这儿打的);SKILL.md 是主文件,references\ 是三条细则导入失败要排查、或要改技能内容时
references\01-input-and-mapping.md核心规则:12 种表类型怎么判怎么处置、哪些列必须排除、什么时候该合并/拆分、关系怎么命名和挂列遇到「这张表该建成什么」拿不准时查
references\02-checklist.md自检清单:A 类机械项 12 条 + B 类判据项 15 条 + 对外红线 3 条交付前人工过一遍(脚本查不出的部分)
references\03-example.md完整示例:13 张表 → 8 个对象、12 条关系、6 个动作,含处理账与待确认清单第一次做时对照着看;也可直接给客户看效果
templates\input-schema-template.csv表结构输入模板(兜底用):表名/字段/类型/主键/外键/取值说明/样本值只在拿不到 DDL 时用;能拿到建表语句就直接给 DDL
example\example-4tables.xlsx填好的示例四表(带数据,可直接看格式对不对)不确定某一格该怎么填时打开对照
tools\build_templates.py模板/示例的生成脚本(模板和示例都是它产出的)要改类目或加字段时改脚本重跑,别手改 xlsx 当唯一真源
一句话记法:装技能用 table-to-ontology.zip;填表用 templates\ontology-4tables-blank.xlsx;出表后跑 tools\check_ontology.py。 其余 6 个是说明与参考(SKILL.md + 3 个 references 已经装在技能里了,平时不用单独打开)。

③ 装进 WorkBuddy,然后三步跑通

0

先把技能装进 WorkBuddy(用自带的「导入技能」,30 秒)

技能页 → 导入技能 → 弹窗里点「选择 ZIP 文件」→ 选包根目录的:

DB2Ontology-Kangkai\table-to-ontology.zip

这个 zip 是专门做好的技能包:根层直接就是 SKILL.md + references/,正好满足弹窗要求的「文件夹或 zip 需要包含 SKILL.md」。 ⛔ 不要选外层那个 DB2Ontology-Kangkai.zip(它根是 README,容易被判成缺少 SKILL.md)。 弹窗里那个「非高风险自动安装」勾上,能省一次确认。

它不认 zip 就拖文件夹:把解压出来的 skills\table-to-ontology 文件夹直接拖进弹窗的虚线框,效果一样。

备用:不经界面,直接放目录

位置路径效果
用户级(推荐)%USERPROFILE%\.workbuddy\skills\table-to-ontology\装一次,所有项目都能用
项目级<项目文件夹>\.workbuddy\skills\table-to-ontology\只在这个项目里可用

最终结构:…\skills\table-to-ontology\SKILL.md + 同目录 references\ 三个 md(要一起在)。 也可先完整解压,再双击 install-to-workbuddy.bat,自动装到用户级目录(已实测可用)。

怎么知道装上了:技能列表出现 table-to-ontology,描述以「Use when 拿到客户业务系统的表结构…」开头;再说一句「表结构转本体」,它先输出表归类处理账(而不是一表一对象往下建)就是命中了。

⛔ 四种装不上 / 装不对:① 上传被拒「缺少 SKILL.md」=选了外层总包;② 列表里没有=选错层级(进到 references 里);③ 提示已存在=同名重复导入,覆盖或先删;④ 说找不到规则文件=references 没跟着一起进。

最后一招:把 SKILL.md 全文 + references/01-input-and-mapping.md 贴给它当上下文,再说你的表结构——缺点是每次都得贴。

1

收表结构(这一步决定成败,别跳)

三种形态都行,优先直接要 DDL(建表语句 / schema.sql) —— 主键、外键、中文注释都在里面,不用来回问:

形态里面有什么缺什么
DDL / schema.sql ⭐表名、字段、类型、长度、主键、外键、COMMENT 注释样本值、哪些表在用
数据字典 Excel字段清单(表名/字段/类型/注释)外键关系常缺、样本值
按模板的 CSV行列统一、口径干净—(没有 DDL 时的兜底)

让客户的 DBA / 开发导出 DDL,一般 5 分钟:

MySQL      SHOW CREATE TABLE 表名;   或   mysqldump -u用户 -p --no-data 库名 > schema.sql
SQL Server SSMS → 右键数据库 → 任务 → 生成脚本 → 选「仅架构」
Oracle     SELECT DBMS_METADATA.GET_DDL('TABLE','表名') FROM DUAL;
PostgreSQL pg_dump -s -t 表名 库名

⛔ DDL 也补不出来的两样,必须另外要:① 每表 3~5 行样本数据(脱敏)——唯一能验证字段真实含义和取值的东西,没有它枚举值域只能靠猜;② 哪些表还在用、哪些是历史遗留——建了没人问的对象纯属噪音。

⛔ 不要一次丢 80 张表。先挑核心单据链上的 10~15 张(客户 → 商机 → 合同 这类主链路),出第一版,人对齐后再扩。

2

让它出四表 —— 先要「处理账」,再要四表

把下面这段丢给 AI(或 WorkBuddy 里说「表结构转本体」):

按 table-to-ontology 技能,从下面这批表结构推企业本体,
出 对象/属性/关系/动作 四表。

第一步先只给我「表归类处理账」:
每张表 → 判成什么类型 → 处置(建对象 / 合并 / 拆 / 多值属性 / 关系 / 枚举 / 不建)→ 一句理由。
我确认处理账之后,你再填四表。

先要处理账,能提前抓出「字典表当对象建了」「日志表也建了」这类错,比四表出来再推倒省一天。

3

跑自检 + 人工过判据

python tools/check_ontology.py 你的四表.xlsx
python tools/check_ontology.py 你的四表.xlsx --total-fields 115   # 有源字段总数时做对账
  • PASS 结构没问题 → 接着人工过 02-checklist.md 的 B 类判据项(机器查不出)
  • FAIL ERROR 必须清零再交付;WARN 逐条复核

机器能查:列是否齐、枚举是否在白名单、有没有悬空引用、关系有没有挂钩列。 机器查不出:这个对象该不该建、这条关系方向对不对、动作是不是只是查询。

没有 DDL 时:按这个模板整理

这是兜底方案。能拿到 DDL 就不用填这个表。

表名字段名字段中文名类型主键外键→取值说明样本值
crm_customercust_name客户名称varchar(200)苏州某某精密制造
crm_customercust_level客户等级char(2)A=战略/B=重点/C=普通A
crm_customerindustry_code所属行业varchar(20)dict_industry.codeC35

完整版见包内 templates/input-schema-template.csv;不论用哪种形态,每张表再另存一个「样本_表名」Sheet 放 3~5 行真实数据。

④ 示例走查:13 张表 → 8 个对象

场景:一家做工业设备销售的公司,已有自研 CRM(前缀 t_ / d_ / s_ / rpt_)。 共 13 张表、115 个字段。示例只用于演示方法,不含任何真实客户数据。

拿到手的 13 张表

#表名中文量级类型初判
1t_customer客户3 万业务主表
2t_customer_ext客户扩展3 万1:1 扩展表
3t_customer_contact客户联系人8 万子表(1:N)
4t_opportunity商机12 万业务主表
5t_opp_product商机产品明细30 万明细子表
6t_contract合同5 万业务主表
7t_contract_item合同条款明细18 万明细子表
8t_customer_advisor客户-顾问指派6 万中间表
9d_industry行业字典600字典(被引用、有层级)
10d_customer_level客户等级字典4字典(纯取值)
11s_user系统用户800权限层
12t_follow_log跟进记录90 万日志(业务要看历史)
13rpt_customer_month客户月度统计40 万统计快照

表归类处理账(这张表先给人看,确认后再填四表)

表处置判据(为什么)
t_customer + t_customer_ext合并 → 对象「客户」同一主体、同一生命周期、1:1 主键对齐;扩展表只是字段太多拆出去
t_customer_contact→ 对象「联系人」一家客户多个联系人,各自有独立在职/离职状态,会被单独问到("这家客户谁是对接人")
t_opportunity→ 对象「商机」独立生命周期(阶段推进),被合同引用
t_opp_product→ 商机的多值属性「产品明细」行只用于展示与求和,不被任何其他表引用;无独立状态
t_contract→ 对象「合同」独立生命周期(签订/履行/归档),有业务编号
t_contract_item→ 合同的多值属性「条款明细」纯从属,随合同删除
t_customer_advisor→ 对象「客户指派记录」⚠️ 不是关系:中间行带「是否主责」「分配时间」「解除时间」,关系承载不了,必须对象化
d_industry→ 对象「行业」被客户引用、有层级(上级行业)、有启停生命周期;AI 要按行业筛客户
d_customer_level→ 客户.客户等级(枚举)只有 4 行纯取值,没有任何表引用它的 id,业务上不会被单独问"有哪些等级"
s_user不建账号对象账号密码属平台权限层;但"谁负责这个客户"要能答 → 另建「业务人员」对象,来源 s_user
t_follow_log→ 对象「跟进记录」表面是日志,但业务必须能查"上次谁跟这个客户聊了什么"——是业务过程记录,不是运维日志
rpt_customer_month不建统计快照,指标可由商机/合同算出;建了会和源数据打架
13 张表 → 8 个对象不是 13 个,也不是 60 个
12 条关系每条都带挂钩列(表.列)
115 个字段对账62 属性 + 12 关系挂钩 + 41 排除 = 115

对账这一行是硬指标:三个数加不出总数,说明有字段被悄悄丢掉了。

⑤ 四表样例(节选)

完整版见包内 example/example-4tables.xlsx;这里节选对象全量 + 其他抽样。

对象编码一句话(AI 语义)主键通用性
客户customer与我们发生采购关系的企业或组织,是所有业务的发生主体。一家公司只能有一条客户记录,同集团不同法人算不同客户。cust_id行业通用
联系人contact客户内部的具体对接人,可以多人,各自可能有不同在职状态。联系人不是客户。contact_id行业通用
商机opportunity一个有成交可能的销售机会,从初步接触到赢单/输单的完整过程。一个客户可同时有多个商机。opp_id行业通用
合同contract与客户签订的正式销售合同,是收入确认依据。金额不可改,只可作废重签。contract_id行业通用
客户指派记录customer_assignment某客户在一段时间内由谁负责的记录,含主责与协办。换人不改字段,而是结束旧记录开新记录。assign_id客户特有
行业industry客户所属的行业分类,有上下级层级。用于筛选客户、分配行业顾问、统计占比。industry_code行业通用
业务人员staff公司内负责客户与商机的销售/顾问,与登录账号一一对应。只保留业务属性,不含账号密码。staff_id行业通用
跟进记录follow_record业务人员与客户的一次沟通记录,含内容与下次计划。销售过程的真实轨迹。follow_id行业通用
所属对象属性类型必填AI 语义说明来源密级
客户客户名称普通是客户公司全称,与营业执照一致。用于所有对外单据。t_customer.cust_name公开
客户客户等级枚举是客户分级,决定跟进频次与折扣权限:A=年框战略客户(月度拜访)、B=重点客户(双周拜访)、C=普通客户(季度拜访)。D 已停用,遇到按 C 处理。t_customer.cust_level公开
客户客户来源枚举否客户最初从哪里来:展会/官网/转介绍/电话开发/老客户复购。用于评估获客渠道效果。t_customer.source_type公开
客户合作状态枚举是潜客=还没成交、在合作=有未关闭合同、暂停=有合同但暂停供货、流失=连续12个月无新单。流失客户不再进商机推荐。t_customer.coop_status公开
客户统一社会信用代码普通否营业执照上的 18 位信用代码,工商维度唯一标识。与客户编号是两套编码,不要混用。t_customer.credit_code公开
客户年采购规模普通否客户上一年度在我方的采购总额(元),由统计回填,不手工填。t_customer_ext.annual_amt机密
商机商机阶段枚举是10=初步接触、20=需求确认、30=方案报价、40=商务谈判、90=赢单、99=输单。90/99 为终态,不再变更。t_opportunity.stage公开
商机产品明细JSON Array否本商机涉及的产品行:名称/型号/数量/单价/折扣。行只用于展示与报价汇总,不单独跟踪。t_opp_product机密
合同合同编号普通是业务唯一编号,格式 HT-年份-流水,纸质合同与系统必须一致。t_contract.contract_no公开
合同合同状态枚举是10=草稿、20=待审、30=生效、60=履行完毕、90=作废。只有 30 生效才计入收入。t_contract.status公开
联系人姓名普通是客户方对接人姓名。只记真名,不记"张总"这类称呼。t_customer_contact.name机密
联系人手机号普通否对接人手机号,用于拜访预约与回访。属个人信息,仅负责该客户的顾问可见。t_customer_contact.mobile绝密
跟进记录跟进方式枚举是电话=电话沟通、微信=微信沟通、拜访=上门拜访(需填地址)、邮件=邮件往来、其他=其他方式。t_follow_log.type公开
跟进记录跟进内容普通是这次沟通谈了什么(客户原话优先)。是判断客户意向的主要依据。t_follow_log.content机密
客户指派记录是否主责枚举是是=主责顾问(业绩归属、第一联系人)、否=协办。同一客户同一时间只能有一个主责。t_customer_advisor.is_primary公开
行业行业名称普通是行业分类名称,如"汽车零部件制造"。与代码一一对应,代码为准。d_industry.industry_name公开
行业行业代码普通是分类代码(GB/T 4754 口径),客户与统计报表都按此归集。层级见「上级行业」关系。d_industry.industry_code公开
业务人员姓名普通是真实姓名,用于合同签单人、商机归属人显示。s_user.real_name机密
业务人员在职状态枚举是在职=可分配新客户、离职=不可分配但历史业绩保留、停用=长期不在岗。离职人员历史商机不自动转移。s_user.status公开
源对象关系目标对象基数必需挂钩列(源 → 目标)
客户归属行业N:1是t_customer.industry_code → d_industry.industry_code
客户有联系人1:N否t_customer_contact.customer_id → t_customer.cust_id
客户拥有商机1:N否t_opportunity.customer_id → t_customer.cust_id
客户签订合同1:N否t_contract.customer_id → t_customer.cust_id
商机成交为合同1:N否t_contract.opp_id → t_opportunity.opp_id
客户指派记录针对客户N:1是t_customer_advisor.customer_id → t_customer.cust_id
客户指派记录指派给业务人员N:1是t_customer_advisor.user_id → s_user.user_id
商机由…负责业务人员N:1是t_opportunity.owner_id → s_user.user_id
合同由…负责业务人员N:1是t_contract.owner_id → s_user.user_id
跟进记录关于客户N:1是t_follow_log.customer_id → t_customer.cust_id
跟进记录由…发起业务人员N:1是t_follow_log.user_id → s_user.user_id
行业上级行业行业N:1否d_industry.parent_code → d_industry.industry_code

关系方向是业务语义方向(客户 →有→ 商机),不是外键物理方向;关系名用业务动词,不写「关联」「链接」。

所属对象动作角色权限审批执行逻辑(AI 语义)参数(必填/归属人)
客户新建客户销售、销售助理无需审批,留痕「客户第一次接触并确认是真实企业」时用。必填名称+等级+行业;同名客户已存在时不要新建,改用「新增联系人」。客户名称(是/否)、客户等级(是/否)、行业(是/否)
客户调整客户等级销售主管按角色审批「客户年度评估或战略合作变化」时用。必须写原因,A→C 降级要主管确认。客户(是/是)、新等级(是/否)、原因(是/否)
客户指派顾问销售主管按角色审批「新客户分配」或「人员离职/调动需交接」时用。系统结束旧指派记录并开新记录,不改历史。主责同时只能有一个。客户(是/是)、业务人员(是/是)、是否主责(是/否)
跟进记录录入跟进记录销售、顾问无需审批,留痕「每次与客户沟通完」随手记。必须写清谈了什么和下次计划;只写"已联系"没有业务价值。客户(是/否)、跟进方式(是/否)、跟进内容(是/否)
商机推进商机阶段销售按数据归属审批「商机有实质进展」时用。只能向前推进或转输单;90 赢单会自动要求关联合同号。商机(是/是)、目标阶段(是/否)
合同归档合同销售主管按数据归属审批「合同履行完毕或确认作废」时用。作废不影响已发生收入但要注明原因。合同(是/是)、归档类型(是/否)

⛔ 查询列表、看详情、导出 Excel、接口调用 —— 都不是动作。动作只取会改变数据的业务操作。

⑥ 验收与红线

判断产出好不好的三个硬指标

① 对象数量13 张表一般压到 8~15 个对象。对象数 ≈ 表数 = 一表一对象照搬,重做。
② 每对象能答三问谁问它 / 谁写它 / 参与什么判断。答不出来的对象是垃圾对象。
③ 字段对账对得上源字段总数 = 建属性 + 转关系 + 明确排除。对不上=有字段被悄悄丢掉。

红线

红线做法
AI 只出草稿建模表、需求基线、验收标准这几类关键工件必须真人逐条终审——AI 98% 正确也要人读完 100%
推断必须标记AI 推断的条目一律标 🤖推断-待确认,不进对外材料
客户数据不出客户环境人名、手机号、身份证、公司名 ⛔ 不写进本体属性值;本体沉淀的是行业理解,不是客户数据
业务判断不自己定哪个状态算流失、谁能改价格 —— 列进「待确认问题清单」问客户,不替客户做决定

常见错误清单(逐条都是踩过的)

错正确做法
一表一对象,出 60 个对象先归类再定对象,通常压到 8~15 个
字典表建成对象(如「客户等级表」)建成枚举属性,值域写进语义说明
外键列既建属性又建关系只建关系 + 挂钩列;要显示名字的另留可读名称属性
把 create_time/is_deleted/tenant_id 当属性全部排除
直接拿表名当对象名(crm_customer_info)用业务名词:客户、人才、岗位需求
基数全填 1:N 不核对回到数据核对,一对一还是多对多靠样本值验
动作全是「查询/导出」查询不是动作,只取改变数据的业务操作
关系名写「关联」「链接」写业务动词:负责、投递、签订、归属
没样本数据就定枚举取值先标待确认,拿到样本值再定值域