# DPOT Postman Collection

Backend 의 모든 API 를 Postman 에서 테스트할 수 있는 import 파일 모음입니다.

## 폴더 구조

```
postman/
├── README.md                                       ← 이 파일
├── update.ps1                                      ← 갱신 스크립트
│
├── collections/
│   ├── DPOT-Public-API.postman_collection.json     ← /v1/* + /oauth/token (외부 개발자)
│   └── DPOT-Internal-API.postman_collection.json   ← /api/* (내부/관리자)
│
├── DPOT-Local.postman_environment.json             ← https://localhost:4000
├── DPOT-Dev.postman_environment.json               ← https://dev-api.dpot.live
├── DPOT-Prod.postman_environment.json              ← https://api.dpot.live
│
└── _legacy/                                        ← 이전 수동 작성 11개 collection (보관용)
    ├── Account.postman_collection.json
    ├── Auth.postman_collection.json
    └── ...
```

## 현재 endpoint 수 (2026-06-08 기준)

| Collection | Tag/Folder | Requests |
|---|---|---|
| **DPOT-Public-API** | 5 (OAuth, 회원, 상품, 쿠폰, 통계) | **6** |
| **DPOT-Internal-API** | 34 (Auth, MyPage, Forum, Feed, Store, Studio*, Donation*, Developers, Widget, ...) | **231** |

Internal Collection 의 주요 그룹:

- **MyPage** (27) — 내 정보, 포인트, 충전, 출금
- **Forum** (23) — 게시판 (post / comment / reaction / report)
- **Feed** (16) — 피드 / 댓글 / 좋아요 / 북마크
- **Developers** (14) — 개발자 포털 (앱/토큰/통계/프로필/KYC)
- **Store** (14) — 상점 (orders / inventory / channels)
- **StudioCrew** (14) — 크루 관리 (스튜디오)
- **Auth** (11) — 로그인 / 회원가입 / 비밀번호 / 이메일 인증
- **DonationRemote** (11) — 후원 위젯 리모컨
- **Widget** (10) — OBS 위젯 endpoint
- **Crew** (8) — 크루 (사용자측)
- **ChannelTitle** (7), **Note** (6), **Channel** (5), **Studio** (5), **Payment** (5), ...

---

## 1. Postman 에서 Import

### 1-1. Collection import
1. Postman → 좌측 **Collections** 패널 상단 **Import** 클릭
2. `collections/DPOT-Public-API.postman_collection.json` 드래그
3. 다시 Import → `collections/DPOT-Internal-API.postman_collection.json`

### 1-2. Environment import
1. Postman → 좌측 **Environments** 패널 상단 **Import** 클릭
2. 사용할 환경 파일을 import (필요한 개수만큼):
   - `DPOT-Local.postman_environment.json` (로컬 개발)
   - `DPOT-Dev.postman_environment.json` (DEV 서버)
   - `DPOT-Prod.postman_environment.json` (PROD 서버)
3. 우측 상단 environment selector 에서 사용할 환경 선택

> Collection 안의 모든 request 가 `{{baseUrl}}/...` 형식이라 environment 만 바꾸면 호출 대상이 전환됩니다.

---

## 2. 환경 변수

| 변수 | 용도 | 설정 방법 |
|---|---|---|
| `baseUrl` | API host | environment 별로 사전 설정됨 (변경 X) |
| `accessToken` | JWT Bearer (`Authorization: Bearer ...`) | 로그인 후 응답에서 복사 |
| `refreshToken` | refresh token | 로그인 응답에서 복사 |
| `clientId` | OAuth2 Client ID (`dpot_client_xxx`) | developers.dpot.live/apps 에서 발급 |
| `clientSecret` | OAuth2 Client Secret (`dpot_secret_xxx`) | 앱 생성 시 1회 표시 |
| `pat` | Personal Access Token (`dpot_pat_xxx`) | developers.dpot.live/tokens 에서 발급 |
| `channelSID` | 채널 SID (스튜디오/위젯 호출용) | 본인 채널 정보에서 복사 |
| `memberSID` | 회원 SID (특정 회원 조회) | 필요 시 수동 입력 |
| `memberID` | 회원 ID (숫자) | 필요 시 수동 입력 |

### 2-1. 첫 로그인 → 토큰 채우기

1. **Internal Collection** → `Auth` 폴더 → `POST /api/auth/login` 실행
2. body 예시:
   ```json
   { "email": "you@dpot.dev", "password": "your-password" }
   ```
3. 응답의 `data.accessToken` / `data.refreshToken` 복사
4. Environment editor 에서 `accessToken` / `refreshToken` 의 **Current Value** 에 붙여넣기
5. 이후 모든 인증 필요 request 는 자동으로 Bearer 헤더 사용

### 2-2. OAuth2 Client Credentials (Public API)

1. **Public Collection** → `OAuth` → `POST /oauth/token`
2. form-data:
   ```
   grant_type=client_credentials
   client_id={{clientId}}
   client_secret={{clientSecret}}
   scope=read:members read:products
   ```
3. 응답의 `access_token` 을 `accessToken` 변수에 저장
4. `/v1/*` 호출 시 자동 사용

### 2-3. PAT 사용

PAT 는 OAuth2 access token 발급 절차 없이 바로 사용:

```
Authorization: Bearer dpot_pat_xxxxxxxxxxxxxxxxxxxxxx
```

`pat` 변수에 저장 후, 필요한 request 에서 Authorization header 의 `{{accessToken}}` 부분을 `{{pat}}` 로 바꿔서 사용.

---

## 3. Collection 갱신

백엔드에 endpoint 가 추가/변경되면 collection 도 다시 생성해야 합니다.

### 3-1. 백엔드 실행

```powershell
cd D:\dpot\Backend
dotnet run --project Web.Api
```

`https://localhost:4000/health` 이 200 으로 응답하는지 확인.

### 3-2. 갱신 스크립트 실행

```powershell
cd D:\dpot\Backend\Web.Api\postman
pwsh ./update.ps1
```

옵션:
- `-ApiBase https://localhost:4000` (기본값)
- `-SkipPublic` — public 변환 생략
- `-SkipInternal` — internal 변환 생략

스크립트 동작:
1. `$ApiBase/health` 응답 확인
2. `$ApiBase/swagger/public/swagger.json` + `/swagger/internal/swagger.json` fetch
3. `npx openapi-to-postmanv2@5` 로 Postman Collection v2.1 변환
4. `collections/DPOT-*.postman_collection.json` 덮어쓰기

### 3-3. Postman 에 재import

갱신된 파일을 Postman 에서 **Import → Replace existing collection** 으로 적용.

> Environment 파일은 변하지 않으니 한 번만 import 하면 됩니다.

---

## 4. 주의사항

### Internal swagger 는 Production 에 차단됨

```
https://api.dpot.live/swagger/internal/swagger.json     → 404 (보안 차단)
https://dev-api.dpot.live/swagger/internal/swagger.json → 404 (보안 차단)
https://localhost:4000/swagger/internal/swagger.json    → 200 ← 변환은 여기서만
```

`update.ps1` 은 기본적으로 `localhost:4000` 을 호출합니다. 그래서 백엔드를 반드시 로컬에서 띄워야 internal collection 을 갱신할 수 있습니다.

Public swagger 는 모든 환경에 노출되어 있어서, 정 필요하면 PROD 에서도 가져올 수 있습니다:
```powershell
pwsh ./update.ps1 -ApiBase https://api.dpot.live -SkipInternal
```

### 자체 서명 인증서

`localhost:4000` 은 dev 자체 서명 인증서를 사용합니다. `update.ps1` 은 `-SkipCertificateCheck` 옵션으로 우회하지만, Postman 자체는 별도 설정이 필요할 수 있습니다:

Postman → Settings → General → **SSL certificate verification** OFF (로컬 호출 시에만)

PROD/DEV 호출 시에는 정상 와일드카드 인증서 (`*.dpot.live`) 라 ON 으로 유지해도 됩니다.

### `_legacy/` 폴더

기존에 수동 작성된 11개 collection 입니다 (Account, Auth, Channel, Donation, Etc, Forum, Note, Notification, Payment, Studio, Wallet). 한국어 endpoint 이름과 example body 가 직접 정리되어 있어 참고용으로 보관합니다.

새로운 자동 생성 collection 이 swagger 기반이라 endpoint 이름은 영어 (operationId / summary) 입니다. 한국어 이름이 필요하면 endpoint 의 `[EndpointSummary("...")]` 또는 XML doc 주석을 수정 후 백엔드 빌드 → `update.ps1` 재실행 하세요.

---

## 5. 트러블슈팅

| 증상 | 원인 / 해결 |
|---|---|
| `update.ps1` 가 backend 접근 실패 | `dotnet run --project Web.Api` 가 실행 중인지 확인. 포트 4000 점유 여부 확인 |
| `internal swagger 404` | PROD/DEV 에서 swagger fetch 시도. localhost 로 변경하거나 `-SkipInternal` 사용 |
| Postman import 시 한국어 깨짐 | 파일 인코딩은 UTF-8 (BOM 없음). Postman 9+ 권장 |
| `Authorization` 헤더가 안 들어감 | environment 가 선택돼 있고 `accessToken` 변수에 값이 채워졌는지 확인 |
| 401 Unauthorized | accessToken 만료 (1시간). 다시 로그인 또는 OAuth2 token 재발급 |
| CORS 오류 | Postman 자체는 CORS 영향 없음. 브라우저에서 직접 호출 시 발생 가능 |

---

## 6. 관련 문서

- [개발자 포털 plan](../../../.claude/plan/api-developer-portal.md)
- [공개 API 문서 (Scalar)](https://developers.dpot.live/docs) — 외부 개발자용
- [Backend Web.Api/DependencyInjection.cs](../DependencyInjection.cs) — Swagger doc group 설정
- [Backend Web.Api/Program.cs](../Program.cs) — Swagger middleware