create-entity-app-server 0.0.3

package/src/app/plugins/sms/docs/README.md

@@ -0,0 +1,236 @@
+# SMS 플러그인
+
+알리고(Aligo) 등 외부 프로바이더를 통해 SMS/LMS/MMS를 발송합니다.  
+메시지 길이에 따라 자동으로 LMS/MMS로 전환하고, 발송 큐·레이트 리밋·인증번호 기능을 제공합니다.
+
+---
+
+## 목차
+
+- [개요](#개요)
+- [설정](#설정)
+- [API](#api)
+- [프로바이더](#프로바이더)
+- [인증번호 기능](#인증번호-기능)
+- [레이트 리밋](#레이트-리밋)
+- [Entity 테이블](#entity-테이블)
+
+---
+
+## 개요
+
+| 항목            | 내용                                  |
+| --------------- | ------------------------------------- |
+| 기본 경로       | `/api/v1/sms`                         |
+| 설정 파일       | `config.json`                         |
+| 기본 프로바이더 | `aligo`                               |
+| 활성화 기본값   | `false` (명시적으로 `true` 설정 필요) |
+
+### 메시지 타입 자동 전환
+
+| 타입 | 조건                                            |
+| ---- | ----------------------------------------------- |
+| SMS  | 본문 ≤ 80바이트                                 |
+| LMS  | 본문 > 80바이트 (`auto_lms: true` 시 자동 전환) |
+| MMS  | `image_url`이 지정된 경우                       |
+
+---
+
+## 설정
+
+설정 파일: `src/app/plugins/sms/config.json`
+
+### 기본 설정
+
+| 키                      | 기본값                 | 설명                           |
+| ----------------------- | ---------------------- | ------------------------------ |
+| `enabled`               | `false`                | 플러그인 활성화 여부           |
+| `default`               | `"aligo"`              | 기본 사용 프로바이더           |
+| `sender`                | `${SMS_SENDER_NUMBER}` | 발신번호                       |
+| `workers`               | `2`                    | 발송 워커 수                   |
+| `queue_size`            | `200`                  | 큐 최대 크기                   |
+| `dispatch_interval_sec` | `5`                    | 큐 처리 간격 (초)              |
+| `max_retries`           | `3`                    | 최대 재시도 횟수               |
+| `auto_lms`              | `true`                 | 80바이트 초과 시 자동 LMS 전환 |
+| `lms_threshold_bytes`   | `80`                   | LMS 전환 기준 (바이트)         |
+
+### 환경변수
+
+| 환경변수            | 설명                   | 예시            |
+| ------------------- | ---------------------- | --------------- |
+| `ALIGO_API_KEY`     | 알리고 API 키          | `"abc123..."`   |
+| `ALIGO_USER_ID`     | 알리고 사용자 ID       | `"mycompany"`   |
+| `SMS_SENDER_NUMBER` | 발신번호 (등록된 번호) | `"01012345678"` |
+
+---
+
+## API
+
+기본 경로: `/api/v1/sms`
+
+| 메서드 | 경로                                               | 인증 | 설명                |
+| ------ | -------------------------------------------------- | ---- | ------------------- |
+| `POST` | [`/send`](#post-send)                              |      | SMS/LMS/MMS 발송    |
+| `GET`  | [`/status/:seq`](#get-status-seq)                  |      | 발송 기록 조회 안내 |
+| `POST` | [`/verification/send`](#post-verificationsend)     |      | 인증번호 발송       |
+| `POST` | [`/verification/verify`](#post-verificationverify) |      | 인증번호 검증       |
+
+---
+
+### POST /send
+
+SMS, LMS, MMS 발송 요청을 큐에 등록합니다.
+
+**요청 Body**
+
+| 필드         | 타입   | 필수 | 설명                              |
+| ------------ | ------ | ---- | --------------------------------- |
+| `receiver`   | string | ✅   | 수신번호 (`01012345678`)          |
+| `content`    | string | ✅   | 메시지 본문                       |
+| `subject`    | string |      | LMS/MMS 제목                      |
+| `image_url`  | string |      | 이미지 URL (MMS 전환)             |
+| `sender`     | string |      | 발신번호 (기본: config `sender`)  |
+| `provider`   | string |      | 사용 프로바이더 (기본: `default`) |
+| `ref_entity` | string |      | 연관 엔티티 이름                  |
+| `ref_seq`    | number |      | 연관 엔티티 SEQ                   |
+
+**응답 예시**
+
+```json
+{
+    "success": true,
+    "data": {
+        "message": "SMS queued for delivery"
+    }
+}
+```
+
+> 실제 발송 결과는 `sms_log` 엔티티에서 확인합니다.
+
+---
+
+### GET /status/:seq
+
+엔티티 API를 통한 발송 상태 조회를 안내합니다.
+
+> `GET /api/v1/entity/sms_log/{seq}` 를 직접 사용하세요.
+
+---
+
+### POST /verification/send
+
+인증번호를 생성하여 지정 번호로 SMS 발송합니다.
+
+**요청 Body**
+
+| 필드      | 타입   | 필수 | 설명                         |
+| --------- | ------ | ---- | ---------------------------- |
+| `phone`   | string | ✅   | 수신 전화번호                |
+| `purpose` | string |      | 인증 목적 (기본: `"signup"`) |
+
+**응답 예시**
+
+```json
+{
+    "success": true,
+    "data": {
+        "expires_in": 180
+    }
+}
+```
+
+---
+
+### POST /verification/verify
+
+발송된 인증번호를 검증합니다.
+
+**요청 Body**
+
+| 필드      | 타입   | 필수 | 설명                         |
+| --------- | ------ | ---- | ---------------------------- |
+| `phone`   | string | ✅   | 검증할 전화번호              |
+| `code`    | string | ✅   | 인증번호 (6자리)             |
+| `purpose` | string |      | 인증 목적 (기본: `"signup"`) |
+
+**응답 예시**
+
+```json
+{
+    "success": true,
+    "data": {
+        "verified": true
+    }
+}
+```
+
+**오류 응답**
+
+| 상태  | 설명                              |
+| ----- | --------------------------------- |
+| `400` | 코드 불일치, 만료, 최대 시도 초과 |
+| `503` | SMS 서비스 비활성화               |
+
+---
+
+## 프로바이더
+
+현재 사용 가능한 드라이버:
+
+| 드라이버  | 파일                   | 설명           |
+| --------- | ---------------------- | -------------- |
+| `aligo`   | `providers/aligo.ts`   | 알리고 SMS API |
+| `solapi`  | `providers/solapi.ts`  | 솔라피         |
+| `ppurio`  | `providers/ppurio.ts`  | 뿌리오         |
+| `nhn`     | `providers/nhn.ts`     | NHN Cloud SMS  |
+| `aws-sns` | `providers/aws-sns.ts` | Amazon SNS     |
+
+### 알리고 프로바이더 설정
+
+```json
+{
+    "providers": {
+        "aligo": {
+            "driver": "aligo",
+            "api_key": "${ALIGO_API_KEY}",
+            "user_id": "${ALIGO_USER_ID}",
+            "sender": "${SMS_SENDER_NUMBER}"
+        }
+    }
+}
+```
+
+---
+
+## 인증번호 기능
+
+| 설정 키        | 기본값 | 설명                  |
+| -------------- | ------ | --------------------- |
+| `code_length`  | `6`    | 인증번호 자릿수       |
+| `ttl_sec`      | `180`  | 유효 시간 (초)        |
+| `max_attempts` | `5`    | 최대 검증 시도 횟수   |
+| `cooldown_sec` | `60`   | 재발송 대기 시간 (초) |
+
+인증번호는 `sms_verification` 테이블에 저장됩니다.
+
+---
+
+## 레이트 리밋
+
+동일 번호로 과도한 발송을 방지합니다.
+
+| 설정 키                 | 기본값 | 설명                     |
+| ----------------------- | ------ | ------------------------ |
+| `per_number_per_minute` | `5`    | 동일 번호 분당 최대 발송 |
+| `per_minute`            | `60`   | 전체 분당 최대 발송      |
+| `per_hour`              | `500`  | 전체 시간당 최대 발송    |
+
+---
+
+## Entity 테이블
+
+| 테이블             | 설명                                      |
+| ------------------ | ----------------------------------------- |
+| `sms_msg`          | 발송 메시지 원문                          |
+| `sms_log`          | 발송 이력 및 결과 (성공/실패/재시도 횟수) |
+| `sms_verification` | 인증번호 발송 및 검증 기록                |

package/src/app/plugins/sms/entities/sms_log.json

@@ -0,0 +1,65 @@
+{
+    "name": "sms_log",
+    "description": "SMS/LMS/MMS 발송 이력 로그. 사용자 환경에 맞게 fields를 자유롭게 확장할 수 있습니다.",
+    "license_scope": false,
+    "hard_delete": true,
+    "history": false,
+    "read_only": true,
+    "compress": true,
+    "fields": {
+        "status": {
+            "index": true,
+            "type": [
+                "pending",
+                "processing",
+                "sent",
+                "failed"
+            ]
+        },
+        "msg_type": {
+            "index": true,
+            "type": [
+                "sms",
+                "lms",
+                "mms"
+            ]
+        },
+        "receiver": {
+            "index": true,
+            "hash": true,
+            "type": "string"
+        },
+        "sms_msg_seq": {
+            "index": true,
+            "comment": "sms_msg 참조 seq"
+        },
+        "sender": {
+            "type": "string"
+        },
+        "subject": {
+            "type": "string"
+        },
+        "content": {
+            "type": "string"
+        },
+        "image_url": {
+            "type": "string",
+            "comment": "MMS 이미지 URL"
+        },
+        "provider": {
+            "type": "string"
+        },
+        "provider_msg_id": {
+            "type": "string"
+        },
+        "error_message": {
+            "type": "string"
+        },
+        "retry_count": {
+            "type": "uint"
+        },
+        "sent_at": {
+            "type": "string"
+        }
+    }
+}

package/src/app/plugins/sms/entities/sms_msg.json

@@ -0,0 +1,82 @@
+{
+    "name": "sms_msg",
+    "description": "SMS/LMS/MMS 발송 트리거 엔티티. insert 시 sms hook으로 비동기 발송. 사용자 환경에 맞게 fields를 자유롭게 확장할 수 있습니다.",
+    "license_scope": false,
+    "hard_delete": true,
+    "history": false,
+    "read_only": true,
+    "fields": {
+        "status": {
+            "index": true,
+            "type": [
+                "queued",
+                "sent",
+                "failed"
+            ],
+            "default": "queued"
+        },
+        "msg_type": {
+            "index": true,
+            "type": [
+                "sms",
+                "lms",
+                "mms"
+            ],
+            "default": "sms"
+        },
+        "receiver": {
+            "index": true,
+            "hash": true,
+            "type": "string",
+            "required": true,
+            "comment": "수신 전화번호"
+        },
+        "sender": {
+            "type": "string",
+            "comment": "발신번호"
+        },
+        "subject": {
+            "type": "string",
+            "comment": "LMS/MMS 제목 (SMS는 미사용)"
+        },
+        "content": {
+            "type": "string",
+            "comment": "메시지 본문"
+        },
+        "image_url": {
+            "type": "string",
+            "comment": "MMS 이미지 URL"
+        },
+        "provider": {
+            "type": "string",
+            "comment": "발송 프로바이더 키"
+        },
+        "provider_msg_id": {
+            "type": "string",
+            "comment": "프로바이더 메시지 ID"
+        },
+        "ref_entity": {
+            "type": "string"
+        },
+        "ref_seq": {
+            "type": "int"
+        },
+        "error_message": {
+            "type": "string"
+        },
+        "sent_at": {
+            "type": "string"
+        }
+    },
+    "hooks": {
+        "after_insert": [
+            {
+                "type": "sms",
+                "enabled": true,
+                "sms_receiver": "${new.receiver}",
+                "sms_content": "${new.content}",
+                "sms_subject": "${new.subject}"
+            }
+        ]
+    }
+}

package/src/app/plugins/sms/entities/sms_verification.json

@@ -0,0 +1,50 @@
+{
+    "name": "sms_verification",
+    "description": "SMS 인증번호 검증 엔티티. 인증번호 SHA-256 해시 저장, 시도 횟수 관리. 사용자 환경에 맞게 fields를 자유롭게 확장할 수 있습니다.",
+    "license_scope": false,
+    "hard_delete": true,
+    "history": false,
+    "fields": {
+        "phone": {
+            "index": true,
+            "hash": true,
+            "comment": "수신 전화번호",
+            "type": "varchar(20)",
+            "required": true
+        },
+        "purpose": {
+            "index": true,
+            "comment": "인증 목적",
+            "type": [
+                "signup",
+                "password_reset",
+                "identity"
+            ],
+            "required": true
+        },
+        "status": {
+            "index": true,
+            "type": [
+                "pending",
+                "verified",
+                "expired"
+            ],
+            "default": "pending",
+            "required": true
+        },
+        "code_hash": {
+            "type": "varchar(64)",
+            "required": true,
+            "comment": "인증번호 SHA-256 해시"
+        },
+        "expires_at": {
+            "required": true,
+            "comment": "만료 시각"
+        },
+        "attempts": {
+            "type": "uint",
+            "default": 0,
+            "comment": "검증 시도 횟수"
+        }
+    }
+}

package/src/app/plugins/sms/entity-adapter.ts

@@ -0,0 +1,213 @@
+/**
+ * SmsQuerier — Entity Server 어댑터
+ *
+ * entity-server-client를 통해 sms_log, sms_msg 엔티티에 접근.
+ * DB 큐 패턴: pending → processing → sent/failed
+ *
+ * Go 엔티티서버 `internal/sms/entity_adapter.go`에서 포팅
+ *
+ * Note: Go의 CompareAndSwap는 구현하지 않음.
+ *       단일 Node.js 프로세스이므로 dispatch loop에서 순차 처리하여 동시성 문제 방지.
+ */
+
+import { entityServer, logger } from "@gateway/api";
+import type { SmsQuerier, PendingSmsLog, VerificationQuerier } from "./types/index.ts";
+
+export class SmsEntityAdapter implements SmsQuerier {
+    constructor(private readonly maxRetries: number = 3) {}
+
+    /** SMS 발송 로그를 등록한다 */
+    async submitSmsLog(data: Record<string, unknown>): Promise<void> {
+        await entityServer.submit("sms_log", data);
+    }
+
+    /** 대기 중인 SMS 로그를 조회·점유한다 */
+    async claimPendingSmsLogs(limit: number): Promise<PendingSmsLog[]> {
+        const resp = await entityServer.list("sms_log", {
+            status: "pending",
+            page: 1,
+            limit,
+            order: "seq",
+        } as any);
+
+        const items = ((resp.data as any)?.items ?? []) as Record<string, unknown>[];
+        const logs: PendingSmsLog[] = [];
+
+        for (const item of items) {
+            const seq = Number(item.seq ?? 0);
+            if (seq <= 0) continue;
+
+            // pending → processing (단일 프로세스이므로 CAS 대신 직접 갱신)
+            try {
+                await entityServer.submit("sms_log", {
+                    seq,
+                    status: "processing",
+                });
+                logs.push({
+                    log_seq: seq,
+                    provider: String(item.provider ?? ""),
+                    sender: String(item.sender ?? ""),
+                    receiver: String(item.receiver ?? ""),
+                    content: String(item.content ?? ""),
+                    subject: String(item.subject ?? ""),
+                    msg_type: String(item.msg_type ?? ""),
+                    image_url: String(item.image_url ?? ""),
+                    retry_count: Number(item.retry_count ?? 0),
+                    sms_msg_seq: Number(item.sms_msg_seq ?? 0),
+                });
+            } catch (err) {
+                logger.warn(
+                    { err, seq },
+                    "SMS: failed to claim log, skipping",
+                );
+            }
+        }
+
+        return logs;
+    }
+
+    /** SMS 로그 상태를 갱신한다 */
+    async updateSmsLogStatus(
+        logSeq: number,
+        status: string,
+        providerMsgId: string,
+        errMsg: string,
+    ): Promise<void> {
+        const data: Record<string, unknown> = {
+            status,
+            provider_msg_id: providerMsgId,
+            error_message: errMsg,
+        };
+        if (status === "sent") {
+            data.sent_at = "now()";
+        }
+        await entityServer.submit("sms_log", { seq: logSeq, ...data });
+    }
+
+    /** 서버 시작 시 stale processing 로그를 복구한다 */
+    async resetStaleSmsLogs(): Promise<void> {
+        const resp = await entityServer.list("sms_log", {
+            status: "processing",
+            page: 1,
+            limit: 1000,
+        } as any);
+
+        const items = ((resp.data as any)?.items ?? []) as Record<string, unknown>[];
+
+        for (const item of items) {
+            const seq = Number(item.seq ?? 0);
+            const retryCount = Number(item.retry_count ?? 0);
+
+            if (seq <= 0) continue;
+
+            try {
+                if (retryCount >= this.maxRetries) {
+                    await entityServer.submit("sms_log", {
+                        seq,
+                        status: "failed",
+                        error_message: "max retries exceeded (stale recovery)",
+                    });
+                } else {
+                    await entityServer.submit("sms_log", {
+                        seq,
+                        status: "pending",
+                        retry_count: retryCount + 1,
+                    });
+                }
+            } catch (err) {
+                logger.warn(
+                    { err, seq },
+                    "SMS: failed to reset stale log",
+                );
+            }
+        }
+
+        if (items.length > 0) {
+            logger.info(
+                `SMS: reset ${items.length} stale processing logs`,
+            );
+        }
+    }
+
+    /** sms_msg 상태를 갱신한다 */
+    async updateSmsMsgStatus(
+        msgSeq: number,
+        status: string,
+    ): Promise<void> {
+        if (msgSeq <= 0) return;
+        try {
+            await entityServer.submit("sms_msg", { seq: msgSeq, status });
+        } catch (err) {
+            logger.warn(
+                { err, msgSeq },
+                "SMS: failed to update sms_msg status",
+            );
+        }
+    }
+}
+
+/** SMS 인증번호 Entity Adapter */
+export class SmsVerificationEntityAdapter implements VerificationQuerier {
+    /** 인증번호 레코드를 등록하고 seq를 반환한다 */
+    async submitVerification(
+        data: Record<string, unknown>,
+    ): Promise<number> {
+        const resp = await entityServer.submit("sms_verification", data);
+        return resp.seq ?? 0;
+    }
+
+    /** 대기 중인 인증번호 레코드를 조회한다 */
+    async findPendingVerification(
+        phone: string,
+        purpose: string,
+    ): Promise<Record<string, unknown> | null> {
+        const resp = await entityServer.list("sms_verification", {
+            phone,
+            purpose,
+            status: "pending",
+            page: 1,
+            limit: 1,
+            order: "-seq",
+        } as any);
+
+        const items = ((resp.data as any)?.items ?? []) as Record<string, unknown>[];
+        return items[0] ?? null;
+    }
+
+    /** 인증번호 레코드를 갱신한다 */
+    async updateVerification(
+        seq: number,
+        data: Record<string, unknown>,
+    ): Promise<void> {
+        await entityServer.submit("sms_verification", { seq, ...data });
+    }
+
+    /** 동일 전화번호+목적의 이전 pending 건을 모두 만료시킨다 */
+    async expireOldVerifications(
+        phone: string,
+        purpose: string,
+    ): Promise<void> {
+        const resp = await entityServer.list("sms_verification", {
+            phone,
+            purpose,
+            status: "pending",
+            page: 1,
+            limit: 100,
+        } as any);
+
+        const items = ((resp.data as any)?.items ?? []) as Record<string, unknown>[];
+
+        for (const item of items) {
+            const seq = Number(item.seq ?? 0);
+            if (seq <= 0) continue;
+            try {
+                await entityServer.submit("sms_verification", {
+                    seq,
+                    status: "expired",
+                });
+            } catch {
+                // best-effort
+            }
+        }
+    }
+}