openxiangda-devkit-core 2.0.0-alpha.98 → 2.1.0

package/dist/application-services.js

@@ -1,8 +1,14 @@
-import { spawnSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
+import { publishedDeliverySource, assertDeliverySourceUnchanged, DeliverySourceError } from './delivery-source.js';
+import { operationStage, skippedOperationStage, updateOperationStage } from './operation-progress.js';
+import { deliveryInputDigest, reusableValidation, recordValidation, recordSealedCandidate, reusableSealedCandidate } from './delivery-cache.js';
+import { developmentLifecycle, summarizeLifecycle, lifecycleAtCommit, verifyBusinessAcceptance } from './development-lifecycle.js';
+import { runCommandProcess } from './command-process.js';
+import { compileLocalConfiguration } from './configuration-preflight.js';
+import { NativeConfigurationCompilerError, NATIVE_CONFIGURATION_VALIDATOR_DIGEST } from 'openxiangda-contracts/native-compiler';
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync, } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
-import { CONFIGURATION_COMPATIBILITY_CAPABILITY, CURRENT_APPLICATION_CONTRACT, OPENXIANGDA_CONTRACT_VERSION, SCHEMA_VERSIONS, canonicalJson, sha256Digest, } from "openxiangda-contracts";
+import { CONFIGURATION_COMPATIBILITY_CAPABILITY, CURRENT_APPLICATION_CONTRACT, OPENXIANGDA_CONTRACT_VERSION, SCHEMA_VERSIONS, RUNTIME_CAPACITY_PREFLIGHT_SCHEMA, canonicalJson, sha256Digest, } from "openxiangda-contracts";
 import { compileApplicationSources, compileAppPackage, requiredPlatformCapabilities, backendRuntimeRequired, renderAdminNavigationSuggestion, sha256Bytes, validateAppConfig, } from "./compiler/index.js";
 import { OpenXiangdaControlPlaneClient, ControlPlaneError, } from "./control-plane-client.js";
 import { normalizePlatformBaseUrl, OpenXiangdaDeveloperSession, } from "./session.js";
@@ -10,6 +16,9 @@ import { runConnectedDevelopment, selectConnectedDevelopmentEnvironment, } from
 import { backendImageBuildTarget, publishBackendImage, } from "./backend-image-build.js";
 import { OPENXIANGDA_TOOLCHAIN_VERSION } from "./version.js";
 import { git, loadWorkspace, } from "./workspace-loader.js";
+import { validateApplicationUiContract } from './application-ui-contract.js';
+import { initializeOptionalBackend } from './optional-backend.js';
+import { buildPermissionReview } from './compiler/permission-review.js';
 import { validateNestInjectionContract } from "./nest-injection-contract.js";
 import { collectWorkspaceToolchainDependencies, defaultDevkitCoreToolchainCapsule, ToolchainCapsuleScanLimitError, toolchainCapsuleDiagnostic, } from "./toolchain-capsule.js";
 import { advisoryAppSpecDiagnostics, closeAppSpecChange, createAppSpecCapability, createAppSpecChange, initializeAppSpec, inspectAppSpec, summarizeAppSpecContext, } from "./app-spec.js";
@@ -21,7 +30,15 @@ export class OpenXiangdaApplicationServices {
     }
     async workspaceContext(root) {
         const workspace = await this.workspace(root);
-        return this.ok("workspace.context", workspace.context.workspace, workspace.context);
+        const lifecycle = developmentLifecycle(workspace.root, this.appSpecContractIndex(workspace, true));
+        return this.ok("workspace.context", workspace.context.workspace, { ...workspace.context, development: {
+                ...summarizeLifecycle(lifecycle),
+                application: lifecycle.context.application ? { path: lifecycle.context.application.path, content: lifecycle.context.application.content } : null,
+                records: [
+                    ...lifecycle.context.index.capabilities, ...lifecycle.context.index.activeChanges,
+                    ...lifecycle.context.index.decisions, ...lifecycle.context.index.designs, ...lifecycle.context.index.history,
+                ].map(({ id, title, status, path, kind }) => ({ id, title, status, path, kind })),
+            } });
     }
     async appSpecInit(root) {
         const workspace = await this.workspace(root);
@@ -74,15 +91,16 @@ export class OpenXiangdaApplicationServices {
             },
         ]);
     }
-    async appSpecContext(root, selector) {
+    async appSpecContext(root, selector, historyOffset = 0) {
         const workspace = await this.workspace(root);
-        const context = inspectAppSpec(workspace.root, this.appSpecContractIndex(workspace, true), selector);
-        return this.result("spec.context", workspace.context.workspace, context, advisoryAppSpecDiagnostics(context.diagnostics));
+        const context = inspectAppSpec(workspace.root, this.appSpecContractIndex(workspace, true), selector, historyOffset);
+        return this.result("spec.context", workspace.context.workspace, { ...context, lifecycle: summarizeLifecycle(developmentLifecycle(workspace.root, this.appSpecContractIndex(workspace, true), undefined, selector)) }, advisoryAppSpecDiagnostics(context.diagnostics));
     }
     async appSpecCheck(root) {
         const workspace = await this.workspace(root);
         const context = inspectAppSpec(workspace.root, this.appSpecContractIndex(workspace, true));
-        return this.result("spec.check", workspace.context.workspace, context, context.diagnostics, [
+        const lifecycle = developmentLifecycle(workspace.root, this.appSpecContractIndex(workspace, true));
+        return this.result("spec.check", workspace.context.workspace, { ...context, lifecycle: summarizeLifecycle(lifecycle) }, lifecycle.diagnostics, [
             {
                 code: "check",
                 label: "继续运行应用检查",
@@ -90,6 +108,13 @@ export class OpenXiangdaApplicationServices {
             },
         ]);
     }
+    async appSpecVerify(root, deploymentId, evidencePath) {
+        const workspace = await this.workspace(root);
+        const run = await (await this.client(workspace.root)).deployment(workspace.config.app.code, deploymentId);
+        const lifecycle = developmentLifecycle(workspace.root, this.appSpecContractIndex(workspace, true));
+        const verification = verifyBusinessAcceptance(workspace.root, run, lifecycle, evidencePath);
+        return this.result('spec.verify', workspace.context.workspace, verification, verification.diagnostics);
+    }
     async appSpecClose(input) {
         const workspace = await this.workspace(input.root);
         const outcome = closeAppSpecChange({
@@ -152,6 +177,7 @@ export class OpenXiangdaApplicationServices {
             aiCatalogDigest: sources.aiCatalog.digest,
             contract: sources.contracts.value,
             aiCatalog: sources.aiCatalog.value,
+            permissionReview: buildPermissionReview(sources.config.value, sources.contracts.value),
             adminNavigationAuthoring: {
                 schemaVersion: "openxiangda.admin-navigation-authoring/v1",
                 owner: "application",
@@ -176,11 +202,70 @@ export class OpenXiangdaApplicationServices {
             },
         });
     }
+    async contractContext(root, input = {}) {
+        const result = await this.contractDescribe(root);
+        const data = result.data;
+        const groups = {
+            resource: data.contract.resources,
+            operation: data.contract.operations,
+            workflow: data.contract.workflows,
+            route: data.contract.routes,
+            capability: data.aiCatalog.capabilities,
+        };
+        const entries = Object.entries(groups).flatMap(([kind, values]) => values.map(value => ({
+            selector: `${kind}:${String(value.code || value.resourceCode || value.id)}`,
+            kind, code: String(value.code || value.resourceCode || value.id),
+            title: String(value.name || value.label || value.title || value.code || value.resourceCode || value.id),
+            value,
+        })));
+        const selector = input.selector || 'index';
+        const offset = input.offset ?? 0;
+        const limit = input.limit ?? 30;
+        if (!Number.isSafeInteger(offset) || offset < 0 || !Number.isSafeInteger(limit) || limit < 1 || limit > 100) {
+            throw new Error('CONTRACT_SELECTION_INVALID: offset 必须为非负整数，limit 必须在 1 到 100 之间');
+        }
+        let selection;
+        if (selector === 'index')
+            selection = {
+                total: entries.length, offset, limit, nextOffset: offset + limit < entries.length ? offset + limit : null,
+                sections: ['navigation', 'permissions', 'all'],
+                entries: entries.slice(offset, offset + limit).map(({ value: _, ...entry }) => entry),
+            };
+        else if (selector === 'navigation')
+            selection = { adminNavigationAuthoring: data.adminNavigationAuthoring };
+        else if (selector === 'permissions')
+            selection = { permissionReview: data.permissionReview };
+        else if (selector === 'all')
+            selection = data;
+        else {
+            const entry = entries.find(item => item.selector === selector);
+            if (!entry)
+                throw new Error(`CONTRACT_SELECTION_NOT_FOUND: 未知契约选择器 ${selector}，先读取 index`);
+            selection = entry.value;
+        }
+        if (Buffer.byteLength(JSON.stringify(selection)) > 256 * 1024)
+            throw new Error('CONTRACT_SELECTION_TOO_LARGE: 选择结果超过 256 KiB，请按模型或能力读取');
+        return { ...result, data: { configDigest: data.configDigest, contractDigest: data.contractDigest, aiCatalogDigest: data.aiCatalogDigest, counts: data.counts, selector, selection } };
+    }
     async platformCapabilities(root) {
         const workspace = await this.workspace(root);
         const capabilities = await (await this.client(workspace.root)).capabilities();
         return this.ok("platform.capabilities", workspace.context.workspace, capabilities);
     }
+    async administrationContext(root, environmentKey = "preproduction") {
+        const workspace = await this.workspace(root);
+        const environment = this.deploymentEnvironment(environmentKey);
+        const client = await this.client(workspace.root);
+        return this.ok("admin.context", workspace.context.workspace, await client.applicationAdministrationContext(workspace.config.app.code, environment));
+    }
+    async workflowNodeConfigurations(root, workflowCode, environmentKey = "preproduction") {
+        const workspace = await this.workspace(root);
+        const environment = this.deploymentEnvironment(environmentKey);
+        if (!workflowCode || workflowCode.length > 128)
+            throw new Error("WORKFLOW_CODE_REQUIRED");
+        const client = await this.client(workspace.root);
+        return this.ok("admin.workflow", workspace.context.workspace, await client.workflowNodeConfigurations(workspace.config.app.code, workflowCode, environment));
+    }
     async provisionApplication(root) {
         const workspace = await this.workspace(root);
         const capsuleDiagnostics = this.toolchainDiagnostics(workspace);
@@ -512,11 +597,14 @@ export class OpenXiangdaApplicationServices {
     async check(root, environmentKey) {
         const workspace = await this.workspace(root);
         const appSpec = inspectAppSpec(workspace.root, this.appSpecContractIndex(workspace, false));
+        const lifecycle = developmentLifecycle(workspace.root, this.appSpecContractIndex(workspace, false));
         const diagnostics = [
             ...validateAppConfig(workspace.config),
             ...this.versionTrainDiagnostics(workspace),
             ...validateNestInjectionContract(workspace.root),
+            ...validateApplicationUiContract(workspace.root, workspace.config.frontend.root),
             ...advisoryAppSpecDiagnostics(appSpec.diagnostics),
+            ...advisoryAppSpecDiagnostics(lifecycle.diagnostics),
         ];
         if (diagnostics.some(item => item.severity === "error")) {
             const sealedArtifact = this.writeCheckSealedArtifactStatus(workspace, false);
@@ -525,10 +613,28 @@ export class OpenXiangdaApplicationServices {
                 compatibility: null,
                 stages: [],
                 sealedArtifact,
-                appSpec: summarizeAppSpecContext(appSpec),
+                appSpec: { ...summarizeAppSpecContext(appSpec), lifecycle: summarizeLifecycle(lifecycle) },
             }, diagnostics);
         }
-        const generated = await this.generate({ root: workspace.root });
+        let compatibility = null;
+        try {
+            const local = await operationStage('local-configuration', '本地完整配置校验', async () => compileLocalConfiguration(workspace.config, this.toolchainVersion));
+            if (environmentKey) {
+                compatibility = await operationStage('target-preflight', '目标平台只读预检', () => this.validateTargetConfigurationCompatibility(workspace, environmentKey, local));
+            }
+        }
+        catch (error) {
+            diagnostics.push(this.configurationCompatibilityDiagnostic(error));
+            const sealedArtifact = this.writeCheckSealedArtifactStatus(workspace, false);
+            return this.result("check", workspace.context.workspace, {
+                generated: undefined,
+                compatibility: null,
+                stages: [],
+                sealedArtifact,
+                appSpec: { ...summarizeAppSpecContext(appSpec), lifecycle: summarizeLifecycle(lifecycle) },
+            }, diagnostics);
+        }
+        const generated = await operationStage('generate', '生成应用契约', () => this.generate({ root: workspace.root }));
         diagnostics.push(...generated.diagnostics);
         if (!generated.ok) {
             const sealedArtifact = this.writeCheckSealedArtifactStatus(workspace, false);
@@ -537,34 +643,45 @@ export class OpenXiangdaApplicationServices {
                 compatibility: null,
                 stages: [],
                 sealedArtifact,
-                appSpec: summarizeAppSpecContext(appSpec),
+                appSpec: { ...summarizeAppSpecContext(appSpec), lifecycle: summarizeLifecycle(lifecycle) },
             }, diagnostics, generated.nextActions);
         }
-        let compatibility = null;
-        if (environmentKey) {
-            try {
-                compatibility = await this.validateTargetConfigurationCompatibility(workspace, environmentKey);
+        const backendDiagnostics = this.initializeBackend(workspace);
+        if (backendDiagnostics.length) {
+            return this.result("check", workspace.context.workspace, undefined, backendDiagnostics);
+        }
+        const stages = [];
+        const cache = this.deliveryCacheContext(workspace);
+        const inputDigest = deliveryInputDigest(cache);
+        const reusable = reusableValidation(cache, inputDigest);
+        for (const name of ["check", "test", "build"]) {
+            if (reusable) {
+                await operationStage(name, `${this.packageScriptLabel(name)}（复用已验证结果）`, async () => {
+                    updateOperationStage(name, `${this.packageScriptLabel(name)}（复用已验证结果）`, { reused: true, inputDigest, outputDigest: reusable.outputDigest });
+                });
+                stages.push({ name, state: 'passed', ok: true, exitCode: 0, output: '输入与构建输出摘要未变，复用已通过的本地检查', reused: true });
+                continue;
             }
-            catch (error) {
-                diagnostics.push(this.configurationCompatibilityDiagnostic(error));
-                const sealedArtifact = this.writeCheckSealedArtifactStatus(workspace, false);
-                return this.result("check", workspace.context.workspace, {
-                    generated: generated.data,
-                    compatibility: null,
-                    stages: [],
-                    sealedArtifact,
-                    appSpec: summarizeAppSpecContext(appSpec),
-                }, diagnostics);
+            if (stages.some(stage => stage.state === 'failed')) {
+                stages.push({ name, state: 'skipped', ok: false, exitCode: null, output: '前置阶段失败，未执行' });
+                skippedOperationStage(name, this.packageScriptLabel(name));
+                continue;
             }
+            const result = await this.runPackageScript(workspace.root, name);
+            stages.push({ name, ...result, state: result.ok ? 'passed' : 'failed' });
         }
-        const stages = ["check", "test", "build"].map(name => ({
-            name,
-            ...this.runPackageScript(workspace.root, name),
-        }));
-        for (const stage of stages.filter(item => !item.ok)) {
+        for (const stage of stages.filter(item => item.state === 'failed')) {
             const code = `WORKSPACE_${stage.name.toUpperCase()}_FAILED`;
             diagnostics.push(this.diagnostic(code, `工作区 ${stage.name} 脚本失败`, `package.json#scripts.${stage.name}`, "修复失败后重新运行 openxiangda check", { output: stage.output }));
         }
+        if (!reusable && stages.every(stage => stage.state === 'passed')) {
+            try {
+                recordValidation(cache, inputDigest);
+            }
+            catch (error) {
+                diagnostics.push(this.diagnostic('OPENXIANGDA_VALIDATION_INPUT_CHANGED', error.message, 'workspace', '等待源码修改结束后重新运行 openxiangda check'));
+            }
+        }
         const passed = !diagnostics.some(item => item.severity === "error");
         const sealedArtifact = this.writeCheckSealedArtifactStatus(workspace, passed);
         return this.result("check", workspace.context.workspace, {
@@ -572,7 +689,7 @@ export class OpenXiangdaApplicationServices {
             compatibility,
             stages,
             sealedArtifact,
-            appSpec: summarizeAppSpecContext(appSpec),
+            appSpec: { ...summarizeAppSpecContext(appSpec), lifecycle: summarizeLifecycle(lifecycle) },
         }, diagnostics, passed
             ? [
                 {
@@ -589,7 +706,7 @@ export class OpenXiangdaApplicationServices {
         if (diagnostics.length > 0) {
             return this.result("test", workspace.context.workspace, undefined, diagnostics);
         }
-        const command = this.runPackageScript(workspace.root, "test");
+        const command = await this.runPackageScript(workspace.root, "test");
         const commandDiagnostics = command.ok
             ? []
             : [
@@ -635,7 +752,11 @@ export class OpenXiangdaApplicationServices {
             return this.result("build", workspace.context.workspace, undefined, generated.diagnostics, generated.nextActions);
         }
         if (!input.skipWorkspaceBuild) {
-            const command = this.runPackageScript(workspace.root, "build");
+            const backendDiagnostics = this.initializeBackend(workspace);
+            if (backendDiagnostics.length) {
+                return this.result("build", workspace.context.workspace, undefined, backendDiagnostics);
+            }
+            const command = await this.runPackageScript(workspace.root, "build");
             if (!command.ok) {
                 diagnostics.push(this.diagnostic("WORKSPACE_BUILD_FAILED", "前后端生产构建失败", "package.json#scripts.build", "修复构建错误后重试", { output: command.output }));
                 return this.result("build", workspace.context.workspace, undefined, diagnostics);
@@ -755,13 +876,22 @@ export class OpenXiangdaApplicationServices {
         if (diagnostics.length > 0) {
             return this.result("deployment.plan", workspace.context.workspace, undefined, diagnostics);
         }
+        const source = await operationStage('source', '核对远端主线与源码', () => publishedDeliverySource(workspace.root));
+        const lifecycle = developmentLifecycle(workspace.root, this.appSpecContractIndex(workspace, true));
+        if (!lifecycle.readyForTest)
+            return this.result('deployment.plan', workspace.context.workspace, { lifecycle: summarizeLifecycle(lifecycle) }, lifecycle.diagnostics);
         const sources = compileApplicationSources(workspace.config, this.toolchainVersion);
+        const client = await this.client(workspace.root);
+        const candidate = await reusableSealedCandidate(this.deliveryCacheContext(workspace), source);
+        const runtimeCapacity = await this.runtimeCapacityPlan(workspace, client, await client.capabilities(), input, candidate?.package.digest);
         return this.ok("deployment.plan", workspace.context.workspace, {
+            runtimeCapacity,
             environment: input.environment,
             appCode: workspace.config.app.code,
             sealed: false,
             packageDigest: null,
             buildOwner: "openxiangda deploy",
+            source,
             frontendRoot: workspace.config.frontend.root,
             backendRoot: workspace.config.backend.root,
             configDigest: sources.config.digest,
@@ -779,6 +909,7 @@ export class OpenXiangdaApplicationServices {
                 this.diagnostic("DEPLOY_PREPRODUCTION_ONLY", "Native 2.0 只允许直接部署到预发环境", String(input.environment), "使用 openxiangda deploy；生产环境必须显式复用成功的测试 DeploymentRun"),
             ]);
         }
+        const source = await operationStage('source', '核对远端主线与源码', () => publishedDeliverySource(workspace.root));
         const client = await this.client(workspace.root);
         const capabilities = await client.capabilities();
         const sources = compileApplicationSources(workspace.config, this.toolchainVersion);
@@ -791,41 +922,78 @@ export class OpenXiangdaApplicationServices {
         });
         assertRequiredCapabilitiesAvailable(capabilities, requiredPlatformCapabilities(workspace.config));
         const hasBackend = backendRuntimeRequired(workspace.config);
-        const target = !hasBackend || input.backendImage
-            ? undefined
-            : backendImageBuildTarget(capabilities, workspace.config.app.code);
+        const cache = this.deliveryCacheContext(workspace);
+        const capacityCandidate = await reusableSealedCandidate(cache, source, input.backendImage);
+        const runtimeCapacity = await this.runtimeCapacityPlan(workspace, client, capabilities, input, capacityCandidate?.package.digest);
+        if (runtimeCapacity.sufficient === false) {
+            throw new ControlPlaneError(409, 'APPLICATION_V2_RUNTIME_QUOTA_INSUFFICIENT', '应用运行资源不足，已在检查脚本与镜像构建前停止；请释放闲置后端或调整平台配额后重试', runtimeCapacity.capacity);
+        }
+        const generated = await this.generate({ root: workspace.root, check: true });
+        if (!generated.ok)
+            return { ...generated, operation: 'deploy' };
+        const lifecycle = await operationStage('development-records', '核对需求、架构与测试验收计划', async () => {
+            const lifecycle = developmentLifecycle(workspace.root, this.appSpecContractIndex(workspace, true));
+            return { ...lifecycle, ok: lifecycle.readyForTest };
+        });
+        if (!lifecycle.readyForTest)
+            return this.result('deploy', workspace.context.workspace, { lifecycle: summarizeLifecycle(lifecycle) }, lifecycle.diagnostics);
         const checked = await this.check(workspace.root, input.environment);
         if (!checked.ok)
             return { ...checked, operation: "deploy" };
-        const backendImage = hasBackend
+        await assertDeliverySourceUnchanged(workspace.root, source);
+        const preparedInputDigest = deliveryInputDigest(cache);
+        const reused = await operationStage('candidate', '核对可复用的不可变制品', async () => {
+            const candidate = await reusableSealedCandidate(cache, source, input.backendImage);
+            updateOperationStage('candidate', candidate ? '复用已验证的不可变制品' : '准备构建新制品', { reused: !!candidate, ...(candidate ? { packageDigest: candidate.package.digest } : {}) });
+            return candidate;
+        });
+        if (capacityCandidate && capacityCandidate.package.digest !== reused?.package.digest) {
+            throw new ControlPlaneError(409, 'OPENXIANGDA_RUNTIME_CAPACITY_CANDIDATE_CHANGED', '检查过程中可复用制品发生变化，请重新预检后部署');
+        }
+        const backendImage = !reused && hasBackend
             ? input.backendImage
                 ? input.backendImage
-                : (await publishBackendImage({
+                : (await operationStage('backend-image', '构建并上传后端镜像', () => publishBackendImage({
                     root: workspace.root,
                     backendRoot: workspace.config.backend.root,
-                    target: target,
+                    target: backendImageBuildTarget(capabilities, workspace.config.app.code),
+                    uploader: client,
                     ...(workspace.context.workspace.revision
                         ? { sourceRevision: workspace.context.workspace.revision }
                         : {}),
-                })).reference
+                }))).reference
             : undefined;
-        const built = await this.buildSealed({
+        await assertDeliverySourceUnchanged(workspace.root, source);
+        const built = reused ? this.ok('build', workspace.context.workspace, {
+            ...reused, sealedArtifact: this.sealedArtifactStatus(workspace, reused.package.digest, true),
+        }) : await operationStage('seal', '校验并冻结不可变制品', () => this.buildSealed({
             ...input,
             root: workspace.root,
             ...(backendImage ? { backendImage } : {}),
             skipWorkspaceBuild: true,
-        });
+        }));
         if (!built.ok || !built.data)
             return built;
+        if (preparedInputDigest && preparedInputDigest !== deliveryInputDigest(cache)) {
+            throw new DeliverySourceError('OPENXIANGDA_VALIDATION_INPUT_CHANGED', '密封期间源码、依赖或构建环境发生变化，已停止上传', '等待修改结束后重新运行 openxiangda deploy');
+        }
+        if (!reused)
+            recordSealedCandidate(cache, built.data.package);
+        const retained = await publishedDeliverySource(workspace.root, source.commit);
+        if (retained.repository !== source.repository) {
+            throw new DeliverySourceError('DELIVERY_REPOSITORY_CHANGED', '发布准备期间绑定远端发生变化', '恢复并核对原来源仓库，再发布同一候选');
+        }
+        await assertDeliverySourceUnchanged(workspace.root, source);
         const deployment = await (await import("./deployment.js")).submitAppPackage({
             client,
             capabilities,
             compiledPackage: built.data.package,
             artifactContent: built.data.artifactContent,
             environmentKind: input.environment,
+            ...(input.deploymentStrategy ? { deploymentStrategy: input.deploymentStrategy } : {}),
             ...(input.environmentId ? { environmentId: input.environmentId } : {}),
             idempotencyKey: input.idempotencyKey ||
-                `deploy:${built.data.package.digest}:${input.environment}`,
+                `deploy:${built.data.package.digest}:${input.environment}${input.deploymentStrategy === 'maintenance-replace' ? ':maintenance-replace' : ''}`,
             ...(input.requestId ? { requestId: input.requestId } : {}),
         });
         return this.ok("deploy", workspace.context.workspace, deployment, [
@@ -836,6 +1004,21 @@ export class OpenXiangdaApplicationServices {
             },
         ]);
     }
+    async runtimeCapacityPlan(workspace, client, capabilities, input, packageDigest) {
+        const result = await operationStage('runtime-capacity', '只读预检运行资源配额', () => client.runtimeCapacityPreflight(workspace.config.app.code, capabilities, {
+            schemaVersion: RUNTIME_CAPACITY_PREFLIGHT_SCHEMA,
+            ...(input.deploymentStrategy ? { deploymentStrategy: input.deploymentStrategy } : {}),
+            environmentKey: input.environment,
+            ...(input.environmentId ? { environmentId: input.environmentId } : {}),
+            backend: backendRuntimeRequired(workspace.config) ? { isolation: workspace.config.backend.isolation || 'shared', resourceProfile: workspace.config.backend.resourceProfile || 'light' } : null,
+            ...(packageDigest ? { packageDigest, idempotencyKey: input.idempotencyKey || `deploy:${packageDigest}:${input.environment}${input.deploymentStrategy === 'maintenance-replace' ? ':maintenance-replace' : ''}` } : {}),
+        }));
+        const { assertRuntimeCapacityPreflight } = await import('./deployment.js');
+        assertRuntimeCapacityPreflight(result, input.environmentId, input.deploymentStrategy);
+        if (result.basis === 'existing-run' && !packageDigest)
+            throw new ControlPlaneError(409, 'OPENXIANGDA_RUNTIME_CAPACITY_PREFLIGHT_RESULT_INVALID', '平台返回了未绑定本地候选的原运行');
+        return result;
+    }
     async deploymentStatus(root, deploymentId) {
         const workspace = await this.workspace(root);
         const client = await this.client(workspace.root);
@@ -945,6 +1128,20 @@ export class OpenXiangdaApplicationServices {
                 : []),
         ];
     }
+    async productionDeploymentPlan(root, deploymentId) {
+        const workspace = await this.workspace(root);
+        const client = await this.client(workspace.root);
+        const source = await client.deployment(workspace.config.app.code, deploymentId);
+        const appVersionId = String(source.result?.applicationVersionId || '');
+        if (!appVersionId)
+            throw new Error('DEPLOYMENT_APP_VERSION_NOT_AVAILABLE: 测试运行尚无可晋级版本');
+        const diagnostics = await this.productionPromotionDiagnostics(workspace, client, source, appVersionId);
+        return this.result('deployment.plan', workspace.context.workspace, {
+            environment: 'production', sourceDeploymentId: deploymentId, appVersionId,
+            packageDigest: source.packageDigest, sealed: true, submitted: false,
+            rebuild: false, businessAcceptance: '需要核对该测试版本的业务验收记录',
+        }, diagnostics);
+    }
     async deployProduction(root, deploymentId) {
         const workspace = await this.workspace(root);
         const capsuleDiagnostics = this.toolchainDiagnostics(workspace);
@@ -961,12 +1158,12 @@ export class OpenXiangdaApplicationServices {
         if (diagnostics.length > 0) {
             return this.result("deploy", workspace.context.workspace, undefined, diagnostics);
         }
-        const deployment = await client.promote({
+        const deployment = await operationStage('submit', '提交生产晋级', () => client.promote({
             appCode: workspace.config.app.code,
             appVersionId,
             environmentKind: environment,
             idempotencyKey: `promote:${source.packageDigest}:${environment}`,
-        });
+        }));
         return this.ok("deploy", workspace.context.workspace, deployment, [
             { code: "status", label: "查看生产部署状态", command: `openxiangda status ${deployment.id}` },
         ]);
@@ -978,15 +1175,29 @@ export class OpenXiangdaApplicationServices {
             diagnostics.push(this.diagnostic("PRODUCTION_PREPRODUCTION_RUN_REQUIRED", "生产晋级来源必须是成功的预发 DeploymentRun", "deploymentId", "等待预发部署成功，并使用该 DeploymentRun ID 晋级", { status: source.status, environment: source.environment.kind }));
             return diagnostics;
         }
-        const versions = await client.appVersions(workspace.config.app.code, 100);
-        const version = versions.items.find(item => item.id === appVersionId);
-        if (!version) {
-            return [
-                this.diagnostic("PRODUCTION_APP_VERSION_NOT_FOUND", "预发运行引用的 AppVersion 不在当前应用版本集中", "appVersionId"),
-            ];
+        let version;
+        try {
+            const capabilities = await client.capabilities();
+            const { assertApplicationContractCompatible, assertProductionPromotionPreflight } = await import('./deployment.js');
+            assertApplicationContractCompatible(capabilities, CURRENT_APPLICATION_CONTRACT);
+            version = await operationStage('promotion-preflight', '按原测试制品预检生产环境', () => client.productionPromotionPreflight(workspace.config.app.code, source.id));
+            assertProductionPromotionPreflight(version, {
+                appCode: workspace.config.app.code, sourceDeploymentId: source.id, appVersionId, packageDigest: source.packageDigest,
+            });
+            const testedLifecycle = lifecycleAtCommit(workspace.root, version.source.commit, this.appSpecContractIndex(workspace, true));
+            if (!testedLifecycle.changeId || !testedLifecycle.acceptanceIds.length) {
+                diagnostics.push(this.diagnostic('APPSPEC_TESTED_PLAN_REQUIRED', '指定测试版本缺少可追溯的需求与验收计划', 'appspec', '补齐真实记录并发布新的测试候选，再执行验收和生产晋级'));
+            }
+            // 原测试提交中的设计基线也必须有效，当前主线的补写不能补签旧版本。
+            diagnostics.push(...testedLifecycle.design.diagnostics);
+            const acceptance = await operationStage('business-acceptance', '核对原测试版本的业务验收报告', async () => verifyBusinessAcceptance(workspace.root, source, testedLifecycle));
+            diagnostics.push(...acceptance.diagnostics);
+        }
+        catch (error) {
+            return [this.configurationCompatibilityDiagnostic(error)];
         }
         if (workspace.context.workspace.dirty || version.source.dirty) {
-            diagnostics.push(this.diagnostic("PRODUCTION_SOURCE_DIRTY", "生产晋级只接受来源干净且当前工作区无未提交变更的 AppVersion", "git", "提交并推送变更后重新部署预发，再晋级该 AppVersion"));
+            diagnostics.push(this.diagnostic("PRODUCTION_SOURCE_DIRTY", "生产晋级只接受来源干净且当前工作区无未提交变更的 AppVersion", "git", "提交并推送当前改动，或在干净主线目录中晋级该测试版本"));
         }
         const repository = git(workspace.root, ["config", "--get", "remote.origin.url"]);
         const currentRepository = this.repositoryIdentity(repository);
@@ -996,25 +1207,15 @@ export class OpenXiangdaApplicationServices {
             currentRepository !== sourceRepository) {
             diagnostics.push(this.diagnostic("PRODUCTION_SOURCE_REPOSITORY_MISMATCH", "当前工作区仓库与 AppVersion 来源仓库不一致", "git.remote.origin.url", "在构建该 AppVersion 的同一仓库中执行晋级", { current: repository || null, source: version.source.repository }));
         }
-        const upstream = git(workspace.root, [
-            "rev-parse",
-            "--abbrev-ref",
-            "--symbolic-full-name",
-            "@{upstream}",
-        ]);
-        if (!upstream) {
-            diagnostics.push(this.diagnostic("PRODUCTION_UPSTREAM_MISSING", "当前 Git 分支没有 upstream，无法证明 AppVersion 来源已进入远端主线", "git", "为当前分支配置 upstream 并推送来源 commit"));
+        if (diagnostics.length)
+            return diagnostics;
+        try {
+            await operationStage('promotion-source', '核对测试制品的主线来源', () => publishedDeliverySource(workspace.root, version.source.commit));
         }
-        else {
-            const refreshed = spawnSync("git", ["-C", workspace.root, "fetch", "--quiet"], { encoding: "utf8" });
-            if (refreshed.status !== 0) {
-                diagnostics.push(this.diagnostic("PRODUCTION_UPSTREAM_REFRESH_FAILED", "无法刷新远端引用，生产晋级不能依赖可能过期的本地 upstream", "git", "恢复远端访问并重新执行晋级"));
-                return diagnostics;
-            }
-            const contained = spawnSync("git", ["-C", workspace.root, "merge-base", "--is-ancestor", version.source.commit, upstream], { encoding: "utf8" });
-            if (contained.status !== 0) {
-                diagnostics.push(this.diagnostic("PRODUCTION_SOURCE_NOT_IN_UPSTREAM", "AppVersion 来源 commit 尚未包含在当前 upstream 中", "git", "推送来源 commit，确认 upstream 更新后再晋级", { commit: version.source.commit, upstream }));
-            }
+        catch (error) {
+            if (!(error instanceof DeliverySourceError))
+                throw error;
+            diagnostics.push(this.diagnostic(error.code, error.message, 'git', String(error.data.remediation), error.data));
         }
         return diagnostics;
     }
@@ -1083,10 +1284,14 @@ export class OpenXiangdaApplicationServices {
         if (!generated.ok) {
             return this.result("dev", workspace.context.workspace, undefined, generated.diagnostics, generated.nextActions);
         }
+        const backendDiagnostics = this.initializeBackend(workspace);
+        if (backendDiagnostics.length) {
+            return this.result("dev", workspace.context.workspace, undefined, backendDiagnostics);
+        }
         try {
             const linkPath = join(workspace.root, ".openxiangda", "link.json");
             if (!existsSync(linkPath)) {
-                throw new Error("OPENXIANGDA_CONNECTED_LINK_REQUIRED: 先运行 openxiangda create <directory>");
+                throw new Error("OPENXIANGDA_CONNECTED_LINK_REQUIRED: 先运行 openxiangda create <directory> --base-url <platform>");
             }
             let link;
             try {
@@ -1200,10 +1405,10 @@ export class OpenXiangdaApplicationServices {
                 : {}),
         };
     }
-    async validateTargetConfigurationCompatibility(workspace, environmentKey) {
+    async validateTargetConfigurationCompatibility(workspace, environmentKey, local) {
         const client = await this.client(workspace.root);
         const capabilities = await client.capabilities();
-        const sources = compileApplicationSources(workspace.config, this.toolchainVersion);
+        const { sources } = local;
         const required = {
             ...CURRENT_APPLICATION_CONTRACT,
             configurationBundleSchemaVersion: sources.config.value.schemaVersion,
@@ -1233,9 +1438,21 @@ export class OpenXiangdaApplicationServices {
             configurationDigest: sources.config.digest,
             contractDigest: sources.contracts.digest,
         }, requiredPlatformCapabilities(workspace.config));
+        if (result.projectionDigest !== local.compiled.aggregateDigest) {
+            throw new ControlPlaneError(409, 'OPENXIANGDA_CONFIGURATION_PROJECTION_MISMATCH', '相同校验规则与输入生成了不同投影，已停止构建，请检查平台配套版本', {
+                pointer: '/projectionDigest', expectedProjectionDigest: local.compiled.aggregateDigest,
+                actualProjectionDigest: result.projectionDigest, validatorDigest: NATIVE_CONFIGURATION_VALIDATOR_DIGEST,
+            });
+        }
         return result;
     }
     configurationCompatibilityDiagnostic(error) {
+        if (error instanceof NativeConfigurationCompilerError) {
+            return this.diagnostic(error.code, '应用声明未通过本地完整配置校验', error.pointer, '按错误指针修正应用声明，运行 openxiangda check 复核', {
+                pointer: error.pointer, identifiers: error.identifiers, validatorDigest: NATIVE_CONFIGURATION_VALIDATOR_DIGEST,
+                validationOwner: 'local-shared-compiler',
+            });
+        }
         const data = error instanceof ControlPlaneError &&
             error.data &&
             typeof error.data === "object" &&
@@ -1306,20 +1523,40 @@ export class OpenXiangdaApplicationServices {
     get toolchainVersion() {
         return this.options.toolchainVersion || OPENXIANGDA_TOOLCHAIN_VERSION;
     }
+    deliveryCacheContext(workspace) {
+        return {
+            root: workspace.root, frontendRoot: workspace.config.frontend.root,
+            ...(backendRuntimeRequired(workspace.config) ? { backendRoot: workspace.config.backend.root } : {}),
+            toolchain: { version: this.toolchainVersion, capsule: this.toolchainCapsule, validatorDigest: NATIVE_CONFIGURATION_VALIDATOR_DIGEST },
+        };
+    }
     get toolchainCapsule() {
         return this.options.toolchainCapsule || defaultDevkitCoreToolchainCapsule();
     }
-    runPackageScript(root, script) {
-        const result = spawnSync("pnpm", ["run", script], {
-            cwd: root,
-            encoding: "utf8",
-            env: process.env,
+    initializeBackend(workspace) {
+        try {
+            initializeOptionalBackend(workspace.root, workspace.config, {
+                ...(this.options.toolchainCapsule?.packages.openxiangda
+                    ? { sdkVersion: this.options.toolchainCapsule.packages.openxiangda }
+                    : {}),
+            });
+            return [];
+        }
+        catch (error) {
+            return [{
+                    ...this.diagnostic(String(error.code || "OPENXIANGDA_BACKEND_INITIALIZATION_FAILED"), error.message, workspace.config.backend.root, "修复初始化或依赖安装问题后重新运行 openxiangda check"),
+                    retryable: error.retryable === true,
+                }];
+        }
+    }
+    packageScriptLabel(script) {
+        return { check: '类型与规范检查', test: '应用测试', build: '前后端构建' }[script] || script;
+    }
+    async runPackageScript(root, script) {
+        return operationStage(script, this.packageScriptLabel(script), async () => {
+            const result = await runCommandProcess('pnpm', ['run', script], { cwd: root });
+            return { ok: result.ok, exitCode: result.status ?? 1, output: result.output.trim(), outputTruncated: result.outputTruncated };
         });
-        return {
-            ok: result.status === 0,
-            exitCode: result.status ?? 1,
-            output: `${result.stdout || ""}${result.stderr || ""}`.trim(),
-        };
     }
     repositoryIdentity(value) {
         const normalized = String(value || "").trim();
@@ -1513,7 +1750,7 @@ export class OpenXiangdaApplicationServices {
                 remediation: "运行 create 幂等完成工作区绑定和平台初始化",
                 actionCode: "create",
                 actionLabel: "初始化应用",
-                command: "openxiangda create <directory>",
+                command: "openxiangda create <directory> --base-url <platform>",
                 path: ".openxiangda/link.json",
             },
             OPENXIANGDA_CONNECTED_LINK_INVALID: {
@@ -1521,7 +1758,7 @@ export class OpenXiangdaApplicationServices {
                 remediation: "运行 create 幂等校验并重新生成当前应用绑定",
                 actionCode: "create",
                 actionLabel: "重新初始化应用",
-                command: "openxiangda create <directory>",
+                command: "openxiangda create <directory> --base-url <platform>",
                 path: ".openxiangda/link.json",
             },
             OPENXIANGDA_CONNECTED_LOGIN_REQUIRED: {
@@ -1595,7 +1832,7 @@ export class OpenXiangdaApplicationServices {
             operation,
             workspace,
             ...(data === undefined ? {} : { data }),
-            diagnostics,
+            diagnostics: [...diagnostics].sort((left, right) => ({ error: 0, warning: 1, info: 2 })[left.severity] - ({ error: 0, warning: 1, info: 2 })[right.severity]),
             nextActions,
         };
     }