docs: [finance] 계정별원장·손익계산서 API 명세 추가
This commit is contained in:
김보곤
1
INDEX.md
1
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 자동생성, 취소 복원) |
|
||||
|
||||
225
frontend/api-specs/account-ledger-income-statement-api.md
Normal file
225
frontend/api-specs/account-ledger-income-statement-api.md
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user