构建类型安全、高效的 SwiftData/Core Data 模型

@Model
class People {
  var name: String = ""
  var weight: Double? // 完美表达"可能没有体重记录"的语义
}

extension People {
    @NSManaged public var weight: NSNumber? // 符合 Core Data 要求但不符合 Swift 风格
}

extension People {
    @NSManaged public var name: String
  
    // 对外暴露符合 Swift 风格的类型安全 API
    public var weight: Double? {
        get { weightRaw?.doubleValue }
        set {
            weightRaw = newValue as NSNumber?
        }
    }
}

extension People {
    // 内部属性，对调用者隐藏实现细节
    @NSManaged var weightRaw: NSNumber?
}

import NonEmpty

extension People {
    public var name: NonEmptyString {
        get { NonEmpty(stringLiteral: nameRaw) }
        set { nameRaw = newValue.rawValue }
    }
}

extension People {
    @NSManaged var nameRaw: String
}

/// 验证后的名称结构体，确保名称符合长度要求
public struct ValidatedName {
    /// 笔记名称最小长度
    public static let lengthLowerBound = 3
    /// 笔记名称最大长度
    public static let lengthUpperBound = 20
    /// 笔记名称的原始字符串值
    public let rawValue: String

    /// 创建并验证名称
    public init(_ name: String) throws(NameError) {
        let cleanName = try Self.validate(name)
        rawValue = cleanName
    }

    /// 验证名称是否符合规则
    static func validate(_ name: String) throws(NameError) -> String {
        let name = name.toSingleLineCleanedString() // 去除非法字符
        guard let name else {
            throw NameError.nameIsEmpty
        }
        guard name.count >= lengthLowerBound, name.count < lengthUpperBound else {
            throw NameError.nameLengthIsInvalid(
                lowerBound: lengthLowerBound, upperBound: lengthUpperBound)
        }
        return name
    }

    /// 名称验证错误类型
    public enum NameError: Equatable, Sendable, Error {
        case nameIsEmpty
        case nameLengthIsInvalid(lowerBound: Int, upperBound: Int)
    }
}

/// 扩展 ValidatedName 以支持信任初始化方法
extension ValidatedName {
    /// 从已验证的数据源创建实例
    /// - Parameter validatedValue: 已经过验证的笔记名称
    /// - Note: 此初始化方法仅应在确保数据已经过验证的情况下使用（如从数据库读取）。
    ///         对于新输入的数据，请使用 `init(_:) throws` 方法进行验证。
    public init(trust validatedValue: String) {
        rawValue = validatedValue
    }
}

extension String {
    // 字符串处理，根据业务需求实现过滤逻辑
    func toSingleLineCleanedString() -> String? {
        let result = self.trimmingCharacters(in: .whitespacesAndNewlines)
        return result.isEmpty ? nil : result
    }
}

extension People {
    public var name: ValidatedName {
        get { ValidatedName(trust: nameRaw) }
        set { nameRaw = newValue.rawValue }
    }
}

// 使用示例
let people = People(content: viewContext)
people.name = try ValidatedName("    ") // error，不满足条件

// 通过枚举定义 ItemData 实体中不同数据类型的特化内容
public enum ItemDataContent: Equatable, Sendable {
    case singleValue(eventDate: Date, value: Double)
    case singleOption(eventDate: Date, optionID: UUID)
    case valueWithOption(eventDate: Date, value: Double, optionID: UUID)
    case dualValues(eventDate: Date, pairValue: ValidatedPairDouble)
    case valueWithInterval(pairDate: ValidatedPairDate, value: Double)
    case optionWithInterval(pairDate: ValidatedPairDate, optionID: UUID)
    case interval(pairDate: ValidatedPairDate)
}

// MARK: - 公开属性
extension ItemData {
    @NSManaged public var createTimestamp: Date
    @NSManaged public var uid: UUID
    @NSManaged public var item: Item?
    @NSManaged public var memo: Memo?

    // 将多个原始属性整合为一个语义丰富的复合类型
    public var dataContent: ItemDataContent? {
        get { dataContentGetter(type: type) }
        set { dateContentSetter(content: newValue) }
    }
}

// 隐藏的内部属性实现
extension ItemData {
  @NSManaged var startDate: Date?
  @NSManaged var endDate: Date?
  @NSManaged var value1: NSNumber?
  // 其他内部属性...
}

extension DataContent {
    public var optionSelections: [Int8] {
        get { /* 内部转换逻辑*/ } // 比如保存成数组 
        set { /* 内部转换逻辑 */ }
    }
}

// 使用示例
dataContent.optionSelections = [2, 3, 6, 1]  // 用户选择了 ID 为 2, 3, 6, 1 的选项

extension DataContent {
    // 对外提供直观的数组接口
    public var optionSelections: [Int] {
        get { optionIDsNumber.toArray() }
        set { optionIDsNumber = optionIDsToInt64(optionIDs: newValue) }
    }
    
    // 内部存储为位掩码
    private var optionIDsNumber: Int64
}

func optionIDsToInt64(optionIDs: Int[Int]) -> Int64 {
    var result: Int64 = 0
    for id in optionIDs {
        if id >= 0, id <= 63 {
            // 每个ID设置对应的位
            result |= (1 << id)
        }
    }
    return result
}
NSPredicate(format: "(optionIDsNumber & %@) == %@", NSNumber(value: bitmask),NSNumber(value: bitmask))

// 构建查询谓词：查找同时包含 ID 为 2、3 和 10 的所有记录
let optionIDs = [2, 3, 10]
let bitmask = optionIDsToInt64(optionIDs: optionIDs)  // 将选项 ID 数组转换为位掩码

// 使用位与(&)运算符检查是否包含所有指定选项
let predicate = NSPredicate(
    format: "(optionIDsNumber & %@) == %@", 
    NSNumber(value: bitmask), 
    NSNumber(value: bitmask)
)

extension ItemData {
    /// 创建新的数据项，但不自动插入上下文
    /// - Parameters:
    ///   - createTimestamp: 创建时间戳
    ///   - uid: 唯一标识符
    ///   - dataContent: 数据内容（复合类型）
    public convenience init(
        createTimestamp: Date,
        uid: UUID,
        dataContent: ItemDataContent // 只需提供一个复合类型，而非多个分散属性
    ) {
        self.init(entity: Self.entity(), insertInto: nil) // 借鉴SwiftData的设计，不主动插入上下文
        self.createTimestamp = createTimestamp
        self.uid = uid
        self.dataContent = dataContent
    }
}

let item = Item(
    name: try ValidatedName("New Item"),
    createTimestamp: Date()
)
viewContext.insert(item) // 显式插入上下文

let itemData = ItemData(
    createTimestamp: Date(),
    uid: UUID(),
    dataContent: .singleValue(eventDate: Date(), value: 98.6)
)
viewContext.insert(itemData) // 显式插入上下文

// 建立关系
itemData.item = item