Poly ItemType 多态建模

Poly ItemType（Polymorphic ItemType）用于把多个具体 ItemType 作为一组 poly sources 暴露给查询、 Item 属性或 Relationship 的 related type。它最有价值的场景，是“一个引用位置需要接受多种具体对象”。

适用版本

本文以 R24～R34 Programmer's Guide 的 Polymorphic ItemTypes Server Event Inheritance、 官方应用中的 poly source 用法，以及 Extended Classification 官方文档为基线。 旧版管理界面可能把关系页显示为 Morphae，新版文档或界面也常称 Poly Sources；以目标 Release 为准。

---

1. Poly ItemType 是统一入口，不是新实体

Poly ItemType 表达“这些来源可以在某些位置被当作一组使用”。 真实业务记录仍属于 Part、Document 等具体 ItemType。

因此：

• 新增业务对象时，目标应是具体 poly source。
• 生命周期、表单和业务规则主要仍在具体 ItemType 上设计。
• 查询 Poly ItemType 可以返回不同来源的 Item。
• 指向 Poly ItemType 的关系或 Item 属性可以选择不同来源对象。

不要把 Poly ItemType 描述成可直接保存公共业务数据的“抽象父表”。

---

2. 什么时候使用

需求	是否适合 Poly ItemType
一个 Change Item 关系要关联 Part、Document、CAD	适合
对多个来源执行统一搜索或选择	适合
两个 ItemType 只是字段相似，但不会被共同引用	通常不需要
希望把名称完全不同的字段自动映射成一列	不适合，Poly 不提供任意字段映射
希望所有来源共享同一张数据库表	不应以底层表结构推导方案

如果引用位置永远只允许一个具体类型，应直接指向该 ItemType，减少选择界面和包依赖复杂度。

---

3. 公共属性契约

Poly ItemType 上出现的属性必须能由每个 poly source 提供。 实践中应确保所有来源存在同名、兼容数据类型的 Property。

例如，统一搜索需要以下列：

Poly Property	Part	Document
name	name	name
item_number	item_number	item_number
state	state	state

如果 Document 只有 title、Part 只有 name，不要假设可以在 Morphae 关系上声明 title → name 映射。 应重新设计公共属性，或在各来源维护一个语义一致的公共字段。

修改顺序很重要

先让每个 poly source 具备公共 Property，再修改 Poly ItemType。 否则保存或包导入可能出现“property must be common to all sources”一类错误。

---

4. 建模步骤

4.1 定义公共契约

1. 列出真正需要统一显示或查询的 Property。
2. 核对每个来源的内部名称、数据类型、长度和数据源。
3. 对不一致项决定统一字段、同步规则或放弃公共列。
4. 先把公共 Property 部署到所有来源。

4.2 创建 Polymorphic ItemType

1. 新建 ItemType，例如 z_Deliverable。
2. 将 Implementation Type 设为 Polymorphic。
3. 保存后，在 Poly Sources / Morphae 关系中添加来源。
4. 只添加已经满足公共属性契约的 ItemType。
5. 保存并检查搜索界面可选择的来源。

4.3 作为关系目标

1. 创建 RelationshipType，例如 z_Project Deliverable。
2. Source 指向业务容器 z_Project。
3. Related 指向 z_Deliverable Poly ItemType。
4. 在测试 Project 中分别选择两个具体来源。

Poly ItemType 让一个关系接受多种 related Item；关系本身仍可以保存数量、角色、顺序等自己的属性。

---

5. AML 查询边界

可以使用 Poly ItemType 做统一 get：

<AML>
  <Item type="z_Deliverable"
        action="get"
        select="id,item_number,name" />
</AML>

返回项可能来自不同具体 ItemType。消费端必须读取结果 Item 的实际 type，不能假设全部是同一种来源。

当需要新增、编辑、删除或执行来源专属 action 时，先确定具体 ItemType，再对该来源发起操作。 不要把对 Poly 的 get 能工作，外推为所有 action 都能透明分派。

只选择公共字段

统一查询优先 select 明确的公共 Property。 来源专属字段应在识别实际 type 后再查询，避免空值与难以解释的网格列。

---

6. Server Event 继承

官方 Programmer's Guide 允许在 Polymorphic ItemType 上定义 Server Event。 其 poly sources 会继承该事件处理器；每个来源发生对应事件时，处理器会执行。

这适合真正跨来源一致的规则，例如统一审计前置校验。

实施前必须确认：

• Method 只读取所有来源都具备的公共 Property。
• 不与来源自身事件重复执行相同逻辑。
• serverEvents="0" 的行为与 Required Server Event 设置已验证。
• 批量请求下 Server Event Version 行为符合目标 Release。
• 失败与回滚场景已测试。

在 ItemType 的 Inherited Server Events 区域可以检查来源继承到的事件。

---

7. Poly 与 Extended Classification

Poly ItemType 也可能参与 xProperty 查询，但要注意来源一致性。 官方 Extended Classification 文档明确指出：如果某个 xProperty 存在于 Poly ItemType、却不存在于某个 poly source， 对该来源请求该 xProperty 会返回 Null。

因此不要用 Poly 绕过分类模型：

1. 明确 xProperty 应定义在 Poly、来源还是分类树。
2. 对每个来源分别测试有值、无值和无定义三种情况。
3. 查询结果同时记录实际 ItemType。
4. 升级或重命名 poly source 后重新验证 xClassification Tree。

---

8. 可复现实验：两个来源、一个关系

8.1 准备

1. 创建 z_Test_Part 与 z_Test_Document。
2. 两者都添加 item_number 和 name，类型保持一致。
3. 各创建一条测试数据。
4. 创建 z_Test_Deliverable Poly ItemType并添加两个来源。

8.2 验证查询

1. 对 z_Test_Deliverable 执行上节 AML。
2. 断言结果包含两条数据。
3. 记录每条 Item 的实际 type。
4. 用 item_number 条件分别命中两个来源。

8.3 验证关系

1. 创建 z_Test_Project 和指向 Poly 的 RelationshipType。
2. 在同一个 Project 中分别关联两个来源 Item。
3. 保存、重新打开并确认两条关系仍指向正确具体类型。
4. 用两个不同权限账号验证来源 Item 的可见性。

8.4 验证失败路径

1. 在 Poly 上尝试增加一个只存在于其中一个来源的测试 Property。
2. 记录平台给出的验证错误。
3. 撤销修改，先向另一来源添加同名兼容 Property。
4. 再次保存并导出包，验证部署顺序。

测试完成后删除整个 z_Test_* 测试包，不直接清理内部数据库表。

---

9. 打包与升级

Package Definition 至少应包含：

• Poly ItemType。
• 新增的 poly source ItemType（若非目标环境已有）。
• 所有来源新增的公共 Properties。
• Morphae / Poly Sources 关系。
• 指向 Poly 的 Property 或 RelationshipType。
• Poly 上的 Server Event 及 Method。

在 imports.mf 中先导入来源与公共属性，再导入 Poly 及其引用。 使用 Thorough 模式在干净数据库演练，避免目标环境因旧版公共属性不一致而失败。

---

10. 常见错误

宣称 Poly 一定对应 SQL View 或 UNION ALL

这是实现层推断，不是稳定的建模契约。不要直接修改数据库对象，也不要用其名称编写业务 SQL。

宣称公共属性可以任意映射

来源需要提供共同属性。名称或类型不一致时应重新建模，而不是虚构映射步骤。

在 Poly 上直接新增业务记录

新增应指向具体 poly source；Poly 主要作为统一引用和查询入口。

认为 Poly 权限覆盖所有来源

权限组合必须用不同来源和业务 Identity 实测，不能以 Poly 搜索页的显示结果推断服务器授权。

忘记继承 Server Event

Poly 上的事件会影响所有来源。新增 poly source 前要检查 Inherited Server Events。

---

11. 官方依据

• Server Events — Polymorphic ItemTypes Server Event Inheritance
• R34 Programmer's Guide
• Variant Management 27 Administrator Guide — 官方 Poly Source 示例
• Extended Classification — PolyItem xProperty 行为
• Aras Labs 对公共属性要求的答复

文档最后核验：2026-08-13。