create-entity-server 0.0.9 → 0.0.15

package/template/samples/entities/10_hook_submit_delete.json

@@ -0,0 +1,75 @@
+{
+    "name": "project",
+    "description": "submit & delete 훅 예제 — 프로젝트 생성 시 기본 태스크 자동 생성, 삭제 시 연관 데이터 정리",
+    "index": {
+        "owner_seq": {
+            "comment": "프로젝트 소유자 user seq",
+            "required": true
+        },
+        "name": {
+            "comment": "프로젝트명",
+            "required": true
+        },
+        "status": {
+            "comment": "진행 상태",
+            "type": ["planning", "active", "on_hold", "completed", "cancelled"],
+            "default": "planning"
+        },
+        "due_date": {
+            "comment": "마감일 (*_date → DATE 자동 추론)"
+        },
+        "task_count": {
+            "comment": "태스크 수 (*_count → INT 자동 추론)"
+        }
+    },
+    "types": {
+        "description": "text"
+    },
+    "hooks": {
+        "after_insert": [
+            {
+                "comment": "프로젝트 생성 시 기본 태스크 3개 자동 생성 (submit 훅)",
+                "type": "submit",
+                "entity": "task",
+                "data": {
+                    "project_seq": "${new.seq}",
+                    "title": "요구사항 분석",
+                    "status": "todo",
+                    "priority": "high"
+                }
+            },
+            {
+                "comment": "프로젝트 멤버에 소유자 자동 추가 (submit 훅 Upsert)",
+                "type": "submit",
+                "entity": "project_member",
+                "match": {
+                    "project_seq": "${new.seq}",
+                    "user_seq": "${new.owner_seq}"
+                },
+                "data": {
+                    "project_seq": "${new.seq}",
+                    "user_seq": "${new.owner_seq}",
+                    "role": "owner"
+                }
+            }
+        ],
+        "after_delete": [
+            {
+                "comment": "프로젝트 삭제 시 모든 태스크 삭제 (delete 훅)",
+                "type": "delete",
+                "entity": "task",
+                "match": {
+                    "project_seq": "${old.seq}"
+                }
+            },
+            {
+                "comment": "프로젝트 삭제 시 멤버 목록 삭제 (delete 훅)",
+                "type": "delete",
+                "entity": "project_member",
+                "match": {
+                    "project_seq": "${old.seq}"
+                }
+            }
+        ]
+    }
+}

package/template/samples/entities/11_hook_webhook.json

@@ -0,0 +1,82 @@
+{
+    "name": "payment",
+    "description": "webhook 훅 예제 — 결제 완료/환불 시 외부 정산 서비스 실시간 통보",
+    "index": {
+        "order_seq": {
+            "comment": "주문 seq",
+            "required": true
+        },
+        "user_seq": {
+            "comment": "결제자 user seq",
+            "required": true
+        },
+        "amount": {
+            "comment": "결제 금액 (*_amount → DECIMAL(15,2) 자동 추론)",
+            "required": true
+        },
+        "method": {
+            "comment": "결제 수단",
+            "type": ["card", "bank_transfer", "virtual_account", "point"],
+            "required": true
+        },
+        "status": {
+            "comment": "결제 상태",
+            "type": ["pending", "paid", "cancelled", "refunded"],
+            "default": "pending"
+        },
+        "paid_at": {
+            "comment": "결제 완료일시 (*_at → DATETIME 자동 추론)"
+        }
+    },
+    "types": {
+        "pg_transaction_id": "varchar(100)",
+        "failure_reason": "text"
+    },
+    "comments": {
+        "pg_transaction_id": "PG사 거래 ID",
+        "failure_reason": "실패 사유"
+    },
+    "hooks": {
+        "after_insert": [
+            {
+                "comment": "결제 생성 시 정산 서버로 비동기 통보 (webhook 훅)",
+                "type": "webhook",
+                "url": "https://settlement.internal/hooks/payment-created",
+                "method": "POST",
+                "headers": {
+                    "Authorization": "Bearer ${ctx.webhook_secret}",
+                    "Content-Type": "application/json"
+                },
+                "body": {
+                    "payment_seq": "${new.seq}",
+                    "order_seq": "${new.order_seq}",
+                    "user_seq": "${new.user_seq}",
+                    "amount": "${new.amount}",
+                    "method": "${new.method}",
+                    "status": "${new.status}"
+                },
+                "async": true,
+                "timeout": 5000
+            }
+        ],
+        "after_update": [
+            {
+                "comment": "결제 상태 변경(환불 등) 시 정산 서버에 동기 통보 (webhook 훅)",
+                "type": "webhook",
+                "url": "https://settlement.internal/hooks/payment-updated",
+                "method": "POST",
+                "headers": {
+                    "Authorization": "Bearer ${ctx.webhook_secret}"
+                },
+                "body": {
+                    "payment_seq": "${new.seq}",
+                    "old_status": "${old.status}",
+                    "new_status": "${new.status}",
+                    "amount": "${new.amount}"
+                },
+                "async": false,
+                "timeout": 8000
+            }
+        ]
+    }
+}

package/template/samples/entities/12_hook_push.json

@@ -0,0 +1,73 @@
+{
+    "name": "delivery",
+    "description": "push 훅 예제 — 배송 상태 변경 시 고객에게 푸시 알림 전송 (다단계 상태 알림)",
+    "index": {
+        "order_seq": {
+            "comment": "주문 seq",
+            "required": true
+        },
+        "customer_seq": {
+            "comment": "고객 user seq",
+            "required": true
+        },
+        "tracking_number": {
+            "comment": "운송장 번호",
+            "unique": true
+        },
+        "carrier": {
+            "comment": "택배사",
+            "type": ["cj", "lotte", "hanjin", "post", "direct"],
+            "default": "cj"
+        },
+        "status": {
+            "comment": "배송 상태",
+            "type": [
+                "ready",
+                "picked_up",
+                "in_transit",
+                "out_for_delivery",
+                "delivered",
+                "failed"
+            ],
+            "default": "ready"
+        },
+        "estimated_date": {
+            "comment": "예상 도착일 (*_date → DATE 자동 추론)"
+        },
+        "delivered_at": {
+            "comment": "배송 완료일시 (*_at → DATETIME 자동 추론)"
+        }
+    },
+    "hooks": {
+        "after_insert": [
+            {
+                "comment": "배송 시작 푸시 알림",
+                "type": "push",
+                "target_user_field": "customer_seq",
+                "title": "배송 시작",
+                "push_body": "주문 #${new.order_seq}의 배송이 시작되었습니다. 운송장: ${new.tracking_number}",
+                "push_data": {
+                    "action": "delivery_started",
+                    "delivery_seq": "${new.seq}",
+                    "tracking_number": "${new.tracking_number}"
+                }
+            }
+        ],
+        "after_update": [
+            {
+                "comment": "배송 상태 변경 시 푸시 알림",
+                "type": "push",
+                "target_user_field": "customer_seq",
+                "title": "배송 상태 업데이트",
+                "push_body": "배송 상태가 '${new.status}'(으)로 변경되었습니다. 운송장: ${new.tracking_number}",
+                "push_data": {
+                    "action": "delivery_status_changed",
+                    "delivery_seq": "${new.seq}",
+                    "old_status": "${old.status}",
+                    "new_status": "${new.status}",
+                    "tracking_number": "${new.tracking_number}"
+                }
+            }
+        ]
+    }
+}

package/template/samples/entities/13_read_only.json

@@ -0,0 +1,51 @@
+{
+    "name": "activity_log",
+    "description": "read_only 예제 — API를 통한 수정·삭제가 불가하고 서버 내부(훅/SP) 로만 기록되는 감사 로그",
+    "read_only": true,
+    "license_scope": false,
+    "hard_delete": true,
+    "history_ttl": 0,
+    "index": {
+        "actor_seq": {
+            "comment": "행위자 user seq (null = 시스템)"
+        },
+        "entity_name": {
+            "comment": "대상 엔티티명",
+            "required": true
+        },
+        "entity_seq": {
+            "comment": "대상 레코드 seq"
+        },
+        "action": {
+            "comment": "수행된 작업",
+            "type": [
+                "INSERT",
+                "UPDATE",
+                "DELETE",
+                "LOGIN",
+                "LOGOUT",
+                "EXPORT",
+                "IMPORT"
+            ],
+            "required": true
+        },
+        "ip_address": {
+            "comment": "요청 IP",
+            "type": "varchar(45)"
+        },
+        "result_code": {
+            "comment": "결과 코드 (HTTP 상태)",
+            "type": "int"
+        }
+    },
+    "types": {
+        "before_snapshot": "text",
+        "after_snapshot": "text",
+        "detail": "text"
+    },
+    "comments": {
+        "before_snapshot": "변경 전 데이터 스냅샷 (JSON)",
+        "after_snapshot": "변경 후 데이터 스냅샷 (JSON)",
+        "detail": "추가 상세 정보"
+    }
+}

package/template/samples/entities/14_optimistic_lock.json

@@ -0,0 +1,29 @@
+{
+    "name": "inventory",
+    "description": "optimistic_lock 예제 — 동시 수정 충돌 방지가 필요한 재고 엔티티",
+    "optimistic_lock": true,
+    "index": {
+        "product_seq": {
+            "comment": "상품 seq",
+            "required": true,
+            "unique": true
+        },
+        "warehouse_code": {
+            "comment": "창고 코드",
+            "required": true
+        },
+        "qty_available": {
+            "comment": "가용 재고 수량 (*_qty → INT 자동 추론)"
+        },
+        "qty_reserved": {
+            "comment": "예약된 재고 수량 (*_qty → INT 자동 추론)"
+        },
+        "location": {
+            "comment": "창고 내 위치 (예: A-01-03)"
+        },
+        "last_stocked_at": {
+            "comment": "마지막 입고일시 (*_at → DATETIME 자동 추론)"
+        }
+    },
+    "unique": [["product_seq", "warehouse_code"]]
+}

package/template/samples/entities/15_reset_defaults.json

@@ -0,0 +1,95 @@
+{
+    "name": "country",
+    "description": "reset_defaults 예제 — reset-all 실행 시 주요 국가 코드 자동 시딩",
+    "index": {
+        "code": {
+            "comment": "ISO 3166-1 alpha-2 국가 코드 (예: KR, US)",
+            "required": true,
+            "unique": true
+        },
+        "name_ko": {
+            "comment": "국가명 (한국어)"
+        },
+        "name_en": {
+            "comment": "국가명 (영어)"
+        },
+        "region": {
+            "comment": "대륙/지역",
+            "type": [
+                "asia",
+                "europe",
+                "americas",
+                "africa",
+                "oceania",
+                "middle_east"
+            ]
+        },
+        "phone_code": {
+            "comment": "국가 전화 코드 (예: +82)"
+        },
+        "is_active": {
+            "comment": "서비스 지원 여부 (is_* → TINYINT(1) 자동 추론)",
+            "default": true
+        }
+    },
+    "license_scope": false,
+    "hard_delete": true,
+    "reset_defaults": [
+        {
+            "code": "KR",
+            "name_ko": "대한민국",
+            "name_en": "South Korea",
+            "region": "asia",
+            "phone_code": "+82",
+            "is_active": true
+        },
+        {
+            "code": "US",
+            "name_ko": "미국",
+            "name_en": "United States",
+            "region": "americas",
+            "phone_code": "+1",
+            "is_active": true
+        },
+        {
+            "code": "JP",
+            "name_ko": "일본",
+            "name_en": "Japan",
+            "region": "asia",
+            "phone_code": "+81",
+            "is_active": true
+        },
+        {
+            "code": "CN",
+            "name_ko": "중국",
+            "name_en": "China",
+            "region": "asia",
+            "phone_code": "+86",
+            "is_active": true
+        },
+        {
+            "code": "DE",
+            "name_ko": "독일",
+            "name_en": "Germany",
+            "region": "europe",
+            "phone_code": "+49",
+            "is_active": true
+        },
+        {
+            "code": "GB",
+            "name_ko": "영국",
+            "name_en": "United Kingdom",
+            "region": "europe",
+            "phone_code": "+44",
+            "is_active": true
+        },
+        {
+            "code": "SG",
+            "name_ko": "싱가포르",
+            "name_en": "Singapore",
+            "region": "asia",
+            "phone_code": "+65",
+            "is_active": true
+        }
+    ]
+}

package/template/samples/entities/README.md

@@ -0,0 +1,94 @@
+# 엔티티 설정 예제
+
+`entities/` 디렉토리에 배치하는 `.json` 설정 파일 예제 모음입니다.  
+엔티티 서버의 **모든 주요 기능을 하나씩** 알아볼 수 있도록 주제별로 구성하였습니다.
+
+> **전체 레퍼런스**: [docs/ops/entity-config-guide.md](../../docs/ops/entity-config-guide.md)  
+> **훅 가이드**: [docs/ops/hooks.md](../../docs/ops/hooks.md)
+
+---
+
+## 기능별 샘플 목록
+
+### 기본 필드 & 타입
+
+| 파일                                                     | 엔티티    | 설명                                                                                                                         |
+| -------------------------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| [01_basic_fields.json](01_basic_fields.json)             | `contact` | 필드명 패턴으로 타입이 **자동 추론**되는 모든 케이스 (`_seq`, `_date`, `_at`, `is_*`, `_count`, `_amount`, `email`, `phone`) |
+| [02_types_and_defaults.json](02_types_and_defaults.json) | `product` | 자동 추론이 안 될 때 **`types` 명시 선언** + `defaults` + `reset_defaults` 시딩                                              |
+
+### 제약 & 참조
+
+| 파일                                                               | 엔티티        | 설명                                                                     |
+| ------------------------------------------------------------------ | ------------- | ------------------------------------------------------------------------ |
+| [03_hash_and_unique.json](03_hash_and_unique.json)                 | `member`      | **`hash`** (민감 필드 해시 저장) + **단일 `unique`** + **복합 `unique`** |
+| [04_fk_and_composite_unique.json](04_fk_and_composite_unique.json) | `team_member` | **`fk`** 외래키 참조 + **복합 유니크** (`team_seq + user_seq`)           |
+
+### 성능 & 운영
+
+| 파일                                                               | 엔티티        | 설명                                                                      |
+| ------------------------------------------------------------------ | ------------- | ------------------------------------------------------------------------- |
+| [05_cache.json](05_cache.json)                                     | `config_item` | **`cache`** 엔티티 레벨 캐시 (`ttl_seconds: 600`)                         |
+| [06_history_and_hard_delete.json](06_history_and_hard_delete.json) | `article`     | **`history_ttl`** 수정 이력 3년 보관 + **`hard_delete: false`** 논리 삭제 |
+| [14_optimistic_lock.json](14_optimistic_lock.json)                 | `inventory`   | **`optimistic_lock`** 동시 수정 충돌 방지 (재고 등 경쟁 조건 있는 데이터) |
+
+### 멀티테넌트
+
+| 파일                                           | 엔티티      | 설명                                                         |
+| ---------------------------------------------- | ----------- | ------------------------------------------------------------ |
+| [07_license_scope.json](07_license_scope.json) | `workspace` | **`license_scope: true`** 라이선스별 데이터 완전 분리 + 캐시 |
+
+### 특수 모드
+
+| 파일                                             | 엔티티         | 설명                                                                             |
+| ------------------------------------------------ | -------------- | -------------------------------------------------------------------------------- |
+| [13_read_only.json](13_read_only.json)           | `activity_log` | **`read_only: true`** API로 수정 불가, 서버 내부(훅/SP)에서만 기록되는 감사 로그 |
+| [15_reset_defaults.json](15_reset_defaults.json) | `country`      | **`reset_defaults`** 대량 시딩 — `reset-all` 시 국가 코드 자동 입력              |
+
+### 훅 (Hooks)
+
+| 파일                                                     | 엔티티       | 훅 타입             | 설명                                                                      |
+| -------------------------------------------------------- | ------------ | ------------------- | ------------------------------------------------------------------------- |
+| [08_hook_sql.json](08_hook_sql.json)                     | `user_point` | `sql`               | 실행형 SQL (포인트 이력 INSERT) + 조회형 SQL (`assign_to`로 결과 주입)    |
+| [09_hook_entity.json](09_hook_entity.json)               | `post`       | `entity`            | `after_get`/`after_list`에서 관련 엔티티 자동 주입 (작성자 프로필, 댓글)  |
+| [10_hook_submit_delete.json](10_hook_submit_delete.json) | `project`    | `submit` / `delete` | 생성 시 연관 엔티티 자동 생성(Upsert 포함), 삭제 시 연관 데이터 자동 정리 |
+| [11_hook_webhook.json](11_hook_webhook.json)             | `payment`    | `webhook`           | 외부 HTTP 통보 — 비동기(결제 생성) + 동기(상태 변경)                      |
+| [12_hook_push.json](12_hook_push.json)                   | `delivery`   | `push`              | 배송 상태 변경 시 고객 FCM 푸시 알림                                      |
+
+### 이전 예제
+
+| 파일                                               | 엔티티               | 설명                                          |
+| -------------------------------------------------- | -------------------- | --------------------------------------------- |
+| [order_notification.json](order_notification.json) | `order_notification` | 주문 생성/수정 시 push 훅 (push 훅 기본 예제) |
+
+---
+
+## 훅 타입 한눈에 보기
+
+| 훅 타입   | 핵심 필드                                 | 주요 용도               | 샘플                                           |
+| --------- | ----------------------------------------- | ----------------------- | ---------------------------------------------- |
+| `sql`     | `query`, `params`                         | SQL 실행 또는 결과 주입 | `08_hook_sql.json`                             |
+| `entity`  | `entity`, `action`, `assign_to`           | 관련 데이터 자동 로드   | `09_hook_entity.json`                          |
+| `submit`  | `entity`, `data`, `match`                 | 다른 엔티티 생성/수정   | `10_hook_submit_delete.json`                   |
+| `delete`  | `entity`, `match`                         | 다른 엔티티 삭제        | `10_hook_submit_delete.json`                   |
+| `webhook` | `url`, `body`, `async`                    | 외부 HTTP 호출          | `11_hook_webhook.json`                         |
+| `push`    | `target_user_field`, `title`, `push_body` | FCM 푸시 알림 전송      | `12_hook_push.json`, `order_notification.json` |
+
+## 훅 실행 시점
+
+| 시점           | 설명           | 주로 사용                  |
+| -------------- | -------------- | -------------------------- |
+| `after_insert` | 데이터 삽입 후 | 감사 로그, 알림, 연관 생성 |
+| `after_update` | 데이터 수정 후 | 변경 이력, 상태 알림       |
+| `after_delete` | 데이터 삭제 후 | 연관 데이터 정리           |
+| `after_get`    | 단건 조회 후   | 관련 데이터 병합           |
+| `after_list`   | 목록 조회 후   | 각 항목 추가 정보 주입     |
+
+## 훅 템플릿 변수
+
+| 변수                 | 설명                          |
+| -------------------- | ----------------------------- |
+| `${new.field}`       | 삽입/수정 후 데이터의 필드 값 |
+| `${old.field}`       | 수정/삭제 전 데이터의 필드 값 |
+| `${ctx.license_seq}` | 현재 요청의 라이선스 seq      |
+| `${ctx.user_seq}`    | 현재 로그인 사용자 seq        |

package/template/samples/entities/order_notification.json

@@ -0,0 +1,51 @@
+{
+    "name": "order_notification",
+    "description": "주문 알림 예제 — 주문 생성 시 고객에게 푸시 전송",
+    "index": {
+        "customer_seq": {
+            "comment": "고객 user seq",
+            "required": true
+        },
+        "order_number": {
+            "comment": "주문 번호",
+            "required": true
+        },
+        "status": {
+            "comment": "주문 상태",
+            "type": ["placed", "confirmed", "shipped", "delivered", "cancelled"],
+            "default": "placed"
+        },
+        "total_amount": {
+            "comment": "주문 금액",
+            "type": "uint"
+        }
+    },
+    "hooks": {
+        "after_insert": [
+            {
+                "type": "push",
+                "target_user_field": "customer_seq",
+                "title": "주문 접수",
+                "push_body": "주문 #${new.order_number}이 접수되었습니다. 금액: ${new.total_amount}원",
+                "push_data": {
+                    "action": "order_created",
+                    "order_seq": "${new.seq}",
+                    "order_number": "${new.order_number}"
+                }
+            }
+        ],
+        "after_update": [
+            {
+                "type": "push",
+                "target_user_field": "customer_seq",
+                "title": "주문 상태 변경",
+                "push_body": "주문 #${new.order_number} 상태: ${new.status}",
+                "push_data": {
+                    "action": "order_updated",
+                    "order_seq": "${new.seq}",
+                    "status": "${new.status}"
+                }
+            }
+        ]
+    }
+}

package/template/samples/flutter/lib/entity_server_client.dart

@@ -125,6 +125,97 @@ class EntityServerClient {
   Future<Map<String, dynamic>> rollback(String entity, int historySeq) =>
       _request('POST', '/v1/entity/$entity/rollback/$historySeq');
 
+  /// 푸시 발송 트리거 엔티티에 submit합니다.
+  Future<Map<String, dynamic>> push(
+    String pushEntity,
+    Map<String, dynamic> payload, {
+    String? transactionId,
+  }) =>
+      submit(pushEntity, payload, transactionId: transactionId);
+
+  /// push_log 목록 조회 헬퍼
+  Future<Map<String, dynamic>> pushLogList({int page = 1, int limit = 20}) =>
+      list('push_log', page: page, limit: limit);
+
+  /// account_device 디바이스 등록/갱신 헬퍼 (push_token 단일 필드)
+  Future<Map<String, dynamic>> registerPushDevice(
+    int accountSeq,
+    String deviceId,
+    String pushToken, {
+    String? platform,
+    String? deviceType,
+    String? browser,
+    String? browserVersion,
+    bool pushEnabled = true,
+    String? transactionId,
+  }) {
+    final payload = <String, dynamic>{
+      'id': deviceId,
+      'account_seq': accountSeq,
+      'push_token': pushToken,
+      'push_enabled': pushEnabled,
+      if (platform != null && platform.isNotEmpty) 'platform': platform,
+      if (deviceType != null && deviceType.isNotEmpty)
+        'device_type': deviceType,
+      if (browser != null && browser.isNotEmpty) 'browser': browser,
+      if (browserVersion != null && browserVersion.isNotEmpty)
+        'browser_version': browserVersion,
+    };
+    return submit('account_device', payload, transactionId: transactionId);
+  }
+
+  /// account_device.seq 기준 push_token 갱신 헬퍼
+  Future<Map<String, dynamic>> updatePushDeviceToken(
+    int deviceSeq,
+    String pushToken, {
+    bool pushEnabled = true,
+    String? transactionId,
+  }) {
+    return submit('account_device', {
+      'seq': deviceSeq,
+      'push_token': pushToken,
+      'push_enabled': pushEnabled,
+    }, transactionId: transactionId);
+  }
+
+  /// account_device.seq 기준 푸시 수신 비활성화 헬퍼
+  Future<Map<String, dynamic>> disablePushDevice(
+    int deviceSeq, {
+    String? transactionId,
+  }) {
+    return submit('account_device', {
+      'seq': deviceSeq,
+      'push_enabled': false,
+    }, transactionId: transactionId);
+  }
+
+  /// 요청 본문을 읽어 JSON으로 반환합니다.
+  /// - application/octet-stream: 암호 패킷 복호화
+  /// - 그 외: 평문 JSON 파싱
+  Future<Map<String, dynamic>> readRequestBody(
+    Uint8List rawBody, {
+    String contentType = 'application/json',
+    bool requireEncrypted = false,
+  }) async {
+    final lowered = contentType.toLowerCase();
+    final isEncrypted = lowered.contains('application/octet-stream');
+
+    if (requireEncrypted && !isEncrypted) {
+      throw Exception(
+          'Encrypted request required: Content-Type must be application/octet-stream');
+    }
+
+    if (isEncrypted) {
+      if (rawBody.isEmpty) {
+        throw Exception('Encrypted request body is empty');
+      }
+      return await _decryptPacket(rawBody);
+    }
+
+    if (rawBody.isEmpty) return {};
+    return jsonDecode(utf8.decode(rawBody)) as Map<String, dynamic>;
+  }
+
   // ─── 내부 ─────────────────────────────────────────────────────────
 
   Future<Map<String, dynamic>> _request(