feat(modeler): EIP4 侧板五控件(办理人meta透传/会签/formKey/扩展属性/监听器)

选中 userTask 时在标准属性面板上方叠加 React 侧板(§0.5 P5),全部写操作经
modeling.updateProperties(element,{...}),undo/redo 天然生效:
- 办理人:activiti:candidateUsers 经 codec parse→items 表格→build 写回,
  🔴 codec 外层业务 meta(taskSuccessService 等)存 ref、写回原样带回(硬要求用例覆盖)
- 会签:loopCharacteristics 开关(moddle.create MultiInstanceLoopCharacteristics,
  activiti:collection multiInstance 变体+elementVariable=assignee+completionCondition
  全票/过半/指定数 N 三预设);关→undefined
- formKey:GET /api/workflow/wftemplates 下拉写 activiti:formKey(裸 UUID),「无」清除
- 扩展属性:长尾 $attrs(activiti:/flowable:)增删改
- 任务监听器:activiti:taskListener event+class/delegateExpression 互斥;已有 field
  子元素显示徽标并原样保留(moddle 元素引用不动)

新增 useSelectedElement hook(订阅 selection.changed,单选返 element/多选空选 null/卸载解绑)。
ProcessModelerPage 右栏上方挂 Eip4Panel(modeler 入 state 驱动订阅)。
📌 红线回归:ProcessModelerPage 断言 moddleExtensions 键恰 ['activiti']、
additionalModules 长度 2(防双包冲突静默丢 userTask)。

测试:Eip4Panel 20 + useSelectedElement 5 + ProcessModelerPage 10(+1 红线);
全量 vitest 164 绿 / tsc -b 干净 / npm run build 成功。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
2026-07-02 11:35:13 +08:00
parent 3dfb90f59b
commit 6dc9075648
7 changed files with 1138 additions and 9 deletions

624
src/modeler/Eip4Panel.tsx Normal file
View File

@@ -0,0 +1,624 @@
// EIP4 定制侧板:选中 userTask 时叠加办理人/会签/formKey/扩展属性/任务监听器五控件。
//
// 设计要点(计划 T2.4 + §0.5 P5):
// - 全部写操作经 bpmn-js `modeling.updateProperties(element, {...})`,undo/redo 天然生效。
// - 办理人/会签共用 items 编辑器(ItemsEditor),表达式编解码走 candidateExpression codec。
// - 🔴 meta 透传硬要求:codec parse 出的外层业务字段(taskSuccessService 等)存入 ref,
// 写回时原样带回 build,否则重新部署会打掉已部署流程的任务后置服务钩子。
// - 扩展属性只列长尾 $attrs(已声明属性如 formKey/candidateUsers 不进 $attrs,故不重复)。
// - taskListener 重建时原样保留其 field 子元素(moddle 元素引用不动)。
// - 原生标准属性面板照旧显示于本侧板下方,本控件顶部灰字提示以本控件为准。
import { useEffect, useRef, useState } from 'react';
import {
buildCandidateExpression,
parseCandidateExpression,
type CandidateVariant,
type UserPropertyItem,
} from './candidateExpression';
import { fetchWfTemplates, type WfTemplateOption } from '../api/processModeler';
import type { BpmnElement, SelectionModeler } from './useSelectedElement';
import { useSelectedElement } from './useSelectedElement';
// ── bpmn-js 服务契约(最小) ───────────────────────────────────────────────────
interface Modeling {
updateProperties(element: BpmnElement, props: Record<string, unknown>): void;
}
interface Moddle {
create(type: string, props?: Record<string, unknown>): Record<string, unknown>;
}
export interface PanelModeler extends SelectionModeler {
get(service: string): unknown;
}
// ── 办理人 type 取值(§0 实测 10 种)+ 中文标签 ────────────────────────────────
const CANDIDATE_TYPES: Array<{ value: string; label: string }> = [
{ value: 'user', label: '指定人员' },
{ value: 'depart', label: '指定部门' },
{ value: 'position', label: '指定岗位' },
{ value: 'formSpecifiedDimension', label: '表单指定维度' },
{ value: 'initiator', label: '流程发起人' },
{ value: 'sameToTask', label: '同某任务办理人' },
{ value: 'beforeTaskLeader', label: '上一办理人领导' },
{ value: 'beforeTaskDepartManager', label: '上一办理人部门经理' },
{ value: 'scriptUser', label: '脚本/表达式' },
{ value: 'projectRoleType', label: '项目角色' },
];
const LISTENER_EVENTS = ['create', 'assignment', 'complete', 'all'];
// ── 会签完成条件预设 ─────────────────────────────────────────────────────────
type CompletionType = 'all' | 'majority' | 'count';
const COMPLETION_ALL = '${nrOfCompletedInstances/nrOfInstances==1}';
const COMPLETION_MAJORITY = '${nrOfCompletedInstances/nrOfInstances>0.5}';
function completionBody(type: CompletionType, n: number): string {
if (type === 'majority') return COMPLETION_MAJORITY;
if (type === 'count') return '${nrOfCompletedInstances>=' + n + '}';
return COMPLETION_ALL;
}
function parseCompletion(body: string | undefined): { type: CompletionType; n: number } {
if (!body) return { type: 'all', n: 2 };
if (body.indexOf('>0.5') >= 0) return { type: 'majority', n: 2 };
const m = body.match(/nrOfCompletedInstances>=(\d+)/);
if (m) return { type: 'count', n: Number(m[1]) };
return { type: 'all', n: 2 };
}
// ── moddle 读值(兼容 .get(name) 与直读属性) ──────────────────────────────────
function mget(obj: unknown, name: string): unknown {
if (!obj || typeof obj !== 'object') return undefined;
const o = obj as Record<string, unknown> & { get?: (n: string) => unknown };
if (typeof o.get === 'function') return o.get(name);
return o[name];
}
function newCandidateItem(): UserPropertyItem {
return {
type: 'user',
content: '',
isCandidate: true,
isSendMail: false,
isSendPhone: false,
isSendMessage: false,
};
}
interface ListenerRow {
event: string;
mode: 'class' | 'delegateExpression';
value: string;
/** 原监听器的 field 子元素数组(编辑时原样保留,引用不动)。 */
fields?: unknown[];
}
interface CosignState {
enabled: boolean;
items: UserPropertyItem[];
completionType: CompletionType;
completionN: number;
}
// ── items 编辑器(办理人 / 会签人员复用) ──────────────────────────────────────
function ItemsEditor({
idPrefix,
items,
onChange,
}: {
idPrefix: string;
items: UserPropertyItem[];
onChange: (next: UserPropertyItem[]) => void;
}) {
const patch = (i: number, p: Partial<UserPropertyItem>) =>
onChange(items.map((it, idx) => (idx === i ? { ...it, ...p } : it)));
const remove = (i: number) => onChange(items.filter((_, idx) => idx !== i));
const add = () => onChange([...items, newCandidateItem()]);
return (
<div style={{ display: 'flex', flexDirection: 'column', gap: 6 }}>
{items.map((it, i) => (
<div
key={i}
style={{
border: '1px solid var(--line)',
borderRadius: 4,
padding: 6,
display: 'flex',
flexDirection: 'column',
gap: 4,
}}
>
<div style={{ display: 'flex', gap: 4 }}>
<select
data-testid={`${idPrefix}-type-${i}`}
value={it.type}
onChange={(e) => patch(i, { type: e.target.value })}
style={{ flex: '0 0 120px' }}
>
{CANDIDATE_TYPES.map((t) => (
<option key={t.value} value={t.value}>
{t.label}
</option>
))}
</select>
<input
data-testid={`${idPrefix}-content-${i}`}
value={it.content}
placeholder="人员/部门/岗位 id 或表达式"
onChange={(e) => patch(i, { content: e.target.value })}
style={{ flex: 1, minWidth: 0 }}
/>
<button
className="btn btn-sm"
data-testid={`${idPrefix}-remove-${i}`}
onClick={() => remove(i)}
title="删除该行"
>
删
</button>
</div>
<div style={{ display: 'flex', gap: 10, flexWrap: 'wrap', fontSize: 12 }}>
<label>
<input
type="checkbox"
data-testid={`${idPrefix}-iscandidate-${i}`}
checked={!!it.isCandidate}
onChange={(e) => patch(i, { isCandidate: e.target.checked })}
/>{' '}
候选
</label>
<label>
<input
type="checkbox"
data-testid={`${idPrefix}-mail-${i}`}
checked={!!it.isSendMail}
onChange={(e) => patch(i, { isSendMail: e.target.checked })}
/>{' '}
邮件
</label>
<label>
<input
type="checkbox"
data-testid={`${idPrefix}-phone-${i}`}
checked={!!it.isSendPhone}
onChange={(e) => patch(i, { isSendPhone: e.target.checked })}
/>{' '}
短信
</label>
<label>
<input
type="checkbox"
data-testid={`${idPrefix}-msg-${i}`}
checked={!!it.isSendMessage}
onChange={(e) => patch(i, { isSendMessage: e.target.checked })}
/>{' '}
站内
</label>
</div>
</div>
))}
<button className="btn btn-sm" data-testid={`${idPrefix}-add`} onClick={add}>
+ 添加办理人
</button>
</div>
);
}
function Section({ title, children }: { title: string; children: React.ReactNode }) {
return (
<div style={{ borderBottom: '1px solid var(--line)', padding: '10px 12px' }}>
<div style={{ fontWeight: 600, fontSize: 13, marginBottom: 8 }}>{title}</div>
{children}
</div>
);
}
export function Eip4Panel({ modeler }: { modeler: PanelModeler | null }) {
const element = useSelectedElement(modeler);
const modeling = modeler ? (modeler.get('modeling') as Modeling | undefined) : undefined;
const moddle = modeler ? (modeler.get('moddle') as Moddle | undefined) : undefined;
const isUserTask = element?.type === 'bpmn:UserTask';
// ── 本地编辑态(选中变更时从 businessObject 重新初始化) ──────────────────────
const [candidateItems, setCandidateItems] = useState<UserPropertyItem[]>([]);
const [cosign, setCosign] = useState<CosignState>({
enabled: false,
items: [],
completionType: 'all',
completionN: 2,
});
const [formKey, setFormKey] = useState('');
const [extAttrs, setExtAttrs] = useState<Array<{ key: string; value: string }>>([]);
const [newAttr, setNewAttr] = useState<{ key: string; value: string }>({ key: '', value: '' });
const [listeners, setListeners] = useState<ListenerRow[]>([]);
const [templates, setTemplates] = useState<WfTemplateOption[]>([]);
// meta 透传:codec parse 出的外层业务字段,写回时原样带回(不进 UI 渲染,只存 ref)。
const candidateMetaRef = useRef<Record<string, unknown>>({});
const cosignMetaRef = useRef<Record<string, unknown>>({});
// 非 taskListener 的扩展元素(formProperty 等)原样保留(引用不动)。
const otherExtRef = useRef<unknown[]>([]);
// formKey 数据源加载一次。
useEffect(() => {
let alive = true;
Promise.resolve(fetchWfTemplates())
.then((t) => alive && setTemplates(Array.isArray(t) ? t : []))
.catch(() => alive && setTemplates([]));
return () => {
alive = false;
};
}, []);
// 选中变更 → 从 businessObject 重新初始化本地态。
useEffect(() => {
if (!element || element.type !== 'bpmn:UserTask') {
setCandidateItems([]);
setCosign({ enabled: false, items: [], completionType: 'all', completionN: 2 });
setFormKey('');
setExtAttrs([]);
setNewAttr({ key: '', value: '' });
setListeners([]);
candidateMetaRef.current = {};
cosignMetaRef.current = {};
otherExtRef.current = [];
return;
}
const bo = element.businessObject;
// 办理人
const cand = parseCandidateExpression(bo.get('activiti:candidateUsers') as string | undefined);
setCandidateItems(cand?.items ?? []);
candidateMetaRef.current = cand?.meta ?? {};
// 会签
const loop = bo.get('loopCharacteristics');
if (loop) {
const parsed = parseCandidateExpression(mget(loop, 'activiti:collection') as string | undefined);
const cc = parseCompletion((mget(loop, 'completionCondition') as { body?: string } | undefined)?.body);
setCosign({
enabled: true,
items: parsed?.items ?? [],
completionType: cc.type,
completionN: cc.n,
});
cosignMetaRef.current = parsed?.meta ?? {};
} else {
setCosign({ enabled: false, items: [], completionType: 'all', completionN: 2 });
cosignMetaRef.current = {};
}
// formKey
setFormKey((bo.get('activiti:formKey') as string) ?? '');
// 扩展属性(长尾 $attrs,只留 activiti:/flowable: 前缀)
const attrs = bo.$attrs ?? {};
setExtAttrs(
Object.entries(attrs)
.filter(([k]) => k.startsWith('activiti:') || k.startsWith('flowable:'))
.map(([key, value]) => ({ key, value: String(value) })),
);
setNewAttr({ key: '', value: '' });
// 任务监听器
const extEl = bo.get('extensionElements') as { values?: unknown[] } | undefined;
const values = (extEl?.values ?? []) as unknown[];
otherExtRef.current = values.filter((v) => (v as { $type?: string }).$type !== 'activiti:taskListener');
setListeners(
values
.filter((v) => (v as { $type?: string }).$type === 'activiti:taskListener')
.map((v) => {
const cls = mget(v, 'class') as string | undefined;
const del = mget(v, 'delegateExpression') as string | undefined;
const fields = ((v as { fields?: unknown[] }).fields ?? mget(v, 'fields')) as unknown[] | undefined;
return {
event: (mget(v, 'event') as string) ?? 'create',
mode: cls ? 'class' : del ? 'delegateExpression' : 'class',
value: cls ?? del ?? '',
fields: fields && fields.length ? fields : undefined,
} as ListenerRow;
}),
);
}, [element]);
function update(props: Record<string, unknown>) {
if (element && modeling) modeling.updateProperties(element, props);
}
// ── 办理人写回 ─────────────────────────────────────────────────────────────
function writeCandidate(items: UserPropertyItem[]) {
setCandidateItems(items);
if (items.length === 0) {
update({ 'activiti:candidateUsers': undefined });
return;
}
update({
'activiti:candidateUsers': buildCandidateExpression(items, 'candidate', candidateMetaRef.current),
});
}
// ── 会签写回 ───────────────────────────────────────────────────────────────
function writeCosign(next: CosignState) {
setCosign(next);
if (!next.enabled) {
update({ loopCharacteristics: undefined });
return;
}
if (!moddle) return;
const collection = buildCandidateExpression(
next.items,
'multiInstance' as CandidateVariant,
cosignMetaRef.current,
);
const completionCondition = moddle.create('bpmn:FormalExpression', {
body: completionBody(next.completionType, next.completionN),
});
const loop = moddle.create('bpmn:MultiInstanceLoopCharacteristics', {
isSequential: false,
'activiti:collection': collection,
'activiti:elementVariable': 'assignee',
completionCondition,
});
update({ loopCharacteristics: loop });
}
// ── formKey 写回 ───────────────────────────────────────────────────────────
function writeFormKey(value: string) {
setFormKey(value);
update({ 'activiti:formKey': value === '' ? undefined : value });
}
// ── 扩展属性写回 ───────────────────────────────────────────────────────────
function addExtAttr() {
const key = newAttr.key.trim();
if (!key) return;
setExtAttrs((prev) => {
const rest = prev.filter((a) => a.key !== key);
return [...rest, { key, value: newAttr.value }];
});
update({ [key]: newAttr.value });
setNewAttr({ key: '', value: '' });
}
function editExtAttr(key: string, value: string) {
setExtAttrs((prev) => prev.map((a) => (a.key === key ? { ...a, value } : a)));
update({ [key]: value });
}
function removeExtAttr(key: string) {
setExtAttrs((prev) => prev.filter((a) => a.key !== key));
update({ [key]: undefined });
}
// ── 任务监听器写回 ─────────────────────────────────────────────────────────
function writeListeners(next: ListenerRow[]) {
setListeners(next);
if (!moddle) return;
const listenerEls = next.map((l) => {
const props: Record<string, unknown> = { event: l.event };
props[l.mode] = l.value;
if (l.fields && l.fields.length) props.fields = l.fields;
return moddle.create('activiti:taskListener', props);
});
const all = [...otherExtRef.current, ...listenerEls];
const extEl = all.length ? moddle.create('bpmn:ExtensionElements', { values: all }) : undefined;
update({ extensionElements: extEl });
}
function addListener() {
writeListeners([...listeners, { event: 'create', mode: 'class', value: '' }]);
}
function patchListener(i: number, p: Partial<ListenerRow>) {
writeListeners(listeners.map((l, idx) => (idx === i ? { ...l, ...p } : l)));
}
function removeListener(i: number) {
writeListeners(listeners.filter((_, idx) => idx !== i));
}
// ── 渲染 ───────────────────────────────────────────────────────────────────
if (!element) {
return (
<div data-testid="process-modeler-eip4-panel" style={hintStyle}>
请选择一个用户任务节点以编辑 EIP4 属性。
</div>
);
}
if (!isUserTask) {
return (
<div data-testid="process-modeler-eip4-panel" style={hintStyle}>
选中的不是用户任务节点。EIP4 定制控件仅对用户任务(办理人 / 会签 / formKey)可用。
</div>
);
}
return (
<div
data-testid="process-modeler-eip4-panel"
style={{ overflow: 'auto', maxHeight: '55%', borderBottom: '1px solid var(--line)' }}
>
<div style={{ padding: '8px 12px', fontSize: 12, color: 'var(--text-3)', background: 'var(--surface-2, #fafafa)' }}>
EIP4 引擎以本控件为准,下方标准面板原生字段仅供高级调试。
</div>
<Section title="办理人">
<ItemsEditor idPrefix="eip4-candidate" items={candidateItems} onChange={writeCandidate} />
</Section>
<Section title="会签(多实例)">
<label style={{ display: 'flex', alignItems: 'center', gap: 6, fontSize: 13, marginBottom: 8 }}>
<input
type="checkbox"
data-testid="eip4-cosign-toggle"
checked={cosign.enabled}
onChange={(e) => writeCosign({ ...cosign, enabled: e.target.checked })}
/>
启用会签
</label>
{cosign.enabled ? (
<div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
<ItemsEditor
idPrefix="eip4-cosign"
items={cosign.items}
onChange={(items) => writeCosign({ ...cosign, items })}
/>
<div style={{ display: 'flex', alignItems: 'center', gap: 6, fontSize: 13 }}>
<span>完成条件</span>
<select
data-testid="eip4-cosign-completion-type"
value={cosign.completionType}
onChange={(e) =>
writeCosign({ ...cosign, completionType: e.target.value as CompletionType })
}
>
<option value="all">全票通过</option>
<option value="majority">过半通过</option>
<option value="count">指定数</option>
</select>
{cosign.completionType === 'count' ? (
<input
type="number"
min={1}
data-testid="eip4-cosign-completion-n"
value={cosign.completionN}
onChange={(e) =>
writeCosign({ ...cosign, completionN: Number(e.target.value) || 1 })
}
style={{ width: 64 }}
/>
) : null}
</div>
</div>
) : null}
</Section>
<Section title="表单(formKey)">
<select
data-testid="eip4-formkey-select"
value={formKey}
onChange={(e) => writeFormKey(e.target.value)}
style={{ width: '100%' }}
>
<option value="">(无)</option>
{/* 当前值不在模板列表时,补一条占位以免下拉丢值 */}
{formKey && !templates.some((t) => t.id === formKey) ? (
<option value={formKey}>{formKey}(当前)</option>
) : null}
{templates.map((t) => (
<option key={t.id} value={t.id}>
{t.name}
</option>
))}
</select>
</Section>
<Section title="扩展属性(activiti/flowable)">
<div style={{ display: 'flex', flexDirection: 'column', gap: 6 }}>
{extAttrs.map((a, i) => (
<div key={a.key} style={{ display: 'flex', gap: 4 }}>
<input
data-testid={`eip4-extattr-key-${i}`}
value={a.key}
readOnly
style={{ flex: '0 0 130px', minWidth: 0 }}
/>
<input
data-testid={`eip4-extattr-value-${i}`}
value={a.value}
onChange={(e) => editExtAttr(a.key, e.target.value)}
style={{ flex: 1, minWidth: 0 }}
/>
<button
className="btn btn-sm"
data-testid={`eip4-extattr-remove-${i}`}
onClick={() => removeExtAttr(a.key)}
>
删
</button>
</div>
))}
<div style={{ display: 'flex', gap: 4 }}>
<input
data-testid="eip4-extattr-new-key"
placeholder="activiti:key"
value={newAttr.key}
onChange={(e) => setNewAttr((s) => ({ ...s, key: e.target.value }))}
style={{ flex: '0 0 130px', minWidth: 0 }}
/>
<input
data-testid="eip4-extattr-new-value"
placeholder="value"
value={newAttr.value}
onChange={(e) => setNewAttr((s) => ({ ...s, value: e.target.value }))}
style={{ flex: 1, minWidth: 0 }}
/>
<button className="btn btn-sm" data-testid="eip4-extattr-add" onClick={addExtAttr}>
+ 增
</button>
</div>
</div>
</Section>
<Section title="任务监听器(taskListener)">
<div style={{ display: 'flex', flexDirection: 'column', gap: 6 }}>
{listeners.map((l, i) => (
<div
key={i}
style={{ border: '1px solid var(--line)', borderRadius: 4, padding: 6, display: 'flex', flexDirection: 'column', gap: 4 }}
>
<div style={{ display: 'flex', gap: 4, alignItems: 'center' }}>
<select
data-testid={`eip4-listener-event-${i}`}
value={l.event}
onChange={(e) => patchListener(i, { event: e.target.value })}
style={{ flex: '0 0 110px' }}
>
{LISTENER_EVENTS.map((ev) => (
<option key={ev} value={ev}>
{ev}
</option>
))}
</select>
<select
data-testid={`eip4-listener-mode-${i}`}
value={l.mode}
onChange={(e) =>
patchListener(i, { mode: e.target.value as ListenerRow['mode'] })
}
style={{ flex: '0 0 130px' }}
>
<option value="class">class</option>
<option value="delegateExpression">delegateExpression</option>
</select>
<button
className="btn btn-sm"
data-testid={`eip4-listener-remove-${i}`}
onClick={() => removeListener(i)}
>
删
</button>
</div>
<input
data-testid={`eip4-listener-value-${i}`}
value={l.value}
placeholder={l.mode === 'class' ? '全限定类名' : '${bean}'}
onChange={(e) => patchListener(i, { value: e.target.value })}
/>
{l.fields && l.fields.length ? (
<span style={{ fontSize: 11, color: 'var(--text-3)' }}>
含 field 配置({l.fields.length})· 编辑时原样保留
</span>
) : null}
</div>
))}
<button className="btn btn-sm" data-testid="eip4-listener-add" onClick={addListener}>
+ 添加监听器
</button>
</div>
</Section>
</div>
);
}
const hintStyle: React.CSSProperties = {
padding: 12,
color: 'var(--text-3)',
fontSize: 12,
borderBottom: '1px solid var(--line)',
};