Surface upgrade suggestions on insufficient-balance downloads

[gamadev1]

Summary

• POST api/v1/downloads previously returned a bare OperationResult.Failed with the message Localizer["InsufficientBalance"] on an insufficient-balance charge — that key had no resx entry anywhere in the repo, so it rendered literally as the string InsufficientBalance to callers.
• GameService.SpendPointsAsync already computes UpgradeSuggestions (up to 3 active plans that would cover the feature) on this same failure, matching what games/spends v2 already exposes — but ContentDeliveryService/DownloadContentResponseDto had no field to carry it through, so it was silently dropped for downloads specifically.
• This PR adds a real localized message and plumbs UpgradeSuggestions through to the download response, so the frontend can drive the same "upgrade/top-up" UI on a denied download that it already can on games/spends.

Changes

• src/Core/Resource/Application/GameService.resx (new): real text for the InsufficientBalance key.
• DownloadContentResponseDto/DownloadContentResponseViewModel: added UpgradeSuggestions; relaxed Url from required to nullable (there's no URL on a failed/no-download response).
• ContentDeliveryService.DownloadContentAsync: forwards UpgradeSuggestions on the insufficient-balance branch instead of discarding them.
• DownloadsController.Download: maps UpgradeSuggestions DTO → ViewModel using the same pattern already used by games/spends v2.
• docs/business/content-delivery.md: documents the new response field and the resx fix.

Test plan

• dotnet build (0 warnings/errors, TreatWarningsAsErrors on)
• Manually tested via Swagger against the local dev stack (insufficient-balance case returns real message + upgrade suggestions; success/free cases unaffected)

[github-actions]

🤖 AI Generated Review

This review was generated automatically and does not replace human review.

Review chunk 1/1

Summary

This pull request introduces a feature to provide upgrade suggestions when a download fails due to insufficient balance. Changes span several files, including adjustments to data transfer objects, services, and view models, as well as adding new resource files for localization.

Potential Issues

• Null Handling: In ContentDeliveryService.cs, when setting UpgradeSuggestions, ensure spendResult.Data?.UpgradeSuggestions is not null to avoid potential null reference exceptions.
• Data Consistency: Ensure that the DownloadContentResponseDto and DownloadContentResponseViewModel always stay in sync, especially when adding or modifying fields like UpgradeSuggestions.

Suggestions

• Error Handling: Consider adding error logging in ContentDeliveryService.cs for instances where spendResult.OperationResult is not successful. This can improve troubleshooting efforts in production.
• Documentation Improvement: Update comments/documentation to mention the addition of upgrade suggestions feature as this could be helpful for developers interacting with the API.

Positive Feedback

• Comprehensive Solution: The addition of upgrade suggestions is integrated well across various layers: data transfer objects, services, view models, and resource files.
• Localization: Adding the GameService.resx entry for InsufficientBalance improves internationalization support, conforming to best practices in software development.
• Code Readability: The code changes, particularly in the service and view model layers, are clear and maintain existing coding conventions, making it easy for future developers to understand and maintain.
• Logical Segmentation: Well-structured approach by segregating different concerns like DTO modifications, service-level changes, and UI/view model impacts.