create-entity-app-server 0.0.3

package/docs/routes/push-routes.md

@@ -0,0 +1,205 @@
+# Push Routes
+
+기준 파일: `src/app/plugins/push/`
+
+이 문서는 실제 API 호출 중심(라우트표/사용 예제/응답 예제)을 다룹니다.  
+플러그인의 개요/설정/운영 가이드는 [Push Guide](../plugins/push.md) 문서를 참고하세요.
+
+## 라우트 목록
+
+| Method | Path                                                   | 인증 | 설명                    |
+| ------ | ------------------------------------------------------ | ---- | ----------------------- |
+| POST   | [/api/v1/push/device](#post-v1apipushdevice)           | JWT  | 디바이스 토큰 등록/갱신 |
+| DELETE | [/api/v1/push/device/:seq](#delete-v1apipushdeviceseq) | JWT  | 디바이스 비활성화       |
+| POST   | [/api/v1/push/send](#post-v1apipushsend)               | —    | 단일 계정 발송          |
+| POST   | [/api/v1/push/broadcast](#post-v1apipushbroadcast)     | —    | 다중 계정 브로드캐스트  |
+| GET    | [/api/v1/push/status/:seq](#get-v1apipushstatusseq)    | —    | 발송 상태 조회 안내     |
+
+## 라우트 상세
+
+### POST /api/v1/push/device
+
+<a id="post-v1apipushdevice"></a>
+
+- 설명: 클라이언트 FCM/APNs 토큰을 등록하거나 갱신한다. `device_id` 기준 upsert.
+- **인증 필요** (JWT Bearer)
+- 요청 파라미터:
+
+| 위치 | 필드              | 타입   | 필수 | 설명                                            |
+| ---- | ----------------- | ------ | ---- | ----------------------------------------------- |
+| Body | `device_id`       | string | ✅   | 디바이스 고유 ID (클라이언트 생성 UUID)         |
+| Body | `push_token`      | string | ✅   | FCM Registration Token 또는 APNs Device Token   |
+| Body | `platform`        | string |      | `android` `ios` `web` `windows` `macos` `linux` |
+| Body | `device_type`     | string |      | `mobile` `tablet` `desktop` 등                  |
+| Body | `browser`         | string |      | 브라우저명 (web 플랫폼)                         |
+| Body | `browser_version` | string |      | 브라우저 버전                                   |
+
+- 사용 예제:
+
+```bash
+curl -X POST "http://localhost:3000/api/v1/push/device" \
+  -H "Authorization: Bearer {access_token}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "device_id": "unique-device-uuid",
+    "push_token": "FCM-or-APNs-token...",
+    "platform": "android",
+    "device_type": "mobile"
+  }'
+```
+
+- 응답 예제:
+
+`200 OK`
+
+```json
+{ "ok": true, "data": { "seq": 12 } }
+```
+
+---
+
+### DELETE /api/v1/push/device/:seq
+
+<a id="delete-v1apipushdeviceseq"></a>
+
+- 설명: `account_device.push_enabled = false`로 설정한다. 로그아웃 시 호출.
+- **인증 필요** (JWT Bearer)
+- 사용 예제:
+
+```bash
+curl -X DELETE "http://localhost:3000/api/v1/push/device/12" \
+  -H "Authorization: Bearer {access_token}"
+```
+
+- 응답 예제:
+
+`200 OK`
+
+```json
+{ "ok": true }
+```
+
+---
+
+### POST /api/v1/push/send
+
+<a id="post-v1apipushsend"></a>
+
+- 설명: 특정 계정의 모든 활성 디바이스에 Push를 발송한다.
+- 요청 파라미터:
+
+| 위치 | 필드          | 타입   | 필수 | 설명                                   |
+| ---- | ------------- | ------ | ---- | -------------------------------------- |
+| Body | `account_seq` | int    | ✅   | 수신자 account seq                     |
+| Body | `title`       | string | ✅   | 알림 제목                              |
+| Body | `body`        | string | ✅   | 알림 본문                              |
+| Body | `data`        | object |      | 커스텀 key-value 페이로드 (string map) |
+| Body | `ref_entity`  | string |      | 참조 엔티티명                          |
+| Body | `ref_seq`     | int    |      | 참조 레코드 seq                        |
+| Body | `provider`    | string |      | 프로바이더 지정 (없으면 `default`)     |
+
+- 사용 예제:
+
+```bash
+curl -X POST "http://localhost:3000/api/v1/push/send" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "account_seq": 1,
+    "title": "새로운 결재 요청",
+    "body": "결재 요청이 도착했습니다",
+    "data": { "type": "approval", "seq": "42" },
+    "ref_entity": "approval",
+    "ref_seq": 42
+  }'
+```
+
+- 응답 예제:
+
+`200 OK`
+
+```json
+{ "ok": true, "data": { "message": "Push notification queued for delivery" } }
+```
+
+---
+
+### POST /api/v1/push/broadcast
+
+<a id="post-v1apipushbroadcast"></a>
+
+- 설명: 여러 계정의 모든 활성 디바이스에 Push를 일괄 발송한다.
+- 요청 파라미터:
+
+| 위치 | 필드           | 타입   | 필수 | 설명                                     |
+| ---- | -------------- | ------ | ---- | ---------------------------------------- |
+| Body | `account_seqs` | int[]  | ✅   | 수신자 account seq 배열 (비어있으면 400) |
+| Body | `title`        | string | ✅   | 알림 제목                                |
+| Body | `body`         | string | ✅   | 알림 본문                                |
+| Body | `data`         | object |      | 커스텀 key-value 페이로드                |
+| Body | `ref_entity`   | string |      | 참조 엔티티명                            |
+| Body | `provider`     | string |      | 프로바이더 지정                          |
+
+- 사용 예제:
+
+```bash
+curl -X POST "http://localhost:3000/api/v1/push/broadcast" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "account_seqs": [1, 2, 3],
+    "title": "시스템 점검 안내",
+    "body": "오늘 오후 11시~12시 서비스 점검이 있습니다"
+  }'
+```
+
+- 응답 예제:
+
+`200 OK`
+
+```json
+{
+    "ok": true,
+    "data": {
+        "message": "Push notifications queued for 3 accounts",
+        "queued": 3
+    }
+}
+```
+
+---
+
+### GET /api/v1/push/status/:seq
+
+<a id="get-v1apipushstatusseq"></a>
+
+- 설명: 발송 상태는 엔티티 API로 직접 조회한다.
+- 사용 예제:
+
+```bash
+# push_log 단건 조회
+curl "http://localhost:3000/api/v1/entity/push_log/get/{seq}"
+
+# 특정 계정의 발송 이력
+curl -X POST "http://localhost:3000/api/v1/entity/push_log/list" \
+  -d '{ "conditions": { "account_seq": 1 }, "order_by": "seq desc", "limit": 20 }'
+```
+
+---
+
+## 관련 문서
+
+- [Push Guide](../plugins/push.md) — 설정·운영 가이드
+- [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)
+- [라우트 추가 가이드](./how-to-create.md)
+- [← 전체 목록](./README.md)

package/docs/routes/sms-routes.md

@@ -0,0 +1,243 @@
+# SMS Routes
+
+기준 파일: `src/app/plugins/sms/routes.ts`
+
+이 문서는 실제 API 호출 중심(라우트표/사용 예제/응답 예제)을 다룹니다.  
+플러그인의 개요/설정/운영 가이드는 [SMS Guide](../../plugins/sms.md) 문서를 참고하세요.
+
+## 라우트 목록
+
+| Method | Path                                                                | 설명           |
+| ------ | ------------------------------------------------------------------- | -------------- |
+| POST   | [/api/v1/sms/send](#post-v1apismssend)                              | SMS 발송       |
+| GET    | [/api/v1/sms/status/:seq](#get-v1apismsstatusseq)                   | 발송 상태 조회 |
+| POST   | [/api/v1/sms/verification/send](#post-v1apismsverificationsend)     | 인증번호 발송  |
+| POST   | [/api/v1/sms/verification/verify](#post-v1apismsverificationverify) | 인증번호 검증  |
+
+## 라우트 상세
+
+### POST /api/v1/sms/send
+
+<a id="post-v1apismssend"></a>
+
+- 설명: SMS/LMS/MMS 문자를 발송 큐에 등록한다.
+- 요청 파라미터:
+
+| 위치 | 필드         | 타입   | 필수 | 설명                               |
+| ---- | ------------ | ------ | ---- | ---------------------------------- |
+| Body | `receiver`   | string | ✅   | 수신자 전화번호                    |
+| Body | `content`    | string | ✅   | 메시지 본문                        |
+| Body | `provider`   | string |      | 드라이버명 (비어 있으면 `default`) |
+| Body | `sender`     | string |      | 발신번호 (비어 있으면 설정값 사용) |
+| Body | `subject`    | string |      | 제목 (LMS/MMS 전용)                |
+| Body | `image_url`  | string |      | 이미지 URL (MMS 전용)              |
+| Body | `ref_entity` | string |      | 참조 엔티티명                      |
+| Body | `ref_seq`    | number |      | 참조 엔티티 seq                    |
+
+- 사용 예제:
+
+```bash
+curl -X POST "http://localhost:3000/api/v1/sms/send" \
+  -H "Content-Type: application/json" \
+  -d '{"receiver":"01012345678","content":"안녕하세요. 테스트 메시지입니다."}'
+```
+
+- 응답 예제:
+
+`200 OK`
+
+```json
+{
+    "success": true,
+    "data": { "message": "SMS queued for delivery" }
+}
+```
+
+`400 Bad Request` (`receiver` 또는 `content` 누락)
+
+```json
+{
+    "success": false,
+    "error": "receiver is required"
+}
+```
+
+`503 Service Unavailable` (서비스 비활성)
+
+```json
+{
+    "success": false,
+    "error": "SMS service not available"
+}
+```
+
+↑ [목록으로 이동](#라우트-목록)
+
+---
+
+### GET /api/v1/sms/status/:seq
+
+<a id="get-v1apismsstatusseq"></a>
+
+- 설명: 발송 요청 건의 상태를 조회한다. 엔티티 API 사용을 안내한다.
+- 요청 파라미터:
+
+| 위치 | 필드  | 타입   | 필수 | 설명            |
+| ---- | ----- | ------ | ---- | --------------- |
+| Path | `seq` | string | ✅   | SMS 로그 시퀀스 |
+
+- 사용 예제:
+
+```bash
+curl "http://localhost:3000/api/v1/sms/status/42"
+```
+
+- 응답 예제:
+
+`200 OK`
+
+```json
+{
+    "success": true,
+    "data": {
+        "message": "Use entity API: GET /api/v1/entity/sms_log/{seq} to check SMS delivery status"
+    }
+}
+```
+
+↑ [목록으로 이동](#라우트-목록)
+
+---
+
+### POST /api/v1/sms/verification/send
+
+<a id="post-v1apismsverificationsend"></a>
+
+- 설명: 인증번호를 생성하여 SMS로 발송한다.
+- 요청 파라미터:
+
+| 위치 | 필드      | 타입   | 필수 | 설명                    |
+| ---- | --------- | ------ | ---- | ----------------------- |
+| Body | `phone`   | string | ✅   | 수신 전화번호           |
+| Body | `purpose` | string |      | 용도 (기본: `"signup"`) |
+
+- 사용 예제:
+
+```bash
+curl -X POST "http://localhost:3000/api/v1/sms/verification/send" \
+  -H "Content-Type: application/json" \
+  -d '{"phone":"01012345678","purpose":"signup"}'
+```
+
+- 응답 예제:
+
+`200 OK`
+
+```json
+{
+    "success": true,
+    "data": { "expires_in": 180 }
+}
+```
+
+`400 Bad Request` (`phone` 누락)
+
+```json
+{
+    "success": false,
+    "error": "phone is required"
+}
+```
+
+`503 Service Unavailable` (인증번호 서비스 비활성)
+
+```json
+{
+    "success": false,
+    "error": "SMS verification service not available"
+}
+```
+
+↑ [목록으로 이동](#라우트-목록)
+
+---
+
+### POST /api/v1/sms/verification/verify
+
+<a id="post-v1apismsverificationverify"></a>
+
+- 설명: 발송된 인증번호를 검증한다.
+- 요청 파라미터:
+
+| 위치 | 필드      | 타입   | 필수 | 설명                    |
+| ---- | --------- | ------ | ---- | ----------------------- |
+| Body | `phone`   | string | ✅   | 전화번호                |
+| Body | `code`    | string | ✅   | 인증번호                |
+| Body | `purpose` | string |      | 용도 (기본: `"signup"`) |
+
+- 사용 예제:
+
+```bash
+curl -X POST "http://localhost:3000/api/v1/sms/verification/verify" \
+  -H "Content-Type: application/json" \
+  -d '{"phone":"01012345678","code":"482901","purpose":"signup"}'
+```
+
+- 응답 예제:
+
+`200 OK` (검증 성공)
+
+```json
+{
+    "success": true,
+    "data": { "verified": true }
+}
+```
+
+`401 Unauthorized` (인증번호 불일치)
+
+```json
+{
+    "success": false,
+    "error": "invalid verification code"
+}
+```
+
+`400 Bad Request` (만료 또는 최대 시도 초과)
+
+```json
+{
+    "success": false,
+    "error": "code expired"
+}
+```
+
+```json
+{
+    "success": false,
+    "error": "max attempts exceeded"
+}
+```
+
+↑ [목록으로 이동](#라우트-목록)
+
+---
+
+## 관련 문서
+
+- [SMS Guide](../../plugins/sms.md) — 설정·운영 가이드
+- [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)
+- [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/smtp-routes.md

@@ -0,0 +1,155 @@
+# SMTP Routes
+
+기준 파일: `src/app/plugins/smtp/routes.ts`
+
+이 문서는 실제 API 호출 중심(라우트표/사용 예제/응답 예제)을 다룹니다.  
+플러그인의 개요/설정/운영 가이드는 [SMTP Guide](../plugins/smtp.md) 문서를 참고하세요.
+
+## 라우트 우선순위 안내
+
+`/api/v1/smtp/*` 경로는 기본적으로 Go 서버로 패스스루됩니다.  
+단, 이 플러그인에 등록된 아래 라우트는 **앱 서버가 먼저 처리**하며 Go 서버로는 전달되지 않습니다.  
+앱 서버에서 로컬 템플릿을 렌더링한 뒤 완성된 HTML을 Go 서버 내부 API(`/v1/smtp/send`)로 전달합니다.
+
+## 라우트 목록
+
+| Method | Path                                                | 설명                            |
+| ------ | --------------------------------------------------- | ------------------------------- |
+| POST   | [/api/v1/smtp/send](#post-v1apismtpsend)            | 로컬 템플릿 렌더링 후 메일 발송 |
+| GET    | [/api/v1/smtp/status/:seq](#get-v1apismtpstatusseq) | 발송 상태 조회                  |
+
+## 라우트 상세
+
+### POST /api/v1/smtp/send
+
+<a id="post-v1apismtpsend"></a>
+
+- 설명: 이메일을 발송한다. `templateName`이 지정되면 `plugins/smtp/templates/*.html`을 렌더링하여 `body_html`로 완성 후 Go 서버에 전달한다. `templateName` 없이 `body_html`/`body_text`만 지정하면 그대로 전달한다.
+- 요청 파라미터:
+
+| 위치 | 필드           | 타입     | 필수 | 설명                                                |
+| ---- | -------------- | -------- | ---- | --------------------------------------------------- |
+| Body | `to`           | string[] | ✅   | 수신자 이메일 (1개 이상)                            |
+| Body | `subject`      | string   |      | 제목                                                |
+| Body | `templateName` | string   |      | 로컬 템플릿명 (확장자 제외, 예: `"password_reset"`) |
+| Body | `templateDir`  | string   |      | 템플릿 디렉토리 절대경로 (미지정 시 기본값 사용)    |
+| Body | `templateData` | object   |      | 템플릿 변수 맵                                      |
+| Body | `bodyHtml`     | string   |      | 직접 HTML 본문 (`templateName` 대신 사용)           |
+| Body | `bodyText`     | string   |      | 텍스트 본문                                         |
+| Body | `cc`           | string[] |      | 참조                                                |
+| Body | `bcc`          | string[] |      | 숨은 참조                                           |
+| Body | `from`         | string   |      | 발신자                                              |
+| Body | `replyTo`      | string   |      | Reply-To                                            |
+| Body | `refEntity`    | string   |      | 참조 엔티티명                                       |
+| Body | `refSeq`       | number   |      | 참조 엔티티 seq                                     |
+
+- 사용 예제 (로컬 템플릿 사용):
+
+```bash
+curl -X POST "http://localhost:3000/api/v1/smtp/send" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "to": ["user@example.com"],
+    "subject": "비밀번호 재설정",
+    "templateName": "password_reset",
+    "templateData": { "reset_link": "https://example.com/reset?token=abc123" }
+  }'
+```
+
+- 사용 예제 (직접 HTML):
+
+```bash
+curl -X POST "http://localhost:3000/api/v1/smtp/send" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "to": ["user@example.com"],
+    "subject": "안내 메일",
+    "bodyHtml": "<p>안녕하세요.</p>"
+  }'
+```
+
+- 응답 예제:
+
+`200 OK`
+
+```json
+{
+    "success": true,
+    "data": { "seq": 42 }
+}
+```
+
+`400 Bad Request` (`to` 누락)
+
+```json
+{
+    "success": false,
+    "error": "to is required"
+}
+```
+
+↑ [목록으로 이동](#라우트-목록)
+
+---
+
+### GET /api/v1/smtp/status/:seq
+
+<a id="get-v1apismtpstatusseq"></a>
+
+- 설명: 이메일 발송 요청 건의 상태를 Go 서버에 조회한다.
+- 요청 파라미터:
+
+| 위치 | 필드  | 타입   | 필수 | 설명             |
+| ---- | ----- | ------ | ---- | ---------------- |
+| Path | `seq` | number | ✅   | 발송 로그 시퀀스 |
+
+- 사용 예제:
+
+```bash
+curl "http://localhost:3000/api/v1/smtp/status/42"
+```
+
+- 응답 예제:
+
+`200 OK`
+
+```json
+{
+    "success": true,
+    "data": {
+        "ok": true,
+        "status": "sent"
+    }
+}
+```
+
+`400 Bad Request` (잘못된 seq)
+
+```json
+{
+    "success": false,
+    "error": "Invalid seq"
+}
+```
+
+↑ [목록으로 이동](#라우트-목록)
+
+---
+
+## 관련 문서
+
+- [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)
+- [Tax Invoice Routes](./tax-invoice-routes.md)
+- [Push Routes](./push-routes.md)
+- [라우트 추가 가이드](./how-to-create.md)
+- [← 전체 목록](./README.md)