@cloudbase/manager-node 5.6.7 → 5.7.0-beta.0

package/types/deploy/DatabaseDeployer.d.ts

@@ -0,0 +1,70 @@
+import { Environment } from '../environment';
+import { IPGUserMigrationInput } from '../database/type';
+/** 数据库迁移部署配置（对应 cloudbaserc.json 中的 database 块） */
+export interface IDatabaseDeployConfig {
+    /** 数据库类型（v2.1 schema: 目前仅支持 postgresql） */
+    type: 'postgresql';
+    /** migration SQL 文件目录（相对项目根） */
+    migrations?: string;
+}
+/** Plan 中单条 migration 的状态 */
+export interface IDatabasePlanItem {
+    /** 14位数字时间串 */
+    version: string;
+    /** migration 名称 */
+    name: string;
+    /** pending=待执行；applied=已应用；conflict=冲突 */
+    status: 'pending' | 'applied' | 'conflict';
+    /** 冲突原因（仅 conflict 时有值） */
+    reason?: string;
+}
+/** deploy 返回结果 */
+export interface IDatabaseDeployResult {
+    /** 异步任务 ID（无pending时为空字符串） */
+    taskId: string;
+}
+export declare class DatabaseDeployer {
+    private environment;
+    constructor(environment: Environment);
+    /**
+     * 从本地目录解析 migration 文件列表
+     *
+     * 文件名格式：{14位时间戳}_{小写下划线名称}.sql
+     * 例如：20260526000000_create_users.sql
+     *
+     * 按文件名升序排列（即按版本号从早到晚）
+     */
+    parseMigrationFiles(migrationsDir: string): IPGUserMigrationInput[];
+    /**
+     * 生成部署计划
+     *
+     * 调用 previewPGUserMigrations 获取云端对比结果，
+     * 返回每条migration 的状态（pending / applied / conflict）
+     */
+    plan(config: IDatabaseDeployConfig, cwd: string, envId: string): Promise<IDatabasePlanItem[]>;
+    /**
+     * 执行数据库迁移
+     *
+     * 流程：
+     * 1. 解析本地 migration 文件
+     * 2. 预览确认无冲突（有冲突直接 throw，中断整个部署）
+     * 3. 无 pending 则跳过
+     * 4. 提交 pushPGUserMigrations
+     * 5. 轮询describeTaskResult 等待完成
+     */
+    deploy(config: IDatabaseDeployConfig, cwd: string, envId: string): Promise<IDatabaseDeployResult>;
+    /**
+     * 解析 migrations 目录路径
+     * - 未配置：默认 ./cloudbase/migrations
+     * - 仅允许相对路径（禁止 / 开头）
+     */
+    private resolveMigrationsDir;
+    /**
+     * 校验 database.type（当前仅支持 postgresql）
+     */
+    private assertDatabaseType;
+    /**
+     * 轮询等待异步任务完成
+     */
+    private waitForTask;
+}

package/types/deploy/DeployOrchestrator.d.ts

@@ -0,0 +1,150 @@
+import { Environment } from '../environment';
+/** 可编排的资源类型 */
+export type ResourceType = 'database' | 'functions' | 'app' | 'hosting' | 'gateway';
+/** 声明式部署选项 */
+export interface IDeployOptions {
+    /** 解析后的 cloudbaserc 配置（ConfigParser 输出，含 envOverrides 已应用） */
+    config: Record<string, any>;
+    envId: string;
+    /** 只部署指定类型 */
+    only?: ResourceType[];
+    /** 跳过指定类型 */
+    skip?: ResourceType[];
+    /** dry-run：只输出计划不实际部署 */
+    dryRun?: boolean;
+    /** 项目根目录（默认 process.cwd()） */
+    cwd?: string;
+    /** 已存在资源（函数）的覆盖更新：yes=true 直接放行（AI Agent / CI 场景） */
+    yes?: boolean;
+    /** 已存在资源（函数）的覆盖更新确认回调：返回 true 部署、false 跳过（CLI 注入 autoConfirm） */
+    confirmUpdate?: (item: IDeployPlanItem) => Promise<boolean>;
+    /** 强制云端对比（漂移检测）：忽略本地 state 快照的 skip 判定，强制重新对比/部署 */
+    refresh?: boolean;
+    log?: {
+        info?: (msg: string) => void;
+        success?: (msg: string) => void;
+        warn?: (msg: string) => void;
+        error?: (msg: string) => void;
+    };
+}
+/** 部署计划项（资源级） */
+export interface IDeployPlanItem {
+    type: ResourceType;
+    name: string;
+    /** 动作分类：create=新建；update=覆盖更新已有资源；skip=已存在且配置一致；conflict=检测到冲突（需中断）；deploy=直传覆盖（无存在性概念） */
+    status: 'create' | 'update' | 'skip' | 'conflict' | 'deploy';
+    /** 动作说明（用户可读） */
+    action: string;
+    /** 变更字段明细（如 database 迁移聚合、gateway 路由差异等） */
+    changes?: Array<{
+        field: string;
+        from?: string;
+        to?: string;
+    }>;
+    /** hosting 文件级 diff（新增/修改/删除，前 N 条 + 统计） */
+    fileDiff?: {
+        added: string[];
+        modified: string[];
+        deleted: string[];
+        totalChanged: number;
+    };
+    /** 资源级详情子行（dry-run 树状渲染用）：如函数 runtime/构建策略、迁移逐条状态等 */
+    details?: Array<{
+        label: string;
+        value: string;
+    }>;
+}
+/** 部署结果 */
+export interface IDeployResult {
+    plan: IDeployPlanItem[];
+    results: Array<{
+        type: ResourceType;
+        name: string;
+        ok: boolean;
+        url?: string;
+        error?: string;
+        /** 未执行原因：skip=未变更自动跳过；no-confirm=无确认机制保守跳过；skipped-by-user=用户拒绝覆盖 */
+        reason?: 'skip' | 'no-confirm' | 'skipped-by-user';
+    }>;
+}
+/**
+ * 声明式部署编排器
+ * 顺序：database → functions → app → hosting → gateway
+ * 支持 dry-run / only / skip / 幂等重试（database 失败/冲突会中断后续步骤）
+ */
+export declare class DeployOrchestrator {
+    private environment;
+    private databaseDeployer;
+    private functionDeployer;
+    private staticDeployer;
+    private gatewayDeployer;
+    constructor(environment: Environment);
+    /**
+     * 计算部署计划（dry-run 输出）
+     */
+    deployPlan(options: IDeployOptions): Promise<IDeployPlanItem[]>;
+    /**
+     * 执行部署
+     */
+    deploy(options: IDeployOptions): Promise<IDeployResult>;
+    /**
+     * 部署成功后写回本地 state 快照
+     *
+     * - hosting：成功部署/未变更（skip）的项重算产物指纹；失败项保留旧快照
+     * - app：成功部署写 buildAppConfig 快照；skip 复用旧快照
+     * - gateway：保留旧快照（本轮不做路由级实时快照）
+     */
+    private persistState;
+    /**
+     * 构建完整部署计划（按依赖顺序 + only/skip 过滤）
+     *
+     * 通过查询云端状态判定每个资源的动作：
+     * - database：先按迁移文件做 preview，再聚合成单条资源级计划项（pending→create，存在 conflict→conflict，全部 applied→不出现在 plan）
+     * - functions：ListFunctions 判断是否已存在 → create / update（不做本地 hash / 字段 diff）
+     * - app：describeAppInfo 判断是否已存在 → create / update；本地 state 配置一致 → skip
+     * - hosting：本地 state 指纹 diff → 一致 skip（不重新上传）/ 有差异 deploy（带文件级明细）
+     * - gateway：planRoutes 对比云端路由 → create / update / skip（含变更字段明细）
+     * 云端查询失败时降级为保守判定（全 create），不影响 dry-run 展示。
+     */
+    private buildPlan;
+    /**
+     * 按资源类型构建计划（拆分自 buildPlan，控制圈复杂度）
+     */
+    private buildPlanForType;
+    /**
+     * database 计划：preview 聚合成单条资源级计划项
+     */
+    private buildDatabasePlan;
+    /**
+     * app 计划：本地 state 配置一致 → skip；否则按云端存在性 → create / update
+     */
+    private buildAppPlan;
+    /**
+     * hosting 计划：本地 state 指纹 diff → 一致 skip / 有差异 deploy（带文件级明细）
+     */
+    private buildHostingPlans;
+    /**
+     * gateway 计划：planRoutes 对比云端路由 → create / update / skip（含变更字段明细）
+     */
+    private buildGatewayPlans;
+    /**
+     * 查询环境中已存在的函数名集合（查询失败返回空集，降级为全新建判定）
+     */
+    private listExistingFunctionNames;
+    /**
+     * 判断云应用是否已存在（查询失败返回 false，降级为新建判定）
+     */
+    private appExists;
+    /**
+     * 执行单个计划步骤
+     */
+    private executeStep;
+    /** 深比较（JSON 快照语义）：仅用于 app 配置快照等简单对象 */
+    private deepEqual;
+    /** app 配置差异明细（from → to） */
+    private appConfigChanges;
+    /**
+     * 轻量 inline 守卫：配置合法 + 目录存在（validateProject 接线点）
+     */
+    private guardConfig;
+}

package/types/deploy/FunctionDeployer.d.ts

@@ -0,0 +1,158 @@
+import { Environment } from '../environment';
+import { ICloudBuildService } from './function/builders/cloud';
+import { IImagePreflightDeps } from './function/image-preflight';
+import { ICheckReport, IFunctionDeployConfig, IFunctionDeployOptions, IFunctionDeployPlan, IFunctionDeployResult, INormalizedDeployConfig } from './types';
+interface ILegacyFunctionDeployResult {
+    name: string;
+    url?: string;
+}
+/**
+ * 函数部署编排器
+ *
+ * 统一编排 Event 与 HTTP 函数的部署流程，对上层屏蔽以下差异：
+ * - Event 与 HTTP 的运行模型
+ * - zip、cloud、local、image 四种构建策略
+ * - 创建、更新与需要删除重建的场景
+ *
+ * 已支持代码包、已有镜像、云端构建、本地构建、匿名访问与网关路径收敛；
+ * 未实现能力（replace 删除重建、local 企业版 TCR）会显式报错，不会静默跳过。
+ */
+export declare class FunctionDeployer {
+    private readonly environment;
+    private readonly functionService;
+    /** 镜像远端校验依赖，默认真实 docker；测试可注入以避免真实网络/命令 */
+    private readonly imagePreflightDeps?;
+    /**
+     * 云端构建能力工厂，默认基于 CloudAppService 构造真实实现；
+     * 测试可注入以替换打包/网络/tcb API，避免真实 IO
+     */
+    private readonly cloudBuildServiceFactory;
+    constructor(environment: Environment, deps?: {
+        imagePreflightDeps?: IImagePreflightDeps;
+        cloudBuildServiceFactory?: () => ICloudBuildService;
+    });
+    /**
+     * 兼容既有声明式部署入口
+     *
+     * 该方法只负责补齐声明式上下文并委托 deployFunction，避免继续维护第二套
+     * cloud/local/image 分发逻辑。force 在旧入口中表示允许覆盖，计划阶段会自行
+     * 判断 create/update；涉及删除重建时仍要求显式审批，不将 force 等同 allowReplace。
+     */
+    deploy(options: {
+        func: IFunctionDeployConfig;
+        functionRootPath?: string;
+        /** 直接指定函数代码目录（优先于 functionRootPath/name 拼接），对齐 CLI resolveFunctionPath 的 dir 语义 */
+        functionPath?: string;
+        force?: boolean;
+    }): Promise<ILegacyFunctionDeployResult>;
+    /** 解析最终部署策略：显式 buildStrategy 优先，未配置默认 zip */
+    resolveStrategy(config: IFunctionDeployConfig): IFunctionDeployPlan['buildStrategy'];
+    /**
+     * 配置 HTTP 函数匿名访问（public=true）
+     * 通过 OPA Rego 策略追加匿名放通规则，不覆盖用户已有策略
+     */
+    ensurePublicAccess(functionName: string): Promise<void>;
+    /**
+     * 收敛 HTTP 函数网关路由（gatewayPath 配置）
+     *
+     * 幂等：云端不存在该 path → 创建；已存在且一致 → 跳过；不一致 → 更新。
+     * 复用 GatewayDeployer 的幂等收敛与默认域名解析逻辑，与 gateway.routes 声明式部署行为一致。
+     * 返回该函数网关访问 URL（与 resolveUrl 解析结果一致），无 envId 时返回 undefined。
+     */
+    ensureGatewayRoute(config: INormalizedDeployConfig): Promise<string | undefined>;
+    /** 生成匿名访问 OPA Rego 规则 */
+    buildPublicAccessRego(functionName: string): string;
+    /** 生成 HTTP 函数可访问 URL */
+    resolveUrl(config: IFunctionDeployConfig): Promise<string | undefined>;
+    /**
+     * 校验部署配置
+     *
+     * 只做纯函数、无 IO 的配置契约校验，一次返回全部问题
+     */
+    checkConfig(config: IFunctionDeployConfig): ICheckReport;
+    /**
+     * 生成部署计划
+     *
+     * 会查询线上函数状态，用于判断创建、更新或删除重建
+     */
+    plan(config: IFunctionDeployConfig): Promise<IFunctionDeployPlan>;
+    /**
+     * 部署前本地环境检查（有 IO）
+     *
+     * 与 checkConfig 不同，本方法会读取文件系统，目前覆盖 HTTP 代码包所需的
+     * scf_bootstrap 等文件条件。先做配置契约校验，再执行本地检查。
+     */
+    preflight(config: IFunctionDeployConfig): ICheckReport;
+    /**
+     * 部署函数
+     * @param config 部署配置
+     * @param options 部署选项，dryRun 时只生成计划不做任何变更
+     */
+    deployFunction(config: IFunctionDeployConfig, options?: IFunctionDeployOptions): Promise<IFunctionDeployResult>;
+    /**
+     * 将既有声明式调用补齐为完整部署配置
+     */
+    private withLegacyDeployContext;
+    /**
+     * 解析函数部署地域，供镜像远端地域校验使用
+     *
+     * 地域来源于 environment 的鉴权配置；未显式配置时返回 undefined，
+     * 由image-preflight 自动跳过地域校验，不误报。
+     */
+    private resolveDeployRegion;
+    /**
+     * 构造镜像拉取授权 Preflight 所需的 CAM 适配器
+     *
+     * 用 CommonService 走 CAM 通道：ListAttachedRolePolicies 读已绑策略、
+     * AttachRolePolicies 按策略名绑定。任何权限/网络错误都原样抛出，
+     * 交由 cam-preflight 判定并降级，本层不吞异常。
+     */
+    private createCamPreflightAdapter;
+    /** 查询线上函数详情，不存在时返回 null */
+    private getCurrentFunction;
+    /** 判断是否为函数不存在错误，其他错误必须继续抛出 */
+    private isFunctionNotFoundError;
+    /**
+     * 校验 Preflight 报告，存在 fail 项时聚合抛错
+     */
+    private assertPreflightReady;
+    /**
+     * 判断计划是否可以在当前实现范围内执行
+     *
+     * 未实现的能力必须显式报错，避免用户误认为访问规则或镜像构建已经生效
+     */
+    private assertPlanExecutable;
+    /**
+     * 准备部署物
+     *
+     * cloud 策略在云端构建容器内build+push，产出镜像部署物（不依赖本地 Docker）；
+     * local 策略需要先做 Docker 本地能力检查，再本地构建并推送镜像，产出镜像部署物；
+     * 其余策略走同步的 pack。
+     */
+    private prepareArtifact;
+    /** 生成部署物 */
+    private createArtifact;
+    /** 执行部署计划 */
+    private applyPlan;
+    /** 收敛 HTTP 函数访问配置（匿名访问 + 网关路由） */
+    private applyAccessPlan;
+    /** 执行单个步骤并记录耗时与进度 */
+    private runStep;
+    /** 上报进度，回调异常不影响部署流程 */
+    private emitProgress;
+    /** 汇总部署结果 */
+    private buildResult;
+    private emitProgressDone;
+}
+export * from './types';
+export { assertDeployConfig, checkDeployConfig, isCustomImageRuntime, normalizeDeployConfig, normalizeGatewayPath, parseImageReference } from './function/config-guard';
+export { createDeployPlan, toCurrentState } from './function/planner';
+export { createCodeArtifact, createImageArtifactFromConfig, toCloudFunction } from './function/artifact';
+export { buildImageOnCloud } from './function/builders/cloud';
+export type { ICloudBuildService, ICloudBuildResult, ICloudCosInfo, ICloudCreateBuildInput, ICloudCreateBuildResult, ICloudVersionStatus } from './function/builders/cloud';
+export { createCloudBuildService } from './function/cloud-build-service';
+export { runLocalPreflight } from './function/preflight';
+export { runImageRemotePreflight } from './function/image-preflight';
+export type { IImagePreflightDeps } from './function/image-preflight';
+export { runImagePullAuthPreflight, isCamPermissionError, SCF_PULL_IMAGE_ROLE, REQUIRED_IMAGE_PULL_POLICY, IMAGE_PULL_GRANT_URL } from './function/cam-preflight';
+export type { ICamPreflightService } from './function/cam-preflight';

package/types/deploy/GatewayDeployer.d.ts

@@ -0,0 +1,175 @@
+import { Environment } from '../environment';
+import { HTTPServiceRouteParam } from '../env/type';
+/** 网关路由配置（cloudbaserc.json gateway.routes[]） */
+export interface IGatewayRoute {
+    /** 绑定的自定义域名。配置时自动绑定（需 certId）；不填则使用环境 HTTP 访问服务的默认域名（如 {envId}-{uin}.{region}.app.tcloudbase.com） */
+    domain?: string;
+    /** SSL 证书 ID（绑定自定义域名时需要，可先通过 SSL 控制台/API 获取） */
+    certId?: string;
+    /** 域名接入方式（默认 DIRECT 直接接入）：DIRECT/CDN（接入云开发 CDN）/CUSTOM（自定义接入，需 customCname）/EO（接入云开发 EdgeOne） */
+    accessType?: 'DIRECT' | 'CDN' | 'CUSTOM' | 'EO';
+    /** 自定义接入时配置的 CNAME 记录（accessType=CUSTOM 时必填） */
+    customCname?: string;
+    /** 域名协议（默认 HTTP_AND_HTTPS）：HTTP/HTTPS/HTTP_AND_HTTPS/HTTP_TO_HTTPS/HTTPS_TO_HTTP */
+    protocol?: 'HTTP' | 'HTTPS' | 'HTTP_AND_HTTPS' | 'HTTP_TO_HTTPS' | 'HTTPS_TO_HTTP';
+    /** 域名启用状态（默认 true） */
+    enable?: boolean;
+    /** 路径，如 /api 或 /web */
+    path: string;
+    /** 目标：function:<name> 或 hosting:<name> */
+    target: string;
+    /** 是否开启路径透传（默认 false） */
+    enablePathTransmission?: boolean;
+    /** 是否开启身份认证（默认 false） */
+    enableAuth?: boolean;
+    /** 路径重写配置（prefix/staticStorePrefix 只能填一个）。hosting 路由未配置时自动生成 { Prefix: deployPath }；显式配置时透传且不校验 hosting 名称（可引用已部署实例） */
+    pathRewrite?: {
+        prefix?: string;
+        staticStorePrefix?: string;
+    };
+    /** QPS 限频策略 */
+    qpsPolicy?: {
+        /** QPS 限额总量（每秒请求次数），100-100000 */
+        qpsTotal?: number;
+        /** 客户端限频配置 */
+        qpsPerClient?: {
+            limitBy?: 'UserID' | 'ClientIP';
+            limitValue?: number;
+        };
+    };
+}
+/** 网关部署结果 */
+export interface IGatewayDeployResult {
+    domain: string;
+    routes: Array<{
+        path: string;
+        target: string;
+        url: string;
+    }>;
+}
+/**
+ * 网关声明式部署器
+ * 支持 function:<name>（SCF 云函数）与 hosting:<name>（STATIC_STORE 静态托管）两种目标
+ */
+export declare class GatewayDeployer {
+    private environment;
+    constructor(environment: Environment);
+    /**
+     * 部署网关路由
+     *
+     * 域名规则：
+     * - 未配置 domain → 使用环境 HTTP 访问服务的**默认域名**（Domains 中 IsDefault=true，如 {envId}-{uin}.{region}.app.tcloudbase.com），直接创建路由
+     * - 配置了 domain（自定义域名）→ **先自动绑定自定义域名**（bindCustomDomain，需 certId），再创建路由
+     * 不同域名的路由分组创建。
+     */
+    deploy(options: {
+        routes: IGatewayRoute[];
+        envId: string;
+        /** hosting 配置列表（用于为 hosting:<name> 路由生成 PathRewrite.Prefix 部署路径） */
+        hostings?: Array<{
+            name?: string;
+            deployPath?: string;
+        }>;
+    }): Promise<IGatewayDeployResult>;
+    /**
+     * 解析路由配置：校验 target 格式并映射为 HTTPServiceRouteParam
+     *
+     * 对齐 tcb routes add 的底层校验（src/commands/routes/add.ts）：
+     * - path 必须以 / 开头，每段只含字母/数字/./_/-，50 字符内，不支持通配符 *
+     * - 静态托管（STATIC_STORE）上游名固定为 staticstore，且只支持一级路径
+     */
+    parseRoute(route: IGatewayRoute): HTTPServiceRouteParam;
+    /**
+     * 计算网关路由部署计划（dry-run）：每个路由 create/update/skip + 变更字段明细
+     *
+     * 判定逻辑与 deploy() 完全一致：云端不存在的 path → create；
+     * 已存在但显式配置不一致 → update（带 changes）；一致 → skip。
+     */
+    planRoutes(options: {
+        routes: IGatewayRoute[];
+        envId: string;
+        hostings?: Array<{
+            name?: string;
+            deployPath?: string;
+        }>;
+    }): Promise<Array<{
+        path: string;
+        target: string;
+        status: 'create' | 'update' | 'skip';
+        changes?: Array<{
+            field: string;
+            from?: string;
+            to?: string;
+        }>;
+    }>>;
+    /**
+     * 查询指定域名下已存在的路由（幂等收敛用），返回 Map<path, 云端路由详情>
+     */
+    private getExistingRoutes;
+    /**
+     * 判断期望路由与云端已存在路由是否一致
+     *
+     * 只比较**用户显式声明的字段**（enableAuth/enablePathTransmission 显式配置才比较；
+     * QPSPolicy/PathRewrite 本地有值才比较），避免覆盖控制台单独配置的字段。
+     */
+    private routesEqual;
+    /**
+     * 构建 modifyHttpServiceRoute 的路由参数：只包含基础字段 + 用户显式声明的配置字段
+     */
+    private buildModifyParam;
+    private deepEqual;
+    /**
+     * 自动绑定自定义域名（幂等，支持证书更新）
+     *
+     * certId 解析优先级：
+     * 1. 显式配置的 certId 优先（未配置时按域名自动匹配已签发证书）
+     * 2. 域名已绑定 + 未显式 certId 或与云端一致 → 跳过绑定（幂等）
+     * 3. 域名已绑定 + 显式 certId 与云端不一致 → 重新绑定（更新证书）
+     * 4. 未绑定且无法确定 certId → 明确报错并给出操作指引
+     */
+    private ensureDomainBound;
+    /**
+     * 查询当前环境已绑定的自定义域名列表（含证书 ID，用于幂等跳过与证书更新判断）
+     */
+    private getBoundDomains;
+    /**
+     * 按域名自动匹配 SSL 证书 ID（腾讯云 ssl.DescribeCertificates）
+     *
+     * 匹配规则（按返回顺序取第一个）：
+     * - 证书状态为已签发（Status === 1）
+     * - 证书主域名（Domain）或关联域名（SubjectAltName）包含目标域名
+     * - 证书未过期（CertEndTime 晚于当前时间）
+     * 查询失败或无匹配返回 null（由调用方给出明确报错）
+     */
+    private resolveCertIdByDomain;
+    /**
+     * 解析路由（含异步函数类型判断 + hosting 路径重写）
+     *
+     * - function 目标：查询函数详情，HTTP 类型函数 → WEB_SCF（Web 云函数），普通函数 → SCF。
+     *   与 tcb fn deploy 部署 HTTP 函数后控制台创建路由的行为一致（控制台请求中 UpstreamResourceType=WEB_SCF）。
+     * - hosting 目标：自动生成 PathRewrite.Prefix = 对应 hosting 配置的 deployPath（控制台行为：静态托管路由必带
+     *   PathRewrite.Prefix，将 /路由 前缀重写到静态托管的实际部署路径，否则请求会打到存储根路径导致 404）。
+     */
+    private parseRouteWithType;
+    /**
+     * 映射用户 pathRewrite（camelCase）为 API 格式 HTTPServicePathRewrite（PascalCase）
+     */
+    private mapPathRewrite;
+    /**
+     * 生成路由变更字段明细（与 routesEqual 的判定字段一致）
+     */
+    private routeChanges;
+    /**
+     * 解析环境 HTTP 访问服务的默认域名
+     *
+     * 域名优先级：
+     * 1. Domains 列表中 DomainType=HTTPSERVICE 且 IsDefault=true 的域名（HTTP 网关默认域名）
+     *    —— 注意：AI_AGENT/CBR 等类型的域名（如 agt-xxx.agent.tcloudbase.com）也可能 IsDefault=true，
+     *       但它们不是 HTTP 网关默认域名，必须结合 DomainType 过滤
+     * 2. 通过 DescribeEnvInfo 构造的默认域名 `{envId}-{uin}.{region}.app.tcloudbase.com`（兜底，覆盖 Domains 列表为空的场景——实测部分环境下 Domains 列表为空但默认域名仍存在）
+     * 3. 首个 DomainType=HTTPSERVICE 的域名
+     * 4. OriginDomain —— 回源域名（供自定义 CDN/WAF 回源使用，非对外访问地址），仅作最后兜底
+     * 查询失败或域名缺失时**明确报错**，不使用猜测的兜底域名（避免 INVALID_HOST）。
+     */
+    private resolveDomain;
+}