명세서 수정

[malo1557]

---

1. Auth (인증)

1.1 회원가입

POST /api/v1/auth/register

• 사용 테이블: users
• 설명: 새로운 사용자 계정을 생성합니다.
• 요청

  {
    "email": "user@example.com",
    "username": "홍길동",
    "password": "P@ssw0rd!",
    "role": "USER"
  }

• 처리
  • password → BCryptPasswordEncoder로 암호화하여 password_hash에 저장
  • role (USER/ADMIN) 저장
• 응답

  {
    "status": 200,
    "data": null,
    "message": "회원가입이 완료되었습니다."
  }

1.2 로그인 (JWT 발급)

POST /api/v1/auth/login

• 사용 테이블: users
• 설명: 이메일/비밀번호 검증 후 Access Token 및 Refresh Token 발급
• 요청

  {
    "email": "user@example.com",
    "password": "P@ssw0rd!"
  }

• 처리
  • DB에서 이메일 조회 및 비밀번호 매칭 검사
  • 성공 시 Access Token, Refresh Token 생성 (Redis에 Refresh Token 저장)
• 응답

  {
    "status": 200,
    "data": {
      "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    },
    "message": "로그인 성공"
  }

1.3 토큰 재발급

POST /api/v1/auth/refresh

• 사용 테이블: Redis (Refresh Token 저장소)
• 설명: 만료된 Access Token을 Refresh Token을 이용해 갱신
• 요청
  • Header: Authorization: Bearer {Access_Token} (만료된 토큰이라도 파싱하여 userId 추출)
• 처리
  • Redis에 저장된 Refresh Token 유효성 검증 후 새 토큰 발급
• 응답

  {
    "status": 200,
    "data": {
      "accessToken": "new_access_token_..."
    },
    "message": "토큰 재발급 성공"
  }

---

2. 사용자 (User)

2.1 내 정보 조회

GET /api/v1/users/me

• 사용 테이블: users
• 인증: JWT 필수
• 설명: 현재 로그인한 사용자의 프로필 정보 조회
• 응답

  {
    "status": 200,
    "data": {
      "user_id": 1,
      "email": "user@example.com",
      "name": "홍길동",
      "phone_number": "010-1234-5678",
      "budget_amount": 100000,
      "created_at": "2025-05-20T10:00:00"
    },
    "message": "내 정보 조회 성공"
  }

2.2 예산 변경

PATCH /api/v1/users/me/budget

• 사용 테이블: users
• 요청

  {
    "budget_amount": 80000
  }

• 처리
  • users.budget_amount 값 업데이트 (Dirty Checking)
• 응답

  {
    "status": 200,
    "data": {
      "user_id": 1,
      "budget_amount": 80000
    },
    "message": "예산이 변경되었습니다."
  }

---

3. 상품 (Product)

3.1 바코드 스캔 → 상품 조회

POST /api/v1/products/scan

• 사용 테이블: products
• 설명: 카메라로 읽은 바코드로 상품 정보를 조회
• 요청

  {
    "product_id": "8801234567890" // 실제 바코드 값
  }

• 처리
  • products.barcode 컬럼에서 해당 값 조회
  • 없으면 404 Not Found 반환
• 응답

  {
    "status": 200,
    "data": {
      "product_id": "8801234567890",
      "name": "코카콜라 1.5L",
      "price": 3000,
      "stock": 50,
      "is_active": true,
      "updated_at": "..."
    },
    "message": "상품 조회가 완료되었습니다."
  }

3.2 상품 상세 조회

GET /api/v1/products/{product_id}

• 사용 테이블: products
• 설명: URL 경로의 바코드 값으로 상품 상세 정보 조회
• 응답
  • (3.1 응답 데이터와 동일)

3.3 상품 목록 검색

GET /api/v1/products?keyword=콜라&page=0&size=20

• 사용 테이블: products
• 설명: 키워드 검색 (포함 검색) 및 페이징 처리
• 응답

  {
    "status": 200,
    "data": {
      "items": [
        { "product_id": "...", "name": "...", ... }
      ],
      "page": 0,
      "size": 20,
      "total": 5
    },
    "message": "상품 목록 조회가 완료되었습니다."
  }

---

4. 장바구니 (Cart)

4.1 장바구니 조회

GET /api/v1/cart

• 사용 테이블: cart_items, products
• 설명: 현재 로그인한 유저의 장바구니 목록과 총액, 예산 초과 여부 반환
• 응답

  {
    "status": 200,
    "data": {
      "items": [
        {
          "cartItemId": 10,
          "productName": "코카콜라 1.5L",
          "price": 3000,
          "quantity": 2,
          "subtotal": 6000,
          "barcode": "8801234567890",
          "userId": 1
        }
      ],
      "totalAmount": 6000,
      "budgetAmount": 100000,
      "isOverBudget": false
    },
    "message": "장바구니 조회 성공"
  }

4.2 장바구니 담기

POST /api/v1/cart

• 사용 테이블: cart_items
• 요청

  {
    "barcode": "8801234567890"
  }

• 처리
  • 해당 유저의 장바구니에 이미 같은 상품이 있으면 수량 +1
  • 없으면 수량 1로 새로운 행 생성
• 응답

  {
    "status": 200,
    "data": null,
    "message": "장바구니에 추가되었습니다."
  }

4.3 수량 변경

PATCH /api/v1/cart/{cartItemId}?quantity=3

• 사용 테이블: cart_items
• 처리
  • 수량이 0 이하로 요청되면 해당 항목 삭제
  • 그 외에는 요청된 수량으로 업데이트 및 소계(Subtotal) 재계산
• 응답

  {
    "status": 200,
    "data": null,
    "message": "수량이 변경되었습니다."
  }

4.4 항목 삭제

DELETE /api/v1/cart/{cartItemId}

• 사용 테이블: cart_items
• 응답

  {
    "status": 200,
    "data": null,
    "message": "항목이 삭제되었습니다."
  }

---

5. 쇼핑리스트 (Shopping List)

5.1 전체 조회

GET /api/v1/shopping-lists

• 사용 테이블: shopping_lists
• 설명: 생성 시간 오름차순으로 정렬하여 반환
• 응답

  {
    "status": 200,
    "data": [
      {
        "listId": 1,
        "userId": 1,
        "itemName": "우유",
        "isChecked": false,
        "createdAt": "..."
      }
    ],
    "message": "쇼핑리스트 조회에 성공했습니다."
  }

5.2 항목 추가

POST /api/v1/shopping-lists

• 사용 테이블: shopping_lists
• 요청

  {
    "itemName": "계란 1판"
  }

• 응답

  {
    "status": 200,
    "data": { "listId": 2, "itemName": "계란 1판", ... },
    "message": "쇼핑리스트 항목이 추가되었습니다."
  }

5.3 수정 / 체크 토글

PATCH /api/v1/shopping-lists/{listId}

• 사용 테이블: shopping_lists
• 요청 (이름 변경 또는 체크 상태 변경, 둘 다 가능)

  {
    "itemName": "유기농 계란",
    "isChecked": true
  }

• 응답
  • 수정된 객체 반환

---

6. 주문 & 결제 (Order)

6.1 주문 생성 (결제 전)

POST /api/v1/orders

• 사용 테이블: orders, order_details, cart_items
• 설명: 현재 장바구니 내용을 기반으로 주문(PENDING) 생성
• 요청

  {
    "paymentMethod": "KAKAO_PAY"
  }

• 처리
  • 장바구니가 비어있으면 에러
  • CartItem 내용을 OrderDetail로 복사하여 저장
  • Order 생성 (상태: PENDING)
• 응답

  {
    "status": 200,
    "data": {
      "order_id": "ORD-2025...",
      "final_price": 6000,
      "payment_method": "KAKAO_PAY",
      "status": "PENDING",
      "pg_redirect_url": "/payment?orderId=...", // 임시 URL
      "created_at": "..."
    },
    "message": "주문 생성 완료"
  }

6.2 결제 확정 및 토큰 발급

POST /api/v1/orders/{orderId}/pay

• 사용 테이블: orders, cart_items, gate_tokens
• 설명: 결제 승인 처리 → 장바구니 비우기 → 게이트 토큰 발급
• 처리
  • Order 상태를 CAPTURED로 변경
  • 해당 유저의 장바구니(cart_items) 전체 삭제
  • GateToken 생성 (유효기간 10분 JWT)
• 응답

  {
    "status": 200,
    "data": {
      "order_id": "ORD-2025...",
      "status": "CAPTURED",
      "gate_token": "eyJhbGciOiJIUz...", // 이 값을 QR코드로 변환해서 사용
      "final_price": 6000,
      ...
    },
    "message": "결제 완료 및 게이트 토큰 발급 성공"
  }

6.3 주문 목록 조회

GET /api/v1/orders?status=CAPTURED&page=0&size=10

• 사용 테이블: orders
• 응답

  {
    "status": 200,
    "data": {
      "items": [ { "order_id": "...", "final_price": 6000, ... } ],
      "page": 0,
      "size": 10,
      "total": 1
    },
    "message": "주문 목록 조회 성공"
  }

---

7. 게이트 토큰 (Gate)

7.1 토큰 발급 (수동 요청 시)

POST /api/v1/gates/token

• 사용 테이블: gate_tokens, orders
• 설명: 결제 완료된 주문에 대해 게이트 토큰 발급 (결제 API에서 자동 발급되지만, 필요 시 별도 호출 가능)
• 요청

  {
    "order_id": "ORD-2025..."
  }

• 응답

  {
    "status": 200,
    "data": {
      "token_id": 1,
      "order_id": "ORD-2025...",
      "token_value": "eyJhb...",
      "status": "ISSUED",
      "expires_at": "..."
    },
    "message": "게이트 토큰이 발급되었습니다."
  }

7.2 토큰 검증 (게이트 단말기용)

POST /api/v1/gates/verify

• 사용 테이블: gate_tokens
• 요청

  {
    "token_value": "eyJhb...",
    "gate_id": "GATE_01",
    "timestamp": "..."
  }

• 처리
  • 토큰 유효성 및 만료 여부 확인
  • gate_tokens.status를 USED로 변경
• 응답

  {
    "status": "OK",
    "message": "CAPTURED transaction verified, gate open"
  }