create-entity-app-server 0.0.3

package/docs/plugins/oauth.md

@@ -0,0 +1,121 @@
+# OAuth 2.0 소셜 로그인 플러그인
+
+Google·GitHub·Kakao·Naver·Apple 소셜 로그인과 기존 계정 연동을 처리합니다.
+
+---
+
+## 목차
+
+- [개요](#개요)
+- [설정](#설정)
+- [로그인 흐름](#로그인-흐름)
+- [API 레퍼런스](#api-레퍼런스)
+- [엔티티 구조](#엔티티-구조)
+
+---
+
+## 개요
+
+```
+클라이언트 → GET /api/v1/oauth/:provider
+                 │
+                 ▼ (302 Redirect)
+         프로바이더 인증 화면
+                 │
+                 ▼ (code 반환)
+GET /api/v1/oauth/:provider/callback
+    └─ 토큰 교환 → 사용자 정보 조회 → account_oauth upsert → JWT 발급
+```
+
+지원 프로바이더: `google` · `github` · `kakao` · `naver` · `apple`
+
+---
+
+## 설정
+
+플러그인 활성화와 프로바이더 설정은 `app/plugins/oauth/config.json`에서 함께 관리합니다:
+
+```json
+{
+    "enabled": true,
+    "state_secret": "${OAUTH_STATE_SECRET}",
+    "providers": [
+        {
+            "driver": "google",
+            "client_id": "...",
+            "client_secret": "...",
+            "redirect_url": "/v1/oauth/google/callback",
+            "scopes": ["openid", "email", "profile"]
+        }
+    ]
+}
+```
+
+> Apple Sign-In 콜백은 Apple이 `POST`로 전송하므로  
+> Go 서버 CORS·CSRF 설정의 `skip_paths`에 `/api/v1/oauth/apple/callback`을 추가해야 합니다.
+
+---
+
+## 로그인 흐름
+
+### 신규 소셜 로그인
+
+```
+1. 클라이언트: GET /api/v1/oauth/google → 302 → Google 인증 화면
+2. Google: GET /api/v1/oauth/google/callback?code=...
+3. 서버: code 교환 → access_token → 사용자 정보 조회
+4. account_oauth upsert (provider=google, provider_id=...)
+5. account 없으면 자동 생성, 있으면 연결
+6. JWT 발급 → 응답
+```
+
+### 계정 연동 (기존 로그인 계정에 소셜 추가)
+
+```
+POST /api/v1/account/oauth/link { provider, code } (JWT 필요)
+    → account_oauth 추가
+```
+
+---
+
+## API 레퍼런스
+
+### 소셜 로그인
+
+| 메소드         | 경로                               | 설명                                |
+| -------------- | ---------------------------------- | ----------------------------------- |
+| `GET`          | `/api/v1/oauth/:provider`          | 프로바이더 인증 화면으로 리다이렉트 |
+| `GET` / `POST` | `/api/v1/oauth/:provider/callback` | 콜백 처리 + JWT 발급                |
+
+### 계정 OAuth 연동 관리
+
+| 메소드   | 경로                                      | 인증 | 설명                   |
+| -------- | ----------------------------------------- | ---- | ---------------------- |
+| `POST`   | `/api/v1/account/oauth/link`              | JWT  | 프로바이더 연동 추가   |
+| `DELETE` | `/api/v1/account/oauth/link/:provider`    | JWT  | 연동 해제              |
+| `GET`    | `/api/v1/account/oauth/providers`         | JWT  | 연동된 프로바이더 목록 |
+| `POST`   | `/api/v1/account/oauth/refresh/:provider` | JWT  | 프로바이더 토큰 갱신   |
+
+---
+
+## 엔티티 구조
+
+### account_oauth
+
+소셜 계정 연결 정보를 저장합니다 (`plugins/oauth/entities/account_oauth.json`으로 자동 생성).
+
+| 필드               | 타입         | 설명                                      |
+| ------------------ | ------------ | ----------------------------------------- |
+| `account_seq`      | integer      | 연결된 account seq                        |
+| `provider`         | enum         | `google` `github` `kakao` `naver` `apple` |
+| `provider_id`      | varchar(256) | 프로바이더 고유 사용자 ID                 |
+| `status`           | enum         | `linked` `unlinked`                       |
+| `email`            | varchar(320) | 프로바이더에서 제공한 이메일              |
+| `name`             | varchar(256) | 프로바이더 표시 이름                      |
+| `profile_image`    | text         | 프로필 이미지 URL                         |
+| `access_token`     | text         | 프로바이더 Access Token                   |
+| `refresh_token`    | text         | 프로바이더 Refresh Token                  |
+| `token_expires_at` | datetime     | Access Token 만료 시각                    |
+| `raw`              | json         | 프로바이더 원본 응답 (디버깅용)           |
+| `linked_at`        | datetime     | 연동 시각                                 |
+| `unlinked_at`      | datetime     | 연동 해제 시각                            |

package/docs/plugins/ocr.md

@@ -0,0 +1,168 @@
+# OCR(광학 문자 인식) 가이드
+
+AWS Textract, Azure, Google Vision, NAVER Clova, Tesseract, Upstage 등을 통한 문서 인식 가이드입니다.
+
+이 문서는 플러그인의 개요/설정/운영 가이드를 중심으로 다룹니다.  
+실제 라우트표, 호출 예제, 응답 예제는 [OCR Routes](../routes/ocr-routes.md) 문서를 참고하세요.
+
+---
+
+## 목차
+
+- [개요](#개요)
+- [프로바이더 비교](#프로바이더-비교)
+- [설정](#설정)
+- [API 레퍼런스](#api-레퍼런스)
+- [지원 문서 타입](#지원-문서-타입)
+- [비동기 처리](#비동기-처리)
+- [운영 팁](#운영-팁)
+
+---
+
+## 개요
+
+Gateway의 OCR 플러그인은 여러 OCR 프로바이더를 단일 API로 추상화합니다.
+
+- 이미지/PDF → 텍스트 추출
+- 동기 및 비동기(polling) 인식
+- 신분증, 운전면허증, 사업자등록증 등 문서 타입별 구조화 추출
+- OCR 결과 저장 및 조회
+
+---
+
+## 프로바이더 비교
+
+| provider                    | driver         | 특징                                  |
+| --------------------------- | -------------- | ------------------------------------- |
+| AWS Textract                | `aws_textract` | 테이블/폼 구조 추출 우수, 한국어 지원 |
+| Azure Document Intelligence | `azure`        | Form Recognizer 기반, 정형 문서 강점  |
+| Google Vision               | `google`       | 범용 OCR, 다국어 지원 우수            |
+| NAVER Clova OCR             | `naver`        | 한국어 최적화, 신분증/영수증 특화     |
+| Tesseract                   | `tesseract`    | 오픈소스, 자체 호스팅 가능, 무료      |
+| Upstage Document AI         | `upstage`      | 한국어 문서 특화, 고정밀도            |
+
+---
+
+## 설정
+
+`configs/plugins/ocr.json`:
+
+```json
+{
+    "enabled": false,
+    "default_provider": "naver",
+    "providers": {
+        "google": {
+            "driver": "google",
+            "api_key": "${OCR_GOOGLE_API_KEY}"
+        },
+        "naver": {
+            "driver": "naver",
+            "api_key": "${OCR_NAVER_SECRET}",
+            "endpoint": "${OCR_NAVER_INVOKE_URL}"
+        },
+        "aws_textract": {
+            "driver": "aws_textract",
+            "api_key": "${OCR_AWS_ACCESS_KEY}",
+            "api_secret": "${OCR_AWS_SECRET_KEY}",
+            "region": "${OCR_AWS_REGION}"
+        },
+        "azure": {
+            "driver": "azure",
+            "api_key": "${OCR_AZURE_KEY}",
+            "endpoint": "${OCR_AZURE_ENDPOINT}"
+        },
+        "upstage": {
+            "driver": "upstage",
+            "api_key": "${OCR_UPSTAGE_API_KEY}"
+        },
+        "tesseract": {
+            "driver": "tesseract"
+        }
+    }
+}
+```
+
+---
+
+## API 레퍼런스
+
+이 문서는 기능 소개/설정/운영 기준을 다룹니다.  
+라우트별 파라미터 표, 요청/응답 예제, 상태코드는 아래 라우트 문서를 기준으로 확인합니다.
+
+- 상세 API 레퍼런스: [OCR Routes](../routes/ocr-routes.md)
+
+기본 경로: `/api/v1/ocr`
+
+| 메서드   | 경로                | 설명                |
+| -------- | ------------------- | ------------------- |
+| `POST`   | `/recognize`        | 동기 OCR 인식       |
+| `POST`   | `/recognize/async`  | 비동기 OCR 인식     |
+| `POST`   | `/:docType`         | 문서 타입 지정 인식 |
+| `GET`    | `/results`          | 결과 목록 조회      |
+| `GET`    | `/results/:id`      | 결과 상세 조회      |
+| `GET`    | `/results/:id/text` | 인식 텍스트만 조회  |
+| `DELETE` | `/results/:id`      | 결과 삭제           |
+| `GET`    | `/quota`            | 사용량 한도 조회    |
+
+---
+
+## 지원 문서 타입
+
+| docType          | 설명         | 주요 추출 항목             |
+| ---------------- | ------------ | -------------------------- |
+| `id_card`        | 주민등록증   | 이름, 주민번호, 주소       |
+| `driver_license` | 운전면허증   | 이름, 면허번호, 생년월일   |
+| `business_reg`   | 사업자등록증 | 사업자번호, 상호, 대표자명 |
+| `career_cert`    | 경력증명서   | 소속, 직위, 재직기간       |
+| `facility_card`  | 시설관리카드 | 시설명, 주소, 관리번호     |
+| `invoice`        | 청구서/송장  | 발행일, 금액, 품목         |
+| `namecard`       | 명함         | 이름, 회사, 연락처         |
+| `receipt`        | 영수증       | 가맹점, 결제금액, 일시     |
+
+---
+
+## 비동기 처리
+
+```
+1. POST /recognize/async   →  { job_id: "xxx", status: "pending" }
+2. GET  /results/xxx       →  { status: "processing" }  (폴링)
+3. GET  /results/xxx       →  { status: "done", text: "...", structured: {...} }
+```
+
+폴링 권장 간격: 1~2초, 최대 대기 시간: 30초
+
+---
+
+## 결과 텍스트만 가져오기
+
+```
+GET /api/v1/ocr/results/job_abc123/text
+```
+
+```json
+{
+    "id": "job_abc123",
+    "text": "홍길동\n서울특별시 ..."
+}
+```
+
+---
+
+## 운영 팁
+
+- 한국 신분증/영수증 → **NAVER Clova** 또는 **Upstage** 권장
+- 비용 절감이 필요한 경우 **Tesseract** 자체 호스팅 활용
+- `docType` 지정 시 프로바이더가 해당 문서에 최적화된 추출 수행
+- 비동기 API는 PDF 다페이지 처리 시 유용
+- 결과는 DB에 저장되므로 `/results` API로 이력 조회 가능
+
+---
+
+## 관련 문서
+
+- [OCR Routes](../routes/ocr-routes.md)
+- [설정 예제](../../src/app/plugins/ocr/config.example.json)
+- [OCR 추출 템플릿](../../templates/ocr/)
+- [OCR 프롬프트](../../templates/ocr/prompts/)
+- [Entity Server OCR 가이드](../../../docs/plugins/ocr-guide.md)

package/docs/plugins/pg.md

@@ -0,0 +1,226 @@
+# PG(결제) 가이드
+
+토스페이먼츠, KCP, 이니시스, 카카오페이, 페이레터, PayPal 등 다양한 PG사를 통한 결제 처리 가이드입니다.
+
+이 문서는 플러그인의 개요/설정/운영 가이드를 중심으로 다룹니다.  
+실제 라우트표, 호출 예제, 응답 예제는 [PG Routes](../routes/pg-routes.md) 문서를 참고하세요.
+
+---
+
+## 목차
+
+- [개요](#개요)
+- [프로바이더 비교](#프로바이더-비교)
+- [설정](#설정)
+- [결제 흐름](#결제-흐름)
+- [API 레퍼런스](#api-레퍼런스)
+- [웹훅 처리](#웹훅-처리)
+- [운영 팁](#운영-팁)
+
+---
+
+## 개요
+
+Gateway의 PG 플러그인은 여러 결제 대행사를 단일 API로 추상화합니다.
+
+- 주문 생성 → 결제창 → 승인까지 일관된 흐름
+- 전체/부분 취소
+- PG사 웹훅 수신·검증
+- 클라이언트 SDK 설정 제공
+
+---
+
+## 프로바이더 비교
+
+| provider       | driver          | 특징                        |
+| -------------- | --------------- | --------------------------- |
+| 토스페이먼츠   | `toss_payments` | 국내 대표 PG, 간편결제 통합 |
+| KCP            | `kcp`           | 기업향, 에스크로 지원       |
+| KG이니시스     | `inicis`        | 다양한 결제 수단, 해외결제  |
+| 다날           | `danal`         | 휴대폰 소액결제 특화        |
+| 헥토파이낸셜   | `hecto`         | 계좌이체/가상계좌 강점      |
+| 카카오페이     | `kakaopay`      | 카카오 간편결제             |
+| 네이버페이     | `naverpay`      | 네이버 간편결제             |
+| 나이스페이먼츠 | `nice_payments` | 나이스 간편결제             |
+| 페이코         | `payco`         | NHN 간편결제                |
+| 와나           | `wanna`         | B2B 정산 특화               |
+| 페이레터       | `payletter`     | 게임·콘텐츠 결제 특화       |
+| PayPal         | `paypal`        | 글로벌 결제, 해외 고객 지원 |
+
+---
+
+## 설정
+
+`configs/plugins/pg.json`:
+
+```json
+{
+    "enabled": false,
+    "default": "toss_payments",
+    "providers": {
+        "toss_payments": {
+            "driver": "toss_payments",
+            "client_key": "${TOSS_CLIENT_KEY}",
+            "secret_key": "${TOSS_SECRET_KEY}",
+            "api_url": "https://api.tosspayments.com",
+            "api_version": "2024-06-01"
+        },
+        "kakaopay": {
+            "driver": "kakaopay",
+            "admin_key": "${KAKAO_PAY_ADMIN_KEY}",
+            "cid": "${KAKAO_PAY_CID}",
+            "api_url": "https://kapi.kakao.com"
+        },
+        "nice_payments": {
+            "driver": "nice_payments",
+            "client_key": "${NICE_CLIENT_KEY}",
+            "secret_key": "${NICE_SECRET_KEY}",
+            "api_url": "https://api.nicepay.co.kr"
+        },
+        "inicis": {
+            "driver": "inicis",
+            "mid": "${INICIS_MID}",
+            "sign_key": "${INICIS_SIGN_KEY}",
+            "iv": "${INICIS_IV}",
+            "api_url": "https://iniapi.inicis.com"
+        },
+        "naverpay": {
+            "driver": "naverpay",
+            "partner_id": "${NAVER_PAY_PARTNER_ID}",
+            "client_id": "${NAVER_PAY_CLIENT_ID}",
+            "client_secret": "${NAVER_PAY_CLIENT_SECRET}",
+            "chain_id": "${NAVER_PAY_CHAIN_ID}",
+            "api_url": "https://pay.naver.com"
+        },
+        "payco": {
+            "driver": "payco",
+            "partner_id": "${PAYCO_PARTNER_ID}",
+            "partner_secret": "${PAYCO_PARTNER_SECRET}",
+            "api_url": "https://apis.payco.com"
+        },
+        "payletter": {
+            "driver": "payletter",
+            "client_id": "${PAYLETTER_CLIENT_ID}",
+            "api_key": "${PAYLETTER_API_KEY}",
+            "api_key_search": "${PAYLETTER_API_KEY_SEARCH}",
+            "api_url": "https://pgapi.payletter.com"
+        },
+        "paypal": {
+            "driver": "paypal",
+            "client_id": "${PAYPAL_CLIENT_ID}",
+            "secret_key": "${PAYPAL_CLIENT_SECRET}",
+            "api_url": "https://api-m.sandbox.paypal.com",
+            "webhook_secret": "${PAYPAL_WEBHOOK_ID}"
+        }
+    }
+}
+```
+
+### 환경변수 (.env)
+
+```env
+# 토스페이먼츠
+TOSS_CLIENT_KEY=test_ck_...
+TOSS_SECRET_KEY=test_sk_...
+
+# 카카오페이
+KAKAO_PAY_ADMIN_KEY=...
+KAKAO_PAY_CID=TC0ONETIME
+
+# 페이레터
+PAYLETTER_CLIENT_ID=your_client_id
+PAYLETTER_API_KEY=payment_api_key
+PAYLETTER_API_KEY_SEARCH=search_api_key
+
+# PayPal
+PAYPAL_CLIENT_ID=AXxx...
+PAYPAL_CLIENT_SECRET=EXxx...
+PAYPAL_WEBHOOK_ID=WEBHOOK_ID_FROM_PAYPAL_DASHBOARD
+```
+
+---
+
+## 결제 흐름
+
+```
+1. POST /api/v1/pg/orders         →  주문 생성 (order_id 발급)
+2. 클라이언트에서 PG 결제창 호출    →  사용자 결제 진행
+3. POST /api/v1/pg/confirm         →  결제 승인 (payment_key + order_id + amount)
+4. 결제 완료                       →  order status: paid
+```
+
+> 취소 시: `POST /api/v1/pg/orders/:orderId/cancel`
+
+---
+
+## API 레퍼런스
+
+이 문서는 기능 소개/설정/운영 기준을 다룹니다.  
+라우트별 파라미터 표, 요청/응답 예제, 상태코드는 아래 라우트 문서를 기준으로 확인합니다.
+
+- 상세 API 레퍼런스: [PG Routes](../routes/pg-routes.md)
+
+기본 경로: `/api/v1/pg`
+
+| 메서드 | 경로                      | 설명                     |
+| ------ | ------------------------- | ------------------------ |
+| `POST` | `/orders`                 | 주문 생성                |
+| `GET`  | `/orders/:orderId`        | 주문 조회                |
+| `POST` | `/confirm`                | 결제 승인                |
+| `POST` | `/orders/:orderId/cancel` | 결제 취소                |
+| `POST` | `/orders/:orderId/sync`   | PG사와 상태 동기화       |
+| `POST` | `/webhook`                | PG사 웹훅 수신           |
+| `GET`  | `/config`                 | 클라이언트 SDK 설정 조회 |
+
+---
+
+## 웹훅 처리
+
+PG사에서 결제 이벤트를 서버로 전송합니다.
+
+```
+POST /api/v1/pg/webhook
+```
+
+게이트웨이는 웹훅 서명을 검증한 후 `pg_webhook_log` 테이블에 기록합니다.
+
+### 페이레터 웹훅 서명 검증
+
+```
+SHA256(user_id + amount + tid + api_key).toUpperCase()
+```
+
+서명이 일치하지 않으면 `400` 오류를 반환합니다.
+
+### PayPal 웹훅 서명 검증
+
+PayPal Webhook Signature 검증 API를 사용합니다.  
+`webhook_secret` 설정값에 **PayPal 대시보드에서 발급한 Webhook ID**를 입력해야 합니다.
+
+요청 헤더에서 아래 값을 추출한 뒤 `|` 구분자로 합쳐 `signature` 파라미터로 전달합니다:
+
+```
+PAYPAL-AUTH-ALGO|PAYPAL-CERT-URL|PAYPAL-TRANSMISSION-ID|PAYPAL-TRANSMISSION-SIG|PAYPAL-TRANSMISSION-TIME
+```
+
+`webhook_secret` 미설정 시 검증을 건너뜁니다 (개발 환경용).
+
+---
+
+## 운영 팁
+
+- 결제 금액 불일치(`amount mismatch`) 방지를 위해 `confirm` 시 서버 측 금액을 재검증
+- 웹훅 엔드포인트는 PG사 어드민에 등록 필수 (방화벽 허용 포함)
+- `/orders/:orderId/sync`로 웹훅 유실 시 수동으로 PG사 상태 동기화 가능
+- 테스트 환경에서는 PG사 테스트 키 사용 (`test_ck_`, `TC0ONETIME` 등)
+- **PayPal** 라이브 전환 시 `api_url`을 `https://api-m.paypal.com`으로 변경
+- **PayPal** `confirmPayment` 응답의 `paymentKey`는 **Capture ID**이므로 환불 시 이 값을 사용
+
+---
+
+## 관련 문서
+
+- [PG Routes](../routes/pg-routes.md)
+- [설정 예제](../../src/app/plugins/pg/config.example.json)
+- [페이레터 클라이언트 구현](../../src/app/plugins/pg/client-payletter.ts)
+- [Entity Server PG 가이드](../../../docs/plugins/pg-guide.md)

package/docs/plugins/push.md

@@ -0,0 +1,178 @@
+# Push 알림 플러그인
+
+앱서버에 내장된 Push 플러그인으로 FCM (Firebase Cloud Messaging) 및 APNs (Apple Push Notification) 발송을 처리합니다.
+
+> **관련**: [전체 라우트 목록](../routes/README.md) · [흐름도](../flows.md)
+
+---
+
+## 목차
+
+- [개요](#개요)
+- [설정](#설정)
+- [Firebase 키 준비](#firebase-키-준비)
+- [APNs 키 준비](#apns-키-준비)
+- [엔티티 구조](#엔티티-구조)
+
+---
+
+## 개요
+
+```
+POST /api/v1/push/send
+        │
+        ▼
+account_device 조회 (push_enabled=true, push_token 있는 것만)
+        │
+        ▼ (디바이스별)
+push_log(status=pending) DB 저장
+        │
+        ▼ (dispatch_interval_sec 간격 loop)
+push_log → processing (claim)
+        │
+      platform?
+     /        \
+  apns        fcm
+    │           │
+APNs HTTP/2  FCM HTTP v1
+    │           │
+    └─── push_log → sent / failed
+         (토큰 만료 시 account_device.push_enabled = false 자동 처리)
+```
+
+- **비동기 처리**: `enqueueJob`은 큐에 넣기만 하고 즉시 반환 — API 응답 지연 없음
+- **워커 풀**: `workers` 수만큼 고루틴(고루틴 대신 Promise.all)이 병렬 발송
+- **Stale 복구**: 서버 시작 시 `processing` 상태로 남은 로그를 `pending`으로 복구
+
+---
+
+## 설정
+
+`app/plugins/push/config.json`:
+
+```json
+{
+    "enabled": true,
+    "default": "main",
+    "workers": 2,
+    "queue_size": 50,
+    "dispatch_interval_sec": 5,
+    "max_retries": 3,
+    "providers": {
+        "main": {
+            "driver": "fcm",
+            "project_id": "my-firebase-project-id",
+            "key_file": "configs/keys/fcm-service-account.json"
+        },
+        "ios": {
+            "driver": "apns",
+            "key_id": "XXXXXXXXXX",
+            "team_id": "XXXXXXXXXX",
+            "bundle_id": "com.example.app",
+            "key_file": "configs/keys/apns-authkey.p8",
+            "production": false
+        }
+    }
+}
+```
+
+### 최상위 설정 필드
+
+| 필드                    | 기본값  | 설명                         |
+| ----------------------- | ------- | ---------------------------- |
+| `enabled`               | `false` | 플러그인 활성화              |
+| `default`               | —       | 기본 프로바이더 이름         |
+| `workers`               | `2`     | 동시 발송 워커 수            |
+| `queue_size`            | `50`    | dispatch당 한 번에 처리할 수 |
+| `dispatch_interval_sec` | `5`     | 큐 폴링 주기 (초)            |
+| `max_retries`           | `3`     | 발송 실패 최대 재시도 횟수   |
+
+### FCM 프로바이더 필드
+
+| 필드         | 설명                       |
+| ------------ | -------------------------- |
+| `driver`     | `"fcm"` 고정               |
+| `project_id` | Firebase 프로젝트 ID       |
+| `key_file`   | 서비스 계정 JSON 파일 경로 |
+
+### APNs 프로바이더 필드
+
+| 필드         | 설명                                                      |
+| ------------ | --------------------------------------------------------- |
+| `driver`     | `"apns"` 고정                                             |
+| `key_id`     | `.p8` 키 파일 ID (`AuthKey_XXXXX.p8` → `XXXXX`)           |
+| `team_id`    | Apple Developer 팀 ID                                     |
+| `bundle_id`  | 앱 번들 ID (예: `com.example.app`)                        |
+| `key_file`   | `.p8` 키 파일 경로                                        |
+| `production` | `true` = 프로덕션 APNs, `false` = 샌드박스 (기본 `false`) |
+
+> Android는 `main (fcm)` 프로바이더를, iOS는 `ios (apns)` 프로바이더를 사용합니다.
+> `provider` 필드를 지정하지 않으면 `default` 프로바이더로 발송됩니다.
+
+---
+
+## Firebase 키 준비
+
+1. [Firebase Console](https://console.firebase.google.com/) → 프로젝트 설정
+2. **서비스 계정 → 새 비공개 키 생성** → JSON 파일 다운로드
+3. 다운로드한 JSON 파일을 `configs/keys/fcm-service-account.json`으로 저장
+4. `config.json`의 `providers.main.project_id`와 `key_file` 경로 설정
+
+---
+
+## APNs 키 준비
+
+1. [Apple Developer Console](https://developer.apple.com/) → Certificates, Identifiers & Profiles → **Keys**
+2. **"+" 버튼** → "Apple Push Notifications service (APNs)" 체크 → 생성
+3. `.p8` 파일 다운로드 (`AuthKey_XXXXX.p8`) — **한 번만 다운로드 가능**
+4. `configs/keys/apns-authkey.p8`으로 저장
+5. `config.json`의 `providers.ios` 필드 설정:
+    - `key_id`: 파일명의 ID 부분 (`AuthKey_ABCDE12345.p8` → `ABCDE12345`)
+    - `team_id`: Apple Developer 계정 상단에 표시되는 팀 ID
+    - `bundle_id`: 앱 번들 ID
+
+---
+
+## API 레퍼런스
+
+> API 요청/응답/예제는 [Push Routes](../routes/push-routes.md) 문서를 참고하세요.
+
+---
+
+## 엔티티 구조
+
+### account_device
+
+디바이스 등록 및 FCM/APNs 토큰 관리 엔티티.
+
+| 필드              | 타입   | 설명                                              |
+| ----------------- | ------ | ------------------------------------------------- |
+| `account_seq`     | int    | 연결된 계정 seq                                   |
+| `device_id`       | string | 디바이스 고유 ID (upsert 키)                      |
+| `push_token`      | string | FCM Registration Token 또는 APNs Device Token     |
+| `push_enabled`    | bool   | 푸시 수신 활성화 여부 (토큰 만료 시 자동 `false`) |
+| `platform`        | enum   | `android` `ios` `web` `windows` `macos` `linux`   |
+| `device_type`     | string | `mobile` `tablet` `desktop` 등                    |
+| `browser`         | string | 브라우저명 (web 플랫폼)                           |
+| `browser_version` | string | 브라우저 버전                                     |
+
+> `push_enabled=true`이고 `push_token`이 있는 디바이스에만 발송합니다.
+
+### push_log
+
+발송 이력 추적 엔티티.
+
+| 필드            | 타입   | 설명                                   |
+| --------------- | ------ | -------------------------------------- |
+| `status`        | enum   | `pending` `processing` `sent` `failed` |
+| `account_seq`   | int    | 수신자 계정 seq                        |
+| `device_seq`    | int    | 대상 디바이스 seq                      |
+| `platform`      | string | 발송 플랫폼                            |
+| `device_token`  | string | 발송 당시 토큰 값                      |
+| `title`         | string | 알림 제목                              |
+| `body`          | string | 알림 본문                              |
+| `provider`      | string | 사용된 프로바이더 이름                 |
+| `retry_count`   | int    | 재시도 횟수                            |
+| `error_message` | string | 실패 시 오류 메시지                    |
+| `ref_entity`    | string | 참조 엔티티명                          |
+| `sent_at`       | string | 발송 완료 시각                         |