diff --git a/platform-metadata/src/main/java/com/eip4/platform/metadata/publish/MasterDetailLinker.java b/platform-metadata/src/main/java/com/eip4/platform/metadata/publish/MasterDetailLinker.java
new file mode 100644
index 0000000..4199012
--- /dev/null
+++ b/platform-metadata/src/main/java/com/eip4/platform/metadata/publish/MasterDetailLinker.java
@@ -0,0 +1,109 @@
+package com.eip4.platform.metadata.publish;
+
+import java.util.List;
+import java.util.Properties;
+import java.util.UUID;
+
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.stereotype.Component;
+
+import com.dsasp.server.common.dataDic.bean.SYS_Entity;
+import com.dsasp.server.common.dataDic.service.DataDicService;
+import com.dsasp.server.dataDic.bean.Entity;
+import com.eip4.platform.metadata.perf.PoInfoCacheInvalidator;
+
+/**
+ * 主子表接线器(人走五环 · 主子表 recipe 的元数据接线)。
+ *
+ *
把一个已存在的子实体(普通实体 tabletype=1 + 一个指向主表的引用列)接成主表的内联子表:
+ *
+ * - INSERT 一行 SYS_REFERENCEVALUE(entityid=子实体, entityattributeid=子表外键列属性);
+ * - INSERT 主表一条 LIST 类型 SYS_ENTITYATTRIBUTE(referenceid='LIST',
+ * referencevalue=新 SYS_REFERENCEVALUE id, columnname=列表列如 DETAILS)。
+ *
+ * 接线 + {@code cacheInvalidator.evictByTable(主表)} 后,默认流(_ADD/_UPDATE/_LOAD)即自动级联,
+ * 无需任何主子表专属流节点(已实测验证)。LIST 属性无物理 DDL 列(appendColumnDdl 跳过 referenceid='LIST')。
+ *
+ * 幂等:若主表已存在同 columnname 的 LIST 属性,直接返回其 referencevalue,不重复 INSERT。
+ */
+@Component
+public class MasterDetailLinker {
+
+ private final JdbcTemplate jdbcTemplate;
+ private final DataDicService dataDicService;
+ private final PoInfoCacheInvalidator cacheInvalidator;
+
+ public MasterDetailLinker(JdbcTemplate jdbcTemplate,
+ DataDicService dataDicService,
+ PoInfoCacheInvalidator cacheInvalidator) {
+ this.jdbcTemplate = jdbcTemplate;
+ this.dataDicService = dataDicService;
+ this.cacheInvalidator = cacheInvalidator;
+ }
+
+ /**
+ * 接线主→子:确保主表有一条 LIST 属性指向子表(幂等)。
+ *
+ * @param masterTable 主表表名
+ * @param childTable 子表表名(普通实体 tabletype=1)
+ * @param linkColumn 子表上指向主表的外键列名(reference 列)
+ * @param listColumn 主表 LIST 属性的列名(amis input-table 的 name,如 DETAILS)
+ * @param listLabel 主表 LIST 属性的显示名
+ * @param ctx 操作上下文(预留;当前 INSERT 用 'ADMIN' 审计列)
+ * @return 关联的 SYS_REFERENCEVALUE id(新建则为新 UUID,命中既有则为既有值)
+ */
+ public String ensureLink(String masterTable, String childTable, String linkColumn,
+ String listColumn, String listLabel, Properties ctx) {
+ String masterEntityId = entityId(masterTable);
+ String childEntityId = entityId(childTable);
+
+ // 子表外键列的 sys_entityattribute_id
+ String childFkAttrId = jdbcTemplate.queryForObject(
+ "SELECT TRIM(SYS_ENTITYATTRIBUTE_ID) FROM SYS_ENTITYATTRIBUTE "
+ + "WHERE ENTITYID=? AND COLUMNNAME=?",
+ String.class, childEntityId, linkColumn.toUpperCase());
+
+ // 幂等:主表已有同名 LIST 属性 → 复用其 referencevalue
+ List existing = jdbcTemplate.queryForList(
+ "SELECT referencevalue FROM SYS_ENTITYATTRIBUTE "
+ + "WHERE entityid=? AND columnname=? AND referenceid=?",
+ String.class, masterEntityId, listColumn.toUpperCase(), "LIST");
+ if (!existing.isEmpty() && existing.get(0) != null) {
+ return existing.get(0).trim();
+ }
+
+ long now = System.currentTimeMillis();
+ String referenceValueId = UUID.randomUUID().toString();
+ jdbcTemplate.update(
+ "INSERT INTO SYS_REFERENCEVALUE"
+ + "(sys_referencevalue_id,entityid,entityattributeid,isactive,version,"
+ + "createtime,updatetime,createby,updateby)"
+ + " VALUES (?,?,?,?,?,?,?,?,?)",
+ referenceValueId, childEntityId, childFkAttrId, 1, 0,
+ now, now, "ADMIN", "ADMIN");
+
+ String listAttrId = UUID.randomUUID().toString();
+ jdbcTemplate.update(
+ "INSERT INTO SYS_ENTITYATTRIBUTE"
+ + "(sys_entityattribute_id,entityid,columnname,displayname,referenceid,referencevalue,"
+ + "ismandatory,iskey,isidentifier,iscombidentifier,isreadonly,isentitydisplay,"
+ + "isactive,version)"
+ + " VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?)",
+ listAttrId, masterEntityId, listColumn.toUpperCase(), listLabel, "LIST", referenceValueId,
+ 0, 0, 0, 0, 0, 0,
+ 1, 0);
+
+ cacheInvalidator.evictByTable(masterTable);
+ return referenceValueId;
+ }
+
+ private String entityId(String table) {
+ SYS_Entity entity = dataDicService.getSYSEntityByTableName(table.toUpperCase());
+ if (entity == null) {
+ throw new IllegalStateException("实体不存在: " + table);
+ }
+ Entity e = (Entity) entity;
+ String id = e.getPo().get_ID();
+ return id != null ? id : (String) e.getPo().get_Value("SYS_ENTITY_ID");
+ }
+}
diff --git a/platform-metadata/src/test/java/com/eip4/platform/metadata/publish/MasterDetailLinkerTest.java b/platform-metadata/src/test/java/com/eip4/platform/metadata/publish/MasterDetailLinkerTest.java
new file mode 100644
index 0000000..7578c12
--- /dev/null
+++ b/platform-metadata/src/test/java/com/eip4/platform/metadata/publish/MasterDetailLinkerTest.java
@@ -0,0 +1,109 @@
+package com.eip4.platform.metadata.publish;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.ArgumentMatchers.contains;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+import java.util.List;
+import java.util.Properties;
+
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+import org.mockito.ArgumentCaptor;
+import org.springframework.jdbc.core.JdbcTemplate;
+
+import com.dsasp.server.common.dataDic.bean.GeneralPOJO;
+import com.dsasp.server.common.dataDic.bean.SYS_Entity;
+import com.dsasp.server.common.dataDic.service.DataDicService;
+import com.dsasp.server.dataDic.bean.Entity;
+import com.eip4.platform.metadata.perf.PoInfoCacheInvalidator;
+
+@SuppressWarnings({"unchecked", "rawtypes"})
+class MasterDetailLinkerTest {
+
+ private SYS_Entity entityWithId(String entityId) {
+ GeneralPOJO po = mock(GeneralPOJO.class);
+ org.mockito.Mockito.doReturn("SYS_ENTITY").when(po).get_TableName();
+ org.mockito.Mockito.doReturn(entityId).when(po).get_ID();
+ org.mockito.Mockito.doReturn(entityId).when(po).get_Value("SYS_ENTITY_ID");
+ return new Entity(po);
+ }
+
+ private MasterDetailLinker newLinker(JdbcTemplate jdbc, DataDicService dataDic,
+ PoInfoCacheInvalidator invalidator) {
+ return new MasterDetailLinker(jdbc, dataDic, invalidator);
+ }
+
+ @Test
+ @DisplayName("ensureLink 无既有 LIST 属性 → INSERT SYS_REFERENCEVALUE + master LIST 属性,并失效主表缓存")
+ void ensureLinkInserts() {
+ JdbcTemplate jdbc = mock(JdbcTemplate.class);
+ DataDicService dataDic = mock(DataDicService.class);
+ PoInfoCacheInvalidator invalidator = mock(PoInfoCacheInvalidator.class);
+
+ SYS_Entity master = entityWithId("master-id");
+ SYS_Entity child = entityWithId("child-id");
+ when(dataDic.getSYSEntityByTableName("EIP4_ORDER")).thenReturn(master);
+ when(dataDic.getSYSEntityByTableName("EIP4_ORDERLINE")).thenReturn(child);
+
+ // 子表 linkColumn 的 sys_entityattribute_id
+ when(jdbc.queryForObject(contains("FROM SYS_ENTITYATTRIBUTE"), eq(String.class),
+ eq("child-id"), eq("ORDERID"))).thenReturn("child-fk-attr-id");
+ // 幂等检查:主表没有同名 LIST 属性
+ when(jdbc.queryForList(contains("referencevalue"), eq(String.class),
+ eq("master-id"), eq("DETAILS"), anyString()))
+ .thenReturn(List.of());
+
+ String rv = newLinker(jdbc, dataDic, invalidator)
+ .ensureLink("EIP4_ORDER", "EIP4_ORDERLINE", "ORDERID", "DETAILS", "订单明细", new Properties());
+
+ assertNotNull(rv);
+ assertEquals(36, rv.length());
+
+ // 验证两条 INSERT
+ ArgumentCaptor sqlCap = ArgumentCaptor.forClass(String.class);
+ verify(jdbc, org.mockito.Mockito.atLeast(2))
+ .update(sqlCap.capture(), (Object[]) org.mockito.ArgumentMatchers.any(Object[].class));
+ boolean refValInsert = sqlCap.getAllValues().stream()
+ .anyMatch(s -> s.toUpperCase().contains("INSERT INTO SYS_REFERENCEVALUE"));
+ boolean listAttrInsert = sqlCap.getAllValues().stream()
+ .anyMatch(s -> s.toUpperCase().contains("INSERT INTO SYS_ENTITYATTRIBUTE"));
+ org.junit.jupiter.api.Assertions.assertTrue(refValInsert, "应 INSERT SYS_REFERENCEVALUE");
+ org.junit.jupiter.api.Assertions.assertTrue(listAttrInsert, "应 INSERT master LIST 属性");
+
+ verify(invalidator).evictByTable("EIP4_ORDER");
+ }
+
+ @Test
+ @DisplayName("ensureLink 幂等: 主表已有同名 LIST 属性 → 返回既有 referencevalue,不再 INSERT")
+ void ensureLinkIdempotent() {
+ JdbcTemplate jdbc = mock(JdbcTemplate.class);
+ DataDicService dataDic = mock(DataDicService.class);
+ PoInfoCacheInvalidator invalidator = mock(PoInfoCacheInvalidator.class);
+
+ SYS_Entity master = entityWithId("master-id");
+ SYS_Entity child = entityWithId("child-id");
+ when(dataDic.getSYSEntityByTableName("EIP4_ORDER")).thenReturn(master);
+ when(dataDic.getSYSEntityByTableName("EIP4_ORDERLINE")).thenReturn(child);
+ when(jdbc.queryForObject(contains("FROM SYS_ENTITYATTRIBUTE"), eq(String.class),
+ eq("child-id"), eq("ORDERID"))).thenReturn("child-fk-attr-id");
+ // 主表已有同名 LIST 属性,其 referencevalue=existing-rv
+ when(jdbc.queryForList(contains("referencevalue"), eq(String.class),
+ eq("master-id"), eq("DETAILS"), anyString()))
+ .thenReturn(List.of("existing-rv"));
+
+ String rv = newLinker(jdbc, dataDic, invalidator)
+ .ensureLink("EIP4_ORDER", "EIP4_ORDERLINE", "ORDERID", "DETAILS", "订单明细", new Properties());
+
+ assertEquals("existing-rv", rv);
+ verify(jdbc, never()).update(anyString(), (Object[]) any());
+ verify(invalidator, never()).evictByTable(anyString());
+ }
+}