create-entity-app-server 0.0.3

package/docs/routes/email-verification.md

@@ -0,0 +1,269 @@
+# 이메일 인증 API
+
+게이트웨이 독립 라우트 `app/routes/email-verify/`에서 처리.  
+접두사: `/api/v1/email-verify`
+
+## 라우트 목록
+
+| Method | Path                                                             | 인증 | 설명                |
+| ------ | ---------------------------------------------------------------- | ---- | ------------------- |
+| POST   | [/api/v1/email-verify/send](#1-post-send--인증-코드링크-발송)    | —    | 인증 코드/링크 발송 |
+| POST   | [/api/v1/email-verify/confirm](#2-post-confirm--코드-검증)       | —    | 코드 검증           |
+| GET    | [/api/v1/email-verify/activate](#3-get-activate--링크-클릭-인증) | —    | 링크 클릭 인증      |
+| GET    | [/api/v1/email-verify/status](#4-get-status--인증-상태-조회)     | JWT  | 인증 상태 조회      |
+| POST   | [/api/v1/email-verify/change](#5-post-change--이메일-변경)       | JWT  | 이메일 변경         |
+
+---
+
+## 설정
+
+| 파일                                          | 설명        |
+| --------------------------------------------- | ----------- |
+| `app/routes/email-verify/config.json`         | 런타임 설정 |
+| `app/routes/email-verify/config.example.json` | 배포용 예시 |
+
+### config.json 필드
+
+| 필드                            | 타입    | 기본값          | 설명                                  |
+| ------------------------------- | ------- | --------------- | ------------------------------------- |
+| `enabled`                       | boolean | `true`          | 기능 활성화                           |
+| `required`                      | boolean | `false`         | 미인증 계정 로그인 차단               |
+| `code_length`                   | number  | `6`             | 숫자 인증 코드 길이                   |
+| `code_ttl_sec`                  | number  | `300`           | 코드/토큰 유효 시간(초)               |
+| `max_attempts`                  | number  | `5`             | 최대 인증 시도 횟수                   |
+| `resend_cooldown_sec`           | number  | `60`            | 재발송 쿨다운(초)                     |
+| `link_base_url`                 | string  | `""`            | 링크 인증 활성화 URL (link 방식 필수) |
+| `rate_limit.per_email_per_hour` | number  | `5`             | 이메일당 시간당 최대 발송 수          |
+| `email_subject`                 | string  | `"이메일 인증"` | 이메일 제목                           |
+
+> `link_base_url`은 인증 링크 방식(`method: "link"`) 사용 시 필수.  
+> 예: `https://app.example.com/api/v1/email-verify/activate`
+
+---
+
+## 엔드포인트
+
+### 1. POST /send — 인증 코드/링크 발송
+
+**인증**: 불필요
+
+#### 요청 파라미터 (Body)
+
+| 필드     | 타입   | 필수 | 기본값   | 설명                          |
+| -------- | ------ | ---- | -------- | ----------------------------- |
+| `email`  | string | ✅   | —        | 인증 대상 이메일 (최대 320자) |
+| `method` | string | —    | `"code"` | `"code"` 또는 `"link"`        |
+
+```jsonc
+// 요청
+{
+    "email": "user@example.com",
+    "method": "code"
+}
+
+// 응답 200
+{
+    "success": true,
+    "data": { "message": "인증 이메일을 발송했습니다." }
+}
+```
+
+**동작:**
+
+- 계정 존재 여부와 무관하게 동일 응답 (열거 공격 방지)
+- 이미 인증된 이메일 → `"이미 인증된 이메일입니다."`
+- 재발송 쿨다운(60초) 체크
+- Rate limit: 이메일당 시간 5회
+
+### 2. POST /confirm — 코드 검증
+
+**인증**: 불필요
+
+#### 요청 파라미터 (Body)
+
+| 필드    | 타입   | 필수 | 설명                  |
+| ------- | ------ | ---- | --------------------- |
+| `email` | string | ✅   | 인증 대상 이메일      |
+| `code`  | string | ✅   | 발송된 숫자 인증 코드 |
+
+```jsonc
+// 요청
+{
+    "email": "user@example.com",
+    "code": "482917"
+}
+
+// 성공 200
+{
+    "success": true,
+    "data": { "message": "이메일 인증이 완료되었습니다." }
+}
+
+// 실패 401
+{
+    "success": false,
+    "error": "인증 코드가 일치하지 않습니다."
+}
+```
+
+**동작:**
+
+- 만료 확인 (code_ttl_sec)
+- 시도 횟수 초과 시 429 반환
+- constant-time 비교 (timing attack 방지)
+- 성공 시 `email_verified = true`, 코드 필드 초기화
+
+### 3. GET /activate — 링크 클릭 인증
+
+**인증**: 불필요
+
+```
+GET /api/v1/email-verify/activate?email=user@example.com&token=<64자hex>&redirect=1
+```
+
+| 파라미터   | 설명                                                     |
+| ---------- | -------------------------------------------------------- |
+| `email`    | 인증 대상 이메일                                         |
+| `token`    | 발송된 토큰 원문 (64자 hex)                              |
+| `redirect` | `"1"` 시 인증 후 `link_base_url?verified=1`로 리다이렉트 |
+
+**동작:**
+
+- confirm과 동일한 검증 로직 (만료, 시도횟수, constant-time)
+- 시도 횟수 초과/실패 시 attempts 증가
+- `redirect=1` + `link_base_url` 설정 시 302 리다이렉트
+
+### 4. GET /status — 인증 상태 조회
+
+**인증**: JWT 필요
+
+#### 요청 파라미터
+
+없음 (JWT 토큰에서 사용자 식별)
+
+```jsonc
+// 응답 200
+{
+    "success": true,
+    "data": {
+        "email": "user@example.com",
+        "email_verified": false,
+        "required": false,
+        "can_resend": true,
+        "resend_available_at": "2024-01-01T00:01:00.000Z", // can_resend=false일 때만
+    },
+}
+```
+
+### 5. POST /change — 이메일 변경
+
+**인증**: JWT 필요
+
+#### 요청 파라미터 (Body)
+
+| 필드               | 타입   | 필수 | 설명                                    |
+| ------------------ | ------ | ---- | --------------------------------------- |
+| `new_email`        | string | ✅   | 변경할 새 이메일                        |
+| `current_password` | string | 조건 | 비밀번호 계정은 필수, OAuth 전용은 생략 |
+
+```jsonc
+// 요청
+{
+    "new_email": "new@example.com",
+    "current_password": "현재비밀번호"    // 비밀번호 계정 필수, OAuth 전용 생략
+}
+
+// 응답 200
+{
+    "success": true,
+    "data": {
+        "message": "이메일이 변경되었습니다. 새 이메일로 인증 코드를 발송했습니다.",
+        "email": "new@example.com",
+        "email_verified": false
+    }
+}
+```
+
+**동작:**
+
+- 비밀번호 계정: `current_password` 필수 (SHA-256 constant-time 검증)
+- OAuth 전용 계정: 비밀번호 불필요
+- 중복 이메일 확인 (409 Conflict)
+- 기존 인증 필드 초기화 후 새 코드 발송
+
+---
+
+## 가입 연동 흐름
+
+`POST /api/v1/account/register` 실행 시 email-verify 설정에 따라 자동으로 연동됩니다.
+
+```
+이메일 인증 ON  (email-verify/config.json: enabled=true)
+┌─────────────────────────────────────────────────┐
+│ POST /account/register                                │
+│   → 인증 코드/링크 메일 발송                            │
+│   → email_verified = false                             │
+│                                                         │
+│ POST /email-verify/confirm  또는  GET /activate        │
+│   → 코드/토큰 검증 성공                                │
+│   → email_verified = true 저장                        │
+│   → [send_welcome_email=true] 환영 메일 발송             │
+└─────────────────────────────────────────────────┘
+
+이메일 인증 OFF (email-verify/config.json: enabled=false)
+┌─────────────────────────────────────────────────┐
+│ POST /account/register                                │
+│   → email_verified = true (인증 불필요)                   │
+│   → [send_welcome_email=true] 환영 메일 즉시 발송          │
+└─────────────────────────────────────────────────┘
+```
+
+`send_welcome_email` 팔드는 `account/register/config.json`에서 제어합니다.
+
+---
+
+## 에러 코드
+
+| HTTP | 메시지                          | 상황                     |
+| ---- | ------------------------------- | ------------------------ |
+| 400  | email is required               | 이메일 누락              |
+| 400  | email is too long               | 이메일 320자 초과        |
+| 400  | method must be 'code' or 'link' | 잘못된 method            |
+| 400  | link_base_url is not configured | link 방식인데 URL 미설정 |
+| 400  | 인증 요청이 없습니다.           | 코드 발송 이력 없음      |
+| 401  | 인증 코드가 만료되었습니다.     | TTL 초과                 |
+| 401  | 인증 코드가 일치하지 않습니다.  | 코드 불일치              |
+| 401  | 비밀번호가 일치하지 않습니다.   | 이메일 변경 시 비번 틀림 |
+| 409  | 이미 사용 중인 이메일입니다.    | 중복 이메일              |
+| 429  | 발송 제한 횟수를 초과했습니다.  | Rate limit 초과          |
+| 429  | 최대 시도 횟수를 초과했습니다.  | max_attempts 초과        |
+| 429  | 재발송 쿨다운 중입니다.         | 60초 이내 재발송         |
+
+---
+
+## 이메일 템플릿
+
+| 파일                                          | 사용처    | 변수                                             |
+| --------------------------------------------- | --------- | ------------------------------------------------ |
+| `templates/email/auth/verification.html`      | 코드 인증 | `${code}`, `${expires_in}`, `${email}`           |
+| `templates/email/auth/verification_link.html` | 링크 인증 | `${activation_url}`, `${expires_in}`, `${email}` |
+
+---
+
+## 관련 문서
+
+- [Account Routes](./account-routes.md)
+- [Alimtalk Routes](./alimtalk-routes.md)
+- [Friendtalk Routes](./friendtalk-routes.md)
+- [Holidays Routes](./holidays-routes.md)
+- [Identity Routes](./identity-routes.md)
+- [LLM Routes](./llm-routes.md)
+- [OCR Routes](./ocr-routes.md)
+- [Password Reset](./password-reset.md)
+- [PG Routes](./pg-routes.md)
+- [SMS Routes](./sms-routes.md)
+- [SMTP Routes](./smtp-routes.md)
+- [Tax Invoice Routes](./tax-invoice-routes.md)
+- [라우트 추가 가이드](./how-to-create.md)
+- [Push Routes](./push-routes.md)
+- [← 전체 목록](./README.md)

package/docs/routes/friendtalk-routes.md

@@ -0,0 +1,45 @@
+# Friendtalk Routes
+
+기준 파일: `src/app/plugins/friendtalk/routes.ts`
+
+이 문서는 실제 API 호출 중심(라우트표/사용 예제/응답 예제)을 다룹니다.  
+플러그인의 개요/설정/운영 가이드는 [Friendtalk Guide](../../plugins/friendtalk.md) 문서를 참고하세요.
+
+## 라우트 목록
+
+| Method | Path                                                 | 설명        |
+| ------ | ---------------------------------------------------- | ----------- |
+| POST   | [/api/v1/friendtalk/send](#post-v1apifriendtalksend) | 친구톡 발송 |
+
+## 라우트 상세
+
+### POST /api/v1/friendtalk/send
+
+<a id="post-v1apifriendtalksend"></a>
+
+- 설명: 친구톡 메시지를 수신자에게 발송한다.
+- 사용 예제:
+
+```bash
+curl -X POST "http://localhost:3000/api/v1/friendtalk/send" \
+	-H "Content-Type: application/json" \
+	-d '{"to":"01012345678","message":"친구톡 테스트 메시지"}'
+```
+
+## 관련 문서
+
+- [Account Routes](./account-routes.md)
+- [Alimtalk Routes](./alimtalk-routes.md)
+- [Email Verification](./email-verification.md)
+- [Holidays Routes](./holidays-routes.md)
+- [Identity Routes](./identity-routes.md)
+- [LLM Routes](./llm-routes.md)
+- [OCR Routes](./ocr-routes.md)
+- [Password Reset](./password-reset.md)
+- [PG Routes](./pg-routes.md)
+- [SMS Routes](./sms-routes.md)
+- [SMTP Routes](./smtp-routes.md)
+- [Tax Invoice Routes](./tax-invoice-routes.md)
+- [라우트 추가 가이드](./how-to-create.md)
+- [Push Routes](./push-routes.md)
+- [← 전체 목록](./README.md)

package/docs/routes/holidays-routes.md

@@ -0,0 +1,170 @@
+# Holidays Routes
+
+기준 파일: `src/app/plugins/holidays/routes.ts`
+
+이 문서는 실제 API 호출 중심(라우트표/사용 예제/응답 예제)을 다룹니다.  
+플러그인의 개요/설정/운영 가이드는 [Holidays Guide](../../plugins/holidays.md) 문서를 참고하세요.
+
+## 라우트 목록
+
+| Method | Path                                                   | 설명                        |
+| ------ | ------------------------------------------------------ | --------------------------- |
+| GET    | [/api/v1/holidays](#get-v1apiholidays)                 | 공휴일 목록 조회            |
+| GET    | [/api/v1/holidays/:locdate](#get-v1apiholidayslocdate) | 특정 날짜 공휴일 단건 조회  |
+| POST   | [/api/v1/holidays/sync](#post-v1apiholidayssync)       | 수동 동기화 트리거 (관리자) |
+
+## 라우트 상세
+
+### GET /api/v1/holidays
+
+<a id="get-v1apiholidays"></a>
+
+- 설명: 공휴일 목록을 조회한다. 쿼리 파라미터로 연도·월·공휴일 여부 등을 필터링할 수 있다.
+
+**쿼리 파라미터**
+
+| 파라미터     | 타입   | 필수 | 설명                                  |
+| ------------ | ------ | ---- | ------------------------------------- |
+| `year`       | number | -    | 연도 (예: `2025`)                     |
+| `month`      | number | -    | 월 `1`~`12` (예: `5`)                 |
+| `is_holiday` | string | -    | 공휴일 여부 `Y` 또는 `N`              |
+| `date_kind`  | string | -    | 날짜 분류 코드                        |
+| `page`       | number | -    | 페이지 번호 (기본 `1`)                |
+| `limit`      | number | -    | 페이지당 건수 (기본 `50`, 최대 `500`) |
+
+- 사용 예제:
+
+```bash
+# 2025년 5월 공휴일 전체 조회
+curl "http://localhost:3000/api/v1/holidays?year=2025&month=5&is_holiday=Y"
+
+# 2025년 전체 공휴일 조회
+curl "http://localhost:3000/api/v1/holidays?year=2025&is_holiday=Y"
+
+# 페이지네이션
+curl "http://localhost:3000/api/v1/holidays?year=2025&page=1&limit=20"
+```
+
+- 응답 예제:
+
+```json
+{
+    "ok": true,
+    "data": {
+        "items": [
+            {
+                "locdate": 20250505,
+                "dateName": "어린이날",
+                "is_holiday": "Y",
+                "date_kind": "01"
+            }
+        ],
+        "total": 1,
+        "page": 1,
+        "limit": 50
+    }
+}
+```
+
+---
+
+### GET /api/v1/holidays/:locdate
+
+<a id="get-v1apiholidayslocdate"></a>
+
+- 설명: `YYYYMMDD` 형식의 날짜로 해당 날짜의 공휴일 정보를 단건 조회한다.
+
+**경로 파라미터**
+
+| 파라미터  | 타입   | 설명                              |
+| --------- | ------ | --------------------------------- |
+| `locdate` | string | 날짜 (8자리 숫자, 예: `20250505`) |
+
+- 사용 예제:
+
+```bash
+curl "http://localhost:3000/api/v1/holidays/20250505"
+```
+
+- 응답 예제 (공휴일인 경우):
+
+```json
+{
+    "ok": true,
+    "data": {
+        "items": [
+            {
+                "locdate": 20250505,
+                "dateName": "어린이날",
+                "is_holiday": "Y",
+                "date_kind": "01"
+            }
+        ],
+        "total": 1
+    }
+}
+```
+
+- 응답 예제 (해당 날짜 없음):
+
+```json
+{
+    "ok": false,
+    "error": "no holidays on that date"
+}
+```
+
+---
+
+### POST /api/v1/holidays/sync
+
+<a id="post-v1apiholidayssync"></a>
+
+- 설명: 공휴일 데이터를 즉시 수동으로 동기화한다. 관리자 전용.
+- 주의: 플러그인이 비활성화(`enabled: false`)되어 있거나 `HOLIDAY_API_KEY`가 없으면 `503`을 반환한다.
+
+- 사용 예제:
+
+```bash
+curl -X POST "http://localhost:3000/api/v1/holidays/sync"
+```
+
+- 응답 예제:
+
+```json
+{
+    "ok": true,
+    "data": {
+        "message": "Holiday sync completed"
+    }
+}
+```
+
+- 오류 응답 (플러그인 비활성화):
+
+```json
+{
+    "ok": false,
+    "error": "Holidays plugin not enabled"
+}
+```
+
+---
+
+## 관련 문서
+
+- [Account Routes](./account-routes.md)
+- [Alimtalk Routes](./alimtalk-routes.md)
+- [Email Verification](./email-verification.md)
+- [Friendtalk Routes](./friendtalk-routes.md)
+- [Identity Routes](./identity-routes.md)
+- [LLM Routes](./llm-routes.md)
+- [OCR Routes](./ocr-routes.md)
+- [Password Reset](./password-reset.md)
+- [PG Routes](./pg-routes.md)
+- [SMS Routes](./sms-routes.md)
+- [SMTP Routes](./smtp-routes.md)
+- [Tax Invoice Routes](./tax-invoice-routes.md)
+- [라우트 추가 가이드](./how-to-create.md)
+- [Push Routes](./push-routes.md)
+- [← 전체 목록](./README.md)

package/docs/routes/how-to-create.md

@@ -0,0 +1,150 @@
+# 라우트 추가 가이드
+
+`health`는 `app/routes`에 비즈니스 라우트를 추가할 때의 기준 샘플이다.
+
+기준 파일: `src/app/routes/health/route.ts`
+
+## 라우트 추가 방법
+
+새 도메인도 `health`와 같은 패턴으로 구성한다.
+
+### 1) 폴더 구조
+
+`{domain}`은 새 비즈니스 도메인 이름(예: `orders`, `customers`)이다.
+
+```text
+src/app/routes/{domain}/
+├── config.json    — 라우트 활성화 여부 (enabled: true/false)
+├── route.ts
+├── handlers.ts
+├── service.ts
+├── schema.ts
+└── types/
+    ├── index.ts       — 타입 re-export 배럴
+    ├── {model}.ts     — 엔티티/모델별 타입
+    ├── params.ts      — 요청 파라미터 타입
+    ├── query.ts       — 쿼리스트링 타입
+    └── defaults.ts    — 타입별 기본값 객체
+```
+
+### 2) 파일 역할
+
+- `config.json`: 라우트 활성화 여부를 제어한다. `enabled: false`이면 로그 없이 스킵된다.
+- `route.ts`: URL과 핸들러를 연결하는 라우트 테이블만 작성한다.
+- `handlers.ts`: 요청/응답 처리, 입력 파싱, 서비스 호출, 에러 응답을 담당한다.
+- `service.ts`: 실제 비즈니스 로직(entityServer 호출, DB 쿼리, 계산, 상태 처리)을 담당한다.
+- `schema.ts`: zod 스키마로 요청/응답을 런타임 검증한다.
+- `types/`: TypeScript 타입 정의. `index.ts`에서 일괄 re-export한다.
+
+### 3) `config.json` 규칙
+
+`config.json`이 없으면 항상 등록된다. `enabled: false`로 설정하면 관련 로그를 내지 않고 스킵된다.
+
+```json
+{ "enabled": true }
+```
+
+샘플 라우트(`routes/example-db`, `routes/example-es`):
+
+```json
+{ "enabled": false }
+```
+
+### 4) `route.ts` 작성 원칙 (health와 동일)
+
+- `import * as h from "./handlers.ts"` 형태로 핸들러를 가져온다.
+- `app.get`, `app.post`, `app.patch`, `app.delete`로 메서드와 경로만 매핑한다.
+- `route.ts`에 비즈니스 로직을 넣지 않는다.
+
+예시:
+
+```ts
+import type { FastifyInstance } from "fastify";
+import * as h from "./handlers.ts";
+
+export default async function domainRoutes(app: FastifyInstance) {
+    app.get("/", h.list);
+    app.post("/", h.create);
+    app.get("/:id", h.getById);
+}
+```
+
+### 5) 등록 경로 규칙
+
+- `src/app/routes/{domain}/route.ts`로 두면 게이트웨이 경로는 기본적으로 `/api/v1/{domain}/*`로 등록된다.
+- 예: `src/app/routes/orders/route.ts` → `/api/v1/orders/*`
+
+### 6) Entity Server 패스스루 오버라이드
+
+**`plugins/` 또는 `routes/`에 정의한 라우트는 Entity Server 패스스루보다 항상 먼저 처리된다.**
+
+앱 서버 라우트 로딩 순서 (`system/app.ts`):
+
+```
+1. loadExtensionPlugins()        — plugins/*/index.ts (Fastify 플러그인 + 라우트 등록)
+2. registerEntityInterceptor()   — 엔티티 CRUD 훅 인터셉터
+3. registerRoutes()              — routes/*/route.ts (비즈니스 라우트)
+4. registerProxyRoutes()         — /api/v1/{prefix}/* → Entity Server 패스스루 (위에서 처리되지 않은 경로만)
+```
+
+따라서 Entity Server가 원래 처리하던 경로(예: `/api/v1/smtp/send`)라도
+`plugins/smtp/routes.ts`나 `routes/smtp/route.ts`에 동일 경로를 등록하면
+앱 서버가 직접 처리하고 Entity Server로는 전달되지 않는다.
+
+이를 활용하면:
+
+- 로컬 템플릿 렌더링 후 Go 서버로 결과를 전달하거나
+- Entity Server API를 호출하기 전에 앱 서버 로직(인증, 가공, 캐시 등)을 삽입할 수 있다.
+
+### 6) 문서 업데이트 규칙
+
+새 도메인 라우트를 만들면 `docs/routes/`에 라우트 문서를 추가하고, 모든 라우트 문서의 `관련 문서`에도 링크를 추가한다.
+
+## 라우트 목록
+
+| Method | Path                                          | 설명             |
+| ------ | --------------------------------------------- | ---------------- |
+| GET    | [/api/v1/health/](#get-v1apihealth)           | 서비스 상태 확인 |
+| GET    | [/api/v1/health/ready](#get-v1apihealthready) | 준비 상태 확인   |
+
+## 라우트 상세
+
+### GET /api/v1/health/
+
+<a id="get-v1apihealth"></a>
+
+- 설명: 게이트웨이 프로세스의 기본 상태를 점검한다.
+- 사용 예제:
+
+```bash
+curl "http://localhost:3000/api/v1/health/"
+```
+
+### GET /api/v1/health/ready
+
+<a id="get-v1apihealthready"></a>
+
+- 설명: 외부 의존성 포함 서비스 준비 상태(ready)를 점검한다.
+- 사용 예제:
+
+```bash
+curl "http://localhost:3000/api/v1/health/ready"
+```
+
+## 관련 문서
+
+- [Account Routes](./account-routes.md)
+- [Alimtalk Routes](./alimtalk-routes.md)
+- [Email Verification](./email-verification.md)
+- [Friendtalk Routes](./friendtalk-routes.md)
+- [Holidays Routes](./holidays-routes.md)
+- [Identity Routes](./identity-routes.md)
+- [LLM Routes](./llm-routes.md)
+- [OCR Routes](./ocr-routes.md)
+- [Password Reset](./password-reset.md)
+- [PG Routes](./pg-routes.md)
+- [SMS Routes](./sms-routes.md)
+- [SMTP Routes](./smtp-routes.md)
+- [Tax Invoice Routes](./tax-invoice-routes.md)
+- [Push Routes](./push-routes.md)
+- [← 전체 목록](./README.md)