create-entity-server 0.0.9

package/template/samples/react/src/hooks/useEntity.ts

@@ -0,0 +1,105 @@
+/**
+ * Entity Server React 훅
+ *
+ * @tanstack/react-query 기반
+ * 설치: npm install @tanstack/react-query
+ */
+
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import type {
+    EntityListParams,
+    EntityQueryFilter,
+} from "../api/entityServerClient";
+import { entityServer } from "../api/entityServerClient";
+
+// ─── 조회 훅 ─────────────────────────────────────────────────────────────────
+
+/** 단건 조회 */
+export function useEntityGet<T = unknown>(entity: string, seq: number | null) {
+    return useQuery({
+        queryKey: ["entity", entity, seq],
+        queryFn: () => entityServer.get<T>(entity, seq!),
+        enabled: seq != null,
+    });
+}
+
+/** 목록 조회 */
+export function useEntityList<T = unknown>(
+    entity: string,
+    params: EntityListParams = {},
+) {
+    return useQuery({
+        queryKey: ["entity", entity, "list", params],
+        queryFn: () => entityServer.list<T>(entity, params),
+    });
+}
+
+/** 건수 조회 */
+export function useEntityCount(entity: string) {
+    return useQuery({
+        queryKey: ["entity", entity, "count"],
+        queryFn: () => entityServer.count(entity),
+    });
+}
+
+/** 필터 검색 */
+export function useEntityQuery<T = unknown>(
+    entity: string,
+    filter: EntityQueryFilter[],
+    params: EntityListParams = {},
+) {
+    return useQuery({
+        queryKey: ["entity", entity, "query", filter, params],
+        queryFn: () => entityServer.query<T>(entity, filter, params),
+        enabled: filter.length > 0,
+    });
+}
+
+/** 변경 이력 조회 */
+export function useEntityHistory<T = unknown>(
+    entity: string,
+    seq: number | null,
+) {
+    return useQuery({
+        queryKey: ["entity", entity, seq, "history"],
+        queryFn: () => entityServer.history<T>(entity, seq!),
+        enabled: seq != null,
+    });
+}
+
+// ─── 뮤테이션 훅 ─────────────────────────────────────────────────────────────
+
+/** 생성 또는 수정 */
+export function useEntitySubmit(entity: string) {
+    const qc = useQueryClient();
+    return useMutation({
+        mutationFn: (data: Record<string, unknown>) =>
+            entityServer.submit(entity, data),
+        onSuccess: () => {
+            qc.invalidateQueries({ queryKey: ["entity", entity] });
+        },
+    });
+}
+
+/** 삭제 */
+export function useEntityDelete(entity: string) {
+    const qc = useQueryClient();
+    return useMutation({
+        mutationFn: (seq: number) => entityServer.delete(entity, seq),
+        onSuccess: () => {
+            qc.invalidateQueries({ queryKey: ["entity", entity] });
+        },
+    });
+}
+
+/** 롤백 */
+export function useEntityRollback(entity: string) {
+    const qc = useQueryClient();
+    return useMutation({
+        mutationFn: (historySeq: number) =>
+            entityServer.rollback(entity, historySeq),
+        onSuccess: () => {
+            qc.invalidateQueries({ queryKey: ["entity", entity] });
+        },
+    });
+}

package/template/samples/swift/EntityServerClient.swift

@@ -0,0 +1,221 @@
+/**
+ * Entity Server 클라이언트 (Swift / iOS)
+ *
+ * 의존성 (Package.swift / SPM):
+ *   .package(url: "https://github.com/krzyzanowskim/CryptoSwift.git", from: "1.8.0")
+ *
+ * HMAC API Key 인증 방식 사용 예:
+ *   let client = EntityServerClient(
+ *       baseUrl:    "http://your-server:47200",
+ *       apiKey:     "your-api-key",
+ *       hmacSecret: "your-hmac-secret",
+ *       magicLen:   4   // 서버 packet_magic_len 과 동일
+ *   )
+ *   let result = try await client.list("product")
+ *
+ * 트랜잭션 사용 예:
+ *   try await es.transStart()
+ *   do {
+ *     let orderRef  = try await es.submit(entity: "order", data: ["user_seq": 1, "total": 9900])  // seq: "$tx.0"
+ *     try await es.submit(entity: "order_item",
+ *         data: ["order_seq": orderRef["seq"] as Any, "item_seq": 5])                            // "$tx.0" 자동 치환
+ *     let result    = try await es.transCommit()
+ *     let orderSeq  = (result["results"] as? [[String: Any]])?[0]["seq"]                        // 실제 seq
+ *   } catch {
+ *     try? await es.transRollback()
+ *   }
+ */
+
+import CryptoSwift
+import Foundation
+
+public final class EntityServerClient {
+    private let baseURL: URL
+    private let apiKey: String
+    private let hmacSecret: String
+    private let magicLen: Int
+    private let session: URLSession
+    private var activeTxId: String? = nil
+
+    public init(
+        baseUrl: String = "http://localhost:47200",
+        apiKey: String = "",
+        hmacSecret: String = "",
+        magicLen: Int = 4,
+        session: URLSession = .shared
+    ) {
+        self.baseURL = URL(string: baseUrl.removingSuffix("/"))!
+        self.apiKey = apiKey
+        self.hmacSecret = hmacSecret
+        self.magicLen = magicLen
+        self.session = session
+    }
+
+    // ─── CRUD ─────────────────────────────────────────────────────────
+
+    public func get(entity: String, seq: Int64) async throws -> [String: Any] {
+        try await request(method: "GET", path: "/v1/entity/\(entity)/\(seq)")
+    }
+
+    public func list(entity: String, page: Int = 1, limit: Int = 20) async throws -> [String: Any] {
+        try await request(method: "GET", path: "/v1/entity/\(entity)/list?page=\(page)&limit=\(limit)")
+    }
+
+    public func count(entity: String) async throws -> [String: Any] {
+        try await request(method: "GET", path: "/v1/entity/\(entity)/count")
+    }
+
+    public func query(entity: String, filter: [[String: Any]], page: Int = 1, limit: Int = 20) async throws -> [String: Any] {
+        let body = try JSONSerialization.data(withJSONObject: filter)
+        return try await request(method: "POST", path: "/v1/entity/\(entity)/query?page=\(page)&limit=\(limit)", body: body)
+    }
+
+    /// 트랜잭션 시작 — 서버에 트랜잭션 큐를 등록하고 transaction_id 를 반환합니다.
+    /// 이후 submit / delete 가 서버 큐에 쌓이고 transCommit() 시 일괄 처리됩니다.
+    public func transStart() async throws -> String {
+        let res = try await request(method: "POST", path: "/v1/transaction/start")
+        guard let txId = res["transaction_id"] as? String else {
+            throw NSError(domain: "EntityServerClient", code: -1,
+                          userInfo: [NSLocalizedDescriptionKey: "transStart: server did not return transaction_id"])
+        }
+        activeTxId = txId
+        return txId
+    }
+
+    /// 트랜잭션 전체 롤백
+    /// transactionId 생략 시 transStart() 로 시작한 활성 트랜잭션을 롤백합니다.
+    public func transRollback(transactionId: String? = nil) async throws -> [String: Any] {
+        guard let txId = transactionId ?? activeTxId else {
+            throw NSError(domain: "EntityServerClient", code: -1,
+                          userInfo: [NSLocalizedDescriptionKey: "No active transaction. Call transStart() first."])
+        }
+        activeTxId = nil
+        return try await request(method: "POST", path: "/v1/transaction/rollback/\(txId)")
+    }
+
+    /// 트랜잭션 커밋 — 서버 큐에 쌓인 작업을 단일 DB 트랜잭션으로 일괄 처리합니다.
+    /// transactionId 생략 시 transStart() 로 시작한 활성 트랜잭션을 사용합니다.
+    public func transCommit(transactionId: String? = nil) async throws -> [String: Any] {
+        guard let txId = transactionId ?? activeTxId else {
+            throw NSError(domain: "EntityServerClient", code: -1,
+                          userInfo: [NSLocalizedDescriptionKey: "No active transaction. Call transStart() first."])
+        }
+        activeTxId = nil
+        return try await request(method: "POST", path: "/v1/transaction/commit/\(txId)")
+    }
+
+    public func submit(entity: String, data: [String: Any], transactionId: String? = nil) async throws -> [String: Any] {
+        let body = try JSONSerialization.data(withJSONObject: data)
+        var extra: [String: String] = [:]
+        if let txId = transactionId ?? activeTxId { extra["X-Transaction-ID"] = txId }
+        return try await request(method: "POST", path: "/v1/entity/\(entity)/submit", body: body, extraHeaders: extra)
+    }
+
+    public func delete(entity: String, seq: Int64, transactionId: String? = nil, hard: Bool = false) async throws -> [String: Any] {
+        let q = hard ? "?hard=true" : ""
+        var extra: [String: String] = [:]
+        if let txId = transactionId ?? activeTxId { extra["X-Transaction-ID"] = txId }
+        return try await request(method: "DELETE", path: "/v1/entity/\(entity)/delete/\(seq)\(q)", extraHeaders: extra)
+    }
+
+    public func history(entity: String, seq: Int64, page: Int = 1, limit: Int = 50) async throws -> [String: Any] {
+        try await request(method: "GET", path: "/v1/entity/\(entity)/history/\(seq)?page=\(page)&limit=\(limit)")
+    }
+
+    public func rollback(entity: String, historySeq: Int64) async throws -> [String: Any] {
+        try await request(method: "POST", path: "/v1/entity/\(entity)/rollback/\(historySeq)")
+    }
+
+    // ─── 내부 ─────────────────────────────────────────────────────────
+
+    private func request(method: String, path: String, body: Data? = nil, extraHeaders: [String: String] = [:]) async throws -> [String: Any] {
+        let url = baseURL.appendingPathComponent(path, isDirectory: false)
+        var req = URLRequest(url: url)
+        req.httpMethod = method
+
+        let bodyStr = body.map { String(data: $0, encoding: .utf8) ?? "" } ?? ""
+        let timestamp = String(Int(Date().timeIntervalSince1970))
+        let nonce = UUID().uuidString
+        let signature = try sign(method: method, path: path, timestamp: timestamp, nonce: nonce, body: bodyStr)
+
+        req.setValue("application/json", forHTTPHeaderField: "Content-Type")
+        req.setValue(apiKey, forHTTPHeaderField: "X-API-Key")
+        req.setValue(timestamp, forHTTPHeaderField: "X-Timestamp")
+        req.setValue(nonce, forHTTPHeaderField: "X-Nonce")
+        req.setValue(signature, forHTTPHeaderField: "X-Signature")
+        extraHeaders.forEach { req.setValue($0.value, forHTTPHeaderField: $0.key) }
+        req.httpBody = body
+
+        let (data, response) = try await session.data(for: req)
+        let http = response as! HTTPURLResponse
+        let contentType = http.value(forHTTPHeaderField: "Content-Type") ?? ""
+
+        // 패킷 암호화 응답: application/octet-stream → 복호화
+        if contentType.contains("application/octet-stream") {
+            return try decryptPacket(data)
+        }
+
+        guard let json = try JSONSerialization.jsonObject(with: data) as? [String: Any] else {
+            throw EntityServerError.invalidResponse
+        }
+        return json
+    }
+
+    /**
+     * XChaCha20-Poly1305 패킷 복호화
+     * 포맷: [magic:magicLen][nonce:24][ciphertext+tag]
+     * 키: sha256(hmac_secret)
+     */
+    private func decryptPacket(_ data: Data) throws -> [String: Any] {
+        let key = Array(SHA2(variant: .sha256).calculate(for: Array(hmacSecret.utf8)))
+        let bytes = Array(data)
+        let nonce = Array(bytes[magicLen..<(magicLen + 24)])
+        let ciphertext = Array(bytes[(magicLen + 24)...])
+
+        // XChaCha20-Poly1305 복호화 (tag는 ciphertext 마지막 16바이트)
+        let xchacha = XChaCha20Poly1305(key: key, iv: nonce, aad: [])
+        let plaintext = try xchacha.decrypt(ciphertext)
+
+        guard let json = try JSONSerialization.jsonObject(with: Data(plaintext)) as? [String: Any] else {
+            throw EntityServerError.decryptionFailed
+        }
+        return json
+    }
+
+    /** HMAC-SHA256 서명 */
+    private func sign(method: String, path: String, timestamp: String, nonce: String, body: String) throws -> String {
+        let payload = [method, path, timestamp, nonce, body].joined(separator: "|")
+        let mac = try HMAC(key: Array(hmacSecret.utf8), variant: .sha256).authenticate(Array(payload.utf8))
+        return mac.map { String(format: "%02x", $0) }.joined()
+    }
+}
+
+// MARK: - XChaCha20Poly1305 helper (CryptoSwift wrapper)
+private struct XChaCha20Poly1305 {
+    let key: [UInt8]
+    let iv: [UInt8]
+    let aad: [UInt8]
+
+    func decrypt(_ ciphertext: [UInt8]) throws -> [UInt8] {
+        // CryptoSwift ChaCha20.Poly1305 AEAD - tag는 마지막 16바이트
+        let tag = Array(ciphertext.suffix(16))
+        let ct  = Array(ciphertext.dropLast(16))
+        let chacha = try ChaCha20(key: key, iv: iv)
+        let decrypted = try chacha.decrypt(ct)
+        // Poly1305 태그 검증
+        let poly = try Poly1305(key: chacha.keystream().prefix(32)).authenticate(ct + aad)
+        guard poly == tag else { throw EntityServerError.decryptionFailed }
+        return decrypted
+    }
+}
+
+public enum EntityServerError: Error {
+    case invalidResponse
+    case decryptionFailed
+}
+
+private extension String {
+    func removingSuffix(_ suffix: String) -> String {
+        hasSuffix(suffix) ? String(dropLast(suffix.count)) : self
+    }
+}

package/template/scripts/api-key.ps1

@@ -0,0 +1,123 @@
+# API Key Management Script (CLI mode) - Windows PowerShell
+# Can be used even when the server is stopped.
+param(
+    [Parameter(Position=0)]
+    [string]$SubCommand = ""
+)
+
+$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+$ProjectRoot = Split-Path -Parent $ScriptDir
+$BinPath = Join-Path $ProjectRoot "bin\entity-cli.exe"
+
+Set-Location $ProjectRoot
+
+# Load language from .env
+$Language = "ko"
+$EnvFile = Join-Path $ProjectRoot ".env"
+if (Test-Path $EnvFile) {
+    $LangLine = Get-Content $EnvFile | Where-Object { $_ -match '^LANGUAGE=' } | Select-Object -First 1
+    if ($LangLine) { $Language = $LangLine -replace '^LANGUAGE=', '' }
+}
+
+function Show-Help {
+    if ($Language -eq "en") {
+        Write-Host "API Key Management (CLI mode)"
+        Write-Host "============================="
+        Write-Host ""
+        Write-Host "Manage api_keys entity directly via CLI binary."
+        Write-Host "Server does NOT need to be running."
+        Write-Host ""
+        Write-Host "Usage: .\api-key.ps1 <subcommand> [options]"
+        Write-Host ""
+        Write-Host "Subcommands:"
+        Write-Host "  list              List API keys"
+        Write-Host "  add               Create a new API key (key/secret auto-generated)"
+        Write-Host "  delete            Delete an API key by seq"
+        Write-Host "  help              Show this help"
+        Write-Host ""
+        Write-Host "list options:"
+        Write-Host "  --limit=<n>       Max rows to show (default: 20)"
+        Write-Host ""
+        Write-Host "add options:"
+        Write-Host "  --role=<name>     Role name (default: admin)"
+        Write-Host "  --entities=<json> Allowed entities JSON (default: [`"*`"])"
+        Write-Host "  --description=<t> Description"
+        Write-Host "  --user-seq=<n>    Associated user seq"
+        Write-Host "  --apply           Execute (default is dry-run)"
+        Write-Host ""
+        Write-Host "delete options:"
+        Write-Host "  --seq=<n>         API key seq to delete (required)"
+        Write-Host "  --apply           Execute (default is dry-run)"
+        Write-Host ""
+        Write-Host "Examples:"
+        Write-Host "  .\api-key.ps1 list"
+        Write-Host "  .\api-key.ps1 list --limit=50"
+        Write-Host "  .\api-key.ps1 add --role=admin --apply"
+        Write-Host "  .\api-key.ps1 delete --seq=3 --apply"
+    } else {
+        Write-Host "API 키 관리 (CLI 모드)"
+        Write-Host "===================="
+        Write-Host ""
+        Write-Host "CLI 바이너리로 api_keys 엔티티를 직접 조작합니다."
+        Write-Host "서버가 실행 중이지 않아도 사용 가능합니다."
+        Write-Host ""
+        Write-Host "사용법: .\api-key.ps1 <하위명령> [옵션]"
+        Write-Host ""
+        Write-Host "하위 명령:"
+        Write-Host "  list              API 키 목록 조회"
+        Write-Host "  add               새 API 키 생성 (키/시크릿 자동 생성)"
+        Write-Host "  delete            API 키 삭제 (seq 지정)"
+        Write-Host "  help              도움말 출력"
+        Write-Host ""
+        Write-Host "list 옵션:"
+        Write-Host "  --limit=<n>       최대 출력 행 수 (기본: 20)"
+        Write-Host ""
+        Write-Host "add 옵션:"
+        Write-Host "  --role=<이름>     역할명 (기본: admin)"
+        Write-Host "  --entities=<json> 허용 엔티티 JSON (기본: [`"*`"])"
+        Write-Host "  --description=<t> 설명"
+        Write-Host "  --user-seq=<n>    연결 사용자 seq"
+        Write-Host "  --apply           실제 실행 (기본: dry-run)"
+        Write-Host ""
+        Write-Host "delete 옵션:"
+        Write-Host "  --seq=<n>         삭제할 API 키 seq (필수)"
+        Write-Host "  --apply           실제 실행 (기본: dry-run)"
+        Write-Host ""
+        Write-Host "예제:"
+        Write-Host "  .\api-key.ps1 list"
+        Write-Host "  .\api-key.ps1 list --limit=50"
+        Write-Host "  .\api-key.ps1 add --role=admin --apply"
+        Write-Host "  .\api-key.ps1 delete --seq=3 --apply"
+    }
+}
+
+if (-not $SubCommand) {
+    Show-Help
+    exit 0
+}
+
+if (-not (Test-Path $BinPath)) {
+    if ($Language -eq "en") { Write-Host "X bin/entity-cli.exe not found. Run: .\scripts\build.ps1" }
+    else { Write-Host "X bin/entity-cli.exe 파일이 없습니다. 먼저 .\scripts\build.ps1 를 실행하세요." }
+    exit 1
+}
+
+# Collect remaining args (all args after SubCommand)
+$remainingArgs = $args
+
+switch ($SubCommand) {
+    { $_ -in @("list", "show", "add", "delete") } {
+        $env:ENTITY_CLI_NAME = "api-key"
+        & $BinPath api-key $SubCommand @remainingArgs
+    }
+    { $_ -in @("help", "-h", "--help") } {
+        Show-Help
+    }
+    default {
+        if ($Language -eq "en") { Write-Host "X Unknown subcommand: $SubCommand" }
+        else { Write-Host "X 알 수 없는 하위 명령: $SubCommand" }
+        Write-Host ""
+        Show-Help
+        exit 1
+    }
+}

package/template/scripts/api-key.sh

@@ -0,0 +1,130 @@
+#!/bin/bash
+# API 키 관리 스크립트 (CLI 바이너리 직접 호출)
+# 서버가 중단된 상태에서도 사용 가능합니다.
+# HTTP API 방식은 api-keys.sh 를 사용하세요.
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
+BIN_PATH="$PROJECT_ROOT/bin/entity-cli"
+
+cd "$PROJECT_ROOT"
+
+# Load language from .env
+if [ -f .env ]; then
+    LANGUAGE=$(grep '^LANGUAGE=' .env | cut -d '=' -f2)
+fi
+LANGUAGE=${LANGUAGE:-ko}
+
+show_help() {
+    if [ "$LANGUAGE" = "en" ]; then
+        echo "API Key Management (CLI mode)"
+        echo "============================="
+        echo ""
+        echo "Manage api_keys entity directly via CLI binary."
+        echo "Server does NOT need to be running."
+        echo ""
+        echo "Usage: $0 <subcommand> [options]"
+        echo ""
+        echo "Subcommands:"
+        echo "  list              List API keys"
+        echo "  add               Create a new API key (key/secret auto-generated)"
+        echo "  delete            Delete an API key by seq"
+        echo "  help              Show this help"
+        echo ""
+        echo "list options:"
+        echo "  --limit=<n>       Max rows to show (default: 20)"
+        echo ""
+        echo "add options:"
+        echo "  --role=<name>     Role name (default: admin)"
+        echo "  --entities=<json> Allowed entities JSON (default: [\"*\"])"
+        echo "  --description=<t> Description"
+        echo "  --user-seq=<n>    Associated user seq"
+        echo "  --apply           Execute (default is dry-run)"
+        echo ""
+        echo "delete options:"
+        echo "  --seq=<n>         API key seq to delete (required)"
+        echo "  --apply           Execute (default is dry-run)"
+        echo ""
+        echo "Examples:"
+        echo "  $0 list"
+        echo "  $0 list --limit=50"
+        echo "  $0 add --role=admin --apply"
+        echo "  $0 add --role=viewer --entities='[\"user\",\"product\"]' --description=\"Viewer key\" --apply"
+        echo "  $0 add --role=admin --user-seq=1 --apply"
+        echo "  $0 delete --seq=3 --apply"
+    else
+        echo "API 키 관리 (CLI 모드)"
+        echo "===================="
+        echo ""
+        echo "CLI 바이너리로 api_keys 엔티티를 직접 조작합니다."
+        echo "서버가 실행 중이지 않아도 사용 가능합니다."
+        echo ""
+        echo "사용법: $0 <하위명령> [옵션]"
+        echo ""
+        echo "하위 명령:"
+        echo "  list              API 키 목록 조회"
+        echo "  add               새 API 키 생성 (키/시크릿 자동 생성)"
+        echo "  delete            API 키 삭제 (seq 지정)"
+        echo "  help              도움말 출력"
+        echo ""
+        echo "list 옵션:"
+        echo "  --limit=<n>       최대 출력 행 수 (기본: 20)"
+        echo ""
+        echo "add 옵션:"
+        echo "  --role=<이름>     역할명 (기본: admin)"
+        echo "  --entities=<json> 허용 엔티티 JSON (기본: [\"*\"])"
+        echo "  --description=<t> 설명"
+        echo "  --user-seq=<n>    연결 사용자 seq"
+        echo "  --apply           실제 실행 (기본: dry-run)"
+        echo ""
+        echo "delete 옵션:"
+        echo "  --seq=<n>         삭제할 API 키 seq (필수)"
+        echo "  --apply           실제 실행 (기본: dry-run)"
+        echo ""
+        echo "예제:"
+        echo "  $0 list"
+        echo "  $0 list --limit=50"
+        echo "  $0 add --role=admin --apply"
+        echo "  $0 add --role=viewer --entities='[\"user\",\"product\"]' --description=\"뷰어 키\" --apply"
+        echo "  $0 add --role=admin --user-seq=1 --apply"
+        echo "  $0 delete --seq=3 --apply"
+    fi
+}
+
+# 인자 없으면 도움말
+if [ $# -eq 0 ]; then
+    show_help
+    exit 0
+fi
+
+# CLI 바이너리 존재 확인
+if [ ! -f "$BIN_PATH" ]; then
+    if [ "$LANGUAGE" = "en" ]; then
+        echo "❌ bin/entity-cli not found. Run: ./scripts/build.sh"
+    else
+        echo "❌ bin/entity-cli 파일이 없습니다. 먼저 ./scripts/build.sh 를 실행하세요."
+    fi
+    exit 1
+fi
+
+SUBCOMMAND="$1"
+shift
+
+case "$SUBCOMMAND" in
+    list|show|add|delete)
+        ENTITY_CLI_NAME="api-key" "$BIN_PATH" api-key "$SUBCOMMAND" "$@"
+        ;;
+    help|-h|--help)
+        show_help
+        ;;
+    *)
+        if [ "$LANGUAGE" = "en" ]; then
+            echo "❌ Unknown subcommand: $SUBCOMMAND"
+        else
+            echo "❌ 알 수 없는 하위 명령: $SUBCOMMAND"
+        fi
+        echo ""
+        show_help
+        exit 1
+        ;;
+esac

package/template/scripts/cleanup-history.ps1

@@ -0,0 +1,69 @@
+# cleanup-history.ps1 — history_ttl 기준 이력 정리
+#
+# 사용법:
+#   .\scripts\cleanup-history.ps1                        # 도움말
+#   .\scripts\cleanup-history.ps1 --apply                # 전체 이력 정리 실행
+#   .\scripts\cleanup-history.ps1 --entity=account       # dry-run (특정 엔티티)
+#   .\scripts\cleanup-history.ps1 --entity=account --apply
+
+param(
+    [string]$Entity = "",
+    [switch]$Apply
+)
+
+$ErrorActionPreference = "Stop"
+
+$ProjectRoot = Split-Path -Parent $PSScriptRoot
+Set-Location $ProjectRoot
+
+# LANGUAGE 로드
+$Lang = $env:LANGUAGE
+if (-not $Lang) {
+    $EnvFile = Join-Path $ProjectRoot ".env"
+    if (Test-Path $EnvFile) {
+        $line = Get-Content $EnvFile | Where-Object { $_ -match '^LANGUAGE=' } | Select-Object -Last 1
+        if ($line) { $Lang = $line -replace '^LANGUAGE=', '' }
+    }
+}
+if (-not $Lang) { $Lang = "ko" }
+
+function Show-Help {
+    if ($Lang -eq "en") {
+        Write-Host "History TTL Cleanup"
+        Write-Host "==================="
+        Write-Host ""
+        Write-Host "Usage: .\scripts\cleanup-history.ps1 [-Entity <name>] [-Apply]"
+        Write-Host ""
+        Write-Host "Options:"
+        Write-Host "  -Entity <name>   Cleanup only one entity history"
+        Write-Host "  -Apply           Execute delete (default: dry-run)"
+    } else {
+        Write-Host "히스토리 TTL 정리"
+        Write-Host "================"
+        Write-Host ""
+        Write-Host "사용법: .\scripts\cleanup-history.ps1 [-Entity <이름>] [-Apply]"
+        Write-Host ""
+        Write-Host "옵션:"
+        Write-Host "  -Entity <이름>   특정 엔티티 히스토리만 정리"
+        Write-Host "  -Apply           실제 삭제 실행 (기본: dry-run)"
+    }
+}
+
+# 인자 없으면 도움말
+if (-not $Apply -and -not $Entity) {
+    Show-Help
+    exit 0
+}
+
+$CliBin = Join-Path $ProjectRoot "entity-cli.exe"
+if (-not (Test-Path $CliBin)) {
+    if ($Lang -eq "en") { Write-Error "❌ entity-cli.exe not found" }
+    else                { Write-Error "❌ entity-cli.exe 파일이 없습니다" }
+    exit 1
+}
+
+$Args = @("cleanup-history")
+if ($Entity) { $Args += "--entity=$Entity" }
+if ($Apply)  { $Args += "--apply" }
+
+& $CliBin @Args