@stalfh233/omc-cli 0.6.11 → 0.6.13

package/dist/lanes/field.js

@@ -1,18 +1,19 @@
 import { z } from "zod";
 import { ENDPOINTS } from "../endpoints.js";
 import { fieldChangeWireBody, fieldUpdateWireBody, prepareFieldChange, prepareFieldUpdate } from "../field-change.js";
-import { aggregationSelfSchemaMessage, aggregationTargetsOwnSchema, choicesArg, FIELD_PROPERTY_TYPES, fieldOptionsArg, fieldTypeLabel, numericalScaleWarning, propertyTypeArg, relativeCodeArg, stripAggregationPrefix, subFieldArg, SYSTEM_FIELD_CODES, } from "../field-families.js";
+import { aggregationSelfSchemaMessage, aggregationTargetsOwnSchema, choicesArg, childColumnsOf, FIELD_PROPERTY_TYPES, fieldOptionsArg, fieldTypeLabel, numericalScaleWarning, propertyTypeArg, relativeCodeArg, stripAggregationPrefix, subFieldArg, SYSTEM_FIELD_CODES, } from "../field-families.js";
 import { capabilityArg, environmentArg } from "../args.js";
 import { governedRead } from "../read.js";
 import { writeTool } from "../write.js";
-import { decodeJsonColumn, decodeJsonObjectColumn, JSON_COLUMN_PASSTHROUGH } from "../json-column.js";
+import { decodeJsonColumn, decodeJsonObjectColumn, JSON_COLUMN_NULL_COALESCE, JSON_COLUMN_PASSTHROUGH } from "../json-column.js";
 import { syncFormConditionDataRules } from "./datarule.js";
 import { FORM_CONDITION_OPTION_KEYS } from "./datarule-protocol.js";
 import { defineTool, ToolRefusalError } from "../tool-types.js";
 import { wireCall, wireRows, WireError } from "../wire.js";
-import { executeFormDraftWrite, executeFormPublishWrite } from "../form-support.js";
+import { executeFormDraftWrite, executeFormPublishWrite, readFormOrNull } from "../form-support.js";
 import { FIELD_LANE_CONTRACT } from "./field-contract.js";
 import { mapBounded } from "../support.js";
+import { extractBizObjectPage } from "./runtime-data.js";
 const FIELD_LANE = FIELD_LANE_CONTRACT.lane;
 const FIELD_TOOLS = FIELD_LANE_CONTRACT.tools;
 async function readFieldRollback(session, args) {
@@ -45,54 +46,6 @@ function fieldRollbackSpec(toolName) {
 function parseFieldOptionsForReadback(options) {
     return decodeJsonColumn(options, JSON_COLUMN_PASSTHROUGH);
 }
-/**
- * CHILD_TABLE(8) columns as a compact list (issue 2026-10-25 §7).
- *
- * The stored `subSchema` is the full designer payload — system columns included,
- * ~37.6 KB for a 10-column child table when asked for one field by code. A caller
- * almost always wants the column codes (to build formData / verify the attach);
- * the raw payload stays available behind `full:true`. Accepts both the object and
- * the JSON-string wire form.
- */
-function childColumnsOf(subSchema) {
-    let parsed = subSchema;
-    if (typeof subSchema === "string") {
-        try {
-            parsed = JSON.parse(subSchema);
-        }
-        catch {
-            return [];
-        }
-    }
-    if (parsed === null || typeof parsed !== "object")
-        return [];
-    const properties = parsed.properties;
-    if (!Array.isArray(properties))
-        return [];
-    return properties
-        .filter((child) => child !== null && typeof child === "object")
-        .map((child) => {
-        const rawType = child.propertyType ?? child.type;
-        const type = rawType === undefined || rawType === null || Number.isNaN(Number(rawType)) ? null : Number(rawType);
-        const typeLabel = type === null ? undefined : fieldTypeLabel(type);
-        const code = String(child.code ?? child.propertyCode ?? "");
-        return {
-            code,
-            name: String(child.name ?? child.code ?? child.propertyCode ?? ""),
-            type,
-            ...(typeLabel !== undefined ? { typeName: typeLabel } : {}),
-            ...(typeof child.relativeCode === "string" && child.relativeCode ? { relativeCode: child.relativeCode } : {}),
-            // r15 feedback: the projection mixed the platform's system columns with
-            // the authored ones, so "which child columns did I declare?" still needed
-            // a filter. Keep every column but mark the system ones.
-            // `parentId` / `sortKey` are injected by the platform into every child
-            // schema (they are the child row's link + order), so they are system
-            // columns here even though a MAIN model never carries them.
-            ...(SYSTEM_FIELD_CODES.has(code) || code === "parentId" || code === "sortKey" ? { system: true } : {}),
-        };
-    })
-        .filter((child) => child.code.length > 0);
-}
 /**
  * `name_i18n` is a JSON locale map. When every locale value equals the display
  * `name` there is no translation to convey, so echoing the map on every field of
@@ -474,6 +427,7 @@ export function registerFieldLane(tools) {
             return {
                 performed: { errcode: performed.errcode },
                 readback: {
+                    face: "draft",
                     draftFieldPresent: rows.some((row) => (row.code ?? row.propertyCode) === args.code),
                     ...(textLike
                         ? {
@@ -501,6 +455,10 @@ export function registerFieldLane(tools) {
             relativeCode: relativeCodeArg,
             subFields: subFieldArg,
             propertyEmpty: z.boolean().optional().describe("覆盖数据模型层的不可为空声明；传 false 可把历史误建的字段改回可为空（必填/只读应在表单与流程节点配置）"),
+            syncDictionary: z
+                .boolean()
+                .optional()
+                .describe("true 且字段是字典-backed：服务端重读 dictionary 启用记录并重填 options.optionsSet.dictionary.useDictionariesData（字典改动不会被动传播到字段快照）"),
             cascadeRepublish: z
                 .boolean()
                 .optional()
@@ -513,6 +471,7 @@ export function registerFieldLane(tools) {
             return runFieldUpdateCascade(session, args, outcome);
         },
         preflight: (args) => assertNameI18nArg(args.name_i18n),
+        dryRunPayload: fieldUpdateDryRun,
         rollback: fieldRollbackSpec("field.update"),
     });
     writeTool({
@@ -536,6 +495,9 @@ export function registerFieldLane(tools) {
         description: FIELD_TOOLS["field.delete"].description,
         inputSchema: { schemaCode: z.string().min(1), code: z.string().min(1) },
         execute: async (session, args) => {
+            // 真写回执只给摘要（省查询成本）；全量引用/行数扫描留给 --dry-run。
+            // impact 放进 readback：governedWrite 只透传 performed/readback/steps。
+            const impact = await collectFieldDeleteImpact(session, args, { full: false });
             const performed = await wireCall(session, {
                 path: ENDPOINTS.fieldForceDelete,
                 method: "POST",
@@ -544,11 +506,452 @@ export function registerFieldLane(tools) {
             const draft = await wireCall(session, { path: ENDPOINTS.fieldList, query: { schemaCode: args.schemaCode, isPublish: "false" } });
             const published = await wireCall(session, { path: ENDPOINTS.fieldList, query: { schemaCode: args.schemaCode, isPublish: "true" } });
             const gone = (value) => !wireRows(value).some((row) => (row.code ?? row.propertyCode) === args.code);
-            return { performed: { errcode: performed.errcode }, readback: { absentDraft: gone(draft.data), absentPublished: gone(published.data) } };
+            return {
+                performed: { errcode: performed.errcode },
+                readback: { absentDraft: gone(draft.data), absentPublished: gone(published.data), impact },
+            };
+        },
+        dryRunPayload: async (session, args) => {
+            const impact = await collectFieldDeleteImpact(session, args, { full: true });
+            return { wouldChange: true, impact, schemaCode: args.schemaCode, code: args.code };
         },
         rollback: fieldRollbackSpec("field.delete"),
     });
 }
+/** Normalize options JSON (string or object) into a plain object for comparison/merge. */
+function optionsObjectOf(raw) {
+    if (raw === null || raw === undefined)
+        return {};
+    if (typeof raw === "string") {
+        const trimmed = raw.trim();
+        if (!trimmed)
+            return {};
+        try {
+            const parsed = JSON.parse(trimmed);
+            return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+        }
+        catch {
+            return {};
+        }
+    }
+    if (typeof raw === "object" && !Array.isArray(raw))
+        return raw;
+    return {};
+}
+/** Stable fingerprint for draft↔published options equality (r29e F10/F11). */
+function optionsFingerprint(raw) {
+    const options = optionsObjectOf(raw);
+    // 去掉平台自动垫的空值键（如 dictionaryData:""），避免 SHORT_TEXT 因
+    // `{dictionaryData:""}` vs `{}` 假差异而拒绝 already-published 短路（ticket 81）。
+    // 字典/关联真正有内容的键仍参与比对。
+    const meaningful = {};
+    for (const [key, value] of Object.entries(options)) {
+        if (value === "" || value === null || value === undefined)
+            continue;
+        if (Array.isArray(value) && value.length === 0)
+            continue;
+        if (typeof value === "object" && !Array.isArray(value) && Object.keys(value).length === 0)
+            continue;
+        meaningful[key] = value;
+    }
+    if (Object.keys(meaningful).length === 0)
+        return "";
+    try {
+        return JSON.stringify(meaningful);
+    }
+    catch {
+        return String(raw ?? "");
+    }
+}
+function dictionaryBindingOf(options) {
+    const optionsSet = options.optionsSet;
+    if (!optionsSet || optionsSet.optionsType !== "dictionary")
+        return undefined;
+    const dictionary = (optionsSet.dictionary ?? {});
+    const use = Array.isArray(dictionary.useDictionariesData)
+        ? dictionary.useDictionariesData.map((row) => ({
+            code: String(row.code ?? ""),
+            ...(row.name !== undefined ? { name: String(row.name) } : {}),
+            ...(row.id !== undefined ? { id: String(row.id) } : {}),
+        }))
+        : [];
+    return {
+        ...(typeof dictionary.checkedDictionary === "string" ? { checkedDictionary: dictionary.checkedDictionary } : {}),
+        ...(typeof dictionary.checkedDictionaryCode === "string" ? { checkedDictionaryCode: dictionary.checkedDictionaryCode } : {}),
+        useDictionariesData: use,
+    };
+}
+async function loadEnabledDictionaryRecords(session, binding) {
+    const dicId = binding.checkedDictionary;
+    const code = binding.checkedDictionaryCode;
+    let id = dicId ?? "";
+    if (!id && code) {
+        const header = (await wireCall(session, { path: ENDPOINTS.dictionaryGetByCode, query: { code } })).data;
+        id = String(header?.id ?? "");
+    }
+    if (!id)
+        return [];
+    const data = await wireCall(session, { path: ENDPOINTS.dictionaryEnabledRecords, query: { dicId: id } });
+    const rows = Array.isArray(data.data) ? data.data : [];
+    return rows
+        .map((row) => ({ id: String(row.id ?? ""), code: String(row.code ?? ""), name: String(row.name ?? row.code ?? "") }))
+        .filter((row) => row.code.length > 0)
+        .sort((left, right) => left.code.localeCompare(right.code));
+}
+/** Keys that change the stored data shape (not just display labels). */
+const DATA_SHAPE_OPTION_KEYS = new Set(["scale", "propertyType", "propertyEmpty", "choices"]);
+function fieldValuesEqual(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+function choiceCodesOf(options) {
+    const set = options.optionsSet;
+    if (!set || typeof set !== "object" || Array.isArray(set))
+        return undefined;
+    const custom = set.custom;
+    if (!Array.isArray(custom))
+        return undefined;
+    return custom
+        .map((entry) => {
+        if (!entry || typeof entry !== "object" || Array.isArray(entry))
+            return "";
+        return String(entry.code ?? entry.value ?? "");
+    })
+        .filter((code) => code.length > 0);
+}
+async function loadFieldRowForUpdate(session, schemaCode, code) {
+    const listed = await wireCall(session, { path: ENDPOINTS.fieldList, query: { schemaCode, isPublish: "false" } });
+    let rows = wireRows(listed.data);
+    if (!rows.some((row) => (row.code ?? row.propertyCode) === code)) {
+        const published = await wireCall(session, { path: ENDPOINTS.fieldList, query: { schemaCode, isPublish: "true" } });
+        rows = wireRows(published.data);
+    }
+    const record = rows.find((row) => (row.code ?? row.propertyCode) === code);
+    if (!record)
+        throw new WireError("business", `field ${code} not found on ${schemaCode}`, 301001);
+    return record;
+}
+async function countModelDataRows(session, schemaCode) {
+    try {
+        const result = await wireCall(session, {
+            path: ENDPOINTS.runtimeQueryList,
+            method: "POST",
+            body: { schemaCode, queryCode: schemaCode, filters: [], mobile: false, page: 0, size: 1, queryVersion: 1, showTotal: true },
+        });
+        return { dataRows: extractBizObjectPage(result.data).total };
+    }
+    catch (error) {
+        return {
+            dataRows: "unknown",
+            note: `拿不到行数：${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+/**
+ * Session-aware dry-run for field.update: structured from→to changes (only real
+ * diffs), plus an honest dataImpact note when storage-shape keys move.
+ */
+async function fieldUpdateDryRun(session, args) {
+    const record = await loadFieldRowForUpdate(session, args.schemaCode, args.code);
+    if (args.options !== undefined) {
+        const publishedRows = await wireCall(session, { path: ENDPOINTS.fieldList, query: { schemaCode: args.schemaCode, isPublish: "true" } })
+            .then((response) => wireRows(response.data))
+            .catch(() => []);
+        assertNoSelfSchemaAggregation({ schemaCode: args.schemaCode, propertyType: record.type ?? record.propertyType, options: args.options }, publishedRows);
+        await assertNoChildSchemaAggregation(session, args.schemaCode, record.type ?? record.propertyType, args.options);
+    }
+    const targetVersion = session.detectedVersion();
+    const update = {
+        schemaCode: args.schemaCode,
+        code: args.code,
+        base: record,
+        ...(targetVersion ? { targetVersion } : {}),
+        ...(args.name !== undefined ? { name: args.name } : {}),
+        ...(args.name_i18n !== undefined ? { name_i18n: args.name_i18n } : {}),
+        ...(args.options !== undefined ? { options: args.options } : {}),
+        ...(args.choices !== undefined ? { choices: args.choices } : {}),
+        ...(args.relativeCode !== undefined ? { relativeCode: args.relativeCode } : {}),
+        ...(args.subFields !== undefined ? { subFields: args.subFields } : {}),
+        ...(args.propertyEmpty !== undefined ? { propertyEmpty: args.propertyEmpty } : {}),
+    };
+    const prepared = prepareFieldUpdate(update);
+    const currentOptions = decodeJsonObjectColumn(record.options, { invalid: "throw", array: "accept", object: "accept" }) ?? {};
+    const changes = [];
+    const pushChange = (field, from, to) => {
+        if (fieldValuesEqual(from, to))
+            return;
+        changes.push({ field, from, to });
+    };
+    if (args.name !== undefined)
+        pushChange("name", record.name ?? null, prepared.name ?? args.name);
+    if (args.name_i18n !== undefined) {
+        const fromI18n = typeof record.name_i18n === "string" ? record.name_i18n : record.name_i18n ?? null;
+        pushChange("name_i18n", fromI18n, prepared.nameI18n ?? args.name_i18n);
+    }
+    if (args.propertyEmpty !== undefined)
+        pushChange("propertyEmpty", record.propertyEmpty ?? null, args.propertyEmpty);
+    if (args.relativeCode !== undefined)
+        pushChange("relativeCode", record.relativeCode ?? null, args.relativeCode);
+    if (args.options !== undefined || args.choices !== undefined) {
+        const optionKeys = new Set([...Object.keys(currentOptions), ...Object.keys(prepared.options)]);
+        for (const key of [...optionKeys].sort()) {
+            if (key === "optionsSet" && args.choices !== undefined)
+                continue;
+            pushChange(`options.${key}`, currentOptions[key] ?? null, prepared.options[key] ?? null);
+        }
+        if (args.choices !== undefined) {
+            const fromChoices = choiceCodesOf(currentOptions) ?? [];
+            pushChange("choices", fromChoices, [...args.choices]);
+        }
+    }
+    const shapeTouched = changes.some((change) => {
+        if (change.field === "propertyEmpty" || change.field === "choices")
+            return true;
+        if (change.field === "options.scale" || change.field === "options.propertyType" || change.field === "options.propertyEmpty")
+            return true;
+        if (change.field.startsWith("options.") && DATA_SHAPE_OPTION_KEYS.has(change.field.slice("options.".length)))
+            return true;
+        return false;
+    });
+    let dataImpact;
+    if (shapeTouched) {
+        const counted = await countModelDataRows(session, args.schemaCode);
+        const shapeFields = changes
+            .filter((change) => change.field === "propertyEmpty" || change.field === "choices" || change.field === "options.scale" || change.field === "options.propertyType" || change.field === "options.propertyEmpty" || (change.field.startsWith("options.") && DATA_SHAPE_OPTION_KEYS.has(change.field.slice("options.".length))))
+            .map((change) => change.field);
+        dataImpact = {
+            ...(counted.dataRows === "unknown"
+                ? { dataRows: "unknown", note: counted.note ?? "拿不到行数：data.list total 不可用" }
+                : {
+                    dataRows: counted.dataRows,
+                    note: `触及数据形状键（${shapeFields.join("、")}）；现有 ${counted.dataRows} 条数据不会被本工具自动重写，请自行评估显示/校验影响`,
+                }),
+        };
+    }
+    return {
+        wouldChange: changes.length > 0,
+        changes,
+        ...(dataImpact !== undefined ? { dataImpact } : {}),
+        schemaCode: args.schemaCode,
+        code: args.code,
+    };
+}
+function formControlCodes(face) {
+    if (typeof face !== "string")
+        return [];
+    try {
+        const parsed = JSON.parse(face);
+        return Object.keys(parsed);
+    }
+    catch {
+        return [];
+    }
+}
+function scriptMentionsField(script, code) {
+    if (!script)
+        return false;
+    const escaped = code.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`(?:^|[^A-Za-z0-9_])${escaped}(?:[^A-Za-z0-9_]|$)`).test(script);
+}
+async function scanFieldRuleReferences(session, schemaCode, code) {
+    const references = [];
+    let rows = [];
+    try {
+        rows = wireRows((await wireCall(session, { path: ENDPOINTS.businessRuleListBySchemaCode, query: { schemaCode } })).data);
+    }
+    catch (error) {
+        return { references, unknown: `业务规则列表不可用：${error instanceof Error ? error.message : String(error)}` };
+    }
+    for (const row of rows) {
+        const ruleCode = String(row.code ?? "");
+        const ruleId = row.id;
+        if (typeof ruleId !== "string" || ruleId === "")
+            continue;
+        let record = null;
+        try {
+            record = (await wireCall(session, { path: ENDPOINTS.businessRuleGet, query: { id: ruleId } })).data;
+        }
+        catch {
+            continue;
+        }
+        if (!record)
+            continue;
+        const nodes = decodeJsonColumn(record.node, JSON_COLUMN_NULL_COALESCE);
+        if (!Array.isArray(nodes))
+            continue;
+        for (const rawNode of nodes) {
+            const nodeCode = String(rawNode.nodeCode ?? "");
+            const nodeType = String(rawNode.nodeType ?? "");
+            const mapping = rawNode.methodMapping;
+            let via;
+            if (["CREATE", "UPDATE", "DELETE"].includes(nodeType) && Array.isArray(rawNode.dataActions)
+                && rawNode.dataActions.some((action) => String(action.targetDataItem ?? "") === code)) {
+                via = "dataActions.targetDataItem";
+            }
+            if (!via && mapping) {
+                for (const [key, label] of [["inputMappings", "inputMappings.bizCode"], ["outputMappings", "outputMappings.bizCode"]]) {
+                    if (Array.isArray(mapping[key]) && mapping[key].some((entry) => String(entry.bizCode ?? "") === code && (entry.codeType === undefined || entry.codeType === 1))) {
+                        via = label;
+                        break;
+                    }
+                }
+            }
+            if (!via)
+                continue;
+            references.push({
+                kind: "businessRule",
+                code: ruleCode || nodeCode,
+                name: String(record.name ?? (ruleCode || nodeCode)),
+                via,
+                schemaCode,
+            });
+            break;
+        }
+    }
+    return { references };
+}
+async function scanFieldFormListviewOnlineJs(session, schemaCode, code) {
+    const references = [];
+    const dependentUpdates = {};
+    // form.get 面：控件码清单
+    try {
+        const sheet = (await wireCall(session, { path: ENDPOINTS.sheetGet, query: { schemaCode, sheetCode: schemaCode } })).data;
+        if (!sheet) {
+            dependentUpdates.form = { present: false, note: "默认表单不存在（sheetGet 空）" };
+        }
+        else {
+            const draftControls = formControlCodes(sheet.draftAttributesJson);
+            const publishedControls = formControlCodes(sheet.publishedAttributesJson);
+            const inDraft = draftControls.includes(code);
+            const inPublished = publishedControls.includes(code);
+            dependentUpdates.form = {
+                present: true,
+                inDraft,
+                inPublished,
+                note: inDraft || inPublished
+                    ? "删除字段后表单控件会残留；需 form.draft(rebuild)/form.publish 清理"
+                    : "默认表单控件码未引用该字段",
+            };
+            if (inDraft || inPublished) {
+                references.push({
+                    kind: "form",
+                    code: schemaCode,
+                    name: String(sheet.name ?? schemaCode),
+                    via: inDraft && inPublished ? "draft+published controls" : inDraft ? "draft controls" : "published controls",
+                    schemaCode,
+                });
+            }
+            // online JS：扫 customScript 原文是否提及字段 code
+            const scripts = [];
+            for (const face of [sheet.draftHtmlJson, sheet.publishedHtmlJson]) {
+                if (typeof face !== "string" || !face.trim())
+                    continue;
+                try {
+                    const parsed = JSON.parse(face);
+                    if (!Array.isArray(parsed))
+                        continue;
+                    const custom = parsed.find((element) => element?.id === "customScript");
+                    if (typeof custom?.innerHTML === "string" && custom.innerHTML.trim())
+                        scripts.push(custom.innerHTML);
+                }
+                catch {
+                    // ignore malformed html face
+                }
+            }
+            const mentioned = scripts.some((script) => scriptMentionsField(script, code));
+            dependentUpdates.onlineJs = {
+                scanned: true,
+                mentioned,
+                note: mentioned
+                    ? "在线 JS 原文仍包含该字段 code；删除后脚本引用会静默残留，需 onlinejs.compose 清理"
+                    : "在线 JS 原文未匹配到该字段 code（按词边界扫描，不含间接引用）",
+            };
+            if (mentioned) {
+                references.push({
+                    kind: "onlineJs",
+                    code: schemaCode,
+                    name: String(sheet.name ?? schemaCode),
+                    via: "customScript.innerHTML",
+                    schemaCode,
+                });
+            }
+        }
+    }
+    catch (error) {
+        dependentUpdates.form = { unknown: true, note: `form.get 不可用：${error instanceof Error ? error.message : String(error)}` };
+        dependentUpdates.onlineJs = { unknown: true, note: `onlinejs 扫描跳过：form 面读取失败` };
+    }
+    // listview.get 面：列/条件
+    try {
+        const got = await wireCall(session, { path: ENDPOINTS.listQueryGet, query: { schemaCode, code: schemaCode, clientType: "PC" } });
+        const model = (got.data ?? null);
+        if (!model || !model.id) {
+            dependentUpdates.listview = { present: false, note: "默认列表视图不存在" };
+        }
+        else {
+            const columns = Array.isArray(model.queryColumns) ? model.queryColumns : [];
+            const conditions = Array.isArray(model.queryConditions) ? model.queryConditions : [];
+            const inColumns = columns.some((column) => String(column.propertyCode ?? "") === code);
+            const inConditions = conditions.some((condition) => String(condition.propertyCode ?? "") === code);
+            dependentUpdates.listview = {
+                present: true,
+                code: String(model.code ?? schemaCode),
+                inColumns,
+                inConditions,
+                note: inColumns || inConditions
+                    ? "删除字段后列表列/条件会残留；需 listview.configure 清理"
+                    : "默认列表视图列/条件未引用该字段",
+            };
+            if (inColumns || inConditions) {
+                references.push({
+                    kind: "listview",
+                    code: String(model.code ?? schemaCode),
+                    name: String(model.name ?? model.code ?? schemaCode),
+                    via: inColumns && inConditions ? "columns+conditions" : inColumns ? "columns" : "conditions",
+                    schemaCode,
+                });
+            }
+        }
+    }
+    catch (error) {
+        dependentUpdates.listview = { unknown: true, note: `listview.get 不可用：${error instanceof Error ? error.message : String(error)}` };
+    }
+    return { references, dependentUpdates };
+}
+/**
+ * field.delete 影响面：dry-run 全量（行数 + 规则 + 表单/视图/在线JS），
+ * 真写回执给摘要（不扫规则图，只扫表单/视图/在线JS + 行数）。
+ */
+async function collectFieldDeleteImpact(session, args, options) {
+    const counted = await countModelDataRows(session, args.schemaCode);
+    const references = [];
+    const unknowns = [];
+    if (options.full) {
+        const rules = await scanFieldRuleReferences(session, args.schemaCode, args.code);
+        references.push(...rules.references);
+        if (rules.unknown)
+            unknowns.push(rules.unknown);
+    }
+    else {
+        unknowns.push("真写回执未扫业务规则引用（成本高）；完整引用面请先 --dry-run");
+    }
+    const surfaces = await scanFieldFormListviewOnlineJs(session, args.schemaCode, args.code);
+    references.push(...surfaces.references);
+    for (const key of ["form", "listview", "onlineJs"]) {
+        const face = surfaces.dependentUpdates[key];
+        if (face?.unknown === true && typeof face.note === "string")
+            unknowns.push(face.note);
+    }
+    return {
+        dataRows: counted.dataRows,
+        ...(counted.note ? { dataRowsNote: counted.note } : counted.dataRows === "unknown" ? { dataRowsNote: "拿不到行数：data.list total 不可用" } : {}),
+        references,
+        dependentUpdates: surfaces.dependentUpdates,
+        ...(unknowns.length > 0 ? { unknown: unknowns } : {}),
+        note: options.full
+            ? "完整影响面（规则+表单+视图+在线JS+行数）。删除不会自动清理依赖面残留。"
+            : "摘要影响面（表单+视图+在线JS+行数；规则请看 dry-run）。删除不会自动清理依赖面残留。",
+    };
+}
 /** The proven field.update write body — shared by the write tool and the cascade path. */
 async function runFieldUpdate(session, args) {
     const listed = await wireCall(session, { path: ENDPOINTS.fieldList, query: { schemaCode: args.schemaCode, isPublish: "false" } });
@@ -560,7 +963,33 @@ async function runFieldUpdate(session, args) {
     const record = rows.find((row) => (row.code ?? row.propertyCode) === args.code);
     if (!record)
         throw new WireError("business", `field ${args.code} not found on ${args.schemaCode}`, 301001);
-    if (args.options !== undefined) {
+    let effectiveOptions = args.options;
+    let dictionarySynced;
+    if (args.syncDictionary === true) {
+        const baseOptions = optionsObjectOf(args.options ?? record.options);
+        const binding = dictionaryBindingOf(baseOptions);
+        if (!binding?.checkedDictionary && !binding?.checkedDictionaryCode) {
+            throw new ToolRefusalError({
+                status: "refused",
+                blocker: "field-not-dictionary-backed",
+                schemaCode: args.schemaCode,
+                code: args.code,
+                message: `field.update syncDictionary:true 要求字段 options.optionsSet.optionsType=dictionary（含 checkedDictionary/checkedDictionaryCode）；${args.schemaCode}.${args.code} 不是字典-backed`,
+            });
+        }
+        const enabled = await loadEnabledDictionaryRecords(session, binding);
+        const optionsSet = { ...baseOptions.optionsSet };
+        const dictionary = { ...(optionsSet.dictionary ?? {}) };
+        dictionary.useDictionariesData = enabled;
+        optionsSet.dictionary = dictionary;
+        optionsSet.optionsType = "dictionary";
+        effectiveOptions = { ...baseOptions, optionsSet };
+        dictionarySynced = {
+            from: binding.useDictionariesData.map((row) => row.code).filter(Boolean),
+            to: enabled.map((row) => row.code),
+        };
+    }
+    if (effectiveOptions !== undefined) {
         // Same platform cycle as field.create (r17). On UPDATE the caller may also
         // be rewriting a previously-fine AGGREGATION, so resolve the child tables
         // from the published face the same way; a read failure must not silently
@@ -568,8 +997,8 @@ async function runFieldUpdate(session, args) {
         const publishedRows = await wireCall(session, { path: ENDPOINTS.fieldList, query: { schemaCode: args.schemaCode, isPublish: "true" } })
             .then((response) => wireRows(response.data))
             .catch(() => []);
-        assertNoSelfSchemaAggregation({ schemaCode: args.schemaCode, propertyType: record.type ?? record.propertyType, options: args.options }, publishedRows);
-        await assertNoChildSchemaAggregation(session, args.schemaCode, record.type ?? record.propertyType, args.options);
+        assertNoSelfSchemaAggregation({ schemaCode: args.schemaCode, propertyType: record.type ?? record.propertyType, options: effectiveOptions }, publishedRows);
+        await assertNoChildSchemaAggregation(session, args.schemaCode, record.type ?? record.propertyType, effectiveOptions);
     }
     const targetVersion = session.detectedVersion();
     const update = {
@@ -579,7 +1008,7 @@ async function runFieldUpdate(session, args) {
         ...(targetVersion ? { targetVersion } : {}),
         ...(args.name !== undefined ? { name: args.name } : {}),
         ...(args.name_i18n !== undefined ? { name_i18n: args.name_i18n } : {}),
-        ...(args.options !== undefined ? { options: args.options } : {}),
+        ...(effectiveOptions !== undefined ? { options: effectiveOptions } : {}),
         ...(args.choices !== undefined ? { choices: args.choices } : {}),
         ...(args.relativeCode !== undefined ? { relativeCode: args.relativeCode } : {}),
         ...(args.subFields !== undefined ? { subFields: args.subFields } : {}),
@@ -597,7 +1026,7 @@ async function runFieldUpdate(session, args) {
     // failure never hides the field write (it is surfaced as formConditionSync.error).
     let formConditionSync;
     let formConditionSyncError;
-    if (args.options !== undefined && !prepared.isChildTable) {
+    if (effectiveOptions !== undefined && !prepared.isChildTable) {
         const previous = decodeJsonObjectColumn(record.options, { invalid: "throw", array: "accept", object: "accept" }) ?? {};
         try {
             const sync = await syncFormConditionDataRules(session, args.schemaCode, args.code, previous, prepared.options);
@@ -619,11 +1048,13 @@ async function runFieldUpdate(session, args) {
             ? { note: { conditionCompiled: prepared.conditionCompiled, hint: "符号式/裸值条件已就地编译为平台中文规范形状；单选字段按选项 code 比较仍需 specifyOption；此配置是门户交互层，data.submit 不拦截" } }
             : {}),
         readback: {
+            face: "draft",
             fieldPresent: after !== undefined,
             ...(after?.name !== undefined ? { name: after.name } : {}),
             ...(typeof after?.name_i18n === "string" ? { name_i18n: after.name_i18n } : {}),
             ...(after?.type !== undefined || after?.propertyType !== undefined ? { type: after?.type ?? after?.propertyType } : {}),
             ...(storedOptions !== undefined && storedOptions !== null ? { options: storedOptions } : {}),
+            ...(dictionarySynced !== undefined ? { dictionarySynced } : {}),
             ...(formConditionSync !== undefined ? { formConditionSync } : {}),
             ...(formConditionSyncError !== undefined ? { formConditionSync: { error: formConditionSyncError } } : {}),
         },
@@ -638,6 +1069,182 @@ async function runFieldUpdate(session, args) {
  * cascaded republish exists precisely because the PUBLISHED face carries the
  * stale shape while the field is present there.
  */
+/**
+ * GitLab issue #24（2026-11-05，Windows 8.6.44 实测）：`field.publish` 用**子表**
+ * 的 schemaCode 调用时平台回 300004「数据模型不存在！」——子表不是顶层 biz schema，
+ * 发布是父模型级的。旧回执只给 `omc help omc-refusals`，用户只能自己猜父模型。
+ * 这里在失败路径上反查一次（读面，最多 60 个模型、并发 4），把父模型直接点名。
+ */
+async function findChildTableParent(session, childCode) {
+    const candidates = wireRows((await wireCall(session, { path: ENDPOINTS.modelList, query: {} })).data)
+        .filter((row) => row.type === "BizModel" && typeof row.code === "string" && String(row.code).length > 0)
+        .slice(0, 60);
+    const queue = [...candidates];
+    let found;
+    const workers = Array.from({ length: 4 }, async () => {
+        for (;;) {
+            if (found !== undefined)
+                return;
+            const row = queue.shift();
+            if (row === undefined)
+                return;
+            const parent = String(row.code);
+            try {
+                const fields = wireRows((await wireCall(session, { path: ENDPOINTS.fieldList, query: { schemaCode: parent, isPublish: "true" } })).data);
+                if (fields.some((field) => Number(field.type ?? field.propertyType) === FIELD_PROPERTY_TYPES.CHILD_TABLE && String(field.code ?? field.propertyCode ?? "") === childCode)) {
+                    found = { parent };
+                    return;
+                }
+            }
+            catch {
+                // A model whose field face is unreadable must not abort the search.
+            }
+        }
+    });
+    await Promise.all(workers);
+    return found;
+}
+/**
+ * GitLab issue #24 的**主诉**：`field.publish` 成功只证明「字段可用」，
+ * 业务页面还要表单布局里有这个控件。顶层字段看 attributes 的顶层键；子表列看
+ * 父 Sheet201 控件的 `columns`（child keys 永远不进 viewJson）。
+ *
+ * 只在**确实缺**的时候占字节；同步时回一个短字符串。
+ */
+async function dictionaryStaleAdvisory(session, publishedRows) {
+    const stale = [];
+    const cache = new Map();
+    for (const row of publishedRows) {
+        const code = String(row.code ?? row.propertyCode ?? "");
+        if (!code || SYSTEM_FIELD_CODES.has(code))
+            continue;
+        const binding = dictionaryBindingOf(optionsObjectOf(row.options));
+        if (!binding)
+            continue;
+        const cacheKey = `${binding.checkedDictionary ?? ""}|${binding.checkedDictionaryCode ?? ""}`;
+        let enabledCodes = cache.get(cacheKey);
+        if (enabledCodes === undefined) {
+            try {
+                enabledCodes = (await loadEnabledDictionaryRecords(session, binding)).map((entry) => entry.code);
+            }
+            catch {
+                continue;
+            }
+            cache.set(cacheKey, enabledCodes);
+        }
+        const fieldCodes = binding.useDictionariesData.map((entry) => entry.code).filter(Boolean);
+        const enabledSet = new Set(enabledCodes);
+        const fieldSet = new Set(fieldCodes);
+        const missingInField = enabledCodes.filter((entry) => !fieldSet.has(entry));
+        const extraInField = fieldCodes.filter((entry) => !enabledSet.has(entry));
+        if (missingInField.length > 0 || extraInField.length > 0) {
+            stale.push({ code, missingInField, extraInField });
+        }
+    }
+    return stale.length > 0 ? stale : undefined;
+}
+function relationMappingsEmptyWarnings(publishedRows) {
+    const empty = publishedRows
+        .filter((row) => {
+        const type = Number(row.type ?? row.propertyType);
+        if (type !== FIELD_PROPERTY_TYPES.WORK_SHEET)
+            return false;
+        const options = optionsObjectOf(row.options);
+        const mappings = options.mappings;
+        if (mappings === undefined || mappings === null)
+            return true;
+        if (typeof mappings === "string")
+            return mappings.trim() === "" || mappings.trim() === "[]";
+        if (Array.isArray(mappings))
+            return mappings.length === 0;
+        return false;
+    })
+        .map((row) => String(row.code ?? row.propertyCode ?? ""))
+        .filter((code) => code.length > 0);
+    if (empty.length === 0)
+        return undefined;
+    return [{ code: "relation-mappings-empty", fields: empty, hint: "选中时不回填副本列；配 options.mappings 后再 field.publish" }];
+}
+async function formBindingAdvisory(session, schemaCode, publishedRows) {
+    const dictionaryStale = await dictionaryStaleAdvisory(session, publishedRows);
+    const warnings = relationMappingsEmptyWarnings(publishedRows);
+    let form = null;
+    try {
+        form = await readFormOrNull(session, schemaCode, schemaCode);
+    }
+    catch {
+        return undefined;
+    }
+    const extras = {
+        ...(dictionaryStale !== undefined ? { dictionaryStale } : {}),
+        ...(warnings !== undefined ? { warnings } : {}),
+    };
+    if (form === null) {
+        return {
+            formPresent: false,
+            note: `模型没有表单，业务页面看不到任何字段；建表单：omc call configure_form --args '${JSON.stringify({ schemaCode })}'`,
+            ...extras,
+        };
+    }
+    const attributesRaw = typeof form.publishedAttributesJson === "string" && form.publishedAttributesJson.trim() !== "" && form.publishedAttributesJson.trim() !== "{}"
+        ? form.publishedAttributesJson
+        : typeof form.draftAttributesJson === "string" && form.draftAttributesJson.trim() !== "" && form.draftAttributesJson.trim() !== "{}"
+            ? form.draftAttributesJson
+            : undefined;
+    if (attributesRaw === undefined) {
+        return {
+            formPresent: true,
+            note: `表单存在但布局为空，业务页面看不到字段；重建：omc call configure_form --args '${JSON.stringify({ schemaCode, rebuild: true })}'`,
+            ...extras,
+        };
+    }
+    let attributes;
+    try {
+        attributes = JSON.parse(attributesRaw);
+    }
+    catch {
+        return { formPresent: true, note: "表单布局不是合法 JSON，未做绑定核对（先 form.get 读原文修复）", ...extras };
+    }
+    const business = publishedRows.filter((row) => {
+        const code = String(row.code ?? row.propertyCode ?? "");
+        return code.length > 0 && !SYSTEM_FIELD_CODES.has(code) && FIELD_PROPERTY_TYPES[fieldTypeName(row)] !== undefined;
+    });
+    const missingTopLevel = business
+        .filter((row) => fieldTypeName(row) !== "CHILD_TABLE" && attributes[String(row.code ?? row.propertyCode)] === undefined)
+        .map((row) => String(row.code ?? row.propertyCode));
+    const missingChildColumns = [];
+    for (const row of business) {
+        if (fieldTypeName(row) !== "CHILD_TABLE")
+            continue;
+        const parent = String(row.code ?? row.propertyCode);
+        const columns = attributes[parent]?.columns;
+        const bound = new Set(Array.isArray(columns) ? columns.map((column) => String(column.key ?? "")) : []);
+        const missing = childColumnsOf(row.subSchema).filter((column) => column.system !== true && !bound.has(column.code)).map((column) => column.code);
+        if (missing.length > 0)
+            missingChildColumns.push({ parent, fieldCodes: missing });
+    }
+    if (missingTopLevel.length === 0 && missingChildColumns.length === 0) {
+        if (dictionaryStale === undefined && warnings === undefined)
+            return "in-sync";
+        return { formPresent: true, layout: "in-sync", ...extras };
+    }
+    const fix = missingChildColumns.length > 0
+        ? { schemaCode, ...(missingTopLevel.length > 0 ? { fieldCodes: missingTopLevel } : {}), childColumns: missingChildColumns }
+        : { schemaCode, fieldCodes: missingTopLevel, rebuild: true };
+    return {
+        formPresent: true,
+        ...(missingTopLevel.length > 0 ? { notInFormLayout: missingTopLevel } : {}),
+        ...(missingChildColumns.length > 0 ? { childColumnsNotInForm: missingChildColumns } : {}),
+        note: "字段已发布但**表单布局里没有**，业务页面看不到。子表列用 childColumns 增量绑进 Sheet201（不动其它控件）；顶层缺字段用 rebuild:true（会重建布局）",
+        nextCommand: `omc call configure_form --args '${JSON.stringify(fix)}'`,
+        ...extras,
+    };
+}
+/** PropertyType label for a raw field row (accepts {type} or {propertyType}). */
+function fieldTypeName(row) {
+    const raw = row.typeName ?? fieldTypeLabel(row.type ?? row.propertyType);
+    return String(raw ?? "");
+}
 export async function executeFieldPublish(session, args) {
     // bizproperty/publish is MODEL-SCOPED: one call publishes every draft
     // field of the schema. `code`/`codes` only select which fields to verify
@@ -683,8 +1290,30 @@ export async function executeFieldPublish(session, args) {
         return { mode: "detail", verified: true, checked: bounded.length, ok: mismatches.length === 0, ...(mismatches.length > 0 ? { mismatches } : {}) };
     };
     const preRead = await wireCall(session, { path: ENDPOINTS.fieldList, query: { schemaCode: args.schemaCode, isPublish: "true" } });
-    const prePublished = wireRows(preRead.data).map(codeOf).filter((code) => code.length > 0);
-    if (args.force !== true && requestedCodes.length > 0 && requestedCodes.every((code) => prePublished.includes(code))) {
+    const prePublishedRows = wireRows(preRead.data);
+    const prePublished = prePublishedRows.map(codeOf).filter((code) => code.length > 0);
+    // r29e F10/F11：旧短路只看「code 在发布面存在」，改了 options 仍报
+    // already-published + verification.ok（假绿）。再比草稿/发布 options 指纹；
+    // 不一致就真发布。name/type 仍由 verifyFieldDetails 核对。
+    const draftOptionsByCode = new Map(wireRows((await wireCall(session, { path: ENDPOINTS.fieldList, query: { schemaCode: args.schemaCode, isPublish: "false" } })).data)
+        .map((row) => [codeOf(row), optionsFingerprint(row.options)])
+        .filter(([code]) => code.length > 0));
+    const publishedOptionsByCode = new Map(prePublishedRows
+        .map((row) => [codeOf(row), optionsFingerprint(row.options)])
+        .filter(([code]) => code.length > 0));
+    const optionsMatchRequested = requestedCodes.length > 0 &&
+        requestedCodes.every((code) => {
+            if (!prePublished.includes(code))
+                return false;
+            // 模型级 publish 后草稿面可能被清空（ticket 81 幂等重试场景）——草稿行不在
+            // 时没有「内容不一致」可证，按已发布存在即可短路。
+            if (!draftOptionsByCode.has(code))
+                return true;
+            const draftFp = draftOptionsByCode.get(code) ?? "";
+            const publishedFp = publishedOptionsByCode.get(code) ?? "";
+            return draftFp === publishedFp;
+        });
+    if (args.force !== true && requestedCodes.length > 0 && requestedCodes.every((code) => prePublished.includes(code)) && optionsMatchRequested) {
         return {
             performed: { skipped: "already-published", scope: "model" },
             readback: {
@@ -693,6 +1322,7 @@ export async function executeFieldPublish(session, args) {
                 ...(args.codes ? { publishedFieldsPresent: Object.fromEntries(args.codes.map((code) => [code, true])) } : {}),
                 allRequestedPresent: true,
                 verification: await verifyFieldDetails(requestedCodes),
+                formBinding: await formBindingAdvisory(session, args.schemaCode, prePublishedRows),
             },
         };
     }
@@ -718,6 +1348,22 @@ export async function executeFieldPublish(session, args) {
             break;
         }
         catch (error) {
+            // GitLab issue #24 附带坑 1：用**子表** schemaCode 发布 → 平台 300004
+            // 「数据模型不存在！」。子表不是顶层 biz schema，发布是父模型级。旧回执只
+            // 把裸 wire 错误冒泡 + 指向 omc help omc-refusals，用户只能自己猜父模型。
+            if (error instanceof WireError && error.kind === "business" && error.errcode === 300004) {
+                const parent = await findChildTableParent(session, args.schemaCode).catch(() => undefined);
+                throw new ToolRefusalError({
+                    status: "refused",
+                    blocker: parent ? "field-publish-child-schema" : "wire-business",
+                    errcode: 300004,
+                    schemaCode: args.schemaCode,
+                    ...(parent ? { childOf: parent.parent, nextCommand: `omc call field.publish --args '${JSON.stringify({ schemaCode: parent.parent })}'` } : {}),
+                    message: parent
+                        ? `${args.schemaCode} 是子表（属于父模型 ${parent.parent}），不是顶层数据模型——平台按顶层 schema 发布，所以回 300004「数据模型不存在！」。改发父模型：omc call field.publish --args '${JSON.stringify({ schemaCode: parent.parent })}'（模型级一次发布全部草稿字段，子表列随父模型一起发布）`
+                        : `${args.schemaCode} 不在顶层数据模型清单里（300004 数据模型不存在）。若它是子表，请用**父模型**的 schemaCode 发布；\`omc call model.list\` 可核对顶层模型 code`,
+                });
+            }
             const transientColumnSync = error instanceof WireError && error.kind === "business" && error.errcode === 50000 && error.message.includes("不存在列");
             if (!(transientColumnSync && attempt < 3))
                 throw error;
@@ -748,6 +1394,8 @@ export async function executeFieldPublish(session, args) {
             ...(args.codes ? { publishedFieldsPresent: Object.fromEntries(args.codes.map((code) => [code, publishedCodes.includes(code)])) } : {}),
             ...(requested.length > 0 ? { allRequestedPresent: present.length === requested.length } : {}),
             verification,
+            // issue #24 主诉：publishedCodes 只证明「字段可用」，不等于「页面可见」。
+            formBinding: await formBindingAdvisory(session, args.schemaCode, wireRows(readback.data)),
         },
     };
 }