# 계정별원장·손익계산서 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` | 기간 손익계산서 조회 |
| `GET` | `/api/v1/income-statement/monthly` | 월별 손익계산서 조회 |

### 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)
> **기수**: 코드브릿지엑스 설립 2025-09-13 기준, 제1기 = 2025년, 제2기 = 2026년

### 3.2.1 월별 조회 파라미터

| 파라미터 | 타입 | 필수 | 설명 |
|---------|------|:----:|------|
| `year` | `integer` | Y | 조회 연도 (`2026`) |
| `unit` | `string` | N | `won` (기본) / `thousand` / `million` |

### 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.3.1 월별 조회 응답 구조

```typescript
interface MonthlyIncomeStatementResponse {
  success: boolean;
  message: string;
  data: {
    year: number;              // 2026
    fiscal_year: number;       // 2 (제2기)
    fiscal_label: string;      // "제 2 기"
    unit: 'won' | 'thousand' | 'million';
    months: MonthPL[];
  };
}

interface MonthPL {
  month: string;          // "01", "02", ...
  label: string;          // "1월", "2월", ...
  sections: PLSection[];  // 해당 월의 손익 항목 (current_amount만 유효, previous_amount는 0)
}
```

### 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열, 토글로 숨김 가능)
- **월별 보기**: 연도 선택 → 월별 버튼(1~12월) → 개별 월 또는 전체 비교
- **당기 컬럼 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
