zentao-api 0.3.2 → 0.4.0

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',
             }
         ],
     },
@@ -1021,13 +1016,12 @@ export const BUILTIN_MODULES = [
                 display: '获取产品计划列表，支持获取产品下的产品计划',
                 type: 'list',
                 method: 'get',
-                path: '/{scope}/{scopeID}/productplans',
+                path: '/products/{productID}/productplans',
                 resultType: 'list',
                 pagerGetter: 'pager',
                 resultGetter: 'productplans',
                 pathParams: {
-                    scope: { description: '产品计划范围', options: [{ value: 'products', label: '产品' }] },
-                    scopeID: '范围ID',
+                    productID: '所属产品ID',
                 },
                 params: [
                     {
@@ -1193,7 +1187,6 @@ export const BUILTIN_MODULES = [
                 pathParams: {
                     productplanID: '产品计划ID',
                 },
-                render: 'action',
             }
         ],
     },
@@ -1213,8 +1206,8 @@ export const BUILTIN_MODULES = [
                 pagerGetter: 'pager',
                 resultGetter: 'stories',
                 pathParams: {
-                    scope: { description: '需求范围', options: [{ value: 'products', label: '产品' }, { value: 'projects', label: '项目' }, { value: 'executions', label: '执行' }] },
-                    scopeID: '范围ID',
+                    scope: { description: '需求所属范围', options: [{ value: 'products', label: '产品' }, { value: 'projects', label: '项目' }, { value: 'executions', label: '执行' }] },
+                    scopeID: '所属范围ID',
                 },
                 params: [
                     {
@@ -1423,7 +1416,6 @@ export const BUILTIN_MODULES = [
                 pathParams: {
                     storyID: '需求ID',
                 },
-                render: 'action',
             }, {
                 name: 'activate',
                 display: '激活需求',
@@ -1451,7 +1443,6 @@ export const BUILTIN_MODULES = [
                         }
                     },
                 },
-                render: 'action',
             }, {
                 name: 'change',
                 display: '变更需求',
@@ -1493,7 +1484,6 @@ export const BUILTIN_MODULES = [
                         ]
                     },
                 },
-                render: 'action',
             }, {
                 name: 'close',
                 display: '关闭需求',
@@ -1524,7 +1514,6 @@ export const BUILTIN_MODULES = [
                         ]
                     },
                 },
-                render: 'action',
             }
         ],
     },
@@ -1539,13 +1528,12 @@ export const BUILTIN_MODULES = [
                 display: '获取业务需求列表，支持获取产品下的业务需求',
                 type: 'list',
                 method: 'get',
-                path: '/{scope}/{scopeID}/epics',
+                path: '/products/{productID}/epics',
                 resultType: 'list',
                 pagerGetter: 'pager',
                 resultGetter: 'epics',
                 pathParams: {
-                    scope: { description: '业务需求范围', options: [{ value: 'products', label: '产品' }] },
-                    scopeID: '范围ID',
+                    productID: '所属产品ID',
                 },
                 params: [
                     {
@@ -1745,7 +1733,6 @@ export const BUILTIN_MODULES = [
                 pathParams: {
                     epicID: '业务需求ID',
                 },
-                render: 'action',
             }, {
                 name: 'activate',
                 display: '激活业务需求',
@@ -1773,7 +1760,6 @@ export const BUILTIN_MODULES = [
                         }
                     },
                 },
-                render: 'action',
             }, {
                 name: 'change',
                 display: '变更业务需求',
@@ -1815,7 +1801,6 @@ export const BUILTIN_MODULES = [
                         ]
                     },
                 },
-                render: 'action',
             }, {
                 name: 'close',
                 display: '关闭业务需求',
@@ -1846,7 +1831,6 @@ export const BUILTIN_MODULES = [
                         ]
                     },
                 },
-                render: 'action',
             }
         ],
     },
@@ -1861,13 +1845,12 @@ export const BUILTIN_MODULES = [
                 display: '获取用户需求列表，支持获取产品下的用户需求',
                 type: 'list',
                 method: 'get',
-                path: '/{scope}/{scopeID}/requirements',
+                path: '/products/{productID}/requirements',
                 resultType: 'list',
                 pagerGetter: 'pager',
                 resultGetter: 'requirements',
                 pathParams: {
-                    scope: { description: '用户需求范围', options: [{ value: 'products', label: '产品' }] },
-                    scopeID: '范围ID',
+                    productID: '所属产品ID',
                 },
                 params: [
                     {
@@ -2066,7 +2049,6 @@ export const BUILTIN_MODULES = [
                 pathParams: {
                     requirementID: '用户需求ID',
                 },
-                render: 'action',
             }, {
                 name: 'activate',
                 display: '激活用户需求',
@@ -2094,7 +2076,6 @@ export const BUILTIN_MODULES = [
                         }
                     },
                 },
-                render: 'action',
             }, {
                 name: 'change',
                 display: '变更用户需求',
@@ -2126,7 +2107,6 @@ export const BUILTIN_MODULES = [
                         }
                     },
                 },
-                render: 'action',
             }, {
                 name: 'close',
                 display: '关闭用户需求',
@@ -2157,7 +2137,6 @@ export const BUILTIN_MODULES = [
                         ]
                     },
                 },
-                render: 'action',
             }
         ],
     },
@@ -2177,8 +2156,8 @@ export const BUILTIN_MODULES = [
                 pagerGetter: 'pager',
                 resultGetter: 'bugs',
                 pathParams: {
-                    scope: { description: 'Bug范围', options: [{ value: 'products', label: '产品' }, { value: 'projects', label: '项目' }, { value: 'executions', label: '执行' }] },
-                    scopeID: '范围ID',
+                    scope: { description: 'Bug所属范围', options: [{ value: 'products', label: '产品' }, { value: 'projects', label: '项目' }, { value: 'executions', label: '执行' }] },
+                    scopeID: '所属范围ID',
                 },
                 params: [
                     {
@@ -2376,7 +2355,6 @@ export const BUILTIN_MODULES = [
                 pathParams: {
                     bugID: 'Bug ID',
                 },
-                render: 'action',
             }, {
                 name: 'activate',
                 display: '激活Bug',
@@ -2411,7 +2389,6 @@ export const BUILTIN_MODULES = [
                         }
                     },
                 },
-                render: 'action',
             }, {
                 name: 'close',
                 display: '关闭Bug',
@@ -2435,7 +2412,6 @@ export const BUILTIN_MODULES = [
                         }
                     },
                 },
-                render: 'action',
             }, {
                 name: 'resolve',
                 display: '解决Bug',
@@ -2478,7 +2454,6 @@ export const BUILTIN_MODULES = [
                         ]
                     },
                 },
-                render: 'action',
             }
         ],
     },
@@ -2498,8 +2473,8 @@ export const BUILTIN_MODULES = [
                 pagerGetter: 'pager',
                 resultGetter: 'testcases',
                 pathParams: {
-                    scope: { description: '测试用例范围', options: [{ value: 'products', label: '产品' }, { value: 'projects', label: '项目' }, { value: 'executions', label: '执行' }] },
-                    scopeID: '范围ID',
+                    scope: { description: '测试用例所属范围', options: [{ value: 'products', label: '产品' }, { value: 'projects', label: '项目' }, { value: 'executions', label: '执行' }] },
+                    scopeID: '所属范围ID',
                 },
                 params: [
                     {
@@ -2715,7 +2690,6 @@ export const BUILTIN_MODULES = [
                 pathParams: {
                     testcasID: '测试用例ID',
                 },
-                render: 'action',
             }
         ],
     },
@@ -2730,13 +2704,12 @@ export const BUILTIN_MODULES = [
                 display: '获取任务列表，支持获取执行下的任务',
                 type: 'list',
                 method: 'get',
-                path: '/{scope}/{scopeID}/tasks',
+                path: '/executions/{executionID}/tasks',
                 resultType: 'list',
                 pagerGetter: 'pager',
                 resultGetter: 'tasks',
                 pathParams: {
-                    scope: { description: '任务范围', options: [{ value: 'executions', label: '执行' }] },
-                    scopeID: '范围ID',
+                    executionID: '所属执行ID',
                 },
                 params: [
                     {
@@ -2933,7 +2906,6 @@ export const BUILTIN_MODULES = [
                 pathParams: {
                     taskID: '任务ID',
                 },
-                render: 'action',
             }, {
                 name: 'activate',
                 display: '激活任务',
@@ -2966,7 +2938,6 @@ export const BUILTIN_MODULES = [
                         }
                     },
                 },
-                render: 'action',
             }, {
                 name: 'close',
                 display: '关闭任务',
@@ -2990,7 +2961,6 @@ export const BUILTIN_MODULES = [
                         }
                     },
                 },
-                render: 'action',
             }, {
                 name: 'finish',
                 display: '完成任务',
@@ -3041,7 +3011,6 @@ export const BUILTIN_MODULES = [
                         ]
                     },
                 },
-                render: 'action',
             }, {
                 name: 'start',
                 display: '启动任务',
@@ -3086,7 +3055,6 @@ export const BUILTIN_MODULES = [
                         ]
                     },
                 },
-                render: 'action',
             }
         ],
     },
@@ -3101,13 +3069,12 @@ export const BUILTIN_MODULES = [
                 display: '获取反馈列表，支持获取产品下的反馈',
                 type: 'list',
                 method: 'get',
-                path: '/{scope}/{scopeID}/feedbacks',
+                path: '/products/{productID}/feedbacks',
                 resultType: 'list',
                 pagerGetter: 'pager',
                 resultGetter: 'feedbacks',
                 pathParams: {
-                    scope: { description: '反馈范围', options: [{ value: 'products', label: '产品' }] },
-                    scopeID: '范围ID',
+                    productID: '所属产品ID',
                 },
                 params: [
                     {
@@ -3277,7 +3244,6 @@ export const BUILTIN_MODULES = [
                 pathParams: {
                     feedbackID: '反馈ID',
                 },
-                render: 'action',
             }, {
                 name: 'activate',
                 display: '激活反馈',
@@ -3305,7 +3271,6 @@ export const BUILTIN_MODULES = [
                         }
                     },
                 },
-                render: 'action',
             }, {
                 name: 'close',
                 display: '关闭反馈',
@@ -3336,7 +3301,6 @@ export const BUILTIN_MODULES = [
                         ]
                     },
                 },
-                render: 'action',
             }
         ],
     },
@@ -3351,13 +3315,12 @@ export const BUILTIN_MODULES = [
                 display: '获取工单列表，支持获取产品下的工单',
                 type: 'list',
                 method: 'get',
-                path: '/{scope}/{scopeID}/tickets',
+                path: '/products/{productID}/tickets',
                 resultType: 'list',
                 pagerGetter: 'pager',
                 resultGetter: 'tickets',
                 pathParams: {
-                    scope: { description: '工单范围', options: [{ value: 'products', label: '产品' }] },
-                    scopeID: '范围ID',
+                    productID: '所属产品ID',
                 },
                 params: [
                     {
@@ -3538,7 +3501,6 @@ export const BUILTIN_MODULES = [
                 pathParams: {
                     ticketID: '工单ID',
                 },
-                render: 'action',
             }, {
                 name: 'activate',
                 display: '激活工单',
@@ -3566,7 +3528,6 @@ export const BUILTIN_MODULES = [
                         }
                     },
                 },
-                render: 'action',
             }, {
                 name: 'close',
                 display: '关闭工单',
@@ -3598,7 +3559,6 @@ export const BUILTIN_MODULES = [
                         ]
                     },
                 },
-                render: 'action',
             }
         ],
     },
@@ -3613,12 +3573,11 @@ export const BUILTIN_MODULES = [
                 display: '获取应用列表，支持获取产品下的应用',
                 type: 'list',
                 method: 'get',
-                path: '/{scope}/{scopeID}/systems',
+                path: '/products/{productID}/systems',
                 resultType: 'list',
                 pagerGetter: 'pager',
                 pathParams: {
-                    scope: { description: '应用范围', options: [{ value: 'products', label: '产品' }] },
-                    scopeID: '范围ID',
+                    productID: '所属产品ID',
                 },
             }, {
                 name: 'create',
@@ -3724,8 +3683,8 @@ export const BUILTIN_MODULES = [
                 pagerGetter: 'pager',
                 resultGetter: 'builds',
                 pathParams: {
-                    scope: { description: '版本范围', options: [{ value: 'projects', label: '项目' }, { value: 'executions', label: '执行' }] },
-                    scopeID: '范围ID',
+                    scope: { description: '版本所属范围', options: [{ value: 'projects', label: '项目' }, { value: 'executions', label: '执行' }] },
+                    scopeID: '所属范围ID',
                 },
             }, {
                 name: 'create',
@@ -3866,7 +3825,6 @@ export const BUILTIN_MODULES = [
                 pathParams: {
                     buildID: '版本ID',
                 },
-                render: 'action',
             }
         ],
     },
@@ -3886,8 +3844,8 @@ export const BUILTIN_MODULES = [
                 pagerGetter: 'pager',
                 resultGetter: 'testtasks',
                 pathParams: {
-                    scope: { description: '测试单范围', options: [{ value: 'products', label: '产品' }, { value: 'projects', label: '项目' }, { value: 'executions', label: '执行' }] },
-                    scopeID: '范围ID',
+                    scope: { description: '测试单所属范围', options: [{ value: 'products', label: '产品' }, { value: 'projects', label: '项目' }, { value: 'executions', label: '执行' }] },
+                    scopeID: '所属范围ID',
                 },
             }, {
                 name: 'create',
@@ -4034,7 +3992,6 @@ export const BUILTIN_MODULES = [
                 pathParams: {
                     testtaskID: '测试单ID',
                 },
-                render: 'action',
             }
         ],
     },
@@ -4049,13 +4006,12 @@ export const BUILTIN_MODULES = [
                 display: '获取发布列表，支持获取产品下的发布',
                 type: 'list',
                 method: 'get',
-                path: '/{scope}/{scopeID}/releases',
+                path: '/products/{productID}/releases',
                 resultType: 'list',
                 pagerGetter: 'pager',
                 resultGetter: 'releases',
                 pathParams: {
-                    scope: { description: '发布范围', options: [{ value: 'products', label: '产品' }] },
-                    scopeID: '范围ID',
+                    productID: '所属产品ID',
                 },
             }, {
                 name: 'create',
@@ -4176,7 +4132,6 @@ export const BUILTIN_MODULES = [
                 pathParams: {
                     releasID: '发布ID',
                 },
-                render: 'action',
             }
         ],
     },
@@ -4219,7 +4174,6 @@ export const BUILTIN_MODULES = [
                 pathParams: {
                     fileID: '附件ID',
                 },
-                render: 'action',
             }
         ],
     }

package/dist/modules/query.d.ts

@@ -1,4 +1,4 @@
-import type { ModuleAction, ModuleDefinition } from '../types/index.js';
+import type { ModuleAction, ModuleActionParam, ModuleActionParamRole, ModuleDefinition } from '../types/index.js';
 /**
  * 获取模块定义。
  *
@@ -27,6 +27,18 @@ export declare function getModule(moduleName: string): ModuleDefinition;
  * @throws {ZentaoError} `E_INVALID_MODULE`（模块未注册）或 `E_INVALID_ACTION`（动作不存在）。
  */
 export declare function getModuleAction(moduleName: string, actionName: string): ModuleAction;
+/**
+ * 获取指定模块下的某个动作的参数。
+ *
+ * @param moduleName - 模块名（大小写不敏感）。
+ * @param actionName - 动作名（大小写不敏感）；支持 `ls` 作为 `list` 的别名。
+ * @param options - 选项。
+ * @param options.roles - 角色，可选 `path`、`query`、`body`。
+ * @returns 动作参数。
+ */
+export declare function getModuleActionParams(moduleName: string, actionName: string, options?: {
+    roles?: ModuleActionParamRole[];
+}): ModuleActionParam[];
 /**
  * 返回当前运行时注册表中的所有模块名。
  *

package/dist/modules/query.js

@@ -47,6 +47,65 @@ export function getModuleAction(moduleName, actionName) {
     }
     throw new ZentaoError('E_INVALID_ACTION', { module: moduleName, action: actionName });
 }
+/**
+ * 获取指定模块下的某个动作的参数。
+ *
+ * @param moduleName - 模块名（大小写不敏感）。
+ * @param actionName - 动作名（大小写不敏感）；支持 `ls` 作为 `list` 的别名。
+ * @param options - 选项。
+ * @param options.roles - 角色，可选 `path`、`query`、`body`。
+ * @returns 动作参数。
+ */
+export function getModuleActionParams(moduleName, actionName, options) {
+    const { roles } = options ?? {};
+    const params = [];
+    const action = getModuleAction(moduleName, actionName);
+    if (!action) {
+        return [];
+    }
+    if (action.pathParams && (!roles || roles.includes('path'))) {
+        Object.entries(action.pathParams).forEach(([name, param]) => {
+            if (typeof param === 'string') {
+                param = {
+                    description: param,
+                };
+            }
+            params.push({
+                name,
+                role: 'path',
+                required: true,
+                ...param,
+            });
+        });
+    }
+    if (action.params && (!roles || roles.includes('query'))) {
+        params.push(...action.params.map(x => ({ ...x, role: 'query' })));
+    }
+    const schema = action.requestBody?.schema;
+    if (schema && (!roles || roles.includes('body'))) {
+        if (schema.type === 'object') {
+            const requiredSet = new Set(schema.required ? schema.required.map(x => x.toLowerCase()) : []);
+            Object.entries(schema.properties).forEach(([name, property]) => {
+                params.push({
+                    name,
+                    role: 'body',
+                    required: property.required ?? requiredSet.has(name.toLowerCase()),
+                    type: (property.type === 'integer' ? 'number' : property.type) ?? 'string',
+                    ...property,
+                });
+            });
+        }
+        else {
+            params.push({
+                name: 'data',
+                role: 'body',
+                required: true,
+                type: schema.type,
+            });
+        }
+    }
+    return params;
+}
 /**
  * 返回当前运行时注册表中的所有模块名。
  *

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

@@ -10,6 +10,14 @@ export declare function deepClone<T>(value: T): T;
 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[];

package/dist/modules/registry-store.js

@@ -1,6 +1,23 @@
 import { ZentaoError } from '../misc/errors.js';
 import { isRecord } from '../utils/object.js';
 import { BUILTIN_MODULES } from './generated.js';
+// 动作类型到 HTTP 方法 / 结果形态的默认推导表：当动作未显式声明 method / resultType 时按 type 补齐。
+const METHOD_BY_TYPE = {
+    list: 'get',
+    get: 'get',
+    create: 'post',
+    update: 'put',
+    delete: 'delete',
+    action: 'post',
+};
+const RESULT_TYPE_BY_TYPE = {
+    list: 'list',
+    get: 'object',
+    create: 'object',
+    update: 'object',
+    delete: 'text',
+    action: 'text',
+};
 // 运行时注册表存放「深克隆 + 深冻结」后的模块定义：
 // - 深克隆：避免用户后续修改自己的输入对象时污染注册表；
 // - 深冻结：让 getModule / getModuleAction 可以零拷贝返回引用，
@@ -57,8 +74,32 @@ export function deepFreeze(value) {
     }
     return Object.freeze(value);
 }
+/**
+ * 按 {@link ModuleAction.type} 就地补齐省略的 `method` / `resultType`。
+ *
+ * 已显式声明的字段保持不变；当 `type` 无法推导出对应默认值时抛错，提示显式指定。
+ *
+ * @throws {ZentaoError} `E_INDETERMINATE_ACTION_METHOD` / `E_INDETERMINATE_ACTION_RESULT_TYPE`
+ */
+export function normalizeAction(action) {
+    if (action.method === undefined) {
+        const method = METHOD_BY_TYPE[action.type];
+        if (method === undefined) {
+            throw new ZentaoError('E_INDETERMINATE_ACTION_METHOD', { action: String(action.name), type: String(action.type) });
+        }
+        action.method = method;
+    }
+    if (action.resultType === undefined) {
+        const resultType = RESULT_TYPE_BY_TYPE[action.type];
+        if (resultType === undefined) {
+            throw new ZentaoError('E_INDETERMINATE_ACTION_RESULT_TYPE', { action: String(action.name), type: String(action.type) });
+        }
+        action.resultType = resultType;
+    }
+    return action;
+}
 export function freezeAction(action) {
-    return deepFreeze(action);
+    return deepFreeze(normalizeAction(action));
 }
 export function freezeModule(module) {
     module.actions.forEach(freezeAction);
@@ -102,7 +143,14 @@ export function validateModule(module) {
     }
 }
 export function validateAction(action) {
-    if (!action || typeof action.name !== 'string' || typeof action.path !== 'string' || typeof action.method !== 'string') {
+    if (!action || typeof action.name !== 'string' || typeof action.path !== 'string') {
+        throw new ZentaoError('E_INVALID_ACTION_DEFINITION');
+    }
+    // method / resultType 可省略（由 normalizeAction 按 type 推导），但显式给出时必须是字符串。
+    if (action.method !== undefined && typeof action.method !== 'string') {
+        throw new ZentaoError('E_INVALID_ACTION_DEFINITION');
+    }
+    if (action.resultType !== undefined && typeof action.resultType !== 'string') {
         throw new ZentaoError('E_INVALID_ACTION_DEFINITION');
     }
 }