create-entity-app-server 0.0.3

package/scripts/run.sh

@@ -0,0 +1,202 @@
+#!/bin/bash
+# run.sh — Entity App Server 실행 / 종료
+#
+# 사용법:
+#   ./scripts/run.sh start   — 프로덕션 모드 백그라운드 실행 (dist/system.js)
+#   ./scripts/run.sh stop    — 실행 중인 서버 종료
+#   ./scripts/run.sh dev     — 개발 모드 실행 (tsx watch)
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
+
+cd "$PROJECT_ROOT"
+
+# .env 로드
+[ -f ".env" ] && set -o allexport && source .env && set +o allexport
+
+PID_FILE="$PROJECT_ROOT/.gateway.pid"
+LOG_FILE="$PROJECT_ROOT/logs/gateway.log"
+
+get_gateway_port() {
+    local config_port
+    local env_port
+
+    env_port="${SERVER_PORT:-${PORT:-}}"
+    env_port=$(echo "$env_port" | tr -d '[:space:]')
+    if [[ "$env_port" =~ ^[0-9]+$ ]] && [ "$env_port" -gt 0 ]; then
+        echo "$env_port"
+        return
+    fi
+
+    if [ -f "$PROJECT_ROOT/configs/server.json" ]; then
+        config_port=$(grep -E '"port"[[:space:]]*:' "$PROJECT_ROOT/configs/server.json" | head -n 1 | sed -E 's/.*:[[:space:]]*([0-9]+).*/\1/')
+        config_port=$(echo "$config_port" | tr -d '[:space:]')
+        if [[ "$config_port" =~ ^[0-9]+$ ]] && [ "$config_port" -gt 0 ]; then
+            echo "$config_port"
+            return
+        fi
+    fi
+
+    echo "3000"
+}
+
+find_gateway_pids() {
+    local port
+    port=$(get_gateway_port)
+    ss -ltnp 2>/dev/null | sed -n "s/.*:$port .*pid=\([0-9]\+\).*/\1/p" | sort -u
+}
+
+show_port_in_use_error() {
+    local port
+    port=$(get_gateway_port)
+
+    echo "❌ 포트 $port 는 이미 사용 중입니다. Entity App Server를 시작하지 않습니다."
+
+    echo "   먼저 종료하려면: $0 stop"
+}
+
+ensure_port_available() {
+    mapfile -t PORT_PIDS < <(find_gateway_pids)
+    if [ "${#PORT_PIDS[@]}" -gt 0 ]; then
+        show_port_in_use_error
+        exit 1
+    fi
+}
+
+stop_pid() {
+    local pid="$1"
+
+    if [ -z "$pid" ]; then
+        return 1
+    fi
+
+    if ! kill -0 "$pid" 2>/dev/null; then
+        return 1
+    fi
+
+    kill "$pid" 2>/dev/null || true
+
+    for _ in $(seq 1 50); do
+        if ! kill -0 "$pid" 2>/dev/null; then
+            return 0
+        fi
+        sleep 0.1
+    done
+
+    kill -9 "$pid" 2>/dev/null || true
+    return 0
+}
+
+_print_help() {
+    echo ""
+    echo "  Entity App Server 실행"
+    echo "  ================"
+    echo ""
+    echo "  사용법: $0 <명령>"
+    echo ""
+    echo "  명령:"
+    echo "    start   프로덕션 모드로 백그라운드 실행 (dist/system.js)"
+    echo "    stop    실행 중인 서버 종료"
+    echo "    dev     개발 모드 실행 (tsx watch)"
+    echo ""
+    echo "  예제:"
+    echo "    $0 start       # 서버 시작"
+    echo "    $0 stop        # 서버 종료"
+    echo "    $0 dev         # 개발 모드"
+    echo ""
+    if [ -f "$PID_FILE" ]; then
+        local PID
+        PID=$(cat "$PID_FILE")
+        if kill -0 "$PID" 2>/dev/null; then
+            echo "  현재 상태: 실행 중 (PID $PID)  로그: $LOG_FILE"
+        else
+            echo "  현재 상태: 종료됨 (stale PID 파일 존재)"
+        fi
+        echo ""
+    fi
+}
+
+if [ $# -eq 0 ]; then
+    _print_help
+    exit 0
+fi
+
+case "$1" in
+    start)
+        ensure_port_available
+
+        if [ ! -f "dist/system.js" ]; then
+            echo "❌ dist/system.js가 없습니다. 먼저 빌드하세요:"
+            echo "   ./scripts/build.sh prod"
+            exit 1
+        fi
+
+        # 이미 실행 중인지 확인
+        if [ -f "$PID_FILE" ]; then
+            PID=$(cat "$PID_FILE")
+            if kill -0 "$PID" 2>/dev/null; then
+                echo "  ⚠️  이미 실행 중입니다 (PID $PID)"
+                echo "  종료하려면: $0 stop"
+                exit 0
+            fi
+            rm -f "$PID_FILE"
+        fi
+
+        mkdir -p "$(dirname "$LOG_FILE")"
+        nohup node --import tsx/esm dist/system.js >> "$LOG_FILE" 2>&1 &
+        echo $! > "$PID_FILE"
+        PID=$(cat "$PID_FILE")
+
+        echo ""
+        echo "  ✓ Entity App Server 시작됨"
+        echo "    PID: $PID"
+        echo "    로그: $LOG_FILE"
+        echo "    종료: $0 stop"
+        echo ""
+        ;;
+
+    stop)
+        stopped_any=false
+
+        if [ -f "$PID_FILE" ]; then
+            PID=$(cat "$PID_FILE")
+            if stop_pid "$PID"; then
+                echo "  ✓ Entity App Server 종료됨 (PID $PID)"
+                stopped_any=true
+            fi
+            rm -f "$PID_FILE"
+        fi
+
+        mapfile -t PORT_PIDS < <(find_gateway_pids)
+        for PID in "${PORT_PIDS[@]}"; do
+            if stop_pid "$PID"; then
+                echo "  ✓ Entity App Server 종료됨 (port PID $PID)"
+                stopped_any=true
+            fi
+        done
+
+        rm -f "$PID_FILE"
+
+        if [ "$stopped_any" = false ]; then
+            echo "  실행 중인 Entity App Server 프로세스를 찾지 못했습니다."
+        fi
+        ;;
+
+    dev)
+        if [ -f "$PID_FILE" ] || [ -n "$(find_gateway_pids | head -n 1)" ]; then
+            echo "  기존 Entity App Server 정리 중..."
+            "$SCRIPT_DIR/run.sh" stop
+        fi
+
+        echo "  Starting Entity App Server (dev mode)..."
+        exec npm run dev
+        ;;
+
+    *)
+        echo "❌ 알 수 없는 명령: $1"
+        _print_help
+        exit 1
+        ;;
+esac

package/src/app/hooks/README.md

@@ -0,0 +1,148 @@
+# app/hooks/
+
+Entity Server CRUD 요청 전/후에 실행되는 비즈니스 훅 모음.
+
+## 구조
+
+```
+hooks/
+├── index.ts             — 엔티티별 훅 등록 테이블 (유일한 진입점)
+├── order.ts             — 주문 훅 예시 (모든 훅 메서드 시연)
+├── post.ts              — 게시글 훅 예시
+└── {entity}.ts          — 추가 엔티티 훅
+```
+
+## 동작 원리
+
+```
+클라이언트 요청
+  └─ Gateway 미들웨어
+       └─ 훅 체크 → before 훅 실행
+            └─ Entity Server 요청
+                 └─ after 훅 실행 → 클라이언트 응답
+```
+
+- `registry.ts` 의 키가 Entity Server 엔티티 이름과 일치해야 한다.
+- 훅이 없는 엔티티는 전/후 처리 없이 그대로 통과한다.
+- `find` (목록 조회)에도 `afterGet`이 자동 적용된다.
+
+## 훅 메서드 일람
+
+| 메서드         | 시점         | 반환값                   | 설명                           |
+| -------------- | ------------ | ------------------------ | ------------------------------ |
+| `beforeGet`    | 단건 조회 전 | `boolean` (false = 차단) | 접근 제어                      |
+| `afterGet`     | 단건 조회 후 | 가공된 데이터            | 마스킹, 필드 추가/제거         |
+| `beforeSubmit` | 등록/수정 전 | 실제 저장될 데이터       | 검증, 자동 필드 설정           |
+| `afterSubmit`  | 등록/수정 후 | 최종 응답 데이터         | 알림, 연관 처리                |
+| `beforeDelete` | 삭제 전      | `boolean` (false = 차단) | 삭제 조건 검증                 |
+| `afterDelete`  | 삭제 후      | `void`                   | 연관 데이터 정리               |
+| `beforeList`   | 목록 조회 전 | 가공된 params            | 기본 정렬·필터 추가, 접근 제어 |
+| `afterList`    | 목록 조회 후 | 가공된 응답              | 응답 데이터 변환               |
+
+모든 메서드는 선택 구현이다. 필요한 것만 정의하면 된다.
+
+## 새 훅 추가 방법
+
+### 1) 훅 파일 생성
+
+```ts
+// app/hooks/my-entity.ts
+import type {
+    EntityHook,
+    UserInfo,
+    SubmitContext,
+    DeleteContext,
+} from "@gateway/api";
+import { logger, ForbiddenError, ValidationError } from "@gateway/api";
+
+export const myEntityHook: EntityHook = {
+    async beforeSubmit(entity, ctx: SubmitContext, user: UserInfo) {
+        if (!ctx.new.title) {
+            throw new ValidationError("제목은 필수입니다");
+        }
+        return { ...ctx.new, created_by: user.sub };
+    },
+
+    async afterGet(entity, data: any, user: UserInfo) {
+        // 비밀 필드 제거
+        delete data.internal_note;
+        return data;
+    },
+};
+```
+
+### 2) registry.ts 에 등록
+
+```ts
+// app/hooks/index.ts
+import type { EntityHook } from "@gateway/api";
+import { myEntityHook } from "./my-entity.ts";
+
+export const hookRegistry: Record<string, EntityHook> = {
+    my_entity: myEntityHook, // ← 엔티티 이름(JSON 파일명)과 정확히 일치해야 함
+};
+```
+
+## 에러 반환 방법
+
+훅에서 throw 하면 해당 HTTP 에러로 응답된다.
+
+```ts
+import {
+    ForbiddenError,
+    ValidationError,
+    NotFoundError,
+    BadRequestError,
+} from "@gateway/api";
+
+throw new ValidationError("제목은 필수입니다"); // 422
+throw new ForbiddenError("권한이 없습니다"); // 403
+throw new BadRequestError("잘못된 요청입니다"); // 400
+throw new NotFoundError("데이터를 찾을 수 없습니다"); // 404
+```
+
+## `SubmitContext` — 등록/수정 훅 컨텍스트
+
+```ts
+interface SubmitContext {
+    old: Record<string, unknown> | null; // 수정 전 데이터 (신규 INSERT 시 null)
+    new: Record<string, unknown>; // 클라이언트 요청 데이터
+}
+```
+
+신규 INSERT vs 수정 구분:
+
+```ts
+async beforeSubmit(entity, ctx, user) {
+    if (!ctx.old) {
+        // 신규 INSERT
+    } else {
+        // 수정 — ctx.old 에 기존 데이터 있음
+        if (ctx.old.status !== ctx.new.status) {
+            // 상태 변경 감지
+        }
+    }
+    return ctx.new;
+}
+```
+
+## `DeleteContext` — 삭제 훅 컨텍스트
+
+```ts
+interface DeleteContext {
+    seq: number; // 삭제 대상 seq
+    data: Record<string, unknown> | null; // 삭제 대상 전체 데이터 (조회 실패 시 null)
+}
+```
+
+## 현재 등록된 훅
+
+| 엔티티    | 파일         | 주요 동작                                           |
+| --------- | ------------ | --------------------------------------------------- |
+| `account` | `account.ts` | devices 자동 조회                                   |
+| `order`   | `order.ts`   | 전화번호 마스킹, 주문번호 자동 생성, 상태 변경 차단 |
+| `post`    | `post.ts`    | 작성자 자동 설정, 비공개 글 접근 제어               |
+
+## 관련 문서
+
+- [훅 시스템 개요](../../../docs/hooks.md)

package/src/app/hooks/account.ts

@@ -0,0 +1,26 @@
+/**
+ * Account 엔티티 훅 — 계정 조회 시 연관 데이터 자동 포함
+ *
+ * - afterGet: devices(account_device 엔티티 list) 추가
+ */
+
+import type { EntityHook, UserInfo } from "@gateway/api";
+import { entityServer } from "@gateway/api";
+
+export const accountHook: EntityHook = {
+    /**
+     * 계정 단건 조회 후 — 연관 데이터 추가
+     *
+     * - devices: account_device 엔티티에서 account_seq로 목록 조회
+     */
+    async afterGet(entity: string, data: any, _user: UserInfo) {
+        if (data.seq) {
+            const devicesResp = await entityServer.list<any>("account_device", {
+                account_seq: data.seq,
+            } as any);
+            data.devices = devicesResp?.data?.items ?? [];
+        }
+
+        return data;
+    },
+};

package/src/app/hooks/index.ts

@@ -0,0 +1,19 @@
+/**
+ * 엔티티 훅 레지스트리 — 엔티티별 before/after 훅을 등록합니다.
+ *
+ * 키: 엔티티 이름 (entities/ 폴더의 JSON 파일명과 동일)
+ * 값: EntityHook 구현 객체
+ *
+ * Entity Server CRUD 요청 전/후에 해당 엔티티의 훅이 자동 실행됩니다.
+ */
+
+import type { EntityHook } from "@gateway/api";
+import { accountHook } from "./account.ts";
+import { orderHook } from "./order.ts";
+import { postHook } from "./post.ts";
+
+export const hookRegistry: Record<string, EntityHook> = {
+    account: accountHook,
+    order: orderHook,
+    post: postHook,
+};

package/src/app/hooks/order.ts

@@ -0,0 +1,230 @@
+/**
+ * Order 엔티티 훅 예제 — 주문 엔티티의 비즈니스 로직
+ *
+ * Entity Server의 /api/v1/order 요청을 가로채는 훅입니다.
+ * registry.ts 에서 { order: orderHook } 으로 등록하면
+ * 클라이언트 → Gateway → Entity Server 흐름에서 before/after 훅이 자동 실행됩니다.
+ *
+ * - beforeGet:    조회 권한 제어
+ * - afterGet:     민감 정보 마스킹 (find 조회에도 자동 적용)
+ * - beforeSubmit: 데이터 유효성 검증 + 자동 필드 설정
+ * - afterSubmit:  주문 생성 후 알림/로깅
+ * - beforeDelete: 완료된 주문 삭제 차단
+ * - afterDelete:  연관 데이터 정리
+ * - beforeList:   기본 정렬/필터 추가
+ * - afterList:    응답 데이터 가공
+ */
+
+import type {
+    EntityHook,
+    UserInfo,
+    SubmitContext,
+    DeleteContext,
+} from "@gateway/api";
+import { logger, ForbiddenError, ValidationError } from "@gateway/api";
+
+export const orderHook: EntityHook = {
+    // ─────────────────────────────────────────────
+    // Get 훅
+    // ─────────────────────────────────────────────
+
+    /**
+     * 주문 단건 조회 전 — 접근 제어
+     *
+     * - 일반 사용자는 본인 주문만 조회 가능 (아래 예시는 주석)
+     * - false 반환 또는 throw 시 조회 차단
+     */
+    async beforeGet(entity: string, seq: number, user: UserInfo) {
+        // 예: 관리자가 아니면 요청만 허용 (소유권 검사는 afterGet 또는 beforeList에서)
+        logger.debug({ entity, seq, userId: user.sub }, "주문 조회 요청");
+        return true;
+    },
+
+    /**
+     * 주문 단건 조회 후 — 민감 정보 마스킹
+     *
+     * - 반환값이 클라이언트 응답이 됨
+     * - 관리자가 아닌 경우 전화번호 마스킹
+     */
+    async afterGet(entity: string, data: any, user: UserInfo) {
+        if (user.role !== "admin" && data.phone) {
+            data.phone = data.phone.replace(/(\d{3})\d{4}(\d{4})/, "$1****$2");
+        }
+        return data;
+    },
+
+    // ─────────────────────────────────────────────
+    // Submit 훅
+    // ─────────────────────────────────────────────
+
+    /**
+     * 주문 등록/수정 전 데이터 변환 및 검증
+     *
+     * - ctx.old: 수정 전 데이터 (신규 INSERT 시 null)
+     * - ctx.new: 클라이언트가 보낸 요청 데이터
+     * - 반환값이 실제 submit 되는 데이터가 됨
+     */
+    async beforeSubmit(entity: string, ctx: SubmitContext, user: UserInfo) {
+        const data = { ...ctx.new };
+
+        if (!ctx.old) {
+            // ── 신규 주문 ─────────────────────────────
+            if (!data.items || (data.items as any[]).length === 0) {
+                throw new ValidationError("주문 항목이 비어있습니다");
+            }
+
+            data.order_no = `ORD-${Date.now()}`;
+            data.status = "pending";
+            data.ordered_by = user.sub;
+            data.ordered_time = new Date().toISOString();
+
+            logger.info(
+                { orderNo: data.order_no, userId: user.sub },
+                "새 주문 생성 준비",
+            );
+        } else {
+            // ── 수정 — 변경 불가 필드 보호 ───────────
+            delete data.order_no;
+            delete data.ordered_by;
+            delete data.ordered_time;
+
+            // old/new 비교 예시: 상태 변경 감지
+            if (ctx.old.status !== data.status) {
+                logger.info(
+                    { seq: data.seq, from: ctx.old.status, to: data.status },
+                    "주문 상태 변경 감지",
+                );
+            }
+        }
+
+        return data;
+    },
+
+    /**
+     * 주문 등록/수정 후 사이드이펙트
+     *
+     * - ctx.old: 수정 전 데이터 (신규 시 null)
+     * - ctx.new: 엔티티서버에 저장된 결과 데이터
+     * - 실패해도 주문 데이터는 이미 저장됨 (로그만 남김)
+     */
+    async afterSubmit(entity: string, ctx: SubmitContext, user: UserInfo) {
+        logger.info(
+            { seq: ctx.new.seq, orderNo: ctx.new.order_no },
+            "주문 처리 완료",
+        );
+
+        // 신규 주문 알림
+        // if (!ctx.old && ctx.new.status === "pending") {
+        //     await sendNotification(user.email, `주문 ${ctx.new.order_no} 접수`);
+        // }
+
+        // 상태 변경 시 알림
+        // if (ctx.old && ctx.old.status !== ctx.new.status) {
+        //     await sendStatusChangeNotification(ctx.new, ctx.old.status, ctx.new.status);
+        // }
+
+        return ctx.new;
+    },
+
+    // ─────────────────────────────────────────────
+    // Delete 훅
+    // ─────────────────────────────────────────────
+
+    /**
+     * 주문 삭제 전 검증
+     *
+     * - ctx.data로 삭제 대상 데이터 확인 가능
+     * - 완료/배송중 주문은 삭제 차단
+     * - false 반환 시 삭제가 실행되지 않음
+     */
+    async beforeDelete(entity: string, ctx: DeleteContext, user: UserInfo) {
+        // 완료/배송중 주문 삭제 차단
+        if (ctx.data) {
+            const status = ctx.data.status;
+            if (status === "completed" || status === "shipping") {
+                throw new ForbiddenError(
+                    "완료/배송중인 주문은 삭제할 수 없습니다",
+                );
+            }
+        }
+
+        logger.info(
+            { seq: ctx.seq, orderNo: ctx.data?.order_no, userId: user.sub },
+            "주문 삭제 요청",
+        );
+        return true;
+    },
+
+    /**
+     * 주문 삭제 후 정리
+     *
+     * - ctx.data로 삭제된 주문 정보 확인 (로그/알림 등)
+     * - 연관 데이터 정리 (결제 취소, 재고 복구 등)
+     * - 실패해도 삭제는 이미 완료됨
+     */
+    async afterDelete(entity: string, ctx: DeleteContext, user: UserInfo) {
+        logger.info(
+            { seq: ctx.seq, orderNo: ctx.data?.order_no, userId: user.sub },
+            "주문 삭제 완료 — 정리 작업 수행",
+        );
+
+        // 예: 결제 취소 API 호출
+        // await cancelPayment(seq);
+    },
+
+    // ─────────────────────────────────────────────
+    // List 훅
+    // ─────────────────────────────────────────────
+
+    /**
+     * 주문 목록 조회 전 파라미터 변환
+     *
+     * - 기본 정렬 추가
+     * - 관리자가 아니면 본인 주문만 조회하도록 필터 추가
+     */
+    async beforeList(entity: string, params: any, user: UserInfo) {
+        // 기본 정렬: 최신 주문 순
+        if (!params.orderBy) {
+            params.orderBy = "ordered_time";
+            params.orderDir = "desc";
+        }
+
+        // 일반 사용자는 본인 주문만 조회
+        if (user.role !== "admin") {
+            params.conditions = params.conditions || [];
+            params.conditions.push({
+                field: "ordered_by",
+                operator: "eq",
+                value: user.sub,
+            });
+        }
+
+        return params;
+    },
+
+    /**
+     * 주문 목록 조회 후 응답 가공
+     *
+     * - 민감 정보 마스킹
+     * - 추가 필드 계산
+     */
+    async afterList(entity: string, result: any, user: UserInfo) {
+        // 목록의 각 주문에 대해 가공
+        if (result.list) {
+            result.list = result.list.map((order: any) => ({
+                ...order,
+                // 민감 정보 마스킹 (관리자가 아닌 경우)
+                ...(user.role !== "admin" && order.phone
+                    ? {
+                          phone: order.phone.replace(
+                              /(\d{3})\d{4}(\d{4})/,
+                              "$1****$2",
+                          ),
+                      }
+                    : {}),
+            }));
+        }
+
+        return result;
+    },
+};