SamProject/sam-docs
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: [barobill] React 프론트엔드 개선 요청서 작성

Browse Source 
- 신규 API 11개 엔드포인트 연결 가이드 (요청/응답 명세)
- 설정 페이지 개선: 연동 현황 대시보드, 계좌/카드 목록, 인증서/잔액
- 은행/카드 조회 화면: 동기화 버튼 추가 요청
- Server Action 6개 코드 예시 제공
- UI 와이어프레임 포함
This commit is contained in:
김보곤
2026-03-17 15:02:05 +09:00
parent 3588bb3dd7
commit b50e31a038
2 changed files with 405 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
INDEX.md
View File

@@ -281,6 +281,7 @@ DB 도메인별:
| [vehicle-react-implementation.md](plans/vehicle-react-implementation.md) | 차량관리 React 구현 요청서 (3개 메뉴, 컴포넌트 구조, 타입 정의) |
| [stock-production-react-request.md](plans/stock-production-react-request.md) | 재고생산관리 React 구현 요청서 (수주 화면 단순화, API 스펙 포함) |
| [bending-lot-react-request.md](plans/bending-lot-react-request.md) | 절곡품 LOT 재고생산 React 구현 요청서 (캐스케이딩 드롭다운, LOT 자동생성, 취소 복원) |
| [barobill-react-improvement-request.md](plans/barobill-react-improvement-request.md) | 바로빌 React 개선 요청서 (동기화 버튼, 인증서/잔액 표시, 계좌/카드 목록, Server Action 6개) |
### frontend/integration/ — 프론트엔드 개발 가이드

404
plans/barobill-react-improvement-request.md Normal file
View File

@@ -0,0 +1,404 @@
# 바로빌 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