feat(realtime): cross-device realtime sync — protocol v1.0.0 + server/daemon/apple

apple/SitrepApp/Sitrep/MainTabView.swift

@@ -15,9 +15,16 @@ struct MainTabView: View {
     var body: some View {
         configuredTabs
             .safeAreaInset(edge: .top, spacing: 0) {
-                // Honesty first: a monitoring tool must SAY when it can't see.
-                if let err = model.lastError {
-                    ErrorBanner(text: err)
+                VStack(spacing: 0) {
+                    // Honesty first: a monitoring tool must SAY when it can't see.
+                    if let err = model.lastError {
+                        ErrorBanner(text: err)
+                    } else if let status = SyncStatusStrip.label(for: model.connectionPhase) {
+                        SyncStatusStrip(color: status.color, text: status.text)
+                    }
+                    if model.supersededNotice {
+                        SupersededBanner(isPresented: $model.supersededNotice)
+                    }
                 }
             }
     }
@@ -66,12 +73,22 @@ struct MainTabView: View {
         .onReceive(NotificationCenter.default.publisher(for: .sitrepOpenEvents)) { _ in
             selection = 2
         }
-        // Coming back to foreground: refresh immediately and revive the
-        // poll loop if anything killed it while suspended.
+        // Coming back to foreground: refresh immediately, (re)connect the
+        // realtime channel, and revive the HTTP fallback poll if anything
+        // killed it while suspended. While the WebSocket is live, refresh()
+        // only updates REST-only state (presence) — the reliable collections
+        // stay owned by deltas. Leaving the foreground closes the realtime
+        // connection — the interest lease simply lapses server-side rather
+        // than being explicitly released.
         .onChange(of: scenePhase) { _, phase in
-            if phase == .active {
+            switch phase {
+            case .active:
                 model.ensurePolling()
                 Task { await model.refresh() }
+            case .background:
+                model.leaveBackground()
+            default:
+                break
             }
         }
     }
@@ -94,6 +111,70 @@ struct ErrorBanner: View {
     }
 }
 
+/// A subtle, transient strip about THIS PHONE's realtime connection to the
+/// server — distinct from `PresencePill`/`PresenceRow`, which report
+/// whether the Mac/Agent is reporting in. Reuses the same dot-plus-caption
+/// language rather than a new visual system; shows nothing once the
+/// connection is `.live` (the common case), so it stays out of the way.
+struct SyncStatusStrip: View {
+    let color: Color
+    let text: String
+
+    /// nil means "healthy, show nothing" — only `.live` and `.idle` (not yet
+    /// started) count as nothing-to-say; every other phase is transient and
+    /// worth a one-line, low-emphasis mention.
+    static func label(for phase: RealtimeClient.Phase) -> (color: Color, text: String)? {
+        switch phase {
+        case .idle, .live: nil
+        case .connecting, .handshaking: (.gray, "正在连接实时同步…")
+        case .subscribed: (.gray, "正在同步…")
+        case .failed: (.orange, "实时同步中断，已切换到低频刷新")
+        }
+    }
+
+    var body: some View {
+        HStack(spacing: 6) {
+            Circle().fill(color).frame(width: 6, height: 6)
+            Text(text).font(.caption2.weight(.medium)).foregroundStyle(.secondary)
+        }
+        .frame(maxWidth: .infinity)
+        .padding(.vertical, 4)
+        .background(.background.secondary)
+        .transition(.move(edge: .top).combined(with: .opacity))
+        .animation(.default, value: text)
+    }
+}
+
+/// One-shot, non-disruptive notice for SPEC.md §9.4 `superseded`: this
+/// device's realtime connection was replaced by another connection using
+/// the same credential — most often the same phone's own connection racing
+/// itself across a fast background/foreground cycle, but possibly a sign
+/// the credential is in use elsewhere. Tap to dismiss; not repeated.
+struct SupersededBanner: View {
+    @Binding var isPresented: Bool
+
+    var body: some View {
+        Button {
+            withAnimation { isPresented = false }
+        } label: {
+            Label("这台设备的实时连接被另一个连接取代，可能是该凭据在别处也在使用", systemImage: "info.circle")
+                .font(.caption.weight(.medium))
+                .lineLimit(2)
+                .frame(maxWidth: .infinity, alignment: .leading)
+                .padding(.horizontal, 12)
+                .padding(.vertical, 7)
+        }
+        .buttonStyle(.plain)
+        .background(.blue.opacity(0.12))
+        .foregroundStyle(.blue)
+        .transition(.move(edge: .top).combined(with: .opacity))
+        .task {
+            try? await Task.sleep(for: .seconds(6))
+            withAnimation { isPresented = false }
+        }
+    }
+}
+
 /// "Is my Mac alive" — the first question a monitoring tool must answer.
 /// Green: agent heartbeat or ingest within a minute. Orange: minutes quiet.
 /// Red: nothing for 10+ minutes.