create-entity-app-server 0.0.3

package/docs/plugins/sms.md

@@ -0,0 +1,228 @@
+# SMS 가이드
+
+SMS/LMS/MMS 문자 발송 및 본인인증(인증번호) 기능에 대한 설정·운영 가이드입니다.
+
+이 문서는 플러그인의 개요/설정/운영 가이드를 중심으로 다룹니다.  
+실제 라우트표, 호출 예제, 응답 예제는 [SMS Routes](../routes/sms-routes.md) 문서를 참고하세요.
+
+---
+
+## 목차
+
+- [개요](#개요)
+- [프로바이더 비교](#프로바이더-비교)
+- [설정](#설정)
+- [발송 흐름](#발송-흐름)
+- [인증번호(본인인증)](#인증번호본인인증)
+- [엔티티 구조](#엔티티-구조)
+- [운영 팁](#운영-팁)
+
+---
+
+## 개요
+
+SMS 플러그인은 **DB 큐 패턴**으로 문자를 발송합니다. 클라이언트가 발송 요청을 하면
+`sms_log` 엔티티에 `pending` 상태로 저장 → 디스패치 루프가 주기적으로 조회 → 프로바이더 API 호출 → 결과에 따라 `sent`/`failed` 갱신.
+
+| 메시지 타입 | 설명                           |
+| ----------- | ------------------------------ |
+| SMS         | 80byte 이하 단문               |
+| LMS         | 80byte 초과 장문 (2,000byte)   |
+| MMS         | 이미지 첨부 멀티미디어 (300KB) |
+
+`auto_lms: true`(기본) 설정 시, 본문 바이트 수에 따라 자동으로 SMS/LMS 판정합니다.
+
+---
+
+## 프로바이더 비교
+
+| 항목      | **aligo**         | **solapi**            | **ppurio**             | **nhn_cloud**        | **aws_sns**          |
+| --------- | ----------------- | --------------------- | ---------------------- | -------------------- | -------------------- |
+| 홈페이지  | aligo.in          | solapi.com            | ppurio.com             | nhncloud.com         | aws.amazon.com/sns   |
+| SMS 단가  | ~9원              | ~10원                 | ~10원                  | ~9원                 | 종량(건당 ~$0.00645) |
+| 인증 방식 | API Key + User ID | API Key + HMAC-SHA256 | Account + Bearer Token | App Key + Secret Key | AWS Sig V4           |
+| LMS/MMS   | ✅                | ✅                    | ✅                     | ✅                   | ❌ (SMS만 지원)      |
+| 해외 발송 | ✅                | ✅                    | ✅                     | ✅                   | ✅ (글로벌)          |
+
+---
+
+## 설정
+
+플러그인 디렉토리에 위치한 `config.json`:
+
+```json
+{
+    "enabled": true,
+    "default": "aligo",
+    "sender": "${SMS_SENDER}",
+    "workers": 2,
+    "queue_size": 200,
+    "dispatch_interval_sec": 5,
+    "max_retries": 3,
+    "auto_lms": true,
+    "lms_threshold_bytes": 80,
+    "providers": {
+        "aligo": {
+            "driver": "aligo",
+            "api_key": "${ALIGO_API_KEY}",
+            "user_id": "${ALIGO_USER_ID}",
+            "sender": "${SMS_SENDER}"
+        }
+    },
+    "verification": {
+        "code_length": 6,
+        "ttl_sec": 180,
+        "max_attempts": 5,
+        "cooldown_sec": 60
+    }
+}
+```
+
+### 주요 설정 항목
+
+| 항목                    | 기본값 | 설명                             |
+| ----------------------- | ------ | -------------------------------- |
+| `enabled`               | `true` | 기능 활성화 여부                 |
+| `default`               | —      | 기본 프로바이더 이름 (key, 필수) |
+| `sender`                | —      | 글로벌 발신번호                  |
+| `workers`               | `2`    | 동시 발송 워커 수                |
+| `queue_size`            | `200`  | dispatch당 최대 claim 수         |
+| `dispatch_interval_sec` | `5`    | 디스패처 폴링 주기(초)           |
+| `max_retries`           | `3`    | 최대 재시도 횟수                 |
+| `auto_lms`              | `true` | 자동 LMS 판정 활성화             |
+| `lms_threshold_bytes`   | `80`   | LMS 전환 바이트 임계값           |
+
+### 인증번호 설정
+
+| 항목           | 기본값 | 설명                  |
+| -------------- | ------ | --------------------- |
+| `code_length`  | `6`    | 인증번호 자릿수       |
+| `ttl_sec`      | `180`  | 인증번호 유효시간(초) |
+| `max_attempts` | `5`    | 최대 인증 시도 횟수   |
+| `cooldown_sec` | `60`   | 재발송 대기시간(초)   |
+
+### 드라이버별 필수 필드
+
+| Driver      | 필수 필드                            |
+| ----------- | ------------------------------------ |
+| `aligo`     | `api_key`, `user_id`                 |
+| `solapi`    | `api_key`, `api_secret`              |
+| `ppurio`    | `account`, `api_key`                 |
+| `nhn_cloud` | `app_key`, `secret_key`              |
+| `aws_sns`   | `region`, `access_key`, `secret_key` |
+
+### 환경변수 치환
+
+설정 파일에서 `${VAR}` 패턴은 `process.env.VAR` 값으로 자동 치환됩니다.
+
+---
+
+## 발송 흐름
+
+```
+클라이언트 → POST /api/v1/sms/send
+                ↓
+         sms_log(pending) DB 저장
+                ↓
+         dispatch loop (N초 주기)
+                ↓
+         pending 조회 → processing 갱신
+                ↓
+         프로바이더 API 호출 (N workers 병렬)
+                ↓
+         sent / failed 상태 갱신
+```
+
+1. **enqueue**: `handleSend` → `SmsService.enqueueJob()` → `sms_log` 엔티티에 `pending` 저장
+2. **dispatch**: `setInterval`로 주기적 실행 → `claimPendingSmsLogs()` (pending → processing)
+3. **process**: 워커가 프로바이더 `send()` 호출 → 결과에 따라 `finalize()`
+4. **finalize**: `sent` 또는 `failed` 갱신 + 참조 `sms_msg` 상태 연동
+5. **stale recovery**: 서버 시작 시 `processing` 상태 로그를 `pending`으로 복구 (max_retries 초과 시 `failed`)
+
+---
+
+## 인증번호(본인인증)
+
+SMS 본인인증은 `verification` 설정이 존재할 때 활성화됩니다.
+
+### 흐름
+
+1. `POST /api/v1/sms/verification/send` → 이전 pending 만료 → 코드 생성 → SHA-256 해시 저장 → SMS 발송
+2. `POST /api/v1/sms/verification/verify` → pending 조회 → 만료/시도횟수 확인 → constant-time 비교
+
+### 보안
+
+- 인증번호는 **SHA-256 해시**로만 저장 (평문 미저장)
+- 검증 시 **constant-time comparison** (`timingSafeEqual`) 사용
+- 코드 생성은 `crypto.randomInt()` (암호학적 난수)
+- 불일치 시에만 시도 횟수 증가 (timing attack 방지)
+
+---
+
+## 엔티티 구조
+
+### sms_log
+
+| 필드              | 타입     | 설명                           |
+| ----------------- | -------- | ------------------------------ |
+| `seq`             | integer  | PK                             |
+| `status`          | string   | pending/processing/sent/failed |
+| `provider`        | string   | 프로바이더 driver              |
+| `sender`          | string   | 발신번호                       |
+| `receiver`        | string   | 수신번호                       |
+| `content`         | text     | 본문                           |
+| `subject`         | string   | 제목 (LMS/MMS)                 |
+| `msg_type`        | string   | sms/lms/mms                    |
+| `image_url`       | string   | MMS 이미지 URL                 |
+| `provider_msg_id` | string   | 프로바이더 메시지 ID           |
+| `error_message`   | text     | 실패 사유                      |
+| `retry_count`     | integer  | 재시도 횟수                    |
+| `sent_at`         | datetime | 발송 완료 시각                 |
+
+### sms_verification
+
+| 필드         | 타입     | 설명                     |
+| ------------ | -------- | ------------------------ |
+| `seq`        | integer  | PK                       |
+| `phone`      | string   | 전화번호                 |
+| `purpose`    | string   | 용도 (signup, reset 등)  |
+| `status`     | string   | pending/verified/expired |
+| `code_hash`  | string   | SHA-256 해시             |
+| `expires_at` | datetime | 만료 시각                |
+| `attempts`   | integer  | 시도 횟수                |
+
+---
+
+## 운영 팁
+
+### 발신번호 사전등록
+
+국내 SMS 서비스는 **발신번호 사전등록**이 필수입니다. 아래 각 프로바이더 콘솔에서 등록 후 `sender` 필드에 설정하세요.
+
+| 프로바이더 | 발신번호 등록 페이지                                              |
+| ---------- | ----------------------------------------------------------------- |
+| aligo      | https://smartsms.aligo.in/admin/sendnumber/sendnumber_manage.html |
+| solapi     | https://console.solapi.com/credentials                            |
+| ppurio     | https://www.ppurio.com/mypage/callbackList                        |
+| nhn_cloud  | https://console.nhncloud.com/SMS                                  |
+| aws_sns    | AWS Console → Amazon SNS → Origination numbers                    |
+
+### 프로바이더 fallback
+
+`providers` 객체에 여러 프로바이더를 등록하고, 발송 시 `provider` 필드로 교체 가능합니다. 기본은 `default` 프로바이더가 사용됩니다.
+
+### 모니터링
+
+- `sms_log` 엔티티에서 `status=failed` 필터로 실패 건 확인
+- 로그에서 `SMS:` 접두사로 필터링
+- stale recovery 로그: `SMS: reset N stale processing logs`
+
+### Graceful Shutdown
+
+서비스 종료 시 진행 중인 dispatch 작업이 완료될 때까지 대기합니다.
+
+---
+
+## 관련 문서
+
+- [SMS Routes](../routes/sms-routes.md) — API 라우트 레퍼런스

package/docs/plugins/taxinvoice.md

@@ -0,0 +1,197 @@
+# 세금계산서 가이드
+
+바로빌, 이세로, 팝빌, 스마트빌, 볼타 등을 통한 전자세금계산서 발급 가이드입니다.
+
+이 문서는 플러그인의 개요/설정/운영 가이드를 중심으로 다룹니다.  
+실제 라우트표, 호출 예제, 응답 예제는 [Tax Invoice Routes](../routes/tax-invoice-routes.md) 문서를 참고하세요.
+
+---
+
+## 목차
+
+- [개요](#개요)
+- [프로바이더 비교](#프로바이더-비교)
+- [설정](#설정)
+- [발급 흐름](#발급-흐름)
+- [API 레퍼런스](#api-레퍼런스)
+- [상태 흐름](#상태-흐름)
+- [국세청 전송](#국세청-전송)
+- [운영 팁](#운영-팁)
+
+---
+
+## 개요
+
+Gateway의 세금계산서 플러그인은 여러 세금계산서 발급 대행 프로바이더를 단일 API로 추상화합니다.
+
+- 즉시 발급 (등록 + 발행 일괄 처리)
+- 단계별 발급 (draft 저장 → 검토 → 발행)
+- 발행 취소
+- 국세청(NTS) 전송 상태 추적
+
+---
+
+## 프로바이더 비교
+
+| provider | driver     | 특징                              |
+| -------- | ---------- | --------------------------------- |
+| 바로빌   | `barobill` | 국내 점유율 1위, 다양한 연동 방식 |
+| 이지로   | `ezero`    | 이지로 전자세금계산서             |
+| 팝빌     | `popbill`  | API 문서 풍부, 중소기업 많이 사용 |
+| KT-NET   | `ktnet`    | KT-NET 세금계산서 서비스          |
+
+---
+
+## 설정
+
+`configs/plugins/tax-invoice.json`:
+
+```json
+{
+    "enabled": false,
+    "default": "barobill",
+    "providers": {
+        "barobill": {
+            "driver": "barobill",
+            "cert_key": "${TAXINVOICE_CERT_KEY}",
+            "corp_num": "${TAXINVOICE_CORP_NUM}",
+            "user_id": "${TAXINVOICE_USER_ID}",
+            "api_endpoint": "https://barobill.co.kr/TAPI/TaxInvoiceService.asmx"
+        },
+        "ezero": {
+            "driver": "ezero",
+            "cert_key": "${EZERO_CERT_KEY}",
+            "corp_num": "${EZERO_CORP_NUM}",
+            "user_id": "${EZERO_USER_ID}",
+            "api_endpoint": "https://www.ezero.co.kr/tax-invoice/api"
+        },
+        "popbill": {
+            "driver": "popbill",
+            "link_id": "${POPBILL_LINK_ID}",
+            "secret_key": "${POPBILL_SECRET_KEY}",
+            "corp_num": "${POPBILL_CORP_NUM}",
+            "api_url": "https://www.popbill.com"
+        },
+        "ktnet": {
+            "driver": "ktnet",
+            "cert_key": "${KTNET_CERT_KEY}",
+            "corp_num": "${KTNET_CORP_NUM}",
+            "user_id": "${KTNET_USER_ID}",
+            "api_endpoint": "https://www.b2b.kt.com/einvoice"
+        }
+    }
+}
+```
+
+### 환경변수 (.env)
+
+```env
+TAXINVOICE_CERT_KEY=your_cert_key
+TAXINVOICE_CORP_NUM=1234567890
+TAXINVOICE_USER_ID=your_user_id
+
+EZERO_CERT_KEY=your_cert_key
+EZERO_CORP_NUM=1234567890
+EZERO_USER_ID=your_user_id
+
+POPBILL_LINK_ID=your_link_id
+POPBILL_SECRET_KEY=your_secret_key
+POPBILL_CORP_NUM=1234567890
+
+KTNET_CERT_KEY=your_cert_key
+KTNET_CORP_NUM=1234567890
+KTNET_USER_ID=your_user_id
+```
+
+---
+
+## 발급 흐름
+
+### 즉시 발급 (추천)
+
+```
+POST /api/v1/taxinvoice     →  등록 + 발행 일괄 처리  →  issued
+```
+
+### 단계별 발급
+
+```
+1. POST /api/v1/taxinvoice/register    →  draft (임시 저장)
+2. POST /api/v1/taxinvoice/:seq/issue  →  issued (발행 처리)
+3. (선택) GET /api/v1/taxinvoice/:seq/state  →  NTS 전송 상태 확인
+```
+
+---
+
+## API 레퍼런스
+
+이 문서는 기능 소개/설정/운영 기준을 다룹니다.  
+라우트별 파라미터 표, 요청/응답 예제, 상태코드는 아래 라우트 문서를 기준으로 확인합니다.
+
+- 상세 API 레퍼런스: [Tax Invoice Routes](../routes/tax-invoice-routes.md)
+
+기본 경로: `/api/v1/taxinvoice`
+
+| 메서드 | 경로           | 설명                       |
+| ------ | -------------- | -------------------------- |
+| `POST` | `/`            | 즉시 발급 (등록+발행 일괄) |
+| `POST` | `/register`    | 세금계산서 등록 (draft)    |
+| `POST` | `/:seq/issue`  | 발행 처리                  |
+| `POST` | `/:seq/cancel` | 발행 취소                  |
+| `GET`  | `/:seq/state`  | 처리 상태 조회             |
+| `GET`  | `/:seq`        | 세금계산서 상세 조회       |
+
+---
+
+## 상태 흐름
+
+```
+draft
+  │
+  ├─ 발행 실패 → pre_issue_waiting (재시도 대기)
+  │
+  └─ 발행 성공 → issued
+                   │
+                   └─ 국세청 전송 대기 → accepted
+                                          │
+                                          └─ 전송 완료 (nts_state: completed)
+```
+
+| status              | 설명                |
+| ------------------- | ------------------- |
+| `draft`             | 임시 저장           |
+| `pre_issue_waiting` | 발행 재시도 대기 중 |
+| `issued`            | 발행 완료           |
+| `cancelled`         | 취소됨              |
+
+| nts_state   | 설명                 |
+| ----------- | -------------------- |
+| `pending`   | 국세청 전송 전       |
+| `accepted`  | 국세청 수신 완료     |
+| `completed` | 국세청 처리 완료     |
+| `rejected`  | 국세청에서 오류 반려 |
+
+---
+
+## 국세청 전송
+
+- 발행된 세금계산서는 **익일 오전까지** 국세청에 자동 전송됩니다.
+- `nts_state: rejected` 시 사유를 확인 후 수정 재발행 필요합니다.
+- 재전송은 프로바이더 어드민 또는 `/state` 폴링으로 확인 가능합니다.
+
+---
+
+## 운영 팁
+
+- 발행 전 `register`로 초안 저장 후 담당자 검토 → `issue` 권장 (오류 방지)
+- `supply_value + tax_value = total_value` 를 반드시 확인 (검증 오류 가장 많음)
+- 테스트 환경에서는 각 프로바이더의 샌드박스 API URL 사용
+- 발행 취소는 국세청 전송 전에만 가능 → 이후에는 수정세금계산서 발행 필요
+
+---
+
+## 관련 문서
+
+- [Tax Invoice Routes](../routes/tax-invoice-routes.md)
+- [설정 예제](../../src/app/plugins/taxinvoice/config.example.json)
+- [Entity Server 세금계산서 가이드](../../../docs/plugins/tax-invoice-guide.md)

package/docs/routes/README.md

@@ -0,0 +1,247 @@
+# 앱서버 담당 엔드포인트 전체 목록
+
+> **라우트 우선순위**: `plugins/*/routes.ts` 및 `routes/*/route.ts`에 등록된 경로는
+> Go 서버 패스스루보다 **항상 먼저 처리**됩니다.
+> Go 서버가 제공하는 API 경로와 동일한 경로를 앱 서버에 정의하면 앱 서버가 우선 처리합니다.
+> 자세한 내용: [라우트 추가 가이드 §6](how-to-create.md#6-go-서버-패스스루-오버라이드)
+
+---
+
+## 계정
+
+> 상세: [account-routes.md](account-routes.md)
+
+| 앱서버 경로                     | 설명                                               |
+| ------------------------------- | -------------------------------------------------- |
+| `POST /api/v1/account/register` | 회원가입 + 이메일 인증 발송                        |
+| `POST /api/v1/account/withdraw` | 이메일 확보 → Go 익명화 내부 호출 → 완료 메일 발송 |
+
+---
+
+## 2FA (TOTP)
+
+> 상세: [account-routes.md](account-routes.md)
+
+| 앱서버 경로                                    | 설명                 |
+| ---------------------------------------------- | -------------------- |
+| `POST /api/v1/account/2fa/setup`               | TOTP 설정            |
+| `POST /api/v1/account/2fa/setup/verify`        | TOTP 활성화 확인     |
+| `DELETE /api/v1/account/2fa`                   | 2FA 비활성화         |
+| `GET /api/v1/account/2fa/status`               | 2FA 상태 조회        |
+| `POST /api/v1/account/2fa/verify`              | TOTP 검증 (2단계)    |
+| `POST /api/v1/account/2fa/recovery`            | 리커버리 코드 로그인 |
+| `POST /api/v1/account/2fa/recovery/regenerate` | 리커버리 코드 재생성 |
+
+---
+
+## OAuth 소셜 로그인
+
+> 상세: [account-routes.md](account-routes.md)
+
+| 앱서버 경로                                 | 설명                  |
+| ------------------------------------------- | --------------------- |
+| `GET /api/v1/oauth/:provider`               | OAuth 리다이렉트      |
+| `GET/POST /api/v1/oauth/:provider/callback` | OAuth 콜백 → JWT 발급 |
+
+---
+
+## OAuth 계정 연동
+
+> 상세: [account-routes.md](account-routes.md)
+
+| 앱서버 경로                                    | 설명                   |
+| ---------------------------------------------- | ---------------------- |
+| `POST /api/v1/account/oauth/link`              | OAuth 프로바이더 연동  |
+| `DELETE /api/v1/account/oauth/link/:provider`  | OAuth 연동 해제        |
+| `GET /api/v1/account/oauth/providers`          | 연동된 프로바이더 목록 |
+| `POST /api/v1/account/oauth/refresh/:provider` | OAuth 토큰 갱신        |
+
+---
+
+## 이메일 인증
+
+> 상세: [email-verification.md](email-verification.md)
+
+| 앱서버 경로                         | 설명                |
+| ----------------------------------- | ------------------- |
+| `POST /api/v1/email-verify/send`    | 인증 코드/링크 발송 |
+| `POST /api/v1/email-verify/confirm` | 인증 코드 확인      |
+| `GET /api/v1/email-verify/activate` | 링크 클릭 인증      |
+| `GET /api/v1/email-verify/status`   | 인증 상태 조회      |
+| `POST /api/v1/email-verify/change`  | 이메일 변경         |
+
+---
+
+## 비밀번호 재설정
+
+> 상세: [password-reset.md](password-reset.md)
+
+| 앱서버 경로                           | 설명             |
+| ------------------------------------- | ---------------- |
+| `POST /api/v1/password-reset/request` | 재설정 메일 발송 |
+| `GET /api/v1/password-reset/validate` | 토큰 유효성 확인 |
+| `POST /api/v1/password-reset/verify`  | 새 비밀번호 설정 |
+
+---
+
+## Push 알림
+
+> 상세: [push-routes.md](push-routes.md) · 설정/운영: [../plugins/push.md](../plugins/push.md)
+
+| 앱서버 경로                       | 설명                          |
+| --------------------------------- | ----------------------------- |
+| `POST /api/v1/push/device`        | 디바이스 토큰 등록/갱신       |
+| `DELETE /api/v1/push/device/:seq` | 디바이스 푸시 수신 비활성화   |
+| `POST /api/v1/push/send`          | Push 발송 (단일 계정)         |
+| `POST /api/v1/push/broadcast`     | Push 브로드캐스트 (다중 계정) |
+| `GET /api/v1/push/status/:seq`    | 발송 상태 조회 안내           |
+
+---
+
+## SMS
+
+> 상세: [sms-routes.md](sms-routes.md) · 설정/운영: [../plugins/sms.md](../plugins/sms.md)
+
+| Method | 앱서버 경로                       | 설명           |
+| ------ | --------------------------------- | -------------- |
+| POST   | `/api/v1/sms/send`                | SMS 발송       |
+| GET    | `/api/v1/sms/status/:seq`         | 발송 상태 조회 |
+| POST   | `/api/v1/sms/verification/send`   | 인증번호 발송  |
+| POST   | `/api/v1/sms/verification/verify` | 인증번호 검증  |
+
+---
+
+## SMTP 메일
+
+> 상세: [smtp-routes.md](smtp-routes.md) · 설정/운영: [../plugins/smtp.md](../plugins/smtp.md)
+
+| Method | 앱서버 경로                | 설명                            |
+| ------ | -------------------------- | ------------------------------- |
+| POST   | `/api/v1/smtp/send`        | 로컬 템플릿 렌더링 후 메일 발송 |
+| GET    | `/api/v1/smtp/status/:seq` | 발송 상태 조회                  |
+
+> 위 경로 외의 `/api/v1/smtp/*` 는 Go 서버로 패스스루됩니다.
+
+---
+
+## 알림톡 (Alimtalk)
+
+> 상세: [alimtalk-routes.md](alimtalk-routes.md) · 설정/운영: [../plugins/alimtalk.md](../plugins/alimtalk.md)
+
+| Method | 앱서버 경로                          | 설명             |
+| ------ | ------------------------------------ | ---------------- |
+| POST   | `/api/v1/alimtalk/send`              | 알림톡 발송      |
+| GET    | `/api/v1/alimtalk/status/:seq`       | 발송 상태 조회   |
+| GET    | `/api/v1/alimtalk/templates`         | 템플릿 목록 조회 |
+| POST   | `/api/v1/alimtalk/webhook/:provider` | 공급사 웹훅 수신 |
+
+---
+
+## 친구톡 (Friendtalk)
+
+> 상세: [friendtalk-routes.md](friendtalk-routes.md) · 설정/운영: [../plugins/friendtalk.md](../plugins/friendtalk.md)
+
+| Method | 앱서버 경로               | 설명        |
+| ------ | ------------------------- | ----------- |
+| POST   | `/api/v1/friendtalk/send` | 친구톡 발송 |
+
+---
+
+## PG 결제
+
+> 상세: [pg-routes.md](pg-routes.md) · 설정/운영: [../plugins/pg.md](../plugins/pg.md)
+
+| Method | 앱서버 경로                         | 설명                      |
+| ------ | ----------------------------------- | ------------------------- |
+| POST   | `/api/v1/pg/orders`                 | 주문 생성                 |
+| GET    | `/api/v1/pg/orders/:orderId`        | 주문 단건 조회            |
+| POST   | `/api/v1/pg/confirm`                | 결제 승인                 |
+| POST   | `/api/v1/pg/orders/:orderId/cancel` | 결제 취소                 |
+| POST   | `/api/v1/pg/orders/:orderId/sync`   | 결제 상태 동기화          |
+| POST   | `/api/v1/pg/webhook`                | PG 웹훅 수신              |
+| GET    | `/api/v1/pg/config`                 | 클라이언트 결제 설정 조회 |
+
+---
+
+## 세금계산서 (Tax Invoice)
+
+> 상세: [tax-invoice-routes.md](tax-invoice-routes.md) · 설정/운영: [../plugins/taxinvoice.md](../plugins/taxinvoice.md)
+
+| Method | 앱서버 경로                      | 설명                              |
+| ------ | -------------------------------- | --------------------------------- |
+| POST   | `/api/v1/taxinvoice`             | 세금계산서 등록/발행 요청(레거시) |
+| POST   | `/api/v1/taxinvoice/register`    | 세금계산서 등록                   |
+| POST   | `/api/v1/taxinvoice/:seq/issue`  | 등록 건 발행                      |
+| POST   | `/api/v1/taxinvoice/:seq/cancel` | 발행 취소                         |
+| GET    | `/api/v1/taxinvoice/:seq/state`  | 발행 상태 조회                    |
+| GET    | `/api/v1/taxinvoice/:seq`        | 상세 조회                         |
+
+---
+
+## LLM
+
+> 상세: [llm-routes.md](llm-routes.md) · 설정/운영: [../plugins/llm.md](../plugins/llm.md)
+
+| Method | 앱서버 경로                               | 설명                            |
+| ------ | ----------------------------------------- | ------------------------------- |
+| POST   | `/api/v1/llm/chat`                        | 일반 채팅 응답 생성             |
+| POST   | `/api/v1/llm/chat/stream`                 | 스트리밍 채팅 응답              |
+| POST   | `/api/v1/llm/conversations`               | 대화 세션 생성                  |
+| POST   | `/api/v1/llm/conversations/:seq/messages` | 대화 메시지 전송                |
+| GET    | `/api/v1/llm/conversations`               | 대화 세션 목록                  |
+| GET    | `/api/v1/llm/conversations/:seq`          | 대화 세션 상세                  |
+| PATCH  | `/api/v1/llm/conversations/:seq`          | 대화 세션 정보 수정             |
+| DELETE | `/api/v1/llm/conversations/:seq`          | 대화 세션 삭제                  |
+| POST   | `/api/v1/llm/rag/documents`               | RAG 문서 업로드                 |
+| GET    | `/api/v1/llm/rag/documents`               | RAG 문서 목록                   |
+| DELETE | `/api/v1/llm/rag/documents/:id`           | RAG 문서 삭제                   |
+| POST   | `/api/v1/llm/rag/search`                  | RAG 검색                        |
+| POST   | `/api/v1/llm/rag/chat`                    | RAG 기반 채팅                   |
+| POST   | `/api/v1/llm/rag/chat/stream`             | RAG 스트리밍 채팅               |
+| POST   | `/api/v1/llm/rag/rebuild-index`           | RAG 인덱스 재구성               |
+| GET    | `/api/v1/llm/providers`                   | 사용 가능한 LLM 프로바이더 조회 |
+| GET    | `/api/v1/llm/usage`                       | LLM 사용량 상세                 |
+| GET    | `/api/v1/llm/usage/summary`               | LLM 사용량 요약                 |
+| GET    | `/api/v1/llm/cache/stats`                 | 캐시 통계 조회                  |
+
+---
+
+## OCR
+
+> 상세: [ocr-routes.md](ocr-routes.md) · 설정/운영: [../plugins/ocr.md](../plugins/ocr.md)
+
+| Method | 앱서버 경로                    | 설명                 |
+| ------ | ------------------------------ | -------------------- |
+| POST   | `/api/v1/ocr/recognize`        | OCR 동기 인식        |
+| POST   | `/api/v1/ocr/recognize/async`  | OCR 비동기 인식      |
+| POST   | `/api/v1/ocr/:docType`         | 문서 유형별 OCR 인식 |
+| GET    | `/api/v1/ocr/results`          | OCR 결과 목록 조회   |
+| GET    | `/api/v1/ocr/results/:id`      | OCR 결과 단건 조회   |
+| GET    | `/api/v1/ocr/results/:id/text` | OCR 텍스트 추출 조회 |
+| DELETE | `/api/v1/ocr/results/:id`      | OCR 결과 삭제        |
+| GET    | `/api/v1/ocr/quota`            | OCR 사용량/쿼터 조회 |
+
+---
+
+## 본인인증 (Identity)
+
+> 상세: [identity-routes.md](identity-routes.md) · 설정/운영: [../plugins/identity.md](../plugins/identity.md)
+
+| Method | 앱서버 경로                           | 설명             |
+| ------ | ------------------------------------- | ---------------- |
+| POST   | `/api/v1/identity/request`            | 인증 요청 생성   |
+| POST   | `/api/v1/identity/callback`           | 중계사 콜백 수신 |
+| GET    | `/api/v1/identity/result/:request_id` | 인증 결과 조회   |
+| POST   | `/api/v1/identity/verify-ci`          | CI 중복 확인     |
+
+---
+
+## 공휴일 (Holidays)
+
+> 상세: [holidays-routes.md](holidays-routes.md) · 설정/운영: [../plugins/holidays.md](../plugins/holidays.md)
+
+| Method | 앱서버 경로                 | 설명                        |
+| ------ | --------------------------- | --------------------------- |
+| GET    | `/api/v1/holidays`          | 공휴일 목록 조회            |
+| GET    | `/api/v1/holidays/:locdate` | 특정 날짜 공휴일 단건 조회  |
+| POST   | `/api/v1/holidays/sync`     | 수동 동기화 트리거 (관리자) |