create-entity-app-server 0.0.3

package/docs/routes/identity-routes.md

@@ -0,0 +1,310 @@
+# Identity Routes
+
+기준 파일: `src/app/plugins/identity/routes.ts`
+
+이 문서는 실제 API 호출 중심(라우트표/사용 예제/응답 예제)을 다룹니다.
+플러그인의 개요/설정/운영 가이드는 [Identity Guide](../../plugins/identity.md) 문서를 참고하세요.
+
+## 라우트 목록
+
+| Method | Path                                                                      | 설명             |
+| ------ | ------------------------------------------------------------------------- | ---------------- |
+| POST   | [/api/v1/identity/request](#post-v1apiidentityrequest)                    | 인증 요청 생성   |
+| POST   | [/api/v1/identity/callback](#post-v1apiidentitycallback)                  | 중계사 콜백 수신 |
+| GET    | [/api/v1/identity/result/:request_id](#get-v1apiidentityresultrequest_id) | 인증 결과 조회   |
+| POST   | [/api/v1/identity/verify-ci](#post-v1apiidentityverify-ci)                | CI 중복 확인     |
+
+## 라우트 상세
+
+### POST /api/v1/identity/request
+
+<a id="post-v1apiidentityrequest"></a>
+
+- 설명: 본인인증 요청을 생성하고 팝업 호출에 필요한 데이터를 반환한다.
+- 인증: JWT 선택 (있으면 `account_seq` 자동 추출)
+- 사용 예제:
+
+```bash
+curl -X POST "http://localhost:3000/api/v1/identity/request" \
+     -H "Content-Type: application/json" \
+     -d '{
+       "purpose": "signup",
+       "method": "popup",
+       "provider": "nice"
+     }'
+```
+
+- 요청 Body:
+
+| 필드       | 타입   | 필수 | 설명                                                                                          |
+| ---------- | ------ | ---- | --------------------------------------------------------------------------------------------- |
+| `purpose`  | string | ✅   | 인증 목적 (`signup` / `find_account` / `password_reset` / `adult_verify` / `identity_change`) |
+| `method`   | string |      | 인증 방식 (`popup` / `pass` / `sms`), 기본: `popup`                                           |
+| `provider` | string |      | 프로바이더 지정 (`nice` / `kmc` / `danal`), 기본: 설정의 `default`                            |
+
+- 성공 응답 (200):
+
+```json
+{
+    "ok": true,
+    "data": {
+        "request_id": "a1b2c3d4...64자hex",
+        "popup_url": "https://nice.checkplus.co.kr/CheckPlusSafeModel/service.cb",
+        "enc_data": "ZW5jcnlwdGVk...",
+        "token_version_id": "20250101...",
+        "integrity_value": "hmac..."
+    }
+}
+```
+
+> **NICE**: `popup_url`, `enc_data`, `token_version_id`, `integrity_value` 반환
+> **KMC**: `popup_url`, `enc_data` 반환
+> **다날**: `popup_url`, `enc_data` 반환
+
+- 에러 응답:
+
+| 코드 | 조건                              |
+| ---- | --------------------------------- |
+| 400  | `purpose` 누락 또는 유효하지 않음 |
+| 500  | 프로바이더 통신 실패              |
+| 503  | Identity 플러그인 비활성화        |
+
+---
+
+### POST /api/v1/identity/callback
+
+<a id="post-v1apiidentitycallback"></a>
+
+- 설명: NICE/KMC/다날 중계사가 본인인증 완료 후 호출하는 콜백 엔드포인트.
+- 인증: 없음 (중계사에서 직접 호출)
+- Content-Type: `application/x-www-form-urlencoded` 또는 `application/json`
+- 사용 예제:
+
+```bash
+# form-urlencoded (NICE/KMC 기본)
+curl -X POST "http://localhost:3000/api/v1/identity/callback?provider=nice" \
+     -H "Content-Type: application/x-www-form-urlencoded" \
+     -d "enc_data=ZW5jcnlwdGVk...&token_version_id=20250101..."
+```
+
+- 요청 Body:
+
+| 필드               | 타입   | 필수 | 설명                                  |
+| ------------------ | ------ | ---- | ------------------------------------- |
+| `enc_data`         | string | ✅   | 중계사 암호화된 콜백 데이터           |
+| `token_version_id` | string |      | NICE 전용, 토큰 버전 ID               |
+| `provider`         | string |      | 프로바이더 (body 또는 query 파라미터) |
+| `rec_cert`         | string |      | KMC 전용, `enc_data` 대체 파라미터    |
+
+- 성공 응답: HTML 페이지 (`text/html`)
+    - `window.opener.postMessage`로 인증 결과를 부모 창에 전달
+    - 자동으로 팝업 닫기
+
+```js
+// 부모 창에서 수신하는 메시지 형식
+{
+  type: "identity_verification",
+  request_id: "a1b2c3d4...64자hex",
+  status: "verified"  // 또는 "failed"
+}
+```
+
+---
+
+### GET /api/v1/identity/result/:request_id
+
+<a id="get-v1apiidentityresultrequest_id"></a>
+
+- 설명: 본인인증 결과를 마스킹하여 조회한다.
+- 인증: JWT 선택
+- 사용 예제:
+
+```bash
+curl "http://localhost:3000/api/v1/identity/result/a1b2c3d4...64자hex"
+```
+
+- 경로 파라미터:
+
+| 필드         | 타입   | 설명                    |
+| ------------ | ------ | ----------------------- |
+| `request_id` | string | 인증 요청 ID (64자 hex) |
+
+- 성공 응답 (200):
+
+```json
+{
+    "ok": true,
+    "data": {
+        "status": "verified",
+        "name": "홍*동",
+        "birthDate": "1990****",
+        "gender": "M",
+        "phone": "010****5678",
+        "verifiedAt": "2025-01-15T10:30:00+09:00",
+        "isDuplicate": false,
+        "accountLinked": true
+    }
+}
+```
+
+- 마스킹 규칙:
+
+| 필드        | 규칙                                 |
+| ----------- | ------------------------------------ |
+| `name`      | 첫/끝 글자 유지, 중간 `*` ("홍\*동") |
+| `birthDate` | 앞 4자리(연도) 유지, 뒤 `****`       |
+| `phone`     | 앞 3자리 + `****` + 뒤 4자리         |
+
+- 에러 응답:
+
+| 코드 | 조건                             |
+| ---- | -------------------------------- |
+| 400  | `request_id` 누락 또는 형식 오류 |
+| 404  | 요청 없음                        |
+| 503  | Identity 플러그인 비활성화       |
+
+---
+
+### POST /api/v1/identity/verify-ci
+
+<a id="post-v1apiidentityverify-ci"></a>
+
+- 설명: CI 해시로 이미 가입된 계정이 있는지 확인한다.
+- 인증: JWT 필수
+- 사용 예제:
+
+```bash
+curl -X POST "http://localhost:3000/api/v1/identity/verify-ci" \
+     -H "Content-Type: application/json" \
+     -H "Authorization: Bearer eyJhbGci..." \
+     -d '{"ci_hash": "e3b0c44298fc..."}'
+```
+
+- 요청 Body:
+
+| 필드      | 타입   | 필수 | 설명                         |
+| --------- | ------ | ---- | ---------------------------- |
+| `ci_hash` | string | ✅   | CI의 SHA-256 해시 (64자 hex) |
+
+- 성공 응답 (200):
+
+```json
+{
+    "ok": true,
+    "data": {
+        "exists": true,
+        "account_seq": 12345
+    }
+}
+```
+
+- 에러 응답:
+
+| 코드 | 조건                       |
+| ---- | -------------------------- |
+| 400  | `ci_hash` 누락             |
+| 500  | 조회 실패                  |
+| 503  | Identity 플러그인 비활성화 |
+
+---
+
+## 프론트엔드 연동 예제
+
+```html
+<script>
+    async function startVerification() {
+        // 1. 인증 요청 생성
+        const res = await fetch("/api/v1/identity/request", {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ purpose: "signup", method: "popup" }),
+        });
+        const { data } = await res.json();
+
+        // 2. 인증 팝업 열기
+        const form = document.createElement("form");
+        form.method = "POST";
+        form.action = data.popup_url;
+        form.target = "identity_popup";
+
+        const fields = { enc_data: data.enc_data };
+        if (data.token_version_id)
+            fields.token_version_id = data.token_version_id;
+        if (data.integrity_value) fields.integrity_value = data.integrity_value;
+
+        for (const [k, v] of Object.entries(fields)) {
+            const input = document.createElement("input");
+            input.type = "hidden";
+            input.name = k;
+            input.value = v;
+            form.appendChild(input);
+        }
+
+        document.body.appendChild(form);
+        window.open("", "identity_popup", "width=500,height=600");
+        form.submit();
+        form.remove();
+
+        // 3. 결과 수신
+        window.addEventListener("message", async (e) => {
+            if (e.data?.type === "identity_verification") {
+                if (e.data.status === "verified") {
+                    const result = await fetch(
+                        `/api/v1/identity/result/${e.data.request_id}`,
+                    );
+                    const { data } = await result.json();
+                    console.log("인증 결과:", data);
+                }
+            }
+        });
+    }
+</script>
+```
+
+## 정규화 규칙
+
+### 성별 (gender)
+
+| 입력 값                         | 정규화 결과 |
+| ------------------------------- | ----------- |
+| `"0"`, `"M"`, `"m"`, `"male"`   | `"M"`       |
+| `"1"`, `"F"`, `"f"`, `"female"` | `"F"`       |
+| 기타                            | 원본 반환   |
+
+### 통신사 (carrier)
+
+| 입력 값       | 정규화 결과  |
+| ------------- | ------------ |
+| `"1"`, `"01"` | `"SKT"`      |
+| `"2"`, `"02"` | `"KT"`       |
+| `"3"`, `"03"` | `"LGU"`      |
+| `"4"`, `"04"` | `"MVNO_SKT"` |
+| `"5"`, `"05"` | `"MVNO_KT"`  |
+| `"6"`, `"06"` | `"MVNO_LGU"` |
+| 기타          | 원본 반환    |
+
+### 국적 (nationality)
+
+| 입력 값                | 정규화 결과 |
+| ---------------------- | ----------- |
+| `"0"`, `"local"`, `""` | `"local"`   |
+| `"1"`, `"foreign"`     | `"foreign"` |
+| 기타                   | 원본 반환   |
+
+## 관련 문서
+
+- [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)
+- [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)