# P2P 회원 페이지 UX 재설계 지침서

> v1.0 · 2026-07-13 · 작성: Cowork (시안 합의 완료 — dudgh 확정)
> 대상: p2p-ui (`cryptoments-admin/p2p-ui`) + open-api `P2pWithdrawPageController` / core `P2pWithdrawService`
> 관련: `P2P_MEMBER_SETTINGS_GUIDE.md`(설정 화면 — 계좌/빠른조회/텔레그램/거래상태는 전부 설정으로 이관 완료 전제), `P2P_MEMBER_TELEGRAM_GUIDE.md`(딥링크 진입점)

---

## 0. 배경 — 왜 재설계하는가

기존 회원 페이지는 시스템 모델(주문→매칭→정산)을 그대로 노출해 UX가 난해했고, 검토 중 안전 이슈도 발견됐다.

| # | 문제 | 코드 근거 |
|---|------|----------|
| 1 | "남은 금액"에 미매칭/매칭 진행 중/확인 대기 3개념이 뭉개짐 | `OrderDetailView.vue` 28~33행 `remaining = krw − confirmed` |
| 2 | 상세의 반환 카드가 "매칭되지 않은 X원"이라고 표기하나 실제로는 **매칭 진행 중 금액 포함** — 요청→승인 시 활성 매칭 강제취소(분쟁 유발) | `P2pWithdrawService.convertToDirectWithdrawal` 291행 Fix B |
| 3 | `requestUsdtConvert`가 무검증 — 터미널 주문/중복 요청/주소 덮어쓰기 허용 | `P2pWithdrawService` 322~330행 |
| 4 | 수동확인 버튼이 원탭 즉시 정산(`confirmBankTransfer`→`startSettlementForMatch`) — 오터치 시 USDT 지급, 회수는 분쟁뿐 | `P2pMatchingService` 694~739행 |
| 5 | 대시보드 "판매 대기 금액"이 확인 기준 집계라 매칭 진행 중 금액이 차감 안 됨 (100만 주문 60만 매칭 시 200만 표시) | `P2pWithdrawPageController` 111~114행 |
| 6 | 다중 주문 시 정보 분산 — 통합 뷰 없음. `createOrder`에 동시 활성 주문 가드도 없음(§4-4 결정 필요) | `P2pWithdrawService.createOrder` |
| 7 | SETTLING("정산 중")이 회원에게 노출되나 회원이 할 일 없음 | `confirmBankTransfer` 730행, `P2pSettlementService` 687행 |

---

## 1. 핵심 원칙 — 금액 3분류가 공통 언어

모든 화면(대시보드·상세·내역·반환 카드)이 아래 3분류만 사용한다. **프론트 재계산 금지 — 백엔드가 응답으로 내려준다**(§4-1).

```
받음        confirmedKrw = confirmed_amount
들어오는 중  inTransitKrw = matched_amount − confirmed_amount   (활성 매칭: CREATED/BANK_PENDING/DISPUTED)
구매자 대기  waitingKrw   = krw_amount − matched_amount          (미매칭 잔여 — USDT 반환의 유일한 대상)
```

- 매칭 취소/만료 시 `matched_amount`가 줄어 `waiting`으로 자동 복귀 — 별도 상태 불필요.
- 히어로/진행바는 세 값을 색으로 표현: 받음 `#0F6E56`(green) / 들어오는 중 `#BA7517`(amber) / 대기 회색.

## 2. 상태 매핑 표 (백엔드 ↔ 회원 문구)

### 2.1 출금 주문 (p2p_withdraw_orders.status)

| 백엔드 | 회원 표시 | 비고 |
|---|---|---|
| PENDING | 구매자 찾는 중 | 진행바 0% |
| PARTIALLY_MATCHED / MATCHED | 입금 받는 중 | 3분류 진행바 |
| SETTLING | **완료** | 뱃지는 완료로 합침. 상세 하단에만 "코인 전달 처리 중" 소표기. `bank_confirmed_at`(전액 확인 시각) 기준 30분 초과 시 "처리가 지연되고 있어요 — 문의하기"로 전환 |
| COMPLETED | 완료 | |
| CANCELLED / EXPIRED | 취소 / 만료 | 진행바·스텝 숨김(기존 유지) |

### 2.2 매칭 (p2p_matches.status) — 상세 "입금 내역" 건별

| 백엔드 | 자동확인 모드 | 수동확인 모드 |
|---|---|---|
| CREATED | 구매자 준비 중 | 구매자 준비 중 (확인 버튼 노출하되 카드 톤 낮춤) |
| BANK_PENDING | 구매자가 보내는 중 · 자동으로 확인돼요 | **확인 대기** (경고 카드 승격 + 버튼 강조) |
| BANK_CONFIRMED / SETTLING / SETTLED | 받음 · HH:mm | 동일 |
| DISPUTED | 확인 중 (분쟁) — 빨간 톤 유지 | 동일 |
| CANCELLED / FAILED | 무효 (흐리게, 기존 opacity 유지) | 동일 |

용어 교체: "매칭 내역"→**입금 내역**, "이체 대기"→위 표, "부분 매칭" 뱃지→불필요(진행바가 대체).

## 3. 화면 스펙

### 3.1 대시보드 (DashboardView)

구조(위→아래): 인사+설정 아이콘 → **조건부 슬롯 스택** → 히어로 → 진행 중 거래(최대 3건 + 전체 보기) → 지난 거래 → CTA.

**조건부 슬롯** — 우선순위순, 동시 최대 2개:

| 순위 | 슬롯 | 노출 조건 | 동작 |
|---|---|---|---|
| 1 | 거래중지 배너 | `trading_paused=1` | "새 매칭이 잡히지 않아요 · 진행 중 거래는 계속돼요" + **영업 재개** 버튼(원탭 허용 — 리스크 없는 방향). 거래중지 행동 자체는 설정에서만 |
| 2 | 확인할 입금 N건 | 수동확인 대상 매칭(BANK_PENDING) 존재 | 1건이면 확인 시트 직행, 복수면 해당 거래 상세 목록으로 |
| 3 | 텔레그램 연결 안내 | 수동확인 모드 && 텔레그램 미연결 | "연결하면 입금 확인 요청을 바로 받아요" → 설정 딥링크 |
| 4 | 계좌 등록 카드 | 계좌 미등록 | 히어로 대신 노출. "입금받을 계좌를 등록해 주세요" + 등록 CTA |

**히어로**: "판매 진행 중 · N건" + 총액(KRW/USDT) + 3분류 진행바 + 칩 3개. 거래중지 상태에선 중립 톤으로 강등.

**제거 (설정으로 이관)**: 계좌 카드(등록 후), 빠른조회 연결 상태/D-day, "판매 시작·거래 시작" 버튼(판매 생성은 파트너 사이트 영역 — 회원이 여기서 시작하는 개념 아님).

**CTA**: "거래 내역 전체 보기" 하나만.

### 3.2 거래 상세 (OrderDetailView)

- 스텝퍼(등록→매칭→입금확인→정산) **제거** → 금액 흐름 바(3분류) + 칩.
- "입금 내역" 건별 카드: 금액 + 보낸 분(buyerName) + §2.2 상태 문구.
- 수동확인 모드: 건별 `[N원 받았어요]` 버튼 → §3.3 공통 시트. 자동 모드: 버튼 없음, "입금되면 자동으로 확인돼요 · 보통 10분 이내".
- **USDT 반환 카드**: `waitingKrw > 0`일 때만. 문구 "구매자를 못 찾은 {waiting}원을 USDT로 돌려받을 수 있어요". `inTransit`만 있고 waiting=0이면 미노출. (§4-2 백엔드 가드와 쌍)
- 하단: "문제가 있나요? 도움받기" (분쟁 진입, 기존 유지).

### 3.3 수동확인 시트 — 공통 단일 컴포넌트

**진입점 3곳이 전부 이 시트로 수렴** (matchId로 특정): ① 대시보드 슬롯 ② 상세 건 카드 버튼 ③ 텔레그램 알림 딥링크(`P2P_MEMBER_TELEGRAM_GUIDE.md` 연계).

내용: 제목 "이 입금을 통장에서 확인하셨나요?" + 경고 "확인하면 바로 코인이 지급되고 되돌릴 수 없어요." + 정보(입금 금액/보낸 분/요청 시각) + **대조 체크박스** "통장에서 {금액}·{보낸분} 입금을 직접 확인했어요" (체크 전 확정 버튼 비활성) + `[아직이에요 / 받았어요, 완료]`.

### 3.4 거래 내역 (OrdersView)

- 탭: 진행 중 N / 끝난 거래.
- 행: 금액+USDT, §2.1 상태 문구, 3분류 미니 진행바, 서브라인(예: "받음 90만 · 들어오는 중 60만" / "아직 매칭 전 · 언제든 USDT로 돌려받기 가능").

## 4. 백엔드 변경 목록 (open-api / core)

1. **3분류 응답 필드**: 대시보드·상세·목록 응답에 `matchedAmount`(또는 `confirmedKrw/inTransitKrw/waitingKrw` 계산 완료값) 추가. 기존 `pendingKrw` 등 필드는 호환 유지. 상세는 order.matched_amount가 소스 오브 트루스(프론트 합산 금지).
2. **`requestUsdtConvert` 가드**: ① `status ∈ {PENDING, PARTIALLY_MATCHED}`만 허용 ② `usdtConvertStatus == null` 확인(중복/덮어쓰기 차단) ③ `waitingKrw > 0` 필수. 전환 승인 시 활성 매칭 강제취소(Fix B)는 안전망으로 유지하되, 요청 단계에서 미매칭 잔여 기준으로 받으므로 정상 흐름에서 발동하지 않게 됨. **전환 금액도 waiting 기준으로 변경 검토** — 현행 `computeRemainder`(krw−confirmed)는 진행 중 매칭 몫까지 전환함 (§0-2와 동일 뿌리, 구현 시 확정).
3. **`confirm-deposit` 강화(선택)**: `amount` 파라미터 추가 — 서버에서 매칭 금액과 대조, 불일치 시 409. 감사 로그(회원 확인 vs 스크래핑 확인 구분은 기존 `bankTransferRef=WITHDRAWER_CONFIRM` 유지).
4. **(결정 필요) `createOrder` 동시 활성 주문**: 현행 무가드(허용). backend `CLAUDE.md`의 "동일 계좌 동시 활성 주문 불가" 문구와 불일치. 이번 재설계로 다중 주문 UX가 수용 가능해졌으므로 **"허용"으로 정책 확정하고 CLAUDE.md 문구를 정정**하는 쪽을 권장 — 반대로 확정 시 createOrder에 가드 추가.
5. **SETTLING 지연 표기**: 프론트 판정으로 충분 — 전액 확인 시각 이후 30분 경과 && status=SETTLING이면 지연 문구. 별도 API 불필요.

## 5. 카피 표 (확정 문구)

| 위치 | 문구 |
|---|---|
| 히어로 라벨 | 판매 진행 중 · N건 |
| 3분류 칩 | 받음 / 들어오는 중 / 구매자 대기 |
| 확인 슬롯 | 확인할 입금 N건 · {금액}원 — 통장 확인 후 완료해 주세요 |
| 거래중지 배너 | 거래중지 중 — 새 매칭이 잡히지 않아요 · 진행 중 거래는 계속돼요 [영업 재개] |
| 계좌 카드 | 입금받을 계좌를 등록해 주세요 — 판매 대금(원화)을 받을 본인 계좌가 필요해요 |
| 자동확인 안내 | 입금되면 자동으로 확인돼요 · 보통 10분 이내 |
| 수동확인 안내(상세) | 이 계좌는 자동 확인이 안 돼요. 통장에서 확인 후 건별로 완료해 주세요 |
| 확인 시트 경고 | 확인하면 바로 코인이 지급되고 되돌릴 수 없어요 |
| 반환 카드 | 구매자를 못 찾은 {waiting}원을 USDT로 돌려받을 수 있어요 |
| SETTLING 소표기 | 코인 전달을 마무리하고 있어요 · 회원님이 하실 일은 없어요 |
| SETTLING 지연 | 처리가 지연되고 있어요 — 문의하기 |

## 6. 구현 순서

- **P0 (안전장치 — IA 개편과 무관하게 먼저)**: §4-2 전환 가드 + §3.2 반환 카드 waiting 기준 + §3.3 수동확인 2단계 시트(현행 화면에 끼워도 됨)
- **P1 (IA 개편)**: 3분류 응답(§4-1) → 대시보드(§3.1) → 상세(§3.2) → 내역(§3.4)
- **P2**: 텔레그램 딥링크 진입(별도 가이드 구현 시), §4-3 금액 대조 API, §4-4 정책 확정 반영

## 7. 시안 근거 (합의된 결정)

- 판매 시작 CTA 제거 — 판매 생성은 파트너 영역, 회원 제어는 거래 상태(재개/정지)뿐. 재개=대시보드 원탭 허용, 정지=설정에서만 (2026-07-13 합의)
- SETTLING은 회원 뱃지에서 "완료"로 합침 + 상세 소표기 + 지연 시 문의 전환 (2026-07-13 합의)
- 빠른조회는 필수 아님 → 대시보드 노출 제거, 설정 전용 (2026-07-13 합의)
- 확인 시트 진입점 3곳(대시보드/상세 건 카드/텔레그램) 단일 컴포넌트 수렴 (2026-07-13 합의)