# P2P 출금회원 설정 화면 — 프론트/디자인 핸드오프

> 작성: 2026-07-10 (Cowork) · 대상: `cryptoments-admin/p2p-ui`(Vue, 모바일) 작업자 + 디자인
> 백엔드 상세: `P2P_MEMBER_SETTINGS_GUIDE.md`, `P2P_MEMBER_TELEGRAM_GUIDE.md`
> 이 문서는 **화면·상태·API 계약·카피** 중심. 서버 내부 로직은 위 지침서 참조.

## 0. 한눈에

P2P 출금회원 페이지(`/m/{memberToken}` → PIN 인증)에 **설정 화면**을 신설한다.
기존 `p2p-ui`는 대시보드/계좌등록/거래내역만 있고 **설정 화면이 없다** → 신규 `SettingsView` 추가.

설정 5개 섹션: ① 계좌 관리 ② 거래 상태(중지/시작) ③ 빠른조회 인증(스크래핑) ④ 입금방식(자동/수동) ⑤ 텔레그램 연동.

**출시 단계**
- **Phase A** (먼저): ①수정·②거래중지·③상태노출·④토글저장·⑤텔레그램 연결 — 이 화면 대부분.
- **Phase B** (후속): ④ 수동모드의 "텔레그램 입금확인" 동작. Phase B 전에도 화면은 완성되며, 수동 선택 시 "수동 확인은 준비 중" 안내만.

> ⚠️ 아래 API 중 다수는 **신규(설계·미구현)**. 실제 연동 전 백엔드와 스펙 최종 확정 필요. 각 표에 `상태` 표기.

## 1. 진입점 / 내비게이션

- 대시보드(`DashboardView`) 상단/하단에 **⚙️ 설정** 진입 버튼.
- 라우트 예: `/settings` (세션 필요 — 미인증 시 PIN 화면으로).
- 모바일 단일 컬럼(`MobileLayout` 재사용). 섹션은 카드형 5개, 세로 스택.
- 상단 헤더: "설정" + 뒤로가기.

## 2. 화면 구조 (IA)

```
[설정]
 ├─ 1. 계좌 관리          … 계좌 카드 리스트 + [계좌 추가]
 │     └ 계좌 카드: 은행/번호(마스킹)/예금주 + 인증배지 + [수정][재인증][삭제]
 ├─ 2. 거래 상태          … 토글 (영업중 ⇄ 거래중지) + 상태 설명
 ├─ 3. 빠른조회 인증       … 계좌별 인증상태(유효/만료임박/필요) + [인증하기/재인증]
 ├─ 4. 입금방식           … 세그먼트 (자동 | 수동) + 수동 설명/경고
 └─ 5. 텔레그램 연동       … 연결상태 + [연결하기(딥링크)] / 알림토글 / [연결 해제]
```
> ③은 ①의 계좌 카드와 데이터가 겹친다(계좌별 스크래핑 상태). **디자인 선택**: ③을 독립 섹션으로 둘지,
> ①계좌 카드 안에 인증배지+버튼으로 합칠지. 권장: **①카드에 통합** + ③은 "만료 임박 계좌" 요약만.

## 3. 섹션별 상세

### ① 계좌 관리

계좌 카드 리스트(회원은 다계좌 가능). 카드 요소: 은행명, 계좌번호(마스킹 `***-**-1234`), 예금주,
인증 배지(③), 액션 `[수정] [재인증] [삭제]`.

| 액션 | API | 메서드 | 상태 |
|------|-----|--------|------|
| 목록 | `/p2p/page/settings` (accounts[]) 또는 대시보드 | GET | accounts는 기존, settings 신규 |
| 은행 목록(등록 폼) | `/p2p/page/banks` | GET | 기존 |
| 등록(+빠른조회) | `/p2p/page/account` | POST | 기존 |
| **수정(예금주)** | `/p2p/page/account` | PUT | **신규** |
| 재인증 | `/p2p/page/account/re-auth` | POST | 기존 |
| 삭제 | `/p2p/page/account?accountId=` | DELETE | 기존 |

- **수정 범위**: 예금주명 등 비식별 필드만. 은행/계좌번호 변경은 "삭제 후 재등록"으로 안내(수정 불가).
- 삭제: 진행 중 출금이 있으면 서버가 `409 BANK_ACCOUNT_IN_USE` → 토스트 "진행 중 거래가 있어 삭제할 수 없어요."
- 등록 폼 필드: 은행 선택, 계좌번호, 예금주, (빠른조회 시)자격증명. → ③ 참고.

### ② 거래 상태 (중지/시작)

토글 1개. `영업중`(기본) ⇄ `거래중지`.

| 액션 | API | 메서드 | 상태 |
|------|-----|--------|------|
| 조회 | `/p2p/page/settings` (tradingStatus) | GET | 신규 |
| 변경 | `/p2p/page/settings/trading-status` | PUT | 신규 |

요청: `{ "status": "ACTIVE" | "PAUSED" }`

- **의미(카피 중요)**: 거래중지 = **새 매칭만 멈춤**. 이미 매칭·정산 중인 건은 계속 진행됨.
  - 토글 ON→중지 시 확인 문구: "거래중지 시 새로운 매칭이 잡히지 않아요. 진행 중인 거래는 그대로 완료됩니다."
  - 중지 상태 배너: "🔴 거래중지 중 — 새 매칭이 잡히지 않습니다. [영업 재개]"
- 로그인·조회·계좌관리·출금내역은 중지와 무관하게 정상.
- 관리자에 의한 계정 정지(로그인 불가)와는 다른 개념 — 이 토글은 회원 본인용.

### ③ 빠른조회 인증 (CODEF 스크래핑)

계좌별 인증 상태 표시 + 인증/재인증 액션. (①과 통합 권장)

- 상태값(배지): `유효`(ACTIVE) / `만료 임박`(≤N일) / `인증 필요`(미인증·EXPIRED·REVOKED).
- `reauthRequired=true`면 강조(주황). 만료일 `consentExpiresAt` 표시.
- 인증/재인증은 자격증명 입력 폼 → `POST /account`(신규 등록 시) 또는 `/account/re-auth`(기존 계좌).
- 자격증명 입력 필드는 **CODEF 빠른조회용 금융 로그인 정보**(형식은 백엔드와 확정 — `credentialJson` blob).
  민감정보 → 마스킹 입력·전송 후 화면 미보관.
- 은행별 빠른조회 지원여부는 `/p2p/page/banks`의 `autoConfirmSupported`로 분기.
  - **자동확인 은행**: 빠른조회 인증 필요(자격증명 입력).
  - **수동확인 전용 은행(인터넷은행 등)**: 자격증명 불필요, 입금방식이 자동 강제 수동 처리. "이 은행은 수동 확인 전용이에요 — 텔레그램 연결이 필요합니다" 안내 + ⑤ 연결 유도.

### ④ 입금방식 (자동 | 수동)

세그먼트 컨트롤 2택. 기본 `자동`.

| 액션 | API | 메서드 | 상태 |
|------|-----|--------|------|
| 조회 | `/p2p/page/settings` (depositMethod) | GET | 신규 |
| 변경 | `/p2p/page/settings/deposit-method` | PUT | 신규 |

요청: `{ "method": "AUTO" | "MANUAL" }`

- **자동**: 입금이 시스템(빠른조회)으로 자동 확인됨. (권장 기본)
- **수동**: 부재중 등 특별한 사유로 **입금을 직접 확인**할 때. 빠른조회 자동확인 대신,
  구매자 입금 시 **텔레그램으로 "입금 확인 요청"이 오고 버튼으로 직접 확인**한다.
  - ※ **인터넷은행 등 수동확인 전용 은행 계좌는 이 토글과 무관하게 항상 수동**으로 동작(자동확인 불가). → 텔레그램 연결 필수.
  - **확정 카피(2026-07-15, A안)** — 설명문(시안): "입금을 직접 확인합니다. 구매자 입금 시 확인 요청을 처리해요." + 주의 박스 한 줄:
    **"수동은 입금을 직접 확인해야 해요. 10분 이내 확인을 권장하며, 텔레그램 연결이 필요합니다."**
    (상세 규칙 — 지연 시 관리자 확인·신고 안내 — 는 수동확인 시트/텔레그램 메시지에서 맥락상 노출, 설정 화면엔 미포함)
  - **텔레그램 미연결 상태에서 수동 선택 → ⑤ 연결 유도**(수동은 텔레그램 없으면 확인 수단이 없음).
  - Phase B 미배포 구간: 수동 선택 시 "수동 확인 기능은 준비 중이에요"(자동으로 처리됨) 안내.

### ⑤ 텔레그램 연동

연결 상태 + 연결/토글/해제.

| 액션 | API | 메서드 | 상태 |
|------|-----|--------|------|
| 상태 조회 | `/p2p/page/telegram` | GET | 신규 |
| 연결 링크 발급 | `/p2p/page/telegram/connect-token` | GET | 신규 |
| 알림 on/off | `/p2p/page/telegram/notify` | PUT | 신규 |
| 연결 해제 | `/p2p/page/telegram` | DELETE | 신규 |

- 미연결: `[텔레그램 연결하기]` 버튼 → `connect-token` 호출 → 응답 `deepLink`(`https://t.me/cryptoments_p2p_bot?start=m_...`)를
  **새 탭/딥링크로 오픈**. 텔레그램 앱에서 봇 대화 열림 → 자동 연결.
  - 응답: `{ "deepLink": "...", "expiresIn": 300 }` (5분 만료 → 만료 시 재발급).
  - 연결 완료는 텔레그램 쪽에서 처리되므로, 화면은 복귀 후 상태 폴링/새로고침으로 `connected=true` 반영.
- 연결됨: "✅ 연결됨" + 알림 수신 토글(`notifyEnabled`) + `[연결 해제]`.
- 해제 확인: "연결을 해제하면 알림을 받을 수 없어요. (수동 입금방식은 확인이 어려워집니다)".

## 4. 통합 조회 API — `GET /p2p/page/settings` (신규)

설정 화면 진입 시 1회 호출로 전 섹션 초기 상태 로드.

```json
{
  "tradingStatus": "ACTIVE",              // ACTIVE | PAUSED
  "depositMethod": "AUTO",                // AUTO | MANUAL
  "telegram": { "connected": true, "notifyEnabled": true },
  "manualPendingCount": 0,                // 수동: 확인 대기 중인 입금 건수(배지용, Phase B)
  "accounts": [
    {
      "id": 12, "bankCode": "048", "bankName": "신협",
      "accountNumber": "***-**-1234", "accountHolder": "홍길동",
      "scrapingStatus": "ACTIVE",         // ACTIVE | EXPIRED | REVOKED | CREATED
      "consentExpiresAt": "2027-06-26T00:00:00",
      "reauthRequired": false
    }
  ]
}
```
> 필드명은 제안값 — 백엔드 확정 시 소폭 변동 가능. 프론트는 optional/누락 방어.

## 5. 수동(MANUAL) 입금확인 — 화면 관점 (Phase B)

**확인(positive)** 은 텔레그램 원탭 버튼에서 끝난다(앱 화면 아님). **"입금이 안 왔어요/문제"(negative)** 는
텔레그램 URL 버튼이 **위젯 페이지를 열어 PIN 인증 후** 처리 → 이 페이지가 **프론트 신규 작업**. p2p-ui가 할 일:

1. 입금방식이 수동인데 텔레그램 미연결이면 **강한 유도 배너**: "수동 확인은 텔레그램 연결이 필요해요."
2. 거래 상세(`OrderDetailView`)/대시보드에 **수동 확인 대기 배지**(`manualPendingCount`) 노출 — "확인 대기 N건".
3. 위젯에도 **[입금 확인] 버튼 유지**(텔레그램을 못 쓸 때 백업 경로):
   기존 `POST /p2p/page/orders/{code}/confirm-deposit/{matchId}` 재사용.
4. **문제 신고 화면(신규)** — 텔레그램 "입금이 안 왔어요" 버튼의 딥링크 도착지.
   - 진입: `/m/{memberToken}#/orders/{orderCode}?match={matchId}` → PIN 인증.
   - 액션: 재확인(위 confirm) 또는 **문제 신고 폼**(사유: 입금없음/금액상이/기타 + 증빙 첨부).
   - 신규 API: `POST /p2p/page/orders/{code}/matches/{matchId}/report` `{reason, evidenceUrl?}` → 회원(출금자) 분쟁 제기.

텔레그램 메시지(참고, 프론트 구현 아님):
- C1 "입금 확인 요청" + 버튼 `[✅ 입금 확인](원탭) [⚠️ 입금이 안 왔어요](페이지)`
- C2 리마인더(미확인 시) / C3 에스컬레이션(기한 임박)

## 6. 공통 상태 / 엣지 / 카피

- **로딩**: 각 섹션 스켈레톤. 저장 액션은 낙관적 업데이트 + 실패 시 롤백.
- **빈 상태(계좌 0개)**: "등록된 계좌가 없어요. 계좌를 추가하고 빠른조회 인증을 받아 주세요." + `[계좌 추가]`.
- **에러 토스트**: 409(사용중/중복), 404(계좌·주문 없음), 401(세션 만료→PIN 재인증), 5xx(잠시 후 재시도).
- **세션 만료**: p2p-ui 기존 정책(sessionStorage + 30분 무활동) 준수 — 만료 시 PIN 화면.
- **접근성/모바일**: 토글·세그먼트 큰 터치 타깃, 민감정보(계좌·자격증명) 마스킹.

## 7. 디자인 결정 필요 (열린 항목)

1. ③ 빠른조회를 **독립 섹션 vs ①계좌 카드 통합** (권장: 통합).
2. ④ 수동 선택 시 텔레그램 미연결 처리: **강제 연결 유도 vs 경고만**.
3. 수동 확인 대기 배지 위치(대시보드/거래상세/설정 중).
4. 거래중지 배너 스타일/노출 범위(설정 안 vs 전 화면 상단).
5. Phase B 전 "수동 준비 중" 처리: **수동 옵션 비활성 vs 선택가능+안내**.

## 8. 범위 밖 (백엔드/기타 담당)

- 매칭·정산·빠른조회(CODEF) 호출, 텔레그램 봇 콜백/발송, 내부 확인 엔드포인트 → 백엔드.
- 텔레그램 인라인 버튼 UX는 텔레그램 봇 메시지(디자인 대상 아님).
- 신협 등 은행별 빠른조회 지원/문구는 백엔드 `banks` 응답 기반.

---
### 부록. 엔드포인트 요약 (프론트 연동표)

| 섹션 | 메서드 · 경로 | 상태 | 비고 |
|------|---------------|------|------|
| 공통 | GET `/p2p/page/settings` | 신규 | 초기 로드 |
| ① | GET `/p2p/page/banks` | 기존(+`autoConfirmSupported` 신규필드) | 자동/수동 은행 그룹핑 |
| ① | POST `/p2p/page/account` | 기존 | 등록(+빠른조회) |
| ① | PUT `/p2p/page/account` | 신규 | 수정(예금주) |
| ① | POST `/p2p/page/account/re-auth` | 기존 | 재인증 |
| ① | DELETE `/p2p/page/account` | 기존 | 삭제 |
| ② | PUT `/p2p/page/settings/trading-status` | 신규 | ACTIVE/PAUSED |
| ④ | PUT `/p2p/page/settings/deposit-method` | 신규 | AUTO/MANUAL |
| ⑤ | GET `/p2p/page/telegram` | 신규 | 연결상태 |
| ⑤ | GET `/p2p/page/telegram/connect-token` | 신규 | 딥링크 |
| ⑤ | PUT `/p2p/page/telegram/notify` | 신규 | 알림 on/off |
| ⑤ | DELETE `/p2p/page/telegram` | 신규 | 해제 |
| 수동(B) | POST `/p2p/page/orders/{code}/confirm-deposit/{matchId}` | 기존 | 위젯 백업 확인 |
| 수동(B) | POST `/p2p/page/orders/{code}/matches/{matchId}/report` | 신규 | 문제 신고(출금자 분쟁) |