Leyve Docs

다크모드

Company 공통 외부 서비스 연동 핸드오프 ​

기준일: 2026-07-13. Prototype UI와 운영 백엔드 경계를 구분한다.

결정된 구조 ​

  • 연동 소유자는 Office가 아닌 계약 주체 Company다.
  • 고객용 관리 경로는 Company 관리 → 외부 서비스 연동 → 연동 관리다.
  • Company 연결 후 계좌별로 Office·모듈·사용 목적을 매핑한다.
  • 인증서, 사업자번호, 연동 ID, API 코드는 DB나 브라우저에 저장하지 않고 Edge Function secret에만 둔다.

현재 구현 범위 ​

영역상태비고
Company 연동 현황·요금·Office/모듈 매핑 UIPrototype 구현localStorage 상태, 운영 DB 전환 필요
은행 계좌 목록·거래 조회읽기 전용 Edge 연동로그인 필수, 끝자리 019 서버 강제
채널 정산금 분류구현eligibleForReceipt=false, 정산 대사로 보냄
홈택스 세금계산서·현금영수증 수집⚠️ 데모 수집 실배선연동 화면 [홈택스 수집 실행] = useBarobillIntegration.syncHometaxSourceDocuments → accountingSourceDocumentRepo.collect{TaxInvoices,CashReceipts}(Prototype 데모 수집·(source,external_key) 멱등). 실 바로빌 Edge 어댑터·일 배치는 후속(인증키·자격증명)
카드 매출·매입(승인내역) 수집⚠️ 데모 수집 실배선(옵트인)연동 화면 [카드 수집 실행] = syncCardSourceDocuments → accountingSourceDocumentRepo.collect{CardSales,CardPurchases}. 서비스(card-sales·card-purchase)는 기본 비활성 — 사용 설정 시 요금 반영. 여신금융협회 승인내역·법인카드 사용내역이 원천, 카드사별 등록은 실 어댑터 후속
외부 연동 운영 DB스키마 제공migration 20260713070000_company_external_service_integrations.sql

요금 SSOT ​

  • 홈택스 세금계산서: 월 20,000원
  • 홈택스 현금영수증: 월 20,000원
  • 카드 매출(승인내역): 월 10,000원 예상(옵트인·기본 비활성)
  • 카드 매입(사용내역): 월 10,000원 예상(옵트인·기본 비활성)
  • 은행 계좌 조회: 계좌당 월 3,000원 예상. 운영 계약서로 확정 후 fee_status=confirmed으로 바꾼다.
  • Leyve 상품료와 외부 연동 실비는 견적·청구서에서 항목을 분리한다.

고객 표면 네이밍 불변식 ​

  • 공급사명은 어댑터 키·환경변수·서버 로그·개발 문서에서만 사용한다.
  • 화면, AI 답변, 도움말, 운영 설명서, 사용자 오류 메시지에는 공급사명을 반환하지 않는다.
  • 기능 표시명은 외부 서비스 연동, 증빙 자동수집, 은행 입금, CMS·가상계좌, PG 결제, 채널 정산금을 사용한다.
  • 고객 경로는 /headquarters/integrations/external-service다. 기존 provider 경로는 북마크 호환을 위한 redirect로만 유지한다.
  • 외부 API의 오류 본문을 그대로 브라우저로 전달하지 않고 중립 메시지와 추적 ID로 변환한다.

불변식 ​

  1. Goldnus에서는 끝자리 019 관리비 계좌 한 개만 활성한다. 0개이거나 2개 이상이면 조회를 실패시킨다.
  2. 은행 입금은 즉시 수납이 아니라 수납 후보다. 대상·금액·중복을 확인해야 한다.
  3. 가상계좌·CMS·PG 정산금은 이미 채널에서 수납 처리됐으므로 수납 후보에서 제외한다.
  4. 증빙 수집은 (source, external_key) 유니크로 재수집 멱등을 보장한다.
  5. 동기화 이력은 성공·실패·중복·제외 건수와 trace ID를 남긴다.
  6. 브라우저의 활성 토글과 무관하게 조회 API는 Company·Goldnus 정책을 서버에서 다시 검증한다. 끝자리 019 계좌가 정확히 한 개가 아니면 수집을 시작하지 않는다.
  7. 홈택스 일부 서비스나 은행 한 채널만 장애여도 연결 전체를 정상으로 표시하지 않는다. 서비스별 configured, adapter-pending, demo-collected(Prototype 데모 수집 실행됨), connected, failed를 구분한다.
  8. 동기화 이력(syncRuns)은 type(bank|hometax)으로 구분한다 — 은행은 후보/정산대사 건수, 홈택스는 신규/중복(멱등) 건수를 남긴다.

as-built — 홈택스 데모 수집 실배선 (2026-07-21) ​

  • 연동 화면 홈택스 연동 섹션의 [홈택스 수집 실행] = useBarobillIntegration.syncHometaxSourceDocuments(). 사용 설정된 서비스(tax-invoice·cash-receipt)만 accountingSourceDocumentRepo.collect{TaxInvoices,CashReceipts}로 수집(방향 무관 세금계산서 매출/매입 + 현금영수증). 결과는 syncRuns(type hometax·신규/중복 건수)로 기록하고, 수집된 서비스의 adapterStatus를 demo-collected로 반영 → integrationHealth가 데모 수집 가능(success)으로 전환.
  • 카드 승인내역 연동 섹션의 [카드 수집 실행] = syncCardSourceDocuments(). 원천이 홈택스(국세청)와 다른 여신금융협회/카드사라 별도 실행·별도 syncRun(type card). 사용 설정된 card-sales(여신금융협회 매출 승인내역)·card-purchase(법인카드 사용내역)만 accountingSourceDocumentRepo.collect{CardSales,CardPurchases}로 수집. 카드 서비스는 카탈로그 category:'card'·기본 비활성 옵트인(활성 시 providerFeeItems/monthlyProviderFee에 반영). 수집분은 회계 거래수집에서 카드 매출=DR 외상매출금/CR 매출+부가세예수금, 카드 매입=DR 비용+부가세대급금/CR 미지급금(0253) 후보로 매핑(매퍼가 source 무관 처리).
  • ⚠ 실 바로빌 스크래핑이 아니다 — accountingSourceDocumentRepo.collect*는 accountingSourceDocumentMock.COLLECTIBLE을 (source, external_key) 멱등 병합하는 Prototype 데모 수집(상세: accounting-source-documents-barobill.md §2-1). 실 어댑터 스왑 시 이 orchestration(서비스 게이팅·syncRun 기록)은 그대로 두고 repo 어댑터만 라이브로 교체.
  • 수집분은 재무 › 증빙 관리(EvidenceMainOrg)와 회계 › 거래수집(OperatingTransactionCollectionInboxOrg → 전표 후보)로 흐른다 — 연동 화면이 수집 트리거의 플랫폼 레벨 진입점, 재무/회계는 소비처.
  • 경계: useBarobillIntegration(platform-core)이 accountingSourceDocumentRepo(accounting-source-documents)를 소비 → platform-core→accounting-source-documents=2(baseline 갱신·audit clean).

개발팀 다음 순서 ​

  1. Company external integration repository를 migration 테이블에 연결한다.
  2. 바로빌 홈택스 조회 Edge Function과 일 배치를 구현해 accountingSourceDocumentRepo의 데모 collect를 라이브 어댑터로 스왑한다(orchestration 계약 유지).
  3. 수집 원문을 정규화하고 중복 제거 후 accounting_source_documents에 upsert한다(external_key 유니크).
  4. 재수집·오류 상세·만료 알림과 관리자 권한·감사로그를 연결한다.