docs: [종합정비] Phase 3 신규 도메인 기능 문서 16개 작성

- features/esign/README.md: 전자서명 (4모델, 16 API) - features/documents/README.md: 문서관리 (12모델, EAV 기반, 15 API) - features/ai/README.md: AI 리포트 (Gemini 2.0, 4 API) - features/equipment/README.md: 설비관리 (MNG 전용) - features/finance/ 9개 하위문서: 입출금, 급여, 가지급금, 세금계산서, 악성채권, 어음, 카드, 미지급비용, 채권현황, CEO 대시보드 - features/finance/README.md 재구조화 (14개 하위문서 목록) - features/barobill-kakaotalk/README.md 확장 (API 설정 + 세금계산서) - rules/numbering-rules.md: 채번규칙 (6세그먼트, 원자적 UPSERT) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-27 18:03:25 +09:00
parent d4e5f62413
commit ae7e139d12
17 changed files with 1001 additions and 12 deletions
--- a/features/ai/README.md
+++ b/features/ai/README.md
@@ -0,0 +1,82 @@
+# AI 분석 리포트 (AI Report)
+
+> **상태**: API 구현 완료
+> **최종 갱신**: 2026-02-27
+
+---
+
+## 1. 개요
+
+Google Gemini API를 활용한 재무 분석 리포트 자동 생성 시스템. 테넌트의 비즈니스 데이터(지출, 매출, 매입, 입출금, 카드/계좌, 미수금)를 자동 수집하여 AI 기반 분석 리포트를 생성한다.
+
+**핵심 기능:**
+- 일간/주간/월간 재무 분석 리포트 자동 생성
+- Gemini 2.0 Flash 모델 연동
+- 토큰 사용량 자동 추적 및 비용 계산 (USD/KRW)
+- 전월 동기간 대비 변화율 분석
+
+---
+
+## 2. 모델
+
+| 모델 | 테이블 | 설명 | Traits |
+|------|--------|------|--------|
+| `AiReport` | `ai_reports` | AI 리포트 (유형, 내용, 상태) | BelongsToTenant |
+| `AiTokenUsage` | `ai_token_usages` | 토큰 사용량 추적 (모델, 메뉴, 비용) | BelongsToTenant |
+| `AiPricingConfig` | `ai_pricing_configs` | AI 모델별 단가 설정 (3600초 캐시) | BelongsToTenant |
+| `AiVoiceRecording` | `ai_voice_recordings` | 음성 녹음 (GCS URI, STT 결과) | BelongsToTenant |
+
+**리포트 유형:** daily, weekly, monthly
+
+**리포트 상태:** pending → completed / failed
+
+**분석 영역 (6개):**
+- 지출 (Withdrawal), 매출 (Sale), 매입 (Purchase)
+- 입출금 (Deposit), 카드/계좌, 미수금 (Receivable)
+
+---
+
+## 3. 서비스
+
+| 서비스 | 주요 메서드 | 설명 |
+|--------|-----------|------|
+| `AiReportService` | list | 리포트 목록 (필터: report_type, status, 날짜) |
+| | show | 리포트 상세 |
+| | generate | 리포트 생성 (데이터 수집 → Gemini API 호출 → 저장) |
+| | delete | 리포트 삭제 |
+
+**내부 처리 흐름:**
+```
+generate() → collectBusinessData() → buildPrompt() → callGeminiApi() → saveTokenUsage()
+```
+
+---
+
+## 4. API 엔드포인트
+
+| HTTP | URI | 설명 |
+|------|-----|------|
+| GET | `/v1/reports/ai` | AI 리포트 목록 |
+| POST | `/v1/reports/ai/generate` | AI 리포트 생성 |
+| GET | `/v1/reports/ai/{id}` | AI 리포트 상세 |
+| DELETE | `/v1/reports/ai/{id}` | AI 리포트 삭제 |
+
+---
+
+## 5. FormRequest
+
+| Request | 주요 검증 |
+|---------|----------|
+| `AiReportListRequest` | per_page, report_type (in), status (in), start_date, end_date |
+| `AiReportGenerateRequest` | report_date (nullable, before_or_equal:today), report_type (nullable) |
+
+---
+
+## 관련 문서
+
+- [DB 스키마 — 공통](../../system/database/commons.md)
+- Swagger: `/api-docs` → Reports 섹션
+
+---
+
+**최종 업데이트**: 2026-02-27
--- a/features/barobill-kakaotalk/README.md
+++ b/features/barobill-kakaotalk/README.md
@@ -377,7 +377,37 @@ $buttons = [

 ---

-## 8. 참고 자료
+## 8. API 측 바로빌 연동 (세금계산서)
+
+MNG의 카카오톡 연동 외에, API(`api/`)에서도 바로빌 서비스를 사용한다:
+
+### 8.1 바로빌 설정 API
+
+| HTTP | URI | 설명 |
+|------|-----|------|
+| GET | `/v1/barobill-settings` | 바로빌 설정 조회 |
+| PUT | `/v1/barobill-settings` | 바로빌 설정 저장 (사업자번호, 인증키, 자동발행 등) |
+| POST | `/v1/barobill-settings/test-connection` | 연동 테스트 |
+
+### 8.2 세금계산서 발행
+
+`BarobillService`는 세금계산서 발행/취소/국세청 전송 상태 조회도 담당한다:
+
+| API 메서드 | 설명 |
+|-----------|------|
+| `issueTaxInvoice()` | 세금계산서 발행 (RegistAndIssueTaxInvoice) |
+| `cancelTaxInvoice()` | 세금계산서 취소 |
+| `checkNtsSendStatus()` | 국세청 전송 상태 조회 |
+| `checkBusinessNumber()` | 사업자번호 휴폐업 조회 |
+| `testConnection()` | GetAccessToken으로 연동 테스트 |
+
+**인증키 보안:** `cert_key`는 Laravel `Crypt` 파사드로 자동 암/복호화
+
+→ 상세: [세금계산서 관리](../finance/tax-invoices.md)
+
+---
+
+## 9. 참고 자료

 - [바로빌 API 문서](https://dev.barobill.co.kr)
 - [카카오비즈니스 채널 관리](https://business.kakao.com)
--- a/features/documents/README.md
+++ b/features/documents/README.md
@@ -0,0 +1,120 @@
+# 문서관리 시스템 (Document Management)
+
+> **상태**: API 완전 구현
+> **최종 갱신**: 2026-02-27
+
+---
+
+## 1. 개요
+
+EAV(Entity-Attribute-Value) 패턴 기반의 동적 문서 관리 시스템. 문서 서식(Template)을 정의하면 해당 서식에 따라 문서를 생성·결재·관리할 수 있다. 제품 검사(FQC), 공정 검사 등 다양한 문서 유형을 하나의 시스템으로 처리한다.
+
+**핵심 기능:**
+- 문서 서식(Template) 관리: 결재선, 기본필드, 섹션, 컬럼 정의
+- EAV 기반 동적 데이터 저장 (section_id + column_id + row_index + field_key)
+- 결재 워크플로우: 작성 → 검토 → 승인 (다단계)
+- FQC(제품검사) 일괄 생성 및 진행 현황
+- 첨부파일 관리 (서명, 이미지, 참조 문서)
+
+---
+
+## 2. 모델
+
+### 서식 (Template) 계층
+
+| 모델 | 설명 |
+|------|------|
+| `DocumentTemplate` | 서식 마스터 (이름, 카테고리, 회사 정보, 활성 여부) |
+| `DocumentTemplateApprovalLine` | 결재선 (이름, 부서, 역할, 순서) |
+| `DocumentTemplateBasicField` | 기본 필드 (라벨, 유형, 기본값) |
+| `DocumentTemplateSection` | 섹션 (제목, 이미지, 순서) |
+| `DocumentTemplateSectionField` | 섹션 필드 (field_key, 유형, 옵션, 필수 여부) |
+| `DocumentTemplateColumn` | 컬럼 (라벨, 너비, 유형, 하위 라벨) |
+| `DocumentTemplateLink` | 서식 간 연결 |
+
+### 문서 (Document) 계층
+
+| 모델 | 설명 | Traits |
+|------|------|--------|
+| `Document` | 문서 인스턴스 (서식 기반, 상태, 연결 대상) | BelongsToTenant, Auditable, SoftDeletes |
+| `DocumentApproval` | 결재 기록 (단계, 역할, 상태, 코멘트) | BelongsToTenant |
+| `DocumentData` | EAV 데이터 (section + column + row + field_key → value) | BelongsToTenant |
+| `DocumentAttachment` | 첨부파일 (유형: general, signature, image, reference) | BelongsToTenant |
+
+**문서 상태 흐름:**
+```
+DRAFT → PENDING → APPROVED
+                → REJECTED → DRAFT (재작성)
+      → CANCELLED
+```
+
+**컬럼 유형:** text, check, complex, select, measurement
+
+---
+
+## 3. 서비스
+
+| 서비스 | 주요 메서드 |
+|--------|-----------|
+| `DocumentService` | list, show, create, update, destroy, submit, approve, reject, cancel, bulkCreateFqc, fqcStatus, resolve, upsert, formatTemplateForReact |
+| `DocumentTemplateService` | list, show |
+
+---
+
+## 4. API 엔드포인트
+
+### 서식 조회 (읽기 전용)
+
+| HTTP | URI | 설명 |
+|------|-----|------|
+| GET | `/v1/document-templates` | 서식 목록 |
+| GET | `/v1/document-templates/{id}` | 서식 상세 (필드·컬럼·섹션 포함) |
+
+### 문서 CRUD + 워크플로우
+
+| HTTP | URI | 설명 |
+|------|-----|------|
+| GET | `/v1/documents` | 문서 목록 (필터: status, template_id, 날짜, 검색) |
+| POST | `/v1/documents` | 문서 생성 |
+| GET | `/v1/documents/{id}` | 문서 상세 |
+| PATCH | `/v1/documents/{id}` | 문서 수정 |
+| DELETE | `/v1/documents/{id}` | 문서 삭제 |
+| POST | `/v1/documents/{id}/submit` | 결재 요청 |
+| POST | `/v1/documents/{id}/approve` | 승인 |
+| POST | `/v1/documents/{id}/reject` | 반려 |
+| POST | `/v1/documents/{id}/cancel` | 취소/회수 |
+
+### 특수 기능
+
+| HTTP | URI | 설명 |
+|------|-----|------|
+| POST | `/v1/documents/bulk-create-fqc` | FQC 일괄 생성 |
+| GET | `/v1/documents/fqc-status` | FQC 진행 현황 |
+| GET | `/v1/documents/resolve` | 카테고리+item_id로 문서 조회 |
+| POST | `/v1/documents/upsert` | 생성 또는 업데이트 |
+
+---
+
+## 5. FormRequest
+
+| Request | 주요 검증 |
+|---------|----------|
+| `StoreRequest` | template_id (필수, exists), title, approvers[], data[] (EAV), attachments[] |
+| `UpdateRequest` | title, data[] (EAV), attachments[] |
+| `IndexRequest` | status, template_id, search, 날짜 범위, 정렬 |
+| `BulkCreateFqcRequest` | order_id, template_id, item_count |
+| `ResolveRequest` | category, item_id |
+| `ApproveRequest` | comment (선택) |
+| `RejectRequest` | comment (필수) |
+
+---
+
+## 관련 문서
+
+- [DB 스키마 — 문서/전자서명](../../system/database/documents.md)
+- [게시판 시스템](../boards/README.md) — 유사한 EAV 패턴 적용
+- Swagger: `/api-docs` → Documents 섹션
+
+---
+
+**최종 업데이트**: 2026-02-27
--- a/features/equipment/README.md
+++ b/features/equipment/README.md
@@ -0,0 +1,50 @@
+# 설비관리 (Equipment Management)
+
+> **상태**: MNG 전용 (API 미구현)
+> **최종 갱신**: 2026-02-27
+
+---
+
+## 1. 개요
+
+MNG 관리자 패널에서만 사용 가능한 설비 관리 기능. REST API 엔드포인트는 없으며, Blade/HTMX 기반 웹 인터페이스로 운영된다.
+
+**핵심 기능:**
+- 설비 등록/수정/삭제 (생산 설비, 검사 장비 등)
+- 설비 점검 이력 관리
+- 설비별 상태 추적
+
+---
+
+## 2. 구현 위치
+
+| 구분 | 경로 | 비고 |
+|------|------|------|
+| Models | `mng/app/Models/Equipment/` | MNG 전용 |
+| Controllers | `mng/app/Http/Controllers/Equipment/` | Blade 렌더링 |
+| Views | `mng/resources/views/equipment/` | HTMX + DaisyUI |
+| Routes | `mng/routes/web.php` → equipment 그룹 | 웹 라우트만 |
+
+**참고:** API(`api/`)에는 Equipment 관련 모델·서비스·컨트롤러·라우트가 없음. 모바일/외부 연동이 필요하면 API 개발 필요.
+
+---
+
+## 3. DB 테이블
+
+마이그레이션은 `api/` 측에 존재하지만 모델은 `mng/`에만 구현됨.
+
+| 테이블 | 설명 |
+|--------|------|
+| `equipments` | 설비 마스터 (이름, 유형, 상태, 위치) |
+| `equipment_inspections` | 설비 점검 이력 |
+
+---
+
+## 관련 문서
+
+- [MNG 구조](../../system/mng-structure.md)
+- [DB 스키마 — 공통](../../system/database/commons.md)
+
+---
+
+**최종 업데이트**: 2026-02-27
--- a/features/esign/README.md
+++ b/features/esign/README.md
@@ -0,0 +1,101 @@
+# 전자서명 (E-Sign)
+
+> **상태**: API 완전 구현
+> **최종 갱신**: 2026-02-27
+
+---
+
+## 1. 개요
+
+PDF 문서에 대한 전자서명 계약 관리 시스템. 계약 생성 → 서명 필드 설정 → 발송 → OTP 인증 → 서명 → 완료의 전체 라이프사이클을 관리한다.
+
+**핵심 기능:**
+- PDF 계약서 업로드 및 서명 필드 배치
+- 서명 순서 관리 (작성자 우선 / 상대방 우선)
+- OTP 기반 본인인증 후 서명
+- 서명 완료 시 PDF 합성 + 감사 페이지 추가
+- 토큰 기반 외부 서명자 접근 (비인증)
+
+---
+
+## 2. 모델
+
+| 모델 | 테이블 | 설명 | Traits |
+|------|--------|------|--------|
+| `EsignContract` | `esign_contracts` | 계약서 (상태, 파일, 만료일) | BelongsToTenant, Auditable, SoftDeletes |
+| `EsignSigner` | `esign_signers` | 서명자 (순서, OTP, 서명 이미지) | BelongsToTenant |
+| `EsignSignField` | `esign_sign_fields` | 서명 필드 (위치, 유형, 페이지) | BelongsToTenant |
+| `EsignAuditLog` | `esign_audit_logs` | 감사 로그 (IP, UA, 행위) | BelongsToTenant |
+
+**계약 상태 흐름:**
+```
+draft → pending → partially_signed → completed
+                                   → expired
+                → cancelled
+                → rejected
+```
+
+**서명 필드 유형:** signature, stamp, text, date, checkbox
+
+---
+
+## 3. 서비스
+
+| 서비스 | 주요 메서드 |
+|--------|-----------|
+| `EsignContractService` | list, create, show, cancel, send, remind, configureFields, stats |
+| `EsignSignService` | getByToken, sendOtp, verifyOtp, submitSignature, reject |
+| `EsignAuditService` | log, logPublic, getContractLogs |
+| `EsignPdfService` | generateHash, verifyIntegrity, composeSigned, addAuditPage |
+
+---
+
+## 4. API 엔드포인트
+
+### 계약 관리 (인증 필요)
+
+| HTTP | URI | 설명 |
+|------|-----|------|
+| GET | `/v1/esign/contracts` | 계약 목록 |
+| POST | `/v1/esign/contracts` | 계약 생성 (PDF 업로드) |
+| GET | `/v1/esign/contracts/stats` | 통계 |
+| GET | `/v1/esign/contracts/{id}` | 계약 상세 |
+| POST | `/v1/esign/contracts/{id}/cancel` | 계약 취소 |
+| POST | `/v1/esign/contracts/{id}/fields` | 서명 필드 설정 |
+| POST | `/v1/esign/contracts/{id}/send` | 계약 발송 |
+| POST | `/v1/esign/contracts/{id}/remind` | 리마인드 |
+| GET | `/v1/esign/contracts/{id}/download` | PDF 다운로드 |
+| GET | `/v1/esign/contracts/{id}/verify` | 무결성 검증 |
+
+### 서명 처리 (토큰 기반, 외부 접근)
+
+| HTTP | URI | 설명 |
+|------|-----|------|
+| GET | `/v1/esign/sign/{token}` | 계약 정보 조회 |
+| POST | `/v1/esign/sign/{token}/otp/send` | OTP 발송 |
+| POST | `/v1/esign/sign/{token}/otp/verify` | OTP 검증 |
+| GET | `/v1/esign/sign/{token}/document` | 문서 조회 |
+| POST | `/v1/esign/sign/{token}/submit` | 서명 제출 |
+| POST | `/v1/esign/sign/{token}/reject` | 서명 거절 |
+
+---
+
+## 5. FormRequest
+
+| Request | 주요 검증 |
+|---------|----------|
+| `ContractStoreRequest` | title (필수, max:200), file (필수, pdf, max:20MB), sign_order_type, 서명자 정보 |
+| `FieldConfigureRequest` | fields 배열 (page, position, size, type) |
+| `SignSubmitRequest` | signature_image (파일), field_values (배열) |
+| `SignRejectRequest` | reason (필수) |
+
+---
+
+## 관련 문서
+
+- [DB 스키마 — 문서/전자서명](../../system/database/documents.md)
+- Swagger: `/api-docs` → ESign 섹션
+
+---
+
+**최종 업데이트**: 2026-02-27
--- a/features/finance/README.md
+++ b/features/finance/README.md
@@ -1,19 +1,52 @@
-# 재무/자금관리 기능
+# 재무/자금관리 (Finance)
+
+> **최종 갱신**: 2026-02-27

 ## 개요

-SAM 프로젝트의 재무/자금관리 모듈은 회사의 자금 흐름을 종합적으로 관리하는 시스템입니다.
-바로빌 API 연동을 통한 실시간 거래 조회, 계좌 관리, 자금 계획, 전표 관리 기능을 제공합니다.
+SAM 프로젝트의 재무/자금관리 모듈. 입출금, 급여, 가지급금, 세금계산서, 어음, 악성채권 추심, CEO 대시보드까지 재무 전 영역을 관리한다. 바로빌 API 연동을 통한 실시간 거래 조회 및 전자세금계산서 발행을 지원한다.

-## 메뉴 구성
+## 문서 목록

-| 메뉴 | 경로 | 설명 | UI 기술 |
-|------|------|------|---------|
-| [재무 대시보드](./finance-dashboard.md) | `/finance/dashboard` | 자금 현황 종합 요약 | Blade + JS |
-| [일일자금일보](./daily-fund-report.md) | `/finance/daily-fund` | 기간별 계좌 입출금 현황 보고서 | React 18 |
-| [자금계획일정](./fund-schedules.md) | `/finance/fund-schedules` | 입금/지급 예정 일정 관리 | Blade |
-| [보유계좌관리](./bank-accounts.md) | `/finance/accounts` | 회사 은행계좌 정보 관리 | Blade + HTMX |
-| [계좌입출금내역](./account-transactions.md) | `/finance/account-transactions` | 바로빌 연동 거래 조회 및 회계 분류 | React 18 |
+### 자금관리 (기존)
+
+| 문서 | 설명 |
+|------|------|
+| [finance-dashboard.md](./finance-dashboard.md) | 재무 대시보드 |
+| [daily-fund-report.md](./daily-fund-report.md) | 일일자금일보 |
+| [fund-schedules.md](./fund-schedules.md) | 자금계획일정 |
+| [bank-accounts.md](./bank-accounts.md) | 보유계좌관리 |
+| [account-transactions.md](./account-transactions.md) | 계좌입출금내역 (바로빌 연동) |
+
+### 입출금·카드 (신규)
+
+| 문서 | 설명 |
+|------|------|
+| [deposits-withdrawals.md](./deposits-withdrawals.md) | 입금/출금 관리 |
+| [cards.md](./cards.md) | 카드관리 + 카드거래내역 |
+
+### 급여·채권·비용 (신규)
+
+| 문서 | 설명 |
+|------|------|
+| [payroll.md](./payroll.md) | 급여관리 (급여대장 + 급여관리) |
+| [loans.md](./loans.md) | 가지급금 관리 (이자계산, 세금시뮬레이션) |
+| [expected-expenses.md](./expected-expenses.md) | 미지급비용 관리 |
+| [receivables-ledger.md](./receivables-ledger.md) | 채권현황·거래처원장·은행거래 |
+| [bad-debts.md](./bad-debts.md) | 악성채권 추심관리 |
+
+### 세금·어음 (신규)
+
+| 문서 | 설명 |
+|------|------|
+| [tax-invoices.md](./tax-invoices.md) | 세금계산서 (바로빌 발행 연동) |
+| [bills.md](./bills.md) | 어음관리 |
+
+### 경영진 대시보드 (신규)
+
+| 문서 | 설명 |
+|------|------|
+| [ceo-dashboard.md](./ceo-dashboard.md) | CEO 대시보드·종합분석·부가세·접대비·복리후생비 |

 ## 아키텍처

--- a/features/finance/bad-debts.md
+++ b/features/finance/bad-debts.md
@@ -0,0 +1,47 @@
+# 악성채권 추심관리 (Bad Debts)
+
+> **최종 갱신**: 2026-02-27
+
+---
+
+## 1. 개요
+
+미수금이 장기 연체된 악성채권의 추심 관리. 상태 추적, 관련 서류 첨부, 메모 관리를 지원한다.
+
+**상태:** collecting (추심중) → legal_action (법적조치) → recovered (회수완료) / bad_debt (대손처리)
+
+---
+
+## 2. 모델
+
+| 모델 | 설명 |
+|------|------|
+| `BadDebt` | 악성채권 마스터 (거래처, 금액, 상태, 연체일수, 담당자) |
+| `BadDebtDocument` | 추심 관련 서류 |
+| `BadDebtMemo` | 추심 메모/활동 기록 |
+
+---
+
+## 3. API 엔드포인트
+
+| HTTP | URI | 설명 |
+|------|-----|------|
+| GET | `/v1/bad-debts` | 악성채권 목록 |
+| POST | `/v1/bad-debts` | 악성채권 등록 |
+| GET | `/v1/bad-debts/summary` | 요약 |
+| GET | `/v1/bad-debts/{id}` | 악성채권 상세 |
+| PUT | `/v1/bad-debts/{id}` | 악성채권 수정 |
+| DELETE | `/v1/bad-debts/{id}` | 악성채권 삭제 |
+| PATCH | `/v1/bad-debts/{id}/toggle` | 활성 토글 |
+| POST | `/v1/bad-debts/{id}/documents` | 서류 추가 |
+| DELETE | `/v1/bad-debts/{id}/documents/{documentId}` | 서류 삭제 |
+| POST | `/v1/bad-debts/{id}/memos` | 메모 추가 |
+| DELETE | `/v1/bad-debts/{id}/memos/{memoId}` | 메모 삭제 |
+
+---
+
+## 관련 문서
+
+- [재무관리 개요](README.md)
+- [채권현황](receivables-ledger.md)
+- Swagger: `/api-docs` → BadDebts 섹션
--- a/features/finance/bills.md
+++ b/features/finance/bills.md
@@ -0,0 +1,40 @@
+# 어음관리 (Bills)
+
+> **최종 갱신**: 2026-02-27
+
+---
+
+## 1. 개요
+
+어음(약속어음, 당좌수표 등)의 등록·상태 변경·분할 관리.
+
+---
+
+## 2. 모델
+
+| 모델 | 설명 |
+|------|------|
+| `Bill` | 어음 마스터 (금액, 만기일, 상태) |
+| `BillInstallment` | 어음 분할 납부 |
+
+---
+
+## 3. API 엔드포인트
+
+| HTTP | URI | 설명 |
+|------|-----|------|
+| GET | `/v1/bills` | 어음 목록 |
+| POST | `/v1/bills` | 어음 등록 |
+| GET | `/v1/bills/summary` | 요약 |
+| GET | `/v1/bills/dashboard-detail` | 대시보드 상세 |
+| GET | `/v1/bills/{id}` | 어음 상세 |
+| PUT | `/v1/bills/{id}` | 어음 수정 |
+| DELETE | `/v1/bills/{id}` | 어음 삭제 |
+| PATCH | `/v1/bills/{id}/status` | 상태 변경 |
+
+---
+
+## 관련 문서
+
+- [재무관리 개요](README.md)
+- Swagger: `/api-docs` → Bills 섹션
--- a/features/finance/cards.md
+++ b/features/finance/cards.md
@@ -0,0 +1,51 @@
+# 카드관리 (Cards & Card Transactions)
+
+> **최종 갱신**: 2026-02-27
+
+---
+
+## 1. 개요
+
+법인카드 등록·관리 및 카드 사용내역 조회·계정과목 배정.
+
+---
+
+## 2. API 엔드포인트
+
+### 카드 관리
+
+| HTTP | URI | 설명 |
+|------|-----|------|
+| GET | `/v1/cards` | 카드 목록 |
+| POST | `/v1/cards` | 카드 등록 |
+| GET | `/v1/cards/active` | 활성 카드 목록 |
+| GET | `/v1/cards/{id}` | 카드 상세 |
+| PUT | `/v1/cards/{id}` | 카드 수정 |
+| DELETE | `/v1/cards/{id}` | 카드 삭제 |
+| PATCH | `/v1/cards/{id}/toggle` | 상태 토글 |
+
+**Card 모델 특이사항:**
+- `card_number_encrypted`: 카드번호 자동 암호화
+- `card_password_encrypted`: 비밀번호 자동 암호화
+- `getMaskedCardNumber()`: 마스킹 처리된 번호 반환
+
+### 카드 거래내역
+
+| HTTP | URI | 설명 |
+|------|-----|------|
+| GET | `/v1/card-transactions` | 거래 목록 |
+| POST | `/v1/card-transactions` | 거래 등록 |
+| GET | `/v1/card-transactions/summary` | 요약 |
+| GET | `/v1/card-transactions/dashboard` | 대시보드 |
+| PUT | `/v1/card-transactions/bulk-update-account` | 계정과목 일괄 수정 |
+| GET | `/v1/card-transactions/{id}` | 거래 상세 |
+| PUT | `/v1/card-transactions/{id}` | 거래 수정 |
+| DELETE | `/v1/card-transactions/{id}` | 거래 삭제 |
+
+---
+
+## 관련 문서
+
+- [재무관리 개요](README.md)
+- [법인카드·차량 관리](../card-vehicle/README.md) — 차량 관련 카드 사용
+- Swagger: `/api-docs` → Cards / CardTransactions 섹션
--- a/features/finance/ceo-dashboard.md
+++ b/features/finance/ceo-dashboard.md
@@ -0,0 +1,49 @@
+# CEO 대시보드 및 분석 (CEO Dashboard & Reports)
+
+> **최종 갱신**: 2026-02-27
+
+---
+
+## 1. 개요
+
+경영진용 종합 대시보드. 현황판, 오늘의 이슈, 캘린더, 종합 분석, 부가세·접대비·복리후생비 현황, 일일보고서를 제공한다.
+
+---
+
+## 2. API 엔드포인트
+
+### 종합 현황
+
+| HTTP | URI | 설명 |
+|------|-----|------|
+| GET | `/v1/comprehensive-analysis` | 종합 분석 보고서 |
+| GET | `/v1/status-board/summary` | CEO 현황판 요약 |
+| GET | `/v1/daily-report` | 일일 보고서 |
+
+### 오늘의 이슈
+
+| HTTP | URI | 설명 |
+|------|-----|------|
+| GET | `/v1/today-issues` | 오늘의 이슈 목록 |
+
+### 캘린더
+
+| HTTP | URI | 설명 |
+|------|-----|------|
+| GET | `/v1/calendar/schedules` | 캘린더 일정 |
+
+### 세무/경비 현황
+
+| HTTP | URI | 설명 |
+|------|-----|------|
+| GET | `/v1/vat/summary` | 부가세 현황 |
+| GET | `/v1/entertainment/summary` | 접대비 현황 |
+| GET | `/v1/welfare/summary` | 복리후생비 현황 |
+
+---
+
+## 관련 문서
+
+- [재무관리 개요](README.md)
+- [AI 분석 리포트](../ai/README.md) — AI 기반 재무 분석
+- Swagger: `/api-docs` → Dashboard / Reports 섹션
--- a/features/finance/deposits-withdrawals.md
+++ b/features/finance/deposits-withdrawals.md
@@ -0,0 +1,44 @@
+# 입출금 관리 (Deposits & Withdrawals)
+
+> **최종 갱신**: 2026-02-27
+
+---
+
+## 1. 개요
+
+입금(Deposit)과 출금(Withdrawal)을 개별 관리하며, 계정과목 일괄 배정 및 요약 통계를 제공한다.
+
+---
+
+## 2. API 엔드포인트
+
+### 입금 (Deposits)
+
+| HTTP | URI | 설명 |
+|------|-----|------|
+| GET | `/v1/deposits` | 입금 목록 |
+| POST | `/v1/deposits` | 입금 등록 |
+| GET | `/v1/deposits/summary` | 입금 요약 |
+| POST | `/v1/deposits/bulk-update-account-code` | 계정과목 일괄 수정 |
+| GET | `/v1/deposits/{id}` | 입금 상세 |
+| PUT | `/v1/deposits/{id}` | 입금 수정 |
+| DELETE | `/v1/deposits/{id}` | 입금 삭제 |
+
+### 출금 (Withdrawals)
+
+| HTTP | URI | 설명 |
+|------|-----|------|
+| GET | `/v1/withdrawals` | 출금 목록 |
+| POST | `/v1/withdrawals` | 출금 등록 |
+| GET | `/v1/withdrawals/summary` | 출금 요약 |
+| POST | `/v1/withdrawals/bulk-update-account-code` | 계정과목 일괄 수정 |
+| GET | `/v1/withdrawals/{id}` | 출금 상세 |
+| PUT | `/v1/withdrawals/{id}` | 출금 수정 |
+| DELETE | `/v1/withdrawals/{id}` | 출금 삭제 |
+
+---
+
+## 관련 문서
+
+- [재무관리 개요](README.md)
+- Swagger: `/api-docs` → Deposits / Withdrawals 섹션
--- a/features/finance/expected-expenses.md
+++ b/features/finance/expected-expenses.md
@@ -0,0 +1,32 @@
+# 미지급비용 관리 (Expected Expenses)
+
+> **최종 갱신**: 2026-02-27
+
+---
+
+## 1. 개요
+
+발생은 확정되었으나 아직 지급되지 않은 비용(미지급비용)의 관리. 지급 예정일 관리 및 대시보드 상세를 제공한다.
+
+---
+
+## 2. API 엔드포인트
+
+| HTTP | URI | 설명 |
+|------|-----|------|
+| GET | `/v1/expected-expenses` | 미지급비용 목록 |
+| POST | `/v1/expected-expenses` | 미지급비용 등록 |
+| GET | `/v1/expected-expenses/summary` | 요약 |
+| GET | `/v1/expected-expenses/dashboard-detail` | 대시보드 상세 |
+| DELETE | `/v1/expected-expenses` | 다중 삭제 |
+| PUT | `/v1/expected-expenses/update-payment-date` | 지급 예정일 수정 |
+| GET | `/v1/expected-expenses/{id}` | 미지급비용 상세 |
+| PUT | `/v1/expected-expenses/{id}` | 미지급비용 수정 |
+| DELETE | `/v1/expected-expenses/{id}` | 미지급비용 삭제 |
+
+---
+
+## 관련 문서
+
+- [재무관리 개요](README.md)
+- Swagger: `/api-docs` → ExpectedExpenses 섹션
--- a/features/finance/loans.md
+++ b/features/finance/loans.md
@@ -0,0 +1,54 @@
+# 가지급금 관리 (Loans)
+
+> **최종 갱신**: 2026-02-27
+
+---
+
+## 1. 개요
+
+임직원 가지급금(대여금)의 지급·정산·이자 계산·세금 시뮬레이션을 관리한다.
+
+**핵심 기능:**
+- 가지급금 지급/부분정산/완전정산
+- 인정이자 자동 계산 (연도별 이율 적용)
+- 세금 시뮬레이션 (법인세, 소득세, 지방소득세)
+- 연도별 이자 보고서
+
+---
+
+## 2. 모델
+
+**주요 필드:** user_id, loan_date, amount, purpose, settlement_date, settlement_amount, status, withdrawal_id
+
+**상태:** outstanding (미정산) → partial (부분정산) → settled (정산완료)
+
+**이자율:** 2024/2025: 4.6% (연리)
+
+**세율:** 법인세 19%, 소득세 35%, 지방소득세 10%
+
+**주요 메서드:** calculateRecognizedInterest(), calculateTaxes(), isEditable(), isDeletable(), isSettleable()
+
+---
+
+## 3. API 엔드포인트
+
+| HTTP | URI | 설명 |
+|------|-----|------|
+| GET | `/v1/loans` | 가지급금 목록 |
+| POST | `/v1/loans` | 가지급금 지급 등록 |
+| GET | `/v1/loans/summary` | 요약 |
+| GET | `/v1/loans/dashboard` | 대시보드 |
+| GET | `/v1/loans/tax-simulation` | 세금 시뮬레이션 |
+| POST | `/v1/loans/calculate-interest` | 인정이자 계산 |
+| GET | `/v1/loans/interest-report/{year}` | 연도별 이자 보고서 |
+| GET | `/v1/loans/{id}` | 가지급금 상세 |
+| PUT | `/v1/loans/{id}` | 가지급금 수정 |
+| DELETE | `/v1/loans/{id}` | 가지급금 삭제 |
+| POST | `/v1/loans/{id}/settle` | 정산 처리 |
+
+---
+
+## 관련 문서
+
+- [재무관리 개요](README.md)
+- Swagger: `/api-docs` → Loans 섹션
--- a/features/finance/payroll.md
+++ b/features/finance/payroll.md
@@ -0,0 +1,66 @@
+# 급여관리 (Payroll & Salary)
+
+> **최종 갱신**: 2026-02-27
+
+---
+
+## 1. 개요
+
+두 가지 급여 모델이 병존한다:
+- **Payroll**: 급여대장 (기본급, 수당, 공제 상세, 확정/지급 워크플로우)
+- **Salary**: 급여관리 React 연동용 (통계, 내보내기, 상태 일괄 변경)
+
+---
+
+## 2. 모델
+
+### Payroll (급여대장)
+
+**주요 필드:** user_id, pay_year, pay_month, base_salary, overtime_pay, bonus, allowances(JSON), gross_salary, income_tax, resident_tax, health_insurance, pension, employment_insurance, deductions(JSON), total_deductions, net_salary, status, confirmed_at, paid_at, withdrawal_id
+
+**상태:** draft → confirmed → paid
+
+### Salary (급여관리)
+
+**주요 필드:** employee_id, year, month, base_salary, total_allowance, total_overtime, total_bonus, total_deduction, net_payment, allowance_details(JSON), deduction_details(JSON), payment_date, status
+
+---
+
+## 3. API 엔드포인트
+
+### 급여대장 (Payrolls)
+
+| HTTP | URI | 설명 |
+|------|-----|------|
+| GET | `/v1/payrolls` | 급여 목록 |
+| POST | `/v1/payrolls` | 급여 생성 |
+| GET | `/v1/payrolls/summary` | 급여 요약 |
+| POST | `/v1/payrolls/calculate` | 급여 계산 |
+| POST | `/v1/payrolls/bulk-confirm` | 일괄 확정 |
+| GET | `/v1/payrolls/{id}` | 급여 상세 |
+| PUT | `/v1/payrolls/{id}` | 급여 수정 |
+| DELETE | `/v1/payrolls/{id}` | 급여 삭제 |
+| POST | `/v1/payrolls/{id}/confirm` | 확정 |
+| POST | `/v1/payrolls/{id}/pay` | 지급 처리 |
+| GET | `/v1/payrolls/{id}/payslip` | 급여명세서 조회 |
+
+### 급여관리 (Salaries)
+
+| HTTP | URI | 설명 |
+|------|-----|------|
+| GET | `/v1/salaries` | 급여 목록 |
+| POST | `/v1/salaries` | 급여 생성 |
+| GET | `/v1/salaries/statistics` | 급여 통계 |
+| GET | `/v1/salaries/export` | 급여 내보내기 |
+| POST | `/v1/salaries/bulk-update-status` | 상태 일괄 변경 |
+| GET | `/v1/salaries/{id}` | 급여 상세 |
+| PUT | `/v1/salaries/{id}` | 급여 수정 |
+| DELETE | `/v1/salaries/{id}` | 급여 삭제 |
+| PATCH | `/v1/salaries/{id}/status` | 상태 변경 |
+
+---
+
+## 관련 문서
+
+- [재무관리 개요](README.md)
+- Swagger: `/api-docs` → Payrolls / Salaries 섹션
--- a/features/finance/receivables-ledger.md
+++ b/features/finance/receivables-ledger.md
@@ -0,0 +1,42 @@
+# 채권현황·거래처원장·은행거래 (Receivables & Ledger)
+
+> **최종 갱신**: 2026-02-27
+
+---
+
+## 1. 개요
+
+미수금(채권) 현황 조회, 거래처별 원장 조회, 은행 거래 내역 조회를 통합 관리한다.
+
+---
+
+## 2. API 엔드포인트
+
+### 채권현황 (Receivables)
+
+| HTTP | URI | 설명 |
+|------|-----|------|
+| GET | `/v1/receivables` | 채권 목록 |
+| GET | `/v1/receivables/summary` | 채권 요약 |
+| PUT | `/v1/receivables/overdue-status` | 연체 상태 수정 |
+| PUT | `/v1/receivables/memos` | 메모 수정 |
+
+### 거래처원장 (Vendor Ledger)
+
+| HTTP | URI | 설명 |
+|------|-----|------|
+| GET | `/v1/vendor-ledger` | 거래처원장 조회 |
+
+### 은행거래 (Bank Transactions)
+
+| HTTP | URI | 설명 |
+|------|-----|------|
+| GET | `/v1/bank-transactions` | 은행 거래 목록 |
+
+---
+
+## 관련 문서
+
+- [재무관리 개요](README.md)
+- [악성채권 추심](bad-debts.md) — 연체 → 악성채권 전환 시
+- Swagger: `/api-docs` → Receivables / VendorLedger 섹션
--- a/features/finance/tax-invoices.md
+++ b/features/finance/tax-invoices.md
@@ -0,0 +1,40 @@
+# 세금계산서 (Tax Invoices)
+
+> **최종 갱신**: 2026-02-27
+
+---
+
+## 1. 개요
+
+세금계산서 발행·취소·국세청 전송 상태 관리. 바로빌(Barobill) API를 통해 전자세금계산서를 발행하며, 수동 관리도 가능하다.
+
+**세금계산서 유형:** tax_invoice (세금계산서), invoice (계산서-면세), modified (수정세금계산서)
+
+**발행 유형:** normal (정발행), reverse (역발행), trustee (위수탁)
+
+**방향:** sales (매출), purchases (매입)
+
+---
+
+## 2. API 엔드포인트
+
+| HTTP | URI | 설명 |
+|------|-----|------|
+| GET | `/v1/tax-invoices` | 세금계산서 목록 |
+| POST | `/v1/tax-invoices` | 세금계산서 생성 |
+| GET | `/v1/tax-invoices/summary` | 요약 |
+| GET | `/v1/tax-invoices/{id}` | 세금계산서 상세 |
+| PUT | `/v1/tax-invoices/{id}` | 세금계산서 수정 |
+| DELETE | `/v1/tax-invoices/{id}` | 세금계산서 삭제 |
+| POST | `/v1/tax-invoices/{id}/issue` | 발행 (바로빌 API 연동) |
+| POST | `/v1/tax-invoices/{id}/cancel` | 취소 |
+| GET | `/v1/tax-invoices/{id}/check-status` | 국세청 전송 상태 확인 |
+| POST | `/v1/tax-invoices/bulk-issue` | 일괄 발행 |
+
+---
+
+## 관련 문서
+
+- [재무관리 개요](README.md)
+- [바로빌 연동](../barobill-kakaotalk/README.md) — 전자세금계산서 발행 API
+- Swagger: `/api-docs` → TaxInvoices 섹션
--- a/rules/numbering-rules.md
+++ b/rules/numbering-rules.md
@@ -0,0 +1,108 @@
+# 채번규칙 (Numbering Rules)
+
+> **상태**: 내부 서비스 (직접 API 없음)
+> **최종 갱신**: 2026-02-27
+
+---
+
+## 1. 개요
+
+문서 번호(견적번호, 수주번호 등)를 규칙 기반으로 자동 생성하는 내부 서비스. 테넌트별로 채번 규칙을 설정하면, 해당 규칙에 따라 일련번호가 자동 생성된다. 규칙이 없는 경우 레거시 포맷으로 폴백.
+
+**핵심 기능:**
+- 유연한 패턴 기반 번호 생성 (6가지 세그먼트 유형)
+- Atomic UPSERT로 동시성 안전 시퀀스 관리
+- 기간별 자동 리셋 (일/월/년/무제한)
+- 미리보기 기능 (DB 업데이트 없음)
+
+---
+
+## 2. 모델
+
+| 모델 | 테이블 | 설명 |
+|------|--------|------|
+| `NumberingRule` | `numbering_rules` | 채번 규칙 정의 (document_type, pattern, reset_period) |
+| `NumberingSequence` | `numbering_sequences` | 일련번호 카운터 (tenant + type + scope + period) |
+
+**지원 문서 유형:** quote, order, sale, work_order, material_receipt
+
+**리셋 주기:** daily, monthly, yearly, never
+
+---
+
+## 3. 패턴 구조
+
+패턴은 JSON 배열로 세그먼트를 정의한다.
+
+| 세그먼트 | 설명 | 예시 |
+|---------|------|------|
+| `static` | 고정 문자열 | `{ "type": "static", "value": "QT" }` |
+| `date` | 날짜 포맷 | `{ "type": "date", "format": "ymd" }` → `260227` |
+| `sequence` | 일련번호 | `{ "type": "sequence", "padding": 4 }` → `0001` |
+| `separator` | 구분자 | `{ "type": "separator", "value": "-" }` |
+| `param` | 외부 파라미터 | `{ "type": "param", "key": "product_category" }` |
+| `mapping` | 값 매핑 | `{ "type": "mapping", "key": "category", "map": {"A": "PR"} }` |
+
+**패턴 예시:**
+```json
+[
+  { "type": "static", "value": "KD" },
+  { "type": "separator", "value": "-" },
+  { "type": "mapping", "key": "category", "map": { "A": "PR" }, "default": "XX" },
+  { "type": "separator", "value": "-" },
+  { "type": "date", "format": "ymd" },
+  { "type": "separator", "value": "-" },
+  { "type": "sequence", "padding": 2 }
+]
+```
+→ `KD-PR-260227-01`
+
+---
+
+## 4. 서비스
+
+| 서비스 | 메서드 | 설명 |
+|--------|--------|------|
+| `NumberingService` | `generate($documentType, $params)` | 번호 생성 (규칙 없으면 null → 레거시 폴백) |
+| | `preview($documentType, $params)` | 미리보기 (시퀀스 증가 없음) |
+| `QuoteNumberService` | `generate()` | 견적번호 생성 (NumberingService → 레거시 폴백) |
+| | `validate()` | 형식 검증 |
+| | `isUnique()` | 중복 체크 |
+
+**레거시 포맷:** `QT{YYYYMMDD}{NNNN}` (예: `QT202602270001`)
+
+---
+
+## 5. 동시성 처리
+
+```sql
+INSERT INTO numbering_sequences (tenant_id, document_type, scope_key, period_key, last_sequence)
+VALUES (?, ?, ?, ?, 1)
+ON DUPLICATE KEY UPDATE last_sequence = last_sequence + 1
+```
+
+MySQL의 `UPSERT`를 사용하여 동시 요청에서도 시퀀스 충돌 없이 안전하게 번호 생성.
+
+---
+
+## 6. 호출 위치
+
+직접 API 엔드포인트는 없으며, 아래 서비스에서 내부 호출된다:
+
+| 서비스 | 용도 |
+|--------|------|
+| `QuoteNumberService` | 견적번호 생성 |
+| `OrderService` | 수주번호 생성 |
+| `WorkOrderService` | 작업지시번호 생성 |
+| `MaterialReceiptService` | 입고번호 생성 |
+
+---
+
+## 관련 문서
+
+- [DB 스키마 — 공통](../system/database/commons.md)
+- [품목 정책](item-policy.md) — 품목 코드 체계
+
+---
+
+**최종 업데이트**: 2026-02-27