From b50e31a0383e214864cb8c089022b62e60de18e5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EA=B9=80=EB=B3=B4=EA=B3=A4?= Date: Tue, 17 Mar 2026 15:02:05 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20[barobill]=20React=20=ED=94=84=EB=A1=A0?= =?UTF-8?q?=ED=8A=B8=EC=97=94=EB=93=9C=20=EA=B0=9C=EC=84=A0=20=EC=9A=94?= =?UTF-8?q?=EC=B2=AD=EC=84=9C=20=EC=9E=91=EC=84=B1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 신규 API 11개 엔드포인트 연결 가이드 (요청/응답 명세) - 설정 페이지 개선: 연동 현황 대시보드, 계좌/카드 목록, 인증서/잔액 - 은행/카드 조회 화면: 동기화 버튼 추가 요청 - Server Action 6개 코드 예시 제공 - UI 와이어프레임 포함 --- INDEX.md | 1 + plans/barobill-react-improvement-request.md | 404 ++++++++++++++++++++ 2 files changed, 405 insertions(+) create mode 100644 plans/barobill-react-improvement-request.md diff --git a/INDEX.md b/INDEX.md index cc172e6..aa3ba31 100644 --- a/INDEX.md +++ b/INDEX.md @@ -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/ — 프론트엔드 개발 가이드 diff --git a/plans/barobill-react-improvement-request.md b/plans/barobill-react-improvement-request.md new file mode 100644 index 0000000..653e402 --- /dev/null +++ b/plans/barobill-react-improvement-request.md @@ -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> { + 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