아키텍처 경계
Greenfield 정답
회사 공통 기준은 업무 의미·계약·재사용 경계를 정의합니다. 같은 기능을 재사용한다는 이유만으로 모든 제품이 하나의 서버나 DB를 써야 하는 것은 아닙니다. 공통 코드·reference kit를 제품 서버에서 실행하는 방식과 중앙 API를 호출하는 방식은 구분하며, 실행 주체는 적용 범위가 명시된 제품·런타임 결정이 소유합니다.
결제와 전자문서는 상태 전이·비밀키·개인정보·대사 책임을 분리합니다. 이를 별도 서비스로 배포할지, 제품 내부의 별도 실행 경계로 둘지는 해당 아키텍처에서 정합니다.
의존 방향
text
회사 공통 정의·표준·가격 규칙 (Leysys Docs)
│ 참조
제품별 업무·운영·아키텍처 (각 product-docs)
│ 채택
제품 화면 / 제품 서버
│ 인증된 업무 요청
승인된 실행 주체 ──> provider adapter
└─> 검증된 결제 사실 / 제품 정책에 따른 이용 권한화면은 비밀키나 provider 원문으로 결제 성공·이용 권한을 결정하지 않습니다. 서버의 승인된 실행 주체가 인증·금액·상태를 검증합니다. 공통 식별 계약을 쓴다는 사실은 브랜드마다 별도인 가입·계정을 하나로 합친다는 뜻이 아닙니다.
확인된 결제 실행 구조
| 적용 범위 | 실행 구조 | 정본과 상태 |
|---|---|---|
| Billing Authority를 채택하는 제품 | 제품 서버 → Billing Authority → PG adapter | leysys-control-plane README와 THIN-BILLING-AUTHORITY-PRODUCT-BFF-2026-07-15 결정. 저장소 이름은 호환 이름이며 범용 identity 플랫폼이 아닙니다 |
| Listing Core 기반 리스팅 플랫폼 | 플랫폼별 Supabase Edge Function → PG adapter | leysys-listing-core의 Accepted 결정 LISTING-CORE-V1-2026-09-26 §5. 공통 reference kit는 control-plane에서 추출할 계획이며 게시·채택 완료를 뜻하지 않습니다 |
두 번째 결정은 리스팅 플랫폼 범위입니다. 이를 회사 전체의 Edge Function 의무나 Billing Authority의 전면 폐기로 확대하지 않습니다. 실제 배포·운영 여부는 제공 상태와 소유 제품의 검증 기록으로 확인합니다.
계정과 상품
- 계정 기능은 공통 구현을 재사용할 수 있습니다. 플랫폼 안에서는 한 계정으로 업무 모듈을 이용하며, 단독 브랜드는 브랜드마다 별도 가입·계정을 둡니다(제품 구조 S5).
- 같은 사람이나 이메일이라고 해서 브랜드 간 계정 identity를 자동 병합하지 않습니다. 브랜드에서 플랫폼으로 이동할 때는 계정 이관이 필요합니다. 실제 격리·이관은 소유 런타임에서 검증합니다.
- 결제 주체는 개인 account 또는 organization일 수 있습니다.
product_key는 이를 사용하는 런타임의 안정 식별자입니다. 플랫폼·브랜드 route namespace나 업무 모듈 키와 자동으로 같아지지 않으며 문서 정리만으로 API·DB 필드를 바꾸지 않습니다.- 가격의 계산 의미는 공통 가격 규칙, 금액·판매 조건은 제품 가격표, 결제 상태와 이용 권한 전이는 승인된 실행 주체가 소유합니다.
- Billing Authority의
(product_key, scope)entitlement와 로컬 catalog는 해당 구현의 계약입니다. 다른 런타임의 schema를 이 문서가 대체하지 않습니다. - PG가 보내는 상품명이나 상태만으로 이용 권한을 부여하지 않습니다.
공급자 선택
공급자 선택과 호출은 승인된 서버 실행 주체의 책임입니다. 브라우저 입력이 판매 주체·금액·권한을 임의로 결정해서는 안 됩니다.
| 구현 | 선택·연결의 소유자 | 불명확한 결과 처리 |
|---|---|---|
| Billing Authority | 승인된 catalog와 provider account | 기존 결제 시도를 같은 provider에서 조회·대사 |
| 제품 소유 결제 실행 | 제품 아키텍처에 명시된 서버 adapter와 설정 | 동일 결제 의도·거래 연결을 보존하고 같은 provider에서 대사 |
| Integrations gateway | capability routing과 기존 document binding | 발행·취소 결과가 불명확하면 같은 provider에서 대사 |
기존 문서의 provider binding은 유지합니다. 결과가 불명확하다는 이유로 다른 provider에 다시 발행·승인을 요청하지 않습니다.
단계별 데이터 저장소
2026-10-04 KST 오너 결정입니다. 저장소는 제품의 단계로 고릅니다.
| 단계 | 저장소 |
|---|---|
프로토타입(-proto 저장소) | 기본은 브라우저 localStorage입니다. 서버가 꼭 필요한 기능만 Supabase를 씁니다 |
| 초기 MVP | Supabase. 초기에 Supabase로 시작한 실제 서비스는 그대로 이어 쓰기도 합니다 |
| 실제 서비스 고도화 | MariaDB |
- localStorage를 쓰는 프로토타입에는 실행되지 않는 SQL이나 서버 참고 구현을 새로 두지 않습니다. 서버가 지켜야 할 계약(역할, 권한 키, 불변식)은 인계 문서로 넘기고, 실제 서비스의 백엔드가 자기 저장소 기술로 구현합니다.
- 공통 표준은 특정 DB에 묶이지 않게 씁니다. 예를 들어 접근 역할 체계는 역할·관계·권한 키·불변식으로 정하며, 어느 저장소에서도 같은 규칙으로 구현합니다.
- 결정 기록:
docs/decisions/DATA-STORE-BY-STAGE-2026-10-04.md
런타임 원칙
- 외부 변경 요청은 안정된 업무 식별자와 idempotency key로 중복을 막습니다.
- 비밀키는 승인된 실행 주체의 secret store에만 둡니다.
- provider 원문과 상태 전이는 접근 제한된 감사 저장소에서 관리합니다.
- webhook 수신과 도메인 상태 적용을 분리하고 provider 사실을 검증합니다.
unknown은 실패나 성공으로 추측하지 않고 reconciliation 대상으로 둡니다.- account/product/capability 권한은 provider 호출 전에 확인합니다.
문서 정본과 코드 정본
회사 공통 원칙은 이 사이트가, 특정 제품의 구성·운영·실행 구조는 해당 제품 문서가 소유합니다. Billing Authority와 Integrations 상세 페이지는 해당 구현을 채택하거나 유지보수할 때 쓰는 참고 계약이며 회사 전체에 대한 채택 명령이 아닙니다. schema·상태 전이·adapter 동작의 정본은 소유 런타임의 코드와 테스트입니다.