create-entity-app-server 0.0.3

package/docs/routes/account-routes.md

@@ -0,0 +1,262 @@
+# Account Routes
+
+> **위치**: `app/routes/account/`  
+> **프리픽스**: `/api/v1/account`
+
+## 라우트 목록
+
+| Method | Path                                                    | 인증 | 설명     |
+| ------ | ------------------------------------------------------- | ---- | -------- |
+| POST   | [/api/v1/account/register](#post-v1apiaccount-register) | —    | 회원가입 |
+| POST   | [/api/v1/account/withdraw](#post-v1apiaccountwithdraw)  | JWT  | 회원탈퇴 |
+
+---
+
+## 개요
+
+계정 관련 라우트를 묶는 플러그인입니다.  
+자동 로더가 `routes/account/route.ts`를 탐색하여 `/api/v1/account` prefix로 등록하고,  
+`route.ts` 내부에서 하위 라우트를 수동으로 등록합니다.
+
+```
+routes/account/route.ts          ← 자동 로더가 /api/v1/account 로 등록
+├── register/route.ts            ← /register prefix 로 수동 등록
+│   → POST /api/v1/account/register
+└── withdraw/route.ts            ← /withdraw prefix 로 수동 등록
+    → POST /api/v1/account/withdraw
+```
+
+---
+
+## API 엔드포인트
+
+### POST `/api/v1/account/register`
+
+<a id="post-v1apiaccount-register"></a>
+
+이메일·비밀번호로 계정을 생성합니다.  
+설정에 따라 가입 직후 **이메일 인증 메일** 또는 **환영 메일**을 발송할 수 있습니다.
+
+> entity-server의 `POST /v1/auth/register`를 게이트웨이로 이관한 구현입니다.
+
+#### 요청 본문
+
+| 필드       | 타입   | 필수 | 설명                              |
+| ---------- | ------ | ---- | --------------------------------- |
+| `email`    | string | ✅   | 이메일 주소 (중복 불가)           |
+| `password` | string | ✅   | 비밀번호 (비밀번호 정책 적용)     |
+| `name`     | string | -    | 이름                              |
+| `phone`    | string | -    | 전화번호                          |
+| 기타 필드  | any    | -    | account 엔티티의 추가 필드로 전달 |
+
+> **주의**: `status`, `rbac_role`, `has_password`, `email_verified`, `passwd` 등
+> 보안 관련 필드는 요청 본문에 포함해도 무시됩니다.
+
+#### 응답
+
+**201 Created:**
+
+```json
+{
+    "ok": true,
+    "data": {
+        "seq": 42,
+        "email": "user@example.com",
+        "email_verified": false
+    }
+}
+```
+
+`email_verified`는 email-verify/config.json 에서 `enabled: true`일 때 `false`, 그 외엔 `true`.
+
+**400 Bad Request:**
+
+```json
+{ "ok": false, "error": "email is required" }
+{ "ok": false, "error": "비밀번호는 최소 8자 이상이어야 합니다" }
+```
+
+**409 Conflict:**
+
+```json
+{ "ok": false, "error": "이미 사용 중인 이메일입니다." }
+```
+
+#### 사용 예제
+
+```bash
+curl -X POST "http://localhost:3000/api/v1/account/register" \
+    -H "Content-Type: application/json" \
+    -d '{
+        "email": "user@example.com",
+        "password": "Passw0rd!",
+        "name": "홍길동"
+    }'
+```
+
+---
+
+## 처리 흐름
+
+### 회원가입
+
+```
+POST /api/v1/account/register
+  │
+  ├─ 1. 입력 검증 (email, password 필수 / 이메일 형식)
+  ├─ 2. 비밀번호 정책 검증 (configs/security.json password_policy)
+  ├─ 3. 이메일 중복 확인 (account 엔티티)
+  ├─ 4. 비밀번호 SHA-256+salt 해시
+  ├─ 5. account 엔티티 생성 (entityServer.submit)
+  │      status: "active", rbac_role: default_role
+  │      email_verified: email-verify.enabled ? false : true
+  │
+  ├─ 6a. [email-verify.enabled=true]  → 인증 코드/링크 메일 발송 (비동기)
+  │          (환영 메일은 인증 완료 후 confirm/activate에서 발송)
+  ├─ 6b. [email-verify.enabled=false, send_welcome_email=true]
+  │          → 즉시 환영 메일 발송 (비동기)
+  │
+  └─ 201 { seq, email, email_verified }
+```
+
+### 이메일 인증 완료 (환영 메일 연동)
+
+```
+POST /api/v1/email-verify/confirm  또는  GET /api/v1/email-verify/activate
+  │
+  ├─ 코드/토큰 검증
+  ├─ email_verified = true 저장
+  ├─ [send_welcome_email=true] → 환영 메일 발송 (비동기)
+  └─ 200
+```
+
+이메일 발송은 **비동기** — 발송 실패가 201/200 응답에 영향을 주지 않습니다.
+
+---
+
+## 설정 (`src/app/routes/account/register/config.json`)
+
+| 키                      | 타입    | 기본값                 | 설명                                                                         |
+| ----------------------- | ------- | ---------------------- | ---------------------------------------------------------------------------- |
+| `enabled`               | boolean | `true`                 | 라우트 활성화 여부                                                           |
+| `send_welcome_email`    | boolean | `false`                | 가입 후 환영 메일 발송 (이메일 인증 불필요시 즉시, 인증 필요시 인증 완료 후) |
+| `welcome_email_subject` | string  | `"가입을 환영합니다!"` | 환영 메일 제목                                                               |
+| `default_role`          | string  | `"user"`               | 신규 계정 RBAC role                                                          |
+
+> 이메일 인증 여부(인증 코드 길이, TTL 등)는 `email-verify/config.json`의 `enabled`로 제어됩니다.
+
+### 설정 예시
+
+```json
+{
+    "enabled": true,
+    "send_welcome_email": true,
+    "welcome_email_subject": "가입을 환영합니다!",
+    "default_role": "user"
+}
+```
+
+---
+
+## API 엔드포인트
+
+### POST `/api/v1/account/withdraw`
+
+<a id="post-v1apiaccountwithdraw"></a>
+
+현재 로그인한 계정을 탈퇴(익명화)합니다.
+
+> **JWT 필수** — `Authorization: Bearer <token>` 헤더
+
+#### 요청 본문
+
+| 필드     | 타입   | 필수 | 설명                                        |
+| -------- | ------ | ---- | ------------------------------------------- |
+| `passwd` | string | 조건 | 비밀번호 계정(`has_password=true`)이면 필수 |
+
+#### 응답
+
+**200 OK:**
+
+```json
+{ "ok": true, "data": { "message": "탈퇴 처리가 완료되었습니다." } }
+```
+
+**400 / 401 / 403 / 404:**
+
+```json
+{ "ok": false, "error": "비밀번호가 필요합니다." }
+{ "ok": false, "error": "비밀번호가 일치하지 않습니다." }
+{ "ok": false, "error": "관리자 계정은 자가 탈퇴가 불가합니다." }
+```
+
+#### 탈퇴 처리 내용
+
+| 대상                     | 처리                                                                   |
+| ------------------------ | ---------------------------------------------------------------------- |
+| `account.email`          | `withdrawn_<seq>@anonymized.local` 덮어쓰기                            |
+| `account.passwd`         | `""` (비밀번호 삭제)                                                   |
+| `account.status`         | `"inactive"`                                                           |
+| `account.has_password`   | `false`                                                                |
+| `account.email_verified` | `false`                                                                |
+| `account_oauth`          | 연결 OAuth 레코드 전체 hard delete                                     |
+| `user`                   | `name = "탈퇴회원_<seq>"`, `profile_image = ""`, `status = "inactive"` |
+| `password_history`       | 전체 hard delete                                                       |
+
+> user / account_oauth / password_history 엔티티가 없는 환경에서는 해당 단계를 무시합니다.
+
+#### 사용 예제
+
+```bash
+curl -X POST "http://localhost:3000/api/v1/account/withdraw" \
+    -H "Authorization: Bearer <jwt_token>" \
+    -H "Content-Type: application/json" \
+    -d '{ "passwd": "my_password" }'
+```
+
+---
+
+## 이메일 템플릿
+
+| 용도      | 파일                                            | 변수                  |
+| --------- | ----------------------------------------------- | --------------------- |
+| 인증 코드 | `templates/email/auth/verification.html`        | `code`, `ttl_minutes` |
+| 인증 링크 | `templates/email/auth/verification_link.html`   | `link`, `ttl_minutes` |
+| 환영 메일 | `src/app/routes/account/templates/welcome.html` | `name`, `email`       |
+
+---
+
+## 하위 라우트 추가 방법
+
+`app/routes/account/route.ts`에 등록 한 줄을 추가합니다.
+
+```typescript
+// app/routes/account/route.ts
+import newRoutes from "./new-feature/route.ts";
+
+export default async function accountRoutes(app: FastifyInstance) {
+    await app.register(registerRoutes, { prefix: "/register" });
+    await app.register(withdrawPlugin, { prefix: "/withdraw" });
+    await app.register(newRoutes, { prefix: "/new-feature" }); // 추가
+}
+```
+
+---
+
+## 관련 문서
+
+- [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)
+- [Push Routes](./push-routes.md)
+- [← 전체 목록](./README.md)

package/docs/routes/alimtalk-routes.md

@@ -0,0 +1,187 @@
+# Alimtalk Routes
+
+기준 파일: `src/app/plugins/alimtalk/routes.ts`
+
+이 문서는 실제 API 호출 중심(라우트표/사용 예제/응답 예제)을 다룹니다.  
+플러그인의 개요/설정/운영 가이드는 [Alimtalk Guide](../../plugins/alimtalk.md) 문서를 참고하세요.
+
+## 라우트 목록
+
+| Method | Path                                                                     | 설명             |
+| ------ | ------------------------------------------------------------------------ | ---------------- |
+| POST   | [/api/v1/alimtalk/send](#post-v1apialimtalksend)                         | 알림톡 발송      |
+| GET    | [/api/v1/alimtalk/status/:seq](#get-v1apialimtalkstatusseq)              | 발송 상태 조회   |
+| GET    | [/api/v1/alimtalk/templates](#get-v1apialimtalktemplates)                | 템플릿 목록 조회 |
+| POST   | [/api/v1/alimtalk/webhook/:provider](#post-v1apialimtalkwebhookprovider) | 공급사 웹훅 수신 |
+
+## 라우트 상세
+
+### POST /api/v1/alimtalk/send
+
+<a id="post-v1apialimtalksend"></a>
+
+- 설명: 수신자/템플릿 정보를 기반으로 알림톡을 발송한다.
+- 요청 파라미터:
+
+| 위치 | 필드            | 타입   | 필수 | 설명                               |
+| ---- | --------------- | ------ | ---- | ---------------------------------- |
+| Body | `template_code` | string | ✅   | 카카오 알림톡 템플릿 코드          |
+| Body | `receiver`      | string | ✅   | 수신자 전화번호                    |
+| Body | `variables`     | object |      | 템플릿 `#{변수명}` 치환 값         |
+| Body | `provider`      | string |      | 드라이버명 (비어 있으면 `default`) |
+
+- 사용 예제:
+
+```bash
+curl -X POST "http://localhost:3000/api/v1/alimtalk/send" \
+	-H "Content-Type: application/json" \
+	-d '{"template_code":"ORDER_001","receiver":"01012345678","variables":{"고객명":"홍길동","주문번호":"ORD-2025-001","결제금액":"35,000"}}'
+```
+
+- 응답 예제:
+
+`202 Accepted`
+
+```json
+{
+    "ok": true,
+    "message": "alimtalk queued"
+}
+```
+
+`400 Bad Request` (`template_code`, `receiver` 누락)
+
+```json
+{
+    "ok": false,
+    "message": "template_code and receiver are required"
+}
+```
+
+`503 Service Unavailable` (서비스 비활성/미주입)
+
+```json
+{
+    "ok": false,
+    "message": "Alimtalk service not available"
+}
+```
+
+### GET /api/v1/alimtalk/status/:seq
+
+<a id="get-v1apialimtalkstatusseq"></a>
+
+- 설명: 발송 요청 건(`seq`)의 상태를 조회한다.
+- 요청 파라미터:
+
+| 위치 | 필드  | 타입   | 필수 | 설명               |
+| ---- | ----- | ------ | ---- | ------------------ |
+| Path | `seq` | string | ✅   | 알림톡 로그 시퀀스 |
+
+- 사용 예제:
+
+```bash
+curl "http://localhost:3000/api/v1/alimtalk/status/501"
+```
+
+- 응답 예제:
+
+`501 Not Implemented`
+
+```json
+{
+    "ok": false,
+    "message": "not implemented yet"
+}
+```
+
+### GET /api/v1/alimtalk/templates
+
+<a id="get-v1apialimtalktemplates"></a>
+
+- 설명: 사용 가능한 알림톡 템플릿 목록을 조회한다.
+- 요청 파라미터: 없음
+- 사용 예제:
+
+```bash
+curl "http://localhost:3000/api/v1/alimtalk/templates"
+```
+
+- 응답 예제:
+
+`200 OK`
+
+```json
+{
+    "ok": true,
+    "templates": [
+        {
+            "code": "ORDER_001",
+            "name": "주문 접수 알림",
+            "variables": ["고객명", "주문번호", "결제금액"]
+        }
+    ],
+    "count": 1
+}
+```
+
+`503 Service Unavailable`
+
+```json
+{
+    "ok": false,
+    "message": "Alimtalk service not available"
+}
+```
+
+### POST /api/v1/alimtalk/webhook/:provider
+
+<a id="post-v1apialimtalkwebhookprovider"></a>
+
+- 설명: 알림톡 공급사에서 전달한 상태 변경 이벤트를 수신한다.
+- 요청 파라미터:
+
+| 위치 | 필드         | 타입          | 필수 | 설명                      |
+| ---- | ------------ | ------------- | ---- | ------------------------- |
+| Path | `provider`   | string        | ✅   | 웹훅 발신 공급사 식별자   |
+| Body | `(raw json)` | object/string |      | 공급사 웹훅 페이로드 원문 |
+
+- 사용 예제:
+
+```bash
+curl -X POST "http://localhost:3000/api/v1/alimtalk/webhook/provider-a" \
+	-H "Content-Type: application/json" \
+	-d '{"messageId":"msg-001","status":"DELIVERED"}'
+```
+
+- 응답 예제:
+
+`200 OK` (정상 처리/내부 오류 모두 재시도 방지 목적)
+
+```text
+OK
+```
+
+`400 Bad Request` (`provider` 누락)
+
+```text
+provider required
+```
+
+## 관련 문서
+
+- [Account Routes](./account-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)
+- [Push Routes](./push-routes.md)
+- [← 전체 목록](./README.md)