diff --git a/features/ai/README.md b/features/ai/README.md new file mode 100644 index 0000000..6cb0ec3 --- /dev/null +++ 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 diff --git a/features/barobill-kakaotalk/README.md b/features/barobill-kakaotalk/README.md index 84b923f..151f1fb 100644 --- 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) diff --git a/features/documents/README.md b/features/documents/README.md new file mode 100644 index 0000000..91f3dd9 --- /dev/null +++ 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 diff --git a/features/equipment/README.md b/features/equipment/README.md new file mode 100644 index 0000000..7f0274d --- /dev/null +++ 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 diff --git a/features/esign/README.md b/features/esign/README.md new file mode 100644 index 0000000..40d54dd --- /dev/null +++ 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 diff --git a/features/finance/README.md b/features/finance/README.md index 7a63a5a..912448a 100644 --- 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 대시보드·종합분석·부가세·접대비·복리후생비 | ## 아키텍처 diff --git a/features/finance/bad-debts.md b/features/finance/bad-debts.md new file mode 100644 index 0000000..edbb9ae --- /dev/null +++ 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 섹션 diff --git a/features/finance/bills.md b/features/finance/bills.md new file mode 100644 index 0000000..048ebe3 --- /dev/null +++ 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 섹션 diff --git a/features/finance/cards.md b/features/finance/cards.md new file mode 100644 index 0000000..3eac972 --- /dev/null +++ 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 섹션 diff --git a/features/finance/ceo-dashboard.md b/features/finance/ceo-dashboard.md new file mode 100644 index 0000000..6332413 --- /dev/null +++ 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 섹션 diff --git a/features/finance/deposits-withdrawals.md b/features/finance/deposits-withdrawals.md new file mode 100644 index 0000000..be41a48 --- /dev/null +++ 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 섹션 diff --git a/features/finance/expected-expenses.md b/features/finance/expected-expenses.md new file mode 100644 index 0000000..808df95 --- /dev/null +++ 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 섹션 diff --git a/features/finance/loans.md b/features/finance/loans.md new file mode 100644 index 0000000..ffa3dc1 --- /dev/null +++ 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 섹션 diff --git a/features/finance/payroll.md b/features/finance/payroll.md new file mode 100644 index 0000000..f5d1498 --- /dev/null +++ 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 섹션 diff --git a/features/finance/receivables-ledger.md b/features/finance/receivables-ledger.md new file mode 100644 index 0000000..fd62f72 --- /dev/null +++ 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 섹션 diff --git a/features/finance/tax-invoices.md b/features/finance/tax-invoices.md new file mode 100644 index 0000000..02dd70c --- /dev/null +++ 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 섹션 diff --git a/rules/numbering-rules.md b/rules/numbering-rules.md new file mode 100644 index 0000000..ef5ad2a --- /dev/null +++ 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