suixinkan_ios_new/suixinkan/Features/Home/Models/HomeMenuItem.swift

//
//  HomeMenuItem.swift
//  suixinkan
//
//  Created by Codex on 2026/6/22.
//

import Foundation

/// 首页菜单实体，表示一个由权限 URI 派生出来的可点击功能入口。
struct HomeMenuItem: Equatable, Identifiable {
    let title: String
    let uri: String
    let iconSrc: String?

    var id: String {
        uri
    }
}

/// 首页可导航目标实体，表示首页菜单能进入的本地页面或占位页面。
enum HomeRoute: Hashable {
    case profileSpace
    case scenicSelection
    case permissionApply
    case permissionApplyStatus
    case scenicApplication
    case moreFunctions
    case settings
    case paymentCollection
    case wallet
    case taskManagement
    case taskCreate
    case taskDetail(id: Int, summary: PhotographerTaskItem?)
    case cloudStorage
    case cloudStorageTransit
    case materialLibrary
    case materialUpload
    case sampleLibrary
    case sampleUpload
    case albumList
    case albumTrailer
    case modulePlaceholder(uri: String, title: String)
}

/// 首页权限 URI 解析结果，区分 Tab 跳转、本地页面、已知不支持和未知占位。
enum HomeMenuResolvedRoute: Equatable {
    case tab(AppTab)
    case orders(OrdersEntry)
    case destination(HomeRoute)
    case unsupported(uri: String, title: String, reason: String)
    case placeholder(uri: String, title: String)
}

/// 未知首页路由记录实体，用于诊断后端新增但 iOS 尚未映射的 URI。
struct UnknownHomeRouteRecord: Codable, Equatable {
    let uri: String
    let title: String
    let firstSeenAt: Date
    let lastSeenAt: Date
    let count: Int
}

/// 首页权限路由审计项，表示一个权限菜单和它的解析结果。
struct HomePermissionRouteAuditEntry: Equatable {
    let uri: String
    let title: String
    let route: HomeMenuResolvedRoute
}

/// 首页权限路由审计结果，按可路由、已知不支持、未知三类聚合。
struct HomePermissionRouteAudit: Equatable {
    let routable: [HomePermissionRouteAuditEntry]
    let unsupported: [HomePermissionRouteAuditEntry]
    let unknown: [HomePermissionRouteAuditEntry]

    var hasUnknownRoutes: Bool {
        !unknown.isEmpty
    }
}