create-entity-app-server 0.0.3

package/docs/plugins/2fa.md

@@ -0,0 +1,121 @@
+# 2FA (TOTP) 플러그인
+
+QR 코드 기반 TOTP(Time-based One-Time Password) 2단계 인증 플러그인입니다.
+
+---
+
+## 목차
+
+- [개요](#개요)
+- [설정](#설정)
+- [로그인 흐름](#로그인-흐름)
+- [API 레퍼런스](#api-레퍼런스)
+- [엔티티 구조](#엔티티-구조)
+
+---
+
+## 개요
+
+Go 서버 로그인(`/v1/auth/login`)이 `two_factor_token`을 반환하면, 클라이언트는
+이 플러그인의 `/api/v1/account/2fa/verify` 로 TOTP 코드를 전달해 최종 JWT를 발급받습니다.
+
+```
+POST /v1/auth/login
+    └─ 2FA 활성화 계정 → { two_factor_token: "..." }
+            │
+            ▼
+POST /api/v1/account/2fa/verify   (TOTP 코드 제출)
+    └─ 검증 성공 → { access_token, refresh_token }
+```
+
+---
+
+## 설정
+
+`app/plugins/2fa/config.json`:
+
+```json
+{
+    "enabled": true,
+    "issuer": "EntityServer",
+    "code_digits": 6,
+    "period_sec": 30,
+    "skew": 1,
+    "recovery_code_count": 10,
+    "setup_token_ttl_sec": 300,
+    "max_verify_attempts": 5,
+    "verify_lockout_sec": 300,
+    "jwt_access_ttl_sec": 3600,
+    "jwt_refresh_ttl_sec": 1209600,
+    "jwt_issuer": "entity-server"
+}
+```
+
+| 필드                  | 기본값            | 설명                                  |
+| --------------------- | ----------------- | ------------------------------------- |
+| `enabled`             | `true`            | 플러그인 활성화                       |
+| `issuer`              | `"EntityServer"`  | OTP 앱에 표시되는 서비스 이름         |
+| `code_digits`         | `6`               | OTP 코드 자릿수                       |
+| `period_sec`          | `30`              | OTP 유효 주기 (초)                    |
+| `skew`                | `1`               | 허용 시간 오차 (±`skew` 주기)         |
+| `recovery_code_count` | `10`              | 발급되는 복구 코드 수                 |
+| `setup_token_ttl_sec` | `300`             | 설정 토큰 유효 시간 (초)              |
+| `max_verify_attempts` | `5`               | 실패 허용 횟수 (초과 시 잠금)         |
+| `verify_lockout_sec`  | `300`             | 잠금 해제까지 대기 시간 (초)          |
+| `jwt_access_ttl_sec`  | `3600`            | 발급하는 Access Token 유효 시간 (초)  |
+| `jwt_refresh_ttl_sec` | `1209600`         | 발급하는 Refresh Token 유효 시간 (초) |
+| `jwt_issuer`          | `"entity-server"` | JWT `iss` 클레임 값                   |
+
+---
+
+## 로그인 흐름
+
+```
+1. POST /v1/auth/login → { two_factor_token }
+2. POST /api/v1/account/2fa/verify { two_factor_token, code } → { access_token, refresh_token }
+```
+
+복구 코드 사용 시:
+
+```
+POST /api/v1/account/2fa/recovery { two_factor_token, recovery_code }
+    → { access_token, refresh_token }
+```
+
+### 2FA 등록 흐름
+
+```
+1. POST /api/v1/account/2fa/setup (JWT) → { qr_url, secret, setup_token }
+2. 클라이언트: OTP 앱으로 QR 스캔
+3. POST /api/v1/account/2fa/setup/verify { setup_token, code } → 활성화 완료 + 복구 코드 반환
+```
+
+---
+
+## API 레퍼런스
+
+| 메소드   | 경로                                      | 인증               | 설명                          |
+| -------- | ----------------------------------------- | ------------------ | ----------------------------- |
+| `POST`   | `/api/v1/account/2fa/setup`               | JWT                | 2FA 설정 시작 (QR·secret)     |
+| `POST`   | `/api/v1/account/2fa/setup/verify`        | JWT or setup_token | 2FA 활성화 확인               |
+| `DELETE` | `/api/v1/account/2fa`                     | JWT                | 2FA 비활성화                  |
+| `GET`    | `/api/v1/account/2fa/status`              | JWT                | 2FA 활성화 여부 조회          |
+| `POST`   | `/api/v1/account/2fa/recovery/regenerate` | JWT                | 복구 코드 재생성              |
+| `POST`   | `/api/v1/account/2fa/verify`              | two_factor_token   | TOTP 코드 검증 + JWT 발급     |
+| `POST`   | `/api/v1/account/2fa/recovery`            | two_factor_token   | 복구 코드로 로그인 + JWT 발급 |
+
+---
+
+## 엔티티 구조
+
+2FA 플러그인 활성화 시 `account` 엔티티에 아래 필드가 추가됩니다  
+(`plugins/2fa/entities/account.json`으로 자동 동기화).
+
+| 필드                   | 타입        | 설명                                  |
+| ---------------------- | ----------- | ------------------------------------- |
+| `totp_secret`          | varchar(64) | TOTP Base32 시크릿 (암호화 저장 권장) |
+| `totp_enabled`         | bool        | 2FA 활성화 여부                       |
+| `totp_enabled_time`    | datetime    | 2FA 활성화 시각                       |
+| `totp_recovery_codes`  | text        | 복구 코드 목록 (JSON 배열)            |
+| `totp_failed_attempts` | uint        | 연속 실패 횟수 (잠금 판단 기준)       |
+| `totp_locked_until`    | datetime    | 잠금 해제 시각                        |

package/docs/plugins/alimtalk.md

@@ -0,0 +1,212 @@
+# 알림톡(Alimtalk) 가이드
+
+카카오 알림톡 발송 기능에 대한 설정·API·운영 가이드입니다.
+
+이 문서는 플러그인의 개요/설정/운영 가이드를 중심으로 다룹니다.  
+실제 라우트표, 호출 예제, 응답 예제는 [Alimtalk Routes](../routes/alimtalk-routes.md) 문서를 참고하세요.
+
+---
+
+## 목차
+
+- [개요](#개요)
+- [프로바이더 비교](#프로바이더-비교)
+- [설정](#설정)
+- [발송 흐름](#발송-흐름)
+- [API 레퍼런스](#api-레퍼런스)
+- [템플릿 등록](#템플릿-등록)
+- [운영 팁](#운영-팁)
+
+---
+
+## 개요
+
+카카오 알림톡은 **사전 검수된 템플릿** 기반으로 정보성 메시지를 발송합니다. 광고성 메시지는 불가하며, 카카오 비즈니스 채널이 필요합니다.
+
+| 항목      | 알림톡          | SMS         |
+| --------- | --------------- | ----------- |
+| 채널      | 카카오톡        | 일반 문자   |
+| 가격      | ~6.5원/건       | ~10원/건    |
+| 템플릿    | 사전 검수 필수  | 자유        |
+| 수신 조건 | 카카오톡 사용자 | 모든 휴대폰 |
+
+---
+
+## 프로바이더 비교
+
+| 항목        | **aligo**         | **solapi**            | **ppurio**             | **nhn_cloud**        |
+| ----------- | ----------------- | --------------------- | ---------------------- | -------------------- |
+| 홈페이지    | aligo.in          | solapi.com            | ppurio.com             | nhncloud.com         |
+| 알림톡 단가 | 6.5원             | 7원                   | 8원                    | 7.5원                |
+| 인증 방식   | API Key + User ID | API Key + HMAC-SHA256 | Account + Bearer Token | App Key + Secret Key |
+| SMS 폴백    | ✅                | ✅                    | ✅                     | ✅                   |
+
+---
+
+## 설정
+
+`configs/notification/alimtalk.json`:
+
+```json
+{
+    "enabled": true,
+    "default": "aligo",
+    "sender_key": "${ALIMTALK_SENDER_KEY}",
+    "workers": 2,
+    "dispatch_interval_sec": 5,
+    "queue_size": 200,
+    "max_retries": 3,
+    "_template_file": "templates/notification/alimtalk.json",
+    "providers": {
+        "aligo": {
+            "driver": "aligo",
+            "api_key": "${ALIGO_API_KEY}",
+            "user_id": "${ALIGO_USER_ID}",
+            "sender_key": "${ALIMTALK_SENDER_KEY}"
+        },
+        "solapi": {
+            "driver": "solapi",
+            "api_key": "${SOLAPI_API_KEY}",
+            "api_secret": "${SOLAPI_API_SECRET}",
+            "sender_key": "${ALIMTALK_SENDER_KEY}",
+            "pf_id": "${SOLAPI_PF_ID}"
+        },
+        "bizgo": {
+            "driver": "bizgo",
+            "biz_id": "${BIZGO_BIZ_ID}",
+            "api_key": "${BIZGO_API_KEY}",
+            "api_secret": "${BIZGO_API_SECRET}",
+            "sender_key": "${ALIMTALK_SENDER_KEY}"
+        },
+        "nhncloud": {
+            "driver": "nhncloud",
+            "app_key": "${NHNCLOUD_APP_KEY}",
+            "secret_key": "${NHNCLOUD_SECRET_KEY}",
+            "sender_key": "${ALIMTALK_SENDER_KEY}"
+        }
+    }
+}
+```
+
+### 주요 설정 항목
+
+| 항목                    | 기본값 | 설명                             |
+| ----------------------- | ------ | -------------------------------- |
+| `enabled`               | `true` | 기능 활성화 여부                 |
+| `default`               | -      | 기본 프로바이더 이름 (key, 필수) |
+| `sender_key`            | -      | 카카오 발신프로필 키             |
+| `workers`               | `2`    | 동시 발송 워커 수                |
+| `dispatch_interval_sec` | `5`    | 디스패처 폴링 주기(초)           |
+| `max_retries`           | `3`    | 최대 재시도 횟수                 |
+| `_template_file`        | -      | 템플릿 정의 JSON 파일 경로       |
+
+### 프로바이더별 드라이버 설정
+
+| driver     | 필수 필드                                       |
+| ---------- | ----------------------------------------------- |
+| `aligo`    | `api_key`, `user_id`, `sender_key`              |
+| `solapi`   | `api_key`, `api_secret`, `pf_id`, `sender_key`  |
+| `ppurio`   | `account`, `api_key`, `sender_key`              |
+| `bizgo`    | `biz_id`, `api_key`, `api_secret`, `sender_key` |
+| `nhncloud` | `app_key`, `secret_key`, `sender_key`           |
+
+### 환경변수 (.env)
+
+```env
+ALIMTALK_SENDER_KEY=your-sender-key
+ALIGO_API_KEY=your-aligo-api-key
+ALIGO_USER_ID=your-aligo-user-id
+# SOLAPI_API_KEY=
+# SOLAPI_API_SECRET=
+# SOLAPI_PF_ID=
+```
+
+---
+
+## 발송 흐름
+
+```
+POST /api/v1/alimtalk/send
+         │
+         ▼
+     enqueueJob()
+         │
+         ▼
+alimtalk_log (pending) INSERT
+         │
+         ▼
+디스패처 (dispatch_interval_sec 주기)
+         │
+     ClaimPendingLogs() [CAS: pending→processing]
+         │
+         ▼
+워커 (workers 수만큼 병렬)
+         │
+     ├─ 템플릿 캐시에서 #{변수} 바인딩
+     ├─ 프로바이더 API 호출
+     ├─ 성공 → status: sent, sent_at 기록
+     └─ 실패 → status: failed, retry_count 증가
+```
+
+---
+
+## API 레퍼런스
+
+이 문서는 기능 소개/설정/운영 기준을 다룹니다.  
+라우트별 파라미터 표, 요청/응답 예제, 상태코드는 아래 라우트 문서를 기준으로 확인합니다.
+
+- 상세 API 레퍼런스: [Alimtalk Routes](../routes/alimtalk-routes.md)
+
+기본 경로: `/api/v1/alimtalk`
+
+| 메서드 | 경로                 | 설명                    |
+| ------ | -------------------- | ----------------------- |
+| `POST` | `/send`              | 알림톡 발송 요청        |
+| `GET`  | `/templates`         | 템플릿 목록 조회        |
+| `GET`  | `/status/:seq`       | 발송 상태 조회 (미구현) |
+| `POST` | `/webhook/:provider` | 프로바이더 웹훅 수신    |
+
+---
+
+## 템플릿 등록
+
+### templates/notification/alimtalk.json 형식
+
+```json
+[
+    {
+        "templateCode": "ORDER_001",
+        "templateName": "주문 접수 알림",
+        "variables": ["고객명", "주문번호", "결제금액"]
+    }
+]
+```
+
+> 서버 시작 시 인메모리 캐시에 로드됩니다. 변경 후 재시작 필요.
+
+### 템플릿 작성 규칙
+
+| 규칙      | 설명                          |
+| --------- | ----------------------------- |
+| 변수 형식 | `#{변수명}`                   |
+| 최대 길이 | 1,000자                       |
+| 버튼      | 최대 5개                      |
+| 내용      | 정보성만 허용, 광고 문구 불가 |
+
+---
+
+## 운영 팁
+
+- 새 템플릿 카카오 검수는 **1~3 영업일** 소요 — 운영 전 충분한 여유 확보
+- 알림톡(~6.5원)이 SMS(~10원)보다 저렴 — 가능하면 우선 사용
+- `#{변수명}`과 `variables` JSON 키가 **완전히 일치**해야 함
+- 카카오 비즈니스 채널 차단 시 모든 발송 중단 → 채널 상태 모니터링 필요
+
+---
+
+## 관련 문서
+
+- [Alimtalk Routes](../routes/alimtalk-routes.md)
+- [친구톡 가이드](friendtalk.md)
+- [설정 예제](../../configs-example/notification/alimtalk.json)
+- [Entity Server 알림톡 가이드](../../../docs/notification/alimtalk-guide.md)

package/docs/plugins/friendtalk.md

@@ -0,0 +1,158 @@
+# 친구톡(FriendTalk) 가이드
+
+카카오톡 채널을 추가한 친구에게 자유 형식 브랜드 메시지를 발송하는 기능입니다.
+
+이 문서는 플러그인의 개요/설정/운영 가이드를 중심으로 다룹니다.  
+실제 라우트표, 호출 예제, 응답 예제는 [Friendtalk Routes](../routes/friendtalk-routes.md) 문서를 참고하세요.
+
+---
+
+## 목차
+
+- [개요](#개요)
+- [알림톡과의 차이점](#알림톡과의-차이점)
+- [설정](#설정)
+- [API 레퍼런스](#api-레퍼런스)
+- [msg_type별 발송 예시](#msg_type별-발송-예시)
+- [광고 메시지 규칙](#광고-메시지-규칙)
+- [운영 팁](#운영-팁)
+
+---
+
+## 개요
+
+친구톡은 카카오톡 채널을 **추가한 사용자에게만** 발송 가능한 마케팅형 메시지입니다.
+
+- 사전 검수 템플릿 **불필요** — 자유 텍스트 즉시 발송
+- 이미지·와이드·캐러셀 등 다양한 메시지 유형 지원
+- 광고성 메시지 수신 동의 및 광고 표기 **의무**
+
+---
+
+## 알림톡과의 차이점
+
+| 항목        | 알림톡              | 친구톡                                         |
+| ----------- | ------------------- | ---------------------------------------------- |
+| 템플릿      | ✅ 필수 (사전 검수) | ❌ 불필요                                      |
+| 수신 대상   | 채널 미추가 포함    | **채널 추가 친구만**                           |
+| 메시지 유형 | 텍스트 (변수 치환)  | 텍스트·이미지·와이드·캐러셀                    |
+| 광고 표기   | 비광고 허용         | 광고 여부 명시 필수                            |
+| 설정 파일   | `alimtalk.json`     | `friendtalk.json` (프로바이더는 alimtalk 공유) |
+
+---
+
+## 설정
+
+`configs/notification/friendtalk.json`:
+
+```json
+{
+    "enabled": false,
+    "default": "solapi",
+    "workers": 2,
+    "ad_prefix": "(광고)",
+    "default_ad": true,
+    "_template_file": "templates/notification/friendtalk.json",
+    "providers": {
+        "solapi": {
+            "driver": "solapi",
+            "api_key": "${SOLAPI_API_KEY}",
+            "api_secret": "${SOLAPI_API_SECRET}",
+            "pf_id": "${SOLAPI_PF_ID}",
+            "api_url": "https://api.solapi.com"
+        },
+        "aligo": {
+            "driver": "aligo",
+            "api_key": "${ALIGO_API_KEY}",
+            "user_id": "${ALIGO_USER_ID}",
+            "sender_key": "${ALIMTALK_SENDER_KEY}"
+        },
+        "nhncloud": {
+            "driver": "nhncloud",
+            "app_key": "${NHNCLOUD_APP_KEY}",
+            "secret_key": "${NHNCLOUD_SECRET_KEY}",
+            "plus_friend_id": "${KAKAO_PLUS_FRIEND_ID}"
+        }
+    }
+}
+```
+
+### 설정 항목
+
+| 항목             | 기본값     | 설명                                    |
+| ---------------- | ---------- | --------------------------------------- |
+| `enabled`        | `false`    | 기능 활성화 여부 (`false`이면 503 반환) |
+| `default`        | -          | 기본 프로바이더 이름 (key, 필수)        |
+| `workers`        | `2`        | 백그라운드 발송 워커 수                 |
+| `ad_prefix`      | `"(광고)"` | `is_ad: true`일 때 본문 앞 자동 삽입    |
+| `default_ad`     | `true`     | `is_ad` 미지정 시 기본값                |
+| `_template_file` | -          | 본문 패턴 템플릿 파일 경로              |
+
+---
+
+## API 레퍼런스
+
+이 문서는 기능 소개/설정/운영 기준을 다룹니다.  
+라우트별 파라미터 표, 요청/응답 예제, 상태코드는 아래 라우트 문서를 기준으로 확인합니다.
+
+- 상세 API 레퍼런스: [Friendtalk Routes](../routes/friendtalk-routes.md)
+
+기본 경로: `/api/v1/friendtalk`
+
+| 메서드 | 경로    | 설명                |
+| ------ | ------- | ------------------- |
+| `POST` | `/send` | 친구톡 발송 큐 등록 |
+
+---
+
+## msg_type별 발송 예시
+
+### 이미지형 (image)
+
+```json
+{
+    "receiver": "01012345678",
+    "content": "이번 주 특가 상품을 확인하세요!",
+    "msg_type": "image",
+    "image_url": "https://cdn.example.com/promo.jpg",
+    "image_link": "https://example.com/promo",
+    "is_ad": true
+}
+```
+
+### 와이드 이미지형 (wide_image)
+
+```json
+{
+    "receiver": "01012345678",
+    "content": "신상품 출시",
+    "msg_type": "wide_image",
+    "image_url": "https://cdn.example.com/wide.jpg",
+    "image_link": "https://example.com/new"
+}
+```
+
+---
+
+## 광고 메시지 규칙
+
+- `is_ad: true`이면 `ad_prefix`(기본: `(광고)`)가 본문 앞에 **자동 삽입**됩니다
+- 광고 메시지는 수신 동의를 받은 사용자에게만 발송해야 합니다
+- 카카오 정책 위반 시 채널 차단 위험이 있습니다
+
+---
+
+## 운영 팁
+
+- `enabled: false`이면 API 호출 시 **503** 반환 — 운영 전 반드시 `true`로 변경
+- 채널 추가 친구가 아닌 번호로 발송하면 프로바이더에서 오류 반환
+- 솔라피(`solapi`) 권장 — SDK 지원 및 통합 메시징 편리
+
+---
+
+## 관련 문서
+
+- [Friendtalk Routes](../routes/friendtalk-routes.md)
+- [알림톡 가이드](alimtalk.md)
+- [설정 예제](../../configs-example/notification/friendtalk.json)
+- [템플릿 예제](../../templates/notification/friendtalk.json)

package/docs/plugins/holidays.md

@@ -0,0 +1,98 @@
+# 공휴일 동기화 플러그인
+
+공공데이터포털 공휴일 API에서 국가 공휴일을 주기적으로 동기화하고 조회하는 플러그인입니다.
+
+이 문서는 플러그인 개요/설정/운영 가이드를 다룹니다.  
+실제 라우트표, 호출 예제, 응답 예제는 [Holidays Routes](../routes/holidays-routes.md) 문서를 참고하세요.
+
+---
+
+## 목차
+
+- [개요](#개요)
+- [필수 환경변수](#필수-환경변수)
+- [설정](#설정)
+- [동기화 동작](#동기화-동작)
+- [운영 팁](#운영-팁)
+
+---
+
+## 개요
+
+- 서버 시작 시 즉시 1회 동기화 (누락 데이터 보완)
+- cron 스케줄에 따라 자동 재동기화
+- Entity Server의 `holiday` 엔티티에 데이터 저장
+- GET/단건 조회 및 수동 동기화 API 제공
+
+---
+
+## 필수 환경변수
+
+| 변수명            | 설명                      |
+| ----------------- | ------------------------- |
+| `HOLIDAY_API_KEY` | 공공데이터포털 API 인증키 |
+
+`.env` 파일에 추가:
+
+```
+HOLIDAY_API_KEY=your_api_key_here
+```
+
+> 공공데이터포털(data.go.kr) → [한국천문연구원\_특일 정보](https://www.data.go.kr/data/15012690/openapi.do) 에서 발급
+
+---
+
+## 설정
+
+`src/app/plugins/holidays/config.json`:
+
+```json
+{
+    "enabled": true,
+    "cron": "0 3 1 1,12 *",
+    "yearsAhead": 1,
+    "entity": "holiday"
+}
+```
+
+| 항목         | 설명                                              | 기본값           |
+| ------------ | ------------------------------------------------- | ---------------- |
+| `enabled`    | 플러그인 활성화 여부                              | `false`          |
+| `cron`       | 자동 동기화 스케줄 (5-필드 cron, Asia/Seoul 기준) | `"0 3 1 1,12 *"` |
+| `yearsAhead` | 현재 연도 기준 몇 년 앞까지 동기화할지            | `1`              |
+| `entity`     | Entity Server에서 사용하는 엔티티 이름            | `"holiday"`      |
+
+### cron 예시
+
+| cron 표현식    | 설명                               |
+| -------------- | ---------------------------------- |
+| `0 3 1 1,12 *` | 1월 1일·12월 1일 새벽 3시 (기본값) |
+| `0 2 1 * *`    | 매월 1일 새벽 2시                  |
+| `0 0 * * 0`    | 매주 일요일 자정                   |
+
+---
+
+## 동기화 동작
+
+1. **서버 시작 시**: `onReady` 훅에서 즉시 1회 동기화 실행
+2. **cron 스케줄**: 설정된 주기마다 자동 실행
+3. **수동 트리거**: `POST /api/v1/holidays/sync` API 호출
+
+동기화 대상 연도: 현재 연도 ~ `(현재 연도 + yearsAhead)`
+
+---
+
+## 운영 팁
+
+- `HOLIDAY_API_KEY`가 없으면 플러그인이 비활성화됩니다. 로그에 경고가 출력됩니다.
+- 공공 API 호출 실패 시 기존 데이터는 유지되며 에러 로그만 남습니다.
+- 연초(1월 1일)와 연말(12월 1일) 자동 갱신으로 다음 해 공휴일을 미리 확보합니다.
+- Entity Server의 `holiday` 엔티티 스키마가 없으면 동기화 시 에러가 발생합니다.
+
+---
+
+## 관련 문서
+
+- [Holidays Routes](../routes/holidays-routes.md)
+- [PG Guide](./pg.md)
+- [LLM Guide](./llm.md)