create-entity-app-server 0.0.3

package/docs/routes/ocr-routes.md

@@ -0,0 +1,133 @@
+# OCR Routes
+
+기준 파일: `src/app/plugins/ocr/routes.ts`
+
+이 문서는 실제 API 호출 중심(라우트표/사용 예제/응답 예제)을 다룹니다.  
+플러그인의 개요/설정/운영 가이드는 [OCR Guide](../../plugins/ocr.md) 문서를 참고하세요.
+
+## 라우트 목록
+
+| Method | Path                                                        | 설명                 |
+| ------ | ----------------------------------------------------------- | -------------------- |
+| POST   | [/api/v1/ocr/recognize](#post-v1apiocrrecognize)            | OCR 동기 인식        |
+| POST   | [/api/v1/ocr/recognize/async](#post-v1apiocrrecognizeasync) | OCR 비동기 인식      |
+| POST   | [/api/v1/ocr/:docType](#post-v1apiocrdoctype)               | 문서 유형별 OCR 인식 |
+| GET    | [/api/v1/ocr/results](#get-v1apiocrresults)                 | OCR 결과 목록 조회   |
+| GET    | [/api/v1/ocr/results/:id](#get-v1apiocrresultsid)           | OCR 결과 단건 조회   |
+| GET    | [/api/v1/ocr/results/:id/text](#get-v1apiocrresultsidtext)  | OCR 텍스트 추출 조회 |
+| DELETE | [/api/v1/ocr/results/:id](#delete-v1apiocrresultsid)        | OCR 결과 삭제        |
+| GET    | [/api/v1/ocr/quota](#get-v1apiocrquota)                     | OCR 사용량/쿼터 조회 |
+
+## 라우트 상세
+
+### POST /api/v1/ocr/recognize
+
+<a id="post-v1apiocrrecognize"></a>
+
+- 설명: OCR 인식을 동기 방식으로 수행하고 즉시 결과를 반환한다.
+- 사용 예제:
+
+```bash
+curl -X POST "http://localhost:3000/api/v1/ocr/recognize" \
+	-H "Content-Type: application/json" \
+	-d '{"imageUrl":"https://example.com/receipt.jpg"}'
+```
+
+### POST /api/v1/ocr/recognize/async
+
+<a id="post-v1apiocrrecognizeasync"></a>
+
+- 설명: OCR 작업을 비동기로 등록하고 추적 가능한 작업 ID를 반환한다.
+- 사용 예제:
+
+```bash
+curl -X POST "http://localhost:3000/api/v1/ocr/recognize/async" \
+	-H "Content-Type: application/json" \
+	-d '{"imageUrl":"https://example.com/invoice.jpg"}'
+```
+
+### POST /api/v1/ocr/:docType
+
+<a id="post-v1apiocrdoctype"></a>
+
+- 설명: `docType`(예: receipt, invoice) 기반 템플릿으로 OCR 인식을 수행한다.
+- 사용 예제:
+
+```bash
+curl -X POST "http://localhost:3000/api/v1/ocr/receipt" \
+	-H "Content-Type: application/json" \
+	-d '{"imageUrl":"https://example.com/receipt.jpg"}'
+```
+
+### GET /api/v1/ocr/results
+
+<a id="get-v1apiocrresults"></a>
+
+- 설명: 저장된 OCR 결과를 목록 형태로 조회한다.
+- 사용 예제:
+
+```bash
+curl "http://localhost:3000/api/v1/ocr/results"
+```
+
+### GET /api/v1/ocr/results/:id
+
+<a id="get-v1apiocrresultsid"></a>
+
+- 설명: OCR 결과 ID 단건의 원본/메타 정보를 조회한다.
+- 사용 예제:
+
+```bash
+curl "http://localhost:3000/api/v1/ocr/results/98765"
+```
+
+### GET /api/v1/ocr/results/:id/text
+
+<a id="get-v1apiocrresultsidtext"></a>
+
+- 설명: OCR 결과에서 텍스트 추출 결과만 조회한다.
+- 사용 예제:
+
+```bash
+curl "http://localhost:3000/api/v1/ocr/results/98765/text"
+```
+
+### DELETE /api/v1/ocr/results/:id
+
+<a id="delete-v1apiocrresultsid"></a>
+
+- 설명: 저장된 OCR 결과를 삭제한다.
+- 사용 예제:
+
+```bash
+curl -X DELETE "http://localhost:3000/api/v1/ocr/results/98765"
+```
+
+### GET /api/v1/ocr/quota
+
+<a id="get-v1apiocrquota"></a>
+
+- 설명: OCR 호출량, 잔여량 등 사용량 정보를 조회한다.
+- 사용 예제:
+
+```bash
+curl "http://localhost:3000/api/v1/ocr/quota"
+```
+
+## 관련 문서
+
+- [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)
+- [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/password-reset.md

@@ -0,0 +1,234 @@
+# 비밀번호 재설정 (Password Reset)
+
+> **위치**: `app/routes/password-reset/`  
+> **프리픽스**: `/api/v1/password-reset`  
+> **모드**: `temp_password` (임시 비밀번호) | `link` (리셋 링크)
+
+## 라우트 목록
+
+| Method | Path                                                                                           | 인증 | 모드 | 설명                  |
+| ------ | ---------------------------------------------------------------------------------------------- | ---- | ---- | --------------------- |
+| POST   | [/api/v1/password-reset/request](#post-v1apipassword-resetrequest)                             | —    | 공통 | 비밀번호 재설정 요청  |
+| GET    | [/api/v1/password-reset/validate/:token](#get-v1apipassword-resetvalidatetoken-link-모드-전용) | —    | link | 토큰 유효성 확인      |
+| POST   | [/api/v1/password-reset/verify](#post-v1apipassword-resetverify-link-모드-전용)                | —    | link | 토큰 검증 + 비번 변경 |
+
+---
+
+## 개요
+
+비밀번호 분실 시 이메일을 통해 비밀번호를 재설정할 수 있는 셀프서비스 기능입니다.
+
+---
+
+## 모드
+
+### 1. 임시 비밀번호 모드 (`temp_password`) — 기본값
+
+```
+사용자 → POST /request {email}
+         → 임시 비밀번호 생성 (12자)
+         → account.temp_password_hash 저장
+         → 이메일 발송 (임시 비밀번호 포함)
+         → 항상 성공 응답
+
+사용자 → POST /api/v1/auth/login {email, passwd: 임시비밀번호}
+         → 엔티티서버 로그인 (프록시)
+         → force_password_change: true 응답
+
+사용자 → POST /api/v1/auth/change-password {current_passwd, new_passwd}
+         → 엔티티서버 비밀번호 변경 (프록시)
+```
+
+### 2. 리셋 링크 모드 (`link`)
+
+```
+사용자 → POST /request {email}
+         → 32-byte 토큰 생성
+         → SHA-256(token) → account.password_reset_token 저장
+         → 이메일 발송 (리셋 URL 포함)
+
+사용자 → GET /validate/:token
+         → 토큰 유효성 확인 (프론트엔드 UI용)
+
+사용자 → POST /verify {token, new_password}
+         → 토큰 검증 + 새 비밀번호 해싱 + account 업데이트
+```
+
+---
+
+## API 엔드포인트
+
+### POST `/api/v1/password-reset/request`
+
+비밀번호 재설정 요청. 계정 존재 여부와 관계없이 항상 동일한 응답을 반환합니다.
+
+#### 요청 파라미터 (Body)
+
+| 필드    | 타입   | 필수 | 설명             |
+| ------- | ------ | ---- | ---------------- |
+| `email` | string | ✅   | 계정 이메일 주소 |
+
+**Request:**
+
+```json
+{
+    "email": "user@example.com"
+}
+```
+
+**Response (항상 200):**
+
+```json
+{
+    "ok": true,
+    "message": "요청이 처리되었습니다."
+}
+```
+
+### GET `/api/v1/password-reset/validate/:token` (link 모드 전용)
+
+토큰 유효성을 확인합니다. 프론트엔드에서 비밀번호 입력 폼을 표시하기 전 사용합니다.
+
+#### 경로 파라미터
+
+| 필드    | 타입   | 필수 | 설명                          |
+| ------- | ------ | ---- | ----------------------------- |
+| `token` | string | ✅   | 이메일로 발송된 64자 hex 토큰 |
+
+**Response:**
+
+```json
+{
+    "success": true,
+    "data": {
+        "valid": true,
+        "expires_in_sec": 280
+    }
+}
+```
+
+### POST `/api/v1/password-reset/verify` (link 모드 전용)
+
+토큰을 검증하고 새 비밀번호를 설정합니다.
+
+#### 요청 파라미터 (Body)
+
+| 필드           | 타입   | 필수 | 설명                          |
+| -------------- | ------ | ---- | ----------------------------- |
+| `token`        | string | ✅   | 이메일로 발송된 64자 hex 토큰 |
+| `new_password` | string | ✅   | 새 비밀번호                   |
+
+**Request:**
+
+```json
+{
+    "token": "64자_hex_토큰",
+    "new_password": "새비밀번호"
+}
+```
+
+**Success Response:**
+
+```json
+{
+    "success": true,
+    "data": {
+        "message": "비밀번호가 변경되었습니다."
+    }
+}
+```
+
+---
+
+## 설정
+
+| 파일                                            | 설명        |
+| ----------------------------------------------- | ----------- |
+| `app/routes/password-reset/config.json`         | 런타임 설정 |
+| `app/routes/password-reset/config.example.json` | 배포용 예시 |
+
+### config.json 필드
+
+```json
+{
+    "enabled": true,
+    "mode": "temp_password",
+    "temp_password_ttl_sec": 300,
+    "temp_password_length": 12,
+    "link_base_url": "https://myapp.com/reset-password",
+    "link_token_ttl_sec": 300,
+    "rate_limit": {
+        "per_email_per_hour": 5,
+        "per_ip_per_minute": 10
+    },
+    "email_subject": "비밀번호 재설정"
+}
+```
+
+| 키                              | 설명                            | 기본값              |
+| ------------------------------- | ------------------------------- | ------------------- |
+| `enabled`                       | 기능 활성화                     | `true`              |
+| `mode`                          | `"temp_password"` 또는 `"link"` | `"temp_password"`   |
+| `temp_password_ttl_sec`         | 임시 비밀번호 유효 시간(초)     | `300` (5분)         |
+| `temp_password_length`          | 임시 비밀번호 길이              | `12`                |
+| `link_base_url`                 | 리셋 링크 URL (link 모드)       | `""`                |
+| `link_token_ttl_sec`            | 토큰 유효 시간(초) (link 모드)  | `300` (5분)         |
+| `rate_limit.per_email_per_hour` | 이메일당 시간당 최대 요청       | `5`                 |
+| `rate_limit.per_ip_per_minute`  | IP당 분당 최대 요청             | `10`                |
+| `email_subject`                 | 이메일 제목                     | `"비밀번호 재설정"` |
+
+환경변수 치환 지원: `"link_base_url": "${RESET_PASSWORD_URL}"`
+
+---
+
+## 보안
+
+| 항목           | 대책                                       |
+| -------------- | ------------------------------------------ |
+| 계정 열거 방지 | 이메일 존재 여부와 관계없이 동일 응답      |
+| Rate Limit     | 이메일당 5회/시간, IP당 10회/분 (인메모리) |
+| 임시 비밀번호  | SHA-256 + 16B salt 해시만 DB 저장          |
+| 토큰 보안      | SHA-256 해시만 DB 저장 (256-bit 엔트로피)  |
+| 일회성         | 사용 즉시 토큰/임시비번 필드 삭제          |
+| Constant-time  | `timingSafeEqual` 사용 (password-utils.ts) |
+
+---
+
+## 이메일 템플릿
+
+| 파일                       | 용도               | 변수                                            |
+| -------------------------- | ------------------ | ----------------------------------------------- |
+| `auth/password_reset`      | 임시 비밀번호 안내 | `${temp_password}`, `${expires_in}`, `${email}` |
+| `auth/password_reset_link` | 리셋 링크 안내     | `${reset_url}`, `${expires_in}`, `${email}`     |
+| `auth/force_reset`         | 관리자 강제 리셋   | `${temp_password}`, `${email}`                  |
+
+템플릿 위치: `templates/email/auth/`
+
+---
+
+## 커스터마이징
+
+`app/routes/password-reset/handlers.ts`를 직접 수정하여:
+
+- 비밀번호 정책 검증 추가
+- 커스텀 이메일 템플릿 변수 추가
+- 외부 Rate Limit 서비스(Redis 등) 연동
+- SMS 기반 인증번호 리셋 추가
+
+## 관련 문서
+
+- [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)
+- [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/pg-routes.md

@@ -0,0 +1,144 @@
+# PG Routes
+
+기준 파일: `src/app/plugins/pg/routes.ts`
+
+이 문서는 실제 API 호출 중심(라우트표/사용 예제/응답 예제)을 다룹니다.  
+플러그인의 개요/설정/운영 가이드는 [PG Guide](../../plugins/pg.md) 문서를 참고하세요.
+
+## 라우트 목록
+
+| Method | Path                                                                  | 설명                      |
+| ------ | --------------------------------------------------------------------- | ------------------------- |
+| POST   | [/api/v1/pg/orders](#post-v1apipgorders)                              | 주문 생성                 |
+| GET    | [/api/v1/pg/orders/:orderId](#get-v1apipgordersorderid)               | 주문 단건 조회            |
+| POST   | [/api/v1/pg/confirm](#post-v1apipgconfirm)                            | 결제 승인                 |
+| POST   | [/api/v1/pg/orders/:orderId/cancel](#post-v1apipgordersorderidcancel) | 결제 취소                 |
+| POST   | [/api/v1/pg/orders/:orderId/sync](#post-v1apipgordersorderidsync)     | 결제 상태 동기화          |
+| POST   | [/api/v1/pg/webhook](#post-v1apipgwebhook)                            | PG 웹훅 수신              |
+| GET    | [/api/v1/pg/config](#get-v1apipgconfig)                               | 클라이언트 결제 설정 조회 |
+
+## 라우트 상세
+
+### POST /api/v1/pg/orders
+
+<a id="post-v1apipgorders"></a>
+
+- 설명: 결제 요청을 위한 주문을 생성한다.
+- 사용 예제:
+
+```bash
+curl -X POST "http://localhost:3000/api/v1/pg/orders" \
+	-H "Content-Type: application/json" \
+	-d '{"amount":10000,"orderName":"테스트 주문"}'
+```
+
+### GET /api/v1/pg/orders/:orderId
+
+<a id="get-v1apipgordersorderid"></a>
+
+- 설명: 주문 ID로 결제 주문 상태를 조회한다.
+- 사용 예제:
+
+```bash
+curl "http://localhost:3000/api/v1/pg/orders/ORD_20260304_0001"
+```
+
+### POST /api/v1/pg/confirm
+
+<a id="post-v1apipgconfirm"></a>
+
+- 설명: PG 승인 토큰을 받아 결제를 최종 승인한다.
+- 사용 예제:
+
+```bash
+curl -X POST "http://localhost:3000/api/v1/pg/confirm" \
+	-H "Content-Type: application/json" \
+	-d '{"paymentKey":"pay_xxx","orderId":"ORD_20260304_0001","amount":10000}'
+```
+
+### POST /api/v1/pg/orders/:orderId/cancel
+
+<a id="post-v1apipgordersorderidcancel"></a>
+
+- 설명: 승인된 결제를 주문 기준으로 취소한다.
+- 사용 예제:
+
+```bash
+curl -X POST "http://localhost:3000/api/v1/pg/orders/ORD_20260304_0001/cancel" \
+	-H "Content-Type: application/json" \
+	-d '{"reason":"고객 요청"}'
+```
+
+### POST /api/v1/pg/orders/:orderId/sync
+
+<a id="post-v1apipgordersorderidsync"></a>
+
+- 설명: 관리 목적의 주문 상태 강제 동기화를 수행한다.
+- 사용 예제:
+
+```bash
+curl -X POST "http://localhost:3000/api/v1/pg/orders/ORD_20260304_0001/sync"
+```
+
+### POST /api/v1/pg/webhook
+
+<a id="post-v1apipgwebhook"></a>
+
+- 설명: PG사가 호출하는 웹훅 엔드포인트로 결제 이벤트를 수신한다.
+- 사용 예제:
+
+```bash
+# 일반 (토스페이먼츠 등)
+curl -X POST "http://localhost:3000/api/v1/pg/webhook" \
+	-H "Content-Type: application/json" \
+	-d '{"eventType":"PAYMENT_STATUS_CHANGED","orderId":"ORD_20260304_0001"}'
+
+# PayPal 웹훅 (헤더에 서명 정보 포함)
+curl -X POST "http://localhost:3000/api/v1/pg/webhook" \
+	-H "Content-Type: application/json" \
+	-H "PAYPAL-AUTH-ALGO: SHA256withRSA" \
+	-H "PAYPAL-CERT-URL: https://api.paypal.com/v1/notifications/xxx" \
+	-H "PAYPAL-TRANSMISSION-ID: tx-id" \
+	-H "PAYPAL-TRANSMISSION-SIG: sig" \
+	-H "PAYPAL-TRANSMISSION-TIME: 2026-03-06T12:00:00Z" \
+	-d '{"event_type":"PAYMENT.CAPTURE.COMPLETED","resource":{"id":"cap_xxx"}}'
+```
+
+> **PayPal 웹훅 서명 헤더 조합**
+>
+> 게이트웨이에서 `signature` 값을 구성하는 방식:
+>
+> ```
+> {PAYPAL-AUTH-ALGO}|{PAYPAL-CERT-URL}|{PAYPAL-TRANSMISSION-ID}|{PAYPAL-TRANSMISSION-SIG}|{PAYPAL-TRANSMISSION-TIME}
+> ```
+>
+> `webhook_secret` 설정이 없으면 검증을 건너뜁니다.
+
+### GET /api/v1/pg/config
+
+<a id="get-v1apipgconfig"></a>
+
+- 설명: 프런트엔드 결제 SDK 초기화용 설정값을 조회한다.
+- 사용 예제:
+
+```bash
+curl "http://localhost:3000/api/v1/pg/config"
+```
+
+## 관련 문서
+
+- [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)
+- [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)