weaver-work-cli 0.1.29 → 0.1.31

package/dist/shortcuts/contract/operations/performance.js

@@ -0,0 +1,733 @@
+/**
+ * ⑨ 业绩核算：原六菜单链接构造（纯本地）+ 来源台账 List 只读查询（HTTP）。
+ *
+ * 语义与源脚本 query_link.py / eb-list-api.md 对齐：
+ * - 人员/枚举/数值/数值区间条件一律进 needs_ui，由用户在页面补填，AI 不代操作。
+ * - combination 路由（合同收款）不透传筛选 query，只出入口地址。
+ * - searchPermittedEbMenus 请求体是关键词字符串数组，不是对象。
+ * - VIEWPORT/NList 分支未实现（customConfig 需平台 LZW 编码），遇到即报错说明。
+ */
+import { PERFORMANCE_CATALOG, CONTRACT_SOURCES, } from '../data/performance-catalog.js';
+import { contractValidationError } from '../errors.js';
+import { requireNonEmptyString } from './shared.js';
+const ORIGIN_PLACEHOLDER = '{baseUrl}';
+const BROWSER_WIDTH = 1000;
+const NULL_OPS = new Set(['isNull', 'isNotNull']);
+function catalog() {
+    return PERFORMANCE_CATALOG;
+}
+function findMenu(name) {
+    const c = catalog();
+    const matches = c.menus.filter((m) => m.name === name || m.aliases.includes(name));
+    if (matches.length !== 1) {
+        throw contractValidationError('menu_ambiguous', '请选择菜单：' + c.menus.map((m) => m.name).join('、'));
+    }
+    return matches[0];
+}
+function findField(menu, name) {
+    const matches = menu.fields.filter((f) => name === f[0] || name === f[1] || name === 'field_' + f[1]);
+    if (matches.length !== 1) {
+        throw contractValidationError('field_not_found', `${menu.name}没有唯一字段 ${name}`);
+    }
+    return matches[0];
+}
+function normalizePeriod(value) {
+    const v = String(value).replace(/\s+/gu, '').replace('年', '-').replace(/月/gu, '').replace(/-$/u, '');
+    const m = /^(\d{4})(?:-(\d{1,2}))?$/u.exec(v);
+    if (!m)
+        throw contractValidationError('bad_period', '年月应为 YYYY 或 YYYY-MM；相对日期先按用户时区换算。');
+    const year = parseInt(m[1], 10);
+    if (m[2]) {
+        const month = parseInt(m[2], 10);
+        if (month < 1 || month > 12)
+            throw contractValidationError('bad_period', '月份超出 1-12。');
+        return `${String(year).padStart(4, '0')}-${String(month).padStart(2, '0')}`;
+    }
+    return String(year);
+}
+function periodCondition(menu, period, fieldName) {
+    const p = normalizePeriod(period);
+    const name = fieldName ?? menu.default_time;
+    if (!name) {
+        throw contractValidationError('no_default_time', '渠道订单-商务没有默认业绩年月，请指定 time-field：签订年份、签订月份或签订日期。');
+    }
+    const field = findField(menu, name);
+    if (field[2] === 'date') {
+        const year = parseInt(p.slice(0, 4), 10);
+        const hasMonth = p.includes('-');
+        const month = hasMonth ? parseInt(p.slice(5), 10) : 1;
+        const lastDay = hasMonth ? new Date(year, month, 0).getDate() : 31;
+        const endMonth = hasMonth ? month : 12;
+        const endDay = hasMonth ? lastDay : 31;
+        const pad = (n) => String(n).padStart(2, '0');
+        return {
+            field: name,
+            operator: 'between',
+            value: [`${year}-${pad(month)}-01`, `${year}-${pad(endMonth)}-${pad(endDay)}`],
+        };
+    }
+    const isYearMonth = name.endsWith('年月') || name === '签订年份' || name === '签订月份';
+    if (field[2] !== 'text' || !isYearMonth) {
+        throw contractValidationError('bad_time_field', `${name}不是已核对的年月/日期字段。`);
+    }
+    if (name === '签订年份' && p.includes('-')) {
+        throw contractValidationError('bad_time_field', '按月份查询商务订单时使用 time-field「签订月份」。');
+    }
+    return { field: name, operator: 'startWith', value: p };
+}
+function numberText(value) {
+    const s = String(value).replace(/,/gu, '').trim();
+    if (!/^-?\d+(\.\d+)?$/u.test(s)) {
+        throw contractValidationError('bad_number', `数值应为纯数字，先换算“万”等单位：${String(value)}`);
+    }
+    return String(parseFloat(s));
+}
+function encodeURIComponent0(v) {
+    return encodeURIComponent(v);
+}
+function buildQuery(menu, conditions, origin) {
+    const c = catalog();
+    const route = `/ebdapp/view/${c.app_id}/${menu.route}/${menu.page_id}-${menu.menu_id}`;
+    const params = [
+        ['cusMenuId', menu.menu_id],
+        ['urlPageTitle', menu.title_param],
+        ['appId_' + (menu.app_param_page_id ?? menu.page_id), c.app_id],
+    ];
+    const filters = [];
+    const needsUi = [];
+    const warnings = [];
+    const seen = new Set();
+    for (const condition of conditions) {
+        const label = String(condition.field);
+        const [fLabel, fid, kind] = findField(menu, label);
+        const key = 'field_' + fid;
+        if (seen.has(key)) {
+            throw contractValidationError('duplicate_condition', `${fLabel}条件重复；先合并，不能通过覆盖丢弃条件。`);
+        }
+        seen.add(key);
+        const op = condition.operator ?? findField(menu, label)[3];
+        const allowed = c.operators[kind];
+        if (!allowed?.includes(op)) {
+            throw contractValidationError('bad_operator', `${fLabel}不支持操作符 ${op}`);
+        }
+        let value = condition.value;
+        if (!NULL_OPS.has(op) && (value === undefined || value === null || value === '' || (Array.isArray(value) && value.length === 0))) {
+            throw contractValidationError('missing_value', `${fLabel}缺少筛选值。`);
+        }
+        const item = { field: fLabel, key, operator: op, value };
+        if (NULL_OPS.has(op)) {
+            value = '';
+        }
+        else if (kind.startsWith('person') || kind === 'browser') {
+            needsUi.push({ ...item, reason: '需用户在页面检索并选择真实人员/关联对象，核对同名项后搜索；AI不代操作。' });
+            continue;
+        }
+        else if (kind in c.enums) {
+            const choices = Array.isArray(value) ? value : [value];
+            const mapping = c.enums[kind];
+            const ids = [];
+            for (const choice of choices) {
+                const cs = String(choice);
+                if (cs in mapping)
+                    ids.push(mapping[cs]);
+                else if (Object.values(mapping).includes(cs))
+                    ids.push(cs);
+                else
+                    throw contractValidationError('bad_enum', `${fLabel}没有选项 ${cs}`);
+            }
+            needsUi.push({ ...item, resolved_ids: ids, reason: '需用户在页面选择枚举项并搜索；枚举URL序列化未实测，AI不代操作。' });
+            continue;
+        }
+        else if (op === 'between') {
+            if (!Array.isArray(value) || value.length !== 2) {
+                throw contractValidationError('bad_between', `${fLabel}的 between 条件需要两个边界组成的数组。`);
+            }
+            if (kind === 'date') {
+                const [a, b] = value.map((x) => String(x));
+                if (!/^\d{4}-\d{2}-\d{2}$/u.test(a) || !/^\d{4}-\d{2}-\d{2}$/u.test(b)) {
+                    throw contractValidationError('bad_between', `${fLabel}的日期边界应为 YYYY-MM-DD。`);
+                }
+                if (a > b)
+                    throw contractValidationError('bad_between', `${fLabel}范围起点大于终点。`);
+                value = [a, b];
+            }
+            else {
+                const [a, b] = value.map((x) => numberText(x));
+                if (parseFloat(a) > parseFloat(b))
+                    throw contractValidationError('bad_between', `${fLabel}范围起点大于终点。`);
+                needsUi.push({ ...item, value: [a, b], reason: '需用户在页面填写数值范围并搜索；数值URL序列化未实测，AI不代操作。' });
+                continue;
+            }
+            const bounds = value;
+            params.push([key + '[0]', String(bounds[0])], [key + '[1]', String(bounds[1])], [key + '_condition_type', op]);
+            filters.push({ ...item, value });
+            continue;
+        }
+        else if (kind === 'number') {
+            needsUi.push({ ...item, value: numberText(value), reason: '需用户在页面应用数值条件并搜索；数值URL序列化未实测，AI不代操作。' });
+            continue;
+        }
+        else if (typeof value === 'object') {
+            throw contractValidationError('bad_value', `${fLabel}需要字符串筛选值。`);
+        }
+        else {
+            value = String(value);
+        }
+        params.push([key, value], [key + '_condition_type', op]);
+        filters.push({ ...item, value });
+    }
+    if (menu.route === 'combination') {
+        for (const f of filters)
+            needsUi.push({ ...f, reason: '组合页不透传筛选query；需用户填写该条件并搜索，AI不代操作。' });
+        filters.length = 0;
+        params.length = 3;
+    }
+    const defaultTime = menu.default_time;
+    if (defaultTime && ![...filters, ...needsUi].some((f) => f.field === defaultTime)) {
+        warnings.push(`页面可能默认限制${defaultTime}为当年。请用户核对实际范围；要求全部年份/其他时间口径时，由用户清空默认年月再搜索。`);
+    }
+    const url = origin + route + '?' + params.map(([k, v]) => `${encodeURIComponent0(k)}=${encodeURIComponent0(v)}`).join('&');
+    return {
+        menu: menu.name,
+        url,
+        filters,
+        needs_ui: needsUi,
+        warnings,
+        browsertool: {
+            version: '1.0',
+            callId: 'performance-query-1',
+            toolId: 'open_web',
+            arguments: { url, title: menu.name, activate: true, width: BROWSER_WIDTH },
+        },
+        page_verified: false,
+        execution: needsUi.length ? 'manual-page-filter' : 'filtered-link',
+    };
+}
+function requireOrigin(input) {
+    const raw = String(input.origin ?? '').trim();
+    if (!raw) {
+        throw contractValidationError('origin_required', `缺少业务域名 origin：传当前环境 baseUrl（与合同办公同一个域名，形如 https://xxx.cn），不要传含 ${ORIGIN_PLACEHOLDER} 的占位值。`);
+    }
+    if (raw.includes(ORIGIN_PLACEHOLDER)) {
+        throw contractValidationError('origin_unresolved', `业务域名未解析：origin 含 ${ORIGIN_PLACEHOLDER} 占位符。`);
+    }
+    let parsed;
+    try {
+        parsed = new URL(raw);
+    }
+    catch {
+        throw contractValidationError('bad_origin', 'origin 必须是完整的 http/https 域名。');
+    }
+    if (!/^https?:$/u.test(parsed.protocol) || !parsed.hostname) {
+        throw contractValidationError('bad_origin', 'origin 必须是完整的 http/https 域名。');
+    }
+    if (parsed.username || (parsed.pathname && parsed.pathname !== '/') || parsed.search || parsed.hash) {
+        throw contractValidationError('bad_origin', 'origin 只能是 scheme+host，不能带路径、query 或用户信息。');
+    }
+    return raw.replace(/\/$/u, '');
+}
+// ---------------------------------------------------------------- 操作定义
+function pageContract(name, summary, props, required) {
+    return { name, summary, risk: 'read', inputSchema: { type: 'object', additionalProperties: false, properties: props, required } };
+}
+export const contractPerformanceOperations = [
+    {
+        name: 'contract.performance.link',
+        inputSchema: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                menu: { type: 'string' },
+                origin: { type: 'string' },
+                period: { type: 'string' },
+                'time-field': { type: 'string' },
+                conditions: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        additionalProperties: false,
+                        properties: { field: { type: 'string' }, operator: { type: 'string' }, value: {} },
+                    },
+                },
+            },
+            required: ['menu', 'origin'],
+        },
+        async execute(input) {
+            const menu = findMenu(requireNonEmptyString(input.menu, 'menu'));
+            const origin = requireOrigin(input);
+            const conditions = [];
+            if (input.period) {
+                conditions.push(periodCondition(menu, String(input.period), input['time-field'] ? String(input['time-field']) : undefined));
+            }
+            else if (input['time-field']) {
+                throw contractValidationError('period_required', 'time-field 需要与 period 同时使用。');
+            }
+            let conditionList = input.conditions;
+            if (typeof conditionList === 'string') {
+                try {
+                    conditionList = JSON.parse(conditionList);
+                }
+                catch {
+                    throw contractValidationError('bad_conditions', 'conditions 不是合法 JSON 数组。');
+                }
+            }
+            if (Array.isArray(conditionList)) {
+                for (const c of conditionList) {
+                    conditions.push({ field: String(c.field), operator: c.operator ? String(c.operator) : undefined, value: c.value });
+                }
+            }
+            const built = buildQuery(menu, conditions, origin);
+            return {
+                status: 'DONE',
+                data: built,
+            };
+        },
+    },
+    {
+        name: 'contract.performance.fields',
+        inputSchema: {
+            type: 'object',
+            additionalProperties: false,
+            properties: { menu: { type: 'string' } },
+            required: ['menu'],
+        },
+        async execute(input) {
+            const c = catalog();
+            const menu = findMenu(requireNonEmptyString(input.menu, 'menu'));
+            return {
+                status: 'DONE',
+                data: {
+                    menu: menu.name,
+                    default_time: menu.default_time ?? null,
+                    fields: menu.fields.map((f) => ({
+                        label: f[0],
+                        key: 'field_' + f[1],
+                        kind: f[2],
+                        default_operator: f[3],
+                        operators: c.operators[f[2]] ?? [],
+                        options: c.enums[f[2]] ?? null,
+                    })),
+                },
+            };
+        },
+    },
+    {
+        name: 'contract.performance.source.entry',
+        inputSchema: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                source: { type: 'string', description: '来源名或别名；缺省返回全部三个来源' },
+                origin: { type: 'string' },
+            },
+            required: ['origin'],
+        },
+        async execute(input) {
+            const origin = requireOrigin(input);
+            const sources = CONTRACT_SOURCES.sources;
+            const wanted = input.source ? String(input.source) : null;
+            const out = sources
+                .filter((s) => !wanted || s.source === wanted || s.aliases.includes(wanted))
+                .map((s) => ({
+                source: s.source,
+                entry_url: origin + s.list_entry.url,
+                card_path: s.card_path,
+                obj_id: s.obj_id,
+            }));
+            if (wanted && out.length === 0) {
+                throw contractValidationError('source_not_found', '来源不存在，可选：' + sources.map((s) => s.source).join('、'));
+            }
+            return { status: 'DONE', data: { sources: out } };
+        },
+    },
+    {
+        name: 'contract.performance.menu.search',
+        risk: 'read',
+        inputSchema: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                keywords: { type: 'array', items: { type: 'string' }, description: '关键词数组，每个菜单必须唯一匹配' },
+            },
+            required: ['keywords'],
+        },
+        async execute(input, context) {
+            let keywordList = input.keywords;
+            if (typeof keywordList === 'string') {
+                try {
+                    keywordList = JSON.parse(keywordList);
+                }
+                catch {
+                    throw contractValidationError('bad_keywords', 'keywords 不是合法 JSON 数组。');
+                }
+            }
+            if (!Array.isArray(keywordList))
+                throw contractValidationError('bad_keywords', 'keywords 必须是字符串数组。');
+            const keywords = keywordList.map((k) => requireNonEmptyString(k, 'keywords'));
+            const result = (await context.host.contractRequest({
+                method: 'POST',
+                path: '/api/ebuilder/form/viewlist/searchPermittedEbMenus',
+                body: keywords,
+            }));
+            const menus = Array.isArray(result) ? result : (result.data ?? []);
+            return {
+                status: 'DONE',
+                data: {
+                    menus: menus.map((m) => ({
+                        name: m.menuName ?? m.name ?? null,
+                        pageType: m.pageType ?? null,
+                        pageId: m.pageId ?? null,
+                        menuUrl: m.menuUrl ?? null,
+                        appId: m.appId ?? null,
+                        objId: m.objId ?? null,
+                    })),
+                    note: 'pageType=SEARCH 的 pageId 即 listId；VIEWPORT 的 pageId 是 hostPageId（本 CLI 未实现 VIEWPORT 查询）。',
+                },
+            };
+        },
+    },
+    {
+        name: 'contract.performance.list.init',
+        risk: 'read',
+        inputSchema: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                apiPrefix: { type: 'string', description: '/api/ebuilder 或 /api/ebuilder{appId}' },
+                listId: { type: 'string' },
+                expectedObjId: { type: 'string', description: '来源配置里已确认的表单 ID，传入则校验' },
+            },
+            required: ['apiPrefix', 'listId'],
+        },
+        async execute(input, context) {
+            const prefix = requireApiPrefix(input.apiPrefix);
+            const listId = requireNonEmptyString(input.listId, 'listId');
+            const result = (await context.host.contractRequest({
+                method: 'POST',
+                path: `${prefix}/form/list/listInit`,
+                body: { listId },
+            }));
+            const objId = result?.data?.objid ?? result?.data?.objId ?? null;
+            if (objId == null) {
+                throw contractValidationError('list_init_failed', 'listInit 未返回 objId，不能继续查询。');
+            }
+            if (input.expectedObjId && String(objId) !== String(input.expectedObjId)) {
+                throw contractValidationError('obj_id_mismatch', `listInit 的 objId ${objId} 与来源配置 ${input.expectedObjId} 不一致，停止查询。`);
+            }
+            return { status: 'DONE', data: { objId: String(objId), apiPrefix: prefix, listId } };
+        },
+    },
+    {
+        name: 'contract.performance.list.filters',
+        risk: 'read',
+        inputSchema: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                apiPrefix: { type: 'string' },
+                listId: { type: 'string' },
+                appId: { type: 'string' },
+                objId: { type: 'string' },
+                includeFields: { type: 'boolean', description: '是否同时读取列映射 getListFields' },
+            },
+            required: ['apiPrefix', 'listId', 'appId', 'objId'],
+        },
+        async execute(input, context) {
+            const prefix = requireApiPrefix(input.apiPrefix);
+            const listId = requireNonEmptyString(input.listId, 'listId');
+            const appId = requireNonEmptyString(input.appId, 'appId');
+            const objId = requireNonEmptyString(input.objId, 'objId');
+            const query = { apid: appId, tpaid: listId, objId, viewType: 'tableView', isVirtualForm: 'false' };
+            const filters = (await context.host.contractRequest({
+                method: 'GET',
+                path: `${prefix}/form/listFilter/getSearchFilters/${listId}`,
+                query,
+            }));
+            let fields = null;
+            if (input.includeFields) {
+                fields = await context.host.contractRequest({
+                    method: 'GET',
+                    path: `${prefix}/form/list/getListFields/${listId}`,
+                    query: { ...query, clientType: 'PC' },
+                });
+            }
+            return { status: 'DONE', data: { filters: filters?.data ?? filters, fields } };
+        },
+    },
+    {
+        name: 'contract.performance.list.query',
+        risk: 'read',
+        inputSchema: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                apiPrefix: { type: 'string' },
+                listId: { type: 'string' },
+                appId: { type: 'string' },
+                objId: { type: 'string' },
+                searchFieldId: { type: 'string', description: '真实合同号字段 ID' },
+                searchOperator: { type: 'string', description: '默认 eq；仅支持 eq/like/startWith' },
+                searchValue: { type: 'string', description: '完整合同号或关键词' },
+                searchParamJson: {
+                    type: 'string',
+                    description: '完整 searchParamData JSON 字符串；提供时忽略 searchFieldId/Operator/Value',
+                },
+                pageSize: { type: 'number' },
+                maxPages: { type: 'number', description: '最多翻页数，默认 10；到达上限且仍有数据会提示缩小范围' },
+            },
+            required: ['apiPrefix', 'listId', 'appId', 'objId'],
+        },
+        async execute(input, context) {
+            const prefix = requireApiPrefix(input.apiPrefix);
+            const listId = requireNonEmptyString(input.listId, 'listId');
+            const appId = requireNonEmptyString(input.appId, 'appId');
+            const objId = requireNonEmptyString(input.objId, 'objId');
+            const pageSize = input.pageSize ? Number(input.pageSize) : 200;
+            const maxPages = input.maxPages ? Number(input.maxPages) : 10;
+            let searchParamData;
+            if (input.searchParamJson) {
+                try {
+                    searchParamData = JSON.parse(String(input.searchParamJson));
+                }
+                catch {
+                    throw contractValidationError('bad_search_param', 'searchParamJson 不是合法 JSON。');
+                }
+            }
+            else {
+                const fieldId = requireNonEmptyString(input.searchFieldId, 'searchFieldId');
+                const value = requireNonEmptyString(input.searchValue, 'searchValue');
+                const op = input.searchOperator ? String(input.searchOperator) : 'eq';
+                if (!['eq', 'like', 'startWith'].includes(op)) {
+                    throw contractValidationError('bad_operator', '本操作仅支持 eq/like/startWith；其他条件请在页面完成。');
+                }
+                const key = 'field_' + fieldId;
+                searchParamData = {
+                    searchType: '2',
+                    type: 'and',
+                    groupFields: {},
+                    commonSearchFields: {
+                        [key]: [{ [key]: value, [key + '_condition_type']: op }],
+                    },
+                };
+            }
+            const tableuid = `wb-${Date.now()}-${Math.floor(Math.random() * 1e8)}`;
+            const body = {
+                current: 1,
+                pageSize,
+                requiredMatch: 1,
+                tableuid,
+                listId,
+                searchParamData,
+                isFollow: 0,
+                isShareToMe: 0,
+                filterCondition: {},
+                terminal: 'PC',
+            };
+            const rows = [];
+            let total = null;
+            let page = 1;
+            for (; page <= maxPages; page++) {
+                body.current = page;
+                const data = (await context.host.contractRequest({
+                    method: 'POST',
+                    path: `${prefix}/form/list/getListDatas?passid=${objId}&cid=${objId}`,
+                    body,
+                }));
+                const display = data?.data?.displayData;
+                const batch = Array.isArray(display) ? display : Array.isArray(data?.data?.rows) ? data.data.rows : [];
+                rows.push(...batch);
+                const count = (await context.host.contractRequest({
+                    method: 'POST',
+                    path: `${prefix}/form/list/getListDataCount?passid=${objId}&cid=${objId}`,
+                    body,
+                }));
+                total = Number(count?.data?.total ?? 0);
+                if (rows.length >= (total ?? 0))
+                    break;
+            }
+            const truncated = total !== null && rows.length < total;
+            return {
+                status: 'DONE',
+                data: {
+                    context: { objId, appId, listId, apiPrefix: prefix },
+                    searchParamData,
+                    rows,
+                    pagination: { total, fetched: rows.length, pageSize, truncated, maxPages },
+                    warning: truncated
+                        ? `真实总数 ${total} 超过本次取回 ${rows.length} 条（maxPages=${maxPages}）。请缩小范围后重查，不能把部分结果当全量。`
+                        : null,
+                },
+            };
+        },
+    },
+    {
+        name: 'contract.performance.receipt.query',
+        risk: 'read',
+        inputSchema: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                origin: { type: 'string' },
+                listId: { type: 'string', description: '收款 List 的 listId；缺省用 catalog 里「合同收款」菜单的 list_id' },
+                apiPrefix: { type: 'string' },
+                appId: { type: 'string' },
+                objId: { type: 'string' },
+                contractNumbers: { type: 'array', items: { type: 'string' }, description: '完整合同号列表' },
+                pageSize: { type: 'number' },
+            },
+            required: ['origin', 'contractNumbers'],
+        },
+        async execute(input, context) {
+            const origin = requireOrigin(input);
+            const c = catalog();
+            const menu = findMenu('合同收款');
+            const listId = input.listId ? String(input.listId) : menu.list_id;
+            if (!listId) {
+                throw contractValidationError('list_id_required', 'catalog 未记录「合同收款」的 listId，请传 listId。');
+            }
+            let numberList = input.contractNumbers;
+            if (typeof numberList === 'string') {
+                try {
+                    numberList = JSON.parse(numberList);
+                }
+                catch {
+                    throw contractValidationError('bad_contract_numbers', 'contractNumbers 不是合法 JSON 数组。');
+                }
+            }
+            if (!Array.isArray(numberList))
+                throw contractValidationError('bad_contract_numbers', 'contractNumbers 必须是字符串数组。');
+            const numbers = numberList.map((n) => requireNonEmptyString(n, 'contractNumbers'));
+            // 先 init 拿真实运行上下文
+            const init = (await context.host.contractRequest({
+                method: 'POST',
+                path: `/api/ebuilder/form/list/listInit`,
+                body: { listId },
+            }));
+            const objId = String(init?.data?.objid ?? init?.data?.objId ?? '');
+            if (!objId)
+                throw contractValidationError('list_init_failed', '收款 List listInit 未返回 objId。');
+            const appId = input.appId ? String(input.appId) : String(c.app_id);
+            const prefix = input.apiPrefix ? requireApiPrefix(input.apiPrefix) : '/api/ebuilder';
+            const fieldId = menu.fields.find((f) => f[0] === '合同号')?.[1];
+            if (!fieldId)
+                throw contractValidationError('field_missing', 'catalog 中「合同收款」没有合同号字段。');
+            const pageSize = input.pageSize ? Number(input.pageSize) : 200;
+            const results = [];
+            for (const number of numbers) {
+                const searchParamData = {
+                    searchType: '2',
+                    type: 'and',
+                    groupFields: {},
+                    commonSearchFields: {
+                        ['field_' + fieldId]: [{ ['field_' + fieldId]: number, ['field_' + fieldId + '_condition_type']: 'eq' }],
+                    },
+                };
+                const tableuid = `wb-${Date.now()}-${Math.floor(Math.random() * 1e8)}`;
+                const body = {
+                    current: 1, pageSize, requiredMatch: 1, tableuid, listId, searchParamData,
+                    isFollow: 0, isShareToMe: 0, filterCondition: {}, terminal: 'PC',
+                };
+                try {
+                    const data = (await context.host.contractRequest({
+                        method: 'POST',
+                        path: `${prefix}/form/list/getListDatas?passid=${objId}&cid=${objId}`,
+                        body,
+                    }));
+                    const count = (await context.host.contractRequest({
+                        method: 'POST',
+                        path: `${prefix}/form/list/getListDataCount?passid=${objId}&cid=${objId}`,
+                        body,
+                    }));
+                    const display = data?.data?.displayData;
+                    const rows = Array.isArray(display) ? display : Array.isArray(data?.data?.rows) ? data.data.rows : [];
+                    const total = Number(count?.data?.total ?? 0);
+                    results.push({
+                        contract_number: number,
+                        status: rows.length ? 'receipt_records_found' : 'no_accessible_receipt',
+                        record_count: rows.length,
+                        total,
+                        rows,
+                        message: rows.length ? '当前账户查询到收款记录；有记录不代表已收齐。' : '当前账户范围内未查到该合同号的收款记录。',
+                    });
+                }
+                catch (error) {
+                    results.push({
+                        contract_number: number,
+                        status: 'query_failed',
+                        stage: 'receipt_ledger_query',
+                        message: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            }
+            const failed = results.filter((r) => r.status === 'query_failed').length;
+            return {
+                status: 'DONE',
+                data: {
+                    results,
+                    entry_url: origin + `/ebdapp/view/${c.app_id}/${menu.route}/${menu.page_id}-${menu.menu_id}`,
+                    status_summary: failed === results.length ? 'failed' : failed ? 'partial' : 'success',
+                    note: '组合页仅是 UI 容器；数据来自其底层 List。收款时间范围如需限定，请在页面或后续条件中明确，前轮合同年份不自动变为收款年份。',
+                },
+            };
+        },
+    },
+];
+export function performanceContractContracts() {
+    return [
+        pageContract('contract.performance.link', '构造原六业绩菜单的过滤链接（纯本地）', {
+            menu: { type: 'string' },
+            origin: { type: 'string' },
+            period: { type: 'string' },
+            'time-field': { type: 'string' },
+            conditions: { type: 'array', items: { type: 'object' } },
+        }, ['menu', 'origin']),
+        pageContract('contract.performance.fields', '列出业绩菜单筛选字段（纯本地）', { menu: { type: 'string' } }, ['menu']),
+        pageContract('contract.performance.source.entry', '三类合同来源台账入口地址（纯本地）', {
+            source: { type: 'string' },
+            origin: { type: 'string' },
+        }, ['origin']),
+        pageContract('contract.performance.menu.search', '按关键词搜索有权限的 EB 菜单', {
+            keywords: { type: 'array', items: { type: 'string' } },
+        }, ['keywords']),
+        pageContract('contract.performance.list.init', 'List 初始化并校验 objId', {
+            apiPrefix: { type: 'string' },
+            listId: { type: 'string' },
+            expectedObjId: { type: 'string' },
+        }, ['apiPrefix', 'listId']),
+        pageContract('contract.performance.list.filters', '读取搜索配置与列映射', {
+            apiPrefix: { type: 'string' },
+            listId: { type: 'string' },
+            appId: { type: 'string' },
+            objId: { type: 'string' },
+            includeFields: { type: 'boolean' },
+        }, ['apiPrefix', 'listId', 'appId', 'objId']),
+        pageContract('contract.performance.list.query', '按精确条件查询来源台账（全页）', {
+            apiPrefix: { type: 'string' },
+            listId: { type: 'string' },
+            appId: { type: 'string' },
+            objId: { type: 'string' },
+            searchFieldId: { type: 'string' },
+            searchOperator: { type: 'string' },
+            searchValue: { type: 'string' },
+            searchParamJson: { type: 'string' },
+            pageSize: { type: 'number' },
+            maxPages: { type: 'number' },
+        }, ['apiPrefix', 'listId', 'appId', 'objId']),
+        pageContract('contract.performance.receipt.query', '按合同号查合同收款台账', {
+            origin: { type: 'string' },
+            listId: { type: 'string' },
+            apiPrefix: { type: 'string' },
+            appId: { type: 'string' },
+            objId: { type: 'string' },
+            contractNumbers: { type: 'array', items: { type: 'string' } },
+            pageSize: { type: 'number' },
+        }, ['origin', 'contractNumbers']),
+    ];
+}
+function requireApiPrefix(value) {
+    const raw = requireNonEmptyString(value, 'apiPrefix');
+    if (raw !== '/api/ebuilder' && !/^\/api\/ebuilder\/?\d+$/u.test(raw) && !/^\/api\/ebuilder\d+$/u.test(raw)) {
+        throw contractValidationError('bad_api_prefix', `apiPrefix 只能是 /api/ebuilder 或 /api/ebuilder{appId}，收到：${raw}`);
+    }
+    return raw;
+}