meeglesdk 0.1.8 → 0.2.0

package/dist/service/workitem/wbsDraft.js

@@ -0,0 +1,394 @@
+/**
+ * WBS 草稿服务
+ *
+ * 之所以单独拆出这个服务，是因为计划表草稿接口已经形成独立能力域，
+ * 继续混在 workflow 服务里会让文档对齐、接口扩展和测试边界越来越混乱。
+ */
+import { BaseService } from '../../core/base-service.js';
+import { WbsProjectKeyResolver } from './wbsProjectKeyResolver.js';
+/** API 路径 */
+export const API_PATHS = {
+    /** 创建 WBS 草稿 */
+    CREATE: '/open_api/work_item/wbs_draft/create',
+    /** 查询 WBS 草稿 */
+    QUERY: '/open_api/work_item/wbs_view_draft/query',
+    /** 查询创建草稿进度 */
+    CREATE_PROGRESS: '/open_api/work_item/wbs_draft_create/progress/query',
+    /** 更新 WBS 草稿 */
+    PATCH: '/open_api/work_item/wbs_draft/patch/update',
+    /** 查询更新草稿进度 */
+    PATCH_PROGRESS: '/open_api/work_item/wbs_draft_patch/progress/query',
+    /** 发布 WBS 草稿 */
+    PUBLISH: '/open_api/work_item/wbs_draft/publish',
+    /** 完成创建草稿审核 */
+    COMPLETE_CREATE_AUDIT: '/open_api/wbs_view_draft/complete-create-audit',
+    /** 重置 WBS 草稿 */
+    RESET: '/open_api/work_item/wbs_draft/reset',
+    /** 查询发布草稿进度 */
+    PUBLISH_PROGRESS: '/open_api/work_item/wbs_draft_publish/progress/query',
+    /** 查询重置草稿进度 */
+    RESET_PROGRESS: '/open_api/work_item/wbs_draft_reset/progress/query',
+    /** 查询 WBS 草稿子工作项配置 */
+    SUB_WORK_ITEM_CONF: '/open_api/work_item/wbs_view_draft/sub_work_item_conf',
+    /** 查询 WBS 草稿骨架 */
+    STRUCTURE: '/open_api/work_item/wbs_draft/structure/query',
+    /** 查询 WBS 草稿行详情 */
+    ROW_DETAIL: '/open_api/work_item/wbs_draft/detail/query',
+    /** 查询 WBS 草稿行配置 */
+    ROW_CONFIG: '/open_api/work_item/wbs_draft/task_conf/query',
+    /** 更新草稿冻结行 */
+    UPDATE_FROZEN_ROWS: '/open_api/:project_key/wbs_view_draft/update/frozen_rows',
+    /** 基于提交版本发布草稿 */
+    COLLABORATION_PUBLISH: '/open_api/:project_key/wbs_view_draft/publish',
+    /** 审批拒绝切回草稿 */
+    SWITCH_BACK: '/open_api/:project_key/wbs_view_draft/switch',
+};
+/**
+ * WBS 草稿服务
+ */
+export class WbsDraftService extends BaseService {
+    projectKeyResolver;
+    constructor(requestHandler) {
+        super(requestHandler);
+        this.projectKeyResolver = new WbsProjectKeyResolver(requestHandler);
+    }
+    /**
+     * 创建 WBS 草稿
+     *
+     * @param request 创建请求
+     * @param options 请求选项
+     * @returns 创建草稿结果
+     */
+    async createDraft(request, options) {
+        const projectKey = await this.projectKeyResolver.resolveProjectKey({
+            projectKey: request.project_key,
+            workItemId: request.work_item_id,
+            workItemTypeKey: request.work_item_type_key,
+            options,
+        });
+        return this.post(API_PATHS.CREATE, {
+            ...request,
+            project_key: projectKey,
+        }, options);
+    }
+    /**
+     * 查询 WBS 草稿
+     *
+     * @param request 查询请求
+     * @param options 请求选项
+     * @returns WBS 草稿
+     */
+    async getDraft(request, options) {
+        const projectKey = await this.projectKeyResolver.resolveProjectKey({
+            projectKey: request.project_key,
+            workItemId: request.work_item_id,
+            workItemTypeKey: request.work_item_type_key,
+            options,
+        });
+        const result = await this.post(API_PATHS.QUERY, {
+            ...request,
+            project_key: projectKey,
+        }, options);
+        return result.wbs_draft ?? {};
+    }
+    /**
+     * 更新 WBS 草稿
+     *
+     * @param request 更新请求
+     * @param options 请求选项
+     * @returns 平台返回的关系字段回填结果
+     */
+    async patchDraft(request, options) {
+        const projectKey = await this.projectKeyResolver.resolveProjectKey({
+            projectKey: request.project_key,
+            workItemId: request.work_item_id,
+            options,
+        });
+        return this.post(API_PATHS.PATCH, {
+            ...request,
+            project_key: projectKey,
+        }, options);
+    }
+    /**
+     * 发布 WBS 草稿
+     *
+     * @param request 发布请求
+     * @param options 请求选项
+     */
+    async publishDraft(request, options) {
+        const projectKey = await this.projectKeyResolver.resolveProjectKey({
+            projectKey: request.project_key,
+            workItemId: request.work_item_id,
+            options,
+        });
+        return this.post(API_PATHS.PUBLISH, {
+            ...request,
+            project_key: projectKey,
+        }, options);
+    }
+    /**
+     * 查询创建草稿进度
+     *
+     * @param request 进度查询请求
+     * @param options 请求选项
+     * @returns 任务进度
+     */
+    async getCreateDraftProgress(request, options) {
+        const projectKey = await this.projectKeyResolver.resolveProjectKey({
+            projectKey: request.project_key,
+            workItemId: request.work_item_id,
+            options,
+        });
+        return this.post(API_PATHS.CREATE_PROGRESS, {
+            ...request,
+            project_key: projectKey,
+        }, options);
+    }
+    /**
+     * 完成创建草稿审核
+     *
+     * 这条接口和普通草稿发布链路分离，
+     * 单独暴露可以避免调用方误把审核态提交当成普通发布。
+     *
+     * @param request 审核完成请求
+     * @param options 请求选项
+     * @returns 是否成功
+     */
+    async completeCreateAuditDraft(request, options) {
+        const projectKey = await this.projectKeyResolver.resolveProjectKey({
+            projectKey: request.project_key,
+            workItemId: request.work_item_id,
+            options,
+        });
+        const result = await this.post(API_PATHS.COMPLETE_CREATE_AUDIT, {
+            ...request,
+            project_key: projectKey,
+        }, options);
+        return { success: result.success };
+    }
+    /**
+     * 重置 WBS 草稿
+     *
+     * @param request 重置请求
+     * @param options 请求选项
+     * @returns 重置后的 WBS 草稿
+     */
+    async resetDraft(request, options) {
+        const projectKey = await this.projectKeyResolver.resolveProjectKey({
+            projectKey: request.project_key,
+            workItemId: request.work_item_id,
+            options,
+        });
+        return this.post(API_PATHS.RESET, {
+            ...request,
+            project_key: projectKey,
+        }, options);
+    }
+    /**
+     * 查询更新草稿进度
+     *
+     * @param request 进度查询请求
+     * @param options 请求选项
+     * @returns 任务进度
+     */
+    async getPatchDraftProgress(request, options) {
+        const projectKey = await this.projectKeyResolver.resolveProjectKey({
+            projectKey: request.project_key,
+            options,
+        });
+        return this.post(API_PATHS.PATCH_PROGRESS, {
+            ...request,
+            project_key: projectKey,
+        }, options);
+    }
+    /**
+     * 查询 WBS 草稿子工作项配置
+     *
+     * @param request 查询请求
+     * @param options 请求选项
+     * @returns 子工作项配置列表
+     */
+    async getSubWorkItemConf(request, options) {
+        const projectKey = await this.projectKeyResolver.resolveProjectKey({
+            projectKey: request.project_key,
+            workItemId: request.work_item_id,
+            options,
+        });
+        const result = await this.get(API_PATHS.SUB_WORK_ITEM_CONF, {
+            ...options,
+            query: {
+                draft_id: request.draft_id,
+                work_item_id: request.work_item_id,
+                node_uuid: request.node_uuid,
+                project_key: projectKey,
+                ...options?.query,
+            },
+        });
+        return result.draft_view_sub_work_item_confs ?? [];
+    }
+    /**
+     * 查询全量计划表草稿骨架
+     *
+     * 草稿骨架是后续行详情查询的前置输入，保持独立方法可以让调用链路更清晰。
+     *
+     * @param request 草稿骨架查询请求
+     * @param options 请求选项
+     * @returns 草稿骨架响应
+     */
+    async queryStructure(request, options) {
+        const projectKey = await this.projectKeyResolver.resolveProjectKey({
+            projectKey: request.project_key,
+            workItemId: request.work_item_id,
+            options,
+        });
+        return this.post(API_PATHS.STRUCTURE, {
+            ...request,
+            project_key: projectKey,
+        }, options);
+    }
+    /**
+     * 查询计划表草稿数据行详细信息
+     *
+     * @param request 草稿行详情查询请求
+     * @param options 请求选项
+     * @returns 草稿行详情原始响应
+     */
+    async queryRowDetails(request, options) {
+        const projectKey = await this.projectKeyResolver.resolveProjectKey({
+            projectKey: request.project_key,
+            workItemId: request.work_item_id,
+            options,
+        });
+        return this.post(API_PATHS.ROW_DETAIL, {
+            ...request,
+            project_key: projectKey,
+        }, options);
+    }
+    /**
+     * 查询计划表草稿行配置信息
+     *
+     * @param request 草稿行配置查询请求
+     * @param options 请求选项
+     * @returns 草稿行配置原始响应
+     */
+    async queryRowConfig(request, options) {
+        const projectKey = await this.projectKeyResolver.resolveProjectKey({
+            projectKey: request.project_key,
+            workItemId: request.work_item_id,
+            options,
+        });
+        return this.post(API_PATHS.ROW_CONFIG, {
+            ...request,
+            project_key: projectKey,
+        }, options);
+    }
+    /**
+     * 更新草稿冻结行
+     *
+     * @param request 冻结行更新请求
+     * @param options 请求选项
+     */
+    async updateFrozenRows(request, options) {
+        const projectKey = await this.projectKeyResolver.resolveProjectKey({
+            projectKey: request.project_key,
+            workItemId: request.work_item_id,
+            options,
+        });
+        await this.post(API_PATHS.UPDATE_FROZEN_ROWS, request, {
+            ...options,
+            pathParams: {
+                ...(options?.pathParams ?? {}),
+                project_key: projectKey,
+            },
+            responseValidator: options?.responseValidator,
+        });
+    }
+    /**
+     * 基于提交版本发布草稿
+     *
+     * @param request 发布请求
+     * @param options 请求选项
+     * @returns 是否成功
+     */
+    async publishDraftByCommit(request, options) {
+        const projectKey = await this.projectKeyResolver.resolveProjectKey({
+            projectKey: request.project_key,
+            workItemId: request.work_item_id,
+            options,
+        });
+        const result = await this.post(API_PATHS.COLLABORATION_PUBLISH, {
+            work_item_id: request.work_item_id,
+            draft_id: request.draft_id,
+            commit_id: request.commit_id,
+        }, {
+            ...options,
+            pathParams: {
+                ...(options?.pathParams ?? {}),
+                project_key: projectKey,
+            },
+        });
+        return { success: result.success };
+    }
+    /**
+     * 查询发布草稿进度
+     *
+     * @param request 进度查询请求
+     * @param options 请求选项
+     * @returns 任务进度
+     */
+    async getPublishDraftProgress(request, options) {
+        const projectKey = await this.projectKeyResolver.resolveProjectKey({
+            projectKey: request.project_key,
+            workItemId: request.work_item_id,
+            options,
+        });
+        return this.post(API_PATHS.PUBLISH_PROGRESS, {
+            ...request,
+            project_key: projectKey,
+        }, options);
+    }
+    /**
+     * 审批拒绝后切回草稿
+     *
+     * @param request 切回草稿请求
+     * @param options 请求选项
+     * @returns 是否成功
+     */
+    async switchBackDraft(request, options) {
+        const projectKey = await this.projectKeyResolver.resolveProjectKey({
+            projectKey: request.project_key,
+            workItemId: request.work_item_id,
+            options,
+        });
+        const result = await this.post(API_PATHS.SWITCH_BACK, {
+            work_item_id: request.work_item_id,
+            draft_id: request.draft_id,
+            commit_id: request.commit_id,
+        }, {
+            ...options,
+            pathParams: {
+                ...(options?.pathParams ?? {}),
+                project_key: projectKey,
+            },
+        });
+        return { success: result.success };
+    }
+    /**
+     * 查询重置草稿进度
+     *
+     * @param request 进度查询请求
+     * @param options 请求选项
+     * @returns 任务进度
+     */
+    async getResetDraftProgress(request, options) {
+        const projectKey = await this.projectKeyResolver.resolveProjectKey({
+            projectKey: request.project_key,
+            workItemId: request.work_item_id,
+            options,
+        });
+        return this.post(API_PATHS.RESET_PROGRESS, {
+            ...request,
+            project_key: projectKey,
+        }, options);
+    }
+}

package/dist/service/workitem/wbsProjectKeyResolver.d.ts

@@ -0,0 +1,34 @@
+/**
+ * WBS 空间标识解析器
+ *
+ * WBS 相关接口对 project_key 的要求和普通工作项接口不同：
+ * 普通接口通常接受 simple_name，而 WBS 接口实际要求内部 project_key。
+ * 这里统一做一次解析，避免调用方为同一空间维护两套标识。
+ */
+import { BaseService, type ServiceRequestOptions } from '../../core/base-service.js';
+interface ResolveProjectKeyRequest {
+    projectKey: string;
+    workItemId?: number;
+    workItemTypeKey?: string;
+    options?: ServiceRequestOptions<unknown>;
+}
+/**
+ * WBS project_key 解析器
+ */
+export declare class WbsProjectKeyResolver extends BaseService {
+    private readonly cache;
+    private readonly pending;
+    /**
+     * 解析 WBS 可用的 project_key
+     *
+     * @param request 解析参数
+     * @returns WBS 接口可接受的空间 key
+     */
+    resolveProjectKey(request: ResolveProjectKeyRequest): Promise<string>;
+    private resolveProjectKeyInternal;
+    private resolveByWorkItemQuery;
+    private resolveByWorkItemFilter;
+    private extractCanonicalProjectKey;
+    private pickResolverOptions;
+}
+export {};

package/dist/service/workitem/wbsProjectKeyResolver.js

@@ -0,0 +1,133 @@
+/**
+ * WBS 空间标识解析器
+ *
+ * WBS 相关接口对 project_key 的要求和普通工作项接口不同：
+ * 普通接口通常接受 simple_name，而 WBS 接口实际要求内部 project_key。
+ * 这里统一做一次解析，避免调用方为同一空间维护两套标识。
+ */
+import { BaseService } from '../../core/base-service.js';
+const API_PATHS = {
+    WORK_ITEM_QUERY: '/open_api/:project_key/work_item/:work_item_type_key/query',
+    WORK_ITEM_FILTER: '/open_api/:project_key/work_item/filter',
+    WORK_ITEM_TYPES: '/open_api/:project_key/work_item/all-types',
+};
+const CANONICAL_PROJECT_KEY_PATTERN = /^[0-9a-f]{24}$/i;
+/**
+ * WBS project_key 解析器
+ */
+export class WbsProjectKeyResolver extends BaseService {
+    cache = new Map();
+    pending = new Map();
+    /**
+     * 解析 WBS 可用的 project_key
+     *
+     * @param request 解析参数
+     * @returns WBS 接口可接受的空间 key
+     */
+    async resolveProjectKey(request) {
+        const projectKey = request.projectKey.trim();
+        if (!projectKey || CANONICAL_PROJECT_KEY_PATTERN.test(projectKey)) {
+            return projectKey;
+        }
+        const cached = this.cache.get(projectKey);
+        if (cached) {
+            return cached;
+        }
+        const pending = this.pending.get(projectKey);
+        if (pending) {
+            return pending;
+        }
+        const task = this.resolveProjectKeyInternal({
+            ...request,
+            projectKey,
+        }).finally(() => {
+            this.pending.delete(projectKey);
+        });
+        this.pending.set(projectKey, task);
+        return task;
+    }
+    async resolveProjectKeyInternal(request) {
+        const { projectKey, workItemId, workItemTypeKey, options } = request;
+        if (workItemId !== undefined && workItemTypeKey) {
+            const byQuery = await this.resolveByWorkItemQuery(projectKey, workItemId, workItemTypeKey, options);
+            if (byQuery) {
+                this.cache.set(projectKey, byQuery);
+                return byQuery;
+            }
+        }
+        if (workItemId !== undefined) {
+            const byFilter = await this.resolveByWorkItemFilter(projectKey, workItemId, options);
+            if (byFilter) {
+                this.cache.set(projectKey, byFilter);
+                return byFilter;
+            }
+        }
+        return projectKey;
+    }
+    async resolveByWorkItemQuery(projectKey, workItemId, workItemTypeKey, options) {
+        try {
+            const result = await this.post(API_PATHS.WORK_ITEM_QUERY, {
+                work_item_ids: [workItemId],
+            }, {
+                ...this.pickResolverOptions(options),
+                pathParams: {
+                    ...(options?.pathParams ?? {}),
+                    project_key: projectKey,
+                    work_item_type_key: workItemTypeKey,
+                },
+            });
+            return this.extractCanonicalProjectKey(result[0]?.project_key);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async resolveByWorkItemFilter(projectKey, workItemId, options) {
+        try {
+            const workItemTypes = await this.get(API_PATHS.WORK_ITEM_TYPES, {
+                ...this.pickResolverOptions(options),
+                pathParams: {
+                    ...(options?.pathParams ?? {}),
+                    project_key: projectKey,
+                },
+            });
+            const workItemTypeKeys = workItemTypes
+                .map((item) => item.type_key || item.api_name)
+                .filter((item) => Boolean(item));
+            if (workItemTypeKeys.length === 0) {
+                return undefined;
+            }
+            const result = await this.postPaginated(API_PATHS.WORK_ITEM_FILTER, {
+                work_item_type_keys: workItemTypeKeys,
+                work_item_ids: [workItemId],
+                page_size: 1,
+            }, {
+                ...this.pickResolverOptions(options),
+                pathParams: {
+                    ...(options?.pathParams ?? {}),
+                    project_key: projectKey,
+                },
+            });
+            return this.extractCanonicalProjectKey(result.data[0]?.project_key);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    extractCanonicalProjectKey(projectKey) {
+        if (!projectKey) {
+            return undefined;
+        }
+        return CANONICAL_PROJECT_KEY_PATTERN.test(projectKey) ? projectKey : undefined;
+    }
+    pickResolverOptions(options) {
+        return {
+            query: options?.query,
+            auth: options?.auth,
+            idempotencyKey: options?.idempotencyKey,
+            timeout: options?.timeout,
+            skipRetry: options?.skipRetry,
+            retry: options?.retry,
+        };
+    }
+}

package/dist/service/workitem/wbsView/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * WBS 发布态服务
+ *
+ * 计划表发布态接口和草稿态是两套能力边界，
+ * 单独拆出服务可以避免 draft/view 两类接口再次混用。
+ */
+import { BaseService, type ServiceRequestOptions } from '../../../core/base-service.js';
+import type { QueryWbsViewStructureRequest, QueryWbsViewStructureResponse, QueryWbsViewRowDetailRequest, QueryWbsViewRowDetailResponse, QueryWbsInstanceExpandInfoRequest, QueryWbsInstanceExpandInfoResponse } from '../../../types/workitem.js';
+/** API 路径 */
+export declare const API_PATHS: {
+    /** 查询全量计划表骨架 */
+    STRUCTURE: string;
+    /** 查询计划表行详情 */
+    DETAIL: string;
+    /** 查询计划表扩展信息 */
+    EXPAND: string;
+};
+/**
+ * WBS 发布态服务
+ */
+export declare class WbsViewService extends BaseService {
+    /**
+     * 查询全量计划表骨架
+     *
+     * @param request 查询请求
+     * @param options 请求选项
+     * @returns 发布态计划表骨架
+     */
+    queryStructure(request: QueryWbsViewStructureRequest, options?: ServiceRequestOptions<QueryWbsViewStructureResponse>): Promise<QueryWbsViewStructureResponse>;
+    /**
+     * 查询计划表行详细信息
+     *
+     * @param request 查询请求
+     * @param options 请求选项
+     * @returns 发布态计划表行详情
+     */
+    queryRowDetails(request: QueryWbsViewRowDetailRequest, options?: ServiceRequestOptions<QueryWbsViewRowDetailResponse>): Promise<QueryWbsViewRowDetailResponse>;
+    /**
+     * 查询计划表扩展信息
+     *
+     * @param request 查询请求
+     * @param options 请求选项
+     * @returns 发布态计划表扩展信息
+     */
+    queryExpandInfo(request: QueryWbsInstanceExpandInfoRequest, options?: ServiceRequestOptions<QueryWbsInstanceExpandInfoResponse>): Promise<QueryWbsInstanceExpandInfoResponse>;
+}

package/dist/service/workitem/wbsView/index.js

@@ -0,0 +1,51 @@
+/**
+ * WBS 发布态服务
+ *
+ * 计划表发布态接口和草稿态是两套能力边界，
+ * 单独拆出服务可以避免 draft/view 两类接口再次混用。
+ */
+import { BaseService } from '../../../core/base-service.js';
+/** API 路径 */
+export const API_PATHS = {
+    /** 查询全量计划表骨架 */
+    STRUCTURE: '/open_api/work_item/wbs_view/structure/query',
+    /** 查询计划表行详情 */
+    DETAIL: '/open_api/work_item/wbs_view/detail/query',
+    /** 查询计划表扩展信息 */
+    EXPAND: '/open_api/work_item/wbs_instance/expand/query',
+};
+/**
+ * WBS 发布态服务
+ */
+export class WbsViewService extends BaseService {
+    /**
+     * 查询全量计划表骨架
+     *
+     * @param request 查询请求
+     * @param options 请求选项
+     * @returns 发布态计划表骨架
+     */
+    async queryStructure(request, options) {
+        return this.post(API_PATHS.STRUCTURE, request, options);
+    }
+    /**
+     * 查询计划表行详细信息
+     *
+     * @param request 查询请求
+     * @param options 请求选项
+     * @returns 发布态计划表行详情
+     */
+    async queryRowDetails(request, options) {
+        return this.post(API_PATHS.DETAIL, request, options);
+    }
+    /**
+     * 查询计划表扩展信息
+     *
+     * @param request 查询请求
+     * @param options 请求选项
+     * @returns 发布态计划表扩展信息
+     */
+    async queryExpandInfo(request, options) {
+        return this.post(API_PATHS.EXPAND, request, options);
+    }
+}