zentao-api 0.6.6 → 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

@@ -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',
@@ -178,6 +180,7 @@ export function applyBuiltinOverrides() {
     // 定义获取需求层级操作
     defineModuleActions('story', {
         name: 'getGrades',
+        minVersion: ['22.5', 'biz13.5', 'max8.5', 'ipd5.5'],
         display: '获取需求层级选项',
         type: 'list',
         method: 'get',

package/dist/modules/query.d.ts

@@ -1,14 +1,15 @@
-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;
 /**
  * 获取指定模块下的某个动作。
  *
@@ -20,9 +21,10 @@ export declare function getModule(moduleName: string): ModuleDefinition | undefi
  *
  * @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;
 /**
  * 获取指定模块下的某个动作的参数。
  *
@@ -30,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[];
 /**
@@ -41,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;
 }
 /**
  * 获取指定模块下的某个动作。
@@ -23,10 +30,11 @@ export function getModule(moduleName) {
  *
  * @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;
@@ -39,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 [];
     }
@@ -98,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;
 }
 /**
  * 获取对象属性。

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');

package/dist/profiles/index.d.ts

@@ -1,4 +1,4 @@
-import type { ZentaoProfile, ZentaoProfileRecord } from '../types/index.js';
+import type { ServerConfig, ZentaoProfile, ZentaoProfileRecord } from '../types/index.js';
 /**
  * 浏览器环境下用于在 `localStorage` 中保存 profile 数据的 key。
  *
@@ -50,6 +50,8 @@ export declare function getProfile(profileKey?: string): Promise<ZentaoProfileRe
  *   `E_INVALID_BASE_URL`、`E_PROFILE_STORAGE_INVALID`、`E_PROFILE_STORAGE_UNAVAILABLE`。
  */
 export declare function addProfile(profile: ZentaoProfile): Promise<ZentaoProfileRecord>;
+/** 只刷新已有 profile 的服务器配置，不切换当前账号或重建已删除的记录。 @internal */
+export declare function updateProfileServerConfig(profileKey: string, serverConfig: ServerConfig, fetchedAt: string): Promise<void>;
 /**
  * 删除指定 profile。
  *

package/dist/profiles/index.js

@@ -238,6 +238,18 @@ export function addProfile(profile) {
         return toRecord(normalized);
     });
 }
+/** 只刷新已有 profile 的服务器配置，不切换当前账号或重建已删除的记录。 @internal */
+export function updateProfileServerConfig(profileKey, serverConfig, fetchedAt) {
+    return withStoreMutex(async () => {
+        const store = await readStore();
+        const profile = findProfile(store, profileKey);
+        if (!profile)
+            return;
+        profile.serverConfig = cloneJson(serverConfig);
+        profile.serverConfigFetchedAt = fetchedAt;
+        await writeStore(store);
+    });
+}
 /**
  * 删除指定 profile。
  *

package/dist/request/index.d.ts

@@ -27,6 +27,9 @@ export type RequestResultFor<Name extends BuiltinRequestName> = ActionMetaOf<Nam
  * 选项优先级为：本次调用 options > 全局 options > 客户端默认值。
  * 当响应 `status` 为 `"fail"` 时，默认按原样返回；若 `options.throwOnFail`
  * 或全局 `throwOnFail` 为真，则改为抛出 `E_API_FAILED`。
+ * 请求前按 Action 的 `minVersion` 检查服务器版本；全局 `version` 可避免配置探测，
+ * `forceRefreshConfig` 则强制使用实际版本。无法获取配置时默认抛错，
+ * `skipVersionCheckOnConfigError` 可允许本次跳过检查，但不能忽略明确的版本不匹配。
  *
  * 对 `update` 动作，当 `options.autoFill` 或全局 `autoFill` 为真时，会先 GET 当前对象，
  * 用现值补齐用户未显式传入的 body 字段后再 PUT，避免禅道覆盖未提交字段。详见 {@link RequestOptions.autoFill}。

package/dist/request/index.js

@@ -1,4 +1,5 @@
-import { ZentaoError } from '../misc/errors.js';
+import { isZentaoConfigFetchError, ZentaoError } from '../misc/errors.js';
+import { parseZentaoVersion, supportsZentaoVersion } from '../misc/zentao-version.js';
 import { getGlobalOptions } from '../misc/global-options.js';
 import { getModule, getModuleAction } from '../modules/registry.js';
 import { extractPager, extractResult, resolveActionRequest } from '../modules/resolve.js';
@@ -57,17 +58,17 @@ function getExplicitDataKeys(data) {
  * 字段归属判断同时覆盖平铺 `params` 字段与 `params.data` 中的字段；只有 schema 中声明、
  * 用户未传且当前对象存在的字段才会被补齐，避免覆盖用户本次想修改的字段。
  */
-async function autoFillUpdateParams(module, action, params, options) {
+async function autoFillUpdateParams(module, action, params, options, version) {
     const properties = action.requestBody?.schema?.properties;
     const getAction = module.actions.find((candidate) => candidate.type === 'get' && candidate.path === action.path);
     if (!properties || !getAction)
         return params;
-    const current = (await request(`${module.name}/${getAction.name}`, params, {
+    const current = (await requestInternal(`${module.name}/${getAction.name}`, params, {
         client: options.client,
         timeout: options.timeout,
         insecure: options.insecure,
         throwOnFail: true,
-    })).data;
+    }, version)).data;
     if (!isRecord(current))
         return params;
     const explicitDataKeys = getExplicitDataKeys(params.data);
@@ -172,6 +173,10 @@ function normalizeResponse(command, raw, options) {
     return response;
 }
 export async function request(name, params = {}, options = {}) {
+    return requestInternal(name, params, options);
+}
+/** version 为 undefined 时解析一次，null 表示本次调用已选择跳过版本检查。 */
+async function requestInternal(name, params, options, version) {
     const globals = getGlobalOptions();
     const client = options.client ?? globals.client;
     if (!client) {
@@ -195,8 +200,35 @@ export async function request(name, params = {}, options = {}) {
     if (!action) {
         throw new ZentaoError('E_INVALID_ACTION', { module: moduleName, action: actionName });
     }
+    if (version === undefined) {
+        if (!options.forceRefreshConfig && globals.version !== undefined) {
+            version = globals.version;
+        }
+        else {
+            try {
+                version = (await client.getZentaoConfig({
+                    forceRefresh: options.forceRefreshConfig,
+                    timeout: options.timeout ?? globals.timeout,
+                    insecure: options.insecure ?? globals.insecure,
+                })).version;
+            }
+            catch (error) {
+                if (!(options.skipVersionCheckOnConfigError ?? globals.skipVersionCheckOnConfigError)
+                    || !isZentaoConfigFetchError(error))
+                    throw error;
+                version = null;
+            }
+        }
+    }
+    if (version !== null && !supportsZentaoVersion(parseZentaoVersion(version), action.minVersion)) {
+        throw new ZentaoError('E_UNSUPPORTED_ZENTAO_VERSION', {
+            action: `${module.name}/${action.name}`,
+            version,
+            minVersion: action.minVersion.join(', '),
+        }, { action: `${module.name}/${action.name}`, version, minVersion: action.minVersion });
+    }
     const finalParams = action.type === 'update' && (options.autoFill ?? globals.autoFill)
-        ? await autoFillUpdateParams(module, action, mergedParams, options)
+        ? await autoFillUpdateParams(module, action, mergedParams, { ...options, client }, version)
         : mergedParams;
     const command = resolveActionRequest(module, actionName, finalParams);
     const preparedBody = await prepareActionBody(command, {

package/dist/types/client.d.ts

@@ -36,3 +36,8 @@ export interface ClientRequestOptions {
     /** 单次请求 TLS 跳过证书验证选项；仅 Node.js 运行时支持。 */
     insecure?: boolean;
 }
+/** {@link ZentaoClient.getZentaoConfig} 的选项。 */
+export interface GetZentaoConfigOptions extends Pick<ClientRequestOptions, 'timeout' | 'insecure' | 'signal'> {
+    /** 忽略已有缓存并重新获取配置，默认 false；同一客户端的并发获取会合并。 */
+    forceRefresh?: boolean;
+}

package/dist/types/module.d.ts

@@ -90,6 +90,8 @@ export type ModuleActionGetterFn<T, O = RequestProcessOptions> = (data: unknown,
 export interface ModuleAction {
     /** 动作名称，例如 `list`、`get`、`close`。 */
     name: ModuleActionName;
+    /** 各系列支持的最低禅道正式版本，例如 `['22.0', 'biz13.0', 'max8.0', 'ipd5.0']`；不能为空或重复系列，未列出的系列不支持。 */
+    minVersion: readonly string[];
     /** 动作类型，决定高阶 request 的路径/参数解析策略，并在 `method`、`resultType` 省略时作为推导依据。 */
     type: ModuleActionType;
     /** 面向用户展示的动作名称。 */
@@ -140,6 +142,11 @@ export interface ModuleDefinition {
     /** 模块支持的动作集合。 */
     actions: readonly ModuleAction[];
 }
+/** 注册库查询选项；不传版本时返回完整的当前定义，不使用全局版本。 */
+export interface ModuleQueryOptions {
+    /** 仅返回该禅道版本支持的动作，以及至少含有一个支持动作的模块。 */
+    version?: string;
+}
 /** 将模块动作和参数解析后的可执行请求描述。 */
 export interface ModuleActionRequest {
     /** 模块名称。 */

package/dist/types/options.d.ts

@@ -2,6 +2,10 @@ import type { ZentaoClient } from '../client/index.js';
 import type { ProcessListOptions, ProcessSingleOptions } from './data.js';
 /** SDK 进程级全局默认选项，供高阶 {@link request} 调用复用。 */
 export interface GlobalOptions {
+    /** 当前禅道正式版本，例如 `biz13.5`；普通高阶请求直接使用，单次强制刷新时使用实际版本。不会自动写入 profile。 */
+    version?: string;
+    /** 配置网络或响应获取失败时，允许登录继续或高阶请求跳过版本检查，默认 false；不忽略版本不匹配、格式错误或存储错误。 */
+    skipVersionCheckOnConfigError?: boolean;
     /** 默认客户端；通常由 `ZentaoClient.init()` 设置。 */
     client?: ZentaoClient;
     /** 默认每页记录数，会映射到模块动作的 `recPerPage` 参数。 */
@@ -25,6 +29,10 @@ export interface GlobalOptions {
 }
 /** 高阶 `request("moduleName")` / `request("moduleName/methodName")` / `request("moduleName/<objectID>")` 的单次调用选项。 */
 export interface RequestOptions extends ProcessListOptions {
+    /** 强制刷新服务器配置并用实际版本校验本次请求，优先于全局 version；不会改写全局版本。 */
+    forceRefreshConfig?: boolean;
+    /** 配置网络或响应获取失败时跳过本次版本检查；优先于全局设置，默认 false，不忽略版本不匹配或格式错误。 */
+    skipVersionCheckOnConfigError?: boolean;
     /** 本次调用使用的客户端；优先级高于全局客户端。 */
     client?: ZentaoClient;
     /** 本次调用使用的每页记录数，优先级高于全局 `recPerPage`。 */

package/dist/types/profile.d.ts

@@ -36,6 +36,8 @@ export interface ZentaoProfile {
     lastUsedTime?: string;
     /** 禅道服务端配置。 */
     serverConfig?: ServerConfig;
+    /** 成功从 `?mode=getconfig` 获取配置的本地 ISO 时间；缺失时缓存需要刷新。 */
+    serverConfigFetchedAt?: string;
     /** 客户端自定义配置。 */
     config?: ZentaoProfileConfig;
     /** 允许上层应用保存额外字段。 */

package/dist/types/response.d.ts

@@ -58,6 +58,13 @@ export interface LoginResponse extends ApiResponse {
 }
 /** 禅道 `?mode=getconfig` 返回的服务端配置。 */
 export interface ServerConfig {
+    /**
+     * 禅道版本，不同系列以不同的前缀表示，下面为例子：
+     * - `22.5`：开源版 22.5
+     * - `biz13.5`：企业版 13.5
+     * - `max8.5`：旗舰版 8.5
+     * - `ipd5.5`：IPD 5.5
+     */
     version: string;
     systemMode: string;
     sprintConcept: string;
@@ -67,4 +74,6 @@ export interface ServerConfig {
     methodVar: string;
     viewVar: string;
     sessionVar: string;
+    /** 保留服务端返回的其他配置字段。 */
+    [key: string]: unknown;
 }

package/dist/version.js

@@ -1,5 +1,5 @@
-const fallbackBuild = "2026-08-29T09:25:28.910Z";
-const fallbackVersion = "0.6.6";
+const fallbackBuild = "2026-09-05T14:37:58.417Z";
+const fallbackVersion = "0.6.7";
 /**
  * 构建标识，由构建脚本通过 `__ZENTAO_API_BUILD__` 注入。
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zentao-api",
-  "version": "0.6.6",
+  "version": "0.6.7",
   "type": "module",
   "description": "Browser and Node.js SDK for ZenTao API",
   "license": "MIT",