@stalfh233/omc-cli 0.4.88 → 0.4.91

package/dist/lanes/org-tree.js

@@ -0,0 +1,52 @@
+import { ENDPOINTS } from "../endpoints.js";
+import { wireCall, wireRows } from "../wire.js";
+export async function collectOrgDepartments(session, options = {}) {
+    const limit = options.limit ?? 500;
+    const fetchLevel = async (deptId) => {
+        const query = deptId === undefined ? {} : { deptIds: deptId };
+        const data = (await wireCall(session, { path: ENDPOINTS.organizationDepartmentTree, query })).data;
+        return Array.isArray(data?.departmentList) ? data.departmentList : wireRows(data);
+    };
+    const rows = [];
+    const seen = new Set();
+    const push = (level) => {
+        const added = [];
+        for (const row of level) {
+            const id = String(row.id ?? "");
+            if (id === "" || seen.has(id))
+                continue;
+            seen.add(id);
+            rows.push({ ...row, id, name: String(row.name ?? ""), parentId: String(row.parentId ?? "") });
+            added.push(id);
+        }
+        return added;
+    };
+    const queue = [];
+    if (options.rootId !== undefined) {
+        try {
+            const self = (await wireCall(session, { path: ENDPOINTS.organizationDepartmentGet, query: { deptId: options.rootId } })).data;
+            if (self)
+                push([self]);
+        }
+        catch {
+            // unknown id → empty result
+        }
+        queue.push(...push(await fetchLevel(options.rootId)));
+    }
+    else {
+        const roots = await fetchLevel(undefined);
+        push(roots);
+        queue.push(...roots.map((row) => String(row.id ?? "")).filter((id) => id.length > 0));
+    }
+    let truncated = false;
+    while (queue.length > 0) {
+        if (rows.length >= limit) {
+            truncated = true;
+            break;
+        }
+        const parentId = queue.shift();
+        queue.push(...push(await fetchLevel(parentId)));
+    }
+    return { rows, truncated };
+}
+//# sourceMappingURL=org-tree.js.map

package/dist/lanes/organization.js

@@ -7,6 +7,7 @@ import { wireCall, wireRows, WireError } from "../wire.js";
 import { ENDPOINTS } from "../endpoints.js";
 import { environmentArg, capabilityArg } from "../args.js";
 import { LANES } from "./lane-ids.js";
+import { collectOrgDepartments } from "./org-tree.js";
 /**
  * Organization WRITE faces (8.6.41 customer transcript, 2026-10-21).
  *
@@ -130,11 +131,33 @@ export function registerOrganizationLane(tools) {
                 query: { ...orgQuery(session), roleId: String(args.roleId), page: String(args.page ?? 0), size: String(args.size ?? 500) },
             })).data;
             const rows = Array.isArray(data?.content) ? data.content : wireRows(data);
+            // The wire row carries `deptId: null` and `departmentId` absent; the
+            // member's department rides `parentDepartmentName[0].deptId` (and
+            // `ouScope[0].id`). Projecting only `departmentId` made every member look
+            // department-less (r15 misdiagnosis; P4).
+            const memberDepartment = (row) => {
+                const direct = row.departmentId ?? row.deptId;
+                if (typeof direct === "string" && direct.length > 0)
+                    return direct;
+                const parents = Array.isArray(row.parentDepartmentName) ? row.parentDepartmentName : [];
+                for (const parent of parents)
+                    if (typeof parent.deptId === "string" && parent.deptId)
+                        return parent.deptId;
+                const scopes = Array.isArray(row.ouScope) ? row.ouScope : [];
+                for (const scope of scopes)
+                    if (typeof scope.id === "string" && scope.id)
+                        return scope.id;
+                return null;
+            };
             const members = rows.map((row) => ({
                 id: roleUserId(row),
                 name: row.name ?? null,
                 username: row.username ?? null,
-                departmentId: row.departmentId ?? null,
+                departmentId: memberDepartment(row),
+                departmentName: row.departmentName ?? null,
+                // `ouScope` decides whether a role member can be resolved as a workflow
+                // participant. Surface the count so an empty scope is visible here.
+                scopeCount: Array.isArray(row.ouScope) ? row.ouScope.length : null,
                 unitType: row.unitType ?? null,
             }));
             return { roleId: String(args.roleId), count: members.length, total: data?.totalElements ?? members.length, members };
@@ -301,10 +324,67 @@ export function registerOrganizationLane(tools) {
         const after = (await wireCall(session, { path: ENDPOINTS.organizationDepartmentGet, query: { ...orgQuery(session), deptId: args.deptId } })).data;
         return { performed: { errcode: 0 }, readback: { deptId: args.deptId, name: after?.name ?? null, parentId: after?.parentId ?? null, managerId: after?.managerId ?? null, enabled: after?.enabled ?? null } };
     });
-    writeTool(tools, "org.department.delete", LANE, SCOPES.deptDelete, "删除部门（`GET organization/department/strike_out?id=`）。平台会拒绝：有子部门 → 200009「部门下面存在子部门，不能删除！」；有用户 → 200002「部门下面存在用户，不能删除！」。工具先计数并在回读里给出，仍由平台裁决。", { deptId: z.string().min(1) }, async (session, args) => {
+    writeTool(tools, "org.department.delete", LANE, SCOPES.deptDelete, "删除部门（`GET organization/department/strike_out?id=`）。平台会拒绝：有子部门 → 200009「部门下面存在子部门，不能删除！」；有用户 → 200002「部门下面存在用户，不能删除！」。工具先计数并在回读里给出，仍由平台裁决。", { deptId: z.string().min(1), force: z.boolean().optional().describe("true = 先逐个删除子部门（仅当子部门无用户）再删本部门；有用户仍由平台裁决") }, async (session, args) => {
         const users = wireRows((await wireCall(session, { path: ENDPOINTS.organizationDepartmentUsers, query: { ...orgQuery(session), deptId: args.deptId } })).data);
+        // Pre-check children: the platform's 200009 ("部门下面存在子部门") is
+        // accurate but sends the caller hunting for ids. Name them and hand over
+        // the child-delete command (found during r15 org cleanup).
+        const walked = await collectOrgDepartments(session);
+        const children = walked.rows
+            .filter((row) => row.parentId === String(args.deptId))
+            .map((row) => ({ id: row.id, name: row.name }))
+            .filter((row) => row.id.length > 0);
+        let deletedChildren = 0;
+        if (children.length > 0) {
+            if (args.force !== true)
+                throw new ToolRefusalError({
+                    status: "refused", blocker: "department-has-children", deptId: String(args.deptId), children,
+                    nextCommand: `omc call org.department.delete --args '${JSON.stringify({ deptId: children[0].id })}'`,
+                    message: `部门 ${args.deptId} 下还有 ${children.length} 个子部门，平台拒绝删除（200009）。先删子部门，或传 force:true 让工具按顺序删除：${children.map((child) => `${child.name}(${child.id})`).join("、")}。`,
+                });
+            // force = deepest-first over the WHOLE subtree (a direct child with its
+            // own children would fail 200009 otherwise).
+            const byParent = new Map();
+            for (const row of walked.rows) {
+                if (row.id === String(args.deptId))
+                    continue;
+                const list = byParent.get(row.parentId) ?? [];
+                list.push({ id: row.id, name: row.name });
+                byParent.set(row.parentId, list);
+            }
+            const ordered = [];
+            const walk = (parentId) => {
+                for (const child of byParent.get(parentId) ?? []) {
+                    walk(child.id);
+                    ordered.push(child);
+                }
+            };
+            walk(String(args.deptId));
+            deletedChildren = ordered.length;
+            for (const child of ordered) {
+                try {
+                    await wireCall(session, { path: ENDPOINTS.organizationDepartmentDelete, query: { ...orgQuery(session), id: child.id } });
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    const usersPending = /200002|用户/.test(message);
+                    throw new ToolRefusalError({
+                        status: "refused", blocker: usersPending ? "department-has-users" : "department-delete-failed",
+                        deptId: String(args.deptId), blockedChild: child,
+                        nextCommand: `omc call org.department.users --args '${JSON.stringify({ deptId: child.id })}'`,
+                        message: `force 清理到子部门 ${child.name}(${child.id}) 时失败：${message}。${usersPending ? "该部门下还有员工——先转出再删。" : "平台拒绝删除该子部门。"}`,
+                    });
+                }
+            }
+        }
+        if (users.length > 0)
+            throw new ToolRefusalError({
+                status: "refused", blocker: "department-has-users", deptId: String(args.deptId), users: users.length,
+                nextCommand: `omc call org.department.users --args '${JSON.stringify({ deptId: String(args.deptId) })}'`,
+                message: `部门 ${args.deptId} 下还有 ${users.length} 名员工，平台拒绝删除（200002）。先用 org.department.users 看人，再用 org.user.transferDepartment 转出（平台不允许删带人的部门）。`,
+            });
         await wireCall(session, { path: ENDPOINTS.organizationDepartmentDelete, query: { ...orgQuery(session), id: args.deptId } });
-        return { performed: { errcode: 0 }, readback: { deptId: args.deptId, deleted: true, usersBeforeDelete: users.length } };
+        return { performed: { errcode: 0 }, readback: { deptId: args.deptId, deleted: true, usersBeforeDelete: users.length, deletedChildren } };
     });
     tools.push(defineTool({
         name: "org.department.users",
@@ -388,7 +468,26 @@ export function registerOrganizationLane(tools) {
         const departments = wireRows((await wireCall(session, {
             path: ENDPOINTS.organizationUserDepartments, query: { ...orgQuery(session), id: String(args.userId) },
         })).data).map((row) => ({ deptId: row.deptId ?? null, deptName: row.deptName ?? null, isMain: row.isMain ?? null }));
-        return { performed: { errcode: 0 }, readback: { userId: args.userId, name: after?.name ?? null, departmentId: after?.departmentId ?? null, mobile: after?.mobile ?? null, email: after?.email ?? null, active: after?.active ?? null, userStatus: after?.status ?? null, departments } };
+        return {
+            performed: { errcode: 0 },
+            readback: {
+                userId: args.userId,
+                name: after?.name ?? null,
+                departmentId: after?.departmentId ?? null,
+                mobile: after?.mobile ?? null,
+                email: after?.email ?? null,
+                active: after?.active ?? null,
+                userStatus: after?.status ?? null,
+                departments,
+                // r15 P7: `active` did not persist on 1.1.25 (passed true, read false).
+                // It looks derived from account activation/binding rather than a
+                // writable switch — say so instead of letting the caller re-create the
+                // user to "fix" it.
+                ...(args.active !== undefined && after?.active !== args.active
+                    ? { activeWarning: `传了 active=${String(args.active)}，平台读回 ${String(after?.active)}：active 在 1.1.25 上不是可直接写的开关（疑似由账号激活/绑定派生）。启停账号用 status=ENABLE/DISABLE/LOCK；不要为改 active 新建用户。` }
+                    : {}),
+            },
+        };
     });
     writeTool(tools, "org.user.delete", LANE, SCOPES.userDelete, "删除员工（`GET organization/user/strike_out?id=`）。只传用户 id；返回 deleted。", { userId: z.string().min(1) }, async (session, args) => {
         await wireCall(session, { path: ENDPOINTS.organizationUserDelete, query: { ...orgQuery(session), id: args.userId } });
@@ -444,6 +543,7 @@ export function registerOrganizationLane(tools) {
         if (rows.length > 0 && args.force !== true)
             throw new ToolRefusalError({
                 status: "refused", blocker: "role-has-members", roleId: String(args.roleId), members: rows.length,
+                nextCommand: `omc call org.role.delete --args '${JSON.stringify({ roleId: String(args.roleId), force: true })}'`,
                 message: `角色下还有 ${rows.length} 名成员，平台拒绝删除（errmsg：角色下已经包含用户数据）。先 org.role.removeUsers，或传 force:true 让工具移出后再删。`,
             });
         if (rows.length > 0)
@@ -459,6 +559,7 @@ export function registerOrganizationLane(tools) {
         if (roles.length > 0 && args.force !== true)
             throw new ToolRefusalError({
                 status: "refused", blocker: "role-group-has-roles", roleGroupId: String(args.roleGroupId), roles: roles.length,
+                nextCommand: `omc call org.roleGroup.delete --args '${JSON.stringify({ roleGroupId: String(args.roleGroupId), force: true })}'`,
                 message: `角色组下还有 ${roles.length} 个角色，平台拒绝删除（errmsg：角色组下已经包含角色数据）。先删角色，或传 force:true。`,
             });
         for (const role of roles) {
@@ -624,7 +725,10 @@ export function registerOrganizationLane(tools) {
             id: z.string().min(1).describe("部门 id"),
             name: z.string().min(1),
             deptPath: z.string().optional().describe("完整路径，如 根组织/广州总所"),
-            type: z.string().optional().describe("默认 \"1\"（部门节点）"),
+            // The wire wants the enum as a STRING ("1"); a number used to die in
+            // input validation with a generic tool-input-invalid (r10). Accept both
+            // and normalize, so the mistake cannot cost a round.
+            type: z.union([z.string(), z.number()]).optional().describe("部门节点固定 \"1\"（字符串；也接受数字 1，工具会归一化）"),
         })).describe("要设置的管理范围节点"),
         mode: z.enum(["merge", "replace"]).optional().describe("默认 merge（读旧值合并）；replace = 覆盖整个范围"),
         dryRun: z.boolean().optional(),
@@ -633,7 +737,7 @@ export function registerOrganizationLane(tools) {
             path: ENDPOINTS.organizationRoleGetOuScope,
             query: { ...orgQuery(session), roleId: args.roleId, userId: args.userId },
         })).data);
-        const wanted = args.scopes.map((scope) => ({ id: scope.id, name: scope.name, type: scope.type ?? "1", ...(scope.deptPath ? { deptPath: scope.deptPath } : {}) }));
+        const wanted = args.scopes.map((scope) => ({ id: scope.id, name: scope.name, type: scope.type === undefined ? "1" : String(scope.type), ...(scope.deptPath ? { deptPath: scope.deptPath } : {}) }));
         const merged = args.mode === "replace"
             ? wanted
             : [...before.map((row) => ({ id: String(row.id ?? ""), name: String(row.name ?? ""), type: String(row.type ?? "1"), ...(row.deptPath ? { deptPath: String(row.deptPath) } : {}) })).filter((row) => row.id !== ""), ...wanted]

package/dist/lanes/rule-lifecycle.js

@@ -204,11 +204,32 @@ export function registerRuleLifecycleLane(tools) {
                 ruleCode: args.ruleCode,
                 message: `规则 ${args.ruleCode} 当前未启用（enabled=${String(row.enabled)}）——先 rule.enable（publish+enable 两步），否则设计器显示「失效·未启用」且按钮不会执行它`,
             });
-        const performed = await wireCall(session, {
-            path: ruleRuntimeExecutePath(args.schemaCode, args.ruleCode),
-            method: "POST",
-            body: { schemaCode: args.schemaCode, ids, ruleCode: args.ruleCode, consolidation: args.consolidation === true },
-        });
+        let performed;
+        try {
+            performed = await wireCall(session, {
+                path: ruleRuntimeExecutePath(args.schemaCode, args.ruleCode),
+                method: "POST",
+                body: { schemaCode: args.schemaCode, ids, ruleCode: args.ruleCode, consolidation: args.consolidation === true },
+            });
+        }
+        catch (error) {
+            // 550001 业务规则不存在 on the launcher runtime path means the rule was
+            // not REGISTERED as a custom trigger (r15: a data-event graph saved with
+            // customTrigger:true still 550001s). Name the semantic instead of
+            // forwarding a bare platform code.
+            if (error instanceof WireError && error.kind === "business" && error.errcode === 550001)
+                throw new ToolRefusalError({
+                    status: "refused",
+                    blocker: "rule-not-custom-trigger",
+                    schemaCode: args.schemaCode,
+                    ruleCode: args.ruleCode,
+                    nextCommand: `omc call rule.get --args '${JSON.stringify({ schemaCode: args.schemaCode, ruleCode: args.ruleCode })}'`,
+                    message: `平台 launcher 运行时没有注册规则 ${args.ruleCode}（550001 业务规则不存在）。\`rule.run\` 走的是「按钮/自定义触发」端点，` +
+                        `只认 CUSTOM_NODE 触发的规则；数据事件（Create/Update/…）的规则不会注册在这里。` +
+                        `要看规则图里有没有 CUSTOM_NODE，用 rule.get 看 nodes；要验证数据事件规则请走 data.submit/data.update，要验证按钮请绑到列表/表单按钮后在门户点击。`,
+                });
+            throw error;
+        }
         const payload = (performed.data ?? null);
         const objects = Array.isArray(payload) ? payload : [];
         return {

package/dist/lanes/runtime-data.js

@@ -216,6 +216,47 @@ function projectReadbackRecord(record, args) {
         return record;
     return compactRuntimeRecord(source);
 }
+/**
+ * Approval-submit readback (issue 2026-10-25 §2).
+ *
+ * An approval submit changed almost nothing: the caller needs "did the flow
+ * advance" (sequenceStatus) plus "did the fields I typed persist". Returning the
+ * whole compact record made every approval level pay for the full row again
+ * (r12: 25 data.submit calls / 55.6 KB — the single largest read face).
+ * `summary`/`fields`/`full` still win when supplied; this is only the default.
+ */
+/**
+ * Which submitted values did the immediate readback NOT show? (r10 F8)
+ *
+ * The platform's form/load face can answer with only system columns right after
+ * a write transaction (r14: `readback.authoritative` held just `modifiedTime`
+ * while `data.load` a moment later had every business field). Without a note the
+ * caller reads that as "the write dropped my data" and writes again.
+ */
+function readbackEmptyFields(formData, record) {
+    const source = record !== null && typeof record === "object" && !Array.isArray(record) ? record : {};
+    return Object.entries(formData)
+        .filter(([key, value]) => value !== null && value !== undefined && (source[key] === null || source[key] === undefined))
+        .map(([key]) => key);
+}
+function readbackWarningFor(emptyFields, toolName) {
+    if (emptyFields.length === 0)
+        return undefined;
+    return `${toolName} 已 DELIVERED，但即时读回里这些本次提交的字段为空/缺省：${emptyFields.join("、")}。平台 form/load 在写事务后可能先回系统字段、业务字段滞后（真机 1.1.25，r14 见过只回 modifiedTime 的一笔）。**先 omc call data.load 核对，不要重写**；若 data.load 仍为空，才按投影/字段 code 排查。`;
+}
+function projectApprovalReadback(record, submittedKeys) {
+    if (record === null || typeof record !== "object" || Array.isArray(record))
+        return {};
+    const source = record;
+    const projected = {};
+    for (const key of ["id", "bizObjectId", "schemaCode", "sequenceStatus"])
+        if (key in source)
+            projected[key] = source[key];
+    for (const key of submittedKeys)
+        if (key in source && !(key in projected))
+            projected[key] = compactRuntimeValue(source[key]);
+    return projected;
+}
 /** Shared optional schema fields for the write readback projection. */
 export const readbackProjectionArgs = {
     summary: z.boolean().optional().describe("只回身份/状态字段，裁剪 readback.authoritative（默认关闭，读回为业务字段+身份的精简记录）"),
@@ -750,8 +791,11 @@ export function registerRuntimeDataLane(tools) {
         // branch) — business rules only run once data.submit advances the
         // row. Saying so on every plain-save readback prevents the
         // "rule didn't fire" misdiagnosis.
+        const savedRecord = normalizeLoadedRecord((readbackData ?? {}));
+        const savedEmptyFields = readbackEmptyFields(formData, savedRecord);
         const plainReadback = {
-            authoritative: projectReadbackRecord(normalizeLoadedRecord((readbackData ?? {})), args),
+            authoritative: projectReadbackRecord(savedRecord, args),
+            ...(savedEmptyFields.length > 0 ? { readbackWarning: readbackWarningFor(savedEmptyFields, "data.save") } : {}),
             draftRuleHint: "草稿态（DRAFT）保存不触发业务规则——DRAFT 行跳过 Create/Update 分发（DomainServiceImpl.java:240-248）；要一调完成态本调用加 submit:true；已存草稿直提形状：data.submit {schemaCode, bizObjectId: 本读回的 bizObjectId, formData}（submit 自持久化）",
         };
         // r18 retro (G3): one-call COMPLETED creation — the agent goal is usually
@@ -824,6 +868,7 @@ export function registerRuntimeDataLane(tools) {
                 schemaCode: args.schemaCode,
                 bizObjectId: args.bizObjectId,
                 sheetCode,
+                nextCommand: `omc call data.list --args '${JSON.stringify({ schemaCode: args.schemaCode })}'`,
                 message: "no live business object with this id; refusing to update (the platform would otherwise insert a new row)",
             });
         }
@@ -840,12 +885,14 @@ export function registerRuntimeDataLane(tools) {
         const returnedId = typeof performedData.objectId === "string" ? performedData.objectId : typeof performedData.bizObjectId === "string" ? performedData.bizObjectId : args.bizObjectId;
         const readbackData = await loadExistingBizObject(session, args.schemaCode, sheetCode, returnedId);
         const sequenceStatus = extractSequenceStatus(readbackData);
+        const updatedRecord = normalizeLoadedRecord(readbackData);
+        const updatedEmptyFields = readbackEmptyFields(formData, updatedRecord);
         return {
             performed: { errcode: performed.errcode, bizObjectId: returnedId, sheetCode, resolvedFrom },
             // Flat record contract (ticket 17): live FormLoadVO normalizes to the
             // fake's flat field shape so `authoritative.<fieldCode>` reads work on
             // both faces.
-            readback: { authoritative: projectReadbackRecord(normalizeLoadedRecord(readbackData), args), sequenceStatus },
+            readback: { authoritative: projectReadbackRecord(updatedRecord, args), sequenceStatus, ...(updatedEmptyFields.length > 0 ? { readbackWarning: readbackWarningFor(updatedEmptyFields, "data.update") } : {}) },
         };
     });
     /**
@@ -1006,6 +1053,7 @@ export function registerRuntimeDataLane(tools) {
                 schemaCode: args.schemaCode,
                 bizObjectId: targetObjectId,
                 workflowCode: explicitWorkflowCode,
+                nextCommand: "omc describe data.submit --example workflow-backed-data-submit",
                 message: "8.6.26 has no REST in-place workflow start for an existing no-instance row (submitWorkflowByWorkflowCode -> createAndGetBizObject INSERTs -> 40000 duplicate primary key; the load+update starter is facade-only). Supported shape: create workflow drafts via data.save with workflowCode (returns same-id row + DRAFT instance + start workItemId), then data.submit with that workItemId + workflowInstanceId + bizObjectId",
             });
         }
@@ -1021,6 +1069,7 @@ export function registerRuntimeDataLane(tools) {
                     schemaCode: args.schemaCode,
                     bizObjectId: targetObjectId,
                     sheetCode,
+                    nextCommand: `omc call data.list --args '${JSON.stringify({ schemaCode: args.schemaCode })}'`,
                     message: "no live business object with this id; refusing to submit (the platform would otherwise create a new row)",
                 });
             }
@@ -1163,13 +1212,20 @@ export function registerRuntimeDataLane(tools) {
             // start path returns only {result, objectId}); the authoritative loaded
             // row carries it. Prefer the response, then the row.
             const effectiveInstanceId = workflowInstanceId ?? extractWorkflowInstanceId(loaded) ?? (loadedRecord && typeof loadedRecord.workflowInstanceId === "string" && loadedRecord.workflowInstanceId ? loadedRecord.workflowInstanceId : null);
+            // An approval submit returns the status + the fields the caller submitted,
+            // not the whole row: r12's 25 approvals were the largest read face at
+            // 55.6 KB. Explicit summary/fields/full keep their contract.
+            const approvalDelta = hasWorkItem && args.summary !== true && args.full !== true && !(Array.isArray(args.fields) && args.fields.length > 0);
             readback = {
                 ...readback,
                 workflowInstanceId: effectiveInstanceId,
                 objectId,
                 workItemId: typeof performedData.workItemId === "string" ? performedData.workItemId : null,
                 sequenceStatus,
-                submittedData: projectReadbackRecord(loadedRecord, args),
+                submittedData: approvalDelta ? projectApprovalReadback(loadedRecord, Object.keys(formData ?? {})) : projectReadbackRecord(loadedRecord, args),
+                ...(approvalDelta
+                    ? { readbackShape: "approval-delta", readbackHint: "审批提交默认只回 sequenceStatus + 本次提交的字段；要整条记录（含子表/系统字段）加 full:true，要指定字段加 fields:[...]" }
+                    : {}),
             };
             // Multi-level approval: after a submit advances the flow, the caller
             // almost always needs the NEXT pending todo — bench52/53 paid an extra

package/dist/lanes/workflow.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { ENDPOINTS } from "../endpoints.js";
+import { collectOrgDepartments } from "./org-tree.js";
 import { capabilityArg, environmentArg } from "../args.js";
 import { governedRead } from "../read.js";
 import { ToolRefusalError } from "../tool-types.js";
@@ -732,6 +733,86 @@ function participantReferenceWarnings(template) {
     }
     return warnings;
 }
+/**
+ * Role participants are filtered by `ouScope ∩ originator's department chain`.
+ * A role whose members all have an empty scope therefore resolves to NOBODY —
+ * but the workflow still publishes, the submit still answers 0, and the todo
+ * silently falls back to the originator (r9/r10 live; r15 lost 12 calls to it).
+ * Refuse BEFORE the update wire (read-only check, fail-open when the member
+ * list is unavailable) so the trap is named where the participant is authored.
+ */
+async function assertRoleParticipantScopes(session, body) {
+    const rows = Array.isArray(body.activities)
+        ? body.activities
+        : body.activities && typeof body.activities === "object"
+            ? Object.values(body.activities)
+            : [];
+    const roles = [];
+    for (const activity of rows) {
+        if (String(activity.activityType ?? "") !== "PARTICIPANT")
+            continue;
+        const raw = activity.participant;
+        if (typeof raw !== "string" || !raw.trim().startsWith("["))
+            continue;
+        for (const segment of raw.split("+")) {
+            let parsed;
+            try {
+                parsed = JSON.parse(segment.trim());
+            }
+            catch {
+                continue;
+            }
+            if (!Array.isArray(parsed))
+                continue;
+            for (const entry of parsed) {
+                if (entry === null || typeof entry !== "object")
+                    continue;
+                const record = entry;
+                if (String(record.type ?? record.participantType ?? "") !== "2")
+                    continue;
+                const roleId = String(record.id ?? "");
+                if (roleId)
+                    roles.push({ activityCode: String(activity.activityCode ?? ""), roleId, roleName: String(record.name ?? roleId) });
+            }
+        }
+    }
+    const problems = [];
+    for (const role of roles) {
+        let members;
+        try {
+            const data = (await wireCall(session, {
+                path: ENDPOINTS.organizationRoleUsers,
+                query: { corpId: session.enterpriseId(), roleId: role.roleId, page: "0", size: "500" },
+            })).data;
+            members = Array.isArray(data?.content) ? data.content : wireRows(data);
+        }
+        catch {
+            // A read failure must not block the write (fail open) — the platform
+            // will answer, and the participant warnings still ride the readback.
+            continue;
+        }
+        if (members.length === 0)
+            continue; // nothing to prove
+        const withScope = members.filter((member) => Array.isArray(member.ouScope) && member.ouScope.length > 0);
+        if (withScope.length === 0)
+            problems.push({ ...role, members: members.length });
+    }
+    if (problems.length === 0)
+        return;
+    const detail = problems.map((problem) => `${problem.activityCode} → 角色 ${problem.roleName}(${problem.roleId}) 的 ${problem.members} 名成员 ouScope 全为空`).join("；");
+    const first = problems[0];
+    throw new ToolRefusalError({
+        status: "refused",
+        blocker: "workflow-participant-role-scope-empty",
+        roles: problems,
+        nextCommand: `omc call org.role.users --args '${JSON.stringify({ roleId: first.roleId })}'`,
+        message: `节点参与者用了角色，但该角色成员的 ouScope 为空：${detail}。` +
+            `平台按「ouScope ∩ 发起人部门链」解析角色成员，空范围 = 永远解析不到人；流程仍会发布、submit 仍回 errcode 0，` +
+            `待办会**静默回退给发起人**（r9/r10/r15 真机）。` +
+            `先给成员补管理范围（部门节点）：omc call org.role.setUserScope --args '{"roleId":"${first.roleId}","userId":"<成员recId>","scopes":[{"id":"<部门id>","name":"<部门名>","type":"1"}],"mode":"replace"}'，` +
+            `或在 addUsers 时直接带 scopes。补完再重试本次 workflow.update。`,
+    });
+}
 function isPlatformParticipantReference(participant) {
     if (/^\{[^}]+\}$/.test(participant))
         return true; // {Originator} keyword
@@ -2102,6 +2183,7 @@ export function registerWorkflowLane(tools) {
         await backfillDesignerDefaults(session, args.schemaCode, body, template);
         assertFirstActivityIsOriginator(template, "workflow.update", body);
         validateWorkflowRender(body, "workflow.update");
+        await assertRoleParticipantScopes(session, body);
         // Live: workflow/update does NOT run the template validator — it stores a
         // refused participant silently and only /publish answers the
         // ValidateMessage[]. So the guard belongs on publish/bindRule, not here.
@@ -2553,6 +2635,7 @@ export function registerWorkflowLane(tools) {
                     blocker: "workflow-has-instances",
                     workflowCode: args.code,
                     ...(pending > 0 ? { pendingWorkItems: pending } : {}),
+                    nextCommand: `omc call workitem.list --args '${JSON.stringify({ workflowCode: args.code })}'`,
                     message: `流程 ${args.code} 还有流程实例，平台拒绝删除（402508）。**不要改用 model.delete 绕过**——那会把流程模板级联删掉，` +
                         `留下指向空模板的待办，而平台全局待办搜索会给每条待办解析模板，**一条缺失就整页 NPE（50000），所有用户的待办列表一起坏掉**（r14 实测 8 连击，需维护者清库）。` +
                         `正确顺序：① 先完结/清理实例的待办（workitem.list --workflowCode ${args.code} 看还有哪些在办）；② 再 workflow.delete；③ 最后才 model.delete。`,
@@ -3028,50 +3111,15 @@ export function registerWorkflowLane(tools) {
         lane: WORKFLOW_LANE,
         scope: WORKFLOW_TOOLS["org.department.list"].scope,
         description: WORKFLOW_TOOLS["org.department.list"].description,
-        inputSchema: { environment: environmentArg, parentId: z.string().min(1).optional().describe("只列出该部门下的子树（默认从根递归展开整棵部门树）"), capability: capabilityArg },
+        inputSchema: { environment: environmentArg, parentId: z.string().min(1).optional().describe("只列出该部门及其下属（BFS 展开；默认从根展开整棵部门树）"), capability: capabilityArg },
         handler: async (ctx, args, self) => governedRead(ctx, self, args, async (session) => {
-            // `/department/tree` semantics (live 2026-10-22, 1.1.25): no `deptIds`
-            // → the ROOTS; with `deptIds=<id>` → that department's WHOLE SUBTREE
-            // (not one level). So: roots once, then one subtree call per root.
+            // `/department/tree` semantics (re-verified r15, 1.1.25): no `deptIds`
+            // → ROOTS; `deptIds=<id>` → DIRECT CHILDREN. The old "whole subtree"
+            // reading hid third-level departments (电气组) from this list. The shared
+            // walker does a bounded BFS.
             const requested = args.parentId;
-            const fetchLevel = async (deptId) => {
-                const query = deptId === undefined ? {} : { deptIds: deptId };
-                const data = (await wireCall(session, { path: ENDPOINTS.organizationDepartmentTree, query })).data;
-                return Array.isArray(data?.departmentList) ? data.departmentList : wireRows(data);
-            };
-            const levels = [];
-            const seen = new Set();
-            const push = (rows) => {
-                for (const row of rows) {
-                    const id = String(row.id ?? "");
-                    if (id === "" || seen.has(id))
-                        continue;
-                    seen.add(id);
-                    levels.push(row);
-                }
-            };
-            if (requested === undefined) {
-                push(await fetchLevel(undefined));
-            }
-            else {
-                // `deptIds=<id>` returns the subtree BELOW that department, excluding
-                // it (live 2026-10-22). A caller asking for `parentId` expects that
-                // department itself too, so add it from the authoritative record.
-                try {
-                    const self = (await wireCall(session, { path: ENDPOINTS.organizationDepartmentGet, query: { deptId: requested } })).data;
-                    if (self)
-                        push([self]);
-                }
-                catch {
-                    // an unknown id simply yields an empty list
-                }
-                push(await fetchLevel(requested));
-            }
-            for (const root of levels.filter((row) => String(row.parentId ?? "") === "" || requested !== undefined).map((row) => String(row.id ?? ""))) {
-                if (seen.size >= 500)
-                    break;
-                push(await fetchLevel(root));
-            }
+            const walked = await collectOrgDepartments(session, requested === undefined ? {} : { rootId: requested });
+            const levels = walked.rows;
             const departments = levels.map((dept) => ({
                 id: dept.id ?? null,
                 name: dept.name ?? null,
@@ -3112,33 +3160,10 @@ export function registerWorkflowLane(tools) {
             if (!keyword) {
                 return governedRead(ctx, self, args, async (session) => {
                     const orgQuery = { corpId: session.enterpriseId() };
-                    const seenDepartments = new Set();
-                    const order = [];
-                    const pushRows = (rows) => {
-                        for (const row of rows) {
-                            const id = String(row.id ?? "");
-                            if (id === "" || seenDepartments.has(id))
-                                continue;
-                            seenDepartments.add(id);
-                            order.push(id);
-                        }
-                    };
-                    // `/department/tree` answers `{departmentList:[...]}`, not a bare array;
-                    // `wireRows` only understands arrays/page envelopes.
-                    const treeRows = async (deptId) => {
-                        const data = (await wireCall(session, {
-                            path: ENDPOINTS.organizationDepartmentTree,
-                            query: deptId === undefined ? orgQuery : { ...orgQuery, deptIds: deptId },
-                        })).data;
-                        return Array.isArray(data?.departmentList) ? data.departmentList : [];
-                    };
-                    pushRows(await treeRows());
-                    // `deptIds` returns the subtree BELOW that department; walk the roots.
-                    for (const rootId of [...order]) {
-                        if (order.length >= 200)
-                            break;
-                        pushRows(await treeRows(rootId));
-                    }
+                    // r15: `deptIds` answers DIRECT CHILDREN only, so the earlier
+                    // roots + one-level walk missed users in third-level departments.
+                    const walked = await collectOrgDepartments(session, { limit: 200 });
+                    const order = walked.rows.map((row) => row.id);
                     const seenUsers = new Map();
                     let departmentsScanned = 0;
                     for (const deptId of order.slice(0, 200)) {
@@ -3163,7 +3188,7 @@ export function registerWorkflowLane(tools) {
                         count: users.length,
                         total: users.length,
                         departmentsScanned,
-                        ...(order.length > 200 ? { truncated: true, note: `部门树超过 200 个，只聚合了前 200 个；用 wd 关键字精确检索` } : {}),
+                        ...(walked.truncated || order.length >= 200 ? { truncated: true, note: `部门树超过 200 个，只聚合了前 200 个；用 wd 关键字精确检索` } : {}),
                         users,
                         hint: "无关键字=列全员（按部门树聚合）。平台 user/search 的 wd 不支持空串（10005），所以这条路径走 department/list_user；只要某部门的人用 org.department.users。",
                     };