zentao-api 0.3.1 → 0.3.3

package/dist/modules/registry.js

@@ -1,224 +1,19 @@
-import { ZentaoError } from '../misc/errors.js';
-import { asArray } from '../utils/index.js';
+// 模块注册表的统一出入口（barrel）。
+// 实际实现按职责拆分：
+// - ./registry-store —— 共享运行时状态与 克隆/冻结/合并/校验 等底层原语（内部使用）。
+// - ./define         —— 定义/写入模块（defineModules / defineModuleActions / resetModuleDefinitions）。
+// - ./override       —— 内置覆盖/扩展（基于 define，随 SDK 发布并在加载/重置时自动应用）。
+// - ./query          —— 获取模块信息（getModule / getModuleAction / getModuleNames / isModuleName）。
 import { BUILTIN_MODULES } from './generated.js';
+import { applyBuiltinOverrides } from './override.js';
+import { setPostResetHook } from './registry-store.js';
 export { BUILTIN_MODULES };
 export const MODULES = BUILTIN_MODULES;
-// 运行时注册表存放「深克隆 + 深冻结」后的模块定义：
-// - 深克隆：避免用户后续修改自己的输入对象时污染注册表；
-// - 深冻结：让 getModule / getModuleAction 可以零拷贝返回引用，
-//   外部尝试改写会在严格模式下抛 TypeError，开销也降到 O(1) 查询。
-let modules = freezeModules(cloneBuiltinModules());
-let moduleMap = buildModuleMap(modules);
-function deepClone(value) {
-    if (Array.isArray(value)) {
-        return value.map((item) => deepClone(item));
-    }
-    if (value && typeof value === 'object' && !(value instanceof Function)) {
-        const result = {};
-        for (const [key, nestedValue] of Object.entries(value)) {
-            result[key] = deepClone(nestedValue);
-        }
-        return result;
-    }
-    return value;
-}
-function cloneBuiltinModules() {
-    return deepClone(BUILTIN_MODULES);
-}
-function deepFreeze(value) {
-    if (value === null || typeof value !== 'object')
-        return value;
-    if (Object.isFrozen(value))
-        return value;
-    for (const key of Object.keys(value)) {
-        deepFreeze(value[key]);
-    }
-    return Object.freeze(value);
-}
-function freezeAction(action) {
-    return deepFreeze(action);
-}
-function freezeModule(module) {
-    module.actions.forEach(freezeAction);
-    return deepFreeze(module);
-}
-function freezeModules(source) {
-    source.forEach(freezeModule);
-    return source;
-}
-function findActionIndex(source, actionName) {
-    const key = actionName.toLowerCase();
-    return source.findIndex((action) => String(action.name).toLowerCase() === key);
-}
-function mergeActions(base, extension) {
-    const next = base.slice();
-    for (const action of extension) {
-        const index = findActionIndex(next, String(action.name));
-        const frozen = freezeAction(deepClone(action));
-        if (index >= 0) {
-            next[index] = frozen;
-        }
-        else {
-            next.push(frozen);
-        }
-    }
-    return next;
-}
-function mergeModule(base, extension) {
-    return freezeModule({
-        ...base,
-        ...deepClone(extension),
-        actions: mergeActions(base.actions, extension.actions),
-    });
-}
-function buildModuleMap(source) {
-    return new Map(source.map((module) => [module.name.toLowerCase(), module]));
-}
-function rebuildMap() {
-    moduleMap = buildModuleMap(modules);
-}
-function validateModule(module) {
-    if (!module || typeof module.name !== 'string' || !Array.isArray(module.actions)) {
-        throw new ZentaoError('E_INVALID_MODULE_DEFINITION');
-    }
-}
-function validateAction(action) {
-    if (!action || typeof action.name !== 'string' || typeof action.path !== 'string' || typeof action.method !== 'string') {
-        throw new ZentaoError('E_INVALID_ACTION_DEFINITION');
-    }
-}
-/**
- * 注册或扩展模块定义。
- *
- * 行为细节：
- * - 模块名匹配大小写不敏感。
- * - 未知模块直接追加到注册表末尾。
- * - 已存在的模块默认按 `mergeModule` 合并：模块元数据浅合并、动作按名同名替换/未知追加；
- *   `options.replace` 为 `true` 时整体替换。
- * - 所有写入都会做深克隆 + 深冻结：调用方后续修改自己的对象不会污染注册表，注册表也不可被外部改写。
- *
- * @param input - 单个或一组模块定义。
- * @param options - 写入策略，参见 {@link DefineModulesOptions}。
- * @throws {ZentaoError} `E_INVALID_MODULE_DEFINITION` —— 缺少 `name` 或 `actions` 字段。
- */
-export function defineModules(input, options = {}) {
-    for (const module of asArray(input)) {
-        validateModule(module);
-        const key = module.name.toLowerCase();
-        const index = modules.findIndex((item) => item.name.toLowerCase() === key);
-        if (index >= 0) {
-            modules[index] = options.replace
-                ? freezeModule(deepClone(module))
-                : mergeModule(modules[index], module);
-        }
-        else {
-            modules.push(freezeModule(deepClone(module)));
-        }
-    }
-    rebuildMap();
-}
-/**
- * 为已存在的模块追加或覆盖动作。
- *
- * 不做深度合并：同名动作整体替换，未知动作追加。这避免在 schema、参数数组等字段上出现隐式合并规则。
- *
- * @param moduleName - 目标模块名（大小写不敏感）。
- * @param input - 单个或一组动作定义。
- * @throws {ZentaoError} `E_INVALID_MODULE`（模块未注册）或 `E_INVALID_ACTION_DEFINITION`
- *   （动作缺少 `name` / `path` / `method` 等必填字段）。
- */
-export function defineModuleActions(moduleName, input) {
-    const key = moduleName.toLowerCase();
-    const module = moduleMap.get(key);
-    if (!module) {
-        throw new ZentaoError('E_INVALID_MODULE', { module: moduleName });
-    }
-    const actions = module.actions.slice();
-    for (const action of asArray(input)) {
-        validateAction(action);
-        const index = findActionIndex(actions, String(action.name));
-        const frozen = freezeAction(deepClone(action));
-        // 同名动作替换，未知动作追加；不做深度合并，避免 schema/数组字段出现隐式规则。
-        if (index >= 0) {
-            actions[index] = frozen;
-        }
-        else {
-            actions.push(frozen);
-        }
-    }
-    const nextModule = freezeModule({ ...module, actions });
-    const index = modules.findIndex((item) => item.name.toLowerCase() === key);
-    modules[index] = nextModule;
-    rebuildMap();
-}
-/**
- * 获取模块定义。
- *
- * 模块名匹配大小写不敏感。返回值是注册表内部的已深冻结引用（O(1) 查询、零拷贝），
- * 任何写入尝试在严格模式下会抛 `TypeError`；如需修改请使用 {@link defineModules}。
- *
- * @param moduleName - 模块名。
- * @returns 已注册的模块定义。
- * @throws {ZentaoError} `E_INVALID_MODULE` —— 模块未注册。
- */
-export function getModule(moduleName) {
-    const module = moduleMap.get(moduleName.toLowerCase());
-    if (!module) {
-        throw new ZentaoError('E_INVALID_MODULE', { module: moduleName });
-    }
-    return module;
-}
-/**
- * 获取指定模块下的某个动作。
- *
- * 解析顺序：
- * 1. `actionName === 'ls'` 时映射为 `list`（仅作为别名，不会修改注册表）。
- * 2. 在该模块的动作中按名称大小写不敏感匹配。
- * 3. 当请求的动作不是基础 CRUD（`list`/`get`/`create`/`update`/`delete`）时，
- *    额外允许命中 `type === 'action'` 的自定义动作（即使名字不在基础 CRUD 中）。
- *
- * 返回值同样是已深冻结的引用，请勿尝试修改。
- *
- * @param moduleName - 模块名（大小写不敏感）。
- * @param actionName - 动作名（大小写不敏感）；支持 `ls` 作为 `list` 的别名。
- * @returns 匹配到的动作定义。
- * @throws {ZentaoError} `E_INVALID_MODULE`（模块未注册）或 `E_INVALID_ACTION`（动作不存在）。
- */
-export function getModuleAction(moduleName, actionName) {
-    const module = getModule(moduleName);
-    const normalized = actionName === 'ls' ? 'list' : actionName;
-    const direct = module.actions.find((action) => String(action.name).toLowerCase() === normalized.toLowerCase());
-    if (direct)
-        return direct;
-    const crud = new Set(['list', 'get', 'create', 'update', 'delete']);
-    if (!crud.has(normalized)) {
-        const custom = module.actions.find((action) => action.type === 'action' && String(action.name).toLowerCase() === normalized.toLowerCase());
-        if (custom)
-            return custom;
-    }
-    throw new ZentaoError('E_INVALID_ACTION', { module: moduleName, action: actionName });
-}
-/**
- * 返回当前运行时注册表中的所有模块名。
- *
- * 顺序与模块写入注册表的顺序一致；包括内置模块和通过 {@link defineModules} 追加的用户模块。
- *
- * @returns 模块名数组（保留原始大小写）。
- */
-export function getModuleNames() {
-    return modules.map((module) => module.name);
-}
-/**
- * 判断模块名是否已注册。
- *
- * @param moduleName - 模块名；匹配大小写不敏感。
- * @returns 已注册返回 `true`，否则 `false`。
- */
-export function isModuleName(moduleName) {
-    return moduleMap.has(moduleName.toLowerCase());
-}
-/** @internal */
-export function resetModuleDefinitions() {
-    modules = freezeModules(cloneBuiltinModules());
-    rebuildMap();
-}
+export { defineModules, defineModuleActions, extendModuleAction, resetModuleDefinitions, } from './define.js';
+export { applyBuiltinOverrides };
+// 内置覆盖接线：避免 define ↔ override 之间的循环依赖。
+// - 加载时应用一次；
+// - 注册为 store 的「重置后钩子」，使 resetModuleDefinitions 还原内置基线后自动重新应用。
+setPostResetHook(applyBuiltinOverrides);
+applyBuiltinOverrides();
+export { getModule, getModuleAction, getModuleNames, isModuleName, } from './query.js';

package/dist/modules/resolve.d.ts

@@ -2,6 +2,6 @@ import type { ListPagerInfo, ModuleAction, ModuleDefinition, ResolvedModuleComma
 /** 将模块名、动作名和调用参数解析为实际 API 请求路径、查询参数和请求体。 */
 export declare function resolveModuleCommand(module: ModuleDefinition, actionName: string, params?: Record<string, unknown>): ResolvedModuleCommand;
 /** 根据动作定义中的 resultGetter，从原始响应里提取业务数据。 */
-export declare function extractResult(action: ModuleAction, response: Record<string, unknown>): unknown;
+export declare function extractResult(action: ModuleAction, response: Record<string, unknown>, params?: Record<string, unknown>): unknown;
 /** 根据动作定义中的 pagerGetter，从原始响应里提取分页信息。 */
-export declare function extractPager(action: ModuleAction, response: Record<string, unknown>): ListPagerInfo | undefined;
+export declare function extractPager(action: ModuleAction, response: Record<string, unknown>, params?: Record<string, unknown>): ListPagerInfo | undefined;

package/dist/modules/resolve.js

@@ -173,32 +173,32 @@ export function resolveModuleCommand(module, actionName, params = {}) {
     };
 }
 /** 根据动作定义中的 resultGetter，从原始响应里提取业务数据。 */
-export function extractResult(action, response) {
+export function extractResult(action, response, params = {}) {
     const getter = action.resultGetter;
     if (!getter)
         return response.data ?? response;
     if (typeof getter === 'function')
-        return getter(response, {});
+        return getter(response, params);
     if (typeof getter === 'string')
         return getNestedValue(response, getter);
     const result = {};
     for (const [targetKey, sourceKey] of Object.entries(getter)) {
-        result[targetKey] = response[sourceKey];
+        result[targetKey] = getNestedValue(response, sourceKey);
     }
     return result;
 }
 /** 根据动作定义中的 pagerGetter，从原始响应里提取分页信息。 */
-export function extractPager(action, response) {
+export function extractPager(action, response, params = {}) {
     const getter = action.pagerGetter;
     if (!getter)
         return response.pager;
     if (typeof getter === 'function')
-        return getter(response, {});
+        return getter(response, params);
     if (typeof getter === 'string')
         return getNestedValue(response, getter);
-    const page = response[getter.pageID];
-    const recPerPage = response[getter.recPerPage];
-    const recTotal = response[getter.recTotal];
+    const page = getNestedValue(response, getter.pageID);
+    const recPerPage = getNestedValue(response, getter.recPerPage);
+    const recTotal = getNestedValue(response, getter.recTotal);
     if (page === undefined || recPerPage === undefined || recTotal === undefined)
         return undefined;
     return {

package/dist/request/index.d.ts

@@ -104,6 +104,9 @@ export type RequestResultFor<Name extends BuiltinRequestName> = ActionOfRequest<
  * 当响应 `status` 为 `"fail"` 时，默认按原样返回；若 `options.throwOnFail`
  * 或全局 `throwOnFail` 为真，则改为抛出 `E_API_FAILED`。
  *
+ * 对 `update` 动作，当 `options.autoFill` 或全局 `autoFill` 为真时，会先 GET 当前对象，
+ * 用现值补齐用户未显式传入的 body 字段后再 PUT，避免禅道覆盖未提交字段。详见 {@link RequestOptions.autoFill}。
+ *
  * @typeParam T 期望的 `data` 字段类型；不传时为 `unknown`，调用方需要自行收窄。
  * @param name - 请求名，例如 `product`、`product/list` 或 `product/1`。
  * @param params - 请求参数。

package/dist/request/index.js

@@ -1,6 +1,6 @@
 import { ZentaoError } from '../misc/errors.js';
 import { getGlobalOptions } from '../misc/global-options.js';
-import { getModule } from '../modules/registry.js';
+import { getModule, getModuleAction } from '../modules/registry.js';
 import { extractPager, extractResult, resolveModuleCommand } from '../modules/resolve.js';
 import { isRecord, processData } from '../utils/index.js';
 /** 将 `moduleName`、`moduleName/methodName` 或 `moduleName/<objectID>` 请求名拆成模块名、动作名和对象 ID。 */
@@ -30,6 +30,54 @@ function splitRequestName(name) {
         actionName,
     };
 }
+/** 解析 `params.data` 中用户显式传入的 body 字段名，用于 autoFill 判断字段归属。 */
+function getExplicitDataKeys(data) {
+    let value = data;
+    if (typeof value === 'string') {
+        try {
+            value = JSON.parse(value);
+        }
+        catch {
+            return new Set();
+        }
+    }
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+        return new Set(Object.keys(value));
+    }
+    return new Set();
+}
+/**
+ * 在执行 `update` 动作前，用当前对象的现值填充用户未显式传入的 body 字段。
+ *
+ * 仅当模块存在 `type: 'get'` 动作且 update 动作声明了对象类型 body schema 时生效；
+ * 否则原样返回参数。GET 失败或返回非对象时同样跳过填充，交由后续 PUT 正常处理。
+ *
+ * 字段归属判断同时覆盖平铺 `params` 字段与 `params.data` 中的字段；只有 schema 中声明、
+ * 用户未传且当前对象存在的字段才会被补齐，避免覆盖用户本次想修改的字段。
+ */
+async function autoFillUpdateParams(module, action, params, options) {
+    const properties = action.requestBody?.schema?.properties;
+    const getAction = module.actions.find((candidate) => candidate.type === 'get');
+    if (!properties || !getAction)
+        return params;
+    const current = (await request(`${module.name}/${getAction.name}`, params, {
+        client: options.client,
+        timeout: options.timeout,
+        insecure: options.insecure,
+        throwOnFail: options.throwOnFail,
+    })).data;
+    if (!isRecord(current))
+        return params;
+    const explicitDataKeys = getExplicitDataKeys(params.data);
+    const filled = { ...params };
+    for (const key of Object.keys(properties)) {
+        const userProvided = Object.prototype.hasOwnProperty.call(params, key) || explicitDataKeys.has(key);
+        if (!userProvided && Object.prototype.hasOwnProperty.call(current, key)) {
+            filled[key] = current[key];
+        }
+    }
+    return filled;
+}
 function stringifyMessage(value) {
     if (typeof value === 'string')
         return value;
@@ -96,9 +144,9 @@ function normalizeResponse(command, raw, options) {
     }
     const record = raw;
     const status = record.status === 'fail' ? 'fail' : 'success';
-    const data = applyProcessing(extractResult(command.action, record), options);
+    const data = applyProcessing(extractResult(command.action, record, command.params), options);
     const rawMessage = record.message;
-    const pager = extractPager(command.action, record);
+    const pager = extractPager(command.action, record, command.params);
     const response = {
         status,
         message: stringifyMessage(rawMessage),
@@ -134,7 +182,13 @@ export async function request(name, params = {}, options = {}) {
         ...(id !== undefined ? { id } : {}),
         ...(recPerPage !== undefined ? { recPerPage } : {}),
     };
-    const command = resolveModuleCommand(module, actionName, mergedParams);
+    // autoFill：update 动作先 GET 当前对象，用现值补齐用户未显式传入的字段，
+    // 避免禅道 PUT 把未提交字段覆盖为空。
+    const action = getModuleAction(moduleName, actionName);
+    const finalParams = action.type === 'update' && (options.autoFill ?? globals.autoFill)
+        ? await autoFillUpdateParams(module, action, mergedParams, options)
+        : mergedParams;
+    const command = resolveModuleCommand(module, actionName, finalParams);
     const raw = await client.request(command.path, {
         method: String(command.action.method).toUpperCase(),
         query: command.query,

package/dist/types/client.d.ts

@@ -0,0 +1,38 @@
+/** 创建 {@link ZentaoClient} 时使用的配置。 */
+export interface ZentaoClientOptions {
+    /** 禅道站点根地址，例如 `https://zentao.example.com`；SDK 会自动拼接 `/api.php/v2`。 */
+    baseUrl: string;
+    /** 禅道 API Token；未提供时可稍后通过 {@link ZentaoClient.login} 获取并写入实例。 */
+    token?: string;
+    /** 默认请求超时时间，单位毫秒。 */
+    timeout?: number;
+    /** 是否跳过 TLS 证书验证；仅 Node.js 运行时支持，浏览器中会抛错。 */
+    insecure?: boolean;
+}
+/** SDK 支持的 HTTP 方法。 */
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
+/** 请求体序列化方式。 */
+export type ClientRequestBodyType = 'json' | 'form' | 'raw';
+/** 响应体解析方式。 */
+export type ClientResponseType = 'auto' | 'json' | 'text' | 'arrayBuffer' | 'blob' | 'response';
+/** `ZentaoClient.request()` 的单次请求选项。 */
+export interface ClientRequestOptions {
+    /** HTTP 方法，默认 `GET`。 */
+    method?: HttpMethod;
+    /** 请求体；`GET` 请求会忽略该字段。普通对象默认按 JSON 发送，`FormData` / `Blob` / `ArrayBuffer` 等会原样发送。 */
+    body?: unknown;
+    /** 请求体序列化方式。默认 `json`；传入 `FormData` 等原生 body 时会自动按 `raw` 处理。 */
+    bodyType?: ClientRequestBodyType;
+    /** 响应体解析方式。默认 `auto`，会优先尝试 JSON，失败后回落为文本。 */
+    responseType?: ClientResponseType;
+    /** 额外请求头；会与 SDK 自动注入的 `Token` / `Content-Type` 合并。 */
+    headers?: HeadersInit;
+    /** URL 查询参数；`undefined` 值会被跳过。 */
+    query?: Record<string, string | number | boolean | undefined>;
+    /** 外部取消信号；会与 SDK 自身的超时控制合并。 */
+    signal?: AbortSignal;
+    /** 单次请求超时时间，优先级高于全局和客户端默认值。 */
+    timeout?: number;
+    /** 单次请求 TLS 跳过证书验证选项；仅 Node.js 运行时支持。 */
+    insecure?: boolean;
+}

package/dist/types/client.js

@@ -0,0 +1 @@
+export {};

package/dist/types/data.d.ts

@@ -0,0 +1,42 @@
+/** 本地数据处理的基础记录类型，对应一条对象数据。 */
+export type DataRecord = Record<string, unknown>;
+/** 单条过滤条件，字段名支持 `.` 访问子字段。 */
+export interface DataRecordFilter {
+    /** 字段路径，例如 `status` 或 `assignedTo.id`。 */
+    key: string;
+    /** 比较运算符。 */
+    operator: '=' | '!=' | '>' | '<' | '>=' | '<=' | '~' | '!~';
+    /** 比较值；数组用于 `=`/`!=`/`~`/`!~` 的“任一/全不”匹配。 */
+    value: string | number | boolean | string[];
+}
+/** 一组过滤条件，组内按 `operator` 组合；多组之间按 AND 组合。 */
+export interface DataRecordFilterGroup {
+    /** 组内条件的组合方式。 */
+    operator: 'AND' | 'OR';
+    /** 组内条件列表。 */
+    conditions: DataRecordFilter[];
+}
+/** 排序表达式，格式为 `字段:asc|desc`。 */
+export type SortExpr = `${string}:${'asc' | 'desc'}`;
+/** 自定义排序比较函数。 */
+export type SortFn = (a: DataRecord, b: DataRecord) => number;
+/** {@link processData} 处理列表时的选项；执行顺序为 过滤 → 搜索 → 排序 → 限制数量 → 摘取。 */
+export interface ProcessListOptions {
+    /** 过滤表达式列表，例如 `["status=active", "pri>=2"]`，多条之间按 AND 组合。 */
+    filter?: string[];
+    /** 模糊搜索关键词组，组内空格分隔为 OR，多组之间按 AND 组合。 */
+    search?: string[];
+    /** 限定搜索字段，缺省时搜索全部字段。 */
+    searchFields?: string[];
+    /** 排序表达式，多个字段以英文逗号分隔，例如 `pri:desc,id:asc`。 */
+    sort?: string;
+    /** 限制返回列表数量，在排序后、摘取前截断；不改变服务端页大小。 */
+    limit?: string;
+    /** 摘取字段路径列表。 */
+    pick?: string[];
+}
+/** {@link processData} 处理单条对象时的选项。 */
+export interface ProcessSingleOptions {
+    /** 摘取字段路径列表。 */
+    pick?: string[];
+}

package/dist/types/data.js

@@ -0,0 +1 @@
+export {};