create-entity-server 0.0.9 → 0.0.23

package/bin/create.js

@@ -193,6 +193,15 @@ async function run() {
         path.join(targetDir, "entities"),
     );
 
+    // samples/ (없어도 빈 디렉터리 생성)
+    const samplesSrc = path.join(templateDir, "samples");
+    const samplesDest = path.join(targetDir, "samples");
+    if (fs.existsSync(samplesSrc)) {
+        copyDir(samplesSrc, samplesDest);
+    } else {
+        fs.mkdirSync(samplesDest, { recursive: true });
+    }
+
     // .env.example 복사 + .env 생성 (없을 때만)
     copyFile(
         path.join(templateDir, ".env.example"),
@@ -219,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 {
@@ -244,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";
@@ -255,17 +268,22 @@ 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 (샘플 포함)
-  └── scripts/            ← 운영 스크립트
+    ├── scripts/            ← 운영 스크립트
+    └── samples/            ← 샘플 파일
 
   다음 단계:
 ${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.9",
+  "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,14 +1,31 @@
 # 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)
 # 운영에서는 충분히 긴 랜덤 시크릿을 사용하세요.
 JWT_SECRET=your-jwt-secret-here
 
-# Database passwords (database.json의 password_env와 매핑)
+# 서버 포트 (configs/server.json의 port를 오버라이드)
+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
+
+# 푸시 알림 (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/configs/jwt.json

@@ -1,4 +1,5 @@
 {
+    "enabled": true,
     "secret": "${JWT_SECRET}",
     "access_ttl_sec": 3600,
     "refresh_ttl_sec": 1209600,

package/template/configs/oauth.json

@@ -0,0 +1,37 @@
+{
+    "_comment": "OAuth 2.0 설정 예시. 사용할 프로바이더만 남기고 실제 값으로 교체하세요.",
+
+    "state_secret": "${OAUTH_STATE_SECRET}",
+    "state_ttl_sec": 600,
+
+    "providers": {
+        "google": {
+            "client_id": "${GOOGLE_CLIENT_ID}",
+            "client_secret": "${GOOGLE_CLIENT_SECRET}",
+            "redirect_url": "https://your-domain.com/v1/oauth/google/callback",
+            "scopes": ["openid", "email", "profile"]
+        },
+        "github": {
+            "client_id": "${GITHUB_CLIENT_ID}",
+            "client_secret": "${GITHUB_CLIENT_SECRET}",
+            "redirect_url": "https://your-domain.com/v1/oauth/github/callback"
+        },
+        "naver": {
+            "client_id": "${NAVER_CLIENT_ID}",
+            "client_secret": "${NAVER_CLIENT_SECRET}",
+            "redirect_url": "https://your-domain.com/v1/oauth/naver/callback"
+        },
+        "kakao": {
+            "_comment": "Kakao — 커스텀 엔드포인트 예시",
+            "client_id": "${KAKAO_CLIENT_ID}",
+            "client_secret": "${KAKAO_CLIENT_SECRET}",
+            "redirect_url": "https://your-domain.com/v1/oauth/kakao/callback",
+            "auth_url": "https://kauth.kakao.com/oauth/authorize",
+            "token_url": "https://kauth.kakao.com/oauth/token",
+            "user_info_url": "https://kapi.kakao.com/v2/user/me",
+            "scopes": ["profile_nickname", "account_email"],
+            "email_field": "kakao_account.email",
+            "name_field": "properties.nickname"
+        }
+    }
+}

package/template/configs/push.json

@@ -0,0 +1,26 @@
+{
+    "workers": 2,
+    "queue_size": 500,
+    "fcm": {
+        "enabled": true,
+        "type": "service_account",
+        "project_id": "your-firebase-project-id",
+        "private_key_id": "abc123def456...",
+        "private_key_file": "./configs/keys/firebase.pem",
+        "client_email": "firebase-adminsdk-xxxxx@your-firebase-project-id.iam.gserviceaccount.com",
+        "client_id": "123456789012345678901",
+        "auth_uri": "https://accounts.google.com/o/oauth2/auth",
+        "token_uri": "https://oauth2.googleapis.com/token",
+        "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
+        "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/firebase-adminsdk-xxxxx%40your-firebase-project-id.iam.gserviceaccount.com"
+    },
+    "apns": {
+        "enabled": false,
+        "_comment": "APNs 직접 전송 (미구현 - 예약)",
+        "key_file": "./configs/keys/apns.p8",
+        "key_id": "ABCDE12345",
+        "team_id": "FGHIJ67890",
+        "bundle_id": "com.example.myapp",
+        "production": false
+    }
+}

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/README.md

@@ -50,11 +50,11 @@
 
 ### 3. examples/Auth/account.json
 
-사용자 관리 엔티티 (`entities/examples/Auth/` 에 위치 → 배포 시 `dist/entities/Auth/account.json`)
+사용자 관리 엔티티 (`entities/examples/Auth/` 에 위치 → 배포 시 `dist/entities/System/Auth/account.json`)
 
 > **⚠️ JWT 인증을 사용하려면 필수입니다.**  
 > HMAC 인증만 사용하는 경우에는 필요하지 않습니다.  
-> `jwt.json`에 `secret`이 설정된 경우 서버 기동 시 `entities/Auth/account.json`이 존재하지 않으면 오류가 발생합니다.  
+> `jwt.json`에 `secret`이 설정된 경우 서버 기동 시 `entities/System/Auth/account.json`이 존재하지 않으면 오류가 발생합니다.  
 > `email`, `rbac_role` 필드가 index에 포함되어 있어야 합니다.  
 > `./scripts/reset-all.sh --apply` 실행 시 파일이 없으면 자동으로 생성됩니다.
 
@@ -68,7 +68,7 @@
 
 ### 4. examples/Auth/rbac_roles.json
 
-RBAC 역할 정의 엔티티 (`entities/examples/Auth/` 에 위치 → 배포 시 `dist/entities/Auth/rbac_roles.json`)
+RBAC 역할 정의 엔티티 (`entities/examples/Auth/` 에 위치 → 배포 시 `dist/entities/System/Auth/rbac_roles.json`)
 
 > **⚠️ RBAC 인증을 사용하려면 필수입니다.**  
 > `reset-all` 실행 시 `reset_defaults`의 5개 역할이 자동 시딩됩니다.  
@@ -84,7 +84,7 @@ RBAC 역할 정의 엔티티 (`entities/examples/Auth/` 에 위치 → 배포
 
 ### 5. examples/Auth/api_keys.json
 
-API 키 관리 엔티티 (`entities/examples/Auth/` 에 위치 → 배포 시 `dist/entities/Auth/api_keys.json`)
+API 키 관리 엔티티 (`entities/examples/Auth/` 에 위치 → 배포 시 `dist/entities/System/Auth/api_keys.json`)
 
 > **⚠️ HMAC 인증을 사용하려면 필수입니다.**  
 > `reset-all` 실행 시 admin 역할의 API 키 1개가 자동 생성되며 `key_value`와 `hmac_secret`이 출력됩니다.  

package/template/entities/{Auth → System/Auth}/account.json

@@ -34,20 +34,6 @@
         }
     ],
     "hooks": {
-        "before_insert": [
-            {
-                "type": "submit",
-                "entity": "user",
-                "match": {
-                    "email": "${new.email}"
-                },
-                "data": {
-                    "email": "${new.email}",
-                    "status": "active"
-                },
-                "assign_seq_to": "user_seq"
-            }
-        ],
         "after_insert": [
             {
                 "type": "sql",

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,27 +40,48 @@ 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` 포함 시 수정, 없으면 생성
 
 ## 샘플 목록
 
-| 디렉토리       | 프레임워크             | 인증 방식 |
-| -------------- | ---------------------- | --------- |
-| `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 설정 방식
+
+- `php/ci4` 샘플은 `app/Config/EntityServer.php` 중심으로 설정을 관리합니다.
+- 다른 언어 샘플은 각 라이브러리/클라이언트 파일 내부 설정값을 직접 수정해 사용합니다.
+
+### Push 헬퍼
+
+- 모든 샘플 클라이언트는 푸시 트리거용 헬퍼를 제공합니다. - `push(pushEntity, payload[, transactionId])` : 내부적으로 `submit(pushEntity, payload)` 호출 - `pushLogList(...)` : 내부적으로 `list('push_log', ...)` 호출
+- Python 샘플은 PEP8 네이밍으로 `push_log_list(...)` 메서드를 제공합니다.
+
+### 요청 본문(암호 패킷) 읽기 헬퍼
+
+- 모든 샘플에 요청 본문 파싱 헬퍼를 제공합니다. - `application/octet-stream`이면 XChaCha20-Poly1305 패킷을 복호화해 JSON 반환 - 그 외 Content-Type이면 평문 JSON 파싱 - 옵션으로 `requireEncrypted=true` 정책을 줄 수 있습니다.
+- 언어별 메서드명 - Node/React/Kotlin/Java/Swift/Laravel: `readRequestBody(...)` - Python: `read_request_body(...)` - Flutter: `readRequestBody(...)`