zentao-api 0.6.5 → 0.6.7

package/dist/modules/override.d.ts

@@ -20,6 +20,7 @@
  * ```ts
  * defineModuleActions('bug', {
  *   name: 'assignTo',
+ *   minVersion: ['22.0', 'biz13.0', 'max8.0', 'ipd5.0'],
  *   display: '指派 Bug',
  *   type: 'action',
  *   method: 'put',
@@ -44,6 +45,7 @@
  *   actions: [
  *     {
  *       name: 'list',
+ *       minVersion: ['22.0', 'biz13.0', 'max8.0', 'ipd5.0'],
  *       type: 'list',
  *       method: 'get',
  *       path: '/customs',

package/dist/modules/override.js

@@ -1,4 +1,4 @@
-import { extendModuleAction } from './define.js';
+import { extendModuleAction, defineModuleActions } from './define.js';
 import { extractResult } from './resolve.js';
 import { snapshotToMarkdown } from '../utils/doc-helper/markdown.js';
 import { isRecord } from '../utils/index.js';
@@ -24,6 +24,7 @@ import { isRecord } from '../utils/index.js';
  * ```ts
  * defineModuleActions('bug', {
  *   name: 'assignTo',
+ *   minVersion: ['22.0', 'biz13.0', 'max8.0', 'ipd5.0'],
  *   display: '指派 Bug',
  *   type: 'action',
  *   method: 'put',
@@ -48,6 +49,7 @@ import { isRecord } from '../utils/index.js';
  *   actions: [
  *     {
  *       name: 'list',
+ *       minVersion: ['22.0', 'biz13.0', 'max8.0', 'ipd5.0'],
  *       type: 'list',
  *       method: 'get',
  *       path: '/customs',
@@ -90,14 +92,6 @@ export function applyBuiltinOverrides() {
         }
         return action;
     });
-    // 修改 task/list URL 定义
-    extendModuleAction('task', 'list', (action) => {
-        action.path = '/executions/{executionID}/tasks';
-        action.pathParams = {
-            executionID: '执行ID',
-        };
-        return action;
-    });
     // 修改 acl 字段默认值为 open
     [
         ['product', 'create'],
@@ -113,31 +107,10 @@ export function applyBuiltinOverrides() {
             return action;
         });
     });
-    // execution-create 支持创建阶段
+    // execution/create 补充 OpenAPI 尚未声明的里程碑字段
     extendModuleAction('execution', 'create', (action) => {
         const properties = action.requestBody.schema?.properties;
         if (properties) {
-            if (!properties.type) {
-                properties.type = {
-                    type: 'string',
-                    description: '类型(sprint 迭代，敏捷项目用 | stage 阶段，瀑布/IPD 用 | kanban 看板)',
-                };
-            }
-            if (!properties.attribute) {
-                properties.attribute = {
-                    type: 'string',
-                    description: [
-                        '阶段属性：mix - 综合（父阶段可挂不同类型子阶段）',
-                        'request - 需求（不关联需求、不测、不构建、不导入 Bug）',
-                        'design - 设计（不测、不构建、不 DevOps）',
-                        'dev - 开发（功能完整，可需求、任务、测试、构建）',
-                        'qa - 测试（同上，偏测试）',
-                        'release - 发布（同上，偏发布）',
-                        'review - 总结评审（最严：不关联需求、不测、不构建）',
-                        'other - 其他（无上述专项限制）'
-                    ].join(' | '),
-                };
-            }
             if (!properties.milestone) {
                 properties.milestone = {
                     type: 'integer',
@@ -145,13 +118,6 @@ export function applyBuiltinOverrides() {
                     format: 'int32'
                 };
             }
-            if (!properties.parent) {
-                properties.parent = {
-                    type: 'integer',
-                    description: '父级项目',
-                    format: 'int32'
-                };
-            }
         }
         return action;
     });
@@ -179,34 +145,6 @@ export function applyBuiltinOverrides() {
         }
         return action;
     });
-    // 修改 BUG 列表选项
-    extendModuleAction('bug', 'list', (action) => {
-        const params = action.params;
-        const browseTypeParam = params?.find((param) => param.name === 'browseType');
-        if (browseTypeParam && browseTypeParam.options?.length) {
-            const options = browseTypeParam.options;
-            const assignedtomeOption = options.find(x => x.value === 'assignedtome');
-            if (assignedtomeOption) {
-                browseTypeParam.options = [
-                    ...options.filter(x => x !== assignedtomeOption),
-                    {
-                        ...assignedtomeOption,
-                        value: 'assigntome',
-                    }
-                ];
-            }
-            if (!browseTypeParam.options.some(x => x.value === 'resolvedbyme')) {
-                browseTypeParam.options = [
-                    ...browseTypeParam.options,
-                    {
-                        value: 'resolvedbyme',
-                        label: '由我解决',
-                    }
-                ];
-            }
-        }
-        return action;
-    });
     // 获取文档详情时支持将文档原始 JSON 内容转换为 Markdown
     extendModuleAction('doc', 'get', (action) => {
         const oldGetter = action.resultGetter;
@@ -239,4 +177,39 @@ export function applyBuiltinOverrides() {
         };
         return action;
     });
+    // 定义获取需求层级操作
+    defineModuleActions('story', {
+        name: 'getGrades',
+        minVersion: ['22.5', 'biz13.5', 'max8.5', 'ipd5.5'],
+        display: '获取需求层级选项',
+        type: 'list',
+        method: 'get',
+        path: '/storygrades',
+        resultType: 'list',
+        resultGetter: 'grades',
+    });
+    // 需求创建时支持设置需求层级
+    extendModuleAction('story', 'create', (action) => {
+        const properties = action.requestBody.schema?.properties;
+        if (properties && !properties.grade) {
+            properties.grade = {
+                type: 'integer',
+                description: '需求层级，可用的需求层级可以通过 story-getGrades 操作获取',
+            };
+        }
+        return action;
+    });
+    // 创建和修改任务时，任务类型字段
+    ['create', 'update'].forEach((actionName) => {
+        extendModuleAction('task', actionName, (action) => {
+            const properties = action.requestBody.schema?.properties;
+            if (properties && !properties.type) {
+                properties.type = {
+                    type: 'string',
+                    description: '任务类型（枚举：design 设计 | devel 开发 | request 需求 | test 测试 | study 研究 | discuss 讨论 | ui 界面 | affair 事务 | misc 其他）',
+                };
+            }
+            return action;
+        });
+    });
 }

package/dist/modules/query.d.ts

@@ -1,30 +1,30 @@
-import type { ModuleAction, ModuleActionParam, ModuleActionParamRole, ModuleDefinition } from '../types/index.js';
+import type { ModuleAction, ModuleActionParam, ModuleActionParamRole, ModuleDefinition, ModuleQueryOptions } from '../types/index.js';
 /**
  * 获取模块定义。
  *
- * 模块名匹配大小写不敏感。返回值是注册表内部的已深冻结引用（O(1) 查询、零拷贝），
+ * 模块名匹配大小写不敏感。未传版本时返回注册表内部的已深冻结引用（O(1) 查询、零拷贝），
  * 任何写入尝试在严格模式下会抛 `TypeError`；如需修改请使用 {@link defineModules}。
  *
  * @param moduleName - 模块名。
- * @returns 已注册的模块定义；模块未注册时返回 `undefined`。
+ * @param options - 可选版本过滤；不传时保留完整注册表引用，传入时返回冻结的过滤视图。
+ * @returns 已注册的模块定义；模块未注册或过滤后没有动作时返回 `undefined`。
  */
-export declare function getModule(moduleName: string): ModuleDefinition | undefined;
+export declare function getModule(moduleName: string, options?: ModuleQueryOptions): ModuleDefinition | undefined;
 /**
  * 获取指定模块下的某个动作。
  *
  * 解析顺序：
  * 1. `actionName === 'ls'` 时映射为 `list`（仅作为别名，不会修改注册表）。
  * 2. 在该模块的动作中按名称大小写不敏感匹配。
- * 3. 当请求的动作不是基础 CRUD（`list`/`get`/`create`/`update`/`delete`）时，
- *    额外允许命中 `type === 'action'` 的自定义动作（即使名字不在基础 CRUD 中）。
  *
  * 返回值同样是已深冻结的引用，请勿尝试修改。
  *
  * @param moduleName - 模块名（大小写不敏感）。
  * @param actionName - 动作名（大小写不敏感）；支持 `ls` 作为 `list` 的别名。
+ * @param options - 可选版本过滤。
  * @returns 匹配到的动作定义；模块未注册或动作不存在时返回 `undefined`。
  */
-export declare function getModuleAction(moduleName: string, actionName: string): ModuleAction | undefined;
+export declare function getModuleAction(moduleName: string, actionName: string, options?: ModuleQueryOptions): ModuleAction | undefined;
 /**
  * 获取指定模块下的某个动作的参数。
  *
@@ -32,9 +32,10 @@ export declare function getModuleAction(moduleName: string, actionName: string):
  * @param actionName - 动作名（大小写不敏感）；支持 `ls` 作为 `list` 的别名。
  * @param options - 选项。
  * @param options.roles - 角色，可选 `path`、`query`、`body`。
+ * @param options.version - 可选禅道版本；不支持该动作时返回空数组，不做参数级版本过滤。
  * @returns 动作参数。
  */
-export declare function getModuleActionParams(moduleName: string, actionName: string, options?: {
+export declare function getModuleActionParams(moduleName: string, actionName: string, options?: ModuleQueryOptions & {
     roles?: ModuleActionParamRole[];
 }): ModuleActionParam[];
 /**
@@ -43,15 +44,17 @@ export declare function getModuleActionParams(moduleName: string, actionName: st
  * 顺序与模块写入注册表的顺序一致；包括内置模块和通过 {@link defineModules} 追加的用户模块。
  *
  * @returns 模块名数组（保留原始大小写）。
+ * @param options - 可选版本过滤，仅保留含有支持动作的模块。
  */
-export declare function getModuleNames(): string[];
+export declare function getModuleNames(options?: ModuleQueryOptions): string[];
 /**
  * 判断模块名是否已注册。
  *
  * @param moduleName - 模块名；匹配大小写不敏感。
+ * @param options - 可选版本过滤。
  * @returns 已注册返回 `true`，否则 `false`。
  */
-export declare function isModuleName(moduleName: string): boolean;
+export declare function isModuleName(moduleName: string, options?: ModuleQueryOptions): boolean;
 /**
  * 获取对象属性。
  *

package/dist/modules/query.js

@@ -1,16 +1,23 @@
+import { parseZentaoVersion, supportsZentaoVersion } from '../misc/zentao-version.js';
 import { objectProps } from './object-props.js';
 import { getModuleMapState, getModulesState } from './registry-store.js';
 /**
  * 获取模块定义。
  *
- * 模块名匹配大小写不敏感。返回值是注册表内部的已深冻结引用（O(1) 查询、零拷贝），
+ * 模块名匹配大小写不敏感。未传版本时返回注册表内部的已深冻结引用（O(1) 查询、零拷贝），
  * 任何写入尝试在严格模式下会抛 `TypeError`；如需修改请使用 {@link defineModules}。
  *
  * @param moduleName - 模块名。
- * @returns 已注册的模块定义；模块未注册时返回 `undefined`。
+ * @param options - 可选版本过滤；不传时保留完整注册表引用，传入时返回冻结的过滤视图。
+ * @returns 已注册的模块定义；模块未注册或过滤后没有动作时返回 `undefined`。
  */
-export function getModule(moduleName) {
-    return getModuleMapState().get(moduleName.toLowerCase());
+export function getModule(moduleName, options = {}) {
+    const version = options.version === undefined ? undefined : parseZentaoVersion(options.version);
+    const module = getModuleMapState().get(moduleName.toLowerCase());
+    if (!version || !module)
+        return module;
+    const actions = module.actions.filter(action => supportsZentaoVersion(version, action.minVersion));
+    return actions.length ? Object.freeze({ ...module, actions: Object.freeze(actions) }) : undefined;
 }
 /**
  * 获取指定模块下的某个动作。
@@ -18,30 +25,20 @@ export function getModule(moduleName) {
  * 解析顺序：
  * 1. `actionName === 'ls'` 时映射为 `list`（仅作为别名，不会修改注册表）。
  * 2. 在该模块的动作中按名称大小写不敏感匹配。
- * 3. 当请求的动作不是基础 CRUD（`list`/`get`/`create`/`update`/`delete`）时，
- *    额外允许命中 `type === 'action'` 的自定义动作（即使名字不在基础 CRUD 中）。
  *
  * 返回值同样是已深冻结的引用，请勿尝试修改。
  *
  * @param moduleName - 模块名（大小写不敏感）。
  * @param actionName - 动作名（大小写不敏感）；支持 `ls` 作为 `list` 的别名。
+ * @param options - 可选版本过滤。
  * @returns 匹配到的动作定义；模块未注册或动作不存在时返回 `undefined`。
  */
-export function getModuleAction(moduleName, actionName) {
-    const module = getModule(moduleName);
+export function getModuleAction(moduleName, actionName, options) {
+    const module = getModule(moduleName, options);
     if (!module)
         return undefined;
     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;
-    }
-    return undefined;
+    return module.actions.find((action) => String(action.name).toLowerCase() === normalized.toLowerCase());
 }
 /**
  * 获取指定模块下的某个动作的参数。
@@ -50,12 +47,13 @@ export function getModuleAction(moduleName, actionName) {
  * @param actionName - 动作名（大小写不敏感）；支持 `ls` 作为 `list` 的别名。
  * @param options - 选项。
  * @param options.roles - 角色，可选 `path`、`query`、`body`。
+ * @param options.version - 可选禅道版本；不支持该动作时返回空数组，不做参数级版本过滤。
  * @returns 动作参数。
  */
 export function getModuleActionParams(moduleName, actionName, options) {
     const { roles } = options ?? {};
     const params = [];
-    const action = getModuleAction(moduleName, actionName);
+    const action = getModuleAction(moduleName, actionName, options);
     if (!action) {
         return [];
     }
@@ -82,12 +80,13 @@ export function getModuleActionParams(moduleName, actionName, options) {
         if (schema.type === 'object') {
             const requiredSet = new Set(schema.required ? schema.required.map(x => x.toLowerCase()) : []);
             Object.entries(schema.properties).forEach(([name, property]) => {
+                const propertyType = property.type;
                 params.push({
+                    ...property,
                     name,
                     role: 'body',
                     required: property.required ?? requiredSet.has(name.toLowerCase()),
-                    type: (property.type === 'integer' ? 'number' : property.type) ?? 'string',
-                    ...property,
+                    type: propertyType === 'integer' ? 'number' : propertyType ?? 'string',
                 });
             });
         }
@@ -108,18 +107,23 @@ export function getModuleActionParams(moduleName, actionName, options) {
  * 顺序与模块写入注册表的顺序一致；包括内置模块和通过 {@link defineModules} 追加的用户模块。
  *
  * @returns 模块名数组（保留原始大小写）。
+ * @param options - 可选版本过滤，仅保留含有支持动作的模块。
  */
-export function getModuleNames() {
-    return getModulesState().map((module) => module.name);
+export function getModuleNames(options = {}) {
+    const version = options.version === undefined ? undefined : parseZentaoVersion(options.version);
+    return getModulesState()
+        .filter(module => !version || module.actions.some(action => supportsZentaoVersion(version, action.minVersion)))
+        .map(module => module.name);
 }
 /**
  * 判断模块名是否已注册。
  *
  * @param moduleName - 模块名；匹配大小写不敏感。
+ * @param options - 可选版本过滤。
  * @returns 已注册返回 `true`，否则 `false`。
  */
-export function isModuleName(moduleName) {
-    return getModuleMapState().has(moduleName.toLowerCase());
+export function isModuleName(moduleName, options) {
+    return getModule(moduleName, options) !== undefined;
 }
 /**
  * 获取对象属性。
@@ -128,5 +132,5 @@ export function isModuleName(moduleName) {
  * @returns 对象属性。
  */
 export function getObjectProps(objectType) {
-    return objectProps[objectType];
+    return objectProps[objectType] ?? {};
 }

package/dist/modules/registry-store.js

@@ -1,4 +1,5 @@
 import { ZentaoError } from '../misc/errors.js';
+import { validateMinVersion } from '../misc/zentao-version.js';
 import { isRecord } from '../utils/object.js';
 import { BUILTIN_MODULES } from './generated.js';
 // 动作类型到 HTTP 方法 / 结果形态的默认推导表：当动作未显式声明 method / resultType 时按 type 补齐。
@@ -99,6 +100,7 @@ export function normalizeAction(action) {
     return action;
 }
 export function freezeAction(action) {
+    validateAction(action);
     return deepFreeze(normalizeAction(action));
 }
 export function freezeModule(module) {
@@ -146,6 +148,7 @@ export function validateAction(action) {
     if (!action || typeof action.name !== 'string' || typeof action.path !== 'string') {
         throw new ZentaoError('E_INVALID_ACTION_DEFINITION');
     }
+    validateMinVersion(action.minVersion);
     // method / resultType 可省略（由 normalizeAction 按 type 推导），但显式给出时必须是字符串。
     if (action.method !== undefined && typeof action.method !== 'string') {
         throw new ZentaoError('E_INVALID_ACTION_DEFINITION');