create-entity-app-server 0.0.3

package/docs/hooks.md

@@ -0,0 +1,600 @@
+# 엔티티 훅
+
+엔티티 CRUD 요청 전/후에 커스텀 비즈니스 로직을 실행하는 메커니즘입니다.
+
+---
+
+## 개요
+
+Gateway는 Entity Server로 프록시하기 **전에** 훅이 등록된 엔티티의 get/find/submit/delete/list 요청을 인터셉트합니다.
+`find`는 `get`과 동일한 단건 조회이므로 `afterGet` 훅이 자동 적용됩니다.
+
+```
+클라이언트 → Gateway (인터셉터)
+               │
+               ├─ beforeHook 실행
+               ├─ Entity Server CRUD
+               ├─ afterHook 실행
+               │
+               └→ 응답
+```
+
+- **before 훅** — 예외 throw 시 요청 차단 (Entity Server에 미반영)
+- **after 훅** — 예외 시 로그만 남기고 통과 (이미 반영됨, 롤백 불가)
+
+---
+
+## 빠른 시작
+
+### 1. 훅 파일 생성
+
+```ts
+// app/hooks/entities/order.ts
+import type {
+    EntityHook,
+    SubmitContext,
+    DeleteContext,
+    UserInfo,
+} from "@gateway/api";
+import { logger, ValidationError, ForbiddenError } from "@gateway/api";
+
+export const orderHook: EntityHook = {
+    async beforeSubmit(entity, ctx: SubmitContext, user: UserInfo) {
+        if (!ctx.old && !ctx.new.items?.length) {
+            throw new ValidationError("주문 항목이 비어있습니다");
+        }
+        return { ...ctx.new, ordered_by: user.sub };
+    },
+
+    async afterSubmit(entity, ctx: SubmitContext, user: UserInfo) {
+        if (ctx.old && ctx.old.status !== ctx.new.status) {
+            logger.info(
+                { from: ctx.old.status, to: ctx.new.status },
+                "상태 변경",
+            );
+        }
+        return ctx.new;
+    },
+
+    async beforeDelete(entity, ctx: DeleteContext, user: UserInfo) {
+        if (ctx.data?.status === "completed") {
+            throw new ForbiddenError("완료된 주문은 삭제 불가");
+        }
+        return true;
+    },
+
+    async afterDelete(entity, ctx: DeleteContext, user: UserInfo) {
+        logger.info(
+            { seq: ctx.seq, orderNo: ctx.data?.order_no },
+            "주문 삭제됨",
+        );
+    },
+};
+```
+
+### 2. 레지스트리에 등록
+
+```ts
+// app/hooks/registry.ts
+import type { EntityHook } from "@gateway/api";
+import { orderHook } from "./entities/order.ts";
+
+export const hookRegistry: Record<string, EntityHook> = {
+    order: orderHook, // 키 = entities/ 폴더의 엔티티 이름
+};
+```
+
+서버 시작 시 `app/hooks/registry.ts`를 자동 로드합니다. 파일이 없으면 훅 없이 동작합니다.
+
+---
+
+## EntityHook 인터페이스
+
+```ts
+interface EntityHook {
+    // Get — 단건 조회 (seq)
+    // find 조회에도 afterGet이 자동 적용됩니다.
+    beforeGet?(entity: string, seq: number, user: UserInfo): Promise<boolean>;
+    afterGet?(entity: string, data: any, user: UserInfo): Promise<any>;
+
+    // Submit — 생성/수정
+    beforeSubmit?(
+        entity: string,
+        ctx: SubmitContext,
+        user: UserInfo,
+    ): Promise<any>;
+    afterSubmit?(
+        entity: string,
+        ctx: SubmitContext,
+        user: UserInfo,
+    ): Promise<any>;
+
+    // Delete — 삭제
+    beforeDelete?(
+        entity: string,
+        ctx: DeleteContext,
+        user: UserInfo,
+    ): Promise<boolean>;
+    afterDelete?(
+        entity: string,
+        ctx: DeleteContext,
+        user: UserInfo,
+    ): Promise<void>;
+
+    // List — 목록 조회
+    beforeList?(entity: string, params: any, user: UserInfo): Promise<any>;
+    afterList?(entity: string, result: any, user: UserInfo): Promise<any>;
+}
+```
+
+모든 훅은 **선택적**입니다. 필요한 훅만 구현하면 됩니다.
+
+---
+
+## 컨텍스트 타입
+
+### SubmitContext
+
+Submit 훅(before/after)에 전달되는 old/new 컨텍스트입니다.
+
+```ts
+interface SubmitContext<T = any> {
+    old: T | null; // 수정 전 데이터 (INSERT 시 null)
+    new: T; // 요청 데이터(before) 또는 저장된 결과(after)
+}
+```
+
+| 시점                      | `ctx.old`           | `ctx.new`                |
+| ------------------------- | ------------------- | ------------------------ |
+| **beforeSubmit** (INSERT) | `null`              | 클라이언트 요청 데이터   |
+| **beforeSubmit** (UPDATE) | 수정 전 기존 데이터 | 클라이언트 요청 데이터   |
+| **afterSubmit** (INSERT)  | `null`              | 엔티티서버에 저장된 결과 |
+| **afterSubmit** (UPDATE)  | 수정 전 기존 데이터 | 엔티티서버에 저장된 결과 |
+
+- `old`는 인터셉터가 `entityServer.get()`으로 자동 조회합니다 (훅에서 별도 조회 불필요)
+- `beforeSubmit`의 **반환값**이 실제 Entity Server로 submit되는 데이터가 됩니다
+
+### DeleteContext
+
+Delete 훅(before/after)에 전달되는 컨텍스트입니다.
+
+```ts
+interface DeleteContext<T = any> {
+    seq: number; // 삭제 대상 시퀀스
+    data: T | null; // 삭제 대상 데이터 (조회 실패 시 null)
+}
+```
+
+| 시점             | `ctx.seq`     | `ctx.data`       |
+| ---------------- | ------------- | ---------------- |
+| **beforeDelete** | 삭제할 시퀀스 | 삭제 대상 데이터 |
+| **afterDelete**  | 삭제된 시퀀스 | 삭제된 데이터    |
+
+- `data`도 인터셉터가 자동 조회합니다
+- 조회 실패 시 `data = null`로 전달되므로 옵셔널 체이닝(`ctx.data?.field`) 사용을 권장합니다
+
+### UserInfo
+
+JWT에서 디코딩된 사용자 정보입니다.
+
+```ts
+interface UserInfo {
+    sub: number; // 사용자 시퀀스
+    email: string; // 이메일
+    role: string; // 역할 (admin, user 등)
+    [key: string]: unknown; // 추가 클레임
+}
+```
+
+---
+
+## 훅별 상세
+
+### beforeGet
+
+단건 조회 **전** 접근 제어를 수행합니다. `false` 반환 또는 예외 throw 시 조회가 차단됩니다.
+
+```ts
+async beforeGet(entity: string, seq: number, user: UserInfo) {
+    // 예: 비공개 데이터 접근 차단 (실제 소유권 검사는 afterGet에서 데이터 기반으로)
+    logger.debug({ entity, seq, userId: user.sub }, "단건 조회 요청");
+    return true;  // 조회 허용
+}
+```
+
+**에러 처리**: 예외 throw 시 요청이 차단되고 클라이언트에 에러가 반환됩니다.
+
+### afterGet
+
+단건 조회 **후** 응답 데이터를 가공합니다. 반환값이 클라이언트 응답이 됩니다.
+
+```ts
+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",
+        );
+    }
+
+    // 계산 필드 추가
+    if (data.content) {
+        data.preview =
+            data.content.slice(0, 100) +
+            (data.content.length > 100 ? "…" : "");
+    }
+
+    return data;
+}
+```
+
+**에러 처리**: 예외가 발생하면 로그만 남기고 원본 데이터를 반환합니다.
+
+### beforeSubmit
+
+데이터 **변환** 및 **검증**을 수행합니다. 반환값이 실제 submit 데이터가 됩니다.
+
+```ts
+async beforeSubmit(entity: string, ctx: SubmitContext, user: UserInfo) {
+    const data = { ...ctx.new };
+
+    if (!ctx.old) {
+        // ── 신규 (INSERT) ──
+        data.created_by = user.sub;
+        data.created_time = new Date().toISOString();
+    } else {
+        // ── 수정 (UPDATE) ── ctx.old로 기존 데이터 확인
+        delete data.created_by;  // 변경 불가 필드 보호
+
+        if (ctx.old.status === "locked") {
+            throw new ForbiddenError("잠긴 데이터는 수정할 수 없습니다");
+        }
+    }
+
+    return data;  // ← 이 값이 Entity Server로 전송됨
+}
+```
+
+**에러 처리**: 예외 throw 시 요청이 차단되고 클라이언트에 에러가 반환됩니다.
+
+### afterSubmit
+
+저장 완료 후 **사이드이펙트**를 실행합니다. 반환값은 응답에 포함되지 않습니다.
+
+```ts
+async afterSubmit(entity: string, ctx: SubmitContext, user: UserInfo) {
+    // 신규 생성 시 알림
+    if (!ctx.old) {
+        // await sendEmail(user.email, `${ctx.new.seq}번 항목이 생성되었습니다`);
+    }
+
+    // 상태 변경 감지
+    if (ctx.old && ctx.old.status !== ctx.new.status) {
+        logger.info(
+            { seq: ctx.new.seq, from: ctx.old.status, to: ctx.new.status },
+            "상태 변경됨",
+        );
+    }
+
+    return ctx.new;
+}
+```
+
+**에러 처리**: 예외가 발생해도 데이터는 이미 저장됨. 로그만 남기고 무시됩니다.
+
+### beforeDelete
+
+삭제 **차단 여부**를 결정합니다. `false` 반환 또는 예외 throw 시 삭제가 차단됩니다.
+
+```ts
+async beforeDelete(entity: string, ctx: DeleteContext, user: UserInfo) {
+    // 완료 상태는 삭제 차단
+    if (ctx.data?.status === "completed") {
+        throw new ForbiddenError("완료된 항목은 삭제할 수 없습니다");
+    }
+
+    // 본인 소유만 삭제 허용
+    if (ctx.data && ctx.data.owner_id !== user.sub && user.role !== "admin") {
+        throw new ForbiddenError("본인 데이터만 삭제할 수 있습니다");
+    }
+
+    return true;  // 삭제 허용
+}
+```
+
+### afterDelete
+
+삭제 후 **정리 작업**을 수행합니다.
+
+```ts
+async afterDelete(entity: string, ctx: DeleteContext, user: UserInfo) {
+    logger.info(
+        { seq: ctx.seq, name: ctx.data?.name, deletedBy: user.sub },
+        "항목 삭제 완료",
+    );
+
+    // 연관 데이터 정리
+    // await entityServer.delete("order_item", relatedSeq);
+}
+```
+
+### beforeList
+
+목록 조회 **파라미터를 변환**합니다. 기본 정렬, 권한 기반 필터 추가 등에 사용합니다.
+
+```ts
+async beforeList(entity: string, params: any, user: UserInfo) {
+    // 기본 정렬
+    if (!params.orderBy) {
+        params.orderBy = "created_time";
+        params.orderDir = "desc";
+    }
+
+    // 일반 사용자는 본인 데이터만 조회
+    if (user.role !== "admin") {
+        params.conditions = params.conditions || [];
+        params.conditions.push({
+            field: "owner_id",
+            operator: "eq",
+            value: user.sub,
+        });
+    }
+
+    return params;
+}
+```
+
+### afterList
+
+목록 조회 **응답을 가공**합니다. 마스킹, 계산 필드 추가 등에 사용합니다.
+
+```ts
+async afterList(entity: string, result: any, user: UserInfo) {
+    if (result.list) {
+        result.list = result.list.map((item: any) => ({
+            ...item,
+            // 본문 미리보기 (100자)
+            preview: item.content?.slice(0, 100) + (item.content?.length > 100 ? "…" : ""),
+            // 민감 정보 마스킹
+            phone: user.role !== "admin"
+                ? item.phone?.replace(/(\d{3})\d{4}(\d{4})/, "$1****$2")
+                : item.phone,
+        }));
+    }
+    return result;
+}
+```
+
+---
+
+## 실행 흐름
+
+### Get 흐름
+
+```
+GET /api/v1/entity/order/42
+│
+├─ hasHook("order")? → YES  (NO면 프록시로 패스스루)
+│
+├─ ① beforeGet("order", 42, user) → true/false
+├─ ② entityServer.get("order", 42) → 조회 결과
+├─ ③ afterGet("order", data, user) → 가공된 결과
+│
+└─ 응답: { ok: true, data: 가공결과 }
+```
+
+### Find 흐름
+
+`find`는 `get`과 동일한 단건 조회이므로 별도의 훅 없이 `afterGet`을 재사용합니다.
+
+```
+POST /api/v1/entity/order/find
+│
+├─ hasHook("order")? → YES  (NO면 프록시로 패스스루)
+│
+├─ ① entityServer.find("order", conditions) → 조회 결과
+├─ ② afterGet("order", data, user) → 가공된 결과 (마스킹 등)
+│
+└─ 응답: { ok: true, data: 가공결과 }
+```
+
+### Submit 흐름
+
+```
+POST /api/v1/entity/order/submit
+│
+├─ hasHook("order")? → YES  (NO면 프록시로 패스스루)
+│
+├─ ① data.seq 있으면 entityServer.get() → old 데이터 조회
+├─ ② beforeSubmit({ old, new: reqData }) → 변환된 데이터 반환
+├─ ③ entityServer.submit(변환데이터) → { ok, seq }
+├─ ④ entityServer.get(seq) → 저장된 결과 조회
+├─ ⑤ afterSubmit({ old, new: 저장결과 }) → 사이드이펙트
+│
+└─ 응답: { ok: true, seq }
+```
+
+### Delete 흐름
+
+```
+POST /api/v1/entity/order/delete/42
+│
+├─ hasHook("order")? → YES
+│
+├─ ① entityServer.get(42) → 삭제 대상 데이터 조회
+├─ ② beforeDelete({ seq: 42, data }) → true/false
+├─ ③ entityServer.delete(42) → { ok, deleted }
+├─ ④ afterDelete({ seq: 42, data }) → 사이드이펙트
+│
+└─ 응답: { ok: true, deleted: 1 }
+```
+
+### List 흐름
+
+```
+POST /api/v1/entity/order/list?page=1&limit=20
+│
+├─ hasHook("order")? → YES
+│
+├─ ① beforeList(params) → 변환된 파라미터 반환
+├─ ② entityServer.list(변환파라미터) → 목록 결과
+├─ ③ afterList(result) → 가공된 결과 반환
+│
+└─ 응답: { ok: true, data: 가공결과 }
+```
+
+### 훅 미등록 엔티티
+
+레지스트리에 등록되지 않은 엔티티는 인터셉터를 거치지 않고 **Entity Server로 직접 프록시**됩니다.
+
+---
+
+## 훅 우회 (skipHooks)
+
+쿼리 파라미터로 훅을 우회할 수 있습니다:
+
+```
+POST /api/v1/entity/order/submit?skipHooks=true
+```
+
+주로 내부 시스템 호출이나 마이그레이션 시 사용합니다.
+
+---
+
+## 파일 구조
+
+```
+app/
+  hooks/
+    registry.ts                ← 훅 등록 (엔티티명 → EntityHook 매핑)
+    entities/
+      order.ts                 ← 주문 훅 구현
+      post.ts                  ← 게시글 훅 구현
+      {your-entity}.ts         ← 새 훅 추가 시 여기에 생성
+```
+
+| 파일            | 역할                                                           |
+| --------------- | -------------------------------------------------------------- |
+| `registry.ts`   | 엔티티명을 키로 EntityHook 객체를 매핑. 서버 시작 시 자동 로드 |
+| `entities/*.ts` | 엔티티별 훅 구현. EntityHook 인터페이스의 메서드를 선택 구현   |
+
+---
+
+## 새 훅 추가하기
+
+### 1. 훅 파일 작성
+
+```ts
+// app/hooks/entities/product.ts
+import type { EntityHook, SubmitContext, UserInfo } from "@gateway/api";
+import { logger } from "@gateway/api";
+
+export const productHook: EntityHook = {
+    async beforeSubmit(entity, ctx: SubmitContext, user: UserInfo) {
+        const data = { ...ctx.new };
+        // 가격 음수 방지
+        if (data.price != null && Number(data.price) < 0) {
+            data.price = 0;
+        }
+        return data;
+    },
+};
+```
+
+### 2. 레지스트리에 추가
+
+```ts
+// app/hooks/registry.ts
+import type { EntityHook } from "@gateway/api";
+import { orderHook } from "./entities/order.ts";
+import { postHook } from "./entities/post.ts";
+import { productHook } from "./entities/product.ts"; // 추가
+
+export const hookRegistry: Record<string, EntityHook> = {
+    order: orderHook,
+    post: postHook,
+    product: productHook, // 추가
+};
+```
+
+### 3. 서버 재시작
+
+훅은 서버 시작 시 로드되므로 재시작이 필요합니다.
+
+---
+
+## 에러 처리 정책
+
+| 훅 종류        | 예외 발생 시     | 설명                                         |
+| -------------- | ---------------- | -------------------------------------------- |
+| `beforeGet`    | **조회 차단**    | 클라이언트에 에러 반환. Entity Server 미호출 |
+| `afterGet`     | **로그 후 무시** | 원본 데이터 그대로 반환                      |
+| `beforeSubmit` | **요청 차단**    | 클라이언트에 에러 반환. Entity Server 미반영 |
+| `afterSubmit`  | **로그 후 무시** | 데이터는 이미 저장됨                         |
+| `beforeDelete` | **삭제 차단**    | 클라이언트에 에러 반환. 삭제 미실행          |
+| `afterDelete`  | **로그 후 무시** | 삭제는 이미 완료됨                           |
+| `beforeList`   | **요청 차단**    | 클라이언트에 에러 반환                       |
+| `afterList`    | **로그 후 무시** | 원본 결과 그대로 반환                        |
+
+before 훅에서는 `ValidationError`, `ForbiddenError` 등의 에러 클래스를 throw하여 적절한 HTTP 상태 코드와 메시지를 반환할 수 있습니다:
+
+```ts
+import { ValidationError, ForbiddenError, BadRequestError } from "@gateway/api";
+
+// 422 Unprocessable Entity
+throw new ValidationError("필수 항목이 누락되었습니다");
+
+// 403 Forbidden
+throw new ForbiddenError("권한이 없습니다");
+
+// 400 Bad Request
+throw new BadRequestError("잘못된 요청입니다");
+```
+
+---
+
+## @gateway/api 임포트
+
+훅에서 사용할 수 있는 주요 임포트:
+
+```ts
+// 타입
+import type {
+    EntityHook,
+    SubmitContext,
+    DeleteContext,
+    UserInfo,
+} from "@gateway/api";
+
+// 유틸리티
+import { logger, entityServer } from "@gateway/api";
+
+// 에러 클래스
+import {
+    ValidationError, // 422
+    ForbiddenError, // 403
+    BadRequestError, // 400
+    NotFoundError, // 404
+    ConflictError, // 409
+    UnauthorizedError, // 401
+} from "@gateway/api";
+```
+
+`entityServer`를 사용하면 훅 안에서 다른 엔티티를 조회/수정할 수 있습니다:
+
+```ts
+async afterSubmit(entity, ctx: SubmitContext, user: UserInfo) {
+    // 다른 엔티티 조회
+    const res = await entityServer.get("customer", ctx.new.customer_seq);
+    const customer = res.data;
+
+    // 다른 엔티티 수정
+    await entityServer.submit("notification", {
+        target_user: customer.email,
+        message: `주문 ${ctx.new.order_no} 접수`,
+    });
+
+    return ctx.new;
+}
+```

package/docs/internals.md

@@ -0,0 +1,60 @@
+# 앱서버 내부 구조
+
+---
+
+## 부트스트랩 순서
+
+```
+node dist/system.js
+    │
+    ▼
+system/app.ts
+    ├─  1. Fastify 인스턴스 생성
+    ├─  2. 보안 기본 — CORS, Helmet, Rate Limit
+    ├─  3. 시스템 미들웨어 (middleware/)
+    │     requestId → accessLog → errorHandler → cache
+    │     → auth (JWT verify) → csrf → packetEncrypt → database (Kysely)
+    ├─  4. loadHooks() — app/hooks/registry.ts 로드 → 훅 매핑 등록
+    ├─  5. loadExtensionPlugins() — app/plugins/** 자동 로드
+    │     └─ alimtalk, llm, ocr, pg, identity, taxinvoice 등
+    ├─  6. registerEntityInterceptor() — 엔티티 CRUD 인터셉터 등록
+    ├─  7. registerRoutes() — app/routes/** 자동 로드
+    │     └─ 각 route.ts Fastify 플러그인으로 등록
+    ├─  8. registerProxyRoutes() — Entity Server 패스스루 프록시
+    │     └─ 위에서 처리되지 않은 /api/v1/* 경로만 전달
+    ├─  9. loadSchedules() — app/schedules/** 자동 로드
+    ├─ 10. /health 헬스체크 등록
+    └─ 11. 서버 시작 (listen) → 스타트업 배너 출력
+```
+
+---
+
+## 요청 처리 흐름 (비즈니스 라우트)
+
+```
+HTTP 요청
+    │
+    ▼
+시스템 미들웨어 체인 (middleware/)
+    ├─ Helmet (보안 헤더)
+    ├─ CORS (origin 검증)
+    ├─ Rate Limit
+    ├─ Request ID 부여
+    ├─ Access Log 기록
+    ├─ JWT decode → req.user
+    ├─ CSRF (state-changing 요청)
+    └─ 패킷 복호화 (설정된 경우)
+    │
+    ▼
+라우트 핸들러
+    ├─ preHandler: authRequired (JWT verify, 필요한 라우트만)
+    ├─ 비즈니스 로직 실행
+    │   ├─ entityServer.* 호출 (SDK)
+    │   ├─ dbConn() (Kysely 직접 쿼리)
+    │   └─ sendEmail / 외부 API 호출
+    └─ 응답 반환
+    │
+    ▼
+HTTP 응답
+    └─ 패킷 암호화 (설정된 경우)
+```