create-entity-server 0.0.9 → 0.0.15

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"),
@@ -260,7 +269,8 @@ async function run() {
   ├── .env                ← 환경 변수 설정 (여기를 먼저 수정하세요)
   ├── configs/            ← CORS, JWT 등 서버 설정
   ├── entities/           ← 엔티티 스키마 JSON (샘플 포함)
-  └── scripts/            ← 운영 스크립트
+    ├── scripts/            ← 운영 스크립트
+    └── samples/            ← 샘플 파일
 
   다음 단계:
 ${cdCmd ? `    ${cdCmd}` : ""}

package/package.json

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

package/template/.env.example

@@ -9,6 +9,22 @@ ENCRYPTION_KEY=your-32-char-hex-encryption-key-here
 # 운영에서는 충분히 긴 랜덤 시크릿을 사용하세요.
 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_NAME_DEVELOPMENT=your-development-db-name
+DB_USER_DEVELOPMENT=your-development-db-user
 DB_PASSWORD_DEVELOPMENT=your-development-db-password
+
+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/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/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/samples/README.md

@@ -57,9 +57,25 @@ signature = HMAC-SHA256(hmacSecret, payload) → hex
 
 | 디렉토리       | 프레임워크             | 인증 방식 |
 | -------------- | ---------------------- | --------- |
+| `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       |
+
+### 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(...)`

package/template/samples/entities/01_basic_fields.json

@@ -0,0 +1,39 @@
+{
+    "name": "contact",
+    "description": "기본 필드 타입 예제 — 인덱스 필드 자동 추론 패턴 모음",
+    "index": {
+        "name": {
+            "comment": "이름 (*_name → VARCHAR(100) 자동 추론)"
+        },
+        "email": {
+            "comment": "이메일 (*email* → VARCHAR(255) 자동 추론)",
+            "type": "email"
+        },
+        "phone": {
+            "comment": "전화번호 (*phone* → VARCHAR(50) 자동 추론)"
+        },
+        "birth_date": {
+            "comment": "생년월일 (*_date → DATE 자동 추론)"
+        },
+        "joined_at": {
+            "comment": "가입일시 (*_at → DATETIME 자동 추론)"
+        },
+        "visit_count": {
+            "comment": "방문 횟수 (*_count → INT 자동 추론)"
+        },
+        "total_amount": {
+            "comment": "총 금액 (*_amount → DECIMAL(15,2) 자동 추론)"
+        },
+        "is_verified": {
+            "comment": "인증 여부 (is_* → TINYINT(1) 자동 추론)"
+        },
+        "user_seq": {
+            "comment": "연결된 사용자 seq (*_seq → BIGINT UNSIGNED 자동 추론)"
+        },
+        "status": {
+            "comment": "상태 (enum 배열로 허용값 제한)",
+            "type": ["active", "inactive"],
+            "default": "active"
+        }
+    }
+}

package/template/samples/entities/02_types_and_defaults.json

@@ -0,0 +1,68 @@
+{
+    "name": "product",
+    "description": "명시적 타입 선언 & defaults 예제 — 자동 추론이 안 되는 필드에 types 사용",
+    "index": {
+        "sku": {
+            "comment": "상품 코드",
+            "required": true,
+            "unique": true
+        },
+        "category": {
+            "comment": "카테고리",
+            "type": ["electronics", "furniture", "clothing", "food"],
+            "default": "electronics"
+        },
+        "price": {
+            "comment": "정가 (decimal — 자동추론 불가, 명시 선언)",
+            "type": "decimal"
+        },
+        "stock_qty": {
+            "comment": "재고 수량 (*_qty → INT 자동 추론)"
+        },
+        "weight": {
+            "comment": "무게(kg) — 자동추론 없음, types에서 decimal 선언",
+            "type": "decimal"
+        },
+        "is_available": {
+            "comment": "판매 가능 여부 (is_* → TINYINT(1) 자동 추론)",
+            "default": true
+        },
+        "launched_at": {
+            "comment": "출시일시 (*_at → DATETIME 자동 추론)"
+        }
+    },
+    "types": {
+        "description": "text",
+        "thumbnail_url": "varchar(500)",
+        "spec_json": "text",
+        "barcode": "varchar(50)"
+    },
+    "comments": {
+        "description": "상품 설명 (긴 텍스트)",
+        "thumbnail_url": "썸네일 이미지 URL",
+        "spec_json": "상세 스펙 JSON",
+        "barcode": "바코드"
+    },
+    "defaults": {
+        "is_available": true,
+        "stock_qty": 0
+    },
+    "reset_defaults": [
+        {
+            "sku": "ELEC-001",
+            "category": "electronics",
+            "price": 99000,
+            "stock_qty": 100,
+            "is_available": true,
+            "description": "샘플 전자제품"
+        },
+        {
+            "sku": "FURN-001",
+            "category": "furniture",
+            "price": 299000,
+            "stock_qty": 20,
+            "is_available": true,
+            "description": "샘플 가구"
+        }
+    ]
+}

package/template/samples/entities/03_hash_and_unique.json

@@ -0,0 +1,33 @@
+{
+    "name": "member",
+    "description": "hash & unique 예제 — 민감 필드 해시 저장 + 단일/복합 유니크",
+    "index": {
+        "email": {
+            "comment": "이메일 (고유 — 중복 불가)",
+            "type": "email",
+            "required": true,
+            "unique": true
+        },
+        "phone": {
+            "comment": "전화번호 (해시 저장 — 평문 노출 차단)",
+            "hash": true
+        },
+        "resident_id": {
+            "comment": "주민등록번호 앞 7자리 (해시 + 유니크 — 중복 가입 방지)",
+            "hash": true,
+            "unique": true
+        },
+        "nickname": {
+            "comment": "닉네임 (unique — 중복 불가)"
+        },
+        "org_seq": {
+            "comment": "소속 조직 seq"
+        },
+        "status": {
+            "comment": "상태",
+            "type": ["active", "inactive", "withdrawn"],
+            "default": "active"
+        }
+    },
+    "unique": [["org_seq", "nickname"]]
+}

package/template/samples/entities/04_fk_and_composite_unique.json

@@ -0,0 +1,31 @@
+{
+    "name": "team_member",
+    "description": "외래키(fk) & 복합 유니크 예제 — 팀-사용자 다대다 중간 테이블",
+    "index": {
+        "team_seq": {
+            "comment": "팀 seq (fk: team.seq)",
+            "required": true
+        },
+        "user_seq": {
+            "comment": "사용자 seq (fk: user.seq)",
+            "required": true
+        },
+        "role": {
+            "comment": "팀 내 역할",
+            "type": ["owner", "admin", "member", "viewer"],
+            "default": "member"
+        },
+        "invited_by": {
+            "comment": "초대한 사용자 seq (fk: user.seq, nullable)"
+        },
+        "joined_at": {
+            "comment": "참가일시 (*_at → DATETIME 자동 추론)"
+        }
+    },
+    "unique": [["team_seq", "user_seq"]],
+    "fk": {
+        "team_seq": "team.seq",
+        "user_seq": "user.seq",
+        "invited_by": "user.seq"
+    }
+}

package/template/samples/entities/05_cache.json

@@ -0,0 +1,54 @@
+{
+    "name": "config_item",
+    "description": "캐시 예제 — 자주 읽히고 드물게 변경되는 설정값에 엔티티 레벨 캐시 활성화",
+    "index": {
+        "key": {
+            "comment": "설정 키 (고유)",
+            "required": true,
+            "unique": true
+        },
+        "category": {
+            "comment": "설정 카테고리",
+            "type": ["system", "ui", "feature_flag", "notification"],
+            "default": "system"
+        },
+        "is_public": {
+            "comment": "공개 여부 (is_* → TINYINT(1) 자동 추론)"
+        }
+    },
+    "types": {
+        "value": "text",
+        "description": "text"
+    },
+    "comments": {
+        "value": "설정 값 (JSON 또는 문자열)",
+        "description": "설정 설명"
+    },
+    "cache": {
+        "enabled": true,
+        "ttl_seconds": 600
+    },
+    "reset_defaults": [
+        {
+            "key": "site.name",
+            "category": "system",
+            "value": "My Service",
+            "is_public": true,
+            "description": "서비스명"
+        },
+        {
+            "key": "feature.dark_mode",
+            "category": "feature_flag",
+            "value": "true",
+            "is_public": true,
+            "description": "다크모드 기능 활성화"
+        },
+        {
+            "key": "notification.email_enabled",
+            "category": "notification",
+            "value": "true",
+            "is_public": false,
+            "description": "이메일 알림 활성화"
+        }
+    ]
+}

package/template/samples/entities/06_history_and_hard_delete.json

@@ -0,0 +1,42 @@
+{
+    "name": "article",
+    "description": "이력 보존(history_ttl) & 완전삭제(hard_delete) 예제 — 게시글 수정 이력 3년 보관",
+    "index": {
+        "author_seq": {
+            "comment": "작성자 user seq",
+            "required": true
+        },
+        "title": {
+            "comment": "제목",
+            "required": true
+        },
+        "category": {
+            "comment": "카테고리",
+            "type": ["notice", "blog", "faq", "news"],
+            "default": "blog"
+        },
+        "status": {
+            "comment": "게시 상태",
+            "type": ["draft", "published", "archived"],
+            "default": "draft"
+        },
+        "published_at": {
+            "comment": "게시일시 (*_at → DATETIME 자동 추론)"
+        },
+        "view_count": {
+            "comment": "조회 수 (*_count → INT 자동 추론)"
+        }
+    },
+    "types": {
+        "content": "text",
+        "summary": "text",
+        "tags_json": "text"
+    },
+    "comments": {
+        "content": "본문 (마크다운)",
+        "summary": "요약 (목록 표시용)",
+        "tags_json": "태그 배열 JSON"
+    },
+    "history_ttl": 1095,
+    "hard_delete": false
+}

package/template/samples/entities/07_license_scope.json

@@ -0,0 +1,43 @@
+{
+    "name": "workspace",
+    "description": "license_scope 예제 — 멀티테넌트에서 라이선스별 데이터 완전 분리",
+    "license_scope": true,
+    "index": {
+        "name": {
+            "comment": "워크스페이스명",
+            "required": true
+        },
+        "plan": {
+            "comment": "플랜",
+            "type": ["free", "starter", "pro", "enterprise"],
+            "default": "free"
+        },
+        "max_members": {
+            "comment": "최대 팀원 수 (자동추론: 직접 uint 선언)"
+        },
+        "owner_seq": {
+            "comment": "소유자 user seq"
+        },
+        "is_active": {
+            "comment": "활성 여부 (is_* → TINYINT(1) 자동 추론)",
+            "default": true
+        },
+        "expires_at": {
+            "comment": "만료일시 (*_at → DATETIME 자동 추론)"
+        }
+    },
+    "types": {
+        "max_members": "uint",
+        "settings_json": "text"
+    },
+    "comments": {
+        "settings_json": "워크스페이스 설정 JSON"
+    },
+    "defaults": {
+        "max_members": 5
+    },
+    "cache": {
+        "enabled": true,
+        "ttl_seconds": 120
+    }
+}

package/template/samples/entities/08_hook_sql.json

@@ -0,0 +1,52 @@
+{
+    "name": "user_point",
+    "description": "SQL 훅 예제 — INSERT/UPDATE 시 자동 감사 로그 기록 (실행형) + SELECT 결과 주입 (조회형)",
+    "index": {
+        "user_seq": {
+            "comment": "사용자 seq",
+            "required": true,
+            "unique": true
+        },
+        "point": {
+            "comment": "보유 포인트",
+            "type": "uint"
+        },
+        "grade": {
+            "comment": "등급",
+            "type": ["bronze", "silver", "gold", "platinum"],
+            "default": "bronze"
+        },
+        "updated_at": {
+            "comment": "마지막 포인트 변경일시 (*_at → DATETIME 자동 추론)"
+        }
+    },
+    "hooks": {
+        "after_insert": [
+            {
+                "comment": "포인트 생성 이력 기록 (실행형 SQL 훅)",
+                "type": "sql",
+                "query": "INSERT INTO point_history (user_seq, delta, reason, created_time) VALUES (?, ?, ?, NOW())",
+                "params": ["${new.user_seq}", "${new.point}", "initial_grant"],
+                "async": false
+            }
+        ],
+        "after_update": [
+            {
+                "comment": "포인트 변경 이력 기록 (실행형 SQL 훅)",
+                "type": "sql",
+                "query": "INSERT INTO point_history (user_seq, delta, reason, created_time) VALUES (?, ?, ?, NOW())",
+                "params": ["${new.user_seq}", "${new.point}", "update"],
+                "async": true
+            }
+        ],
+        "after_get": [
+            {
+                "comment": "최근 포인트 변경 이력 5건 주입 (조회형 SQL 훅)",
+                "type": "sql",
+                "query": "SELECT delta, reason, created_time FROM point_history WHERE user_seq = ? ORDER BY created_time DESC LIMIT 5",
+                "params": ["${new.user_seq}"],
+                "assign_to": "recent_history"
+            }
+        ]
+    }
+}

package/template/samples/entities/09_hook_entity.json

@@ -0,0 +1,71 @@
+{
+    "name": "post",
+    "description": "entity 훅 예제 — after_get/after_list 시 관련 엔티티 데이터를 자동 주입",
+    "index": {
+        "author_seq": {
+            "comment": "작성자 user seq",
+            "required": true
+        },
+        "title": {
+            "comment": "제목",
+            "required": true
+        },
+        "status": {
+            "comment": "상태",
+            "type": ["draft", "published", "hidden"],
+            "default": "draft"
+        },
+        "comment_count": {
+            "comment": "댓글 수 (*_count → INT 자동 추론)"
+        },
+        "like_count": {
+            "comment": "좋아요 수 (*_count → INT 자동 추론)"
+        },
+        "published_at": {
+            "comment": "게시일시 (*_at → DATETIME 자동 추론)"
+        }
+    },
+    "types": {
+        "content": "text"
+    },
+    "comments": {
+        "content": "본문"
+    },
+    "hooks": {
+        "after_get": [
+            {
+                "comment": "게시글 조회 시 작성자 프로필 자동 주입",
+                "type": "entity",
+                "entity": "user",
+                "action": "get",
+                "conditions": {
+                    "seq": "${new.author_seq}"
+                },
+                "assign_to": "author"
+            },
+            {
+                "comment": "게시글 조회 시 최근 댓글 10개 자동 주입",
+                "type": "entity",
+                "entity": "comment",
+                "action": "list",
+                "conditions": {
+                    "post_seq": "${new.seq}",
+                    "status": "visible"
+                },
+                "assign_to": "comments"
+            }
+        ],
+        "after_list": [
+            {
+                "comment": "목록 조회 시 각 게시글에 작성자 이름 주입",
+                "type": "entity",
+                "entity": "user",
+                "action": "get",
+                "conditions": {
+                    "seq": "${new.author_seq}"
+                },
+                "assign_to": "author"
+            }
+        ]
+    }
+}