제품 온보딩

회사 공통 정의를 채택하고 제품의 실행·데이터·권한 책임을 확정하는 순서입니다. 공통 규칙을 따른다는 이유만으로 모든 제품이 같은 결제 서버를 호출해야 하는 것은 아닙니다.

1. 공통 정의와 제품 적용

• 제품 구조의 플랫폼·모듈·Core·공통 서비스를 사용합니다.
• 명명 표준과 가격 규칙을 적용합니다.
• 제품별 금액·권한·업무 의미·배포 상태는 product-docs와 소유 runtime에 기록합니다.
• 문서 소유권에 따라 공통 정의와 제품 적용을 중복 확정하지 않습니다.

2. 실행 주체와 계약

제품의 승인 ADR로 결제·연동 실행 주체를 선택하고 책임을 기록합니다.

선택한 경계	제품이 채택할 계약	실행 주체의 책임
중앙 Billing Authority	승인된 API와 @leysys/control-plane-client, catalog·entitlement 계약	provider 호출·결제 장부·대사·정규화된 entitlement
제품 소유 서버	해당 제품 ADR의 결제·권한 API와 provider 계약	provider 호출·결제 상태·권한 전이·대사·감사
Integrations gateway	실제 제공이 확인된 capability·client 계약	routing·문서 binding·같은 provider 조회·대사

계약·결제 주체, account·organization·문서의 안정 식별자, 금액을 확정하는 서버, 권한 전이의 소유자를 정합니다. Billing Authority를 선택했다면 해당 product_key와 entitlement scope를 승인하며, 다른 실행 구조에 이 필드 이름을 기계적으로 강제하지 않습니다.

Listing Core의 2026-09-26 KST 확정 ADR은 리스팅 플랫폼별 Supabase Edge Function 결제와 공통 reference kit 추출 계획을 소유합니다. 이 계획을 게시된 kit로 설명하거나 다른 제품의 중앙 결제 계약을 자동 변경하지 않습니다.

3. 제공 상태 확인

현재 제공 상태와 선택한 runtime의 코드·배포 증거를 함께 확인합니다.

• Billing Authority staging ECS는 2026-10-01 KST에 desired/running 1/1을 확인했습니다. Production catalog·traffic·제품 채택은 그 확인 범위에 포함되지 않습니다.
• Integrations의 기반 코드·client 상태는 2026-07-15 KST 과거 조사입니다. 이번 검토에서 현재 API 배포·package 게시 여부를 다시 검증하지 않았으므로 실제 채택 전에 확인합니다.
• SDK를 채택할 때는 필요한 exact version의 게시·설치·import를 확인합니다. 모든 구현에 같은 SDK를 강제하거나, 계획 단계의 reference kit를 dependency로 추가하지 않습니다.

4. 비밀값과 안전한 실행

• provider secret·billing key·signing key는 선택한 실행 주체의 secret store에 둡니다.
• service credential이 필요한 소비자는 최소 권한 server credential만 사용합니다. 브라우저·모바일 앱·공개 환경변수·Git에는 secret과 service token을 넣지 않습니다.
• 원문 provider evidence는 접근이 제한된 감사 저장소에 보존하고 일반 응답·로그에 노출하지 않습니다.
• 운영 활성화 전에는 비활성 설정과 sandbox fixture로 승인·취소·권한 전이를 확인합니다.
• return URL·origin·service scope allowlist를 실제 계약에 맞게 검토합니다.
• 동일 의도의 retry에는 동일 local/idempotency key를 사용합니다. 결과가 unknown이면 같은 provider에서 조회·대사하고 임의로 다른 provider에 재전송하지 않습니다.
• 기존 문서를 이관할 때는 provider binding을 보존합니다. Gateway를 채택한 구현의 routing은 gateway가 소유합니다. 제품 소유 결제 실행에 관한 결정이 이 문서의 gateway 계약을 자동 변경하지 않습니다.

5. 관련 동작 검증

영역	필요한 검증
결제·구독	서버 금액 검증, checkout·return URL, idempotency replay, 승인 timeout·대사, 환불·취소와 권한 종료, webhook 중복·순서 역전
접근 권한	redirect·미검증 webhook만으로 활성화되지 않음, 검증된 결제 기록 후 권한 전이, 누락·만료·잘못된 권한 결과의 fail-closed 처리
외부 문서·메시징	sandbox 요청·조회, 중복 key, unknown·취소 실패, 같은 provider 대사, 기존 문서 binding, capability 권한과 감사 접근

Billing Authority 소비자는 해당 entitlement snapshot을 확인합니다. 제품 소유 실행 주체는 자기 결제·권한 계약의 상태 전이를 검증합니다. 모든 제품의 권한 데이터를 한 서버의 schema로 맞춘다고 가정하지 않습니다.

6. 운영 활성화

선택한 구현에 필요한 배포·migration, package 채택, secret rotation, 대사·webhook 운영자, 알림, 개인정보 보존·파기, sandbox 결과, 안전한 비활성화·복구 절차를 확인한 뒤 활성화합니다. 실제 결제·문서 발행과 production 변경은 소유 제품의 승인·검증 절차를 따릅니다.

문서 정리, SDK 설치, staging task 실행만으로 production-ready를 선언하지 않습니다. AI 작업 지침은 AI 에이전트 지침을 제품의 적용 범위와 함께 연결합니다.