@stalfh233/omc-cli 0.4.73 → 0.4.75

package/dist/lanes/organization.js

@@ -0,0 +1,662 @@
+import { z } from "zod";
+import { ToolInputError, ToolRefusalError } from "../tool-types.js";
+import { defineTool } from "../tool-types.js";
+import { governedRead } from "../read.js";
+import { writeTool } from "../write.js";
+import { wireCall, wireRows, WireError } from "../wire.js";
+import { ENDPOINTS } from "../endpoints.js";
+import { environmentArg, capabilityArg } from "../args.js";
+import { LANES } from "./lane-ids.js";
+/**
+ * Organization WRITE faces (8.6.41 customer transcript, 2026-10-21).
+ *
+ * The read faces already existed (org.role.list / org.department.list /
+ * org.user.search); the customer's manual work was entirely writes: create a
+ * role group ("分组" in the UI is a role), create roles under it, add members,
+ * and set each member's management scope. Those are now first-class tools.
+ *
+ * Three wire quirks are encoded here because every one of them cost the
+ * customer a failed round:
+ *  - `corpId` must ride the QUERY (a self-maintained org uses the literal
+ *    "other" in the body), not only the header;
+ *  - `add_role_user` wants `unitType` as a STRING "3", `update_ouscope` wants
+ *    the INT 3;
+ *  - `update_ouscope` is REPLACE semantics with no rollback, so the tool reads
+ *    the current scope and merges by default (`replace:true` is explicit).
+ */
+const LANE = LANES.workflow;
+const SCOPE = "organization role/member/scope lifecycle via /api/api/organization/role/*";
+const SCOPES = {
+    roleUsers: "organization role member read (role/users)",
+    userScope: "organization role member management scope read (role/get_ouscope)",
+    groupCreate: "organization role group create (role/add_role_group)",
+    roleCreate: "organization role create (role/add_role)",
+    roleUpdate: "organization role update (role/modify_role)",
+    addUsers: "organization role member add (role/add_role_user)",
+    removeUsers: "organization role member remove (role/strike_out_role_user)",
+    setScope: "organization role member scope update (role/update_ouscope)",
+    roleDelete: "organization role delete (role/strike_out_role)",
+    roleGroupDelete: "organization role group delete (role/strike_out_role_group)",
+    userTransfer: "organization user department transfer (user/dept_transfer)",
+    deptCreate: "organization department create (department/add)",
+    deptUpdate: "organization department update (department/modefied)",
+    deptDelete: "organization department delete (department/strike_out)",
+    deptUsers: "organization department member read (department/list_user)",
+    userCreate: "organization user create (user/add)",
+    userUpdate: "organization user update (user/modify)",
+    userDelete: "organization user delete (user/strike_out)",
+    userInfo: "organization user read (user/info)",
+    userDepartments: "organization user department read (user/departments)",
+};
+/**
+ * `DeptType` is a Jackson enum over INT indices: writing the readable
+ * "dept"/"DEPT" answers 10009 「类型转换异常: not one of [0,1,2,3]」 (live
+ * 2026-10-22, 1.1.25). Accept the names and map them.
+ */
+const DEPT_TYPE_CODES = Object.freeze({
+    DEPT: 0, DEPARTMENT: 0, 部门: 0,
+    EDU_DEPT: 1, 家校部门: 1,
+    YUNS_DEPT: 2, 云枢部门: 2,
+    VIRTUAL_EDU_DEPT: 3, 虚拟家校部门: 3,
+});
+function deptTypeCode(value) {
+    if (value === undefined)
+        return 0;
+    if (typeof value === "number") {
+        if (!Number.isInteger(value) || value < 0 || value > 3)
+            throw new ToolInputError({ status: "error", blocker: "tool-input-invalid", tool: "org.department.create", message: `deptType ${String(value)} 不在 0..3（0=部门 1=家校部门 2=云枢部门 3=虚拟家校部门）` });
+        return value;
+    }
+    const code = DEPT_TYPE_CODES[String(value).trim().toUpperCase()] ?? DEPT_TYPE_CODES[String(value).trim()];
+    if (code === undefined)
+        throw new ToolInputError({ status: "error", blocker: "tool-input-invalid", tool: "org.department.create", message: `deptType "${String(value)}" 不认识；可用 ${Object.keys(DEPT_TYPE_CODES).join("、")} 或整数 0..3` });
+    return code;
+}
+const orgQuery = (session) => ({ corpId: session.enterpriseId() });
+const roleUserId = (row) => String(row.id ?? row.userId ?? row.recId ?? "");
+async function memberRows(session, roleId) {
+    const data = (await wireCall(session, {
+        path: ENDPOINTS.organizationRoleUsers,
+        query: { ...orgQuery(session), roleId, page: "0", size: "500" },
+    })).data;
+    return Array.isArray(data?.content) ? data.content : wireRows(data);
+}
+async function removeMembers(session, roleId, userIds) {
+    if (userIds.length === 0)
+        return;
+    await wireCall(session, {
+        path: ENDPOINTS.organizationRoleRemoveUser, method: "POST", query: orgQuery(session),
+        body: { roleId, userIds },
+    });
+}
+async function rolesInGroup(session, roleGroupId) {
+    // `expandAll=true` is mandatory: without it /role/list only fills the FIRST
+    // group's children, so roles under any other group read back as absent.
+    const data = (await wireCall(session, { path: ENDPOINTS.organizationRoleList, query: { expandAll: "true" } })).data;
+    const roles = [];
+    const walk = (rows, inside) => {
+        for (const row of rows) {
+            const isGroup = row.group === true || (row.group === undefined && Array.isArray(row.children) && row.children.length > 0);
+            const id = String(row.id ?? "");
+            if (inside || (isGroup && id === roleGroupId)) {
+                if (!isGroup && id !== "")
+                    roles.push({ id, name: String(row.name ?? "") });
+            }
+            if (Array.isArray(row.children))
+                walk(row.children, inside || (isGroup && id === roleGroupId));
+        }
+    };
+    walk(wireRows(data), false);
+    return roles;
+}
+export function registerOrganizationLane(tools) {
+    tools.push(defineTool({
+        name: "org.role.users",
+        layer: "low",
+        kind: "read",
+        lane: LANE,
+        scope: SCOPES.roleUsers,
+        description: "列出角色成员（`GET organization/role/users`）。返回 members[{id(recId),name,...}]；**id 是 recId，不是账号**（addUsers/setUserScope 都传它）。",
+        inputSchema: {
+            environment: environmentArg,
+            roleId: z.string().min(1).describe("角色 id（不是角色 code）"),
+            page: z.number().int().min(0).optional(),
+            size: z.number().int().min(1).max(500).optional(),
+            capability: capabilityArg,
+        },
+        handler: async (ctx, args, self) => governedRead(ctx, self, args, async (session) => {
+            const data = (await wireCall(session, {
+                path: ENDPOINTS.organizationRoleUsers,
+                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);
+            const members = rows.map((row) => ({
+                id: roleUserId(row),
+                name: row.name ?? null,
+                username: row.username ?? null,
+                departmentId: row.departmentId ?? null,
+                unitType: row.unitType ?? null,
+            }));
+            return { roleId: String(args.roleId), count: members.length, total: data?.totalElements ?? members.length, members };
+        }),
+    }));
+    tools.push(defineTool({
+        name: "org.role.userScope",
+        layer: "low",
+        kind: "read",
+        lane: LANE,
+        scope: SCOPES.userScope,
+        description: "读成员的管理范围（`GET organization/role/get_ouscope`）。`type:\"1\"`=部门节点；update_ouscope 是覆盖语义，改前先读。",
+        inputSchema: {
+            environment: environmentArg,
+            roleId: z.string().min(1),
+            userId: z.string().min(1).describe("成员的用户记录 id（recId）"),
+            capability: capabilityArg,
+        },
+        handler: async (ctx, args, self) => governedRead(ctx, self, args, async (session) => {
+            const data = (await wireCall(session, {
+                path: ENDPOINTS.organizationRoleGetOuScope,
+                query: { ...orgQuery(session), roleId: String(args.roleId), userId: String(args.userId) },
+            })).data;
+            const scopes = wireRows(data).map((row) => ({ id: row.id ?? null, name: row.name ?? null, type: row.type ?? null, deptPath: row.deptPath ?? null }));
+            return { roleId: String(args.roleId), userId: String(args.userId), count: scopes.length, scopes };
+        }),
+    }));
+    writeTool(tools, "org.roleGroup.create", LANE, SCOPES.groupCreate, "创建角色组（`POST organization/role/add_role_group`）。返回 roleGroupId，角色挂在它下面。**corpId 默认写当前企业**（`session.enterpriseId()`）：平台的 `corpId` 只从 body 取，body 缺省时才按 parentId 反查企业设置，查不到就 NPE（被吞成 errcode 0）；`corpId=\"other\"` 是平台合法的「非组织分组」语义，只有明确要建非组织分组时才传。", {
+        roleGroupName: z.string().min(1).describe("角色组名称（界面显示的分组名）"),
+        parentId: z.string().min(1).describe("上级角色组 id。**必填**：1.1.25 的 add_role_group 会先 getByParentId(parentId)，空值直接 Preconditions 异常（50000 parentIds cannot be empty）；顶层组请传现有组 id（如「默认」组），平台允许嵌套"),
+        code: z.string().optional(),
+        corpId: z.string().min(1).optional().describe("组织 corpId，默认当前登录企业；传 \"other\" 表示非组织分组（该组在组织管理里不归属任何企业）"),
+    }, async (session, args) => {
+        const corpId = args.corpId ?? session.enterpriseId();
+        const data = (await wireCall(session, {
+            path: ENDPOINTS.organizationRoleAddGroup, method: "POST",
+            query: orgQuery(session),
+            body: { roleGroupName: args.roleGroupName, corpId, ...(args.parentId ? { parentId: args.parentId } : {}), ...(args.code ? { code: args.code } : {}) },
+        })).data;
+        const roleGroupId = String(data?.roleGroupId ?? data?.id ?? "");
+        if (!roleGroupId)
+            throw new ToolRefusalError({ status: "refused", blocker: "wire-shape", message: "平台未返回 roleGroupId；不要假设创建成功，先 org.role.list 回读" });
+        const readbackCorpId = data?.corpId ?? null;
+        // The platform takes corpId from the body verbatim (RoleGroupHelper
+        // .createRoleGroupModel, 1.1.25): a silent rewrite means the value we sent
+        // did not land, and participants built from this group would not resolve
+        // in the org tree.
+        const corpIdHonoured = readbackCorpId === null || String(readbackCorpId) === corpId;
+        return {
+            performed: { errcode: 0 },
+            readback: {
+                roleGroupId,
+                roleGroupName: data?.roleGroupName ?? args.roleGroupName,
+                code: data?.code ?? null,
+                corpId: readbackCorpId,
+                ...(corpIdHonoured ? {} : { warning: `平台回读 corpId=${String(readbackCorpId)}，与请求的 ${corpId} 不一致；该组可能不归属当前企业，先 org.role.list 核对` }),
+            },
+        };
+    });
+    writeTool(tools, "org.role.create", LANE, SCOPES.roleCreate, "创建角色（界面「分组」；`POST organization/role/add_role`）。返回 roleId；code 创建时 null、随后补 SYS<时间戳>，要稳定编码就传 code。", {
+        roleName: z.string().min(1),
+        roleGroupId: z.string().min(1).describe("所属角色组 id（org.role.list 的 groups[].id）"),
+        roleGroupName: z.string().optional(),
+        roleType: z.enum(["SYS", "CUSTOMIZE", "OTHER"]).optional().describe("默认 SYS（平台会把角色统一落成 SYS，见 RoleHelper.createRoleModel）"),
+        code: z.string().optional(),
+        remarks: z.string().optional(),
+        corpId: z.string().min(1).optional().describe("组织 corpId，默认当前登录企业；传 \"other\" 表示非组织分组角色"),
+    }, async (session, args) => {
+        const corpId = args.corpId ?? session.enterpriseId();
+        const data = (await wireCall(session, {
+            path: ENDPOINTS.organizationRoleAdd, method: "POST",
+            query: orgQuery(session),
+            body: {
+                roleName: args.roleName,
+                roleGroupId: args.roleGroupId,
+                ...(args.roleGroupName ? { roleGroupName: args.roleGroupName } : {}),
+                roleType: args.roleType ?? "SYS",
+                corpId,
+                ...(args.code ? { code: args.code } : {}),
+                ...(args.remarks ? { remarks: args.remarks } : {}),
+            },
+        })).data;
+        const roleId = String(data?.roleId ?? data?.id ?? "");
+        if (!roleId)
+            throw new ToolRefusalError({ status: "refused", blocker: "wire-shape", message: "平台未返回 roleId；先 org.role.list 回读确认" });
+        const readbackCorpId = data?.corpId ?? null;
+        return {
+            performed: { errcode: 0 },
+            readback: {
+                roleId,
+                roleName: data?.roleName ?? args.roleName,
+                code: data?.code ?? null,
+                corpId: readbackCorpId,
+                ...(readbackCorpId === null || String(readbackCorpId) === corpId ? {} : { warning: `平台回读 corpId=${String(readbackCorpId)}，与请求的 ${corpId} 不一致` }),
+            },
+        };
+    });
+    // ── department ────────────────────────────────────────────────────────────
+    writeTool(tools, "org.department.create", LANE, SCOPES.deptCreate, "新建部门（`POST organization/department/add`）。**1.1.25 平台强制 parentId**（省略会 200007「部门parentId不能为空！」）——省略时工具自动取部门树的第一个根部门作父级；deptType 传名字或 0..3（平台按 int 枚举反序列化，写 \"dept\" 会 10009）。返回 deptId。", {
+        name: z.string().min(1).describe("部门名称"),
+        parentId: z.string().min(1).optional().describe("上级部门 id；省略则自动挂到部门树的第一个根部门（1.1.25 不接受空 parentId）"),
+        deptType: z.union([z.string(), z.number().int()]).optional().describe("默认 0=部门；1=家校部门 2=云枢部门 3=虚拟家校部门"),
+        code: z.string().optional(),
+        managerId: z.string().optional().describe("部门主管的用户 id"),
+        sortKey: z.number().int().optional(),
+        remarks: z.string().optional(),
+    }, async (session, args) => {
+        // department/add answers 200007 「部门parentId不能为空！」 on an empty
+        // parentId (live 1.1.25, r10 F5). Resolve the tree's first root instead of
+        // forwarding an omission the platform rejects.
+        let parentId = args.parentId;
+        if (!parentId) {
+            const treeData = (await wireCall(session, { path: ENDPOINTS.organizationDepartmentTree })).data;
+            // `/department/tree` answers `{departmentList:[…]}` (the same shape
+            // org.department.list handles); wireRows alone would throw
+            // "expected row array in envelope data".
+            const roots = Array.isArray(treeData?.departmentList) ? treeData.departmentList : wireRows(treeData);
+            const root = roots.find((row) => {
+                const pid = row.parentId;
+                return pid === undefined || pid === null || pid === "";
+            });
+            parentId = root ? String(root.id ?? "") : "";
+            if (!parentId)
+                throw new ToolRefusalError({ status: "refused", blocker: "org-department-root-absent", message: "部门树没有任何根部门，无法推断 parentId；平台 1.1.25 不接受空 parentId，请先建根部门或显式传 parentId" });
+        }
+        const data = (await wireCall(session, {
+            path: ENDPOINTS.organizationDepartmentAdd, method: "POST", query: orgQuery(session),
+            body: {
+                name: args.name, corpId: session.enterpriseId(), unitType: "1", enabled: true, deptType: deptTypeCode(args.deptType),
+                parentId,
+                ...(args.code ? { code: args.code } : {}),
+                ...(args.managerId ? { managerId: args.managerId } : {}),
+                ...(args.sortKey !== undefined ? { sortKey: args.sortKey } : {}),
+                ...(args.remarks ? { remarks: args.remarks } : {}),
+            },
+        })).data;
+        const deptId = String(data?.id ?? "");
+        if (!deptId)
+            throw new ToolRefusalError({ status: "refused", blocker: "wire-shape", message: "平台未返回部门 id；先 org.department.list 回读确认" });
+        return { performed: { errcode: 0 }, readback: { deptId, name: data?.name ?? args.name, parentId: data?.parentId ?? args.parentId ?? null, code: data?.code ?? null } };
+    });
+    writeTool(tools, "org.department.update", LANE, SCOPES.deptUpdate, "改部门（`POST organization/department/modefied`）。先 get_dept_info 读现状再合并提交，只传要改的字段（名称/上级/主管/排序/备注/启用）。", {
+        deptId: z.string().min(1),
+        name: z.string().optional(),
+        parentId: z.string().optional(),
+        managerId: z.string().optional(),
+        sortKey: z.number().int().optional(),
+        remarks: z.string().optional(),
+        enabled: z.boolean().optional(),
+    }, async (session, args) => {
+        const current = (await wireCall(session, { path: ENDPOINTS.organizationDepartmentGet, query: { ...orgQuery(session), deptId: args.deptId } })).data;
+        if (!current)
+            throw new ToolRefusalError({ status: "refused", blocker: "wire-shape", message: `get_dept_info 未返回部门 ${args.deptId}` });
+        const body = {
+            ...current,
+            ...(args.name !== undefined ? { name: args.name } : {}),
+            ...(args.parentId !== undefined ? { parentId: args.parentId } : {}),
+            ...(args.managerId !== undefined ? { managerId: args.managerId } : {}),
+            ...(args.sortKey !== undefined ? { sortKey: args.sortKey } : {}),
+            ...(args.remarks !== undefined ? { remarks: args.remarks } : {}),
+            ...(args.enabled !== undefined ? { enabled: args.enabled } : {}),
+        };
+        await wireCall(session, { path: ENDPOINTS.organizationDepartmentModify, method: "POST", query: orgQuery(session), body });
+        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) => {
+        const users = wireRows((await wireCall(session, { path: ENDPOINTS.organizationDepartmentUsers, query: { ...orgQuery(session), deptId: args.deptId } })).data);
+        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 } };
+    });
+    tools.push(defineTool({
+        name: "org.department.users",
+        layer: "low", kind: "read", lane: LANE, scope: SCOPES.deptUsers,
+        description: "列出部门下的员工（`GET organization/department/list_user?deptId=`）。返回 members[{id(recId),name,username,mobile}]。",
+        inputSchema: { environment: environmentArg, deptId: z.string().min(1), capability: capabilityArg },
+        handler: async (ctx, args, self) => governedRead(ctx, self, args, async (session) => {
+            const data = (await wireCall(session, { path: ENDPOINTS.organizationDepartmentUsers, query: { ...orgQuery(session), deptId: String(args.deptId) } })).data;
+            const members = wireRows(data).map((row) => ({ id: row.id ?? row.userId ?? null, name: row.name ?? null, username: row.username ?? null, mobile: row.mobile ?? null }));
+            return { deptId: String(args.deptId), count: members.length, members };
+        }),
+    }));
+    // ── employee ──────────────────────────────────────────────────────────────
+    writeTool(tools, "org.user.create", LANE, SCOPES.userCreate, "新建员工账号（`POST organization/user/add`）。必填 name/username/departmentId；工具自动补 `userLabelIds:[]`、`userManagerConfigList:[]`、`roleIds:[]` —— 平台 dealUserLabel 对 null 直接 NPE（50000，真机 1.1.25）。返回 userId(recId)；初始密码由平台默认策略生成。", {
+        name: z.string().min(1),
+        username: z.string().min(1).describe("登录账号"),
+        departmentId: z.string().min(1).describe("所属部门 id（必须先存在，否则 201011「用户的部门不存在！」）"),
+        mobile: z.string().optional(),
+        email: z.string().optional(),
+        employeeNo: z.string().optional(),
+        gender: z.enum(["MALE", "FEMALE", "OTHER"]).optional(),
+        roleIds: z.array(z.string()).optional().describe("同时授予的角色 id"),
+        partTimeDeptIds: z.array(z.string()).optional().describe("兼职部门 id（主部门仍是 departmentId）"),
+        deptIds: z.array(z.string()).optional().describe("`partTimeDeptIds` 的别名"),
+        userLabelIds: z.array(z.string()).optional(),
+        active: z.boolean().optional(),
+        status: z.enum(["ENABLE", "DISABLE", "LOCK"]).optional(),
+    }, async (session, args) => {
+        const data = (await wireCall(session, {
+            path: ENDPOINTS.organizationUserAdd, method: "POST", query: orgQuery(session),
+            body: {
+                name: args.name, username: args.username, departmentId: args.departmentId, currentDeptId: args.departmentId,
+                corpId: session.enterpriseId(), unitType: "3", enabled: true, active: args.active ?? true,
+                status: args.status ?? "ENABLE",
+                userLabelIds: args.userLabelIds ?? [], userManagerConfigList: [], roleIds: args.roleIds ?? [], deptIds: args.partTimeDeptIds ?? args.deptIds ?? [],
+                ...(args.mobile ? { mobile: args.mobile } : {}),
+                ...(args.email ? { email: args.email } : {}),
+                ...(args.employeeNo ? { employeeNo: args.employeeNo } : {}),
+                ...(args.gender ? { gender: args.gender } : {}),
+            },
+        })).data;
+        const userId = String(data?.id ?? "");
+        if (!userId)
+            throw new ToolRefusalError({ status: "refused", blocker: "wire-shape", message: "平台未返回用户 id；先 org.user.search 回读确认" });
+        return { performed: { errcode: 0 }, readback: { userId, name: data?.name ?? args.name, username: data?.username ?? args.username, departmentId: data?.departmentId ?? args.departmentId } };
+    });
+    writeTool(tools, "org.user.update", LANE, SCOPES.userUpdate, "改员工（`POST organization/user/modify`）。先 user/info 读现状再合并；工具强制补 `deptIds:[]` 等四个数组——平台 modified 对 null 的 deptIds 直接 NPE（50000，真机 1.1.25）。可改姓名/部门/手机/邮箱/角色/启停。", {
+        userId: z.string().min(1),
+        name: z.string().optional(),
+        departmentId: z.string().optional(),
+        mobile: z.string().optional(),
+        email: z.string().optional(),
+        employeeNo: z.string().optional(),
+        gender: z.enum(["MALE", "FEMALE", "OTHER"]).optional(),
+        roleIds: z.array(z.string()).optional(),
+        partTimeDeptIds: z.array(z.string()).optional().describe("兼职部门 id；**覆盖语义**（传 [] 清空兼职，主部门不变）"),
+        active: z.boolean().optional(),
+        status: z.enum(["ENABLE", "DISABLE", "LOCK"]).optional(),
+    }, async (session, args) => {
+        const current = (await wireCall(session, { path: ENDPOINTS.organizationUserInfo, query: { ...orgQuery(session), id: args.userId } })).data;
+        if (!current)
+            throw new ToolRefusalError({ status: "refused", blocker: "wire-shape", message: `user/info 未返回用户 ${args.userId}` });
+        const body = {
+            ...current,
+            id: args.userId,
+            ...(args.name !== undefined ? { name: args.name } : {}),
+            ...(args.departmentId !== undefined ? { departmentId: args.departmentId, currentDeptId: args.departmentId } : {}),
+            ...(args.mobile !== undefined ? { mobile: args.mobile } : {}),
+            ...(args.email !== undefined ? { email: args.email } : {}),
+            ...(args.employeeNo !== undefined ? { employeeNo: args.employeeNo } : {}),
+            ...(args.gender !== undefined ? { gender: args.gender } : {}),
+            ...(args.active !== undefined ? { active: args.active } : {}),
+            ...(args.status !== undefined ? { status: args.status } : {}),
+            deptIds: args.partTimeDeptIds ?? (Array.isArray(current.deptIds) ? current.deptIds : []),
+            userLabelIds: Array.isArray(current.userLabelIds) ? current.userLabelIds : [],
+            userManagerConfigList: Array.isArray(current.userManagerConfigList) ? current.userManagerConfigList : [],
+            roleIds: args.roleIds ?? (Array.isArray(current.roleIds) ? current.roleIds : []),
+        };
+        await wireCall(session, { path: ENDPOINTS.organizationUserModify, method: "POST", query: orgQuery(session), body });
+        const after = (await wireCall(session, { path: ENDPOINTS.organizationUserInfo, query: { ...orgQuery(session), id: args.userId } })).data;
+        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 } };
+    });
+    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 } });
+        return { performed: { errcode: 0 }, readback: { userId: args.userId, deleted: true } };
+    });
+    tools.push(defineTool({
+        name: "org.user.info",
+        layer: "low", kind: "read", lane: LANE, scope: SCOPES.userInfo,
+        description: "读员工详情（`GET organization/user/info?id=`）。返回姓名/账号/部门/手机/邮箱/状态/角色 id 等。",
+        inputSchema: { environment: environmentArg, userId: z.string().min(1), capability: capabilityArg },
+        handler: async (ctx, args, self) => governedRead(ctx, self, args, async (session) => {
+            let data = null;
+            try {
+                data = (await wireCall(session, { path: ENDPOINTS.organizationUserInfo, query: { ...orgQuery(session), id: String(args.userId) } })).data;
+            }
+            catch (error) {
+                // A deleted/unknown user answers 10011 (业务模型不存在-style business
+                // error) rather than an empty body; "read a user" should not turn an
+                // absence into a refusal.
+                if (!(error instanceof WireError) || error.errcode !== 10011)
+                    throw error;
+            }
+            if (!data)
+                return { userId: String(args.userId), exists: false };
+            return {
+                userId: String(args.userId), exists: true,
+                name: data.name ?? null, username: data.username ?? null, departmentId: data.departmentId ?? null,
+                mobile: data.mobile ?? null, email: data.email ?? null, active: data.active ?? null,
+                // `status` is reserved by the tool envelope (ok/refused/…): a user's
+                // ENABLE/DISABLE value under that key made the read look like a failed
+                // tool call (live 2026-10-22).
+                userStatus: data.status ?? null,
+                roleIds: Array.isArray(data.roleIds) ? data.roleIds : [],
+            };
+        }),
+    }));
+    tools.push(defineTool({
+        name: "org.user.departments",
+        layer: "low", kind: "read", lane: LANE, scope: SCOPES.userDepartments,
+        description: "读员工所属部门（含兼职，`GET organization/user/departments?id=`）。返回 departments[{deptId,deptName,isMain}]。",
+        inputSchema: { environment: environmentArg, userId: z.string().min(1), capability: capabilityArg },
+        handler: async (ctx, args, self) => governedRead(ctx, self, args, async (session) => {
+            const data = (await wireCall(session, { path: ENDPOINTS.organizationUserDepartments, query: { ...orgQuery(session), id: String(args.userId) } })).data;
+            const departments = wireRows(data).map((row) => ({ deptId: row.deptId ?? null, deptName: row.deptName ?? null, isMain: row.isMain ?? null }));
+            return { userId: String(args.userId), count: departments.length, departments };
+        }),
+    }));
+    writeTool(tools, "org.role.delete", LANE, SCOPES.roleDelete, "删除角色（`GET organization/role/strike_out_role?ids=`）。平台**拒绝删除仍有成员的角色**（`-1 角色下已经包含用户数据！`，实测 1.1.25）：默认先读成员数、非空即拒绝并给出人数；`force:true` 才会先逐人移出再删。", {
+        roleId: z.string().min(1),
+        force: z.boolean().optional().describe("true = 先移出全部成员再删角色"),
+    }, async (session, args) => {
+        const rows = await memberRows(session, String(args.roleId));
+        if (rows.length > 0 && args.force !== true)
+            throw new ToolRefusalError({
+                status: "refused", blocker: "role-has-members", roleId: String(args.roleId), members: rows.length,
+                message: `角色下还有 ${rows.length} 名成员，平台拒绝删除（errmsg：角色下已经包含用户数据）。先 org.role.removeUsers，或传 force:true 让工具移出后再删。`,
+            });
+        if (rows.length > 0)
+            await removeMembers(session, String(args.roleId), rows.map(roleUserId));
+        await wireCall(session, { path: ENDPOINTS.organizationRoleDelete, query: { ...orgQuery(session), ids: String(args.roleId) } });
+        return { performed: { errcode: 0 }, readback: { roleId: String(args.roleId), deleted: true, removedMembers: rows.length } };
+    });
+    writeTool(tools, "org.roleGroup.delete", LANE, SCOPES.roleGroupDelete, "删除角色组（`GET organization/role/strike_out_role_group?ids=`）。平台**拒绝删除仍含角色的组**（`-1 角色组下已经包含角色数据！`）：默认先数角色、非空即拒绝；`force:true` 会逐个删角色（含其成员）再删组。", {
+        roleGroupId: z.string().min(1),
+        force: z.boolean().optional(),
+    }, async (session, args) => {
+        const roles = await rolesInGroup(session, String(args.roleGroupId));
+        if (roles.length > 0 && args.force !== true)
+            throw new ToolRefusalError({
+                status: "refused", blocker: "role-group-has-roles", roleGroupId: String(args.roleGroupId), roles: roles.length,
+                message: `角色组下还有 ${roles.length} 个角色，平台拒绝删除（errmsg：角色组下已经包含角色数据）。先删角色，或传 force:true。`,
+            });
+        for (const role of roles) {
+            const members = await memberRows(session, role.id);
+            if (members.length > 0)
+                await removeMembers(session, role.id, members.map(roleUserId));
+            await wireCall(session, { path: ENDPOINTS.organizationRoleDelete, query: { ...orgQuery(session), ids: role.id } });
+        }
+        await wireCall(session, { path: ENDPOINTS.organizationRoleGroupDelete, query: { ...orgQuery(session), ids: String(args.roleGroupId) } });
+        return { performed: { errcode: 0 }, readback: { roleGroupId: String(args.roleGroupId), deleted: true, removedRoles: roles.map((role) => role.id) } };
+    });
+    writeTool(tools, "org.user.transferDepartment", LANE, SCOPES.userTransfer, "把员工从一个部门移到另一个部门（`POST organization/user/dept_transfer`，body `{userIds,sourceDept,targetDept}`）。sourceDept 必填（缺它 50000）；移动后原部门不再包含该员工，主部门保持。", {
+        userId: z.string().min(1),
+        fromDeptId: z.string().min(1).describe("原部门 id（必填）"),
+        toDeptId: z.string().min(1).describe("目标部门 id"),
+    }, async (session, args) => {
+        await wireCall(session, {
+            path: ENDPOINTS.organizationUserDeptTransfer, method: "POST", query: orgQuery(session),
+            body: { userIds: [String(args.userId)], sourceDept: String(args.fromDeptId), targetDept: String(args.toDeptId) },
+        });
+        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: String(args.userId), fromDeptId: String(args.fromDeptId), toDeptId: String(args.toDeptId), departments } };
+    });
+    writeTool(tools, "org.role.update", LANE, SCOPES.roleUpdate, "改角色名称/编码/备注/所属角色组（`POST organization/role/modify_role`）。先读现状再提交，只传要改的字段。**平台要求 roleGroupId 必填**（缺则 202012「角色组主键Id不能为空」），工具默认回填当前组；**corpId 不可改**（RoleHelper.update 不读该字段），要换企业只能在目标企业下重建角色。", {
+        roleId: z.string().min(1),
+        roleName: z.string().optional(),
+        roleGroupId: z.string().min(1).optional().describe("移到别的角色组（默认保持当前组）。平台 update 必填该字段，且目标组必须存在、roleType=SYS"),
+        code: z.string().optional(),
+        remarks: z.string().optional(),
+    }, async (session, args) => {
+        const current = (await wireCall(session, { path: ENDPOINTS.organizationRoleGet, query: { ...orgQuery(session), roleId: String(args.roleId) } })).data;
+        if (!current)
+            throw new ToolRefusalError({ status: "refused", blocker: "wire-shape", message: `role/get 未返回角色 ${String(args.roleId)}；不要盲目 modify` });
+        // RoleHelper.update (1.1.25) validates roleName AND roleGroupId as
+        // REQUIRED before touching the row (validateRoleParam): a delta that omits
+        // either answers 202001 「角色名称不能为空」 / 202012 「角色组主键Id不能为空」.
+        // Both are backfilled from role/get, so a remarks-only edit works.
+        const roleName = String(args.roleName ?? current.roleName ?? current.name ?? "");
+        if (roleName === "")
+            throw new ToolRefusalError({ status: "refused", blocker: "wire-shape", message: `角色 ${String(args.roleId)} 读不到 roleName；平台 modify_role 要求该字段，请显式传 roleName` });
+        const roleGroupId = String(args.roleGroupId ?? current.roleGroupId ?? current.groupId ?? "");
+        if (roleGroupId === "")
+            throw new ToolRefusalError({ status: "refused", blocker: "wire-shape", message: `角色 ${String(args.roleId)} 读不到 roleGroupId；平台 modify_role 要求该字段，请显式传 roleGroupId` });
+        const body = {
+            ...current,
+            roleId: String(args.roleId),
+            roleName,
+            roleGroupId,
+            ...(args.code !== undefined ? { code: args.code } : {}),
+            ...(args.remarks !== undefined ? { remarks: args.remarks } : {}),
+            corpId: current.corpId ?? "other",
+            roleType: current.roleType ?? "SYS",
+        };
+        await wireCall(session, { path: ENDPOINTS.organizationRoleModify, method: "POST", query: orgQuery(session), body });
+        const after = (await wireCall(session, { path: ENDPOINTS.organizationRoleGet, query: { ...orgQuery(session), roleId: String(args.roleId) } })).data;
+        // role/get answers RoleModel (name/groupId), not RoleVO (roleName/
+        // roleGroupId) — read both spellings so the readback is never null.
+        return {
+            performed: { errcode: 0 },
+            readback: {
+                roleId: String(args.roleId),
+                roleName: after?.roleName ?? after?.name ?? null,
+                roleGroupId: after?.roleGroupId ?? after?.groupId ?? null,
+                code: after?.code ?? null,
+                remarks: after?.remarks ?? null,
+            },
+        };
+    });
+    writeTool(tools, "org.role.addUsers", LANE, SCOPES.addUsers, "加成员并（可选）一次设好管理范围（`add_role_user` + 逐人 `update_ouscope`，一个工具调用）。users[].id 必须是 recId（org.user.search 的 id）；传 `scopes` 会应用到本次新增的每个人。**平台的 add_role_user 虽然收 `ouScope` 但会忽略它**（实测 1.1.25，回读仍为空），所以范围必须单独写——工具内部已按顺序完成。加完回读成员与范围。", {
+        roleId: z.string().min(1),
+        users: z.array(z.object({ id: z.string().min(1).describe("用户记录 id（recId）"), name: z.string().min(1) })).min(1),
+        scopes: z.array(z.object({
+            id: z.string().min(1).describe("部门 id"),
+            name: z.string().min(1),
+            deptPath: z.string().optional(),
+            type: z.string().optional().describe("默认 \"1\"（部门节点）"),
+        })).optional().describe("应用到本次新增的每个成员的管​理范围；省略则不设（成员 ouScope 为空）"),
+        sortKey: z.number().int().optional(),
+        userIds: z.array(z.object({ id: z.string().min(1), name: z.string().min(1) })).optional().describe("`users` 的别名"),
+    }, async (session, args) => {
+        const users = args.users ?? args.userIds ?? [];
+        if (users.length === 0)
+            throw new ToolInputError({ status: "error", blocker: "tool-input-invalid", tool: "org.role.addUsers", message: "需要 users（或 userIds）至少一人" });
+        await wireCall(session, {
+            path: ENDPOINTS.organizationRoleAddUser, method: "POST",
+            query: orgQuery(session),
+            body: { roleId: args.roleId, sortKey: args.sortKey ?? 999, userIds: users.map((user) => ({ id: user.id, name: user.name, type: 3, unitType: "3" })) },
+        });
+        const readback = async () => {
+            const data = (await wireCall(session, {
+                path: ENDPOINTS.organizationRoleUsers,
+                query: { ...orgQuery(session), roleId: String(args.roleId), page: "0", size: "500" },
+            })).data;
+            return Array.isArray(data?.content) ? data.content : wireRows(data);
+        };
+        const rows = await readback();
+        const present = new Set(rows.map(roleUserId));
+        const added = users.filter((user) => present.has(user.id)).map((user) => user.id);
+        const missing = users.filter((user) => !present.has(user.id)).map((user) => user.id);
+        const scopeResults = [];
+        if (args.scopes !== undefined && args.scopes.length > 0) {
+            const ouScopeList = args.scopes.map((scope) => ({ id: scope.id, name: scope.name, type: scope.type ?? "1", ...(scope.deptPath ? { deptPath: scope.deptPath } : {}) }));
+            for (const id of added) {
+                await wireCall(session, {
+                    path: ENDPOINTS.organizationRoleUpdateOuScope, method: "POST", query: orgQuery(session),
+                    body: { roleId: String(args.roleId), userId: id, unitType: 3, sortKey: args.sortKey ?? 999, ouScopeList },
+                });
+                const scope = wireRows((await wireCall(session, {
+                    path: ENDPOINTS.organizationRoleGetOuScope,
+                    query: { ...orgQuery(session), roleId: String(args.roleId), userId: id },
+                })).data);
+                scopeResults.push({ userId: id, scopes: scope.length });
+            }
+        }
+        return {
+            performed: { errcode: 0 },
+            readback: {
+                roleId: String(args.roleId), added,
+                ...(missing.length > 0 ? { missing, hint: "这些 recId 未出现在成员列表：确认 id 是 recId、用户未离职/禁用" } : {}),
+                ...(scopeResults.length > 0 ? { scopeResults } : {}),
+                // ouScope 是流程角色参与人解析的过滤维度：平台
+                // ParticipantService.listManagerIdsByUserIdsAndRoleCode 用
+                // `h_org_role_user.ouScope ∩ 发起人部门链`，ouScope 为空 = 该成员
+                // 永远解析不到。没传 scopes 时把这条代价显式说出来（r9+r10 两次
+                // 真机坐实；不是 corpId 问题）。
+                ...(args.scopes === undefined || args.scopes.length === 0
+                    ? {
+                        warnings: [
+                            {
+                                code: "org-role-member-scope-empty",
+                                severity: "warning",
+                                message: "本次未传 scopes：新增成员的 ouScope 为空，**不能作为流程角色参与人被解析**（平台按 ouScope ∩ 发起人部门链过滤，r9/r10 真机坐实）。如果这个角色要用于审批/参与人，请补 scopes（部门节点）或随后调用 org.role.setUserScope；只用于权限分配可忽略。",
+                            },
+                        ],
+                    }
+                    : {}),
+                total: rows.length,
+            },
+        };
+    });
+    writeTool(tools, "org.role.removeUsers", LANE, SCOPES.removeUsers, "把成员移出角色（`POST organization/role/strike_out_role_user`）。**平台要求 JSON body `{roleId,userIds:[...]}`**——用 query 或 `ids` 会报 10009 `Required request body is missing`（实测 1.1.25）。只移出角色，不删用户。", {
+        roleId: z.string().min(1),
+        ids: z.array(z.string().min(1)).min(1).describe("要移出的成员 recId 列表"),
+    }, async (session, args) => {
+        await wireCall(session, {
+            path: ENDPOINTS.organizationRoleRemoveUser, method: "POST", query: orgQuery(session),
+            body: { roleId: String(args.roleId), userIds: args.ids },
+        });
+        const data = (await wireCall(session, {
+            path: ENDPOINTS.organizationRoleUsers,
+            query: { ...orgQuery(session), roleId: String(args.roleId), page: "0", size: "500" },
+        })).data;
+        const rows = Array.isArray(data?.content) ? data.content : wireRows(data);
+        const present = new Set(rows.map(roleUserId));
+        return { performed: { errcode: 0 }, readback: { roleId: String(args.roleId), removed: args.ids.filter((id) => !present.has(id)), stillPresent: args.ids.filter((id) => present.has(id)), total: data?.totalElements ?? rows.length } };
+    });
+    writeTool(tools, "org.role.setUserScope", LANE, SCOPES.setScope, "设置成员管理范围（`POST organization/role/update_ouscope`）。平台覆盖语义、无回滚：默认读旧值合并（mode:\"merge\"），mode:\"replace\" 才整体替换。unitType 传数字 3（addUsers 里是字符串 \"3\"）。节点 {id,name,type:\"1\",deptPath}。", {
+        roleId: z.string().min(1),
+        userId: z.string().min(1).describe("成员 recId"),
+        scopes: z.array(z.object({
+            id: z.string().min(1).describe("部门 id"),
+            name: z.string().min(1),
+            deptPath: z.string().optional().describe("完整路径，如 根组织/广州总所"),
+            type: z.string().optional().describe("默认 \"1\"（部门节点）"),
+        })).describe("要设置的管理范围节点"),
+        mode: z.enum(["merge", "replace"]).optional().describe("默认 merge（读旧值合并）；replace = 覆盖整个范围"),
+        dryRun: z.boolean().optional(),
+    }, async (session, args) => {
+        const before = wireRows((await wireCall(session, {
+            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 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]
+                .filter((row, index, all) => all.findIndex((candidate) => candidate.id === row.id) === index);
+        const removed = before.map((row) => String(row.id ?? "")).filter((id) => id !== "" && !merged.some((row) => row.id === id));
+        if (args.mode === "replace" && removed.length > 0)
+            // A data-loss write without an explicit acknowledgement is exactly the
+            // failure mode the customer hit manually; refuse unless replace was
+            // chosen deliberately (mode): the caller already opted in.
+            void removed;
+        await wireCall(session, {
+            path: ENDPOINTS.organizationRoleUpdateOuScope, method: "POST",
+            query: orgQuery(session),
+            body: { roleId: args.roleId, userId: args.userId, unitType: 3, sortKey: 999, ouScopeList: merged },
+        });
+        const after = wireRows((await wireCall(session, {
+            path: ENDPOINTS.organizationRoleGetOuScope,
+            query: { ...orgQuery(session), roleId: args.roleId, userId: args.userId },
+        })).data).map((row) => ({ id: row.id ?? null, name: row.name ?? null, type: row.type ?? null, deptPath: row.deptPath ?? null }));
+        return {
+            performed: { errcode: 0 },
+            readback: { roleId: args.roleId, userId: args.userId, mode: args.mode ?? "merge", before: before.length, after: after.length, scopes: after, ...(removed.length > 0 ? { removedScopeIds: removed } : {}) },
+        };
+    });
+}
+//# sourceMappingURL=organization.js.map