Add order tail flows and migrate queue, message, settlement, and audit modules.

Wire deposit orders, historical shooting, and multi-travel uploads into Orders, and replace home placeholders for queue management, message center, scenic settlement, and withdrawal audit.

Co-authored-by: Cursor <cursoragent@cursor.com>

suixinkan/Features/Home/Home.md

@@ -33,6 +33,6 @@ Home 模块负责登录后的首页工作台，包括当前景区展示、工作
 
 ## 后续迁移
 
-目前 `payment_collection`、`payment_qr`、`payment_code` 已由 `Features/Payment` 的真实收款页面接管，`wallet` 已由 `Features/Wallet` 的真实钱包页面接管，`scenicselection`、`permission_apply`、`permission_apply_status`、`scenicapplication` 已由 `Features/ScenicPermission` 接管，`task_management`、`task_management_editor`、`task_create` 已由 `Features/Tasks` 接管，`cloud_management`、`cloud_storage_transit`、`asset_management`、`material_upload`、`album_list`、`album_trailer`、`sample_management`、`sample_upload` 已由 `Features/Assets` 接管，`checkin_points` 已由 `Features/PunchPoint` 接管，`location_report` 和 `location_report_history` 已由 `Features/LocationReport` 接管，`pm`、`project_edit` 已由 `Features/Projects` 的摄影师项目管理接管，`pm_manager` 已由店铺项目管理接管，`schedule_management` 已由 `Features/Schedule` 接管，`registration_invitation`、`photographer_invite`、`invite_record` 已由 `Features/Invite` 接管。`withdrawal_audit` 仍属于后台性质的提现审核管理模块，`scenic_settlement` 和 `scenic_settlement_review` 仍属于独立结算模块，本轮保留占位，后续应作为独立功能迁移。
+目前 `payment_collection`、`payment_qr`、`payment_code` 已由 `Features/Payment` 的真实收款页面接管，`wallet` 已由 `Features/Wallet` 的真实钱包页面接管，`scenicselection`、`permission_apply`、`permission_apply_status`、`scenicapplication` 已由 `Features/ScenicPermission` 接管，`task_management`、`task_management_editor`、`task_create` 已由 `Features/Tasks` 接管，`cloud_management`、`cloud_storage_transit`、`asset_management`、`material_upload`、`album_list`、`album_trailer`、`sample_management`、`sample_upload` 已由 `Features/Assets` 接管，`checkin_points` 已由 `Features/PunchPoint` 接管，`location_report` 和 `location_report_history` 已由 `Features/LocationReport` 接管，`pm`、`project_edit` 已由 `Features/Projects` 的摄影师项目管理接管，`pm_manager` 已由店铺项目管理接管，`schedule_management` 已由 `Features/Schedule` 接管，`registration_invitation`、`photographer_invite`、`invite_record` 已由 `Features/Invite` 接管，`deposit_order_detail`、`deposit_order`、`deposit_order_shooting_info` 已由 `Features/Orders` 的押金订单页接管，`withdrawal_audit` 已由 `Features/WithdrawalAudit` 接管，`scenic_settlement` 和 `scenic_settlement_review` 已由 `Features/ScenicSettlement` 接管，`message_center` 已由 `Features/MessageCenter` 接管，`/scenic-queue` 和 `queue_management` 已由 `Features/QueueManagement` 接管。
 
 后续迁移具体首页子模块时，应先在 `HomeRoute` 增加目标页面，再更新 `HomeMenuRouter.resolve` 对应 URI 的映射，并同步补充单元测试。

suixinkan/Features/Home/Models/HomeMenuItem.swift

@@ -54,6 +54,12 @@ enum HomeRoute: Hashable {
     case punchPointQR(id: Int, title: String, qrURL: String)
     case locationReport
     case locationReportHistory
+    case depositOrders
+    case withdrawalAudit
+    case scenicSettlement
+    case scenicSettlementReview
+    case messageCenter
+    case queueManagement
     case modulePlaceholder(uri: String, title: String)
 }
 

suixinkan/Features/Home/Routing/HomeMenuRouter.swift

@@ -127,6 +127,18 @@ enum HomeMenuRouter {
             return .destination(.locationReport)
         case "location_report_history":
             return .destination(.locationReportHistory)
+        case "deposit_order_detail", "deposit_order", "deposit_order_shooting_info":
+            return .destination(.depositOrders)
+        case "withdrawal_audit":
+            return .destination(.withdrawalAudit)
+        case "scenic_settlement":
+            return .destination(.scenicSettlement)
+        case "scenic_settlement_review":
+            return .destination(.scenicSettlementReview)
+        case "message_center":
+            return .destination(.messageCenter)
+        case "/scenic-queue", "queue_management":
+            return .destination(.queueManagement)
         case "store", "more_functions":
             return .destination(.moreFunctions)
         case "fly", "pilot_controller":
@@ -135,17 +147,8 @@ enum HomeMenuRouter {
                 title: title.isEmpty ? self.title(for: uri) : title,
                 reason: "DJI/飞控模块已明确不纳入 iOS 迁移和后续开发范围。"
             )
-        case "message_center",
-             "/scenic-queue",
-             "queue_management",
-             "deposit_order_detail",
-             "deposit_order",
-             "deposit_order_shooting_info",
-             "withdrawal_audit",
-             "live_stream_management",
+        case "live_stream_management",
              "live_album",
-             "scenic_settlement",
-             "scenic_settlement_review",
              "operating-area",
              "pilot_cert":
             let resolvedTitle = title.isEmpty ? self.title(for: uri) : title

suixinkan/Features/Home/Views/HomeSupportViews.swift

@@ -84,6 +84,18 @@ extension HomeRoute {
             LocationReportView()
         case .locationReportHistory:
             LocationReportHistoryView()
+        case .depositOrders:
+            DepositOrderEntryView()
+        case .withdrawalAudit:
+            WithdrawalAuditView()
+        case .scenicSettlement:
+            ScenicSettlementView()
+        case .scenicSettlementReview:
+            ScenicSettlementReviewView()
+        case .messageCenter:
+            MessageCenterView()
+        case .queueManagement:
+            QueueManagementView()
         case let .modulePlaceholder(uri, title):
             HomeMigrationModuleView(title: title, uri: uri)
         }

suixinkan/Features/MessageCenter/API/MessageCenterAPI.swift

@@ -0,0 +1,74 @@
+//
+//  MessageCenterAPI.swift
+//  suixinkan
+//
+//  Created by Codex on 2026/6/25.
+//
+
+import Foundation
+import Observation
+
+/// 消息中心服务协议，定义消息列表、已读和删除能力。
+@MainActor
+protocol MessageCenterServing {
+    /// 获取消息列表，使用 last_id 游标分页。
+    func messageList(lastId: Int, limit: Int, unread: Int) async throws -> MessageListResponse
+
+    /// 标记单条消息为已读。
+    func messageRead(id: Int) async throws
+
+    /// 删除单条消息。
+    func messageDelete(id: Int) async throws
+}
+
+@MainActor
+@Observable
+/// 消息中心 API，封装消息相关网络请求。
+final class MessageCenterAPI {
+    @ObservationIgnored private let client: APIClient
+
+    /// 初始化消息中心 API，并注入共享网络客户端。
+    init(client: APIClient) {
+        self.client = client
+    }
+
+    /// 获取消息列表，使用 last_id 游标分页。
+    func messageList(lastId: Int = 0, limit: Int = 20, unread: Int = 0) async throws -> MessageListResponse {
+        try await client.send(
+            APIRequest(
+                method: .get,
+                path: "/api/app/msg/list",
+                queryItems: [
+                    URLQueryItem(name: "last_id", value: String(max(lastId, 0))),
+                    URLQueryItem(name: "limit", value: String(max(limit, 1))),
+                    URLQueryItem(name: "unread", value: String(max(unread, 0)))
+                ]
+            )
+        )
+    }
+
+    /// 标记单条消息为已读。
+    func messageRead(id: Int) async throws {
+        let _: EmptyPayload = try await client.send(
+            APIRequest(
+                method: .post,
+                path: "/api/app/msg/read",
+                queryItems: [URLQueryItem(name: "id", value: String(id))],
+                body: EmptyPayload()
+            )
+        )
+    }
+
+    /// 删除单条消息。
+    func messageDelete(id: Int) async throws {
+        let _: EmptyPayload = try await client.send(
+            APIRequest(
+                method: .post,
+                path: "/api/app/msg/delete",
+                body: MessageDeleteRequest(id: id)
+            )
+        )
+    }
+}
+
+extension MessageCenterAPI: MessageCenterServing {}

suixinkan/Features/MessageCenter/MessageCenter.md

@@ -0,0 +1,18 @@
+# 消息中心模块
+
+## 模块职责
+
+`Features/MessageCenter` 承接首页 `message_center` 权限入口，负责消息列表、未读筛选、标记已读、全部已读、详情展示和删除。
+
+## 代码结构
+
+- `MessageCenterAPI`：封装 `/api/app/msg/list`、`/api/app/msg/read`、`/api/app/msg/delete`。
+- `MessageCenterViewModel`：管理 `last_id` 游标分页、筛选、去重排序、已读和删除后的本地状态同步。
+- `MessageCenterView`：提供统计卡、全部/未读筛选、列表、失败重试、空态、详情和删除确认。
+
+## 数据与边界
+
+- 消息详情不请求独立详情接口，直接使用列表返回的标题、内容、类型和推送时间。
+- 点击消息时先调用已读接口，再进入详情，并将本地未读状态同步为已读。
+- 全部已读沿用旧 iOS 能力，逐条调用已读接口；任一失败时保留原状态并透出错误。
+- 首屏刷新失败会清空旧数据和分页状态，加载更多失败保留当前列表。

suixinkan/Features/MessageCenter/Models/MessageCenterModels.swift

@@ -0,0 +1,226 @@
+//
+//  MessageCenterModels.swift
+//  suixinkan
+//
+//  Created by Codex on 2026/6/25.
+//
+
+import Foundation
+import SwiftUI
+
+/// 消息中心列表响应，使用 last_id 游标分页。
+struct MessageListResponse: Decodable, Equatable {
+    let hasMore: Bool
+    let lastId: Int
+    let items: [MessageEntity]
+
+    enum CodingKeys: String, CodingKey {
+        case hasMore = "has_more"
+        case lastId = "last_id"
+        case items
+    }
+
+    /// 创建空消息响应，主要用于测试和失败兜底。
+    init(hasMore: Bool = false, lastId: Int = 0, items: [MessageEntity] = []) {
+        self.hasMore = hasMore
+        self.lastId = lastId
+        self.items = items
+    }
+
+    /// 宽松解码分页状态，兼容后端数字/字符串/布尔类型不稳定。
+    init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        hasMore = try container.decodeLossyBool(forKey: .hasMore) ?? false
+        lastId = try container.decodeLossyInt(forKey: .lastId) ?? 0
+        items = try container.decodeIfPresent([MessageEntity].self, forKey: .items) ?? []
+    }
+}
+
+/// 后端消息实体。
+struct MessageEntity: Decodable, Equatable, Identifiable {
+    let id: Int
+    let type: Int
+    let typeName: String
+    let title: String
+    let content: String
+    let pushAt: String
+    let createdAt: String
+    let isRead: Bool
+
+    enum CodingKeys: String, CodingKey {
+        case id
+        case type
+        case typeName = "type_name"
+        case title
+        case content
+        case pushAt = "push_at"
+        case createdAt = "created_at"
+        case isRead = "is_read"
+    }
+
+    /// 创建消息实体，主要用于测试。
+    init(
+        id: Int,
+        type: Int,
+        typeName: String = "",
+        title: String = "",
+        content: String = "",
+        pushAt: String = "",
+        createdAt: String = "",
+        isRead: Bool = false
+    ) {
+        self.id = id
+        self.type = type
+        self.typeName = typeName
+        self.title = title
+        self.content = content
+        self.pushAt = pushAt
+        self.createdAt = createdAt
+        self.isRead = isRead
+    }
+
+    /// 宽松解码消息字段，避免单条异常字段导致整页失败。
+    init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        id = try container.decodeLossyInt(forKey: .id) ?? 0
+        type = try container.decodeLossyInt(forKey: .type) ?? 0
+        typeName = try container.decodeLossyString(forKey: .typeName)
+        title = try container.decodeLossyString(forKey: .title)
+        content = try container.decodeLossyString(forKey: .content)
+        pushAt = try container.decodeLossyString(forKey: .pushAt)
+        createdAt = try container.decodeLossyString(forKey: .createdAt)
+        isRead = try container.decodeLossyBool(forKey: .isRead) ?? false
+    }
+}
+
+/// 删除消息请求体。
+struct MessageDeleteRequest: Encodable {
+    let id: Int
+}
+
+/// 页面展示用消息类型。
+enum MessageType: Equatable {
+    case order
+    case writeOff
+    case system
+
+    /// 消息类型图标。
+    var iconName: String {
+        switch self {
+        case .order:
+            return "cart.fill"
+        case .writeOff:
+            return "qrcode.viewfinder"
+        case .system:
+            return "bell.badge.fill"
+        }
+    }
+
+    /// 消息类型标题。
+    var title: String {
+        switch self {
+        case .order:
+            return "订单"
+        case .writeOff:
+            return "核销"
+        case .system:
+            return "系统"
+        }
+    }
+
+    /// 消息类型颜色。
+    var color: Color {
+        switch self {
+        case .order:
+            return AppDesign.primary
+        case .writeOff:
+            return AppDesign.success
+        case .system:
+            return AppDesign.warning
+        }
+    }
+}
+
+/// 页面展示用消息项。
+struct MessageItem: Identifiable, Equatable {
+    let id: String
+    let msgId: Int?
+    let title: String
+    let detail: String
+    let time: String
+    var isRead: Bool
+    let type: MessageType
+}
+
+/// 消息筛选项。
+enum MessageFilter: Int, CaseIterable, Identifiable {
+    case all = 0
+    case unread = 1
+
+    var id: Int { rawValue }
+
+    /// 筛选标题。
+    var title: String {
+        switch self {
+        case .all:
+            return "全部"
+        case .unread:
+            return "未读"
+        }
+    }
+}
+
+private extension KeyedDecodingContainer {
+    /// 将 String、数字和 Bool 宽松解码为字符串。
+    func decodeLossyString(forKey key: Key) throws -> String {
+        if let value = try? decodeIfPresent(String.self, forKey: key) {
+            return value
+        }
+        if let value = try? decodeIfPresent(Int.self, forKey: key) {
+            return String(value)
+        }
+        if let value = try? decodeIfPresent(Double.self, forKey: key) {
+            return String(value)
+        }
+        if let value = try? decodeIfPresent(Bool.self, forKey: key) {
+            return value ? "1" : "0"
+        }
+        return ""
+    }
+
+    /// 将 String、数字和 Bool 宽松解码为 Int。
+    func decodeLossyInt(forKey key: Key) throws -> Int? {
+        if let value = try? decodeIfPresent(Int.self, forKey: key) {
+            return value
+        }
+        if let value = try? decodeIfPresent(Double.self, forKey: key) {
+            return Int(value)
+        }
+        if let value = try? decodeIfPresent(String.self, forKey: key),
+           case let text = value.trimmingCharacters(in: .whitespacesAndNewlines),
+           !text.isEmpty {
+            return Int(text) ?? Int(Double(text) ?? 0)
+        }
+        if let value = try? decodeIfPresent(Bool.self, forKey: key) {
+            return value ? 1 : 0
+        }
+        return nil
+    }
+
+    /// 将 String、数字和 Bool 宽松解码为 Bool。
+    func decodeLossyBool(forKey key: Key) throws -> Bool? {
+        if let value = try? decodeIfPresent(Bool.self, forKey: key) {
+            return value
+        }
+        if let value = try? decodeIfPresent(Int.self, forKey: key) {
+            return value != 0
+        }
+        if let value = try? decodeIfPresent(String.self, forKey: key),
+           case let text = value.trimmingCharacters(in: .whitespacesAndNewlines).lowercased(),
+           !text.isEmpty {
+            if ["1", "true", "yes"].contains(text) { return true }
+            if ["0", "false", "no"].contains(text) { return false }
+        }
+        return nil
+    }
+}

suixinkan/Features/MessageCenter/ViewModels/MessageCenterViewModel.swift

@@ -0,0 +1,170 @@
+//
+//  MessageCenterViewModel.swift
+//  suixinkan
+//
+//  Created by Codex on 2026/6/25.
+//
+
+import Foundation
+import Observation
+
+@MainActor
+@Observable
+/// 消息中心 ViewModel，负责消息分页、筛选、已读和删除。
+final class MessageCenterViewModel {
+    var messages: [MessageItem] = []
+    var selectedFilter: MessageFilter = .all
+    var isLoading = false
+    var isLoadingMore = false
+    var loadFailed = false
+    var loadFailureReason: String?
+    var message: String?
+
+    private(set) var hasMoreMessages = false
+    private(set) var lastId = 0
+    private let pageSize = 20
+
+    /// 未读消息数量。
+    var unreadCount: Int {
+        messages.filter { !$0.isRead }.count
+    }
+
+    /// 当前筛选说明。
+    var filterDescription: String {
+        selectedFilter == .all ? "显示全部消息" : "仅显示未读消息"
+    }
+
+    /// 切换筛选并重新加载首屏。
+    func selectFilter(_ filter: MessageFilter, api: any MessageCenterServing) async {
+        guard selectedFilter != filter else { return }
+        selectedFilter = filter
+        await reloadFirstPage(api: api)
+    }
+
+    /// 重新加载首屏消息，失败时清空旧数据。
+    func reloadFirstPage(api: any MessageCenterServing) async {
+        isLoading = true
+        loadFailed = false
+        loadFailureReason = nil
+        message = nil
+        defer { isLoading = false }
+
+        do {
+            let response = try await api.messageList(lastId: 0, limit: pageSize, unread: selectedFilter.rawValue)
+            messages = mapMessages(response.items)
+            hasMoreMessages = response.hasMore
+            lastId = response.lastId
+        } catch {
+            clearMessages()
+            loadFailed = true
+            loadFailureReason = error.localizedDescription
+            message = error.localizedDescription
+        }
+    }
+
+    /// 加载更多消息，失败时保留当前数据和分页状态。
+    func loadMore(api: any MessageCenterServing) async {
+        guard hasMoreMessages, !isLoadingMore, !isLoading else { return }
+        isLoadingMore = true
+        message = nil
+        defer { isLoadingMore = false }
+
+        do {
+            let response = try await api.messageList(lastId: lastId, limit: pageSize, unread: selectedFilter.rawValue)
+            messages.append(contentsOf: mapMessages(response.items))
+            messages = deduplicatedAndSorted(messages)
+            hasMoreMessages = response.hasMore
+            lastId = response.lastId
+        } catch {
+            message = error.localizedDescription
+        }
+    }
+
+    /// 标记单条消息为已读，接口成功后再更新本地状态。
+    func markAsRead(api: any MessageCenterServing, item: MessageItem) async throws {
+        guard !item.isRead, let msgId = item.msgId else { return }
+        try await api.messageRead(id: msgId)
+        guard let index = messages.firstIndex(where: { $0.id == item.id }) else { return }
+        messages[index].isRead = true
+    }
+
+    /// 将当前列表中的未读消息逐条标记为已读。
+    func markAllAsRead(api: any MessageCenterServing) async throws {
+        let original = messages
+        do {
+            for item in messages where !item.isRead {
+                if let msgId = item.msgId {
+                    try await api.messageRead(id: msgId)
+                }
+            }
+            messages = messages.map { item in
+                var next = item
+                next.isRead = true
+                return next
+            }
+        } catch {
+            messages = original
+            throw error
+        }
+    }
+
+    /// 删除消息，接口成功后再移除本地列表。
+    func deleteMessage(api: any MessageCenterServing, item: MessageItem) async throws {
+        if let msgId = item.msgId {
+            try await api.messageDelete(id: msgId)
+        }
+        messages.removeAll { $0.id == item.id }
+    }
+
+    /// 将后端实体转换为页面展示实体。
+    func mapMessages(_ source: [MessageEntity]) -> [MessageItem] {
+        source.map { item in
+            MessageItem(
+                id: "msg_\(item.id)",
+                msgId: item.id,
+                title: item.title.trimmingCharacters(in: .whitespacesAndNewlines).nonEmpty
+                    ?? item.typeName.trimmingCharacters(in: .whitespacesAndNewlines).nonEmpty
+                    ?? "系统通知",
+                detail: item.content,
+                time: item.pushAt.trimmingCharacters(in: .whitespacesAndNewlines).nonEmpty
+                    ?? item.createdAt.trimmingCharacters(in: .whitespacesAndNewlines).nonEmpty
+                    ?? "0000-00-00 00:00",
+                isRead: item.isRead,
+                type: Self.messageType(from: item.type)
+            )
+        }
+    }
+
+    /// 将后端类型映射为页面消息类型。
+    static func messageType(from value: Int) -> MessageType {
+        switch value {
+        case 1:
+            return .order
+        case 2:
+            return .writeOff
+        default:
+            return .system
+        }
+    }
+
+    private func deduplicatedAndSorted(_ source: [MessageItem]) -> [MessageItem] {
+        var unique: [String: MessageItem] = [:]
+        for item in source {
+            unique[item.id] = item
+        }
+        return unique.values.sorted { $0.time > $1.time }
+    }
+
+    private func clearMessages() {
+        messages = []
+        hasMoreMessages = false
+        lastId = 0
+        isLoadingMore = false
+    }
+}
+
+private extension String {
+    var nonEmpty: String? {
+        isEmpty ? nil : self
+    }
+}

suixinkan/Features/MessageCenter/Views/MessageCenterViews.swift

@@ -0,0 +1,302 @@
+//
+//  MessageCenterViews.swift
+//  suixinkan
+//
+//  Created by Codex on 2026/6/25.
+//
+
+import SwiftUI
+
+/// 消息中心页面，展示消息列表、筛选、已读和删除入口。
+struct MessageCenterView: View {
+    @Environment(MessageCenterAPI.self) private var messageAPI
+    @Environment(ToastCenter.self) private var toastCenter
+    @State private var viewModel = MessageCenterViewModel()
+    @State private var selectedMessage: MessageItem?
+    @State private var processingMessageId: String?
+
+    var body: some View {
+        VStack(spacing: 0) {
+            header
+            content
+        }
+        .background(Color(hex: 0xF5F7FA).ignoresSafeArea())
+        .navigationTitle("消息中心")
+        .navigationBarTitleDisplayMode(.inline)
+        .toolbar {
+            ToolbarItem(placement: .topBarTrailing) {
+                Button("全部已读") {
+                    Task { await markAllAsRead() }
+                }
+                .font(.system(size: AppMetrics.FontSize.subheadline, weight: .semibold))
+                .disabled(viewModel.unreadCount == 0 || viewModel.messages.isEmpty)
+            }
+        }
+        .sheet(item: $selectedMessage) { item in
+            MessageDetailView(item: item) { deleteItem in
+                await deleteMessage(deleteItem)
+            }
+        }
+        .task {
+            if viewModel.messages.isEmpty {
+                await viewModel.reloadFirstPage(api: messageAPI)
+            }
+        }
+        .refreshable {
+            await viewModel.reloadFirstPage(api: messageAPI)
+        }
+    }
+
+    private var header: some View {
+        VStack(alignment: .leading, spacing: AppMetrics.Spacing.medium) {
+            HStack(spacing: AppMetrics.Spacing.medium) {
+                messageMetric(title: "消息总数", value: "\(viewModel.messages.count)", color: AppDesign.primary)
+                messageMetric(title: "未读消息", value: "\(viewModel.unreadCount)", color: AppDesign.warning)
+            }
+
+            Picker("消息筛选", selection: Binding(
+                get: { viewModel.selectedFilter },
+                set: { filter in
+                    Task { await viewModel.selectFilter(filter, api: messageAPI) }
+                }
+            )) {
+                ForEach(MessageFilter.allCases) { filter in
+                    Text(filter.title).tag(filter)
+                }
+            }
+            .pickerStyle(.segmented)
+
+            Text(viewModel.filterDescription)
+                .font(.system(size: AppMetrics.FontSize.caption))
+                .foregroundStyle(AppDesign.textSecondary)
+        }
+        .padding(AppMetrics.Spacing.pageHorizontal)
+        .background(.white)
+    }
+
+    @ViewBuilder
+    private var content: some View {
+        if viewModel.isLoading && viewModel.messages.isEmpty {
+            ProgressView("加载中...")
+                .frame(maxWidth: .infinity, maxHeight: .infinity)
+        } else if viewModel.loadFailed {
+            ContentUnavailableView {
+                Label("消息加载失败", systemImage: "exclamationmark.triangle")
+            } description: {
+                Text(viewModel.loadFailureReason ?? "请稍后重试")
+            } actions: {
+                Button("重新加载") {
+                    Task { await viewModel.reloadFirstPage(api: messageAPI) }
+                }
+                .buttonStyle(.borderedProminent)
+            }
+            .frame(maxWidth: .infinity, maxHeight: .infinity)
+        } else if viewModel.messages.isEmpty {
+            ContentUnavailableView("暂无消息", systemImage: "bell", description: Text("暂无可查看的系统消息"))
+                .frame(maxWidth: .infinity, maxHeight: .infinity)
+        } else {
+            ScrollView {
+                LazyVStack(spacing: AppMetrics.Spacing.medium) {
+                    ForEach(viewModel.messages) { item in
+                        Button {
+                            Task { await openMessage(item) }
+                        } label: {
+                            MessageRow(item: item, processing: processingMessageId == item.id)
+                        }
+                        .buttonStyle(.plain)
+                        .onAppear {
+                            if item.id == viewModel.messages.last?.id {
+                                Task { await viewModel.loadMore(api: messageAPI) }
+                            }
+                        }
+                    }
+
+                    if viewModel.isLoadingMore {
+                        ProgressView()
+                            .frame(maxWidth: .infinity)
+                            .padding(.vertical, AppMetrics.Spacing.medium)
+                    }
+                }
+                .padding(AppMetrics.Spacing.pageHorizontal)
+            }
+        }
+    }
+
+    private func messageMetric(title: String, value: String, color: Color) -> some View {
+        VStack(alignment: .leading, spacing: 4) {
+            Text(title)
+                .font(.system(size: AppMetrics.FontSize.caption))
+                .foregroundStyle(AppDesign.textSecondary)
+            Text(value)
+                .font(.system(size: 24, weight: .bold))
+                .foregroundStyle(color)
+                .lineLimit(1)
+        }
+        .frame(maxWidth: .infinity, alignment: .leading)
+        .padding(AppMetrics.Spacing.medium)
+        .background(color.opacity(0.08), in: RoundedRectangle(cornerRadius: AppMetrics.CornerRadius.card))
+    }
+
+    private func openMessage(_ item: MessageItem) async {
+        processingMessageId = item.id
+        defer { processingMessageId = nil }
+        do {
+            try await viewModel.markAsRead(api: messageAPI, item: item)
+        } catch {
+            toastCenter.show(error.localizedDescription)
+        }
+        selectedMessage = viewModel.messages.first(where: { $0.id == item.id }) ?? item
+    }
+
+    private func markAllAsRead() async {
+        do {
+            try await viewModel.markAllAsRead(api: messageAPI)
+            toastCenter.show("已全部标记为已读")
+        } catch {
+            toastCenter.show(error.localizedDescription)
+        }
+    }
+
+    @discardableResult
+    private func deleteMessage(_ item: MessageItem) async -> Bool {
+        processingMessageId = item.id
+        defer { processingMessageId = nil }
+        do {
+            try await viewModel.deleteMessage(api: messageAPI, item: item)
+            toastCenter.show("消息已删除")
+            return true
+        } catch {
+            toastCenter.show(error.localizedDescription)
+            return false
+        }
+    }
+}
+
+private struct MessageRow: View {
+    let item: MessageItem
+    let processing: Bool
+
+    var body: some View {
+        HStack(alignment: .top, spacing: AppMetrics.Spacing.medium) {
+            ZStack {
+                RoundedRectangle(cornerRadius: 8)
+                    .fill(item.type.color.opacity(0.12))
+                Image(systemName: item.type.iconName)
+                    .font(.system(size: 20, weight: .semibold))
+                    .foregroundStyle(item.type.color)
+            }
+            .frame(width: 48, height: 48)
+
+            VStack(alignment: .leading, spacing: 8) {
+                HStack(alignment: .firstTextBaseline, spacing: 8) {
+                    Text(item.title)
+                        .font(.system(size: AppMetrics.FontSize.body, weight: .semibold))
+                        .foregroundStyle(AppDesign.textPrimary)
+                        .lineLimit(1)
+                    if !item.isRead {
+                        Circle()
+                            .fill(Color(hex: 0xEF4444))
+                            .frame(width: 7, height: 7)
+                    }
+                    Spacer()
+                    Text(item.type.title)
+                        .font(.system(size: AppMetrics.FontSize.caption, weight: .medium))
+                        .foregroundStyle(item.type.color)
+                }
+
+                Text(item.detail.isEmpty ? "暂无消息内容" : item.detail)
+                    .font(.system(size: AppMetrics.FontSize.subheadline))
+                    .foregroundStyle(AppDesign.textSecondary)
+                    .lineLimit(2)
+
+                Text(item.time)
+                    .font(.system(size: AppMetrics.FontSize.caption))
+                    .foregroundStyle(Color(hex: 0x9CA3AF))
+            }
+        }
+        .padding(AppMetrics.Spacing.medium)
+        .background(.white, in: RoundedRectangle(cornerRadius: AppMetrics.CornerRadius.card))
+        .overlay {
+            RoundedRectangle(cornerRadius: AppMetrics.CornerRadius.card)
+                .stroke(Color(hex: item.isRead ? 0xECEFF3 : 0xBFD7FF), lineWidth: 1)
+        }
+        .opacity(processing ? 0.6 : 1)
+    }
+}
+
+private struct MessageDetailView: View {
+    let item: MessageItem
+    let onDelete: (MessageItem) async -> Bool
+    @Environment(\.dismiss) private var dismiss
+    @State private var showDeleteConfirm = false
+    @State private var deleting = false
+
+    var body: some View {
+        NavigationStack {
+            ScrollView {
+                VStack(spacing: AppMetrics.Spacing.large) {
+                    ZStack {
+                        RoundedRectangle(cornerRadius: 12)
+                            .fill(item.type.color.opacity(0.12))
+                        Image(systemName: item.type.iconName)
+                            .font(.system(size: 38, weight: .bold))
+                            .foregroundStyle(item.type.color)
+                    }
+                    .frame(width: 82, height: 82)
+
+                    VStack(spacing: AppMetrics.Spacing.small) {
+                        Text(item.title)
+                            .font(.system(size: AppMetrics.FontSize.title2, weight: .bold))
+                            .foregroundStyle(AppDesign.textPrimary)
+                            .multilineTextAlignment(.center)
+                        Text(item.time)
+                            .font(.system(size: AppMetrics.FontSize.subheadline))
+                            .foregroundStyle(AppDesign.textSecondary)
+                    }
+
+                    Text(item.detail.isEmpty ? "暂无消息内容" : item.detail)
+                        .font(.system(size: AppMetrics.FontSize.body))
+                        .foregroundStyle(AppDesign.textPrimary)
+                        .lineSpacing(6)
+                        .frame(maxWidth: .infinity, alignment: .leading)
+                        .padding(AppMetrics.Spacing.large)
+                        .background(.white, in: RoundedRectangle(cornerRadius: AppMetrics.CornerRadius.card))
+                }
+                .padding(AppMetrics.Spacing.pageHorizontal)
+            }
+            .background(Color(hex: 0xF5F7FA).ignoresSafeArea())
+            .navigationTitle("消息详情")
+            .navigationBarTitleDisplayMode(.inline)
+            .toolbar {
+                ToolbarItem(placement: .cancellationAction) {
+                    Button("关闭") { dismiss() }
+                }
+                ToolbarItem(placement: .topBarTrailing) {
+                    Button(role: .destructive) {
+                        showDeleteConfirm = true
+                    } label: {
+                        if deleting {
+                            ProgressView()
+                        } else {
+                            Image(systemName: "trash")
+                        }
+                    }
+                    .disabled(deleting || item.msgId == nil)
+                }
+            }
+            .alert("确认删除", isPresented: $showDeleteConfirm) {
+                Button("取消", role: .cancel) {}
+                Button("删除", role: .destructive) {
+                    Task {
+                        deleting = true
+                        let success = await onDelete(item)
+                        deleting = false
+                        if success { dismiss() }
+                    }
+                }
+            } message: {
+                Text("删除后不可恢复，是否继续？")
+            }
+        }
+    }
+}

suixinkan/Features/Orders/API/OrdersAPI.swift

@@ -32,6 +32,30 @@ protocol OrderServing {
 
     /// 获取门店订单详情。
     func storeOrderDetail(storeId: Int, orderNumber: String) async throws -> StoreOrderDetailResponse
+
+    /// 获取押金订单列表。
+    func depositOrderList(scenicId: Int, page: Int, pageSize: Int) async throws -> ListPayload<DepositOrderListItem>
+
+    /// 核销押金订单。
+    func depositOrderWriteOff(orderNumber: String) async throws
+
+    /// 申请押金订单退款。
+    func depositOrderRefund(orderNumber: String, refundReason: String) async throws
+
+    /// 获取订单某个拍摄点的底片、成片和评价信息。
+    func storeOrderShootingDetail(storeId: Int, orderNumber: String, scenicSpotId: Int, photogUid: Int) async throws -> StoreOrderShootingDetailResponse
+
+    /// 申请普通订单退款。
+    func orderRefund(orderNumber: String, refundType: OrderRefundMode, refundAmount: String, refundReason: String) async throws
+
+    /// 获取订单历史拍摄信息。
+    func multiTravelShootHistory(orderNumber: String) async throws -> MultiTravelShootHistoryResponse
+
+    /// 获取多点旅拍订单已核销打卡点列表。
+    func multiTravelVerifiedScenicSpotList(orderNumber: String) async throws -> [MultiTravelVerifiedScenicSpotItem]
+
+    /// 提交多点旅拍任务素材。
+    func multiTravelUploadMaterial(_ request: MultiTravelUploadMaterialRequest) async throws
 }
 
 @MainActor
@@ -131,4 +155,106 @@ final class OrdersAPI: OrderServing {
             )
         )
     }
+
+    /// 获取押金订单列表。
+    func depositOrderList(scenicId: Int, page: Int = 1, pageSize: Int = 10) async throws -> ListPayload<DepositOrderListItem> {
+        try await client.send(
+            APIRequest(
+                method: .get,
+                path: "/api/yf-handset-app/photog/order/deposit-list",
+                queryItems: [
+                    URLQueryItem(name: "scenic_id", value: "\(scenicId)"),
+                    URLQueryItem(name: "page", value: "\(max(page, 1))"),
+                    URLQueryItem(name: "page_size", value: "\(max(pageSize, 1))")
+                ]
+            )
+        )
+    }
+
+    /// 核销押金订单。
+    func depositOrderWriteOff(orderNumber: String) async throws {
+        let _: EmptyPayload = try await client.send(
+            APIRequest(
+                method: .post,
+                path: "/api/yf-handset-app/photog/order/deposit-writeoff",
+                body: DepositOrderWriteOffRequest(orderNumber: orderNumber)
+            )
+        )
+    }
+
+    /// 申请押金订单退款。
+    func depositOrderRefund(orderNumber: String, refundReason: String) async throws {
+        let _: EmptyPayload = try await client.send(
+            APIRequest(
+                method: .post,
+                path: "/api/yf-handset-app/photog/order/deposit-refund",
+                body: DepositOrderRefundRequest(orderNumber: orderNumber, refundReason: refundReason)
+            )
+        )
+    }
+
+    /// 获取订单某个拍摄点的底片、成片和评价信息。
+    func storeOrderShootingDetail(storeId: Int, orderNumber: String, scenicSpotId: Int, photogUid: Int) async throws -> StoreOrderShootingDetailResponse {
+        try await client.send(
+            APIRequest(
+                method: .get,
+                path: "/api/app/store/order/shooting-detail",
+                queryItems: [
+                    URLQueryItem(name: "store_id", value: "\(storeId)"),
+                    URLQueryItem(name: "order_number", value: orderNumber),
+                    URLQueryItem(name: "scenic_spot_id", value: "\(scenicSpotId)"),
+                    URLQueryItem(name: "photog_uid", value: "\(photogUid)")
+                ]
+            )
+        )
+    }
+
+    /// 申请普通订单退款。
+    func orderRefund(orderNumber: String, refundType: OrderRefundMode, refundAmount: String, refundReason: String) async throws {
+        let _: EmptyPayload = try await client.send(
+            APIRequest(
+                method: .post,
+                path: "/api/yf-handset-app/photog/order/refund",
+                body: OrderRefundRequest(
+                    orderNumber: orderNumber,
+                    refundType: refundType.rawValue,
+                    refundAmount: refundAmount,
+                    refundReason: refundReason
+                )
+            )
+        )
+    }
+
+    /// 获取订单历史拍摄信息。
+    func multiTravelShootHistory(orderNumber: String) async throws -> MultiTravelShootHistoryResponse {
+        try await client.send(
+            APIRequest(
+                method: .get,
+                path: "/api/yf-handset-app/photog/order/multi-travel/shoot-history",
+                queryItems: [URLQueryItem(name: "order_number", value: orderNumber)]
+            )
+        )
+    }
+
+    /// 获取多点旅拍订单已核销打卡点列表。
+    func multiTravelVerifiedScenicSpotList(orderNumber: String) async throws -> [MultiTravelVerifiedScenicSpotItem] {
+        try await client.send(
+            APIRequest(
+                method: .get,
+                path: "/api/yf-handset-app/photog/order/multi-travel/verified-scenic-spot-list",
+                queryItems: [URLQueryItem(name: "order_number", value: orderNumber)]
+            )
+        )
+    }
+
+    /// 提交多点旅拍任务素材。
+    func multiTravelUploadMaterial(_ request: MultiTravelUploadMaterialRequest) async throws {
+        let _: EmptyPayload = try await client.send(
+            APIRequest(
+                method: .post,
+                path: "/api/yf-handset-app/photog/order/multi-travel/upload-material",
+                body: request
+            )
+        )
+    }
 }

suixinkan/Features/Orders/Models/OrderModels.swift

@@ -197,10 +197,101 @@ struct WriteOffRequest: Encodable {
     }
 }
 
+/// 押金订单列表实体，表示首页押金订单卡片的基础信息和操作状态。
+struct DepositOrderListItem: Decodable, Identifiable, Equatable, Hashable {
+    let id: Int
+    let orderNumber: String
+    let userPhone: String
+    let amount: String
+    let status: Int
+    let statusName: String
+    let createdAt: String
+
+    enum CodingKeys: String, CodingKey {
+        case id
+        case orderNumber = "order_number"
+        case userPhone = "user_phone"
+        case amount
+        case status
+        case statusName = "status_name"
+        case createdAt = "created_at"
+    }
+
+    /// 宽松解码押金订单字段，兼容后端数字和字符串混用。
+    init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        id = try container.decodeLossyInt(forKey: .id) ?? 0
+        orderNumber = try container.decodeLossyString(forKey: .orderNumber)
+        userPhone = try container.decodeLossyString(forKey: .userPhone)
+        amount = try container.decodeLossyString(forKey: .amount)
+        status = try container.decodeLossyInt(forKey: .status) ?? 0
+        statusName = try container.decodeLossyString(forKey: .statusName)
+        createdAt = try container.decodeLossyString(forKey: .createdAt)
+    }
+}
+
+/// 押金订单核销请求实体。
+struct DepositOrderWriteOffRequest: Encodable, Equatable {
+    let orderNumber: String
+
+    enum CodingKeys: String, CodingKey {
+        case orderNumber = "order_number"
+    }
+}
+
+/// 押金订单退款请求实体。
+struct DepositOrderRefundRequest: Encodable, Equatable {
+    let orderNumber: String
+    let refundReason: String
+
+    enum CodingKeys: String, CodingKey {
+        case orderNumber = "order_number"
+        case refundReason = "refund_reason"
+    }
+}
+
+/// 普通订单退款模式，表示全额退款或部分退款。
+enum OrderRefundMode: Int, CaseIterable, Identifiable, Hashable {
+    case full = 1
+    case partial = 3
+
+    var id: Int { rawValue }
+
+    /// 退款模式展示文案。
+    var title: String {
+        switch self {
+        case .full:
+            return "全额退款"
+        case .partial:
+            return "部分退款"
+        }
+    }
+}
+
+/// 普通订单退款请求实体。
+struct OrderRefundRequest: Encodable, Equatable {
+    let orderNumber: String
+    let refundType: Int
+    let refundAmount: String
+    let refundReason: String
+
+    enum CodingKeys: String, CodingKey {
+        case orderNumber = "order_number"
+        case refundType = "refund_type"
+        case refundAmount = "refund_amount"
+        case refundReason = "refund_reason"
+    }
+}
+
 /// 订单详情路由实体，表示订单模块内部可 push 的二级页面。
 enum OrdersRoute: Hashable {
     case storeDetail(OrderEntity)
     case writeOffDetail(WriteOffOrderItem)
+    case depositDetail(orderNumber: String)
+    case depositShootingInfo(orderNumber: String, scenicSpotId: Int, photogUid: Int)
+    case historicalShooting(orderNumber: String)
+    case multiTravelTaskUpload(orderNumber: String)
+    case orderTrailer(orderNumber: String, title: String)
 }
 
 /// 订单详情接口响应实体，承载门店订单详情页的完整展示数据。
@@ -346,6 +437,226 @@ struct StoreOrderShootingListItem: Decodable, Identifiable, Equatable, Hashable
     }
 }
 
+/// 订单拍摄信息响应实体，表示某个打卡点的评价、底片和成片。
+struct StoreOrderShootingDetailResponse: Decodable, Equatable, Hashable {
+    let scenicSpotId: Int
+    let scenicSpotName: String
+    let orderType: Int
+    let orderTypeName: String
+    let orderComment: StoreOrderComment?
+    let materialList: [OrderMediaFile]
+    let completeList: [OrderMediaFile]
+
+    enum CodingKeys: String, CodingKey {
+        case scenicSpotId = "scenic_spot_id"
+        case scenicSpotName = "scenic_spot_name"
+        case orderType = "order_type"
+        case orderTypeName = "order_type_name"
+        case orderComment = "order_comment"
+        case materialList = "material_list"
+        case completeList = "complete_list"
+    }
+
+    /// 宽松解码拍摄信息详情。
+    init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        scenicSpotId = try container.decodeLossyInt(forKey: .scenicSpotId) ?? 0
+        scenicSpotName = try container.decodeLossyString(forKey: .scenicSpotName)
+        orderType = try container.decodeLossyInt(forKey: .orderType) ?? 0
+        orderTypeName = try container.decodeLossyString(forKey: .orderTypeName)
+        orderComment = try container.decodeIfPresent(StoreOrderComment.self, forKey: .orderComment)
+        materialList = try container.decodeIfPresent([OrderMediaFile].self, forKey: .materialList) ?? []
+        completeList = try container.decodeIfPresent([OrderMediaFile].self, forKey: .completeList) ?? []
+    }
+}
+
+/// 订单评价实体，表示拍摄、修图、景区、服务和相机评分。
+struct StoreOrderComment: Decodable, Equatable, Hashable {
+    let starShooting: Int
+    let starRetouching: Int
+    let starScenery: Int
+    let starService: Int
+    let starCamera: Int
+    let content: String
+    let createdAt: String
+
+    enum CodingKeys: String, CodingKey {
+        case starShooting = "star_shooting"
+        case starRetouching = "star_retouching"
+        case starScenery = "star_scenery"
+        case starService = "star_service"
+        case starCamera = "star_camera"
+        case content
+        case createdAt = "created_at"
+    }
+
+    /// 宽松解码评价字段。
+    init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        starShooting = try container.decodeLossyInt(forKey: .starShooting) ?? 0
+        starRetouching = try container.decodeLossyInt(forKey: .starRetouching) ?? 0
+        starScenery = try container.decodeLossyInt(forKey: .starScenery) ?? 0
+        starService = try container.decodeLossyInt(forKey: .starService) ?? 0
+        starCamera = try container.decodeLossyInt(forKey: .starCamera) ?? 0
+        content = try container.decodeLossyString(forKey: .content)
+        createdAt = try container.decodeLossyString(forKey: .createdAt)
+    }
+}
+
+/// 订单媒体文件实体，表示底片、成片或历史拍摄媒体。
+struct OrderMediaFile: Decodable, Identifiable, Equatable, Hashable {
+    var id: String { "\(fileUrl)-\(fileName)-\(uploadTime)" }
+
+    let fileName: String
+    let fileUrl: String
+    let fileType: Int
+    let fileSize: Int64
+    let coverUrl: String
+    let uploadTime: String
+
+    var isVideo: Bool {
+        fileType == 1
+    }
+
+    var previewURLString: String {
+        coverUrl.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty ? fileUrl : coverUrl
+    }
+
+    enum CodingKeys: String, CodingKey {
+        case fileName = "file_name"
+        case fileUrl = "file_url"
+        case fileType = "file_type"
+        case fileSize = "file_size"
+        case coverUrl = "cover_url"
+        case uploadTime = "upload_time"
+    }
+
+    /// 宽松解码媒体文件字段。
+    init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        fileName = try container.decodeLossyString(forKey: .fileName)
+        fileUrl = try container.decodeLossyString(forKey: .fileUrl)
+        fileType = try container.decodeLossyInt(forKey: .fileType) ?? 0
+        fileSize = Int64(try container.decodeLossyInt(forKey: .fileSize) ?? 0)
+        coverUrl = try container.decodeLossyString(forKey: .coverUrl)
+        uploadTime = try container.decodeLossyString(forKey: .uploadTime)
+    }
+}
+
+/// 历史拍摄响应实体，表示订单多点位历史拍摄媒体。
+struct MultiTravelShootHistoryResponse: Decodable, Equatable, Hashable {
+    let projectName: String
+    let projectType: Int
+    let projectTypeName: String
+    let photogSpotList: [PhotogSpotItem]
+
+    enum CodingKeys: String, CodingKey {
+        case projectName = "project_name"
+        case projectType = "project_type"
+        case projectTypeName = "project_type_name"
+        case photogSpotList = "photog_spot_list"
+    }
+
+    /// 宽松解码历史拍摄响应。
+    init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        projectName = try container.decodeLossyString(forKey: .projectName)
+        projectType = try container.decodeLossyInt(forKey: .projectType) ?? 0
+        projectTypeName = try container.decodeLossyString(forKey: .projectTypeName)
+        photogSpotList = try container.decodeIfPresent([PhotogSpotItem].self, forKey: .photogSpotList) ?? []
+    }
+}
+
+/// 历史拍摄打卡点实体，表示某个摄影师在打卡点上传过的媒体。
+struct PhotogSpotItem: Decodable, Identifiable, Equatable, Hashable {
+    var id: String { "\(scenicSpotId)-\(photogUid)" }
+
+    let scenicSpotId: Int
+    let photogUid: Int
+    let scenicSpotName: String
+    let photogNickname: String
+    let photogName: String
+    let files: [OrderMediaFile]
+
+    var photographerDisplayName: String {
+        let nickname = photogNickname.trimmingCharacters(in: .whitespacesAndNewlines)
+        return nickname.isEmpty ? photogName : nickname
+    }
+
+    enum CodingKeys: String, CodingKey {
+        case scenicSpotId = "scenic_spot_id"
+        case photogUid = "photog_uid"
+        case scenicSpotName = "scenic_spot_name"
+        case photogNickname = "photog_nickname"
+        case photogName = "photog_name"
+        case files
+    }
+
+    /// 宽松解码历史拍摄打卡点。
+    init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        scenicSpotId = try container.decodeLossyInt(forKey: .scenicSpotId) ?? 0
+        photogUid = try container.decodeLossyInt(forKey: .photogUid) ?? 0
+        scenicSpotName = try container.decodeLossyString(forKey: .scenicSpotName)
+        photogNickname = try container.decodeLossyString(forKey: .photogNickname)
+        photogName = try container.decodeLossyString(forKey: .photogName)
+        files = try container.decodeIfPresent([OrderMediaFile].self, forKey: .files) ?? []
+    }
+}
+
+/// 多点旅拍已核销打卡点实体，用于任务上传时选择目标打卡点。
+struct MultiTravelVerifiedScenicSpotItem: Decodable, Identifiable, Equatable, Hashable {
+    let id: Int
+    let name: String
+
+    enum CodingKeys: String, CodingKey {
+        case id
+        case name
+    }
+
+    /// 宽松解码已核销打卡点字段。
+    init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        id = try container.decodeLossyInt(forKey: .id) ?? 0
+        name = try container.decodeLossyString(forKey: .name)
+    }
+}
+
+/// 多点旅拍任务素材提交请求实体。
+struct MultiTravelUploadMaterialRequest: Encodable, Equatable {
+    let orderNumber: String
+    let scenicSpotId: Int
+    let cloudFile: [MultiTravelCloudFileItem]
+    let uploadFile: [MultiTravelUploadFileItem]
+
+    enum CodingKeys: String, CodingKey {
+        case orderNumber = "order_number"
+        case scenicSpotId = "scenic_spot_id"
+        case cloudFile = "cloud_file"
+        case uploadFile = "upload_file"
+    }
+}
+
+/// 多点旅拍云盘素材提交项。
+struct MultiTravelCloudFileItem: Encodable, Equatable {
+    let fileId: Int
+
+    enum CodingKeys: String, CodingKey {
+        case fileId = "file_id"
+    }
+}
+
+/// 多点旅拍本地上传素材提交项。
+struct MultiTravelUploadFileItem: Encodable, Equatable {
+    let fileName: String
+    let fileUrl: String
+
+    enum CodingKeys: String, CodingKey {
+        case fileName = "file_name"
+        case fileUrl = "file_url"
+    }
+}
+
 /// 订单详情展示适配实体，统一列表摘要和详情接口响应的读取方式。
 struct StoreOrderDetailDisplay: Equatable {
     let orderNumber: String

suixinkan/Features/Orders/Orders.md

@@ -2,15 +2,21 @@
 
 ## 模块职责
 
-Orders 模块负责登录后的订单 Tab。当前已覆盖订单管理和核销订单两个入口，提供列表展示、筛选、分页、刷新、订单详情、扫码核销和手动核销闭环。
+Orders 模块负责登录后的订单 Tab。当前已覆盖订单管理、核销订单和押金订单相关入口，提供列表展示、筛选、分页、刷新、订单详情、扫码核销、手动核销、押金核销、押金退款、普通订单退款、历史拍摄、任务上传和尾片入口闭环。
 
-当前仍不迁移退款、历史拍摄、任务上传、视频预告、完整拍摄详情等长尾流程；这些入口统一进入安全占位页，后续按独立模块逐个迁移。
+当前仍不迁移独立视频播放器增强、尾片审核进度、上传后自动关联订单尾片等后端未体现的能力；这些能力后续按明确接口再补。
 
 ## 核心对象
 
 - `OrdersView`：订单 Tab 根视图，读取 `AccountContext`、`PermissionContext`、`AppRouter` 和 `OrdersAPI`。
 - `OrdersViewModel`：管理订单子入口、筛选条件、分页状态、加载状态和手动核销状态。
 - `OrderDetailViewModel`：管理订单详情接口加载、错误提示和列表摘要兜底展示。
+- `DepositOrderListViewModel`：管理押金订单分页、核销、退款和操作后刷新。
+- `DepositOrderDetailViewModel`：管理押金订单详情加载，缺少门店时不发起请求。
+- `DepositOrderShootingInfoViewModel`：管理押金订单单个打卡点的底片、成片和评价。
+- `OrderRefundViewModel`：管理普通订单退款入口判断、全额/部分退款金额校验和提交保护。
+- `HistoricalShootingInfoViewModel`：管理多点位订单历史拍摄媒体展示。
+- `MultiTravelTaskUploadViewModel`：管理多点旅拍任务上传的订单号、已核销打卡点、云盘附件、本地附件、OSS 上传和提交。
 - `OrdersAPI`：封装订单列表、核销订单列表和订单核销接口。
 - `OrdersEntry`：表示订单 Tab 内部入口，包含订单管理和核销订单。
 - `OrdersRoute`：表示订单模块二级页面路由，包含订单详情和核销订单详情。
@@ -26,8 +32,18 @@ Orders 模块负责登录后的订单 Tab。当前已覆盖订单管理和核销
 
 核销订单支持扫码和手动输入订单号。扫码使用 AVFoundation，不缓存扫码结果；扫码成功后先用 `OrderNumberParser` 提取订单号，命中当前核销列表时滚动定位并高亮卡片，未命中时填入订单号并允许继续核销。核销前统一弹确认框，确认后调用核销接口。核销成功后重新拉取第一页核销订单，并重置分页状态；核销失败只清理提交状态，不刷新列表。
 
+押金订单入口由首页 `deposit_order_detail`、`deposit_order`、`deposit_order_shooting_info` 进入。没有订单上下文时先展示押金订单页，用户可以手输订单号进入详情，也可以从列表进入详情。押金详情复用门店订单详情接口，按当前门店 ID 和订单号加载；拍摄点列表进入拍摄信息页，展示评价、底片和成片。
+
+普通订单退款只在 `orderStatus == 18 || orderStatus == 30`、`orderType != 19` 且可退金额大于 0 时展示入口。全额退款使用可退金额，部分退款要求金额大于 0、最多两位小数且不能超过可退金额。押金退款要求填写退款原因，普通退款和押金退款都不保存表单数据，提交成功后刷新对应订单数据。
+
+历史拍摄按订单号请求 `/api/yf-handset-app/photog/order/multi-travel/shoot-history`，仅展示项目、拍摄点和已有媒体，不做上传、下载、删除或编辑。
+
+任务上传仅对 `orderType == 19` 的多点旅拍订单展示。页面先按订单号请求 `/api/yf-handset-app/photog/order/multi-travel/verified-scenic-spot-list` 获取已核销打卡点，再支持选择云盘素材和本地图片/视频；本地素材先通过 `OSSUploadService.uploadTaskFile` 上传，成功后和云盘文件一起提交到 `/api/yf-handset-app/photog/order/multi-travel/upload-material`。
+
+视频预告和尾片上传按旧工程现状统一进入 `OrderTrailerView`，该页只做订单尾片流程引导，并打开已迁移的 `AlbumTrailerEntryView` 完成相册预览上传，不新增独立订单尾片接口。
+
 ## 路由边界
 
-首页 `photographer_orders` 和 `/scenic-order-manage` 会进入订单管理，`verification_order` 会进入核销订单。订单详情和核销订单详情已接入 `AppRoute.orders` 真实路由，push 后继续隐藏 TabBar。
+首页 `photographer_orders` 和 `/scenic-order-manage` 会进入订单管理，`verification_order` 会进入核销订单，`deposit_order_detail`、`deposit_order`、`deposit_order_shooting_info` 会进入押金订单页。订单详情、核销订单详情、押金详情、押金拍摄信息、历史拍摄、任务上传和订单尾片已接入 `AppRoute.orders` 真实路由，push 后继续隐藏 TabBar。
 
-退款、历史拍摄、任务上传、视频预告等尚未迁移的能力仍进入占位页，避免入口崩溃。
+未明确接口的订单后续能力继续进入占位页，避免入口崩溃。

suixinkan/Features/Orders/ViewModels/OrderDetailViewModel.swift

@@ -43,8 +43,13 @@ final class OrderDetailViewModel {
     }
 
     /// 加载门店订单详情，缺少门店 ID 时只保留列表摘要展示。
-    func load(api: OrderServing, fallbackStoreId: Int?) async {
-        guard detail == nil, !loading else { return }
+    func load(api: OrderServing, fallbackStoreId: Int?, forceReload: Bool = false) async {
+        guard !loading else { return }
+        if forceReload {
+            detail = nil
+        } else {
+            guard detail == nil else { return }
+        }
 
         guard let storeId = item.storeId ?? fallbackStoreId, storeId > 0 else {
             contextMessage = "缺少门店上下文，当前展示订单摘要。"

suixinkan/Features/Orders/ViewModels/OrderLongTailViewModels.swift

@@ -0,0 +1,610 @@
+//
+//  OrderLongTailViewModels.swift
+//  suixinkan
+//
+//  Created by Codex on 2026/6/25.
+//
+
+import Foundation
+import Observation
+
+@MainActor
+@Observable
+/// 押金订单列表 ViewModel，负责分页、核销、退款和操作后刷新。
+final class DepositOrderListViewModel {
+    private(set) var orders: [DepositOrderListItem] = []
+    private(set) var total = 0
+    private(set) var page = 1
+    private(set) var hasMore = false
+    private(set) var loading = false
+    private(set) var loadingMore = false
+    private(set) var operatingOrderNumber: String?
+    var errorMessage: String?
+
+    private let pageSize = 10
+
+    /// 加载押金订单列表，缺少景区时清空旧数据且不请求接口。
+    func reload(api: OrderServing, scenicId: Int?, reset: Bool) async {
+        guard let scenicId, scenicId > 0 else {
+            resetState()
+            return
+        }
+
+        if reset {
+            page = 1
+            total = 0
+            orders = []
+            loading = true
+        } else {
+            guard !loadingMore, hasMore else { return }
+            loadingMore = true
+        }
+
+        defer {
+            loading = false
+            loadingMore = false
+        }
+
+        do {
+            let result = try await api.depositOrderList(scenicId: scenicId, page: page, pageSize: pageSize)
+            total = result.total
+            if page == 1 {
+                orders = result.list
+            } else {
+                orders.append(contentsOf: result.list)
+            }
+            page += 1
+            hasMore = orders.count < result.total && !result.list.isEmpty
+            errorMessage = nil
+        } catch {
+            if reset {
+                orders = []
+                total = 0
+                page = 1
+                hasMore = false
+            }
+            errorMessage = error.localizedDescription
+        }
+    }
+
+    /// 核销押金订单，成功后刷新第一页。
+    func writeOff(api: OrderServing, scenicId: Int?, orderNumber: String) async -> Bool {
+        let normalized = orderNumber.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !normalized.isEmpty, operatingOrderNumber == nil else { return false }
+        guard let scenicId, scenicId > 0 else {
+            errorMessage = "缺少景区上下文"
+            return false
+        }
+
+        operatingOrderNumber = normalized
+        defer { operatingOrderNumber = nil }
+
+        do {
+            try await api.depositOrderWriteOff(orderNumber: normalized)
+            await reload(api: api, scenicId: scenicId, reset: true)
+            return true
+        } catch {
+            errorMessage = error.localizedDescription
+            return false
+        }
+    }
+
+    /// 申请押金订单退款，原因必填，成功后刷新第一页。
+    func refund(api: OrderServing, scenicId: Int?, orderNumber: String, reason: String) async -> Bool {
+        let normalizedOrderNumber = orderNumber.trimmingCharacters(in: .whitespacesAndNewlines)
+        let normalizedReason = reason.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !normalizedOrderNumber.isEmpty, operatingOrderNumber == nil else { return false }
+        guard !normalizedReason.isEmpty else {
+            errorMessage = "请填写退款原因"
+            return false
+        }
+        guard let scenicId, scenicId > 0 else {
+            errorMessage = "缺少景区上下文"
+            return false
+        }
+
+        operatingOrderNumber = normalizedOrderNumber
+        defer { operatingOrderNumber = nil }
+
+        do {
+            try await api.depositOrderRefund(orderNumber: normalizedOrderNumber, refundReason: normalizedReason)
+            await reload(api: api, scenicId: scenicId, reset: true)
+            return true
+        } catch {
+            errorMessage = error.localizedDescription
+            return false
+        }
+    }
+
+    /// 清理错误文案。
+    func clearError() {
+        errorMessage = nil
+    }
+
+    private func resetState() {
+        orders = []
+        total = 0
+        page = 1
+        hasMore = false
+        loading = false
+        loadingMore = false
+        operatingOrderNumber = nil
+        errorMessage = nil
+    }
+}
+
+@MainActor
+@Observable
+/// 押金订单详情 ViewModel，负责按门店和订单号加载详情。
+final class DepositOrderDetailViewModel {
+    private(set) var detail: StoreOrderDetailResponse?
+    private(set) var loading = false
+    var errorMessage: String?
+
+    /// 加载押金订单详情，缺少门店或订单号时不请求接口。
+    func load(api: OrderServing, storeId: Int?, orderNumber: String) async {
+        let normalized = orderNumber.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard let storeId, storeId > 0 else {
+            reset(message: "当前账号缺少门店信息")
+            return
+        }
+        guard !normalized.isEmpty else {
+            reset(message: "订单号不能为空")
+            return
+        }
+
+        detail = nil
+        loading = true
+        defer { loading = false }
+
+        do {
+            detail = try await api.storeOrderDetail(storeId: storeId, orderNumber: normalized)
+            errorMessage = nil
+        } catch {
+            detail = nil
+            errorMessage = error.localizedDescription
+        }
+    }
+
+    /// 清理错误文案。
+    func clearError() {
+        errorMessage = nil
+    }
+
+    private func reset(message: String) {
+        detail = nil
+        loading = false
+        errorMessage = message
+    }
+}
+
+@MainActor
+@Observable
+/// 押金拍摄信息 ViewModel，负责加载单个打卡点的媒体和评分。
+final class DepositOrderShootingInfoViewModel {
+    private(set) var detail: StoreOrderShootingDetailResponse?
+    private(set) var loading = false
+    var errorMessage: String?
+
+    /// 加载押金订单拍摄信息，缺少门店或订单号时不请求接口。
+    func load(api: OrderServing, storeId: Int?, orderNumber: String, scenicSpotId: Int, photogUid: Int) async {
+        let normalized = orderNumber.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard let storeId, storeId > 0 else {
+            reset(message: "当前账号缺少门店信息")
+            return
+        }
+        guard !normalized.isEmpty else {
+            reset(message: "订单号不能为空")
+            return
+        }
+
+        detail = nil
+        loading = true
+        defer { loading = false }
+
+        do {
+            detail = try await api.storeOrderShootingDetail(
+                storeId: storeId,
+                orderNumber: normalized,
+                scenicSpotId: scenicSpotId,
+                photogUid: photogUid
+            )
+            errorMessage = nil
+        } catch {
+            detail = nil
+            errorMessage = error.localizedDescription
+        }
+    }
+
+    /// 清理错误文案。
+    func clearError() {
+        errorMessage = nil
+    }
+
+    private func reset(message: String) {
+        detail = nil
+        loading = false
+        errorMessage = message
+    }
+}
+
+@MainActor
+@Observable
+/// 普通订单退款 ViewModel，负责退款入口判断、金额校验和提交保护。
+final class OrderRefundViewModel {
+    var mode: OrderRefundMode = .full
+    var amount = ""
+    var reason = ""
+    private(set) var submitting = false
+    var errorMessage: String?
+
+    /// 判断订单是否允许展示普通退款入口。
+    func canRefund(_ item: OrderEntity) -> Bool {
+        (item.orderStatus == 18 || item.orderStatus == 30) &&
+            item.orderType != 19 &&
+            availableAmount(for: item) > 0
+    }
+
+    /// 打开退款表单时初始化默认值。
+    func begin(item: OrderEntity) {
+        mode = .full
+        amount = availableAmountText(for: item)
+        reason = ""
+        errorMessage = nil
+    }
+
+    /// 提交普通订单退款。
+    func submit(api: OrderServing, item: OrderEntity) async -> Bool {
+        guard !submitting else { return false }
+        guard canRefund(item) else {
+            errorMessage = "当前订单不可退款"
+            return false
+        }
+        let normalizedReason = reason.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !normalizedReason.isEmpty else {
+            errorMessage = "请输入退款原因"
+            return false
+        }
+
+        let refundAmount: String
+        switch mode {
+        case .full:
+            refundAmount = availableAmountText(for: item)
+        case .partial:
+            guard let normalized = Self.normalizedMoney(amount) else {
+                errorMessage = "请输入有效的退款金额"
+                return false
+            }
+            guard (Decimal(string: normalized) ?? 0) <= availableAmount(for: item) else {
+                errorMessage = "退款金额不能大于可退金额"
+                return false
+            }
+            refundAmount = normalized
+        }
+
+        submitting = true
+        errorMessage = nil
+        defer { submitting = false }
+
+        do {
+            try await api.orderRefund(
+                orderNumber: item.orderNumber,
+                refundType: mode,
+                refundAmount: refundAmount,
+                refundReason: normalizedReason
+            )
+            return true
+        } catch {
+            errorMessage = error.localizedDescription
+            return false
+        }
+    }
+
+    /// 计算普通订单可退金额。
+    func availableAmount(for item: OrderEntity) -> Decimal {
+        let paid = Self.decimalValue(item.actualPayAmount)
+        if paid > 0 { return paid }
+        return Self.decimalValue(item.actualRefundAmount.isEmpty ? item.refundAmount : item.actualRefundAmount)
+    }
+
+    /// 返回可退金额展示和提交文案。
+    func availableAmountText(for item: OrderEntity) -> String {
+        Self.moneyText(availableAmount(for: item))
+    }
+
+    /// 将输入金额规范成两位小数，空值、非法值和超过两位小数返回 nil。
+    static func normalizedMoney(_ rawValue: String) -> String? {
+        let text = rawValue.trimmingCharacters(in: .whitespacesAndNewlines).replacingOccurrences(of: ",", with: "")
+        guard !text.isEmpty else { return nil }
+        let pattern = #"^\d+(\.\d{1,2})?$"#
+        guard text.range(of: pattern, options: .regularExpression) != nil,
+              let value = Decimal(string: text),
+              value > 0 else {
+            return nil
+        }
+        return moneyText(value)
+    }
+
+    private static func decimalValue(_ text: String) -> Decimal {
+        Decimal(string: text.trimmingCharacters(in: .whitespacesAndNewlines).replacingOccurrences(of: ",", with: "")) ?? 0
+    }
+
+    private static func moneyText(_ value: Decimal) -> String {
+        let number = NSDecimalNumber(decimal: value)
+        let handler = NSDecimalNumberHandler(
+            roundingMode: .plain,
+            scale: 2,
+            raiseOnExactness: false,
+            raiseOnOverflow: false,
+            raiseOnUnderflow: false,
+            raiseOnDivideByZero: false
+        )
+        return String(format: "%.2f", number.rounding(accordingToBehavior: handler).doubleValue)
+    }
+}
+
+@MainActor
+@Observable
+/// 历史拍摄 ViewModel，负责按订单号加载多点位历史拍摄媒体。
+final class HistoricalShootingInfoViewModel {
+    private(set) var projectName = ""
+    private(set) var projectTypeName = ""
+    private(set) var spots: [PhotogSpotItem] = []
+    private(set) var loading = false
+    var errorMessage: String?
+
+    /// 加载历史拍摄信息，订单号为空时清空旧数据且不请求接口。
+    func load(api: OrderServing, orderNumber: String) async {
+        let normalized = orderNumber.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !normalized.isEmpty else {
+            reset(message: "订单号不能为空")
+            return
+        }
+
+        loading = true
+        defer { loading = false }
+
+        do {
+            let result = try await api.multiTravelShootHistory(orderNumber: normalized)
+            projectName = result.projectName
+            projectTypeName = result.projectTypeName
+            spots = result.photogSpotList
+            errorMessage = nil
+        } catch {
+            reset(message: error.localizedDescription)
+        }
+    }
+
+    /// 清理错误文案。
+    func clearError() {
+        errorMessage = nil
+    }
+
+    private func reset(message: String) {
+        projectName = ""
+        projectTypeName = ""
+        spots = []
+        loading = false
+        errorMessage = message
+    }
+}
+
+@MainActor
+@Observable
+/// 多点旅拍任务上传 ViewModel，负责订单号、打卡点、云盘附件、本地附件和素材提交。
+final class MultiTravelTaskUploadViewModel {
+    var orderNumber = ""
+    var selectedSpotId: Int?
+    private(set) var spots: [MultiTravelVerifiedScenicSpotItem] = []
+    var selectedCloudFiles: [TaskCloudSelectionItem] = []
+    var selectedLocalFiles: [TaskLocalUploadItem] = []
+    private(set) var isLoadingSpots = false
+    private(set) var isSubmitting = false
+    private(set) var didSubmitSuccessfully = false
+    var errorMessage: String?
+
+    private var loadedSpotOrderNumber = ""
+
+    /// 当前选中打卡点展示名。
+    var selectedSpotName: String {
+        spots.first(where: { $0.id == selectedSpotId })?.name ?? "请选择打卡点"
+    }
+
+    /// 判断提交按钮是否满足基础启用条件。
+    var canSubmit: Bool {
+        !isSubmitting &&
+            selectedSpotId != nil &&
+            (!selectedCloudFiles.isEmpty || !selectedLocalFiles.isEmpty) &&
+            !selectedLocalFiles.contains(where: \.isUploading)
+    }
+
+    /// 初始化任务上传表单订单号。
+    init(initialOrderNumber: String = "") {
+        orderNumber = initialOrderNumber
+    }
+
+    /// 加载当前订单已核销打卡点，订单号为空时不请求接口。
+    func loadSpots(api: OrderServing) async {
+        let normalized = orderNumber.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !normalized.isEmpty else {
+            resetSpotSelection()
+            return
+        }
+
+        isLoadingSpots = true
+        defer { isLoadingSpots = false }
+
+        do {
+            let result = try await api.multiTravelVerifiedScenicSpotList(orderNumber: normalized)
+            spots = result
+            loadedSpotOrderNumber = normalized
+            if !spots.contains(where: { $0.id == selectedSpotId }) {
+                selectedSpotId = spots.first?.id
+            }
+            errorMessage = nil
+        } catch {
+            resetSpotSelection()
+            errorMessage = error.localizedDescription
+        }
+    }
+
+    /// 切换选中的打卡点。
+    func selectSpot(id: Int?) {
+        selectedSpotId = id
+    }
+
+    /// 合并云盘附件，按文件 ID 去重。
+    func mergeCloudFiles(_ files: [TaskCloudSelectionItem]) {
+        var next = selectedCloudFiles
+        for file in files where !next.contains(where: { $0.id == file.id }) {
+            next.append(file)
+        }
+        selectedCloudFiles = next
+    }
+
+    /// 移除指定云盘附件。
+    func removeCloudFile(id: Int) {
+        selectedCloudFiles.removeAll { $0.id == id }
+    }
+
+    /// 添加本地图片或视频附件。
+    func addLocalFile(data: Data, fileName: String) {
+        selectedLocalFiles.append(
+            TaskLocalUploadItem(
+                id: UUID(),
+                data: data,
+                fileName: fileName,
+                fileType: Self.fileType(for: fileName),
+                remark: "",
+                uploadedURL: nil,
+                progress: 0,
+                errorMessage: nil
+            )
+        )
+    }
+
+    /// 移除指定本地附件。
+    func removeLocalFile(id: UUID) {
+        selectedLocalFiles.removeAll { $0.id == id }
+    }
+
+    /// 提交多点旅拍任务素材；本地附件先上传 OSS，再提交最终 URL。
+    @discardableResult
+    func submit(api: OrderServing, uploadService: any OSSUploadServing, scenicId: Int?) async -> Bool {
+        guard !isSubmitting else { return false }
+        guard let requestContext = validateBeforeSubmit(scenicId: scenicId) else { return false }
+
+        isSubmitting = true
+        didSubmitSuccessfully = false
+        errorMessage = nil
+        defer { isSubmitting = false }
+
+        do {
+            let uploadFiles = try await uploadLocalFiles(uploadService: uploadService, scenicId: requestContext.scenicId)
+            try await api.multiTravelUploadMaterial(
+                MultiTravelUploadMaterialRequest(
+                    orderNumber: requestContext.orderNumber,
+                    scenicSpotId: requestContext.scenicSpotId,
+                    cloudFile: selectedCloudFiles.map { MultiTravelCloudFileItem(fileId: $0.id) },
+                    uploadFile: uploadFiles
+                )
+            )
+            didSubmitSuccessfully = true
+            return true
+        } catch {
+            errorMessage = error.localizedDescription
+            return false
+        }
+    }
+
+    /// 清理错误文案。
+    func clearError() {
+        errorMessage = nil
+    }
+
+    private func validateBeforeSubmit(scenicId: Int?) -> SubmitContext? {
+        let normalizedOrderNumber = orderNumber.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard let scenicId, scenicId > 0 else {
+            errorMessage = "请先选择景区"
+            return nil
+        }
+        guard !normalizedOrderNumber.isEmpty else {
+            errorMessage = "请先填写订单号"
+            return nil
+        }
+        guard loadedSpotOrderNumber == normalizedOrderNumber else {
+            errorMessage = "请先刷新打卡点"
+            return nil
+        }
+        guard let selectedSpotId else {
+            errorMessage = "请选择打卡点"
+            return nil
+        }
+        guard !selectedCloudFiles.isEmpty || !selectedLocalFiles.isEmpty else {
+            errorMessage = "请至少选择一个素材文件"
+            return nil
+        }
+        guard !selectedLocalFiles.contains(where: \.isUploading) else {
+            errorMessage = "文件上传中，请稍后提交"
+            return nil
+        }
+        return SubmitContext(scenicId: scenicId, orderNumber: normalizedOrderNumber, scenicSpotId: selectedSpotId)
+    }
+
+    private func uploadLocalFiles(uploadService: any OSSUploadServing, scenicId: Int) async throws -> [MultiTravelUploadFileItem] {
+        var uploadFiles: [MultiTravelUploadFileItem] = []
+        for index in selectedLocalFiles.indices {
+            if let uploadedURL = selectedLocalFiles[index].uploadedURL {
+                uploadFiles.append(MultiTravelUploadFileItem(fileName: selectedLocalFiles[index].fileName, fileUrl: uploadedURL))
+                continue
+            }
+
+            selectedLocalFiles[index].errorMessage = nil
+            let fileID = selectedLocalFiles[index].id
+            do {
+                let url = try await uploadService.uploadTaskFile(
+                    data: selectedLocalFiles[index].data,
+                    fileName: selectedLocalFiles[index].fileName,
+                    fileType: selectedLocalFiles[index].fileType,
+                    scenicId: scenicId,
+                    onProgress: { [weak self] progress in
+                        Task { @MainActor in
+                            self?.updateLocalFileProgress(id: fileID, progress: progress)
+                        }
+                    }
+                )
+                selectedLocalFiles[index].uploadedURL = url
+                selectedLocalFiles[index].progress = 100
+                uploadFiles.append(MultiTravelUploadFileItem(fileName: selectedLocalFiles[index].fileName, fileUrl: url))
+            } catch {
+                selectedLocalFiles[index].progress = 0
+                selectedLocalFiles[index].errorMessage = error.localizedDescription
+                throw error
+            }
+        }
+        return uploadFiles
+    }
+
+    private func updateLocalFileProgress(id: UUID, progress: Int) {
+        guard let index = selectedLocalFiles.firstIndex(where: { $0.id == id }) else { return }
+        selectedLocalFiles[index].progress = progress
+    }
+
+    private func resetSpotSelection() {
+        spots = []
+        selectedSpotId = nil
+        loadedSpotOrderNumber = ""
+        isLoadingSpots = false
+    }
+
+    private static func fileType(for fileName: String) -> Int {
+        let ext = URL(fileURLWithPath: fileName).pathExtension.lowercased()
+        return ["mp4", "mov", "m4v", "avi"].contains(ext) ? 1 : 2
+    }
+
+    private struct SubmitContext {
+        let scenicId: Int
+        let orderNumber: String
+        let scenicSpotId: Int
+    }
+}

suixinkan/Features/Orders/Views/DepositOrderViews.swift

@@ -0,0 +1,596 @@
+//
+//  DepositOrderViews.swift
+//  suixinkan
+//
+//  Created by Codex on 2026/6/25.
+//
+
+import SwiftUI
+
+/// 押金订单入口页，支持订单号查询、列表分页、核销和退款。
+struct DepositOrderEntryView: View {
+    @Environment(AccountContext.self) private var accountContext
+    @Environment(OrdersAPI.self) private var ordersAPI
+    @Environment(RouterPath.self) private var router
+    @Environment(ToastCenter.self) private var toastCenter
+    @Environment(\.globalLoading) private var globalLoading
+
+    @State private var viewModel = DepositOrderListViewModel()
+    @State private var orderNumber = ""
+    @State private var pendingWriteOff: DepositOrderListItem?
+    @State private var pendingRefund: DepositOrderListItem?
+    @State private var refundReason = ""
+
+    var body: some View {
+        List {
+            Section("订单查询") {
+                TextField("请输入押金订单号", text: $orderNumber)
+                    .textInputAutocapitalization(.never)
+                    .autocorrectionDisabled(true)
+
+                Button("查看订单详情") {
+                    navigateToDetail(orderNumber)
+                }
+                .disabled(orderNumber.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty)
+            }
+
+            Section {
+                if viewModel.orders.isEmpty {
+                    ContentUnavailableView("暂无押金订单", systemImage: "doc.text.magnifyingglass")
+                        .frame(maxWidth: .infinity, minHeight: 180)
+                } else {
+                    ForEach(viewModel.orders) { item in
+                        DepositOrderRow(
+                            item: item,
+                            isOperating: viewModel.operatingOrderNumber == item.orderNumber,
+                            onDetail: { navigateToDetail(item.orderNumber) },
+                            onWriteOff: { pendingWriteOff = item },
+                            onRefund: { pendingRefund = item }
+                        )
+                    }
+
+                    if viewModel.hasMore {
+                        Button(viewModel.loadingMore ? "加载中..." : "加载更多") {
+                            Task { await viewModel.reload(api: ordersAPI, scenicId: accountContext.currentScenic?.id, reset: false) }
+                        }
+                        .frame(maxWidth: .infinity, alignment: .center)
+                        .disabled(viewModel.loadingMore)
+                    }
+                }
+            } header: {
+                HStack {
+                    Text("押金订单列表")
+                    Spacer()
+                    Text("\(viewModel.orders.count)/\(viewModel.total)")
+                }
+            }
+        }
+        .listStyle(.insetGrouped)
+        .scrollContentBackground(.hidden)
+        .background(Color(hex: 0xF5F5F5).ignoresSafeArea())
+        .navigationTitle("押金订单")
+        .navigationBarTitleDisplayMode(.inline)
+        .refreshable { await reload(showLoading: false) }
+        .task { await reload(showLoading: true) }
+        .confirmationDialog("确认核销该押金订单？", isPresented: writeOffBinding, titleVisibility: .visible) {
+            Button("确认核销") {
+                guard let pendingWriteOff else { return }
+                Task { await writeOff(pendingWriteOff) }
+            }
+            Button("取消", role: .cancel) {}
+        } message: {
+            Text(pendingWriteOff?.orderNumber ?? "")
+        }
+        .alert("申请退款", isPresented: refundBinding) {
+            TextField("请输入退款原因", text: $refundReason)
+            Button("提交") {
+                guard let pendingRefund else { return }
+                Task { await refund(pendingRefund) }
+            }
+            Button("取消", role: .cancel) {
+                pendingRefund = nil
+                refundReason = ""
+            }
+        } message: {
+            Text("请填写退款原因后提交。")
+        }
+        .alert("提示", isPresented: errorBinding) {
+            Button("知道了", role: .cancel) {}
+        } message: {
+            Text(viewModel.errorMessage ?? "")
+        }
+    }
+
+    private var writeOffBinding: Binding<Bool> {
+        Binding(
+            get: { pendingWriteOff != nil },
+            set: { if !$0 { pendingWriteOff = nil } }
+        )
+    }
+
+    private var refundBinding: Binding<Bool> {
+        Binding(
+            get: { pendingRefund != nil },
+            set: { if !$0 { pendingRefund = nil; refundReason = "" } }
+        )
+    }
+
+    private var errorBinding: Binding<Bool> {
+        Binding(
+            get: { viewModel.errorMessage != nil },
+            set: { if !$0 { viewModel.clearError() } }
+        )
+    }
+
+    /// 跳转到押金订单详情页。
+    private func navigateToDetail(_ rawOrderNumber: String) {
+        let text = rawOrderNumber.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !text.isEmpty else { return }
+        router.navigate(to: .orders(.depositDetail(orderNumber: text)))
+    }
+
+    /// 刷新押金订单列表。
+    private func reload(showLoading: Bool) async {
+        if showLoading {
+            await globalLoading.withLoading {
+                await viewModel.reload(api: ordersAPI, scenicId: accountContext.currentScenic?.id, reset: true)
+            }
+        } else {
+            await viewModel.reload(api: ordersAPI, scenicId: accountContext.currentScenic?.id, reset: true)
+        }
+    }
+
+    /// 核销押金订单并提示结果。
+    private func writeOff(_ item: DepositOrderListItem) async {
+        pendingWriteOff = nil
+        let success = await viewModel.writeOff(api: ordersAPI, scenicId: accountContext.currentScenic?.id, orderNumber: item.orderNumber)
+        if success {
+            toastCenter.show("核销成功")
+        }
+    }
+
+    /// 提交押金订单退款并提示结果。
+    private func refund(_ item: DepositOrderListItem) async {
+        let reason = refundReason
+        pendingRefund = nil
+        refundReason = ""
+        let success = await viewModel.refund(api: ordersAPI, scenicId: accountContext.currentScenic?.id, orderNumber: item.orderNumber, reason: reason)
+        if success {
+            toastCenter.show("退款申请已提交")
+        }
+    }
+}
+
+/// 押金订单列表行，展示订单状态和操作按钮。
+private struct DepositOrderRow: View {
+    let item: DepositOrderListItem
+    let isOperating: Bool
+    let onDetail: () -> Void
+    let onWriteOff: () -> Void
+    let onRefund: () -> Void
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: AppMetrics.Spacing.small) {
+            HStack {
+                Text(item.orderNumber.isEmpty ? "--" : item.orderNumber)
+                    .font(.system(size: AppMetrics.FontSize.subheadline, weight: .semibold))
+                    .foregroundStyle(AppDesign.textPrimary)
+                Spacer()
+                Text(item.statusName.isEmpty ? "状态\(item.status)" : item.statusName)
+                    .font(.system(size: AppMetrics.FontSize.caption, weight: .medium))
+                    .foregroundStyle(statusColor)
+                    .padding(.horizontal, AppMetrics.Spacing.small)
+                    .frame(height: 24)
+                    .background(statusColor.opacity(0.12), in: Capsule())
+            }
+
+            HStack {
+                Text("¥\(item.amount.isEmpty ? "0.00" : item.amount)")
+                    .font(.system(size: AppMetrics.FontSize.body, weight: .semibold))
+                    .foregroundStyle(AppDesign.primary)
+                Spacer()
+                Text(item.createdAt.isEmpty ? "--" : item.createdAt)
+                    .font(.system(size: AppMetrics.FontSize.caption))
+                    .foregroundStyle(AppDesign.textSecondary)
+            }
+
+            if !item.userPhone.isEmpty {
+                Text("手机号：\(item.userPhone)")
+                    .font(.system(size: AppMetrics.FontSize.caption))
+                    .foregroundStyle(AppDesign.textSecondary)
+            }
+
+            HStack(spacing: AppMetrics.Spacing.small) {
+                rowButton("详情", tint: AppDesign.primary, action: onDetail)
+                rowButton(isOperating ? "处理中..." : "核销", tint: Color(hex: 0x22C55E), disabled: isOperating, action: onWriteOff)
+                rowButton(isOperating ? "处理中..." : "退款", tint: Color(hex: 0xF59E0B), disabled: isOperating, action: onRefund)
+            }
+        }
+        .padding(.vertical, AppMetrics.Spacing.xSmall)
+    }
+
+    private var statusColor: Color {
+        switch item.status {
+        case 20:
+            return AppDesign.primary
+        case 30:
+            return Color(hex: 0x22C55E)
+        case 50:
+            return Color(hex: 0xEF4444)
+        default:
+            return Color(hex: 0xF59E0B)
+        }
+    }
+
+    /// 构建列表行操作按钮。
+    private func rowButton(_ title: String, tint: Color, disabled: Bool = false, action: @escaping () -> Void) -> some View {
+        Button(action: action) {
+            Text(title)
+                .font(.system(size: AppMetrics.FontSize.caption, weight: .semibold))
+                .foregroundStyle(disabled ? AppDesign.textSecondary : tint)
+                .frame(maxWidth: .infinity)
+                .frame(height: 34)
+                .background((disabled ? Color(hex: 0xEEF2F7) : tint.opacity(0.12)), in: RoundedRectangle(cornerRadius: 8))
+        }
+        .buttonStyle(.plain)
+        .disabled(disabled)
+    }
+}
+
+/// 押金订单详情页，展示订单基础信息和拍摄点列表。
+struct DepositOrderDetailView: View {
+    @Environment(AccountContext.self) private var accountContext
+    @Environment(OrdersAPI.self) private var ordersAPI
+    @Environment(RouterPath.self) private var router
+    @Environment(\.globalLoading) private var globalLoading
+
+    let orderNumber: String
+    @State private var viewModel = DepositOrderDetailViewModel()
+
+    var body: some View {
+        List {
+            if let detail = viewModel.detail {
+                Section("订单信息") {
+                    OrderDetailValueRow(title: "订单号", value: detail.orderNumber)
+                    OrderDetailValueRow(title: "订单状态", value: detail.orderStatusName)
+                    OrderDetailValueRow(title: "订单类型", value: detail.orderTypeLabel)
+                    OrderDetailValueRow(title: "项目名称", value: detail.projectName)
+                    OrderDetailValueRow(title: "订单金额", value: "¥\(detail.actualPayAmount.isEmpty ? "0.00" : detail.actualPayAmount)")
+                    OrderDetailValueRow(title: "退款金额", value: "¥\(detail.actualRefundAmount.isEmpty ? "0" : detail.actualRefundAmount)")
+                    OrderDetailValueRow(title: "手机号", value: detail.phone)
+                    OrderDetailValueRow(title: "下单时间", value: detail.createdAt)
+                    OrderDetailValueRow(title: "付款时间", value: detail.payTime)
+                    OrderDetailValueRow(title: "完成时间", value: detail.completeTime)
+                }
+
+                if let projectInfo = detail.multiTravel?.projectInfo {
+                    Section("项目配置") {
+                        OrderDetailValueRow(title: "打卡点数", value: "\(projectInfo.settleSpotNum)")
+                        OrderDetailValueRow(title: "单点底片", value: "\(projectInfo.singleSpotMaterialNum)")
+                        OrderDetailValueRow(title: "单点精修", value: "\(projectInfo.singleSpotPhotoNum)")
+                        OrderDetailValueRow(title: "单点视频", value: "\(projectInfo.singleSpotVideoNum)")
+                    }
+                }
+
+                Section("拍摄详情") {
+                    let shootingList = detail.multiTravel?.shootingList ?? []
+                    if shootingList.isEmpty {
+                        ContentUnavailableView("暂无拍摄记录", systemImage: "photo.stack")
+                    } else {
+                        ForEach(shootingList) { item in
+                            Button {
+                                router.navigate(
+                                    to: .orders(
+                                        .depositShootingInfo(
+                                            orderNumber: detail.orderNumber,
+                                            scenicSpotId: item.scenicSpotId,
+                                            photogUid: item.photogUid
+                                        )
+                                    )
+                                )
+                            } label: {
+                                DepositShootingPointRow(item: item)
+                            }
+                        }
+                    }
+                }
+            } else {
+                Section {
+                    ContentUnavailableView("暂无订单详情", systemImage: "doc.text.magnifyingglass")
+                        .frame(maxWidth: .infinity, minHeight: 220)
+                }
+            }
+        }
+        .listStyle(.insetGrouped)
+        .scrollContentBackground(.hidden)
+        .background(Color(hex: 0xF5F5F5).ignoresSafeArea())
+        .navigationTitle("押金订单详情")
+        .navigationBarTitleDisplayMode(.inline)
+        .task {
+            await globalLoading.withLoading {
+                await viewModel.load(api: ordersAPI, storeId: accountContext.currentStore?.id, orderNumber: orderNumber)
+            }
+        }
+        .alert("提示", isPresented: errorBinding) {
+            Button("知道了", role: .cancel) {}
+        } message: {
+            Text(viewModel.errorMessage ?? "")
+        }
+    }
+
+    private var errorBinding: Binding<Bool> {
+        Binding(
+            get: { viewModel.errorMessage != nil },
+            set: { if !$0 { viewModel.clearError() } }
+        )
+    }
+}
+
+/// 押金订单拍摄点行。
+private struct DepositShootingPointRow: View {
+    let item: StoreOrderShootingListItem
+
+    var body: some View {
+        HStack {
+            VStack(alignment: .leading, spacing: AppMetrics.Spacing.xSmall) {
+                Text(title)
+                    .font(.system(size: AppMetrics.FontSize.subheadline, weight: .semibold))
+                    .foregroundStyle(AppDesign.textPrimary)
+                Text(item.photogName.isEmpty ? "摄影师未分配" : item.photogName)
+                    .font(.system(size: AppMetrics.FontSize.caption))
+                    .foregroundStyle(AppDesign.textSecondary)
+            }
+            Spacer()
+            VStack(alignment: .trailing, spacing: AppMetrics.Spacing.xSmall) {
+                Text(item.status == 2 ? "已拍摄" : "待拍摄")
+                    .font(.system(size: AppMetrics.FontSize.caption, weight: .medium))
+                    .foregroundStyle(item.status == 2 ? Color(hex: 0x22C55E) : AppDesign.primary)
+                Text(String(format: "评分 %.1f", max(item.startAvg, item.start)))
+                    .font(.system(size: AppMetrics.FontSize.caption))
+                    .foregroundStyle(AppDesign.textSecondary)
+            }
+            Image(systemName: "chevron.right")
+                .font(.system(size: AppMetrics.FontSize.caption, weight: .semibold))
+                .foregroundStyle(AppDesign.textSecondary)
+        }
+    }
+
+    private var title: String {
+        let text = item.scenicSpotName.isEmpty ? item.staffName : item.scenicSpotName
+        return text.isEmpty ? "未命名打卡点" : text
+    }
+}
+
+/// 押金拍摄信息页，展示评价、底片和成片。
+struct DepositOrderShootingInfoView: View {
+    @Environment(AccountContext.self) private var accountContext
+    @Environment(OrdersAPI.self) private var ordersAPI
+    @Environment(\.globalLoading) private var globalLoading
+
+    let orderNumber: String
+    let scenicSpotId: Int
+    let photogUid: Int
+
+    @State private var viewModel = DepositOrderShootingInfoViewModel()
+    @State private var selectedTab: DepositShootingMediaTab = .negative
+
+    var body: some View {
+        List {
+            if let detail = viewModel.detail {
+                Section("拍摄点") {
+                    OrderDetailValueRow(title: "名称", value: detail.scenicSpotName)
+                    OrderDetailValueRow(title: "订单类型", value: detail.orderTypeName)
+                }
+
+                Section("评分与评价") {
+                    if let comment = detail.orderComment {
+                        RatingRow(title: "拍摄满意度", score: comment.starShooting)
+                        RatingRow(title: "修图满意度", score: comment.starRetouching)
+                        RatingRow(title: "景区满意度", score: comment.starScenery)
+                        RatingRow(title: "服务满意度", score: comment.starService)
+                        RatingRow(title: "相机满意度", score: comment.starCamera)
+                        Text(comment.content.isEmpty ? "暂无评价内容" : comment.content)
+                            .font(.system(size: AppMetrics.FontSize.subheadline))
+                            .foregroundStyle(AppDesign.textSecondary)
+                    } else {
+                        ContentUnavailableView("暂无评价信息", systemImage: "star")
+                    }
+                }
+
+                Section {
+                    Picker("媒体类型", selection: $selectedTab) {
+                        Text("底片").tag(DepositShootingMediaTab.negative)
+                        Text("成片").tag(DepositShootingMediaTab.complete)
+                    }
+                    .pickerStyle(.segmented)
+
+                    OrderMediaGrid(files: selectedTab == .negative ? detail.materialList : detail.completeList)
+                } header: {
+                    Text("媒体文件")
+                }
+            } else {
+                Section {
+                    ContentUnavailableView("暂无拍摄信息", systemImage: "photo.stack")
+                        .frame(maxWidth: .infinity, minHeight: 220)
+                }
+            }
+        }
+        .listStyle(.insetGrouped)
+        .scrollContentBackground(.hidden)
+        .background(Color(hex: 0xF5F5F5).ignoresSafeArea())
+        .navigationTitle("拍摄信息")
+        .navigationBarTitleDisplayMode(.inline)
+        .task {
+            await globalLoading.withLoading {
+                await viewModel.load(
+                    api: ordersAPI,
+                    storeId: accountContext.currentStore?.id,
+                    orderNumber: orderNumber,
+                    scenicSpotId: scenicSpotId,
+                    photogUid: photogUid
+                )
+            }
+        }
+        .alert("提示", isPresented: errorBinding) {
+            Button("知道了", role: .cancel) {}
+        } message: {
+            Text(viewModel.errorMessage ?? "")
+        }
+    }
+
+    private var errorBinding: Binding<Bool> {
+        Binding(
+            get: { viewModel.errorMessage != nil },
+            set: { if !$0 { viewModel.clearError() } }
+        )
+    }
+}
+
+/// 历史拍摄信息页，展示多点位拍摄媒体。
+struct HistoricalShootingInfoView: View {
+    @Environment(OrdersAPI.self) private var ordersAPI
+    @Environment(\.globalLoading) private var globalLoading
+
+    let orderNumber: String
+    @State private var viewModel = HistoricalShootingInfoViewModel()
+
+    var body: some View {
+        List {
+            Section("订单") {
+                OrderDetailValueRow(title: "订单号", value: orderNumber)
+                OrderDetailValueRow(title: "项目名称", value: viewModel.projectName)
+                OrderDetailValueRow(title: "项目类型", value: viewModel.projectTypeName)
+            }
+
+            Section("历史拍摄") {
+                if viewModel.spots.isEmpty {
+                    ContentUnavailableView("暂无历史拍摄信息", systemImage: "photo.on.rectangle")
+                        .frame(maxWidth: .infinity, minHeight: 220)
+                } else {
+                    ForEach(viewModel.spots) { spot in
+                        VStack(alignment: .leading, spacing: AppMetrics.Spacing.small) {
+                            HStack {
+                                Label(spot.scenicSpotName.isEmpty ? "未命名打卡点" : spot.scenicSpotName, systemImage: "mappin.and.ellipse")
+                                    .font(.system(size: AppMetrics.FontSize.subheadline, weight: .semibold))
+                                    .foregroundStyle(AppDesign.primary)
+                                Spacer()
+                                Text("摄影师：\(spot.photographerDisplayName)")
+                                    .font(.system(size: AppMetrics.FontSize.caption))
+                                    .foregroundStyle(AppDesign.textSecondary)
+                            }
+                            OrderMediaGrid(files: spot.files)
+                        }
+                        .padding(.vertical, AppMetrics.Spacing.xSmall)
+                    }
+                }
+            }
+        }
+        .listStyle(.insetGrouped)
+        .scrollContentBackground(.hidden)
+        .background(Color(hex: 0xF5F5F5).ignoresSafeArea())
+        .navigationTitle("历史拍摄")
+        .navigationBarTitleDisplayMode(.inline)
+        .task {
+            await globalLoading.withLoading {
+                await viewModel.load(api: ordersAPI, orderNumber: orderNumber)
+            }
+        }
+        .alert("提示", isPresented: errorBinding) {
+            Button("知道了", role: .cancel) {}
+        } message: {
+            Text(viewModel.errorMessage ?? "")
+        }
+    }
+
+    private var errorBinding: Binding<Bool> {
+        Binding(
+            get: { viewModel.errorMessage != nil },
+            set: { if !$0 { viewModel.clearError() } }
+        )
+    }
+}
+
+/// 拍摄媒体类型。
+private enum DepositShootingMediaTab: Hashable {
+    case negative
+    case complete
+}
+
+/// 通用订单详情键值行。
+private struct OrderDetailValueRow: View {
+    let title: String
+    let value: String
+
+    var body: some View {
+        HStack(alignment: .top) {
+            Text(title)
+                .font(.system(size: AppMetrics.FontSize.subheadline))
+                .foregroundStyle(AppDesign.textSecondary)
+            Spacer(minLength: AppMetrics.Spacing.medium)
+            Text(value.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty ? "--" : value)
+                .font(.system(size: AppMetrics.FontSize.subheadline, weight: .medium))
+                .foregroundStyle(AppDesign.textPrimary)
+                .multilineTextAlignment(.trailing)
+        }
+    }
+}
+
+/// 评分展示行。
+private struct RatingRow: View {
+    let title: String
+    let score: Int
+
+    var body: some View {
+        HStack {
+            Text(title)
+                .font(.system(size: AppMetrics.FontSize.subheadline))
+                .foregroundStyle(AppDesign.textSecondary)
+            Spacer()
+            Text(String(repeating: "★", count: max(score, 0)))
+                .font(.system(size: AppMetrics.FontSize.subheadline))
+                .foregroundStyle(Color(hex: 0xF59E0B))
+        }
+    }
+}
+
+/// 订单媒体网格，统一展示图片和视频缩略图。
+private struct OrderMediaGrid: View {
+    let files: [OrderMediaFile]
+
+    private let columns = [
+        GridItem(.flexible(), spacing: AppMetrics.Spacing.small),
+        GridItem(.flexible(), spacing: AppMetrics.Spacing.small),
+        GridItem(.flexible(), spacing: AppMetrics.Spacing.small)
+    ]
+
+    var body: some View {
+        if files.isEmpty {
+            ContentUnavailableView("暂无媒体文件", systemImage: "photo")
+                .frame(maxWidth: .infinity, minHeight: 140)
+        } else {
+            LazyVGrid(columns: columns, spacing: AppMetrics.Spacing.small) {
+                ForEach(files) { file in
+                    Link(destination: URL(string: file.fileUrl) ?? APIEnvironment.production.baseURL) {
+                        ZStack(alignment: .bottomTrailing) {
+                            RemoteImage(urlString: file.previewURLString) {
+                                RoundedRectangle(cornerRadius: 8)
+                                    .fill(AppDesign.primarySoft)
+                            }
+                            .frame(height: 88)
+                            .clipShape(RoundedRectangle(cornerRadius: 8))
+
+                            if file.isVideo {
+                                Image(systemName: "play.circle.fill")
+                                    .font(.system(size: 18, weight: .semibold))
+                                    .foregroundStyle(.white)
+                                    .shadow(radius: 2)
+                                    .padding(AppMetrics.Spacing.xSmall)
+                            }
+                        }
+                    }
+                    .buttonStyle(.plain)
+                }
+            }
+        }
+    }
+}

suixinkan/Features/Orders/Views/OrderDetailViews.swift

@@ -17,6 +17,8 @@ struct StoreOrderDetailView: View {
 
     let item: OrderEntity
     @State private var viewModel: OrderDetailViewModel
+    @State private var refundViewModel = OrderRefundViewModel()
+    @State private var showRefundSheet = false
 
     /// 使用列表订单初始化详情页，并创建详情 ViewModel。
     init(item: OrderEntity) {
@@ -96,10 +98,36 @@ struct StoreOrderDetailView: View {
             }
 
             Section("后续功能") {
-                placeholderButton("历史拍摄", title: "历史拍摄")
-                placeholderButton("任务上传", title: "任务上传")
-                placeholderButton("视频预告", title: "视频预告")
-                placeholderButton("退款", title: "订单退款")
+                Button {
+                    router.navigate(to: .orders(.historicalShooting(orderNumber: viewModel.display.orderNumber)))
+                } label: {
+                    navigationRow("历史拍摄")
+                }
+                if item.orderType == 19 {
+                    Button {
+                        router.navigate(to: .orders(.multiTravelTaskUpload(orderNumber: viewModel.display.orderNumber)))
+                    } label: {
+                        navigationRow("任务上传")
+                    }
+                }
+                Button {
+                    router.navigate(to: .orders(.orderTrailer(orderNumber: viewModel.display.orderNumber, title: "视频预告")))
+                } label: {
+                    navigationRow("视频预告")
+                }
+                Button {
+                    router.navigate(to: .orders(.orderTrailer(orderNumber: viewModel.display.orderNumber, title: "尾片上传")))
+                } label: {
+                    navigationRow("尾片上传")
+                }
+                if refundViewModel.canRefund(item) {
+                    Button {
+                        refundViewModel.begin(item: item)
+                        showRefundSheet = true
+                    } label: {
+                        navigationRow("退款")
+                    }
+                }
             }
         }
         .listStyle(.insetGrouped)
@@ -117,6 +145,17 @@ struct StoreOrderDetailView: View {
         } message: {
             Text(viewModel.errorMessage ?? "")
         }
+        .sheet(isPresented: $showRefundSheet) {
+            OrderRefundSheet(
+                item: item,
+                viewModel: refundViewModel,
+                onCancel: { showRefundSheet = false },
+                onSubmit: {
+                    Task { await submitRefund() }
+                }
+            )
+            .presentationDetents([.medium, .large])
+        }
     }
 
     private var displayPayTime: String {
@@ -136,20 +175,24 @@ struct StoreOrderDetailView: View {
         )
     }
 
-    /// 构建尚未迁移业务入口的占位按钮。
-    private func placeholderButton(_ label: String, title: String) -> some View {
-        Button {
-            router.navigate(to: .placeholder(title: title))
-        } label: {
-            HStack {
-                Text(label)
-                Spacer()
-                Image(systemName: "chevron.right")
-                    .font(.system(size: AppMetrics.FontSize.caption, weight: .semibold))
-                    .foregroundStyle(AppDesign.textSecondary)
-            }
+    /// 构建可跳转业务入口行。
+    private func navigationRow(_ label: String) -> some View {
+        HStack {
+            Text(label)
+            Spacer()
+            Image(systemName: "chevron.right")
+                .font(.system(size: AppMetrics.FontSize.caption, weight: .semibold))
+                .foregroundStyle(AppDesign.textSecondary)
         }
-        .foregroundStyle(AppDesign.textPrimary)
+    }
+
+    /// 提交普通订单退款并刷新详情。
+    private func submitRefund() async {
+        let success = await refundViewModel.submit(api: ordersAPI, item: item)
+        guard success else { return }
+        showRefundSheet = false
+        toastCenter.show("退款申请已提交")
+        await viewModel.load(api: ordersAPI, fallbackStoreId: accountContext.currentStore?.id, forceReload: true)
     }
 
     /// 将空金额转换为 0，避免详情页出现孤立货币符号。
@@ -158,6 +201,79 @@ struct StoreOrderDetailView: View {
     }
 }
 
+/// 普通订单退款表单，负责收集退款模式、金额和原因。
+private struct OrderRefundSheet: View {
+    let item: OrderEntity
+    @Bindable var viewModel: OrderRefundViewModel
+    let onCancel: () -> Void
+    let onSubmit: () -> Void
+    @FocusState private var focusedField: RefundInputField?
+
+    var body: some View {
+        NavigationStack {
+            Form {
+                Section("订单") {
+                    OrderDetailRow(title: "订单号", value: item.orderNumber)
+                    OrderDetailRow(title: "可退金额", value: "¥\(viewModel.availableAmountText(for: item))")
+                }
+
+                Section("退款方式") {
+                    Picker("退款方式", selection: $viewModel.mode) {
+                        ForEach(OrderRefundMode.allCases) { mode in
+                            Text(mode.title).tag(mode)
+                        }
+                    }
+                    .pickerStyle(.segmented)
+
+                    if viewModel.mode == .partial {
+                        TextField("请输入退款金额", text: $viewModel.amount)
+                            .keyboardType(.decimalPad)
+                            .focused($focusedField, equals: .amount)
+                    }
+                }
+
+                Section("退款原因") {
+                    TextEditor(text: $viewModel.reason)
+                        .frame(minHeight: 96)
+                        .focused($focusedField, equals: .reason)
+                }
+
+                if let errorMessage = viewModel.errorMessage {
+                    Section {
+                        Text(errorMessage)
+                            .font(.system(size: AppMetrics.FontSize.footnote))
+                            .foregroundStyle(Color(hex: 0xEF4444))
+                    }
+                }
+            }
+            .navigationTitle("订单退款")
+            .navigationBarTitleDisplayMode(.inline)
+            .toolbar {
+                ToolbarItem(placement: .cancellationAction) {
+                    Button("取消", action: onCancel)
+                        .disabled(viewModel.submitting)
+                }
+                ToolbarItem(placement: .confirmationAction) {
+                    Button(viewModel.submitting ? "提交中..." : "提交", action: onSubmit)
+                        .disabled(viewModel.submitting)
+                }
+                ToolbarItemGroup(placement: .keyboard) {
+                    Spacer()
+                    Button("完成") {
+                        focusedField = nil
+                    }
+                }
+            }
+        }
+    }
+}
+
+/// 退款表单当前聚焦字段。
+private enum RefundInputField: Hashable {
+    case amount
+    case reason
+}
+
 /// 核销订单详情页，展示核销列表项信息并支持再次发起核销。
 struct WriteOffOrderDetailView: View {
     @Environment(AccountContext.self) private var accountContext

suixinkan/Features/Orders/Views/OrderTailUploadViews.swift

@@ -0,0 +1,357 @@
+//
+//  OrderTailUploadViews.swift
+//  suixinkan
+//
+//  Created by Codex on 2026/6/25.
+//
+
+import PhotosUI
+import SwiftUI
+import UniformTypeIdentifiers
+
+/// 多点旅拍任务上传页面，负责选择打卡点和素材后提交到订单接口。
+struct MultiTravelTaskUploadView: View {
+    @Environment(AccountContext.self) private var accountContext
+    @Environment(OrdersAPI.self) private var ordersAPI
+    @Environment(OSSUploadService.self) private var uploadService
+    @Environment(ToastCenter.self) private var toastCenter
+    @Environment(\.dismiss) private var dismiss
+    @Environment(\.globalLoading) private var globalLoading
+
+    @State private var viewModel: MultiTravelTaskUploadViewModel
+    @State private var showSpotPicker = false
+    @State private var showCloudSelection = false
+    @State private var pickerItems: [PhotosPickerItem] = []
+
+    /// 使用订单号初始化任务上传页面。
+    init(initialOrderNumber: String) {
+        _viewModel = State(initialValue: MultiTravelTaskUploadViewModel(initialOrderNumber: initialOrderNumber))
+    }
+
+    var body: some View {
+        ScrollView {
+            VStack(spacing: AppMetrics.Spacing.medium) {
+                orderSection
+                cloudFileSection
+                localFileSection
+                submitButton
+            }
+            .padding(AppMetrics.Spacing.pageHorizontal)
+            .padding(.vertical, AppMetrics.Spacing.medium)
+        }
+        .background(Color(hex: 0xF5F7FA))
+        .navigationTitle("任务上传")
+        .navigationBarTitleDisplayMode(.inline)
+        .task {
+            await viewModel.loadSpots(api: ordersAPI)
+        }
+        .sheet(isPresented: $showCloudSelection) {
+            NavigationStack {
+                TaskCloudFileSelectionView { items in
+                    viewModel.mergeCloudFiles(items)
+                    showCloudSelection = false
+                }
+            }
+        }
+        .confirmationDialog("选择打卡点", isPresented: $showSpotPicker, titleVisibility: .visible) {
+            ForEach(viewModel.spots) { spot in
+                Button(spot.name.isEmpty ? "打卡点 \(spot.id)" : spot.name) {
+                    viewModel.selectSpot(id: spot.id)
+                }
+            }
+            Button("取消", role: .cancel) {}
+        }
+        .onChange(of: pickerItems) { _, items in
+            Task { await importPickerItems(items) }
+        }
+        .alert("提示", isPresented: errorBinding) {
+            Button("知道了", role: .cancel) {}
+        } message: {
+            Text(viewModel.errorMessage ?? "")
+        }
+    }
+
+    /// 订单号和打卡点选择区域。
+    private var orderSection: some View {
+        VStack(alignment: .leading, spacing: AppMetrics.Spacing.small) {
+            Text("基础信息")
+                .font(.system(size: AppMetrics.FontSize.body, weight: .semibold))
+                .foregroundStyle(AppDesign.textPrimary)
+
+            TextField("关联订单号", text: $viewModel.orderNumber)
+                .textInputAutocapitalization(.never)
+                .autocorrectionDisabled(true)
+                .appInputFieldStyle(cornerRadius: AppMetrics.CornerRadius.input, minHeight: AppMetrics.ControlSize.inputHeight)
+
+            HStack(spacing: AppMetrics.Spacing.small) {
+                Button(viewModel.isLoadingSpots ? "加载中..." : "刷新打卡点") {
+                    Task { await viewModel.loadSpots(api: ordersAPI) }
+                }
+                .disabled(viewModel.isLoadingSpots)
+                .font(.system(size: AppMetrics.FontSize.subheadline, weight: .semibold))
+                .foregroundStyle(AppDesign.primary)
+                .frame(width: 104, height: 40)
+                .background(AppDesign.primarySoft, in: RoundedRectangle(cornerRadius: AppMetrics.CornerRadius.input))
+
+                Button {
+                    showSpotPicker = true
+                } label: {
+                    HStack(spacing: AppMetrics.Spacing.xSmall) {
+                        Text(viewModel.selectedSpotName)
+                            .lineLimit(1)
+                        Spacer()
+                        Image(systemName: "chevron.down")
+                            .font(.system(size: AppMetrics.FontSize.caption, weight: .semibold))
+                    }
+                    .font(.system(size: AppMetrics.FontSize.subheadline, weight: .medium))
+                    .foregroundStyle(AppDesign.textPrimary)
+                    .padding(.horizontal, AppMetrics.Spacing.small)
+                    .frame(maxWidth: .infinity)
+                    .frame(height: 40)
+                    .background(Color(hex: 0xF3F4F6), in: RoundedRectangle(cornerRadius: AppMetrics.CornerRadius.input))
+                }
+                .buttonStyle(.plain)
+                .disabled(viewModel.spots.isEmpty)
+            }
+
+            if viewModel.spots.isEmpty && !viewModel.isLoadingSpots {
+                Text("暂无可选打卡点，请确认订单已完成核销。")
+                    .font(.system(size: AppMetrics.FontSize.footnote))
+                    .foregroundStyle(AppDesign.textSecondary)
+            }
+        }
+        .padding(AppMetrics.Spacing.medium)
+        .background(.white, in: RoundedRectangle(cornerRadius: AppMetrics.CornerRadius.card))
+    }
+
+    /// 云盘素材选择区域。
+    private var cloudFileSection: some View {
+        VStack(alignment: .leading, spacing: AppMetrics.Spacing.small) {
+            HStack {
+                Text("云盘素材")
+                    .font(.system(size: AppMetrics.FontSize.body, weight: .semibold))
+                    .foregroundStyle(AppDesign.textPrimary)
+                Spacer()
+                Button("选择云盘文件") {
+                    showCloudSelection = true
+                }
+                .font(.system(size: AppMetrics.FontSize.subheadline, weight: .semibold))
+                .foregroundStyle(AppDesign.primary)
+            }
+
+            if viewModel.selectedCloudFiles.isEmpty {
+                Text("未选择云盘文件")
+                    .font(.system(size: AppMetrics.FontSize.subheadline))
+                    .foregroundStyle(AppDesign.textSecondary)
+            } else {
+                ForEach(viewModel.selectedCloudFiles) { file in
+                    OrderTaskAttachmentRow(
+                        title: file.fileName.isEmpty ? "文件 \(file.id)" : file.fileName,
+                        subtitle: "云盘文件"
+                    ) {
+                        viewModel.removeCloudFile(id: file.id)
+                    }
+                }
+            }
+        }
+        .padding(AppMetrics.Spacing.medium)
+        .background(.white, in: RoundedRectangle(cornerRadius: AppMetrics.CornerRadius.card))
+    }
+
+    /// 本地素材选择区域。
+    private var localFileSection: some View {
+        VStack(alignment: .leading, spacing: AppMetrics.Spacing.small) {
+            HStack {
+                Text("本地素材")
+                    .font(.system(size: AppMetrics.FontSize.body, weight: .semibold))
+                    .foregroundStyle(AppDesign.textPrimary)
+                Spacer()
+                PhotosPicker(selection: $pickerItems, maxSelectionCount: 9, matching: .any(of: [.images, .videos])) {
+                    Text("选择图片/视频")
+                        .font(.system(size: AppMetrics.FontSize.subheadline, weight: .semibold))
+                        .foregroundStyle(AppDesign.primary)
+                }
+            }
+
+            if viewModel.selectedLocalFiles.isEmpty {
+                Text("未选择本地文件")
+                    .font(.system(size: AppMetrics.FontSize.subheadline))
+                    .foregroundStyle(AppDesign.textSecondary)
+            } else {
+                ForEach(viewModel.selectedLocalFiles) { file in
+                    OrderTaskAttachmentRow(title: file.fileName, subtitle: file.statusText) {
+                        viewModel.removeLocalFile(id: file.id)
+                    }
+                }
+            }
+        }
+        .padding(AppMetrics.Spacing.medium)
+        .background(.white, in: RoundedRectangle(cornerRadius: AppMetrics.CornerRadius.card))
+    }
+
+    /// 提交按钮。
+    private var submitButton: some View {
+        Button {
+            Task { await submit() }
+        } label: {
+            Text(viewModel.isSubmitting ? "保存中..." : "保存任务素材")
+                .font(.system(size: AppMetrics.FontSize.body, weight: .semibold))
+                .foregroundStyle(.white)
+                .frame(maxWidth: .infinity)
+                .frame(height: AppMetrics.ControlSize.primaryButtonHeight)
+                .background(viewModel.canSubmit ? AppDesign.primary : Color(hex: 0xC9CED6), in: RoundedRectangle(cornerRadius: AppMetrics.CornerRadius.button))
+        }
+        .disabled(!viewModel.canSubmit)
+    }
+
+    private var errorBinding: Binding<Bool> {
+        Binding(
+            get: { viewModel.errorMessage != nil },
+            set: { visible in
+                if !visible { viewModel.clearError() }
+            }
+        )
+    }
+
+    /// 导入本地图片或视频。
+    private func importPickerItems(_ items: [PhotosPickerItem]) async {
+        for item in items {
+            do {
+                guard let data = try await item.loadTransferable(type: Data.self) else { continue }
+                viewModel.addLocalFile(data: data, fileName: Self.fileName(for: item))
+            } catch {
+                toastCenter.show(error.localizedDescription)
+            }
+        }
+        pickerItems = []
+    }
+
+    /// 提交任务素材。
+    private func submit() async {
+        let success = await globalLoading.withLoading {
+            await viewModel.submit(api: ordersAPI, uploadService: uploadService, scenicId: accountContext.currentScenic?.id)
+        }
+        if success {
+            toastCenter.show("任务素材已保存")
+            dismiss()
+        } else if let message = viewModel.errorMessage {
+            toastCenter.show(message)
+        }
+    }
+
+    /// 根据 PhotosPicker 类型生成本地文件名。
+    private static func fileName(for item: PhotosPickerItem) -> String {
+        let isVideo = item.supportedContentTypes.contains { $0.conforms(to: .movie) || $0.conforms(to: .video) }
+        return "\(UUID().uuidString).\(isVideo ? "mp4" : "jpg")"
+    }
+}
+
+/// 订单尾片入口页面，复用相册预览上传能力承接视频预告和尾片上传。
+struct OrderTrailerView: View {
+    @State private var showAlbumTrailer = false
+
+    let orderNumber: String
+    let title: String
+
+    var body: some View {
+        VStack(spacing: AppMetrics.Spacing.medium) {
+            VStack(alignment: .leading, spacing: AppMetrics.Spacing.small) {
+                Text(title)
+                    .font(.system(size: AppMetrics.FontSize.title3, weight: .semibold))
+                    .foregroundStyle(AppDesign.textPrimary)
+                Text("订单号：\(orderNumber.isEmpty ? "--" : orderNumber)")
+                    .font(.system(size: AppMetrics.FontSize.subheadline))
+                    .foregroundStyle(AppDesign.textSecondary)
+                Text("用于完成订单尾片素材的最终核对与提交，按“选择相册 -> 预览文件 -> 确认上传”流程操作。")
+                    .font(.system(size: AppMetrics.FontSize.footnote))
+                    .foregroundStyle(AppDesign.textSecondary)
+            }
+            .frame(maxWidth: .infinity, alignment: .leading)
+            .padding(AppMetrics.Spacing.medium)
+            .background(.white, in: RoundedRectangle(cornerRadius: AppMetrics.CornerRadius.card))
+
+            VStack(alignment: .leading, spacing: AppMetrics.Spacing.small) {
+                Text("提交流程")
+                    .font(.system(size: AppMetrics.FontSize.body, weight: .semibold))
+                    .foregroundStyle(AppDesign.textPrimary)
+                trailerStep("1. 进入相册预览上传并选择目标相册")
+                trailerStep("2. 核对素材内容与顺序后确认上传")
+                trailerStep("3. 上传完成后返回订单页继续处理")
+            }
+            .frame(maxWidth: .infinity, alignment: .leading)
+            .padding(AppMetrics.Spacing.medium)
+            .background(.white, in: RoundedRectangle(cornerRadius: AppMetrics.CornerRadius.card))
+
+            Button("打开相册预览上传") {
+                showAlbumTrailer = true
+            }
+            .font(.system(size: AppMetrics.FontSize.body, weight: .semibold))
+            .foregroundStyle(.white)
+            .frame(maxWidth: .infinity)
+            .frame(height: AppMetrics.ControlSize.primaryButtonHeight)
+            .background(AppDesign.primary, in: RoundedRectangle(cornerRadius: AppMetrics.CornerRadius.button))
+
+            Spacer()
+        }
+        .padding(AppMetrics.Spacing.pageHorizontal)
+        .padding(.vertical, AppMetrics.Spacing.medium)
+        .background(Color(hex: 0xF5F7FA).ignoresSafeArea())
+        .navigationTitle(title)
+        .navigationBarTitleDisplayMode(.inline)
+        .sheet(isPresented: $showAlbumTrailer) {
+            NavigationStack {
+                AlbumTrailerEntryView()
+            }
+        }
+    }
+
+    /// 构建尾片流程步骤行。
+    private func trailerStep(_ text: String) -> some View {
+        HStack(alignment: .top, spacing: AppMetrics.Spacing.small) {
+            Circle()
+                .fill(AppDesign.primary)
+                .frame(width: 6, height: 6)
+                .padding(.top, 6)
+            Text(text)
+                .font(.system(size: AppMetrics.FontSize.footnote))
+                .foregroundStyle(AppDesign.textSecondary)
+        }
+    }
+}
+
+/// 订单任务素材附件行。
+private struct OrderTaskAttachmentRow: View {
+    let title: String
+    let subtitle: String
+    let onDelete: () -> Void
+
+    var body: some View {
+        HStack(spacing: AppMetrics.Spacing.small) {
+            Image(systemName: "paperclip")
+                .foregroundStyle(AppDesign.primary)
+                .frame(width: AppMetrics.ControlSize.iconTapArea, height: AppMetrics.ControlSize.iconTapArea)
+                .background(AppDesign.primarySoft, in: Circle())
+
+            VStack(alignment: .leading, spacing: AppMetrics.Spacing.xxSmall) {
+                Text(title)
+                    .font(.system(size: AppMetrics.FontSize.subheadline, weight: .semibold))
+                    .foregroundStyle(AppDesign.textPrimary)
+                    .lineLimit(1)
+                Text(subtitle)
+                    .font(.system(size: AppMetrics.FontSize.caption))
+                    .foregroundStyle(AppDesign.textSecondary)
+            }
+
+            Spacer()
+
+            Button(action: onDelete) {
+                Image(systemName: "xmark.circle.fill")
+                    .foregroundStyle(AppDesign.placeholder)
+                    .frame(width: AppMetrics.ControlSize.iconTapArea, height: AppMetrics.ControlSize.iconTapArea)
+            }
+            .accessibilityLabel("删除附件")
+        }
+        .padding(AppMetrics.Spacing.small)
+        .background(Color(hex: 0xF8FAFC), in: RoundedRectangle(cornerRadius: AppMetrics.CornerRadius.input))
+    }
+}

suixinkan/Features/QueueManagement/API/ScenicQueueAPI.swift

@@ -0,0 +1,201 @@
+//
+//  ScenicQueueAPI.swift
+//  suixinkan
+//
+//  Created by Codex on 2026/6/25.
+//
+
+import Foundation
+import Observation
+
+/// 排队管理服务协议，定义列表、动作、设置、二维码和实时 token 能力。
+@MainActor
+protocol ScenicQueueServing: AnyObject {
+    func scenicQueueStats(scenicId: Int, scenicSpotId: Int) async throws -> ScenicQueueStatsData
+    func scenicQueueHome(scenicId: Int, scenicSpotId: Int, type: Int, page: Int, pageSize: Int) async throws -> ScenicQueueHomeData
+    func socketToken() async throws -> SocketTokenResponse
+    func scenicQueueCall(id: Int64) async throws -> ScenicQueueCallData
+    func scenicQueuePass(id: Int64) async throws -> ScenicQueuePassData
+    func scenicQueueFinish(id: Int64) async throws -> ScenicQueueFinishData
+    func scenicQueueRequeueInsertBefore(recordId: Int64, operatorId: Int) async throws
+    func scenicQueueUserMark(_ request: ScenicQueueUserMarkRequest) async throws
+    func scenicQueueSetting(scenicId: Int, scenicSpotId: Int?) async throws -> ScenicQueueSettingData
+    func scenicQueueSaveSetting(_ request: ScenicQueueSaveSettingRequest) async throws
+    func scenicQueueShootQueueQRCode(scenicId: Int, scenicSpotId: Int) async throws -> ScenicQueueShootQueueQRCodeData
+    func scenicQueueSettingChangeLog(scenicId: Int, scenicSpotId: Int?, page: Int, pageSize: Int) async throws -> ScenicQueueSettingChangeLogData
+}
+
+@MainActor
+@Observable
+/// 排队管理 API，封装 `/api/app/scenic-queue` 下的排队接口。
+final class ScenicQueueAPI {
+    @ObservationIgnored private let client: APIClient
+
+    /// 初始化排队管理 API，并注入共享网络客户端。
+    init(client: APIClient) {
+        self.client = client
+    }
+
+    /// 获取当前打卡点排队统计。
+    func scenicQueueStats(scenicId: Int, scenicSpotId: Int) async throws -> ScenicQueueStatsData {
+        do {
+            return try await client.send(
+                APIRequest(
+                    method: .get,
+                    path: "/api/app/scenic-queue/queue-stats",
+                    queryItems: [
+                        URLQueryItem(name: "scenic_id", value: String(scenicId)),
+                        URLQueryItem(name: "scenic_spot_id", value: String(scenicSpotId))
+                    ]
+                )
+            )
+        } catch APIError.emptyData {
+            return ScenicQueueStatsData()
+        }
+    }
+
+    /// 获取当前打卡点排队列表。
+    func scenicQueueHome(
+        scenicId: Int,
+        scenicSpotId: Int,
+        type: Int,
+        page: Int = 1,
+        pageSize: Int = 20
+    ) async throws -> ScenicQueueHomeData {
+        do {
+            return try await client.send(
+                APIRequest(
+                    method: .get,
+                    path: "/api/app/scenic-queue/home",
+                    queryItems: [
+                        URLQueryItem(name: "scenic_id", value: String(scenicId)),
+                        URLQueryItem(name: "scenic_spot_id", value: String(scenicSpotId)),
+                        URLQueryItem(name: "type", value: String(type)),
+                        URLQueryItem(name: "page", value: String(max(page, 1))),
+                        URLQueryItem(name: "page_size", value: String(max(pageSize, 1)))
+                    ]
+                )
+            )
+        } catch APIError.emptyData {
+            return ScenicQueueHomeData()
+        }
+    }
+
+    /// 获取 WebSocket 订阅 token。
+    func socketToken() async throws -> SocketTokenResponse {
+        try await client.send(APIRequest(method: .get, path: "/api/app/socket-token"))
+    }
+
+    /// 叫号。
+    func scenicQueueCall(id: Int64) async throws -> ScenicQueueCallData {
+        do {
+            return try await client.send(
+                APIRequest(method: .post, path: "/api/app/scenic-queue/call", body: ScenicQueueActionRequest(id: id))
+            )
+        } catch APIError.emptyData {
+            return ScenicQueueCallData(id: id)
+        }
+    }
+
+    /// 标记过号。
+    func scenicQueuePass(id: Int64) async throws -> ScenicQueuePassData {
+        do {
+            return try await client.send(
+                APIRequest(method: .post, path: "/api/app/scenic-queue/pass", body: ScenicQueueActionRequest(id: id))
+            )
+        } catch APIError.emptyData {
+            return ScenicQueuePassData(id: id)
+        }
+    }
+
+    /// 标记完成。
+    func scenicQueueFinish(id: Int64) async throws -> ScenicQueueFinishData {
+        do {
+            return try await client.send(
+                APIRequest(method: .post, path: "/api/app/scenic-queue/finish", body: ScenicQueueActionRequest(id: id))
+            )
+        } catch APIError.emptyData {
+            return ScenicQueueFinishData(id: id)
+        }
+    }
+
+    /// 将过号记录重新插回当前排队队列。
+    func scenicQueueRequeueInsertBefore(recordId: Int64, operatorId: Int) async throws {
+        let _: EmptyPayload = try await client.send(
+            APIRequest(
+                method: .post,
+                path: "/api/app/scenic-queue/requeue-insert-before",
+                body: ScenicQueueRequeueInsertBeforeRequest(recordId: recordId, operatorId: operatorId)
+            )
+        )
+    }
+
+    /// 标记用户身份/限制排队。
+    func scenicQueueUserMark(_ request: ScenicQueueUserMarkRequest) async throws {
+        let _: EmptyPayload = try await client.send(
+            APIRequest(method: .post, path: "/api/app/scenic-queue/user-mark", body: request)
+        )
+    }
+
+    /// 获取排队设置。
+    func scenicQueueSetting(scenicId: Int, scenicSpotId: Int?) async throws -> ScenicQueueSettingData {
+        var query = [URLQueryItem(name: "scenic_id", value: String(scenicId))]
+        if let scenicSpotId {
+            query.append(URLQueryItem(name: "scenic_spot_id", value: String(scenicSpotId)))
+        }
+        do {
+            return try await client.send(
+                APIRequest(method: .get, path: "/api/app/scenic-queue/setting", queryItems: query)
+            )
+        } catch APIError.emptyData {
+            return ScenicQueueSettingData()
+        }
+    }
+
+    /// 保存排队设置。
+    func scenicQueueSaveSetting(_ request: ScenicQueueSaveSettingRequest) async throws {
+        let _: EmptyPayload = try await client.send(
+            APIRequest(method: .post, path: "/api/app/scenic-queue/save-setting", body: request)
+        )
+    }
+
+    /// 获取取号二维码。
+    func scenicQueueShootQueueQRCode(scenicId: Int, scenicSpotId: Int) async throws -> ScenicQueueShootQueueQRCodeData {
+        try await client.send(
+            APIRequest(
+                method: .get,
+                path: "/api/app/scenic-queue/shoot-queue-qrcode",
+                queryItems: [
+                    URLQueryItem(name: "scenic_id", value: String(scenicId)),
+                    URLQueryItem(name: "scenic_spot_id", value: String(scenicSpotId))
+                ]
+            )
+        )
+    }
+
+    /// 获取排队设置变更日志。
+    func scenicQueueSettingChangeLog(
+        scenicId: Int,
+        scenicSpotId: Int?,
+        page: Int = 1,
+        pageSize: Int = 20
+    ) async throws -> ScenicQueueSettingChangeLogData {
+        var query = [
+            URLQueryItem(name: "scenic_id", value: String(scenicId)),
+            URLQueryItem(name: "page", value: String(max(page, 1))),
+            URLQueryItem(name: "page_size", value: String(max(pageSize, 1)))
+        ]
+        if let scenicSpotId {
+            query.append(URLQueryItem(name: "scenic_spot_id", value: String(scenicSpotId)))
+        }
+        do {
+            return try await client.send(
+                APIRequest(method: .get, path: "/api/app/scenic-queue/setting-change-log", queryItems: query)
+            )
+        } catch APIError.emptyData {
+            return ScenicQueueSettingChangeLogData()
+        }
+    }
+}
+
+extension ScenicQueueAPI: ScenicQueueServing {}

suixinkan/Features/QueueManagement/Models/ScenicQueueModels.swift

@@ -0,0 +1,491 @@
+//
+//  ScenicQueueModels.swift
+//  suixinkan
+//
+//  Created by Codex on 2026/6/25.
+//
+
+import Foundation
+
+/// 排队统计响应。
+struct ScenicQueueStatsData: Decodable, Equatable {
+    let queueCount: Int
+    let avgWaitMin: Double
+    let time: String
+
+    enum CodingKeys: String, CodingKey {
+        case queueCount = "queue_count"
+        case avgWaitMin = "avg_wait_min"
+        case time
+    }
+
+    /// 创建排队统计，主要用于空响应兜底。
+    init(queueCount: Int = 0, avgWaitMin: Double = 0, time: String = "") {
+        self.queueCount = queueCount
+        self.avgWaitMin = avgWaitMin
+        self.time = time
+    }
+
+    /// 宽松解码统计字段。
+    init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        queueCount = try container.decodeLossyInt(forKey: .queueCount) ?? 0
+        avgWaitMin = try container.decodeLossyDouble(forKey: .avgWaitMin) ?? 0
+        time = try container.decodeLossyString(forKey: .time)
+    }
+}
+
+/// 排队首页响应，兼容 list 为数组或分页对象两种形态。
+struct ScenicQueueHomeData: Decodable, Equatable {
+    let stats: ScenicQueueHomeStats?
+    let list: ScenicQueueHomeListBlock?
+    let time: String?
+
+    enum CodingKeys: String, CodingKey {
+        case stats
+        case list
+        case time
+    }
+
+    /// 创建排队首页数据，主要用于空响应兜底。
+    init(stats: ScenicQueueHomeStats? = nil, list: ScenicQueueHomeListBlock? = nil, time: String? = nil) {
+        self.stats = stats
+        self.list = list
+        self.time = time
+    }
+
+    /// 宽松解码排队首页数据。
+    init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        stats = try container.decodeIfPresent(ScenicQueueHomeStats.self, forKey: .stats)
+        if let block = try? container.decodeIfPresent(ScenicQueueHomeListBlock.self, forKey: .list) {
+            list = block
+        } else if let tickets = try? container.decodeIfPresent([ScenicQueueTicket].self, forKey: .list) {
+            list = ScenicQueueHomeListBlock(list: tickets)
+        } else {
+            list = nil
+        }
+        time = try container.decodeIfPresent(String.self, forKey: .time)
+    }
+}
+
+/// 排队首页统计块。
+struct ScenicQueueHomeStats: Decodable, Equatable {
+    let type: Int
+
+    enum CodingKeys: String, CodingKey {
+        case type
+    }
+
+    /// 创建统计块。
+    init(type: Int = 0) {
+        self.type = type
+    }
+
+    /// 宽松解码统计块。
+    init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        type = try container.decodeLossyInt(forKey: .type) ?? 0
+    }
+}
+
+/// 排队列表分页块。
+struct ScenicQueueHomeListBlock: Decodable, Equatable {
+    let list: [ScenicQueueTicket]
+    let total: Int
+    let page: Int
+    let pageSize: Int
+
+    enum CodingKeys: String, CodingKey {
+        case list
+        case total
+        case page
+        case pageSize = "page_size"
+    }
+
+    /// 创建分页块。
+    init(list: [ScenicQueueTicket] = [], total: Int? = nil, page: Int = 1, pageSize: Int = 20) {
+        self.list = list
+        self.total = total ?? list.count
+        self.page = page
+        self.pageSize = pageSize
+    }
+
+    /// 宽松解码分页块。
+    init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        list = try container.decodeIfPresent([ScenicQueueTicket].self, forKey: .list) ?? []
+        total = try container.decodeLossyInt(forKey: .total) ?? list.count
+        page = try container.decodeLossyInt(forKey: .page) ?? 1
+        pageSize = try container.decodeLossyInt(forKey: .pageSize) ?? max(list.count, 20)
+    }
+}
+
+/// 单个排队取号记录。
+struct ScenicQueueTicket: Decodable, Equatable, Identifiable {
+    let id: Int64
+    let queueCode: String
+    let mobile: String
+    let status: Int
+    let statusText: String
+    let waitMin: Int
+    let aheadCount: Int
+    let isCalled: Int
+    let createdAt: String
+    let calledAt: String
+    let expiredAt: String
+    let finishedAt: String
+    let queueBanLabel: String
+    let identityTag: String
+    let queueTime: String
+    let queueCountToday: Int
+    let uid: Int64
+    let markAsPhotog: Int
+    let markAsFreelancePhotog: Int
+    let isMissRequeue: Int
+    let missRequeueText: String
+
+    var phoneMasked: String {
+        let digits = mobile.filter(\.isNumber)
+        if mobile.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty { return "--" }
+        guard digits.count >= 7 else { return mobile }
+        return "\(digits.prefix(3))****\(digits.suffix(4))"
+    }
+
+    var dialPhoneDigits: String {
+        let digits = mobile.filter(\.isNumber)
+        return digits.isEmpty ? mobile.filter { !$0.isWhitespace } : digits
+    }
+
+    var queueTimeDisplay: String {
+        Self.formatQueueTime(queueTime.nonEmptyOrDefault(createdAt))
+    }
+
+    var skippedTimeDisplay: String {
+        Self.formatQueueTime(expiredAt.nonEmptyOrDefault(calledAt.nonEmptyOrDefault(createdAt)))
+    }
+
+    var shouldShowIdentityTag: Bool {
+        let text = identityTag.trimmingCharacters(in: .whitespacesAndNewlines)
+        return !text.isEmpty && text != "普通用户"
+    }
+
+    var isMissRequeueRecord: Bool {
+        isMissRequeue == 1
+    }
+
+    enum CodingKeys: String, CodingKey {
+        case id
+        case queueCode = "queue_code"
+        case mobile
+        case status
+        case statusText = "status_text"
+        case waitMin = "wait_min"
+        case aheadCount = "ahead_count"
+        case isCalled = "is_called"
+        case createdAt = "created_at"
+        case calledAt = "called_at"
+        case expiredAt = "expired_at"
+        case finishedAt = "finished_at"
+        case queueBanLabel = "queue_ban_label"
+        case identityTag = "identity_tag"
+        case queueTime = "queue_time"
+        case queueCountToday = "queue_count_today"
+        case uid
+        case markAsPhotog = "mark_as_photog"
+        case markAsFreelancePhotog = "mark_as_freelance_photog"
+        case isMissRequeue = "is_miss_requeue"
+        case missRequeueText = "is_miss_requeue_text"
+    }
+
+    enum AlternateCodingKeys: String, CodingKey {
+        case queueNo = "queue_no"
+        case queueNumber = "queue_number"
+        case code
+        case phone
+        case statusName = "status_name"
+    }
+
+    /// 创建取号记录，主要用于本地状态替换和测试。
+    init(
+        id: Int64,
+        queueCode: String,
+        mobile: String,
+        status: Int,
+        statusText: String,
+        waitMin: Int,
+        aheadCount: Int,
+        isCalled: Int,
+        createdAt: String,
+        calledAt: String,
+        expiredAt: String,
+        finishedAt: String,
+        queueBanLabel: String = "",
+        identityTag: String = "",
+        queueTime: String = "",
+        queueCountToday: Int = 0,
+        uid: Int64 = 0,
+        markAsPhotog: Int = 0,
+        markAsFreelancePhotog: Int = 0,
+        isMissRequeue: Int = 0,
+        missRequeueText: String = ""
+    ) {
+        self.id = id
+        self.queueCode = queueCode
+        self.mobile = mobile
+        self.status = status
+        self.statusText = statusText
+        self.waitMin = waitMin
+        self.aheadCount = aheadCount
+        self.isCalled = isCalled
+        self.createdAt = createdAt
+        self.calledAt = calledAt
+        self.expiredAt = expiredAt
+        self.finishedAt = finishedAt
+        self.queueBanLabel = queueBanLabel
+        self.identityTag = identityTag
+        self.queueTime = queueTime
+        self.queueCountToday = queueCountToday
+        self.uid = uid
+        self.markAsPhotog = markAsPhotog
+        self.markAsFreelancePhotog = markAsFreelancePhotog
+        self.isMissRequeue = isMissRequeue
+        self.missRequeueText = missRequeueText
+    }
+
+    /// 宽松解码取号记录，兼容 Android 历史字段别名。
+    init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        let alternate = try decoder.container(keyedBy: AlternateCodingKeys.self)
+        id = Int64(try container.decodeLossyInt(forKey: .id) ?? 0)
+        queueCode = try container.decodeLossyString(forKey: .queueCode)
+            .nonEmptyOrDefault(
+                try alternate.decodeLossyString(forKey: .queueNo)
+                    .nonEmptyOrDefault(
+                        try alternate.decodeLossyString(forKey: .queueNumber)
+                            .nonEmptyOrDefault(try alternate.decodeLossyString(forKey: .code))
+                    )
+            )
+        mobile = try container.decodeLossyString(forKey: .mobile)
+            .nonEmptyOrDefault(try alternate.decodeLossyString(forKey: .phone))
+        status = try container.decodeLossyInt(forKey: .status) ?? 0
+        statusText = try container.decodeLossyString(forKey: .statusText)
+            .nonEmptyOrDefault(try alternate.decodeLossyString(forKey: .statusName))
+        waitMin = try container.decodeLossyInt(forKey: .waitMin) ?? 0
+        aheadCount = try container.decodeLossyInt(forKey: .aheadCount) ?? 0
+        isCalled = try container.decodeLossyInt(forKey: .isCalled) ?? 0
+        createdAt = try container.decodeLossyString(forKey: .createdAt)
+        calledAt = try container.decodeLossyString(forKey: .calledAt)
+        expiredAt = try container.decodeLossyString(forKey: .expiredAt)
+        finishedAt = try container.decodeLossyString(forKey: .finishedAt)
+        queueBanLabel = try container.decodeLossyString(forKey: .queueBanLabel).trimmingCharacters(in: .whitespacesAndNewlines)
+        identityTag = try container.decodeLossyString(forKey: .identityTag).trimmingCharacters(in: .whitespacesAndNewlines)
+        queueTime = try container.decodeLossyString(forKey: .queueTime)
+        queueCountToday = max(try container.decodeLossyInt(forKey: .queueCountToday) ?? 0, 0)
+        uid = Int64(try container.decodeLossyInt(forKey: .uid) ?? 0)
+        markAsPhotog = try container.decodeLossyInt(forKey: .markAsPhotog) ?? 0
+        markAsFreelancePhotog = try container.decodeLossyInt(forKey: .markAsFreelancePhotog) ?? 0
+        isMissRequeue = try container.decodeLossyInt(forKey: .isMissRequeue) ?? 0
+        missRequeueText = try container.decodeLossyString(forKey: .missRequeueText).trimmingCharacters(in: .whitespacesAndNewlines)
+    }
+
+    private static func formatQueueTime(_ raw: String) -> String {
+        let text = raw.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !text.isEmpty else { return "--" }
+        if text.range(of: #"^\d{2}-\d{2}\s+\d{2}:\d{2}$"#, options: .regularExpression) != nil {
+            return text
+        }
+        let formatter = DateFormatter()
+        formatter.locale = Locale(identifier: "en_US_POSIX")
+        for format in ["yyyy-MM-dd HH:mm:ss", "yyyy-MM-dd HH:mm"] {
+            formatter.dateFormat = format
+            if let date = formatter.date(from: text) {
+                formatter.dateFormat = "MM-dd HH:mm"
+                return formatter.string(from: date)
+            }
+        }
+        return text
+    }
+}
+
+/// 排队动作请求体。
+struct ScenicQueueActionRequest: Encodable {
+    let id: Int64
+}
+
+/// socket token 响应。
+struct SocketTokenResponse: Decodable, Equatable {
+    let socketToken: String
+
+    enum CodingKeys: String, CodingKey {
+        case socketToken = "socket_token"
+    }
+
+    /// 创建 socket token 响应。
+    init(socketToken: String = "") {
+        self.socketToken = socketToken
+    }
+
+    /// 宽松解码 socket token。
+    init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        socketToken = try container.decodeLossyString(forKey: .socketToken)
+    }
+}
+
+/// 排队动作响应。
+struct ScenicQueueActionData: Decodable, Equatable {
+    let id: Int64
+    let status: Int
+    let statusText: String
+    let calledAt: String?
+
+    enum CodingKeys: String, CodingKey {
+        case id
+        case status
+        case statusText = "status_text"
+        case calledAt = "called_at"
+    }
+
+    /// 创建动作响应。
+    init(id: Int64 = 0, status: Int = 0, statusText: String = "", calledAt: String? = nil) {
+        self.id = id
+        self.status = status
+        self.statusText = statusText
+        self.calledAt = calledAt
+    }
+
+    /// 宽松解码动作响应。
+    init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        id = Int64(try container.decodeLossyInt(forKey: .id) ?? 0)
+        status = try container.decodeLossyInt(forKey: .status) ?? 0
+        statusText = try container.decodeLossyString(forKey: .statusText)
+        calledAt = try container.decodeIfPresent(String.self, forKey: .calledAt)
+    }
+}
+
+typealias ScenicQueueCallData = ScenicQueueActionData
+typealias ScenicQueuePassData = ScenicQueueActionData
+typealias ScenicQueueFinishData = ScenicQueueActionData
+typealias QueueItem = ScenicQueueTicket
+
+/// 重新排队请求体。
+struct ScenicQueueRequeueInsertBeforeRequest: Encodable {
+    let recordId: Int64
+    let operatorId: Int
+
+    enum CodingKeys: String, CodingKey {
+        case recordId = "record_id"
+        case operatorId = "operator_id"
+    }
+}
+
+/// 用户标记请求体。
+struct ScenicQueueUserMarkRequest: Encodable, Equatable {
+    let uid: Int64
+    let scenicId: Int64
+    let markAsFreelancePhotog: Int
+    let queueBanDays: Int?
+    let operatorId: Int?
+
+    enum CodingKeys: String, CodingKey {
+        case uid
+        case scenicId = "scenic_id"
+        case markAsFreelancePhotog = "mark_as_freelance_photog"
+        case queueBanDays = "queue_ban_days"
+        case operatorId = "operator_id"
+    }
+}
+
+/// 排队列表类型。
+enum QueueListType: Int, CaseIterable, Identifiable {
+    case queueing = 1
+    case passed = 2
+
+    var id: Int { rawValue }
+
+    /// 分段标题。
+    var title: String {
+        switch self {
+        case .queueing:
+            return "当前排队"
+        case .passed:
+            return "过号列表"
+        }
+    }
+
+    /// 空态文案。
+    var emptyText: String {
+        switch self {
+        case .queueing:
+            return "暂无排队"
+        case .passed:
+            return "暂无过号"
+        }
+    }
+}
+
+/// 远端叫号提示。
+struct ScenicQueueRemoteCallAnnouncement: Identifiable, Equatable {
+    let id: Int64
+    let queueCode: String
+}
+
+private extension KeyedDecodingContainer {
+    func decodeLossyString(forKey key: Key) throws -> String {
+        if let value = try? decodeIfPresent(String.self, forKey: key) {
+            return value
+        }
+        if let value = try? decodeIfPresent(Int.self, forKey: key) {
+            return String(value)
+        }
+        if let value = try? decodeIfPresent(Double.self, forKey: key) {
+            return String(value)
+        }
+        if let value = try? decodeIfPresent(Bool.self, forKey: key) {
+            return value ? "1" : "0"
+        }
+        return ""
+    }
+
+    func decodeLossyInt(forKey key: Key) throws -> Int? {
+        if let value = try? decodeIfPresent(Int.self, forKey: key) {
+            return value
+        }
+        if let value = try? decodeIfPresent(Double.self, forKey: key) {
+            return Int(value)
+        }
+        if let value = try? decodeIfPresent(String.self, forKey: key),
+           case let text = value.trimmingCharacters(in: .whitespacesAndNewlines),
+           !text.isEmpty {
+            return Int(text) ?? Int(Double(text) ?? 0)
+        }
+        if let value = try? decodeIfPresent(Bool.self, forKey: key) {
+            return value ? 1 : 0
+        }
+        return nil
+    }
+
+    func decodeLossyDouble(forKey key: Key) throws -> Double? {
+        if let value = try? decodeIfPresent(Double.self, forKey: key) {
+            return value
+        }
+        if let value = try? decodeIfPresent(Int.self, forKey: key) {
+            return Double(value)
+        }
+        if let value = try? decodeIfPresent(String.self, forKey: key),
+           case let text = value.trimmingCharacters(in: .whitespacesAndNewlines),
+           !text.isEmpty {
+            return Double(text)
+        }
+        return nil
+    }
+}
+
+private extension String {
+    func nonEmptyOrDefault(_ fallback: String) -> String {
+        let text = trimmingCharacters(in: .whitespacesAndNewlines)
+        return text.isEmpty ? fallback : text
+    }
+}

suixinkan/Features/QueueManagement/Models/ScenicQueueSettingsModels.swift

@@ -0,0 +1,368 @@
+//
+//  ScenicQueueSettingsModels.swift
+//  suixinkan
+//
+//  Created by Codex on 2026/6/25.
+//
+
+import Foundation
+
+/// 排队设置响应。
+struct ScenicQueueSettingData: Decodable, Equatable {
+    let exists: Bool
+    let setting: ScenicQueueSettingItem?
+    let time: String?
+
+    enum CodingKeys: String, CodingKey {
+        case exists
+        case setting
+        case time
+    }
+
+    /// 创建排队设置响应。
+    init(exists: Bool = false, setting: ScenicQueueSettingItem? = nil, time: String? = nil) {
+        self.exists = exists
+        self.setting = setting
+        self.time = time
+    }
+
+    /// 宽松解码排队设置响应。
+    init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        exists = try container.decodeLossyBool(forKey: .exists) ?? false
+        setting = try container.decodeIfPresent(ScenicQueueSettingItem.self, forKey: .setting)
+        time = try container.decodeLossyString(forKey: .time)
+    }
+}
+
+/// 排队设置实体。
+struct ScenicQueueSettingItem: Decodable, Equatable {
+    let id: Int64?
+    let scenicId: Int?
+    let scenicSpotId: Int?
+    let scenicSpotName: String
+    let photoEstimateMin: Int
+    let photoEstimateSec: Int
+    let firstNoticeThresholdPos: Int
+    let firstNoticeSmsEnabled: Int
+    let firstNoticeCallEnabled: Int
+    let secondNoticeThresholdPos: Int
+    let secondNoticeSmsEnabled: Int
+    let secondNoticeCallEnabled: Int
+    let countdownBroadcastIntervalSec: Int
+    let countdownReadableThresholdSec: Int
+    let queueDistanceMeter: Int
+    let queueTakeLimit: Int
+    let missCallRequeueOffset: Int
+    let showStartShootButton: Int?
+    let autoCallNextCount: Int?
+    let businessStartTime: String
+    let businessEndTime: String
+    let status: Int
+    let remark: String
+    let voiceBroadcasts: [ScenicQueueVoiceBroadcastItem]
+    let createdAt: String
+    let updatedAt: String
+
+    enum CodingKeys: String, CodingKey {
+        case id
+        case scenicId = "scenic_id"
+        case scenicSpotId = "scenic_spot_id"
+        case scenicSpotName = "scenic_spot_name"
+        case photoEstimateMin = "photo_estimate_min"
+        case photoEstimateSec = "photo_estimate_sec"
+        case firstNoticeThresholdPos = "first_notice_threshold_pos"
+        case firstNoticeSmsEnabled = "first_notice_sms_enabled"
+        case firstNoticeCallEnabled = "first_notice_call_enabled"
+        case secondNoticeThresholdPos = "second_notice_threshold_pos"
+        case secondNoticeSmsEnabled = "second_notice_sms_enabled"
+        case secondNoticeCallEnabled = "second_notice_call_enabled"
+        case countdownBroadcastIntervalSec = "countdown_broadcast_interval_sec"
+        case countdownReadableThresholdSec = "countdown_readable_threshold_sec"
+        case queueDistanceMeter = "queue_distance_meter"
+        case queueTakeLimit = "queue_take_limit"
+        case missCallRequeueOffset = "miss_call_requeue_offset"
+        case showStartShootButton = "show_start_shoot_button"
+        case autoCallNextCount = "auto_call_next_count"
+        case businessStartTime = "business_start_time"
+        case businessEndTime = "business_end_time"
+        case status
+        case remark
+        case voiceBroadcasts = "voice_broadcasts"
+        case createdAt = "created_at"
+        case updatedAt = "updated_at"
+    }
+
+    /// 宽松解码排队设置实体。
+    init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        id = (try container.decodeLossyInt(forKey: .id)).map(Int64.init)
+        scenicId = try container.decodeLossyInt(forKey: .scenicId)
+        scenicSpotId = try container.decodeLossyInt(forKey: .scenicSpotId)
+        scenicSpotName = try container.decodeLossyString(forKey: .scenicSpotName)
+        photoEstimateMin = try container.decodeLossyInt(forKey: .photoEstimateMin) ?? 0
+        photoEstimateSec = try container.decodeLossyInt(forKey: .photoEstimateSec) ?? 0
+        firstNoticeThresholdPos = try container.decodeLossyInt(forKey: .firstNoticeThresholdPos) ?? 0
+        firstNoticeSmsEnabled = try container.decodeLossyInt(forKey: .firstNoticeSmsEnabled) ?? 0
+        firstNoticeCallEnabled = try container.decodeLossyInt(forKey: .firstNoticeCallEnabled) ?? 0
+        secondNoticeThresholdPos = try container.decodeLossyInt(forKey: .secondNoticeThresholdPos) ?? 0
+        secondNoticeSmsEnabled = try container.decodeLossyInt(forKey: .secondNoticeSmsEnabled) ?? 0
+        secondNoticeCallEnabled = try container.decodeLossyInt(forKey: .secondNoticeCallEnabled) ?? 0
+        countdownBroadcastIntervalSec = try container.decodeLossyInt(forKey: .countdownBroadcastIntervalSec) ?? 50
+        countdownReadableThresholdSec = try container.decodeLossyInt(forKey: .countdownReadableThresholdSec) ?? 15
+        queueDistanceMeter = try container.decodeLossyInt(forKey: .queueDistanceMeter) ?? 0
+        queueTakeLimit = try container.decodeLossyInt(forKey: .queueTakeLimit) ?? 0
+        missCallRequeueOffset = try container.decodeLossyInt(forKey: .missCallRequeueOffset) ?? 1
+        showStartShootButton = try container.decodeLossyInt(forKey: .showStartShootButton)
+        autoCallNextCount = try container.decodeLossyInt(forKey: .autoCallNextCount)
+        businessStartTime = try container.decodeLossyString(forKey: .businessStartTime)
+        businessEndTime = try container.decodeLossyString(forKey: .businessEndTime)
+        status = try container.decodeLossyInt(forKey: .status) ?? 1
+        remark = try container.decodeLossyString(forKey: .remark)
+        voiceBroadcasts = (try? container.decodeIfPresent([ScenicQueueVoiceBroadcastItem].self, forKey: .voiceBroadcasts)) ?? []
+        createdAt = try container.decodeLossyString(forKey: .createdAt)
+        updatedAt = try container.decodeLossyString(forKey: .updatedAt)
+    }
+}
+
+/// 排队语音播报预设。
+struct ScenicQueueVoiceBroadcastItem: Codable, Identifiable, Equatable {
+    var id: String { "\(sortOrder)-\(content)" }
+    let content: String
+    let sortOrder: Int
+
+    enum CodingKeys: String, CodingKey {
+        case content
+        case sortOrder = "sort_order"
+    }
+
+    /// 创建语音播报预设。
+    init(content: String, sortOrder: Int) {
+        self.content = content
+        self.sortOrder = sortOrder
+    }
+
+    /// 宽松解码语音播报预设。
+    init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        content = try container.decodeLossyString(forKey: .content).trimmingCharacters(in: .whitespacesAndNewlines)
+        sortOrder = try container.decodeLossyInt(forKey: .sortOrder) ?? 0
+    }
+}
+
+/// 保存排队设置请求体。
+struct ScenicQueueSaveSettingRequest: Encodable, Equatable {
+    let scenicId: Int
+    let scenicSpotId: Int
+    let photoEstimateMin: Int
+    let photoEstimateSec: Int
+    let firstNoticeThresholdPos: Int
+    let firstNoticeSmsEnabled: Int
+    let firstNoticeCallEnabled: Int
+    let secondNoticeThresholdPos: Int
+    let secondNoticeSmsEnabled: Int
+    let secondNoticeCallEnabled: Int
+    let countdownBroadcastIntervalSec: Int
+    let countdownReadableThresholdSec: Int
+    let queueDistanceMeter: Int?
+    let queueTakeLimit: Int?
+    let missCallRequeueOffset: Int?
+    let showStartShootButton: Int?
+    let autoCallNextCount: Int?
+    let businessStartTime: String
+    let businessEndTime: String
+    let voiceBroadcasts: [ScenicQueueVoiceBroadcastItem]
+    let status: Int
+    let remark: String?
+
+    enum CodingKeys: String, CodingKey {
+        case scenicId = "scenic_id"
+        case scenicSpotId = "scenic_spot_id"
+        case photoEstimateMin = "photo_estimate_min"
+        case photoEstimateSec = "photo_estimate_sec"
+        case firstNoticeThresholdPos = "first_notice_threshold_pos"
+        case firstNoticeSmsEnabled = "first_notice_sms_enabled"
+        case firstNoticeCallEnabled = "first_notice_call_enabled"
+        case secondNoticeThresholdPos = "second_notice_threshold_pos"
+        case secondNoticeSmsEnabled = "second_notice_sms_enabled"
+        case secondNoticeCallEnabled = "second_notice_call_enabled"
+        case countdownBroadcastIntervalSec = "countdown_broadcast_interval_sec"
+        case countdownReadableThresholdSec = "countdown_readable_threshold_sec"
+        case queueDistanceMeter = "queue_distance_meter"
+        case queueTakeLimit = "queue_take_limit"
+        case missCallRequeueOffset = "miss_call_requeue_offset"
+        case showStartShootButton = "show_start_shoot_button"
+        case autoCallNextCount = "auto_call_next_count"
+        case businessStartTime = "business_start_time"
+        case businessEndTime = "business_end_time"
+        case voiceBroadcasts = "voice_broadcasts"
+        case status
+        case remark
+    }
+}
+
+/// 排队设置变更日志响应。
+struct ScenicQueueSettingChangeLogData: Decodable, Equatable {
+    let total: Int
+    let page: Int
+    let pageSize: Int
+    let list: [ScenicQueueSettingChangeLogItem]
+
+    enum CodingKeys: String, CodingKey {
+        case total
+        case page
+        case pageSize = "page_size"
+        case list
+    }
+
+    /// 创建变更日志响应。
+    init(total: Int = 0, page: Int = 1, pageSize: Int = 20, list: [ScenicQueueSettingChangeLogItem] = []) {
+        self.total = total
+        self.page = page
+        self.pageSize = pageSize
+        self.list = list
+    }
+
+    /// 宽松解码变更日志响应。
+    init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        total = try container.decodeLossyInt(forKey: .total) ?? 0
+        page = try container.decodeLossyInt(forKey: .page) ?? 1
+        pageSize = try container.decodeLossyInt(forKey: .pageSize) ?? 20
+        list = (try? container.decodeIfPresent([ScenicQueueSettingChangeLogItem].self, forKey: .list)) ?? []
+    }
+}
+
+/// 排队设置变更日志项。
+struct ScenicQueueSettingChangeLogItem: Decodable, Equatable, Identifiable {
+    let id: Int64
+    let scenicSpotName: String
+    let operatorName: String
+    let operatorPhoneTail: String
+    let summary: String
+    let displayText: String
+    let createdAt: String
+
+    enum CodingKeys: String, CodingKey {
+        case id
+        case scenicSpotName = "scenic_spot_name"
+        case operatorName = "operator_name"
+        case operatorPhoneTail = "operator_phone_tail"
+        case summary
+        case displayText = "display_text"
+        case createdAt = "created_at"
+    }
+
+    /// 宽松解码变更日志项。
+    init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        id = Int64(try container.decodeLossyInt(forKey: .id) ?? 0)
+        scenicSpotName = try container.decodeLossyString(forKey: .scenicSpotName)
+        operatorName = try container.decodeLossyString(forKey: .operatorName)
+        operatorPhoneTail = try container.decodeLossyString(forKey: .operatorPhoneTail)
+        summary = try container.decodeLossyString(forKey: .summary)
+        displayText = try container.decodeLossyString(forKey: .displayText)
+        createdAt = try container.decodeLossyString(forKey: .createdAt)
+    }
+}
+
+/// 排队取号二维码响应。
+struct ScenicQueueShootQueueQRCodeData: Decodable, Equatable {
+    let qrcodeUrl: String
+
+    enum CodingKeys: String, CodingKey {
+        case qrcodeUrl = "qrcode_url"
+    }
+
+    /// 创建二维码响应。
+    init(qrcodeUrl: String = "") {
+        self.qrcodeUrl = qrcodeUrl
+    }
+
+    /// 宽松解码二维码响应。
+    init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        qrcodeUrl = try container.decodeLossyString(forKey: .qrcodeUrl)
+    }
+}
+
+/// 本地排队设置快照，用于服务器无配置或离线时保留关键配置。
+struct ScenicQueueSettingsSnapshot: Codable, Equatable {
+    var shootMinute: Int = 0
+    var shootSecond: Int = 30
+    var firstAheadCount: Int = 0
+    var firstSms: Bool = false
+    var firstPhone: Bool = false
+    var secondAheadCount: Int = 0
+    var secondSms: Bool = false
+    var secondPhone: Bool = false
+    var broadcastIntervalSec: Int = 50
+    var countdownThresholdSec: Int = 15
+    var queueDistanceMeter: Int = 0
+    var queueTakeLimit: Int = 0
+    var missCallRequeueOffset: Int = 1
+    var showStartShootingButton: Bool = true
+    var autoCallAheadCount: Int = 0
+    var quickCallButtonEnabled: Bool = false
+    var prepareCallButtonEnabled: Bool = false
+    var businessOpen: Bool = true
+    var businessStartTime: String = "10:00"
+    var businessEndTime: String = "20:00"
+
+    enum CodingKeys: String, CodingKey {
+        case shootMinute = "shoot_minute"
+        case shootSecond = "shoot_second"
+        case firstAheadCount = "first_ahead_count"
+        case firstSms = "first_sms"
+        case firstPhone = "first_phone"
+        case secondAheadCount = "second_ahead_count"
+        case secondSms = "second_sms"
+        case secondPhone = "second_phone"
+        case broadcastIntervalSec = "broadcast_interval_sec"
+        case countdownThresholdSec = "countdown_threshold_sec"
+        case queueDistanceMeter = "queue_distance_meter"
+        case queueTakeLimit = "queue_take_limit"
+        case missCallRequeueOffset = "miss_call_requeue_offset"
+        case showStartShootingButton = "show_start_shooting_button"
+        case autoCallAheadCount = "auto_call_ahead_count"
+        case quickCallButtonEnabled = "quick_call_button_enabled"
+        case prepareCallButtonEnabled = "prepare_call_button_enabled"
+        case businessOpen = "business_open"
+        case businessStartTime = "business_start_time"
+        case businessEndTime = "business_end_time"
+    }
+}
+
+private extension KeyedDecodingContainer {
+    func decodeLossyString(forKey key: Key) throws -> String {
+        if let value = try? decodeIfPresent(String.self, forKey: key) { return value }
+        if let value = try? decodeIfPresent(Int.self, forKey: key) { return String(value) }
+        if let value = try? decodeIfPresent(Double.self, forKey: key) { return String(value) }
+        if let value = try? decodeIfPresent(Bool.self, forKey: key) { return value ? "1" : "0" }
+        return ""
+    }
+
+    func decodeLossyInt(forKey key: Key) throws -> Int? {
+        if let value = try? decodeIfPresent(Int.self, forKey: key) { return value }
+        if let value = try? decodeIfPresent(Double.self, forKey: key) { return Int(value) }
+        if let value = try? decodeIfPresent(String.self, forKey: key),
+           case let text = value.trimmingCharacters(in: .whitespacesAndNewlines),
+           !text.isEmpty {
+            return Int(text) ?? Int(Double(text) ?? 0)
+        }
+        if let value = try? decodeIfPresent(Bool.self, forKey: key) { return value ? 1 : 0 }
+        return nil
+    }
+
+    func decodeLossyBool(forKey key: Key) throws -> Bool? {
+        if let value = try? decodeIfPresent(Bool.self, forKey: key) { return value }
+        if let value = try? decodeIfPresent(Int.self, forKey: key) { return value != 0 }
+        if let value = try? decodeIfPresent(String.self, forKey: key),
+           case let text = value.trimmingCharacters(in: .whitespacesAndNewlines).lowercased(),
+           !text.isEmpty {
+            if ["1", "true", "yes"].contains(text) { return true }
+            if ["0", "false", "no"].contains(text) { return false }
+        }
+        return nil
+    }
+}

suixinkan/Features/QueueManagement/Models/ScenicQueueSettingsStore.swift

@@ -0,0 +1,172 @@
+//
+//  ScenicQueueSettingsStore.swift
+//  suixinkan
+//
+//  Created by Codex on 2026/6/25.
+//
+
+import Foundation
+
+/// 排队管理本地设置 key。
+enum ScenicQueueLocalSettings {
+    static let selectedSpotIdKey = "scenic_queue_selected_spot_id"
+    static let selectedSpotNameKey = "scenic_queue_selected_spot_name"
+    static let customTtsTextKey = "scenic_queue_custom_tts_text"
+    static let settingsSnapshotKey = "scenic_queue_settings_snapshot"
+    static let photoEstimateSecondsKey = "scenic_queue_photo_estimate_seconds"
+    static let broadcastIntervalSecondsKey = "scenic_queue_broadcast_interval_seconds"
+    static let countdownThresholdSecondsKey = "scenic_queue_countdown_threshold_seconds"
+    static let showStartShootingButtonKey = "scenic_queue_show_start_shooting_button"
+    static let autoCallAheadCountKey = "scenic_queue_auto_call_ahead_count"
+    static let quickCallButtonEnabledKey = "scenic_queue_quick_call_button_enabled"
+    static let prepareCallButtonEnabledKey = "scenic_queue_prepare_call_button_enabled"
+    static let presetVoicesKey = "scenic_queue_preset_voices"
+    static let ttsEnabledKey = "scenic_queue_tts_enabled"
+    static let backgroundPollEnabledKey = "scenic_queue_background_poll_enabled"
+}
+
+/// 排队管理本地设置存储，按用户、景区、打卡点隔离并兼容旧 key。
+enum ScenicQueueSettingsStore {
+    /// 生成景区作用域 key。
+    static func scopedKey(base: String, userId: String?, scenicId: Int?) -> String {
+        guard let scenicId else { return base }
+        let user = normalizedUserId(userId)
+        return "\(base)_user_\(user)_scenic_\(scenicId)"
+    }
+
+    /// 生成打卡点作用域 key。
+    static func scopedSpotKey(base: String, userId: String?, scenicId: Int?, spotId: Int?) -> String {
+        guard let scenicId, let spotId else { return scopedKey(base: base, userId: userId, scenicId: scenicId) }
+        let user = normalizedUserId(userId)
+        return "\(base)_user_\(user)_scenic_\(scenicId)_spot_\(spotId)"
+    }
+
+    /// 读取已选打卡点 ID。
+    static func selectedSpotId(userId: String?, scenicId: Int?) -> Int? {
+        guard let scenicId else { return legacyPositiveInt(forKey: ScenicQueueLocalSettings.selectedSpotIdKey) }
+        let key = scopedKey(base: ScenicQueueLocalSettings.selectedSpotIdKey, userId: userId, scenicId: scenicId)
+        if let value = positiveInt(forKey: key) { return value }
+        if let legacy = legacyPositiveInt(forKey: ScenicQueueLocalSettings.selectedSpotIdKey) {
+            UserDefaults.standard.set(legacy, forKey: key)
+            return legacy
+        }
+        return nil
+    }
+
+    /// 读取已选打卡点名称。
+    static func selectedSpotName(userId: String?, scenicId: Int?) -> String {
+        guard let scenicId else {
+            return UserDefaults.standard.string(forKey: ScenicQueueLocalSettings.selectedSpotNameKey) ?? ""
+        }
+        let key = scopedKey(base: ScenicQueueLocalSettings.selectedSpotNameKey, userId: userId, scenicId: scenicId)
+        if let value = UserDefaults.standard.string(forKey: key), !value.isEmpty { return value }
+        let legacy = UserDefaults.standard.string(forKey: ScenicQueueLocalSettings.selectedSpotNameKey) ?? ""
+        if !legacy.isEmpty {
+            UserDefaults.standard.set(legacy, forKey: key)
+        }
+        return legacy
+    }
+
+    /// 保存已选打卡点。
+    static func saveSelectedSpot(id: Int, name: String, userId: String?, scenicId: Int) {
+        let defaults = UserDefaults.standard
+        defaults.set(id, forKey: ScenicQueueLocalSettings.selectedSpotIdKey)
+        defaults.set(name, forKey: ScenicQueueLocalSettings.selectedSpotNameKey)
+        defaults.set(id, forKey: scopedKey(base: ScenicQueueLocalSettings.selectedSpotIdKey, userId: userId, scenicId: scenicId))
+        defaults.set(name, forKey: scopedKey(base: ScenicQueueLocalSettings.selectedSpotNameKey, userId: userId, scenicId: scenicId))
+    }
+
+    /// 读取自定义语音文本。
+    static func customTtsText(userId: String?, scenicId: Int?, spotId: Int?) -> String {
+        guard let scenicId, let spotId else {
+            return UserDefaults.standard.string(forKey: ScenicQueueLocalSettings.customTtsTextKey) ?? ""
+        }
+        let key = scopedSpotKey(base: ScenicQueueLocalSettings.customTtsTextKey, userId: userId, scenicId: scenicId, spotId: spotId)
+        if let value = UserDefaults.standard.string(forKey: key) { return value }
+        let legacy = UserDefaults.standard.string(forKey: ScenicQueueLocalSettings.customTtsTextKey) ?? ""
+        if !legacy.isEmpty {
+            UserDefaults.standard.set(legacy, forKey: key)
+        }
+        return legacy
+    }
+
+    /// 保存自定义语音文本。
+    static func saveCustomTtsText(_ text: String, userId: String?, scenicId: Int?, spotId: Int?) {
+        let trimmed = text.trimmingCharacters(in: .whitespacesAndNewlines)
+        UserDefaults.standard.set(trimmed, forKey: ScenicQueueLocalSettings.customTtsTextKey)
+        if let scenicId, let spotId {
+            UserDefaults.standard.set(
+                trimmed,
+                forKey: scopedSpotKey(base: ScenicQueueLocalSettings.customTtsTextKey, userId: userId, scenicId: scenicId, spotId: spotId)
+            )
+        }
+    }
+
+    /// 读取设置快照。
+    static func settingsSnapshot(userId: String?, scenicId: Int, spotId: Int) -> ScenicQueueSettingsSnapshot? {
+        let keys = [
+            scopedSpotKey(base: ScenicQueueLocalSettings.settingsSnapshotKey, userId: userId, scenicId: scenicId, spotId: spotId),
+            "scenic_\(scenicId)_spot_\(spotId)_\(ScenicQueueLocalSettings.settingsSnapshotKey)",
+            "scenic_\(scenicId)_\(ScenicQueueLocalSettings.settingsSnapshotKey)"
+        ]
+        for key in keys {
+            guard let data = UserDefaults.standard.data(forKey: key),
+                  let snapshot = try? JSONDecoder().decode(ScenicQueueSettingsSnapshot.self, from: data)
+            else { continue }
+            return snapshot
+        }
+        return nil
+    }
+
+    /// 保存设置快照。
+    static func saveSettingsSnapshot(_ snapshot: ScenicQueueSettingsSnapshot, userId: String?, scenicId: Int, spotId: Int) {
+        guard let data = try? JSONEncoder().encode(snapshot) else { return }
+        UserDefaults.standard.set(
+            data,
+            forKey: scopedSpotKey(base: ScenicQueueLocalSettings.settingsSnapshotKey, userId: userId, scenicId: scenicId, spotId: spotId)
+        )
+        UserDefaults.standard.set(data, forKey: "scenic_\(scenicId)_spot_\(spotId)_\(ScenicQueueLocalSettings.settingsSnapshotKey)")
+    }
+
+    /// 读取语音预设。
+    static func presetVoices(userId: String?, scenicId: Int?, spotId: Int?) -> [String] {
+        guard let scenicId, let spotId else { return [] }
+        let keys = [
+            scopedSpotKey(base: ScenicQueueLocalSettings.presetVoicesKey, userId: userId, scenicId: scenicId, spotId: spotId),
+            "scenic_\(scenicId)_spot_\(spotId)_\(ScenicQueueLocalSettings.presetVoicesKey)"
+        ]
+        for key in keys {
+            guard let data = UserDefaults.standard.data(forKey: key),
+                  let voices = try? JSONDecoder().decode([String].self, from: data)
+            else { continue }
+            return voices
+        }
+        return []
+    }
+
+    /// 保存语音预设。
+    static func savePresetVoices(_ voices: [String], userId: String?, scenicId: Int, spotId: Int) {
+        let normalized = Array(voices.map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }.filter { !$0.isEmpty }.prefix(5))
+        guard let data = try? JSONEncoder().encode(normalized) else { return }
+        UserDefaults.standard.set(
+            data,
+            forKey: scopedSpotKey(base: ScenicQueueLocalSettings.presetVoicesKey, userId: userId, scenicId: scenicId, spotId: spotId)
+        )
+        UserDefaults.standard.set(data, forKey: "scenic_\(scenicId)_spot_\(spotId)_\(ScenicQueueLocalSettings.presetVoicesKey)")
+    }
+
+    private static func normalizedUserId(_ userId: String?) -> String {
+        let text = userId?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        return text.isEmpty ? "anonymous" : text
+    }
+
+    private static func positiveInt(forKey key: String) -> Int? {
+        guard UserDefaults.standard.object(forKey: key) != nil else { return nil }
+        let value = UserDefaults.standard.integer(forKey: key)
+        return value > 0 ? value : nil
+    }
+
+    private static func legacyPositiveInt(forKey key: String) -> Int? {
+        positiveInt(forKey: key)
+    }
+}

suixinkan/Features/QueueManagement/QueueManagement.md

@@ -0,0 +1,20 @@
+# 排队管理模块
+
+## 模块职责
+
+`Features/QueueManagement` 承接首页 `/scenic-queue` 和 `queue_management` 权限入口，负责景区打卡点队列列表、叫号、过号、完成、重新排队、用户标记、队列设置、排队二维码和配置日志。
+
+## 代码结构
+
+- `ScenicQueueAPI`：封装 `/api/app/scenic-queue/...` 和 `/api/app/socket-token`。
+- `QueueManagementViewModel`：管理已保存打卡点门禁、当前排队/过号列表分页、统计、队列动作和页面前台实时监听。
+- `ScenicQueueSettingsViewModel`：管理打卡点设置加载、本地快照兜底、表单校验、保存、二维码和配置日志。
+- `ScenicQueueSettingsStore`：按 `userId + scenicId + spotId` 作用域保存本地排队设置，并兼容旧 key。
+- `Core/Queue`：承接排队 WebSocket、远端叫号去重、语音播报和页面离开后的短轮询运行时。
+
+## 业务边界
+
+- 列表页从当前账号景区和打卡点上下文读取数据；没有已保存打卡点时只显示设置引导，不自动选择第一个打卡点。
+- 叫号成功后只做本地已叫号标记；过号、完成、重新排队和用户标记成功后刷新当前打卡点列表。
+- 页面可见时由 `QueueManagementViewModel` 维护 WebSocket 监听；页面离开后由 `ScenicQueueRuntime` 按本地开关进行短轮询。
+- 设置保存前校验拍摄时长、通知阈值、播报间隔、读秒阈值、排队范围、排队次数、过号顺延和自定义播报长度。

suixinkan/Features/QueueManagement/ViewModels/QueueManagementViewModels.swift

@@ -0,0 +1,884 @@
+//
+//  QueueManagementViewModels.swift
+//  suixinkan
+//
+//  Created by Codex on 2026/6/25.
+//
+
+import Foundation
+import Observation
+import Photos
+import SwiftUI
+import UIKit
+
+@MainActor
+@Observable
+/// 排队管理列表 ViewModel，负责打卡点门禁、列表分页、动作和实时事件。
+final class QueueManagementViewModel {
+    var loading = false
+    var loadingMore = false
+    var items: [QueueItem] = []
+    var scenicSpots: [ScenicSpotItem] = []
+    var selectedSpotId: Int?
+    var selectedListType: QueueListType = .queueing
+    var queueCount = 0
+    var avgWaitMin = 0.0
+    var totalCount = 0
+    var hasMore = false
+    var page = 1
+    var lastSyncTimeText = "--"
+    var queueGatePassed = false
+    var selectedSpotName = "--"
+    var showStartShootingButton = true
+    var autoCallAheadCount = 0
+    var quickCallButtonEnabled = false
+    var prepareCallButtonEnabled = false
+    var remoteCallAnnouncement: ScenicQueueRemoteCallAnnouncement?
+    var errorMessage: String?
+
+    @ObservationIgnored private let pageSize = 10
+    @ObservationIgnored private let socketClient = ScenicQueueSocketClient()
+    @ObservationIgnored private var realtimeSpotId: Int?
+    @ObservationIgnored private var realtimeScenicId: Int?
+    @ObservationIgnored private var currentUserId: String?
+    @ObservationIgnored private var currentScenicId: Int?
+    @ObservationIgnored private var pendingRemoteCalledRecordIds = Set<Int64>()
+    @ObservationIgnored private var handledRemoteCallEventIds = Set<String>()
+
+    /// 待处理排队数量。
+    var pendingCount: Int {
+        items.filter { $0.status < 7 && !$0.statusText.contains("完成") }.count
+    }
+
+    /// 平均等待时间文案。
+    var avgWaitMinText: String {
+        avgWaitMin.rounded() == avgWaitMin ? "\(Int(avgWaitMin))" : String(format: "%.1f", avgWaitMin)
+    }
+
+    /// 当前打卡点名称。
+    var currentSpotName: String {
+        scenicSpots.first(where: { $0.id == selectedSpotId })?.name
+            ?? selectedSpotName.nonEmptyOrDefault(queueGatePassed ? "--" : "未设置打卡点")
+    }
+
+    /// 重新加载排队数据。没有已保存打卡点时只展示设置引导，不自动选第一个。
+    func reload(api: any ScenicQueueServing, scenicId: Int?, userId: String?, spots: [ScenicSpotItem]) async {
+        guard let scenicId else {
+            reset()
+            return
+        }
+
+        loading = true
+        errorMessage = nil
+        defer { loading = false }
+
+        currentUserId = userId
+        currentScenicId = scenicId
+        scenicSpots = spots
+
+        let savedSpotId = ScenicQueueSettingsStore.selectedSpotId(userId: userId, scenicId: scenicId)
+        if let savedSpotId, spots.isEmpty || spots.contains(where: { $0.id == savedSpotId }) {
+            selectedSpotId = savedSpotId
+            selectedSpotName = ScenicQueueSettingsStore.selectedSpotName(userId: userId, scenicId: scenicId)
+                .nonEmptyOrDefault(spots.first(where: { $0.id == savedSpotId })?.name ?? "--")
+            queueGatePassed = true
+            await syncQueueSettingFromServerIfMatchesLocal(api: api, userId: userId, scenicId: scenicId, spotId: savedSpotId)
+            refreshShootingCallConfig(userId: userId, scenicId: scenicId, spotId: savedSpotId)
+        } else {
+            selectedSpotId = nil
+            selectedSpotName = "--"
+            queueGatePassed = false
+            clearQueueData()
+            return
+        }
+
+        do {
+            try await loadPage(api: api, scenicId: scenicId, userId: userId, page: 1)
+        } catch {
+            clearQueueData()
+            errorMessage = error.localizedDescription
+        }
+    }
+
+    /// 切换列表类型并加载第一页。
+    func selectListType(_ type: QueueListType, api: any ScenicQueueServing, scenicId: Int?, userId: String?) async {
+        guard selectedListType != type else { return }
+        selectedListType = type
+        await reloadCurrentSpot(api: api, scenicId: scenicId, userId: userId)
+    }
+
+    /// 重新加载当前打卡点列表。
+    func reloadCurrentSpot(api: any ScenicQueueServing, scenicId: Int?, userId: String?) async {
+        guard let scenicId else { return }
+        loading = true
+        errorMessage = nil
+        defer { loading = false }
+        do {
+            try await loadPage(api: api, scenicId: scenicId, userId: userId, page: 1)
+        } catch {
+            clearQueueData()
+            errorMessage = error.localizedDescription
+        }
+    }
+
+    /// 加载下一页。
+    func loadMore(api: any ScenicQueueServing, scenicId: Int?, userId: String?) async {
+        guard let scenicId, hasMore, !loadingMore else { return }
+        loadingMore = true
+        defer { loadingMore = false }
+        do {
+            try await loadPage(api: api, scenicId: scenicId, userId: userId, page: page + 1)
+        } catch {
+            errorMessage = error.localizedDescription
+        }
+    }
+
+    /// 叫号，成功后仅本地标记为已叫号。
+    func callQueue(api: any ScenicQueueServing, id: Int64) async throws {
+        let data = try await api.scenicQueueCall(id: id)
+        markQueueCalled(id: id, statusText: data.statusText)
+    }
+
+    /// 标记过号并刷新列表。
+    func passQueue(api: any ScenicQueueServing, scenicId: Int?, userId: String?, id: Int64) async throws {
+        _ = try await api.scenicQueuePass(id: id)
+        items.removeAll { $0.id == id }
+        queueCount = max(queueCount - 1, 0)
+        await reloadCurrentSpot(api: api, scenicId: scenicId, userId: userId)
+    }
+
+    /// 标记完成并刷新列表。
+    func finishQueue(api: any ScenicQueueServing, scenicId: Int?, userId: String?, id: Int64) async throws -> ScenicQueueFinishData {
+        let data = try await api.scenicQueueFinish(id: id)
+        items.removeAll { $0.id == id }
+        queueCount = max(queueCount - 1, 0)
+        await reloadCurrentSpot(api: api, scenicId: scenicId, userId: userId)
+        return data
+    }
+
+    /// 重新排队并切回当前排队列表。
+    func requeue(api: any ScenicQueueServing, scenicId: Int?, userId: String?, id: Int64, operatorId: Int) async throws {
+        try await api.scenicQueueRequeueInsertBefore(recordId: id, operatorId: operatorId)
+        selectedListType = .queueing
+        await reloadCurrentSpot(api: api, scenicId: scenicId, userId: userId)
+    }
+
+    /// 标记用户身份/限制排队。
+    func userMark(api: any ScenicQueueServing, scenicId: Int?, userId: String?, request: ScenicQueueUserMarkRequest) async throws {
+        try await api.scenicQueueUserMark(request)
+        await reloadCurrentSpot(api: api, scenicId: scenicId, userId: userId)
+    }
+
+    /// 启动页面前台实时监听。
+    func startRealtime(api: any ScenicQueueServing, scenicId: Int?, userId: String?) async {
+        guard queueGatePassed, let scenicId, let scenicSpotId = selectedSpotId else {
+            stopRealtime()
+            return
+        }
+        guard realtimeScenicId != scenicId || realtimeSpotId != scenicSpotId else { return }
+        stopRealtime()
+        do {
+            let token = try await api.socketToken().socketToken.trimmingCharacters(in: .whitespacesAndNewlines)
+            guard !token.isEmpty else { return }
+            realtimeScenicId = scenicId
+            realtimeSpotId = scenicSpotId
+            socketClient.connect(socketToken: token, scenicSpotId: scenicSpotId) { [weak self] message in
+                Task { @MainActor in
+                    await self?.handleSocketMessage(message, api: api, scenicId: scenicId, userId: userId)
+                }
+            }
+        } catch {
+            errorMessage = error.localizedDescription
+        }
+    }
+
+    /// 停止页面实时监听。
+    func stopRealtime() {
+        socketClient.disconnect()
+        realtimeScenicId = nil
+        realtimeSpotId = nil
+        pendingRemoteCalledRecordIds.removeAll()
+        handledRemoteCallEventIds.removeAll()
+    }
+
+    /// 当前拍摄预计时长秒数。
+    var shootingDurationSeconds: Int {
+        guard let scenicId = currentScenicId, let selectedSpotId,
+              let snapshot = ScenicQueueSettingsStore.settingsSnapshot(userId: currentUserId, scenicId: scenicId, spotId: selectedSpotId)
+        else {
+            return max(UserDefaults.standard.integer(forKey: ScenicQueueLocalSettings.photoEstimateSecondsKey), 0)
+        }
+        return max(snapshot.shootMinute * 60 + snapshot.shootSecond, 0)
+    }
+
+    private func handleSocketMessage(_ message: ScenicQueueSocketMessage, api: any ScenicQueueServing, scenicId: Int, userId: String?) async {
+        guard message.isScenicQueueEvent,
+              let params = message.data?.params,
+              let changedSpotId = params.scenicSpotId,
+              let selectedSpotId,
+              changedSpotId == Int64(selectedSpotId)
+        else { return }
+
+        switch message.data?.action {
+        case ScenicQueueSocketMessage.queueUpdatedAction:
+            await reloadCurrentSpot(api: api, scenicId: scenicId, userId: userId)
+        case ScenicQueueSocketMessage.ticketCalledAction:
+            await handleRemoteTicketCalled(params: params, api: api, scenicId: scenicId, userId: userId)
+        default:
+            return
+        }
+    }
+
+    private func handleRemoteTicketCalled(params: ScenicQueueSocketParams, api: any ScenicQueueServing, scenicId: Int, userId: String?) async {
+        guard let recordId = params.recordId, recordId > 0 else { return }
+        if let operatorUid = params.operatorUid,
+           let myUid = Int64(userId ?? ""),
+           operatorUid == myUid {
+            return
+        }
+        let eventId = params.eventId?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        if !eventId.isEmpty, !handledRemoteCallEventIds.insert(eventId).inserted {
+            return
+        }
+        pendingRemoteCalledRecordIds.insert(recordId)
+        guard let selectedSpotId else { return }
+        _ = try? await api.scenicQueueStats(scenicId: scenicId, scenicSpotId: selectedSpotId)
+        let tickets = (try? await loadQueueingTickets(api: api, scenicId: scenicId, scenicSpotId: selectedSpotId)) ?? []
+        if selectedListType == .queueing {
+            items = tickets
+            totalCount = max(totalCount, tickets.count)
+            hasMore = tickets.count < totalCount
+        }
+        consumePendingRemoteCalledTickets(from: tickets)
+        await reloadCurrentSpot(api: api, scenicId: scenicId, userId: userId)
+    }
+
+    private func loadQueueingTickets(api: any ScenicQueueServing, scenicId: Int, scenicSpotId: Int) async throws -> [QueueItem] {
+        let home = try await api.scenicQueueHome(
+            scenicId: scenicId,
+            scenicSpotId: scenicSpotId,
+            type: QueueListType.queueing.rawValue,
+            page: 1,
+            pageSize: pageSize
+        )
+        return home.list?.list ?? []
+    }
+
+    private func consumePendingRemoteCalledTickets(from tickets: [QueueItem]) {
+        guard let ticket = tickets.first(where: {
+            pendingRemoteCalledRecordIds.contains($0.id) && ($0.isCalled == 1 || $0.status == 1 || $0.statusText.contains("已叫号"))
+        }) else {
+            return
+        }
+        pendingRemoteCalledRecordIds.remove(ticket.id)
+        remoteCallAnnouncement = ScenicQueueRemoteCallAnnouncement(id: ticket.id, queueCode: ticket.queueCode)
+    }
+
+    private func loadPage(api: any ScenicQueueServing, scenicId: Int, userId: String?, page targetPage: Int) async throws {
+        guard let scenicSpotId = selectedSpotId else { return }
+        let home = try await api.scenicQueueHome(
+            scenicId: scenicId,
+            scenicSpotId: scenicSpotId,
+            type: selectedListType.rawValue,
+            page: targetPage,
+            pageSize: pageSize
+        )
+        let stats = (try? await api.scenicQueueStats(scenicId: scenicId, scenicSpotId: scenicSpotId)) ?? ScenicQueueStatsData()
+        let block = home.list
+        let nextList = block?.list ?? []
+
+        if targetPage <= 1 {
+            items = nextList
+        } else {
+            items.append(contentsOf: nextList)
+        }
+        page = targetPage
+        totalCount = block?.total ?? items.count
+        hasMore = page * pageSize < totalCount
+        queueCount = stats.queueCount
+        avgWaitMin = stats.avgWaitMin
+        let syncText = stats.time.isEmpty ? (home.time ?? "") : stats.time
+        lastSyncTimeText = syncText.isEmpty ? "--" : syncText
+        refreshShootingCallConfig(userId: userId, scenicId: scenicId, spotId: scenicSpotId)
+    }
+
+    private func markQueueCalled(id: Int64, statusText: String) {
+        let trimmedStatus = statusText.trimmingCharacters(in: .whitespacesAndNewlines)
+        items = items.map { item in
+            guard item.id == id else { return item }
+            return ScenicQueueTicket(
+                id: item.id,
+                queueCode: item.queueCode,
+                mobile: item.mobile,
+                status: max(item.status, 1),
+                statusText: trimmedStatus.nonEmptyOrDefault(item.statusText.contains("已叫号") ? item.statusText : "已叫号"),
+                waitMin: item.waitMin,
+                aheadCount: item.aheadCount,
+                isCalled: 1,
+                createdAt: item.createdAt,
+                calledAt: item.calledAt,
+                expiredAt: item.expiredAt,
+                finishedAt: item.finishedAt,
+                queueBanLabel: item.queueBanLabel,
+                identityTag: item.identityTag,
+                queueTime: item.queueTime,
+                queueCountToday: item.queueCountToday,
+                uid: item.uid,
+                markAsPhotog: item.markAsPhotog,
+                markAsFreelancePhotog: item.markAsFreelancePhotog,
+                isMissRequeue: item.isMissRequeue,
+                missRequeueText: item.missRequeueText
+            )
+        }
+    }
+
+    private func reset() {
+        stopRealtime()
+        loading = false
+        loadingMore = false
+        scenicSpots = []
+        selectedSpotId = nil
+        selectedSpotName = "--"
+        queueGatePassed = false
+        selectedListType = .queueing
+        currentScenicId = nil
+        clearQueueData()
+    }
+
+    private func clearQueueData() {
+        loadingMore = false
+        items = []
+        queueCount = 0
+        avgWaitMin = 0
+        totalCount = 0
+        hasMore = false
+        page = 1
+        lastSyncTimeText = "--"
+    }
+
+    private func refreshShootingCallConfig(userId: String?, scenicId: Int, spotId: Int) {
+        let snapshot = ScenicQueueSettingsStore.settingsSnapshot(userId: userId, scenicId: scenicId, spotId: spotId) ?? ScenicQueueSettingsSnapshot()
+        showStartShootingButton = snapshot.showStartShootingButton
+        autoCallAheadCount = min(max(snapshot.autoCallAheadCount, 0), 5)
+        quickCallButtonEnabled = snapshot.quickCallButtonEnabled
+        prepareCallButtonEnabled = snapshot.prepareCallButtonEnabled
+    }
+
+    private func syncQueueSettingFromServerIfMatchesLocal(api: any ScenicQueueServing, userId: String?, scenicId: Int, spotId: Int) async {
+        guard let data = try? await api.scenicQueueSetting(scenicId: scenicId, scenicSpotId: spotId),
+              data.exists,
+              let setting = data.setting
+        else { return }
+        if let settingScenicId = setting.scenicId, settingScenicId != scenicId { return }
+        if let settingSpotId = setting.scenicSpotId, settingSpotId != spotId { return }
+
+        let local = ScenicQueueSettingsStore.settingsSnapshot(userId: userId, scenicId: scenicId, spotId: spotId) ?? ScenicQueueSettingsSnapshot()
+        let snapshot = ScenicQueueSettingsSnapshot(
+            shootMinute: min(max(setting.photoEstimateMin, 0), 30),
+            shootSecond: min(max(setting.photoEstimateSec, 0), 59),
+            firstAheadCount: min(max(setting.firstNoticeThresholdPos, 0), 50),
+            firstSms: setting.firstNoticeSmsEnabled == 1,
+            firstPhone: setting.firstNoticeCallEnabled == 1,
+            secondAheadCount: min(max(setting.secondNoticeThresholdPos, 0), 50),
+            secondSms: setting.secondNoticeSmsEnabled == 1,
+            secondPhone: setting.secondNoticeCallEnabled == 1,
+            broadcastIntervalSec: ScenicQueueSettingsViewModel.coercedBroadcastInterval(setting.countdownBroadcastIntervalSec),
+            countdownThresholdSec: ScenicQueueSettingsViewModel.coercedCountdownThreshold(setting.countdownReadableThresholdSec),
+            queueDistanceMeter: min(max(setting.queueDistanceMeter, 0), 9_999_990),
+            queueTakeLimit: min(max(setting.queueTakeLimit, 0), 999_999),
+            missCallRequeueOffset: min(max(setting.missCallRequeueOffset, 1), 9_999),
+            showStartShootingButton: (setting.showStartShootButton ?? (local.showStartShootingButton ? 1 : 0)) == 1,
+            autoCallAheadCount: min(max(setting.autoCallNextCount ?? local.autoCallAheadCount, 0), 5),
+            quickCallButtonEnabled: local.quickCallButtonEnabled,
+            prepareCallButtonEnabled: local.prepareCallButtonEnabled,
+            businessOpen: setting.status == 1,
+            businessStartTime: setting.businessStartTime,
+            businessEndTime: setting.businessEndTime
+        )
+        ScenicQueueSettingsStore.saveSettingsSnapshot(snapshot, userId: userId, scenicId: scenicId, spotId: spotId)
+        ScenicQueueSettingsStore.saveSelectedSpot(
+            id: spotId,
+            name: setting.scenicSpotName.nonEmptyOrDefault(selectedSpotName),
+            userId: userId,
+            scenicId: scenicId
+        )
+        if !setting.remark.isEmpty, setting.remark != "A0001" {
+            ScenicQueueSettingsStore.saveCustomTtsText(setting.remark, userId: userId, scenicId: scenicId, spotId: spotId)
+        }
+        let voices = setting.voiceBroadcasts
+            .sorted { $0.sortOrder < $1.sortOrder }
+            .map { $0.content.trimmingCharacters(in: .whitespacesAndNewlines) }
+            .filter { !$0.isEmpty }
+        if !voices.isEmpty {
+            ScenicQueueSettingsStore.savePresetVoices(Array(voices.prefix(5)), userId: userId, scenicId: scenicId, spotId: spotId)
+        }
+        selectedSpotName = setting.scenicSpotName.nonEmptyOrDefault(selectedSpotName)
+    }
+}
+
+@MainActor
+@Observable
+/// 排队设置 ViewModel，负责设置读取、校验、保存、二维码和日志。
+final class ScenicQueueSettingsViewModel {
+    var loading = false
+    var message: String?
+    var scenicSpots: [ScenicSpotItem] = []
+    var selectedSpotId: Int?
+    var photoEstimateMin = "0"
+    var photoEstimateSec = "30"
+    var firstAhead = "0"
+    var firstSms = false
+    var firstPhone = false
+    var secondAhead = "0"
+    var secondSms = false
+    var secondPhone = false
+    var broadcastIntervalSec = "50"
+    var countdownThresholdSec = "15"
+    var maxQueueRangeKm = "0.00"
+    var localQueueLimit = "0"
+    var localPassDelay = "1"
+    var showStartShootingButton = true
+    var autoCallAheadCount = "0"
+    var queueOpen = true
+    var businessStartTime = ScenicQueueSettingsViewModel.businessTime(hour: 10, minute: 0)
+    var businessEndTime = ScenicQueueSettingsViewModel.businessTime(hour: 20, minute: 0)
+    var customTtsText = ""
+    var presetVoices: [String] = []
+    var quickCallButtonEnabled = false
+    var prepareCallButtonEnabled = false
+    var logs: [ScenicQueueSettingChangeLogItem] = []
+    var qrcodeURL = ""
+
+    @ObservationIgnored private let speaker = ScenicQueueSpeechService()
+    @ObservationIgnored private var currentUserId: String?
+    @ObservationIgnored private var currentScenicId: Int?
+
+    /// 加载设置。设置页允许自动选中第一个打卡点。
+    func load(api: any ScenicQueueServing, scenicId: Int?, userId: String?, spots: [ScenicSpotItem]) async {
+        guard let scenicId else {
+            resetSettingsState()
+            message = "请先选择景区"
+            return
+        }
+        currentUserId = userId
+        currentScenicId = scenicId
+        scenicSpots = spots
+        message = nil
+        loading = true
+        defer { loading = false }
+        logs = []
+
+        let savedSpotId = ScenicQueueSettingsStore.selectedSpotId(userId: userId, scenicId: scenicId)
+        selectedSpotId = savedSpotId.flatMap { id in spots.first(where: { $0.id == id })?.id ?? id } ?? selectedSpotId ?? spots.first?.id
+        guard selectedSpotId != nil else { return }
+        await loadSelectedSpotSetting(api: api, scenicId: scenicId, userId: userId)
+    }
+
+    /// 加载当前选中打卡点设置。
+    func loadSelectedSpotSetting(api: any ScenicQueueServing, scenicId: Int?, userId: String?) async {
+        guard let scenicId, let selectedSpotId else { return }
+        currentUserId = userId
+        currentScenicId = scenicId
+        presetVoices = ScenicQueueSettingsStore.presetVoices(userId: userId, scenicId: scenicId, spotId: selectedSpotId)
+        let savedCustomText = ScenicQueueSettingsStore.customTtsText(userId: userId, scenicId: scenicId, spotId: selectedSpotId)
+        if !savedCustomText.isEmpty, savedCustomText != "A0001" {
+            customTtsText = savedCustomText
+        }
+        if let snapshot = ScenicQueueSettingsStore.settingsSnapshot(userId: userId, scenicId: scenicId, spotId: selectedSpotId) {
+            apply(snapshot)
+        }
+        do {
+            let setting = try await api.scenicQueueSetting(scenicId: scenicId, scenicSpotId: selectedSpotId)
+            if setting.exists, let item = setting.setting {
+                apply(item)
+                ScenicQueueSettingsStore.saveSettingsSnapshot(makeSnapshot(), userId: userId, scenicId: scenicId, spotId: selectedSpotId)
+            }
+        } catch {
+            message = error.localizedDescription
+        }
+    }
+
+    /// 加载设置变更日志。
+    func loadSettingChangeLogs(api: any ScenicQueueServing, scenicId: Int?) async {
+        guard let scenicId else {
+            message = "请先选择景区"
+            return
+        }
+        do {
+            let data = try await api.scenicQueueSettingChangeLog(scenicId: scenicId, scenicSpotId: selectedSpotId, page: 1, pageSize: 20)
+            logs = data.list
+        } catch {
+            message = error.localizedDescription
+        }
+    }
+
+    /// 获取排队二维码 URL。
+    func fetchQRCode(api: any ScenicQueueServing, scenicId: Int?) async throws -> String {
+        guard let scenicId else { throw APIError.networkFailed("请先选择景区") }
+        guard let selectedSpotId else { throw APIError.networkFailed("请选择打卡点") }
+        let data = try await api.scenicQueueShootQueueQRCode(scenicId: scenicId, scenicSpotId: selectedSpotId)
+        let url = data.qrcodeUrl.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !url.isEmpty else { throw APIError.networkFailed("服务端未返回二维码图片地址") }
+        qrcodeURL = url
+        return url
+    }
+
+    /// 保存二维码图片到系统相册。
+    func saveQRCodeToPhotoLibrary(qrcodeURL: String) async throws {
+        let trimmed = qrcodeURL.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else {
+            throw APIError.networkFailed("服务端未返回二维码图片地址")
+        }
+        let status = await PHPhotoLibrary.requestAuthorization(for: .addOnly)
+        guard status == .authorized || status == .limited else {
+            throw APIError.networkFailed("请在系统设置中允许保存图片到相册")
+        }
+        let image = try await loadQRCodeImage(from: trimmed)
+        try await PHPhotoLibrary.shared().performChanges {
+            PHAssetChangeRequest.creationRequestForAsset(from: image)
+        }
+    }
+
+    /// 保存排队设置。
+    func save(api: any ScenicQueueServing, scenicId: Int?, userId: String?) async throws {
+        guard let scenicId else { throw APIError.networkFailed("请先选择景区") }
+        guard let selectedSpotId else { throw APIError.networkFailed("请选择打卡点") }
+        currentUserId = userId
+        currentScenicId = scenicId
+        let min = try AppFormValidator.rangedInteger(photoEstimateMin, name: "拍摄时长分钟", range: 0...30)
+        let sec = try AppFormValidator.rangedInteger(photoEstimateSec, name: "拍摄时长秒", range: 0...59)
+        guard min > 0 || sec > 0 else { throw APIError.networkFailed("拍摄时长须大于 0") }
+        let first = try AppFormValidator.rangedInteger(firstAhead, name: "第一次通知阈值", range: 0...50)
+        let second = try AppFormValidator.rangedInteger(secondAhead, name: "第二次通知阈值", range: 0...50)
+        try AppFormValidator.validateQueueNoticeThresholds(first: first, second: second)
+        let interval = try AppFormValidator.rangedInteger(broadcastIntervalSec, name: "播报间隔时间", range: 40...60)
+        let countdown = try AppFormValidator.rangedInteger(countdownThresholdSec, name: "进入读秒倒计时阈值", range: 10...30)
+        let autoCallAhead = try AppFormValidator.rangedInteger(autoCallAheadCount, name: "自动叫号后续几位", range: 0...5)
+        maxQueueRangeKm = try normalizedMaxQueueRangeForDisplay()
+        let queueDistanceMeter = try queueDistanceMeterForSubmit()
+        let queueTakeLimit = try AppFormValidator.rangedInteger(localQueueLimit, name: "排队次数限制", range: 0...999_999)
+        let missCallRequeueOffset = try AppFormValidator.rangedInteger(localPassDelay, name: "过号顺延", range: 1...9_999)
+        guard customTtsText.trimmingCharacters(in: .whitespacesAndNewlines).count <= 255 else {
+            throw APIError.networkFailed("自定义播报文本最多 255 个字")
+        }
+
+        loading = true
+        defer { loading = false }
+        try await api.scenicQueueSaveSetting(ScenicQueueSaveSettingRequest(
+            scenicId: scenicId,
+            scenicSpotId: selectedSpotId,
+            photoEstimateMin: min,
+            photoEstimateSec: sec,
+            firstNoticeThresholdPos: first,
+            firstNoticeSmsEnabled: firstSms ? 1 : 0,
+            firstNoticeCallEnabled: firstPhone ? 1 : 0,
+            secondNoticeThresholdPos: second,
+            secondNoticeSmsEnabled: secondSms ? 1 : 0,
+            secondNoticeCallEnabled: secondPhone ? 1 : 0,
+            countdownBroadcastIntervalSec: interval,
+            countdownReadableThresholdSec: countdown,
+            queueDistanceMeter: queueDistanceMeter,
+            queueTakeLimit: queueTakeLimit,
+            missCallRequeueOffset: missCallRequeueOffset,
+            showStartShootButton: showStartShootingButton ? 1 : 0,
+            autoCallNextCount: autoCallAhead,
+            businessStartTime: Self.businessTimePayload(businessStartTime),
+            businessEndTime: Self.businessTimePayload(businessEndTime),
+            voiceBroadcasts: voiceBroadcastsForSavePayload(),
+            status: queueOpen ? 1 : 0,
+            remark: customTtsText.trimmingCharacters(in: .whitespacesAndNewlines).nilIfEmpty
+        ))
+        let spotName = scenicSpots.first(where: { $0.id == selectedSpotId })?.name ?? ""
+        ScenicQueueSettingsStore.saveSelectedSpot(id: selectedSpotId, name: spotName, userId: userId, scenicId: scenicId)
+        saveTimingSnapshot(min: min, sec: sec, interval: interval, countdown: countdown)
+        saveShootingCallSettings(autoCallAhead: autoCallAhead)
+        saveCustomTextLocally()
+        ScenicQueueSettingsStore.savePresetVoices(presetVoices, userId: userId, scenicId: scenicId, spotId: selectedSpotId)
+        ScenicQueueSettingsStore.saveSettingsSnapshot(makeSnapshot(
+            min: min,
+            sec: sec,
+            first: first,
+            second: second,
+            interval: interval,
+            countdown: countdown,
+            queueDistanceMeter: queueDistanceMeter,
+            queueTakeLimit: queueTakeLimit,
+            missCallRequeueOffset: missCallRequeueOffset,
+            autoCallAhead: autoCallAhead
+        ), userId: userId, scenicId: scenicId, spotId: selectedSpotId)
+    }
+
+    /// 保存自定义文本为本地预设。
+    func saveCustomTextAsPreset() {
+        let text = customTtsText.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard text.count <= 255 else {
+            message = "自定义播报文本最多 255 个字"
+            return
+        }
+        saveCustomTextLocally()
+        if !text.isEmpty, !presetVoices.contains(text), presetVoices.count < 5 {
+            presetVoices.append(text)
+        }
+        if let scenicId = currentScenicId, let selectedSpotId {
+            ScenicQueueSettingsStore.savePresetVoices(presetVoices, userId: currentUserId, scenicId: scenicId, spotId: selectedSpotId)
+        }
+    }
+
+    /// 更新最大排队范围输入。
+    func updateMaxQueueRange(_ value: String) {
+        maxQueueRangeKm = AppFormValidator.sanitizedMoneyInput(value, maxDecimalPlaces: 2)
+    }
+
+    /// 播放测试音。
+    func playTestSound() {
+        speaker.speak("蓝牙音响测试音，请确认外放音量是否合适。")
+    }
+
+    /// 播放自定义播报文本。
+    func playCustomText() {
+        let text = customTtsText.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !text.isEmpty else {
+            message = "请输入要播报的文字"
+            return
+        }
+        speaker.speak(text)
+    }
+
+    /// 删除预设语音。
+    func deletePresetVoice(at index: Int) {
+        guard presetVoices.indices.contains(index) else { return }
+        presetVoices.remove(at: index)
+    }
+
+    private func resetSettingsState() {
+        loading = false
+        scenicSpots = []
+        selectedSpotId = nil
+        photoEstimateMin = "0"
+        photoEstimateSec = "30"
+        firstAhead = "0"
+        firstSms = false
+        firstPhone = false
+        secondAhead = "0"
+        secondSms = false
+        secondPhone = false
+        broadcastIntervalSec = "50"
+        countdownThresholdSec = "15"
+        maxQueueRangeKm = "0.00"
+        localQueueLimit = "0"
+        localPassDelay = "1"
+        showStartShootingButton = true
+        autoCallAheadCount = "0"
+        queueOpen = true
+        businessStartTime = Self.businessTime(hour: 10, minute: 0)
+        businessEndTime = Self.businessTime(hour: 20, minute: 0)
+        customTtsText = ""
+        logs = []
+        presetVoices = []
+        quickCallButtonEnabled = false
+        prepareCallButtonEnabled = false
+        qrcodeURL = ""
+    }
+
+    private func apply(_ setting: ScenicQueueSettingItem?) {
+        guard let setting else { return }
+        if let spotId = setting.scenicSpotId { selectedSpotId = spotId }
+        photoEstimateMin = "\(setting.photoEstimateMin)"
+        photoEstimateSec = "\(setting.photoEstimateSec)"
+        firstAhead = "\(setting.firstNoticeThresholdPos)"
+        firstSms = setting.firstNoticeSmsEnabled == 1
+        firstPhone = setting.firstNoticeCallEnabled == 1
+        secondAhead = "\(setting.secondNoticeThresholdPos)"
+        secondSms = setting.secondNoticeSmsEnabled == 1
+        secondPhone = setting.secondNoticeCallEnabled == 1
+        broadcastIntervalSec = "\(Self.coercedBroadcastInterval(setting.countdownBroadcastIntervalSec))"
+        countdownThresholdSec = "\(Self.coercedCountdownThreshold(setting.countdownReadableThresholdSec))"
+        maxQueueRangeKm = Self.queueDistanceDisplay(meters: setting.queueDistanceMeter)
+        localQueueLimit = "\(min(max(setting.queueTakeLimit, 0), 999_999))"
+        localPassDelay = "\(min(max(setting.missCallRequeueOffset, 1), 9_999))"
+        if let showStartShootButton = setting.showStartShootButton { showStartShootingButton = showStartShootButton == 1 }
+        if let autoCallNextCount = setting.autoCallNextCount { autoCallAheadCount = "\(min(max(autoCallNextCount, 0), 5))" }
+        queueOpen = setting.status == 1
+        businessStartTime = Self.parseBusinessTime(setting.businessStartTime, fallback: Self.businessTime(hour: 10, minute: 0))
+        businessEndTime = Self.parseBusinessTime(setting.businessEndTime, fallback: Self.businessTime(hour: 20, minute: 0))
+        if !setting.remark.isEmpty, setting.remark != "A0001" { customTtsText = setting.remark }
+        let voices = setting.voiceBroadcasts
+            .sorted { $0.sortOrder < $1.sortOrder }
+            .map { $0.content.trimmingCharacters(in: .whitespacesAndNewlines) }
+            .filter { !$0.isEmpty }
+        if !voices.isEmpty { presetVoices = Array(voices.prefix(5)) }
+    }
+
+    private func apply(_ snapshot: ScenicQueueSettingsSnapshot) {
+        photoEstimateMin = "\(min(max(snapshot.shootMinute, 0), 30))"
+        photoEstimateSec = "\(min(max(snapshot.shootSecond, 0), 59))"
+        firstAhead = "\(min(max(snapshot.firstAheadCount, 0), 50))"
+        firstSms = snapshot.firstSms
+        firstPhone = snapshot.firstPhone
+        secondAhead = "\(min(max(snapshot.secondAheadCount, 0), 50))"
+        secondSms = snapshot.secondSms
+        secondPhone = snapshot.secondPhone
+        broadcastIntervalSec = "\(Self.coercedBroadcastInterval(snapshot.broadcastIntervalSec))"
+        countdownThresholdSec = "\(Self.coercedCountdownThreshold(snapshot.countdownThresholdSec))"
+        maxQueueRangeKm = Self.queueDistanceDisplay(meters: snapshot.queueDistanceMeter)
+        localQueueLimit = "\(min(max(snapshot.queueTakeLimit, 0), 999_999))"
+        localPassDelay = "\(min(max(snapshot.missCallRequeueOffset, 1), 9_999))"
+        showStartShootingButton = snapshot.showStartShootingButton
+        autoCallAheadCount = "\(min(max(snapshot.autoCallAheadCount, 0), 5))"
+        quickCallButtonEnabled = snapshot.quickCallButtonEnabled
+        prepareCallButtonEnabled = snapshot.prepareCallButtonEnabled
+        queueOpen = snapshot.businessOpen
+        businessStartTime = Self.parseBusinessTime(snapshot.businessStartTime, fallback: Self.businessTime(hour: 10, minute: 0))
+        businessEndTime = Self.parseBusinessTime(snapshot.businessEndTime, fallback: Self.businessTime(hour: 20, minute: 0))
+    }
+
+    private func normalizedMaxQueueRangeForDisplay() throws -> String {
+        let normalized = AppFormValidator.normalizedMoneyForSubmit(maxQueueRangeKm)
+        guard !normalized.isEmpty,
+              normalized.range(of: #"^\d+(\.\d{1,2})?$"#, options: .regularExpression) != nil,
+              let value = Decimal(string: normalized, locale: Locale(identifier: "en_US_POSIX"))
+        else {
+            throw APIError.networkFailed("允许排队的最大范围格式不正确")
+        }
+        let max = Decimal(999_999) / Decimal(100)
+        guard value >= 0, value <= max else {
+            throw APIError.networkFailed("允许排队的最大范围须在 0～9999.99")
+        }
+        return String(format: "%.2f", NSDecimalNumber(decimal: value).doubleValue)
+    }
+
+    private func queueDistanceMeterForSubmit() throws -> Int {
+        _ = try normalizedMaxQueueRangeForDisplay()
+        let value = Decimal(string: maxQueueRangeKm, locale: Locale(identifier: "en_US_POSIX")) ?? 0
+        return NSDecimalNumber(decimal: value * Decimal(1000)).intValue
+    }
+
+    private func loadQRCodeImage(from text: String) async throws -> UIImage {
+        if let url = URL(string: text), ["http", "https"].contains(url.scheme?.lowercased()) {
+            let (data, _) = try await URLSession.shared.data(from: url)
+            if let image = UIImage(data: data) { return image }
+        }
+        if let generated = Self.generateQRCode(from: text) { return generated }
+        throw APIError.networkFailed("二维码图片生成失败")
+    }
+
+    private static func generateQRCode(from string: String) -> UIImage? {
+        let filter = CIFilter.qrCodeGenerator()
+        filter.message = Data(string.utf8)
+        guard let outputImage = filter.outputImage else { return nil }
+        let transformed = outputImage.transformed(by: CGAffineTransform(scaleX: 8, y: 8))
+        let context = CIContext()
+        guard let cgImage = context.createCGImage(transformed, from: transformed.extent) else { return nil }
+        return UIImage(cgImage: cgImage)
+    }
+
+    private func saveTimingSnapshot(min: Int, sec: Int, interval: Int, countdown: Int) {
+        UserDefaults.standard.set(max(min * 60 + sec, 0), forKey: ScenicQueueLocalSettings.photoEstimateSecondsKey)
+        UserDefaults.standard.set(interval, forKey: ScenicQueueLocalSettings.broadcastIntervalSecondsKey)
+        UserDefaults.standard.set(countdown, forKey: ScenicQueueLocalSettings.countdownThresholdSecondsKey)
+    }
+
+    private func saveShootingCallSettings(autoCallAhead: Int) {
+        UserDefaults.standard.set(showStartShootingButton, forKey: ScenicQueueLocalSettings.showStartShootingButtonKey)
+        UserDefaults.standard.set(autoCallAhead, forKey: ScenicQueueLocalSettings.autoCallAheadCountKey)
+        UserDefaults.standard.set(quickCallButtonEnabled, forKey: ScenicQueueLocalSettings.quickCallButtonEnabledKey)
+        UserDefaults.standard.set(prepareCallButtonEnabled, forKey: ScenicQueueLocalSettings.prepareCallButtonEnabledKey)
+    }
+
+    private func saveCustomTextLocally() {
+        ScenicQueueSettingsStore.saveCustomTtsText(customTtsText, userId: currentUserId, scenicId: currentScenicId, spotId: selectedSpotId)
+    }
+
+    private func voiceBroadcastsForSavePayload() -> [ScenicQueueVoiceBroadcastItem] {
+        Array(presetVoices
+            .map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }
+            .filter { !$0.isEmpty }
+            .prefix(5)
+            .enumerated()
+            .map { index, content in ScenicQueueVoiceBroadcastItem(content: content, sortOrder: index + 1) })
+    }
+
+    private func makeSnapshot(
+        min: Int? = nil,
+        sec: Int? = nil,
+        first: Int? = nil,
+        second: Int? = nil,
+        interval: Int? = nil,
+        countdown: Int? = nil,
+        queueDistanceMeter: Int? = nil,
+        queueTakeLimit: Int? = nil,
+        missCallRequeueOffset: Int? = nil,
+        autoCallAhead: Int? = nil
+    ) -> ScenicQueueSettingsSnapshot {
+        ScenicQueueSettingsSnapshot(
+            shootMinute: min ?? (Int(photoEstimateMin) ?? 0),
+            shootSecond: sec ?? (Int(photoEstimateSec) ?? 30),
+            firstAheadCount: first ?? (Int(firstAhead) ?? 0),
+            firstSms: firstSms,
+            firstPhone: firstPhone,
+            secondAheadCount: second ?? (Int(secondAhead) ?? 0),
+            secondSms: secondSms,
+            secondPhone: secondPhone,
+            broadcastIntervalSec: interval ?? (Int(broadcastIntervalSec) ?? 50),
+            countdownThresholdSec: countdown ?? (Int(countdownThresholdSec) ?? 15),
+            queueDistanceMeter: queueDistanceMeter ?? ((Decimal(string: maxQueueRangeKm) ?? 0) as NSDecimalNumber).intValue * 1000,
+            queueTakeLimit: queueTakeLimit ?? (Int(localQueueLimit) ?? 0),
+            missCallRequeueOffset: missCallRequeueOffset ?? (Int(localPassDelay) ?? 1),
+            showStartShootingButton: showStartShootingButton,
+            autoCallAheadCount: autoCallAhead ?? (Int(autoCallAheadCount) ?? 0),
+            quickCallButtonEnabled: quickCallButtonEnabled,
+            prepareCallButtonEnabled: prepareCallButtonEnabled,
+            businessOpen: queueOpen,
+            businessStartTime: Self.businessTimePayload(businessStartTime),
+            businessEndTime: Self.businessTimePayload(businessEndTime)
+        )
+    }
+
+    static func coercedBroadcastInterval(_ raw: Int) -> Int {
+        (40...60).contains(raw) ? raw : 50
+    }
+
+    static func coercedCountdownThreshold(_ raw: Int) -> Int {
+        (10...30).contains(raw) ? raw : 15
+    }
+
+    static func businessTime(hour: Int, minute: Int) -> Date {
+        Calendar.current.date(from: DateComponents(hour: hour, minute: minute)) ?? Date()
+    }
+
+    static func parseBusinessTime(_ raw: String, fallback: Date) -> Date {
+        let text = raw.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !text.isEmpty else { return fallback }
+        for format in ["HH:mm", "HH:mm:ss"] {
+            let formatter = DateFormatter()
+            formatter.locale = Locale(identifier: "en_US_POSIX")
+            formatter.dateFormat = format
+            if let date = formatter.date(from: text) { return date }
+        }
+        return fallback
+    }
+
+    static func businessTimePayload(_ date: Date) -> String {
+        let formatter = DateFormatter()
+        formatter.locale = Locale(identifier: "en_US_POSIX")
+        formatter.dateFormat = "HH:mm"
+        return formatter.string(from: date)
+    }
+
+    private static func queueDistanceDisplay(meters: Int) -> String {
+        let clamped = min(max(meters, 0), 9_999_990)
+        return String(format: "%.2f", Double(clamped) / 1000)
+    }
+}
+
+private extension String {
+    var nilIfEmpty: String? {
+        let text = trimmingCharacters(in: .whitespacesAndNewlines)
+        return text.isEmpty ? nil : text
+    }
+
+    func nonEmptyOrDefault(_ fallback: String) -> String {
+        let text = trimmingCharacters(in: .whitespacesAndNewlines)
+        return text.isEmpty ? fallback : text
+    }
+}

suixinkan/Features/QueueManagement/Views/QueueManagementViews.swift

@@ -0,0 +1,464 @@
+//
+//  QueueManagementViews.swift
+//  suixinkan
+//
+//  Created by Codex on 2026/6/25.
+//
+
+import SwiftUI
+
+/// 排队管理首页，展示当前打卡点队列和操作入口。
+struct QueueManagementView: View {
+    @Environment(AccountContext.self) private var accountContext
+    @Environment(ScenicSpotContext.self) private var scenicSpotContext
+    @Environment(ScenicQueueAPI.self) private var queueAPI
+    @Environment(ScenicQueueRuntime.self) private var queueRuntime
+    @Environment(ToastCenter.self) private var toastCenter
+    @State private var viewModel = QueueManagementViewModel()
+    @State private var pendingAction: QueueActionConfirmation?
+    @State private var markTarget: QueueItem?
+    @State private var processingId: Int64?
+
+    private var currentScenicId: Int? { accountContext.currentScenic?.id }
+    private var currentUserId: String? { accountContext.profile?.userId }
+
+    var body: some View {
+        ScrollView {
+            VStack(spacing: AppMetrics.Spacing.medium) {
+                header
+                if currentScenicId == nil {
+                    ContentUnavailableView("请先选择景区", systemImage: "map", description: Text("排队管理需要当前景区上下文"))
+                        .frame(minHeight: 260)
+                } else if !viewModel.queueGatePassed {
+                    gateCard
+                } else {
+                    listSection
+                }
+            }
+            .padding(AppMetrics.Spacing.pageHorizontal)
+        }
+        .background(Color(hex: 0xF5F7FA).ignoresSafeArea())
+        .navigationTitle("排队管理")
+        .navigationBarTitleDisplayMode(.inline)
+        .toolbar {
+            ToolbarItem(placement: .topBarTrailing) {
+                NavigationLink {
+                    ScenicQueueSettingsView()
+                } label: {
+                    Image(systemName: "gearshape")
+                }
+                .accessibilityLabel("排队设置")
+            }
+        }
+        .alert(item: $pendingAction) { action in
+            Alert(
+                title: Text(action.title),
+                message: Text(action.message),
+                primaryButton: .default(Text("确认")) {
+                    Task { await perform(action) }
+                },
+                secondaryButton: .cancel()
+            )
+        }
+        .sheet(item: $markTarget) { item in
+            QueueUserMarkView(item: item) { markAsFreelance, banDays in
+                await userMark(item: item, markAsFreelance: markAsFreelance, banDays: banDays)
+            }
+        }
+        .task(id: reloadTaskID) {
+            await reload()
+            await viewModel.startRealtime(api: queueAPI, scenicId: currentScenicId, userId: currentUserId)
+        }
+        .onAppear {
+            queueRuntime.setSuspendedByQueueScreen(true)
+        }
+        .onDisappear {
+            viewModel.stopRealtime()
+            queueRuntime.setSuspendedByQueueScreen(false)
+        }
+        .refreshable {
+            await reload()
+        }
+        .onChange(of: viewModel.remoteCallAnnouncement) { _, announcement in
+            if let announcement {
+                toastCenter.show("远端已叫号 \(announcement.queueCode.isEmpty ? "当前游客" : announcement.queueCode)")
+            }
+        }
+        .onChange(of: viewModel.errorMessage) { _, message in
+            if let message { toastCenter.show(message) }
+        }
+    }
+
+    private var reloadTaskID: String {
+        "\(currentScenicId ?? 0)-\(scenicSpotContext.spots.map(\.id).description)"
+    }
+
+    private var header: some View {
+        VStack(spacing: AppMetrics.Spacing.medium) {
+            HStack(spacing: AppMetrics.Spacing.medium) {
+                metricCard(title: "在排人数", value: "\(viewModel.queueCount)", icon: "person.3.fill", color: AppDesign.primary)
+                metricCard(title: "平均等待", value: "\(viewModel.avgWaitMinText) 分", icon: "clock.fill", color: AppDesign.warning)
+            }
+
+            HStack {
+                VStack(alignment: .leading, spacing: 4) {
+                    Text(accountContext.currentScenic?.name ?? "未选择景区")
+                        .font(.system(size: AppMetrics.FontSize.body, weight: .semibold))
+                        .foregroundStyle(AppDesign.textPrimary)
+                    Text("打卡点：\(viewModel.currentSpotName)")
+                        .font(.system(size: AppMetrics.FontSize.subheadline))
+                        .foregroundStyle(AppDesign.textSecondary)
+                }
+                Spacer()
+                Text(viewModel.lastSyncTimeText)
+                    .font(.system(size: AppMetrics.FontSize.caption))
+                    .foregroundStyle(AppDesign.textSecondary)
+            }
+            .padding(AppMetrics.Spacing.medium)
+            .background(.white, in: RoundedRectangle(cornerRadius: AppMetrics.CornerRadius.card))
+        }
+    }
+
+    private var gateCard: some View {
+        VStack(spacing: AppMetrics.Spacing.medium) {
+            Image(systemName: "mappin.and.ellipse")
+                .font(.system(size: 42, weight: .semibold))
+                .foregroundStyle(AppDesign.primary)
+            Text("请先设置排队打卡点")
+                .font(.system(size: AppMetrics.FontSize.title3, weight: .semibold))
+                .foregroundStyle(AppDesign.textPrimary)
+            Text("排队列表需要固定打卡点后才能加载。")
+                .font(.system(size: AppMetrics.FontSize.subheadline))
+                .foregroundStyle(AppDesign.textSecondary)
+            NavigationLink {
+                ScenicQueueSettingsView()
+            } label: {
+                Label("前往设置", systemImage: "gearshape")
+                    .font(.system(size: AppMetrics.FontSize.body, weight: .semibold))
+                    .frame(maxWidth: .infinity)
+                    .frame(height: AppMetrics.ControlSize.primaryButtonHeight)
+            }
+            .buttonStyle(.borderedProminent)
+        }
+        .padding(AppMetrics.Spacing.large)
+        .frame(maxWidth: .infinity)
+        .background(.white, in: RoundedRectangle(cornerRadius: AppMetrics.CornerRadius.card))
+    }
+
+    private var listSection: some View {
+        VStack(spacing: AppMetrics.Spacing.medium) {
+            Picker("排队类型", selection: Binding(
+                get: { viewModel.selectedListType },
+                set: { type in
+                    Task { await viewModel.selectListType(type, api: queueAPI, scenicId: currentScenicId, userId: currentUserId) }
+                }
+            )) {
+                ForEach(QueueListType.allCases) { type in
+                    Text(type.title).tag(type)
+                }
+            }
+            .pickerStyle(.segmented)
+
+            if viewModel.loading && viewModel.items.isEmpty {
+                ProgressView("加载中...")
+                    .frame(maxWidth: .infinity, minHeight: 240)
+            } else if viewModel.items.isEmpty {
+                ContentUnavailableView(viewModel.selectedListType.emptyText, systemImage: "person.crop.circle.badge.questionmark")
+                    .frame(maxWidth: .infinity, minHeight: 240)
+                    .background(.white, in: RoundedRectangle(cornerRadius: AppMetrics.CornerRadius.card))
+            } else {
+                LazyVStack(spacing: AppMetrics.Spacing.medium) {
+                    ForEach(Array(viewModel.items.enumerated()), id: \.element.id) { index, item in
+                        QueueTicketCard(
+                            item: item,
+                            index: index + 1,
+                            listType: viewModel.selectedListType,
+                            processing: processingId == item.id,
+                            onCall: { pendingAction = QueueActionConfirmation(kind: item.isCalled == 1 ? .recall : .call, item: item) },
+                            onPass: { pendingAction = QueueActionConfirmation(kind: .pass, item: item) },
+                            onFinish: { pendingAction = QueueActionConfirmation(kind: .finish, item: item) },
+                            onRequeue: { pendingAction = QueueActionConfirmation(kind: .requeue, item: item) },
+                            onMark: { markTarget = item }
+                        )
+                        .onAppear {
+                            if item.id == viewModel.items.last?.id {
+                                Task { await viewModel.loadMore(api: queueAPI, scenicId: currentScenicId, userId: currentUserId) }
+                            }
+                        }
+                    }
+                    if viewModel.loadingMore {
+                        ProgressView()
+                            .frame(maxWidth: .infinity)
+                            .padding(.vertical, AppMetrics.Spacing.medium)
+                    }
+                }
+            }
+        }
+    }
+
+    private func metricCard(title: String, value: String, icon: String, color: Color) -> some View {
+        HStack(spacing: AppMetrics.Spacing.medium) {
+            Image(systemName: icon)
+                .font(.system(size: 22, weight: .bold))
+                .foregroundStyle(color)
+                .frame(width: 38, height: 38)
+                .background(color.opacity(0.12), in: RoundedRectangle(cornerRadius: 8))
+            VStack(alignment: .leading, spacing: 3) {
+                Text(title)
+                    .font(.system(size: AppMetrics.FontSize.caption))
+                    .foregroundStyle(AppDesign.textSecondary)
+                Text(value)
+                    .font(.system(size: AppMetrics.FontSize.title3, weight: .bold))
+                    .foregroundStyle(AppDesign.textPrimary)
+                    .lineLimit(1)
+                    .minimumScaleFactor(0.75)
+            }
+        }
+        .frame(maxWidth: .infinity, alignment: .leading)
+        .padding(AppMetrics.Spacing.medium)
+        .background(.white, in: RoundedRectangle(cornerRadius: AppMetrics.CornerRadius.card))
+    }
+
+    private func reload() async {
+        await viewModel.reload(
+            api: queueAPI,
+            scenicId: currentScenicId,
+            userId: currentUserId,
+            spots: scenicSpotContext.spots
+        )
+    }
+
+    private func perform(_ action: QueueActionConfirmation) async {
+        processingId = action.item.id
+        defer { processingId = nil }
+        do {
+            switch action.kind {
+            case .call, .recall:
+                try await viewModel.callQueue(api: queueAPI, id: action.item.id)
+            case .pass:
+                try await viewModel.passQueue(api: queueAPI, scenicId: currentScenicId, userId: currentUserId, id: action.item.id)
+            case .finish:
+                _ = try await viewModel.finishQueue(api: queueAPI, scenicId: currentScenicId, userId: currentUserId, id: action.item.id)
+            case .requeue:
+                try await viewModel.requeue(api: queueAPI, scenicId: currentScenicId, userId: currentUserId, id: action.item.id, operatorId: Int(currentUserId ?? "") ?? 0)
+            }
+        } catch {
+            toastCenter.show(error.localizedDescription)
+        }
+    }
+
+    private func userMark(item: QueueItem, markAsFreelance: Bool, banDays: Int) async -> Bool {
+        guard let scenicId = currentScenicId else { return false }
+        processingId = item.id
+        defer { processingId = nil }
+        do {
+            try await viewModel.userMark(
+                api: queueAPI,
+                scenicId: scenicId,
+                userId: currentUserId,
+                request: ScenicQueueUserMarkRequest(
+                    uid: item.uid,
+                    scenicId: Int64(scenicId),
+                    markAsFreelancePhotog: markAsFreelance ? 1 : 0,
+                    queueBanDays: markAsFreelance ? banDays : nil,
+                    operatorId: Int(currentUserId ?? "")
+                )
+            )
+            return true
+        } catch {
+            toastCenter.show(error.localizedDescription)
+            return false
+        }
+    }
+}
+
+private struct QueueTicketCard: View {
+    let item: QueueItem
+    let index: Int
+    let listType: QueueListType
+    let processing: Bool
+    let onCall: () -> Void
+    let onPass: () -> Void
+    let onFinish: () -> Void
+    let onRequeue: () -> Void
+    let onMark: () -> Void
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: AppMetrics.Spacing.medium) {
+            HStack(alignment: .top) {
+                VStack(alignment: .leading, spacing: 6) {
+                    HStack(spacing: 8) {
+                        Text(item.queueCode.isEmpty ? "\(index)" : item.queueCode)
+                            .font(.system(size: 26, weight: .bold))
+                            .foregroundStyle(AppDesign.textPrimary)
+                        if item.isCalled == 1 || item.statusText.contains("已叫号") {
+                            tag("已叫号", color: AppDesign.primary)
+                        }
+                        if item.shouldShowIdentityTag {
+                            tag(item.identityTag, color: AppDesign.warning)
+                        }
+                    }
+                    Text(item.phoneMasked)
+                        .font(.system(size: AppMetrics.FontSize.subheadline))
+                        .foregroundStyle(AppDesign.textSecondary)
+                }
+                Spacer()
+                VStack(alignment: .trailing, spacing: 5) {
+                    Text(item.statusText.isEmpty ? "--" : item.statusText)
+                        .font(.system(size: AppMetrics.FontSize.caption, weight: .semibold))
+                        .foregroundStyle(AppDesign.primary)
+                    Text(item.queueTimeDisplay)
+                        .font(.system(size: AppMetrics.FontSize.caption))
+                        .foregroundStyle(AppDesign.textSecondary)
+                }
+            }
+
+            HStack(spacing: AppMetrics.Spacing.small) {
+                info("等待", "\(item.waitMin)分")
+                info("前方", "\(item.aheadCount)位")
+                info("今日", "\(item.queueCountToday)次")
+            }
+
+            if !item.queueBanLabel.isEmpty || item.isMissRequeueRecord {
+                HStack(spacing: 8) {
+                    if !item.queueBanLabel.isEmpty {
+                        tag(item.queueBanLabel, color: AppDesign.warning)
+                    }
+                    if item.isMissRequeueRecord {
+                        tag(item.missRequeueText.isEmpty ? "重排" : item.missRequeueText, color: AppDesign.warning)
+                    }
+                }
+            }
+
+            HStack(spacing: AppMetrics.Spacing.small) {
+                if listType == .queueing {
+                    actionButton(item.isCalled == 1 ? "重叫" : "叫号", icon: "speaker.wave.2.fill", action: onCall)
+                    actionButton("过号", icon: "forward.end.fill", action: onPass)
+                    actionButton("完成", icon: "checkmark.circle.fill", action: onFinish)
+                } else {
+                    actionButton("重排", icon: "arrow.uturn.left", action: onRequeue)
+                }
+                actionButton("标记", icon: "person.badge.key.fill", action: onMark)
+            }
+        }
+        .padding(AppMetrics.Spacing.medium)
+        .background(.white, in: RoundedRectangle(cornerRadius: AppMetrics.CornerRadius.card))
+        .opacity(processing ? 0.6 : 1)
+    }
+
+    private func info(_ title: String, _ value: String) -> some View {
+        VStack(spacing: 4) {
+            Text(title)
+                .font(.system(size: AppMetrics.FontSize.caption))
+                .foregroundStyle(AppDesign.textSecondary)
+            Text(value)
+                .font(.system(size: AppMetrics.FontSize.subheadline, weight: .semibold))
+                .foregroundStyle(AppDesign.textPrimary)
+        }
+        .frame(maxWidth: .infinity)
+        .padding(.vertical, 8)
+        .background(Color(hex: 0xF8FAFC), in: RoundedRectangle(cornerRadius: 8))
+    }
+
+    private func tag(_ text: String, color: Color) -> some View {
+        Text(text)
+            .font(.system(size: AppMetrics.FontSize.caption, weight: .semibold))
+            .foregroundStyle(color)
+            .padding(.horizontal, 8)
+            .padding(.vertical, 4)
+            .background(color.opacity(0.12), in: Capsule())
+    }
+
+    private func actionButton(_ title: String, icon: String, action: @escaping () -> Void) -> some View {
+        Button(action: action) {
+            Label(title, systemImage: icon)
+                .font(.system(size: AppMetrics.FontSize.caption, weight: .semibold))
+                .frame(maxWidth: .infinity)
+                .frame(height: 36)
+        }
+        .buttonStyle(.bordered)
+    }
+}
+
+private struct QueueUserMarkView: View {
+    let item: QueueItem
+    let onConfirm: (Bool, Int) async -> Bool
+    @Environment(\.dismiss) private var dismiss
+    @State private var markAsFreelance = true
+    @State private var queueBanDays = 7
+    @State private var submitting = false
+
+    var body: some View {
+        NavigationStack {
+            Form {
+                Section("用户") {
+                    Text(item.queueCode.isEmpty ? "当前游客" : item.queueCode)
+                    Text(item.phoneMasked)
+                }
+                Section("标记") {
+                    Toggle("标记为打野摄影师", isOn: $markAsFreelance)
+                    Stepper("限制排队 \(queueBanDays) 天", value: $queueBanDays, in: 0...999)
+                }
+            }
+            .navigationTitle("用户标记")
+            .navigationBarTitleDisplayMode(.inline)
+            .toolbar {
+                ToolbarItem(placement: .cancellationAction) {
+                    Button("取消") { dismiss() }
+                }
+                ToolbarItem(placement: .confirmationAction) {
+                    Button(submitting ? "提交中" : "提交") {
+                        Task {
+                            submitting = true
+                            let ok = await onConfirm(markAsFreelance, queueBanDays)
+                            submitting = false
+                            if ok { dismiss() }
+                        }
+                    }
+                    .disabled(submitting)
+                }
+            }
+        }
+    }
+}
+
+private struct QueueActionConfirmation: Identifiable {
+    enum Kind {
+        case call
+        case recall
+        case pass
+        case finish
+        case requeue
+    }
+
+    let kind: Kind
+    let item: QueueItem
+
+    var id: String { "\(kind)-\(item.id)" }
+
+    var title: String {
+        switch kind {
+        case .call: return "确认叫号"
+        case .recall: return "确认重新叫号"
+        case .pass: return "确认过号"
+        case .finish: return "确认完成"
+        case .requeue: return "确认重新排队"
+        }
+    }
+
+    var message: String {
+        let queueCode = item.queueCode.isEmpty ? "该游客" : item.queueCode
+        switch kind {
+        case .call:
+            return "确定要叫号 \(queueCode) 吗？"
+        case .recall:
+            return "确定要重新叫号 \(queueCode) 吗？"
+        case .pass:
+            return "确定将 \(queueCode) 标记为过号吗？"
+        case .finish:
+            return "确定 \(queueCode) 已完成拍摄吗？"
+        case .requeue:
+            return "确定将 \(queueCode) 重新插入当前排队队列吗？"
+        }
+    }
+}

suixinkan/Features/QueueManagement/Views/ScenicQueueSettingsViews.swift

@@ -0,0 +1,343 @@
+//
+//  ScenicQueueSettingsViews.swift
+//  suixinkan
+//
+//  Created by Codex on 2026/6/25.
+//
+
+import SwiftUI
+
+/// 排队设置页面。
+struct ScenicQueueSettingsView: View {
+    @Environment(AccountContext.self) private var accountContext
+    @Environment(ScenicSpotContext.self) private var scenicSpotContext
+    @Environment(ScenicQueueAPI.self) private var queueAPI
+    @Environment(ScenicQueueRuntime.self) private var queueRuntime
+    @Environment(ToastCenter.self) private var toastCenter
+    @State private var viewModel = ScenicQueueSettingsViewModel()
+    @State private var selectedTab: ScenicQueueSettingsTab = .basic
+    @State private var qrcodeURL: String?
+    @State private var saving = false
+
+    private var currentScenicId: Int? { accountContext.currentScenic?.id }
+    private var currentUserId: String? { accountContext.profile?.userId }
+
+    var body: some View {
+        ScrollView {
+            VStack(spacing: AppMetrics.Spacing.medium) {
+                Picker("设置分组", selection: $selectedTab) {
+                    ForEach(ScenicQueueSettingsTab.allCases) { tab in
+                        Text(tab.title).tag(tab)
+                    }
+                }
+                .pickerStyle(.segmented)
+
+                switch selectedTab {
+                case .basic:
+                    basicSection
+                case .notice:
+                    noticeSection
+                case .voice:
+                    voiceSection
+                case .logs:
+                    logsSection
+                }
+            }
+            .padding(AppMetrics.Spacing.pageHorizontal)
+        }
+        .background(Color(hex: 0xF5F7FA).ignoresSafeArea())
+        .navigationTitle("排队设置")
+        .navigationBarTitleDisplayMode(.inline)
+        .toolbar {
+            ToolbarItemGroup(placement: .topBarTrailing) {
+                Button {
+                    Task { await fetchQRCode() }
+                } label: {
+                    Image(systemName: "qrcode")
+                }
+                .accessibilityLabel("取号二维码")
+
+                Button(saving ? "保存中" : "保存") {
+                    Task { await save() }
+                }
+                .disabled(saving || viewModel.loading)
+            }
+        }
+        .sheet(item: Binding(
+            get: { qrcodeURL.map(QueueQRCodeSheetItem.init(url:)) },
+            set: { qrcodeURL = $0?.url }
+        )) { item in
+            QueueQRCodeView(url: item.url) {
+                await saveQRCode(url: item.url)
+            }
+        }
+        .task(id: taskID) {
+            await viewModel.load(api: queueAPI, scenicId: currentScenicId, userId: currentUserId, spots: scenicSpotContext.spots)
+            await viewModel.loadSettingChangeLogs(api: queueAPI, scenicId: currentScenicId)
+        }
+        .onChange(of: viewModel.message) { _, message in
+            if let message { toastCenter.show(message) }
+        }
+    }
+
+    private var taskID: String {
+        "\(currentScenicId ?? 0)-\(scenicSpotContext.spots.map(\.id).description)"
+    }
+
+    private var basicSection: some View {
+        VStack(alignment: .leading, spacing: AppMetrics.Spacing.medium) {
+            sectionTitle("基础设置")
+            Picker("打卡点", selection: Binding(
+                get: { viewModel.selectedSpotId ?? 0 },
+                set: { id in
+                    viewModel.selectedSpotId = id == 0 ? nil : id
+                    Task { await viewModel.loadSelectedSpotSetting(api: queueAPI, scenicId: currentScenicId, userId: currentUserId) }
+                }
+            )) {
+                Text("请选择").tag(0)
+                ForEach(viewModel.scenicSpots) { spot in
+                    Text(spot.name).tag(spot.id)
+                }
+            }
+            .pickerStyle(.menu)
+            .frame(maxWidth: .infinity, alignment: .leading)
+
+            Toggle("开放排队", isOn: $viewModel.queueOpen)
+            DatePicker("营业开始", selection: $viewModel.businessStartTime, displayedComponents: .hourAndMinute)
+            DatePicker("营业结束", selection: $viewModel.businessEndTime, displayedComponents: .hourAndMinute)
+            field("最大排队范围", text: $viewModel.maxQueueRangeKm, keyboard: .decimalPad, unit: "公里")
+                .onChange(of: viewModel.maxQueueRangeKm) { _, value in viewModel.updateMaxQueueRange(value) }
+            field("排队次数限制", text: $viewModel.localQueueLimit, keyboard: .numberPad, unit: "次")
+            field("过号顺延", text: $viewModel.localPassDelay, keyboard: .numberPad, unit: "位")
+            field("拍摄分钟", text: $viewModel.photoEstimateMin, keyboard: .numberPad, unit: "分")
+            field("拍摄秒数", text: $viewModel.photoEstimateSec, keyboard: .numberPad, unit: "秒")
+            Toggle("展示开始拍摄按钮", isOn: $viewModel.showStartShootingButton)
+            field("自动叫号后续", text: $viewModel.autoCallAheadCount, keyboard: .numberPad, unit: "位")
+            Toggle("快捷叫号按钮", isOn: $viewModel.quickCallButtonEnabled)
+            Toggle("预备叫号按钮", isOn: $viewModel.prepareCallButtonEnabled)
+        }
+        .cardStyle()
+    }
+
+    private var noticeSection: some View {
+        VStack(alignment: .leading, spacing: AppMetrics.Spacing.medium) {
+            sectionTitle("通知规则")
+            field("第一次通知阈值", text: $viewModel.firstAhead, keyboard: .numberPad, unit: "位")
+            Toggle("第一次短信通知", isOn: $viewModel.firstSms)
+            Toggle("第一次电话通知", isOn: $viewModel.firstPhone)
+            Divider()
+            field("第二次通知阈值", text: $viewModel.secondAhead, keyboard: .numberPad, unit: "位")
+            Toggle("第二次短信通知", isOn: $viewModel.secondSms)
+            Toggle("第二次电话通知", isOn: $viewModel.secondPhone)
+        }
+        .cardStyle()
+    }
+
+    private var voiceSection: some View {
+        VStack(alignment: .leading, spacing: AppMetrics.Spacing.medium) {
+            sectionTitle("语音播报")
+            Toggle("本地语音合成提醒", isOn: Binding(
+                get: { queueRuntime.voiceEnabled },
+                set: { queueRuntime.voiceEnabled = $0 }
+            ))
+            Toggle("后台短时轮询", isOn: Binding(
+                get: { queueRuntime.backgroundPollingEnabled },
+                set: { queueRuntime.backgroundPollingEnabled = $0 }
+            ))
+            field("播报间隔", text: $viewModel.broadcastIntervalSec, keyboard: .numberPad, unit: "秒")
+            field("读秒阈值", text: $viewModel.countdownThresholdSec, keyboard: .numberPad, unit: "秒")
+
+            TextEditor(text: $viewModel.customTtsText)
+                .frame(minHeight: 88)
+                .appInputFieldStyle(cornerRadius: AppMetrics.CornerRadius.input, minHeight: 88)
+            HStack {
+                Button("试听") { viewModel.playCustomText() }
+                    .buttonStyle(.bordered)
+                Button("保存为预设") { viewModel.saveCustomTextAsPreset() }
+                    .buttonStyle(.borderedProminent)
+            }
+            Button("播放测试音") { viewModel.playTestSound() }
+                .buttonStyle(.bordered)
+
+            if !viewModel.presetVoices.isEmpty {
+                ForEach(Array(viewModel.presetVoices.enumerated()), id: \.offset) { index, text in
+                    HStack {
+                        Text(text)
+                            .font(.system(size: AppMetrics.FontSize.subheadline))
+                            .foregroundStyle(AppDesign.textPrimary)
+                            .lineLimit(2)
+                        Spacer()
+                        Button {
+                            viewModel.deletePresetVoice(at: index)
+                        } label: {
+                            Image(systemName: "trash")
+                        }
+                    }
+                    .padding(.vertical, 6)
+                }
+            }
+        }
+        .cardStyle()
+    }
+
+    private var logsSection: some View {
+        VStack(alignment: .leading, spacing: AppMetrics.Spacing.medium) {
+            HStack {
+                sectionTitle("配置日志")
+                Spacer()
+                Button {
+                    Task { await viewModel.loadSettingChangeLogs(api: queueAPI, scenicId: currentScenicId) }
+                } label: {
+                    Image(systemName: "arrow.clockwise")
+                }
+            }
+            if viewModel.logs.isEmpty {
+                ContentUnavailableView("暂无配置日志", systemImage: "clock.arrow.circlepath")
+                    .frame(maxWidth: .infinity, minHeight: 180)
+            } else {
+                ForEach(viewModel.logs) { log in
+                    VStack(alignment: .leading, spacing: 6) {
+                        Text(log.displayText.isEmpty ? log.summary : log.displayText)
+                            .font(.system(size: AppMetrics.FontSize.subheadline, weight: .medium))
+                            .foregroundStyle(AppDesign.textPrimary)
+                        Text("\(log.scenicSpotName) \(log.operatorName) \(log.createdAt)")
+                            .font(.system(size: AppMetrics.FontSize.caption))
+                            .foregroundStyle(AppDesign.textSecondary)
+                    }
+                    .frame(maxWidth: .infinity, alignment: .leading)
+                    Divider()
+                }
+            }
+        }
+        .cardStyle()
+    }
+
+    private func field(_ title: String, text: Binding<String>, keyboard: UIKeyboardType, unit: String) -> some View {
+        HStack(spacing: AppMetrics.Spacing.medium) {
+            Text(title)
+                .font(.system(size: AppMetrics.FontSize.subheadline))
+                .foregroundStyle(AppDesign.textPrimary)
+                .frame(width: 104, alignment: .leading)
+            TextField("", text: text)
+                .keyboardType(keyboard)
+                .textFieldStyle(.plain)
+                .multilineTextAlignment(.trailing)
+            Text(unit)
+                .font(.system(size: AppMetrics.FontSize.caption))
+                .foregroundStyle(AppDesign.textSecondary)
+        }
+        .appInputFieldStyle(cornerRadius: AppMetrics.CornerRadius.input, minHeight: AppMetrics.ControlSize.inputHeight)
+    }
+
+    private func sectionTitle(_ title: String) -> some View {
+        Text(title)
+            .font(.system(size: AppMetrics.FontSize.body, weight: .semibold))
+            .foregroundStyle(AppDesign.textPrimary)
+    }
+
+    private func fetchQRCode() async {
+        do {
+            qrcodeURL = try await viewModel.fetchQRCode(api: queueAPI, scenicId: currentScenicId)
+        } catch {
+            toastCenter.show(error.localizedDescription)
+        }
+    }
+
+    private func saveQRCode(url: String) async {
+        do {
+            try await viewModel.saveQRCodeToPhotoLibrary(qrcodeURL: url)
+            toastCenter.show("二维码已保存")
+        } catch {
+            toastCenter.show(error.localizedDescription)
+        }
+    }
+
+    private func save() async {
+        saving = true
+        defer { saving = false }
+        do {
+            try await viewModel.save(api: queueAPI, scenicId: currentScenicId, userId: currentUserId)
+            toastCenter.show("排队设置已保存")
+            await viewModel.loadSettingChangeLogs(api: queueAPI, scenicId: currentScenicId)
+        } catch {
+            toastCenter.show(error.localizedDescription)
+        }
+    }
+}
+
+private enum ScenicQueueSettingsTab: CaseIterable, Identifiable {
+    case basic
+    case notice
+    case voice
+    case logs
+
+    var id: Self { self }
+
+    var title: String {
+        switch self {
+        case .basic: return "基础"
+        case .notice: return "通知"
+        case .voice: return "语音"
+        case .logs: return "日志"
+        }
+    }
+}
+
+private struct QueueQRCodeSheetItem: Identifiable {
+    let url: String
+    var id: String { url }
+}
+
+private struct QueueQRCodeView: View {
+    let url: String
+    let onSave: () async -> Void
+    @Environment(\.dismiss) private var dismiss
+    @State private var saving = false
+
+    var body: some View {
+        NavigationStack {
+            VStack(spacing: AppMetrics.Spacing.large) {
+                RemoteImage(urlString: url, contentMode: .fit) {
+                    Image(systemName: "qrcode")
+                        .font(.system(size: 80))
+                        .foregroundStyle(AppDesign.placeholder)
+                }
+                .frame(maxWidth: .infinity)
+                .frame(height: 280)
+                .padding(AppMetrics.Spacing.large)
+                .background(.white, in: RoundedRectangle(cornerRadius: AppMetrics.CornerRadius.card))
+
+                Button {
+                    Task {
+                        saving = true
+                        await onSave()
+                        saving = false
+                    }
+                } label: {
+                    Label(saving ? "保存中" : "保存到相册", systemImage: "square.and.arrow.down")
+                        .frame(maxWidth: .infinity)
+                        .frame(height: AppMetrics.ControlSize.primaryButtonHeight)
+                }
+                .buttonStyle(.borderedProminent)
+                .disabled(saving)
+            }
+            .padding(AppMetrics.Spacing.pageHorizontal)
+            .background(Color(hex: 0xF5F7FA).ignoresSafeArea())
+            .navigationTitle("取号二维码")
+            .navigationBarTitleDisplayMode(.inline)
+            .toolbar {
+                ToolbarItem(placement: .cancellationAction) {
+                    Button("关闭") { dismiss() }
+                }
+            }
+        }
+    }
+}
+
+private extension View {
+    func cardStyle() -> some View {
+        padding(AppMetrics.Spacing.medium)
+            .frame(maxWidth: .infinity, alignment: .leading)
+            .background(.white, in: RoundedRectangle(cornerRadius: AppMetrics.CornerRadius.card))
+    }
+}

suixinkan/Features/ScenicPermission/ScenicPermission.md

@@ -26,4 +26,4 @@
 
 当前景区、当前门店、角色 ID 和景区作用域属于账号快照，可保存到 UserDefaults。定位结果、景区申请图片临时数据、OSS STS token、上传进度和表单输入不落盘。
 
-`scenic_settlement` 和 `scenic_settlement_review` 是首页独立结算业务入口，不属于本模块迁移范围，目前仍保持占位。
+`scenic_settlement` 和 `scenic_settlement_review` 是首页独立结算业务入口，已由 `Features/ScenicSettlement` 接管。ScenicPermission 模块只提供景区列表、景区申请记录和权限申请记录等可复用接口。

suixinkan/Features/ScenicSettlement/API/ScenicSettlementAPI.swift

@@ -0,0 +1,41 @@
+//
+//  ScenicSettlementAPI.swift
+//  suixinkan
+//
+//  Created by Codex on 2026/6/25.
+//
+
+import Foundation
+import Observation
+
+/// 景区结算服务协议，定义结算申请提交能力。
+@MainActor
+protocol ScenicSettlementServing {
+    /// 提交单个景区的结算申请。
+    func scenicSettlementSubmit(_ request: ScenicSettlementSubmitRequest) async throws
+}
+
+@MainActor
+@Observable
+/// 景区结算 API，封装结算申请提交网络请求。
+final class ScenicSettlementAPI {
+    @ObservationIgnored private let client: APIClient
+
+    /// 初始化景区结算 API，并注入共享网络客户端。
+    init(client: APIClient) {
+        self.client = client
+    }
+
+    /// 提交单个景区的结算申请。
+    func scenicSettlementSubmit(_ request: ScenicSettlementSubmitRequest) async throws {
+        let _: EmptyPayload = try await client.send(
+            APIRequest(
+                method: .post,
+                path: "/api/yf-handset-app/photog/scenic-settlement/submit",
+                body: request
+            )
+        )
+    }
+}
+
+extension ScenicSettlementAPI: ScenicSettlementServing {}

suixinkan/Features/ScenicSettlement/Models/ScenicSettlementModels.swift

@@ -0,0 +1,28 @@
+//
+//  ScenicSettlementModels.swift
+//  suixinkan
+//
+//  Created by Codex on 2026/6/25.
+//
+
+import Foundation
+
+/// 景区结算可选项，表示一个可申请结算的景区。
+struct ScenicSettlementOption: Equatable, Identifiable {
+    let id: Int
+    let name: String
+    var selected: Bool
+}
+
+/// 景区结算提交请求实体。
+struct ScenicSettlementSubmitRequest: Encodable, Equatable {
+    let scenicId: Int
+    let applyAmount: String
+    let applyRemark: String
+
+    enum CodingKeys: String, CodingKey {
+        case scenicId = "scenic_id"
+        case applyAmount = "apply_amount"
+        case applyRemark = "apply_remark"
+    }
+}

suixinkan/Features/ScenicSettlement/ScenicSettlement.md

@@ -0,0 +1,23 @@
+# 景区结算模块
+
+## 模块职责
+
+`Features/ScenicSettlement` 承接首页 `scenic_settlement` 和 `scenic_settlement_review` 权限入口，负责景区结算申请提交和结算相关审核记录展示。
+
+## 结算申请
+
+`ScenicSettlementViewModel` 从账号上下文读取已有景区，并通过 `ScenicPermissionAPI.scenicListAll` 加载全部可申请景区，排除已开通景区后供用户多选。
+
+提交时校验金额必填、正数且最多两位小数，再按景区 ID 升序逐条调用 `/api/yf-handset-app/photog/scenic-settlement/submit`。全部成功后清空已选景区、金额和备注；任一请求失败时保留当前表单并提示错误。
+
+## 结算审核
+
+`ScenicSettlementReviewViewModel` 复用景区申请记录和权限申请记录接口：
+- `scenicApplicationPendingAll`
+- `roleApplyAll`
+
+两个通道独立容错。单通道失败时展示另一通道数据并提示失败；双通道失败时展示整页失败和重新加载入口。
+
+## 边界
+
+旧 Android 工程中的景区结算仍是本地 mock 数据。本模块以旧 iOS 已接入的真实结算提交接口和审核记录聚合方式为迁移依据，不新增后端未体现的详情审批操作。

suixinkan/Features/ScenicSettlement/ViewModels/ScenicSettlementViewModels.swift

@@ -0,0 +1,264 @@
+//
+//  ScenicSettlementViewModels.swift
+//  suixinkan
+//
+//  Created by Codex on 2026/6/25.
+//
+
+import Foundation
+import Observation
+import SwiftUI
+
+@MainActor
+@Observable
+/// 景区结算申请 ViewModel，管理可申请景区、多选、金额备注和提交。
+final class ScenicSettlementViewModel {
+    var existingScenics: [BusinessScope] = []
+    var options: [ScenicSettlementOption] = []
+    var amountText = ""
+    var remarkText = ""
+    var isLoading = false
+    var isSubmitting = false
+    var loadFailed = false
+    var loadFailureReason: String?
+    var message: String?
+
+    private var selectedIds = Set<Int>()
+
+    /// 已选择景区数量。
+    var selectedCount: Int {
+        selectedIds.count
+    }
+
+    /// 当前选择的景区 ID，供测试和提交使用。
+    var selectedScenicIds: Set<Int> {
+        selectedIds
+    }
+
+    /// 金额校验状态。
+    var amountValidation: ScenicSettlementAmountValidation {
+        let trimmed = amountText.trimmingCharacters(in: .whitespacesAndNewlines)
+        if trimmed.isEmpty { return .empty }
+        guard trimmed.range(of: #"^\d+(\.\d{1,2})?$"#, options: .regularExpression) != nil else {
+            return .invalidFormat
+        }
+        guard let decimal = Decimal(string: trimmed), decimal > 0 else {
+            return .notPositive
+        }
+        return .valid
+    }
+
+    /// 是否允许提交结算申请。
+    var canSubmit: Bool {
+        !isSubmitting && !selectedIds.isEmpty && amountValidation == .valid
+    }
+
+    /// 加载已开通景区和可申请结算景区。
+    func load(api: any ScenicPermissionServing, existingScenics: [BusinessScope]) async {
+        isLoading = true
+        loadFailed = false
+        loadFailureReason = nil
+        self.existingScenics = existingScenics
+        defer { isLoading = false }
+
+        do {
+            let all = try await api.scenicListAll().list
+            let existingIds = Set(existingScenics.map(\.id))
+            options = all
+                .filter { !existingIds.contains($0.id) }
+                .map { ScenicSettlementOption(id: $0.id, name: $0.name, selected: selectedIds.contains($0.id)) }
+        } catch {
+            options = []
+            selectedIds.removeAll()
+            loadFailed = true
+            loadFailureReason = error.localizedDescription
+            message = "可申请景区加载失败，请重试"
+        }
+    }
+
+    /// 切换一个景区的结算申请选择状态。
+    func toggleScenic(id: Int) {
+        guard let index = options.firstIndex(where: { $0.id == id }) else { return }
+        options[index].selected.toggle()
+        if options[index].selected {
+            selectedIds.insert(id)
+        } else {
+            selectedIds.remove(id)
+        }
+    }
+
+    /// 提交结算申请，多景区按 ID 升序逐条提交。
+    func submit(api: any ScenicSettlementServing) async -> Bool {
+        guard !isSubmitting else { return false }
+        guard canSubmit else {
+            message = validationMessage
+            return false
+        }
+
+        isSubmitting = true
+        defer { isSubmitting = false }
+
+        let amount = normalizedAmount
+        let remark = remarkText.trimmingCharacters(in: .whitespacesAndNewlines)
+
+        do {
+            for scenicId in selectedIds.sorted() {
+                try await api.scenicSettlementSubmit(
+                    ScenicSettlementSubmitRequest(
+                        scenicId: scenicId,
+                        applyAmount: amount,
+                        applyRemark: remark
+                    )
+                )
+            }
+            selectedIds.removeAll()
+            options = options.map { option in
+                ScenicSettlementOption(id: option.id, name: option.name, selected: false)
+            }
+            amountText = ""
+            remarkText = ""
+            message = "提交成功，等待审核"
+            return true
+        } catch {
+            message = error.localizedDescription
+            return false
+        }
+    }
+
+    private var normalizedAmount: String {
+        let decimal = Decimal(string: amountText.trimmingCharacters(in: .whitespacesAndNewlines)) ?? 0
+        return String(format: "%.2f", NSDecimalNumber(decimal: decimal).doubleValue)
+    }
+
+    private var validationMessage: String {
+        if selectedIds.isEmpty { return "请先选择景区" }
+        switch amountValidation {
+        case .empty:
+            return "请填写结算金额"
+        case .invalidFormat:
+            return "金额格式错误，最多支持两位小数"
+        case .notPositive:
+            return "金额需大于 0"
+        case .valid:
+            return ""
+        }
+    }
+}
+
+/// 景区结算金额校验结果。
+enum ScenicSettlementAmountValidation: Equatable {
+    case empty
+    case invalidFormat
+    case notPositive
+    case valid
+
+    /// 对应的状态提示文案。
+    var badgeText: String {
+        switch self {
+        case .empty: "待填写金额"
+        case .invalidFormat: "金额格式错误"
+        case .notPositive: "金额需大于 0"
+        case .valid: "金额有效"
+        }
+    }
+
+    /// 对应的状态颜色。
+    var badgeColor: Color {
+        switch self {
+        case .empty, .notPositive:
+            return AppDesign.warning
+        case .invalidFormat:
+            return Color(hex: 0xDC2626)
+        case .valid:
+            return AppDesign.success
+        }
+    }
+}
+
+@MainActor
+@Observable
+/// 景区结算审核 ViewModel，聚合景区申请和权限申请审核记录。
+final class ScenicSettlementReviewViewModel {
+    var scenicApplications: [ScenicApplicationPendingResponse] = []
+    var roleApplications: [RoleApplyPendingResponse] = []
+    var isLoading = false
+    var message: String?
+    var loadFailedAll = false
+    var scenicLoadFailed = false
+    var roleLoadFailed = false
+
+    /// 待审核记录数量。
+    var pendingCount: Int {
+        scenicApplications.filter { $0.status == 1 }.count + roleApplications.filter { $0.status == 1 }.count
+    }
+
+    /// 加载审核记录，单通道失败时保留另一通道数据。
+    func load(api: any ScenicPermissionServing) async {
+        isLoading = true
+        loadFailedAll = false
+        scenicLoadFailed = false
+        roleLoadFailed = false
+        message = nil
+        defer { isLoading = false }
+
+        var errors: [String] = []
+        var scenicLoaded = false
+        var roleLoaded = false
+
+        do {
+            scenicApplications = try await api.scenicApplicationPendingAll().items
+            scenicLoaded = true
+        } catch {
+            scenicApplications = []
+            scenicLoadFailed = true
+            errors.append("景区申请记录加载失败")
+        }
+
+        do {
+            roleApplications = try await api.roleApplyAll()
+            roleLoaded = true
+        } catch {
+            roleApplications = []
+            roleLoadFailed = true
+            errors.append("权限申请记录加载失败")
+        }
+
+        loadFailedAll = !scenicLoaded && !roleLoaded
+        if !errors.isEmpty {
+            message = errors.joined(separator: "；")
+        }
+    }
+
+    /// 审核状态文案。
+    func statusText(_ status: Int, fallback: String = "") -> String {
+        let trimmed = fallback.trimmingCharacters(in: .whitespacesAndNewlines)
+        if !trimmed.isEmpty { return trimmed }
+        switch status {
+        case 1: return "待审核"
+        case 2: return "已通过"
+        case 3: return "已驳回"
+        case 9: return "已取消"
+        default: return "未知"
+        }
+    }
+
+    /// 审核状态图标。
+    func statusIcon(_ status: Int) -> String {
+        switch status {
+        case 2: return "checkmark.circle.fill"
+        case 3: return "xmark.octagon.fill"
+        case 1: return "clock.badge.exclamationmark.fill"
+        default: return "questionmark.circle.fill"
+        }
+    }
+
+    /// 审核状态颜色。
+    func statusColor(_ status: Int) -> Color {
+        switch status {
+        case 2: return AppDesign.success
+        case 3: return Color(hex: 0xDC2626)
+        case 1: return AppDesign.warning
+        default: return AppDesign.textSecondary
+        }
+    }
+}

suixinkan/Features/ScenicSettlement/Views/ScenicSettlementViews.swift

@@ -0,0 +1,432 @@
+//
+//  ScenicSettlementViews.swift
+//  suixinkan
+//
+//  Created by Codex on 2026/6/25.
+//
+
+import SwiftUI
+
+/// 景区结算申请页，支持选择未开通结算的景区并提交金额。
+struct ScenicSettlementView: View {
+    @Environment(AccountContext.self) private var accountContext
+    @Environment(ScenicPermissionAPI.self) private var scenicPermissionAPI
+    @Environment(ScenicSettlementAPI.self) private var scenicSettlementAPI
+    @Environment(ToastCenter.self) private var toastCenter
+    @State private var viewModel = ScenicSettlementViewModel()
+    @State private var showScenicApplication = false
+
+    var body: some View {
+        VStack(spacing: 0) {
+            NewScenicBanner {
+                showScenicApplication = true
+            }
+            ScrollView {
+                VStack(spacing: AppMetrics.Spacing.small) {
+                    existingScenicsSection
+                    selectableScenicsSection
+                    settlementInfoSection
+                }
+                .padding(AppMetrics.Spacing.medium)
+            }
+            submitButton
+        }
+        .background(Color(hex: 0xF5F7FA).ignoresSafeArea())
+        .navigationTitle("景区结算")
+        .navigationBarTitleDisplayMode(.inline)
+        .task {
+            await viewModel.load(api: scenicPermissionAPI, existingScenics: accountContext.scenicScopes)
+        }
+        .refreshable {
+            await viewModel.load(api: scenicPermissionAPI, existingScenics: accountContext.scenicScopes)
+        }
+        .sheet(isPresented: $showScenicApplication) {
+            NavigationStack {
+                ScenicApplicationView()
+            }
+        }
+        .onChange(of: viewModel.message) { _, message in
+            guard let message else { return }
+            toastCenter.show(message)
+            viewModel.message = nil
+        }
+    }
+
+    private var existingScenicsSection: some View {
+        VStack(alignment: .leading, spacing: AppMetrics.Spacing.xSmall) {
+            Text("已有景区")
+                .font(.system(size: AppMetrics.FontSize.subheadline, weight: .semibold))
+            if viewModel.existingScenics.isEmpty {
+                Text("暂无已开通景区")
+                    .font(.system(size: AppMetrics.FontSize.caption))
+                    .foregroundStyle(AppDesign.textSecondary)
+            } else {
+                ForEach(viewModel.existingScenics) { scenic in
+                    HStack(spacing: AppMetrics.Spacing.xSmall) {
+                        Image(systemName: "checkmark.seal.fill")
+                            .foregroundStyle(AppDesign.success)
+                        Text(scenic.name)
+                            .font(.system(size: AppMetrics.FontSize.footnote))
+                            .foregroundStyle(AppDesign.textPrimary)
+                        Spacer(minLength: 0)
+                    }
+                }
+            }
+        }
+        .frame(maxWidth: .infinity, alignment: .leading)
+        .padding(AppMetrics.Spacing.small)
+        .background(.white, in: RoundedRectangle(cornerRadius: 12))
+    }
+
+    private var selectableScenicsSection: some View {
+        VStack(alignment: .leading, spacing: AppMetrics.Spacing.xSmall) {
+            HStack {
+                Text("可申请结算景区")
+                    .font(.system(size: AppMetrics.FontSize.subheadline, weight: .semibold))
+                Spacer()
+                formBadge("已选 \(viewModel.selectedCount)", tint: viewModel.selectedCount == 0 ? AppDesign.textSecondary : AppDesign.primary)
+            }
+
+            if viewModel.isLoading && viewModel.options.isEmpty {
+                ProgressView()
+                    .frame(maxWidth: .infinity, minHeight: 120)
+            } else if viewModel.loadFailed {
+                VStack(spacing: AppMetrics.Spacing.xSmall) {
+                    ContentUnavailableView(
+                        "可申请景区加载失败",
+                        systemImage: "exclamationmark.triangle",
+                        description: Text(viewModel.loadFailureReason ?? "请检查网络后重试")
+                    )
+                    Button("重新加载") {
+                        Task { await viewModel.load(api: scenicPermissionAPI, existingScenics: accountContext.scenicScopes) }
+                    }
+                    .font(.system(size: AppMetrics.FontSize.footnote, weight: .semibold))
+                    .buttonStyle(.plain)
+                }
+                .frame(maxWidth: .infinity, minHeight: 160)
+            } else if viewModel.options.isEmpty {
+                Text("暂无可申请结算景区")
+                    .font(.system(size: AppMetrics.FontSize.caption))
+                    .foregroundStyle(AppDesign.textSecondary)
+            } else {
+                ForEach(viewModel.options) { option in
+                    Button {
+                        viewModel.toggleScenic(id: option.id)
+                    } label: {
+                        HStack {
+                            Text(option.name)
+                                .font(.system(size: AppMetrics.FontSize.footnote))
+                                .foregroundStyle(option.selected ? AppDesign.primary : AppDesign.textPrimary)
+                            Spacer()
+                            Image(systemName: option.selected ? "checkmark.circle.fill" : "circle")
+                                .foregroundStyle(option.selected ? AppDesign.primary : Color(hex: 0xCBD5E1))
+                        }
+                        .padding(.horizontal, AppMetrics.Spacing.small)
+                        .padding(.vertical, AppMetrics.Spacing.xSmall)
+                        .background(option.selected ? AppDesign.primarySoft : Color(hex: 0xF8FAFC), in: RoundedRectangle(cornerRadius: 8))
+                    }
+                    .buttonStyle(.plain)
+                }
+            }
+        }
+        .frame(maxWidth: .infinity, alignment: .leading)
+        .padding(AppMetrics.Spacing.small)
+        .background(.white, in: RoundedRectangle(cornerRadius: 12))
+    }
+
+    private var settlementInfoSection: some View {
+        VStack(alignment: .leading, spacing: AppMetrics.Spacing.xSmall) {
+            HStack {
+                Text("结算信息")
+                    .font(.system(size: AppMetrics.FontSize.subheadline, weight: .semibold))
+                    .foregroundStyle(AppDesign.textPrimary)
+                Spacer()
+                formBadge("已选 \(viewModel.selectedCount)", tint: viewModel.selectedCount == 0 ? AppDesign.textSecondary : AppDesign.primary)
+                formBadge(viewModel.amountValidation.badgeText, tint: viewModel.amountValidation.badgeColor)
+            }
+            TextField("申请金额（必填）", text: Binding(
+                get: { viewModel.amountText },
+                set: { viewModel.amountText = $0 }
+            ))
+            .keyboardType(.decimalPad)
+            .textFieldStyle(.plain)
+            .padding(.horizontal, AppMetrics.Spacing.small)
+            .frame(minHeight: 44)
+            .background(Color(hex: 0xF8FAFC), in: RoundedRectangle(cornerRadius: 10))
+
+            TextField("备注信息（可选）", text: Binding(
+                get: { viewModel.remarkText },
+                set: { viewModel.remarkText = $0 }
+            ), axis: .vertical)
+            .lineLimit(2...4)
+            .textFieldStyle(.plain)
+            .padding(AppMetrics.Spacing.small)
+            .frame(minHeight: 86, alignment: .topLeading)
+            .background(Color(hex: 0xF8FAFC), in: RoundedRectangle(cornerRadius: 10))
+        }
+        .padding(AppMetrics.Spacing.small)
+        .background(.white, in: RoundedRectangle(cornerRadius: 12))
+    }
+
+    private var submitButton: some View {
+        Button(viewModel.isSubmitting ? "提交中..." : "提交审核") {
+            Task { _ = await viewModel.submit(api: scenicSettlementAPI) }
+        }
+        .font(.system(size: AppMetrics.FontSize.body, weight: .semibold))
+        .foregroundStyle(.white)
+        .frame(maxWidth: .infinity)
+        .frame(height: 48)
+        .background(viewModel.canSubmit ? AppDesign.primary : Color(hex: 0xC9CED6), in: RoundedRectangle(cornerRadius: 12))
+        .buttonStyle(.plain)
+        .disabled(!viewModel.canSubmit)
+        .padding(AppMetrics.Spacing.medium)
+        .background(.white)
+    }
+
+    private func formBadge(_ text: String, tint: Color) -> some View {
+        Text(text)
+            .font(.system(size: AppMetrics.FontSize.caption, weight: .medium))
+            .foregroundStyle(tint)
+            .padding(.horizontal, AppMetrics.Spacing.small)
+            .frame(height: 22)
+            .background(tint.opacity(0.12), in: Capsule())
+    }
+}
+
+/// 景区结算审核记录页，展示景区申请和权限申请审核状态。
+struct ScenicSettlementReviewView: View {
+    @Environment(ScenicPermissionAPI.self) private var scenicPermissionAPI
+    @Environment(ToastCenter.self) private var toastCenter
+    @State private var viewModel = ScenicSettlementReviewViewModel()
+
+    var body: some View {
+        ScrollView {
+            VStack(spacing: AppMetrics.Spacing.small) {
+                if viewModel.loadFailedAll {
+                    fullFailureView
+                } else {
+                    reviewSummary
+                    scenicSection
+                    roleSection
+                }
+            }
+            .padding(AppMetrics.Spacing.medium)
+        }
+        .background(Color(hex: 0xF5F7FA).ignoresSafeArea())
+        .navigationTitle("结算审核")
+        .navigationBarTitleDisplayMode(.inline)
+        .task {
+            await viewModel.load(api: scenicPermissionAPI)
+        }
+        .refreshable {
+            await viewModel.load(api: scenicPermissionAPI)
+        }
+        .onChange(of: viewModel.message) { _, message in
+            guard let message else { return }
+            toastCenter.show(message)
+            viewModel.message = nil
+        }
+    }
+
+    private var fullFailureView: some View {
+        VStack(spacing: AppMetrics.Spacing.small) {
+            ContentUnavailableView(
+                "审核记录加载失败",
+                systemImage: "exclamationmark.triangle",
+                description: Text("景区申请与权限申请均未加载成功，请检查网络后重试")
+            )
+            Button("重新加载") {
+                Task { await viewModel.load(api: scenicPermissionAPI) }
+            }
+            .font(.system(size: AppMetrics.FontSize.footnote, weight: .semibold))
+            .foregroundStyle(AppDesign.primary)
+            .padding(.horizontal, AppMetrics.Spacing.small)
+            .frame(height: 34)
+            .background(AppDesign.primarySoft, in: RoundedRectangle(cornerRadius: 8))
+            .buttonStyle(.plain)
+        }
+        .frame(maxWidth: .infinity, minHeight: 260)
+        .background(.white, in: RoundedRectangle(cornerRadius: 12))
+    }
+
+    private var reviewSummary: some View {
+        HStack(spacing: AppMetrics.Spacing.xSmall) {
+            summaryCard("景区申请", "\(viewModel.scenicApplications.count)")
+            summaryCard("权限申请", "\(viewModel.roleApplications.count)")
+            summaryCard("待审核", "\(viewModel.pendingCount)")
+        }
+    }
+
+    private var scenicSection: some View {
+        VStack(alignment: .leading, spacing: AppMetrics.Spacing.xSmall) {
+            sectionHeader("景区申请记录", count: viewModel.scenicApplications.count, icon: "mountain.2.fill")
+            if viewModel.scenicLoadFailed {
+                sectionFailureRow("景区申请记录加载失败")
+            } else if viewModel.scenicApplications.isEmpty {
+                Text("暂无景区申请记录")
+                    .font(.system(size: AppMetrics.FontSize.caption))
+                    .foregroundStyle(AppDesign.textSecondary)
+            } else {
+                ForEach(viewModel.scenicApplications) { item in
+                    reviewRow(
+                        title: item.scenicName,
+                        code: item.code,
+                        subtitle: item.createdAt,
+                        status: viewModel.statusText(item.status),
+                        status: item.status
+                    )
+                }
+            }
+        }
+        .padding(AppMetrics.Spacing.small)
+        .background(.white, in: RoundedRectangle(cornerRadius: 12))
+    }
+
+    private var roleSection: some View {
+        VStack(alignment: .leading, spacing: AppMetrics.Spacing.xSmall) {
+            sectionHeader("权限申请记录", count: viewModel.roleApplications.count, icon: "person.badge.shield.checkmark.fill")
+            if viewModel.roleLoadFailed {
+                sectionFailureRow("权限申请记录加载失败")
+            } else if viewModel.roleApplications.isEmpty {
+                Text("暂无权限申请记录")
+                    .font(.system(size: AppMetrics.FontSize.caption))
+                    .foregroundStyle(AppDesign.textSecondary)
+            } else {
+                ForEach(viewModel.roleApplications) { item in
+                    reviewRow(
+                        title: "\(item.roleName) · \(scenicNames(item.scenicList))",
+                        code: item.code,
+                        subtitle: item.createdAt,
+                        status: viewModel.statusText(item.status, fallback: item.statusLabel),
+                        status: item.status
+                    )
+                }
+            }
+        }
+        .padding(AppMetrics.Spacing.small)
+        .background(.white, in: RoundedRectangle(cornerRadius: 12))
+    }
+
+    private func sectionFailureRow(_ text: String) -> some View {
+        HStack(spacing: AppMetrics.Spacing.xSmall) {
+            Image(systemName: "exclamationmark.triangle")
+                .foregroundStyle(AppDesign.warning)
+            Text(text)
+                .font(.system(size: AppMetrics.FontSize.caption))
+                .foregroundStyle(AppDesign.textSecondary)
+            Spacer(minLength: 0)
+            Button("重试") {
+                Task { await viewModel.load(api: scenicPermissionAPI) }
+            }
+            .font(.system(size: AppMetrics.FontSize.caption, weight: .semibold))
+            .foregroundStyle(AppDesign.primary)
+            .buttonStyle(.plain)
+        }
+        .padding(AppMetrics.Spacing.xSmall)
+        .background(Color(hex: 0xFFF7ED), in: RoundedRectangle(cornerRadius: 8))
+    }
+
+    private func reviewRow(title: String, code: String, subtitle: String, status statusText: String, status: Int) -> some View {
+        VStack(alignment: .leading, spacing: AppMetrics.Spacing.xSmall) {
+            Text(title)
+                .font(.system(size: AppMetrics.FontSize.subheadline, weight: .semibold))
+                .foregroundStyle(AppDesign.textPrimary)
+            Label("申请编号：\(code.settlementDash)", systemImage: "number.square.fill")
+                .font(.system(size: AppMetrics.FontSize.caption, weight: .medium))
+                .foregroundStyle(AppDesign.primary)
+                .padding(.horizontal, AppMetrics.Spacing.small)
+                .frame(height: 22)
+                .background(AppDesign.primarySoft, in: Capsule())
+            HStack {
+                Label(statusText, systemImage: viewModel.statusIcon(status))
+                    .font(.system(size: AppMetrics.FontSize.caption, weight: .medium))
+                    .foregroundStyle(viewModel.statusColor(status))
+                    .padding(.horizontal, AppMetrics.Spacing.small)
+                    .frame(height: 22)
+                    .background(viewModel.statusColor(status).opacity(0.12), in: Capsule())
+                Spacer(minLength: 0)
+                Label(subtitle.settlementDash, systemImage: "clock")
+                    .font(.system(size: AppMetrics.FontSize.caption))
+                    .foregroundStyle(AppDesign.textSecondary)
+            }
+        }
+        .padding(AppMetrics.Spacing.xSmall)
+        .background(Color(hex: 0xF8FAFC), in: RoundedRectangle(cornerRadius: 10))
+    }
+
+    private func summaryCard(_ title: String, _ value: String) -> some View {
+        VStack(alignment: .leading, spacing: 4) {
+            Text(title)
+                .font(.system(size: AppMetrics.FontSize.caption))
+                .foregroundStyle(AppDesign.textSecondary)
+            Text(value)
+                .font(.system(size: AppMetrics.FontSize.title, weight: .semibold))
+                .foregroundStyle(AppDesign.textPrimary)
+        }
+        .frame(maxWidth: .infinity, alignment: .leading)
+        .padding(AppMetrics.Spacing.small)
+        .background(.white, in: RoundedRectangle(cornerRadius: 12))
+    }
+
+    private func sectionHeader(_ title: String, count: Int, icon: String) -> some View {
+        HStack(spacing: AppMetrics.Spacing.xSmall) {
+            Image(systemName: icon)
+                .font(.system(size: AppMetrics.FontSize.footnote, weight: .semibold))
+                .foregroundStyle(AppDesign.primary)
+            Text(title)
+                .font(.system(size: AppMetrics.FontSize.subheadline, weight: .semibold))
+                .foregroundStyle(AppDesign.textPrimary)
+            Spacer()
+            Text("\(count)")
+                .font(.system(size: AppMetrics.FontSize.caption, weight: .medium))
+                .foregroundStyle(AppDesign.primary)
+                .padding(.horizontal, AppMetrics.Spacing.small)
+                .frame(height: 22)
+                .background(AppDesign.primarySoft, in: Capsule())
+        }
+    }
+
+    private func scenicNames(_ items: [RoleApplyScenicItem]) -> String {
+        let names = items.map(\.name).filter { !$0.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty }
+        return names.isEmpty ? "--" : names.joined(separator: "、")
+    }
+}
+
+private struct NewScenicBanner: View {
+    let onApplyClick: () -> Void
+
+    var body: some View {
+        HStack(spacing: AppMetrics.Spacing.xSmall) {
+            Image(systemName: "building.2.fill")
+                .font(.system(size: 20, weight: .semibold))
+                .foregroundStyle(Color(hex: 0xFF7B00))
+            Text("没有找到心仪的景区")
+                .font(.system(size: AppMetrics.FontSize.footnote, weight: .medium))
+                .foregroundStyle(Color(hex: 0xFF7B00))
+                .lineLimit(1)
+                .minimumScaleFactor(0.85)
+            Spacer()
+            Button(action: onApplyClick) {
+                HStack(spacing: 4) {
+                    Text("申请平台开通新景区")
+                        .lineLimit(1)
+                        .minimumScaleFactor(0.8)
+                    Image(systemName: "chevron.right")
+                }
+                .font(.system(size: AppMetrics.FontSize.caption, weight: .semibold))
+                .foregroundStyle(Color(hex: 0xFF7B00))
+            }
+            .buttonStyle(.plain)
+        }
+        .padding(.horizontal, AppMetrics.Spacing.medium)
+        .padding(.vertical, AppMetrics.Spacing.small)
+        .background(Color(hex: 0xFFF0E2))
+    }
+}
+
+private extension String {
+    var settlementDash: String {
+        let trimmed = trimmingCharacters(in: .whitespacesAndNewlines)
+        return trimmed.isEmpty ? "--" : trimmed
+    }
+}

suixinkan/Features/WithdrawalAudit/ViewModels/WithdrawalAuditViewModel.swift

@@ -0,0 +1,139 @@
+//
+//  WithdrawalAuditViewModel.swift
+//  suixinkan
+//
+//  Created by Codex on 2026/6/25.
+//
+
+import Foundation
+import Observation
+
+/// 提现审核筛选项，按提现记录的状态文案聚合审核视角。
+enum WithdrawalAuditFilter: String, CaseIterable, Identifiable {
+    case all
+    case processing
+    case completed
+
+    var id: String { rawValue }
+
+    /// 筛选项展示标题。
+    var title: String {
+        switch self {
+        case .all: "全部"
+        case .processing: "处理中"
+        case .completed: "已完成"
+        }
+    }
+}
+
+@MainActor
+@Observable
+/// 提现审核 ViewModel，负责提现记录分页、状态筛选和失败状态清理。
+final class WithdrawalAuditViewModel {
+    var records: [WalletWithdrawRecord] = []
+    var selectedFilter: WithdrawalAuditFilter = .all
+    var isLoading = false
+    var isLoadingMore = false
+    var loadFailed = false
+    var loadFailureReason: String?
+    var errorMessage: String?
+
+    private let pageSize = 10
+    private var page = 1
+    private var total = 0
+
+    /// 当前筛选下的提现记录。
+    var filteredRecords: [WalletWithdrawRecord] {
+        filteredRecords(for: selectedFilter)
+    }
+
+    /// 是否还有下一页。
+    var hasMore: Bool {
+        records.count < total
+    }
+
+    /// 记录总数，优先使用服务端 total。
+    var totalCount: Int {
+        max(total, records.count)
+    }
+
+    /// 处理中数量。
+    var processingCount: Int {
+        filteredRecords(for: .processing).count
+    }
+
+    /// 已完成数量。
+    var completedCount: Int {
+        filteredRecords(for: .completed).count
+    }
+
+    /// 按指定筛选返回提现记录。
+    func filteredRecords(for filter: WithdrawalAuditFilter) -> [WalletWithdrawRecord] {
+        switch filter {
+        case .all:
+            return records
+        case .processing:
+            return records.filter { record in
+                let status = record.statusLabel
+                return status.contains("中") || status.contains("待")
+            }
+        case .completed:
+            return records.filter { record in
+                let status = record.statusLabel
+                return status.contains("完成") || status.contains("到账") || status.contains("通过")
+            }
+        }
+    }
+
+    /// 切换筛选项，仅影响本地展示。
+    func selectFilter(_ filter: WithdrawalAuditFilter) {
+        selectedFilter = filter
+    }
+
+    /// 重新加载第一页提现审核记录。
+    func reload(api: WalletServing) async {
+        isLoading = true
+        loadFailed = false
+        loadFailureReason = nil
+        errorMessage = nil
+        defer { isLoading = false }
+
+        do {
+            let response = try await api.walletWithdrawList(page: 1, pageSize: pageSize)
+            records = response.item
+            total = response.total
+            page = 1
+        } catch {
+            clearRecords()
+            loadFailed = true
+            loadFailureReason = error.localizedDescription
+            errorMessage = error.localizedDescription
+        }
+    }
+
+    /// 加载下一页提现审核记录。
+    func loadMore(api: WalletServing) async {
+        guard hasMore, !isLoadingMore, !isLoading else { return }
+        isLoadingMore = true
+        errorMessage = nil
+        defer { isLoadingMore = false }
+
+        let nextPage = page + 1
+        do {
+            let response = try await api.walletWithdrawList(page: nextPage, pageSize: pageSize)
+            records += response.item
+            total = response.total
+            page = nextPage
+        } catch {
+            errorMessage = error.localizedDescription
+        }
+    }
+
+    /// 清空旧提现审核数据，避免失败后残留上一账号或上一状态记录。
+    private func clearRecords() {
+        records = []
+        page = 1
+        total = 0
+        isLoadingMore = false
+    }
+}

suixinkan/Features/WithdrawalAudit/Views/WithdrawalAuditView.swift

@@ -0,0 +1,311 @@
+//
+//  WithdrawalAuditView.swift
+//  suixinkan
+//
+//  Created by Codex on 2026/6/25.
+//
+
+import SwiftUI
+
+/// 提现审核列表页，以审核视角展示钱包提现记录和处理进度。
+struct WithdrawalAuditView: View {
+    @Environment(WalletAPI.self) private var walletAPI
+    @Environment(ToastCenter.self) private var toastCenter
+    @State private var viewModel = WithdrawalAuditViewModel()
+    @State private var selectedRecord: WalletWithdrawRecord?
+
+    var body: some View {
+        ScrollView {
+            VStack(spacing: AppMetrics.Spacing.small) {
+                summarySection
+                filterSection
+                contentSection
+            }
+            .padding(AppMetrics.Spacing.medium)
+        }
+        .background(Color(hex: 0xF5F7FA).ignoresSafeArea())
+        .navigationTitle("提现审核")
+        .navigationBarTitleDisplayMode(.inline)
+        .task {
+            await viewModel.reload(api: walletAPI)
+        }
+        .refreshable {
+            await viewModel.reload(api: walletAPI)
+        }
+        .sheet(item: $selectedRecord) { record in
+            NavigationStack {
+                WithdrawalAuditDetailView(record: record)
+            }
+        }
+        .onChange(of: viewModel.errorMessage) { _, message in
+            guard let message else { return }
+            toastCenter.show(message)
+            viewModel.errorMessage = nil
+        }
+    }
+
+    private var summarySection: some View {
+        HStack(spacing: AppMetrics.Spacing.xSmall) {
+            summaryCard("记录总数", "\(viewModel.totalCount)")
+            summaryCard("处理中", "\(viewModel.processingCount)")
+            summaryCard("已完成", "\(viewModel.completedCount)")
+        }
+    }
+
+    private var filterSection: some View {
+        VStack(alignment: .leading, spacing: AppMetrics.Spacing.small) {
+            Picker("审核筛选", selection: Binding(
+                get: { viewModel.selectedFilter },
+                set: { viewModel.selectFilter($0) }
+            )) {
+                ForEach(WithdrawalAuditFilter.allCases) { filter in
+                    Text(filter.title).tag(filter)
+                }
+            }
+            .pickerStyle(.segmented)
+
+            HStack(spacing: AppMetrics.Spacing.xSmall) {
+                badge("当前 \(viewModel.selectedFilter.title)", tint: AppDesign.primary)
+                badge("共 \(viewModel.filteredRecords.count) 条", tint: AppDesign.textSecondary)
+                Spacer(minLength: 0)
+            }
+        }
+        .padding(AppMetrics.Spacing.small)
+        .background(.white, in: RoundedRectangle(cornerRadius: 12))
+    }
+
+    @ViewBuilder
+    private var contentSection: some View {
+        if viewModel.isLoading && viewModel.records.isEmpty {
+            ProgressView()
+                .frame(maxWidth: .infinity, minHeight: 220)
+                .background(.white, in: RoundedRectangle(cornerRadius: 12))
+        } else if viewModel.loadFailed && viewModel.records.isEmpty {
+            VStack(spacing: AppMetrics.Spacing.small) {
+                ContentUnavailableView(
+                    "提现审核记录加载失败",
+                    systemImage: "exclamationmark.triangle",
+                    description: Text(viewModel.loadFailureReason ?? "请检查网络后重试")
+                )
+                Button("重新加载") {
+                    Task { await viewModel.reload(api: walletAPI) }
+                }
+                .font(.system(size: AppMetrics.FontSize.footnote, weight: .semibold))
+                .foregroundStyle(AppDesign.primary)
+                .padding(.horizontal, AppMetrics.Spacing.small)
+                .frame(height: 34)
+                .background(AppDesign.primarySoft, in: RoundedRectangle(cornerRadius: 8))
+                .buttonStyle(.plain)
+            }
+            .frame(maxWidth: .infinity, minHeight: 220)
+            .background(.white, in: RoundedRectangle(cornerRadius: 12))
+        } else if viewModel.filteredRecords.isEmpty {
+            ContentUnavailableView("暂无提现审核记录", systemImage: "tray", description: Text("可切换筛选条件或下拉刷新"))
+                .frame(maxWidth: .infinity, minHeight: 220)
+                .background(.white, in: RoundedRectangle(cornerRadius: 12))
+        } else {
+            VStack(spacing: AppMetrics.Spacing.small) {
+                ForEach(viewModel.filteredRecords) { record in
+                    recordCard(record)
+                }
+                if viewModel.hasMore {
+                    Button(viewModel.isLoadingMore ? "加载中..." : "加载更多") {
+                        Task { await viewModel.loadMore(api: walletAPI) }
+                    }
+                    .font(.system(size: AppMetrics.FontSize.footnote, weight: .medium))
+                    .foregroundStyle(AppDesign.primary)
+                    .frame(maxWidth: .infinity)
+                    .frame(height: 40)
+                    .background(.white, in: RoundedRectangle(cornerRadius: 10))
+                    .buttonStyle(.plain)
+                    .disabled(viewModel.isLoadingMore)
+                }
+            }
+        }
+    }
+
+    private func recordCard(_ record: WalletWithdrawRecord) -> some View {
+        HStack(alignment: .top, spacing: AppMetrics.Spacing.small) {
+            VStack(alignment: .leading, spacing: AppMetrics.Spacing.xSmall) {
+                Text("¥ \(moneyText(record.amount))")
+                    .font(.system(size: AppMetrics.FontSize.title, weight: .semibold))
+                    .foregroundStyle(AppDesign.primary)
+                Text("申请时间：\(record.createdAt.withdrawalAuditDash)")
+                    .font(.system(size: AppMetrics.FontSize.caption))
+                    .foregroundStyle(AppDesign.textSecondary)
+            }
+            Spacer(minLength: AppMetrics.Spacing.small)
+            VStack(alignment: .trailing, spacing: AppMetrics.Spacing.xSmall) {
+                Text(statusText(record.statusLabel))
+                    .font(.system(size: AppMetrics.FontSize.caption, weight: .medium))
+                    .foregroundStyle(statusColor(record.statusLabel))
+                    .padding(.horizontal, AppMetrics.Spacing.small)
+                    .frame(height: 24)
+                    .background(statusColor(record.statusLabel).opacity(0.12), in: Capsule())
+                Button("查看详情") {
+                    selectedRecord = record
+                }
+                .font(.system(size: AppMetrics.FontSize.caption, weight: .medium))
+                .foregroundStyle(AppDesign.primary)
+                .padding(.horizontal, AppMetrics.Spacing.small)
+                .frame(height: 28)
+                .background(AppDesign.primarySoft, in: RoundedRectangle(cornerRadius: 8))
+                .buttonStyle(.plain)
+            }
+        }
+        .padding(AppMetrics.Spacing.small)
+        .background(.white, in: RoundedRectangle(cornerRadius: 12))
+    }
+
+    private func summaryCard(_ title: String, _ value: String) -> some View {
+        VStack(alignment: .leading, spacing: 3) {
+            Text(title)
+                .font(.system(size: AppMetrics.FontSize.caption))
+                .foregroundStyle(AppDesign.textSecondary)
+            Text(value)
+                .font(.system(size: AppMetrics.FontSize.subheadline, weight: .semibold))
+                .foregroundStyle(AppDesign.textPrimary)
+        }
+        .frame(maxWidth: .infinity, alignment: .leading)
+        .padding(AppMetrics.Spacing.small)
+        .background(.white, in: RoundedRectangle(cornerRadius: 12))
+    }
+
+    private func badge(_ text: String, tint: Color) -> some View {
+        Text(text)
+            .font(.system(size: AppMetrics.FontSize.caption, weight: .medium))
+            .foregroundStyle(tint)
+            .padding(.horizontal, AppMetrics.Spacing.small)
+            .frame(height: 22)
+            .background(tint.opacity(0.12), in: Capsule())
+    }
+}
+
+/// 提现审核详情页，展示单笔提现记录的审核时间线。
+private struct WithdrawalAuditDetailView: View {
+    let record: WalletWithdrawRecord
+    @Environment(\.dismiss) private var dismiss
+
+    var body: some View {
+        ScrollView {
+            VStack(spacing: AppMetrics.Spacing.small) {
+                card {
+                    row("提现金额", "¥ \(moneyText(record.amount))")
+                    row("申请时间", record.createdAt.withdrawalAuditDash)
+                    HStack {
+                        Text("当前状态")
+                            .font(.system(size: AppMetrics.FontSize.footnote))
+                            .foregroundStyle(AppDesign.textSecondary)
+                        Spacer()
+                        Text(statusText(record.statusLabel))
+                            .font(.system(size: AppMetrics.FontSize.caption, weight: .medium))
+                            .foregroundStyle(statusColor(record.statusLabel))
+                            .padding(.horizontal, AppMetrics.Spacing.small)
+                            .frame(height: 24)
+                            .background(statusColor(record.statusLabel).opacity(0.12), in: Capsule())
+                    }
+                    if let expectedAt = record.expectedAt?.withdrawalAuditNonEmpty {
+                        row("预计到账", expectedAt)
+                    }
+                    if let auditTime = record.auditTime?.withdrawalAuditNonEmpty {
+                        row("审核时间", auditTime)
+                    }
+                    if let completedAt = record.completedAt?.withdrawalAuditNonEmpty {
+                        row("到账时间", completedAt)
+                    }
+                }
+
+                card {
+                    Text("处理进度")
+                        .font(.system(size: AppMetrics.FontSize.subheadline, weight: .semibold))
+                        .foregroundStyle(AppDesign.textPrimary)
+                    timelineRow("1. 提交申请", record.createdAt.withdrawalAuditDash, done: true)
+                    timelineRow("2. 审核中", record.auditTime?.withdrawalAuditDash ?? "--", done: true)
+                    timelineRow("3. 打款中", record.expectedAt?.withdrawalAuditDash ?? "--", done: record.completedAt?.withdrawalAuditNonEmpty == nil)
+                    timelineRow("4. 已完成", record.completedAt?.withdrawalAuditDash ?? "--", done: record.completedAt?.withdrawalAuditNonEmpty != nil)
+                }
+            }
+            .padding(AppMetrics.Spacing.medium)
+        }
+        .background(Color(hex: 0xF5F7FA).ignoresSafeArea())
+        .navigationTitle("审核详情")
+        .navigationBarTitleDisplayMode(.inline)
+        .toolbar {
+            ToolbarItem(placement: .topBarLeading) {
+                Button("关闭") { dismiss() }
+            }
+        }
+    }
+
+    private func card<Content: View>(@ViewBuilder _ content: () -> Content) -> some View {
+        VStack(alignment: .leading, spacing: AppMetrics.Spacing.small) {
+            content()
+        }
+        .padding(AppMetrics.Spacing.small)
+        .background(.white, in: RoundedRectangle(cornerRadius: 12))
+    }
+
+    private func row(_ title: String, _ value: String) -> some View {
+        HStack {
+            Text(title)
+                .font(.system(size: AppMetrics.FontSize.footnote))
+                .foregroundStyle(AppDesign.textSecondary)
+            Spacer()
+            Text(value)
+                .font(.system(size: AppMetrics.FontSize.footnote))
+                .foregroundStyle(AppDesign.textPrimary)
+                .multilineTextAlignment(.trailing)
+        }
+    }
+
+    private func timelineRow(_ title: String, _ time: String, done: Bool) -> some View {
+        HStack(spacing: AppMetrics.Spacing.xSmall) {
+            Circle()
+                .fill(done ? AppDesign.success : Color(hex: 0xD1D5DB))
+                .frame(width: 8, height: 8)
+            Text(title)
+                .font(.system(size: AppMetrics.FontSize.footnote))
+                .foregroundStyle(AppDesign.textPrimary)
+            Spacer()
+            Text(time)
+                .font(.system(size: AppMetrics.FontSize.caption))
+                .foregroundStyle(AppDesign.textSecondary)
+        }
+        .padding(.horizontal, AppMetrics.Spacing.small)
+        .frame(height: 34)
+        .background(Color(hex: 0xF8FAFC), in: RoundedRectangle(cornerRadius: 8))
+    }
+}
+
+private func statusText(_ status: String) -> String {
+    status.withdrawalAuditNonEmpty ?? "处理中"
+}
+
+private func statusColor(_ status: String) -> Color {
+    if status.contains("通过") || status.contains("完成") || status.contains("到账") {
+        return AppDesign.success
+    }
+    if status.contains("拒") || status.contains("失败") {
+        return Color(hex: 0xDC2626)
+    }
+    return AppDesign.warning
+}
+
+private func moneyText(_ raw: String) -> String {
+    let value = raw.filter { "0123456789.-".contains($0) }
+    guard let decimal = Decimal(string: value), decimal > 0 else {
+        return "0.00"
+    }
+    return NSDecimalNumber(decimal: decimal).stringValue
+}
+
+private extension String {
+    var withdrawalAuditNonEmpty: String? {
+        let trimmed = trimmingCharacters(in: .whitespacesAndNewlines)
+        return trimmed.isEmpty ? nil : trimmed
+    }
+
+    var withdrawalAuditDash: String {
+        withdrawalAuditNonEmpty ?? "--"
+    }
+}

suixinkan/Features/WithdrawalAudit/WithdrawalAudit.md

@@ -0,0 +1,16 @@
+# 提现审核模块
+
+## 模块职责
+
+`Features/WithdrawalAudit` 承接首页 `withdrawal_audit` 权限入口，以审核视角展示钱包提现记录、状态筛选和单笔处理进度。
+
+## 业务流程
+
+- `WithdrawalAuditView` 进入后调用 `WalletAPI.walletWithdrawList` 加载第一页提现记录。
+- `WithdrawalAuditViewModel` 管理分页、加载更多、筛选状态和失败清理。
+- 筛选只在本地执行：处理中匹配状态文案中的“中/待”，已完成匹配“完成/到账/通过”。
+- 刷新失败会清空旧记录和分页状态，避免账号或权限切换后残留上一组财务数据。
+
+## 边界
+
+本模块不做管理员提现审批操作。旧 Android 工程未找到提现审批列表或操作接口，当前按旧 iOS 的提现记录审核视角迁移。