create-entity-server 0.0.15 → 0.0.23

package/bin/create.js

@@ -228,11 +228,14 @@ async function run() {
             );
             console.warn(`  https://github.com/${REPO}/releases\n`);
         } else {
+            const binDir = path.join(targetDir, "bin");
+            fs.mkdirSync(binDir, { recursive: true });
+
             for (const bin of ["entity-server", "entity-cli"]) {
                 const ext = platform === "windows" ? ".exe" : "";
                 const fileName = `${bin}-${platform}-${arch}${ext}`;
                 const url = `https://github.com/${REPO}/releases/download/v${VERSION}/${fileName}`;
-                const dest = path.join(targetDir, bin + ext);
+                const dest = path.join(binDir, bin + ext);
 
                 process.stdout.write(`  ↓ ${fileName} 다운로드 중...`);
                 try {
@@ -253,8 +256,9 @@ async function run() {
     // ── 3. 완료 안내 ─────────────────────────────────────────────────────────
 
     const relDir = path.relative(process.cwd(), targetDir) || dirName;
-    const serverExe = isWin ? ".\\entity-server.exe" : "./entity-server";
-    const cliExe = isWin ? ".\\entity-cli.exe" : "./entity-cli";
+    const serverExe = isWin
+        ? ".\\bin\\entity-server.exe"
+        : "./bin/entity-server";
     const runScript = isWin
         ? ".\\scripts\\run.ps1 start"
         : "./scripts/run.sh start";
@@ -264,8 +268,9 @@ async function run() {
   ✓ 완료!
 
   ${relDir}/
-  ├── entity-server${binExt}   ← 서버 바이너리
-  ├── entity-cli${binExt}      ← CLI 도구
+    ├── bin/
+    │   ├── entity-server${binExt}   ← 서버 바이너리
+    │   └── entity-cli${binExt}      ← CLI 도구
   ├── .env                ← 환경 변수 설정 (여기를 먼저 수정하세요)
   ├── configs/            ← CORS, JWT 등 서버 설정
   ├── entities/           ← 엔티티 스키마 JSON (샘플 포함)
@@ -274,8 +279,11 @@ async function run() {
 
   다음 단계:
 ${cdCmd ? `    ${cdCmd}` : ""}
-    nano .env             # PORT, DB_PATH, 암호화 키 설정
-    ${serverExe}          # 서버 실행
+        ./scripts/generate-env-keys${isWin ? ".ps1 -Apply" : ".sh --apply"}   # ENCRYPTION_KEY/JWT_SECRET 생성 후 .env 반영
+        vim .env              # PORT, DB_PATH 등 기본 환경값 확인/수정
+        vim configs/*.json    # database/server/jwt 등 운영 설정
+        vim entities/*.json   # 사용할 엔티티 스키마 정의
+        ${serverExe}          # 마지막: 서버 실행
 
   서버마다 .env 의 PORT 와 DB_PATH 를 다르게 설정하면
   같은 머신에서 여러 프로젝트를 동시에 운영할 수 있습니다.

package/package.json

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

package/template/.env.example

@@ -1,8 +1,10 @@
 # Entity Server 환경변수 설정 예시
 # 실제 사용시 이 파일을 .env로 복사하고 값을 변경하세요: cp .env.example .env
+# ./scripts/generate-env-keys.sh 를 사용하여 랜덤 시크릿을 생성할 수 있습니다.
 
-# 기본 암복호화 키 (license 엔티티 등 공통 fallback 키)
-# 32자 16진수 문자열 (128bit AES-CTR 키)
+# 기본 암복호화 마스터 시크릿 (license 엔티티 등 공통 fallback 키)
+# HKDF-SHA256 으로 32바이트(256-bit) XChaCha20-Poly1305 키를 유도하는 마스터 시크릿입니다.
+# 충분한 엔트로피를 가진 임의 문자열이면 됩니다 (예: openssl rand -hex 32 으로 생성).
 ENCRYPTION_KEY=your-32-char-hex-encryption-key-here
 
 # JWT 서명 키 (HS256)
@@ -13,18 +15,17 @@ JWT_SECRET=your-jwt-secret-here
 SERVER_PORT=47200
 
 # Database values (database.json의 ${ENV_VAR}와 매핑)
+DB_HOST_DEVELOPMENT=127.0.0.1
+DB_PORT_DEVELOPMENT=3306
 DB_NAME_DEVELOPMENT=your-development-db-name
 DB_USER_DEVELOPMENT=your-development-db-user
 DB_PASSWORD_DEVELOPMENT=your-development-db-password
 
+DB_HOST_PRODUCTION=127.0.0.1
+DB_PORT_PRODUCTION=3306
 DB_NAME_PRODUCTION=your-production-db-name
 DB_USER_PRODUCTION=your-production-db-user
 DB_PASSWORD_PRODUCTION=your-production-db-password
 
-# PostgreSQL group (선택)
-# DB_NAME_POSTGRESQL=your-postgresql-db-name
-# DB_USER_POSTGRESQL=your-postgresql-db-user
-# DB_PASSWORD_POSTGRESQL=your-postgresql-db-password
-
 # 푸시 알림 (push.json에서 ${FCM_PROJECT_ID} 등으로 참조 가능)
 # FCM_PROJECT_ID=your-firebase-project-id

package/template/configs/database.json

@@ -1,23 +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": "127.0.0.1",
-            "port": 3306,
-            "database": "entity_server",
-            "user": "root",
+            "host": "${DB_HOST_DEVELOPMENT}",
+            "port": "${DB_PORT_DEVELOPMENT}",
+            "database": "${DB_NAME_DEVELOPMENT}",
+            "user": "${DB_USER_DEVELOPMENT}",
             "password": "${DB_PASSWORD_DEVELOPMENT}",
-            "maxOpenConns": 20
+            "maxOpenConns": 20,
+            "maxIdleConns": 10,
+            "connMaxLifetimeSec": 3600
         },
         "production": {
             "driver": "mysql",
-            "host": "127.0.0.1",
-            "port": 3306,
-            "database": "entity_server",
-            "user": "entity_user",
+            "host": "${DB_HOST_PRODUCTION}",
+            "port": "${DB_PORT_PRODUCTION}",
+            "database": "${DB_NAME_PRODUCTION}",
+            "user": "${DB_USER_PRODUCTION}",
             "password": "${DB_PASSWORD_PRODUCTION}",
-            "maxOpenConns": 50
+            "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/entities/Account/account_audit.json

@@ -1,17 +1,16 @@
 {
     "name": "account_audit",
-    "description": "account_audit Entity",
+    "description": "account 감사 로그. JWT 인증 시에만 account_seq는 required",
     "index": {
         "account_seq": {
-            "comment": "계정 seq",
+            "comment": "계정 seq (JWT 인증 시 account.seq 참조. HMAC은 nullable)",
             "type": "bigint",
-            "required": true
+            "nullable": true
         },
         "action": {
             "comment": "작업 유형",
             "type": ["INSERT", "UPDATE", "DELETE", "LOGIN", "LOGOUT"],
             "required": true
         }
-    },
-    "license_scope": false
+    }
 }

package/template/entities/System/system_audit_log.json

@@ -1,6 +1,6 @@
 {
     "name": "system_audit_log",
-    "description": "시스템 감사 로그. 서버 레벨에서 자동 기록되며 API를 통한 직접 수정은 허용되지 않습니다.",
+    "description": "시스템 감사 로그. 서버 레벨에서 자동 기록되며 API를 통한 직접 수정은 허용되지 않습니다. JWT 인증 시에만 account_seq 기록",
     "db_group": "system",
     "hard_delete": true,
     "history_ttl": 0,
@@ -18,7 +18,8 @@
         },
         "entity_seq": {
             "comment": "대상 엔티티 레코드 seq. 로그인/로그아웃 등 레코드 없는 경우 NULL",
-            "type": "bigint"
+            "type": "bigint",
+            "nullable": true
         },
         "action": {
             "comment": "수행된 작업 유형",
@@ -34,16 +35,19 @@
             "required": true
         },
         "account_seq": {
-            "comment": "작업을 수행한 계정 seq. 비인증 요청은 NULL",
-            "type": "bigint"
+            "comment": "작업을 수행한 계정 seq. JWT 인증 요청은 account.seq, 비인증/HMAC 요청은 NULL",
+            "type": "bigint",
+            "nullable": true
         },
         "ip_address": {
             "comment": "요청 IP 주소 (IPv4/IPv6)",
-            "type": "varchar(45)"
+            "type": "varchar(45)",
+            "nullable": true
         },
         "endpoint": {
             "comment": "요청 API 엔드포인트",
-            "type": "varchar(200)"
+            "type": "varchar(200)",
+            "nullable": true
         },
         "request_method": {
             "comment": "HTTP 메서드 (GET/POST/PUT/DELETE 등)",
@@ -51,7 +55,8 @@
         },
         "request_payload": {
             "comment": "요청 본문 JSON. 민감 필드(password, token 등) 자동 마스킹 후 저장. ServerConfig.AuditLogPayload = true 일 때만 기록",
-            "type": "text"
+            "type": "text",
+            "nullable": true
         },
         "result_code": {
             "comment": "HTTP 응답 코드 (200, 400, 401, 403, 500 등)",
@@ -59,7 +64,8 @@
         },
         "error_message": {
             "comment": "실패 시 오류 메시지 요약",
-            "type": "varchar(500)"
+            "type": "varchar(500)",
+            "nullable": true
         }
     }
 }

package/template/samples/README.md

@@ -15,11 +15,12 @@ Client / Browser
 Backend Server  ←── 이 샘플이 구현하는 부분
       │
       ▼ HMAC 서명 (서버 간 통신)
-Entity Server (Go)
+Entity Server
 ```
 
-> **React (SPA)** 샘플은 HMAC 대신 JWT Bearer 토큰을 사용합니다.  
-> 브라우저 환경에서는 HMAC secret을 노출할 수 없기 때문입니다.
+> **브라우저(React·Vanilla)** 환경에서도 HMAC / JWT 모두 사용 가능합니다.  
+> 단, 브라우저에서 HMAC을 사용하면 `hmacSecret`이 클라이언트에 노출되므로,  
+> **프론트엔드 프로덕션 환경에서는 JWT 사용을 권장합니다.**
 
 ## HMAC 서명 공식
 
@@ -39,31 +40,36 @@ signature = HMAC-SHA256(hmacSecret, payload) → hex
 
 ## API 엔드포인트
 
-| 동작      | 메서드 | 경로                               |
-| --------- | ------ | ---------------------------------- |
-| 단건 조회 | GET    | `/v1/entity/{name}/{seq}`          |
-| 목록 조회 | GET    | `/v1/entity/{name}/list`           |
-| 필터 검색 | POST   | `/v1/entity/{name}/query`          |
-| 건수 조회 | GET    | `/v1/entity/{name}/count`          |
-| 생성/수정 | POST   | `/v1/entity/{name}/submit`         |
-| 삭제      | DELETE | `/v1/entity/{name}/delete/{seq}`   |
-| 이력 조회 | GET    | `/v1/entity/{name}/history/{seq}`  |
-| 롤백      | POST   | `/v1/entity/{name}/rollback/{seq}` |
+| 동작           | 메서드 | 경로                               |
+| -------------- | ------ | ---------------------------------- |
+| 단건 조회      | GET    | `/v1/entity/{name}/{seq}`          |
+| 조건 단건 조회 | POST   | `/v1/entity/{name}/find`           |
+| 목록 조회      | POST   | `/v1/entity/{name}/list`           |
+| 필터 검색      | POST   | `/v1/entity/{name}/query`          |
+| 건수 조회      | POST   | `/v1/entity/{name}/count`          |
+| 생성/수정      | POST   | `/v1/entity/{name}/submit`         |
+| 삭제           | POST   | `/v1/entity/{name}/delete/{seq}`   |
+| 이력 조회      | GET    | `/v1/entity/{name}/history/{seq}`  |
+| 롤백           | POST   | `/v1/entity/{name}/rollback/{seq}` |
 
 - `list` 쿼리 파라미터: `?page=1&limit=20&order_by=<field>`
 - `submit` — body에 `seq` 포함 시 수정, 없으면 생성
 
 ## 샘플 목록
 
-| 디렉토리       | 프레임워크             | 인증 방식 |
-| -------------- | ---------------------- | --------- |
-| `entities/`    | 엔티티 설정 예제       | —         |
-| `php/ci4/`     | CodeIgniter 4          | HMAC      |
-| `php/laravel/` | Laravel                | HMAC      |
-| `java/`        | Java (표준 라이브러리) | HMAC      |
-| `node/`        | Node.js (fetch)        | HMAC      |
-| `python/`      | Python (requests)      | HMAC      |
-| `react/`       | React + TypeScript     | JWT       |
+| 디렉토리       | 프레임워크                                     | 인증 방식  |
+| -------------- | ---------------------------------------------- | ---------- |
+| `entities/`    | 엔티티 설정 예제                               | —          |
+| `browser/`     | 브라우저 (Vanilla ES Module, 빌드 도구 불필요) | HMAC / JWT |
+| `php/ci4/`     | CodeIgniter 4                                  | HMAC / JWT |
+| `php/laravel/` | Laravel                                        | HMAC / JWT |
+| `java/`        | Java (표준 라이브러리)                         | HMAC / JWT |
+| `kotlin/`      | Kotlin (표준 라이브러리)                       | HMAC / JWT |
+| `swift/`       | Swift (URLSession)                             | HMAC / JWT |
+| `flutter/`     | Flutter (Dart)                                 | HMAC / JWT |
+| `node/`        | Node.js (fetch)                                | HMAC / JWT |
+| `python/`      | Python (requests)                              | HMAC / JWT |
+| `react/`       | React + TypeScript                             | HMAC / JWT |
 
 ### CI4 설정 방식