weaver-work-cli 0.1.8 → 0.1.20

package/dist/shortcuts/caizhilian/operations/shared.js

@@ -0,0 +1,408 @@
+import { createHash } from 'node:crypto';
+import { caizhilianValidationError } from '../errors.js';
+/** 原型污染防护：禁止出现在输入对象中的键。 */
+const FORBIDDEN_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+export function asObject(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw caizhilianValidationError('input_not_object', '输入必须是 JSON 对象');
+    }
+    return value;
+}
+export function assertNoForbiddenKeys(input) {
+    for (const key of Object.keys(input)) {
+        if (FORBIDDEN_KEYS.has(key)) {
+            throw caizhilianValidationError('forbidden_key', `输入包含非法字段：${key}`);
+        }
+    }
+}
+/** 移除值为 undefined 的键，避免把空值写进请求体。 */
+export function compact(body) {
+    for (const key of Object.keys(body)) {
+        if (body[key] === undefined)
+            delete body[key];
+    }
+    return body;
+}
+export function pickDefined(value, keys) {
+    const result = {};
+    for (const key of keys) {
+        if (value[key] !== undefined)
+            result[key] = value[key];
+    }
+    return result;
+}
+/** 取业务响应中的 data 段（源 response_convention.data_path = data）。 */
+export function responseData(response) {
+    const data = response?.data;
+    if (data === null || data === undefined)
+        return {};
+    if (typeof data !== 'object')
+        return { value: data };
+    return data;
+}
+export function fingerprint(value) {
+    return createHash('sha256').update(JSON.stringify(value ?? null)).digest('hex').slice(0, 32);
+}
+// ── 标量校验 ──────────────────────────────────────────────
+export function requireText(value, field) {
+    if (value === undefined || value === null) {
+        throw caizhilianValidationError('field_required', `缺少必填参数: ${field}`);
+    }
+    const text = typeof value === 'string' ? value.trim() : String(value).trim();
+    if (!text)
+        throw caizhilianValidationError('field_required', `缺少必填参数: ${field}`);
+    return text;
+}
+export function optionalText(value, field) {
+    if (value === undefined || value === null)
+        return undefined;
+    const text = typeof value === 'string' ? value.trim() : String(value).trim();
+    return text ? text : undefined;
+}
+/** 数字 ID（源统一按字符串提交，这里同时接受数字与数字字符串）。 */
+export function requireId(value, field) {
+    const text = requireText(value, field);
+    if (!/^\d+$/.test(text))
+        throw caizhilianValidationError('id_invalid', `${field} 必须是数字 ID`);
+    return text;
+}
+export function optionalId(value, field) {
+    const text = optionalText(value, field);
+    if (text === undefined)
+        return undefined;
+    if (!/^\d+$/.test(text))
+        throw caizhilianValidationError('id_invalid', `${field} 必须是数字 ID`);
+    return text;
+}
+export function requireIdList(value, field) {
+    const list = requireList(value, field);
+    return list.map((item, index) => requireId(item, `${field}[${index}]`));
+}
+export function optionalIdList(value, field) {
+    if (value === undefined || value === null || value === '')
+        return undefined;
+    return requireIdList(value, field);
+}
+/**
+ * 拒绝超出 JS 安全整数范围（2^53）的整数入参。
+ *
+ * E10 的 ID 是 19 位雪花号，超过安全整数范围；用 JSON 数字传入时在 `JSON.parse` 阶段
+ * 就已经丢精度（如 1261580569640443937 → 1261580569640444000），拿这种 ID 去查询
+ * 服务端只会静默返回空结果，调用方却以为是「接口不支持」。所以在入口处显式报错，
+ * 要求把大整数（ID）改用字符串传入。
+ */
+export function assertNoLossyIntegers(value, path = 'input') {
+    if (typeof value === 'number') {
+        if (Number.isInteger(value) && !Number.isSafeInteger(value)) {
+            throw caizhilianValidationError('number_out_of_range', `${path} 的整数超出安全整数范围（${value}），大整数（如 ID）请改用字符串传入`);
+        }
+        return;
+    }
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => assertNoLossyIntegers(item, `${path}[${index}]`));
+        return;
+    }
+    if (value !== null && typeof value === 'object') {
+        for (const [key, item] of Object.entries(value)) {
+            assertNoLossyIntegers(item, `${path}.${key}`);
+        }
+    }
+}
+export function requireList(value, field) {
+    if (!Array.isArray(value) || value.length === 0) {
+        throw caizhilianValidationError('list_required', `${field} 必填且至少一项`);
+    }
+    return value;
+}
+export function optionalList(value, field) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (!Array.isArray(value))
+        throw caizhilianValidationError('list_invalid', `${field} 必须是数组`);
+    return value.length ? value : undefined;
+}
+/** 字符串数组：源把单值也接受为 [值]。 */
+export function normalizeStringList(value, field) {
+    if (value === undefined || value === null || value === '')
+        return undefined;
+    const list = Array.isArray(value) ? value : [value];
+    const result = list
+        .map((item) => (typeof item === 'string' ? item.trim() : item === undefined || item === null ? '' : String(item)))
+        .filter((item) => item !== '');
+    if (!result.length)
+        return undefined;
+    void field;
+    return result;
+}
+export function assertEnum(value, allowed, field) {
+    const text = requireText(value, field);
+    if (!allowed.includes(text)) {
+        throw caizhilianValidationError('enum_invalid', `${field} 必须是 ${allowed.join(' / ')} 之一，收到: ${JSON.stringify(text)}`);
+    }
+    return text;
+}
+export function optionalEnum(value, allowed, field) {
+    if (value === undefined || value === null || value === '')
+        return undefined;
+    return assertEnum(value, allowed, field);
+}
+export function toBoolean(value, fallback = false) {
+    if (value === undefined || value === null || value === '')
+        return fallback;
+    if (typeof value === 'boolean')
+        return value;
+    const text = String(value).trim().toLowerCase();
+    if (text === 'true' || text === '1')
+        return true;
+    if (text === 'false' || text === '0')
+        return false;
+    return fallback;
+}
+/** 分页参数（源 parse_page_args：page_no>=1、page_size>=1）。 */
+export function parsePage(args, defaultPageSize, defaultPageNo = 1) {
+    const pageNo = toPositiveInt(args.page_no, 'page_no', defaultPageNo);
+    const pageSize = toPositiveInt(args.page_size, 'page_size', defaultPageSize);
+    return { pageNo, pageSize };
+}
+export function toPositiveInt(value, field, fallback) {
+    if (value === undefined || value === null || value === '')
+        return fallback;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        throw caizhilianValidationError('number_invalid', `${field} 必须是正整数`);
+    }
+    return parsed;
+}
+/** 源统一用 has_next = len(list) >= page_size 判断翻页（total 服务端可能为 0，不可信）。 */
+export function hasNextPage(list, pageSize) {
+    return Array.isArray(list) && list.length >= pageSize;
+}
+// ── 时间 ──────────────────────────────────────────────────
+const CN_TZ_OFFSET_MS = 8 * 60 * 60 * 1000;
+function pad(value) {
+    return value < 10 ? `0${value}` : String(value);
+}
+/** 毫秒时间戳 → 东八区 'YYYY-MM-DD HH:MM:SS'（源 _utils.timestamp_to_date_str）。 */
+export function timestampToDateStr(tsMs, fallback = '') {
+    if (tsMs === undefined || tsMs === null || tsMs === '')
+        return fallback;
+    const parsed = Number(tsMs);
+    if (!Number.isFinite(parsed) || parsed < 0)
+        return fallback;
+    return formatDateTimeMs(parsed + CN_TZ_OFFSET_MS, true);
+}
+function formatDateTimeMs(shiftedMs, withSeconds) {
+    const t = new Date(shiftedMs);
+    const date = `${t.getUTCFullYear()}-${pad(t.getUTCMonth() + 1)}-${pad(t.getUTCDate())}`;
+    const time = `${pad(t.getUTCHours())}:${pad(t.getUTCMinutes())}${withSeconds ? `:${pad(t.getUTCSeconds())}` : ''}`;
+    return `${date} ${time}`;
+}
+export const TIME_RANGE_VALUES = [
+    'today',
+    'yesterday',
+    'this_week',
+    'last_week',
+    'this_month',
+    'last_month',
+    'this_year',
+    'last_year',
+    'last_7_days',
+    'last_30_days',
+    'last_90_days',
+];
+const DAY_MS = 24 * 60 * 60 * 1000;
+/**
+ * 解析 create_time 之类的时间范围入参（源 _utils.TimeRange.resolve）。
+ * 支持枚举关键字与 last_<N>_days；也接受调用方直接给出 'YYYY-MM-DD HH:MM~YYYY-MM-DD HH:MM'。
+ * 输出统一为东八区本地时间区间字符串，用 '~' 连接。
+ */
+export function resolveTimeRange(value, field = 'create_time', now = new Date()) {
+    const text = requireText(value, field);
+    if (/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}~\d{4}-\d{2}-\d{2} \d{2}:\d{2}$/.test(text))
+        return text;
+    const cn = now.getTime() + CN_TZ_OFFSET_MS;
+    const shifted = new Date(cn);
+    const todayMs = Date.UTC(shifted.getUTCFullYear(), shifted.getUTCMonth(), shifted.getUTCDate());
+    const nowStr = formatDateTimeMs(cn, false);
+    const at = (ms, hour, minute) => formatDateTimeMs(ms + hour * 3600_000 + minute * 60_000, false);
+    const lastNDays = /^last_(\d+)_days$/.exec(text);
+    switch (text) {
+        case 'today':
+            return `${at(todayMs, 0, 0)}~${nowStr}`;
+        case 'yesterday':
+            return `${at(todayMs - DAY_MS, 0, 0)}~${at(todayMs - DAY_MS, 23, 59)}`;
+        case 'this_week':
+            return `${at(todayMs - weekdayMondayOffset(shifted) * DAY_MS, 0, 0)}~${nowStr}`;
+        case 'last_week': {
+            const thisMonday = todayMs - weekdayMondayOffset(shifted) * DAY_MS;
+            return `${at(thisMonday - 7 * DAY_MS, 0, 0)}~${at(thisMonday - DAY_MS, 23, 59)}`;
+        }
+        case 'this_month':
+            return `${at(Date.UTC(shifted.getUTCFullYear(), shifted.getUTCMonth(), 1), 0, 0)}~${nowStr}`;
+        case 'last_month': {
+            const firstOfThis = Date.UTC(shifted.getUTCFullYear(), shifted.getUTCMonth(), 1);
+            const lastOfPrevious = firstOfThis - DAY_MS;
+            const previous = new Date(lastOfPrevious);
+            return `${at(Date.UTC(previous.getUTCFullYear(), previous.getUTCMonth(), 1), 0, 0)}~${at(lastOfPrevious, 23, 59)}`;
+        }
+        case 'this_year':
+            return `${at(Date.UTC(shifted.getUTCFullYear(), 0, 1), 0, 0)}~${nowStr}`;
+        case 'last_year': {
+            const year = shifted.getUTCFullYear() - 1;
+            return `${at(Date.UTC(year, 0, 1), 0, 0)}~${at(Date.UTC(year, 11, 31), 23, 59)}`;
+        }
+        default:
+            break;
+    }
+    if (lastNDays) {
+        const days = Number(lastNDays[1]);
+        if (days > 0)
+            return `${at(todayMs - (days - 1) * DAY_MS, 0, 0)}~${nowStr}`;
+    }
+    throw caizhilianValidationError('time_range_invalid', `${field} 不支持: ${JSON.stringify(text)}，可选值: ${[...TIME_RANGE_VALUES, 'last_<N>_days'].join(' / ')}`);
+}
+function weekdayMondayOffset(date) {
+    return (date.getUTCDay() + 6) % 7;
+}
+// ── 输入白名单 ────────────────────────────────────────────
+/**
+ * 旧字段别名归一化（遵循模块 CLI 生成规范）：
+ *   - 只把 `deprecatedInputAliases` 登记的旧字段映射到 canonical 字段；
+ *   - canonical 与旧字段同时出现且取值不一致 → 结构化校验错误（禁止任一方静默覆盖）；
+ *   - 归一化后删除旧字段，保证后续纯函数校验与 handler 只看到 canonical 字段。
+ */
+export function normalizeAliases(input, aliases) {
+    const out = { ...input };
+    for (const [canonical, oldKeys] of Object.entries(aliases)) {
+        for (const oldKey of oldKeys) {
+            if (!(oldKey in out))
+                continue;
+            const oldValue = out[oldKey];
+            if (oldValue === undefined || oldValue === null || oldValue === '') {
+                delete out[oldKey];
+                continue;
+            }
+            const canonicalValue = out[canonical];
+            const hasCanonical = canonicalValue !== undefined && canonicalValue !== null && canonicalValue !== '';
+            if (hasCanonical && JSON.stringify(canonicalValue) !== JSON.stringify(oldValue)) {
+                throw caizhilianValidationError('alias_conflict', `字段 ${canonical} 与旧字段 ${oldKey} 同时出现且取值不一致，请只保留一个`);
+            }
+            if (!hasCanonical)
+                out[canonical] = oldValue;
+            delete out[oldKey];
+        }
+    }
+    return out;
+}
+/** 顶层输入严格白名单：schema 已声明 additionalProperties: false，运行时同样拒绝未知字段。 */
+export function assertKnownKeys(input, allowed, operation) {
+    const unknown = Object.keys(input).filter((key) => !allowed.includes(key));
+    if (unknown.length > 0) {
+        throw caizhilianValidationError('unknown_field', `${operation} 不支持字段：${unknown.join('、')}`, { unknown });
+    }
+}
+/**
+ * 与源 `if args.get(key)` 真值语义一致的可选字符串：
+ * 仅过滤 undefined / null / 空串，保留原始空白（正文、HTML 不做 trim）。
+ */
+export function optionalRawText(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    const text = typeof value === 'string' ? value : String(value);
+    return text === '' ? undefined : text;
+}
+// ── Python 语义小工具（源脚本直译）────────────────────────
+/** 源 `isinstance(x, dict)`：排除数组与 null 的普通对象判断。 */
+export function isPlainObject(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+/** 源 Python repr 的字符串形态（报错文案里用 !r 输出）。 */
+export function pyRepr(value) {
+    return typeof value === 'string' ? `'${value}'` : JSON.stringify(value) ?? String(value);
+}
+/**
+ * 源 int(x) 语义：数字截断取整，字符串必须整体是整数，None/'' 用默认值，
+ * 其余抛错（对应 Python 的 TypeError / ValueError）。
+ */
+export function pyInt(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            throw new TypeError('int() argument out of range');
+        return Math.trunc(value);
+    }
+    const text = value === null ? '' : String(value).trim();
+    if (!/^[+-]?\d+$/.test(text))
+        throw new TypeError(`int() invalid literal: ${pyRepr(value)}`);
+    return Number(text);
+}
+// ── 源文案对齐的小工具 ────────────────────────────────────
+/** 源 `str(args.get(k) or "").strip()` + 各自的空值文案。 */
+export function requireNonEmpty(value, message, subtype = 'field_required') {
+    const text = value === undefined || value === null ? '' : String(value).trim();
+    if (!text)
+        throw caizhilianValidationError(subtype, message);
+    return text;
+}
+/** 源 `",".join(str(i) for i in ids)`（非列表时直接 str(ids)）。 */
+export function joinIds(value) {
+    return Array.isArray(value) ? value.map((item) => String(item)).join(',') : String(value);
+}
+/** 源 `if not ids` 的真值判断（None / 空串 / 空列表 / 0 均视为空）。 */
+export function isFalsyIds(value) {
+    if (value === undefined || value === null)
+        return true;
+    if (Array.isArray(value))
+        return value.length === 0;
+    if (typeof value === 'string')
+        return value.trim() === '';
+    if (typeof value === 'number')
+        return value === 0;
+    return false;
+}
+/** 源 sorted(x) + ', '.join(...) 的报错文案片段。 */
+export function sortedJoin(values) {
+    return [...values].sort().join(', ');
+}
+/** 源 f-string 里 `{args.get(k)}` 的 str() 形态（None → 'None'）。 */
+export function pyStr(value) {
+    if (value === undefined || value === null)
+        return 'None';
+    if (typeof value === 'string')
+        return value;
+    return JSON.stringify(value) ?? String(value);
+}
+/** 源 `str(record.get(key, ""))`：键缺失取空串，键存在但为 None 取 'None'。 */
+export function pyGetStr(record, key) {
+    return key in record ? pyStr(record[key]) : '';
+}
+/** 源 Python bool() 语义（注意 'false' 这类非空字符串为真、NaN 为真）。 */
+export function pyBool(value) {
+    if (value === undefined || value === null)
+        return false;
+    if (typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number')
+        return value !== 0;
+    if (typeof value === 'string')
+        return value.length > 0;
+    if (Array.isArray(value))
+        return value.length > 0;
+    if (isPlainObject(value))
+        return Object.keys(value).length > 0;
+    return true;
+}
+/**
+ * 源 _plugin_helpers.validate_required_params：
+ * 键缺失（None）或纯空白字符串视为缺失；数字 0 / False 等非字符串假值不算缺失。
+ * 报错文案与源一致：`缺少必填参数: <key>`，按 required 顺序逐个校验。
+ */
+export function validateRequiredParams(args, required) {
+    for (const key of required) {
+        const value = args[key];
+        if (value === undefined || value === null || (typeof value === 'string' && !value.trim())) {
+            throw caizhilianValidationError('field_required', `缺少必填参数: ${key}`);
+        }
+    }
+}