设计质量：最佳实践、反模式与验证

第 6 课 · 共 6 课 约 9 分钟

命名、分组、状态；八个反模式；用业务题链验证；上线前清单。

本课目标

读完这一课，你将能够

  • 用命名、分组和状态让模型好读、好演进
  • 认出八个反模式，说出各自的改法
  • 用业务题链验证模型，并跑一遍上线前清单

命名、分组与状态

评审从名字开始，因为名字最难事后改：改一个链接端的名字或一个属性的类型，就是破坏性变更，会牵连每个用它的应用。所以先约定，再建。

好的写法要避免的
对象类型单数的具体名词，业务专家一眼认得：WorkOrderdata、item、record
属性短而自明，不带类型和实现细节：standardCostUsdvalue、fieldX、dtLastInspMod
日期全模型只用一种写法，并写进约定混用 createdDate 和 dateOfCreation
链接端两头都读得通：customer.orders、salesOrder.customerrelatedItems、link1

新建 Object Type 和 Interface 用 PascalCase，例如 WorkOrder。属性和链接端用 camelCase，Action 用 kebab-case。示例工厂已有的小写类型名仍可用；新建类型要遵守新标准。定义时还会检查链接端：同一对象类型上，链接端名不能重复，也不能和属性同名。

分组（type group）是贴在对象类型上的分类标签，方便搜索和浏览，比如销售、生产、供应。状态决定能不能删除：active 是缺省状态，表示应用在用；experimental 还在开发；deprecated 准备删除；example 只用于培训。不能直接删除 active 构件或属性。先改成 deprecated 或 experimental，提交定义或合并，再删除。弃用时必须写 deprecated.message 和 deadline；replacedBy 可选。

八个反模式

下面八个是常见的坑，评审时逐条对照自己的模型。

症状改法
系统孤岛erpMaterial、mesMaterial 描述同一种物料合成一个 material，写明每个属性以谁为准
大杂烩源表几十列全收，含同步时间戳和内部 ID只留有人会看、搜、筛的属性
部门孤岛salesCustomer、qualityCustomer 各建各的一个 customer，部门信息用属性和关系
上帝对象一个 asset，属性含义随 assetType 变，一半为空拆成 machine、productionLine，共有部分用接口
金锤子什么都做成 Action，比如让人每天点「重算汇总」汇总用派生属性或聚合；数据一变就要做的事，用工作流的 change 触发；Action 留给人的决定
Action 泛滥一个类型十几个 set-…，各改一个字段合成 hold-work-order 这样的业务动作；常见的警戒线是超过 10 个
时间机器workOrderV1、workOrderV2，或用 isCurrent 区分副本一个对象，加编辑历史、时间序列或变更记录对象
含糊命名value、type、date、relatedItems具体的名字，链接端按关系命名

用真实问题验证

结构评审只能说明模型自洽，不能说明有人用得上。验证要拿真实的业务问题当验收题，而且做题的不能是建模的人，因为建模的人会凭记忆绕过缺口。

好题从状况问到影响：先确定情境，再顺着关系追贡献因素，最后评估波及范围。题目来自组织每周反复问的事，不是来自你已经知道能答的事。示例工厂的一条题链：

  1. 情境

    哪家客户本月订单量最大？

  2. 产品

    它的订单里哪个产品占大头？

  3. 工单

    哪些工单在生产这个产品？

  4. 物料

    这些工单要用哪些物料（BOM）？

  5. 缺口

    哪些物料的现存量不够？

  6. 影响

    哪家供应商的延误，让最多的工单有风险？

走一遍就是一次评审：每一步都要能沿着关系走到。哪一步要导出表格再手工拼，说明关系或概念缺了。记下每个人卡在哪、搜了什么词，这些词就是缺的别名，也就是 synonyms。

再让智能体做同一批题：给只读的 Agent Key 和问题，不给路径。人能做、智能体不能，缺的是靠经验才知道的业务规则；都不能，缺的是数据、关系或含义。

上线前的清单

先让平台查结构上的问题：

aidc semantic define ontology/ --dry-run            # do references close? which changes are breaking?
aidc semantic branch create tidy-links
aidc semantic branch modify tidy-links ontology/
aidc semantic branch validate tidy-links            # merge checks
aidc semantic ontology --json --branch tidy-links   # read it back the way an agent will

再逐项过这张单子：

  • 每个对象类型是现实里的一样东西，不是一张表；名字业务专家认得。
  • 每个属性都有人会看、搜或筛，同步时间戳这类技术列没有进来。
  • 每个关系都能回答一个业务问题，两头读起来是一句话。
  • 手工维护的计数和复制来的名字，都改成了派生属性或关系。
  • 重复了三次的形状抽成了接口，必填的接口属性类型一致。
  • 每个 Action 是一件业务上的事，不是「改一个字段」。
  • 破坏性改动已和下游应用确认：改基数，改链接端名或端点，改属性类型，接口加必填属性，类型不再实现某个接口。
  • 一条题链走通了，而且做题的不是建模的人。

这一门到此结束。下一门课讲怎样把数据接进来：数据源只读地流进这些对象类型。

要点

  • 名字最难事后改：先约定，用业务的话，全模型一种日期写法，链接端两头都读得通。
  • 删除 active 构件或属性前，先改状态并提交；弃用要写原因和期限。破坏性改动先和下游应用确认。
  • 八个反模式大多是同一类错：复制、混同或含糊，评审时逐条对照。
  • 用业务题链验证，做题的不是建模的人，再让智能体做一遍。
  • 上线前先跑平台检查，再过一遍清单。

练一练

评审一份模型

拿示例工厂或你自己的模型来做。

用八个反模式逐条给这份模型打分，写出最严重的两处和各自的改法。

小测

选一个答案，马上看解析。

Q1同一种物料在 ERP 和 MES 里各建了一个类型：erpMaterial 和 mesMaterial。这是哪种反模式？

Q2要验证模型好不好用，最有价值的做法是？

Q3一个对象类型已有 12 个 set-… 开头的 Action，各改一个字段。该怎么办？

延伸阅读