蓝凌EKP产品：关联机制浅析

在 EKP 系统中，"关联机制"是实现跨业务对象关联、文档互相关联的重要基础能力。本文将从实际项目落地角度，完整介绍关联机制的接入步骤、关键代码以及常见注意事项，帮助你一次性跑通整个流程。

一、关联机制简介

关联机制用于在主业务对象（如文档、流程、知识对象）之间建立逻辑关联关系，支持在编辑页、阅读页中统一维护和展示关联内容。
关联机制文档

典型应用场景包括：

文档与文档之间的关联
文档与流程实例的关联
知识对象与其他业务对象的关联

二、整体接入流程概览

接入关联机制需要同时改动 8 个层面：

Model 层
Form 层
Edit JSP 页面
View JSP 页面
design.xml
数据字典（data-dict）
Action 层
注意事项与坑点

下面逐一展开。

三、修改 Model（核心）

1️⃣ 实现接口

在需要支持关联机制的 Model 类 中，实现接口：

复制代码

com.landray.kmss.sys.relation.interfaces.ISysRelationMainModel

2️⃣ 增加关联属性

复制代码

/**
 * 关联域模型信息
 */
private SysRelationMain sysRelationMain = null;

public SysRelationMain getSysRelationMain() {
    return sysRelationMain;
}

public void setSysRelationMain(SysRelationMain sysRelationMain) {
    this.sysRelationMain = sysRelationMain;
}

/**
 * 关联分表字段
 */
protected String relationSeparate = null;

public String getRelationSeparate() {
    return relationSeparate;
}

public void setRelationSeparate(String relationSeparate) {
    this.relationSeparate = relationSeparate;
}

📌 说明

SysRelationMain：关联主对象
relationSeparate：用于分表或业务隔离场景

四、修改 Form

在对应的 Form 类 中，实现接口：

复制代码

com.landray.kmss.sys.relation.interfaces.ISysRelationMainForm

并添加：

复制代码

/**
 * 关联机制
 */
private SysRelationMainForm sysRelationMainForm = new SysRelationMainForm();

public SysRelationMainForm getSysRelationMainForm() {
    return sysRelationMainForm;
}

📌 作用

用于在页面层承载、回传关联数据。

五、修改 Edit 页面（JSP）

在编辑页面中插入关联机制编辑区：

复制代码

<tr LKS_LabelName="<bean:message bundle='sys-relation' key='sysRelationMain.tab.label' />">

    <c:set var="mainModelForm" value="${kmDocKnowledgeForm}" scope="request"/>
    <c:set var="currModelName" value="com.landray.kmss.km.doc.model.KmDocKnowledge" scope="request"/>

    <td>
        <%@ include file="/sys/relation/include/sysRelationMain_edit.jsp"%>
    </td>

</tr>

参数说明

参数名	是否必填	说明
LKS_LabelName	是	标签名称，如"关联文档"
mainModelForm	是	主 Form 对象
currModelName	可选	主 Model 类名（编辑页必须）

六、修改 View 页面（JSP）

阅读页配置方式与 Edit 页面类似，仅替换 include 文件：

复制代码

<%@ include file="/sys/relation/include/sysRelationMain_view.jsp"%>

📌 注意

模板的 view 页面不要加关联 view
模板只需要 edit 页面即可

七、修改 design.xml

在对应模块的 design.xml 中增加 relation 节点：

复制代码

<relation
    modelName="com.landray.kmss.km.doc.model.KmDocKnowledge"
    messageKey="km-doc:kmDoc.tree.title"/>

⚠️ 重要顺序要求

relation 节点 必须放在 flowDef 之前，否则系统会提示格式错误。

八、修改数据字典（data-dict）

在模块的 data-dict/*.xml 中，为允许被关联的字段增加：

复制代码

canRelation="true"

示例：

复制代码

<simpleProperty
    name="docSubject"
    messageKey="sys-doc:sysDocBaseInfo.docSubject"
    canSearch="true"
    canRelation="true"
    type="String"
    column="doc_subject"
    length="200"
/>

📌 表示该字段可作为关联条件字段。

九、修改 Action（关键）

在创建文档时，需要初始化模板关联信息。

1️⃣ 重载 createNewForm()

复制代码

getDispatchCoreService().initFormSetting(
    mainForm,
    null,
    moduleModel,
    null,
    new RequestContext(request)
);

参数说明

参数	说明
mainForm	主 Form（实现 ISysRelationMainForm）
moduleModel	模板对应的 Model（实现 ISysRelationMainModel）

📌 若不初始化，将导致模板关联信息丢失。

十、注意事项（非常重要）

✔ 关联信息会随 Model ↔ Form 转换 自动维护

✔ Service 层会统一处理新增、更新、删除

✔ 外键字段若要支持搜索，displayProperty 必须配置

✔ 模板 view 页面不要加载关联 view

十一、总结

关联机制本质上是 一套横跨 Model / Form / 页面 / XML / Action 的系统能力，只要严格按步骤接入，整体运行非常稳定。

建议做法：

封装一个可复用的关联接入 Checklist
新模块统一按本文步骤接入
模板与实例页面严格区分