docs: [finance] 손익계산서 서비스 이관 기획서 + FE API 명세 추가
This commit is contained in:
김보곤
157
dev/dev_plans/income-statement-service-migration-plan.md
Normal file
157
dev/dev_plans/income-statement-service-migration-plan.md
Normal file
@@ -0,0 +1,157 @@
|
||||
# 손익계산서 서비스 이관 기획서
|
||||
|
||||
> **작성일**: 2026-03-20
|
||||
> **상태**: 기획 확정, API 완료
|
||||
> **대상**: MNG → API + React (서비스 이관)
|
||||
> **위치**: 서비스 > 회계관리 > 손익계산서
|
||||
|
||||
---
|
||||
|
||||
## 1. 개요
|
||||
|
||||
### 1.1 목적
|
||||
|
||||
MNG 백오피스의 손익계산서 조회 기능을 서비스(API + React)로 이관한다.
|
||||
API에는 이미 동일 로직의 `IncomeStatementService`가 구현되어 있으므로, **API 코드 변경 없이** React 프론트엔드 구현만 필요하다.
|
||||
|
||||
### 1.2 배경
|
||||
|
||||
- MNG `회계/세무관리 > 손익계산서` 메뉴로 기존 구현 완료 (2026-03-19)
|
||||
- API에 `IncomeStatementService` + `IncomeStatementController`가 MNG와 동일 로직으로 이미 구현됨
|
||||
- 기간별 조회 (`GET /api/v1/income-statement`) + 월별 조회 (`GET /api/v1/income-statement/monthly`) 2개 엔드포인트 제공
|
||||
|
||||
### 1.3 이관 범위
|
||||
|
||||
| 구분 | MNG (현재) | API + React (이관 후) |
|
||||
|------|-----------|---------------------|
|
||||
| **백엔드** | Controller 직접 로직 | `IncomeStatementService` (이미 완료) |
|
||||
| **프론트** | Blade + React (@verbatim) | React (Next.js) |
|
||||
| **인증** | 세션 기반 | Bearer 토큰 + `BelongsToTenant` |
|
||||
| **API 코드 변경** | — | **불필요** (이미 완료) |
|
||||
|
||||
---
|
||||
|
||||
## 2. 현재 MNG 기능 분석
|
||||
|
||||
### 2.1 MNG 기능 목록
|
||||
|
||||
| 기능 | MNG 메서드 | API 대응 |
|
||||
|------|-----------|---------|
|
||||
| 페이지 렌더링 | `index()` | React 라우트 |
|
||||
| 기간별 조회 | `data()` | `GET /api/v1/income-statement` |
|
||||
| 월별 조회 | `monthly()` | `GET /api/v1/income-statement/monthly` |
|
||||
|
||||
### 2.2 손익계산서 구조 (PL_STRUCTURE)
|
||||
|
||||
한국 일반기업회계기준에 따른 10개 항목:
|
||||
|
||||
```
|
||||
I. 매출액 = revenue(sales_revenue) 합계
|
||||
II. 매출원가 = expense(cogs + construction_cost) 합계
|
||||
III. 매출총이익 = I - II (계산)
|
||||
IV. 판매비와관리비 = expense(selling_admin) 합계
|
||||
V. 영업이익 = III - IV (계산)
|
||||
VI. 영업외수익 = revenue(other_revenue) 합계
|
||||
VII. 영업외비용 = expense(other_expense) - [99800, 99900] 합계
|
||||
VIII.법인세비용차감전순이익 = V + VI - VII (계산)
|
||||
IX. 법인세비용 = expense[99800, 99900] 특정 코드만
|
||||
X. 당기순이익 = VIII - IX (계산)
|
||||
```
|
||||
|
||||
### 2.3 데이터 소스
|
||||
|
||||
일반전표(`journal_entry_lines`) + 홈택스 세금계산서(`hometax_invoice_journals`)를 합산하여 계정코드별 차변/대변 합계를 구한다.
|
||||
|
||||
### 2.4 MNG ↔ API 비교
|
||||
|
||||
| 항목 | MNG | API |
|
||||
|------|-----|-----|
|
||||
| PL_STRUCTURE | 동일 | 동일 |
|
||||
| getAccountSums (journal + hometax) | 동일 | 동일 |
|
||||
| buildSections | 동일 | 동일 |
|
||||
| evaluateFormula | 동일 | 동일 |
|
||||
| 단위 변환 (won/thousand/million) | 동일 | 동일 |
|
||||
| 기수 계산 (getFiscalYear) | 동일 | 동일 |
|
||||
| `_debug` 필드 | 포함 | 미포함 (정상) |
|
||||
|
||||
**결론**: API 코드 변경 불필요.
|
||||
|
||||
---
|
||||
|
||||
## 3. API 엔드포인트
|
||||
|
||||
### 3.1 기간별 손익계산서
|
||||
|
||||
| Method | Path | 설명 |
|
||||
|--------|------|------|
|
||||
| `GET` | `/api/v1/income-statement` | 기간별 손익계산서 (당기+전기) |
|
||||
|
||||
**요청 파라미터**:
|
||||
|
||||
| 파라미터 | 타입 | 필수 | 설명 |
|
||||
|---------|------|:----:|------|
|
||||
| `start_date` | `string(date)` | Y | 당기 시작일 |
|
||||
| `end_date` | `string(date)` | Y | 당기 종료일 |
|
||||
| `unit` | `string` | N | `won`(기본) / `thousand` / `million` |
|
||||
|
||||
### 3.2 월별 손익계산서
|
||||
|
||||
| Method | Path | 설명 |
|
||||
|--------|------|------|
|
||||
| `GET` | `/api/v1/income-statement/monthly` | 월별 손익계산서 |
|
||||
|
||||
**요청 파라미터**:
|
||||
|
||||
| 파라미터 | 타입 | 필수 | 설명 |
|
||||
|---------|------|:----:|------|
|
||||
| `year` | `integer` | Y | 조회 연도 (2020~2100) |
|
||||
| `unit` | `string` | N | `won`(기본) / `thousand` / `million` |
|
||||
|
||||
---
|
||||
|
||||
## 4. React 구현 요구사항
|
||||
|
||||
### 4.1 보기 모드
|
||||
|
||||
| 모드 | API | 설명 |
|
||||
|------|-----|------|
|
||||
| **기간 보기** | `GET /income-statement` | 당기+전기 비교 (토글로 전기 숨김 가능) |
|
||||
| **월별 보기** | `GET /income-statement/monthly` | 연도별 1~12월 비교 |
|
||||
|
||||
### 4.2 UI 컨트롤
|
||||
|
||||
- 보기 모드 전환 (`[기간 보기]` / `[월별 보기]`)
|
||||
- 당기/전기 토글 (`[당기만]` / `[당기+전기]`) — 기간 보기에서만
|
||||
- 월 선택 (`[전체]` `[1월]` `[2월]` ... `[12월]`) — 월별 보기에서만
|
||||
- 기간 필터 (시작일~종료일) / 연도 선택
|
||||
- 단위 선택 (원 / 천원 / 백만원)
|
||||
- 인쇄 버튼
|
||||
|
||||
### 4.3 테이블 레이아웃
|
||||
|
||||
**기간 보기**: 과목 | 당기(세부+소계) | 전기(세부+소계, 토글)
|
||||
**월별 단일 월**: 과목 | 금액(세부+소계)
|
||||
**월별 전체**: 과목(sticky) | 1월 | 2월 | ... | 12월 (가로 스크롤)
|
||||
|
||||
---
|
||||
|
||||
## 5. MNG 참고 화면
|
||||
|
||||
> MNG 개발서버: `https://admin.codebridge-x.com` → 회계/세무관리 > 손익계산서
|
||||
|
||||
| 파일 | 설명 |
|
||||
|------|------|
|
||||
| `mng/app/Http/Controllers/Finance/IncomeStatementController.php` | 전체 로직 |
|
||||
| `mng/resources/views/finance/income-statement.blade.php` | React 컴포넌트 (UI 참고) |
|
||||
|
||||
---
|
||||
|
||||
## 관련 문서
|
||||
|
||||
- [dev/dev_plans/account-ledger-income-statement-plan.md](account-ledger-income-statement-plan.md) — 원래 MNG 구현 기획서
|
||||
- [frontend/api-specs/income-statement-service-api.md](../../frontend/api-specs/income-statement-service-api.md) — FE API 명세 (서비스 이관 버전)
|
||||
- [frontend/api-specs/account-ledger-service-api.md](../../frontend/api-specs/account-ledger-service-api.md) — 계정별원장 FE API 명세
|
||||
|
||||
---
|
||||
|
||||
**최종 업데이트**: 2026-03-20
|
||||
Reference in New Issue
Block a user