SamProject/sam-docs
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
93c0e2815c9c6bcbf261a87166928b014e4eef45
sam-docs/frontend/api-specs/income-statement-service-api.md

383 lines
13 KiB
Markdown
Raw Blame History

# 손익계산서 API 명세 (서비스 이관)
> **작성일**: 2026-03-20
> **상태**: API 완료, React 구현 대기
> **대상**: React 프론트엔드 개발자
---
## 1. 개요
회계관리 메뉴에 **손익계산서** 화면을 구현한다.
기간별 당기/전기 비교와 월별 비교 두 가지 보기 모드를 제공한다.
한국 일반기업회계기준에 따른 10개 항목(I~X) 구조로 매출액, 매출원가, 영업이익, 당기순이익 등을 표시한다.
### 메뉴 위치
```
회계관리
├── 일반전표입력 ← 기존
├── 계정별원장 ← 기존
├── 손익계산서 ← 이 화면
├── ...
```
---
## 2. API 엔드포인트
### 2.1 기간별 손익계산서
```
GET /api/v1/income-statement
```
**요청 파라미터** (Query String):
| 파라미터 | 타입 | 필수 | 설명 | 예시 |
|---------|------|:----:|------|------|
| `start_date` | `string(date)` | Y | 당기 시작일 | `2026-01-01` |
| `end_date` | `string(date)` | Y | 당기 종료일 | `2026-12-31` |
| `unit` | `string` | N | `won`(기본) / `thousand` / `million` | `won` |
> **전기**: API가 자동으로 전년 동기를 계산 (예: 2026 → 2025)
**응답 예시**:
```json
{
"success": true,
"message": "조회되었습니다.",
"data": {
"period": {
"current": {
"start": "2026-01-01",
"end": "2026-12-31",
"label": "제 2 (당)기"
},
"previous": {
"start": "2025-01-01",
"end": "2025-12-31",
"label": "제 1 (전)기"
}
},
"unit": "won",
"sections": [
{
"code": "I",
"name": "매출액",
"current_amount": 50000000,
"previous_amount": 30000000,
"items": [
{ "code": "40400", "name": "용역매출", "current": 50000000, "previous": 30000000 }
],
"is_calculated": false
},
{
"code": "II",
"name": "매출원가",
"current_amount": 20000000,
"previous_amount": 15000000,
"items": [
{ "code": "50100", "name": "서비스매출원가", "current": 12000000, "previous": 8000000 },
{ "code": "50200", "name": "외주용역비", "current": 8000000, "previous": 7000000 }
],
"is_calculated": false
},
{
"code": "III",
"name": "매출총이익",
"current_amount": 30000000,
"previous_amount": 15000000,
"items": [],
"is_calculated": true
}
]
}
}
```
---
### 2.2 월별 손익계산서
```
GET /api/v1/income-statement/monthly
```
**요청 파라미터** (Query String):
| 파라미터 | 타입 | 필수 | 설명 | 예시 |
|---------|------|:----:|------|------|
| `year` | `integer` | Y | 조회 연도 | `2026` |
| `unit` | `string` | N | `won`(기본) / `thousand` / `million` | `won` |
**응답 예시**:
```json
{
"success": true,
"message": "조회되었습니다.",
"data": {
"year": 2026,
"fiscal_year": 2,
"fiscal_label": "제 2 기",
"unit": "won",
"months": [
{
"month": "01",
"label": "1월",
"sections": [
{
"code": "I",
"name": "매출액",
"current_amount": 5000000,
"previous_amount": 5000000,
"items": [
{ "code": "40400", "name": "용역매출", "current": 5000000, "previous": 5000000 }
],
"is_calculated": false
}
]
},
{
"month": "02",
"label": "2월",
"sections": []
}
]
}
}
```
> **참고**: 미래 월은 응답에 포함되지 않는다.
> 월별 데이터에서 `previous_amount`와 `item.previous`는 `current`와 동일한 값 (월별 비교에서는 의미 없음).
---
## 3. TypeScript 인터페이스
```typescript
// 기간별 손익계산서 응답
interface IncomeStatementResponse {
success: boolean;
message: string;
data: {
period: {
current: { start: string; end: string; label: string }; // "제 2 (당)기"
previous: { start: string; end: string; label: string }; // "제 1 (전)기"
};
unit: 'won' | 'thousand' | 'million';
sections: PLSection[];
};
}
// 월별 손익계산서 응답
interface MonthlyIncomeStatementResponse {
success: boolean;
message: string;
data: {
year: number;
fiscal_year: number;
fiscal_label: string; // "제 2 기"
unit: 'won' | 'thousand' | 'million';
months: MonthPL[];
};
}
interface MonthPL {
month: string; // "01", "02", ...
label: string; // "1월", "2월", ...
sections: PLSection[];
}
interface PLSection {
code: string; // "I", "II", "III", ... "X"
name: string; // "매출액", "매출원가", "매출총이익", ...
current_amount: number; // 당기 금액
previous_amount: number; // 전기 금액
items: PLItem[]; // 세부 계정과목 (계산 항목은 빈 배열)
is_calculated: boolean; // true = 계산 항목 (III, V, VIII, X)
}
interface PLItem {
code: string; // 계정코드 "40400"
name: string; // 계정명 "용역매출"
current: number; // 당기 금액
previous: number; // 전기 금액
}
```
---
## 4. 화면 구현 가이드
### 4.1 화면 구조
```
┌───────────────────────────────────────────────────┐
│ 📊 손익계산서 [인쇄] │
├───────────────────────────────────────────────────┤
│ [기간 보기] [월별 보기] [당기만] [당기+전기] │
│ 기간: [시작일]~[종료일] 단위: [원▾] [조회] │
├───────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────┐ │
│ │ 과 목 │ 제 2 (당)기 │ 제 1 (전)기│ │
│ │ │ 금 액 │ 금 액 │ │
│ ├─────────────────┼──────────────┼─────────────┤ │
│ │ I. 매출액 │ │ │ │
│ │ 용역매출 │ 50,000,000 │ │ │
│ │ │ │ 50,000,000 │ │
│ ├─────────────────┼──────────────┼─────────────┤ │
│ │ II. 매출원가 │ │ │ │
│ │ 서비스매출원가│ 12,000,000 │ │ │
│ │ 외주용역비 │ 8,000,000 │ │ │
│ │ │ │ 20,000,000 │ │
│ ├─────────────────┼──────────────┼─────────────┤ │
│ │ III. 매출총이익 │ │ 30,000,000 │ │ ← 강조 (연두)
│ │ ... │ │ │ │
│ │ X. 당기순이익 │ │ 25,000,000 │ │ ← 강조 (연두)
│ └─────────────────┴──────────────┴─────────────┘ │
│ (단위: 원) │
└───────────────────────────────────────────────────┘
```
### 4.2 보기 모드 전환
| 모드 | 필터 | API | 설명 |
|------|------|-----|------|
| **기간 보기** | 시작일~종료일 + 단위 | `GET /income-statement` | 당기+전기 2열 비교 |
| **월별 보기** | 연도 + 단위 | `GET /income-statement/monthly` | 월별 비교 |
- 모드 전환 시 기존 데이터 초기화 후 새로 조회
- 기본: 기간 보기, 당해 1/1 ~ 12/31
### 4.3 기간 보기 테이블 (PeriodTable)
**컬럼 구성**:
| 상태 | 컬럼 |
|------|------|
| `당기만` | 과목 \| 금액(세부) \| 금액(소계) |
| `당기+전기` | 과목 \| 당기(세부) \| 당기(소계) \| 전기(세부) \| 전기(소계) |
**행 유형**:
| 행 유형 | 조건 | 스타일 | 금액 표시 |
|---------|------|--------|----------|
| **섹션 헤더** | `is_calculated === false` | 굵은 글씨 | items 없으면 소계열에 금액, 있으면 빈칸 |
| **세부 항목** | `items[]` | 들여쓰기(pl-12), 일반 | 세부열에 금액, 마지막 항목의 소계열에 섹션 합계 |
| **계산 항목** | `is_calculated === true` | 강조 배경 | 소계열에만 금액 |
**강조 표시 (emerald-50 배경)**:
- III (매출총이익), V (영업이익), VIII (법인세비용차감전순이익), X (당기순이익)
### 4.4 월별 보기 테이블 (MonthlyTable)
**단일 월 선택**: 기간 보기와 유사한 1열 테이블
**전체 월 선택**: 가로 스크롤 비교 테이블
```
┌──────────────┬──────┬──────┬──────┬─────┐
│ 과목 (sticky)│ 1월 │ 2월 │ 3월 │ ... │
├──────────────┼──────┼──────┼──────┼─────┤
│ I. 매출액 │ 5M │ 4M │ 6M │ ... │
│ 용역매출 │ 5M │ 4M │ 6M │ ... │
│ II. 매출원가 │ 2M │ 1M │ 3M │ ... │
│ III. 매출총이│ 3M │ 3M │ 3M │ ... │ ← 강조
│ ... │ │ │ │ │
└──────────────┴──────┴──────┴──────┴─────┘
```
- 과목 열: `sticky left-0` (가로 스크롤 시 고정)
- 최소 너비: `months.length * 110 + 200` px
### 4.5 월 선택 버튼 (월별 보기)
```
[전체] [1월] [2월] [3월] ... [12월]
```
- 데이터가 있는 월만 버튼 표시 (미래 월은 API 응답에 없음)
- `전체` 선택 시 가로 스크롤 비교 테이블
- 개별 월 선택 시 단일 열 테이블
### 4.6 숫자 포맷
```typescript
const fmt = (n: number): string => {
if (n === 0 || n === null || n === undefined) return '';
if (n < 0) return '(' + Math.abs(n).toLocaleString() + ')';
return n.toLocaleString();
};
const UNIT_LABELS: Record<string, string> = {
won: '원',
thousand: '천원',
million: '백만원'
};
```
### 4.7 인쇄
- `window.print()` 사용
- 조회 조건, 인쇄 버튼에 `no-print` 클래스
- CSS: `@media print { .no-print { display: none !important; } }`
### 4.8 기본값
| 항목 | 기본값 |
|------|--------|
| 보기 모드 | 기간 보기 |
| 시작일 | 당해 1/1 |
| 종료일 | 당해 12/31 |
| 단위 | 원 (`won`) |
| 당기/전기 | 당기만 |
| 월 선택 | 전체 |
- 페이지 진입 시 기본값으로 자동 조회
---
## 5. 손익계산서 항목 구조
```
I. 매출액 ← 합계 항목 (세부 계정과목 표시)
II. 매출원가 ← 합계 항목
III. 매출총이익 = I - II ← 계산 항목 (is_calculated: true, 강조)
IV. 판매비와관리비 ← 합계 항목
V. 영업이익 = III - IV ← 계산 항목 (강조)
VI. 영업외수익 ← 합계 항목
VII. 영업외비용 ← 합계 항목
VIII.법인세비용차감전순이익 ← 계산 항목
IX. 법인세비용 ← 합계 항목
X. 당기순이익 = VIII - IX ← 계산 항목 (강조)
```
- **합계 항목**: `items[]`에 세부 계정과목 포함, `current_amount`/`previous_amount`는 합계
- **계산 항목**: `items[]`는 빈 배열, `is_calculated: true`, 금액은 공식으로 계산된 결과
---
## 6. MNG 참고 화면
> MNG 개발서버: `https://admin.codebridge-x.com` → 회계/세무관리 > 손익계산서
| 파일 | 설명 |
|------|------|
| `mng/app/Http/Controllers/Finance/IncomeStatementController.php` | 전체 로직 (PL_STRUCTURE, buildSections) |
| `mng/resources/views/finance/income-statement.blade.php` | React 컴포넌트 (PeriodTable, MonthlyTable) |
---
## 관련 문서
- [dev/dev_plans/income-statement-service-migration-plan.md](../../dev/dev_plans/income-statement-service-migration-plan.md) — 이관 기획서
- [frontend/api-specs/account-ledger-service-api.md](account-ledger-service-api.md) — 계정별원장 API 명세
- [features/finance/README.md](../../features/finance/README.md) — 재무관리 기능 개요
---
**최종 업데이트**: 2026-03-20
Reference in New Issue View Git Blame Copy Permalink