@stalfh233/omc-cli 0.4.74 → 0.4.76

package/dist/form-support.js

@@ -4,7 +4,7 @@ import { decodeJsonObjectColumn } from "./json-column.js";
 import { ToolRefusalError } from "./tool-types.js";
 import { FIELD_CONTROL_TYPES, SYSTEM_FIELD_CODES, fieldControlOptions, relationDisplayField, relationMappings, } from "./field-families.js";
 import { deriveControlOptions } from "./capability-shape.js";
-import { validateFormLayoutShape } from "./form-layout.js";
+import { hardLayoutViolations, validateFormLayoutShape } from "./form-layout.js";
 /**
  * Propagate each relation field's `options.mappings` into its form control so
  * the form-fill carry is configured where the form renderer reads it. The
@@ -602,9 +602,7 @@ export function isEmptyLayoutJson(value) {
  * face (one-sided included), covering configure_form/apply_changes paths that
  * do not pass through the `form.draft` write permission gate.
  */
-export function assertCallerFormLayout(args) {
-    if (args.draftViewJson === undefined && args.draftAttributesJson === undefined)
-        return;
+export function formLayoutViolations(args) {
     const parse = (value) => {
         if (typeof value !== "string")
             return undefined;
@@ -615,7 +613,12 @@ export function assertCallerFormLayout(args) {
             return undefined;
         }
     };
-    const violations = validateFormLayoutShape(parse(args.draftViewJson), parse(args.draftAttributesJson));
+    return validateFormLayoutShape(parse(args.draftViewJson), parse(args.draftAttributesJson));
+}
+export function assertCallerFormLayout(args) {
+    if (args.draftViewJson === undefined && args.draftAttributesJson === undefined)
+        return;
+    const violations = hardLayoutViolations(formLayoutViolations(args));
     if (violations.length > 0) {
         throw new ToolRefusalError({
             status: "refused",
@@ -665,14 +668,177 @@ export function refuseEmptyCallerLayout(args) {
         message: `显式提供的 ${emptyFaces.join("、")} 是空布局（"[]"/"{}"）——平台设计器 Save 会把草稿清成该形态（非无损），照写会丢控件。若确要清空布局请显式传 allowEmptyLayout:true；若是设计器 Save 后的修复，先用表单版本历史（/api/api/app/bizsheet/history/list）取回完好版本原文再写回`,
     });
 }
+/**
+ * Form-toolbar buttons are a THREE-LAYER configuration (live 2026-10-23, 1.1.25
+ * + backend source):
+ *  1. `bizsheet.options.customButtonJson` (a STRINGIFIED JSON array) is the
+ *     authoring face — `ModelManagementFacadeImpl.publishBizForm:1022` turns it
+ *     into `h_biz_button` rows with `triggerType=FORM`, `triggerCode=<formCode>`
+ *     at publish time.
+ *  2. Those rows are what `ActionPermissionHandler` reads
+ *     (`getByTriggerTypeAndCode(FORM, bizCode)`).
+ *  3. Whether a button shows at a given node is filtered by the workflow
+ *     activity's `buttonPermission.customBtns[].enabled` (the designer's
+ *     「表单操作」 checkboxes) plus `showPermCode`.
+ *
+ * `customButtonJson` MUST stay a string inside the options JSON — passing the
+ * array inline makes the platform answer 50000 (fastjson
+ * "syntax error, position at 0, name customButtonJson").
+ */
+export const FORM_BUTTON_LOCATIONS = Object.freeze(["FORM", "ROW", "LIST"]);
+const FORM_BUTTON_BIND_ACTIONS = new Set([
+    "LIST",
+    "FORM",
+    "ADD_DATA",
+    "FLOW",
+    "BUSINESS_RULE",
+    "SCRIPT",
+    "CUSTOM_PAGE",
+    "WORKFLOW_CENTER_PAGE",
+    "FRONT_EVENT",
+    "AGENT",
+]);
+const FORM_BUTTON_OPERATE_TYPES = new Set(["WITH_VIEW", "WITH_OUT_VIEW"]);
+/** Validate the caller's form-button list before any wire (same shape as listview buttons, FORM location). */
+export function validateFormButtons(buttons, tool) {
+    if (!Array.isArray(buttons))
+        throw new ToolRefusalError({ status: "refused", blocker: "form-buttons-invalid", message: `${tool}: buttons 必须是数组（BizButtonModel 数组）` });
+    const seen = new Set();
+    return buttons.map((raw, index) => {
+        const button = (raw ?? {});
+        const code = typeof button.code === "string" ? button.code : "";
+        const name = typeof button.name === "string" ? button.name : "";
+        if (code === "")
+            throw new ToolRefusalError({ status: "refused", blocker: "form-buttons-invalid", message: `${tool}: buttons[${index}].code 必填（表单按钮的唯一标识，流程节点按它勾选）` });
+        if (name === "")
+            throw new ToolRefusalError({ status: "refused", blocker: "form-buttons-invalid", message: `${tool}: buttons[${index}].name 必填（设计器/表单页显示名）` });
+        if (seen.has(code))
+            throw new ToolRefusalError({ status: "refused", blocker: "form-buttons-duplicate", message: `${tool}: buttons 里 code ${code} 重复` });
+        seen.add(code);
+        const useLocation = typeof button.useLocation === "string" ? button.useLocation : "FORM";
+        if (!FORM_BUTTON_LOCATIONS.includes(useLocation))
+            throw new ToolRefusalError({ status: "refused", blocker: "form-buttons-invalid", message: `${tool}: buttons[${index}].useLocation 只能是 ${FORM_BUTTON_LOCATIONS.join("|")}（表单工具栏按钮用 FORM）` });
+        const bindAction = typeof button.bindAction === "string" ? button.bindAction : "";
+        if (!FORM_BUTTON_BIND_ACTIONS.has(bindAction))
+            throw new ToolRefusalError({ status: "refused", blocker: "form-buttons-invalid", message: `${tool}: buttons[${index}].bindAction 必须是 ButtonBindAction 名（SCRIPT/BUSINESS_RULE/FLOW/FORM/ADD_DATA/CUSTOM_PAGE/…）` });
+        const operateType = typeof button.operateType === "string" ? button.operateType : "";
+        if (!FORM_BUTTON_OPERATE_TYPES.has(operateType))
+            throw new ToolRefusalError({ status: "refused", blocker: "form-buttons-invalid", message: `${tool}: buttons[${index}].operateType 必须是 WITH_VIEW 或 WITH_OUT_VIEW` });
+        if (bindAction === "SCRIPT" || bindAction === "BUSINESS_RULE" || bindAction === "FLOW" || bindAction === "ADD_DATA" || bindAction === "FORM") {
+            const actionConfig = button.actionConfig;
+            const record = typeof actionConfig === "string" ? (() => { try {
+                return JSON.parse(actionConfig);
+            }
+            catch {
+                return undefined;
+            } })() : actionConfig;
+            const config = record && typeof record === "object" && !Array.isArray(record) ? record : undefined;
+            if (bindAction === "SCRIPT" && typeof config?.scriptData !== "string")
+                throw new ToolRefusalError({ status: "refused", blocker: "form-buttons-invalid", message: `${tool}: buttons[${index}] SCRIPT 需要 actionConfig.scriptData（前端脚本源码字符串）` });
+            if ((bindAction === "BUSINESS_RULE" || bindAction === "FLOW") && (typeof button.targetCode !== "string" || button.targetCode === ""))
+                throw new ToolRefusalError({ status: "refused", blocker: "form-buttons-invalid", message: `${tool}: buttons[${index}] ${bindAction} 需要 targetCode` });
+        }
+        return {
+            ...button,
+            code,
+            name,
+            useLocation,
+            bindAction,
+            operateType,
+            // The platform stores actionConfig as a string; a caller's object is
+            // serialized once here (double-encoding breaks the renderer).
+            ...(button.actionConfig !== undefined && typeof button.actionConfig !== "string" ? { actionConfig: JSON.stringify(button.actionConfig) } : {}),
+            sortKey: typeof button.sortKey === "number" ? button.sortKey : index,
+        };
+    });
+}
+function decodeOptionsColumn(value) {
+    if (value === null || value === undefined || value === "")
+        return {};
+    if (typeof value === "object" && !Array.isArray(value))
+        return { ...value };
+    if (typeof value === "string") {
+        try {
+            const parsed = JSON.parse(value);
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed))
+                return { ...parsed };
+        }
+        catch {
+            // A corrupt options column must not silently drop other options.
+        }
+    }
+    return {};
+}
+/**
+ * Merge the caller's form buttons into the sheet `options` column. Returns the
+ * options JSON string to POST (undefined = leave the column untouched).
+ */
+export function mergeFormOptionsWithButtons(existingOptions, input, tool) {
+    const hasButtons = input.buttons !== undefined;
+    const hasJson = input.customButtonJson !== undefined;
+    const removeCodes = input.removeButtonCodes ?? [];
+    if (hasButtons && hasJson)
+        throw new ToolRefusalError({ status: "refused", blocker: "form-buttons-ambiguous", message: `${tool}: buttons 与 customButtonJson 只能给一种（buttons 数组更好读；customButtonJson 用于原样透传读回值）` });
+    if (!hasButtons && !hasJson && removeCodes.length === 0)
+        return undefined;
+    let incoming = [];
+    if (hasButtons) {
+        incoming = validateFormButtons(input.buttons, tool);
+    }
+    else if (hasJson) {
+        const raw = String(input.customButtonJson);
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            throw new ToolRefusalError({ status: "refused", blocker: "form-buttons-invalid", message: `${tool}: customButtonJson 必须是 JSON 数组字符串` });
+        }
+        incoming = validateFormButtons(parsed, tool);
+    }
+    const options = decodeOptionsColumn(existingOptions);
+    // Default MERGE: an upsert by `code` so a caller can add or edit ONE button
+    // without re-sending the whole list (and without a read-modify-write race).
+    // `replace` restores the whole-list semantics.
+    const mode = input.buttonsMode ?? "merge";
+    const existing = readFormButtons(options) ?? [];
+    let final;
+    if (mode === "replace") {
+        final = incoming;
+    }
+    else {
+        const byCode = new Map(existing.map((button) => [String(button.code ?? ""), button]));
+        for (const button of incoming)
+            byCode.set(String(button.code), { ...(byCode.get(String(button.code)) ?? {}), ...button });
+        for (const code of removeCodes)
+            byCode.delete(String(code));
+        final = [...byCode.values()].map((button, index) => ({ ...button, sortKey: typeof button.sortKey === "number" ? button.sortKey : index }));
+    }
+    if (removeCodes.length > 0 && mode === "replace")
+        throw new ToolRefusalError({ status: "refused", blocker: "form-buttons-invalid", message: `${tool}: removeButtonCodes 只用于 buttonsMode:"merge"（replace 已用新列表整体替换）` });
+    options.customButtonJson = JSON.stringify(final);
+    return JSON.stringify(options);
+}
+/** The caller's buttons from a READ face (parsed array, or null when absent). */
+export function readFormButtons(options) {
+    const record = decodeOptionsColumn(options);
+    const raw = record.customButtonJson;
+    if (typeof raw !== "string" || raw === "")
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
 export async function executeFormDraftWrite(session, args) {
     if (args.draftHtmlJson !== undefined) {
         assertHtmlRender(args.draftHtmlJson, { schemaCode: args.schemaCode, sheetCode: args.sheetCode, face: "draftHtmlJson" });
     }
     // Caller-provided layouts get the distribution-grade shape gate (options
     // objects, string viewJson cells, no child keys as rows) before any wire.
-    if (args.draftViewJson !== undefined || args.draftAttributesJson !== undefined)
-        assertCallerFormLayout(args);
     // Ticket 74 — refuse CALLER-PROVIDED empty layouts before any wire call.
     // The platform designer's Save clears draft faces to "[]"/"{}" (non-lossless);
     // re-writing that shape explicitly is how the 13-control loss happened.
@@ -723,6 +889,42 @@ export async function executeFormDraftWrite(session, args) {
         if (pre === null)
             throw new WireError("business", `form ${args.sheetCode} was created but is not readable`, 302024);
     }
+    //
+    // 1.3 of issue 2026-10-23: the platform's OWN readback can carry shapes this
+    // gate rejects (`child_column_in_rows` when a published layout lists child
+    // columns as rows; `layout_row_overflow` on the auto system row). Refusing a
+    // byte-identical round-trip makes "read → write back" impossible, so a face
+    // that matches the sheet's own published/draft face is allowed through with
+    // the violations reported as warnings. Caller-authored layouts stay strict.
+    const roundTripFaces = new Set();
+    let layoutWarnings = [];
+    if (args.draftViewJson !== undefined || args.draftAttributesJson !== undefined) {
+        const pre2 = pre;
+        const same = (provided, stored) => typeof provided === "string" && typeof stored === "string" && provided.trim() === stored.trim();
+        const viewRoundTrip = same(args.draftViewJson, pre2?.publishedViewJson) || same(args.draftViewJson, pre2?.draftViewJson);
+        const attributesRoundTrip = same(args.draftAttributesJson, pre2?.publishedAttributesJson) || same(args.draftAttributesJson, pre2?.draftAttributesJson);
+        const allProvidedAreRoundTrip = (args.draftViewJson === undefined || viewRoundTrip) && (args.draftAttributesJson === undefined || attributesRoundTrip);
+        if (!allProvidedAreRoundTrip && args.fromReadback === true) {
+            throw new ToolRefusalError({
+                status: "refused",
+                blocker: "form-layout-invalid",
+                schemaCode: args.schemaCode,
+                sheetCode: args.sheetCode,
+                message: "fromReadback:true 但本次布局与已存草稿/发布面不一致——读过之后又改过就必须按普通写面校验（去掉 fromReadback，或按 validation 修正）",
+                validation: formLayoutViolations(args),
+            });
+        }
+        if (allProvidedAreRoundTrip) {
+            layoutWarnings = formLayoutViolations(args);
+            if (args.draftViewJson !== undefined)
+                roundTripFaces.add("draftViewJson");
+            if (args.draftAttributesJson !== undefined)
+                roundTripFaces.add("draftAttributesJson");
+        }
+        else {
+            assertCallerFormLayout(args);
+        }
+    }
     // Field-level relation mappings are the source of truth; read the published
     // fields so the scaffold (or an existing draft) can carry them into the
     // matching form control, where the form renderer reads them at fill time.
@@ -856,6 +1058,11 @@ export async function executeFormDraftWrite(session, args) {
         if (composed !== undefined)
             assertFormulasSurvivedRebuild(composed, previousAttributes, { schemaCode: args.schemaCode, sheetCode: args.sheetCode });
     }
+    // Form toolbar buttons live on `options.customButtonJson`; the publish step
+    // turns them into h_biz_button rows (triggerType=FORM). Merge rather than
+    // replace so unrelated options (presetButtonManage, sheetPresetButtonManage)
+    // survive.
+    const mergedOptions = mergeFormOptionsWithButtons(pre?.options, { buttons: args.buttons, customButtonJson: args.customButtonJson, buttonsMode: args.buttonsMode, removeButtonCodes: args.removeButtonCodes }, "form.draft");
     const payload = {
         ...(pre ?? {}),
         schemaCode: args.schemaCode,
@@ -863,6 +1070,7 @@ export async function executeFormDraftWrite(session, args) {
         name: pre?.name ?? args.sheetCode,
         sheetType: pre?.sheetType ?? 0,
         published: false,
+        ...(mergedOptions !== undefined ? { options: mergedOptions } : {}),
         // Draft writes are full-row updates, but they must not destroy the
         // currently published face. Publish promotion is a separate operation;
         // preserving these columns keeps the published form usable if the draft
@@ -878,7 +1086,123 @@ export async function executeFormDraftWrite(session, args) {
     const performed = await wireCall(session, { path: ENDPOINTS.sheetUpdate, method: "POST", body: payload });
     const readback = await wireCall(session, { path: ENDPOINTS.sheetGet, query: { schemaCode: args.schemaCode, sheetCode: args.sheetCode } });
     const sheet = (readback.data ?? {});
-    return { performed: { errcode: performed.errcode }, readback: { hasDraft: sheet.existDraft === true || typeof sheet.draftViewJson === "string", ...(args.rebuild === true && previousAttributes ? { rebuildPreservedControls } : {}) } };
+    const formButtons = readFormButtons(sheet.options);
+    return {
+        performed: { errcode: performed.errcode },
+        readback: {
+            hasDraft: sheet.existDraft === true || typeof sheet.draftViewJson === "string",
+            ...(formButtons !== null ? { formButtons, formButtonCodes: formButtons.map((button) => String(button.code ?? "")) } : {}),
+            ...(mergedOptions !== undefined ? { customButtonJsonWritten: true } : {}),
+            ...(roundTripFaces.size > 0
+                ? {
+                    layoutGate: "platform-roundtrip",
+                    layoutRoundTripFaces: [...roundTripFaces],
+                    layoutNote: "本次布局与平台读回的原样布局一致，形状告警只提示不拒绝（平台自身产出可能含子表列行/系统行超宽）",
+                    ...(layoutWarnings.length > 0 ? { layoutWarnings } : {}),
+                }
+                : {}),
+            ...(args.rebuild === true && previousAttributes ? { rebuildPreservedControls } : {}),
+        },
+    };
+}
+/** Schema-wide FORM buttons (code -> row) — the set a workflow node can tick. */
+export async function readSchemaFormButtons(session, schemaCode) {
+    const inventory = (await wireCall(session, { path: ENDPOINTS.systemGetCustomButtons, query: { schemaCode } })).data;
+    const triggers = Array.isArray(inventory?.formCustomButtons) ? inventory.formCustomButtons : [];
+    const byCode = {};
+    for (const trigger of triggers) {
+        const buttons = Array.isArray(trigger.buttonModels) ? trigger.buttonModels : [];
+        for (const button of buttons) {
+            const code = String(button.code ?? "");
+            if (code !== "" && byCode[code] === undefined)
+                byCode[code] = button;
+        }
+    }
+    return byCode;
+}
+/**
+ * Execute ONE form-toolbar button on ONE record — the exact request the portal
+ * posts when that button is clicked (live 2026-10-23, Playwright capture,
+ * AI-Platform 1.1.25):
+ *   POST /api/api/runtime/form/executeCustomButton
+ *   {bizButtonModel:<the h_biz_button row>, bizObjectList:[<full bizObject>],
+ *    reacquireDataFromDb:true}
+ * Distinct from the list-row button face (`launcher/domain_service_runtime`
+ * with `ids[]`): form buttons carry the whole record.
+ */
+export async function executeFormRunButtonWrite(session, args) {
+    const inventory = (await wireCall(session, { path: ENDPOINTS.systemGetCustomButtons, query: { schemaCode: args.schemaCode } })).data;
+    const triggers = Array.isArray(inventory?.formCustomButtons) ? inventory.formCustomButtons : [];
+    const trigger = triggers.find((row) => String(row.triggerCode ?? "") === args.sheetCode) ?? triggers[0];
+    const buttons = Array.isArray(trigger?.buttonModels) ? trigger.buttonModels : [];
+    if (buttons.length === 0)
+        throw new ToolRefusalError({
+            status: "refused",
+            blocker: "form-button-absent",
+            schemaCode: args.schemaCode,
+            sheetCode: args.sheetCode,
+            message: `表单 ${args.sheetCode} 没有自定义按钮（getCustomButtons 的 buttonModels 为空）——先用 form.publish 传 buttons（写 options.customButtonJson）生成 h_biz_button(triggerType=FORM)`,
+        });
+    const button = buttons.find((row) => String(row.code ?? "") === args.buttonCode);
+    if (!button)
+        throw new ToolRefusalError({
+            status: "refused",
+            blocker: "form-button-absent",
+            schemaCode: args.schemaCode,
+            sheetCode: args.sheetCode,
+            buttonCode: args.buttonCode,
+            available: buttons.map((row) => String(row.code ?? "")),
+            message: `表单 ${args.sheetCode} 没有按钮 ${args.buttonCode}；可用：${buttons.map((row) => String(row.code ?? "")).join("、")}`,
+        });
+    const loaded = (await wireCall(session, { path: ENDPOINTS.runtimeFormLoad, query: { schemaCode: args.schemaCode, sheetCode: args.sheetCode, objectId: args.bizObjectId, isMobile: "false" } })).data;
+    const bizObject = (loaded?.bizObject ?? null);
+    if (!bizObject)
+        throw new ToolRefusalError({
+            status: "refused",
+            blocker: "form-object-absent",
+            schemaCode: args.schemaCode,
+            bizObjectId: args.bizObjectId,
+            message: `读不到记录 ${args.bizObjectId} 的 bizObject（runtime/form/load 无 bizObject）——先 data.load 核对 bizObjectId`,
+        });
+    // The portal flattens the org/person fields to id strings before posting
+    // (form-detail's customButtonRule: `c.owner=(c.owner?.id)||""` etc.). Sending
+    // the loaded objects makes the platform answer 10009
+    // "Cannot deserialize value of type java.lang.String from Object value".
+    const idOf = (value) => {
+        if (typeof value === "string")
+            return value;
+        if (value && typeof value === "object" && !Array.isArray(value)) {
+            const id = value.id;
+            return typeof id === "string" ? id : "";
+        }
+        return "";
+    };
+    const submitted = { ...bizObject };
+    for (const key of ["owner", "creater", "modifier", "ownerDeptId", "createdDeptId"]) {
+        if (submitted[key] !== undefined)
+            submitted[key] = idOf(submitted[key]);
+    }
+    submitted.formMode = loaded?.formMode ?? "isRead";
+    submitted.activityCode = loaded?.activityCode ?? null;
+    const performed = await wireCall(session, {
+        path: ENDPOINTS.runtimeFormExecuteCustomButton,
+        method: "POST",
+        body: { bizButtonModel: button, bizObjectList: [submitted], reacquireDataFromDb: true },
+    });
+    return {
+        performed: { errcode: performed.errcode, buttonCode: args.buttonCode, bizObjectId: args.bizObjectId },
+        readback: {
+            schemaCode: args.schemaCode,
+            sheetCode: args.sheetCode,
+            buttonCode: args.buttonCode,
+            buttonName: String(button.name ?? ""),
+            bindAction: String(button.bindAction ?? ""),
+            targetCode: button.targetCode ?? null,
+            errmsg: performed.data?.errmsg ?? null,
+            ...(performed.errcode === 302045 ? { dataInUse: true, hint: "302045：数据被占用（有人正在编辑该行），稍后重试" } : {}),
+            effectHint: "平台只回执行结果；按钮绑定的规则副作用请另读 data.load。表单按钮走 executeCustomButton（带整条记录），与列表按钮的 launcher 路径不同",
+        },
+    };
 }
 /**
  * Shared form.publish write body — promotes the saved draft to published,
@@ -913,7 +1237,14 @@ export async function executeFormPublishWrite(session, args) {
         throw new WireError("business", `form ${args.sheetCode} not found`, 302024);
     if (pre.draftHtmlJson !== "[]")
         assertHtmlRender(pre.draftHtmlJson, { schemaCode: args.schemaCode, sheetCode: args.sheetCode, face: "draftHtmlJson" });
-    const forcePromote = args.force === true || args.rebuild === true;
+    // A button-only publish on an ALREADY published form must still promote: the
+    // platform materialises h_biz_button rows from options.customButtonJson during
+    // the publish call, so short-circuiting "already-published" would silently
+    // drop the buttons (live 2026-10-23).
+    const hasButtonDelta = args.buttons !== undefined ||
+        args.customButtonJson !== undefined ||
+        (Array.isArray(args.removeButtonCodes) && args.removeButtonCodes.length > 0);
+    const forcePromote = args.force === true || args.rebuild === true || hasButtonDelta;
     if (pre.published === true && !forcePromote)
         return { performed: { skipped: "already-published" }, readback: { published: true } };
     if (!hasDraft(pre))
@@ -939,8 +1270,14 @@ export async function executeFormPublishWrite(session, args) {
             });
         }
     }
+    // Buttons ride `options.customButtonJson`; the platform converts them into
+    // h_biz_button(triggerType=FORM) rows during THIS publish call
+    // (ModelManagementFacadeImpl.publishBizForm:1022). Passing them here is the
+    // only way to create form buttons without the designer.
+    const mergedOptions = mergeFormOptionsWithButtons(pre.options, { buttons: args.buttons, customButtonJson: args.customButtonJson, buttonsMode: args.buttonsMode, removeButtonCodes: args.removeButtonCodes }, "form.publish");
     const payload = {
         ...pre,
+        ...(mergedOptions !== undefined ? { options: mergedOptions } : {}),
         schemaCode: args.schemaCode,
         code: args.sheetCode,
         name: pre.name,
@@ -961,6 +1298,20 @@ export async function executeFormPublishWrite(session, args) {
     const performed = await wireCall(session, { path: ENDPOINTS.sheetPublish, method: "POST", body: payload });
     const readback = await wireCall(session, { path: ENDPOINTS.sheetGet, query: { schemaCode: args.schemaCode, sheetCode: args.sheetCode } });
     const sheet = (readback.data ?? {});
-    return { performed: { errcode: performed.errcode }, readback: { published: sheet.published === true, publishedHtmlJsonPresent: typeof sheet.publishedHtmlJson === "string" } };
+    const formButtons = readFormButtons(sheet.options);
+    return {
+        performed: { errcode: performed.errcode },
+        readback: {
+            published: sheet.published === true,
+            publishedHtmlJsonPresent: typeof sheet.publishedHtmlJson === "string",
+            ...(formButtons !== null
+                ? {
+                    formButtons,
+                    formButtonCodes: formButtons.map((button) => String(button.code ?? "")),
+                    formButtonNote: "按钮已写入 options.customButtonJson，本次 publish 已生成 h_biz_button(triggerType=FORM)；表单页是否显示还取决于流程节点 buttonPermission.customBtns[].enabled（设计器「表单操作」勾选）",
+                }
+                : {}),
+        },
+    };
 }
 //# sourceMappingURL=form-support.js.map

package/dist/human-summary.js

@@ -168,6 +168,10 @@ function phraseOf(tool, args, outcome) {
             return `发布流程 ${stringArg(args, "code") ?? "?"}（${schemaCode ?? "?"}）`;
         case "workflow.bindRule": {
             const codes = Array.isArray(args.ruleCodes) ? args.ruleCodes.join("、") : stringArg(args, "ruleCode") ?? "?";
+            const activityCode = stringArg(args, "activityCode");
+            const nodeEvent = stringArg(args, "nodeEvent");
+            if (activityCode !== undefined && nodeEvent !== undefined)
+                return `绑定流程节点事件规则：${stringArg(args, "workflowCode") ?? "?"} 的节点 ${activityCode}.${nodeEvent} ← ${codes}`;
             return `绑定流程事件规则：${stringArg(args, "workflowCode") ?? "?"} 的 ${stringArg(args, "handler") ?? "end"} 处理器 ← ${codes}`;
         }
         case "workflow.delete":

package/dist/lanes/businessrule.js

@@ -220,7 +220,14 @@ export function registerBusinessRuleLane(tools) {
                 schemaCode: record.schemaCode,
                 bizRuleType: record.bizRuleType,
                 enabled: record.enabled,
+                // The platform's `status` column lags behind the enable switch: r10
+                // saw `enabled:true` with `ruleStatus:"DISABLED"` while rule.list said
+                // ENABLED. `enabled` is the dispatch truth; flag the disagreement
+                // instead of letting two faces contradict each other silently.
                 ruleStatus: record.status,
+                ...(record.enabled === true && String(record.status ?? "") !== "ENABLED"
+                    ? { statusLag: true, statusNote: "平台 status 列滞后：enabled=true 才是分发真相（列表面/日志可复核）；不要据 ruleStatus=DISABLED 判定未启用" }
+                    : {}),
                 defaultRule: record.defaultRule,
                 developmentMode: record.developmentMode,
                 ruleVersion: record.ruleVersion,

package/dist/lanes/datarule.js

@@ -453,14 +453,37 @@ function childFormulaBareReferences(formula, childFieldCodes) {
  * field (→ platform 50000 on submit). Field-aware via the child schema's
  * published fields; a caller-provided set avoids a duplicate fieldList read.
  */
+/**
+ * 1.4 of issue 2026-10-23: `datarule.list` resolves a CHILD-table schema
+ * (bizdatarule/list answers rows) while `bizproperty/list?schemaCode=<child>`
+ * answers 601003 业务模型不存在 — the same schema code reads on one face and
+ * fails on the other. Do not let the field-metadata probe veto a write that the
+ * rule face itself accepts: return null (metadata unavailable) and let callers
+ * skip the field-level guards with a warning.
+ */
+async function readPublishedFieldCodesOrNull(session, schemaCode) {
+    try {
+        const rows = wireRows((await wireCall(session, { path: ENDPOINTS.fieldList, query: { schemaCode, isPublish: "true" } })).data);
+        return new Set(rows.map((row) => String(row.code ?? row.propertyCode ?? "")));
+    }
+    catch (error) {
+        if (error instanceof WireError && error.kind === "business" && (error.errcode === 601003 || error.errcode === 10011))
+            return null;
+        throw error;
+    }
+}
 async function assertChildFormulaRefs(session, args, knownChildFields) {
     if (args.dataRuleType !== 2 || args.childRule !== true)
         return;
     const formula = type2FormulaText(args.options);
     if (formula === null)
         return;
-    const codes = knownChildFields ??
-        new Set(wireRows((await wireCall(session, { path: ENDPOINTS.fieldList, query: { schemaCode: args.schemaCode, isPublish: "true" } })).data).map((row) => String(row.code ?? row.propertyCode ?? "")));
+    const codes = knownChildFields === undefined ? await readPublishedFieldCodesOrNull(session, args.schemaCode) : knownChildFields;
+    // Metadata unavailable (child-table schema on a face that only answers the
+    // rule side): the bare-reference heuristic needs the field list, so skip it
+    // rather than refusing a write the platform accepts.
+    if (codes === null)
+        return;
     const bare = childFormulaBareReferences(formula, codes);
     if (bare.length === 0)
         return;
@@ -658,8 +681,8 @@ export async function syncFormConditionDataRules(session, schemaCode, fieldCode,
     const existing = await listDataRules(session, schemaCode);
     // The designer's rule rows live on the PUBLISHED face (like datarule.create's
     // own guard); a draft-only field cannot carry a designer-visible row yet.
-    const published = wireRows((await wireCall(session, { path: ENDPOINTS.fieldList, query: { schemaCode, isPublish: "true" } })).data)
-        .some((row) => String(row.code ?? row.propertyCode ?? "") === fieldCode);
+    const publishedCodes = await readPublishedFieldCodesOrNull(session, schemaCode);
+    const published = publishedCodes === null ? true : publishedCodes.has(fieldCode);
     for (const key of changedKeys) {
         const dataRuleType = FORM_CONDITION_RULE_TYPES[key];
         const next = text(nextOptions, key);
@@ -726,12 +749,13 @@ export function registerDataRuleLane(tools) {
         assertDataRuleCheckType(args.dataRuleType, args.checkType);
         assertDataRuleTarget(args);
         const codes = dataRuleTargetCodes(args);
-        const fields = wireRows((await wireCall(session, { path: ENDPOINTS.fieldList, query: { schemaCode: args.schemaCode, isPublish: "true" } })).data);
-        const published = new Set(fields.map((row) => String(row.code ?? row.propertyCode ?? "")));
+        const published = await readPublishedFieldCodesOrNull(session, args.schemaCode);
         await assertChildFormulaRefs(session, args, published);
-        const missing = codes.filter((code) => !published.has(code));
-        if (missing.length > 0)
-            throw new ToolRefusalError({ status: "refused", blocker: "datarule-property-not-published", schemaCode: args.schemaCode, propertyCodes: codes, missing, message: `字段 ${args.schemaCode}.${missing.join(",")} 不在发布面上；拒绝 datarule.create POST` });
+        if (published !== null) {
+            const missing = codes.filter((code) => !published.has(code));
+            if (missing.length > 0)
+                throw new ToolRefusalError({ status: "refused", blocker: "datarule-property-not-published", schemaCode: args.schemaCode, propertyCodes: codes, missing, message: `字段 ${args.schemaCode}.${missing.join(",")} 不在发布面上；拒绝 datarule.create POST` });
+        }
         const existingRules = await listDataRules(session, args.schemaCode);
         // dataRuleType 1 (CHECK_RULE) fans out into 5 checkTypes that COEXIST on one
         // field (the platform auto-creates a checkType 4 maxLength row per text

package/dist/lanes/form-contract.js

@@ -15,11 +15,13 @@ export const FORM_WIRE = Object.freeze({
     publishAlreadyPublished: "published:true with force!==true skips as already-published",
     forceRepublish: "onlinejs.compose passes force:true so it can re-promote after a prior publish",
     emptyLayoutGuard: "ticket 74: the platform designer's Save is NOT lossless — it clears draftViewJson to \"[]\" and draftAttributesJson to \"{}\"; form.draft refuses CALLER-PROVIDED empty layouts (blocker form-empty-layout, zero wire, escape allowEmptyLayout:true) and form.publish refuses to promote a draft with fewer controls than the published face (blocker form-publish-degrade, escape allowDegrade:true); the recovery path is the form version history (/api/api/app/bizsheet/history/list) — fetch the intact version's view/attributes originals and rewrite the draft before publishing",
+    formButtons: "form toolbar buttons are a three-layer configuration (live 2026-10-23, 1.1.25): (1) bizsheet.options.customButtonJson — a STRINGIFIED JSON array — is the authoring face; ModelManagementFacadeImpl.publishBizForm:1022 turns it into h_biz_button rows with triggerType=FORM, triggerCode=<formCode> at publish; (2) those rows are what ActionPermissionHandler.getByTriggerTypeAndCode(FORM, bizCode) reads; (3) whether a button shows at a node is filtered by the workflow activity's buttonPermission.customBtns[].enabled (the designer 表单操作 checkboxes) plus showPermCode; the execute face is POST /api/api/runtime/form/executeCustomButton {bizButtonModel, bizObjectList:[<full bizObject>], reacquireDataFromDb:true} — NOT the list-button launcher path with ids[]",
     actionsColumns: "ticket 100: draftActionsJson/publishedActionsJson are REAL bizsheet columns (BizForm.java:95-100 @SerializableField; BizFormModel.java:59-62 serialized by bizsheet/get) — the designer writes draftActionsJson on save and both faces on publish (frontend-dist/admin/js/4280.cfa75764.js offsets 193538/185347); form.get full:true surfaces them; publish promotes draftActionsJson → publishedActionsJson",
 });
-const FORM_GET_DESCRIPTION = '读取默认表单（bizsheet/get）的发布状态与控件清单（紧凑默认）。**发布态以返回的 `published` / `existDraft` 布尔为准**（`published:true`=已发布；`published:false,existDraft:true`=只有草稿，**未发布**）——不要用 `publishedControlCodes` 是否非空来推断（草稿字段会让它非空，误判为已发布）。**每个模型交付前其默认表单必须 `published:true`**：用 `configure_form` 或 `form.draft(rebuild:true)`+`form.publish` 发布，并逐模型 `form.get` 核对。传 `controls:["code",…]` 只取指定控件的 options（如关联控件的 mappings）；传 `full:true` 才返回 draft/published 的完整 view/attributes/html/actions JSON（actions 列为设计器保存/发布的表单级按钮动作）。体积大，仅在需要整体布局时用。';
-const FORM_DRAFT_DESCRIPTION = "Save the default-form DRAFT (bizsheet/update). Reads the current sheet, merges the caller's explicit draftViewJson/draftAttributesJson (or preserves the existing draft); when both are absent on a fresh default form, composes the designer-standard scaffold from the model's published fields. A redundant field (relation-mapping carry-through target) always stays bound; with no workflow it is hidden in the design (options.visible=false), with a workflow it stays visible for per-node propertyPermissions. Pass `draftHtmlJson` to thread custom online-script HTML through. Empty-layout guard: explicitly passing \"[]\"/\"{}\" view/attributes is refused (form-empty-layout) — the platform designer's Save is NOT lossless and clears drafts to exactly that shape; escape with allowEmptyLayout:true, and recover cleared drafts from the form version history (/api/api/app/bizsheet/history/list). **表单控件属性（含关联填充 mappings）从字段行派生**：改关联映射的事实源在字段 options.mappings（field.update → field.publish），直接改这里的控件映射会被平台按字段重算覆盖（真机 2026-10-14 实证）；字段发布后如需刷新已发布表单的控件映射，用本工具 rebuild:false 重存（保留现有布局与在线JS）再 form.publish。";
-const FORM_PUBLISH_DESCRIPTION = "Publish the default form (bizsheet/publish, proven shape: draft*Json promoted to published*Json verbatim) with published-face readback. Degrade guard: refuses to promote a draft carrying FEWER controls than the published face (form-publish-degrade) — the designer's Save clears drafts non-losslessly; recover via the form version history (/api/api/app/bizsheet/history/list) and rewrite the draft first, or pass allowDegrade:true to force the reduction. rebuild:true is the one-call refresh: discard the existing draft, re-scaffold from the published fields (non-structural control options preserved), then force-promote — use it after a field shape change.";
+const FORM_GET_DESCRIPTION = '读取默认表单（bizsheet/get）的发布状态与控件清单（紧凑默认）。**发布态以返回的 `published` / `existDraft` 布尔为准**（`published:true`=已发布；`published:false,existDraft:true`=只有草稿，**未发布**）——不要用 `publishedControlCodes` 是否非空来推断（草稿字段会让它非空，误判为已发布）。**每个模型交付前其默认表单必须 `published:true`**：用 `configure_form` 或 `form.draft(rebuild:true)`+`form.publish` 发布，并逐模型 `form.get` 核对。`full:true` 还返回 `options` 与解析后的 `customButtonJson`（表单工具栏按钮）。传 `controls:["code",…]` 只取指定控件的 options（如关联控件的 mappings）；传 `full:true` 才返回 draft/published 的完整 view/attributes/html/actions JSON（actions 列为设计器保存/发布的表单级按钮动作）。体积大，仅在需要整体布局时用。';
+const FORM_DRAFT_DESCRIPTION = "Save the default-form DRAFT (bizsheet/update). Reads the current sheet, merges the caller's explicit draftViewJson/draftAttributesJson (or preserves the existing draft); when both are absent on a fresh default form, composes the designer-standard scaffold from the model's published fields. A redundant field (relation-mapping carry-through target) always stays bound; with no workflow it is hidden in the design (options.visible=false), with a workflow it stays visible for per-node propertyPermissions. Pass `draftHtmlJson` to thread custom online-script HTML through. Empty-layout guard: explicitly passing \"[]\"/\"{}\" view/attributes is refused (form-empty-layout) — the platform designer's Save is NOT lossless and clears drafts to exactly that shape; escape with allowEmptyLayout:true, and recover cleared drafts from the form version history (/api/api/app/bizsheet/history/list). **读回原样回写**：从 `form.get` 取回的 view/attributes 直接回传时加 `fromReadback:true`——工具会与已存草稿/发布面逐字比对，一致才放行（平台自身布局可能含子表列行/系统行默认宽度），被改动过的面照常按 validation 拒绝。**表单工具栏按钮**：`buttons`（数组）或 `customButtonJson`（原样字符串）写进 `biz_sheet.options.customButtonJson`；**要到 form.publish 才生成 h_biz_button(triggerType=FORM)**，且表单页是否显示还取决于流程节点 `buttonPermission.customBtns[].enabled`（设计器「表单操作」勾选）。`useLocation` 用 FORM/ROW/LIST，表单工具栏按钮用 FORM。 **表单控件属性（含关联填充 mappings）从字段行派生**：改关联映射的事实源在字段 options.mappings（field.update → field.publish），直接改这里的控件映射会被平台按字段重算覆盖（真机 2026-10-14 实证）；字段发布后如需刷新已发布表单的控件映射，用本工具 rebuild:false 重存（保留现有布局与在线JS）再 form.publish。";
+const FORM_PUBLISH_DESCRIPTION = "Publish the default form (bizsheet/publish, proven shape: draft*Json promoted to published*Json verbatim) with published-face readback. Degrade guard: refuses to promote a draft carrying FEWER controls than the published face (form-publish-degrade) — the designer's Save clears drafts non-losslessly; recover via the form version history (/api/api/app/bizsheet/history/list) and rewrite the draft first, or pass allowDegrade:true to force the reduction. rebuild:true is the one-call refresh: discard the existing draft, re-scaffold from the published fields (non-structural control options preserved), then force-promote — use it after a field shape change. **表单工具栏按钮**：传 `buttons`（或 `customButtonJson`）→ 写进 `options.customButtonJson` 并在本次 publish 生成 `h_biz_button(triggerType=FORM, triggerCode=<formCode>)`（平台 `publishBizForm:1022`）；`options.customButtonJson` 必须是**字符串化数组**（对象会 50000 syntax error）；表单页是否显示再由流程节点 `buttonPermission.customBtns[].enabled` 过滤。";
+const FORM_RUN_BUTTON_DESCRIPTION = "执行表单工具栏按钮（平台同款面：`POST /api/api/runtime/form/executeCustomButton`，body `{bizButtonModel, bizObjectList:[<完整业务对象>], reacquireDataFromDb:true}`）。**与列表行按钮不同**：列表按钮发 `launcher/domain_service_runtime/<schema>/<rule>` + `ids[]`（用 `rule.run`），表单按钮带**整条记录**，不能互换。按钮来源 `GET /api/api/system/getCustomButtons`（只列 triggerType=FORM 的 h_biz_button）。前提：按钮已由 `form.publish` 的 `buttons`/`customButtonJson` 生成。返回是执行结果信封，规则副作用用 `data.load` 另读；被规则 UPDATE 的目标行须是 COMPLETED（引擎查不到 DRAFT）。`302045` = 数据被占用。";
 const CONFIGURE_FORM_DESCRIPTION = "High-level: bind fields into the default form and publish it (form.draft → form.publish), subject to the write permission gate. Delegates to the proven form.draft scaffold + form.publish paths so the real empty-form layout (and any caller-supplied draftHtmlJson) is persisted and promoted — never bypasses with a shortcut body. `sheetCode` is optional: omitted means the model's default sheet (sheetCode = schemaCode).";
 export const FORM_LANE_CONTRACT = Object.freeze({
     lane: LANES.form,
@@ -42,6 +44,7 @@ export const FORM_LANE_CONTRACT = Object.freeze({
         forceRepublish: FORM_WIRE.forceRepublish,
         emptyLayoutGuard: FORM_WIRE.emptyLayoutGuard,
         actionsColumns: FORM_WIRE.actionsColumns,
+        formButtons: FORM_WIRE.formButtons,
     }),
     wireBindings: Object.freeze({
         draftBody: Object.freeze([behaviorBinding("test/form-scaffold.test.ts#form.draft scaffolds an empty default form from published fields", assertFormContract)]),
@@ -54,6 +57,7 @@ export const FORM_LANE_CONTRACT = Object.freeze({
         forceRepublish: Object.freeze([behaviorBinding("test/issue-11-online-js.test.ts#onlinejs.compose merges customScript into the existing draftHtmlJson layout", assertFormContract)]),
         emptyLayoutGuard: Object.freeze([behaviorBinding("test/ticket-74-form-empty-layout.test.ts#ticket 74: form.draft refuses an explicitly empty draftViewJson", assertFormContract)]),
         actionsColumns: Object.freeze([behaviorBinding("test/ticket-100-form-actions-columns.test.ts#form.get full:true surfaces draftActionsJson/publishedActionsJson", assertFormContract)]),
+        formButtons: Object.freeze([behaviorBinding("test/form-buttons.test.ts#form.publish with buttons materialises FORM-trigger buttons and form.get surfaces them", assertFormContract)]),
     }),
     evidence: Object.freeze([
         ".scratch/omc-route-wayfinder/leg2-closeout.md",
@@ -65,6 +69,7 @@ export const FORM_LANE_CONTRACT = Object.freeze({
         "form.draft": Object.freeze({ scope: "draft publish publishedHtmlJson readback", description: FORM_DRAFT_DESCRIPTION }),
         "form.publish": Object.freeze({ scope: "draft publish publishedHtmlJson readback", description: FORM_PUBLISH_DESCRIPTION }),
         configure_form: Object.freeze({ scope: "draft publish publishedHtmlJson readback", description: CONFIGURE_FORM_DESCRIPTION }),
+        "form.runButton": Object.freeze({ scope: "form toolbar button execution", description: FORM_RUN_BUTTON_DESCRIPTION }),
     }),
 });
 export function assertFormContract() {
@@ -74,7 +79,7 @@ export function assertFormContract() {
     assertDescriptionCarries(FORM_LANE_CONTRACT, "form.get", ["bizsheet/get", "draft/published", "mappings", "`full:true`", "actions"]);
     if (!FORM_WIRE.actionsColumns.includes("BizForm.java:95-100"))
         throw new Error("form contract must pin the actions-columns evidence (ticket 100)");
-    assertDescriptionCarries(FORM_LANE_CONTRACT, "form.draft", ["bizsheet/update", "draftViewJson", "draftAttributesJson", "scaffold", "draftHtmlJson", "form-empty-layout"]);
+    assertDescriptionCarries(FORM_LANE_CONTRACT, "form.draft", ["bizsheet/update", "draftViewJson", "draftAttributesJson", "scaffold", "draftHtmlJson", "form-empty-layout", "fromReadback"]);
     if (!FORM_WIRE.redundantFieldVisibility.includes("propertyPermissions"))
         throw new Error("form contract must carry the redundant-field visibility (propertyPermissions) fact");
     assertDescriptionCarries(FORM_LANE_CONTRACT, "form.publish", ["bizsheet/publish", "draft*Json", "published*Json", "verbatim", "form-publish-degrade", "history/list", "rebuild:true", "force-promote"]);
@@ -93,5 +98,10 @@ export function assertFormContract() {
         throw new Error("form contract must pin the force-republish override");
     if (!FORM_WIRE.emptyLayoutGuard.includes("form-empty-layout") || !FORM_WIRE.emptyLayoutGuard.includes("form-publish-degrade"))
         throw new Error("form contract must pin the empty-layout/degrade guards");
+    if (!FORM_WIRE.formButtons.includes("customButtonJson") || !FORM_WIRE.formButtons.includes("executeCustomButton") || !FORM_WIRE.formButtons.includes("publishBizForm:1022"))
+        throw new Error("form contract must pin the form-button three-layer mechanism");
+    assertDescriptionCarries(FORM_LANE_CONTRACT, "form.draft", ["buttons", "customButtonJson", "h_biz_button", "buttonPermission"]);
+    assertDescriptionCarries(FORM_LANE_CONTRACT, "form.publish", ["buttons", "customButtonJson", "triggerType=FORM", "buttonPermission"]);
+    assertDescriptionCarries(FORM_LANE_CONTRACT, "form.runButton", ["executeCustomButton", "bizObjectList", "getCustomButtons", "rule.run", "302045"]);
 }
 //# sourceMappingURL=form-contract.js.map