# 바로빌 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<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 기술 참조](../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
