Leysys Docs

AI 에이전트 지침 ​

AI는 문서 소유권, 제품 구조, 관련 명명 표준과 가격 규칙을 먼저 확인합니다. 회사 공통 정의는 Leysys Docs, 제품의 적용·구현 계약은 해당 product-docs와 runtime 저장소가 소유합니다. llms.txt는 탐색 입구이며 llms-full.txt는 이 경계를 요약합니다.

제품 저장소에 연결할 공통 지침 ​

다음 블록을 해당 제품의 적용 범위와 함께 AGENTS.md에 연결할 수 있습니다.

markdown
## Leysys 공통 정의와 실행 경계

- 회사 공통 제품 구조·명명·가격 규칙·문서 소유권: https://docs.leysys.com
- 직원 접근 역할은 https://docs.leysys.com/standards/access-roles 를 따른다. 역할 이름을 직접 비교하지 않고 권한 키로 판정하며, 슈퍼 관리자와 사람별 본사 플래그를 두지 않는다.
- 레코드 식별 필드(고유코드·관리코드·등록번호·유형·상태·이름)는 https://docs.leysys.com/standards/record-identity 를 따른다. 관리코드는 바꾸지 않고 다시 쓰지 않으며, 등록번호는 일반 편집이 아니라 정정으로 바꾸고, 삭제는 다른 기록이 참조하지 않을 때만 한다.
- 공통 입력 정보(당사자·사업자·조직·연락처·주소)는 https://docs.leysys.com/standards/common-fields 를 따른다. 의미는 법령·공식 등록 체계가 정하고, 이름은 HTML autocomplete 토큰 → schema.org → vCard 순서로 고르며, 토큰·코드(camelCase)·DB(snake_case)가 같은 단어를 쓴다(`mobileTel`·`mobile_tel`, `bday`, `addressLine1`). `phone`·`mobilePhone`·`zipcode`·`detailAddress`·`firstName`·`businessRegNum` 같은 이름을 새로 만들지 않는다. 당사자 유형(개인·법인·법인 아닌 단체)과 세법상 구분(개인·법인·구성원별 과세)을 나누고, 개인·법인의 한국 등록번호(13자리)와 사업자 등록(10자리, 당사자 하나에 0개 이상)을 섞지 않는다. 식별번호·주소·담당자는 목록이 정본이고 API는 중첩 객체이며, 「역할」이라는 말은 접근 역할에만 쓴다(담당자 `contactType`, 주소 `addressType`). 연락처 기본 필드는 휴대전화번호(`mobileTel`)·전화번호(`tel`, 옛 「일반전화」)·이메일주소이고, 자택·직장·팩스·대표전화 등은 [추가]를 눌러야 생기는 선택 필드다. 다른 사람의 정보를 입력하는 화면은 `autocomplete="off"`다. 실제 가입자 대역(010-2XXX–010-9XXX) 번호와 실제일 수 있는 등록번호를 예시로 쓰지 않는다.
- 제품의 업무·코드·데이터·배포 경계는 해당 제품의 최신 확정 ADR과 runtime 계약을 확인한다.
- 결제 실행 주체는 제품 ADR로 정한다. 중앙 Billing Authority를 쓰는 제품은 해당 SDK/API를 소비하고, 제품 소유 서버가 실행 주체인 제품은 승인된 provider 계약을 그 서버에서 구현한다.
- provider secret, service token, billing key, signing key는 실행 주체의 secret store에 둔다. Git·공개 문서·브라우저·모바일 앱에 넣지 않는다.
- redirect, 미검증 webhook 원문 또는 provider status만으로 제품 권한을 부여하지 않는다. 검증된 결제 근거와 권한 전이를 소유한 runtime의 결과를 사용한다.
- mutation에는 stable local key와 idempotency key를 사용하며 같은 의도의 retry는 같은 key를 재사용한다.
- 승인·발행·취소 결과가 unknown이면 같은 provider와 같은 의도에서 조회·대사한다. 다른 provider로 무작정 재전송하지 않는다.
- 계획·과거 검증·현재 staging·production traffic·출시 준비를 구분한다. package와 API의 실제 제공 상태는 https://docs.leysys.com/reference/status 및 소유 runtime의 증거로 확인한다.

작업 판단 순서 ​

  1. 변경이 회사 공통 규칙인지 제품별 적용인지 판정하고 문서 소유자를 정합니다.
  2. 해당 제품의 최신 확정 ADR에서 결제·연동 실행 주체와 데이터·권한 책임을 확인합니다.
  3. 선택된 실행 주체의 계약과 실제 제공 상태를 확인합니다. 과거 문서의 중앙 SDK 사용 예를 모든 제품의 의무로 확대하지 않습니다.
  4. 업무 입력, provider 전용 값, 서버가 검증할 금액·권한을 구분합니다.
  5. idempotency, timeout, unknown/reconciliation, 감사와 권한 전이를 설계합니다.
  6. 성공·중복·순서 역전·timeout·unknown·권한 거부·취소 실패를 영향 범위에서 검증합니다.

구현별 적용 범위 ​

  • Billing Authority 채택 제품: @leysys/control-plane-client와 승인된 HTTP 계약을 사용합니다. provider orchestration·결제 장부는 Authority가 소유하며, 소비 제품은 (accountId, productKey)의 정규화된 entitlement 계약으로 접근을 판정합니다.
  • 제품 소유 결제 서버: 제품의 승인 ADR에 따라 provider 호출·서명 검증·결제 상태와 권한 전이를 소유합니다. 비밀값을 클라이언트에 노출하거나 redirect만으로 결제를 확정하지 않습니다.
  • Integrations gateway 채택 구현: gateway가 routing과 document-provider binding을 소유합니다. getOperation·reconcile_same_provider 등은 해당 구현의 계약으로 확인하고, 미게시 client나 미검증 API를 사용 가능하다고 가정하지 않습니다.

2026-09-26 KST Listing Core의 확정 ADR은 리스팅 플랫폼마다 Supabase Edge Function에서 결제를 실행하고 control-plane 코드를 정리한 공통 reference kit를 만들도록 정합니다. 이 결정은 리스팅 플랫폼 범위이며, kit 게시 완료나 다른 모든 제품의 runtime 변경을 뜻하지 않습니다.

상태와 근거 ​

2026-10-01 KST 읽기 전용 확인에서 기존 Billing Authority staging ECS는 1/1 task로 실행 중입니다. 이 사실로 production catalog·traffic·제품 채택을 확인한 것은 아닙니다. Integrations의 기반 코드와 client 상태는 2026-07-15 KST의 과거 조사이며 이번 검토에서 현재 운영 여부를 다시 확인하지 않았습니다. 상세한 증거 범위는 현재 제공 상태를 따릅니다.

문서에 없는 route·method·enum·환경변수를 만들지 않으며, manifest를 게시 증거로, migration 파일을 운영 DB 적용 증거로 사용하지 않습니다. Provider 구현을 다룰 때는 공급자 공식 문서를 실행 주체의 adapter 범위에서 확인합니다.

© 2026 Leysys. 무단 복제·배포·판매를 금지합니다.