Leyve Docs

다크모드

회계증빙관리 — 바로빌 수집 연동·데이터 모델 (BE 참고) ​

독자: BE 개발자/AI. 작성: 2026-07-11, 상태 갱신: 2026-07-13. as-built = FE mock(accountingSourceDocumentMock/Repo) — 홈택스 실수집 0. 은행 조회는 별도 읽기 전용 Edge 연동이 있다. 상위 전략 정합: PLANNING-STAGE-DB-SUPABASE-2026-07-09 — 대외연동은 어댑터 seam 뒤 한 곳(공전소 docubank 핸드오프와 동형).

BE 함의(2026-07-26 개정): FE 데모 규칙 분류(accountingSourceDocumentClassifyRules.js)는 서버화 시 accounting_source_document_classification_rules(counterparty_pattern·item_pattern·direction·account_id·priority) 테이블 + 수집 시점 자동 제안으로 승격한다. 수동 분류 우선(멱등) 불변식은 유지한다.

1. 데이터 모델 — accounting_source_documents ​

운영 목표는 AWS + RDS MariaDB다. 전체 파일·버전·링크 모델은 docs/decisions/DOCUMENT-DOMAIN-BOUNDARIES-2026-07-26.md가 정본이며, 이 aggregate는 파일 바이트를 직접 저장하지 않고 document_version_id를 참조한다.

sql
create table accounting_source_documents (
  id binary(16) primary key,
  company_id binary(16) not null,
  workspace_id binary(16) not null,
  document_version_id binary(16) null,
  direction enum('sales','purchase') not null,
  source_type varchar(40) not null,
  external_key varchar(255) null,
  issued_on date not null,
  counterparty_id binary(16) null,
  counterparty_registration_number varchar(40) null,
  supply_amount decimal(19,4) not null,
  tax_amount decimal(19,4) not null,
  currency char(3) not null,
  account_id binary(16) null,
  classification_status varchar(30) not null,
  journal_candidate_id binary(16) null,
  collected_at datetime(6) null,
  created_at datetime(6) not null,
  unique key uq_accounting_source_external
    (company_id, workspace_id, source_type, external_key)
);
  • 재수집 멱등 범위는 (company_id, workspace_id, source_type, external_key)다.
  • 원문·금액·발행일은 수정하지 않는다. 분류 상태와 account_id, 전표 후보 연결만 상태전이를 거친다.
  • FE mock의 source, date, bizNo, vat, accountCode는 어댑터 DTO다. 서버 경계에서 각각 sourceType, issuedOn, counterpartyRegistrationNumber, taxAmount, accountId로 정규화한다.

2. 바로빌 수집 API 매핑 (seam accountingSourceDocumentRepo — collect류) ​

seam 메서드바로빌 서비스비고
collectTaxInvoices(period)세금계산서 API (BarobillAPI TI — 매출/매입 목록·상세 조회)발행분은 기존 세금계산서 앱(useTaxInvoiceIssuance)과 원천 동일 — external_key로 중복 방지
collectCardSales(period)카드매출 조회 API (여신금융협회 승인내역)협회 측 차단 이슈 이력 있음(가용성 유의)
collectCardPurchases(period)법인카드 사용내역(매입) 조회카드사별 등록 필요
collectCashReceipts(period)현금영수증 API (CASHBILL — 발행/수취 조회)
(후속) 계좌 입출금계좌조회 API (BANK)⚠ 수납 대사 3채널과 공유 원천 — collecting 레인(FEATURE-COLLECTING-RECONCILIATION-CHANNELS)과 어댑터 공용화 협의 후 진행
  • 인증: 바로빌 연동회원(연동 ID + API 인증키). Edge Function(barobill-collect-*)이 보관 — 브라우저 노출 금지.
  • 수집 주기: 일 배치 + 화면 [바로빌 수집] 수동 트리거. 실패 격리·TraceId 리포트(공전소 §8 동형).
  • Company 공통 연동·요금·Office 매핑은 barobill-company-integration.md를 SSOT로 삼는다.

2-1. as-built (2026-07-21) — collect seam 데모 실배선 ​

  • accountingSourceDocumentRepo.collect{TaxInvoices,CardSales,CardPurchases,CashReceipts}는 더 이상 NOT_WIRED throw가 아니다. Prototype 데모 수집으로 실배선됨 — accountingSourceDocumentMock.COLLECTIBLE(홈택스/바로빌이 가져올 시나리오 증빙 풀)을 evidences로 (source, external_key) 멱등 병합(collectEvidences(predicate)). 반환 { added, skipped }.
  • 회계증빙관리 [증빙 자동수집] 버튼은 연동 미설정(accountingSourceDocumentReadiness==='limited')일 때만 disabled, 그 외에는 방향별(매출: 세금계산서+카드매출+현금영수증 / 매입: 세금계산서+카드매입+현금영수증) 수집 실행. 재수집 시 이미 있는 external_key는 스킵(중복 없음).
  • ⚠ 이는 실 스크래핑이 아니다. 실 바로빌/홈택스 연동은 아래 라이브 어댑터 스케치(makeSupabaseRepo → barobill-collect-* Edge)로 스왑하며, 연동회원 인증키·자격증명·Edge 배포가 선행이다. 정직 표기(시나리오 데이터 badge)는 유지.
  • 서버화 시 external_key는 §1 accounting_source_documents.external_key(수집 멱등 키)로 승격 — FE collectEvidences의 (source, external_key) 스킵 규칙이 그대로 DB (source, external_key) 유니크 제약으로 이관된다.

3. 예상 부가세 규칙 (as-built) ​

  • A(매출 세액) − B(매입 세액) = 예정 납부 세액. 분기 = 작성일 기준(월→분기), 원천별 분해 Σ 보존(vitest 고정).
  • 미포함(정직 표기): 세액공제(신용카드 발행 공제 등)·예정고지세액·불공제 매입(접대비 등) 분류. 불공제 처리는 account_code 기반 후속.
  • 확정 신고값과의 대사는 세무대리인/홈택스 몫 — 본 화면은 경영 추정용.

4. 회계·수납 레인 경계 (2026-07-11 합의 전제) ​

  • 계정과목 마스터(CoA)·분개 전기 = 회계 모듈(다른 레인) — 본 모듈은 분류 라벨까지만, CoA FK 연결은 협의 후.
  • 계좌 입출금·수납 대사 = collecting 레인 파킹 캡처 존중 — 본 모듈 비범위.

5. 반응형 표현 계약과 API 무변경 (2026-07-13) ​

  • FE는 동일한 증빙 목록을 PC 표와 휴대폰 카드로 나누어 표현한다. 두 표현 모두 같은 id, account_code, 분류 mutation을 사용하므로 별도 mobile endpoint나 DTO를 만들지 않는다.
  • 조회 월 Select의 value는 기존 YYYY-MM, 전체 기간은 빈 문자열이다. 원천 Select/탭의 value도 기존 source enum(taxInvoice|card|cashReceipt|pg, 전체는 빈 문자열)을 그대로 쓴다.
  • 계정과목 Select는 PC에서 최소 폭, 모바일에서 카드 전체 폭으로 표시될 뿐 저장 계약은 동일하다: classify(id, accountCode|null). 빈 값은 null=미분류로 정규화한다.
  • 모바일 카드가 합계금액을 먼저 노출하더라도 서버 합계 필드는 추가하지 않는다. supply_amount + vat로 FE가 파생하며 두 원천 금액의 불변식은 유지한다.