프로토타입 백엔드 api 명세서 이거로 픽스하면 되는지 궁금합니다.

[kkm0315]

1. Auth / 사용자 (users)

1.1 회원가입

POST /api/auth/signup

• 사용 테이블: users
• 설명: 새 user row 생성

요청

{
  "email": "user@example.com",
  "password": "P@ssw0rd!",
  "name": "홍길동",
  "phone_number": "010-1234-5678",
  "budget_amount": 100000
}

처리

• password → password_hash(BCrypt 등) 로 저장
• budget_amount → users.budget_amount
• created_at 현재 시간

응답

{
  "success": true,
  "data": {
    "user_id": 1,
    "email": "user@example.com",
    "name": "홍길동",
    "phone_number": "010-1234-5678",
    "budget_amount": 100000,
    "created_at": "2025-09-22T12:00:00Z"
  }
}

---

1.2 로그인(JWT 발급)

POST /api/auth/login

• 사용 테이블: users
• 설명: email + password 검사 후 JWT 발급

요청

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

응답

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": 3600,
    "user": {
      "user_id": 1,
      "email": "user@example.com",
      "name": "홍길동",
      "phone_number": "010-1234-5678",
      "budget_amount": 100000
    }
  }
}

---

1.3 내 정보 조회

GET /api/users/me

• 사용 테이블: users
• 인증: JWT
• 설명: 현재 로그인 유저 row 조회

응답

{
  "success": true,
  "data": {
    "user_id": 1,
    "email": "user@example.com",
    "name": "홍길동",
    "phone_number": "010-1234-5678",
    "budget_amount": 100000,
    "created_at": "2025-09-22T12:00:00Z"
  }
}

---

1.4 예산 변경 (budget_amount)

PATCH /api/users/me/budget

• 사용 테이블: users

요청

{
  "budget_amount": 80000
}

응답

{
  "success": true,
  "data": {
    "user_id": 1,
    "budget_amount": 80000
  }
}

---

2. 상품 (products)

2.1 바코드 스캔 → 상품 조회

POST /api/products/scan

• 사용 테이블: products
• 설명: 카메라로 읽은 바코드 값을 product_id 로 취급

요청

{
  "product_id": "8801234567890"   // = products.product_id
}

응답(상품 존재)

{
  "success": true,
  "data": {
    "product_id": "8801234567890",
    "name": "콜라 500ml",
    "price": 1800,
    "stock": 25,
    "is_active": true,
    "updated_at": "2025-09-22T10:00:00Z"
  }
}

---

2.2 상품 상세 조회

GET /api/products/{product_id}

• 사용 테이블: products

응답

{
  "success": true,
  "data": {
    "product_id": "8801234567890",
    "name": "콜라 500ml",
    "price": 1800,
    "stock": 25,
    "is_active": true,
    "updated_at": "2025-09-22T10:00:00Z"
  }
}

---

2.3 상품 목록 검색

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

• 사용 테이블: products

응답

{
  "success": true,
  "data": {
    "items": [
      {
        "product_id": "8801234567890",
        "name": "콜라 500ml",
        "price": 1800,
        "stock": 25,
        "is_active": true
      }
    ],
    "page": 0,
    "size": 20,
    "total": 1
  }
}

---

3. 장바구니(cart_items)

ERD상 따로 cart 테이블 없이 cart_items만 있으니까,
“현재 장바구니 = user_id 기준 cart_items + products join 결과”로 본다.

3.1 현재 장바구니 조회

GET /api/cart

• 사용 테이블: cart_items, products
• 인증: JWT

응답

{
  "success": true,
  "data": {
    "user_id": 1,
    "items": [
      {
        "cart_item_id": 10,
        "product_id": "8801234567890",
        "name": "콜라 500ml",
        "price": 1800,             // products.price
        "quantity": 2,             // cart_items.quantity
        "subtotal": 3600           // cart_items.subtotal
      },
      {
        "cart_item_id": 11,
        "product_id": "8809999999999",
        "name": "감자칩",
        "price": 2500,
        "quantity": 1,
        "subtotal": 2500
      }
    ],
    "total_price": 6100
  }
}

total_price 는 cart_items.subtotal 합계(orders.final_price의 베이스).

---

3.2 장바구니에 상품 추가

POST /api/cart/items

• 사용 테이블: cart_items
• 설명: (user_id, product_id) 로 row 생성 또는 기존 row 수량 증가

요청

{
  "product_id": "8801234567890",
  "quantity": 1
}

처리

1. user_id = JWT의 user_id
2. 해당 user_id + product_id 의 cart_items 가 존재하면 quantity/subtotal 업데이트
3. 없으면 새 row 삽입

응답

{
  "success": true,
  "data": {
    "cart_item_id": 10,
    "user_id": 1,
    "product_id": "8801234567890",
    "quantity": 2,
    "subtotal": 3600,
    "created_at": "2025-09-22T12:10:00Z"
  }
}

---

3.3 장바구니 수량 변경

PATCH /api/cart/items/{cart_item_id}

• 사용 테이블: cart_items

요청

{
  "quantity": 3
}

응답

{
  "success": true,
  "data": {
    "cart_item_id": 10,
    "quantity": 3,
    "subtotal": 5400
  }
}

---

3.4 장바구니 항목 삭제

DELETE /api/cart/items/{cart_item_id}

• 사용 테이블: cart_items

응답

{
  "success": true
}

---

4. 쇼핑리스트(shopping_lists)

테이블이 “한 줄 = 한 아이템” 구조라서 그 기준으로 설계.

4.1 쇼핑리스트 전체 조회

GET /api/shopping-lists

• 사용 테이블: shopping_lists

응답

{
  "success": true,
  "data": [
    {
      "list_id": 1,
      "user_id": 1,
      "item_name": "콜라 500ml",
      "is_checked": true,
      "created_at": "2025-09-22T09:00:00Z"
    },
    {
      "list_id": 2,
      "user_id": 1,
      "item_name": "감자칩",
      "is_checked": false,
      "created_at": "2025-09-22T09:05:00Z"
    }
  ]
}

---

4.2 쇼핑리스트 아이템 추가

POST /api/shopping-lists

요청

{
  "item_name": "우유 1L"
}

응답

{
  "success": true,
  "data": {
    "list_id": 3,
    "user_id": 1,
    "item_name": "우유 1L",
    "is_checked": false,
    "created_at": "2025-09-22T10:00:00Z"
  }
}

---

4.3 쇼핑리스트 수정 / 체크 토글

PATCH /api/shopping-lists/{list_id}

요청 예시(체크 상태 변경)

{
  "is_checked": true
}

요청 예시(이름 변경)

{
  "item_name": "저지방 우유 1L"
}

응답

{
  "success": true,
  "data": {
    "list_id": 3,
    "item_name": "저지방 우유 1L",
    "is_checked": true
  }
}

---

4.4 쇼핑리스트 항목 삭제

DELETE /api/shopping-lists/{list_id}

응답

{
  "success": true
}

---

5. 주문 / 결제(orders, order_details)

5.1 장바구니 → 주문 생성 & PG 준비

POST /api/orders

• 사용 테이블: orders, order_details, cart_items, products

• 설명:

  1. user_id 의 cart_items 불러와서 합계 계산
  2. orders 에 row 생성 (status = "PENDING")
  3. 각 cart_items → order_details row로 복사
  4. PG 결제 준비 후 redirect URL 반환

요청

{
  "payment_method": "KAKAO_PAY"
}

응답

{
  "success": true,
  "data": {
    "order_id": "O20250922001",
    "user_id": 1,
    "final_price": 15200,
    "payment_method": "KAKAO_PAY",
    "status": "PENDING",
    "pg_redirect_url": "https://kakaopay.com/...",
    "created_at": "2025-09-22T12:20:00Z"
  }
}

이때 DB 상태

• orders

  • order_id = "O20250922001"
  • user_id = 1
  • final_price = cart_items.subtotal 합계
  • payment_method = "KAKAO_PAY"
  • status = 'PENDING'
  • created_at = now

• order_details

  • 각 cart_items 에 대해

    • order_id = 위 order_id
    • product_id = cart_items.product_id
    • product_name = products.name
    • item_price = products.price
    • quantity = cart_items.quantity

• 성공 후 cart_items 는 비우는 방향(또는 주문 완료 후 비우기).

---

5.2 PG 웹훅(CAPTURED 확정)

POST /api/payments/webhook

• 사용 테이블: orders
• 설명: PG → 서버. 결제 확정 시 orders.status, approved_at, receipt_url 갱신.

요청(예시)

{
  "order_id": "O20250922001",
  "status": "CAPTURED",
  "approved_at": "2025-09-22T12:35:12Z",
  "final_price": 15200,
  "receipt_url": "https://pg.com/receipt/123"
}

처리

• orders where order_id = ...

  • status = "CAPTURED"
  • approved_at 업데이트
  • receipt_url 업데이트

응답

{
  "success": true
}

---

5.3 주문 상세 조회

GET /api/orders/{order_id}

• 사용 테이블: orders, order_details

응답

{
  "success": true,
  "data": {
    "order": {
      "order_id": "O20250922001",
      "user_id": 1,
      "final_price": 15200,
      "payment_method": "KAKAO_PAY",
      "status": "CAPTURED",
      "approved_at": "2025-09-22T12:35:12Z",
      "receipt_url": "https://pg.com/receipt/123",
      "created_at": "2025-09-22T12:20:00Z"
    },
    "order_details": [
      {
        "order_detail_id": 100,
        "product_id": "8801234567890",
        "product_name": "콜라 500ml",
        "item_price": 1800,
        "quantity": 2
      },
      {
        "order_detail_id": 101,
        "product_id": "8809999999999",
        "product_name": "감자칩",
        "item_price": 2500,
        "quantity": 1
      }
    ]
  }
}

---

5.4 주문 목록 조회(내 결제 내역)

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

• 사용 테이블: orders

응답

{
  "success": true,
  "data": {
    "items": [
      {
        "order_id": "O20250922001",
        "final_price": 15200,
        "payment_method": "KAKAO_PAY",
        "status": "CAPTURED",
        "approved_at": "2025-09-22T12:35:12Z"
      }
    ],
    "page": 0,
    "size": 10,
    "total": 1
  }
}

---

5.5 결제 실패/취소 알림

POST /api/orders/{order_id}/fail

• 사용 테이블: orders

요청

{
  "reason": "PG_USER_CANCEL"
}

처리: orders.status = "FAILED" 또는 "CANCELED"

응답

{
  "success": true,
  "data": {
    "order_id": "O20250922001",
    "status": "CANCELED"
  }
}

---

6. 게이트 토큰(gate_tokens)

6.1 출구 토큰 발급 (앱 → 서버)

POST /api/gates/token

• 사용 테이블: gate_tokens, orders
• 설명: orders.status = CAPTURED 인 order 에 대해 gate_tokens row 생성

요청

{
  "order_id": "O20250922001"
}

처리

• orders.status 가 "CAPTURED" 인지 확인

• JWT/ECDSA 등으로 token_value 생성

• gate_tokens row 삽입

  • order_id = 요청값
  • token_value = 생성한 토큰 문자열
  • status = "ISSUED"
  • issued_at = now
  • expires_at = now + 60초

응답

{
  "success": true,
  "data": {
    "token_id": 1,
    "order_id": "O20250922001",
    "token_value": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
    "status": "ISSUED",
    "issued_at": "2025-09-22T12:39:00Z",
    "expires_at": "2025-09-22T12:40:00Z"
  }
}

---

6.2 게이트 단말 → 서버 토큰 검증

POST /api/gates/verify

• 사용 테이블: gate_tokens, orders

• 설명:

  • token_value 검증
  • gate_tokens.status / used_at 갱신
  • orders.status 가 CAPTURED 인지 확인 후 OK/FAIL 응답

요청

{
  "token_value": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
  "gate_id": "GATE_A01",
  "timestamp": "2025-09-22T12:39:58Z"
}

성공 응답(토큰 유효 + orders.status = CAPTURED)

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

이때 DB

• gate_tokens.status = "USED"
• gate_tokens.used_at = now

실패 예시(만료)

{
  "status": "FAIL",
  "reason": "EXPIRED",
  "message": "토큰이 만료되었습니다. 앱에서 재발급 후 다시 시도해주세요."
}

---

7. 관리자용 API (선택) – ERD 매핑

7.1 상품 추가/수정/삭제

• POST /api/admin/products → products insert
• PUT /api/admin/products/{product_id} → products update
• DELETE /api/admin/products/{product_id} → products delete or is_active=false

요청(추가 예시)

{
  "product_id": "8801234567890",
  "name": "콜라 500ml",
  "price": 1800,
  "stock": 100,
  "is_active": true
}

[malo1557]

수정된 API 명세서 (프로토타입 버전)

5. 주문 / 결제 (Orders)

5.1 장바구니 → 주문 생성 (결제 준비)

• URL: POST /api/v1/orders
• 설명: 현재 사용자의 장바구니 품목을 바탕으로 주문을 생성(PENDING)하고, 결제 페이지로 이동할 URL(가짜)을 반환합니다.
• 요청 (Body):

  {
    "payment_method": "KAKAO_PAY"
  }

• 응답:

  {
    "status": 200,
    "data": {
      "order_id": "ORD-20250922-1A2B3C4D",
      "user_id": 1,
      "final_price": 15200,
      "payment_method": "KAKAO_PAY",
      "status": "PENDING",
      "pg_redirect_url": "https://mock-pg.com/pay?orderId=ORD-20250922-1A2B3C4D",
      "created_at": "2025-09-22T12:20:00Z"
    },
    "message": "주문이 생성되었습니다. 결제를 진행해주세요."
  }

5.2 결제 승인 (Mock API) (기존 PG 웹훅 대체)

• URL: POST /api/v1/orders/{order_id}/pay
• 설명: (프로토타입 전용) '결제하기' 버튼 클릭 시 호출하여 해당 주문을 즉시 결제 완료(CAPTURED) 상태로 변경합니다.
• 요청: 없음 (Path Variable만 사용)
• 응답:

  {
    "status": 200,
    "data": {
      "order_id": "ORD-20250922-1A2B3C4D",
      "final_price": 15200,
      "payment_method": "KAKAO_PAY",
      "status": "CAPTURED",
      "pg_redirect_url": null,
      "created_at": "2025-09-22T12:20:00Z"
    },
    "message": "결제가 정상적으로 승인되었습니다. (Mock)"
  }

---

6. 게이트 토큰 (Gates)

6.1 출구 토큰 발급 (앱 → 서버)

• URL: POST /api/v1/gates/token
• 설명: orders.status = CAPTURED인 주문에 대해 1회용 게이트 토큰을 발급합니다.
• 요청 (Body):

  {
    "order_id": "ORD-20250922-1A2B3C4D"
  }

• 응답:

  {
    "status": 200,
    "data": {
      "token_id": 1,
      "order_id": "ORD-20250922-1A2B3C4D",
      "token_value": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
      "status": "ISSUED",
      "issued_at": "2025-09-22T12:39:00Z",
      "expires_at": "2025-09-22T12:40:00Z"
    },
    "message": "토큰이 발급되었습니다."
  }

6.2 게이트 단말 토큰 검증 (게이트 → 서버)

• URL: POST /api/v1/gates/verify
• 설명: 게이트 단말기가 스캔한 QR 토큰의 유효성을 검증하고 문 개방 여부를 응답받습니다.
• 요청 (Body):

  {
    "token_value": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
    "gate_id": "GATE_A01",
    "timestamp": "2025-09-22T12:39:58Z"
  }

• 응답 (성공):

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

• 응답 (실패 - 만료/미결제 등):

  {
    "status": "FAIL",
    "reason": "INVALID_OR_EXPIRED",
    "message": "토큰이 만료되었습니다."
  }

주문 게이트쪽 명세서 수정