1. API 호출 흐름

1. 로그인 (JWT 발급)
   POST /api/auth/login
   요청: { "id": "...", "pw": "..." }
   응답: { "token": "Bearer <jwt>" }
2. 토큰 저장
   클라이언트 측에서 JWT 토큰을 저장
3. 주문 목록 조회
   GET /api/orders?status=paid
   헤더: Authorization: Bearer <token>
4. 주문 상세 조회
   GET /api/orders/{order_id}
5. 발주서(PDF) 생성 요청
   POST /api/shipments
   요청: { "order_id": 123, "carrier": "CJ" }
6. 상품 재고 동기화
   주문 처리 후 재고 업데이트
   UPDATE products SET stock = stock - <qty> WHERE id = <prod_id>
7. CS 티켓 조회/답변
   GET /api/cs/tickets / POST /api/cs/tickets/{ticket_id}/reply
8. 정산·세금계산서 발행
   POST /api/invoices
   요청: { "period_start": "2025-08-01", "period_end": "2025-08-31" }

2. 주요 DB 테이블 구조

테이블명	주요 컬럼	설명
members	id, name, email, password_hash, grade	일반회원 / 셀러 / 파트너 공통 회원 정보
sellers	id, member_id(FK), shop_name, commission_rate, status	셀러 전용 상점 정보
partners	id, member_id(FK), code, commission_rate, status	파트너 추천 코드 및 수수료율
products	id, seller_id(FK), name, price, stock	셀러 상품 정보
orders	id, member_id(FK), order_no, total_amount, status, created_at	주문 기본 정보
order_items	id, order_id(FK), product_id(FK), quantity, price	주문상품 상세 정보
shipments	id, order_id(FK), courier, tracking_no, label_url, created_at	배송/송장 정보
cs_tickets	id, order_id(FK), member_id(FK), subject, message, status, created_at	CS 문의 및 답변 트래킹
invoices	id, seller_id(FK), period_start, period_end, total_amount, pdf_url	정산 및 세금계산서 발행 내역
partner_logs	id, partner_id(FK), order_id(FK), commission_amount, created_at	파트너 추천 수수료 로그

ER 다이어그램 (Mermaid)

sequenceDiagram
members 1---* sellers
members 1---* partners
sellers 1---* products
members 1---* orders
orders 1---* order_items
orders 1---1 shipments
orders 1---* cs_tickets
sellers 1---* invoices
partners 1---* partner_logs
orders 1---* partner_logs
  

확장 포인트

• Webhooks: PG사·택배사 Callback → /api/webhooks/{source} 엔드포인트 추가
• Admin API: 관리자 전용 /api/admin/... 네임스페이스 분리
• 버전 관리: /api/v1/... → /api/v2... 등 버전 분리
• 캐싱: Redis 도입 → 조회 속도 개선

API 호출 순서

1. 로그인 (JWT 발급)
   POST /api/auth/login
   • 요청 바디: { "username": "...", "password": "..." }
   • 응답 바디: { "token": "Bearer <jwt>" }
2. 주문 목록 조회
   GET /api/orders
   헤더: Authorization: Bearer <token>
3. 주문 상세 조회
   GET /api/orders/{orderId}
4. 송장 생성
   POST /api/shipments
   • 요청 바디: { "order_id": 123, "courier": "CJ", "tracking_no": "CJ123456789" }
5. 상품 목록 조회
   GET /api/products
6. 상품 등록
   POST /api/products
   • 요청 바디: { "name": "상품명", "price": 10000, "stock": 50 }
7. 상품 수정
   PUT /api/products/{productId}
8. CS 문의 조회
   GET /api/tickets
9. CS 답변 등록
   POST /api/tickets/{ticketId}/reply
   • 요청 바디: { "message": "답변 내용" }
10. 매출 리포트 조회
    GET /api/reports/sales?start=2025-08-01&end=2025-08-31

DB 테이블 구조

users

컬럼	타입	설명
id	INT PK AUTO_INCREMENT	사용자 고유 ID
mb_id	VARCHAR(50)	로그인 아이디
password	VARCHAR(255)	암호화된 비밀번호
email	VARCHAR(100)	이메일
grade	TINYINT	회원 등급 (3=일반,4=셀러,5=파트너)
partner_id	INT NULL	추천한 파트너 ID
created_at	DATETIME	등록일

partners

컬럼	타입	설명
id	INT PK AUTO_INCREMENT	파트너 고유 ID
user_id	INT	users.id (FK)
commission_rate	DECIMAL(5,2)	추천 수수료율 (%)
status	ENUM('pending','active','suspended')	파트너 상태
created_at	DATETIME	등록일

sellers

컬럼	타입	설명
id	INT PK AUTO_INCREMENT	셀러 고유 ID
user_id	INT	users.id (FK)
shop_name	VARCHAR(100)	상점 이름
commission_rate	DECIMAL(5,2)	판매 수수료율 (%)
status	ENUM('pending','active','suspended')	셀러 상태
created_at	DATETIME	등록일

products

컬럼	타입	설명
id	INT PK AUTO_INCREMENT	상품 고유 ID
seller_id	INT	sellers.id (FK)
name	VARCHAR(200)	상품명
price	INT	가격 (원)
stock	INT	재고 수량
created_at	DATETIME	등록일
updated_at	DATETIME	수정일

orders

컬럼	타입	설명
id	INT PK AUTO_INCREMENT	주문 고유 ID
order_no	VARCHAR(50)	주문 번호
member_id	INT	users.id (FK)
total_amount	INT	총 결제 금액
status	ENUM('pending','paid','shipped','completed','cancelled')	주문 상태
payment_method	VARCHAR(50)	결제 수단
created_at	DATETIME	주문 일시

order_items

컬럼	타입	설명
id	INT PK AUTO_INCREMENT	아이템 고유 ID
order_id	INT	orders.id (FK)
product_id	INT	products.id (FK)
quantity	INT	수량
price	INT	주문 시 가격

shipments

컬럼	타입	설명
id	INT PK AUTO_INCREMENT	송장 고유 ID
order_id	INT	orders.id (FK)
courier	VARCHAR(50)	택배사
tracking_no	VARCHAR(100)	송장 번호
status	ENUM('ready','in_transit','delivered')	배송 상태
shipped_at	DATETIME NULL	발송 일시

tickets

컬럼	타입	설명
id	INT PK AUTO_INCREMENT	문의 고유 ID
order_id	INT NULL	orders.id (FK)
member_id	INT	users.id (FK)
subject	VARCHAR(200)	문의 제목
message	TEXT	문의 내용
status	ENUM('open','answered','closed')	처리 상태
created_at	DATETIME	등록일

invoices

컬럼	타입	설명
id	INT PK AUTO_INCREMENT	세금계산서 고유 ID
order_id	INT	orders.id (FK)
invoice_no	VARCHAR(50)	세금계산서 번호
issue_date	DATE	발행 일자
pdf_path	VARCHAR(255)	PDF 파일 경로