feat: CVP-first upgrade with automatic chain fallback (#500)

* feat: CVP-first upgrade with automatic chain fallback

- Remove upgradeMode from VersionService request (new SDK sends no mode)
- DownloadPlanBuilder: CVP-first selection, retain chain for other AppTypes
- ClientStrategy: CVP download/apply fallback to chain from cached response
- No second server request needed on CVP failure

* fix: address Copilot review and test failure

- DownloadPlanBuilder: match CVP FromVersion against correct AppType local version
- DownloadPlanBuilder: prefer highest-version CVP when multiple match
- ClientStrategy: fix isCvpAttempt to check Any(a.IsCrossVersion) instead of Count==1
- ClientStrategy: exclude OperationCanceledException from CVP fallback catch
- ClientStrategy: add missing ConfigureAwait(false) on new awaits
- VersionService: update XML docs to remove outdated upgradeMode reference
- Tests: update Build_CrossVersionIncluded test for CVP-first behavior
- Tests: add Build_CvpWithMixedAppTypes test for multi-AppType CVP plans

Author: JusterZhu

src/c#/GeneralUpdate.Core/Download/DownloadPlanBuilder.cs

@@ -133,6 +133,41 @@ public static DownloadPlan Build(
 
         if (candidates.Count == 0) return DownloadPlan.Empty;
 
+        // ── CVP-first selection ──
+        // If a matching cross-version package (CVP) exists whose FromVersion
+        // equals the client's current version, prefer it over chain packages.
+        // This gives the client a single-package shortcut from old → latest.
+        // Prefer the CVP with the highest target version when multiple CVPs match.
+        var matchingCvp = candidates
+            .Where(a => a.IsCrossVersion)
+            .Where(a =>
+            {
+                var fromVer = ParseVersion(a.FromVersion);
+                if (fromVer == null) return false;
+                var localVersion = (a.AppType == (int)AppType.Upgrade)
+                    ? parsedUpgrade
+                    : parsedClient;
+                return fromVer == localVersion;
+            })
+            .OrderByDescending(a => ParseVersion(a.Version))
+            .FirstOrDefault();
+
+        if (matchingCvp != null)
+        {
+            // CVP covers one AppType in a single hop. Still need chain packages
+            // for other AppTypes, and for the same AppType beyond the CVP's target.
+            var cvpAppType = matchingCvp.AppType;
+            var cvpVersion = ParseVersion(matchingCvp.Version);
+            var planAssets = new List<DownloadAsset> { matchingCvp };
+            planAssets.AddRange(candidates
+                .Where(a => !a.IsCrossVersion)
+                .Where(a => a.AppType != cvpAppType
+                            || (cvpVersion != null && ParseVersion(a.Version) > cvpVersion))
+                .OrderBy(a => ParseVersion(a.Version)));
+            return new DownloadPlan(planAssets, isForcibly);
+        }
+
+        // No matching CVP: return all chain packages sorted by version (ascending)
         return new DownloadPlan(candidates, isForcibly);
     }
 

src/c#/GeneralUpdate.Core/Network/VersionService.cs

@@ -226,7 +226,7 @@ public static Task<VersionRespDTO> Validate(string url, string version,
         /// Execution flow:
         /// <list type="number">
         ///   <item><description>Constructs a parameter dictionary with the version, app type, app key,
-        ///   platform, product ID, and upgrade mode.</description></item>
+        ///   platform, and product ID.</description></item>
         ///   <item><description>Sends the parameters via a POST request using <see cref="PostAsync{T}"/>.</description></item>
         ///   <item><description>Deserializes the response into a <see cref="VersionRespDTO"/>.</description></item>
         /// </list>
@@ -243,7 +243,7 @@ public static Task<VersionRespDTO> Validate(string url, string version,
         private async Task<VersionRespDTO> ValidateAsync(string url, string v, int at, string appKey, int pf, string pid,
             CancellationToken t = default)
         {
-            var p = new Dictionary<string, object> { ["version"] = v, ["appType"] = at, ["appKey"] = appKey, ["platform"] = pf, ["productId"] = pid, ["upgradeMode"] = 1 };
+            var p = new Dictionary<string, object> { ["version"] = v, ["appType"] = at, ["appKey"] = appKey, ["platform"] = pf, ["productId"] = pid };
             return await PostAsync<VersionRespDTO>(url, p, VersionRespJsonContext.Default.VersionRespDTO, t);
         }
 

src/c#/GeneralUpdate.Core/Strategy/ClientStrategy.cs

@@ -479,6 +479,12 @@ private async Task ExecuteStandardWorkflowAsync()
         _configInfo.LastVersion = downloadPlan.Assets.LastOrDefault()?.Version;
         GeneralTracer.Info($"ClientStrategy: Scenario={scenario}, AssetCount={downloadPlan.Assets.Count}");
 
+        // Store original assets and CVP flag for chain fallback.
+        // If the CVP download/apply fails, we rebuild the plan from cached chain
+        // packages without a second server request.
+        var isCvpAttempt = downloadPlan.Assets.Any(a => a.IsCrossVersion);
+        var originalAssets = sourceResult.Assets.ToList();
+
         // Dispatch update info event with populated version data (full GeneralSpacestation-compatible fields)
         var versionInfos = downloadPlan.Assets.Select(a => new VersionEntry
         {
@@ -561,78 +567,109 @@ private async Task ExecuteStandardWorkflowAsync()
 
         _osStrategy!.Create(_configInfo);
 
-        // Download ALL packages via orchestrator (requirement 6: client downloads everything
-        // regardless of whether client or upgrade needs updating)
+        // ════════════════════════════════════════════════════════════════════
+        // Download + Apply with CVP fallback to chain.
+        // If the CVP download OR apply fails, retry with chain packages
+        // from the cached original response without a second server request.
+        // ════════════════════════════════════════════════════════════════════
         var orchOptions = Download.Models.DownloadOrchestratorOptions.From(_configInfo);
-        GeneralTracer.Info($"ClientStrategy: downloading {downloadPlan.Assets.Count} asset(s).");
-        if (_orchestrator != null)
+
+        async Task ExecuteDownloadAsync(Download.Models.DownloadPlan plan)
         {
-            await _orchestrator.ExecuteAsync(downloadPlan, _configInfo.TempPath).ConfigureAwait(false);
+            if (_orchestrator != null)
+            {
+                await _orchestrator.ExecuteAsync(plan, _configInfo.TempPath).ConfigureAwait(false);
+            }
+            else
+            {
+                var httpClient = GeneralUpdate.Core.Network.HttpClientProvider.Shared;
+                var orchestrator = new Download.Orchestrators.DefaultDownloadOrchestrator(
+                    httpClient, orchOptions, _customDownloadPolicy,
+                    _customDownloadExecutor, _customDownloadPipelineFactory);
+                await orchestrator.ExecuteAsync(plan, _configInfo.TempPath).ConfigureAwait(false);
+            }
         }
-        else
+
+        // Download + report + build version lists + scenario dispatch
+        async Task DownloadAndApplyAsync(Download.Models.DownloadPlan plan, UpdateScenario sc)
         {
-            var httpClient = GeneralUpdate.Core.Network.HttpClientProvider.Shared;
-            var orchestrator = new Download.Orchestrators.DefaultDownloadOrchestrator(
-                httpClient, orchOptions, _customDownloadPolicy,
-                _customDownloadExecutor, _customDownloadPipelineFactory);
-            await orchestrator.ExecuteAsync(downloadPlan, _configInfo.TempPath).ConfigureAwait(false);
-        }
+            GeneralTracer.Info($"ClientStrategy: downloading {plan.Assets.Count} asset(s).");
+            await ExecuteDownloadAsync(plan).ConfigureAwait(false);
 
-        await SafeReportDownloadCompletedAsync(hooksCtx).ConfigureAwait(false);
-        await SafeOnDownloadCompletedAsync(hooksCtx).ConfigureAwait(false);
+            await SafeReportDownloadCompletedAsync(hooksCtx).ConfigureAwait(false);
+            await SafeOnDownloadCompletedAsync(hooksCtx).ConfigureAwait(false);
 
-        // Build VersionEntry list with AppType preserved from server response.
-        var downloadVersions = downloadPlan.Assets.Select(a => new VersionEntry
-        {
-            RecordId = a.RecordId,
-            Name = a.Name,
-            Hash = a.SHA256,
-            Url = a.Url,
-            Version = a.Version,
-            Format = _configInfo.Format.ToExtension(),
-            AppType = a.AppType ?? (int)AppType.Client
-        }).ToList();
+            // Build VersionEntry list with AppType preserved from server response.
+            var dVersions = plan.Assets.Select(a => new VersionEntry
+            {
+                RecordId = a.RecordId,
+                Name = a.Name,
+                Hash = a.SHA256,
+                Url = a.Url,
+                Version = a.Version,
+                Format = _configInfo.Format.ToExtension(),
+                AppType = a.AppType ?? (int)AppType.Client
+            }).ToList();
+
+            var uVersions = dVersions.Where(v => v.AppType == (int)AppType.Upgrade).ToList();
+            var cVersions = dVersions.Where(v => v.AppType == (int)AppType.Client).ToList();
+            GeneralTracer.Info(
+                $"ClientStrategy: Upgrade packages={uVersions.Count}, MainApp packages={cVersions.Count}");
 
-        var upgradeVersions = downloadVersions.Where(v => v.AppType == (int)AppType.Upgrade).ToList();
-        var clientVersions = downloadVersions.Where(v => v.AppType == (int)AppType.Client).ToList();
-        GeneralTracer.Info(
-            $"ClientStrategy: Upgrade packages={upgradeVersions.Count}, MainApp packages={clientVersions.Count}");
+            // ── Dispatch by scenario ──
+            switch (sc)
+            {
+                case UpdateScenario.UpgradeOnly:
+                    await ApplyUpgradePackagesAsync(uVersions).ConfigureAwait(false);
+                    await SafeOnAfterUpdateAsync(hooksCtx).ConfigureAwait(false);
+                    await SafeReportUpdateAppliedAsync(hooksCtx, _upgradeRecordId).ConfigureAwait(false);
+                    GeneralTracer.Info("ClientStrategy: Upgrade-only update applied, client continues running.");
+                    break;
+
+                case UpdateScenario.MainOnly:
+                    SendProcessIpc(cVersions);
+                    await SafeOnAfterUpdateAsync(hooksCtx).ConfigureAwait(false);
+                    await SafeReportUpdateAppliedAsync(hooksCtx, _mainRecordId).ConfigureAwait(false);
+                    if (LaunchAfterPrepare)
+                    {
+                        await SafeOnBeforeStartAppAsync(hooksCtx).ConfigureAwait(false);
+                        await LaunchUpgradeProcessAsync().ConfigureAwait(false);
+                    }
+                    break;
+
+                case UpdateScenario.Both:
+                    await ApplyUpgradePackagesAsync(uVersions).ConfigureAwait(false);
+                    await SafeOnAfterUpdateAsync(hooksCtx).ConfigureAwait(false);
+                    await SafeReportUpdateAppliedAsync(hooksCtx, _upgradeRecordId).ConfigureAwait(false);
+                    SendProcessIpc(cVersions);
+                    if (LaunchAfterPrepare)
+                    {
+                        await SafeOnBeforeStartAppAsync(hooksCtx).ConfigureAwait(false);
+                        await LaunchUpgradeProcessAsync().ConfigureAwait(false);
+                    }
+                    break;
+                case UpdateScenario.None:
+                default:
+                    throw new InvalidOperationException($"Unhandled update scenario: {sc}");
+            }
+        }
 
-        // ── Dispatch by scenario — one switch, four states, zero nested if-else ──
-        switch (scenario)
+        try
         {
-            case UpdateScenario.UpgradeOnly:
-                await ApplyUpgradePackagesAsync(upgradeVersions).ConfigureAwait(false);
-                await SafeOnAfterUpdateAsync(hooksCtx).ConfigureAwait(false);
-                await SafeReportUpdateAppliedAsync(hooksCtx, _upgradeRecordId).ConfigureAwait(false);
-                GeneralTracer.Info("ClientStrategy: Upgrade-only update applied, client continues running.");
-                break;
-
-            case UpdateScenario.MainOnly:
-                SendProcessIpc(clientVersions);
-                await SafeOnAfterUpdateAsync(hooksCtx).ConfigureAwait(false);
-                await SafeReportUpdateAppliedAsync(hooksCtx, _mainRecordId).ConfigureAwait(false);
-                if (LaunchAfterPrepare)
-                {
-                    await SafeOnBeforeStartAppAsync(hooksCtx).ConfigureAwait(false);
-                    await LaunchUpgradeProcessAsync().ConfigureAwait(false);
-                }
-                break;
-
-            case UpdateScenario.Both:
-                await ApplyUpgradePackagesAsync(upgradeVersions).ConfigureAwait(false);
-                await SafeOnAfterUpdateAsync(hooksCtx).ConfigureAwait(false);
-                await SafeReportUpdateAppliedAsync(hooksCtx, _upgradeRecordId).ConfigureAwait(false);
-                SendProcessIpc(clientVersions);
-                if (LaunchAfterPrepare)
-                {
-                    await SafeOnBeforeStartAppAsync(hooksCtx).ConfigureAwait(false);
-                    await LaunchUpgradeProcessAsync().ConfigureAwait(false);
-                }
-                break;
-            case UpdateScenario.None:
-            default:
-                throw new InvalidOperationException($"Unhandled update scenario: {scenario}");
+            await DownloadAndApplyAsync(downloadPlan, scenario).ConfigureAwait(false);
+        }
+        catch (Exception ex) when (isCvpAttempt && ex is not OperationCanceledException)
+        {
+            GeneralTracer.Warn($"ClientStrategy: CVP attempt failed, falling back to chain packages. {ex.Message}");
+            var fallback = BuildChainFallback(originalAssets, localClientVersion, resolvedUpgradeVersion);
+            if (fallback == null)
+                throw new InvalidOperationException(
+                    "CVP failed and no chain packages are available for fallback.", ex);
+
+            (downloadPlan, scenario) = fallback.Value;
+            UpdateRecordIdsFromPlan(downloadPlan);
+            GeneralTracer.Info($"ClientStrategy: retrying with {downloadPlan.Assets.Count} chain asset(s), Scenario={scenario}");
+            await DownloadAndApplyAsync(downloadPlan, scenario).ConfigureAwait(false);
         }
     }
 
@@ -1122,5 +1159,45 @@ await Reporter
         }
     }
 
+    /// <summary>
+    /// Builds a chain-only fallback plan from the cached original server response,
+    /// excluding any CVP assets. Returns null when no chain packages are available.
+    /// </summary>
+    private (Download.Models.DownloadPlan Plan, UpdateScenario Scenario)? BuildChainFallback(
+        List<Download.Models.DownloadAsset> originalAssets,
+        string localClientVersion,
+        string? resolvedUpgradeVersion)
+    {
+        var chainAssets = originalAssets.Where(a => !a.IsCrossVersion).ToList();
+        var plan = DownloadPlanBuilder.Build(chainAssets, localClientVersion, resolvedUpgradeVersion);
+        if (!plan.HasAssets) return null;
+
+        _configInfo.LastVersion = plan.Assets.LastOrDefault()?.Version;
+        _configInfo.IsMainUpdate = DownloadPlanBuilder.HasUpdate(chainAssets, AppType.Client, localClientVersion);
+        _configInfo.IsUpgradeUpdate = DownloadPlanBuilder.HasUpdate(chainAssets, AppType.Upgrade, resolvedUpgradeVersion);
+
+        var sc = (_configInfo.IsMainUpdate, _configInfo.IsUpgradeUpdate) switch
+        {
+            (false, true) => UpdateScenario.UpgradeOnly,
+            (true, false) => UpdateScenario.MainOnly,
+            (true, true) => UpdateScenario.Both,
+            _ => UpdateScenario.None
+        };
+
+        return (plan, sc);
+    }
+
+    /// <summary>
+    /// Updates <see cref="_mainRecordId"/> and <see cref="_upgradeRecordId"/> from the
+    /// current download plan so status reports use correct record identifiers after fallback.
+    /// </summary>
+    private void UpdateRecordIdsFromPlan(Download.Models.DownloadPlan plan)
+    {
+        _mainRecordId = plan.Assets
+            .FirstOrDefault(a => (a.AppType ?? (int)AppType.Client) == (int)AppType.Client)?.RecordId ?? 0;
+        _upgradeRecordId = plan.Assets
+            .FirstOrDefault(a => a.AppType == (int)AppType.Upgrade)?.RecordId ?? 0;
+    }
+
     #endregion
 }

tests/CoreTest/Download/DownloadPlanBuilderTests.cs

@@ -82,19 +82,40 @@ public void Build_NoAssetIsForcibly_IsForciblyFalse()
     }
 
     [Fact]
-    public void Build_CrossVersionIncluded_ReturnsAllMatchingAssets()
+    public void Build_CrossVersionIncluded_CvpFirst_ReturnsCvpOnly()
     {
+        // When a matching CVP exists, the plan selects the CVP and drops
+        // same-AppType chain packages (CVP covers the full range).
         var assets = new[]
         {
             Asset("cross", "5.0.0", isCrossVersion: true, fromVersion: "1.0.0"),
             Asset("inc", "2.0.0"), Asset("inc2", "3.0.0")
         };
         var result = DownloadPlanBuilder.Build(assets, "1.0.0");
         Assert.True(result.HasAssets);
+        Assert.Single(result.Assets);
+        Assert.True(result.Assets[0].IsCrossVersion);
+        Assert.Equal("5.0.0", result.Assets[0].Version);
+    }
+
+    [Fact]
+    public void Build_CvpWithMixedAppTypes_KeepsChainForOtherTypes()
+    {
+        // CVP covers Client (AppType=1). Upgrade chain packages (AppType=2)
+        // should still be included since the CVP doesn't cover that AppType.
+        var assets = new[]
+        {
+            AssetWithType("cvp", "5.0.0", appType: 1, isCrossVersion: true, fromVersion: "1.0.0"),
+            AssetWithType("upgrade1", "2.0.0", appType: 2),
+            AssetWithType("upgrade2", "3.0.0", appType: 2),
+        };
+        var result = DownloadPlanBuilder.Build(assets, "1.0.0");
+        Assert.True(result.HasAssets);
         Assert.Equal(3, result.Assets.Count);
-        Assert.Equal("2.0.0", result.Assets[0].Version);
-        Assert.Equal("3.0.0", result.Assets[1].Version);
-        Assert.Equal("5.0.0", result.Assets[2].Version);
+        Assert.Equal("5.0.0", result.Assets[0].Version); // CVP first
+        Assert.True(result.Assets[0].IsCrossVersion);
+        Assert.Equal("2.0.0", result.Assets[1].Version); // chain for other AppType
+        Assert.Equal("3.0.0", result.Assets[2].Version);
     }
 
     [Fact]