zentao-api 0.3.1 → 0.3.3

package/dist/misc/errors.d.ts

@@ -21,6 +21,8 @@ export declare const ERRORS: {
     readonly E_INVALID_ACTION: "Unknown action: {module}-{action}";
     readonly E_INVALID_MODULE_DEFINITION: "Invalid module definition.";
     readonly E_INVALID_ACTION_DEFINITION: "Invalid module action definition.";
+    readonly E_INDETERMINATE_ACTION_METHOD: "Cannot infer HTTP method for action \"{action}\" from type \"{type}\"; specify \"method\" explicitly.";
+    readonly E_INDETERMINATE_ACTION_RESULT_TYPE: "Cannot infer result type for action \"{action}\" from type \"{type}\"; specify \"resultType\" explicitly.";
     readonly E_MISSING_PARAM: "Missing required parameter: {param}";
     readonly E_INVALID_PARAM: "Invalid value for parameter {param}: {value}";
     readonly E_INVALID_REQUEST_NAME: "Request name must use the form \"moduleName\", \"moduleName/methodName\", or \"moduleName/<objectID>\".";

package/dist/misc/errors.js

@@ -21,6 +21,8 @@ export const ERRORS = {
     E_INVALID_ACTION: 'Unknown action: {module}-{action}',
     E_INVALID_MODULE_DEFINITION: 'Invalid module definition.',
     E_INVALID_ACTION_DEFINITION: 'Invalid module action definition.',
+    E_INDETERMINATE_ACTION_METHOD: 'Cannot infer HTTP method for action "{action}" from type "{type}"; specify "method" explicitly.',
+    E_INDETERMINATE_ACTION_RESULT_TYPE: 'Cannot infer result type for action "{action}" from type "{type}"; specify "resultType" explicitly.',
     E_MISSING_PARAM: 'Missing required parameter: {param}',
     E_INVALID_PARAM: 'Invalid value for parameter {param}: {value}',
     E_INVALID_REQUEST_NAME: 'Request name must use the form "moduleName", "moduleName/methodName", or "moduleName/<objectID>".',

package/dist/modules/define.d.ts

@@ -0,0 +1,67 @@
+import type { ModuleAction, ModuleDefinition } from '../types/index.js';
+/** {@link defineModules} 的选项。 */
+export interface DefineModulesOptions {
+    /**
+     * 同名模块的写入策略。
+     *
+     * - `false`（默认）：合并模块的元数据，并按动作名对动作做"同名替换、未知追加"。
+     * - `true`：整体替换已存在的模块定义，原有动作会被丢弃。
+     */
+    replace?: boolean;
+}
+/**
+ * 注册或扩展模块定义。
+ *
+ * 行为细节：
+ * - 模块名匹配大小写不敏感。
+ * - 未知模块直接追加到注册表末尾。
+ * - 已存在的模块默认按 `mergeModule` 合并：模块元数据浅合并、动作按名同名替换/未知追加；
+ *   `options.replace` 为 `true` 时整体替换。
+ * - 所有写入都会做深克隆 + 深冻结：调用方后续修改自己的对象不会污染注册表，注册表也不可被外部改写。
+ *
+ * @param input - 单个或一组模块定义。
+ * @param options - 写入策略，参见 {@link DefineModulesOptions}。
+ * @throws {ZentaoError} `E_INVALID_MODULE_DEFINITION` —— 缺少 `name` 或 `actions` 字段。
+ */
+export declare function defineModules(input: ModuleDefinition | ModuleDefinition[], options?: DefineModulesOptions): void;
+/**
+ * 为已存在的模块追加或覆盖动作。
+ *
+ * 不做深度合并：同名动作整体替换，未知动作追加。这避免在 schema、参数数组等字段上出现隐式合并规则。
+ *
+ * `method` / `resultType` 可省略：写入时按动作 `type` 自动推导（见 {@link ModuleAction}）。
+ *
+ * @param moduleName - 目标模块名（大小写不敏感）。
+ * @param input - 单个或一组动作定义。
+ * @throws {ZentaoError} `E_INVALID_MODULE`（模块未注册）、`E_INVALID_ACTION_DEFINITION`
+ *   （动作缺少 `name` / `path`，或 `method` / `resultType` 类型非法），或
+ *   `E_INDETERMINATE_ACTION_METHOD` / `E_INDETERMINATE_ACTION_RESULT_TYPE`（省略字段且无法按 `type` 推导）。
+ */
+export declare function defineModuleActions(moduleName: string, input: ModuleAction | ModuleAction[]): void;
+/**
+ * 扩展已存在的模块动作。
+ *
+ * 与 {@link defineModuleActions} 的「整体替换」不同，这里对单个动作做**深度合并**：
+ * 只需给出待修改的字段，其余字段沿用原动作定义。普通对象递归合并，
+ * 数组及其他值由补丁整体替换，值为 `undefined` 的键会被忽略。
+ *
+ * 当 `action` 为函数时**不做合并**：会以当前动作的深克隆为入参调用它，
+ * 其返回值作为完整的动作定义直接取代原动作定义。
+ *
+ * @param moduleName - 目标模块名（大小写不敏感）。
+ * @param actionName - 目标动作名（大小写不敏感）。
+ * @param action - 深度合并的补丁对象，或接收当前动作深克隆并返回完整动作定义的函数。
+ * @throws {ZentaoError} `E_INVALID_MODULE`（模块未注册）、`E_INVALID_ACTION`（动作不存在）、
+ *   `E_INVALID_ACTION_DEFINITION`（合并结果缺少 `name` / `path`，或 `method` / `resultType` 类型非法），
+ *   或 `E_INDETERMINATE_ACTION_METHOD` / `E_INDETERMINATE_ACTION_RESULT_TYPE`（省略字段且无法按 `type` 推导）。
+ */
+export declare function extendModuleAction(moduleName: string, actionName: string, action: Partial<ModuleAction> | ((action: ModuleAction) => ModuleAction)): void;
+/**
+ * 将注册表重置为内置基线。
+ *
+ * 重置会触发 store 的「重置后钩子」，由 barrel（`./registry.ts`）在其中重新应用内置覆盖
+ * （见 `./override.ts`），因此重置后内置扩展依旧生效。
+ *
+ * @internal
+ */
+export declare function resetModuleDefinitions(): void;

package/dist/modules/define.js

@@ -0,0 +1,123 @@
+import { ZentaoError } from '../misc/errors.js';
+import { asArray } from '../utils/index.js';
+import { deepClone, deepMerge, findActionIndex, freezeAction, freezeModule, getModuleMapState, getModulesState, mergeModule, rebuildModuleMap, resetState, validateAction, validateModule, } from './registry-store.js';
+/**
+ * 注册或扩展模块定义。
+ *
+ * 行为细节：
+ * - 模块名匹配大小写不敏感。
+ * - 未知模块直接追加到注册表末尾。
+ * - 已存在的模块默认按 `mergeModule` 合并：模块元数据浅合并、动作按名同名替换/未知追加；
+ *   `options.replace` 为 `true` 时整体替换。
+ * - 所有写入都会做深克隆 + 深冻结：调用方后续修改自己的对象不会污染注册表，注册表也不可被外部改写。
+ *
+ * @param input - 单个或一组模块定义。
+ * @param options - 写入策略，参见 {@link DefineModulesOptions}。
+ * @throws {ZentaoError} `E_INVALID_MODULE_DEFINITION` —— 缺少 `name` 或 `actions` 字段。
+ */
+export function defineModules(input, options = {}) {
+    const modules = getModulesState();
+    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)));
+        }
+    }
+    rebuildModuleMap();
+}
+/**
+ * 为已存在的模块追加或覆盖动作。
+ *
+ * 不做深度合并：同名动作整体替换，未知动作追加。这避免在 schema、参数数组等字段上出现隐式合并规则。
+ *
+ * `method` / `resultType` 可省略：写入时按动作 `type` 自动推导（见 {@link ModuleAction}）。
+ *
+ * @param moduleName - 目标模块名（大小写不敏感）。
+ * @param input - 单个或一组动作定义。
+ * @throws {ZentaoError} `E_INVALID_MODULE`（模块未注册）、`E_INVALID_ACTION_DEFINITION`
+ *   （动作缺少 `name` / `path`，或 `method` / `resultType` 类型非法），或
+ *   `E_INDETERMINATE_ACTION_METHOD` / `E_INDETERMINATE_ACTION_RESULT_TYPE`（省略字段且无法按 `type` 推导）。
+ */
+export function defineModuleActions(moduleName, input) {
+    const key = moduleName.toLowerCase();
+    const module = getModuleMapState().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 modules = getModulesState();
+    const index = modules.findIndex((item) => item.name.toLowerCase() === key);
+    modules[index] = nextModule;
+    rebuildModuleMap();
+}
+/**
+ * 扩展已存在的模块动作。
+ *
+ * 与 {@link defineModuleActions} 的「整体替换」不同，这里对单个动作做**深度合并**：
+ * 只需给出待修改的字段，其余字段沿用原动作定义。普通对象递归合并，
+ * 数组及其他值由补丁整体替换，值为 `undefined` 的键会被忽略。
+ *
+ * 当 `action` 为函数时**不做合并**：会以当前动作的深克隆为入参调用它，
+ * 其返回值作为完整的动作定义直接取代原动作定义。
+ *
+ * @param moduleName - 目标模块名（大小写不敏感）。
+ * @param actionName - 目标动作名（大小写不敏感）。
+ * @param action - 深度合并的补丁对象，或接收当前动作深克隆并返回完整动作定义的函数。
+ * @throws {ZentaoError} `E_INVALID_MODULE`（模块未注册）、`E_INVALID_ACTION`（动作不存在）、
+ *   `E_INVALID_ACTION_DEFINITION`（合并结果缺少 `name` / `path`，或 `method` / `resultType` 类型非法），
+ *   或 `E_INDETERMINATE_ACTION_METHOD` / `E_INDETERMINATE_ACTION_RESULT_TYPE`（省略字段且无法按 `type` 推导）。
+ */
+export function extendModuleAction(moduleName, actionName, action) {
+    const key = moduleName.toLowerCase();
+    const module = getModuleMapState().get(key);
+    if (!module) {
+        throw new ZentaoError('E_INVALID_MODULE', { module: moduleName });
+    }
+    const actions = module.actions.slice();
+    const actionIndex = findActionIndex(actions, actionName);
+    if (actionIndex < 0) {
+        throw new ZentaoError('E_INVALID_ACTION', { module: moduleName, action: actionName });
+    }
+    const current = actions[actionIndex];
+    // 函数：以当前动作的深克隆为入参，返回值作为完整动作定义直接取代原定义，不做合并。
+    // 对象：作为补丁与原动作深度合并。
+    const next = typeof action === 'function' ? action(deepClone(current)) : deepMerge(current, action);
+    validateAction(next);
+    actions[actionIndex] = freezeAction(next);
+    const nextModule = freezeModule({ ...module, actions });
+    const modules = getModulesState();
+    const index = modules.findIndex((item) => item.name.toLowerCase() === key);
+    modules[index] = nextModule;
+    rebuildModuleMap();
+}
+/**
+ * 将注册表重置为内置基线。
+ *
+ * 重置会触发 store 的「重置后钩子」，由 barrel（`./registry.ts`）在其中重新应用内置覆盖
+ * （见 `./override.ts`），因此重置后内置扩展依旧生效。
+ *
+ * @internal
+ */
+export function resetModuleDefinitions() {
+    resetState();
+}

package/dist/modules/generated.d.ts

@@ -176,7 +176,6 @@ export declare const BUILTIN_MODULES: readonly [{
         readonly pathParams: {
             readonly userID: "用户ID";
         };
-        readonly render: "action";
     }];
 }, {
     readonly name: "program";
@@ -357,7 +356,6 @@ export declare const BUILTIN_MODULES: readonly [{
         readonly pathParams: {
             readonly programID: "项目集ID";
         };
-        readonly render: "action";
     }];
 }, {
     readonly name: "product";
@@ -582,7 +580,6 @@ export declare const BUILTIN_MODULES: readonly [{
         readonly pathParams: {
             readonly productID: "产品ID";
         };
-        readonly render: "action";
     }];
 }, {
     readonly name: "project";
@@ -778,7 +775,6 @@ export declare const BUILTIN_MODULES: readonly [{
         readonly pathParams: {
             readonly projectID: "项目ID";
         };
-        readonly render: "action";
     }];
 }, {
     readonly name: "execution";
@@ -1031,7 +1027,6 @@ export declare const BUILTIN_MODULES: readonly [{
         readonly pathParams: {
             readonly executionID: "执行ID";
         };
-        readonly render: "action";
     }];
 }, {
     readonly name: "productplan";
@@ -1234,7 +1229,6 @@ export declare const BUILTIN_MODULES: readonly [{
         readonly pathParams: {
             readonly productplanID: "产品计划ID";
         };
-        readonly render: "action";
     }];
 }, {
     readonly name: "story";
@@ -1482,7 +1476,6 @@ export declare const BUILTIN_MODULES: readonly [{
         readonly pathParams: {
             readonly storyID: "需求ID";
         };
-        readonly render: "action";
     }, {
         readonly name: "activate";
         readonly display: "激活需求";
@@ -1510,7 +1503,6 @@ export declare const BUILTIN_MODULES: readonly [{
                 };
             };
         };
-        readonly render: "action";
     }, {
         readonly name: "change";
         readonly display: "变更需求";
@@ -1550,7 +1542,6 @@ export declare const BUILTIN_MODULES: readonly [{
                 readonly required: readonly ["reviewer"];
             };
         };
-        readonly render: "action";
     }, {
         readonly name: "close";
         readonly display: "关闭需求";
@@ -1579,7 +1570,6 @@ export declare const BUILTIN_MODULES: readonly [{
                 readonly required: readonly ["closedReason"];
             };
         };
-        readonly render: "action";
     }];
 }, {
     readonly name: "epic";
@@ -1812,7 +1802,6 @@ export declare const BUILTIN_MODULES: readonly [{
         readonly pathParams: {
             readonly epicID: "业务需求ID";
         };
-        readonly render: "action";
     }, {
         readonly name: "activate";
         readonly display: "激活业务需求";
@@ -1840,7 +1829,6 @@ export declare const BUILTIN_MODULES: readonly [{
                 };
             };
         };
-        readonly render: "action";
     }, {
         readonly name: "change";
         readonly display: "变更业务需求";
@@ -1880,7 +1868,6 @@ export declare const BUILTIN_MODULES: readonly [{
                 readonly required: readonly ["reviewer"];
             };
         };
-        readonly render: "action";
     }, {
         readonly name: "close";
         readonly display: "关闭业务需求";
@@ -1909,7 +1896,6 @@ export declare const BUILTIN_MODULES: readonly [{
                 readonly required: readonly ["closedReason"];
             };
         };
-        readonly render: "action";
     }];
 }, {
     readonly name: "requirement";
@@ -2141,7 +2127,6 @@ export declare const BUILTIN_MODULES: readonly [{
         readonly pathParams: {
             readonly requirementID: "用户需求ID";
         };
-        readonly render: "action";
     }, {
         readonly name: "activate";
         readonly display: "激活用户需求";
@@ -2169,7 +2154,6 @@ export declare const BUILTIN_MODULES: readonly [{
                 };
             };
         };
-        readonly render: "action";
     }, {
         readonly name: "change";
         readonly display: "变更用户需求";
@@ -2201,7 +2185,6 @@ export declare const BUILTIN_MODULES: readonly [{
                 };
             };
         };
-        readonly render: "action";
     }, {
         readonly name: "close";
         readonly display: "关闭用户需求";
@@ -2230,7 +2213,6 @@ export declare const BUILTIN_MODULES: readonly [{
                 readonly required: readonly ["closedReason"];
             };
         };
-        readonly render: "action";
     }];
 }, {
     readonly name: "bug";
@@ -2468,7 +2450,6 @@ export declare const BUILTIN_MODULES: readonly [{
         readonly pathParams: {
             readonly bugID: "Bug ID";
         };
-        readonly render: "action";
     }, {
         readonly name: "activate";
         readonly display: "激活Bug";
@@ -2503,7 +2484,6 @@ export declare const BUILTIN_MODULES: readonly [{
                 };
             };
         };
-        readonly render: "action";
     }, {
         readonly name: "close";
         readonly display: "关闭Bug";
@@ -2527,7 +2507,6 @@ export declare const BUILTIN_MODULES: readonly [{
                 };
             };
         };
-        readonly render: "action";
     }, {
         readonly name: "resolve";
         readonly display: "解决Bug";
@@ -2568,7 +2547,6 @@ export declare const BUILTIN_MODULES: readonly [{
                 readonly required: readonly ["resolution"];
             };
         };
-        readonly render: "action";
     }];
 }, {
     readonly name: "testcase";
@@ -2819,7 +2797,6 @@ export declare const BUILTIN_MODULES: readonly [{
         readonly pathParams: {
             readonly testcasID: "测试用例ID";
         };
-        readonly render: "action";
     }];
 }, {
     readonly name: "task";
@@ -3053,7 +3030,6 @@ export declare const BUILTIN_MODULES: readonly [{
         readonly pathParams: {
             readonly taskID: "任务ID";
         };
-        readonly render: "action";
     }, {
         readonly name: "activate";
         readonly display: "激活任务";
@@ -3086,7 +3062,6 @@ export declare const BUILTIN_MODULES: readonly [{
                 };
             };
         };
-        readonly render: "action";
     }, {
         readonly name: "close";
         readonly display: "关闭任务";
@@ -3110,7 +3085,6 @@ export declare const BUILTIN_MODULES: readonly [{
                 };
             };
         };
-        readonly render: "action";
     }, {
         readonly name: "finish";
         readonly display: "完成任务";
@@ -3157,7 +3131,6 @@ export declare const BUILTIN_MODULES: readonly [{
                 readonly required: readonly ["currentConsumed", "realStarted", "finishedDate"];
             };
         };
-        readonly render: "action";
     }, {
         readonly name: "start";
         readonly display: "启动任务";
@@ -3200,7 +3173,6 @@ export declare const BUILTIN_MODULES: readonly [{
                 readonly required: readonly ["realStarted"];
             };
         };
-        readonly render: "action";
     }];
 }, {
     readonly name: "feedback";
@@ -3406,7 +3378,6 @@ export declare const BUILTIN_MODULES: readonly [{
         readonly pathParams: {
             readonly feedbackID: "反馈ID";
         };
-        readonly render: "action";
     }, {
         readonly name: "activate";
         readonly display: "激活反馈";
@@ -3434,7 +3405,6 @@ export declare const BUILTIN_MODULES: readonly [{
                 };
             };
         };
-        readonly render: "action";
     }, {
         readonly name: "close";
         readonly display: "关闭反馈";
@@ -3463,7 +3433,6 @@ export declare const BUILTIN_MODULES: readonly [{
                 readonly required: readonly ["closedReason"];
             };
         };
-        readonly render: "action";
     }];
 }, {
     readonly name: "ticket";
@@ -3685,7 +3654,6 @@ export declare const BUILTIN_MODULES: readonly [{
         readonly pathParams: {
             readonly ticketID: "工单ID";
         };
-        readonly render: "action";
     }, {
         readonly name: "activate";
         readonly display: "激活工单";
@@ -3713,7 +3681,6 @@ export declare const BUILTIN_MODULES: readonly [{
                 };
             };
         };
-        readonly render: "action";
     }, {
         readonly name: "close";
         readonly display: "关闭工单";
@@ -3742,7 +3709,6 @@ export declare const BUILTIN_MODULES: readonly [{
                 readonly required: readonly ["closedReason", "comment"];
             };
         };
-        readonly render: "action";
     }];
 }, {
     readonly name: "system";
@@ -3995,7 +3961,6 @@ export declare const BUILTIN_MODULES: readonly [{
         readonly pathParams: {
             readonly buildID: "版本ID";
         };
-        readonly render: "action";
     }];
 }, {
     readonly name: "testtask";
@@ -4160,7 +4125,6 @@ export declare const BUILTIN_MODULES: readonly [{
         readonly pathParams: {
             readonly testtaskID: "测试单ID";
         };
-        readonly render: "action";
     }];
 }, {
     readonly name: "release";
@@ -4293,7 +4257,6 @@ export declare const BUILTIN_MODULES: readonly [{
         readonly pathParams: {
             readonly releasID: "发布ID";
         };
-        readonly render: "action";
     }];
 }, {
     readonly name: "file";
@@ -4330,6 +4293,5 @@ export declare const BUILTIN_MODULES: readonly [{
         readonly pathParams: {
             readonly fileID: "附件ID";
         };
-        readonly render: "action";
     }];
 }];