09 · 데이터베이스와 영속성

// ❌ 토큰을 UserDefaults 에 — plist 평문, 백업·파일 접근으로 노출된다
UserDefaults.standard.set(accessToken, forKey: "token")

// ✅ Keychain — 데이터 보호로 암호화, 접근성 클래스로 노출 시점을 제한
let query: [String: Any] = [
    kSecClass as String:       kSecClassGenericPassword,
    kSecAttrAccount as String: "accessToken",
    kSecValueData as String:   Data(accessToken.utf8),
    // 첫 잠금 해제 후에만 접근, 이 기기에서만 (백업으로도 유출 안 됨)
    kSecAttrAccessible as String: kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly
]
SecItemAdd(query as CFDictionary, nil)

import Foundation
import Security

// UserDefaults의 plist는 평문이다. 백업·파일 접근으로 그대로 읽힌다.
// 토큰·비밀번호·PIN·암호키는 예외 없이 Keychain으로 간다.

enum KeychainStore {
    static func save(_ value: String, account: String) throws {
        let data = Data(value.utf8)

        // 같은 account가 있으면 먼저 지운다 (SecItemAdd는 중복을 거부한다)
        let deleteQuery: [String: Any] = [
            kSecClass as String: kSecClassGenericPassword,
            kSecAttrAccount as String: account
        ]
        SecItemDelete(deleteQuery as CFDictionary)

        let addQuery: [String: Any] = [
            kSecClass as String: kSecClassGenericPassword,
            kSecAttrAccount as String: account,
            kSecValueData as String: data,
            // ✅ 접근성은 필요한 만큼만 좁게
            //    포그라운드에서만 쓰고 기기 이전도 필요 없다면 WhenPasscodeSetThisDeviceOnly가 가장 좁다
//    (단 패스코드 미설정 기기에는 저장 자체가 안 되고, 패스코드를 해제하면 항목이 삭제된다)
//    그 제약이 부담이면 WhenUnlockedThisDeviceOnly가 현실적인 차선이다
            kSecAttrAccessible as String: kSecAttrAccessibleWhenUnlockedThisDeviceOnly
        ]
        let status = SecItemAdd(addQuery as CFDictionary, nil)
        guard status == errSecSuccess else { throw KeychainError.status(status) }
    }

    static func read(account: String) throws -> String? {
        let query: [String: Any] = [
            kSecClass as String: kSecClassGenericPassword,
            kSecAttrAccount as String: account,
            kSecReturnData as String: true,
            kSecMatchLimit as String: kSecMatchLimitOne
        ]
        var item: CFTypeRef?
        let status = SecItemCopyMatching(query as CFDictionary, &item)
        if status == errSecItemNotFound { return nil }
        guard status == errSecSuccess, let data = item as? Data else {
            throw KeychainError.status(status)
        }
        return String(data: data, encoding: .utf8)
    }
}

enum KeychainError: Error { case status(OSStatus) }

// ❌ 절대 하지 말 것
// UserDefaults.standard.set(accessToken, forKey: "token")
// try token.write(to: documentsURL, atomically: true, encoding: .utf8)

import Foundation

// UserDefaults는 값을 처음 읽는 시점에 그 도메인 plist 전체를 메모리로 읽어 캐시한다.
// 큰 값을 넣으면 콜드스타트가 느려지고 그만큼 계속 상주한다.

// ❌ 이런 것들을 넣으면 안 된다
func badUsage(_ feedJSON: Data, _ image: Data) {
    UserDefaults.standard.set(feedJSON, forKey: "feedCache")     // 수백 KB~MB
    UserDefaults.standard.set(image, forKey: "avatar")           // 이미지
    UserDefaults.standard.set(Array(repeating: "x", count: 10_000), forKey: "log")
}

// ✅ 수 KB 이내의 사용자 설정만
enum Settings {
    private static let defaults = UserDefaults.standard

    static var isDarkMode: Bool {
        get { defaults.bool(forKey: "isDarkMode") }
        set { defaults.set(newValue, forKey: "isDarkMode") }
    }

    static var lastSyncDate: Date? {
        get { defaults.object(forKey: "lastSync") as? Date }
        set { defaults.set(newValue, forKey: "lastSync") }
    }

    static var preferredLanguage: String {
        get { defaults.string(forKey: "language") ?? "ko" }
        set { defaults.set(newValue, forKey: "language") }
    }
}

// ✅ @AppStorage(SwiftUI)도 같은 저장소다 — 크기 기준은 동일하게 적용된다
// @AppStorage("isDarkMode") var isDarkMode = false

// ✅ 현재 크기를 확인해 보는 방법
func inspectSize() {
    guard let bundleID = Bundle.main.bundleIdentifier,
          let dict = UserDefaults.standard.persistentDomain(forName: bundleID),
          let data = try? PropertyListSerialization.data(
            fromPropertyList: dict, format: .binary, options: 0)
    else { return }
    print("UserDefaults 크기: \(data.count / 1024)KB")   // 수십 KB를 넘으면 점검
}

import Foundation

// Documents는 백업되고 iCloud 용량을 먹는다.
// 다시 받을 수 있는 데이터를 여기 두면 사용자 백업이 불필요하게 커진다.

enum Storage {
    private static let fm = FileManager.default

    /// 사용자가 만든 유일본 — 백업 대상
    static var documents: URL {
        try! fm.url(for: .documentDirectory, in: .userDomainMask,
                    appropriateFor: nil, create: true)
    }

    /// 앱이 관리하는 영구 데이터(DB 등) — 백업되지만 사용자에겐 안 보인다
    static var applicationSupport: URL {
        try! fm.url(for: .applicationSupportDirectory, in: .userDomainMask,
                    appropriateFor: nil, create: true)
    }

    /// 재생성 가능 — 백업 제외, 공간 부족 시 OS가 지운다
    static var caches: URL {
        try! fm.url(for: .cachesDirectory, in: .userDomainMask,
                    appropriateFor: nil, create: true)
    }
}

// ✅ Documents에 큰 재생성 가능 파일을 둬야 한다면 백업에서 명시적으로 뺀다
func excludeFromBackup(_ url: URL) throws {
    var mutable = url
    var values = URLResourceValues()
    values.isExcludedFromBackup = true
    try mutable.setResourceValues(values)
}

// 사용 예
func setupPaths() throws {
    // 사용자가 그린 그림 → Documents (백업)
    let drawing = Storage.documents.appendingPathComponent("drawing.png")

    // 다운로드한 지도 타일 → Documents지만 백업 제외 (오프라인에 필요하므로 Caches는 위험)
    let tiles = Storage.documents.appendingPathComponent("tiles.db")
    try excludeFromBackup(tiles)

    // 이미지 썸네일 → Caches (없어져도 다시 만든다)
    let thumbs = Storage.caches.appendingPathComponent("thumbs")

    _ = (drawing, tiles, thumbs)
}

// ⚠️ 백업 제외 여부는 앱 심사에서도 본다. 재생성 가능한 큰 데이터를
//    Documents에 백업 대상으로 두면 리젝 사유가 될 수 있다.

import Foundation

// 파일·UserDefaults로 시작했다가 "정렬해서 보여 줘", "필터 걸어 줘",
// "페이지 단위로 잘라 줘"가 붙기 시작하면 그때가 DB로 옮길 시점이다.

// ❌ 파일 기반이 한계에 부딪히는 신호들
final class FileBasedStore {
    private var items: [Item] = []

    func load() throws {
        let data = try Data(contentsOf: url)
        items = try JSONDecoder().decode([Item].self, from: data)
        // 💥 신호 ①: 전체를 메모리에 올려야만 무엇이든 할 수 있다
    }

    func recent(limit: Int) -> [Item] {
        items.sorted { $0.date > $1.date }.prefix(limit).map { $0 }
        // 💥 신호 ②: 조회할 때마다 전체 정렬
    }

    func search(_ q: String) -> [Item] {
        items.filter { $0.title.contains(q) }
        // 💥 신호 ③: 전체 스캔. 인덱스가 없다.
    }

    func update(_ item: Item) throws {
        if let i = items.firstIndex(where: { $0.id == item.id }) { items[i] = item }
        try JSONEncoder().encode(items).write(to: url, options: .atomic)
        // 💥 신호 ④: 한 건 바꾸는 데 전체를 다시 쓴다
    }

    private let url = URL(fileURLWithPath: "/items.json")
}

// ✅ 위 신호가 둘 이상이면 DB로 옮긴다
//   · 정렬·필터·페이지네이션이 필요하다
//   · 전체를 메모리에 못 올릴 만큼 커진다
//   · 부분 갱신이 잦다
//   · 여러 화면이 같은 데이터를 다른 조건으로 본다
//   · 트랜잭션 정합성이 필요하다

// 선택 기준
//   객체 그래프·UI 자동 연동·CloudKit  → Core Data / SwiftData
//   복잡한 SQL·집계·명시적 스키마 통제 → GRDB / 직접 SQLite
//   단순 key-value가 크게 커진 경우     → SQLite 한 테이블도 충분하다

struct Item: Codable { let id: UUID; let title: String; let date: Date }

BEGIN;                                                   -- 트랜잭션 시작
UPDATE account SET balance = balance - 100 WHERE id = 1;  -- 출금
UPDATE account SET balance = balance + 100 WHERE id = 2;  -- 입금
COMMIT;                                                   -- 둘 다 반영(원자성)
-- 두 UPDATE 사이에서 앱이 죽어도, 커밋 전이면 SQLite 가 자동 ROLLBACK →
-- "출금은 됐는데 입금은 안 된" 반쪽 상태가 남지 않는다.

import CoreData

// "읽고-계산하고-쓰기"가 하나의 의미 단위면 반드시 한 트랜잭션이어야 한다.
// 중간에 죽으면 반쪽 상태가 남는다.

final class TransferService {
    private let container: NSPersistentContainer
    init(container: NSPersistentContainer) { self.container = container }

    // ❌ 개별 save를 두 번 — 사이에 크래시하면 돈이 사라진다
    func transferBad(from: NSManagedObjectID, to: NSManagedObjectID, amount: Int) throws {
        let ctx = container.newBackgroundContext()
        try ctx.performAndWait {
            let a = try ctx.existingObject(with: from) as! Account
            a.balance -= Int64(amount)
            try ctx.save()                    // 💥 여기서 죽으면 출금만 반영

            let b = try ctx.existingObject(with: to) as! Account
            b.balance += Int64(amount)
            try ctx.save()
        }
    }

    // ✅ 하나의 save = 하나의 트랜잭션
    func transfer(from: NSManagedObjectID, to: NSManagedObjectID, amount: Int) async throws {
        let ctx = container.newBackgroundContext()
        try await ctx.perform {
            let a = try ctx.existingObject(with: from) as! Account
            let b = try ctx.existingObject(with: to) as! Account

            guard a.balance >= Int64(amount) else { throw BankError.insufficient }

            a.balance -= Int64(amount)
            b.balance += Int64(amount)

            try ctx.save()                    // ✅ 둘 다 반영되거나 둘 다 무효
        }
    }
}

// ✅ 실패 시 컨텍스트를 되돌린다
func withRollback(_ ctx: NSManagedObjectContext, _ body: () throws -> Void) throws {
    do { try body(); try ctx.save() }
    catch { ctx.rollback(); throw error }     // 미저장 변경을 버린다
}

final class Account: NSManagedObject { @NSManaged var balance: Int64 }
enum BankError: Error { case insufficient }

import CoreData

// 커밋마다 fsync가 붙는다. 행마다 커밋하면 그 비용이 행 수만큼 곱해진다.

final class Importer {
    private let container: NSPersistentContainer
    init(container: NSPersistentContainer) { self.container = container }

    // ❌ 행마다 save — 10만 건이면 10만 번의 fsync
    func importBad(_ rows: [RowDTO]) async throws {
        let ctx = container.newBackgroundContext()
        try await ctx.perform {
            for row in rows {
                let e = Row(context: ctx)
                e.id = row.id
                try ctx.save()                      // 💥
            }
        }
    }

    // ✅ 청크 단위로 커밋 — 트랜잭션 크기와 메모리의 균형점
    func importBatched(_ rows: [RowDTO], batchSize: Int = 5_000) async throws {
        let ctx = container.newBackgroundContext()
        ctx.mergePolicy = NSMergeByPropertyObjectTrumpMergePolicy

        try await ctx.perform {
            for (i, row) in rows.enumerated() {
                let e = Row(context: ctx)
                e.id = row.id

                if (i + 1) % batchSize == 0 {
                    try ctx.save()
                    ctx.reset()                     // ✅ 메모리도 함께 비운다
                }
            }
            try ctx.save()
        }
    }

    // ✅ 더 빠른 경로: NSBatchInsertRequest (객체를 만들지 않고 SQL로 직행)
    func importFast(_ rows: [RowDTO]) async throws {
        let ctx = container.newBackgroundContext()
        try await ctx.perform {
            var index = 0
            let request = NSBatchInsertRequest(entity: Row.entity()) {
                (dict: NSMutableDictionary) -> Bool in
                guard index < rows.count else { return true }   // true면 종료
                dict["id"] = rows[index].id
                index += 1
                return false
            }
            request.resultType = .objectIDs
            try ctx.execute(request)
            // ⚠️ 검증·관계 설정·willSave를 건너뛴다. 단순 적재에만 쓴다.
        }
    }
}

struct RowDTO { let id: UUID }
final class Row: NSManagedObject { @NSManaged var id: UUID }

import CoreData
import SQLite3

// WAL 모드에서 변경은 -wal 파일에 먼저 쌓이고, 체크포인트 때 본 DB로 옮겨진다.
// 그런데 오래된 reader가 붙어 있으면 체크포인트가 진행되지 못해 -wal이 무한히 커진다.

// ❌ 앱 시작부터 종료까지 백그라운드 컨텍스트를 열어 두는 패턴
final class BadStack {
    let container: NSPersistentContainer
    lazy var backgroundContext = container.newBackgroundContext()   // 영구 보유
    init(container: NSPersistentContainer) { self.container = container }
    // 이 컨텍스트가 스냅샷을 붙들고 있으면 체크포인트가 막힌다
}

// ✅ 작업 단위로 만들고 끝나면 놓는다
final class Stack {
    let container: NSPersistentContainer
    init(container: NSPersistentContainer) { self.container = container }

    func perform<T>(_ body: @escaping (NSManagedObjectContext) throws -> T) async throws -> T {
        let ctx = container.newBackgroundContext()      // 매번 새로
        return try await ctx.perform {
            defer { ctx.reset() }                        // 끝나면 비운다
            return try body(ctx)
        }
    }
}

// ✅ 파일 크기를 주기적으로 확인한다
func walSize(storeURL: URL) -> Int {
    let wal = URL(fileURLWithPath: storeURL.path + "-wal")
    let attrs = try? FileManager.default.attributesOfItem(atPath: wal.path)
    return (attrs?[.size] as? Int) ?? 0
}

// ✅ 백그라운드 진입 시 강제 체크포인트로 정리한다
func checkpoint(_ container: NSPersistentContainer) {
    guard let store = container.persistentStoreCoordinator.persistentStores.first,
          let url = store.url else { return }
    // ⚠️ Apple은 Core Data가 만든 SQLite 스토어를 네이티브 sqlite3 API로 조작하지 말라고 명시한다
    //    (포맷이 private이고, Core Data가 연 상태에서는 SQLITE_BUSY로 조용히 실패한다).
    //    지원되는 방법은 스토어를 추가할 때 journal_mode 프라그마를 지정하는 것이다:
    //      desc.setOption(["journal_mode": "DELETE"] as NSDictionary, forKey: NSSQLitePragmasOption)
    //    이러면 Core Data가 -wal 내용을 본 파일로 병합한 뒤 롤백 저널로 동작한다(동시성은 포기).
    _ = (store, url)
}

// ⚠️ 앱이 -wal을 정리하지 않은 채 종료되면 다음 실행의 첫 열기가 느려진다.

sqlite> EXPLAIN QUERY PLAN SELECT * FROM message WHERE room_id = 42;
--  SCAN message                                    ← 풀 스캔 (O(n))

CREATE INDEX idx_message_room ON message(room_id);

sqlite> EXPLAIN QUERY PLAN SELECT * FROM message WHERE room_id = 42;
--  SEARCH message USING INDEX idx_message_room (room_id=?)   ← 인덱스 탐색 (O(log n))

-- 인덱스는 "어떤 쿼리를 빠르게 할 것인가"에서 출발한다.
-- 후보는 WHERE · ORDER BY · JOIN · 외래키에 자주 등장하는 컬럼이다.

-- ① 먼저 실제로 도는 쿼리를 모은다
SELECT * FROM message WHERE room_id = ? ORDER BY created_at DESC LIMIT 20;
SELECT COUNT(*) FROM message WHERE room_id = ? AND is_read = 0;
SELECT * FROM message WHERE sender_id = ? ORDER BY created_at DESC;

-- ② 실행 계획을 확인한다 — SCAN이 보이면 인덱스가 안 쓰이고 있다
EXPLAIN QUERY PLAN
SELECT * FROM message WHERE room_id = 42 ORDER BY created_at DESC LIMIT 20;
--  SCAN message                                   ← 전체 훑기 O(n)

-- ③ 인덱스를 걸고 다시 확인한다
CREATE INDEX idx_message_room_created ON message(room_id, created_at DESC);

EXPLAIN QUERY PLAN
SELECT * FROM message WHERE room_id = 42 ORDER BY created_at DESC LIMIT 20;
--  SEARCH message USING INDEX idx_message_room_created (room_id=?)   ← 적용됨
--  ORDER BY 도 인덱스 순서로 해결되어 정렬 단계가 사라진다

-- ④ 외래키에는 거의 항상 인덱스가 필요하다
--    (SQLite는 외래키에 자동으로 인덱스를 만들지 않는다)
CREATE INDEX idx_message_sender ON message(sender_id);

-- ⑤ 통계를 갱신해 옵티마이저가 좋은 선택을 하게 한다
ANALYZE;

-- ⚠️ 컬럼을 함수로 감싸면 그 컬럼의 '일반' 인덱스는 못 쓴다 (SQLite 3.9.0+의 표현식 인덱스 CREATE INDEX ... ON user(lower(email))를 만들고 WHERE절에 글자 그대로 같은 표현식을 쓰면 탄다)
-- ❌ SELECT * FROM user WHERE lower(email) = ?;
-- ✅ 정규화한 컬럼을 따로 두고 거기에 인덱스를 건다
ALTER TABLE user ADD COLUMN email_lower TEXT;
CREATE INDEX idx_user_email_lower ON user(email_lower);

-- 복합 인덱스는 '왼쪽부터 연속으로' 쓸 수 있다(leftmost prefix).
-- (a, b, c) 인덱스는 (a), (a,b), (a,b,c) 조회에는 쓰이지만 (b), (c)에는 안 쓰인다.

CREATE INDEX idx_msg ON message(room_id, is_read, created_at);

-- ✅ 쓰인다
SELECT * FROM message WHERE room_id = 1;
SELECT * FROM message WHERE room_id = 1 AND is_read = 0;
SELECT * FROM message WHERE room_id = 1 AND is_read = 0 ORDER BY created_at;

-- ❌ 사실상 못 쓴다 (선두 컬럼이 빠졌다. ANALYZE를 돌렸고 선두 컬럼 중복이 아주 많으면 skip-scan으로 탈 수도 있지만 설계 기준으로 삼을 경로는 아니다)
SELECT * FROM message WHERE is_read = 0;
SELECT * FROM message ORDER BY created_at;

-- 순서를 정하는 규칙
--   ① 등호(=)로 걸리는 컬럼을 앞에
--   ② 범위(<, >, BETWEEN)·정렬용 컬럼을 뒤에
--   ③ 여러 쿼리에서 공통으로 쓰는 컬럼을 선두에

-- ❌ 범위 컬럼을 앞에 두면 뒤 컬럼이 무력해진다
CREATE INDEX idx_bad ON message(created_at, room_id);
SELECT * FROM message WHERE created_at > ? AND room_id = 1;
--  created_at 범위로 좁힌 뒤 room_id는 그 안에서 스캔한다

-- ✅ 등호를 앞에
CREATE INDEX idx_good ON message(room_id, created_at);
SELECT * FROM message WHERE room_id = 1 AND created_at > ?;
--  room_id로 정확히 진입한 뒤 created_at 범위를 인덱스 순서로 훑는다

-- ⚠️ "선택도(cardinality)가 높은 컬럼을 무조건 앞에"는 흔한 미신이다.
--    실제 기준은 '그 쿼리에서 등호로 걸리는가'와 '여러 쿼리의 공통 접두인가'다.

-- ✅ 커버링 인덱스 — 필요한 컬럼이 전부 인덱스에 있으면 테이블 접근이 사라진다
CREATE INDEX idx_cover ON message(room_id, created_at, sender_id);
SELECT sender_id FROM message WHERE room_id = 1 ORDER BY created_at;
--  EXPLAIN에 "USING COVERING INDEX"가 뜬다

-- 인덱스는 읽기를 위해 쓰기를 희생하는 거래다.
-- 행 하나를 넣을 때마다 모든 인덱스가 함께 갱신된다.

-- ❌ 로그·이벤트 적재 테이블에 인덱스 5개
CREATE TABLE event (
    id INTEGER PRIMARY KEY,
    type TEXT, user_id INTEGER, session_id TEXT,
    created_at INTEGER, payload TEXT
);
CREATE INDEX idx_e1 ON event(type);
CREATE INDEX idx_e2 ON event(user_id);
CREATE INDEX idx_e3 ON event(session_id);
CREATE INDEX idx_e4 ON event(created_at);
CREATE INDEX idx_e5 ON event(type, created_at);
--  INSERT 한 번에 B-tree 갱신 6회(테이블 + 인덱스 5) + 공간 수 배

-- ✅ 적재 중심 테이블은 인덱스를 최소로
--    조회는 별도의 집계 테이블이나 배치로 처리한다
CREATE TABLE event_lean (
    id INTEGER PRIMARY KEY,             -- rowid만
    type TEXT, created_at INTEGER, payload TEXT
);
CREATE INDEX idx_event_created ON event_lean(created_at);   -- 정리용 하나만

-- ✅ 대량 적재 전에는 인덱스를 잠시 떼는 것도 방법이다
DROP INDEX IF EXISTS idx_event_created;
-- … 수십만 건 INSERT (트랜잭션 하나로) …
CREATE INDEX idx_event_created ON event_lean(created_at);
ANALYZE;

-- ✅ 실제로 쓰이지 않는 인덱스를 찾아 지운다
--    쿼리 로그를 모아 EXPLAIN QUERY PLAN을 돌려 보고,
--    어떤 쿼리에도 등장하지 않는 인덱스는 순손실이다
SELECT name, tbl_name FROM sqlite_master WHERE type = 'index';

-- ✅ 부분 인덱스로 크기를 줄인다 (자주 조회하는 부분집합만)
CREATE INDEX idx_unread ON message(room_id) WHERE is_read = 0;
--  전체가 아니라 읽지 않은 행만 인덱싱 → 훨씬 작고 갱신도 적다

enum SchemaV1: VersionedSchema {
    static var versionIdentifier = Schema.Version(1, 0, 0)
    static var models: [any PersistentModel.Type] { [Trip.self] }
}
enum SchemaV2: VersionedSchema {           // 새 속성 추가처럼 추론 가능한 변경만 lightweight다. 개명은 @Attribute(originalName:)이 필요하고, name을 title·subtitle로 쪼개는 값 가공은 .custom 스테이지가 필요하다
    static var versionIdentifier = Schema.Version(2, 0, 0)
    static var models: [any PersistentModel.Type] { [Trip.self] }
}

enum TripMigrationPlan: SchemaMigrationPlan {
    static var schemas: [any VersionedSchema.Type] { [SchemaV1.self, SchemaV2.self] }
    static var stages: [MigrationStage] {
        // 자동 추론 가능하면 lightweight, 데이터 가공이 필요하면 .custom(before:after:)
        [ .lightweight(fromVersion: SchemaV1.self, toVersion: SchemaV2.self) ]
    }
}

import CoreData

// 마이그레이션 실패의 기본 대응이 "스토어 삭제"면 그건 데이터 유실이다.
// 백업 → 시도 → 실패 시 복원의 순서를 반드시 만든다.

final class MigrationCoordinator {
    private let fm = FileManager.default
    private let storeURL: URL

    init(storeURL: URL) { self.storeURL = storeURL }

    private var backupURL: URL { storeURL.appendingPathExtension("backup") }

    func migrate(_ container: NSPersistentContainer) async throws {
        try makeBackup()

        do {
            try await load(container)
            try? removeBackup()                    // 성공하면 백업 정리
        } catch {
            try restoreBackup()                    // ✅ 실패하면 되돌린다
            throw MigrationError.failedAndRestored(underlying: error)
        }
    }

    private func makeBackup() throws {
        try? removeBackup()          // ✅ -wal, -shm 백업까지 전부 지우고 시작한다
        //    (backupURL 하나만 지우면 이전 크래시 잔재와 충돌해 copyItem이 throw한다)
        guard fm.fileExists(atPath: storeURL.path) else { return }
        // ⚠️ -wal, -shm도 함께 복사해야 일관된 백업이 된다
        for suffix in ["", "-wal", "-shm"] {
            let src = URL(fileURLWithPath: storeURL.path + suffix)
            let dst = URL(fileURLWithPath: backupURL.path + suffix)
            if fm.fileExists(atPath: src.path) { try fm.copyItem(at: src, to: dst) }
        }
    }

    private func restoreBackup() throws {
        for suffix in ["", "-wal", "-shm"] {
            let live = URL(fileURLWithPath: storeURL.path + suffix)
            let back = URL(fileURLWithPath: backupURL.path + suffix)
            try? fm.removeItem(at: live)
            if fm.fileExists(atPath: back.path) { try fm.moveItem(at: back, to: live) }
        }
    }

    private func removeBackup() throws {
        for suffix in ["", "-wal", "-shm"] {
            try? fm.removeItem(at: URL(fileURLWithPath: backupURL.path + suffix))
        }
    }

    private func load(_ c: NSPersistentContainer) async throws {
        try await withCheckedThrowingContinuation { (cont: CheckedContinuation<Void, Error>) in
            c.loadPersistentStores { _, error in
                if let error { cont.resume(throwing: error) } else { cont.resume() }
            }
        }
    }
}

enum MigrationError: Error { case failedAndRestored(underlying: Error) }

import CoreData
import UIKit

// 수십만 건 변환을 메인에서 하면 워치독에 걸려 강제 종료된다.
// 백그라운드에서 진행하고 사용자에게 상태를 보여 준다.

@MainActor
final class MigrationViewController: UIViewController {
    private let progressView = UIProgressView()
    private let statusLabel = UILabel()

    func runMigration(_ coordinator: MigrationCoordinator) async {
        statusLabel.text = "데이터를 정리하는 중입니다…"
        progressView.progress = 0

        do {
            try await coordinator.migrate { [weak self] fraction in
                Task { @MainActor in self?.progressView.progress = Float(fraction) }
            }
            statusLabel.text = "완료"
            showMainScreen()
        } catch {
            // ✅ 실패해도 앱이 죽지 않고 안내로 이어진다
            statusLabel.text = "업그레이드에 실패했습니다."
            showRecoveryOptions(error)
        }
    }

    private func showMainScreen() {}
    private func showRecoveryOptions(_ e: Error) {}
}

// 진행률을 보고하며 변환한다
struct MigrationCoordinator {
    func migrate(onProgress: @escaping (Double) -> Void) async throws {
        let total = try countRows()
        var processed = 0

        try await withCheckedThrowingContinuation { cont in
            DispatchQueue.global(qos: .userInitiated).async {
                do {
                    try self.forEachBatch { batch in
                        try self.convert(batch)
                        processed += batch.count
                        onProgress(Double(processed) / Double(total))
                    }
                    cont.resume()
                } catch { cont.resume(throwing: error) }
            }
        }
    }

    private func countRows() throws -> Int { 0 }
    private func forEachBatch(_ body: ([Row]) throws -> Void) throws {}
    private func convert(_ batch: [Row]) throws {}
}

struct Row {}

import CoreData
import XCTest

// 실제 사용자는 v1에서 바로 v5로 온다. v4→v5만 테스트하면 그 경로가 비어 있다.

final class MigrationTests: XCTestCase {

    /// 각 버전의 실제 스토어 파일을 픽스처로 보관해 두고 전부 돌린다
    func test_모든_버전에서_최신으로_마이그레이션된다() throws {
        let versions = ["v1", "v2", "v3", "v4"]

        for version in versions {
            let fixture = Bundle(for: Self.self)
                .url(forResource: "store-\(version)", withExtension: "sqlite")!
            let temp = FileManager.default.temporaryDirectory
                .appendingPathComponent("\(version)-\(UUID()).sqlite")
            try FileManager.default.copyItem(at: fixture, to: temp)

            let container = makeContainer(at: temp)
            try loadSynchronously(container)          // 여기서 마이그레이션이 돈다

            // ✅ 데이터가 살아남았는지도 확인한다 — "열렸다"만으로는 부족하다
            let ctx = container.viewContext
            let request = NSFetchRequest<NSFetchRequestResult>(entityName: "Item")
    let count = try ctx.count(for: request)
            XCTAssertGreaterThan(count, 0, "\(version)에서 데이터가 유실됐다")

            try? FileManager.default.removeItem(at: temp)
        }
    }

    private func makeContainer(at url: URL) -> NSPersistentContainer {
        let c = NSPersistentContainer(name: "Model")
        let d = NSPersistentStoreDescription(url: url)
        d.shouldMigrateStoreAutomatically = true
        d.shouldInferMappingModelAutomatically = true
        c.persistentStoreDescriptions = [d]
        return c
    }

    private func loadSynchronously(_ c: NSPersistentContainer) throws {
        var loadError: Error?
        c.loadPersistentStores { _, e in loadError = e }
        if let loadError { throw loadError }
    }
}

// ✅ 픽스처를 만드는 방법: 각 릴리스 시점에 시뮬레이터에서 앱을 돌려
//    데이터를 넣고 .sqlite 파일을 꺼내 테스트 번들에 커밋해 둔다.
//    이게 마이그레이션 회귀를 잡는 가장 확실한 방법이다.

import CoreData

// 마이그레이션은 앞으로만 간다. 구버전 앱이 신버전 스토어를 열면
// 모르는 엔티티·속성 때문에 실패한다.

// ✅ ① 하위 호환 여지를 남기는 스키마 변경 규칙
//    · 새 속성은 optional 또는 기본값을 준다 → 구버전이 무시할 수 있다
//    · 기존 속성을 지우거나 이름을 바꾸는 건 파괴적 변경이다
//    · 엔티티 추가는 비교적 안전, 삭제는 위험

// ✅ ② 스토어에 스키마 버전을 명시적으로 기록한다
enum SchemaVersion {
    static let current = 5

    // ⚠️ 버전 마커는 스토어 '안'에 둔다 — UserDefaults에 두면 스토어만 교체·복원될 때
    //    (백업 복원, App Group 공유 스토어 교체) 다운그레이드 감지가 그대로 깨진다.
    private static let key = "appSchemaVersion"

    static func read(_ store: NSPersistentStore) -> Int {
        (store.metadata[key] as? Int) ?? 1
    }
    static func write(_ v: Int, to store: NSPersistentStore) {
        var md = store.metadata ?? [:]
        md[key] = v
        store.metadata = md          // 다음 save 시 스토어 파일에 함께 기록된다
    }
}

// ✅ ③ 구버전 앱이 신버전 스토어를 만나면 '명확히' 안내하고 멈춘다
func guardAgainstDowngrade() throws {
    let ctx = NSManagedObjectContext(concurrencyType: .mainQueueConcurrencyType)
    let stored = SchemaVersion.read(ctx)
    guard stored <= SchemaVersion.current else {
        // 앱을 업데이트하라고 안내한다. 스토어를 지우면 안 된다.
        throw StoreError.storeIsNewerThanApp(stored: stored, app: SchemaVersion.current)
    }
}

enum StoreError: Error {
    case storeIsNewerThanApp(stored: Int, app: Int)
}

// ✅ ④ 정말 되돌려야 한다면 '데이터 내보내기'로 우회한다
//    구버전이 읽을 수 있는 중립 포맷(JSON)으로 내보내고 다시 가져오게 한다
struct ExportBundle: Codable {
    let schemaVersion: Int
    let items: [ItemDTO]
}
struct ItemDTO: Codable { let id: UUID; let title: String }

// ⚠️ TestFlight 사용자는 구버전과 신버전을 오간다. 개발 중에는 이 경로가
//    실제로 발생하므로, 최소한 "앱을 업데이트하세요" 안내는 만들어 둔다.

let container = NSPersistentContainer(name: "Model")
let desc = container.persistentStoreDescriptions.first!

// 저장소를 통째로 바꿔도 위층 코드(fetch/insert/save)는 그대로다.
desc.type = NSInMemoryStoreType     // 테스트용 (또는 NSSQLiteStoreType / NSBinaryStoreType)

container.loadPersistentStores { _, error in
    if let error { fatalError("store load 실패: \(error)") }
}
// → Core Data 는 "무엇으로 저장하느냐"와 "객체를 어떻게 다루느냐"를 분리한다.

import Foundation

// 선택 기준은 "무엇이 중심인가"다.

// ✅ Core Data / SwiftData가 잘 맞는 경우
//    · 객체 그래프와 관계가 중심 (Post ↔ Author ↔ Comment)
//    · UI와 자동 연동이 필요 (NSFetchedResultsController, @FetchRequest, @Query)
//    · CloudKit 동기화
//    · undo/redo, 변경 추적
//    · 애플 생태계 통합을 공짜로 얻고 싶다

// ✅ GRDB / 직접 SQLite가 잘 맞는 경우
//    · 복잡한 조인·집계·리포팅 쿼리가 중심
//    · 예측 가능한 SQL 성능과 실행 계획 통제
//    · 스키마·마이그레이션을 명시적으로 관리
//    · 서버와 같은 SQL 지식을 재사용

// GRDB 예 — SQL이 그대로 드러난다
import GRDB

struct MonthlyStat: FetchableRecord, Decodable {
    let month: String
    let total: Int
    let orderCount: Int
}

func monthlyStats(_ db: Database) throws -> [MonthlyStat] {
    try MonthlyStat.fetchAll(db, sql: """
        SELECT strftime('%Y-%m', created_at) AS month,
               SUM(amount) AS total,
               COUNT(*)    AS orderCount
          FROM "order"
         WHERE status = 'completed'
         GROUP BY month
         ORDER BY month DESC
         LIMIT 12
        """)
}
// Core Data로 같은 걸 하려면 NSExpression·NSFetchRequest 조합이 필요하고
// 실행 계획을 통제하기 어렵다.

// ⚠️ 둘을 섞는 것도 가능하다 — 주 저장소는 Core Data, 통계는 별도 SQLite.
//    다만 두 스키마를 동기화하는 부담이 생기므로 신중히 결정한다.

import CoreData
import XCTest

// 디스크를 쓰면 테스트가 느리고, 이전 테스트의 상태가 남아 서로 간섭한다.

enum TestStack {
    /// SQLite in-memory — 기능이 온전하고 빠르다
    static func makeContainer() -> NSPersistentContainer {
        let container = NSPersistentContainer(name: "Model")
        let description = NSPersistentStoreDescription()

        // ✅ /dev/null을 URL로 주면 SQLite in-memory로 열린다.
        //    NSInMemoryStoreType과 달리 실제 SQLite 동작(제약·인덱스·SQL)이 그대로다.
        description.url = URL(fileURLWithPath: "/dev/null")
        description.shouldAddStoreAsynchronously = false

        container.persistentStoreDescriptions = [description]
        container.loadPersistentStores { _, error in
            precondition(error == nil, "테스트 스토어 로드 실패: \(error!)")
        }
        container.viewContext.mergePolicy = NSMergeByPropertyObjectTrumpMergePolicy
        return container
    }
}

final class OrderTests: XCTestCase {
    private var container: NSPersistentContainer!

    override func setUp() {
        super.setUp()
        container = TestStack.makeContainer()      // ✅ 테스트마다 새 스토어
    }

    override func tearDown() {
        container = nil
        super.tearDown()
    }

    func test_주문_저장() throws {
        let ctx = container.viewContext
        let order = Order(context: ctx)
        order.id = UUID()
        try ctx.save()

        let count = try ctx.count(for: Order.fetchRequest())
        XCTAssertEqual(count, 1)
    }
}

// ⚠️ NSInMemoryStoreType은 SQLite가 아니라 별도 구현이라
//    제약·정렬·일부 predicate 동작이 실제와 다를 수 있다. /dev/null 방식이 안전하다.

final class Order: NSManagedObject {
    @NSManaged var id: UUID
    @nonobjc class func fetchRequest() -> NSFetchRequest<Order> {
        NSFetchRequest<Order>(entityName: "Order")
    }
}

import CoreData

// Core Data를 "SQL 래퍼"로 취급하면 faulting·컨텍스트 수명에서 버그가 난다.

// ⚠️ ① faulting — 관계를 순회하면 건마다 쿼리가 나간다 (N+1)
func nPlusOneProblem(_ ctx: NSManagedObjectContext) throws {
    let posts = try ctx.fetch(Post.fetchRequest())
    for post in posts {
        print(post.author?.name ?? "")     // 💥 post 개수만큼 추가 쿼리
    }
}

// ✅ 미리 채워 온다
func prefetched(_ ctx: NSManagedObjectContext) throws {
    let request = Post.fetchRequest()
    request.relationshipKeyPathsForPrefetching = ["author"]   // ✅ 한 번에
    let posts = try ctx.fetch(request)
    for post in posts { print(post.author?.name ?? "") }
}

// ✅ 개수만 필요하면 객체를 만들지 않는다
func countOnly(_ ctx: NSManagedObjectContext) throws -> Int {
    try ctx.count(for: Post.fetchRequest())    // 객체 생성 없이 SELECT COUNT
}

// ✅ 특정 컬럼만 필요하면 dictionary 결과로
func titlesOnly(_ ctx: NSManagedObjectContext) throws -> [String] {
    let request = NSFetchRequest<NSDictionary>(entityName: "Post")
    request.resultType = .dictionaryResultType
    request.propertiesToFetch = ["title"]
    return try ctx.fetch(request).compactMap { $0["title"] as? String }
}

// ⚠️ ② 저장 타이밍 — save()를 부르기 전까지는 아무것도 디스크에 없다
func saveTiming(_ ctx: NSManagedObjectContext) throws {
    let post = Post(context: ctx)
    post.title = "제목"
    // 여기서 앱이 죽으면 이 변경은 사라진다
    try ctx.save()                              // ✅ 여기서 트랜잭션이 커밋된다
}

// ⚠️ ③ 컨텍스트 수명 — 객체는 자기 컨텍스트에 묶여 있다
//    컨텍스트가 해제되면 그 객체들도 무효가 된다

final class Post: NSManagedObject {
    @NSManaged var title: String
    @NSManaged var author: Author?
    @nonobjc class func fetchRequest() -> NSFetchRequest<Post> {
        NSFetchRequest<Post>(entityName: "Post")
    }
}
final class Author: NSManagedObject { @NSManaged var name: String }

let bg = container.newBackgroundContext()
let objectID = person.objectID          // main 컨텍스트의 객체에서 ID만 추출 (불변·스레드 안전, 넘기기 안전)

bg.perform {                            // 반드시 이 컨텍스트의 큐 위에서 실행
    guard let obj = try? bg.existingObject(with: objectID) else { return }
    obj.setValue("done", forKey: "status")
    try? bg.save()                      // 이 save() 가 하나의 트랜잭션
}

// ❌ 절대 금지: 다른 스레드에서 만든 NSManagedObject 를 그대로 참조
// DispatchQueue.global().async { print(person.name) }   // objectID 아님 → 크래시/데이터 손상

import CoreData

// NSManagedObjectContext와 거기서 나온 객체는 자기 큐에서만 만져야 한다.
// 이 규칙을 어기면 조용히 데이터가 손상되거나 무작위 크래시가 난다.

final class Repository {
    private let container: NSPersistentContainer
    init(container: NSPersistentContainer) { self.container = container }

    // ❌ 컨텍스트를 지역 변수로 붙잡아 아무 데서나 사용
    func updateBad(_ id: NSManagedObjectID) {
        let ctx = container.newBackgroundContext()
        DispatchQueue.global().async {
            let obj = try? ctx.existingObject(with: id)   // 💥 그 큐가 아니다
            obj?.setValue("done", forKey: "status")
            try? ctx.save()
        }
    }

    // ✅ 반드시 그 컨텍스트의 큐 위에서
    func update(_ id: NSManagedObjectID) async throws {
        let ctx = container.newBackgroundContext()
        try await ctx.perform {
            guard let obj = try? ctx.existingObject(with: id) else { return }
            obj.setValue("done", forKey: "status")
            try ctx.save()
        }
    }

    // ✅ 동기 버전이 필요하면 performAndWait
    func updateSync(_ id: NSManagedObjectID) throws {
        let ctx = container.newBackgroundContext()
        try ctx.performAndWait {
            guard let obj = try? ctx.existingObject(with: id) else { return }
            obj.setValue("done", forKey: "status")
            try ctx.save()
        }
    }

    // ✅ viewContext도 예외가 아니다 — 메인 큐에서만
    @MainActor
    func readOnMain() throws -> Int {
        let request = NSFetchRequest<NSFetchRequestResult>(entityName: "Item")
        return try container.viewContext.count(for: request)
    }
}

// ⚠️ .privateQueueConcurrencyType 컨텍스트는 '자기만의 전용 큐'를 갖는다.
//    그 큐가 매번 같은 스레드라는 보장은 없다 — 그래서 perform이 필요하다.

import CoreData

// NSManagedObject는 컨텍스트에 묶여 있다. 다른 컨텍스트·스레드로 넘기면
// 크래시하거나 데이터가 깨진다. 넘길 수 있는 건 objectID뿐이다.

final class SyncService {
    private let container: NSPersistentContainer
    init(container: NSPersistentContainer) { self.container = container }

    @MainActor
    func upload(_ post: Post) async throws {
        // ✅ ① 메인에서 ID만 뽑는다 (불변·스레드 안전)
        let objectID = post.objectID

        // ✅ ② 백그라운드 컨텍스트에서 다시 조회한다
        let bg = container.newBackgroundContext()
        try await bg.perform {
            guard let local = try? bg.existingObject(with: objectID) as? Post else { return }
            local.syncedAt = Date()
            try bg.save()
        }
    }

    // ❌ 절대 금지
    func uploadBad(_ post: Post) {
        DispatchQueue.global().async {
            print(post.title)          // 💥 다른 큐에서 접근
        }
    }
}

// ⚠️ save() 전의 objectID는 '임시 ID'다 — 다른 컨텍스트에서 못 찾는다
func permanentIDBeforeHandoff(_ ctx: NSManagedObjectContext,
                              _ object: NSManagedObject) throws -> NSManagedObjectID {
    if object.objectID.isTemporaryID {
        try ctx.obtainPermanentIDs(for: [object])   // ✅ 영구 ID를 먼저 확보
    }
    return object.objectID
}

// ✅ 값만 필요하면 아예 DTO로 변환해 넘긴다 — 가장 안전하다
struct PostDTO: Sendable {
    let id: UUID
    let title: String

    @MainActor init(_ post: Post) {
        id = post.id
        title = post.title
    }
}

final class Post: NSManagedObject {
    @NSManaged var id: UUID
    @NSManaged var title: String
    @NSManaged var syncedAt: Date?
}

import CoreData

// UI는 viewContext(main), 쓰기·import는 background로 나눈다.
// 두 컨텍스트가 같은 객체를 건드리면 충돌하므로 병합 정책을 명시해야 한다.

final class CoreDataStack {
    let container: NSPersistentContainer

    init(name: String) {
        container = NSPersistentContainer(name: name)
        container.loadPersistentStores { _, error in
            precondition(error == nil)
        }

        // ✅ 백그라운드 저장이 viewContext에 자동 반영되게 한다
        container.viewContext.automaticallyMergesChangesFromParent = true

        // ✅ 충돌 시 어느 쪽을 이길지 명시한다 (기본은 error를 던진다)
        container.viewContext.mergePolicy = NSMergeByPropertyStoreTrumpMergePolicy
        //   StoreTrump  : 디스크(다른 컨텍스트가 저장한 것)가 이긴다  ← 읽기 전용 UI에 적합
        //   ObjectTrump : 메모리(내 변경)가 이긴다                    ← 편집 화면에 적합

        container.viewContext.undoManager = nil          // UI에서 안 쓰면 끈다(성능)
    }

    /// 쓰기 전용 백그라운드 컨텍스트
    func newWriteContext() -> NSManagedObjectContext {
        let ctx = container.newBackgroundContext()
        ctx.mergePolicy = NSMergeByPropertyObjectTrumpMergePolicy
        ctx.automaticallyMergesChangesFromParent = true
        return ctx
    }

    /// 대량 import — 병합 부담을 줄이려고 자동 병합을 끈다
    func newImportContext() -> NSManagedObjectContext {
        let ctx = container.newBackgroundContext()
        ctx.mergePolicy = NSMergeByPropertyObjectTrumpMergePolicy
        ctx.automaticallyMergesChangesFromParent = false
        ctx.undoManager = nil
        return ctx
    }
}

// ⚠️ 병합 정책을 안 정하면 충돌 시 save()가 throw한다.
//    "가끔 저장이 실패한다"의 흔한 원인이다.

import CoreData

// Core Data의 동시성 위반은 즉시 크래시하지 않고 '나중에 이상하게' 나타난다.
// 이 플래그를 켜면 위반 시점에 바로 멈춰 준다.

/*  설정 방법
      Xcode → Product → Scheme → Edit Scheme
        → Run → Arguments → Arguments Passed On Launch
          -com.apple.CoreData.ConcurrencyDebug 1

    켜 두면 잘못된 큐에서 컨텍스트·객체에 접근하는 순간
    __Multithreading_Violation_AllThatIsLeftToUsIsHonor 에서 정지한다.       */

// ✅ CI 테스트에서도 켠다
//    테스트 플랜(.xctestplan)의 Configurations → Arguments Passed On Launch 에
//    -com.apple.CoreData.ConcurrencyDebug 1 을 넣고 xcodebuild test -testPlan <플랜이름> 으로 돌린다
//    (xcodebuild에 -- 로 인자를 직접 붙이는 경로는 없다)

// ✅ 함께 켜면 좋은 다른 디버그 플래그들
/*
    -com.apple.CoreData.SQLDebug 1          실제 실행되는 SQL을 로그로 (1~4 단계)
    -com.apple.CoreData.MigrationDebug 1    마이그레이션 과정 상세 로그
    -com.apple.CoreData.Logging.stderr 1    로그를 stderr로
*/

// ✅ SQLDebug로 N+1을 눈으로 확인할 수 있다
func detectNPlusOne(_ ctx: NSManagedObjectContext) throws {
    // SQLDebug 1을 켜고 이 코드를 돌리면 콘솔에 SELECT가 몇 번 나가는지 보인다
    let posts = try ctx.fetch(NSFetchRequest<NSManagedObject>(entityName: "Post"))
    for post in posts {
        _ = post.value(forKey: "author")     // 여기서 매번 SELECT가 찍히면 N+1
    }
}

// ✅ 코드로도 방어선을 둔다
extension NSManagedObjectContext {
    func assertCorrectQueue() {
        #if DEBUG
        // ⚠️ 이 검사는 viewContext(메인 큐 컨텍스트)의 메인 스레드 접근만 잡는다.
        //    private 큐 컨텍스트는 조건이 항상 참이라 perform 밖에서 만져도 통과한다 —
        //    그건 -com.apple.CoreData.ConcurrencyDebug 1 에 의존해야 한다.
        precondition(concurrencyType != .mainQueueConcurrencyType || Thread.isMainThread,
                     "viewContext를 메인이 아닌 곳에서 접근했다")
        #endif
    }
}