create-entity-app-server 0.0.3

package/docs/cache.md

@@ -0,0 +1,217 @@
+# 캐시 가이드
+
+Gateway 전역 캐시 시스템입니다.  
+`app.cache` 데코레이터로 등록되며, `@gateway/api` 의 `cache()` 헬퍼로 라우트·플러그인 어디서나 동일한 API 로 사용합니다.
+
+**관련 문서**: [설정 파일 가이드](configs.md)
+
+---
+
+## 설정
+
+`configs/cache.json` 파일로 드라이버와 TTL 을 지정합니다.  
+파일이 없으면 메모리 드라이버 + TTL 3600초로 동작합니다.
+
+```bash
+cp configs/cache.example.json configs/cache.json
+```
+
+---
+
+## 드라이버
+
+| 드라이버      | `driver` 값   | 추가 설치             | 특징                                      |
+| ------------- | ------------- | --------------------- | ----------------------------------------- |
+| **메모리**    | `"memory"`    | 없음                  | 기본값. 빠름. 프로세스 재시작 시 초기화.  |
+| **Redis**     | `"redis"`     | `npm install ioredis` | 프로세스 간 공유, 영속성. 외부 서버 필요. |
+| **Memcached** | `"memcached"` | `npm install memjs`   | 경량·고속. `size` 조회 불가 (항상 `-1`).  |
+
+### memory (기본)
+
+```json
+{
+    "driver": "memory",
+    "default_ttl_seconds": 3600,
+    "memory": {
+        "max_entries": 10000
+    }
+}
+```
+
+| 항목          | 타입   | 기본값  | 설명                                                          |
+| ------------- | ------ | ------- | ------------------------------------------------------------- |
+| `max_entries` | number | `10000` | 최대 항목 수. 초과 시 만료 항목 → 오래된 순으로 20% 자동 제거 |
+
+### redis
+
+```json
+{
+    "driver": "redis",
+    "default_ttl_seconds": 3600,
+    "redis": {
+        "host": "localhost",
+        "port": 6379,
+        "password": "",
+        "db": 0,
+        "key_prefix": "gw:",
+        "connect_timeout_ms": 5000
+    }
+}
+```
+
+| 항목                 | 타입   | 기본값      | 설명                  |
+| -------------------- | ------ | ----------- | --------------------- |
+| `host`               | string | `localhost` | Redis 호스트          |
+| `port`               | number | `6379`      | Redis 포트            |
+| `password`           | string | _(없음)_    | AUTH 비밀번호         |
+| `db`                 | number | `0`         | Redis DB 번호         |
+| `key_prefix`         | string | `"gw:"`     | 모든 키에 붙는 접두사 |
+| `connect_timeout_ms` | number | `5000`      | 연결 타임아웃 (ms)    |
+
+### memcached
+
+```json
+{
+    "driver": "memcached",
+    "default_ttl_seconds": 3600,
+    "memcached": {
+        "host": "localhost",
+        "port": 11211,
+        "username": "",
+        "password": ""
+    }
+}
+```
+
+| 항목       | 타입   | 기본값      | 설명                      |
+| ---------- | ------ | ----------- | ------------------------- |
+| `host`     | string | `localhost` | Memcached 호스트          |
+| `port`     | number | `11211`     | Memcached 포트            |
+| `username` | string | _(없음)_    | SASL 인증 사용자명 (선택) |
+| `password` | string | _(없음)_    | SASL 인증 비밀번호 (선택) |
+
+---
+
+## 공통 설정
+
+| 항목                  | 타입   | 기본값     | 설명                               |
+| --------------------- | ------ | ---------- | ---------------------------------- |
+| `driver`              | string | `"memory"` | 사용할 드라이버                    |
+| `default_ttl_seconds` | number | `3600`     | 기본 TTL (초). `0` 이면 만료 없음. |
+
+---
+
+## 사용법
+
+### 기본 패턴 — Cache-Aside
+
+```ts
+import { cache, ok } from "@gateway/api";
+import type { FastifyRequest, FastifyReply } from "fastify";
+
+async function handler(req: FastifyRequest, reply: FastifyReply) {
+    const store = cache();
+
+    // 1. 캐시 조회
+    const cached = await store.get<User[]>("users:all");
+    if (cached) return ok(cached);
+
+    // 2. 원본 데이터 조회
+    const users = await dbConn().selectFrom("users").selectAll().execute();
+
+    // 3. 캐시 저장 (TTL: 60초)
+    await cache.set("users:all", users, 60_000);
+
+    return ok(users);
+}
+```
+
+### TTL 지정
+
+`set()` 의 세 번째 인수는 **밀리초** 단위입니다.
+
+```ts
+await cache.set("key", data); // default_ttl_seconds 사용
+await cache.set("key", data, 30_000); // 30초
+await cache.set("key", data, 60 * 60_000); // 1시간
+await cache.set("key", data, 0); // 만료 없음
+```
+
+### 전체 API
+
+```ts
+const store = cache();
+
+await store.get<T>("key"); // T | null — 없거나 만료 시 null
+await store.set("key", value); // default TTL 로 저장
+await store.set("key", value, ttlMs); // 지정 TTL 로 저장
+await store.del("key"); // 단일 키 삭제
+await store.has("key"); // boolean
+await store.flush(); // 전체 삭제
+
+cache.size; // 현재 항목 수 (memcached 는 -1)
+cache.driver; // "memory" | "redis" | "memcached"
+```
+
+### 키 네이밍 규칙
+
+충돌 방지를 위해 `{리소스}:{식별자}` 형태를 권장합니다.
+
+```ts
+"users:all";
+"users:123";
+"products:list:page1";
+"config:holidays:2026";
+```
+
+### 캐시 무효화
+
+데이터 변경 시 해당 키를 삭제합니다.
+
+```ts
+// 사용자 목록 업데이트 후
+await db.updateTable("users")...execute();
+await cache().del("users:all");
+```
+
+### 플러그인에서 사용
+
+플러그인 `index.ts` 에서는 `app.cache` 로 직접 접근합니다.
+
+```ts
+// src/app/plugins/my-plugin/service.ts
+import { cache } from "@gateway/api";
+
+export async function fetchWithCache(key: string) {
+    const store = cache();
+    const cached = await store.get<Data>(key);
+    if (cached) return cached;
+
+    const data = await fetchData();
+    await store.set(key, data, 5 * 60_000); // 5분
+    return data;
+}
+```
+
+---
+
+## 드라이버별 주의 사항
+
+### 메모리
+
+- 프로세스 재시작 시 캐시가 초기화됩니다.
+- 멀티 프로세스(PM2 cluster 등) 환경에서는 **프로세스 간 캐시가 공유되지 않습니다**.
+- 개발·단일 프로세스 환경에 적합합니다.
+
+### Redis
+
+- 외부 Redis 서버가 필요합니다.
+- 프로세스 간 캐시가 공유됩니다.
+- `key_prefix` 로 다른 애플리케이션과 키 충돌을 방지하세요.
+- Redis 연결 실패 시 서버 시작이 중단됩니다.
+
+### Memcached
+
+- 외부 Memcached 서버가 필요합니다.
+- `cache.size` 는 키 목록 조회 API 부재로 항상 `-1` 을 반환합니다.
+- `cache.flush()` 는 **해당 서버 전체**를 비웁니다 (네임스페이스 없음).

package/docs/configs.md

@@ -0,0 +1,261 @@
+# 설정 파일 가이드
+
+Gateway의 설정은 두 곳에 나뉩니다.
+
+| 위치             | 용도                                                                        |
+| ---------------- | --------------------------------------------------------------------------- |
+| `.env`           | **비밀값** — API Key, HMAC Secret, JWT Secret 등 외부에 노출되면 안 되는 값 |
+| `configs/*.json` | **서버 동작** — 포트, 로깅, DB 접속, CORS 등 행동 방식을 제어하는 값        |
+
+---
+
+## 설정 파일 목록
+
+| 설정                                      | 설명                                       |
+| ----------------------------------------- | ------------------------------------------ |
+| [.env](#env)                              | 비밀값 (Entity Server 키, JWT Secret)      |
+| [server.json](#serverjson)                | 포트, 호스트, 로깅                         |
+| [database.json](database.md)              | DB 드라이버, 접속 정보, 읽기 전용          |
+| [cache.json](cache.md)                    | 캐시 드라이버 (memory / redis / memcached) |
+| [cors.json](security.md#corsjson)         | CORS 허용 도메인, 헤더                     |
+| [security.json](security.md)              | CSRF, 패킷 암호화, 비밀번호 정책           |
+| [identity.json](plugins/identity.md)      | JWT, 세션, 인증                            |
+| [llm.json](plugins/llm.md)                | LLM (OpenAI / Claude / Gemini)             |
+| [ocr.json](plugins/ocr.md)                | OCR                                        |
+| [pg.json](plugins/pg.md)                  | PG 결제                                    |
+| [tax-invoice.json](plugins/taxinvoice.md) | 전자세금계산서                             |
+| [holidays.json](#holidaysjson)            | 공휴일 API 동기화                          |
+| [alimtalk.json](plugins/alimtalk.md)      | 카카오 알림톡                              |
+| [friendtalk.json](plugins/friendtalk.md)  | 카카오 친구톡                              |
+| [sms.json](plugins/sms.md)                | SMS 발송 플러그인                          |
+| [push.json](plugins/push.md)              | FCM/APNs 푸시 알림                         |
+
+> 파일이 없으면 해당 기능은 기본값으로 동작하거나 비활성화됩니다.
+
+---
+
+## .env
+
+`.env` 파일에는 **외부 서비스 연결에 필요한 비밀값만** 적습니다.  
+서버 포트, 로그 레벨 등 행동 설정은 `configs/server.json`에서 합니다.
+
+### 전체 예시
+
+```env
+# ── 필수 ─────────────────────────────────────────────
+NODE_ENV=production
+
+ENTITY_SERVER_URL=http://127.0.0.1:47200
+ENTITY_API_KEY=your-api-key
+ENTITY_HMAC_SECRET=your-hmac-secret
+
+JWT_SECRET=shared-jwt-secret
+
+# ── DB 직접 접속 (database.json 환경변수 치환용) ──
+DB_HOST_DEVELOPMENT=127.0.0.1
+DB_PORT_DEVELOPMENT=3306
+DB_NAME_DEVELOPMENT=mydb_dev
+DB_USER_DEVELOPMENT=root
+DB_PASSWORD_DEVELOPMENT=password
+
+# ── 선택: 플러그인 API 키 ─────────────────────────
+# OPENAI_API_KEY=
+# ANTHROPIC_API_KEY=
+# ALIMTALK_API_KEY=
+# TOSS_SECRET_KEY=
+```
+
+### 항목 설명
+
+| 항목                 | 필수 | 설명                                                                                           |
+| -------------------- | :--: | ---------------------------------------------------------------------------------------------- |
+| `NODE_ENV`           |  ✅  | `development` \| `production` \| `test`                                                        |
+| `ENTITY_SERVER_URL`  |  ✅  | Entity Server 주소 — Entity Server의 `server.json` `port`(기본: 47200)와 일치                  |
+| `ENTITY_API_KEY`     |  ✅  | Entity Server 관리자 화면에서 발급한 API Key                                                   |
+| `ENTITY_HMAC_SECRET` |  ✅  | API Key 발급 시 함께 제공되는 HMAC Secret                                                      |
+| `JWT_SECRET`         |  ✅  | **Entity Server와 반드시 동일한 값** — Entity Server `configs/auth/jwt.json`의 `${JWT_SECRET}` |
+| `DB_*`               |  -   | `database.json`에서 `${변수명}` 형태로 참조할 때만 필요                                        |
+
+### Entity Server 키 맞추기
+
+게이트웨이는 Entity Server에 API Key + HMAC 서명으로 인증합니다.  
+세 값은 **Entity Server에서 발급된 값**을 그대로 복사해야 합니다.
+
+```
+Entity Server 관리자 → API Keys 메뉴 → 키 생성
+  └─ api_key   → 게이트웨이 .env ENTITY_API_KEY
+  └─ hmac_secret → 게이트웨이 .env ENTITY_HMAC_SECRET
+```
+
+JWT Secret은 Entity Server가 발급한 토큰을 게이트웨이가 직접 검증하기 때문에 반드시 같아야 합니다:
+
+```
+Entity Server configs/auth/jwt.json
+  └─ "secret": "${JWT_SECRET}"  ← 엔티티 서버 .env의 JWT_SECRET
+
+게이트웨이 .env
+  └─ JWT_SECRET=<위와 동일한 값>
+```
+
+> ⚠️ `JWT_SECRET`이 다르면 게이트웨이에서 토큰 검증에 실패해 모든 인증 요청이 401을 반환합니다.
+
+### .env.example
+
+`.env.example`을 복사해 시작하세요:
+
+```bash
+cp .env.example .env
+```
+
+---
+
+## server.json
+
+Gateway 서버의 포트, 호스트, 로깅 동작을 제어합니다.
+
+### 전체 예시
+
+```json
+{
+    "namespace": "gw",
+    "port": 3000,
+    "host": "0.0.0.0",
+    "baseUrl": "http://localhost:3000",
+    "logging": {
+        "level": "info",
+        "logDir": "./logs",
+        "access": {
+            "enabled": true,
+            "filename": "access",
+            "frequency": "daily",
+            "maxFiles": 14,
+            "maxSize": "100m"
+        },
+        "error": {
+            "enabled": true,
+            "filename": "error",
+            "frequency": "daily",
+            "maxFiles": 30,
+            "maxSize": "50m"
+        }
+    }
+}
+```
+
+### 설정 항목
+
+| 항목        | 타입   | 기본값      | 설명                                                                                                                   |
+| ----------- | ------ | ----------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `namespace` | string | `"gw"`      | 인스턴스 식별자 — 모든 캐시 키가 `sha256(namespace:key)` 로 저장됨. 여러 앱이 Redis/Memcached를 공유할 때 키 충돌 방지 |
+| `port`      | number | `3000`      | HTTP 리슨 포트                                                                                                         |
+| `host`      | string | `"0.0.0.0"` | 바인드 호스트 (`127.0.0.1`로 제한 가능)                                                                                |
+| `baseUrl`   | string | _(없음)_    | 공개 베이스 URL — 시작 로그에 출력                                                                                     |
+
+#### logging
+
+| 항목                       | 타입    | 기본값     | 설명                                                         |
+| -------------------------- | ------- | ---------- | ------------------------------------------------------------ |
+| `logging.level`            | string  | `"info"`   | `fatal` \| `error` \| `warn` \| `info` \| `debug` \| `trace` |
+| `logging.logDir`           | string  | `"./logs"` | 로그 파일 저장 디렉터리                                      |
+| `logging.access.enabled`   | boolean | `true`     | 접근 로그 파일 활성화                                        |
+| `logging.access.filename`  | string  | `"access"` | 파일 기본명 (pino-roll이 날짜 접미사 자동 추가)              |
+| `logging.access.frequency` | string  | `"daily"`  | 로테이션 주기: `"daily"` \| `"hourly"`                       |
+| `logging.access.maxFiles`  | number  | `14`       | 보관 최대 파일 수 — 초과분 자동 삭제                         |
+| `logging.access.maxSize`   | string  | `"100m"`   | 파일당 최대 크기 — 초과 시 즉시 교체                         |
+| `logging.error.enabled`    | boolean | `true`     | 에러 로그 파일 활성화 (error 레벨 이상)                      |
+| `logging.error.filename`   | string  | `"error"`  | 파일 기본명                                                  |
+| `logging.error.frequency`  | string  | `"daily"`  | 로테이션 주기                                                |
+| `logging.error.maxFiles`   | number  | `30`       | 보관 최대 파일 수                                            |
+| `logging.error.maxSize`    | string  | `"50m"`    | 파일당 최대 크기                                             |
+
+### 로그 파일 구조
+
+`logs/` 디렉터리에 날짜별 파일이 생성됩니다:
+
+```
+logs/
+├── access.2026-03-04.log   ← 오늘 접근 로그
+├── access.2026-03-03.log   ← 어제 (maxFiles 초과 시 자동 삭제)
+├── error.2026-03-04.log    ← 오늘 에러 로그
+└── error.2026-03-03.log
+```
+
+`access.log` — HTTP 요청 1건당 1줄 JSON:
+
+```json
+{
+    "requestId": "abc-123",
+    "method": "GET",
+    "url": "/api/user/list",
+    "statusCode": 200,
+    "responseTime": 12,
+    "ip": "123.45.67.89",
+    "userAgent": "Mozilla/5.0 ..."
+}
+```
+
+`error.log` — `error` / `fatal` 레벨만 기록:
+
+```json
+{
+    "level": 50,
+    "err": { "message": "...", "stack": "..." },
+    "msg": "Unhandled error"
+}
+```
+
+### 환경별 동작
+
+| 동작       | development        | production                         |
+| ---------- | ------------------ | ---------------------------------- |
+| 콘솔 출력  | pino-pretty (컬러) | JSON stdout                        |
+| access.log | 파일 기록됨        | `logging.access.enabled` 값에 따라 |
+| error.log  | 파일 기록됨        | `logging.error.enabled` 값에 따라  |
+
+### 환경변수 플레이스홀더
+
+```json
+{
+    "port": "${SERVER_PORT}",
+    "baseUrl": "${SERVER_BASE_URL}"
+}
+```
+
+---
+
+## cors.json / security.json
+
+CORS, CSRF, 패킷 암호화, 비밀번호 정책 설정은 **[security.md](security.md)** 를 참고하세요.
+
+---
+
+## holidays.json
+
+공휴일 데이터를 자동으로 동기화하는 스케줄러 설정입니다.  
+Entity Server의 `holiday` 엔티티에 공공 데이터 포털(data.go.kr) API로 조회한 공휴일을 저장합니다.
+
+### 전체 예시
+
+```json
+{
+    "enabled": true,
+    "cron": "0 3 1 1,12 *",
+    "yearsAhead": 1,
+    "entity": "holiday"
+}
+```
+
+### 설정 항목
+
+| 항목         | 타입    | 기본값           | 설명                                           |
+| ------------ | ------- | ---------------- | ---------------------------------------------- |
+| `enabled`    | boolean | `true`           | 공휴일 동기화 활성화                           |
+| `cron`       | string  | `"0 3 1 1,12 *"` | 실행 주기 — 기본값은 1월 1일·12월 1일 새벽 3시 |
+| `yearsAhead` | number  | `1`              | 현재 연도 기준 몇 년 앞까지 미리 동기화할지    |
+| `entity`     | string  | `"holiday"`      | 공휴일 데이터를 저장할 엔티티 이름             |
+
+API Key는 `.env`의 `HOLIDAY_API_KEY`에 설정합니다:
+
+```env
+HOLIDAY_API_KEY=your-data-go-kr-api-key
+```