From a0a4f37cb111e43b02dd94eeba3010ba925c9171 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EA=B9=80=EB=B3=B4=EA=B3=A4?= Date: Thu, 19 Mar 2026 11:44:52 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20[finance]=20=EA=B3=84=EC=A0=95=EB=B3=84?= =?UTF-8?q?=EC=9B=90=EC=9E=A5=C2=B7=EC=86=90=EC=9D=B5=EA=B3=84=EC=82=B0?= =?UTF-8?q?=EC=84=9C=20API=20=EB=AA=85=EC=84=B8=20=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- INDEX.md | 1 + .../account-ledger-income-statement-api.md | 225 ++++++++++++++++++ 2 files changed, 226 insertions(+) create mode 100644 frontend/api-specs/account-ledger-income-statement-api.md diff --git a/INDEX.md b/INDEX.md index c3040ac..0f148b2 100644 --- a/INDEX.md +++ b/INDEX.md @@ -316,6 +316,7 @@ DB 도메인별: | [ai-token-usage-api.md](frontend/api-specs/ai-token-usage-api.md) | AI 토큰사용량 API 명세 (2개 엔드포인트 + 화면 가이드 + 타입 정의) | | [usage-subscription-api.md](frontend/api-specs/usage-subscription-api.md) | 이용현황(구독관리 통합) API 명세 (API 완료, 화면 가이드, 타입 정의, 피드백 반영) | | [nonconforming-api.md](frontend/api-specs/nonconforming-api.md) | 부적합관리 API 명세 (7개 엔드포인트 + 화면 가이드 + Server Actions 예시) | +| [account-ledger-income-statement-api.md](frontend/api-specs/account-ledger-income-statement-api.md) | 계정별원장·손익계산서 API 명세 (2개 엔드포인트 + TypeScript 타입 + 화면 가이드) | | [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 자동생성, 취소 복원) | diff --git a/frontend/api-specs/account-ledger-income-statement-api.md b/frontend/api-specs/account-ledger-income-statement-api.md new file mode 100644 index 0000000..4f6e814 --- /dev/null +++ b/frontend/api-specs/account-ledger-income-statement-api.md @@ -0,0 +1,225 @@ +# 계정별원장·손익계산서 API 명세 + +> **작성일**: 2026-03-19 +> **상태**: API 완료, React 미구현 +> **대상**: React 프론트엔드 개발자 + +--- + +## 1. 개요 + +회계/세무 메뉴에 **계정별원장**과 **손익계산서** 2개 화면을 추가한다. +일반전표 + 홈택스 세금계산서 분개 데이터를 통합 조회하여 계정별 거래 내역과 기간별 손익 현황을 표시한다. + +### 메뉴 위치 (MNG 기준) + +``` +회계/세무관리 +├── 일반전표입력 ← 기존 +├── 계정별원장 ← NEW +├── 손익계산서 ← NEW +├── 전자세금계산서 ← 기존 +├── ... +``` + +--- + +## 2. 계정별원장 API + +### 2.1 엔드포인트 + +| Method | Path | 설명 | +|--------|------|------| +| `GET` | `/api/v1/account-ledger` | 계정별원장 조회 | + +### 2.2 요청 파라미터 + +| 파라미터 | 타입 | 필수 | 설명 | +|---------|------|:----:|------| +| `start_date` | `string(date)` | Y | 조회 시작일 (`2026-01-01`) | +| `end_date` | `string(date)` | Y | 조회 종료일 (`2026-03-19`) | +| `account_code` | `string` | Y | 계정과목 코드 (`81100`) | + +### 2.3 응답 구조 + +```typescript +interface AccountLedgerResponse { + success: boolean; + message: string; + data: { + account: { + code: string; // "81100" + name: string; // "복리후생비" + category: string; // "expense" + } | null; + period: { + start_date: string; // "2026-01-01" + end_date: string; // "2026-03-19" + }; + carry_forward: { + debit: number; // 이월 차변 합계 + credit: number; // 이월 대변 합계 + balance: number; // 이월 잔액 + }; + monthly_data: MonthlyData[]; + grand_total: { + debit: number; + credit: number; + balance: number; + }; + }; +} + +interface MonthlyData { + month: string; // "2026-03" + items: LedgerItem[]; + subtotal: { debit: number; credit: number }; + cumulative: { debit: number; credit: number }; +} + +interface LedgerItem { + date: string; // "2026-03-01" + description: string | null; // 적요 + trading_partner_name: string | null; // 거래처명 + biz_no: string | null; // 사업자번호 + debit_amount: number; // 차변 금액 + credit_amount: number; // 대변 금액 + balance: number; // 누적 잔액 + source_type: 'journal' | 'hometax'; // 출처 + source_id: number; // 전표ID 또는 홈택스 인보이스ID +} +``` + +### 2.4 잔액 계산 규칙 + +| 계정 카테고리 | 정상 잔액 | 계산 | +|-------------|----------|------| +| `asset` (자산) | 차변 | 차변 - 대변 | +| `expense` (비용) | 차변 | 차변 - 대변 | +| `liability` (부채) | 대변 | 대변 - 차변 | +| `capital` (자본) | 대변 | 대변 - 차변 | +| `revenue` (수익) | 대변 | 대변 - 차변 | + +### 2.5 화면 요구사항 + +- **조회 필터**: 기간(date range) + 계정과목 검색 (코드/이름) +- **계정과목 목록**: 기존 `GET /api/v1/account-subjects` 활용 +- **테이블 구조**: 날짜, 적요, 거래처, 사업자번호, 차변, 대변, 잔액 +- **월별 소계/누계**: 월이 바뀔 때마다 소계 행 + 누계 행 표시 +- **이월잔액**: 조회 시작일 이전 잔액 (첫 행에 표시) +- **드릴다운**: 행 클릭 시 원본 전표 상세 조회 (`source_type` + `source_id`) + - `journal` → `GET /api/v1/general-journal-entries/{source_id}` + - `hometax` → 홈택스 세금계산서 상세 +- **홈택스 태그**: `source_type === 'hometax'`인 행에 `[홈택스]` 표시 + +--- + +## 3. 손익계산서 API + +### 3.1 엔드포인트 + +| Method | Path | 설명 | +|--------|------|------| +| `GET` | `/api/v1/income-statement` | 손익계산서 조회 | + +### 3.2 요청 파라미터 + +| 파라미터 | 타입 | 필수 | 설명 | +|---------|------|:----:|------| +| `start_date` | `string(date)` | Y | 당기 시작일 (`2026-01-01`) | +| `end_date` | `string(date)` | Y | 당기 종료일 (`2026-12-31`) | +| `unit` | `string` | N | `won` (기본) / `thousand` / `million` | + +> **전기**: API가 자동으로 전년 동기를 계산 (예: 2026 → 2025) + +### 3.3 응답 구조 + +```typescript +interface IncomeStatementResponse { + success: boolean; + message: string; + data: { + period: { + current: { start: string; end: string; label: string }; // "제 22 (당)기" + previous: { start: string; end: string; label: string }; // "제 21 (전)기" + }; + unit: 'won' | 'thousand' | 'million'; + sections: PLSection[]; + }; +} + +interface PLSection { + code: string; // "I", "II", ... "X" + name: string; // "매출액", "매출원가", ... + current_amount: number; // 당기 금액 + previous_amount: number; // 전기 금액 + items: PLItem[]; // 세부 계정과목 (계산 항목은 빈 배열) + is_calculated: boolean; // true = 계산 항목 (III, V, VIII, X) +} + +interface PLItem { + code: string; // 계정코드 "40100" + name: string; // 계정명 "상품매출" + current: number; // 당기 금액 + previous: number; // 전기 금액 +} +``` + +### 3.4 손익계산서 구조 + +``` +I. 매출액 ← sales_revenue 계정 합계 +II. 매출원가 ← cogs + construction_cost 계정 합계 +III. 매출총이익 = I - II ← 계산 (is_calculated: true) +IV. 판매비와관리비 ← selling_admin 계정 합계 +V. 영업이익 = III - IV ← 계산 +VI. 영업외수익 ← other_revenue 계정 합계 +VII. 영업외비용 ← other_expense 계정 (법인세 제외) +VIII.법인세비용차감전순이익 ← 계산 (V + VI - VII) +IX. 법인세비용 ← 계정코드 99800(법인세) + 99900(소득세등) +X. 당기순이익 = VIII - IX ← 계산 +``` + +### 3.5 화면 요구사항 + +- **조회 필터**: 기간(date range) + 금액 단위 선택 +- **테이블**: 과목 | 당기 금액(2열) | 전기 금액(2열) +- **당기 컬럼 2열**: 세부 금액(왼쪽) + 소계(오른쪽) + - 세부 항목이 있는 섹션: 마지막 행의 오른쪽 열에 소계 표시 + - 계산 항목(`is_calculated`): 오른쪽 열에만 금액 표시 +- **계산 항목 강조**: III(매출총이익), V(영업이익), X(당기순이익) 등 배경색 구분 +- **들여쓰기**: 세부 항목(`items`)은 과목 이름 앞에 들여쓰기 +- **단위 표시**: 하단에 `(단위: 원)` 등 표시 +- **인쇄**: 인쇄 버튼 (CSS `@media print` 활용) + +--- + +## 4. 참고: MNG 구현 화면 + +MNG(백오피스)에는 이미 동일 기능이 구현되어 있다. 화면 레이아웃과 UX를 참고한다. + +- **계정별원장**: 더존 프로그램 스타일의 원장 뷰 + 행 클릭 시 전표 상세 모달 +- **손익계산서**: 더존 프로그램 스타일의 P&L 테이블 + 당기/전기 비교 + +> MNG 개발서버: `https://admin.codebridge-x.com` → 회계/세무관리 메뉴 + +--- + +## 5. 관련 API + +| API | 용도 | +|-----|------| +| `GET /api/v1/account-subjects` | 계정과목 목록 (계정별원장 필터용) | +| `GET /api/v1/general-journal-entries/{id}` | 전표 상세 (계정별원장 드릴다운) | + +--- + +## 관련 문서 + +- [dev/dev_plans/account-ledger-income-statement-plan.md](../../dev/dev_plans/account-ledger-income-statement-plan.md) — 전체 기획서 +- [features/finance/README.md](../../features/finance/README.md) — 재무관리 기능 개요 +- [frontend/api-specs/barobill-api.md](barobill-api.md) — 바로빌 회계 API 명세 + +--- + +**최종 업데이트**: 2026-03-19