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>
This commit is contained in:
82
features/ai/README.md
Normal file
82
features/ai/README.md
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user