사용자·계정·지갑 모델

고객 지갑은 하나의 주소보다 넓은 개념입니다. OOLIN에서는 고객사 식별자 uid에 계정을 연결하고, 계정에서 자산별 잔액·입금 주소·거래 내역을 관리합니다. 고객사 애플리케이션은 이 리소스를 묶어 고객에게 지갑 화면을 제공합니다.

사용자, 계정, 주소의 차이

개념	의미	식별 방법
고객사 사용자·가맹점	고객사 서비스의 로그인·업무 주체	고객사 사용자 ID 또는 가맹점 ID
uid	고객사가 Wallet API에 전달하는 안정적인 사용자·사업자 식별자	계정 생성 시 전달한 문자열
Account	자산 잔액과 거래를 소유하는 단위	OOLIN이 반환한 account_id
Deposit Address	계정에 자산을 입금할 네트워크별 목적지	account_id, asset_type_id, network_id, 주소·memo

하나의 uid에는 여러 계정이 연결될 수 있습니다. uid와 account_id를 같은 값으로 취급하거나 첫 번째 조회 결과를 무조건 고객의 대표 계정으로 선택하지 않습니다. 고객사 서비스에서 어떤 계정이 어떤 역할인지 명시적으로 연결합니다.

고객사 고객 customer-001
  → uid: user-customer-001
    → USER 계정
      → 자산 유형별 잔액: USDT, ETH 등
      → 자산·네트워크별 입금 목적지
      → 입금·출금·원장 내역

고객사 가맹점 merchant-001
  → uid: business-merchant-001
    → BUSINESS 계정
      → 고객 결제 수취 잔액
      → 외부 정산과 원장 내역

위 식별자 문자열은 설계 예시입니다. uid를 정할 때는 고객사에서 중복되지 않고 재가입·서비스 재시작에도 연결 관계를 유지할 수 있는 식별자를 사용합니다.

USER와 BUSINESS의 역할

account_type	일반적인 용도	자금 관리 주체
USER	고객 입금, 잔액 조회, 이체·출금	고객 개인의 지갑
BUSINESS	사업자·운영 주체의 입금, 자금 보관·이체·출금	사업자 또는 가맹점의 지갑

고객 지갑에서는 USER 계정에 외부 입금이 적립되고 해당 계정의 잔액으로 외부 출금을 요청합니다. BUSINESS는 사업자 자금 관리에 사용하며 고객별로 만들 필요는 없습니다.

결제에 활용할 때는 고객 USER 계정에서 가맹점 BUSINESS 계정으로 내부이체합니다. 예를 들어 10 USDT를 결제하면 고객 계정에서 10 USDT가 줄고 가맹점 계정에 10 USDT가 늘어납니다. 일반 계정 간 이체도 같은 자금 이동 방식이며 두 계정은 서로 다른 활성 계정이어야 합니다.

계정 유형은 자금의 업무 역할을 나타냅니다. 고객사 서비스의 관리자 권한이나 로그인 권한을 대신하지 않으며, 고객사 백엔드는 요청마다 계정 소유자와 작업 권한을 확인합니다.

계정 생성과 재사용

POST /accounts는 같은 uid로 추가 계정을 만들 수 있습니다. 계정 준비는 다음 순서로 진행합니다.

1. 고객사에 저장된 고객·계정 연결 정보를 확인합니다.
2. GET /users/{uid}/accounts로 기존 계정을 조회합니다. 계정이 없으면 빈 items가 반환됩니다.
3. 의도한 유형·역할의 활성 계정이 있으면 재사용합니다.
4. 의도한 계정이 없을 때만 생성하고 반환된 account_id를 연결해 저장합니다.

같은 고객의 동시 생성 요청은 고객사 백엔드에서 직렬화합니다. 생성 응답이 유실되면 같은 uid의 계정 목록과 저장된 연결을 먼저 확인합니다. 여러 계정을 허용하는 서비스라면 역할별 선택 규칙을 정합니다.

계정 상태와 자금 이동

status	의미	고객사 처리
ACTIVE	정상 이용 상태	작업별 자산·잔액·권한 조건도 확인
LOCKED	잠금 상태	새 자금 이동 전에 상태와 사유 확인
DISABLED	비활성 상태	이용 가능 상태를 확인한 뒤 업무 진행

계정 상태는 거래의 완료 상태와 다릅니다. 계정이 ACTIVE라고 출금이 완료된 것은 아니며, 계정 잠금이 이미 발생한 거래나 원장을 삭제하지도 않습니다. 입출금 결과는 거래 상세로 확인합니다.

입금 목적지 저장

입금 주소는 계정·자산 유형·네트워크 조합으로 발급받습니다. 하나의 계정에 여러 목적지가 있을 수 있고, 주소 문자열만으로 지원 자산이나 네트워크를 판단할 수 없습니다.

다음 정보를 함께 저장하고 고객에게 필요한 목적지 정보를 표시합니다.

• 계정: account_id
• 자산과 네트워크: asset_type_id, network_id
• 목적지: address, tag_or_memo
• 고객사 연결: 고객·가맹점 ID, 환경, 계정 역할

Memo가 필요한 목적지는 주소와 memo를 한 쌍으로 취급합니다. 내부결제에서는 목적지 주소 대신 수신 account_id를 지정할 수 있습니다.

주소의 역할과 address_id·deposit_id의 차이, 발급·재조회와 고객 화면 구성은 입금 주소에서 자세히 설명합니다.

자산별 잔액과 네트워크별 목적지의 관계는 네트워크와 자산에서 설명합니다. 실제 계정 준비 예제는 사용자와 지갑 계정 생성과 결제 계정 구조 설계를 참고합니다.