增加注解

tvbox/Persistence/CacheStore.swift

@@ -5,18 +5,26 @@ import SwiftData
 
 /// 单部剧的续播状态
 struct VodPlaybackState: Codable {
+    /// 当前播放线路标识。
     var flag: String
+    /// 剧集索引。
     var episodeIndex: Int
+    /// 播放进度（秒）。
     var progressSeconds: Double
 }
 
 /// 视频收藏
 @Model
 final class VodCollect {
+    /// 视频 ID（与 sourceKey 组成唯一语义键）。
     var vodId: String = ""
+    /// 片名。
     var vodName: String = ""
+    /// 海报地址。
     var vodPic: String = ""
+    /// 来源站点 key。
     var sourceKey: String = ""
+    /// 最近更新时间（收藏创建/刷新时间）。
     var updateTime: Date = Date()
     
     init(vodId: String, vodName: String, vodPic: String, sourceKey: String) {
@@ -31,12 +39,19 @@ final class VodCollect {
 /// 播放历史记录
 @Model
 final class VodRecord {
+    /// 视频 ID。
     var vodId: String = ""
+    /// 片名。
     var vodName: String = ""
+    /// 海报地址。
     var vodPic: String = ""
+    /// 来源站点 key。
     var sourceKey: String = ""
-    var playNote: String = ""      // 如 "第5集 03:45"
-    var dataJson: String = ""      // 续播状态 JSON（VodPlaybackState）
+    /// 播放标记，如“第5集 03:45”。
+    var playNote: String = ""
+    /// 续播状态 JSON（`VodPlaybackState` 编码结果）。
+    var dataJson: String = ""
+    /// 最近播放时间。
     var updateTime: Date = Date()
     
     init(vodId: String, vodName: String, vodPic: String, sourceKey: String, playNote: String = "") {
@@ -52,8 +67,11 @@ final class VodRecord {
 /// 通用缓存
 @Model
 final class CacheItem {
+    /// 唯一缓存键。
     @Attribute(.unique) var key: String = ""
+    /// 缓存值（字符串形式）。
     var value: String = ""
+    /// 更新时间。
     var updateTime: Date = Date()
     
     init(key: String, value: String) {
@@ -95,6 +113,7 @@ actor CacheStore {
     
     @MainActor
     func removeCollect(vodId: String, sourceKey: String, context: ModelContext) {
+        // 收藏以 (vodId, sourceKey) 为业务唯一键，删除时也按该组合匹配。
         let predicate = #Predicate<VodCollect> { item in
             item.vodId == vodId && item.sourceKey == sourceKey
         }
@@ -151,6 +170,7 @@ actor CacheStore {
         try? context.save()
     }
     
+    /// 读取续播状态（若无记录或 JSON 无法解码则返回 `nil`）。
     @MainActor
     func getPlaybackState(vodId: String, sourceKey: String, context: ModelContext) -> VodPlaybackState? {
         guard let record = fetchRecord(vodId: vodId, sourceKey: sourceKey, context: context) else {
@@ -171,6 +191,7 @@ actor CacheStore {
     
     @MainActor
     private func fetchRecord(vodId: String, sourceKey: String, context: ModelContext) -> VodRecord? {
+        // 历史记录同样以 (vodId, sourceKey) 作为业务键。
         let predicate = #Predicate<VodRecord> { item in
             item.vodId == vodId && item.sourceKey == sourceKey
         }
@@ -185,6 +206,7 @@ actor CacheStore {
         return String(data: data, encoding: .utf8)
     }
     
+    /// 从 JSON 字符串反序列化续播状态。
     private nonisolated static func decodePlaybackState(_ json: String) -> VodPlaybackState? {
         guard let data = json.data(using: .utf8) else { return nil }
         return try? JSONDecoder().decode(VodPlaybackState.self, from: data)