create-entity-app-server 0.0.3

package/docs/README.md

@@ -0,0 +1,274 @@
+# 커스터마이징 가이드
+
+Entity Server Gateway는 `app/` 폴더의 TypeScript 소스를 직접 수정해 동작을 확장할 수 있습니다.
+
+---
+
+## 폴더 구조
+
+```
+app/
+  plugins/          — 비즈니스 플러그인 (결제·LLM·알림 등)
+    alimtalk/       — 카카오 알림톡
+    friendtalk/     — 카카오 친구톡
+    holidays/       — 공휴일 자동 동기화
+    identity/       — 본인인증 (NICE, KMC, Danal)
+    llm/            — LLM 연동 (OpenAI, Gemini, Claude 등)
+    ocr/            — OCR 문서 인식
+    pg/             — 결제 (토스, KCP, 이니시스, 페이레터 등)
+    taxinvoice/     — 전자세금계산서
+  routes/           — 커스텀 API 엔드포인트
+    health/         — 헬스체크 (기본 제공)
+  schedules/        — 백그라운드 크론 스케줄
+    dormancy/       — 장기 미접속 계정 휴면 전환
+    data-retention/ — 개인정보 보유 기간 만료 삭제
+  hooks/
+    registry.ts     — 엔티티 이벤트 훅 등록
+```
+
+---
+
+## 플러그인 수정
+
+각 플러그인은 `app/plugins/{name}/index.ts`의 Fastify 플러그인으로 구성됩니다.  
+서버 시작 시 `plugins/` 하위 폴더를 알파벳 순으로 자동 탐색해 등록합니다.
+
+**기존 모듈 핸들러 수정 예시:**
+
+```ts
+// app/plugins/llm/handlers.ts
+import { ok, fail } from "@gateway/api";
+
+export async function chatHandler(req, reply) {
+    // 원하는 로직으로 수정
+}
+```
+
+**새 플러그인 추가:**
+
+```
+app/plugins/my-module/
+  index.ts     — Fastify 플러그인 (default export 필수)
+  handlers.ts
+  routes.ts
+```
+
+```ts
+// app/plugins/my-module/index.ts
+import type { FastifyInstance } from "fastify";
+
+export default async function myModulePlugin(app: FastifyInstance) {
+    app.get("/my-module/hello", async (req, reply) => {
+        return { message: "hello" };
+    });
+}
+```
+
+서버를 재시작하면 자동으로 로드됩니다.
+
+---
+
+## 커스텀 라우트 추가
+
+`app/routes/{name}/index.ts`에 Fastify 플러그인을 작성합니다.
+
+```ts
+// app/routes/orders/index.ts
+import type { FastifyInstance } from "fastify";
+import { ok } from "@gateway/api";
+
+export default async function ordersRoutes(app: FastifyInstance) {
+    app.get("/orders", async (req, reply) => {
+        return reply.send(ok([{ id: 1 }]));
+    });
+}
+```
+
+---
+
+## 스케줄 추가
+
+`app/schedules/{name}/index.ts`에 `start()` / `stop()`을 구현합니다.
+
+```ts
+// app/schedules/subscription-reminder/index.ts
+import { createCron, logger, type CronHandle } from "@gateway/api";
+
+let cronHandle: CronHandle | null = null;
+
+export function start(): void {
+    cronHandle = createCron({
+        expression: "0 9 * * 1", // 매주 월요일 09:00
+        onTick: async () => {
+            // 배치 로직
+        },
+    });
+    logger.info("subscription-reminder scheduler started");
+}
+
+export function stop(): void {
+    cronHandle?.stop();
+    cronHandle = null;
+}
+```
+
+서버를 재시작하면 자동으로 로드됩니다.  
+자세한 내용은 [스케줄 추가 가이드](schedules/how-to-create.md)를 참고하세요.
+
+---
+
+## 엔티티 훅
+
+엔티티 CRUD 이벤트(before/after) 전후에 커스텀 로직을 실행합니다.  
+Get 훅은 조회 접근 제어/응답 가공(find 조회에도 afterGet 자동 적용), Submit 훅은 `SubmitContext`를 받아 **수정 전(old) / 요청(new)** 데이터에 모두 접근할 수 있습니다.
+
+```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 afterGet(entity, 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;
+    },
+    async beforeSubmit(entity, ctx: SubmitContext, user: UserInfo) {
+        // ctx.old — 수정 전 데이터 (신규 INSERT 시 null)
+        // ctx.new — 클라이언트 요청 데이터
+        if (!ctx.old && (!ctx.new.items || ctx.new.items.length === 0)) {
+            throw new ValidationError("주문 항목이 비어있습니다");
+        }
+        return { ...ctx.new, ordered_by: user.sub };
+    },
+    async afterSubmit(entity, ctx: SubmitContext, user: UserInfo) {
+        // ctx.old / ctx.new 로 변경 전후 비교 가능
+        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) {
+        // ctx.data — 삭제 대상 데이터 (조회 실패 시 null)
+        if (ctx.data?.status === "completed") {
+            throw new ForbiddenError("완료된 주문은 삭제할 수 없습니다");
+        }
+        logger.info(
+            { seq: ctx.seq, orderNo: ctx.data?.order_no },
+            "주문 삭제 요청",
+        );
+        return true;
+    },
+    async afterDelete(entity, ctx: DeleteContext, user: UserInfo) {
+        logger.info(
+            { seq: ctx.seq, orderNo: ctx.data?.order_no },
+            "주문 삭제 완료",
+        );
+    },
+};
+```
+
+```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,
+};
+```
+
+---
+
+## 공개 API (`@gateway/api`)
+
+app 코드에서 사용할 수 있는 헬퍼:
+
+```ts
+import { ok, fail, logger, entityServer } from "@gateway/api";
+import { cache, dbConn } from "@gateway/api";
+import { NotFoundError, BadRequestError } from "@gateway/api";
+import type {
+    EntityHook,
+    SubmitContext,
+    DeleteContext,
+    UserInfo,
+    CacheStore,
+    CacheDriver,
+} from "@gateway/api";
+```
+
+| export                    | 설명                                            |
+| ------------------------- | ----------------------------------------------- |
+| `ok(data, requestId?)`    | 성공 응답 객체 생성                             |
+| `fail(error, requestId?)` | 실패 응답 객체 생성                             |
+| `logger`                  | pino 로거 인스턴스                              |
+| `entityServer`            | Entity Server REST 클라이언트                   |
+| `cache()`                 | 캐시 스토어 반환 — [캐시 가이드](cache.md) 참고 |
+| `dbConn(group?)`          | Kysely DB 인스턴스 반환                         |
+| `AppError`                | 커스텀 에러 베이스 클래스                       |
+| `BadRequestError`         | 400 에러                                        |
+| `UnauthorizedError`       | 401 에러                                        |
+| `ForbiddenError`          | 403 에러                                        |
+| `NotFoundError`           | 404 에러                                        |
+| `ConflictError`           | 409 에러                                        |
+| `ValidationError`         | 422 에러                                        |
+| `CacheStore`              | 캐시 스토어 인터페이스 (type)                   |
+| `CacheDriver`             | `"memory" \| "redis" \| "memcached"` (type)     |
+| `EntityHook`              | 훅 인터페이스 (type)                            |
+| `SubmitContext`           | submit 훅 old/new 컨텍스트 (type)               |
+| `DeleteContext`           | delete 훅 seq/data 컨텍스트 (type)              |
+| `UserInfo`                | JWT에서 디코딩된 사용자 정보 (type)             |
+
+---
+
+## 설정 파일
+
+`configs/` 폴더의 JSON 파일로 서버 동작을 설정합니다.  
+전체 항목은 [설정 파일 가이드](configs.md)를 참고하세요.
+
+```
+configs/
+  server.json       — 포트, 호스트, 로깅
+  database.json     — DB 연결
+  cors.json         — CORS 설정
+  security.json     — CSRF, 패킷 암호화
+  cache.json        — 캐시 드라이버 (memory / redis / memcached)
+
+app/plugins/              — 각 플러그인 디렉토리에 설정 파일 포함
+  alimtalk/config.json    — 카카오 알림톡
+  friendtalk/config.json  — 카카오 친구톡
+  holidays/config.json    — 공휴일 동기화
+  identity/config.json    — 본인인증
+  llm/config.json         — LLM API 키
+  ocr/config.json         — OCR 설정
+  pg/config.json          — 결제 PG 설정
+  push/config.json        — FCM/APNs 푸시 알림
+  sms/config.json         — SMS 발송 설정
+  taxinvoice/config.json  — 전자세금계산서
+```
+
+---
+
+## 관련 문서
+
+- [아키텍처](architecture.md) — 전체 구조, Gateway 4가지 역할, 인증 흐름
+- [system/ 내부 구조](system.md) — 서버 코어 디렉터리 구조와 각 모듈 역할
+- [내부 구조](internals.md) — 부트스트랩 순서, 요청 처리 흐름
+- [설정 파일](configs.md) — .env, server.json, database.json 등
+- [보안 설정](security.md) — CORS, CSRF, 패킷 암호화, 비밀번호 정책
+- [캐시](cache.md) — memory/Redis/Memcached 캐시 사용법
+- [훅](hooks.md) — 엔티티 CRUD 훅 상세 가이드
+- [플러그인 추가](plugins/how-to-create.md) — 새 플러그인 작성 가이드
+- [라우트 추가](routes/how-to-create.md) — 새 라우트 작성 가이드
+- [스크립트 가이드](scripts-guide.md) — run/build/push/release 스크립트 사용법

package/docs/architecture.md

@@ -0,0 +1,295 @@
+# 아키텍처
+
+Entity Server Gateway의 전체 구조와 각 계층의 역할을 설명합니다.
+
+---
+
+## 전체 구조
+
+```mermaid
+graph TD
+  FE["Frontend<br/>(React)"] -- "HTTPS" --> GW
+
+  subgraph GW["Gateway Server"]
+    direction LR
+    SYS["system.js<br/>서버 코어"]
+    API["system-api.js<br/>공개 API"]
+    APP["app/<br/>plugins · routes · hooks"]
+  end
+
+  GW -- "HTTP 프록시" --> ES["Entity Server"]
+  GW -- "app.db 직접 쿼리" --> DB1[("DB<br/>일반·idx 테이블")]
+  ES --> DB2[("DB<br/>엔티티 CRUD·인증·파일")]
+
+  DB1 -. "같은 DB일 수도 <br>다른 DB일 수도" .- DB2
+```
+
+- **Frontend**는 Gateway Server 하나만 인식합니다.
+- **Gateway**가 요청 종류에 따라 Entity Server로 **프록시**하거나 **자체 비즈니스 로직**으로 처리합니다.
+- **DB**는 두 경로로 접근됩니다:
+    - **Entity Server** — 엔티티 CRUD, 인증, 파일 등 표준 기능
+    - **Gateway Server** — 직접 접속 (`app.db`)으로 일반 테이블, idx 테이블, 집계 쿼리 등
+- 두 서버가 **같은 DB**를 공유할 수도, **각각 별도 DB**를 사용할 수도 있습니다.
+
+---
+
+## Gateway의 4가지 역할
+
+### 1. 플러그인 제공
+
+외부 API(LLM, OCR, 결제, 알림톡 등)를 통합하는 비즈니스 플러그인입니다.
+
+```mermaid
+graph LR
+  EXT["app/plugins/"]
+  EXT --> tfa["2fa/<br/>2단계 인증 (TOTP)"]
+  EXT --> ali["alimtalk/<br/>카카오 알림톡"]
+  EXT --> fri["friendtalk/<br/>카카오 친구톡"]
+  EXT --> hol["holidays/<br/>공휴일 조회"]
+  EXT --> idn["identity/<br/>본인인증"]
+  EXT --> llm["llm/<br/>LLM 연동 (OpenAI · Gemini · Claude)"]
+  EXT --> oau["oauth/<br/>소셜 로그인"]
+  EXT --> ocr["ocr/<br/>문서 OCR 인식"]
+  EXT --> pg["pg/<br/>결제 (토스 · KG이니시스 · 나이스)"]
+  EXT --> psh["push/<br/>푸시 알림"]
+  EXT --> sms["sms/<br/>SMS 발송"]
+  EXT --> tax["taxinvoice/<br/>전자세금계산서"]
+```
+
+`app/plugins/{name}/index.ts`에 Fastify 플러그인을 작성하면 서버 시작 시 자동 로드됩니다.
+각 플러그인은 자신이 사용하는 템플릿을 `plugins/{name}/templates/` 아래에 직접 보유합니다.
+
+### 2. 비즈니스 로직 라우트
+
+Entity Server가 제공하지 않는 커스텀 API를 추가합니다.  
+예: 대시보드 집계, 복합 조회, 외부 연동, 리포트 생성 등.
+
+```mermaid
+graph LR
+  RT["app/routes/"]
+  RT --> h["health/<br/>헬스체크 (기본 제공)"]
+  RT --> ac["account/<br/>회원가입 · 탈퇴 · 비밀번호 변경"]
+  RT --> ev["email-verify/<br/>이메일 인증"]
+  RT --> pr["password-reset/<br/>비밀번호 재설정"]
+```
+
+각 라우트는 자신이 사용하는 이메일 템플릿을 `routes/{name}/templates/` 아래에 직접 보유합니다.
+
+### 3. DB 직접 접속
+
+Entity Server를 거치지 않고 DB에 직접 쿼리합니다.  
+엔티티 테이블 외 일반 테이블이나 `idx_*` 인덱스 테이블 조회 등에 사용합니다.
+
+```ts
+// app.db 를 통한 직접 쿼리
+const rows = await app.db.query(
+    "SELECT * FROM dashboard_stats WHERE ...",
+    params,
+);
+```
+
+`configs/database.json`으로 설정하며, 미설정 시 `app.db = null`로 비활성화됩니다.
+
+### 4. 요청 라우팅
+
+Entity Server는 내부망에서만 접근 가능하고, Frontend는 Gateway만 인식합니다.
+
+```mermaid
+flowchart LR
+  FE[Frontend] -- "/api/v1/*" --> GW[Gateway]
+
+  GW -- "프록시" --> ES["Entity Server<br/>auth · oauth · entity · files<br/>push · smtp · sms · identity · utils"]
+  GW -- "자체 처리" --> AR["app routes<br/>plugins · 사용자 라우트"]
+```
+
+---
+
+## 인증 흐름
+
+### 프록시 요청 — JWT 패스스루
+
+Frontend의 JWT를 그대로 Entity Server로 전달합니다.  
+Entity Server가 사용자 권한을 직접 검증합니다.
+
+```mermaid
+sequenceDiagram
+  participant FE as Frontend
+  participant GW as Gateway
+  participant ES as Entity Server
+  FE->>GW: 요청 (JWT 포함)
+  GW->>ES: 프록시 (JWT 그대로 전달)
+  ES-->>GW: 응답
+  GW-->>FE: 응답
+```
+
+### 비즈니스 라우트 — JWT verify + HMAC
+
+Gateway가 JWT를 직접 검증한 뒤, 비즈니스 로직을 수행합니다.  
+Entity Server 호출이 필요하면 HMAC API Key로 서버간 인증합니다.
+
+```mermaid
+sequenceDiagram
+  participant FE as Frontend
+  participant GW as Gateway
+  participant BL as 비즈니스 로직
+  participant ES as Entity Server
+  FE->>GW: 요청 (JWT 포함)
+  GW->>GW: JWT verify
+  GW->>BL: 처리
+  BL-->>ES: (필요 시) HMAC API Key
+  ES-->>BL: 응답
+  BL-->>FE: 응답
+```
+
+---
+
+## 훅 시스템
+
+엔티티 CRUD 전/후에 커스텀 로직을 실행합니다.  
+Get 훅은 단건 조회 접근 제어/응답 가공(find 조회에도 afterGet 자동 적용),
+Submit 훅은 `SubmitContext { old, new }`, Delete 훅은 `DeleteContext { seq, data }`를 받아 변경 전/후 데이터에 접근할 수 있습니다.
+
+```mermaid
+flowchart TD
+  REQ[요청] --> OLD["old 조회<br/>(UPDATE 시 기존 데이터 fetch)"]
+  OLD --> B["beforeSubmit(ctx)<br/>ctx = { old, new }"]
+  B --> ES[Entity Server submit]
+  ES --> REFETCH["new 재조회<br/>(저장된 결과 fetch)"]
+  REFETCH --> A["afterSubmit(ctx)<br/>ctx = { old, new }"]
+  A --> RES[응답]
+```
+
+| 훅             | 실패 시                                     | ctx                                                  |
+| -------------- | ------------------------------------------- | ---------------------------------------------------- |
+| `beforeGet`    | 조회 차단                                   | `seq: number`                                        |
+| `afterGet`     | 로그만 남기고 원본 반환                     | `data: any` (조회된 데이터)                          |
+| `beforeSubmit` | 요청 차단 (아직 Entity Server에 미반영)     | `SubmitContext { old: 수정 전 \| null, new: 요청 }`  |
+| `afterSubmit`  | 로그만 남기고 통과 (이미 반영됨, 롤백 불가) | `SubmitContext { old: 수정 전 \| null, new: 결과 }`  |
+| `beforeDelete` | 요청 차단                                   | `DeleteContext { seq, data: 삭제 대상 \| null }`     |
+| `afterDelete`  | 로그만 남기고 통과                          | `DeleteContext { seq, data: 삭제된 데이터 \| null }` |
+
+- INSERT 시 `ctx.old = null`, UPDATE 시 `ctx.old`에 기존 데이터가 담깁니다.
+- `beforeSubmit`의 반환값이 실제 submit 데이터가 됩니다.
+
+훅 등록: `app/hooks/registry.ts`에 엔티티명을 키로 등록합니다.
+
+---
+
+## 스케줄러
+
+`app/schedules/{name}/index.ts`에서 `start()` 함수를 export하면 서버 시작 시 자동 로드됩니다.
+
+분산 환경에서 중복 실행을 방지하기 위해 `acquireLock` / `releaseLock`을 사용합니다.
+
+```ts
+import { createCron, acquireLock, releaseLock } from "@gateway/api";
+
+export async function start(): Promise<void> {
+    createCron("0 2 * * *", async () => {
+        const locked = await acquireLock("my-job", 300);
+        if (!locked) return;
+        try {
+            // 작업 수행
+        } finally {
+            await releaseLock("my-job");
+        }
+    });
+}
+```
+
+기본 제공 스케줄:
+
+| 스케줄           | 설명                                             |
+| ---------------- | ------------------------------------------------ |
+| `dormancy`       | 장기 미접속 계정 휴면 전환 및 개인정보 처리 알림 |
+| `data-retention` | 탈퇴 계정 개인정보 파기 처리                     |
+
+---
+
+## 코드 구조
+
+```mermaid
+graph LR
+  DIST["dist/"]
+  DIST --> SYS["system.js — 서버 코어 (난독화 번들, 수정 불가)"]
+  DIST --> SAPI["system-api.js — 공개 API 번들 (@gateway/api)"]
+  DIST --> APP["app/ — 사용자 편집 영역"]
+  DIST --> CFG["configs/ — JSON 설정 파일"]
+  DIST --> ENT["entities/ — 엔티티 스키마"]
+  DIST --> DOC["docs/ — 문서"]
+  DIST --> ENV[".env — 환경변수"]
+  APP --> EXT["plugins/{name}/index.ts — 플러그인 (자동 로드)"]
+  APP --> ETPL["plugins/{name}/templates/ — 플러그인 전용 템플릿"]
+  APP --> RT["routes/{name}/index.ts — 커스텀 라우트 (자동 등록)"]
+  APP --> RTPL["routes/{name}/templates/ — 라우트 전용 이메일 템플릿"]
+  APP --> HK["hooks/registry.ts — 엔티티 훅 등록"]
+  APP --> SC["schedules/{name}/index.ts — 스케줄러 (자동 로드)"]
+```
+
+### system.js vs app/
+
+|           | system.js                                    | app/            |
+| --------- | -------------------------------------------- | --------------- |
+| 역할      | 서버 코어 (프록시, 인증, 미들웨어, 플러그인) | 비즈니스 로직   |
+| 배포 형태 | 난독화 번들                                  | TypeScript 소스 |
+| 수정 가능 | ✗                                            | ✓               |
+
+### @gateway/api
+
+app 코드에서 시스템 기능을 사용하기 위한 공개 API입니다.
+
+```ts
+import { ok, fail, logger, entityServer } from "@gateway/api";
+import { NotFoundError, BadRequestError } from "@gateway/api";
+import type { EntityHook } from "@gateway/api";
+```
+
+| export                                    | 설명                                            |
+| ----------------------------------------- | ----------------------------------------------- |
+| `ok(data, requestId?)`                    | 성공 응답 `{ success: true, data }`             |
+| `fail(error, requestId?)`                 | 실패 응답 `{ success: false, error }`           |
+| `logger`                                  | pino 로거                                       |
+| `logFmt`                                  | ANSI 컬러 로그 포맷 유틸리티                    |
+| `env`                                     | 환경변수 객체                                   |
+| `serverConfig`                            | 서버 설정 (port, host, baseUrl 등)              |
+| `entityServer`                            | Entity Server REST 클라이언트 (HMAC 내장)       |
+| `ensurePluginEntities`                    | 플러그인 엔티티 스키마 자동 등록                |
+| `sendEmail`                               | 이메일 발송 (`SendEmailParams`)                 |
+| `sendPush` / `sendPushAll`                | 푸시 알림 발송                                  |
+| `registerPushService`                     | 푸시 서비스 레퍼런스 등록                       |
+| `cache`                                   | 캐시 스토어 (`CacheStore`)                      |
+| `acquireLock` / `releaseLock`             | 분산 락 (스케줄러 중복 실행 방지)               |
+| `createCron` / `validateCron`             | Cron 스케줄러 유틸리티                          |
+| `describeCron` / `nextRuns`               | Cron 설명·다음 실행 시각 조회                   |
+| `dbConn(group?)`                          | Kysely DB 인스턴스 반환 (group 생략 시 default) |
+| `sql`                                     | Kysely SQL 템플릿 태그                          |
+| `AppError`                                | 에러 베이스 클래스 (statusCode 포함)            |
+| `BadRequestError` / `NotFoundError` / ... | HTTP 에러 클래스 (400, 404, ...)                |
+| `sha256` / `hmacSha256` / `encryptAesCbc` | 암호화 유틸리티                                 |
+| `hashString` / `hashBuffer`               | SHA-256 해시 유틸리티                           |
+| `fetchWithTimeout` / `fetchJson`          | HTTP 클라이언트 유틸                            |
+| `toNumber` / `toString` / `toBool`        | 타입 변환 유틸                                  |
+| `generateVerificationCode`                | 인증 코드 생성                                  |
+| `validatePassword` / `loadPasswordPolicy` | 비밀번호 정책 검증·로드                         |
+| `registerWithdrawHook`                    | 회원 탈퇴 훅 등록                               |
+| `setSharedLayout` / `renderTemplate`      | 이메일 템플릿 엔진 (Handlebars 기반)            |
+| `substituteEnvVars`                       | `${ENV}` 형태 환경변수 치환                     |
+| `loadJsonConfig`                          | JSON 설정 파일 로더                             |
+| `normalizePhoneE164` / `formatBizNum`     | 전화번호·사업자번호 포맷 유틸리티               |
+| `EntityHook`                              | 훅 인터페이스 (type)                            |
+| `SubmitContext`                           | submit 훅 old/new 컨텍스트 (type)               |
+| `DeleteContext`                           | delete 훅 seq/data 컨텍스트 (type)              |
+| `UserInfo`                                | JWT 사용자 정보 (type)                          |
+| `SendEmailParams`                         | 이메일 발송 파라미터 (type)                     |
+| `PasswordPolicy`                          | 비밀번호 정책 (type)                            |
+
+---
+
+## 데이터 접근 전략
+
+| 방법                  | 용도                           | 예시                         |
+| --------------------- | ------------------------------ | ---------------------------- |
+| `entityServer` (HMAC) | 표준 엔티티 CRUD               | 사용자 조회, 주문 생성       |
+| `app.db` (직접 쿼리)  | 복잡한 집계, JOIN, 일반 테이블 | 대시보드, 리포트, idx 테이블 |
+
+**원칙**: 가능하면 `entityServer`를 우선 사용하고, 복잡한 쿼리가 필요할 때만 `app.db`를 사용합니다.