콘텐츠로 이동

회원 가입/로그인

회원 가입 프로세스

1. 사용자 생성 API

  • 엔드포인트: POST /api/v1/users
  • 인증 불필요
  • 도메인별 독립적인 사용자 관리

2. 요청 데이터

{
    domain: string;      // 도메인 이름 (필수)
    symId: string;       // 심버스 ID (필수)
    tronAddress: string; // TRON 지갑 주소 (필수)
    nickName?: string;   // 닉네임 (선택)
    referrerCode?: string; // 추천인 코드 (선택)
}

3. 처리 프로세스

  1. 도메인 확인

    • 요청된 도메인이 존재하는지 확인
    • 존재하지 않는 경우 'Domain not found' 에러 발생

  2. 기존 사용자 확인

    • 해당 도메인에 동일한 symId를 가진 사용자가 있는지 확인
    • 있다면 로그인 처리, 없다면 새 사용자 생성

  3. 추천 코드 생성

    • 5자리 숫자로 구성된 고유한 추천 코드 자동 생성 (10000-99999)
    • 시스템 내에서 유일한 값 보장

  4. 추천인 설정

    • 기본적으로 도메인 관리자가 추천인으로 설정
    • referrerCode가 제공된 경우, 해당 코드의 사용자를 추천인으로 설정
    • 잘못된 추천 코드인 경우 'Invalid referral code' 에러 발생

4. 응답 데이터

{
    access_token: string; // JWT 액세스 토큰
    refresh_token: string; // JWT 리프레시 토큰
    user: {
        _id: string;
        symId: string;
        domain: string;
        referralCode: string; // 자동 생성된 5자리 추천 코드
        // ... 기타 사용자 정보
    }
}

5. 제한 사항

  • symId는 도메인 내에서 유일해야 함
  • referralCode는 시스템 전체에서 유일해야 함
  • 추천인은 같은 도메인에 속한 사용자여야 함
  • nickName이 제공된 경우 도메인 내에서 유일해야 함

로그인

API 엔드포인트

POST /v1/users

회원 가입 또는 로그인을 처리합니다.

요청

{
    "domain": "example.com",
    "symId": "0x123...",
    "tronAddress": "TXx2SHKj4NkBpVwN6mMbgXzm8EVeVwpRFz",
    "role": "DOMAIN_USER"
}

필드 설명

  • domain: 사용자가 속한 도메인
  • symId: Symverse 계정의 고유 ID
  • tronAddress: TRON 네트워크의 지갑 주소 (TRC20)
  • role: 사용자 역할 (DOMAIN_USER, DOMAIN_ADMIN, SUPER_ADMIN)

응답

{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....",
    "user": {
        "symId": "test123",
        "domain": "67b2df1451f57701444132bd",
        "role": "DOMAIN_USER",
        "referralCode": "19993",
        "parentId": {
            "_id": "67b2e1576d55b93516e4b23a"
        },
        "referralCount": 0,
        "tronAddress": "TXx2SHKj4NkBpVwN6mMbgXzm8EVeVwpRFz",
        "rewardBalance": 0,
        "referralPath": [],
        "isActive": true,
        "level": 0,
        "_id": "67b53d2c40add8262dfc0631",
        "createdAt": "2025-02-19T02:08:44.285Z",
        "updatedAt": "2025-02-19T02:08:44.285Z",
        "__v": 0
    }
}

오류 응답

{
    "statusCode": 400,
    "message": "tronAddress is required",
    "error": "Bad Request"
}

GET /v1/users

현재 로그인한 사용자의 정보를 조회합니다.

요청 헤더

Authorization: Bearer {access_token}

응답

{
    "_id": "507f1f77bcf86cd799439011",
    "domain": "example.com",
    "symId": "0x123...",
    "tronAddress": "TXx...", // Tron 지갑 주소
    "createdAt": "2024-03-19T..."
}

PATCH /v1/users

사용자 정보를 수정합니다.

요청 헤더

Authorization: Bearer {access_token}

요청

{
    "tronAddress": "TXx..." // Tron 지갑 주소 업데이트
}

응답

{
    "_id": "507f1f77bcf86cd799439011",
    "domain": "example.com",
    "symId": "0x123...",
    "tronAddress": "TXx...", // 업데이트된 Tron 지갑 주소
    "createdAt": "2024-03-19T..."
}

내 정보 조회

GET /api/v1/users/me

로그인한 사용자의 상세 정보를 조회합니다.

1. 요청

  • JWT 인증 필요
  • Bearer 토큰 사용
GET /api/v1/users/me
Authorization: Bearer {access_token}

2. 응답 데이터

{
    _id: string;            // 사용자 고유 ID
    symId: string;          // Symverse 계정 ID
    domain: {               // 도메인 정보
        _id: string;
        name: string;
    };
    role: Role;             // 사용자 권한
    referralCode: string;   // 나의 추천 코드 (5자리 숫자)
    parentId: {             // 추천인 정보
        _id: string;
    };
    referralCount: number;  // 추천한 사용자 수
    tronAddress: string;    // TRON 지갑 주소
    rewardBalance: number;  // 보상 잔액
    referralPath: string[]; // 추천 경로
    isActive: boolean;      // 활성화 상태
    level: number;          // 사용자 레벨
    createdAt: Date;        // 생성일
    updatedAt: Date;        // 수정일
}

3. 응답 예시

{
    "_id": "67b53d2c40add8262dfc0631",
    "symId": "test123",
    "domain": {
        "_id": "67b2df1451f57701444132bd",
        "name": "example.com"
    },
    "role": "DOMAIN_USER",
    "referralCode": "19993",
    "parentId": {
        "_id": "67b2e1576d55b93516e4b23a"
    },
    "referralCount": 0,
    "tronAddress": "TXx2SHKj4NkBpVwN6mMbgXzm8EVeVwpRFz",
    "rewardBalance": 0,
    "referralPath": [],
    "isActive": true,
    "level": 0,
    "createdAt": "2024-02-19T02:08:44.285Z",
    "updatedAt": "2024-02-19T02:08:44.285Z"
}

닉네임 변경

PATCH /api/v1/users/me/nickname

로그인한 사용자의 닉네임을 변경합니다.

1. 요청

  • JWT 인증 필요
  • Bearer 토큰 사용
PATCH /api/v1/users/me/nickname
Authorization: Bearer {access_token}
Content-Type: application/json

{
    "nickname": "홍길동"
}

2. 요청 데이터

{
    nickname: string; // 변경할 닉네임 (2~30자)
}

3. 제한 사항

  • 닉네임은 2~30자 사이여야 합니다.
  • 유효한 문자열이어야 합니다.

4. 응답 데이터

{
    _id: string; // 사용자 고유 ID
    nickName: string; // 변경된 닉네임
    symId: string; // Symverse 계정 ID
    domain: string; // 도메인 정보
}

5. 응답 예시

{
    "_id": "507f1f77bcf86cd799439011",
    "nickName": "홍길동",
    "symId": "user123",
    "domain": "example.com"
}

6. 오류 응답

{
    "statusCode": 400,
    "message": "닉네임은 2~30자 사이여야 합니다.",
    "error": "Bad Request"
}

4. 오류 응답

인증 실패

{
    "statusCode": 401,
    "message": "Unauthorized",
    "error": "Unauthorized"
}

사용자를 찾을 수 없음

{
    "statusCode": 404,
    "message": "User not found",
    "error": "Not Found"
}

5. 주요 필드 설명

  • referralCode: 다른 사용자를 추천할 때 사용하는 고유 코드
  • parentId: 나를 추천한 상위 사용자의 ID
  • referralCount: 내가 추천한 하위 사용자의 수
  • rewardBalance: 누적된 추천 보상 금액
  • level: 추천 트리에서의 사용자 레벨
  • referralPath: 추천 관계의 전체 경로

6. 참고 사항

  • 응답에는 민감한 정보가 포함되어 있으므로 반드시 인증된 요청만 허용
  • 도메인 정보는 populate되어 반환
  • 추천인 정보는 ID만 포함하여 반환