From 5effbb8a0b552c115016475dc5c506119080822f 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 12:51:02 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20[finance]=20=EA=B3=84=EC=A0=95=EC=BD=94?= =?UTF-8?q?=EB=93=9C=20=EB=A7=88=EC=9D=B4=EA=B7=B8=EB=A0=88=EC=9D=B4?= =?UTF-8?q?=EC=85=98=20=EC=9D=B4=EB=A0=A5=20+=20=EC=86=90=EC=9D=B5?= =?UTF-8?q?=EA=B3=84=EC=82=B0=EC=84=9C=20API=20=EB=AA=85=EC=84=B8=20?= =?UTF-8?q?=EC=97=85=EB=8D=B0=EC=9D=B4=ED=8A=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 더존 3자리→KIS 5자리 코드 마이그레이션 기록 (832건) - 손익계산서 월별 API 명세 추가 - 당기/전기 토글, 월별 보기 화면 요구사항 추가 --- INDEX.md | 1 + ...unt_code_migration_and_income_statement.md | 107 ++++++++++++++++++ .../account-ledger-income-statement-api.md | 42 ++++++- 3 files changed, 146 insertions(+), 4 deletions(-) create mode 100644 changes/20260319_account_code_migration_and_income_statement.md diff --git a/INDEX.md b/INDEX.md index 0f148b2..4ac44b1 100644 --- a/INDEX.md +++ b/INDEX.md @@ -279,6 +279,7 @@ DB 도메인별: | [20260319_nonconforming_management_api.md](changes/20260319_nonconforming_management_api.md) | 부적합관리 API 구현 (8개 엔드포인트 + 결재 연동) | | [20260319_statcards_grid_layout_fix.md](changes/20260319_statcards_grid_layout_fix.md) | StatCards 카드 6개 한 행 표시 개선 | | [20260319_item_master_field_validation_fix.md](changes/20260319_item_master_field_validation_fix.md) | 품목기준관리 필드 수정 422 유효성 검증 오류 수정 | +| [20260319_account_code_migration_and_income_statement.md](changes/20260319_account_code_migration_and_income_statement.md) | 계정코드 3→5자리 마이그레이션 + 손익계산서 월별/토글 개선 | --- diff --git a/changes/20260319_account_code_migration_and_income_statement.md b/changes/20260319_account_code_migration_and_income_statement.md new file mode 100644 index 0000000..32b575a --- /dev/null +++ b/changes/20260319_account_code_migration_and_income_statement.md @@ -0,0 +1,107 @@ +# 계정과목 코드 마이그레이션 + 손익계산서 개선 + +**날짜:** 2026-03-19 +**작업자:** Claude Code + +## 변경 개요 + +1. 전표/홈택스 분개의 더존 3자리 계정코드를 KIS 5자리 표준코드로 마이그레이션 +2. 손익계산서 기수(期數) 수정 및 당기/전기 토글 + 월별 보기 기능 추가 +3. 서비스 API에 월별 손익계산서 엔드포인트 추가 + +--- + +## 1. 계정코드 마이그레이션 (DB 데이터) + +### 배경 + +- `account_codes` 테이블: KIS 5자리 표준 코드 (40100, 81100 등) +- `journal_entry_lines` / `hometax_invoice_journals`: 더존 3자리 코드 (401, 811 등) 사용 중 +- 코드 불일치로 손익계산서의 `sub_category` 매칭이 안 되어 금액이 0으로 표시됨 + +### 매핑 (36개) + +| 더존 3자리 | KIS 5자리 | 계정명 | 비고 | +|-----------|----------|--------|------| +| 401 | 40100 | 상품매출 | | +| 402 | 40400 | 제품매출 | | +| 501 | 45100 | 상품매출원가 | 더존 `상품매입` → KIS `상품매출원가` | +| 801 | 80200 | 직원급여 | 더존 `급여` → KIS `직원급여` | +| 805 | 81100 | 복리후생비 | | +| 807 | 81300 | 접대비 | | +| 811 | 81700 | 세금과공과금 | | +| 812 | 81900 | 지급임차료 | 더존 `임차료` → KIS `지급임차료` | +| 838 | 83100 | 지급수수료 | 더존 `용역비` → KIS에 없어 `지급수수료`로 매핑 | +| 901 | 90100 | 이자수익 | | +| ... | ... | ... | 자산/부채/자본 계정 포함 총 36개 | + +### 적용 결과 + +| 테이블 | 업데이트 건수 | +|--------|------------| +| `journal_entry_lines` | 700건 | +| `hometax_invoice_journals` | 132건 | +| 잔여 3자리 코드 | **0건** | + +--- + +## 2. 손익계산서 개선 + +### 기수 수정 + +- 변경 전: `baseYear = 2005` (제22기 = 2026년) +- 변경 후: `baseYear = 2024` (제2기 = 2026년) +- 근거: 코드브릿지엑스 설립일 2025-09-13, 1기 = 2025년 + +### 당기/전기 토글 (MNG) + +- `[당기만]` / `[당기+전기]` 토글 버튼 +- 전기 컬럼을 동적으로 표시/숨김 + +### 월별 보기 (MNG + API) + +- 연도 선택 → 1~12월 개별 손익 조회 +- 전체 보기: 월별 가로 비교 테이블 +- 개별 월 선택: 해당 월만 상세 표시 + +### 서비스 API 엔드포인트 + +| Method | Path | 설명 | +|--------|------|------| +| `GET` | `/api/v1/income-statement` | 기간 손익계산서 (기존) | +| `GET` | `/api/v1/income-statement/monthly` | 월별 손익계산서 (신규) | + +--- + +## 수정된 파일 + +### API (`sam/api`) + +| 파일 | 변경 내용 | +|------|----------| +| `app/Services/IncomeStatementService.php` | monthly() 추가, buildSections 분리, 기수 수정 | +| `app/Http/Controllers/Api/V1/IncomeStatementController.php` | monthly() 엔드포인트 추가 | +| `routes/api/v1/finance.php` | monthly 라우트 추가 | + +### MNG (`sam/mng`) + +| 파일 | 변경 내용 | +|------|----------| +| `app/Http/Controllers/Finance/IncomeStatementController.php` | monthly() 추가, buildSections 분리, 기수 수정 | +| `resources/views/finance/income-statement.blade.php` | 당기/전기 토글, 월별 보기 UI | +| `routes/web.php` | monthly 라우트 추가 | + +### DB (직접 업데이트) + +| 테이블 | 변경 내용 | +|--------|----------| +| `journal_entry_lines` | account_code 3자리→5자리 (700건) | +| `hometax_invoice_journals` | account_code 3자리→5자리 (132건) | + +--- + +## 관련 문서 + +- [dev/dev_plans/account-ledger-income-statement-plan.md](../dev/dev_plans/account-ledger-income-statement-plan.md) — 기획서 +- [frontend/api-specs/account-ledger-income-statement-api.md](../frontend/api-specs/account-ledger-income-statement-api.md) — API 명세 +- [changes/20260317_account_code_migration_mapping.md](20260317_account_code_migration_mapping.md) — 이전 코드 변경 매핑 diff --git a/frontend/api-specs/account-ledger-income-statement-api.md b/frontend/api-specs/account-ledger-income-statement-api.md index 4f6e814..34bae99 100644 --- a/frontend/api-specs/account-ledger-income-statement-api.md +++ b/frontend/api-specs/account-ledger-income-statement-api.md @@ -120,9 +120,10 @@ interface LedgerItem { | Method | Path | 설명 | |--------|------|------| -| `GET` | `/api/v1/income-statement` | 손익계산서 조회 | +| `GET` | `/api/v1/income-statement` | 기간 손익계산서 조회 | +| `GET` | `/api/v1/income-statement/monthly` | 월별 손익계산서 조회 | -### 3.2 요청 파라미터 +### 3.2 기간 조회 파라미터 | 파라미터 | 타입 | 필수 | 설명 | |---------|------|:----:|------| @@ -131,6 +132,14 @@ interface LedgerItem { | `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 응답 구조 @@ -165,6 +174,28 @@ interface PLItem { } ``` +### 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 손익계산서 구조 ``` @@ -182,8 +213,11 @@ X. 당기순이익 = VIII - IX ← 계산 ### 3.5 화면 요구사항 -- **조회 필터**: 기간(date range) + 금액 단위 선택 -- **테이블**: 과목 | 당기 금액(2열) | 전기 금액(2열) +- **보기 모드 토글**: `[기간 보기]` / `[월별 보기]` +- **당기/전기 토글**: `[당기만]` / `[당기+전기]` (기간 보기에서만) +- **조회 필터**: 기간(date range) 또는 연도 + 금액 단위 선택 +- **기간 보기 테이블**: 과목 | 당기 금액(2열) | 전기 금액(2열, 토글로 숨김 가능) +- **월별 보기**: 연도 선택 → 월별 버튼(1~12월) → 개별 월 또는 전체 비교 - **당기 컬럼 2열**: 세부 금액(왼쪽) + 소계(오른쪽) - 세부 항목이 있는 섹션: 마지막 행의 오른쪽 열에 소계 표시 - 계산 항목(`is_calculated`): 오른쪽 열에만 금액 표시