create-entity-server 0.0.23 → 0.0.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-entity-server",
-  "version": "0.0.23",
+  "version": "0.0.26",
   "description": "Create a new entity-server project in one command — like create-react-app or create-vite.",
   "keywords": [
     "entity-server",

package/template/.env.example

@@ -11,6 +11,10 @@ ENCRYPTION_KEY=your-32-char-hex-encryption-key-here
 # 운영에서는 충분히 긴 랜덤 시크릿을 사용하세요.
 JWT_SECRET=your-jwt-secret-here
 
+# 백업 암호화 키 (backup.json의 ${BACKUP_ENCRYPT_KEY}와 매핑)
+# 비워두면 암호화 비활성화. 설정 시 충분한 길이의 랜덤 문자열 권장.
+# BACKUP_ENCRYPT_KEY=your-backup-encryption-key-here
+
 # 서버 포트 (configs/server.json의 port를 오버라이드)
 SERVER_PORT=47200
 
@@ -27,5 +31,13 @@ DB_NAME_PRODUCTION=your-production-db-name
 DB_USER_PRODUCTION=your-production-db-user
 DB_PASSWORD_PRODUCTION=your-production-db-password
 
+# SMTP 이메일 (smtp.json에서 ${SMTP_USERNAME} 등으로 참조)
+# SMTP_USERNAME=user@gmail.com
+# SMTP_PASSWORD=your-app-specific-password
+# SENDGRID_API_KEY=SG.xxxx...
+# SES_SMTP_USERNAME=your-ses-smtp-username
+# SES_SMTP_PASSWORD=your-ses-smtp-password
+# MAILGUN_SMTP_PASSWORD=your-mailgun-smtp-password
+
 # 푸시 알림 (push.json에서 ${FCM_PROJECT_ID} 등으로 참조 가능)
 # FCM_PROJECT_ID=your-firebase-project-id

package/template/configs/backup.json

@@ -0,0 +1,46 @@
+{
+    "enabled": false,
+
+    "data": {
+        "enabled": true,
+        "schedule": "0 2 * * *",
+        "db_groups": ["default"],
+        "entities": {
+            "include": [],
+            "exclude": [],
+            "exclude_patterns": ["*_log"]
+        },
+        "include_history": false,
+        "format": "jsonl",
+        "compress": true,
+        "encrypt_passphrase": "${BACKUP_ENCRYPT_KEY}",
+        "batch_size": 500,
+        "max_concurrent_entities": 3,
+        "retention": {
+            "keep_count": 7,
+            "keep_days": 30
+        }
+    },
+
+    "files": {
+        "enabled": true,
+        "mode": "realtime",
+        "max_retries": 3,
+        "retry_interval_sec": 60
+    },
+
+    "schema": {
+        "enabled": true
+    },
+
+    "target": {
+        "storage_key": "s3-backup",
+        "prefix": "backups"
+    },
+
+    "notification": {
+        "on_success": false,
+        "on_failure": true,
+        "channels": ["log", "smtp"]
+    }
+}

package/template/configs/database.json

@@ -1,17 +1,6 @@
-// ──────────────────────────────────────────────────────────────────────────
-// database.json 설정 예시 (주석 포함 예시 전용 파일 — 실제 파일은 순수 JSON)
-//
-// "default"     : 사용할 그룹 이름 (groups 키 중 하나)
-// "groups"      : 드라이버별 연결 설정 모음
-//   driver        : "mysql" | "postgres" | "mongodb" | "dynamodb" |
-//                   "firestore" | "scylladb" | "couchdb"
-//
-// 환경 변수 참조: "${ENV_VAR_NAME}" 형식으로 값을 주입합니다.
-// ──────────────────────────────────────────────────────────────────────────
 {
     "default": "development",
     "groups": {
-        // ── MySQL (SQL) ─────────────────────────────────────────────────
         "development": {
             "driver": "mysql",
             "host": "${DB_HOST_DEVELOPMENT}",
@@ -33,154 +22,6 @@
             "maxOpenConns": 50,
             "maxIdleConns": 25,
             "connMaxLifetimeSec": 3600
-        },
-
-        // ── MongoDB ─────────────────────────────────────────────────────
-        // URI 우선 사용. uri 가 없으면 host/port/database/username/password 조합.
-        "mongodb_dev": {
-            "driver": "mongodb",
-            "uri": "mongodb://localhost:27017/entity_dev",
-            "database": "entity_dev"
-        },
-        "mongodb_prod": {
-            "driver": "mongodb",
-            "host": "${MONGO_HOST}",
-            "port": 27017,
-            "database": "${MONGO_DB}",
-            "username": "${MONGO_USER}",
-            "password": "${MONGO_PASSWORD}",
-            "uri": ""
-        },
-        "mongodb_replica": {
-            "driver": "mongodb",
-            "uri": "mongodb://${MONGO_USER}:${MONGO_PASS}@mongo1:27017,mongo2:27017,mongo3:27017/${MONGO_DB}?replicaSet=rs0&authSource=admin",
-            "database": "${MONGO_DB}"
-        },
-
-        // ── Amazon DynamoDB ─────────────────────────────────────────────
-        // region 과 IAM 인증이 필요합니다.
-        // 로컬 테스트: endpoint 에 "http://localhost:8000" 지정.
-        "dynamodb_dev": {
-            "driver": "dynamodb",
-            "region": "ap-northeast-2",
-            "endpoint": "http://localhost:8000",
-            "access_key_id": "${AWS_ACCESS_KEY_ID}",
-            "secret_access_key": "${AWS_SECRET_ACCESS_KEY}"
-        },
-        "dynamodb_prod": {
-            "driver": "dynamodb",
-            "region": "${AWS_REGION}",
-            "access_key_id": "${AWS_ACCESS_KEY_ID}",
-            "secret_access_key": "${AWS_SECRET_ACCESS_KEY}"
-        },
-
-        // ── Google Cloud Firestore ──────────────────────────────────────
-        // GCP 프로젝트 ID 와 서비스 계정 JSON 파일(또는 ADC)이 필요합니다.
-        //   credentials_file : 서비스 계정 키 파일 경로 (선택)
-        //   ADC 자동 사용 시 credentials_file 생략 가능.
-        "firestore_dev": {
-            "driver": "firestore",
-            "project_id": "${GCP_PROJECT_ID}",
-            "credentials_file": "${GOOGLE_APPLICATION_CREDENTIALS}"
-        },
-        "firestore_prod": {
-            "driver": "firestore",
-            "project_id": "${GCP_PROJECT_ID}"
-        },
-
-        // ── ScyllaDB / Apache Cassandra ────────────────────────────────
-        // hosts 는 쉼표 구분 문자열 또는 배열 모두 허용합니다.
-        // keyspace 가 없으면 자동 생성됩니다.
-        "scylladb_dev": {
-            "driver": "scylladb",
-            "hosts": "localhost:9042",
-            "keyspace": "entity_dev",
-            "username": "",
-            "password": ""
-        },
-        "scylladb_prod": {
-            "driver": "scylladb",
-            "hosts": "${SCYLLA_HOSTS}",
-            "keyspace": "${SCYLLA_KEYSPACE}",
-            "username": "${SCYLLA_USER}",
-            "password": "${SCYLLA_PASSWORD}",
-            "consistency": "quorum",
-            "timeout": "10s"
-        },
-
-        // ── Apache CouchDB ──────────────────────────────────────────────
-        // URI 우선 사용. uri 가 없으면 host/port/username/password 조합.
-        // 포트 기본값: 5984
-        "couchdb_dev": {
-            "driver": "couchdb",
-            "host": "localhost",
-            "port": 5984,
-            "username": "admin",
-            "password": "password"
-        },
-        "couchdb_uri": {
-            "driver": "couchdb",
-            "uri": "http://admin:password@localhost:5984/"
-        },
-        "couchdb_prod": {
-            "driver": "couchdb",
-            "uri": "http://${COUCH_USER}:${COUCH_PASS}@${COUCH_HOST}:${COUCH_PORT}/"
         }
     }
 }
-
-// ──────────────────────────────────────────────────────────────────────────
-// DataStore 단독 사용 — flat 형식 (groups 없이 최상위에 driver 직접 지정)
-//
-// SQL 없이 NoSQL DataStore만 단독으로 사용할 때는 groups 없이
-// database.json 최상위에 driver 를 직접 지정합니다.
-// store_loader.go 가 groups 키가 없고 NoSQL driver 인 경우에만 DataStore로 인식합니다.
-// ──────────────────────────────────────────────────────────────────────────
-
-// MongoDB flat 형식
-{
-    "driver": "mongodb",
-    "uri": "mongodb://localhost:27017",
-    "database": "entity_server"
-}
-
-// MongoDB — 환경변수 방식
-{
-    "driver": "mongodb",
-    "host": "${MONGO_HOST}",
-    "port": "${MONGO_PORT}",
-    "username": "${MONGO_USER}",
-    "password": "${MONGO_PASSWORD}",
-    "database": "${MONGO_DATABASE}"
-}
-
-// DynamoDB flat 형식
-{
-    "driver": "dynamodb",
-    "region": "${AWS_REGION}",
-    "access_key_id": "${AWS_ACCESS_KEY_ID}",
-    "secret_access_key": "${AWS_SECRET_ACCESS_KEY}"
-}
-
-// Firestore flat 형식
-{
-    "driver": "firestore",
-    "project_id": "${GCP_PROJECT_ID}",
-    "credentials_file": "${GOOGLE_APPLICATION_CREDENTIALS}"
-}
-
-// ScyllaDB flat 형식
-{
-    "driver": "scylladb",
-    "host": "${SCYLLA_HOST}",
-    "port": 9042,
-    "database": "${SCYLLA_KEYSPACE}",
-    "username": "${SCYLLA_USER}",
-    "password": "${SCYLLA_PASSWORD}"
-}
-
-// CouchDB flat 형식
-{
-    "driver": "couchdb",
-    "uri": "http://${COUCH_USER}:${COUCH_PASS}@${COUCH_HOST}:5984/"
-}

package/template/configs/database.json.example

@@ -0,0 +1,186 @@
+// ──────────────────────────────────────────────────────────────────────────
+// database.json 설정 예시 (주석 포함 예시 전용 파일 — 실제 파일은 순수 JSON)
+//
+// "default"     : 사용할 그룹 이름 (groups 키 중 하나)
+// "groups"      : 드라이버별 연결 설정 모음
+//   driver        : "mysql" | "postgres" | "mongodb" | "dynamodb" |
+//                   "firestore" | "scylladb" | "couchdb"
+//
+// 환경 변수 참조: "${ENV_VAR_NAME}" 형식으로 값을 주입합니다.
+// ──────────────────────────────────────────────────────────────────────────
+{
+    "default": "development",
+    "groups": {
+        // ── MySQL (SQL) ─────────────────────────────────────────────────
+        "development": {
+            "driver": "mysql",
+            "host": "${DB_HOST_DEVELOPMENT}",
+            "port": "${DB_PORT_DEVELOPMENT}",
+            "database": "${DB_NAME_DEVELOPMENT}",
+            "user": "${DB_USER_DEVELOPMENT}",
+            "password": "${DB_PASSWORD_DEVELOPMENT}",
+            "maxOpenConns": 20,
+            "maxIdleConns": 10,
+            "connMaxLifetimeSec": 3600
+        },
+        "production": {
+            "driver": "mysql",
+            "host": "${DB_HOST_PRODUCTION}",
+            "port": "${DB_PORT_PRODUCTION}",
+            "database": "${DB_NAME_PRODUCTION}",
+            "user": "${DB_USER_PRODUCTION}",
+            "password": "${DB_PASSWORD_PRODUCTION}",
+            "maxOpenConns": 50,
+            "maxIdleConns": 25,
+            "connMaxLifetimeSec": 3600
+        },
+
+        // ── MongoDB ─────────────────────────────────────────────────────
+        // URI 우선 사용. uri 가 없으면 host/port/database/username/password 조합.
+        "mongodb_dev": {
+            "driver": "mongodb",
+            "uri": "mongodb://localhost:27017/entity_dev",
+            "database": "entity_dev"
+        },
+        "mongodb_prod": {
+            "driver": "mongodb",
+            "host": "${MONGO_HOST}",
+            "port": 27017,
+            "database": "${MONGO_DB}",
+            "username": "${MONGO_USER}",
+            "password": "${MONGO_PASSWORD}",
+            "uri": ""
+        },
+        "mongodb_replica": {
+            "driver": "mongodb",
+            "uri": "mongodb://${MONGO_USER}:${MONGO_PASS}@mongo1:27017,mongo2:27017,mongo3:27017/${MONGO_DB}?replicaSet=rs0&authSource=admin",
+            "database": "${MONGO_DB}"
+        },
+
+        // ── Amazon DynamoDB ─────────────────────────────────────────────
+        // region 과 IAM 인증이 필요합니다.
+        // 로컬 테스트: endpoint 에 "http://localhost:8000" 지정.
+        "dynamodb_dev": {
+            "driver": "dynamodb",
+            "region": "ap-northeast-2",
+            "endpoint": "http://localhost:8000",
+            "access_key_id": "${AWS_ACCESS_KEY_ID}",
+            "secret_access_key": "${AWS_SECRET_ACCESS_KEY}"
+        },
+        "dynamodb_prod": {
+            "driver": "dynamodb",
+            "region": "${AWS_REGION}",
+            "access_key_id": "${AWS_ACCESS_KEY_ID}",
+            "secret_access_key": "${AWS_SECRET_ACCESS_KEY}"
+        },
+
+        // ── Google Cloud Firestore ──────────────────────────────────────
+        // GCP 프로젝트 ID 와 서비스 계정 JSON 파일(또는 ADC)이 필요합니다.
+        //   credentials_file : 서비스 계정 키 파일 경로 (선택)
+        //   ADC 자동 사용 시 credentials_file 생략 가능.
+        "firestore_dev": {
+            "driver": "firestore",
+            "project_id": "${GCP_PROJECT_ID}",
+            "credentials_file": "${GOOGLE_APPLICATION_CREDENTIALS}"
+        },
+        "firestore_prod": {
+            "driver": "firestore",
+            "project_id": "${GCP_PROJECT_ID}"
+        },
+
+        // ── ScyllaDB / Apache Cassandra ────────────────────────────────
+        // hosts 는 쉼표 구분 문자열 또는 배열 모두 허용합니다.
+        // keyspace 가 없으면 자동 생성됩니다.
+        "scylladb_dev": {
+            "driver": "scylladb",
+            "hosts": "localhost:9042",
+            "keyspace": "entity_dev",
+            "username": "",
+            "password": ""
+        },
+        "scylladb_prod": {
+            "driver": "scylladb",
+            "hosts": "${SCYLLA_HOSTS}",
+            "keyspace": "${SCYLLA_KEYSPACE}",
+            "username": "${SCYLLA_USER}",
+            "password": "${SCYLLA_PASSWORD}",
+            "consistency": "quorum",
+            "timeout": "10s"
+        },
+
+        // ── Apache CouchDB ──────────────────────────────────────────────
+        // URI 우선 사용. uri 가 없으면 host/port/username/password 조합.
+        // 포트 기본값: 5984
+        "couchdb_dev": {
+            "driver": "couchdb",
+            "host": "localhost",
+            "port": 5984,
+            "username": "admin",
+            "password": "password"
+        },
+        "couchdb_uri": {
+            "driver": "couchdb",
+            "uri": "http://admin:password@localhost:5984/"
+        },
+        "couchdb_prod": {
+            "driver": "couchdb",
+            "uri": "http://${COUCH_USER}:${COUCH_PASS}@${COUCH_HOST}:${COUCH_PORT}/"
+        }
+    }
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// DataStore 단독 사용 — flat 형식 (groups 없이 최상위에 driver 직접 지정)
+//
+// SQL 없이 NoSQL DataStore만 단독으로 사용할 때는 groups 없이
+// database.json 최상위에 driver 를 직접 지정합니다.
+// store_loader.go 가 groups 키가 없고 NoSQL driver 인 경우에만 DataStore로 인식합니다.
+// ──────────────────────────────────────────────────────────────────────────
+
+// MongoDB flat 형식
+{
+    "driver": "mongodb",
+    "uri": "mongodb://localhost:27017",
+    "database": "entity_server"
+}
+
+// MongoDB — 환경변수 방식
+{
+    "driver": "mongodb",
+    "host": "${MONGO_HOST}",
+    "port": "${MONGO_PORT}",
+    "username": "${MONGO_USER}",
+    "password": "${MONGO_PASSWORD}",
+    "database": "${MONGO_DATABASE}"
+}
+
+// DynamoDB flat 형식
+{
+    "driver": "dynamodb",
+    "region": "${AWS_REGION}",
+    "access_key_id": "${AWS_ACCESS_KEY_ID}",
+    "secret_access_key": "${AWS_SECRET_ACCESS_KEY}"
+}
+
+// Firestore flat 형식
+{
+    "driver": "firestore",
+    "project_id": "${GCP_PROJECT_ID}",
+    "credentials_file": "${GOOGLE_APPLICATION_CREDENTIALS}"
+}
+
+// ScyllaDB flat 형식
+{
+    "driver": "scylladb",
+    "host": "${SCYLLA_HOST}",
+    "port": 9042,
+    "database": "${SCYLLA_KEYSPACE}",
+    "username": "${SCYLLA_USER}",
+    "password": "${SCYLLA_PASSWORD}"
+}
+
+// CouchDB flat 형식
+{
+    "driver": "couchdb",
+    "uri": "http://${COUCH_USER}:${COUCH_PASS}@${COUCH_HOST}:5984/"
+}

package/template/configs/push.json

@@ -2,7 +2,7 @@
     "workers": 2,
     "queue_size": 500,
     "fcm": {
-        "enabled": true,
+        "enabled": false,
         "type": "service_account",
         "project_id": "your-firebase-project-id",
         "private_key_id": "abc123def456...",
@@ -16,7 +16,6 @@
     },
     "apns": {
         "enabled": false,
-        "_comment": "APNs 직접 전송 (미구현 - 예약)",
         "key_file": "./configs/keys/apns.p8",
         "key_id": "ABCDE12345",
         "team_id": "FGHIJ67890",

package/template/configs/server.json

@@ -2,6 +2,7 @@
     "namespace": "entity-prod",
     "default_email_domain": "example.com",
     "language": "ko",
+    "timezone": "Asia/Seoul",
     "environment": "production",
     "port": 47200,
     "enable_auto_schema_sync": true,

package/template/configs/smtp.json

@@ -0,0 +1,43 @@
+{
+    "enabled": false,
+    "default": "main",
+    "workers": 2,
+    "queue_size": 200,
+    "dispatch_interval_sec": 5,
+    "max_retries": 3,
+
+    "providers": {
+        "main": {
+            "host": "smtp.gmail.com",
+            "port": 587,
+            "username": "${SMTP_USERNAME}",
+            "password": "${SMTP_PASSWORD}",
+            "from": "noreply@example.com",
+            "from_name": "My Service",
+            "encryption": "starttls",
+            "auth": "plain",
+            "timeout_sec": 30,
+            "max_connections": 5
+        },
+        "transactional": {
+            "host": "smtp.sendgrid.net",
+            "port": 465,
+            "username": "apikey",
+            "password": "${SENDGRID_API_KEY}",
+            "from": "alerts@example.com",
+            "from_name": "My Service Alerts",
+            "encryption": "ssl",
+            "auth": "plain"
+        }
+    },
+
+    "templates": {
+        "dir": "./configs/templates/email",
+        "default_layout": "layout.html"
+    },
+
+    "rate_limit": {
+        "per_minute": 0,
+        "per_hour": 0
+    }
+}

package/template/configs/storage.json

@@ -0,0 +1,148 @@
+{
+    "enabled": true,
+    "default": "local-main",
+    "max_file_size_mb": 20,
+    "storages": {
+        "local-main": {
+            "driver": "local",
+            "root": "./uploads"
+        },
+
+        "s3-aws": {
+            "driver": "s3",
+            "bucket": "my-entity-files",
+            "region": "ap-northeast-2",
+            "access_key": "${AWS_ACCESS_KEY_ID}",
+            "secret_key": "${AWS_SECRET_ACCESS_KEY}",
+            "prefix": "entity-files"
+        },
+
+        "s3-r2": {
+            "driver": "s3",
+            "bucket": "my-files",
+            "region": "auto",
+            "endpoint": "https://${CF_ACCOUNT_ID}.r2.cloudflarestorage.com",
+            "access_key": "${R2_ACCESS_KEY}",
+            "secret_key": "${R2_SECRET_KEY}",
+            "prefix": "",
+            "_comment": "Cloudflare R2 (S3 호환) — 이그레스 무료"
+        },
+
+        "s3-b2": {
+            "driver": "s3",
+            "bucket": "my-files",
+            "region": "us-west-004",
+            "endpoint": "https://s3.us-west-004.backblazeb2.com",
+            "access_key": "${B2_KEY_ID}",
+            "secret_key": "${B2_APP_KEY}",
+            "_comment": "Backblaze B2 (S3 호환) — S3 대비 1/4 가격"
+        },
+
+        "s3-wasabi": {
+            "driver": "s3",
+            "bucket": "my-files",
+            "region": "ap-northeast-2",
+            "endpoint": "https://s3.ap-northeast-2.wasabisys.com",
+            "access_key": "${WASABI_ACCESS_KEY}",
+            "secret_key": "${WASABI_SECRET_KEY}",
+            "_comment": "Wasabi (S3 호환) — 저가 hot storage"
+        },
+
+        "s3-do-spaces": {
+            "driver": "s3",
+            "bucket": "my-files",
+            "region": "sgp1",
+            "endpoint": "https://sgp1.digitaloceanspaces.com",
+            "access_key": "${DO_SPACES_KEY}",
+            "secret_key": "${DO_SPACES_SECRET}",
+            "_comment": "DigitalOcean Spaces (S3 호환)"
+        },
+
+        "s3-minio": {
+            "driver": "s3",
+            "bucket": "entity-files",
+            "region": "us-east-1",
+            "endpoint": "http://minio.internal:9000",
+            "access_key": "minioadmin",
+            "secret_key": "minioadmin",
+            "_comment": "MinIO (S3 호환) — 자체 호스팅"
+        },
+
+        "s3-ncloud": {
+            "driver": "s3",
+            "bucket": "my-files",
+            "region": "kr-standard",
+            "endpoint": "https://kr.object.ncloudstorage.com",
+            "access_key": "${NCLOUD_ACCESS_KEY}",
+            "secret_key": "${NCLOUD_SECRET_KEY}",
+            "_comment": "Naver Cloud Object Storage (S3 호환)"
+        },
+
+        "azure-example": {
+            "driver": "azure",
+            "container": "files",
+            "account_name": "${AZURE_STORAGE_ACCOUNT}",
+            "account_key": "${AZURE_STORAGE_KEY}",
+            "prefix": "entity-files"
+        },
+
+        "gcs-example": {
+            "driver": "gcs",
+            "bucket": "my-entity-files",
+            "credentials_file": "./configs/keys/gcp-sa.json",
+            "prefix": "entity-files",
+            "_comment": "GKE/Cloud Run에서는 credentials_file 불필요 (Workload Identity)"
+        },
+
+        "sftp-example": {
+            "driver": "sftp",
+            "host": "nas.company.com",
+            "port": 22,
+            "user": "backup",
+            "private_key_file": "./configs/keys/backup_rsa",
+            "root": "/volume1/entity-files",
+            "_comment": "NAS/온프레미스 서버 연동"
+        },
+
+        "swift-kt": {
+            "driver": "swift",
+            "auth_url": "https://ssproxy.ucloudbiz.olleh.com/identity/v3",
+            "container": "my-files",
+            "user": "${KT_USER}",
+            "password": "${KT_PASSWORD}",
+            "tenant_name": "${KT_TENANT}",
+            "domain_name": "Default",
+            "region": "kr1",
+            "_comment": "KT Cloud Storage (OpenStack Swift)"
+        }
+    },
+    "thumbnail": {
+        "enabled": true,
+        "auto_orient": true,
+        "sizes": {
+            "sm": {
+                "width": 160,
+                "height": 160
+            },
+            "md": {
+                "width": 480,
+                "height": 480
+            },
+            "lg": {
+                "width": 1024,
+                "height": 1024
+            }
+        },
+        "quality": 85
+    },
+    "quota": {
+        "default_limit_gb": 0,
+        "threshold_percent": 80,
+        "notify": ["log", "smtp"]
+    },
+    "gc": {
+        "enabled": true,
+        "orphan_threshold_hours": 24,
+        "cron": "0 3 * * *"
+    }
+}

package/template/entities/README.md

@@ -17,13 +17,13 @@
 
 ## 문서 바로가기
 
-| 섹션                                                         | 내용                                      |
-| ------------------------------------------------------------ | ----------------------------------------- |
-| [포함된 예제](#포함된-예제)                                  | 각 예제 파일 상세 설명                    |
-| [엔티티 설정 규칙](#엔티티-설정-규칙)                        | 자동 추론 필드, Types, index 형식, 복합키 |
-| [훅 (Hooks)](#훅-hooks)                                      | SQL 훅, Entity 훅, 실행 시점, 템플릿 변수 |
-| [라이선스 스코프](#라이선스-스코프란)                        | 멀티테넌트 / 단일 시스템 모드             |
-| [Entity Config Guide](../../docs/ops/entity-config-guide.md) | 전체 엔티티 설정 레퍼런스                 |
+| 섹션                                                                 | 내용                                      |
+| -------------------------------------------------------------------- | ----------------------------------------- |
+| [포함된 예제](#포함된-예제)                                          | 각 예제 파일 상세 설명                    |
+| [엔티티 설정 규칙](#엔티티-설정-규칙)                                | 자동 추론 필드, Types, index 형식, 복합키 |
+| [훅 (Hooks)](#훅-hooks)                                              | SQL 훅, Entity 훅, 실행 시점, 템플릿 변수 |
+| [라이선스 스코프](#라이선스-스코프란)                                | 멀티테넌트 / 단일 시스템 모드             |
+| [Entity Config Guide](../../docs/guides/data/entity-config-guide.md) | 전체 엔티티 설정 레퍼런스                 |
 
 ---
 

package/template/samples/entities/README.md

@@ -3,8 +3,8 @@
 `entities/` 디렉토리에 배치하는 `.json` 설정 파일 예제 모음입니다.  
 엔티티 서버의 **모든 주요 기능을 하나씩** 알아볼 수 있도록 주제별로 구성하였습니다.
 
-> **전체 레퍼런스**: [docs/ops/entity-config-guide.md](../../docs/ops/entity-config-guide.md)  
-> **훅 가이드**: [docs/ops/hooks.md](../../docs/ops/hooks.md)
+> **전체 레퍼런스**: [docs/guides/data/entity-config-guide.md](../../docs/guides/data/entity-config-guide.md)  
+> **훅 가이드**: [docs/guides/extensions/hooks.md](../../docs/guides/extensions/hooks.md)
 
 ---
 

package/template/scripts/generate-env-keys.sh

@@ -31,6 +31,11 @@ Options:
     --export      Print shell export format
     --apply       Apply values directly to project .env
 
+Generated keys:
+    ENCRYPTION_KEY      Master encryption key (32-byte hex)
+    JWT_SECRET          JWT signing key (64-byte hex)
+    BACKUP_ENCRYPT_KEY  Backup file encryption key (32-byte hex)
+
 Examples:
     ./scripts/generate-env-keys.sh --create
     ./scripts/generate-env-keys.sh --export
@@ -53,6 +58,11 @@ ENCRYPTION_KEY, JWT_SECRET 랜덤 값을 생성합니다.
     --export      export 형식으로 출력
     --apply       프로젝트 루트 .env 파일에 즉시 반영
 
+생성 키:
+    ENCRYPTION_KEY      마스터 암호화 키 (32바이트 hex)
+    JWT_SECRET          JWT 서명 키 (64바이트 hex)
+    BACKUP_ENCRYPT_KEY  백업 파일 암호화 키 (32바이트 hex)
+
 예제:
     ./scripts/generate-env-keys.sh --create
     ./scripts/generate-env-keys.sh --export
@@ -106,17 +116,20 @@ gen_hex() {
 
 ENCRYPTION_KEY="$(gen_hex 16)"
 JWT_SECRET="$(gen_hex 32)"
+BACKUP_ENCRYPT_KEY="$(gen_hex 16)"
 
 if [[ "$OUTPUT_MODE" == "export" ]]; then
     cat <<EOF
 export ENCRYPTION_KEY=$ENCRYPTION_KEY
 export JWT_SECRET=$JWT_SECRET
+export BACKUP_ENCRYPT_KEY=$BACKUP_ENCRYPT_KEY
 EOF
 elif [[ "$OUTPUT_MODE" == "dotenv" ]]; then
     cat <<EOF
 # $( [ "$LANGUAGE" = "en" ] && echo "Copy & paste to .env" || echo ".env에 복사해서 붙여넣기" )
 ENCRYPTION_KEY=$ENCRYPTION_KEY
 JWT_SECRET=$JWT_SECRET
+BACKUP_ENCRYPT_KEY=$BACKUP_ENCRYPT_KEY
 EOF
 else
     # --apply
@@ -135,14 +148,17 @@ else
 
     upsert_env_key "ENCRYPTION_KEY" "$ENCRYPTION_KEY"
     upsert_env_key "JWT_SECRET" "$JWT_SECRET"
+    upsert_env_key "BACKUP_ENCRYPT_KEY" "$BACKUP_ENCRYPT_KEY"
 
     if [ "$LANGUAGE" = "en" ]; then
         echo "✓ Updated: $ENV_FILE"
         echo "  - ENCRYPTION_KEY"
         echo "  - JWT_SECRET"
+        echo "  - BACKUP_ENCRYPT_KEY"
     else
         echo "✓ 업데이트 완료: $ENV_FILE"
         echo "  - ENCRYPTION_KEY"
         echo "  - JWT_SECRET"
+        echo "  - BACKUP_ENCRYPT_KEY"
     fi
 fi