sam-docs/plans/barobill-react-improvement-request.md

바로빌 React 프론트엔드 개선 요청서

작성일: 2026-03-17 요청자: R&D 실장 대상: 프론트엔드 개발자 우선순위: 🔴 P1 배경: API에 바로빌 SOAP 동기화 서비스가 신규 구축되었으나, React에서 아직 연결되지 않은 부분이 많다.

---

1. 현재 상황

1.1 API 구축 완료 (백엔드)

API에 바로빌 SOAP 서비스가 11개 신규 엔드포인트로 구축 완료되었다. 은행/카드/홈택스 데이터를 바로빌에서 직접 수집(동기화)할 수 있다.

1.2 React 현재 상태 (프론트엔드)

화면	경로	상태	문제
바로빌 설정	/settings/barobill-integration	부분 동작	신규 API 미연결 (동기화, 인증서 상태 등)
은행 거래 조회	/accounting/bank-transactions	동작	수동 동기화 트리거 없음
카드 거래 조회	/accounting/card-transactions	동작	수동 동기화 트리거 없음
홈택스 세금계산서	/accounting/hometax-invoices	동작	수동 동기화 트리거 없음

1.3 핵심 문제

❌ 바로빌 설정 페이지에서 "연동 현황"이 0/0으로 표시 (실제 데이터 있어도)
❌ 인증서 상태(유효/만료일) 표시 없음
❌ 충전잔액 표시 없음
❌ 등록된 계좌/카드 목록 조회 없음 (바로빌 실시간)
❌ 수동 동기화 버튼이 어디에도 없음
❌ 동기화 결과/상태 표시 없음
❌ 카드 수 표시 없음 (status API에 card_count 추가됨)

---

2. 신규 API 엔드포인트 (연결 필요)

2.1 동기화 API (3개)

Method	Path	용도	요청 Body	응답
POST	/api/v1/barobill/sync/bank	은행 거래 수동 동기화	{ start_date?: "YYYYMMDD", end_date?: "YYYYMMDD" }	{ synced: 15, accounts: 2 }
POST	/api/v1/barobill/sync/card	카드 거래 수동 동기화	{ start_date?: "YYYYMMDD", end_date?: "YYYYMMDD" }	{ synced: 8, cards: 1 }
POST	/api/v1/barobill/sync/hometax	홈택스 수동 동기화	{ invoices: [...], invoice_type: "sales"|"purchase" }	{ inserted: 3, updated: 1 }

start_date/end_date 생략 시 기본값: 전월~오늘

2.2 실시간 조회 API (4개)

Method	Path	용도	응답
GET	/api/v1/barobill/accounts	바로빌 등록계좌 목록	{ accounts: [{ bankAccountNum, bankName, bankCode }] }
GET	/api/v1/barobill/cards	바로빌 등록카드 목록	{ cards: [{ cardNum, cardCompany, cardCompanyName, alias }] }
GET	/api/v1/barobill/certificate	인증서 상태	{ certificate: { is_valid, expire_date, regist_date } }
GET	/api/v1/barobill/balance	충전잔액	{ balance: 50000 }

2.3 회원관리 API (3개)

Method	Path	용도	요청 Body
POST	/api/v1/barobill/members	바로빌 회원 등록 (SOAP)	{ biz_no, corp_name, ceo_name, barobill_id, barobill_pwd, ... }
PUT	/api/v1/barobill/members	바로빌 회원 수정	{ corp_name, ceo_name, ... }
GET	/api/v1/barobill/members/status	바로빌 회원 상태	응답: { member: {...}, barobill_state: ... }

2.4 기존 status API 보강

GET /api/v1/barobill/status 응답이 변경되었다:

{
  "bank_service_count": 2,
  "account_link_count": 2,
  "card_count": 3,
  "member": {
    "barobill_id": "juil5130",
    "biz_no": "138-81-66437",
    "corp_name": "(주)주일기업",
    "status": "active",
    "server_mode": "test"
  }
}

변경점:

• card_count 필드 추가 (기존에 없었음)
• member.corp_name 필드 추가
• member.biz_no 포맷 변경 (하이픈 포함 XXX-XX-XXXXX)

---

3. 개선 요청 사항

3.1 바로빌 설정 페이지 개선 (P1)

파일: src/components/settings/BarobillIntegration/

3.1.1 status API 응답 타입 확장

// types.ts — IntegrationStatus 수정
export interface IntegrationStatus {
  bankServiceCount: number;
  accountLinkCount: number;
  cardCount: number;          // ← 추가
  member?: {
    barobillId: string;
    bizNo: string;
    corpName: string;         // ← 추가
    status: string;
    serverMode: string;
  };
}

// actions.ts — transform 수정
transform: (data) => ({
  bankServiceCount: data.bank_service_count ?? 0,
  accountLinkCount: data.account_link_count ?? 0,
  cardCount: data.card_count ?? 0,              // ← 추가
  member: data.member ? {
    barobillId: data.member.barobill_id ?? '',
    bizNo: data.member.biz_no ?? '',
    corpName: data.member.corp_name ?? '',       // ← 추가
    status: data.member.status ?? '',
    serverMode: data.member.server_mode ?? '',
  } : undefined,
}),

3.1.2 연동 상태 대시보드 섹션 추가

설정 페이지 상단에 "연동 현황" 요약 카드를 추가한다.

┌────────────────────────────────────────────────────────────────┐
│  연동 현황                                                      │
│                                                                │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────┐   │
│  │ 계좌  2개 │  │ 카드  3개 │  │ 인증서 ✅ │  │ 잔액 50,000원│   │
│  └──────────┘  └──────────┘  └──────────┘  └──────────────┘   │
│                                                                │
│  회원: juil5130 | 사업자: 138-81-66437 | 모드: 테스트           │
└────────────────────────────────────────────────────────────────┘

필요한 API 호출:

• GET /api/v1/barobill/status — 계좌/카드 수, 회원 정보
• GET /api/v1/barobill/certificate — 인증서 유효성/만료일
• GET /api/v1/barobill/balance — 충전잔액

3.1.3 등록 계좌/카드 목록 표시

현재 계좌/카드는 숫자만 표시된다. 실제 목록을 보여준다.

┌──────────────────────────────┐
│  등록된 계좌 (2개)            │
│  ┌────────────────────────┐  │
│  │ 신한은행 110-XXX-XXXX  │  │
│  │ 국민은행 012-XXX-XXXX  │  │
│  └────────────────────────┘  │
│                              │
│  등록된 카드 (3개)            │
│  ┌────────────────────────┐  │
│  │ 삼성카드 9410-XXXX-... │  │
│  │ 현대카드 4512-XXXX-... │  │
│  │ 신한카드 5210-XXXX-... │  │
│  └────────────────────────┘  │
└──────────────────────────────┘

필요한 API 호출:

• GET /api/v1/barobill/accounts — 계좌 목록
• GET /api/v1/barobill/cards — 카드 목록

3.2 수동 동기화 버튼 추가 (P1)

은행/카드/홈택스 조회 화면에 [동기화] 버튼을 추가한다.

3.2.1 은행 거래 조회 화면

파일: src/components/accounting/BankTransactionInquiry/

┌──────────────────────────────────────────┐
│ 은행 거래 조회                [🔄 동기화] │
│ 기간: 2026-03-01 ~ 2026-03-17           │
│ ─────────────────────────────────────── │
│ 날짜 | 계좌 | 입금 | 출금 | 잔액 | 적요 │
│ ...                                      │
└──────────────────────────────────────────┘

동기화 버튼 동작:

1. 현재 필터의 시작일/종료일을 YYYYMMDD 형식으로 변환
2. POST /api/v1/barobill/sync/bank 호출 (body: { start_date, end_date })
3. 성공 시 toast: "은행 거래 {N}건 동기화 완료" + 목록 새로고침
4. 로딩 중 버튼 비활성화 + 스피너 표시

3.2.2 카드 거래 조회 화면

파일: src/components/accounting/CardTransactionInquiry/

동일한 패턴:

• POST /api/v1/barobill/sync/card 호출
• 성공 시 toast: "카드 거래 {N}건 동기화 완료"

3.2.3 홈택스 세금계산서 화면

파일: src/components/accounting/TaxInvoiceManagement/ (또는 관련 홈택스 컴포넌트)

홈택스는 동기화 구조가 다르다 — API에서 데이터를 받아 sync 요청:

• POST /api/v1/barobill/sync/hometax (body: { invoices: [...], invoice_type })

현재 홈택스 동기화는 데이터를 먼저 받아서 body에 넣어야 하므로, UI 플로우를 별도 설계해야 할 수 있다. 우선 은행/카드 동기화 버튼을 먼저 구현하고, 홈택스는 후순위로 진행한다.

3.3 인증서 만료 경고 표시 (P2)

인증서 만료 30일 이내인 경우 설정 페이지 및 대시보드에 경고를 표시한다.

⚠️ 공동인증서가 30일 이내 만료됩니다. (만료일: 2026-04-15)
   [인증서 갱신하기]

3.4 충전잔액 부족 경고 (P2)

잔액이 10,000원 미만인 경우 경고를 표시한다.

⚠️ 바로빌 충전잔액이 부족합니다. (현재: 3,000원)
   [충전하기]

---

4. actions.ts 추가 함수

아래 Server Action 함수들을 actions.ts에 추가해야 한다.

// ===== 은행 동기화 =====
export async function syncBankTransactions(
  startDate?: string,
  endDate?: string
): Promise<ActionResult<{ synced: number; accounts: number }>> {
  return executeServerAction({
    url: buildApiUrl('/api/v1/barobill/sync/bank'),
    method: 'POST',
    body: {
      start_date: startDate,
      end_date: endDate,
    },
    errorMessage: '은행 거래 동기화에 실패했습니다.',
  });
}

// ===== 카드 동기화 =====
export async function syncCardTransactions(
  startDate?: string,
  endDate?: string
): Promise<ActionResult<{ synced: number; cards: number }>> {
  return executeServerAction({
    url: buildApiUrl('/api/v1/barobill/sync/card'),
    method: 'POST',
    body: {
      start_date: startDate,
      end_date: endDate,
    },
    errorMessage: '카드 거래 동기화에 실패했습니다.',
  });
}

// ===== 등록 계좌 목록 =====
export async function getRegisteredAccounts(): Promise<ActionResult<{
  accounts: Array<{ bankAccountNum: string; bankName: string; bankCode: string }>;
}>> {
  return executeServerAction({
    url: buildApiUrl('/api/v1/barobill/accounts'),
    errorMessage: '등록 계좌 조회에 실패했습니다.',
  });
}

// ===== 등록 카드 목록 =====
export async function getRegisteredCards(): Promise<ActionResult<{
  cards: Array<{ cardNum: string; cardCompany: string; cardCompanyName: string; alias: string }>;
}>> {
  return executeServerAction({
    url: buildApiUrl('/api/v1/barobill/cards'),
    errorMessage: '등록 카드 조회에 실패했습니다.',
  });
}

// ===== 인증서 상태 =====
export async function getCertificateStatus(): Promise<ActionResult<{
  certificate: { is_valid: boolean; expire_date: string | null; regist_date: string | null };
}>> {
  return executeServerAction({
    url: buildApiUrl('/api/v1/barobill/certificate'),
    errorMessage: '인증서 상태 조회에 실패했습니다.',
  });
}

// ===== 충전잔액 =====
export async function getBalance(): Promise<ActionResult<{ balance: number | null }>> {
  return executeServerAction({
    url: buildApiUrl('/api/v1/barobill/balance'),
    errorMessage: '충전잔액 조회에 실패했습니다.',
  });
}

---

5. 수정 대상 파일 목록

파일	작업	우선순위
settings/BarobillIntegration/types.ts	IntegrationStatus에 cardCount, corpName 추가	P1
settings/BarobillIntegration/actions.ts	6개 신규 Server Action 추가, transform 수정	P1
settings/BarobillIntegration/index.tsx	연동 현황 대시보드, 계좌/카드 목록, 인증서/잔액 표시	P1
accounting/BankTransactionInquiry/actions.ts	syncBankTransactions import (또는 별도 생성)	P1
accounting/BankTransactionInquiry/index.tsx	[동기화] 버튼 추가	P1
accounting/CardTransactionInquiry/actions.ts	syncCardTransactions import	P1
accounting/CardTransactionInquiry/index.tsx	[동기화] 버튼 추가	P1

---

6. UI 와이어프레임

6.1 설정 페이지 개선안

┌─────────────────────────────────────────────────────────────────┐
│  바로빌 연동 관리                                                │
│  바로빌 청구, 장부를 연동합니다.                                  │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─ 연동 현황 ─────────────────────────────────────────────┐    │
│  │  👤 juil5130 | (주)주일기업 | 138-81-66437              │    │
│  │  모드: [테스트]                                          │    │
│  │                                                         │    │
│  │  🏦 계좌 2개    💳 카드 3개    📜 인증서 ✅    💰 50,000원│    │
│  │         만료: 2027-12-31                                │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                 │
│  ─── 등록된 계좌 ───────────────────────────────────────────     │
│  │ 신한은행  110-XXX-XXXX │ 국민은행  012-XXX-XXXX │            │
│                                                                 │
│  ─── 등록된 카드 ───────────────────────────────────────────     │
│  │ 삼성카드 9410-XXXX │ 현대카드 4512-XXXX │ 신한카드 5210 │    │
│                                                                 │
│  ─── 바로빌 연동 ──────────────────────────────────────────     │
│  (기존 로그인/회원가입 카드 그대로)                               │
│                                                                 │
│  ─── 계좌 연동 ────────────────────────────────────────────     │
│  (기존 은행 빠른조회/계좌 연동 카드 그대로)                       │
│                                                                 │
│  ─── 카드 연동 / 공인인증서 ───────────────────────────────     │
│  (기존 카드 연동/인증서 등록 카드 그대로)                         │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

6.2 은행/카드 조회 동기화 버튼

┌─────────────────────────────────────────────────────┐
│ 은행 거래 조회                                       │
│                                                     │
│ 기간: [2026-03-01] ~ [2026-03-17]  [조회] [🔄 동기화]│
│                                                     │
│ ┌──────────────────────────────────────────────────┐│
│ │날짜     │계좌        │입금    │출금    │잔액      ││
│ │03-17   │신한 110-xxx│       │50,000 │1,250,000 ││
│ │03-16   │신한 110-xxx│300,000│       │1,300,000 ││
│ └──────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────┘

동기화 클릭 시:
  → [🔄 동기화 중...] (버튼 비활성 + 스피너)
  → 완료 toast: "은행 거래 15건 동기화 완료"
  → 목록 자동 새로고침

---

7. 참고 문서

문서	설명
API SOAP 기술 참조	API 전체 메서드, 동기화, 스케줄러
온보딩 실행 가이드	7단계 절차, API 예시
바로빌 API 명세	기존 42개 REST API 상세
바로빌 연동 시스템	전체 구조, 테스트/운영 모드

---

최종 업데이트: 2026-03-17