增加注解

tvbox/tvboxApp.swift

@@ -1,10 +1,15 @@
 import SwiftUI
 import SwiftData
 
+/// 应用入口。
+/// 负责初始化 SwiftData 容器，并将全局状态 `AppState` 注入到根视图。
 @main
 struct tvboxApp: App {
+    /// 全局运行时状态（配置加载状态、当前源、分栏布局状态等）。
     @StateObject private var appState = AppState()
     
+    /// 全局共享的 SwiftData 容器。
+    /// 这里显式声明 Schema，确保收藏/历史/缓存三类数据使用同一持久化存储。
     var sharedModelContainer: ModelContainer = {
         let schema = Schema([
             VodCollect.self,
@@ -19,6 +24,7 @@ struct tvboxApp: App {
         }
     }()
     
+    /// 应用窗口与根视图。
     var body: some Scene {
         WindowGroup {
             ContentView()
@@ -31,20 +37,32 @@ struct tvboxApp: App {
     }
 }
 
+/// 应用级状态容器。
+/// 统一管理配置加载与页面共享状态，避免在各页面重复拉取配置。
 @MainActor
 class AppState: ObservableObject {
+    /// 解析后的配置单例，提供给所有页面与 ViewModel 使用。
     @Published var apiConfig = ApiConfig.shared
+    /// 配置是否已经成功加载。控制 `ContentView` 显示主界面或首次配置页。
     @Published var isConfigLoaded = false
+    /// 当前首页选中的视频源 key（用于跨页面同步）。
     @Published var currentSourceKey: String = ""
     #if os(macOS)
+    /// macOS 三栏布局可见性（侧栏/内容/详情）。
     @Published var splitViewVisibility: NavigationSplitViewVisibility = .all
+    /// 进入播放器全屏前的分栏状态快照，用于退出全屏后恢复。
     private var splitViewVisibilityBeforePlayerFullScreen: NavigationSplitViewVisibility?
     #endif
     
+    /// 仅提供点播地址时的快捷加载入口（直播地址默认与点播一致）。
     func loadConfig(url: String) async {
         await loadConfig(vodUrl: url, liveUrl: nil)
     }
     
+    /// 加载点播与直播配置。
+    /// - Parameters:
+    ///   - vodUrl: 点播配置地址
+    ///   - liveUrl: 直播配置地址；为空时自动回退到点播地址
     func loadConfig(vodUrl: String, liveUrl: String?) async {
         let trimmedVod = vodUrl.trimmingCharacters(in: .whitespacesAndNewlines)
         let trimmedLive = (liveUrl ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
@@ -59,12 +77,15 @@ class AppState: ObservableObject {
         }
     }
     
+    /// 将“配置已加载”的统一状态写回全局。
+    /// 该方法会在设置页和启动自动加载两个入口中复用。
     func applyLoadedConfigState() {
         isConfigLoaded = true
         currentSourceKey = ApiConfig.shared.homeSourceBean?.key ?? ""
     }
     
     #if os(macOS)
+    /// 进入播放器全屏时隐藏侧栏，减少播放器可视区域干扰。
     func enterPlayerFullScreen() {
         if splitViewVisibilityBeforePlayerFullScreen == nil {
             splitViewVisibilityBeforePlayerFullScreen = splitViewVisibility
@@ -72,6 +93,7 @@ class AppState: ObservableObject {
         splitViewVisibility = .detailOnly
     }
     
+    /// 退出播放器全屏时恢复之前的分栏状态。
     func exitPlayerFullScreen() {
         guard let previous = splitViewVisibilityBeforePlayerFullScreen else { return }
         splitViewVisibility = previous