迁移合作订单完整能力，并统一 AppRoleCode 角色权限与首页菜单展示。

新增 CooperationOrder 模块（双 Tab 列表、获客员绑定、主 Tab 扫码）、订单来源/带客单绑定及配套 API 测试；同步引入 roleCode 权限匹配与相关单元测试。

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

suixinkan/Core/Models/AppRoleCode.swift

@@ -0,0 +1,100 @@
+//
+//  AppRoleCode.swift
+//  suixinkan
+//
+//  Created by Codex on 2026/6/29.
+//
+
+import Foundation
+
+/// App 业务角色枚举，与后端 `app_role_code` / `role_code` 字符串一一对应。
+enum AppRoleCode: String, CaseIterable, Hashable {
+    case driver = "driver"
+    case floristBuilder = "florist_builder"
+    case clerk = "clerk"
+    case liveStream = "live_stream"
+    case frontDesk = "front_desk"
+    case makeupArtist = "makeup_artist"
+    case photographerAssistant = "photographer_assistant"
+    case assistantManager = "assistant_manager"
+    case scenicOperation = "scenic_operation"
+    case scenicAdmin = "scenic_admin"
+    case scenicCS = "scenic_cs"
+    case editor = "editor"
+    case storeAdmin = "store_admin"
+    case photographer = "photographer"
+
+    /// 角色中文展示名。
+    var displayName: String {
+        switch self {
+        case .driver: "司机"
+        case .floristBuilder: "搭建花艺师"
+        case .clerk: "店员"
+        case .liveStream: "直播"
+        case .frontDesk: "前台"
+        case .makeupArtist: "化妆师"
+        case .photographerAssistant: "摄影师助理"
+        case .assistantManager: "副店长"
+        case .scenicOperation: "景区运营"
+        case .scenicAdmin: "景区管理员"
+        case .scenicCS: "飞手"
+        case .editor: "剪辑师"
+        case .storeAdmin: "店铺管理员"
+        case .photographer: "摄影师"
+        }
+    }
+
+    var isStoreAdmin: Bool { self == .storeAdmin }
+    var isScenicAdmin: Bool { self == .scenicAdmin }
+    var isPhotographer: Bool { self == .photographer }
+
+    /// 从后端 role_code 字符串解析角色。
+    static func fromCode(_ code: String?) -> AppRoleCode? {
+        guard let trimmed = code?.trimmingCharacters(in: .whitespacesAndNewlines),
+              !trimmed.isEmpty else { return nil }
+        return AppRoleCode(rawValue: trimmed)
+    }
+
+    /// 从旧版 numeric role id 解析角色，用于一次性缓存迁移。
+    static func fromLegacyRoleId(_ roleId: Int) -> AppRoleCode? {
+        switch roleId {
+        case 41: .photographer
+        case 46: .storeAdmin
+        case 47: .editor
+        case 52: .scenicCS
+        case 53: .scenicAdmin
+        case 54: .scenicOperation
+        default: nil
+        }
+    }
+
+    /// 从角色中文名推断角色，作为 role_code 缺失时的兜底。
+    static func fromRoleName(_ roleName: String?) -> AppRoleCode? {
+        let name = roleName?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        guard !name.isEmpty else { return nil }
+        if name.contains("摄影师助理") { return .photographerAssistant }
+        if name.contains("副店长") { return .assistantManager }
+        if name.contains("搭建花艺") || name.contains("花艺师") { return .floristBuilder }
+        if name.contains("店铺管理") || name.contains("店长") { return .storeAdmin }
+        if name.contains("景区管理") { return .scenicAdmin }
+        if name.contains("景区运营") { return .scenicOperation }
+        if name.contains("景区客服") || name.contains("飞手") { return .scenicCS }
+        if name.contains("剪辑") { return .editor }
+        if name.contains("化妆师") { return .makeupArtist }
+        if name.contains("摄影师") { return .photographer }
+        if name.contains("司机") { return .driver }
+        if name.contains("店员") { return .clerk }
+        if name.contains("直播") { return .liveStream }
+        if name.contains("前台") { return .frontDesk }
+        return AppRoleCode.allCases.first { name.contains($0.displayName) }
+    }
+
+    /// 首页隐藏顶部在线/计时/位置/快捷操作的角色（原 46/47/52/53/54）。
+    static let homeMinimalTopRoles: Set<AppRoleCode> = [
+        .storeAdmin,
+        .editor,
+        .scenicCS,
+        .scenicAdmin,
+        .scenicOperation,
+    ]
+}

suixinkan/Core/Models/RolePermissionMatching.swift

@@ -0,0 +1,76 @@
+//
+//  RolePermissionMatching.swift
+//  suixinkan
+//
+//  Created by Codex on 2026/6/29.
+//
+
+import Foundation
+
+/// 角色权限匹配工具，按 role_code 优先、legacy id、角色名顺序解析当前角色。
+enum RolePermissionMatching {
+    /// 解析当前 App 角色，用于快照迁移和 session 补全。
+    static func resolveRoleCode(
+        roleCode: String?,
+        roleId: Int?,
+        roleName: String?,
+        permissions: [RolePermissionResponse] = []
+    ) -> AppRoleCode? {
+        if let code = AppRoleCode.fromCode(roleCode) { return code }
+        if let legacyId = roleId, legacyId > 0, let code = AppRoleCode.fromLegacyRoleId(legacyId) {
+            return code
+        }
+        if let code = AppRoleCode.fromRoleName(roleName) { return code }
+        return inferFromPermissionList(roleId: roleId, roleName: roleName, permissions: permissions)
+    }
+
+    /// 在角色权限列表中匹配当前角色，优先 role_code。
+    static func match(
+        in permissions: [RolePermissionResponse],
+        roleCode: String?,
+        roleId: Int?,
+        roleName: String?
+    ) -> RolePermissionResponse? {
+        if let code = AppRoleCode.fromCode(roleCode) {
+            if let matched = permissions.first(where: { AppRoleCode.fromCode($0.role.roleCode) == code }) {
+                return matched
+            }
+        }
+        if let roleId, roleId > 0,
+           let matched = permissions.first(where: { $0.role.id == roleId }) {
+            return matched
+        }
+        let trimmedName = roleName?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        if !trimmedName.isEmpty {
+            if let matched = permissions.first(where: { item in
+                let name = item.role.name.trimmingCharacters(in: .whitespacesAndNewlines)
+                return !name.isEmpty && (name.contains(trimmedName) || trimmedName.contains(name))
+            }) {
+                return matched
+            }
+        }
+        return nil
+    }
+
+    /// 从权限列表推断角色 code。
+    private static func inferFromPermissionList(
+        roleId: Int?,
+        roleName: String?,
+        permissions: [RolePermissionResponse]
+    ) -> AppRoleCode? {
+        guard !permissions.isEmpty else { return nil }
+        if let roleId, roleId > 0,
+           let item = permissions.first(where: { $0.role.id == roleId }) {
+            return AppRoleCode.fromCode(item.role.roleCode) ?? AppRoleCode.fromRoleName(item.role.name)
+        }
+        let trimmedName = roleName?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        if !trimmedName.isEmpty,
+           let item = permissions.first(where: { item in
+               let name = item.role.name.trimmingCharacters(in: .whitespacesAndNewlines)
+               return !name.isEmpty && (name.contains(trimmedName) || trimmedName.contains(name))
+           }) {
+            return AppRoleCode.fromCode(item.role.roleCode) ?? AppRoleCode.fromRoleName(item.role.name)
+        }
+        return nil
+    }
+}