新增支付与钱包模块，并接入首页路由

引入真实收款与钱包页面替换首页占位入口，通过 RootView 接入 API，并支持银行卡 OSS 上传及二维码保存到相册。

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

suixinkan/Features/Wallet/API/WalletAPI.swift

@@ -0,0 +1,204 @@
+//
+//  WalletAPI.swift
+//  suixinkan
+//
+//  Created by Codex on 2026/6/22.
+//
+
+import Foundation
+import Observation
+
+/// 钱包模块服务协议，定义钱包、提现、银行卡和积分接口能力。
+@MainActor
+protocol WalletServing {
+    /// 获取钱包汇总数据。
+    func walletSummary(type: Int) async throws -> WalletSummaryResponse
+
+    /// 获取钱包收益明细分页。
+    func walletEarningDetail(startDate: String, endDate: String, page: Int, pageSize: Int) async throws -> WalletEarningDetailResponse
+
+    /// 获取提现记录分页。
+    func walletWithdrawList(page: Int, pageSize: Int) async throws -> WalletWithdrawListResponse
+
+    /// 获取提现申请所需信息。
+    func withdrawInfo() async throws -> WithdrawInfoResponse
+
+    /// 发送提现短信验证码。
+    func withdrawSendSms() async throws
+
+    /// 提交提现申请。
+    func withdrawApply(amount: String, smsCode: String) async throws
+
+    /// 获取银行卡审核和资料信息。
+    func bankCardInfo() async throws -> BankCardInfoResponse
+
+    /// 获取银行列表。
+    func bankList() async throws -> BankListResponse
+
+    /// 获取省市区列表。
+    func areas() async throws -> [AreaNode]
+
+    /// 发送银行卡设置短信验证码。
+    func bankCardVerifyCode() async throws
+
+    /// 更新银行卡资料。
+    func updateBankInfo(_ request: UpdateBankInfoRequest) async throws
+
+    /// 获取积分概览。
+    func pointOverview(staffId: Int) async throws -> PointOverviewResponse
+
+    /// 提交积分兑换申请。
+    func pointWithdrawApply(points: Int, remark: String) async throws
+
+    /// 获取积分兑换记录。
+    func pointWithdrawList(status: Int?, page: Int, pageSize: Int) async throws -> PointWithdrawListResponse
+}
+
+@MainActor
+@Observable
+/// 钱包 API，封装个人钱包、提现、银行卡和积分兑换网络请求。
+final class WalletAPI {
+    @ObservationIgnored private let client: APIClient
+
+    /// 初始化钱包 API，并注入共享网络客户端。
+    init(client: APIClient) {
+        self.client = client
+    }
+
+    /// 获取钱包汇总数据。
+    func walletSummary(type: Int = 0) async throws -> WalletSummaryResponse {
+        try await client.send(
+            APIRequest(
+                method: .get,
+                path: "/api/yf-handset-app/photog/wallet/summary",
+                queryItems: [URLQueryItem(name: "type", value: String(type))]
+            )
+        )
+    }
+
+    /// 获取钱包收益明细分页。
+    func walletEarningDetail(startDate: String, endDate: String, page: Int, pageSize: Int) async throws -> WalletEarningDetailResponse {
+        try await client.send(
+            APIRequest(
+                method: .get,
+                path: "/api/yf-handset-app/photog/wallet/earning-detail",
+                queryItems: [
+                    URLQueryItem(name: "start_date", value: startDate),
+                    URLQueryItem(name: "end_date", value: endDate),
+                    URLQueryItem(name: "page", value: String(page)),
+                    URLQueryItem(name: "page_size", value: String(pageSize))
+                ]
+            )
+        )
+    }
+
+    /// 获取提现记录分页。
+    func walletWithdrawList(page: Int, pageSize: Int) async throws -> WalletWithdrawListResponse {
+        try await client.send(
+            APIRequest(
+                method: .get,
+                path: "/api/yf-handset-app/photog/wallet/withdraw-list",
+                queryItems: [
+                    URLQueryItem(name: "page", value: String(page)),
+                    URLQueryItem(name: "page_size", value: String(pageSize))
+                ]
+            )
+        )
+    }
+
+    /// 获取提现申请所需信息。
+    func withdrawInfo() async throws -> WithdrawInfoResponse {
+        try await client.send(
+            APIRequest(method: .get, path: "/api/yf-handset-app/photog/wallet/withdraw-info")
+        )
+    }
+
+    /// 发送提现短信验证码。
+    func withdrawSendSms() async throws {
+        let _: EmptyPayload = try await client.send(
+            APIRequest(method: .post, path: "/api/yf-handset-app/photog/wallet/withdraw-send-sms", body: EmptyPayload())
+        )
+    }
+
+    /// 提交提现申请。
+    func withdrawApply(amount: String, smsCode: String) async throws {
+        let _: EmptyPayload = try await client.send(
+            APIRequest(
+                method: .post,
+                path: "/api/yf-handset-app/photog/wallet/withdraw-apply",
+                body: WithdrawApplyRequest(amount: amount, smsCode: smsCode)
+            )
+        )
+    }
+
+    /// 获取银行卡审核和资料信息。
+    func bankCardInfo() async throws -> BankCardInfoResponse {
+        try await client.send(
+            APIRequest(method: .get, path: "/api/yf-handset-app/photog/wallet/bank-card/info")
+        )
+    }
+
+    /// 获取银行列表。
+    func bankList() async throws -> BankListResponse {
+        try await client.send(
+            APIRequest(method: .get, path: "/api/yf-handset-app/photog/wallet/bank-list")
+        )
+    }
+
+    /// 获取省市区列表。
+    func areas() async throws -> [AreaNode] {
+        try await client.send(
+            APIRequest(method: .get, path: "/api/app/config/areas")
+        )
+    }
+
+    /// 发送银行卡设置短信验证码。
+    func bankCardVerifyCode() async throws {
+        let _: EmptyPayload = try await client.send(
+            APIRequest(method: .post, path: "/api/yf-handset-app/photog/wallet/bank-card/sms-verify-code", body: EmptyPayload())
+        )
+    }
+
+    /// 更新银行卡资料。
+    func updateBankInfo(_ request: UpdateBankInfoRequest) async throws {
+        let _: EmptyPayload = try await client.send(
+            APIRequest(method: .post, path: "/api/yf-handset-app/photog/wallet/bank-card/update", body: request)
+        )
+    }
+
+    /// 获取积分概览。
+    func pointOverview(staffId: Int) async throws -> PointOverviewResponse {
+        try await client.send(
+            APIRequest(
+                method: .post,
+                path: "/api/yf-handset-app/photog/point/overview",
+                queryItems: [URLQueryItem(name: "staff_id", value: String(staffId))],
+                body: EmptyPayload()
+            )
+        )
+    }
+
+    /// 提交积分兑换申请。
+    func pointWithdrawApply(points: Int, remark: String = "积分提现申请") async throws {
+        let _: EmptyPayload = try await client.send(
+            APIRequest(
+                method: .post,
+                path: "/api/yf-handset-app/photog/point/withdraw/apply",
+                body: PointWithdrawApplyRequest(points: points, remark: remark)
+            )
+        )
+    }
+
+    /// 获取积分兑换记录。
+    func pointWithdrawList(status: Int? = nil, page: Int, pageSize: Int) async throws -> PointWithdrawListResponse {
+        try await client.send(
+            APIRequest(
+                method: .post,
+                path: "/api/yf-handset-app/photog/point/withdraw/list",
+                body: PointWithdrawListRequest(status: status, page: page, pageSize: pageSize)
+            )
+        )
+    }
+}
+
+extension WalletAPI: WalletServing {}

suixinkan/Features/Wallet/Models/WalletModels.swift

@@ -0,0 +1,604 @@
+//
+//  WalletModels.swift
+//  suixinkan
+//
+//  Created by Codex on 2026/6/22.
+//
+
+import Foundation
+
+/// 钱包汇总响应实体，表示累计收益、当前余额和可提现金额。
+struct WalletSummaryResponse: Decodable, Equatable {
+    let amountTotal: String
+    let amountCurrentBalance: String
+    let amountWithdrawable: String
+
+    enum CodingKeys: String, CodingKey {
+        case amountTotal = "amount_total"
+        case amountCurrentBalance = "amount_current_balance"
+        case amountWithdrawable = "amount_withdrawable"
+    }
+
+    /// 创建钱包汇总响应实体，主要用于测试和空状态。
+    init(amountTotal: String = "0.00", amountCurrentBalance: String = "0.00", amountWithdrawable: String = "0.00") {
+        self.amountTotal = amountTotal
+        self.amountCurrentBalance = amountCurrentBalance
+        self.amountWithdrawable = amountWithdrawable
+    }
+
+    /// 自定义解码，兼容金额字段类型不稳定。
+    init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        amountTotal = try container.decodeLossyString(forKey: .amountTotal)
+        amountCurrentBalance = try container.decodeLossyString(forKey: .amountCurrentBalance)
+        amountWithdrawable = try container.decodeLossyString(forKey: .amountWithdrawable)
+    }
+}
+
+/// 钱包收益明细响应实体，表示日分组收益和分页总数。
+struct WalletEarningDetailResponse: Decodable, Equatable {
+    let totalAmount: String
+    let totalPoints: Int
+    let total: Int
+    let list: [WalletEarningDetailGroup]
+
+    enum CodingKeys: String, CodingKey {
+        case totalAmount = "total_amount"
+        case totalPoints = "total_points"
+        case total
+        case list
+    }
+
+    /// 创建收益明细响应实体，主要用于测试替身。
+    init(totalAmount: String = "0.00", totalPoints: Int = 0, total: Int = 0, list: [WalletEarningDetailGroup] = []) {
+        self.totalAmount = totalAmount
+        self.totalPoints = totalPoints
+        self.total = total
+        self.list = list
+    }
+
+    /// 自定义解码，兼容后端字段缺失和类型不稳定。
+    init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        totalAmount = try container.decodeLossyString(forKey: .totalAmount)
+        totalPoints = try container.decodeLossyInt(forKey: .totalPoints) ?? 0
+        total = try container.decodeLossyInt(forKey: .total) ?? 0
+        list = try container.decodeIfPresent([WalletEarningDetailGroup].self, forKey: .list) ?? []
+    }
+}
+
+/// 钱包收益日分组实体，表示某一天的收益、积分和明细。
+struct WalletEarningDetailGroup: Decodable, Equatable, Identifiable {
+    let date: String
+    let dayAmount: String
+    let dayPoints: Int
+    let items: [WalletEarningDetailItem]
+
+    var id: String { date }
+
+    enum CodingKeys: String, CodingKey {
+        case date
+        case dayAmount = "day_amount"
+        case dayPoints = "day_points"
+        case items
+    }
+
+    /// 创建收益日分组实体，主要用于测试替身。
+    init(date: String, dayAmount: String = "0.00", dayPoints: Int = 0, items: [WalletEarningDetailItem] = []) {
+        self.date = date
+        self.dayAmount = dayAmount
+        self.dayPoints = dayPoints
+        self.items = items
+    }
+
+    /// 自定义解码，兼容后端字段缺失和类型不稳定。
+    init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        date = try container.decodeLossyString(forKey: .date)
+        dayAmount = try container.decodeLossyString(forKey: .dayAmount)
+        dayPoints = try container.decodeLossyInt(forKey: .dayPoints) ?? 0
+        items = try container.decodeIfPresent([WalletEarningDetailItem].self, forKey: .items) ?? []
+    }
+}
+
+/// 钱包收益明细实体，表示一笔订单收益或积分来源。
+struct WalletEarningDetailItem: Decodable, Equatable, Identifiable {
+    let id: Int64
+    let amount: String
+    let points: Int
+    let type: Int
+    let typeLabel: String
+    let orderNumberSuffix: String
+    let createdAt: String
+    let withdrawLabel: String?
+    let source: String?
+
+    enum CodingKeys: String, CodingKey {
+        case id
+        case amount
+        case points
+        case type
+        case typeLabel = "type_label"
+        case orderNumberSuffix = "order_number_suffix"
+        case createdAt = "created_at"
+        case withdrawLabel = "withdraw_label"
+        case source
+    }
+
+    /// 自定义解码，兼容字段类型不稳定。
+    init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        id = Int64(try container.decodeLossyInt(forKey: .id) ?? 0)
+        amount = try container.decodeLossyString(forKey: .amount)
+        points = try container.decodeLossyInt(forKey: .points) ?? 0
+        type = try container.decodeLossyInt(forKey: .type) ?? 0
+        typeLabel = try container.decodeLossyString(forKey: .typeLabel)
+        orderNumberSuffix = try container.decodeLossyString(forKey: .orderNumberSuffix)
+        createdAt = try container.decodeLossyString(forKey: .createdAt)
+        withdrawLabel = try container.decodeIfPresent(String.self, forKey: .withdrawLabel)
+        source = try container.decodeIfPresent(String.self, forKey: .source)
+    }
+}
+
+/// 钱包提现记录响应实体，表示提现分页列表。
+struct WalletWithdrawListResponse: Decodable, Equatable {
+    let total: Int
+    let item: [WalletWithdrawRecord]
+
+    enum CodingKeys: String, CodingKey {
+        case total
+        case item
+    }
+
+    /// 创建提现记录响应实体，主要用于测试替身。
+    init(total: Int = 0, item: [WalletWithdrawRecord] = []) {
+        self.total = total
+        self.item = item
+    }
+
+    /// 自定义解码，兼容 total 字段类型不稳定。
+    init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        total = try container.decodeLossyInt(forKey: .total) ?? 0
+        item = try container.decodeIfPresent([WalletWithdrawRecord].self, forKey: .item) ?? []
+    }
+}
+
+/// 钱包提现记录实体，表示一笔提现申请。
+struct WalletWithdrawRecord: Decodable, Equatable, Identifiable {
+    let id: Int64
+    let amount: String
+    let createdAt: String
+    let statusLabel: String
+    let expectedAt: String?
+    let auditTime: String?
+    let completedAt: String?
+
+    enum CodingKeys: String, CodingKey {
+        case id
+        case amount
+        case createdAt = "created_at"
+        case statusLabel = "status_label"
+        case expectedAt = "expected_at"
+        case auditTime = "audit_time"
+        case completedAt = "completed_at"
+    }
+
+    /// 自定义解码，兼容字段类型不稳定。
+    init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        id = Int64(try container.decodeLossyInt(forKey: .id) ?? 0)
+        amount = try container.decodeLossyString(forKey: .amount)
+        createdAt = try container.decodeLossyString(forKey: .createdAt)
+        statusLabel = try container.decodeLossyString(forKey: .statusLabel)
+        expectedAt = try container.decodeIfPresent(String.self, forKey: .expectedAt)
+        auditTime = try container.decodeIfPresent(String.self, forKey: .auditTime)
+        completedAt = try container.decodeIfPresent(String.self, forKey: .completedAt)
+    }
+}
+
+/// 银行卡信息响应实体，包裹当前银行卡资料。
+struct BankCardInfoResponse: Decodable, Equatable {
+    let bankCard: WalletBankCardInfo?
+
+    enum CodingKeys: String, CodingKey {
+        case bankCard = "bank_card"
+    }
+}
+
+/// 钱包银行卡实体，表示银行卡资料和审核状态。
+struct WalletBankCardInfo: Decodable, Equatable, Identifiable {
+    var id: String { cardNumber }
+    let realName: String
+    let bankName: String
+    let branchName: String
+    let cardNumber: String
+    let frontUrl: String?
+    let backUrl: String?
+    let provinceCode: String?
+    let cityCode: String?
+    let rejectReason: String?
+    let auditStatus: Int
+    let auditStatusLabel: String
+
+    enum CodingKeys: String, CodingKey {
+        case realName = "real_name"
+        case bankName = "bank_name"
+        case branchName = "branch_name"
+        case cardNumber = "card_number"
+        case frontUrl = "front_url"
+        case backUrl = "back_url"
+        case provinceCode = "province_code"
+        case cityCode = "city_code"
+        case rejectReason = "reject_reason"
+        case auditStatus = "audit_status"
+        case auditStatusLabel = "audit_status_label"
+    }
+
+    /// 自定义解码，兼容审核状态字段类型不稳定。
+    init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        realName = try container.decodeLossyString(forKey: .realName)
+        bankName = try container.decodeLossyString(forKey: .bankName)
+        branchName = try container.decodeLossyString(forKey: .branchName)
+        cardNumber = try container.decodeLossyString(forKey: .cardNumber)
+        frontUrl = try container.decodeIfPresent(String.self, forKey: .frontUrl)
+        backUrl = try container.decodeIfPresent(String.self, forKey: .backUrl)
+        provinceCode = try container.decodeIfPresent(String.self, forKey: .provinceCode)
+        cityCode = try container.decodeIfPresent(String.self, forKey: .cityCode)
+        rejectReason = try container.decodeIfPresent(String.self, forKey: .rejectReason)
+        auditStatus = try container.decodeLossyInt(forKey: .auditStatus) ?? 0
+        auditStatusLabel = try container.decodeLossyString(forKey: .auditStatusLabel)
+    }
+}
+
+/// 银行列表响应实体，表示可选择银行名称。
+struct BankListResponse: Decodable, Equatable {
+    let banks: [String]
+
+    enum CodingKeys: String, CodingKey {
+        case banks
+    }
+
+    /// 创建银行列表响应实体，主要用于测试替身。
+    init(banks: [String] = []) {
+        self.banks = banks
+    }
+}
+
+/// 省市区节点实体，表示提现银行卡设置中的地区树。
+struct AreaNode: Decodable, Equatable, Identifiable {
+    let id: String
+    let code: String
+    let name: String
+    let children: [AreaNode]
+
+    enum CodingKeys: String, CodingKey {
+        case id
+        case code
+        case name
+        case children
+    }
+
+    /// 自定义解码，兼容 id/code 类型不稳定。
+    init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        code = try container.decodeLossyString(forKey: .code)
+        let rawId = try container.decodeLossyString(forKey: .id).trimmingCharacters(in: .whitespacesAndNewlines)
+        id = rawId.isEmpty ? code : rawId
+        name = try container.decodeLossyString(forKey: .name)
+        children = try container.decodeIfPresent([AreaNode].self, forKey: .children) ?? []
+    }
+}
+
+/// 提现信息响应实体，表示提现上限、手机号和银行卡摘要。
+struct WithdrawInfoResponse: Decodable, Equatable {
+    let amountWithdrawable: String
+    let minWithdrawAmount: String
+    let maxSingleWithdrawAmount: String
+    let maxDailyWithdrawAmount: String
+    let userPhone: String
+    let bankCard: WithdrawBankCardInfo
+    let withdrawInfo: [String]
+
+    enum CodingKeys: String, CodingKey {
+        case amountWithdrawable = "amount_withdrawable"
+        case minWithdrawAmount = "min_withdraw_amount"
+        case maxSingleWithdrawAmount = "max_single_withdraw_amount"
+        case maxDailyWithdrawAmount = "max_daily_withdraw_amount"
+        case userPhone = "user_phone"
+        case bankCard = "bank_card"
+        case withdrawInfo = "withdraw_info"
+    }
+
+    /// 自定义解码，兼容金额字段类型不稳定。
+    init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        amountWithdrawable = try container.decodeLossyString(forKey: .amountWithdrawable)
+        minWithdrawAmount = try container.decodeLossyString(forKey: .minWithdrawAmount)
+        maxSingleWithdrawAmount = try container.decodeLossyString(forKey: .maxSingleWithdrawAmount)
+        maxDailyWithdrawAmount = try container.decodeLossyString(forKey: .maxDailyWithdrawAmount)
+        userPhone = try container.decodeLossyString(forKey: .userPhone)
+        bankCard = try container.decodeIfPresent(WithdrawBankCardInfo.self, forKey: .bankCard) ?? WithdrawBankCardInfo()
+        withdrawInfo = try container.decodeIfPresent([String].self, forKey: .withdrawInfo) ?? []
+    }
+}
+
+/// 提现银行卡摘要实体，表示提现页面展示的银行卡信息。
+struct WithdrawBankCardInfo: Decodable, Equatable {
+    let realName: String
+    let bankName: String
+    let cardNumber: String
+
+    enum CodingKeys: String, CodingKey {
+        case realName = "real_name"
+        case bankName = "bank_name"
+        case cardNumber = "card_number"
+    }
+
+    /// 创建提现银行卡摘要，主要用于空状态兜底。
+    init(realName: String = "", bankName: String = "", cardNumber: String = "") {
+        self.realName = realName
+        self.bankName = bankName
+        self.cardNumber = cardNumber
+    }
+
+    /// 自定义解码，兼容字段类型不稳定。
+    init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        realName = try container.decodeLossyString(forKey: .realName)
+        bankName = try container.decodeLossyString(forKey: .bankName)
+        cardNumber = try container.decodeLossyString(forKey: .cardNumber)
+    }
+}
+
+/// 提现申请请求实体，表示金额和短信验证码。
+struct WithdrawApplyRequest: Encodable {
+    let amount: String
+    let smsCode: String
+
+    enum CodingKeys: String, CodingKey {
+        case amount
+        case smsCode = "sms_code"
+    }
+}
+
+/// 银行卡更新请求实体，表示银行卡资料、证件图片 URL 和验证码。
+struct UpdateBankInfoRequest: Encodable, Equatable {
+    let realName: String
+    let cardNumber: String
+    let bankName: String
+    let branchName: String
+    let frontUrl: String
+    let backUrl: String
+    let provinceCode: String
+    let cityCode: String
+    let smsVerifyCode: String
+
+    enum CodingKeys: String, CodingKey {
+        case realName = "real_name"
+        case cardNumber = "card_number"
+        case bankName = "bank_name"
+        case branchName = "branch_name"
+        case frontUrl = "front_url"
+        case backUrl = "back_url"
+        case provinceCode = "province_code"
+        case cityCode = "city_code"
+        case smsVerifyCode = "sms_verify_code"
+    }
+}
+
+/// 积分概览响应实体，表示当前积分可兑换状态。
+struct PointOverviewResponse: Decodable, Equatable {
+    let totalPoints: Int
+    let availablePoints: Int
+    let withdrawnPoints: Int
+    let pendingPoints: Int
+    let time: String
+
+    enum CodingKeys: String, CodingKey {
+        case totalPoints = "total_points"
+        case availablePoints = "available_points"
+        case withdrawnPoints = "withdrawn_points"
+        case pendingPoints = "pending_points"
+        case time
+    }
+
+    /// 创建积分概览响应实体，主要用于空状态和测试替身。
+    init(totalPoints: Int = 0, availablePoints: Int = 0, withdrawnPoints: Int = 0, pendingPoints: Int = 0, time: String = "") {
+        self.totalPoints = totalPoints
+        self.availablePoints = availablePoints
+        self.withdrawnPoints = withdrawnPoints
+        self.pendingPoints = pendingPoints
+        self.time = time
+    }
+
+    /// 自定义解码，兼容积分字段类型不稳定。
+    init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        totalPoints = try container.decodeLossyInt(forKey: .totalPoints) ?? 0
+        availablePoints = try container.decodeLossyInt(forKey: .availablePoints) ?? 0
+        withdrawnPoints = try container.decodeLossyInt(forKey: .withdrawnPoints) ?? 0
+        pendingPoints = try container.decodeLossyInt(forKey: .pendingPoints) ?? 0
+        time = try container.decodeLossyString(forKey: .time)
+    }
+}
+
+/// 积分兑换申请请求实体。
+struct PointWithdrawApplyRequest: Encodable {
+    let points: Int
+    let remark: String
+}
+
+/// 积分兑换列表请求实体。
+struct PointWithdrawListRequest: Encodable {
+    let status: Int?
+    let page: Int
+    let pageSize: Int
+
+    enum CodingKeys: String, CodingKey {
+        case status
+        case page
+        case pageSize = "page_size"
+    }
+}
+
+/// 积分兑换列表响应实体。
+struct PointWithdrawListResponse: Decodable, Equatable {
+    let total: Int
+    let list: [PointWithdrawItem]
+
+    enum CodingKeys: String, CodingKey {
+        case total
+        case list
+    }
+
+    /// 创建积分兑换列表响应实体，主要用于测试替身。
+    init(total: Int = 0, list: [PointWithdrawItem] = []) {
+        self.total = total
+        self.list = list
+    }
+
+    /// 自定义解码，兼容字段缺失和类型不稳定。
+    init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        total = try container.decodeLossyInt(forKey: .total) ?? 0
+        list = try container.decodeIfPresent([PointWithdrawItem].self, forKey: .list) ?? []
+    }
+}
+
+/// 积分兑换记录实体。
+struct PointWithdrawItem: Decodable, Equatable, Identifiable {
+    let id: Int
+    let points: Int
+    let amount: Double
+    let status: Int
+    let createdAt: String
+
+    enum CodingKeys: String, CodingKey {
+        case id
+        case points
+        case amount
+        case status
+        case createdAt = "created_at"
+    }
+
+    /// 自定义解码，兼容字段类型不稳定。
+    init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        id = try container.decodeLossyInt(forKey: .id) ?? 0
+        points = try container.decodeLossyInt(forKey: .points) ?? 0
+        amount = try container.decodeLossyDouble(forKey: .amount) ?? 0
+        status = try container.decodeLossyInt(forKey: .status) ?? 0
+        createdAt = try container.decodeLossyString(forKey: .createdAt)
+    }
+}
+
+/// 钱包本地路由实体，表示钱包内二级页面。
+enum WalletRoute: Hashable, Identifiable {
+    case withdrawApply
+    case bankCardSettings
+    case pointsRedemption
+    case realNameAuth
+
+    var id: String {
+        switch self {
+        case .withdrawApply: "withdrawApply"
+        case .bankCardSettings: "bankCardSettings"
+        case .pointsRedemption: "pointsRedemption"
+        case .realNameAuth: "realNameAuth"
+        }
+    }
+}
+
+/// 提现资格决策实体，表示点击提现后的下一步页面或提示。
+enum WalletWithdrawDecision: Equatable {
+    case route(WalletRoute)
+    case message(String)
+}
+
+/// 钱包筛选区间实体，表示收益明细查询时间范围。
+enum WalletDateFilter: String, CaseIterable, Identifiable {
+    case last7
+    case last30
+    case last180
+
+    var id: String { rawValue }
+
+    /// 当前筛选区间的展示标题。
+    var title: String {
+        switch self {
+        case .last7: "近7日"
+        case .last30: "近30日"
+        case .last180: "近180日"
+        }
+    }
+
+    /// 根据当前日期计算开始和结束日期。
+    func range(today: Date = Date(), calendar: Calendar = .current) -> (start: String, end: String) {
+        let formatter = DateFormatter()
+        formatter.calendar = calendar
+        formatter.dateFormat = "yyyy-MM-dd"
+        let days: Int
+        switch self {
+        case .last7:
+            days = 6
+        case .last30:
+            days = 29
+        case .last180:
+            days = 179
+        }
+        let startDate = calendar.date(byAdding: .day, value: -days, to: today) ?? today
+        return (formatter.string(from: startDate), formatter.string(from: today))
+    }
+}
+
+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 value.truncatingRemainder(dividingBy: 1) == 0 ? String(Int(value)) : String(value)
+        }
+        return ""
+    }
+
+    /// 将字符串或数字宽松解码为整数。
+    func decodeLossyInt(forKey key: Key) throws -> Int? {
+        if let value = try decodeIfPresent(Int.self, forKey: key) {
+            return value
+        }
+        if let value = try decodeIfPresent(String.self, forKey: key) {
+            let text = value.trimmingCharacters(in: .whitespacesAndNewlines)
+            if let intValue = Int(text) {
+                return intValue
+            }
+            if let doubleValue = Double(text) {
+                return Int(doubleValue)
+            }
+        }
+        if let value = try decodeIfPresent(Double.self, forKey: key) {
+            return Int(value)
+        }
+        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) {
+            return Double(value.trimmingCharacters(in: .whitespacesAndNewlines))
+        }
+        return nil
+    }
+}

suixinkan/Features/Wallet/ViewModels/WalletViewModels.swift

@@ -0,0 +1,538 @@
+//
+//  WalletViewModels.swift
+//  suixinkan
+//
+//  Created by Codex on 2026/6/22.
+//
+
+import Foundation
+import Observation
+
+@MainActor
+/// 钱包实名认证服务协议，抽象实名认证状态读取能力以便测试替换。
+protocol WalletRealNameServing {
+    /// 获取当前登录用户实名认证状态。
+    func realNameInfo() async throws -> RealNameInfoResponse
+}
+
+extension ProfileAPI: WalletRealNameServing {}
+
+/// 钱包首页明细 Tab，区分收益明细和提现记录。
+enum WalletLedgerTab: String, CaseIterable, Identifiable {
+    case earnings
+    case withdraws
+
+    var id: String { rawValue }
+
+    /// Tab 展示标题。
+    var title: String {
+        switch self {
+        case .earnings: "收益明细"
+        case .withdraws: "提现记录"
+        }
+    }
+}
+
+@MainActor
+@Observable
+/// 钱包首页 ViewModel，管理钱包汇总、收益明细、提现记录和提现资格流。
+final class WalletViewModel {
+    var summary: WalletSummaryResponse?
+    var pointsOverview: PointOverviewResponse?
+    var selectedTab: WalletLedgerTab = .earnings
+    var selectedFilter: WalletDateFilter = .last30
+    var earningsGroups: [WalletEarningDetailGroup] = []
+    var withdrawRecords: [WalletWithdrawRecord] = []
+    var isLoadingSummary = false
+    var isLoadingList = false
+    var isCheckingWithdraw = false
+    var errorMessage: String?
+
+    private let pageSize = 20
+    private var earningsPage = 1
+    private var earningsTotal = 0
+    private var withdrawPage = 1
+    private var withdrawTotal = 0
+
+    /// 钱包可提现金额展示文本。
+    var withdrawableText: String {
+        "¥ \(Self.moneyText(summary?.amountWithdrawable))"
+    }
+
+    /// 钱包累计金额展示文本。
+    var totalAmountText: String {
+        "¥ \(Self.moneyText(summary?.amountTotal))"
+    }
+
+    /// 当前余额展示文本。
+    var currentBalanceText: String {
+        "¥ \(Self.moneyText(summary?.amountCurrentBalance))"
+    }
+
+    /// 是否还能继续加载收益明细。
+    var canLoadMoreEarnings: Bool {
+        earningsGroups.flatMap(\.items).count < earningsTotal
+    }
+
+    /// 是否还能继续加载提现记录。
+    var canLoadMoreWithdraws: Bool {
+        withdrawRecords.count < withdrawTotal
+    }
+
+    /// 首次加载钱包首页数据。
+    func loadInitial(api: WalletServing, staffId: Int?) async {
+        isLoadingSummary = true
+        errorMessage = nil
+        async let summaryResult = api.walletSummary(type: 0)
+        async let pointsResult: PointOverviewResponse? = {
+            guard let staffId else { return nil }
+            return try? await api.pointOverview(staffId: staffId)
+        }()
+
+        do {
+            summary = try await summaryResult
+            pointsOverview = await pointsResult
+        } catch {
+            errorMessage = error.localizedDescription
+        }
+        isLoadingSummary = false
+        await reloadList(api: api)
+    }
+
+    /// 按当前 Tab 和筛选条件刷新列表。
+    func reloadList(api: WalletServing) async {
+        switch selectedTab {
+        case .earnings:
+            earningsPage = 1
+            await loadEarnings(api: api, reset: true)
+        case .withdraws:
+            withdrawPage = 1
+            await loadWithdraws(api: api, reset: true)
+        }
+    }
+
+    /// 切换钱包明细 Tab 并刷新对应列表。
+    func selectTab(_ tab: WalletLedgerTab, api: WalletServing) async {
+        guard selectedTab != tab else { return }
+        selectedTab = tab
+        await reloadList(api: api)
+    }
+
+    /// 切换收益明细时间筛选并重置分页。
+    func selectFilter(_ filter: WalletDateFilter, api: WalletServing) async {
+        guard selectedFilter != filter else { return }
+        selectedFilter = filter
+        if selectedTab == .earnings {
+            await reloadList(api: api)
+        }
+    }
+
+    /// 加载下一页当前列表。
+    func loadMore(api: WalletServing) async {
+        switch selectedTab {
+        case .earnings where canLoadMoreEarnings:
+            earningsPage += 1
+            await loadEarnings(api: api, reset: false)
+        case .withdraws where canLoadMoreWithdraws:
+            withdrawPage += 1
+            await loadWithdraws(api: api, reset: false)
+        default:
+            break
+        }
+    }
+
+    /// 根据实名认证和银行卡状态决定提现下一步。
+    func resolveWithdrawDecision(profileAPI: WalletRealNameServing, walletAPI: WalletServing) async -> WalletWithdrawDecision {
+        isCheckingWithdraw = true
+        defer { isCheckingWithdraw = false }
+
+        do {
+            let realName = try await profileAPI.realNameInfo().realNameInfo
+            guard let realName else {
+                return .route(.realNameAuth)
+            }
+            switch realName.auditStatus {
+            case 2:
+                let bankCard = try await walletAPI.bankCardInfo().bankCard
+                guard let bankCard else {
+                    return .route(.bankCardSettings)
+                }
+                if bankCard.auditStatus == 2 {
+                    return .route(.withdrawApply)
+                }
+                if bankCard.auditStatus == 3 {
+                    return .route(.bankCardSettings)
+                }
+                return .message("银行卡审核中，请审核通过后再试")
+            case 3:
+                return .route(.realNameAuth)
+            default:
+                return .message("实名认证审核中，请审核通过后再试")
+            }
+        } catch {
+            return .message(error.localizedDescription)
+        }
+    }
+
+    /// 加载收益明细分页。
+    private func loadEarnings(api: WalletServing, reset: Bool) async {
+        isLoadingList = true
+        errorMessage = nil
+        defer { isLoadingList = false }
+
+        let range = selectedFilter.range()
+        do {
+            let response = try await api.walletEarningDetail(
+                startDate: range.start,
+                endDate: range.end,
+                page: earningsPage,
+                pageSize: pageSize
+            )
+            earningsTotal = response.total
+            earningsGroups = reset ? response.list : earningsGroups + response.list
+        } catch {
+            if !reset { earningsPage = max(1, earningsPage - 1) }
+            if reset { earningsGroups = [] }
+            errorMessage = error.localizedDescription
+        }
+    }
+
+    /// 加载提现记录分页。
+    private func loadWithdraws(api: WalletServing, reset: Bool) async {
+        isLoadingList = true
+        errorMessage = nil
+        defer { isLoadingList = false }
+
+        do {
+            let response = try await api.walletWithdrawList(page: withdrawPage, pageSize: pageSize)
+            withdrawTotal = response.total
+            withdrawRecords = reset ? response.item : withdrawRecords + response.item
+        } catch {
+            if !reset { withdrawPage = max(1, withdrawPage - 1) }
+            if reset { withdrawRecords = [] }
+            errorMessage = error.localizedDescription
+        }
+    }
+
+    /// 规范金额展示，空值按 0.00 处理。
+    static func moneyText(_ rawValue: String?) -> String {
+        let text = rawValue?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        guard let decimal = Decimal(string: text), decimal > 0 else {
+            return "0.00"
+        }
+        return NSDecimalNumber(decimal: decimal).stringValue
+    }
+}
+
+@MainActor
+@Observable
+/// 提现申请 ViewModel，管理提现信息、金额校验、短信验证码和提交。
+final class WithdrawApplyViewModel {
+    var info: WithdrawInfoResponse?
+    var amountText = ""
+    var smsCode = ""
+    var isLoading = false
+    var isSubmitting = false
+    var smsCountdown = 0
+    var errorMessage: String?
+
+    /// 加载提现申请所需信息。
+    func load(api: WalletServing) async {
+        isLoading = true
+        errorMessage = nil
+        defer { isLoading = false }
+        do {
+            info = try await api.withdrawInfo()
+        } catch {
+            errorMessage = error.localizedDescription
+        }
+    }
+
+    /// 发送提现短信验证码。
+    func sendSms(api: WalletServing) async {
+        guard smsCountdown == 0 else { return }
+        do {
+            try await api.withdrawSendSms()
+            smsCountdown = 60
+        } catch {
+            errorMessage = error.localizedDescription
+        }
+    }
+
+    /// 提交提现申请，成功后清空表单。
+    func submit(api: WalletServing) async -> Bool {
+        guard !isSubmitting else { return false }
+        guard let amount = PaymentCollectionViewModel.normalizedMoney(amountText) else {
+            errorMessage = "请输入有效提现金额"
+            return false
+        }
+        guard let info else {
+            errorMessage = "提现信息未加载"
+            return false
+        }
+        guard (Decimal(string: amount) ?? 0) <= (Decimal(string: info.amountWithdrawable) ?? 0) else {
+            errorMessage = "提现金额不能超过可提现金额"
+            return false
+        }
+        guard !smsCode.walletTrimmed.isEmpty else {
+            errorMessage = "请输入短信验证码"
+            return false
+        }
+
+        isSubmitting = true
+        defer { isSubmitting = false }
+        do {
+            try await api.withdrawApply(amount: amount, smsCode: smsCode.walletTrimmed)
+            amountText = ""
+            smsCode = ""
+            return true
+        } catch {
+            errorMessage = error.localizedDescription
+            return false
+        }
+    }
+}
+
+@MainActor
+@Observable
+/// 银行卡设置 ViewModel，管理银行卡表单、图片上传、短信验证码和提交。
+final class WithdrawalSettingsViewModel {
+    var bankCard: WalletBankCardInfo?
+    var banks: [String] = []
+    var areas: [AreaNode] = []
+    var realName = ""
+    var cardNumber = ""
+    var bankName = ""
+    var branchName = ""
+    var provinceCode = ""
+    var cityCode = ""
+    var smsCode = ""
+    var frontImageData: Data?
+    var backImageData: Data?
+    var frontImageURL = ""
+    var backImageURL = ""
+    var uploadProgress = 0
+    var isLoading = false
+    var isSubmitting = false
+    var smsCountdown = 0
+    var errorMessage: String?
+
+    /// 加载银行卡设置需要的银行、地区和已提交资料。
+    func load(api: WalletServing) async {
+        isLoading = true
+        errorMessage = nil
+        defer { isLoading = false }
+        async let bankCardResult = api.bankCardInfo()
+        async let bankListResult = api.bankList()
+        async let areaResult = api.areas()
+        do {
+            let (cardResponse, bankResponse, areaResponse) = try await (bankCardResult, bankListResult, areaResult)
+            bankCard = cardResponse.bankCard
+            banks = bankResponse.banks
+            areas = areaResponse
+            apply(cardResponse.bankCard)
+        } catch {
+            errorMessage = error.localizedDescription
+        }
+    }
+
+    /// 发送银行卡设置短信验证码。
+    func sendSms(api: WalletServing) async {
+        guard smsCountdown == 0 else { return }
+        do {
+            try await api.bankCardVerifyCode()
+            smsCountdown = 60
+        } catch {
+            errorMessage = error.localizedDescription
+        }
+    }
+
+    /// 上传图片并提交银行卡资料。
+    func submit(api: WalletServing, uploader: OSSUploadServing, scenicId: Int?) async -> Bool {
+        guard !isSubmitting else { return false }
+        guard let scenicId else {
+            errorMessage = "请先选择景区"
+            return false
+        }
+        guard validateForm() else { return false }
+
+        isSubmitting = true
+        uploadProgress = 0
+        defer { isSubmitting = false }
+
+        do {
+            let frontURL = try await resolvedImageURL(
+                currentURL: frontImageURL,
+                data: frontImageData,
+                fileName: "bank_card_front.jpg",
+                uploader: uploader,
+                scenicId: scenicId
+            )
+            let backURL = try await resolvedImageURL(
+                currentURL: backImageURL,
+                data: backImageData,
+                fileName: "bank_card_back.jpg",
+                uploader: uploader,
+                scenicId: scenicId
+            )
+            let request = UpdateBankInfoRequest(
+                realName: realName.walletTrimmed,
+                cardNumber: cardNumber.walletTrimmed,
+                bankName: bankName.walletTrimmed,
+                branchName: branchName.walletTrimmed,
+                frontUrl: frontURL,
+                backUrl: backURL,
+                provinceCode: provinceCode.walletTrimmed,
+                cityCode: cityCode.walletTrimmed,
+                smsVerifyCode: smsCode.walletTrimmed
+            )
+            try await api.updateBankInfo(request)
+            frontImageURL = frontURL
+            backImageURL = backURL
+            frontImageData = nil
+            backImageData = nil
+            return true
+        } catch {
+            errorMessage = error.localizedDescription
+            return false
+        }
+    }
+
+    /// 将已有银行卡资料回填到表单。
+    private func apply(_ info: WalletBankCardInfo?) {
+        guard let info else { return }
+        realName = info.realName
+        cardNumber = info.cardNumber
+        bankName = info.bankName
+        branchName = info.branchName
+        provinceCode = info.provinceCode ?? ""
+        cityCode = info.cityCode ?? ""
+        frontImageURL = info.frontUrl ?? ""
+        backImageURL = info.backUrl ?? ""
+    }
+
+    /// 校验银行卡表单必填项。
+    private func validateForm() -> Bool {
+        if realName.walletTrimmed.isEmpty { errorMessage = "请输入持卡人姓名"; return false }
+        if cardNumber.walletTrimmed.isEmpty { errorMessage = "请输入银行卡号"; return false }
+        if bankName.walletTrimmed.isEmpty { errorMessage = "请选择开户银行"; return false }
+        if branchName.walletTrimmed.isEmpty { errorMessage = "请输入开户支行"; return false }
+        if provinceCode.walletTrimmed.isEmpty || cityCode.walletTrimmed.isEmpty { errorMessage = "请选择开户地区"; return false }
+        if frontImageURL.walletTrimmed.isEmpty && frontImageData == nil { errorMessage = "请选择银行卡正面照片"; return false }
+        if backImageURL.walletTrimmed.isEmpty && backImageData == nil { errorMessage = "请选择银行卡反面照片"; return false }
+        if smsCode.walletTrimmed.isEmpty { errorMessage = "请输入短信验证码"; return false }
+        return true
+    }
+
+    /// 返回最终图片 URL，本地选择的新图会先上传 OSS。
+    private func resolvedImageURL(
+        currentURL: String,
+        data: Data?,
+        fileName: String,
+        uploader: OSSUploadServing,
+        scenicId: Int
+    ) async throws -> String {
+        guard let data else { return currentURL }
+        return try await uploader.uploadBankCardImage(data: data, fileName: fileName, scenicId: scenicId) { [weak self] progress in
+            self?.uploadProgress = progress
+        }
+    }
+}
+
+@MainActor
+@Observable
+/// 积分兑换 ViewModel，管理积分概览、兑换记录、兑换金额校验和提交。
+final class PointsRedemptionViewModel {
+    var overview = PointOverviewResponse()
+    var records: [PointWithdrawItem] = []
+    var pointsText = ""
+    var isLoading = false
+    var isSubmitting = false
+    var errorMessage: String?
+
+    private let pageSize = 20
+    private var page = 1
+    private var total = 0
+
+    /// 是否还能继续加载兑换记录。
+    var canLoadMore: Bool {
+        records.count < total
+    }
+
+    /// 加载积分概览和兑换记录。
+    func load(api: WalletServing, staffId: Int?) async {
+        guard let staffId else {
+            errorMessage = "缺少账号信息"
+            return
+        }
+        isLoading = true
+        errorMessage = nil
+        page = 1
+        defer { isLoading = false }
+        do {
+            async let overviewResult = api.pointOverview(staffId: staffId)
+            async let listResult = api.pointWithdrawList(status: nil, page: page, pageSize: pageSize)
+            overview = try await overviewResult
+            let list = try await listResult
+            total = list.total
+            records = list.list
+        } catch {
+            errorMessage = error.localizedDescription
+        }
+    }
+
+    /// 加载下一页积分兑换记录。
+    func loadMore(api: WalletServing) async {
+        guard canLoadMore else { return }
+        page += 1
+        do {
+            let response = try await api.pointWithdrawList(status: nil, page: page, pageSize: pageSize)
+            total = response.total
+            records += response.list
+        } catch {
+            page = max(1, page - 1)
+            errorMessage = error.localizedDescription
+        }
+    }
+
+    /// 将可兑换积分全部填入表单。
+    func fillAllPoints() {
+        pointsText = String(overview.withdrawnPoints)
+    }
+
+    /// 提交积分兑换申请，成功后刷新概览和列表。
+    func submit(api: WalletServing, staffId: Int?) async -> Bool {
+        guard !isSubmitting else { return false }
+        guard let points = Int(pointsText.walletTrimmed), points > 0 else {
+            errorMessage = "请输入有效兑换积分"
+            return false
+        }
+        guard points <= overview.withdrawnPoints else {
+            errorMessage = "兑换积分不能超过可兑换积分"
+            return false
+        }
+        guard let staffId else {
+            errorMessage = "缺少账号信息"
+            return false
+        }
+
+        isSubmitting = true
+        defer { isSubmitting = false }
+        do {
+            try await api.pointWithdrawApply(points: points, remark: "积分提现申请")
+            pointsText = ""
+            await load(api: api, staffId: staffId)
+            return true
+        } catch {
+            errorMessage = error.localizedDescription
+            return false
+        }
+    }
+}
+
+private extension String {
+    /// 钱包模块内部使用的去空白文本，避免依赖其他文件的 fileprivate 扩展。
+    var walletTrimmed: String {
+        trimmingCharacters(in: .whitespacesAndNewlines)
+    }
+}

suixinkan/Features/Wallet/Views/WalletView.swift

@@ -0,0 +1,531 @@
+//
+//  WalletView.swift
+//  suixinkan
+//
+//  Created by Codex on 2026/6/22.
+//
+
+import Combine
+import PhotosUI
+import SwiftUI
+
+/// 钱包首页，展示钱包汇总、收益明细、提现记录和钱包二级入口。
+struct WalletView: View {
+    @Environment(AccountContext.self) private var accountContext
+    @Environment(WalletAPI.self) private var walletAPI
+    @Environment(ProfileAPI.self) private var profileAPI
+    @Environment(ToastCenter.self) private var toastCenter
+
+    @State private var viewModel = WalletViewModel()
+    @State private var route: WalletRoute?
+
+    var body: some View {
+        ScrollView {
+            VStack(spacing: AppMetrics.Spacing.medium) {
+                summaryCard
+                walletActions
+                ledgerControls
+                ledgerList
+            }
+            .padding(.horizontal, AppMetrics.Spacing.pageHorizontal)
+            .padding(.vertical, AppMetrics.Spacing.pageVertical)
+        }
+        .background(Color(hex: 0xF5F7FA))
+        .navigationTitle("我的钱包")
+        .navigationBarTitleDisplayMode(.inline)
+        .navigationDestination(item: $route) { route in
+            switch route {
+            case .withdrawApply:
+                WithdrawApplyView()
+            case .bankCardSettings:
+                WithdrawalSettingsView()
+            case .pointsRedemption:
+                PointsRedemptionView()
+            case .realNameAuth:
+                RealNameAuthView()
+            }
+        }
+        .task {
+            await viewModel.loadInitial(api: walletAPI, staffId: staffId)
+        }
+        .refreshable {
+            await viewModel.loadInitial(api: walletAPI, staffId: staffId)
+        }
+        .onChange(of: viewModel.errorMessage) { _, message in
+            if let message {
+                toastCenter.show(message)
+            }
+        }
+    }
+
+    /// 当前用户 staffId，优先使用账号快照里的 userId。
+    private var staffId: Int? {
+        Int(accountContext.profile?.userId ?? "")
+    }
+
+    /// 钱包汇总卡片。
+    private var summaryCard: some View {
+        VStack(alignment: .leading, spacing: AppMetrics.Spacing.medium) {
+            HStack {
+                VStack(alignment: .leading, spacing: AppMetrics.Spacing.xxSmall) {
+                    Text("可提现金额")
+                        .font(.system(size: AppMetrics.FontSize.subheadline))
+                        .foregroundStyle(.white.opacity(0.86))
+                    Text(viewModel.withdrawableText)
+                        .font(.system(size: AppMetrics.FontSize.largeTitle, weight: .bold))
+                        .foregroundStyle(.white)
+                }
+                Spacer()
+                if viewModel.isLoadingSummary {
+                    ProgressView()
+                        .tint(.white)
+                }
+            }
+
+            HStack(spacing: AppMetrics.Spacing.medium) {
+                walletSummaryItem(title: "累计金额", value: viewModel.totalAmountText)
+                walletSummaryItem(title: "当前余额", value: viewModel.currentBalanceText)
+                walletSummaryItem(title: "可兑换积分", value: "\(viewModel.pointsOverview?.withdrawnPoints ?? 0)")
+            }
+        }
+        .padding(AppMetrics.Spacing.large)
+        .background(AppDesign.primary, in: RoundedRectangle(cornerRadius: 8))
+    }
+
+    /// 钱包快捷操作。
+    private var walletActions: some View {
+        HStack(spacing: AppMetrics.Spacing.small) {
+            walletActionButton(title: "提现", icon: "banknote") {
+                Task {
+                    let decision = await viewModel.resolveWithdrawDecision(profileAPI: profileAPI, walletAPI: walletAPI)
+                    switch decision {
+                    case .route(let nextRoute):
+                        route = nextRoute
+                    case .message(let message):
+                        toastCenter.show(message)
+                    }
+                }
+            }
+            walletActionButton(title: "银行卡", icon: "creditcard") {
+                route = .bankCardSettings
+            }
+            walletActionButton(title: "积分兑换", icon: "giftcard") {
+                route = .pointsRedemption
+            }
+        }
+    }
+
+    /// 明细筛选控件。
+    private var ledgerControls: some View {
+        VStack(spacing: AppMetrics.Spacing.small) {
+            Picker("明细类型", selection: Binding(
+                get: { viewModel.selectedTab },
+                set: { tab in Task { await viewModel.selectTab(tab, api: walletAPI) } }
+            )) {
+                ForEach(WalletLedgerTab.allCases) { tab in
+                    Text(tab.title).tag(tab)
+                }
+            }
+            .pickerStyle(.segmented)
+
+            if viewModel.selectedTab == .earnings {
+                HStack {
+                    ForEach(WalletDateFilter.allCases) { filter in
+                        Button {
+                            Task { await viewModel.selectFilter(filter, api: walletAPI) }
+                        } label: {
+                            Text(filter.title)
+                                .font(.system(size: AppMetrics.FontSize.footnote, weight: .medium))
+                                .foregroundStyle(viewModel.selectedFilter == filter ? .white : AppDesign.primary)
+                                .padding(.horizontal, AppMetrics.Spacing.small)
+                                .padding(.vertical, AppMetrics.Spacing.xSmall)
+                                .background(viewModel.selectedFilter == filter ? AppDesign.primary : AppDesign.primarySoft, in: Capsule())
+                        }
+                    }
+                    Spacer()
+                }
+            }
+        }
+        .padding(AppMetrics.Spacing.medium)
+        .background(.white, in: RoundedRectangle(cornerRadius: 8))
+    }
+
+    /// 钱包明细列表。
+    @ViewBuilder
+    private var ledgerList: some View {
+        if viewModel.selectedTab == .earnings {
+            LazyVStack(spacing: AppMetrics.Spacing.small) {
+                ForEach(viewModel.earningsGroups) { group in
+                    walletSection(title: group.date, subtitle: "¥\(group.dayAmount) / \(group.dayPoints)分") {
+                        ForEach(group.items) { item in
+                            ledgerRow(title: item.typeLabel.isEmpty ? "收益" : item.typeLabel, subtitle: item.createdAt, amount: "+¥\(item.amount)", extra: item.orderNumberSuffix)
+                        }
+                    }
+                }
+                loadMoreButton(enabled: viewModel.canLoadMoreEarnings)
+            }
+        } else {
+            LazyVStack(spacing: AppMetrics.Spacing.small) {
+                ForEach(viewModel.withdrawRecords) { record in
+                    ledgerRow(title: record.statusLabel, subtitle: record.createdAt, amount: "-¥\(record.amount)", extra: record.expectedAt ?? "")
+                        .padding(AppMetrics.Spacing.medium)
+                        .background(.white, in: RoundedRectangle(cornerRadius: 8))
+                }
+                loadMoreButton(enabled: viewModel.canLoadMoreWithdraws)
+            }
+        }
+    }
+
+    /// 汇总子项。
+    private func walletSummaryItem(title: String, value: String) -> some View {
+        VStack(alignment: .leading, spacing: AppMetrics.Spacing.xxxSmall) {
+            Text(title)
+                .font(.system(size: AppMetrics.FontSize.caption))
+                .foregroundStyle(.white.opacity(0.75))
+            Text(value)
+                .font(.system(size: AppMetrics.FontSize.subheadline, weight: .semibold))
+                .foregroundStyle(.white)
+        }
+        .frame(maxWidth: .infinity, alignment: .leading)
+    }
+
+    /// 快捷操作按钮。
+    private func walletActionButton(title: String, icon: String, action: @escaping () -> Void) -> some View {
+        Button(action: action) {
+            VStack(spacing: AppMetrics.Spacing.xSmall) {
+                Image(systemName: icon)
+                    .font(.system(size: 22, weight: .semibold))
+                Text(title)
+                    .font(.system(size: AppMetrics.FontSize.footnote, weight: .medium))
+            }
+            .foregroundStyle(AppDesign.primary)
+            .frame(maxWidth: .infinity, minHeight: 76)
+            .background(.white, in: RoundedRectangle(cornerRadius: 8))
+        }
+    }
+
+    /// 白色分组卡片。
+    private func walletSection<Content: View>(title: String, subtitle: String, @ViewBuilder content: () -> Content) -> some View {
+        VStack(alignment: .leading, spacing: AppMetrics.Spacing.small) {
+            HStack {
+                Text(title)
+                    .font(.system(size: AppMetrics.FontSize.subheadline, weight: .semibold))
+                Spacer()
+                Text(subtitle)
+                    .font(.system(size: AppMetrics.FontSize.caption))
+                    .foregroundStyle(AppDesign.textSecondary)
+            }
+            content()
+        }
+        .padding(AppMetrics.Spacing.medium)
+        .background(.white, in: RoundedRectangle(cornerRadius: 8))
+    }
+
+    /// 明细行。
+    private func ledgerRow(title: String, subtitle: String, amount: String, extra: String) -> some View {
+        HStack(alignment: .top) {
+            VStack(alignment: .leading, spacing: AppMetrics.Spacing.xxxSmall) {
+                Text(title)
+                    .font(.system(size: AppMetrics.FontSize.subheadline, weight: .semibold))
+                    .foregroundStyle(AppDesign.textPrimary)
+                Text([subtitle, extra].filter { !$0.isEmpty }.joined(separator: " · "))
+                    .font(.system(size: AppMetrics.FontSize.caption))
+                    .foregroundStyle(AppDesign.textSecondary)
+            }
+            Spacer()
+            Text(amount)
+                .font(.system(size: AppMetrics.FontSize.subheadline, weight: .semibold))
+                .foregroundStyle(amount.hasPrefix("+") ? AppDesign.success : AppDesign.textPrimary)
+        }
+    }
+
+    /// 加载更多按钮。
+    @ViewBuilder
+    private func loadMoreButton(enabled: Bool) -> some View {
+        if enabled {
+            Button {
+                Task { await viewModel.loadMore(api: walletAPI) }
+            } label: {
+                Text(viewModel.isLoadingList ? "加载中..." : "加载更多")
+                    .font(.system(size: AppMetrics.FontSize.subheadline, weight: .medium))
+                    .frame(maxWidth: .infinity, minHeight: 44)
+            }
+        }
+    }
+}
+
+/// 提现申请页，输入金额和短信验证码后提交提现。
+struct WithdrawApplyView: View {
+    @Environment(WalletAPI.self) private var walletAPI
+    @Environment(ToastCenter.self) private var toastCenter
+    @Environment(\.dismiss) private var dismiss
+    @State private var viewModel = WithdrawApplyViewModel()
+
+    var body: some View {
+        Form {
+            if let info = viewModel.info {
+                Section("银行卡") {
+                    Text("\(info.bankCard.bankName) \(info.bankCard.cardNumber)")
+                    Text("可提现金额：¥\(WalletViewModel.moneyText(info.amountWithdrawable))")
+                }
+            }
+
+            Section("提现金额") {
+                TextField("请输入提现金额", text: $viewModel.amountText)
+                    .keyboardType(.decimalPad)
+                HStack {
+                    TextField("短信验证码", text: $viewModel.smsCode)
+                        .keyboardType(.numberPad)
+                    Button(viewModel.smsCountdown > 0 ? "\(viewModel.smsCountdown)s" : "获取验证码") {
+                        Task { await viewModel.sendSms(api: walletAPI) }
+                    }
+                    .disabled(viewModel.smsCountdown > 0)
+                }
+            }
+
+            Button(viewModel.isSubmitting ? "提交中..." : "提交提现申请") {
+                Task {
+                    if await viewModel.submit(api: walletAPI) {
+                        toastCenter.show("提现申请已提交")
+                        dismiss()
+                    }
+                }
+            }
+            .disabled(viewModel.isSubmitting)
+        }
+        .navigationTitle("提现申请")
+        .navigationBarTitleDisplayMode(.inline)
+        .task { await viewModel.load(api: walletAPI) }
+        .onReceive(Timer.publish(every: 1, on: .main, in: .common).autoconnect()) { _ in
+            if viewModel.smsCountdown > 0 {
+                viewModel.smsCountdown -= 1
+            }
+        }
+        .onChange(of: viewModel.errorMessage) { _, message in
+            if let message {
+                toastCenter.show(message)
+            }
+        }
+    }
+}
+
+/// 银行卡设置页，使用图片选择和 OSS 上传提交银行卡资料。
+struct WithdrawalSettingsView: View {
+    @Environment(AccountContext.self) private var accountContext
+    @Environment(WalletAPI.self) private var walletAPI
+    @Environment(OSSUploadService.self) private var ossUploadService
+    @Environment(ToastCenter.self) private var toastCenter
+    @Environment(\.dismiss) private var dismiss
+
+    @State private var viewModel = WithdrawalSettingsViewModel()
+    @State private var frontItem: PhotosPickerItem?
+    @State private var backItem: PhotosPickerItem?
+
+    var body: some View {
+        Form {
+            if let bankCard = viewModel.bankCard {
+                Section("审核状态") {
+                    Text(bankCard.auditStatusLabel.isEmpty ? "待提交" : bankCard.auditStatusLabel)
+                    if let reason = bankCard.rejectReason, !reason.isEmpty {
+                        Text(reason).foregroundStyle(AppDesign.warning)
+                    }
+                }
+            }
+
+            Section("基础信息") {
+                TextField("持卡人姓名", text: $viewModel.realName)
+                TextField("银行卡号", text: $viewModel.cardNumber)
+                    .keyboardType(.numberPad)
+                Picker("开户银行", selection: $viewModel.bankName) {
+                    Text("请选择").tag("")
+                    ForEach(viewModel.banks, id: \.self) { bank in
+                        Text(bank).tag(bank)
+                    }
+                }
+                TextField("开户支行", text: $viewModel.branchName)
+                Picker("省份", selection: $viewModel.provinceCode) {
+                    Text("请选择").tag("")
+                    ForEach(viewModel.areas) { area in
+                        Text(area.name).tag(area.code)
+                    }
+                }
+                Picker("城市", selection: $viewModel.cityCode) {
+                    Text("请选择").tag("")
+                    ForEach(selectedProvinceChildren) { city in
+                        Text(city.name).tag(city.code)
+                    }
+                }
+            }
+
+            Section("银行卡照片") {
+                bankCardImagePicker(title: "银行卡正面", item: $frontItem, data: viewModel.frontImageData, url: viewModel.frontImageURL)
+                bankCardImagePicker(title: "银行卡反面", item: $backItem, data: viewModel.backImageData, url: viewModel.backImageURL)
+                if viewModel.uploadProgress > 0 && viewModel.uploadProgress < 100 {
+                    ProgressView(value: Double(viewModel.uploadProgress), total: 100)
+                }
+            }
+
+            Section("短信验证码") {
+                HStack {
+                    TextField("请输入短信验证码", text: $viewModel.smsCode)
+                        .keyboardType(.numberPad)
+                    Button(viewModel.smsCountdown > 0 ? "\(viewModel.smsCountdown)s" : "获取验证码") {
+                        Task { await viewModel.sendSms(api: walletAPI) }
+                    }
+                    .disabled(viewModel.smsCountdown > 0)
+                }
+            }
+
+            Button(viewModel.isSubmitting ? "提交中..." : "提交银行卡资料") {
+                Task {
+                    if await viewModel.submit(api: walletAPI, uploader: ossUploadService, scenicId: accountContext.currentScenic?.id) {
+                        toastCenter.show("银行卡资料已提交")
+                        dismiss()
+                    }
+                }
+            }
+            .disabled(viewModel.isSubmitting)
+        }
+        .navigationTitle("银行卡设置")
+        .navigationBarTitleDisplayMode(.inline)
+        .task { await viewModel.load(api: walletAPI) }
+        .onChange(of: frontItem) { _, item in
+            Task { viewModel.frontImageData = try? await item?.loadTransferable(type: Data.self) }
+        }
+        .onChange(of: backItem) { _, item in
+            Task { viewModel.backImageData = try? await item?.loadTransferable(type: Data.self) }
+        }
+        .onReceive(Timer.publish(every: 1, on: .main, in: .common).autoconnect()) { _ in
+            if viewModel.smsCountdown > 0 {
+                viewModel.smsCountdown -= 1
+            }
+        }
+        .onChange(of: viewModel.errorMessage) { _, message in
+            if let message {
+                toastCenter.show(message)
+            }
+        }
+    }
+
+    /// 当前所选省份下的城市列表。
+    private var selectedProvinceChildren: [AreaNode] {
+        viewModel.areas.first { $0.code == viewModel.provinceCode }?.children ?? []
+    }
+
+    /// 银行卡图片选择行。
+    private func bankCardImagePicker(title: String, item: Binding<PhotosPickerItem?>, data: Data?, url: String) -> some View {
+        PhotosPicker(selection: item, matching: .images) {
+            HStack(spacing: AppMetrics.Spacing.small) {
+                bankCardPreview(data: data, url: url)
+                    .frame(width: 88, height: 56)
+                    .clipShape(RoundedRectangle(cornerRadius: 8))
+                Text(title)
+                Spacer()
+                Image(systemName: "chevron.right")
+                    .foregroundStyle(AppDesign.placeholder)
+            }
+        }
+    }
+
+    /// 银行卡图片预览。
+    @ViewBuilder
+    private func bankCardPreview(data: Data?, url: String) -> some View {
+        if let data, let image = UIImage(data: data) {
+            Image(uiImage: image)
+                .resizable()
+                .scaledToFill()
+        } else {
+            RemoteImage(urlString: url) {
+                Rectangle()
+                    .fill(AppDesign.primarySoft)
+                    .overlay {
+                        Image(systemName: "creditcard")
+                            .foregroundStyle(AppDesign.primary)
+                    }
+            }
+        }
+    }
+}
+
+/// 积分兑换页，展示积分概览、提交兑换申请和兑换记录。
+struct PointsRedemptionView: View {
+    @Environment(AccountContext.self) private var accountContext
+    @Environment(WalletAPI.self) private var walletAPI
+    @Environment(ToastCenter.self) private var toastCenter
+    @State private var viewModel = PointsRedemptionViewModel()
+
+    var body: some View {
+        ScrollView {
+            VStack(spacing: AppMetrics.Spacing.medium) {
+                VStack(alignment: .leading, spacing: AppMetrics.Spacing.small) {
+                    Text("可兑换积分")
+                        .font(.system(size: AppMetrics.FontSize.subheadline))
+                        .foregroundStyle(AppDesign.textSecondary)
+                    Text("\(viewModel.overview.withdrawnPoints)")
+                        .font(.system(size: AppMetrics.FontSize.largeTitle, weight: .bold))
+                        .foregroundStyle(AppDesign.textPrimary)
+                    HStack {
+                        TextField("请输入兑换积分", text: $viewModel.pointsText)
+                            .keyboardType(.numberPad)
+                        Button("全部") {
+                            viewModel.fillAllPoints()
+                        }
+                    }
+                    .appInputFieldStyle(cornerRadius: 8, minHeight: AppMetrics.ControlSize.inputHeight)
+                    Button(viewModel.isSubmitting ? "提交中..." : "提交兑换") {
+                        Task {
+                            if await viewModel.submit(api: walletAPI, staffId: staffId) {
+                                toastCenter.show("积分兑换申请已提交")
+                            }
+                        }
+                    }
+                    .frame(maxWidth: .infinity, minHeight: AppMetrics.ControlSize.primaryButtonHeight)
+                    .foregroundStyle(.white)
+                    .background(AppDesign.primary, in: RoundedRectangle(cornerRadius: 8))
+                }
+                .padding(AppMetrics.Spacing.medium)
+                .background(.white, in: RoundedRectangle(cornerRadius: 8))
+
+                LazyVStack(spacing: AppMetrics.Spacing.small) {
+                    ForEach(viewModel.records) { item in
+                        HStack {
+                            VStack(alignment: .leading, spacing: AppMetrics.Spacing.xxxSmall) {
+                                Text("\(item.points) 积分")
+                                    .font(.system(size: AppMetrics.FontSize.subheadline, weight: .semibold))
+                                Text(item.createdAt)
+                                    .font(.system(size: AppMetrics.FontSize.caption))
+                                    .foregroundStyle(AppDesign.textSecondary)
+                            }
+                            Spacer()
+                            Text("¥\(item.amount, specifier: "%.2f")")
+                                .font(.system(size: AppMetrics.FontSize.subheadline, weight: .semibold))
+                        }
+                        .padding(AppMetrics.Spacing.medium)
+                        .background(.white, in: RoundedRectangle(cornerRadius: 8))
+                    }
+                    if viewModel.canLoadMore {
+                        Button("加载更多") {
+                            Task { await viewModel.loadMore(api: walletAPI) }
+                        }
+                    }
+                }
+            }
+            .padding(.horizontal, AppMetrics.Spacing.pageHorizontal)
+            .padding(.vertical, AppMetrics.Spacing.pageVertical)
+        }
+        .background(Color(hex: 0xF5F7FA))
+        .navigationTitle("积分兑换")
+        .navigationBarTitleDisplayMode(.inline)
+        .task { await viewModel.load(api: walletAPI, staffId: staffId) }
+        .onChange(of: viewModel.errorMessage) { _, message in
+            if let message {
+                toastCenter.show(message)
+            }
+        }
+    }
+
+    /// 当前用户 staffId。
+    private var staffId: Int? {
+        Int(accountContext.profile?.userId ?? "")
+    }
+}

suixinkan/Features/Wallet/Wallet.md

@@ -0,0 +1,31 @@
+# 钱包模块
+
+## 模块职责
+
+`Features/Wallet` 承接首页 `wallet` 权限入口，负责个人钱包首页、收益明细、提现记录、提现申请、银行卡设置和积分兑换。
+
+## 代码结构
+
+- `WalletAPI`：封装钱包、提现、银行卡、地区、积分相关接口。
+- `WalletViewModel`：管理钱包汇总、收益明细分页、提现记录分页和提现资格判断。
+- `WithdrawApplyViewModel`：管理提现信息、金额校验、短信验证码和提现提交。
+- `WithdrawalSettingsViewModel`：管理银行卡资料、图片上传和银行卡更新提交。
+- `PointsRedemptionViewModel`：管理积分概览、兑换记录和兑换申请。
+- `WalletView`：钱包首页和钱包内部二级路由入口。
+
+## 提现资格流
+
+点击提现后先查询实名认证：
+
+1. 未提交或驳回：进入已迁移的 `RealNameAuthView`。
+2. 审核中：提示等待实名认证审核通过。
+3. 实名认证通过：查询银行卡资料。
+4. 无银行卡或银行卡驳回：进入 `WithdrawalSettingsView`。
+5. 银行卡审核中：提示等待审核。
+6. 银行卡通过：进入 `WithdrawApplyView`。
+
+## 上传与缓存边界
+
+银行卡正反面照片使用 `PhotosPicker` 选择后，通过 `OSSUploadService.uploadBankCardImage` 上传到 `bank_card/yyyyMMdd/scenicId/...` 路径，再把最终 URL 提交给服务端。
+
+钱包数据只保存在各 ViewModel 内存中。短信验证码、OSS STS、提现表单、银行卡图片 Data 和积分兑换表单均不落盘。