[Local catalog] Error screen for missing catalog when opening POS (#16305)

joshheald · web-flow · commit 895a44af4c6a · 2025-11-05T08:16:27.000Z
diff --git a/Modules/Sources/PointOfSale/Controllers/PointOfSaleObservableItemsController.swift b/Modules/Sources/PointOfSale/Controllers/PointOfSaleObservableItemsController.swift
@@ -63,7 +63,9 @@ final class PointOfSaleObservableItemsController: PointOfSaleItemsControllerProt
     func loadItems(base: ItemListBaseItem) async {
         switch base {
         case .root:
-            if shouldRefresh(for: base) {
+            if await shouldReload(for: base) {
+                await reloadItems(base: base)
+            } else if shouldRefresh(for: base) {
                 await refreshItems(base: base)
             }
             dataSource.loadProducts()
@@ -88,6 +90,15 @@ final class PointOfSaleObservableItemsController: PointOfSaleItemsControllerProt
         }
     }
 
+    func reloadItems(base: ItemListBaseItem) async {
+        guard case .root = base else {
+            return
+        }
+        loadingState = .init()
+
+        try? await catalogSyncCoordinator.performSmartSync(for: siteID)
+    }
+
     func refreshItems(base: ItemListBaseItem) async {
         if itemsEmpty(for: base) {
             refreshState = .loading
@@ -125,9 +136,14 @@ private extension PointOfSaleObservableItemsController {
             return .loading(isCatalogSyncing: true)
         }
 
+        if case .failure(let error) = initialSyncResult {
+            return .error(.errorOnInitalCatalogSync(error: error))
+        }
+
         if !loadingState.productsLoaded && dataSource.isLoadingProducts {
             return .loading()
         }
+
         return .content
     }
 
@@ -137,13 +153,27 @@ private extension PointOfSaleObservableItemsController {
         }
 
         switch syncState {
-        case .syncStarted(_, true), .syncNeverDone:
+        case .initialSyncStarted, .syncNeverDone:
             return true
         default:
             return false
         }
     }
 
+    var initialSyncResult: Result<Void, Error>? {
+        switch catalogSyncCoordinator.fullSyncStateModel.state[siteID] {
+        case .initialSyncFailed(_, let error):
+            return .failure(error)
+        case .syncFailed(_, let error):
+            // If there's no catalog data, treat subsequent sync failures as critical
+            return dataSource.productItems.isEmpty ? .failure(error) : .success(())
+        case .syncCompleted:
+            return .success(())
+        default:
+            return nil
+        }
+    }
+
     var rootState: ItemListState {
         computeItemListState(
             items: dataSource.productItems,
@@ -173,6 +203,19 @@ private extension PointOfSaleObservableItemsController {
 }
 
 private extension PointOfSaleObservableItemsController {
+    func shouldReload(for type: ItemListBaseItem) async -> Bool {
+        guard case .root = type else {
+            return false
+        }
+
+        // Reload if there's a failure
+        if case .failure = initialSyncResult {
+            return true
+        }
+
+        return false
+    }
+
     /// Determines if a refresh should be triggered
     func shouldRefresh(for type: ItemListBaseItem) -> Bool {
         if case .error = refreshState {
diff --git a/Modules/Sources/PointOfSale/Models/PointOfSaleAggregateModel.swift b/Modules/Sources/PointOfSale/Models/PointOfSaleAggregateModel.swift
@@ -115,7 +115,7 @@ protocol PointOfSaleAggregateModelProtocol {
         publishPaymentMessages()
         setupReaderReconnectionObservation()
         setupPaymentSuccessObservation()
-        performIncrementalSync()
+        performInitialSyncIfNeeded()
     }
 }
 
@@ -623,6 +623,13 @@ private extension PointOfSaleAggregateModel {
             try? await catalogSyncCoordinator.performIncrementalSync(for: siteID)
         }
     }
+
+    private func performInitialSyncIfNeeded() {
+        guard let catalogSyncCoordinator else { return }
+        Task {
+            try? await catalogSyncCoordinator.performSmartSync(for: siteID)
+        }
+    }
 }
 
 #if DEBUG
diff --git a/Modules/Sources/PointOfSale/Models/PointOfSaleErrorState.swift b/Modules/Sources/PointOfSale/Models/PointOfSaleErrorState.swift
@@ -3,6 +3,7 @@ import enum Alamofire.AFError
 
 struct PointOfSaleErrorState: Equatable {
     enum ErrorType: Equatable {
+        case initialCatalogSyncError
         case productsLoadError
         case variationsLoadError
         case productsNextPageError
@@ -108,6 +109,14 @@ struct PointOfSaleErrorState: Equatable {
             buttonText: Constants.retryButtonTitle)
     }
 
+    static func errorOnInitalCatalogSync(error: Error? = nil) -> Self {
+        PointOfSaleErrorState(
+            errorType: .initialCatalogSyncError,
+            title: Constants.failedToSyncCatalogTitle,
+            subtitle: subtitle(for: error),
+            buttonText: Constants.retryButtonTitle)
+    }
+
     private static func subtitle(for error: Error?) -> String {
         if let error, error.isConnectivityError {
             return Constants.connectivityErrorSubtitle
@@ -127,6 +136,11 @@ struct PointOfSaleErrorState: Equatable {
             value: "Retry",
             comment: "Generic text for retry buttons appearing on error screens."
         )
+        static let failedToSyncCatalogTitle = NSLocalizedString(
+            "pos.itemList.syncCatalogErrorTitle",
+            value: "Unable to sync catalog",
+            comment: "Title appearing on the item list screen when there's an error syncing the catalog for the first time."
+        )
         static let loadingCouponsErrorTitle = NSLocalizedString(
             "pos.itemList.loadingCouponsErrorTitle.2",
             value: "Unable to load coupons",
diff --git a/Modules/Sources/PointOfSale/Presentation/CardReaderConnection/UI States/PointOfSaleItemListFullscreenErrorView.swift b/Modules/Sources/PointOfSale/Presentation/CardReaderConnection/UI States/PointOfSaleItemListFullscreenErrorView.swift
@@ -4,17 +4,24 @@ import SwiftUI
 struct PointOfSaleItemListFullscreenErrorView: View {
     private let error: PointOfSaleErrorState
     private let onAction: (() -> Void)?
+    private let onExit: (() -> Void)?
 
-    init(error: PointOfSaleErrorState, onAction: (() -> Void)? = nil) {
+    init(error: PointOfSaleErrorState, onAction: (() -> Void)? = nil, onExit: (() -> Void)? = nil) {
         self.error = error
         self.onAction = onAction
+        self.onExit = onExit
     }
 
     var body: some View {
-        PointOfSaleItemListFullscreenView {
-            POSListErrorView(error: error, onAction: onAction)
+        PointOfSaleItemListFullscreenView(showTitle: !isInitialCatalogSyncError) {
+            POSListErrorView(error: error, onAction: onAction, onExit: onExit)
         }
     }
+
+    // TODO: WOOMOB-1692 remove specialisation of errors if possible
+    private var isInitialCatalogSyncError: Bool {
+        error.errorType == .initialCatalogSyncError
+    }
 }
 
 #Preview {
diff --git a/Modules/Sources/PointOfSale/Presentation/CardReaderConnection/UI States/PointOfSaleItemListFullscreenView.swift b/Modules/Sources/PointOfSale/Presentation/CardReaderConnection/UI States/PointOfSaleItemListFullscreenView.swift
@@ -1,16 +1,25 @@
 import SwiftUI
 
 struct PointOfSaleItemListFullscreenView<Content: View>: View {
+    let showTitle: Bool
     let content: () -> Content
 
+    init(showTitle: Bool = true, @ViewBuilder content: @escaping () -> Content) {
+        self.showTitle = showTitle
+        self.content = content
+    }
+
     var body: some View {
         ZStack {
-            VStack(alignment: .center, spacing: PointOfSaleItemListErrorLayout.headerSpacing) {
-                POSHeaderTitleView(
-                    title: Localization.title,
-                    foregroundColor: .posOnSurfaceVariantHighest
-                )
-                Spacer()
+            // TODO: WOOMOB-1692 remove specialisation of errors if possible
+            if showTitle {
+                VStack(alignment: .center, spacing: PointOfSaleItemListErrorLayout.headerSpacing) {
+                    POSHeaderTitleView(
+                        title: Localization.title,
+                        foregroundColor: .posOnSurfaceVariantHighest
+                    )
+                    Spacer()
+                }
             }
 
             content()
diff --git a/Modules/Sources/PointOfSale/Presentation/PointOfSaleDashboardView.swift b/Modules/Sources/PointOfSale/Presentation/PointOfSaleDashboardView.swift
@@ -85,7 +85,9 @@ struct PointOfSaleDashboardView: View {
                             await posModel.couponsSearchController.loadItems(base: .root)
                         }
                     }
-                })
+                }, onExit: error.errorType == .initialCatalogSyncError ? { // TODO: WOOMOB-1692 remove specialisation of errors if possible
+                    dismiss()
+                } : nil)
             case .content:
                 contentView
                     .accessibilitySortPriority(2)
diff --git a/Modules/Sources/PointOfSale/Presentation/Reusable Views/POSListErrorView.swift b/Modules/Sources/PointOfSale/Presentation/Reusable Views/POSListErrorView.swift
@@ -6,14 +6,16 @@ struct POSListErrorView: View {
     @Environment(\.floatingControlAreaSize) private var floatingControlAreaSize: CGSize
     private let viewModel: POSListErrorViewModel
     private let onAction: (() -> Void)?
+    private let onExit: (() -> Void)?
 
     @State private var viewWidth: CGFloat = 0
 
     @Environment(\.keyboardObserver) private var keyboard
 
-    init(error: PointOfSaleErrorState, onAction: (() -> Void)? = nil) {
+    init(error: PointOfSaleErrorState, onAction: (() -> Void)? = nil, onExit: (() -> Void)? = nil) {
         self.viewModel = POSListErrorViewModel(error: error)
         self.onAction = onAction
+        self.onExit = onExit
     }
 
     var body: some View {
@@ -58,6 +60,18 @@ struct POSListErrorView: View {
                     .frame(width: viewWidth / 2)
                     .padding([.leading, .trailing])
                 }
+
+                if let onExit {
+                    Spacer().frame(height: POSSpacing.medium)
+                    Button(action: {
+                        onExit()
+                    }, label: {
+                        Text(Localization.exitButtonText)
+                    })
+                    .buttonStyle(POSOutlinedButtonStyle(size: .normal))
+                    .frame(width: viewWidth / 2)
+                    .padding([.leading, .trailing])
+                }
             }
             Spacer()
         }
@@ -87,6 +101,14 @@ struct POSListErrorViewModel {
     }
 }
 
+private enum Localization {
+    static let exitButtonText = NSLocalizedString(
+        "pos.listError.exitButton",
+        value: "Exit POS",
+        comment: "Button text to exit Point of Sale when there's a critical error"
+    )
+}
+
 #Preview {
     POSListErrorView(error: .errorCouponsDisabled, onAction: {})
 }
diff --git a/Modules/Sources/PointOfSale/ViewHelpers/PointOfSaleDashboardViewHelper.swift b/Modules/Sources/PointOfSale/ViewHelpers/PointOfSaleDashboardViewHelper.swift
@@ -36,8 +36,12 @@ struct PointOfSaleDashboardViewHelper {
 extension PointOfSaleDashboardView.ViewState {
     var showsFloatingControl: Bool {
         switch self {
-        case .content, .error, .unsupportedWidth:
+        case .content, .unsupportedWidth:
             return true
+        case .error(let error):
+            // Hide floating controls for initial catalog sync errors
+            // TODO: WOOMOB-1692 remove specialisation of errors if possible
+            return error.errorType != .initialCatalogSyncError
         case .loading, .ineligible:
             return false
         }
diff --git a/Modules/Sources/Yosemite/Tools/POS/POSCatalogSyncCoordinator.swift b/Modules/Sources/Yosemite/Tools/POS/POSCatalogSyncCoordinator.swift
@@ -98,24 +98,37 @@ public actor POSCatalogSyncCoordinator: POSCatalogSyncCoordinatorProtocol {
             throw POSCatalogSyncError.shouldNotSync
         }
 
-        if case .syncStarted = fullSyncStateModel.state[siteID] {
+        switch fullSyncStateModel.state[siteID] {
+        case .syncStarted, .initialSyncStarted:
             DDLogInfo("⚠️ POSCatalogSyncCoordinator: Sync already in progress for site \(siteID)")
             throw POSCatalogSyncError.syncAlreadyInProgress(siteID: siteID)
+        default:
+            break
         }
 
-        await emitSyncState(.syncStarted(siteID: siteID, isInitialSync: lastFullSyncDate(for: siteID) == nil))
+        let isFirstSync = await lastFullSyncDate(for: siteID) == nil
+
+        emitSyncState(isFirstSync ? .initialSyncStarted(siteID: siteID) : .syncStarted(siteID: siteID))
 
         DDLogInfo("🔄 POSCatalogSyncCoordinator starting full sync for site \(siteID)")
 
         do {
             _ = try await fullSyncService.startFullSync(for: siteID, regenerateCatalog: regenerateCatalog)
             emitSyncState(.syncCompleted(siteID: siteID))
         } catch AFError.explicitlyCancelled, is CancellationError {
-            emitSyncState(.syncFailed(siteID: siteID, error: POSCatalogSyncError.requestCancelled))
+            if isFirstSync {
+                emitSyncState(.initialSyncFailed(siteID: siteID, error: POSCatalogSyncError.requestCancelled))
+            } else {
+                emitSyncState(.syncFailed(siteID: siteID, error: POSCatalogSyncError.requestCancelled))
+            }
             throw POSCatalogSyncError.requestCancelled
         } catch {
             DDLogError("⛔️ POSCatalogSyncCoordinator failed to complete sync for site \(siteID): \(error)")
-            emitSyncState(.syncFailed(siteID: siteID, error: error))
+            if isFirstSync {
+                emitSyncState(.initialSyncFailed(siteID: siteID, error: error))
+            } else {
+                emitSyncState(.syncFailed(siteID: siteID, error: error))
+            }
             throw error
         }
 
@@ -303,7 +316,12 @@ public actor POSCatalogSyncCoordinator: POSCatalogSyncCoordinatorProtocol {
 private extension POSCatalogSyncCoordinator {
     func emitSyncState(_ state: POSCatalogSyncState) {
         let siteID: Int64 = switch state {
-        case .syncStarted(let id, _), .syncCompleted(let id), .syncFailed(let id, _), .syncNeverDone(let id):
+        case .initialSyncStarted(let id),
+                .syncStarted(let id),
+                .syncCompleted(let id),
+                .initialSyncFailed(let id, _),
+                .syncFailed(let id, _),
+                .syncNeverDone(let id):
             id
         }
 
@@ -320,21 +338,23 @@ public class POSCatalogSyncStateModel {
 
 
 public enum POSCatalogSyncState: Equatable {
-    case syncStarted(siteID: Int64, isInitialSync: Bool)
+    case initialSyncStarted(siteID: Int64)
+    case syncStarted(siteID: Int64)
     case syncCompleted(siteID: Int64)
+    case initialSyncFailed(siteID: Int64, error: Error)
     case syncFailed(siteID: Int64, error: Error)
     case syncNeverDone(siteID: Int64)
 
     public static func == (lhs: POSCatalogSyncState, rhs: POSCatalogSyncState) -> Bool {
         switch (lhs, rhs) {
-        case (.syncStarted(let lhsSiteID, let lhsInitial), .syncStarted(let rhsSiteID, let rhsInitial)):
-            return lhsSiteID == rhsSiteID && lhsInitial == rhsInitial
-        case (.syncCompleted(let lhsSiteID), .syncCompleted(let rhsSiteID)):
+        case (.initialSyncStarted(let lhsSiteID), .initialSyncStarted(let rhsSiteID)),
+            (.syncStarted(let lhsSiteID), .syncStarted(let rhsSiteID)),
+            (.syncCompleted(let lhsSiteID), .syncCompleted(let rhsSiteID)),
+            (.syncNeverDone(let lhsSiteID), .syncNeverDone(let rhsSiteID)):
             return lhsSiteID == rhsSiteID
-        case (.syncFailed(let lhsSiteID, let lhsError), .syncFailed(let rhsSiteID, let rhsError)):
+        case (.initialSyncFailed(let lhsSiteID, let lhsError), .initialSyncFailed(let rhsSiteID, let rhsError)),
+            (.syncFailed(let lhsSiteID, let lhsError), .syncFailed(let rhsSiteID, let rhsError)):
             return lhsSiteID == rhsSiteID && lhsError.localizedDescription == rhsError.localizedDescription
-        case (.syncNeverDone(let lhsSiteID), .syncNeverDone(let rhsSiteID)):
-            return lhsSiteID == rhsSiteID
         default:
             return false
         }
diff --git a/Modules/Tests/PointOfSaleTests/Controllers/PointOfSaleObservableItemsControllerTests.swift b/Modules/Tests/PointOfSaleTests/Controllers/PointOfSaleObservableItemsControllerTests.swift
diff --git a/Modules/Tests/YosemiteTests/Tools/POS/POSCatalogSyncCoordinatorTests.swift b/Modules/Tests/YosemiteTests/Tools/POS/POSCatalogSyncCoordinatorTests.swift

Original file line number	Diff line number	Diff line change
`@@ -115,7 +115,7 @@ protocol PointOfSaleAggregateModelProtocol {`
`115`	`115`	`publishPaymentMessages()`
`116`	`116`	`setupReaderReconnectionObservation()`
`117`	`117`	`setupPaymentSuccessObservation()`
`118`		`- performIncrementalSync()`
	`118`	`+ performInitialSyncIfNeeded()`
`119`	`119`	`}`
`120`	`120`	`}`
`121`	`121`
`@@ -623,6 +623,13 @@ private extension PointOfSaleAggregateModel {`
`623`	`623`	`try? await catalogSyncCoordinator.performIncrementalSync(for: siteID)`
`624`	`624`	`}`
`625`	`625`	`}`
	`626`	`+`
	`627`	`+ private func performInitialSyncIfNeeded() {`
	`628`	`+ guard let catalogSyncCoordinator else { return }`
	`629`	`+ Task {`
	`630`	`+ try? await catalogSyncCoordinator.performSmartSync(for: siteID)`
	`631`	`+ }`
	`632`	`+ }`
`626`	`633`	`}`
`627`	`634`
`628`	`635`	`#if DEBUG`
Original file line number	Diff line number	Diff line change
`@@ -85,7 +85,9 @@ struct PointOfSaleDashboardView: View {`
`85`	`85`	`await posModel.couponsSearchController.loadItems(base: .root)`
`86`	`86`	`}`
`87`	`87`	`}`
`88`		`- })`
	`88`	`+ }, onExit: error.errorType == .initialCatalogSyncError ? { // TODO: WOOMOB-1692 remove specialisation of errors if possible`
	`89`	`+ dismiss()`
	`90`	`+ } : nil)`
`89`	`91`	`case .content:`
`90`	`92`	`contentView`
`91`	`93`	`.accessibilitySortPriority(2)`