# 바로빌 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` 응답이 변경되었다: ```json { "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 응답 타입 확장 ```typescript // types.ts — IntegrationStatus 수정 export interface IntegrationStatus { bankServiceCount: number; accountLinkCount: number; cardCount: number; // ← 추가 member?: { barobillId: string; bizNo: string; corpName: string; // ← 추가 status: string; serverMode: string; }; } ``` ```typescript // 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`에 추가해야 한다. ```typescript // ===== 은행 동기화 ===== export async function syncBankTransactions( startDate?: string, endDate?: string ): Promise> { 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> { return executeServerAction({ url: buildApiUrl('/api/v1/barobill/sync/card'), method: 'POST', body: { start_date: startDate, end_date: endDate, }, errorMessage: '카드 거래 동기화에 실패했습니다.', }); } // ===== 등록 계좌 목록 ===== export async function getRegisteredAccounts(): Promise; }>> { return executeServerAction({ url: buildApiUrl('/api/v1/barobill/accounts'), errorMessage: '등록 계좌 조회에 실패했습니다.', }); } // ===== 등록 카드 목록 ===== export async function getRegisteredCards(): Promise; }>> { return executeServerAction({ url: buildApiUrl('/api/v1/barobill/cards'), errorMessage: '등록 카드 조회에 실패했습니다.', }); } // ===== 인증서 상태 ===== export async function getCertificateStatus(): Promise> { return executeServerAction({ url: buildApiUrl('/api/v1/barobill/certificate'), errorMessage: '인증서 상태 조회에 실패했습니다.', }); } // ===== 충전잔액 ===== export async function getBalance(): Promise> { 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 기술 참조](../features/barobill/api-soap-reference.md) | API 전체 메서드, 동기화, 스케줄러 | | [온보딩 실행 가이드](../guides/barobill-onboarding-guide.md) | 7단계 절차, API 예시 | | [바로빌 API 명세](../frontend/api-specs/barobill-api.md) | 기존 42개 REST API 상세 | | [바로빌 연동 시스템](../features/barobill/README.md) | 전체 구조, 테스트/운영 모드 | --- **최종 업데이트**: 2026-03-17