Source: git.bootpay.co.kr/bootpay-sdk/backend-ruby@817dbe804b30af68817b912c2fde28b787040ff2

Source: git.bootpay.co.kr/bootpay-sdk/backend-ruby@817dbe804b30af68817b912c2fde28b787040ff2

Source: git.bootpay.co.kr/bootpay-sdk/backend-ruby@817dbe804b30af68817b912c2fde28b787040ff2

…g_key user_id) * 커머스 API 27종 추가 + 죽은 경로 5건 수정

Source: git.bootpay.co.kr/bootpay-sdk/backend-ruby@3b22da9d52c64cc943de9c5105bd411e9415c76f

…g_key user_id) * 커머스 API 27종 추가 + 죽은 경로 5건 수정

Source: git.bootpay.co.kr/bootpay-sdk/backend-ruby@3b22da9d52c64cc943de9c5105bd411e9415c76f

2-x-development 는 2025-12-02 에 갈라진 뒤 v3.0.0 대에 머물러 있었고, main 이
v3.3.0 까지 앞서 있었다. 두 브랜치를 2-x-development 로 합쳐 이 브랜치를
기준 브랜치로 삼는다.

기능 대조 결과 main 이 상위집합이었다
- main 에만 있던 엔드포인트 10종 (cart, categories, coupon, point, projects/me,
  users/session, wallet 등)
- ck/sk Basic 인증, Idempotency-Key, lookup_user_data, request/token 신경로
- v3.3.0 통일 API (builder / BootpayResponse / 모듈 표면)
따라서 충돌 24건은 모두 main 쪽으로 해소했다.

2-x-development 에만 있던 기능을 main 규약으로 포팅
- SupervisorTerminateParams 신설 + orderSubscription.supervisorTerminate(id, params)
  기존 terminate(id[, reason]) 는 그대로 두고, 위약금·환불액·최종정산·서비스종료일·
  해지기준일까지 보낼 수 있는 오버로드를 추가
- OrderSubscriptionRequestUpdateParams 에 정산 필드 6종 추가
  (price / taxFreePrice / terminationFee / lastBillRefundPrice / finalFee / serviceEndAt)
  및 APPROVAL_APPROVE / APPROVAL_REJECT 상수. 서비스가 body 에 실어 보내도록 배선
- BootpayStoreObjectAuthTest 를 현행 API 로 이관 (4개 verb Basic 인증 +
  basic 값이 토큰으로 저장되던 버그 회귀)

중복 정리 — main 이 같은 엔드포인트를 이미 더 넓게 덮고 있어 제거
- SupervisorOrderSubscription{Pause,Resume,Charge,ChargeRevoke,Approve,Reject}Params
  (main 의 Supervisor*Params 와 필드 동일, 참조 0)
- layer/order_subscription/request/OrderSubscriptionRequest, 구 경로
  SOrderSubscriptionRequestService, 구 경로 OrderSubscriptionRequest*Params
- MallSettingUpdateParams (main 은 SMallSetting pojo 158필드), TestWebhookParams
- 2-x 테스트 7종 — main 의 CommerceWireFormatTest / PgWireFormatTest 가 동일 엔드포인트를
  role·Idempotency-Key 검증까지 포함해 더 넓게 커버
- 리포지토리 루트의 stray BasicAuthProductInfoTest.java

예제를 현행 API 로 갱신
- BootpayExample.lookupSequentialBillingKey → 3-arg (userId 포함)
- store/Webhook: TestWebhookParams → Integer headerContentType
- store/MallSetting: get() → detail(), MallSettingUpdateParams → SMallSetting
- store/order_subscription/request/Request: orderSubscriptionRequest 모듈 경로로 이전,
  하드코딩 키 → Config 사용, approve/reject → approval 값 방식

검증: ./gradlew build --offline → 182 tests, failures 0, errors 0

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

작업 중 원격에 올라온 ruby 동기화 커밋을 통합한다. 봇 변경분은 구 2-x 기반 위에
작성되어 이번 main 통합본과 5개 파일에서 충돌했다. 봇이 새로 얻은 값은 살리고,
구현은 main 통합본(상위집합)을 유지하는 방향으로 해소했다.

봇 변경분 반영
- SUserJoinService: 중복확인 key 상수 5종 추가
  (EMAIL_EXIST / ID_EXIST / PHONE_EXIST / UID_EXIST / GROUP_BUSINESS_NUMBER_EXIST)
- 테스트 가능하도록 request-builder 추출 — 봇이 구 구현에 적용한 구조를
  main 구현 위에 다시 적용했다
  - SUserJoinService.checkExistRequest (path/pk 빈 값 검증 포함)
  - SOrderSubscriptionService.listRequest (search_date_from/to, ex_uid 계열 포함)
  - SOrderSubscriptionRequestIngService.calculateTerminationFeeRequest
    (id·order_number 동시 지정시 둘 다 전송하는 기존 수정 유지)
- 봇 신규 테스트 3종 그대로 편입 (14 케이스, 전부 통과)
- ProductListParams 주석(서버가 keyword 를 읽지 않는다) 반영

충돌 해소 — HEAD(main 통합본) 유지, 손실 없음을 확인
- layer/User.uidExist: HEAD 가 이미 보유하며 idempotencyKey 오버로드까지 있다
  (봇의 2-arg 버전은 mall context 없이 호출해 parity 가 어긋난다)
- app 예제 uidExist: HEAD 에 이미 존재
- SOrderSubscription(RequestIng)Service: HEAD 가 supervisor 계열·Idempotency-Key·
  userContext 를 포함한 상위집합

검증: ./gradlew build --offline → 196 tests, failures 0, errors 0

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

ruby SDK 의 request_checkout 에는 있는데 Java 에는 없던 청구서 생성 파라미터를
반영한다. 기존 SInvoice 필드와 create(invoice) 시그니처는 그대로 두고 추가만 했다.

SInvoice 추가 필드
- user (SInvoiceUser) — 가입 회원이면 userId 만으로 충분하고, 비회원 청구서는
  membershipType="guest" 와 이름·연락처를 함께 지정한다
- products (List<SInvoiceProduct>) — 등록된 상품을 참조해 청구한다
  (invoiceItems 는 이름·금액을 직접 적는 기존 방식으로 그대로 유지)
  - SInvoiceProduct: productId / productOptionId / duration / quantity / priceAdjustments
  - SInvoicePriceAdjustment: priceAdjustmentId / startAt / endAt / name / cycles
  - SInvoicePriceAdjustmentCycle: duration / adjustmentType / name / value /
    minValue / maxValue (discount_percent · discount_price · setup_fee 상수 제공)
- deliveryPrice / useNotification / useAutoLogin / usageApiUrl / sdk
- extra (SInvoiceExtra) — separatelyConfirmed / createOrderImmediately

invoice.create 규약 정정
- Idempotency-Key 헤더와 user role 을 붙인다. list/detail/notify 는 이미 그렇게
  동작하고 있었고 create 만 빠져 있었다 (ruby SDK 와도 어긋나 있었다)
- create(invoice, idempotencyKey) 오버로드 추가

검증 (네트워크 불필요, 로컬 HttpServer 대조)
- user/products/delivery_price/use_*/usage_api_url/extra 직렬화와 role·Idempotency-Key
- price_adjustments → cycles 중첩 직렬화
- 미지정 필드 미전송 (기존 사용 패턴 회귀)
- idempotencyKey 직접 지정

예제: createWithProducts / createSubscriptionWithPromotion / createUsageBased 추가

./gradlew build --offline → 200 tests, failures 0, errors 0

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Commerce 인증만 다른 SDK 와 어긋나 있었다. 다른 구현을 대조해 맞춘다.

  NodeJS  authorizationHeader(): token 있으면 Bearer, 없으면 Basic
  Ruby    rest.rb: @token.present? ? "Bearer #{@token}" : "Basic #{...}"
  Go / Python / PHP / .NET: 토큰이 있으면 Bearer
  Java(기존): 항상 requestAccessToken() = Basic  ← 유일한 이탈

변경
- BootpayStoreObject.authorizationHeader([RequestContext]) 추가. 우선순위는
  RequestContext 토큰 → 인스턴스 토큰(Bearer) → client_key/secret_key(Basic) → 없음
- 인증 정보가 하나도 없으면 Authorization 헤더를 붙이지 않는다
  (기존에는 빈 문자열을 실어 보냈다)
- RequestContext.token 을 실제로 사용한다 (필드는 있는데 무시되고 있었다)
- 8곳의 헤더 부착을 applyAuthHeader(request, context) 로 일원화
- requestAccessToken() 은 Basic 값 계산으로 동작·시그니처 그대로 유지.
  NodeJS 와 같은 주의(이 값을 토큰으로 저장하면 다음 요청부터 인증이 깨진다)를 문서화

⚠️ getAccessToken() 으로 토큰을 발급받은 코드는 이제 Basic 이 아니라 Bearer 로
   전송된다. 기준 SDK 와 같은 동작이며, 토큰 만료(30분) 시 재발급이 필요하다.

버전
- 아직 배포 전이므로 3.4.0 을 되돌려 3.3.0 하나로 합쳤다.
  통일 API + 청구서 파라미터 + 인증 정합성 + 브랜치 통합이 모두 3.3.0 이다.
- CHANGELOG 의 3.4.0 / 3.3.0 항목을 3.3.0 하나로 병합

검증: ./gradlew build --offline → 202 tests, failures 0, errors 0
  (인증 규칙 7건: Bearer 우선 / context 토큰 우선 / 토큰 없으면 Basic /
   자격 없으면 헤더 미부착 / Basic 값이 토큰으로 저장되지 않음 회귀)

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

서버(commerce-api)가 scope_invalid! 로 supervisor/manager 를 요구하는
엔드포인트 11개가 BOOTPAY-ROLE: user 로 나가고 있었다. 해당 API 들은
올바른 토큰으로도 scope 오류로 거절된다.

- orderSubscription: approve / reject / terminate /
  supervisorPause / supervisorResume / supervisorTerminate → supervisor
- category: create / update / delete → supervisor
- userGroup: userCreate / userDelete → manager

원인은 RequestContext 없이 2-인자 HTTP 헬퍼를 호출한 것이다.
BootpayStoreObject.role 기본값이 "user" 라 컨텍스트를 안 넘기면
조용히 user 로 전송된다(예외도 경고도 없다).

SOrderSubscriptionService 와 SUserGroupService 는 이미 있던
supervisorContext() / managerContext() 를 붙이기만 했고,
SCategoryService 는 헬퍼가 없어 신설했다.

부수 효과로 이 11개 호출에 Idempotency-Key 가 자동 부착된다
(다른 supervisor 메서드·ruby SDK 와 동일 규약).
요청 경로와 바디는 변경 없다.

검증: 루프백 HTTP 서버로 실제 전송 헤더를 캡처해 17개 메서드의
BOOTPAY-ROLE 을 서버 요구 scope 와 대조 — 전부 일치 확인.
requestIng.* 는 서버(ing_controller)가 role: 'user' 를 요구하므로
user 유지가 정상이며 건드리지 않았다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

전환 근거였던 '다른 SDK 도 토큰이 있으면 Bearer' 가 사실이 아니었다.
Go / Python / PHP / .NET 은 전부 항상 Basic 이고 토큰 필드를 읽지 않는다
(commerce.go:195, commerce_resource.py:81, BootpayCommerceApi.php:190,
BootpayCommerceObject.cs:180). Bearer 는 NodeJS · Ruby 둘뿐이라 Java 가
맞춰야 할 다수파는 Basic 이었다.

되돌리는 실제 이유는 사용자 피해다.
- 모든 Commerce 서비스에 토큰 가드가 있어(99곳) 기존 사용자는 전원 토큰 보유
  상태다. 따라서 Bearer 전환은 조건부가 아니라 Commerce 사용자 전체에 적용된다.
- 401 폴백도 자동 재발급도 없다. 토큰 30분 만료 후 복구 수단이 없다.
- Java 는 만료 시각을 알 수도 없다. 서버가 주는 expired_at 을 STokenResponse 가
  파싱하지 않고, expire_in 은 PG 형식이라 Commerce 응답에서 항상 0 이다.
- 예외가 아니라 success=false 라 스택트레이스도 남지 않는다. 배포 직후 스모크는
  통과하고 30분 뒤 조용히 전면 실패한다.

변경
- applyAuthHeader 를 v3.2.0 과 동일하게 requestAccessToken() (Basic) 부착으로 환원.
  Bearer 우선 authorizationHeader() 2종은 제거 (3.3.0 미배포분이라 외부 영향 없음)
- invoice.create 가 role 을 'user' 로 고정하던 것을 제거 — setRole('supervisor') 로
  지정해 둔 호출자가 조용히 강등됐다. Idempotency-Key 부착은 유지 (v3.2.0 대비 추가)
- 인증 테스트 7건을 v3.2.0 동작 단언으로 전환 (회귀 방지)
- CHANGELOG: 인증 절을 '이번 릴리스에서 바꾸지 않는다' 로 교체하고 사유 기록

Bearer 전환은 expired_at 파싱 + 만료 기반 재발급 + 401 Basic 폴백을 갖춰 다음
버전에서 진행한다.

검증: compileJava/compileTestJava 통과, 202 tests failures 0 errors 0,
v3.2.0 테스트 소스 15개 javac error 0

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>