From fcd98d5fe37da1544c5f3488f6e883cacddea8e9 Mon Sep 17 00:00:00 2001
From: andreoucostas <67519984+andreoucostas@users.noreply.github.com>
Date: Mon, 7 Sep 2026 17:12:41 +0100
Subject: [PATCH] Show warning when cached docs cannot refresh

---
 .../Docs/Documents/DocumentWithDetailsDto.cs  |  2 +
 .../Volo/Docs/DocsApplicationMappers.cs       |  2 +
 .../Volo/Docs/Documents/DocumentAppService.cs |  4 +-
 .../Volo/Docs/Localization/Domain/en.json     |  1 +
 .../Pages/Documents/Project/Index.cshtml      |  7 ++
 .../Volo/Docs/ApplicationService_Tests.cs     | 72 ++++++++++++++++++-
 .../Volo/Docs/DocsApplicationTestModule.cs    | 12 +++-
 7 files changed, 96 insertions(+), 4 deletions(-)

diff --git a/modules/docs/src/Volo.Docs.Application.Contracts/Volo/Docs/Documents/DocumentWithDetailsDto.cs b/modules/docs/src/Volo.Docs.Application.Contracts/Volo/Docs/Documents/DocumentWithDetailsDto.cs
index 5f559c83e5..228cae1c77 100644
--- a/modules/docs/src/Volo.Docs.Application.Contracts/Volo/Docs/Documents/DocumentWithDetailsDto.cs
+++ b/modules/docs/src/Volo.Docs.Application.Contracts/Volo/Docs/Documents/DocumentWithDetailsDto.cs
@@ -34,6 +34,8 @@ namespace Volo.Docs.Documents
 
         public virtual DateTime LastCachedTime { get; set; }
 
+        public virtual bool IsStaleCacheFallback { get; set; }
+
         public ProjectDto Project { get; set; }
 
         public List<DocumentContributorDto> Contributors { get; set; }
diff --git a/modules/docs/src/Volo.Docs.Application/Volo/Docs/DocsApplicationMappers.cs b/modules/docs/src/Volo.Docs.Application/Volo/Docs/DocsApplicationMappers.cs
index bd8474b7b9..cdeb2628bb 100644
--- a/modules/docs/src/Volo.Docs.Application/Volo/Docs/DocsApplicationMappers.cs
+++ b/modules/docs/src/Volo.Docs.Application/Volo/Docs/DocsApplicationMappers.cs
@@ -43,9 +43,11 @@ public partial class DocumentToDocumentWithDetailsDtoMapper : MapperBase<Documen
 {
     [MapperIgnoreTarget(nameof(DocumentWithDetailsDto.Project))]
     [MapperIgnoreTarget(nameof(DocumentWithDetailsDto.Contributors))]
+    [MapperIgnoreTarget(nameof(DocumentWithDetailsDto.IsStaleCacheFallback))]
     public override partial DocumentWithDetailsDto Map(Document source);
 
     [MapperIgnoreTarget(nameof(DocumentWithDetailsDto.Project))]
     [MapperIgnoreTarget(nameof(DocumentWithDetailsDto.Contributors))]
+    [MapperIgnoreTarget(nameof(DocumentWithDetailsDto.IsStaleCacheFallback))]
     public override partial void Map(Document source, DocumentWithDetailsDto destination);
 }
\ No newline at end of file
diff --git a/modules/docs/src/Volo.Docs.Application/Volo/Docs/Documents/DocumentAppService.cs b/modules/docs/src/Volo.Docs.Application/Volo/Docs/Documents/DocumentAppService.cs
index e5bbca3f5a..8f7701051b 100644
--- a/modules/docs/src/Volo.Docs.Application/Volo/Docs/Documents/DocumentAppService.cs
+++ b/modules/docs/src/Volo.Docs.Application/Volo/Docs/Documents/DocumentAppService.cs
@@ -390,7 +390,9 @@ namespace Volo.Docs.Documents
                 Logger.LogWarning(
                     "Could not retrieve the document ({documentName}, {languageCode}, {version}) from the source. Using the cached version.",
                     documentName, languageCode, version);
-                return CreateDocumentWithDetailsDto(project, document);
+                var documentDto = CreateDocumentWithDetailsDto(project, document);
+                documentDto.IsStaleCacheFallback = true;
+                return documentDto;
             }
         }
 
diff --git a/modules/docs/src/Volo.Docs.Domain/Volo/Docs/Localization/Domain/en.json b/modules/docs/src/Volo.Docs.Domain/Volo/Docs/Localization/Domain/en.json
index 9859a7a4a2..2497f2a5d9 100644
--- a/modules/docs/src/Volo.Docs.Domain/Volo/Docs/Localization/Domain/en.json
+++ b/modules/docs/src/Volo.Docs.Domain/Volo/Docs/Localization/Domain/en.json
@@ -25,6 +25,7 @@
     "ProjectNotFound": "Oops, the requested project was not found!",
     "NavigationDocumentNotFound": "This version does not have a navigation document!",
     "DocumentNotFoundInSelectedLanguage": "Document in the language you wanted is not found. Document in the default language is shown.",
+    "StaleCacheFallbackWarning": "Document refresh failed. The displayed document may be outdated or incorrect.",
     "FilterTopics": "Filter topics",
     "FullSearch": "Search in documents",
     "Volo.Docs.Domain:010001": "Elastic search is not enabled.",
diff --git a/modules/docs/src/Volo.Docs.Web/Pages/Documents/Project/Index.cshtml b/modules/docs/src/Volo.Docs.Web/Pages/Documents/Project/Index.cshtml
index 91b9841a65..79076308d3 100644
--- a/modules/docs/src/Volo.Docs.Web/Pages/Documents/Project/Index.cshtml
+++ b/modules/docs/src/Volo.Docs.Web/Pages/Documents/Project/Index.cshtml
@@ -301,6 +301,13 @@
     @if (Model.Document != null)
     {
         <div class="docs-content">
+            @if (Model.Document.IsStaleCacheFallback)
+            {
+                <abp-alert alert-type="Warning" dismissible="true" class="mb-3">
+                    @L["StaleCacheFallbackWarning"]
+                </abp-alert>
+            }
+
             <div class="top-container mb-3">
                 <div class="w-100">
                     <nav style="--bs-breadcrumb-divider: '>';" aria-label="breadcrumb">
diff --git a/modules/docs/test/Volo.Docs.Application.Tests/Volo/Docs/ApplicationService_Tests.cs b/modules/docs/test/Volo.Docs.Application.Tests/Volo/Docs/ApplicationService_Tests.cs
index 662db4c6aa..9471302480 100644
--- a/modules/docs/test/Volo.Docs.Application.Tests/Volo/Docs/ApplicationService_Tests.cs
+++ b/modules/docs/test/Volo.Docs.Application.Tests/Volo/Docs/ApplicationService_Tests.cs
@@ -1,17 +1,27 @@
-using System.Threading.Tasks;
+using System;
+using System.Threading.Tasks;
+using NSubstitute;
 using Shouldly;
 using Volo.Docs.Common.Projects;
+using Volo.Docs.Documents;
+using Volo.Docs.GitHub.Documents;
 using Xunit;
 
 namespace Volo.Docs
 {
     public class ApplicationService_Tests : DocsApplicationTestBase
     {
+        private readonly IDocumentAppService _documentAppService;
+        private readonly IDocumentRepository _documentRepository;
+        private readonly IGithubRepositoryManager _githubRepositoryManager;
         private readonly IProjectAppService _projectAppService;
         private readonly DocsTestData _testData;
 
         public ApplicationService_Tests()
         {
+            _documentAppService = GetRequiredService<IDocumentAppService>();
+            _documentRepository = GetRequiredService<IDocumentRepository>();
+            _githubRepositoryManager = GetRequiredService<IGithubRepositoryManager>();
             _projectAppService = GetRequiredService<IProjectAppService>();
             _testData = GetRequiredService<DocsTestData>();
         }
@@ -41,5 +51,65 @@ namespace Volo.Docs
             versions.Items.Count.ShouldBe(1);
             versions.Items.ShouldContain(x => x.Name == "0.15.0" && x.DisplayName == "0.15.0");
         }
+
+        [Fact]
+        public async Task GetAsync_Should_Not_Set_Stale_Cache_Fallback_Flag_For_Fresh_Cache()
+        {
+            var document = await _documentAppService.GetAsync(CreateDocumentInput());
+
+            document.IsStaleCacheFallback.ShouldBeFalse();
+            document.Content.ShouldBe("this is abp cli");
+        }
+
+        [Fact]
+        public async Task GetAsync_Should_Set_Stale_Cache_Fallback_Flag_When_Refresh_Fails()
+        {
+            await MakeDocumentStaleAsync();
+            ConfigureRefreshFailure();
+
+            var document = await _documentAppService.GetAsync(CreateDocumentInput());
+
+            document.IsStaleCacheFallback.ShouldBeTrue();
+            document.Content.ShouldBe("this is abp cli");
+        }
+
+        [Fact]
+        public async Task GetAsync_Should_Not_Set_Stale_Cache_Fallback_Flag_When_Refresh_Succeeds()
+        {
+            await MakeDocumentStaleAsync();
+
+            var document = await _documentAppService.GetAsync(CreateDocumentInput());
+
+            document.IsStaleCacheFallback.ShouldBeFalse();
+            document.Content.ShouldBe("stringContent");
+        }
+
+        private GetDocumentInput CreateDocumentInput()
+        {
+            return new GetDocumentInput
+            {
+                ProjectId = _testData.ProjectId,
+                Name = "CLI.md",
+                LanguageCode = "en",
+                Version = "2.0.0"
+            };
+        }
+
+        private async Task MakeDocumentStaleAsync()
+        {
+            await _documentRepository.UpdateProjectLastCachedTimeAsync(_testData.ProjectId, DateTime.MinValue);
+        }
+
+        private void ConfigureRefreshFailure()
+        {
+            _githubRepositoryManager.GetFileRawStringContentAsync(
+                    Arg.Is<string>(url =>
+                        url.EndsWith("/en/CLI.md", StringComparison.OrdinalIgnoreCase) ||
+                        url.EndsWith("/en/CLI/index.md", StringComparison.OrdinalIgnoreCase) ||
+                        url.EndsWith("/en/CLI/Index.md", StringComparison.OrdinalIgnoreCase)),
+                    Arg.Any<string>(),
+                    Arg.Any<string>())
+                .Returns(_ => Task.FromException<string>(new Exception("Simulated refresh failure")));
+        }
     }
 }
diff --git a/modules/docs/test/Volo.Docs.Application.Tests/Volo/Docs/DocsApplicationTestModule.cs b/modules/docs/test/Volo.Docs.Application.Tests/Volo/Docs/DocsApplicationTestModule.cs
index 62d027c220..2b059ab112 100644
--- a/modules/docs/test/Volo.Docs.Application.Tests/Volo/Docs/DocsApplicationTestModule.cs
+++ b/modules/docs/test/Volo.Docs.Application.Tests/Volo/Docs/DocsApplicationTestModule.cs
@@ -1,4 +1,7 @@
-using Volo.Abp.Modularity;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+using NSubstitute;
+using Volo.Abp.Modularity;
 
 namespace Volo.Docs
 {
@@ -8,6 +11,11 @@ namespace Volo.Docs
         )]
     public class DocsApplicationTestModule : AbpModule
     {
-
+        public override void ConfigureServices(ServiceConfigurationContext context)
+        {
+            var hostEnvironment = Substitute.For<IHostEnvironment>();
+            hostEnvironment.EnvironmentName.Returns(Environments.Production);
+            context.Services.AddSingleton(hostEnvironment);
+        }
     }
 }