# P2P 매칭 — 그룹 범위 + LP 라우팅 지침서 (DDL v2.9) 작성일: 2026-08-13 대상: Cowork 서브에이전트 (구현) 선행: P2P 수수료 재설계 v2.8 (`67b4dc0` / `137d0b3` / admin `3cbbabc`), 웹훅 재정의 (`5432258` / admin `947c515`) --- ## 1. 목적 최상위 총판(그룹) 단위로 **자기 그룹 안에서만 매칭할지, 외부 그룹과도 매칭할지**를 제어한다. 그룹이 자립 가능한 유동성을 갖추면 격리해 운영하고, 그전까지는 전체 풀을 공유해 매칭률을 확보하기 위함이다. ### 결정 사항 | 항목 | 결정 | |---|---| | 기본값 | **크로스 매칭 허용** (`TRUE`) | | 설정 단위 | **최상위 총판 1개 필드.** 하위 파트너는 상속만 하고 개별 설정 없음 | | 설정 주체 | **어드민 전용.** 파트너 콘솔에 노출하지 않는다 | | 크로스 판정 | **양쪽 그룹이 모두 허용**해야 성립. 한쪽이라도 "내부만"이면 불가 | | 같은 그룹 | 설정과 무관하게 **항상 매칭** | | 그룹 판정 | `partners.root_partner_id` 비정규화 컬럼 | ### 판정 매트릭스 | | 출금 그룹 내부만 | 출금 그룹 외부 허용 | |---|---|---| | **입금 그룹 내부만** | 크로스 불가 | 크로스 불가 | | **입금 그룹 외부 허용** | 크로스 불가 | **크로스 가능** | 양쪽 AND 로 판정하는 이유 — 한쪽 설정만 보면 "내부만"으로 걸어둔 그룹의 유동성이 외부로 새거나, 반대로 그 그룹의 구매자가 외부 유동성에 붙는다. "내부만"이 확실한 격리를 보장해야 한다. ### 레그별 적용 범위 — ⚠️ 이 설정은 P2P 레그에만 걸린다 폴백 체인 3단계 중 **P2P 레그의 후보 풀만** 좁힌다. 나머지 두 레그는 **현행 그대로** 동작한다. | 레그 | 그룹 제한 | 근거 | |---|---|---| | ① P2P | **적용** | 파트너 간 유동성 거래. 격리 대상이 바로 이것 | | ② TORQ (LP) | **미적용** | 다른 그룹이 아니라 **유동성 공급원**이다. 그룹 격리와 성격이 다르다 | | ③ PARTNER | **미적용** | 구매자가 **입금 파트너 자신의 서비스 계좌**로 이체하는 FIAT 경로. 애초에 자기 자신이라 그룹 개념이 없다. USDT 가 플랫폼에서 이동하지 않아 잠금·게이트도 없고, 서비스 계좌만 있으면 항상 성립하는 최종 안전망 | 즉 **"내부만"으로 걸어도 폴백 체인은 그대로다.** 내부 P2P 유동성이 부족하면 기존과 동일하게 TORQ → PARTNER 로 넘어간다. 바뀌는 것은 ① 단계에서 볼 수 있는 출금 주문 후보뿐이다. > **재검토 지점** — 이 정의는 "그룹 격리 = P2P 상대 제한"이라는 현재 판단에 기반한다. 그룹이 완전 자립(외부 LP 도 쓰지 않음)을 원하는 단계가 오면 LP 사용 여부를 별도 필드로 분리해야 한다. `p2p.torq_fallback_enabled` 가 현재 글로벌 설정으로만 존재한다. ### 범위 밖 (다음 작업) - `p2p.max_p2p_legs` (현재 2) - 후보 정렬 기준 (현재 잔여 DESC → FIFO) --- ## 2. 왜 `root_partner_id` 인가 현재 운영 트리는 **최대 깊이 1단**이다(전체 53곳 중 36 루트 + 17 자식, 2단 이상 0). 그래서 `COALESCE(parent_partner_id, id)` 로도 루트를 구할 수 있다. **그러나 다층 그룹이 들어올 예정이다.** 손자 파트너가 생기는 순간 `COALESCE` 는 부모를 루트로 잘못 잡는다. 실제로는 다른 그룹인데 같은 그룹으로 판정하거나 그 반대가 되고, **에러 없이 조용히 틀린다.** 지금 깊이가 얕을 때 컬럼을 넣으면 백필이 한 줄이다. 다층이 들어온 뒤에 발견하면 이미 잘못된 매칭이 쌓여 있다. 동기화 지점은 하나다 — **파트너 생성 시 부모의 `root_partner_id` 복사**(부모가 최상위면 부모의 `id`). 파트너 이동 기능은 현재 없으므로 대상이 아니다. > ⚠️ 파트너 이동(부모 변경) 기능을 나중에 추가하면 **하위 서브트리 전체의 `root_partner_id` 를 갱신**해야 한다. 컬럼 주석에 이 사실을 남길 것. --- ## 3. DDL (v2.9) ### 3.1 헤더 개정 ``` -- ║ v2.9 (2026-08-13): P2P 매칭 그룹 범위 제어 — ║ -- ║ partners.root_partner_id (최상위 총판 비정규화) + ║ -- ║ p2p_cross_group_matching (최상위에만 의미, 기본 허용). ║ -- ║ 양쪽 그룹이 모두 허용해야 크로스 매칭 성립. ║ -- ║ 지침서: v2-docs/P2P_MATCHING_GROUP_SCOPE_GUIDE.md ║ -- ║ 테이블 수 변화 없음(54개) ║ ``` ### 3.2 ALTER ```sql ALTER TABLE partners ADD COLUMN root_partner_id BIGINT NULL COMMENT '최상위 총판 id (비정규화). 자기 자신이 최상위면 자기 id. 생성 시 부모 값 복사. ⚠️ 파트너 이동(부모 변경) 기능 추가 시 하위 서브트리 전체를 갱신해야 한다 (v2.9)' AFTER parent_partner_id, ADD COLUMN p2p_cross_group_matching BOOLEAN NOT NULL DEFAULT TRUE COMMENT 'P2P 크로스 그룹 매칭 허용 — 최상위 총판 행에만 의미(하위는 루트 값을 따름). FALSE: 자기 그룹 안에서만 매칭. 크로스는 양쪽 그룹이 모두 TRUE 여야 성립. 어드민 전용 설정 — 파트너 콘솔 미노출 (v2.9)' AFTER root_partner_id; CREATE INDEX idx_root_partner ON partners (root_partner_id); -- LP 라우팅 (§6) ALTER TABLE partners ADD COLUMN lp_provider VARCHAR(20) NULL COMMENT 'LP 공급자 (TORQ / TORQ2) — 최상위 총판 행에만 의미(하위는 루트 값을 따름). NULL = TORQ. LP 장애 시 다른 LP 폴백 없음. TORQ2 는 리베이트 없음. 레그 수령 네트워크도 이 값이 정한다(구매자 선택 아님) (v2.9)' AFTER p2p_cross_group_matching; ALTER TABLE torq_trades ADD COLUMN lp_provider VARCHAR(20) NOT NULL DEFAULT 'TORQ' COMMENT 'LP 공급자 (TORQ / TORQ2) — 웹훅 라우팅·리베이트 집계의 유일한 근거. escrow_id 는 provider 간 유일하지 않으므로 조회는 반드시 (lp_provider, escrow_id) 로 한다. 리베이트는 TORQ 만 (v2.9)' AFTER partner_user_id; -- ⚠️ 운영 실측: 인덱스명은 idx_escrow_id 이고 NON-unique 다 (DDL 파일은 uk_escrow_id UNIQUE 로 -- 적혀 있었으나 운영과 어긋나 있었다 — v2.9 에서 파일을 운영 기준으로 정정). -- 현재 데이터는 escrow_id 가 유일하므로(1305/1305) 복합 UNIQUE 추가는 무손실로 성공한다. ALTER TABLE torq_trades DROP INDEX idx_escrow_id, ADD UNIQUE KEY uk_lp_escrow_id (lp_provider, escrow_id); -- tx_hash 는 UNIQUE 로 만들지 않는다 — idx_tx_hash(NON-unique) 유지. 근거는 아래 참조. ``` > **`torq_trades.tx_hash` 에 UNIQUE 를 걸지 않는 이유** > > 이 컬럼은 **LP 의 릴리스 tx** 다. 한 행 = 한 escrow 이므로 두 행이 같은 해시를 갖는 경우는 **LP 가 여러 escrow 를 한 트랜잭션으로 묶어 보낼 때**다. TORQ 는 escrow 단위로 릴리스해 실측 1176 건이 전부 distinct 지만, 그것은 **TORQ 의 구현 특성이지 우리가 강제한 계약이 아니다.** 동작을 모르는 LP(TORQ2)를 붙이려는 시점에 배치 전송을 금지하는 제약을 거는 것은 위험하다. > > DDL 파일이 `uk_torq_trades_tx_hash` UNIQUE 로 선언하고 운영이 `idx_tx_hash` NON-unique 였던 드리프트는 **파일을 운영에 맞추는 방향으로** 해소한다 (v2.9). > > ⚠️ 대신 **`TorqTradeRepository.findByTxHash` 가 단건 반환이라 중복 발생 시 `TooManyResultsException` 이 난다.** 호출부가 `BusinessEventClassifier` / `WebhookProcessingService` 라 웹훅 처리가 통째로 멎는다. `findByP2pMatchId` 와 동일하게 **List 반환 + 결정적 선택**으로 바꿔야 한다 (별도 항목). > ⚠️ **`p2p_match_id` 에는 UNIQUE 를 걸 수 없다.** 매칭 855 에 `torq_trades` 2행(id 808/escrow 810 CANCELLED, id 809/escrow 812 COMPLETED)이 실재한다 — 2026-07-22 TORQ 금액 불일치 수동 보정의 흔적이고, `p2p_matches.torq_escrow_id` 는 여전히 취소된 810 을 가리킨다. 레그↔거래 1:1 은 **보장되지 않는 가정**이다. §6.3 참조. ### 3.3 백필 ```sql -- 트리 깊이 1단이므로 한 번에 끝난다. 2단 이상이 생긴 뒤라면 재귀 CTE 로 바꿀 것. UPDATE partners SET root_partner_id = COALESCE(parent_partner_id, id); -- 검증 — 루트가 자기 자신이거나, 루트 행의 parent 가 NULL 이어야 한다 SELECT p.id, p.partner_code, p.parent_partner_id, p.root_partner_id, r.parent_partner_id AS root_parent FROM partners p LEFT JOIN partners r ON r.id = p.root_partner_id WHERE p.root_partner_id IS NULL OR (r.parent_partner_id IS NOT NULL); -- 결과 0건이어야 한다 ``` --- ## 4. 구현 ### 4.1 그룹 해석 — `P2pGroupResolver` (신설 또는 기존 서비스에 추가) ```java /** 이 파트너가 속한 그룹(최상위 총판) id */ public Long resolveRootPartnerId(Long partnerId) { ... } /** 이 그룹이 크로스 매칭을 허용하는가 — 루트 행의 값을 읽는다 */ public boolean isCrossGroupAllowed(Long rootPartnerId) { ... } ``` `root_partner_id` 가 있으므로 순회가 필요 없다. 컬럼이 NULL 인 이상 데이터는 **자기 자신을 루트로 폴백**하고 `WARN` 로그를 남긴다(백필 누락 방어). ### 4.2 매칭 후보 SQL — ⚠️ 반드시 SQL 에서 좁힌다 `common/.../mapper/P2pMatchingMapper.java` 의 **세 메서드 전부**에 조건을 추가한다. | 메서드 | 용도 | LIMIT | |---|---|---| | `findMatchableWithdrawOrdersForUpdate` | 통합/분할 매칭 후보 | 10 | | `findExactMatchesForUpdate` | 완전일치 (레거시 경로) | 5 | | `findAvailableWithdrawOrders` | **라우팅 판정용** | 100 | > ⚠️ **`LIMIT` 이 Java 필터보다 먼저 적용된다.** 상위 N건을 DB에서 먼저 잠근 뒤 Java 에서 거르는 구조라, 그룹 조건을 Java 후처리로 넣으면 그 N건이 전부 타 그룹으로 채워져 **후보 0건**이 된다(기아 상태). ```sql JOIN partners wp ON wp.id = o.partner_id AND wp.krw_enabled = 1 AND wp.p2p_withdraw_enabled = 1 AND wp.status = 'ACTIVE' JOIN partners wroot ON wroot.id = wp.root_partner_id ... WHERE ... AND ( wp.root_partner_id = #{depositRootId} OR (#{depositCrossAllowed} = 1 AND wroot.p2p_cross_group_matching = 1) ) ``` - `#{depositRootId}` / `#{depositCrossAllowed}` 는 Java 가 입금 파트너 기준으로 해석해 넘긴다 - 같은 그룹이면 첫 조건에서 통과 — 설정과 무관하게 항상 매칭 - `