weaver-work-cli 0.1.7 → 0.1.20

package/dist/shortcuts/caizhilian/operations/handlers/folder.js

@@ -0,0 +1,969 @@
+import { CaizhilianCliError, caizhilianValidationError } from '../../errors.js';
+import { asList, asRecord, assertToleratedBusinessSuccess, buildFolderPermissionAddBody, checkCreateFolderPermission, checkSetFolderPermission, fetchFolderDefaultShareEntries, fetchFolderPermissionAuth, fetchFolderPermissionEntries, fetchFolderPermissions, isAlreadyExistsResponse, updateFolderPermissionAuth, } from '../api.js';
+import { issueWriteLease } from '../confirm.js';
+import { DEFAULT_SEC_LEVEL, buildObjTypeList, parseCascadeRules, parseCascadeRulesOuter, parseFieldCascadeRules, parseObjTypeOptions, parseParamOptions, parseSeclevelAllowed, } from '../form.js';
+import { fingerprint, isFalsyIds, isPlainObject, joinIds, parsePage, pyInt, pyRepr, requireId, requireIdList, requireNonEmpty, sortedJoin, } from '../shared.js';
+import { PERMISSION_TYPES, SETTING_TYPES, FOLDER_PERMISSION_KEYS } from '../specs.js';
+import { caizhilianPrepared, caizhilianSuccess } from '../types.js';
+/**
+ * 文件夹域操作（1:1 对应源 scripts/folder_plugins.py 的 14 个 plugin
+ * + doc-business-operations 的 3 个 http_template：
+ * query_folders_by_name / fetch_folder_default_settings / query_folder_permissions）。
+ *
+ * 写操作按 weaver-work-cli 规范拆成 prepare（只读回查 + 组装请求体 + 签发票据）
+ * 与 apply（真正产生副作用），业务请求体与源保持逐字段一致。
+ */
+// ── 源常量 ────────────────────────────────────────────────
+/** 源 CreateFolderPlugin._SEQ_MIN / _SEQ_MAX。 */
+const SEQ_MIN = -9999;
+const SEQ_MAX = 99999;
+/** 源 CreateFolderPlugin 的 parent_type 取值。 */
+const PARENT_TYPES = ['company', 'privy'];
+const FOLDER_CREATE_PATH = '/api/doc/folders/create';
+const QUERY_FOLDERS_BY_NAME_PATH = '/api/doc/folders/queryFoldersByName';
+const FOLDER_SETTINGS_PATH = '/api/doc/folderSetting/getFolderSettings';
+const DEFAULT_SHARE_ADD_PATH = '/api/doc/setting/default/share/add';
+const DEFAULT_SHARE_DELETE_PATH = '/api/doc/setting/default/share/delete';
+const PERMISSION_FORM_PATH = '/api/doc/permission/data/query';
+const PERMISSION_ADD_PATH = '/api/doc/folderSetting/share/add';
+const PERMISSION_DELETE_PATH = '/api/doc/folderSetting/share/delete';
+const QUERY_FOLDER_COUNT_PATH = '/api/doc/folderpermission/queryFoldersWithPermissionsCount';
+const QUERY_FOLDER_LIST_PATH = '/api/doc/folderpermission/queryFoldersWithPermissions';
+/** 源 query_folders_by_name.json 的 kb_type lookup（default = 200）。 */
+const KB_ROOT_FOLDER_ID = { company: '200', privy: '300', sys: '100' };
+const KB_ROOT_FOLDER_ID_DEFAULT = '200';
+const KB_TYPE_DEFAULT = 'company';
+/** 源 fetch_folder_default_settings 模板的固定 type 变量。 */
+const FOLDER_SETTING_TYPES_PARAM = 'folderDefaultShare,folderDefaultParticipants,defaultVirtualFolder';
+/** 源 FetchFolderSetDefaultShareFormPlugin._CATEGORY_API。 */
+const CATEGORY_API = {
+    creator: '/api/doc/permission/data/queryCreator',
+    generic: '/api/doc/permission/data/queryOther',
+};
+/** 源 AddFolderSetDefaultSharePlugin.user_overrides（顺序即写入顺序）。 */
+const SHARE_USER_OVERRIDES = [
+    'download',
+    'department_attribute',
+    'role_level',
+    'position_level',
+    'position_attribute',
+    'virtualCompany',
+    'createrPositionLevel',
+];
+/** 源 AddFolderSetDefaultSharePlugin.id_fields。 */
+const SHARE_ID_FIELDS = [
+    'obj_id',
+    'obj_id_department',
+    'obj_id_subcompany',
+    'obj_id_role',
+    'obj_id_group',
+    'obj_id_external',
+    'obj_id_customer',
+    'obj_id_customer_type',
+    'obj_id_position',
+    'obj_id_manager',
+    'obj_id_grade',
+];
+/** 源 folder_plugins._AUTH_CHECK_TYPES / _AUTH_TYPE_LABELS。 */
+const AUTH_CHECK_TYPES = ['downloadPremisstion', 'deletePremisstion'];
+const AUTH_TYPE_LABELS = {
+    downloadPremisstion: '下载权限',
+    deletePremisstion: '删除权限',
+};
+/** 源 folder_plugins._DETAIL_AUTH_TYPES / _DETAIL_TITLES / _DETAIL_AUTH_LABELS。 */
+const DETAIL_AUTH_TYPES = ['downloadPremisstion', 'deletePremisstion'];
+const DETAIL_TITLES = {
+    downloadPremisstion: '在此文件夹下能够下载附件',
+    deletePremisstion: '在此文件夹下能够删除文档',
+    newCreateDocPremisstion: '新建权限',
+    copyPermission: '复制权限',
+    movePermission: '移动权限',
+    settingPermission: '文件夹管理员',
+    newCreateFolderPremisstion: '文件夹维护权限',
+    folderDefaultParticipants: '默认参与人',
+    defaultShares: '默认共享人',
+};
+const DETAIL_AUTH_LABELS = {
+    downloadPremisstion: { true: '允许所有人下载', user: '允许以下人员下载', false: '不允许下载' },
+    deletePremisstion: { true: '允许完全控制权限人员删除文档', user: '允许以下人员删除文档' },
+};
+/** 源 query_folder_permissions.json 的固定 typeStr（白名单 4 项 + documentCreateSetting 派生）。 */
+const FOLDER_PERMISSION_QUERY_FIELDS = [
+    'isCreateDoc',
+    'isCreateFolder',
+    'canMoveDoc',
+    'canCopyDoc',
+    'documentCreateSetting',
+];
+/** 源 QueryFoldersByPermissionPlugin 的对象类型集合（Python set → JS Set）。 */
+const QUERY_FOLDER_BASIC_OBJECT_TYPES = new Set([
+    'resource',
+    'department',
+    'subcompany',
+    'role',
+    'group',
+    'position',
+    'all',
+]);
+const QUERY_FOLDER_REQUIRES_IDS = new Set([
+    'resource',
+    'department',
+    'subcompany',
+    'role',
+    'group',
+    'position',
+    'customer',
+    'customer_type',
+]);
+const QUERY_FOLDER_NO_IDS = new Set([
+    'all',
+    'allExternal',
+    'external',
+    'createrSelf',
+    'createrSuperior',
+    'createrSuperiorAll',
+    'createrDepartment',
+    'createrSubcompany',
+    'createrPosition',
+]);
+const QUERY_FOLDER_ALL_OBJECT_TYPES = new Set([...QUERY_FOLDER_REQUIRES_IDS, ...QUERY_FOLDER_NO_IDS]);
+const QUERY_FOLDER_KEY_OBJECT_TYPES = {
+    folderDefaultShareNew: QUERY_FOLDER_ALL_OBJECT_TYPES,
+    folderDefaultParticipants: new Set(['resource']),
+    downloadPremisstion: new Set([...QUERY_FOLDER_BASIC_OBJECT_TYPES, 'customer', 'customer_type']),
+};
+for (const key of [
+    'newCreateFolderPremisstion',
+    'settingPermission',
+    'newCreateDocPremisstion',
+    'deletePremisstion',
+    'copyPermission',
+    'movePermission',
+]) {
+    QUERY_FOLDER_KEY_OBJECT_TYPES[key] = QUERY_FOLDER_BASIC_OBJECT_TYPES;
+}
+const QUERY_FOLDER_KEY_NAMES = {
+    folderDefaultShareNew: '文件夹默认共享',
+    newCreateFolderPremisstion: '文件夹维护权限',
+    settingPermission: '文件夹管理员',
+    folderDefaultParticipants: '默认参与人',
+    newCreateDocPremisstion: '新建文档权限',
+    downloadPremisstion: '下载权限',
+    deletePremisstion: '删除权限',
+    copyPermission: '复制权限',
+    movePermission: '移动权限',
+};
+// ── 通用小工具（对齐源取值语义）──────────────────────────
+/** 源 CreateFolderPlugin 的 inherit_parent 解析：字符串按 true/1，其余按 bool()。 */
+function parseInheritParent(value) {
+    if (typeof value === 'string')
+        return ['true', '1'].includes(value.trim().toLowerCase());
+    if (value === undefined || value === null)
+        return false;
+    if (typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number')
+        return value !== 0;
+    if (Array.isArray(value))
+        return value.length > 0;
+    if (isPlainObject(value))
+        return Object.keys(value).length > 0;
+    return Boolean(value);
+}
+// ── 表单配置查询与 seclevel 解析（源 folder_plugins）──────
+/** 源 _query_form_config：固定 body 的表单配置查询。 */
+async function queryFormConfig(env, folderId, apiPath, operation) {
+    const response = await env.host.request({
+        method: 'POST',
+        path: apiPath,
+        body: {
+            permissionId: 'doc_s01',
+            id: String(folderId),
+            isTemplate: false,
+            tableName: 'folder',
+            sourceId: String(folderId),
+            sourceType: 1,
+        },
+        operation,
+    });
+    return asRecord(response);
+}
+/**
+ * 源 `creator_data, _ = _query_form_config(...)`：失败被吞掉，按 None 处理。
+ */
+async function tryQueryFormConfig(env, folderId, apiPath, operation) {
+    try {
+        return await queryFormConfig(env, folderId, apiPath, operation);
+    }
+    catch {
+        return null;
+    }
+}
+/** 源 _parse_seclevel_args：默认 0~100，允许范围 -999~999，且 min<=max。 */
+function parseSeclevelArgs(args) {
+    let secMin;
+    let secMax;
+    try {
+        secMin = pyInt(args.seclevel_min === '' ? undefined : args.seclevel_min, DEFAULT_SEC_LEVEL.min);
+        secMax = pyInt(args.seclevel_max === '' ? undefined : args.seclevel_max, DEFAULT_SEC_LEVEL.max);
+    }
+    catch {
+        throw caizhilianValidationError('number_invalid', 'seclevel_min/seclevel_max 必须为整数');
+    }
+    for (const [name, value] of [
+        ['seclevel_min', secMin],
+        ['seclevel_max', secMax],
+    ]) {
+        if (value < -999 || value > 999) {
+            throw caizhilianValidationError('range_invalid', `${name} 超出允许范围 -999~999: ${value}`);
+        }
+    }
+    if (secMin > secMax) {
+        throw caizhilianValidationError('range_invalid', `seclevel_min 不能大于 seclevel_max（${secMin} > ${secMax}）`);
+    }
+    return { min: secMin, max: secMax };
+}
+// ── 写操作 apply 名（continuation 与操作绑定，防跨操作串用）──
+const FOLDER_CREATE_APPLY = 'caizhilian.folder.create.apply';
+const DEFAULT_SHARE_ADD_APPLY = 'caizhilian.folder.default-share.add.apply';
+const DEFAULT_SHARE_DELETE_APPLY = 'caizhilian.folder.default-share.delete.apply';
+const PERMISSION_ADD_APPLY = 'caizhilian.folder.permission.add.apply';
+const PERMISSION_DELETE_APPLY = 'caizhilian.folder.permission.delete.apply';
+const PERMISSION_SET_AUTH_APPLY = 'caizhilian.folder.permission.set-auth.apply';
+/** 源 CreateFolderPlugin.execute 的校验 + 请求体组装（含权限回查）。 */
+async function planCreateFolder(args, env, action) {
+    let sequence;
+    try {
+        sequence = pyInt(args.sequence === undefined || args.sequence === null || args.sequence === '' ? undefined : args.sequence, 0);
+    }
+    catch {
+        throw caizhilianValidationError('number_invalid', 'sequence 必须是整数');
+    }
+    const name = requireNonEmpty(args.name, '文件夹名称不能为空');
+    const parentId = requireNonEmpty(args.parent_id, 'parent_id 不能为空');
+    const parentTypeRaw = args.parent_type === undefined || args.parent_type === null ? '' : String(args.parent_type);
+    if (!PARENT_TYPES.includes(parentTypeRaw)) {
+        throw caizhilianValidationError('enum_invalid', `parent_type 只能是 company 或 privy，不支持: ${parentTypeRaw}`);
+    }
+    const inheritParentRaw = args.inherit_parent === undefined ? false : args.inherit_parent;
+    let inheritParent = parseInheritParent(inheritParentRaw);
+    // 源：个人库强制 sequence=0 且不继承父设置。
+    if (parentTypeRaw === 'privy') {
+        sequence = 0;
+        inheritParent = false;
+    }
+    if (sequence < SEQ_MIN || sequence > SEQ_MAX) {
+        throw caizhilianValidationError('range_invalid', `sequence 超出允许范围 [${SEQ_MIN}, ${SEQ_MAX}]`);
+    }
+    await checkCreateFolderPermission(env, parentId, action);
+    return {
+        name,
+        parentId,
+        parentType: parentTypeRaw,
+        sequence,
+        inheritParent,
+        body: {
+            folder: { type: parentTypeRaw, name, sequence },
+            parent: { id: parentId, type: parentTypeRaw },
+            inheritParentFolderSetUp: inheritParent,
+        },
+    };
+}
+const createFolderHandler = {
+    targetKeys: ['parent_id', 'name', 'parent_type'],
+    async prepare(args, env) {
+        const action = 'caizhilian.folder.create';
+        const plan = await planCreateFolder(args, env, action);
+        const lease = await issueWriteLease(env, FOLDER_CREATE_APPLY, args, {
+            parent_id: plan.parentId,
+            name: plan.name,
+            parent_type: plan.parentType,
+            sequence: plan.sequence,
+            inherit_parent: plan.inheritParent,
+            body_fingerprint: fingerprint(plan.body),
+        });
+        return caizhilianPrepared(action, {
+            name: plan.name,
+            parent_id: plan.parentId,
+            parent_type: plan.parentType,
+            sequence: plan.sequence,
+            inherit_parent: plan.inheritParent,
+            request: { method: 'POST', path: FOLDER_CREATE_PATH, body: plan.body },
+        }, lease);
+    },
+    async apply(args, env, lease) {
+        const action = FOLDER_CREATE_APPLY;
+        const plan = await planCreateFolder(args, env, 'caizhilian.folder.create');
+        const expected = typeof lease.body_fingerprint === 'string' ? lease.body_fingerprint : '';
+        if (expected && expected !== fingerprint(plan.body)) {
+            throw caizhilianValidationError('plan_changed', `${action} 的请求体与 prepare 时不一致（父文件夹权限或入参可能已变化），请重新执行 prepare`);
+        }
+        const response = await env.host.request({
+            method: 'POST',
+            path: FOLDER_CREATE_PATH,
+            body: plan.body,
+            operation: action,
+        });
+        const folderId = String(asRecord(asRecord(response).data).folder === undefined ? '' : asRecord(asRecord(asRecord(response).data).folder).id ?? '').trim();
+        if (!folderId) {
+            throw caizhilianValidationError('folder_id_missing', '创建文件夹响应缺少 folder_id');
+        }
+        return caizhilianSuccess(action, {
+            folder_id: folderId,
+            name: plan.name,
+            type: plan.parentType,
+            parent_id: plan.parentId,
+        });
+    },
+};
+// ── caizhilian.folder.query-by-name ───────────────────────
+/** 源 FlattenSearchResultFolderTree._traverse：递归展平 searchResultKeyNode 节点。 */
+function traverseFolderTree(nodes, ancestors, results) {
+    for (const node of nodes) {
+        if (!isPlainObject(node))
+            continue;
+        const content = node.content || node.title || '';
+        const currentPath = [...ancestors, String(content)];
+        if (node.searchResultKeyNode) {
+            results.push({
+                id: String(node.id ?? ''),
+                name: content,
+                folderType: node.folderType ?? '',
+                parentId: String(node.parentId ?? ''),
+                path: currentPath.join('/'),
+            });
+        }
+        const children = node.children;
+        if (Array.isArray(children) && children.length > 0)
+            traverseFolderTree(children, currentPath, results);
+    }
+}
+async function queryFoldersByName(args, env) {
+    const action = 'caizhilian.folder.query-by-name';
+    const folderName = requireNonEmpty(args.folder_name, '缺少必填参数: folder_name');
+    const kbTypeRaw = args.kb_type === undefined || args.kb_type === null || args.kb_type === '' ? KB_TYPE_DEFAULT : String(args.kb_type);
+    const folderId = KB_ROOT_FOLDER_ID[kbTypeRaw] ?? KB_ROOT_FOLDER_ID_DEFAULT;
+    const session = await env.host.getSession();
+    const response = await env.host.request({
+        method: 'POST',
+        path: QUERY_FOLDERS_BY_NAME_PATH,
+        body: {
+            folder: { name: folderName, type: kbTypeRaw, id: folderId },
+            dimension: 'ALL',
+            userId: session.userId,
+        },
+        operation: action,
+    });
+    const results = [];
+    traverseFolderTree(asList(asRecord(asRecord(response).data).nodes), [], results);
+    // 源：完全同名的结果排到前面，其余保持遍历顺序。
+    const matched = results.filter((item) => item.name === folderName);
+    const unmatched = results.filter((item) => item.name !== folderName);
+    return caizhilianSuccess(action, { folders: [...matched, ...unmatched] }, { kb_type: kbTypeRaw, root_folder_id: folderId });
+}
+// ── caizhilian.folder.get-settings ────────────────────────
+/** 源 Engine._apply_array_fields_whitelist：非 dict 元素丢弃，字段按白名单且在原对象中存在才保留。 */
+function pickListFields(value, keys) {
+    if (!Array.isArray(value))
+        return value ?? null;
+    const output = [];
+    for (const item of value) {
+        if (!isPlainObject(item))
+            continue;
+        const picked = {};
+        for (const key of keys)
+            if (key in item)
+                picked[key] = item[key];
+        output.push(picked);
+    }
+    return output;
+}
+async function getFolderSettings(args, env) {
+    const action = 'caizhilian.folder.get-settings';
+    const folderId = requireNonEmpty(args.folder_id, '缺少必填参数: folder_id');
+    const response = await env.host.request({
+        method: 'POST',
+        path: FOLDER_SETTINGS_PATH,
+        body: { id: folderId, type: FOLDER_SETTING_TYPES_PARAM },
+        operation: action,
+    });
+    const data = asRecord(response).data;
+    return caizhilianSuccess(action, {
+        defaultVirtualFolder: Array.isArray(data) ? null : (asRecord(data).defaultVirtualFolder ?? null),
+        folderDefaultParticipants: pickListFields(asRecord(data).folderDefaultParticipants, ['id', 'content', '_entityType']),
+        currentFolder: asRecord(data).currentFolder ?? null,
+        folderDefaultShareNew: pickListFields(asRecord(data).folderDefaultShareNew, [
+            'id',
+            'content',
+            '_entityType',
+            'canDelete',
+        ]),
+    });
+}
+// ── caizhilian.folder.list-default-shares ─────────────────
+async function listDefaultShares(args, env) {
+    const action = 'caizhilian.folder.list-default-shares';
+    // 源入参名为 folderId；执行入口已按 deprecatedInputAliases 归一化为 canonical folder_id。
+    // schema 将该字段声明为数字 ID，运行时按同一约束校验。
+    const folderId = requireId(args.folder_id, 'folder_id');
+    const result = await fetchFolderDefaultShareEntries(env, folderId, action);
+    return caizhilianSuccess(action, { defaultShares: result.shares });
+}
+// ── caizhilian.folder.default-share.form ──────────────────
+async function defaultShareForm(args, env) {
+    const action = 'caizhilian.folder.default-share.form';
+    const folderId = requireNonEmpty(args.folder_id, 'folder_id 不能为空');
+    const categoryRaw = args.category === undefined || args.category === null ? '' : String(args.category).trim();
+    if (!(categoryRaw in CATEGORY_API)) {
+        throw caizhilianValidationError('enum_invalid', `category 必须为 creator 或 generic，收到: ${pyRepr(categoryRaw)}`);
+    }
+    await checkSetFolderPermission(env, folderId, action);
+    const respData = asRecord((await queryFormConfig(env, folderId, CATEGORY_API[categoryRaw], action)).data);
+    const fieldCascadeRules = parseFieldCascadeRules(respData);
+    const { nameMap, availableIds } = parseObjTypeOptions(respData);
+    return caizhilianSuccess(action, {
+        category: categoryRaw,
+        obj_types: buildObjTypeList({
+            cascadeRulesOuter: parseCascadeRulesOuter(respData),
+            cascadeRules: parseCascadeRules(respData),
+            objTypeNames: nameMap,
+            availableIds,
+            fieldCascadeRules,
+            seclevelAllowed: parseSeclevelAllowed(respData),
+        }),
+        param_options: parseParamOptions(respData, fieldCascadeRules),
+    });
+}
+// ── caizhilian.folder.default-share.list ──────────────────
+async function defaultShareList(args, env) {
+    const action = 'caizhilian.folder.default-share.list';
+    const folderId = requireNonEmpty(args.folder_id, 'folder_id 不能为空');
+    await checkSetFolderPermission(env, folderId, action);
+    const result = await fetchFolderDefaultShareEntries(env, folderId, action);
+    return caizhilianSuccess(action, { default_shares: result.shares });
+}
+/** 源 AddFolderSetDefaultSharePlugin.execute 的校验 + 级联规则合成 + 请求体组装。 */
+async function planDefaultShareAdd(args, env, action) {
+    const folderId = requireNonEmpty(args.folder_id, 'folder_id 不能为空');
+    const objType = requireNonEmpty(args.obj_type, 'obj_type 不能为空');
+    const shareLevel = requireNonEmpty(args.share_level, 'share_level 不能为空');
+    const seclevelBody = parseSeclevelArgs(args);
+    await checkSetFolderPermission(env, folderId, action);
+    // 源：两个表单配置查询失败都被忽略，按空规则处理。
+    const creatorData = await tryQueryFormConfig(env, folderId, CATEGORY_API.creator, action);
+    const genericData = await tryQueryFormConfig(env, folderId, CATEGORY_API.generic, action);
+    const creatorRules = creatorData ? parseCascadeRules(asRecord(creatorData.data)) : {};
+    const genericRules = genericData ? parseCascadeRules(asRecord(genericData.data)) : {};
+    const creatorOuter = creatorData ? parseCascadeRulesOuter(asRecord(creatorData.data)) : {};
+    const genericOuter = genericData ? parseCascadeRulesOuter(asRecord(genericData.data)) : {};
+    let rule = creatorRules[objType] || genericRules[objType];
+    if (!rule) {
+        if (objType in creatorOuter || objType in genericOuter) {
+            rule = { datas: {} };
+        }
+        else {
+            throw caizhilianValidationError('obj_type_not_configured', `未找到 obj_type=${pyRepr(objType)} 的配置，请检查 fetch_folder_default_share_form 返回的选项`);
+        }
+    }
+    const body = {
+        permissionId: 'doc_s01',
+        folderId,
+        isTemplate: false,
+        objType,
+        share_level: shareLevel,
+        seclevel: seclevelBody,
+    };
+    for (const [key, value] of Object.entries(asRecord(asRecord(rule).datas))) {
+        if (key === 'share_level' || key === 'download' || key === 'seclevel')
+            continue;
+        body[key] = value;
+    }
+    for (const key of SHARE_USER_OVERRIDES) {
+        if (key in args)
+            body[key] = args[key];
+    }
+    for (const field of SHARE_ID_FIELDS) {
+        if (!(field in args))
+            continue;
+        const value = args[field];
+        if (Array.isArray(value))
+            body[field] = value;
+        else if (typeof value === 'string' && value)
+            body[field] = [value];
+    }
+    if (shareLevel !== '1' && !('download' in body))
+        body.download = ['download'];
+    return { folderId, objType, shareLevel, body };
+}
+const defaultShareAddHandler = {
+    targetKeys: ['folder_id', 'obj_type', 'share_level'],
+    async prepare(args, env) {
+        const action = 'caizhilian.folder.default-share.add';
+        const plan = await planDefaultShareAdd(args, env, action);
+        const lease = await issueWriteLease(env, DEFAULT_SHARE_ADD_APPLY, args, {
+            folder_id: plan.folderId,
+            obj_type: plan.objType,
+            share_level: plan.shareLevel,
+            body_fingerprint: fingerprint(plan.body),
+        });
+        return caizhilianPrepared(action, {
+            folder_id: plan.folderId,
+            obj_type: plan.objType,
+            share_level: plan.shareLevel,
+            seclevel: plan.body.seclevel,
+            request: { method: 'POST', path: DEFAULT_SHARE_ADD_PATH, body: plan.body },
+        }, lease);
+    },
+    async apply(args, env, lease) {
+        const action = DEFAULT_SHARE_ADD_APPLY;
+        const plan = await planDefaultShareAdd(args, env, 'caizhilian.folder.default-share.add');
+        const expected = typeof lease.body_fingerprint === 'string' ? lease.body_fingerprint : '';
+        if (expected && expected !== fingerprint(plan.body)) {
+            throw caizhilianValidationError('plan_changed', `${action} 的请求体与 prepare 时不一致（表单级联规则可能已变化），请重新执行 prepare`);
+        }
+        const data = asRecord(await env.host.request({
+            method: 'POST',
+            path: DEFAULT_SHARE_ADD_PATH,
+            body: plan.body,
+            operation: action,
+            tolerateBusinessError: true,
+        }));
+        if (isAlreadyExistsResponse(data)) {
+            const message = data.message || data.msg || '已存在';
+            return caizhilianSuccess(action, { added: false, message: String(message) });
+        }
+        assertToleratedBusinessSuccess(data, action);
+        // 源：回读列表失败时仍算成功，只是列表为空。
+        let shares = [];
+        try {
+            shares = (await fetchFolderDefaultShareEntries(env, plan.folderId, action)).shares;
+        }
+        catch {
+            shares = [];
+        }
+        return caizhilianSuccess(action, { added: true, default_shares: shares });
+    },
+};
+function planDefaultShareDelete(args) {
+    const folderId = requireNonEmpty(args.folder_id, 'folder_id 不能为空');
+    if (isFalsyIds(args.ids))
+        throw caizhilianValidationError('field_required', 'ids 不能为空');
+    const ids = joinIds(args.ids);
+    return {
+        folderId,
+        ids,
+        body: {
+            sourceId: folderId,
+            permissionId: 'doc_s01',
+            sourceType: 1,
+            folderId,
+            isTemplate: false,
+            ids,
+        },
+    };
+}
+const defaultShareDeleteHandler = {
+    targetKeys: ['folder_id'],
+    async prepare(args, env) {
+        const action = 'caizhilian.folder.default-share.delete';
+        const plan = planDefaultShareDelete(args);
+        await checkSetFolderPermission(env, plan.folderId, action);
+        const lease = await issueWriteLease(env, DEFAULT_SHARE_DELETE_APPLY, args, {
+            folder_id: plan.folderId,
+            ids: plan.ids,
+        });
+        return caizhilianPrepared(action, {
+            folder_id: plan.folderId,
+            ids: plan.ids,
+            request: { method: 'POST', path: DEFAULT_SHARE_DELETE_PATH, body: plan.body },
+        }, lease);
+    },
+    async apply(args, env, _lease) {
+        const action = DEFAULT_SHARE_DELETE_APPLY;
+        const plan = planDefaultShareDelete(args);
+        await env.host.request({
+            method: 'POST',
+            path: DEFAULT_SHARE_DELETE_PATH,
+            body: plan.body,
+            operation: action,
+        });
+        let shares = [];
+        try {
+            shares = (await fetchFolderDefaultShareEntries(env, plan.folderId, action)).shares;
+        }
+        catch {
+            shares = [];
+        }
+        return caizhilianSuccess(action, { deleted: true, default_shares: shares });
+    },
+};
+// ── 文件夹文档权限设置（form / list / add / delete）────────
+function requirePermissionType(value) {
+    const permissionType = value === undefined || value === null ? '' : String(value).trim();
+    if (!PERMISSION_TYPES.includes(permissionType)) {
+        throw caizhilianValidationError('enum_invalid', `permission_type 必须为 ${sortedJoin(PERMISSION_TYPES)} 之一，收到: ${pyRepr(permissionType)}`);
+    }
+    return permissionType;
+}
+/** 源 _check_doc_permission_auth：仅下载/删除权限需要先设为 user。 */
+async function checkDocPermissionAuth(env, folderId, permissionType, action) {
+    if (!AUTH_CHECK_TYPES.includes(permissionType))
+        return;
+    const currentValue = await fetchFolderPermissionAuth(env, folderId, permissionType, action);
+    if (currentValue !== 'user') {
+        const label = AUTH_TYPE_LABELS[permissionType] ?? permissionType;
+        throw caizhilianValidationError('permission_auth_not_user', `当前${label}类型为 ${currentValue}，不可操作具体人员列表。请先通过 update_folder_permission_auth 设为 user`);
+    }
+}
+async function permissionForm(args, env) {
+    const action = 'caizhilian.folder.permission.form';
+    const folderId = requireNonEmpty(args.folder_id, 'folder_id 不能为空');
+    const permissionType = requirePermissionType(args.permission_type);
+    const response = await env.host.request({
+        method: 'POST',
+        path: PERMISSION_FORM_PATH,
+        body: {
+            sourceId: folderId,
+            permissionId: 'doc_s01',
+            sourceType: 1,
+            id: folderId,
+            tableName: permissionType,
+            isTemplate: false,
+        },
+        operation: action,
+    });
+    const respData = asRecord(asRecord(response).data);
+    const fieldCascadeRules = parseFieldCascadeRules(respData);
+    const { nameMap, availableIds } = parseObjTypeOptions(respData);
+    let objTypes = buildObjTypeList({
+        cascadeRulesOuter: parseCascadeRulesOuter(respData),
+        cascadeRules: parseCascadeRules(respData),
+        objTypeNames: nameMap,
+        availableIds,
+        fieldCascadeRules,
+        permissionType,
+    });
+    // 源：默认参与人只允许 resource。
+    if (permissionType === 'folderDefaultParticipants')
+        objTypes = objTypes.filter((item) => item.id === 'resource');
+    return caizhilianSuccess(action, { obj_types: objTypes, param_options: parseParamOptions(respData, fieldCascadeRules) });
+}
+async function permissionList(args, env) {
+    const action = 'caizhilian.folder.permission.list';
+    const folderId = requireNonEmpty(args.folder_id, 'folder_id 不能为空');
+    const permissionType = requirePermissionType(args.permission_type);
+    await checkDocPermissionAuth(env, folderId, permissionType, action);
+    const result = await fetchFolderPermissionEntries(env, folderId, permissionType, action);
+    return caizhilianSuccess(action, { add_visible: result.add_visible, shares: result.shares });
+}
+/** 源 AddFolderPermissionPlugin.execute 的校验 + _build_folder_permission_add_body。 */
+async function planPermissionAdd(args, env, action) {
+    const folderId = requireNonEmpty(args.folder_id, 'folder_id 不能为空');
+    const permissionType = requirePermissionType(args.permission_type);
+    const objType = requireNonEmpty(args.obj_type, 'obj_type 不能为空');
+    if (permissionType === 'folderDefaultParticipants' && objType !== 'resource') {
+        throw caizhilianValidationError('obj_type_not_supported', '默认参与人（folderDefaultParticipants）仅支持 obj_type=resource（人员）');
+    }
+    if ((objType === 'customer' || objType === 'customer_type') && permissionType !== 'downloadPremisstion') {
+        throw caizhilianValidationError('obj_type_not_supported', '客户和客户类型仅支持下载权限（downloadPremisstion）');
+    }
+    await checkSetFolderPermission(env, folderId, action);
+    await checkDocPermissionAuth(env, folderId, permissionType, action);
+    return {
+        folderId,
+        permissionType,
+        objType,
+        body: buildFolderPermissionAddBody(folderId, permissionType, objType, args),
+    };
+}
+const permissionAddHandler = {
+    targetKeys: ['folder_id', 'permission_type', 'obj_type'],
+    async prepare(args, env) {
+        const action = 'caizhilian.folder.permission.add';
+        const plan = await planPermissionAdd(args, env, action);
+        const lease = await issueWriteLease(env, PERMISSION_ADD_APPLY, args, {
+            folder_id: plan.folderId,
+            permission_type: plan.permissionType,
+            obj_type: plan.objType,
+            body_fingerprint: fingerprint(plan.body),
+        });
+        return caizhilianPrepared(action, {
+            folder_id: plan.folderId,
+            permission_type: plan.permissionType,
+            obj_type: plan.objType,
+            target_type: plan.body.targetType ?? null,
+            target_id: plan.body.targetId ?? null,
+            request: { method: 'POST', path: PERMISSION_ADD_PATH, body: plan.body },
+        }, lease);
+    },
+    async apply(args, env, lease) {
+        const action = PERMISSION_ADD_APPLY;
+        const plan = await planPermissionAdd(args, env, 'caizhilian.folder.permission.add');
+        const expected = typeof lease.body_fingerprint === 'string' ? lease.body_fingerprint : '';
+        if (expected && expected !== fingerprint(plan.body)) {
+            throw caizhilianValidationError('plan_changed', `${action} 的请求体与 prepare 时不一致，请重新执行 prepare`);
+        }
+        await env.host.request({ method: 'POST', path: PERMISSION_ADD_PATH, body: plan.body, operation: action });
+        let shares = [];
+        try {
+            shares = (await fetchFolderPermissionEntries(env, plan.folderId, plan.permissionType, action)).shares;
+        }
+        catch {
+            shares = [];
+        }
+        return caizhilianSuccess(action, { added: true, shares });
+    },
+};
+/** 源 DeleteFolderPermissionPlugin.execute：删除前回读列表校验条目存在。 */
+async function planPermissionDelete(args, env, action) {
+    const folderId = requireNonEmpty(args.folder_id, 'folder_id 不能为空');
+    const permissionType = requirePermissionType(args.permission_type);
+    if (isFalsyIds(args.ids))
+        throw caizhilianValidationError('field_required', 'ids 不能为空');
+    const idList = Array.isArray(args.ids) ? args.ids.map((item) => String(item)) : [String(args.ids)];
+    await checkDocPermissionAuth(env, folderId, permissionType, action);
+    const existing = await fetchFolderPermissionEntries(env, folderId, permissionType, action);
+    const shareIds = new Set(existing.shares.map((item) => String(item.id ?? '')));
+    const notFound = idList.filter((id) => !shareIds.has(id));
+    if (notFound.length > 0) {
+        throw caizhilianValidationError('entries_not_found', `以下条目不存在: ${notFound.join(', ')}`);
+    }
+    const ids = idList.join(',');
+    return {
+        folderId,
+        permissionType,
+        idList,
+        ids,
+        body: {
+            sourceId: folderId,
+            permissionId: 'doc_s01',
+            sourceType: 1,
+            folderId,
+            docSettingType: permissionType,
+            isTemplate: false,
+            ids,
+        },
+    };
+}
+const permissionDeleteHandler = {
+    targetKeys: ['folder_id', 'permission_type'],
+    async prepare(args, env) {
+        const action = 'caizhilian.folder.permission.delete';
+        const plan = await planPermissionDelete(args, env, action);
+        const lease = await issueWriteLease(env, PERMISSION_DELETE_APPLY, args, {
+            folder_id: plan.folderId,
+            permission_type: plan.permissionType,
+            ids: plan.ids,
+        });
+        return caizhilianPrepared(action, {
+            folder_id: plan.folderId,
+            permission_type: plan.permissionType,
+            ids: plan.ids,
+            request: { method: 'POST', path: PERMISSION_DELETE_PATH, body: plan.body },
+        }, lease);
+    },
+    async apply(args, env, _lease) {
+        const action = PERMISSION_DELETE_APPLY;
+        const plan = await planPermissionDelete(args, env, 'caizhilian.folder.permission.delete');
+        await env.host.request({ method: 'POST', path: PERMISSION_DELETE_PATH, body: plan.body, operation: action });
+        let shares = [];
+        try {
+            shares = (await fetchFolderPermissionEntries(env, plan.folderId, plan.permissionType, action)).shares;
+        }
+        catch {
+            shares = [];
+        }
+        return caizhilianSuccess(action, { deleted: true, shares });
+    },
+};
+// ── caizhilian.folder.permission.get-auth / set-auth ──────
+async function permissionGetAuth(args, env) {
+    const action = 'caizhilian.folder.permission.get-auth';
+    const folderId = requireNonEmpty(args.folder_id, 'folder_id 不能为空');
+    const permissionType = requireNonEmpty(args.permission_type, 'permission_type 不能为空');
+    const currentValue = await fetchFolderPermissionAuth(env, folderId, permissionType, action);
+    return caizhilianSuccess(action, { permission_type: permissionType, current_value: currentValue });
+}
+function planPermissionSetAuth(args) {
+    return {
+        folderId: requireNonEmpty(args.folder_id, 'folder_id 不能为空'),
+        permissionType: requireNonEmpty(args.permission_type, 'permission_type 不能为空'),
+        value: requireNonEmpty(args.value, 'value 不能为空'),
+    };
+}
+const permissionSetAuthHandler = {
+    targetKeys: ['folder_id', 'permission_type', 'value'],
+    async prepare(args, env) {
+        const action = 'caizhilian.folder.permission.set-auth';
+        const plan = planPermissionSetAuth(args);
+        await checkSetFolderPermission(env, plan.folderId, action);
+        const currentValue = await fetchFolderPermissionAuth(env, plan.folderId, plan.permissionType, action);
+        const lease = await issueWriteLease(env, PERMISSION_SET_AUTH_APPLY, args, {
+            folder_id: plan.folderId,
+            permission_type: plan.permissionType,
+            value: plan.value,
+            current_value: currentValue ?? '',
+        });
+        return caizhilianPrepared(action, {
+            folder_id: plan.folderId,
+            permission_type: plan.permissionType,
+            value: plan.value,
+            current_value: currentValue,
+            request: { method: 'POST', path: '/api/doc/folderBackstageSetting/docPermission' },
+        }, lease);
+    },
+    async apply(args, env) {
+        const action = PERMISSION_SET_AUTH_APPLY;
+        const plan = planPermissionSetAuth(args);
+        await updateFolderPermissionAuth(env, plan.folderId, plan.permissionType, plan.value, action);
+        // 源：回读失败不阻断，current_value 直接为 None。
+        let newValue = null;
+        try {
+            newValue = await fetchFolderPermissionAuth(env, plan.folderId, plan.permissionType, action);
+        }
+        catch {
+            newValue = null;
+        }
+        return caizhilianSuccess(action, {
+            permission_type: plan.permissionType,
+            value: plan.value,
+            current_value: newValue,
+        });
+    },
+};
+// ── caizhilian.folder.permission.detail ───────────────────
+async function permissionDetail(args, env) {
+    const action = 'caizhilian.folder.permission.detail';
+    const folderId = requireNonEmpty(args.folder_id, 'folder_id 不能为空');
+    const settingTypeRaw = args.setting_type === undefined || args.setting_type === null ? '' : String(args.setting_type).trim();
+    if (!SETTING_TYPES.includes(settingTypeRaw)) {
+        throw caizhilianValidationError('enum_invalid', `setting_type 必须为 ${sortedJoin(SETTING_TYPES)} 之一，收到: ${pyRepr(settingTypeRaw)}`);
+    }
+    const title = DETAIL_TITLES[settingTypeRaw] ?? settingTypeRaw;
+    if (DETAIL_AUTH_TYPES.includes(settingTypeRaw)) {
+        const currentValue = await fetchFolderPermissionAuth(env, folderId, settingTypeRaw, action);
+        const labels = DETAIL_AUTH_LABELS[settingTypeRaw] ?? {};
+        const currentSetting = currentValue !== null && currentValue in labels ? labels[currentValue] : currentValue;
+        const listLabel = labels.user ?? '';
+        let items = [];
+        if (currentValue === 'user')
+            items = (await fetchFolderPermissionEntries(env, folderId, settingTypeRaw, action)).shares;
+        return caizhilianSuccess(action, { title, current_setting: currentSetting, list_label: listLabel, items });
+    }
+    if (settingTypeRaw === 'defaultShares') {
+        const result = await fetchFolderDefaultShareEntries(env, folderId, action);
+        return caizhilianSuccess(action, { title, items: result.shares });
+    }
+    const result = await fetchFolderPermissionEntries(env, folderId, settingTypeRaw, action);
+    return caizhilianSuccess(action, { title, items: result.shares });
+}
+// ── caizhilian.folder.permission.query ────────────────────
+async function permissionQuery(args, env) {
+    const action = 'caizhilian.folder.permission.query';
+    const folderIds = requireIdList(args.folder_ids, 'folder_ids');
+    const permissions = await fetchFolderPermissions(env, folderIds, [...FOLDER_PERMISSION_QUERY_FIELDS], action);
+    return caizhilianSuccess(action, { permissions });
+}
+// ── caizhilian.folder.query-by-permission ─────────────────
+/** 源 QueryFoldersByPermissionPlugin.execute 的 permissions 归一化与校验。 */
+function normalizeQueryPermissions(permissionKey, permissionsRaw) {
+    const supported = QUERY_FOLDER_KEY_OBJECT_TYPES[permissionKey] ?? new Set();
+    const keyName = QUERY_FOLDER_KEY_NAMES[permissionKey] ?? permissionKey;
+    if (!Array.isArray(permissionsRaw) || permissionsRaw.length === 0) {
+        throw caizhilianValidationError('list_required', 'permissions 必须是非空数组，示例: [{"object_type": "all"}] 或 [{"object_type": "resource", "object_ids": ["123"]}]');
+    }
+    const apiPermissions = [];
+    permissionsRaw.forEach((item, index) => {
+        if (!isPlainObject(item)) {
+            throw caizhilianValidationError('input_not_object', `permissions[${index}] 必须是对象，格式: {"object_type": "...", "object_ids": [...]}`);
+        }
+        const objType = item.object_type === undefined || item.object_type === null ? '' : String(item.object_type).trim();
+        if (!objType) {
+            throw caizhilianValidationError('field_required', `permissions[${index}] 缺少必填字段 object_type`);
+        }
+        if (!QUERY_FOLDER_ALL_OBJECT_TYPES.has(objType)) {
+            throw caizhilianValidationError('enum_invalid', `permissions[${index}].object_type 不支持: ${pyRepr(objType)}，可选值: ${sortedJoin(QUERY_FOLDER_ALL_OBJECT_TYPES)}`);
+        }
+        if (!supported.has(objType)) {
+            throw caizhilianValidationError('enum_invalid', `permissions[${index}].object_type=${pyRepr(objType)} 与 ${keyName}（${permissionKey}）不兼容，该权限类型支持: ${sortedJoin(supported)}`);
+        }
+        const entry = { objectType: objType };
+        if (QUERY_FOLDER_REQUIRES_IDS.has(objType)) {
+            const objectIds = item.object_ids;
+            if (isFalsyIds(objectIds)) {
+                throw caizhilianValidationError('field_required', `permissions[${index}]：object_type=${pyRepr(objType)} 需要传 object_ids（具体对象 ID 列表）`);
+            }
+            if (!Array.isArray(objectIds)) {
+                throw caizhilianValidationError('list_invalid', `permissions[${index}].object_ids 必须是数组`);
+            }
+            entry.objectIds = objectIds.map((oid) => {
+                // 源用 int() 归一后按数字提交；这里必须保持字符串：E10 对象 ID 是 19 位雪花号，
+                // 超出 JS 安全整数范围（2^53），转成 number 会静默丢精度，服务端按错误 ID 匹配只会返回空。
+                const matched = /^\+?(\d+)$/.exec(oid === undefined || oid === null ? '' : String(oid).trim());
+                const digits = matched ? matched[1].replace(/^0+(?=\d)/, '') : '';
+                if (!digits || digits === '0') {
+                    throw caizhilianValidationError('id_invalid', `permissions[${index}].object_ids 中的值必须为正整数，收到: ${pyRepr(oid)}`);
+                }
+                return digits;
+            });
+        }
+        apiPermissions.push(entry);
+    });
+    return apiPermissions;
+}
+/** 源直接用 client.execute 后自行判断 success/status，这里同样容忍业务失败再自行判定。 */
+async function queryFolderPermissionPage(env, path, body, failureMessage, action) {
+    const data = asRecord(await env.host.request({ method: 'POST', path, body, operation: action, tolerateBusinessError: true }));
+    if (!(data.success || data.status)) {
+        throw new CaizhilianCliError('api', 'business_error', String(data.msg || data.message || failureMessage), {
+            code: data.code ?? data.status,
+            details: { action, message: String(data.msg || data.message || failureMessage) },
+            exitCode: 1,
+        });
+    }
+    return data;
+}
+async function queryFoldersByPermission(args, env) {
+    const action = 'caizhilian.folder.query-by-permission';
+    const permissionKey = requireNonEmpty(args.permission_key, 'permission_key 不能为空');
+    if (!FOLDER_PERMISSION_KEYS.includes(permissionKey)) {
+        throw caizhilianValidationError('enum_invalid', `permission_key 不支持: ${pyRepr(permissionKey)}，可选值: ${sortedJoin(FOLDER_PERMISSION_KEYS)}`);
+    }
+    const apiPermissions = normalizeQueryPermissions(permissionKey, args.permissions);
+    const { pageNo, pageSize } = parsePage(args, 20);
+    const countData = await queryFolderPermissionPage(env, QUERY_FOLDER_COUNT_PATH, { folderPermissionKey: permissionKey, permissions: apiPermissions }, '查询文件夹数量失败', action);
+    const total = countData.data || 0;
+    const listData = await queryFolderPermissionPage(env, QUERY_FOLDER_LIST_PATH, { folderPermissionKey: permissionKey, permissions: apiPermissions, pageNo, pageSize }, '查询文件夹列表失败', action);
+    const folders = asList(listData.data).filter(isPlainObject).map((item) => ({
+        folder_id: String(item.folderId || ''),
+        folder_name: item.folderName || '',
+        folder_type: item.folderType || '',
+    }));
+    return caizhilianSuccess(action, {
+        total,
+        page_no: pageNo,
+        page_size: pageSize,
+        has_next: pageNo * pageSize < Number(total),
+        folders,
+    });
+}
+// ── 处理器汇总 ────────────────────────────────────────────
+export const caizhilianFolderHandlers = {
+    'caizhilian.folder.create': createFolderHandler,
+    'caizhilian.folder.query-by-name': { execute: queryFoldersByName },
+    'caizhilian.folder.get-settings': { execute: getFolderSettings },
+    'caizhilian.folder.list-default-shares': { execute: listDefaultShares },
+    'caizhilian.folder.default-share.form': { execute: defaultShareForm },
+    'caizhilian.folder.default-share.list': { execute: defaultShareList },
+    'caizhilian.folder.default-share.add': defaultShareAddHandler,
+    'caizhilian.folder.default-share.delete': defaultShareDeleteHandler,
+    'caizhilian.folder.permission.form': { execute: permissionForm },
+    'caizhilian.folder.permission.list': { execute: permissionList },
+    'caizhilian.folder.permission.add': permissionAddHandler,
+    'caizhilian.folder.permission.delete': permissionDeleteHandler,
+    'caizhilian.folder.permission.get-auth': { execute: permissionGetAuth },
+    'caizhilian.folder.permission.set-auth': permissionSetAuthHandler,
+    'caizhilian.folder.permission.detail': { execute: permissionDetail },
+    'caizhilian.folder.permission.query': { execute: permissionQuery },
+    'caizhilian.folder.query-by-permission': { execute: queryFoldersByPermission },
+};