zentao-api 0.3.1 → 0.3.3

package/dist/modules/generated.js

@@ -174,7 +174,6 @@ export const BUILTIN_MODULES = [
                 pathParams: {
                     userID: '用户ID',
                 },
-                render: 'action',
             }
         ],
     },
@@ -344,7 +343,6 @@ export const BUILTIN_MODULES = [
                 pathParams: {
                     programID: '项目集ID',
                 },
-                render: 'action',
             }
         ],
     },
@@ -562,7 +560,6 @@ export const BUILTIN_MODULES = [
                 pathParams: {
                     productID: '产品ID',
                 },
-                render: 'action',
             }
         ],
     },
@@ -757,7 +754,6 @@ export const BUILTIN_MODULES = [
                 pathParams: {
                     projectID: '项目ID',
                 },
-                render: 'action',
             }
         ],
     },
@@ -1006,7 +1002,6 @@ export const BUILTIN_MODULES = [
                 pathParams: {
                     executionID: '执行ID',
                 },
-                render: 'action',
             }
         ],
     },
@@ -1193,7 +1188,6 @@ export const BUILTIN_MODULES = [
                 pathParams: {
                     productplanID: '产品计划ID',
                 },
-                render: 'action',
             }
         ],
     },
@@ -1423,7 +1417,6 @@ export const BUILTIN_MODULES = [
                 pathParams: {
                     storyID: '需求ID',
                 },
-                render: 'action',
             }, {
                 name: 'activate',
                 display: '激活需求',
@@ -1451,7 +1444,6 @@ export const BUILTIN_MODULES = [
                         }
                     },
                 },
-                render: 'action',
             }, {
                 name: 'change',
                 display: '变更需求',
@@ -1493,7 +1485,6 @@ export const BUILTIN_MODULES = [
                         ]
                     },
                 },
-                render: 'action',
             }, {
                 name: 'close',
                 display: '关闭需求',
@@ -1524,7 +1515,6 @@ export const BUILTIN_MODULES = [
                         ]
                     },
                 },
-                render: 'action',
             }
         ],
     },
@@ -1745,7 +1735,6 @@ export const BUILTIN_MODULES = [
                 pathParams: {
                     epicID: '业务需求ID',
                 },
-                render: 'action',
             }, {
                 name: 'activate',
                 display: '激活业务需求',
@@ -1773,7 +1762,6 @@ export const BUILTIN_MODULES = [
                         }
                     },
                 },
-                render: 'action',
             }, {
                 name: 'change',
                 display: '变更业务需求',
@@ -1815,7 +1803,6 @@ export const BUILTIN_MODULES = [
                         ]
                     },
                 },
-                render: 'action',
             }, {
                 name: 'close',
                 display: '关闭业务需求',
@@ -1846,7 +1833,6 @@ export const BUILTIN_MODULES = [
                         ]
                     },
                 },
-                render: 'action',
             }
         ],
     },
@@ -2066,7 +2052,6 @@ export const BUILTIN_MODULES = [
                 pathParams: {
                     requirementID: '用户需求ID',
                 },
-                render: 'action',
             }, {
                 name: 'activate',
                 display: '激活用户需求',
@@ -2094,7 +2079,6 @@ export const BUILTIN_MODULES = [
                         }
                     },
                 },
-                render: 'action',
             }, {
                 name: 'change',
                 display: '变更用户需求',
@@ -2126,7 +2110,6 @@ export const BUILTIN_MODULES = [
                         }
                     },
                 },
-                render: 'action',
             }, {
                 name: 'close',
                 display: '关闭用户需求',
@@ -2157,7 +2140,6 @@ export const BUILTIN_MODULES = [
                         ]
                     },
                 },
-                render: 'action',
             }
         ],
     },
@@ -2376,7 +2358,6 @@ export const BUILTIN_MODULES = [
                 pathParams: {
                     bugID: 'Bug ID',
                 },
-                render: 'action',
             }, {
                 name: 'activate',
                 display: '激活Bug',
@@ -2411,7 +2392,6 @@ export const BUILTIN_MODULES = [
                         }
                     },
                 },
-                render: 'action',
             }, {
                 name: 'close',
                 display: '关闭Bug',
@@ -2435,7 +2415,6 @@ export const BUILTIN_MODULES = [
                         }
                     },
                 },
-                render: 'action',
             }, {
                 name: 'resolve',
                 display: '解决Bug',
@@ -2478,7 +2457,6 @@ export const BUILTIN_MODULES = [
                         ]
                     },
                 },
-                render: 'action',
             }
         ],
     },
@@ -2715,7 +2693,6 @@ export const BUILTIN_MODULES = [
                 pathParams: {
                     testcasID: '测试用例ID',
                 },
-                render: 'action',
             }
         ],
     },
@@ -2933,7 +2910,6 @@ export const BUILTIN_MODULES = [
                 pathParams: {
                     taskID: '任务ID',
                 },
-                render: 'action',
             }, {
                 name: 'activate',
                 display: '激活任务',
@@ -2966,7 +2942,6 @@ export const BUILTIN_MODULES = [
                         }
                     },
                 },
-                render: 'action',
             }, {
                 name: 'close',
                 display: '关闭任务',
@@ -2990,7 +2965,6 @@ export const BUILTIN_MODULES = [
                         }
                     },
                 },
-                render: 'action',
             }, {
                 name: 'finish',
                 display: '完成任务',
@@ -3041,7 +3015,6 @@ export const BUILTIN_MODULES = [
                         ]
                     },
                 },
-                render: 'action',
             }, {
                 name: 'start',
                 display: '启动任务',
@@ -3086,7 +3059,6 @@ export const BUILTIN_MODULES = [
                         ]
                     },
                 },
-                render: 'action',
             }
         ],
     },
@@ -3277,7 +3249,6 @@ export const BUILTIN_MODULES = [
                 pathParams: {
                     feedbackID: '反馈ID',
                 },
-                render: 'action',
             }, {
                 name: 'activate',
                 display: '激活反馈',
@@ -3305,7 +3276,6 @@ export const BUILTIN_MODULES = [
                         }
                     },
                 },
-                render: 'action',
             }, {
                 name: 'close',
                 display: '关闭反馈',
@@ -3336,7 +3306,6 @@ export const BUILTIN_MODULES = [
                         ]
                     },
                 },
-                render: 'action',
             }
         ],
     },
@@ -3538,7 +3507,6 @@ export const BUILTIN_MODULES = [
                 pathParams: {
                     ticketID: '工单ID',
                 },
-                render: 'action',
             }, {
                 name: 'activate',
                 display: '激活工单',
@@ -3566,7 +3534,6 @@ export const BUILTIN_MODULES = [
                         }
                     },
                 },
-                render: 'action',
             }, {
                 name: 'close',
                 display: '关闭工单',
@@ -3598,7 +3565,6 @@ export const BUILTIN_MODULES = [
                         ]
                     },
                 },
-                render: 'action',
             }
         ],
     },
@@ -3866,7 +3832,6 @@ export const BUILTIN_MODULES = [
                 pathParams: {
                     buildID: '版本ID',
                 },
-                render: 'action',
             }
         ],
     },
@@ -4034,7 +3999,6 @@ export const BUILTIN_MODULES = [
                 pathParams: {
                     testtaskID: '测试单ID',
                 },
-                render: 'action',
             }
         ],
     },
@@ -4176,7 +4140,6 @@ export const BUILTIN_MODULES = [
                 pathParams: {
                     releasID: '发布ID',
                 },
-                render: 'action',
             }
         ],
     },
@@ -4219,7 +4182,6 @@ export const BUILTIN_MODULES = [
                 pathParams: {
                     fileID: '附件ID',
                 },
-                render: 'action',
             }
         ],
     }

package/dist/modules/override.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 内置覆盖 / 扩展定义。
+ *
+ * 这里集中存放对自动生成注册表（`./generated.ts`）的手工扩展：补充缺失的模块动作、
+ * 修正个别动作的元数据，或登记 OpenAPI 尚未覆盖的自定义模块。
+ *
+ * 与「用户运行时调用 {@link defineModules}」不同，这里的定义会在模块加载时自动应用，
+ * 并在 {@link resetModuleDefinitions} 重置后重新应用，因此它们等同于**内置定义**，
+ * 会随 SDK 一起发布。
+ *
+ * 维护约定：
+ * - 不要修改 `./generated.ts`（它由 `scripts/update-registry.ts` 自动生成）。
+ *   能通过更新 OpenAPI 数据解决的，优先走生成流程；只有生成器无法表达的扩展才写在这里。
+ * - 复用 {@link defineModules} / {@link defineModuleActions} 的语义：
+ *   - {@link defineModuleActions}：为**已存在**的模块追加动作（同名替换、未知追加）。
+ *   - {@link defineModules}：登记**新模块**，或对已存在模块做合并 / 整体替换（`replace`）。
+ * - 写入会自动深克隆 + 深冻结，无需自己处理不可变性。
+ *
+ * @example 为已存在的 `bug` 模块补充一个自定义动作：
+ * ```ts
+ * defineModuleActions('bug', {
+ *   name: 'assignTo',
+ *   display: '指派 Bug',
+ *   type: 'action',
+ *   method: 'put',
+ *   path: '/bugs/{bugID}/assignto',
+ *   resultType: 'text',
+ *   pathParams: { bugID: 'Bug ID' },
+ *   requestBody: {
+ *     required: true,
+ *     schema: {
+ *       assignedTo: { type: 'string', description: '指派给' },
+ *       comment: { type: 'string', description: '备注' },
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * @example 登记一个 OpenAPI 未覆盖的新模块：
+ * ```ts
+ * defineModules({
+ *   name: 'custom',
+ *   display: '自定义模块',
+ *   actions: [
+ *     {
+ *       name: 'list',
+ *       type: 'list',
+ *       method: 'get',
+ *       path: '/customs',
+ *       resultType: 'list',
+ *       pagerGetter: 'pager',
+ *       resultGetter: 'customs',
+ *     },
+ *   ],
+ * });
+ * ```
+ *
+ * @internal
+ */
+export declare function applyBuiltinOverrides(): void;

package/dist/modules/override.js

@@ -0,0 +1,113 @@
+import { extendModuleAction } from './define.js';
+/**
+ * 内置覆盖 / 扩展定义。
+ *
+ * 这里集中存放对自动生成注册表（`./generated.ts`）的手工扩展：补充缺失的模块动作、
+ * 修正个别动作的元数据，或登记 OpenAPI 尚未覆盖的自定义模块。
+ *
+ * 与「用户运行时调用 {@link defineModules}」不同，这里的定义会在模块加载时自动应用，
+ * 并在 {@link resetModuleDefinitions} 重置后重新应用，因此它们等同于**内置定义**，
+ * 会随 SDK 一起发布。
+ *
+ * 维护约定：
+ * - 不要修改 `./generated.ts`（它由 `scripts/update-registry.ts` 自动生成）。
+ *   能通过更新 OpenAPI 数据解决的，优先走生成流程；只有生成器无法表达的扩展才写在这里。
+ * - 复用 {@link defineModules} / {@link defineModuleActions} 的语义：
+ *   - {@link defineModuleActions}：为**已存在**的模块追加动作（同名替换、未知追加）。
+ *   - {@link defineModules}：登记**新模块**，或对已存在模块做合并 / 整体替换（`replace`）。
+ * - 写入会自动深克隆 + 深冻结，无需自己处理不可变性。
+ *
+ * @example 为已存在的 `bug` 模块补充一个自定义动作：
+ * ```ts
+ * defineModuleActions('bug', {
+ *   name: 'assignTo',
+ *   display: '指派 Bug',
+ *   type: 'action',
+ *   method: 'put',
+ *   path: '/bugs/{bugID}/assignto',
+ *   resultType: 'text',
+ *   pathParams: { bugID: 'Bug ID' },
+ *   requestBody: {
+ *     required: true,
+ *     schema: {
+ *       assignedTo: { type: 'string', description: '指派给' },
+ *       comment: { type: 'string', description: '备注' },
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * @example 登记一个 OpenAPI 未覆盖的新模块：
+ * ```ts
+ * defineModules({
+ *   name: 'custom',
+ *   display: '自定义模块',
+ *   actions: [
+ *     {
+ *       name: 'list',
+ *       type: 'list',
+ *       method: 'get',
+ *       path: '/customs',
+ *       resultType: 'list',
+ *       pagerGetter: 'pager',
+ *       resultGetter: 'customs',
+ *     },
+ *   ],
+ * });
+ * ```
+ *
+ * @internal
+ */
+export function applyBuiltinOverrides() {
+    // 创建执行时，需要添加产品字段
+    extendModuleAction('execution', 'create', (action) => {
+        const required = action.requestBody.schema?.required;
+        if (Array.isArray(required) && !required.includes('products')) {
+            required.push('products');
+        }
+        return action;
+    });
+    // 修改 story/update 字段定义
+    extendModuleAction('story', 'update', (action) => {
+        const properties = action.requestBody.schema?.properties;
+        // 为 story/update 增加 plan 字段
+        if (properties && !properties.plan) {
+            properties.plan = {
+                type: 'integer',
+                description: '所属计划',
+                format: 'int32',
+            };
+        }
+        // 修改 category 字段类型为 string
+        if (properties && properties.category) {
+            properties.category = {
+                type: 'string',
+                description: '类别',
+            };
+        }
+        return action;
+    });
+    // 修改 task/list URL 定义
+    extendModuleAction('task', 'list', (action) => {
+        action.path = '/executions/{executionID}/tasks';
+        action.pathParams = {
+            executionID: '执行ID',
+        };
+        return action;
+    });
+    // 修改 acl 字段默认值为 open
+    [
+        ['product', 'create'],
+        ['product', 'update'],
+        ['execution', 'create'],
+        ['execution', 'update'],
+    ].forEach(([moduleName, actionName]) => {
+        extendModuleAction(moduleName, actionName, (action) => {
+            const properties = action.requestBody.schema?.properties;
+            if (properties.acl && properties.acl.defaultValue === undefined) {
+                properties.acl.defaultValue = 'open';
+            }
+            return action;
+        });
+    });
+}

package/dist/modules/query.d.ts

@@ -0,0 +1,44 @@
+import type { ModuleAction, ModuleDefinition } from '../types/index.js';
+/**
+ * 获取模块定义。
+ *
+ * 模块名匹配大小写不敏感。返回值是注册表内部的已深冻结引用（O(1) 查询、零拷贝），
+ * 任何写入尝试在严格模式下会抛 `TypeError`；如需修改请使用 {@link defineModules}。
+ *
+ * @param moduleName - 模块名。
+ * @returns 已注册的模块定义。
+ * @throws {ZentaoError} `E_INVALID_MODULE` —— 模块未注册。
+ */
+export declare function getModule(moduleName: string): ModuleDefinition;
+/**
+ * 获取指定模块下的某个动作。
+ *
+ * 解析顺序：
+ * 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 declare function getModuleAction(moduleName: string, actionName: string): ModuleAction;
+/**
+ * 返回当前运行时注册表中的所有模块名。
+ *
+ * 顺序与模块写入注册表的顺序一致；包括内置模块和通过 {@link defineModules} 追加的用户模块。
+ *
+ * @returns 模块名数组（保留原始大小写）。
+ */
+export declare function getModuleNames(): string[];
+/**
+ * 判断模块名是否已注册。
+ *
+ * @param moduleName - 模块名；匹配大小写不敏感。
+ * @returns 已注册返回 `true`，否则 `false`。
+ */
+export declare function isModuleName(moduleName: string): boolean;

package/dist/modules/query.js

@@ -0,0 +1,68 @@
+import { ZentaoError } from '../misc/errors.js';
+import { getModuleMapState, getModulesState } from './registry-store.js';
+/**
+ * 获取模块定义。
+ *
+ * 模块名匹配大小写不敏感。返回值是注册表内部的已深冻结引用（O(1) 查询、零拷贝），
+ * 任何写入尝试在严格模式下会抛 `TypeError`；如需修改请使用 {@link defineModules}。
+ *
+ * @param moduleName - 模块名。
+ * @returns 已注册的模块定义。
+ * @throws {ZentaoError} `E_INVALID_MODULE` —— 模块未注册。
+ */
+export function getModule(moduleName) {
+    const module = getModuleMapState().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 getModulesState().map((module) => module.name);
+}
+/**
+ * 判断模块名是否已注册。
+ *
+ * @param moduleName - 模块名；匹配大小写不敏感。
+ * @returns 已注册返回 `true`，否则 `false`。
+ */
+export function isModuleName(moduleName) {
+    return getModuleMapState().has(moduleName.toLowerCase());
+}

package/dist/modules/registry-store.d.ts

@@ -0,0 +1,39 @@
+import type { ModuleAction, ModuleDefinition } from '../types/index.js';
+export declare function deepClone<T>(value: T): T;
+/**
+ * 深度合并：以 `patch` 覆盖 `base`，返回新对象，不修改任何入参。
+ *
+ * - 仅当两侧同为普通对象时递归合并；其余情况（含数组）由 `patch` 整体替换。
+ * - `patch` 中值为 `undefined` 的键会被跳过，因此扩展方只需给出待修改的字段。
+ * - 未被 `patch` 触及的嵌套值沿用 `base` 的引用（外层会重新深冻结，引用本就不可变）。
+ */
+export declare function deepMerge<T>(base: T, patch: unknown): T;
+export declare function cloneBuiltinModules(): ModuleDefinition[];
+export declare function deepFreeze<T>(value: T): T;
+/**
+ * 按 {@link ModuleAction.type} 就地补齐省略的 `method` / `resultType`。
+ *
+ * 已显式声明的字段保持不变；当 `type` 无法推导出对应默认值时抛错，提示显式指定。
+ *
+ * @throws {ZentaoError} `E_INDETERMINATE_ACTION_METHOD` / `E_INDETERMINATE_ACTION_RESULT_TYPE`
+ */
+export declare function normalizeAction(action: ModuleAction): ModuleAction;
+export declare function freezeAction(action: ModuleAction): ModuleAction;
+export declare function freezeModule(module: ModuleDefinition): ModuleDefinition;
+export declare function freezeModules(source: ModuleDefinition[]): ModuleDefinition[];
+export declare function findActionIndex(source: readonly ModuleAction[], actionName: string): number;
+export declare function mergeActions(base: readonly ModuleAction[], extension: readonly ModuleAction[]): ModuleAction[];
+export declare function mergeModule(base: ModuleDefinition, extension: ModuleDefinition): ModuleDefinition;
+export declare function buildModuleMap(source: readonly ModuleDefinition[]): Map<string, ModuleDefinition>;
+export declare function validateModule(module: ModuleDefinition): void;
+export declare function validateAction(action: ModuleAction): void;
+/** 当前运行时注册表中的模块数组（define 侧原地修改，query 侧只读）。 */
+export declare function getModulesState(): ModuleDefinition[];
+/** 当前模块名（小写）到模块定义的查找表（O(1) 查询）。 */
+export declare function getModuleMapState(): Map<string, ModuleDefinition>;
+/** 依据当前 modules 重建 moduleMap。所有写入完成后调用以保持二者一致。 */
+export declare function rebuildModuleMap(): void;
+/** 注册「重置后钩子」，在每次 {@link resetState} 还原内置基线后调用。 */
+export declare function setPostResetHook(hook: (() => void) | undefined): void;
+/** 将注册表重置为内置模块（深克隆 + 深冻结），重建查找表，并触发重置后钩子。 */
+export declare function resetState(): void;