SamProject/sam-react-prod
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix: 11개 FAIL 시나리오 수정 후 재테스트 전체 PASS

Browse Source 
Pattern A (4건): 삭제 버튼 미구현 - critical:false + SKIP 처리
Pattern B (7건): 테이블 로드 폴링 + 검색 폴백 추가
추가: VERIFY_DELETE 단계도 삭제 미구현 대응

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
김보곤
2026-03-08 16:22:11 +09:00
parent e684c495ee
commit f5bdc5bac8
804 changed files with 192052 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

82
docs/features/ai/README.md Normal file
View 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

650
docs/features/api-explorer-spec.md Normal file
View File

@@ -0,0 +1,650 @@
# API Explorer 상세 설계서
> **문서 버전**: 1.0
> **작성일**: 2025-12-17
> **대상 프로젝트**: mng (Plain Laravel + Blade + Tailwind)
---
## 1. 개요
### 1.1 목적
Swagger UI의 한계를 극복하고, 개발팀의 API 관리 효율성을 높이기 위한 커스텀 API Explorer 개발
### 1.2 Swagger 대비 개선점
| 기능 | Swagger UI | API Explorer |
|------|------------|--------------|
| 검색 | 엔드포인트명만 | 풀텍스트 (설명, 파라미터 포함) |
| 그룹핑 | 태그만 | 태그 + 상태 + 메서드 + 커스텀 |
| 즐겨찾기 | ❌ | ⭐ 사용자별 북마크 |
| 요청 템플릿 | ❌ | 💾 저장/공유 가능 |
| 히스토리 | ❌ | 📋 최근 요청 + 재실행 |
| 환경 전환 | 수동 | 🔄 원클릭 전환 |
### 1.3 기술 스택
- **Backend**: Laravel 12 (mng 프로젝트)
- **Frontend**: Blade + Tailwind CSS + HTMX
- **Data Source**: OpenAPI 3.0 JSON (`api/storage/api-docs/api-docs.json`)
- **HTTP Client**: Guzzle (서버사이드 프록시)
---
## 2. 시스템 아키텍처
### 2.1 전체 구조
```
┌─────────────────────────────────────────────────────────────────┐
│ API Explorer (mng) │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │
│ │ Browser │───>│ Laravel │───>│ API Server │ │
│ │ (HTMX) │<───│ (Proxy) │<───│ (api/) │ │
│ └──────────────┘ └──────────────┘ └──────────────────┘ │
│ │ │ │
│ │ ┌──────┴──────┐ │
│ │ │ │ │
│ │ ┌─────┴─────┐ ┌─────┴─────┐ │
│ │ │ SQLite │ │ OpenAPI │ │
│ │ │ (Local) │ │ JSON │ │
│ │ └───────────┘ └───────────┘ │
│ │ │
│ ┌──────┴───────────────────────────────────────────────────┐ │
│ │ Local Storage │ │
│ │ • 환경 설정 (현재 서버) │ │
│ │ • UI 상태 (패널 크기, 필터) │ │
│ └────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
```
### 2.2 데이터 흐름
```
1. OpenAPI 파싱
api-docs.json ──> OpenApiParserService ──> 구조화된 API 데이터
2. API 요청 프록시
Browser ──HTMX──> ApiExplorerController ──Guzzle──> API Server
3. 사용자 데이터 (즐겨찾기, 템플릿, 히스토리)
Browser ──> ApiExplorerController ──> SQLite/MySQL
```
---
## 3. 디렉토리 구조
```
mng/
├── app/
│ ├── Http/
│ │ └── Controllers/
│ │ └── DevTools/
│ │ └── ApiExplorerController.php
│ ├── Services/
│ │ └── ApiExplorer/
│ │ ├── OpenApiParserService.php # OpenAPI JSON 파싱
│ │ ├── ApiRequestService.php # API 호출 프록시
│ │ └── ApiExplorerService.php # 비즈니스 로직 통합
│ └── Models/
│ └── DevTools/
│ ├── ApiBookmark.php # 즐겨찾기
│ ├── ApiTemplate.php # 요청 템플릿
│ └── ApiHistory.php # 요청 히스토리
│
├── database/
│ └── migrations/
│ └── 2024_xx_xx_create_api_explorer_tables.php
│
├── resources/
│ └── views/
│ └── dev-tools/
│ └── api-explorer/
│ ├── index.blade.php # 메인 레이아웃
│ ├── partials/
│ │ ├── sidebar.blade.php # API 목록 + 검색/필터
│ │ ├── endpoint-item.blade.php # 개별 엔드포인트 항목
│ │ ├── request-panel.blade.php # 요청 작성 패널
│ │ ├── response-panel.blade.php # 응답 표시 패널
│ │ ├── template-modal.blade.php # 템플릿 저장/불러오기
│ │ └── history-drawer.blade.php # 히스토리 서랍
│ └── components/
│ ├── method-badge.blade.php # HTTP 메서드 배지
│ ├── param-input.blade.php # 파라미터 입력 필드
│ ├── json-editor.blade.php # JSON 편집기
│ └── json-viewer.blade.php # JSON 뷰어 (트리/Raw)
│
├── routes/
│ └── web.php # 라우트 추가
│
└── config/
└── api-explorer.php # 설정 파일
```
---
## 4. 데이터베이스 스키마
### 4.1 ERD
```
┌─────────────────────┐ ┌─────────────────────┐
│ api_bookmarks │ │ api_templates │
├─────────────────────┤ ├─────────────────────┤
│ id (PK) │ │ id (PK) │
│ user_id (FK) │ │ user_id (FK) │
│ endpoint │ │ endpoint │
│ method │ │ method │
│ display_name │ │ name │
│ display_order │ │ description │
│ color │ │ headers (JSON) │
│ created_at │ │ path_params (JSON) │
│ updated_at │ │ query_params (JSON) │
└─────────────────────┘ │ body (JSON) │
│ is_shared │
│ created_at │
│ updated_at │
└─────────────────────┘
┌─────────────────────┐ ┌─────────────────────┐
│ api_histories │ │ api_environments │
├─────────────────────┤ ├─────────────────────┤
│ id (PK) │ │ id (PK) │
│ user_id (FK) │ │ user_id (FK) │
│ endpoint │ │ name │
│ method │ │ base_url │
│ request_headers │ │ api_key │
│ request_body │ │ auth_token │
│ response_status │ │ variables (JSON) │
│ response_headers │ │ is_default │
│ response_body │ │ created_at │
│ duration_ms │ │ updated_at │
│ environment │ └─────────────────────┘
│ created_at │
└─────────────────────┘
```
### 4.2 마이그레이션
```php
// api_bookmarks
Schema::create('api_bookmarks', function (Blueprint $table) {
$table->id();
$table->foreignId('user_id')->constrained()->onDelete('cascade');
$table->string('endpoint', 500);
$table->string('method', 10);
$table->string('display_name', 100)->nullable();
$table->integer('display_order')->default(0);
$table->string('color', 20)->nullable();
$table->timestamps();
$table->unique(['user_id', 'endpoint', 'method']);
$table->index('user_id');
});
// api_templates
Schema::create('api_templates', function (Blueprint $table) {
$table->id();
$table->foreignId('user_id')->constrained()->onDelete('cascade');
$table->string('endpoint', 500);
$table->string('method', 10);
$table->string('name', 100);
$table->text('description')->nullable();
$table->json('headers')->nullable();
$table->json('path_params')->nullable();
$table->json('query_params')->nullable();
$table->json('body')->nullable();
$table->boolean('is_shared')->default(false);
$table->timestamps();
$table->index(['user_id', 'endpoint', 'method']);
$table->index('is_shared');
});
// api_histories
Schema::create('api_histories', function (Blueprint $table) {
$table->id();
$table->foreignId('user_id')->constrained()->onDelete('cascade');
$table->string('endpoint', 500);
$table->string('method', 10);
$table->json('request_headers')->nullable();
$table->json('request_body')->nullable();
$table->integer('response_status');
$table->json('response_headers')->nullable();
$table->longText('response_body')->nullable();
$table->integer('duration_ms');
$table->string('environment', 50);
$table->timestamp('created_at');
$table->index(['user_id', 'created_at']);
$table->index(['endpoint', 'method']);
});
// api_environments
Schema::create('api_environments', function (Blueprint $table) {
$table->id();
$table->foreignId('user_id')->constrained()->onDelete('cascade');
$table->string('name', 50);
$table->string('base_url', 500);
$table->string('api_key', 500)->nullable();
$table->text('auth_token')->nullable();
$table->json('variables')->nullable();
$table->boolean('is_default')->default(false);
$table->timestamps();
$table->index('user_id');
});
```
---
## 5. UI 설계
### 5.1 메인 레이아웃 (3-Panel)
```
┌────────────────────────────────────────────────────────────────────────────┐
│ 🔍 Search... │ [로컬 ▼] │ 📋 History │ ⚙️ Settings │
├────────────────────────────────────────────────────────────────────────────┤
│ │ │ │
│ API Sidebar │ Request Panel │ Response Panel │
│ (resizable) │ (resizable) │ (resizable) │
│ │ │ │
│ ┌───────────────────┐ │ ┌──────────────────────┐ │ ┌──────────────────────┐ │
│ │ 🔍 필터 │ │ │ POST /api/v1/login │ │ │ Status: 200 OK ✓ │ │
│ │ [GET][POST][PUT] │ │ │ │ │ │ Time: 45ms │ │
│ │ [DELETE][PATCH] │ │ │ ┌─ Headers ─────────┐│ │ │ │ │
│ │ │ │ │ │ Authorization: [] ││ │ │ ┌─ Headers ─────────┐│ │
│ │ ⭐ 즐겨찾기 (3) │ │ │ │ Content-Type: [] ││ │ │ │ content-type: ... ││ │
│ │ POST login │ │ │ └──────────────────┘│ │ │ │ x-request-id: ... ││ │
│ │ GET users │ │ │ │ │ │ └──────────────────┘│ │
│ │ POST logout │ │ │ ┌─ Path Params ────┐│ │ │ │ │
│ │ │ │ │ │ (none) ││ │ │ ┌─ Body ─────────────┐│ │
│ │ 📁 Auth │ │ │ └──────────────────┘│ │ │ │ { ││ │
│ │ ├ POST login │ │ │ │ │ │ │ "success": true, ││ │
│ │ ├ POST logout │ │ │ ┌─ Query Params ───┐│ │ │ │ "data": { ││ │
│ │ └ GET me │ │ │ │ (none) ││ │ │ │ "token": "..." ││ │
│ │ │ │ │ └──────────────────┘│ │ │ │ } ││ │
│ │ 📁 Users │ │ │ │ │ │ │ } ││ │
│ │ ├ GET list │ │ │ ┌─ Body (JSON) ────┐│ │ │ └──────────────────┘│ │
│ │ ├ GET {id} │ │ │ │ { ││ │ │ │ │
│ │ ├ POST create │ │ │ │ "user_id": "", ││ │ │ [Raw] [Pretty] [Tree]│ │
│ │ ├ PUT {id} │ │ │ │ "user_pwd": "" ││ │ │ │ │
│ │ └ DELETE {id} │ │ │ │ } ││ │ │ [📋 Copy] [💾 Save] │ │
│ │ │ │ │ └──────────────────┘│ │ │ │ │
│ │ 📁 Products │ │ │ │ │ └──────────────────────┘ │
│ │ └ ... │ │ │ [📋 템플릿] [▶ 실행]│ │ │
│ └───────────────────┘ │ └──────────────────────┘ │ │
│ │ │ │
└────────────────────────────────────────────────────────────────────────────┘
```
### 5.2 컬러 스킴
```css
/* HTTP 메서드 배지 */
.method-get { @apply bg-green-100 text-green-800; }
.method-post { @apply bg-blue-100 text-blue-800; }
.method-put { @apply bg-yellow-100 text-yellow-800; }
.method-patch { @apply bg-orange-100 text-orange-800; }
.method-delete { @apply bg-red-100 text-red-800; }
/* 상태 코드 */
.status-2xx { @apply text-green-600; } /* 성공 */
.status-3xx { @apply text-blue-600; } /* 리다이렉트 */
.status-4xx { @apply text-yellow-600; } /* 클라이언트 에러 */
.status-5xx { @apply text-red-600; } /* 서버 에러 */
```
### 5.3 반응형 동작
| 화면 크기 | 동작 |
|-----------|------|
| Desktop (≥1280px) | 3-Panel 표시 |
| Tablet (768-1279px) | 2-Panel (사이드바 접힘 가능) |
| Mobile (<768px) | 1-Panel (탭 전환) |
---
## 6. API 설계
### 6.1 라우트 정의
```php
// routes/web.php
Route::prefix('dev-tools/api-explorer')
->middleware(['auth'])
->name('api-explorer.')
->group(function () {
// 메인 페이지
Route::get('/', [ApiExplorerController::class, 'index'])->name('index');
// API 목록 (HTMX partial)
Route::get('/endpoints', [ApiExplorerController::class, 'endpoints'])->name('endpoints');
Route::get('/endpoints/{operationId}', [ApiExplorerController::class, 'endpoint'])->name('endpoint');
// API 실행 (프록시)
Route::post('/execute', [ApiExplorerController::class, 'execute'])->name('execute');
// 즐겨찾기
Route::get('/bookmarks', [ApiExplorerController::class, 'bookmarks'])->name('bookmarks');
Route::post('/bookmarks', [ApiExplorerController::class, 'addBookmark'])->name('bookmarks.add');
Route::delete('/bookmarks/{id}', [ApiExplorerController::class, 'removeBookmark'])->name('bookmarks.remove');
Route::put('/bookmarks/reorder', [ApiExplorerController::class, 'reorderBookmarks'])->name('bookmarks.reorder');
// 템플릿
Route::get('/templates', [ApiExplorerController::class, 'templates'])->name('templates');
Route::get('/templates/{endpoint}', [ApiExplorerController::class, 'templatesForEndpoint'])->name('templates.endpoint');
Route::post('/templates', [ApiExplorerController::class, 'saveTemplate'])->name('templates.save');
Route::delete('/templates/{id}', [ApiExplorerController::class, 'deleteTemplate'])->name('templates.delete');
// 히스토리
Route::get('/history', [ApiExplorerController::class, 'history'])->name('history');
Route::delete('/history', [ApiExplorerController::class, 'clearHistory'])->name('history.clear');
Route::post('/history/{id}/replay', [ApiExplorerController::class, 'replayHistory'])->name('history.replay');
// 환경
Route::get('/environments', [ApiExplorerController::class, 'environments'])->name('environments');
Route::post('/environments', [ApiExplorerController::class, 'saveEnvironment'])->name('environments.save');
Route::delete('/environments/{id}', [ApiExplorerController::class, 'deleteEnvironment'])->name('environments.delete');
Route::post('/environments/{id}/default', [ApiExplorerController::class, 'setDefaultEnvironment'])->name('environments.default');
});
```
### 6.2 Controller 메서드 시그니처
```php
class ApiExplorerController extends Controller
{
public function __construct(
private OpenApiParserService $parser,
private ApiRequestService $requester,
private ApiExplorerService $explorer
) {}
// GET /dev-tools/api-explorer
public function index(): View
// GET /dev-tools/api-explorer/endpoints?search=&tags[]=&methods[]=
public function endpoints(Request $request): View // HTMX partial
// GET /dev-tools/api-explorer/endpoints/{operationId}
public function endpoint(string $operationId): View // HTMX partial
// POST /dev-tools/api-explorer/execute
public function execute(ExecuteApiRequest $request): JsonResponse
// Bookmarks CRUD...
// Templates CRUD...
// History CRUD...
// Environments CRUD...
}
```
### 6.3 Service 클래스
```php
// OpenApiParserService - OpenAPI JSON 파싱
class OpenApiParserService
{
public function parse(): array; // 전체 스펙 파싱
public function getEndpoints(): Collection; // 엔드포인트 목록
public function getEndpoint(string $operationId): ?array; // 단일 엔드포인트
public function getTags(): array; // 태그 목록
public function search(string $query): Collection; // 검색
public function filter(array $filters): Collection; // 필터링
}
// ApiRequestService - API 호출 프록시
class ApiRequestService
{
public function execute(
string $method,
string $url,
array $headers = [],
array $query = [],
?array $body = null
): ApiResponse;
}
// ApiExplorerService - 비즈니스 로직 통합
class ApiExplorerService
{
// Bookmark operations
public function getBookmarks(int $userId): Collection;
public function addBookmark(int $userId, array $data): ApiBookmark;
public function removeBookmark(int $bookmarkId): void;
// Template operations
public function getTemplates(int $userId, ?string $endpoint = null): Collection;
public function saveTemplate(int $userId, array $data): ApiTemplate;
public function deleteTemplate(int $templateId): void;
// History operations
public function logRequest(int $userId, array $data): ApiHistory;
public function getHistory(int $userId, int $limit = 50): Collection;
public function clearHistory(int $userId): void;
// Environment operations
public function getEnvironments(int $userId): Collection;
public function saveEnvironment(int $userId, array $data): ApiEnvironment;
}
```
---
## 7. 핵심 기능 상세
### 7.1 스마트 검색
```php
// 검색 대상 필드
$searchFields = [
'endpoint', // /api/v1/users
'summary', // "사용자 목록 조회"
'description', // 상세 설명
'operationId', // getUserList
'parameters.*.name', // 파라미터명
'parameters.*.description', // 파라미터 설명
'tags', // 태그
];
// 검색 알고리즘
1. 정확히 일치 → 최상위
2. 시작 부분 일치 → 높은 순위
3. 포함 → 일반 순위
4. Fuzzy 매칭 → 낮은 순위 (선택적)
```
### 7.2 필터링 옵션
```php
$filters = [
'methods' => ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'],
'tags' => ['Auth', 'Users', 'Products', ...],
'status' => ['stable', 'beta', 'deprecated'],
'hasBody' => true|false,
'requiresAuth' => true|false,
];
```
### 7.3 요청 템플릿 시스템
```json
// 템플릿 저장 형식
{
"name": "로그인 테스트",
"description": "테스트 계정으로 로그인",
"endpoint": "/api/v1/login",
"method": "POST",
"headers": {
"X-API-KEY": "{{API_KEY}}"
},
"body": {
"user_id": "test",
"user_pwd": "testpass"
},
"is_shared": false
}
```
### 7.4 환경 변수 시스템
```json
// 환경 설정 형식
{
"name": "로컬",
"base_url": "http://api.sam.kr",
"api_key": "your-api-key",
"auth_token": null,
"variables": {
"TENANT_ID": "1",
"USER_ID": "test"
}
}
// 변수 치환: {{VARIABLE_NAME}}
// 예: "Authorization": "Bearer {{AUTH_TOKEN}}"
```
---
## 8. HTMX 통합
### 8.1 주요 HTMX 패턴
```html
<!-- 엔드포인트 목록 갱신 -->
<div id="endpoint-list"
hx-get="/dev-tools/api-explorer/endpoints"
hx-trigger="load, search"
hx-swap="innerHTML">
</div>
<!-- 검색 입력 -->
<input type="text"
name="search"
hx-get="/dev-tools/api-explorer/endpoints"
hx-trigger="keyup changed delay:300ms"
hx-target="#endpoint-list"
hx-include="[name='methods[]'], [name='tags[]']">
<!-- 엔드포인트 선택 -->
<button hx-get="/dev-tools/api-explorer/endpoints/{{ $operationId }}"
hx-target="#request-panel"
hx-swap="innerHTML">
</button>
<!-- API 실행 -->
<form hx-post="/dev-tools/api-explorer/execute"
hx-target="#response-panel"
hx-indicator="#loading-spinner">
</form>
<!-- 즐겨찾기 토글 -->
<button hx-post="/dev-tools/api-explorer/bookmarks"
hx-vals='{"endpoint": "{{ $endpoint }}", "method": "{{ $method }}"}'
hx-swap="outerHTML">
⭐
</button>
```
### 8.2 OOB (Out-of-Band) 업데이트
```html
<!-- 응답 후 히스토리 자동 갱신 -->
<div id="history-count" hx-swap-oob="true">
{{ $historyCount }}
</div>
```
---
## 9. 보안 고려사항
### 9.1 접근 제어
- mng 프로젝트 로그인 필수 (`auth` 미들웨어)
- 개발 환경에서만 접근 가능 (선택적)
- API Key/Token은 서버사이드에서만 관리
### 9.2 민감 정보 처리
- 환경 설정의 API Key는 암호화 저장
- 히스토리에서 민감 헤더 마스킹 옵션
- 공유 템플릿에서 인증 정보 자동 제외
### 9.3 프록시 보안
- 허용된 base_url만 프록시 가능 (화이트리스트)
- 요청 크기 제한 (body 최대 1MB)
- 타임아웃 설정 (30초)
---
## 10. 구현 로드맵
### Phase 1: 기본 구조 (3-4일)
- [ ] 디렉토리 구조 생성
- [ ] 마이그레이션 파일 작성
- [ ] OpenApiParserService 구현
- [ ] 기본 UI 레이아웃 (3-Panel)
- [ ] 엔드포인트 목록 표시
### Phase 2: 검색/필터/요청 (3일)
- [ ] 풀텍스트 검색 구현
- [ ] 메서드/태그 필터링
- [ ] 요청 패널 UI
- [ ] ApiRequestService (프록시)
- [ ] 응답 표시 (JSON Viewer)
### Phase 3: 사용자 데이터 (3일)
- [ ] 즐겨찾기 CRUD
- [ ] 템플릿 저장/불러오기
- [ ] 히스토리 기록/재실행
- [ ] 드래그&드롭 정렬
### Phase 4: 환경/고급 기능 (2-3일)
- [ ] 환경 관리 UI
- [ ] 변수 치환 시스템
- [ ] 키보드 단축키
- [ ] UI 폴리싱
- [ ] 반응형 최적화
### Phase 5: 테스트/배포 (2일)
- [ ] 기능 테스트
- [ ] 성능 최적화
- [ ] 문서화
- [ ] 배포
**예상 총 기간: 13-15일**
---
## 11. 향후 확장 가능성
### 11.1 추가 기능 후보
- **Mock 서버**: 테스트용 가짜 응답 생성
- **API 비교**: 두 환경 간 응답 비교
- **자동 테스트**: 저장된 템플릿 일괄 실행
- **변경 감지**: OpenAPI 스펙 변경 알림
- **문서 생성**: Markdown/PDF 문서 자동 생성
### 11.2 통합 가능성
- **CI/CD**: API 테스트 자동화
- **Slack/Teams**: 알림 연동
- **Postman**: 컬렉션 import/export
---
## 12. 참고 자료
### 12.1 유사 도구
- [Scalar](https://scalar.com/) - 현대적 API 문서
- [Stoplight](https://stoplight.io/) - API 설계 도구
- [Insomnia](https://insomnia.rest/) - API 클라이언트
### 12.2 기술 문서
- [OpenAPI 3.0 Specification](https://spec.openapis.org/oas/v3.0.3)
- [HTMX Documentation](https://htmx.org/docs/)
- [Laravel HTTP Client](https://laravel.com/docs/http-client)

425
docs/features/barobill-kakaotalk/README.md Normal file
View File

@@ -0,0 +1,425 @@
# 바로빌 카카오톡 (알림톡/친구톡) 연동
> **문서 버전**: 1.0
> **작성일**: 2026-02-14
> **최종 수정**: 2026-02-24
> **상태**: 운영 중 (전자계약 알림톡 발송 완료)
> **대상 프로젝트**: MNG
---
## 1. 개요
### 1.1 목적
바로빌(Barobill) 플랫폼의 카카오톡 알림톡/친구톡 API를 SAM에 연동하여,
고객사에 카카오톡 메시지를 자동 또는 수동으로 발송하는 기능을 제공한다.
### 1.2 사전 요구사항
| 항목 | 상태 | 설명 |
|------|------|------|
| 법인 명의 휴대폰 준비 | **완료** | 카카오톡 채널 가입에 법인 명의 번호 사용 |
| 카카오톡 채널 개설 | **완료** (2026-02-20) | 채널 ID: `@codebridge`, 채널명: (주)코드브릿지엑스 |
| 바로빌 카카오톡 서비스 신청 | **완료** (2026-02-20) | 바로빌 관리자 페이지에서 카카오톡 서비스 활성화 |
| 채널 연동 (바로빌↔카카오) | **완료** (2026-02-20) | 바로빌 관리 URL에서 채널 연동 처리 |
| 바로빌 파트너 과금 설정 | **완료** (2026-02-23) | 바로빌 측에서 파트너사 과금 설정 완료 |
| 알림톡 템플릿 v1 검수 | **완료** (2026-02-22) | `전자계약_서명요청`, `전자계약_리마인드` 2종 승인 |
| 알림톡 템플릿 v2 검수 | **심사 중** (2026-02-24 접수) | 버튼 URL에 `#{토큰}` 변수 포함 2종 재등록 |
> 상세 등록 가이드: [카카오톡 알림톡 채널 및 템플릿 등록 가이드](../../guides/카카오톡-알림톡-채널-템플릿-등록.md)
### 1.3 알림톡 vs 친구톡
| 구분 | 알림톡 | 친구톡 |
|------|--------|--------|
| **용도** | 정보성 메시지 (주문확인, 배송안내 등) | 광고성 메시지 (프로모션, 이벤트 등) |
| **수신 대상** | 모든 카카오톡 사용자 | 채널 친구 추가한 사용자만 |
| **템플릿** | 필수 (카카오 사전 검수) | 불필요 (자유 형식) |
| **광고 표시** | 불가 | 필수 (`(광고)` 표기) |
| **이미지 첨부** | 불가 | 가능 (이미지/와이드 이미지) |
| **비용** | 건당 약 8~9원 | 건당 약 15~20원 |
| **SMS 대체발송** | 설정 가능 | 설정 가능 |
---
## 2. 아키텍처
### 2.1 시스템 구조
```
SAM MNG (브라우저)
│
├─ [페이지] /barobill/kakaotalk/* ← Blade 뷰
│ KakaotalkController (페이지 렌더링)
│
├─ [API] /api/admin/barobill/kakaotalk/* ← AJAX 호출
│ BarobillKakaotalkController
│
└─ [전자계약] /esign/* ← 자동 발송
EsignApiController::sendAlimtalk()
│
└─ BarobillService (SOAP 클라이언트)
│
└─ 바로빌 KAKAOTALK.asmx (WSDL)
│
└─ 카카오톡 서버
```
### 2.2 바로빌 SOAP API 엔드포인트
| 환경 | WSDL URL |
|------|----------|
| **테스트** | `https://testws.baroservice.com/KAKAOTALK.asmx?WSDL` |
| **운영** | `https://ws.baroservice.com/KAKAOTALK.asmx?WSDL` |
---
## 3. 전자계약 알림톡 연동 (핵심)
### 3.1 발송 흐름
```
전자계약 생성 (E-Sign)
│
├─ [1단계] EsignApiController::sendAlimtalk()
│ │
│ ├─ 채널 ID 조회 (getKakaotalkChannelId)
│ ├─ 템플릿 본문 + 버튼 조회 (getTemplateData)
│ ├─ 변수 치환 (#{이름}, #{계약명}, #{기한})
│ └─ SendATKakaotalkEx 호출
│
├─ [2단계] 바로빌 접수 → SendKey 반환
│
├─ [3단계] 3초 대기 후 GetSendKakaotalk으로 전달 결과 확인
│ │
│ ├─ ResultCode = 1 → 성공
│ └─ ResultCode != 1 → 실패 (에러 반환)
│
└─ [이메일 폴백] 알림톡 실패 시 이메일로 자동 전환
```
### 3.2 등록된 템플릿 (v1 — 현재 운영)
**`전자계약_서명요청`**
```
안녕하세요, #{이름}님.
전자계약 서명 요청이 도착했습니다.
■ 계약명: #{계약명}
■ 서명 기한: #{기한}
아래 버튼을 눌러 계약서를 확인하고 서명해 주세요.
```
- 버튼: `계약서 확인하기` (WL)
- Url1/Url2: `https://mng.codebridge-x.com`
**`전자계약_리마인드`**
```
안녕하세요, #{이름}님.
아직 서명이 완료되지 않은 전자계약이 있습니다.
■ 계약명: #{계약명}
■ 서명 기한: #{기한}
기한 내에 서명을 완료해 주세요.
```
- 버튼: `계약서 확인하기` (WL)
- Url1/Url2: `https://mng.codebridge-x.com`
### 3.3 등록 예정 템플릿 (v2 — 심사 중)
> **2026-02-24 재등록**: 버튼 URL에 `#{토큰}` 변수를 포함하여 동적 서명 URL 지원
- Url1/Url2: `https://mng.codebridge-x.com/esign/sign/#{토큰}`
v2 승인 후 코드 변경 필요:
- `EsignApiController::sendAlimtalk()`에서 동적 `$signUrl`을 버튼 URL로 전달
- 현재 코드의 등록된 URL 그대로 사용 → 동적 URL 사용으로 전환
### 3.4 임시 우회: 로그인 페이지 서명 확인
v1 템플릿의 버튼 URL이 대시보드(`https://mng.codebridge-x.com`)로 고정되어 있어,
로그인 페이지에 전화번호 기반 서명 확인 기능을 추가하였다.
```
알림톡 버튼 클릭 → https://mng.codebridge-x.com → 로그인 페이지
│
└─ "전자계약 서명하기" 섹션
│
├─ 전화번호 입력
├─ POST /esign/verify-phone
└─ 대기 중인 계약 조회 → /esign/sign/{token} 리다이렉트
```
- 라우트: `POST /esign/verify-phone`
- 컨트롤러: `EsignPublicController::verifyPhone()`
- v2 템플릿 승인 후에도 유지 (비로그인 사용자 대응)
### 3.5 관련 파일
| 파일 | 역할 |
|------|------|
| `app/Http/Controllers/ESign/EsignApiController.php` | `sendAlimtalk()`, `getTemplateData()` |
| `app/Http/Controllers/ESign/EsignPublicController.php` | `verifyPhone()` 전화번호 확인 |
| `app/Services/Barobill/BarobillService.php` | SOAP 클라이언트, `sendATKakaotalkEx()` |
| `resources/views/auth/login.blade.php` | 로그인 페이지 서명 확인 UI |
| `routes/web.php` | `/esign/verify-phone` 라우트 |
---
## 4. 트러블슈팅 (실전 경험)
> **경고: 아래 내용은 실제 연동 과정에서 발견한 핵심 이슈다. 반드시 숙지할 것.**
### 4.1 바로빌 API 응답 구조
바로빌 SOAP 응답은 `stdClass` 객체로 반환된다. 배열이 아니므로 주의:
```php
// ❌ 잘못된 접근
$channels = $result['data']; // 배열이 아님
// ✅ 올바른 접근
$data = $result['data']; // stdClass
$channels = is_array($data->KakaotalkChannel)
? $data->KakaotalkChannel
: [$data->KakaotalkChannel]; // 1건이면 객체, N건이면 배열
```
### 4.2 SendKey vs ResultCode (2단계 검증 필수)
> **핵심**: 바로빌이 SendKey를 반환해도 **실제 카카오톡 전달이 실패할 수 있다.**
```
[1단계] SendATKakaotalkEx 호출
→ SendKey 반환 (예: BB_6648603713_AT_3044107_260224)
→ 이것은 "접수 성공"이지 "전달 성공"이 아님!
[2단계] 3초 후 GetSendKakaotalk(SendKey) 호출
→ ResultCode = 1: 전달 성공 ✅
→ ResultCode = 4: 템플릿 데이터 일치 오류 ❌
→ ResultCode != 1: 기타 실패 ❌
```
```php
// 반드시 2단계 검증 필요
if ($result['success'] && is_string($result['data'])) {
$sendKey = $result['data'];
sleep(3); // 카카오톡 전달 대기
$sendResult = $barobill->getSendKakaotalk($member->biz_no, $sendKey);
$resultCode = $sendResult['data']->ResultCode ?? null;
if ($resultCode != 1) {
// 실패 처리!
}
}
```
### 4.3 템플릿 URL 정확 일치 규칙
> **핵심**: 버튼 URL은 등록된 템플릿의 URL과 **정확히 일치**해야 한다. 1글자라도 다르면 실패.
| 등록된 URL | 전송 시 URL | 결과 |
|------------|------------|------|
| `https://mng.codebridge-x.com` | `https://mng.codebridge-x.com` | ResultCode=1 (성공) |
| `https://mng.codebridge-x.com` | `https://mng.codebridge-x.com/esign/sign/xxx` | ResultCode=4 (실패) |
| `https://mng.codebridge-x.com` | `https://mng.codebridge-x.com?sign=xxx` | ResultCode=4 (실패) |
| `https://mng.codebridge-x.com` | `https://mng.codebridge-x.com#sign=xxx` | ResultCode=4 (실패) |
- 경로 추가: 실패
- 쿼리 파라미터 추가: 실패
- URL 프래그먼트(#) 추가: 실패
- **동적 URL을 사용하려면 템플릿에 `#{변수}` 포함하여 재등록 필요**
### 4.4 SmsReply 오류 (-31325)
`SmsReply` 파라미터가 `'S'`(대체발송 사용)인데 `SmsSenderNum`이 비어있으면 `-31325` 오류 발생.
```php
// ❌ 오류 발생
'SmsReply' => empty($smsMessage) ? 'N' : 'S', // SmsSenderNum이 비어도 S로 설정
// ✅ 수정
'SmsReply' => (empty($smsMessage) || empty($smsSenderNum)) ? 'N' : 'S',
```
### 4.5 SOAP 파라미터 구조
바로빌 SOAP API의 파라미터 구조에 주의:
```php
// 올바른 구조
$params = [
'CorpNum' => $bizNo, // 사업자번호 (하이픈 포함: 123-45-67890)
'SenderID' => $barobillId, // 바로빌 계정 ID
'YellowId' => $channelId, // 카카오 채널 ID (@codebridge)
'TemplateName' => '전자계약_서명요청',
'SendDT' => '', // 즉시발송: 빈 문자열
'SmsReply' => 'N', // SMS 발신번호 없으면 반드시 'N'
'SmsSenderNum' => '',
'KakaotalkMessage' => [
'ReceiverName' => $name,
'ReceiverNum' => $phone, // 하이픈 없이: 01012345678
'Title' => '',
'Message' => $message, // 템플릿 변수 치환 완료된 본문
'SmsMessage' => '',
'SmsSubject' => '',
'Buttons' => ['KakaotalkButton' => $buttons], // 버튼 배열
],
];
```
### 4.6 에러 코드 정리
| 코드 | 메시지 | 원인 | 해결 |
|------|--------|------|------|
| 1 | 성공 | 정상 전달 | - |
| 4 | 템플릿 데이터 일치 오류 | 본문/버튼 URL이 등록 템플릿과 불일치 | 등록된 템플릿과 동일하게 전송 |
| -31325 | 대체문자 유형 오류 | SmsReply=S인데 SmsSenderNum 비어있음 | SmsReply를 N으로 설정 |
| 음수값 | 바로빌 API 오류 | 파라미터 오류 또는 서비스 미설정 | 바로빌 에러코드 문서 참조 |
---
## 5. 구현 현황
### 5.1 완료된 항목
| 구분 | 파일 | 설명 |
|------|------|------|
| SOAP 서비스 | `app/Services/Barobill/BarobillService.php` | kakaotalk SOAP 클라이언트 + 15개 API 메서드 |
| 전자계약 알림톡 | `app/Http/Controllers/ESign/EsignApiController.php` | `sendAlimtalk()`, `getTemplateData()` |
| 서명 확인 | `app/Http/Controllers/ESign/EsignPublicController.php` | `verifyPhone()` 전화번호 기반 서명 확인 |
| API 컨트롤러 | `app/Http/Controllers/Api/Admin/Barobill/BarobillKakaotalkController.php` | 15개 API 엔드포인트 |
| 페이지 컨트롤러 | `app/Http/Controllers/Barobill/KakaotalkController.php` | 6개 관리 페이지 |
| 로그인 페이지 | `resources/views/auth/login.blade.php` | 전자계약 서명하기 섹션 |
| 라우트 | `routes/web.php` | `/esign/verify-phone`, `/barobill/kakaotalk/*` |
| 메뉴 등록 | DB (menus 테이블) | 로컬/서버 모두 등록 완료 |
### 5.2 검증 완료 항목
| 항목 | 결과 | 날짜 |
|------|------|------|
| 채널 API 호출 | **성공** | 2026-02-22 |
| 템플릿 조회 | **성공** | 2026-02-22 |
| 알림톡 발송 (본문) | **성공** (ResultCode=1) | 2026-02-24 |
| 알림톡 버튼 URL | **성공** (등록된 URL 사용 시) | 2026-02-24 |
| 전달 결과 확인 (2단계) | **구현 완료** | 2026-02-24 |
| 로그인 페이지 서명 확인 | **성공** | 2026-02-24 |
### 5.3 대기 중인 항목
| 항목 | 상태 | 비고 |
|------|------|------|
| 템플릿 v2 승인 | **심사 중** | 버튼 URL에 `#{토큰}` 변수 포함 |
| v2 승인 후 코드 수정 | **대기** | 동적 서명 URL을 버튼에 전달 |
| `전자계약_완료` 템플릿 | **미등록** | 서명 완료 알림 발송용 |
| SMS 대체발송 | **미설정** | 발신번호 등록 필요 |
| 친구톡 발송 | **대기** | 채널 친구 추가 후 가능 |
| 대량 발송 | **대기** | 단건 안정화 후 |
---
## 6. v2 템플릿 승인 후 코드 변경 가이드
### 6.1 변경 대상
`EsignApiController::sendAlimtalk()` (약 1059~1063행)
### 6.2 현재 코드 (v1)
```php
// 등록된 버튼 URL을 그대로 사용 (동적 URL 사용 시 템플릿 불일치 오류)
$buttons = ! empty($templateButtons) ? $templateButtons : [
['Name' => '계약서 확인하기', 'ButtonType' => 'WL',
'Url1' => 'https://mng.codebridge-x.com', 'Url2' => 'https://mng.codebridge-x.com'],
];
```
### 6.3 변경 코드 (v2 승인 후)
```php
// v2 템플릿: 버튼 URL에 동적 서명 URL 사용
$buttons = [
['Name' => '계약서 확인하기', 'ButtonType' => 'WL',
'Url1' => $signUrl, 'Url2' => $signUrl],
];
```
- `$signUrl`은 1033행에서 이미 생성됨: `config('app.url').'/esign/sign/'.$signer->access_token`
- `getTemplateData()`에서 등록된 버튼 조회는 더 이상 필요 없음 (제거 가능)
---
## 7. API 메서드 목록
### 7.1 BarobillService 카카오톡 메서드
| 메서드 | SOAP Action | 설명 |
|--------|-------------|------|
| `getKakaotalkChannels` | `GetKakaotalkChannels` | 채널 목록 조회 |
| `getKakaotalkChannelManagementUrl` | `GetKakaotalkChannelManagementURL` | 채널 관리 URL |
| `getKakaotalkTemplates` | `GetKakaotalkTemplates` | 템플릿 목록 조회 |
| `getKakaotalkTemplateManagementUrl` | `GetKakaotalkTemplateManagementURL` | 템플릿 관리 URL |
| `sendATKakaotalk` | `SendATKakaotalk` | 알림톡 단건 발송 |
| `sendATKakaotalkEx` | `SendATKakaotalkEx` | 알림톡 단건 발송 (버튼 포함) |
| `sendATKakaotalks` | `SendATKakaotalks` | 알림톡 대량 발송 |
| `sendFTKakaotalk` | `SendFTKakaotalk` | 친구톡 텍스트 단건 |
| `sendFTKakaotalks` | `SendFTKakaotalks` | 친구톡 텍스트 대량 |
| `sendFIKakaotalk` | `SendFIKakaotalk` | 친구톡 이미지 |
| `sendFWKakaotalk` | `SendFWKakaotalk` | 친구톡 와이드 이미지 |
| `getSendKakaotalk` | `GetSendKakaotalk` | 전송 결과 단건 조회 |
| `getSendKakaotalks` | `GetSendKakaotalks` | 전송 결과 다건 조회 |
| `cancelReservedKakaotalk` | `CancelReservedKakaotalk` | 예약 전송 취소 |
---
## 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)
- [카카오 알림톡 가이드](https://kakaobusiness.gitbook.io)
- 바로빌 템플릿 관리: 로그인 후 `https://www.barobill.co.kr` → 카카오톡 템플릿 관리
---
## 변경 이력
| 날짜 | 버전 | 변경 내용 |
|------|------|----------|
| 2026-02-24 | 1.0 | 전자계약 알림톡 연동 완료, 트러블슈팅 문서화, v2 템플릿 가이드 추가 |
| 2026-02-14 | 0.2 | 전자계약(E-Sign) 알림톡 연동 활용 계획 추가 |
| 2026-02-14 | 0.1 | 초안 작성 - 코드 구현 완료, 실 서비스 연동 대기 |

37
docs/features/boards/README.md Normal file
View File

@@ -0,0 +1,37 @@
# 게시판 시스템
> 📌 SAM 프로젝트의 시스템/테넌트 게시판 기능
## 문서 목록
| 문서 | 설명 | 대상 |
|------|------|------|
| [시스템 스펙](../../system/board-system-spec.md) | 게시판 전체 설계 스펙 | 설계 참고 |
| [MNG 구현](./mng-implementation.md) | MNG 관리자 패널 구현 상세 | MNG 개발 |
## 개요
- **MNG**: 시스템 게시판 생성/관리 (`is_system=true`, `tenant_id=null`)
- **API**: 테넌트 게시판 생성 + 시스템 게시판 조회 (`is_system=false`, `tenant_id={tenant}`)
## 빠른 참조
### 데이터베이스
- `boards` - 게시판 정의
- `board_settings` - 커스텀 필드 정의
- `posts` - 게시글
- `comments` - 댓글
### 주요 API
- `GET /api/v1/boards` - 게시판 목록 (시스템 + 테넌트)
- `POST /api/v1/boards/{code}/posts` - 게시글 작성
- `GET /api/v1/boards/{code}/fields` - 커스텀 필드 목록
### MNG 라우트
- `/boards` - 게시판 목록
- `/boards/create` - 게시판 생성
- `/boards/{id}/edit` - 게시판 수정
---
[← 메인 인덱스로](../../INDEX.md)

248
docs/features/boards/mng-implementation.md Normal file
View File

@@ -0,0 +1,248 @@
# 게시판 관리 시스템
## 개요
SAM 프로젝트의 게시판 관리 시스템은 **MNG(상위 관리자)**와 **API(테넌트)**에서 각각 다른 역할로 운영됩니다.
| 구분 | 역할 | 게시판 유형 |
|------|------|-------------|
| **MNG** | 시스템 게시판 생성/관리 | `is_system=true`, `tenant_id=null` |
| **API** | 테넌트 게시판 생성 + 시스템 게시판 조회 | `is_system=false`, `tenant_id={tenant}` |
## 아키텍처
```
┌─────────────────────────────────────────────────────────────┐
│ MNG (상위 관리자) │
│ - 시스템 게시판 CRUD │
│ - 커스텀 필드 관리 │
│ - 모든 테넌트에서 접근 가능한 공용 게시판 │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ boards 테이블 │
│ - is_system: boolean (시스템/테넌트 구분) │
│ - tenant_id: nullable (시스템은 null) │
│ - board_type: varchar(50) - 자유 입력 │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ API (테넌트) │
│ - 시스템 게시판 조회 (읽기 전용) │
│ - 테넌트 게시판 CRUD │
│ - 게시글/댓글 CRUD │
└─────────────────────────────────────────────────────────────┘
```
## 데이터베이스 스키마
### boards 테이블
| 컬럼 | 타입 | 설명 |
|------|------|------|
| id | bigint | PK |
| tenant_id | bigint | FK (nullable - 시스템 게시판은 null) |
| is_system | boolean | 시스템 게시판 여부 (default: false) |
| board_type | varchar(50) | 게시판 유형 (notice, qna, faq 등 자유 입력) |
| board_code | varchar(50) | 게시판 코드 (unique per tenant) |
| name | varchar(100) | 게시판명 |
| description | text | 설명 |
| editor_type | enum | wysiwyg, markdown, text |
| allow_files | boolean | 파일 첨부 허용 |
| max_file_count | int | 최대 파일 수 |
| max_file_size | int | 최대 파일 크기 (KB) |
| extra_settings | json | 추가 설정 |
| is_active | boolean | 활성 상태 |
| deleted_at | timestamp | Soft Delete |
### board_settings 테이블 (커스텀 필드)
| 컬럼 | 타입 | 설명 |
|------|------|------|
| id | bigint | PK |
| board_id | bigint | FK → boards |
| name | varchar(100) | 필드명 (한글 라벨) |
| field_key | varchar(50) | 필드 키 (영문, 스네이크케이스) |
| field_type | varchar(20) | text, textarea, number, date, select 등 |
| is_required | boolean | 필수 여부 |
| sort_order | int | 정렬 순서 |
| options | json | 선택형 필드의 옵션 값 |
## MNG 구현
### 파일 구조
```
mng/
├── app/
│ ├── Http/Controllers/
│ │ ├── BoardController.php # Blade 컨트롤러
│ │ └── Api/Admin/BoardController.php # API 컨트롤러
│ ├── Models/Boards/
│ │ ├── Board.php
│ │ └── BoardSetting.php
│ └── Services/
│ └── BoardService.php
├── resources/views/boards/
│ ├── index.blade.php
│ ├── create.blade.php
│ ├── edit.blade.php
│ └── partials/table.blade.php
└── routes/
├── web.php # Blade 라우트
└── api.php # API 라우트
```
### 라우트
#### Web 라우트 (Blade)
| Method | URI | Name | 설명 |
|--------|-----|------|------|
| GET | /boards | boards.index | 목록 |
| GET | /boards/create | boards.create | 생성 폼 |
| GET | /boards/{id}/edit | boards.edit | 수정 폼 |
#### API 라우트 (HTMX/Ajax)
| Method | URI | 설명 |
|--------|-----|------|
| GET | /api/admin/boards | 목록 (페이지네이션) |
| POST | /api/admin/boards | 생성 |
| GET | /api/admin/boards/{id} | 상세 |
| PUT | /api/admin/boards/{id} | 수정 |
| DELETE | /api/admin/boards/{id} | 삭제 |
| GET | /api/admin/boards/{id}/fields | 커스텀 필드 목록 |
| POST | /api/admin/boards/{id}/fields | 커스텀 필드 추가 |
| PUT | /api/admin/boards/{id}/fields/{fieldId} | 커스텀 필드 수정 |
| DELETE | /api/admin/boards/{id}/fields/{fieldId} | 커스텀 필드 삭제 |
### 커스텀 필드 모달
다중 필드 추가 기능:
- 한 줄에 필드명, 필드키, 타입, 필수 체크박스 배치
- `+ 필드 추가` 버튼으로 행 추가
- X 버튼으로 행 삭제
- 여러 필드 일괄 저장
```
┌─────────────────────────────────────────────────────────────┐
│ 필드 추가 │
├─────────────────────────────────────────────────────────────┤
│ 필드명* 필드키* 타입* 필수 삭제 │
│ [카테고리] [category] [선택 ▼] [✓] [X] │
│ [작성자] [author] [텍스트 ▼] [ ] [X] │
├─────────────────────────────────────────────────────────────┤
│ ┌─────────────────────────┐ │
│ │ + 필드 추가 │ │
│ └─────────────────────────┘ │
│ * 필드 키: 영문 소문자와 언더스코어만 사용 │
├─────────────────────────────────────────────────────────────┤
│ [취소] [저장] │
└─────────────────────────────────────────────────────────────┘
```
## API 구현 (테넌트용)
### 파일 구조
```
api/
├── app/
│ ├── Http/Controllers/Api/V1/
│ │ ├── BoardController.php
│ │ └── PostController.php
│ ├── Http/Requests/Boards/
│ │ ├── BoardStoreRequest.php
│ │ ├── BoardUpdateRequest.php
│ │ ├── PostStoreRequest.php
│ │ ├── PostUpdateRequest.php
│ │ └── CommentStoreRequest.php
│ └── Services/Boards/
│ └── PostService.php
├── app/Swagger/v1/
│ ├── BoardApi.php
│ └── PostApi.php
└── routes/api.php
```
### API 엔드포인트
#### 게시판 API
| Method | URI | 설명 |
|--------|-----|------|
| GET | /api/v1/boards | 접근 가능한 게시판 목록 (시스템 + 테넌트) |
| GET | /api/v1/boards/tenant | 테넌트 게시판만 |
| POST | /api/v1/boards | 테넌트 게시판 생성 |
| GET | /api/v1/boards/{code} | 게시판 상세 (코드 기반) |
| PUT | /api/v1/boards/{id} | 테넌트 게시판 수정 |
| DELETE | /api/v1/boards/{id} | 테넌트 게시판 삭제 |
| GET | /api/v1/boards/{code}/fields | 커스텀 필드 목록 |
#### 게시글 API
| Method | URI | 설명 |
|--------|-----|------|
| GET | /api/v1/boards/{code}/posts | 게시글 목록 |
| POST | /api/v1/boards/{code}/posts | 게시글 작성 |
| GET | /api/v1/boards/{code}/posts/{id} | 게시글 상세 |
| PUT | /api/v1/boards/{code}/posts/{id} | 게시글 수정 |
| DELETE | /api/v1/boards/{code}/posts/{id} | 게시글 삭제 |
#### 댓글 API
| Method | URI | 설명 |
|--------|-----|------|
| GET | /api/v1/boards/{code}/posts/{postId}/comments | 댓글 목록 |
| POST | /api/v1/boards/{code}/posts/{postId}/comments | 댓글 작성 |
| PUT | /api/v1/boards/{code}/posts/{postId}/comments/{commentId} | 댓글 수정 |
| DELETE | /api/v1/boards/{code}/posts/{postId}/comments/{commentId} | 댓글 삭제 |
## 접근 권한 로직
```php
// 게시판 목록 조회 (테넌트 API)
public function index()
{
$tenantId = $this->tenantId();
// 시스템 게시판 + 해당 테넌트 게시판
$boards = Board::where(function ($q) use ($tenantId) {
$q->where('is_system', true)
->orWhere('tenant_id', $tenantId);
})
->where('is_active', true)
->get();
}
// 게시판 수정/삭제 (테넌트는 자신의 게시판만)
public function update($id)
{
$board = Board::where('id', $id)
->where('tenant_id', $this->tenantId())
->where('is_system', false) // 시스템 게시판 수정 불가
->firstOrFail();
}
```
## 커스텀 필드 타입
| 타입 | 설명 | 옵션 |
|------|------|------|
| text | 한 줄 텍스트 | - |
| textarea | 여러 줄 텍스트 | - |
| number | 숫자 | min, max |
| date | 날짜 | - |
| select | 드롭다운 선택 | options[] |
| checkbox | 체크박스 | - |
| radio | 라디오 버튼 | options[] |
| file | 파일 첨부 | allowed_extensions |
## 관련 문서
- [SAM API Rules](../../standards/api-rules.md)
- [MNG Critical Rules](../../../mng/docs/MNG_CRITICAL_RULES.md)
- [Board System Spec](../../system/board-system-spec.md)

465
docs/features/card-vehicle/CORPORATE_CARD_DASHBOARD.md Normal file
View File

@@ -0,0 +1,465 @@
# 법인카드 대시보드 기술 문서
> **작성일**: 2026-02-20
> **프로젝트**: SAM MNG (관리자 웹)
> **경로**: `/finance/corporate-cards`
---
## 1. 개요
법인카드 대시보드는 회사의 법인카드를 등록/관리하고, 바로빌(Barobill) SOAP API를 통해 수집된 카드 거래 데이터를 기반으로 사용 현황을 실시간 파악할 수 있는 재무 관리 도구입니다.
### 핵심 기능
- **카드 등록/수정/비활성화/삭제**: 법인카드 CRUD
- **대시보드 요약 카드 6종**: 등록카드, 총한도, 매월결제일, 사용금액, 결제, 잔여한도
- **결제일 동적 계산**: 현재일이 결제일을 지나면 자동으로 다음 월로 전환
- **휴일/주말 결제일 조정**: 공휴일·주말이면 다음 영업일로 자동 이동
- **바로빌 카드거래 연동**: 카드번호 기반 사용금액 자동 집계
- **결제(선불결제) 내역 관리**: 복수 건의 결제 내역 입력/수정
---
## 2. 시스템 아키텍처
```
┌─────────────────────────────────────────────────────┐
│ Frontend (React 18 + Babel 브라우저 트랜스파일링) │
│ corporate-cards.blade.php │
│ └─ CorporateCardsManagement 컴포넌트 │
│ ├─ 요약 카드 6종 (summary API) │
│ ├─ 카드 목록 테이블 (list API) │
│ ├─ 카드 등록/수정 모달 │
│ └─ 결제 내역 수정 모달 │
└──────────────┬──────────────────────────────────────┘
│ fetch() API 호출
▼
┌─────────────────────────────────────────────────────┐
│ Backend (Laravel 11) │
│ ├─ CorporateCardController (카드 CRUD + 요약) │
│ ├─ CardTransactionController (거래 CRUD) │
│ └─ EcardController (바로빌 SOAP API 연동) │
└──────────────┬──────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ Database (MySQL 8.0) │
│ ├─ corporate_cards (카드 정보) │
│ ├─ corporate_card_prepayments (결제 내역) │
│ ├─ barobill_card_transactions (바로빌 거래) │
│ ├─ barobill_card_transaction_hides (숨긴 거래) │
│ └─ holidays (공휴일 마스터) │
└─────────────────────────────────────────────────────┘
```
---
## 3. API 엔드포인트
모든 엔드포인트는 `/finance/corporate-cards` 접두사 하위에 정의됩니다.
| Method | URI | Controller Method | 설명 |
|--------|-----|-------------------|------|
| GET | `/finance/corporate-cards` | (클로저) | 페이지 렌더링 (React SPA) |
| GET | `/finance/corporate-cards/list` | `index()` | 카드 목록 JSON |
| GET | `/finance/corporate-cards/summary` | `summary()` | 대시보드 요약 데이터 |
| POST | `/finance/corporate-cards/store` | `store()` | 카드 신규 등록 |
| PUT | `/finance/corporate-cards/{id}` | `update()` | 카드 정보 수정 |
| POST | `/finance/corporate-cards/{id}/deactivate` | `deactivate()` | 카드 비활성화 |
| DELETE | `/finance/corporate-cards/{id}` | `destroy()` | 카드 영구삭제 |
| POST | `/finance/corporate-cards/prepayment` | `updatePrepayment()` | 결제 내역 저장 |
### 카드거래 내역 API (별도 컨트롤러)
| Method | URI | Controller | 설명 |
|--------|-----|------------|------|
| GET | `/finance/card-transactions` | `EcardController::index()` | 카드사용내역 페이지 |
| GET | `/finance/card-transactions/list` | `CardTransactionController::index()` | 거래내역 JSON |
| POST | `/finance/card-transactions/store` | `CardTransactionController::store()` | 거래 수동 등록 |
| PUT | `/finance/card-transactions/{id}` | `CardTransactionController::update()` | 거래 수정 |
| DELETE | `/finance/card-transactions/{id}` | `CardTransactionController::destroy()` | 거래 삭제 |
---
## 4. 데이터베이스 테이블
### 4.1 corporate_cards (법인카드)
| 컬럼 | 타입 | 설명 |
|------|------|------|
| id | bigint (PK) | |
| tenant_id | int | 테넌트 ID (Multi-tenant 격리) |
| card_name | varchar(100) | 카드 이름 (예: "업무용 법인카드") |
| card_company | varchar(50) | 카드사 (삼성카드, 현대카드 등) |
| card_number | varchar(30) | 카드번호 (하이픈 포함) |
| card_type | enum | `credit` (신용) / `debit` (체크) |
| payment_day | int | 결제일 (1~31, 기본값 15) |
| credit_limit | decimal(10,2) | 카드 한도 |
| current_usage | decimal(10,2) | 현재 사용량 (수동 관리) |
| card_holder_name | varchar(100) | 카드 명의자 |
| actual_user | varchar(100) | 실사용자 |
| expiry_date | varchar(10) | 유효기간 (YY/MM) |
| cvc | varchar(10) | CVC 코드 |
| status | enum | `active` / `inactive` |
| memo | text | 메모 |
| deleted_at | timestamp | SoftDeletes |
**스코프**: `forTenant($tenantId)`, `active()`
### 4.2 corporate_card_prepayments (결제 내역)
| 컬럼 | 타입 | 설명 |
|------|------|------|
| id | bigint (PK) | |
| tenant_id | int | 테넌트 ID |
| year_month | varchar(7) | 결제 기준 월 (예: "2026-03") |
| amount | int | 총 결제 금액 |
| items | json | 개별 결제 내역 배열 |
| memo | text | 메모 |
**items JSON 구조**:
```json
[
{
"date": "2026-02-10",
"amount": 500000,
"description": "카드대금 납부"
},
{
"date": "2026-02-15",
"amount": 300000,
"description": "추가 납부"
}
]
```
**주요 메서드**: `getOrCreate($tenantId, $yearMonth)` — 해당 월 레코드가 없으면 amount=0으로 자동 생성
### 4.3 barobill_card_transactions (바로빌 카드거래)
| 컬럼 | 타입 | 설명 |
|------|------|------|
| id | bigint (PK) | |
| tenant_id | int | 테넌트 ID |
| card_num | varchar | 카드번호 (하이픈 없음, 정규화) |
| card_company | varchar | 카드사 코드 |
| card_company_name | varchar | 카드사명 |
| use_dt | varchar | 사용일시 (YYYYMMDDHHmmss) |
| use_date | varchar(8) | 사용일 (YYYYMMDD) |
| use_time | varchar(6) | 사용시간 (HHmmss) |
| approval_num | varchar | 승인번호 |
| approval_type | char(1) | `1`: 승인, `2`: 취소 |
| approval_amount | decimal(10,2) | 승인금액 |
| tax | decimal(10,2) | 세금 |
| service_charge | decimal(10,2) | 봉사료 |
| merchant_name | varchar | 가맹점명 |
| merchant_biz_num | varchar | 가맹점 사업자번호 |
| is_manual | boolean | 수동 입력 여부 |
**unique_key (가상 속성)**: `card_num|use_dt|approval_num|approval_amount` — 거래 식별용
### 4.4 barobill_card_transaction_hides (숨긴 거래)
| 컬럼 | 타입 | 설명 |
|------|------|------|
| id | bigint (PK) | |
| tenant_id | int | 테넌트 ID |
| original_unique_key | varchar | 원래 거래의 unique_key |
| card_num | varchar | 카드번호 |
| use_date | varchar(8) | 사용일 |
| original_amount | decimal | 원래 금액 |
| merchant_name | varchar | 가맹점명 |
| hidden_by | int | 숨김 처리한 사용자 ID |
### 4.5 holidays (공휴일)
| 컬럼 | 타입 | 설명 |
|------|------|------|
| id | bigint (PK) | |
| tenant_id | int | 테넌트 ID |
| start_date | date | 시작일 |
| end_date | date | 종료일 |
| name | varchar | 공휴일 이름 |
| type | varchar | 유형 |
| is_recurring | boolean | 매년 반복 여부 |
---
## 5. 핵심 비즈니스 로직
### 5.1 결제일 동적 계산 (★ 핵심 전략)
법인카드의 매월 결제일은 **현재 날짜를 기준으로 동적 계산**됩니다.
**파일**: `CorporateCardController::summary()`
#### 계산 흐름
```
1. 활성 신용카드의 대표 결제일(payment_day) 조회
└─ 첫 번째 활성 신용카드 기준 (예: 15일)
2. 현재 월의 결제일 생성
└─ createPaymentDate(2026, 2, 15) → 2026-02-15
3. 휴일/주말 조정
└─ getAdjustedPaymentDate() → 토/일/공휴일이면 다음 영업일로 이동
└─ 예: 2/15(일) → 2/16(월)
4. 현재일이 결제일을 지났는지 확인
└─ if (now > adjustedDate) → 다음 월로 이동
└─ 예: 현재 2/20, 결제일 2/16 → 다음: 3/15 (→ 3/16 조정)
5. 결과 반환
├─ paymentDate: 조정된 결제일 (표시용)
├─ paymentDay: 원래 결제일 (설정값)
├─ originalDate: 조정 전 결제일
└─ isAdjusted: 조정 여부 (true이면 "15일→휴일조정" 표시)
```
#### 월 말일 처리
```php
// 2월 30일 같은 불가능한 날짜 방지
private function createPaymentDate(int $year, int $month, int $day): Carbon
{
$maxDay = Carbon::create($year, $month)->daysInMonth;
return Carbon::create($year, $month, min($day, $maxDay));
}
// 예: payment_day=31, 2월 → 2/28(또는 2/29)
```
#### 휴일 조정 로직
```php
private function getAdjustedPaymentDate($tenantId, $year, $month, $paymentDay): Carbon
{
$date = createPaymentDate($year, $month, $paymentDay);
// holidays 테이블에서 해당 기간의 휴일 조회
$holidays = Holiday::forTenant($tenantId)
->where('start_date', '<=', $date->addDays(10))
->where('end_date', '>=', $date)
->get();
// 토/일/공휴일이면 다음 영업일로 이동 (앞으로만)
while ($date->isWeekend() || in_array($date, $holidayDates)) {
$date->addDay();
}
return $date;
}
```
### 5.2 청구기간 계산
결제일을 기준으로 청구기간을 산출합니다.
```
청구기간 = 결제일 기준 전월 1일 ~ 결제일 당일
예시 (결제일: 3/15):
- billingStart: 2026-02-01
- billingEnd: 2026-03-15
```
### 5.3 사용금액 집계 (바로빌 카드거래)
**파일**: `CorporateCardController::calculateBillingUsage()`
```
1. 활성 카드의 카드번호 수집
└─ 하이픈 제거하여 정규화 (1234-5678-9012-3456 → 1234567890123456)
2. 바로빌 거래 조회
└─ barobill_card_transactions 테이블
└─ card_num IN (정규화된 카드번호들)
└─ use_date BETWEEN 청구시작(YYYYMMDD) AND 청구끝(YYYYMMDD)
3. 숨긴 거래 제외
└─ barobill_card_transaction_hides에서 hidden unique_key 조회
└─ 해당 거래는 집계에서 제외
4. 승인/취소 구분 합산
└─ approval_type = '1' (승인): +금액
└─ approval_type = '2' (취소): -금액
5. 결과: 전체 합계 + 카드별 합계
└─ { total: 1500000, perCard: { "1234...": 800000, "5678...": 700000 } }
```
### 5.4 잔여 한도 계산
```
잔여한도 = 총한도 - 사용금액 + 결제금액
예시:
총한도: 10,000,000원 (모든 활성 신용카드 credit_limit 합계)
사용금액: 3,000,000원 (바로빌 청구기간 거래 합산)
결제금액: 1,000,000원 (corporate_card_prepayments 해당월)
잔여한도: 8,000,000원
```
---
## 6. 대시보드 요약 카드 (6종)
React 컴포넌트 `CorporateCardsManagement` 내 그리드 레이아웃 (`grid-cols-2 lg:grid-cols-6`)
| # | 카드명 | 데이터 소스 | 계산 방식 |
|---|--------|------------|-----------|
| 1 | **등록 카드** | `cards.length` | 전체/활성 카드 수 |
| 2 | **총 한도** | `totalLimit` | 활성 신용카드의 `credit_limit` 합계 |
| 3 | **매월결제일** | `summaryData.paymentDate` | 동적 계산 (현재일 > 결제일이면 익월) |
| 4 | **사용금액** | `summaryData.billingUsage` | 바로빌 거래 합산 (청구기간 기준) |
| 5 | **결제** | `summaryData.prepaidAmount` | `corporate_card_prepayments` 합계 |
| 6 | **잔여 한도** | 계산값 | `총한도 - 사용금액 + 결제금액` |
### 매월결제일 카드 상세
- **파란색 강조** (border-blue-200, bg-blue-50/30)
- 메인 숫자: `M/D(요일)` 형식 (예: "3/15(월)")
- 보조 텍스트:
- 휴일 미조정: "매월 15일"
- 휴일 조정됨: "15일→휴일조정"
### 결제 카드 상세
- **주황색 강조** (border-amber-200, bg-amber-50/30)
- **수정 버튼**: 결제 내역 모달 열기
- 보조 텍스트: "N건" (입력된 결제 건수) 또는 "미입력"
---
## 7. 프론트엔드 구조
### 기술 스택
- **React 18** (Babel 브라우저 트랜스파일링, CDN)
- **Lucide Icons** (아이콘 라이브러리)
- **Tailwind CSS** (스타일링)
### 컴포넌트 구조
```
CorporateCardsManagement (메인 컴포넌트)
├─ Header (타이틀 + 카드 추가/테스트 버튼)
├─ Summary Cards (6개 요약 카드 그리드)
├─ Search & Filter (검색바 + 상태 필터)
├─ Card Table (카드 목록 테이블)
│ └─ 각 행: 카드정보 + 바로빌 사용금액 + 수정/삭제 버튼
├─ Card Modal (카드 등록/수정 모달)
│ └─ 카드명, 카드사, 카드번호, 유형, 결제일, 한도 등
└─ Prepayment Modal (결제 내역 수정 모달)
└─ 복수 결제 건 (날짜, 금액, 설명) + 합계
```
### 데이터 흐름
```
useEffect (초기 로드)
→ Promise.all([fetchCards(), fetchSummary()])
→ setCards(cardsResult.data)
→ setSummaryData(summaryResult.data)
카드 목록 테이블의 각 카드 행:
→ getBarobillUsage(card.cardNumber)
→ summaryData.cardUsages에서 해당 카드번호의 사용금액 조회
```
---
## 8. Summary API 응답 구조
**GET** `/finance/corporate-cards/summary`
```json
{
"success": true,
"data": {
"paymentDate": "2026-03-16",
"paymentDay": 15,
"originalDate": "2026-03-15",
"isAdjusted": true,
"billingPeriod": {
"start": "2026-02-01",
"end": "2026-03-16"
},
"billingUsage": 2850000,
"cardUsages": {
"1234567890123456": 1500000,
"9876543210987654": 1350000
},
"prepaidAmount": 500000,
"prepaidMemo": "",
"prepaidItems": [
{
"date": "2026-02-10",
"amount": 500000,
"description": "카드대금 납부"
}
]
}
}
```
---
## 9. 파일 경로 정리
### Backend (Laravel)
| 파일 | 설명 |
|------|------|
| `app/Http/Controllers/Finance/CorporateCardController.php` | 카드 CRUD + 요약 + 결제 |
| `app/Http/Controllers/Finance/CardTransactionController.php` | 카드거래 CRUD |
| `app/Http/Controllers/Barobill/EcardController.php` | 바로빌 SOAP API 연동 |
| `app/Models/Finance/CorporateCard.php` | 법인카드 모델 |
| `app/Models/Finance/CorporateCardPrepayment.php` | 결제 내역 모델 |
| `app/Models/Barobill/CardTransaction.php` | 바로빌 카드거래 모델 |
| `app/Models/Barobill/CardTransactionHide.php` | 숨긴 거래 모델 |
| `app/Models/System/Holiday.php` | 공휴일 모델 |
| `routes/web.php` (909~939행) | 라우트 정의 |
### Frontend (React + Blade)
| 파일 | 설명 |
|------|------|
| `resources/views/finance/corporate-cards.blade.php` | React SPA 전체 (약 1,000행) |
---
## 10. 전략적 고려사항
### 10.1 바로빌 데이터 신뢰성
- 바로빌 SOAP API를 통해 카드거래 데이터를 주기적으로 수집
- `unique_key`(카드번호+사용일시+승인번호+금액)로 중복 방지
- 사용자가 특정 거래를 숨길 수 있음 (비용 집계에서 제외)
### 10.2 Multi-tenant 데이터 격리
- 모든 쿼리에 `tenant_id` 조건 적용
- `session('selected_tenant_id', 1)`로 현재 테넌트 식별
### 10.3 카드번호 매칭
- DB(corporate_cards)에는 하이픈 포함 카드번호 저장
- 바로빌(barobill_card_transactions)에는 하이픈 없이 저장
- 매칭 시 `str_replace('-', '', $num)`으로 정규화 후 비교
### 10.4 결제일 자동 조정
- 토요일, 일요일, 공휴일(holidays 테이블)이면 **다음 영업일**로 이동
- 현재일이 해당 월 결제일을 이미 지났으면 **다음 월 결제일**로 자동 전환
- 월 말일 초과 방지 (31일 결제 → 2월은 28일/29일)
### 10.5 결제(Prepayment) 관리
- 월별로 복수 건의 결제 내역 관리 가능
- `items` JSON 필드로 개별 건(날짜, 금액, 설명) 저장
- `amount` 필드에는 `items`의 합계 자동 계산
- 잔여한도 = 총한도 - 사용금액 + 결제금액
---
## 11. 변경 이력
| 날짜 | 변경 내용 |
|------|----------|
| 2026-02-20 | 매월결제일 동적 계산 로직 추가 (현재일 > 결제일 → 익월 전환) |
| 2026-02-20 | 기술문서 최초 작성 |

117
docs/features/card-vehicle/README.md Normal file
View File

@@ -0,0 +1,117 @@
# 카드/차량관리 기능
## 개요
SAM 프로젝트의 카드/차량관리 모듈은 법인카드 관리, 카드 사용내역 조회, 차량 관리, 운행일지, 정비이력을 종합적으로 관리하는 시스템입니다.
바로빌 API 연동을 통한 카드거래 자동 수집, 카드별 사용금액 집계, 차량 운행/정비 기록 관리 기능을 제공합니다.
## 메뉴 구성
| 메뉴 | 경로 | 설명 | UI 기술 |
|------|------|------|---------|
| [법인카드관리](./corporate-cards.md) | `/finance/corporate-cards` | 법인카드 등록/조회, 요약 대시보드 | React 18 |
| [카드사용내역](./card-transactions.md) | `/finance/card-transactions` | 바로빌 연동 카드거래 조회 및 회계 분류 | React 18 |
| [차량목록](./corporate-vehicles.md) | `/finance/corporate-vehicles` | 법인/렌트/리스 차량 등록 관리 | React 18 |
| [차량일지](./vehicle-logs.md) | `/finance/vehicle-logs` | 차량 운행기록 관리 | React 18 |
| [정비이력](./vehicle-maintenance.md) | `/finance/vehicle-maintenance` | 차량 정비/주유/보험 등 비용 관리 | React 18 |
## 아키텍처
```
┌───────────────────────────────────────────────────────────────┐
│ 카드/차량관리 모듈 │
├──────────────────────┬────────────────────────────────────────┤
│ 카드 관리 영역 │ 차량 관리 영역 │
│ │ │
│ ┌────────────────┐ │ ┌──────────┐ ┌────────┐ ┌────────┐ │
│ │ 법인카드관리 │ │ │ 차량목록 │ │ 차량일지 │ │ 정비이력│ │
│ │ (카드 CRUD) │ │ │(차량CRUD)│ │(운행기록)│ │(비용기록)│ │
│ └───────┬────────┘ │ └────┬─────┘ └────┬───┘ └───┬────┘ │
│ │ │ │ │ │ │
│ ┌───────▼────────┐ │ └──────────────┼──────────┘ │
│ │ 카드사용내역 │ │ │ │
│ │(바로빌 연동) │ │ │ │
│ └───────┬────────┘ │ │ │
├──────────┼───────────┴──────────────────────┼─────────────────┤
│ ▼ ▼ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ 데이터베이스 │ │
│ │ corporate_cards, card_transactions, │ │
│ │ barobill_card_transactions, corporate_card_prepayments │ │
│ │ corporate_vehicles, vehicle_logs, vehicle_maintenances │ │
│ └──────────────────────────────────────────────────────────┘ │
└───────────────────────────────────────────────────────────────┘
```
## 주요 기술 스택
| 기술 | 용도 |
|------|------|
| Laravel 11 (PHP 8.3) | 백엔드 프레임워크 |
| React 18 + Babel | 클라이언트 렌더링 UI (전 페이지) |
| Tailwind CSS + Lucide | 스타일링 및 아이콘 |
| Barobill SOAP API | 카드거래 실시간 연동 |
| MySQL 8.0 | 데이터 저장 |
## 데이터 흐름
```
바로빌 SOAP API ──────────────────────────────┐
(CARD.asmx: 카드거래 자동 수집) │
▼
카드 관리: corporate_cards ← 매칭 → barobill_card_transactions
(카드번호 하이픈 제거 후 매칭)
│
├── barobill_card_transaction_splits (분개)
├── barobill_card_transaction_hides (숨김)
├── barobill_card_transaction_amount_logs (수정이력)
└── corporate_card_prepayments (선불결제)
차량 관리: corporate_vehicles
│
├── vehicle_logs (운행기록 → distance_km 합산)
└── vehicle_maintenances (정비기록 → mileage 갱신)
```
## 공통 모델/패턴
### 멀티 테넌트
모든 테이블은 `tenant_id` 기반으로 데이터를 격리합니다.
### React 18 + Babel
모든 페이지는 브라우저 트랜스파일링 방식의 React 18을 사용합니다:
- `@push('scripts')` 블록에 React/Babel/Lucide 스크립트 포함
- `@verbatim` + `<script type="text/babel">` 패턴
- HTMX 네비게이션 시 HX-Redirect 필수 (전체 페이지 리로드)
### 카드번호 매칭 로직
```
corporate_cards.card_number ←매칭→ barobill_card_transactions.card_num
(예: "9438-8309-3638-4247") (예: "9438830936384247")
→ 하이픈 제거 후 매칭: str_replace('-', '', $cardNumber)
```
## 데이터베이스 테이블 요약
### 카드 관련
| 테이블 | 역할 |
|--------|------|
| `corporate_cards` | 법인카드 정보 (카드명, 카드사, 번호, 한도 등) |
| `corporate_card_prepayments` | 월별 선불결제 금액 |
| `card_transactions` | 수동 입력 카드거래 |
| `barobill_card_transactions` | 바로빌 자동 수집 카드거래 |
| `barobill_card_transaction_splits` | 카드거래 분개 (1거래→N계정과목) |
| `barobill_card_transaction_hides` | 거래 숨김 처리 |
| `barobill_card_transaction_amount_logs` | 거래 금액 수정 이력 |
### 차량 관련
| 테이블 | 역할 |
|--------|------|
| `corporate_vehicles` | 법인/렌트/리스 차량 정보 |
| `vehicle_logs` | 차량 운행기록 (출발/도착, 거리, 용도) |
| `vehicle_maintenances` | 정비/주유/보험 등 비용 기록 |

311
docs/features/card-vehicle/card-transactions.md Normal file
View File

@@ -0,0 +1,311 @@
# 카드사용내역
## 개요
카드사용내역은 바로빌 SOAP API를 통해 카드사 거래내역을 실시간 조회하고,
회계 분류(계정과목 지정), 분개(1거래→N계정과목), 거래 숨김, 금액 수정, 수동 거래 등록 등을 지원하는 기능입니다.
- **라우트**: `GET /finance/card-transactions` → 바로빌 EcardController로 리다이렉트
- **실제 페이지**: `GET /barobill/ecard`
- **UI 기술**: React 18 + Babel (브라우저 트랜스파일링)
## 파일 구조
```
mng/
├── app/Http/Controllers/
│ ├── Barobill/
│ │ └── EcardController.php # 메인 컨트롤러 (바로빌 연동)
│ └── Finance/
│ └── CardTransactionController.php # 수동 거래내역 컨트롤러
├── app/Models/Barobill/
│ ├── CardTransaction.php # 바로빌 카드거래 모델
│ ├── CardTransactionSplit.php # 거래 분개 모델
│ ├── CardTransactionHide.php # 거래 숨김 모델
│ └── CardTransactionAmountLog.php # 금액 수정 이력 모델
├── app/Models/Finance/
│ └── CardTransaction.php # 수동 입력 거래 모델
└── resources/views/
├── barobill/ecard/
│ └── index.blade.php # 바로빌 카드거래 React 페이지
└── finance/
└── card-transactions.blade.php # 수동 거래내역 React 페이지
api/
└── database/migrations/
├── 2026_01_23_150000_create_barobill_card_transactions_table.php
├── 2026_01_23_160000_create_barobill_card_transaction_splits_table.php
├── 2026_02_05_100003_create_card_transactions_table.php
├── 2026_02_05_200100_create_barobill_card_transaction_amount_logs_table.php
└── 2026_02_05_500000_create_barobill_card_transaction_hides_table.php
```
## 라우트
### 바로빌 카드거래 (메인)
```php
// routes/web.php (barobill/ecard prefix)
GET / → index() React 페이지 렌더링
GET /cards → cards() 등록된 카드 목록
GET /transactions → transactions() 거래내역 조회 (API+DB 병합)
GET /account-codes → accountCodes() 계정과목 목록
POST /save → save() 거래 저장 (회계 분류)
POST /export → exportExcel() Excel 내보내기
GET /splits → splits() 분개 내역 조회
POST /splits → saveSplits() 분개 저장
DELETE /splits → deleteSplits() 분개 삭제
POST /manual → storeManual() 수동 거래 등록
PUT /manual/{id} → updateManual() 수동 거래 수정
DELETE /manual/{id} → destroyManual() 수동 거래 삭제
POST /hide → hideTransaction() 거래 숨김
POST /restore → restoreTransaction() 거래 숨김 해제
GET /hidden → hiddenTransactions() 숨긴 거래 목록
```
### 수동 거래내역 (보조)
```php
// routes/web.php (card-transactions prefix)
GET /list → index() 수동 거래 목록
POST /store → store() 수동 거래 등록
PUT /{id} → update() 수동 거래 수정
DELETE /{id} → destroy() 수동 거래 삭제
```
## 컨트롤러
### EcardController (바로빌 카드거래)
| 메서드 | HTTP | 설명 |
|--------|------|------|
| `index()` | GET | React 페이지 렌더링 (HX-Redirect 적용) |
| `cards()` | GET | 바로빌 등록 카드 목록 (SOAP API) |
| `transactions()` | GET | **거래내역 조회** (API + DB 병합) |
| `accountCodes()` | GET | 계정과목 목록 |
| `save()` | POST | 거래 저장 (계정과목 지정) |
| `exportExcel()` | POST | Excel 내보내기 |
| `splits()` | GET | 분개 내역 조회 |
| `saveSplits()` | POST | 분개 저장 |
| `deleteSplits()` | DELETE | 분개 삭제 |
| `storeManual()` | POST | 수동 거래 등록 |
| `updateManual()` | PUT | 수동 거래 수정 |
| `destroyManual()` | DELETE | 수동 거래 삭제 |
| `hideTransaction()` | POST | 거래 숨김 처리 |
| `restoreTransaction()` | POST | 거래 숨김 해제 |
| `hiddenTransactions()` | GET | 숨긴 거래 목록 |
### CardTransactionController (수동 거래)
| 메서드 | HTTP | 설명 |
|--------|------|------|
| `index()` | GET | 수동 거래 목록 (필터, 통계 포함) |
| `store()` | POST | 거래 등록 |
| `update()` | PUT | 거래 수정 |
| `destroy()` | DELETE | 거래 삭제 (Soft Delete) |
## 바로빌 SOAP API 연동
### 사용 SOAP 메서드
| WSDL | 메서드 | 기능 |
|------|--------|------|
| CARD.asmx | `GetRegisteredCard` | 등록된 카드 목록 조회 |
| CARD.asmx | `GetPeriodCardLog` | 기간별 카드거래 내역 조회 |
### 테넌트별 서버 모드
```
BarobillMember.server_mode → 'test' 또는 'production'
→ BarobillConfig 재로드 → SOAP 클라이언트 재초기화
```
## 핵심 로직
### 거래내역 조회 흐름 (transactions)
```
React 컴포넌트 (카드/기간 선택)
↓
GET /barobill/ecard/transactions
↓
1. BarobillMember 조회 (바로빌 인증 정보)
↓
2. 테넌트별 서버 모드 적용 (test/production)
↓
3. SOAP 호출: GetPeriodCardLog (바로빌 API)
↓
4. DB 저장된 거래와 병합 (barobill_card_transactions)
↓
5. 숨긴 거래 표시 (barobill_card_transaction_hides)
↓
6. 분개 데이터 병합 (barobill_card_transaction_splits)
↓
7. 수동 거래 병합
↓
8. 정렬 + JSON 응답
```
### 거래 고유 키 (unique_key)
```php
// CardTransaction (Barobill) 모델
return implode('|', [
$this->card_num,
$this->use_dt, // 사용일시
$this->approval_num,
$this->approval_amount,
]);
```
### 거래 금액 처리
```
approval_type = '1' → 승인 (+ 금액)
approval_type = '2' → 취소 (- 금액)
modified_supply_amount, modified_tax → 금액 수정 시 원본 대신 사용
```
### 분개 저장 흐름
```
React (분개 모달)
↓
POST /barobill/ecard/splits
{
originalUniqueKey: "카드번호|사용일시|승인번호|금액",
originalData: { cardNum, useDt, ... },
splits: [
{ amount: 50000, accountCode: "1000", accountName: "당좌예금" },
{ amount: 50000, accountCode: "2000", accountName: "미수금" }
]
}
↓
기존 분개 삭제 → 새 분개 생성 × N
```
## 모델
### CardTransaction (Barobill)
**테이블**: `barobill_card_transactions`
| 필드 | 타입 | 설명 |
|------|------|------|
| `tenant_id` | bigint | 테넌트 ID |
| `card_num` | string | 카드번호 (하이픈 없음) |
| `card_company` / `card_company_name` | string | 카드사 코드/명 |
| `use_dt` | string | 사용일시 (YYYYMMDDHHMMSS) |
| `use_date` / `use_time` | string | 사용일/시간 분리 |
| `approval_num` | string | 승인번호 |
| `approval_type` | string | 1=승인, 2=취소 |
| `approval_amount` | decimal | 승인금액 |
| `tax` / `service_charge` | decimal | 세금/봉사료 |
| `merchant_name` / `merchant_biz_num` | string | 가맹점명/사업자번호 |
| `account_code` / `account_name` | string | 계정과목 코드/명 |
| `modified_supply_amount` / `modified_tax` | decimal | 수정 공급가/세액 |
| `is_manual` | boolean | 수동 입력 여부 |
- **Unique Index**: `[tenant_id, card_num, use_dt, approval_num, approval_amount]`
### CardTransactionSplit
**테이블**: `barobill_card_transaction_splits`
| 필드 | 타입 | 설명 |
|------|------|------|
| `original_unique_key` | string(200) | 원본 거래 고유 키 |
| `split_amount` | decimal | 분개 금액 |
| `split_supply_amount` / `split_tax` | decimal | 공급가/세액 |
| `account_code` / `account_name` | string | 계정과목 |
| `deduction_type` / `evidence_name` | string | 공제구분/증빙명 |
| `sort_order` | int | 정렬 순서 |
### CardTransactionHide
**테이블**: `barobill_card_transaction_hides`
| 필드 | 타입 | 설명 |
|------|------|------|
| `original_unique_key` | string | 거래 고유 키 |
| `card_num` / `use_date` / `approval_num` | string | 원본 거래 정보 |
| `original_amount` / `merchant_name` | string | 원본 금액/가맹점 |
| `hidden_by` | bigint | 숨김 처리 사용자 |
### CardTransactionAmountLog
**테이블**: `barobill_card_transaction_amount_logs`
| 필드 | 타입 | 설명 |
|------|------|------|
| `card_transaction_id` | bigint | 카드거래 FK |
| `before_supply_amount` / `before_tax` | decimal | 수정 전 금액 |
| `after_supply_amount` / `after_tax` | decimal | 수정 후 금액 |
| `modified_by` / `modified_by_name` | string | 수정자 |
| `ip_address` | string | 수정 IP |
### CardTransaction (Finance - 수동)
**테이블**: `card_transactions`
| 필드 | 타입 | 설명 |
|------|------|------|
| `tenant_id` | bigint | 테넌트 ID |
| `card_id` | bigint | 법인카드 FK |
| `transaction_date` | date | 거래일 |
| `time` | string | 거래시간 (HH:MM) |
| `merchant` | string(200) | 가맹점명 |
| `category` | string | 카테고리 |
| `amount` | bigint | 금액 |
| `approval_no` | string | 승인번호 |
| `status` | enum | approved / cancelled |
## 뷰 구성 (React)
### card-transactions.blade.php (수동 거래)
```
┌─ 페이지 헤더 ──────────────────────
│ Excel 내보내기 | 거래 추가 버튼
│
├─ 통계 카드 (4열) ──────────────────
│ 조회 건수 | 총 사용금액 | 승인 금액 | 취소 금액
│
├─ 카테고리 사용현황 (수평 바) ──────
│ 식비 | 교통비 | 접대비 | ... (금액 순 정렬)
│
├─ 필터 영역 ────────────────────────
│ 검색 | 카드 선택 | 카테고리 | 기간 | 상태(전체/승인/취소)
│
├─ 거래 목록 (날짜별 그룹) ──────────
│ 날짜 헤더 (건수, 소계)
│ ├─ 가맹점명 + 카테고리 아이콘
│ ├─ 시간, 카드명, 카테고리라벨
│ ├─ 금액 (승인=빨강, 취소=파랑)
│ └─ 수정/삭제 버튼
│
└─ 등록/수정 모달
카드, 날짜, 시간, 가맹점명, 카테고리
금액, 승인번호, 상태, 메모
```
### 카테고리 목록
| 카테고리 | 아이콘 | 색상 |
|---------|--------|------|
| 식비 | Utensils | amber |
| 교통비 | Car | blue |
| 운영비 | Settings | gray |
| 마케팅비 | Megaphone | purple |
| 사무용품 | Paperclip | teal |
| 도서/교육 | BookOpen | indigo |
| 접대비 | Wine | rose |
| 장비구매 | Monitor | cyan |
| 기타 | MoreHorizontal | gray |
## HTMX 호환성
- React 기반 페이지이므로 **HX-Redirect 필요**
- `@push('scripts')` 블록에 React/Babel 스크립트 포함
- HTMX 네비게이션 시 전체 페이지 리로드 필수

222
docs/features/card-vehicle/corporate-cards.md Normal file
View File

@@ -0,0 +1,222 @@
# 법인카드관리
## 개요
법인카드관리는 회사의 법인카드(신용/체크)를 등록하고 관리하는 기능입니다.
카드 CRUD, 결제일 휴일 조정, 바로빌 기반 사용금액 집계, 선불결제 관리 등을 지원합니다.
- **라우트**: `GET /finance/corporate-cards`
- **라우트 이름**: `finance.corporate-cards`
- **UI 기술**: React 18 + Babel (브라우저 트랜스파일링)
## 파일 구조
```
mng/
├── app/Http/Controllers/Finance/
│ └── CorporateCardController.php # 메인 컨트롤러 (7개 메서드)
├── app/Models/Finance/
│ ├── CorporateCard.php # 법인카드 모델
│ └── CorporateCardPrepayment.php # 선불결제 모델
├── app/Models/Barobill/
│ ├── CardTransaction.php # 바로빌 카드거래 모델
│ └── CardTransactionHide.php # 거래 숨김 모델
├── app/Models/System/
│ └── Holiday.php # 휴일 모델
└── resources/views/finance/
└── corporate-cards.blade.php # React 기반 단일 페이지
api/
└── database/migrations/
├── 2026_01_30_180000_create_corporate_cards_table.php
└── 2026_02_11_100000_create_corporate_card_prepayments_table.php
```
## 라우트
```php
// routes/web.php (finance prefix 그룹 내)
Route::get('/corporate-cards', fn() => ...)->name('corporate-cards');
// API 라우트 (corporate-cards prefix)
GET /list → index() 카드 목록 조회
GET /summary → summary() 요약 데이터 (결제일, 사용금액 등)
POST /prepayment → updatePrepayment() 선불결제 수정
POST /store → store() 카드 등록
PUT /{id} → update() 카드 수정
POST /{id}/deactivate → deactivate() 카드 비활성화
DELETE /{id} → destroy() 카드 영구삭제
```
## 컨트롤러
### CorporateCardController
| 메서드 | HTTP | 설명 |
|--------|------|------|
| `index()` | GET | 카드 목록 JSON 반환 |
| `store()` | POST | 카드 등록 |
| `update()` | PUT | 카드 수정 |
| `deactivate()` | POST | 비활성화 (status → inactive) |
| `destroy()` | DELETE | 영구삭제 (forceDelete) |
| `summary()` | GET | **요약 데이터** (결제일, 사용금액, 선불결제) |
| `updatePrepayment()` | POST | 선불결제 금액 수정 (upsert) |
### summary() 응답 구조
```json
{
"success": true,
"data": {
"paymentDate": "2026-02-19",
"paymentDay": 15,
"originalDate": "2026-02-15",
"isAdjusted": true,
"billingPeriod": { "start": "2026-01-01", "end": "2026-02-19" },
"billingUsage": 3500000,
"cardUsages": { "9438830936384247": 1200000, "1234567890123456": 2300000 },
"prepaidAmount": 500000,
"prepaidMemo": "2월 선결제"
}
}
```
## 핵심 로직
### 휴일 조정 결제일 계산 (getAdjustedPaymentDate)
```
당월 payment_day (예: 15일)
↓
Carbon 날짜 생성
↓
holidays 테이블에서 해당 기간 휴일 조회
↓
토/일/공휴일이면 다음 날로 반복 이동
↓
영업일 결제일 반환 (예: 15일→토→17일(월))
```
### 사용금액 계산 (calculateBillingUsage)
```
청구기간: 전월 1일 ~ 당월 결제일(휴일조정)
↓
corporate_cards에서 활성 카드번호 수집
↓
카드번호 정규화 (하이픈 제거)
↓
barobill_card_transactions 조회 (use_date 범위)
↓
숨긴 거래 제외 (barobill_card_transaction_hides)
↓
approval_type별 합산:
- '1' (승인): + approval_amount
- '2' (취소): - approval_amount
↓
총 사용금액 반환
```
### 잔여 한도 계산
```
잔여 한도 = 총 한도 - 사용금액 + 선불결제
```
## 모델
### CorporateCard
**테이블**: `corporate_cards`
| 필드 | 타입 | 설명 |
|------|------|------|
| `tenant_id` | bigint | 테넌트 ID |
| `card_name` | string(100) | 카드명 (예: "업무용 법인카드") |
| `card_company` | string(50) | 카드사 (삼성, 현대 등) |
| `card_number` | string(30) | 카드번호 (하이픈 포함) |
| `card_type` | enum | credit / debit |
| `payment_day` | tinyint | 결제일 (기본: 15) |
| `credit_limit` | decimal(15,2) | 사용한도 |
| `current_usage` | decimal(15,2) | 현재 사용액 |
| `card_holder_name` | string(100) | 이용자명 (법인 명의) |
| `actual_user` | string(100) | 실사용자 |
| `expiry_date` | string(10) | 유효기간 (YY/MM) |
| `cvc` | string(10) | CVC |
| `status` | enum | active / inactive |
| `memo` | text | 메모 |
#### 주요 Scope
```php
->active() // status = 'active'
->forTenant($id) // tenant_id 필터
```
### CorporateCardPrepayment
**테이블**: `corporate_card_prepayments`
| 필드 | 타입 | 설명 |
|------|------|------|
| `tenant_id` | bigint | 테넌트 ID |
| `year_month` | string(7) | "2026-02" 형식 |
| `amount` | decimal(15,0) | 선불결제 금액 |
| `memo` | string(200) | 메모 |
- Unique: `[tenant_id, year_month]`
- `getOrCreate(tenantId, yearMonth)`: 조회 또는 기본값(0) 생성
## 뷰 구성 (React)
### corporate-cards.blade.php
```
┌─ 페이지 헤더 ──────────────────────
│ 제목: "법인카드 등록/조회"
│ 버튼: "카드 등록" (보라색)
│
├─ 요약 카드 (2열 / lg:6열) ─────────
│ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐
│ │등록카드│ │총 한도│ │매월 │ │사용 │ │선불 │ │잔여 │
│ │ │ │ │ │결제일 │ │금액 │ │결제 │ │한도 │
│ │3장 │ │50백만│ │2/19 │ │35백만│ │5백만 │ │20백만│
│ │활성2 │ │신용 │ │(수) │ │1/1~ │ │[수정]│ │한도- │
│ │ │ │기준 │ │15→조정│ │2/19 │ │ │ │사용+ │
│ │ │ │ │ │ │ │기준 │ │ │ │선결제│
│ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘
│
├─ 검색 및 필터 ─────────────────────
│ 검색창 | 전체 | 활성 | 비활성
│
├─ 카드 목록 테이블 ─────────────────
│ 카드명(카드사) | 카드번호 | 실사용자 | 사용현황(진행바) | 상태
│ └─ 신용: 사용률 % + 프로그레스 바
│ └─ 체크: 사용금액 표시
│
├─ 등록/수정 모달 ───────────────────
│ 카드명, 카드사, 카드종류, 카드번호, 이용자명
│ 유효기간, CVC, 상태, 실사용자
│ 결제일(신용만), 사용한도(신용만), 메모
│ [비활성화] [영구삭제] [취소] [등록/저장]
│
└─ 선불결제 수정 모달 ───────────────
금액 입력 (3자리 콤마), 메모 (선택)
[취소] [저장]
```
### React 주요 기능
| 기능 | 설명 |
|------|------|
| 요약 카드 6개 | 등록카드, 총한도, 매월결제일, 사용금액, 선불결제, 잔여한도 |
| 카드별 사용률 | billingUsage 기준 프로그레스 바 표시 |
| 선불결제 인라인 수정 | 수정 버튼 → 모달 → 금액/메모 입력 → 즉시 반영 |
| 상태 필터 | 전체 / 활성 / 비활성 |
| 카드 검색 | 카드명, 카드사, 이용자명, 실사용자 검색 |
## HTMX 호환성
- React 기반 페이지이므로 **HX-Redirect 필요**
- `@push('scripts')` 블록에 React/Babel 스크립트 포함
- HTMX 네비게이션 시 전체 페이지 리로드 필수

163
docs/features/card-vehicle/corporate-vehicles.md Normal file
View File

@@ -0,0 +1,163 @@
# 차량목록
## 개요
차량목록은 회사의 법인차량(법인/렌트/리스)을 등록하고 관리하는 기능입니다.
소유형태별 차량 등록, 총 주행거리 자동 계산, 차량 상태 관리 등을 지원합니다.
- **라우트**: `GET /finance/corporate-vehicles`
- **UI 기술**: React 18 + Babel (브라우저 트랜스파일링)
## 파일 구조
```
mng/
├── app/Http/Controllers/Finance/
│ └── CorporateVehicleController.php # 메인 컨트롤러 (5개 메서드)
├── app/Models/
│ └── CorporateVehicle.php # 차량 모델
└── resources/views/finance/
└── corporate-vehicles.blade.php # React 기반 단일 페이지
api/
└── database/migrations/
└── 2026_02_02_220000_create_corporate_vehicles_table.php
```
## 라우트
```php
// routes/web.php (finance prefix 그룹 내)
GET /corporate-vehicles → index() 페이지 렌더링
GET /corporate-vehicles/list → list() 차량 목록 (JSON)
POST /corporate-vehicles → store() 차량 등록
PUT /corporate-vehicles/{id} → update() 차량 수정
DELETE /corporate-vehicles/{id} → destroy() 차량 삭제
```
## 컨트롤러
### CorporateVehicleController
| 메서드 | HTTP | 설명 |
|--------|------|------|
| `index()` | GET | React 페이지 렌더링 (HX-Redirect 적용) |
| `list()` | GET | 차량 목록 (필터 + 총 주행거리 계산) |
| `store()` | POST | 차량 등록 |
| `update()` | PUT | 차량 수정 |
| `destroy()` | DELETE | 차량 삭제 |
### list() 핵심 로직
```
필터 파라미터: ownership_type, vehicle_type, status, search
↓
CorporateVehicle::where(tenant_id, ...)
↓
각 차량별 총 주행거리 계산:
total_mileage = initial_mileage + SUM(vehicle_logs.distance_km)
↓
JSON 응답
```
## 모델
### CorporateVehicle
**테이블**: `corporate_vehicles`
| 필드 | 타입 | 설명 |
|------|------|------|
| `tenant_id` | bigint | 테넌트 ID |
| `plate_number` | string(20) | 차량번호 |
| `model` | string(100) | 차량 모델명 |
| `vehicle_type` | string(20) | 차종 |
| `ownership_type` | enum | **corporate** / rent / lease |
| `year` | year | 연식 |
| `driver` | string(50) | 주 운전자 |
| `status` | enum | **active** / maintenance / disposed |
| `mileage` | int | 현재 주행거리 (정비 기준) |
| `memo` | text | 메모 |
#### 법인 전용 필드
| 필드 | 타입 | 설명 |
|------|------|------|
| `purchase_date` | date | 취득일자 |
| `purchase_price` | int | 취득가액 |
#### 렌트/리스 전용 필드
| 필드 | 타입 | 설명 |
|------|------|------|
| `contract_date` | date | 계약일자 |
| `rent_company` | string | 렌트/리스사 |
| `rent_company_tel` | string | 연락처 |
| `rent_period` | string | 계약기간 |
| `agreed_mileage` | int | 약정주행거리 |
| `vehicle_price` | int | 차량가액 |
| `residual_value` | int | 잔존가치 |
| `deposit` | int | 보증금 |
| `monthly_rent` | int | 월 렌트료 |
| `monthly_rent_tax` | int | 부가세 |
| `insurance_company` | string | 보험사 |
| `insurance_company_tel` | string | 보험사 연락처 |
#### Traits / Scope
- `SoftDeletes` 적용
- Casts: year, mileage, purchase_price, vehicle_price, residual_value, deposit, monthly_rent, monthly_rent_tax → integer
## 뷰 구성 (React)
### corporate-vehicles.blade.php
```
┌─ 페이지 헤더 ──────────────────────
│ 제목: "차량목록"
│ 검색 | Excel 다운로드 | 차량 등록 버튼
│
├─ 요약 카드 (4열) ──────────────────
│ 총 차량 | 법인 취득가 | 월 렌트/리스비 | 총 주행거리
│
├─ 필터 바 ──────────────────────────
│ 소유형태: 전체 | 법인 | 렌트 | 리스
│ 상태: 전체 | 운행중 | 정비중 | 처분
│
├─ 차량 목록 테이블 (12열 그리드) ──
│ 차량번호 | 차종/모델 | 소유형태 | 운전자 | 주행거리 | 상태
│ └─ 소유형태: 법인(보라), 렌트(파랑), 리스(초록) 배지
│ └─ 상태: 운행중(초록), 정비중(노랑), 처분(빨강) 배지
│
├─ 등록/수정 모달 ───────────────────
│ 차량번호, 모델명, 차종, 소유형태
│ 연식, 주 운전자, 상태, 메모
│ ─────────────────────────
│ [법인일 때] 취득일자, 취득가액
│ [렌트/리스일 때] 계약일, 렌트사, 계약기간,
│ 약정주행, 차량가액, 잔존가치, 보증금,
│ 월렌트료, 부가세, 보험사
│ ─────────────────────────
│ [삭제] [취소] [등록/저장]
│
└─ 비어있을 때: "등록된 차량이 없습니다" 안내
```
## 데이터 흐름
```
CorporateVehicle (1) ← (N) VehicleLog (총 주행거리 합산)
← (N) VehicleMaintenance (주행거리 갱신)
```
### 주행거리 계산 방식
```
총 주행거리 = CorporateVehicle.mileage (정비 시 갱신 기준값)
+ SUM(vehicle_logs.distance_km) (운행일지 거리 합계)
```
## HTMX 호환성
- React 기반 페이지이므로 **HX-Redirect 필요**
- `@push('scripts')` 블록에 React/Babel 스크립트 포함

179
docs/features/card-vehicle/vehicle-logs.md Normal file
View File

@@ -0,0 +1,179 @@
# 차량일지
## 개요
차량일지는 법인차량의 운행기록을 관리하는 기능입니다.
출발/도착지, 운행 거리, 용도(출퇴근/업무/비업무), 월별 통계 등을 지원합니다.
- **라우트**: `GET /finance/vehicle-logs`
- **UI 기술**: React 18 + Babel (브라우저 트랜스파일링)
## 파일 구조
```
mng/
├── app/Http/Controllers/Finance/
│ └── VehicleLogController.php # 메인 컨트롤러 (7개 메서드)
├── app/Models/
│ └── VehicleLog.php # 운행기록 모델
└── resources/views/finance/
└── vehicle-logs.blade.php # React 기반 단일 페이지
api/
└── database/migrations/
├── 2026_02_03_100000_create_vehicle_logs_table.php
└── 2026_02_03_133000_modify_vehicle_logs_trip_type_enum.php
```
## 라우트
```php
// routes/web.php (finance prefix 그룹 내)
GET /vehicle-logs → index() 페이지 렌더링
GET /vehicle-logs/vehicles → vehicles() 차량 목록 (드롭다운용)
GET /vehicle-logs/list → list() 운행기록 목록 (JSON)
GET /vehicle-logs/summary → summary() 월별 통계
POST /vehicle-logs → store() 기록 등록
PUT /vehicle-logs/{id} → update() 기록 수정
DELETE /vehicle-logs/{id} → destroy() 기록 삭제
```
## 컨트롤러
### VehicleLogController
| 메서드 | HTTP | 설명 |
|--------|------|------|
| `index()` | GET | React 페이지 렌더링 (HX-Redirect 적용) |
| `vehicles()` | GET | 전체 차량 목록 (드롭다운 선택용) |
| `list()` | GET | 운행기록 목록 (필터, 검색) |
| `summary()` | GET | 월별 용도별 통계 (건수, 거리) |
| `store()` | POST | 운행기록 등록 |
| `update()` | PUT | 운행기록 수정 |
| `destroy()` | DELETE | 운행기록 삭제 |
### list() 필터 파라미터
| 파라미터 | 설명 |
|---------|------|
| `vehicle_id` | 차량 ID |
| `year` / `month` | 연/월 |
| `trip_type` | 운행 용도 |
| `search` | 검색 (운전자, 부서, 출발지, 도착지, 비고) |
### summary() 응답 구조
```json
{
"success": true,
"data": [
{ "trip_type": "business", "count": 15, "total_distance": 450 },
{ "trip_type": "commute_to", "count": 22, "total_distance": 330 },
{ "trip_type": "commute_from", "count": 22, "total_distance": 330 },
{ "trip_type": "personal", "count": 3, "total_distance": 45 }
]
}
```
## 모델
### VehicleLog
**테이블**: `vehicle_logs`
| 필드 | 타입 | 설명 |
|------|------|------|
| `tenant_id` | bigint | 테넌트 ID |
| `vehicle_id` | bigint | 차량 FK (corporate_vehicles) |
| `log_date` | date | 운행일 |
| `department` | string(50) | 부서 |
| `driver_name` | string(50) | 운전자명 |
| `trip_type` | enum | 운행 용도 (아래 참조) |
| `departure_type` | string | 출발지 유형 |
| `departure_name` | string | 출발지명 |
| `departure_address` | string | 출발지 주소 |
| `arrival_type` | string | 도착지 유형 |
| `arrival_name` | string | 도착지명 |
| `arrival_address` | string | 도착지 주소 |
| `distance_km` | int | 운행거리 (km) |
| `note` | string(200) | 비고 |
#### 운행 용도 (trip_type)
| 값 | 설명 |
|----|------|
| `commute_to` | 출근용 |
| `commute_from` | 퇴근용 |
| `business` | 업무용 |
| `personal` | 비업무 |
| `commute_round` | 출퇴근 왕복 |
| `business_round` | 업무용 왕복 |
| `personal_round` | 비업무 왕복 |
#### 위치 유형 (departure_type / arrival_type)
| 값 | 설명 |
|----|------|
| `home` | 자택 |
| `office` | 회사 |
| `client` | 거래처 |
| `other` | 기타 |
#### Relationships
```php
$log->vehicle // BelongsTo CorporateVehicle
$log->tenant // BelongsTo Tenant
```
#### Static 메서드
```php
VehicleLog::getTripTypes() // 용도 라벨 배열
VehicleLog::getLocationTypes() // 위치 유형 라벨 배열
VehicleLog::getNoteOptions() // 미리 정의된 비고 옵션
```
## 뷰 구성 (React)
### vehicle-logs.blade.php
```
┌─ 페이지 헤더 ──────────────────────
│ 차량 선택 드롭다운 (현재 주행거리 표시)
│ 연/월 선택 | Excel 다운로드 | 기록 추가 버튼
│
├─ 용도별 통계 카드 ─────────────────
│ 출근 | 퇴근 | 업무 | 비업무
│ 건수 + 총 거리(km)
│
├─ 운행기록 테이블 ──────────────────
│ 날짜 | 차량 | 부서/이름 | 용도 | 출발지 | 도착지 | 거리 | 비고
│ └─ 용도: 출근(초록), 퇴근(파랑), 업무(보라), 비업무(회색) 배지
│ └─ 복사 버튼 (이전 기록 복제)
│ └─ 출발↔도착 교환 버튼 (trip_type도 자동 전환)
│
├─ 등록/수정 모달 ───────────────────
│ 차량 선택, 날짜, 부서, 운전자, 용도
│ 출발지: 유형 + 이름 + 주소
│ 도착지: 유형 + 이름 + 주소
│ 운행거리(km)
│ 비고: 미리 정의된 옵션 버튼 + 자유 입력
│ [삭제] [취소] [등록/저장]
│
└─ 비어있을 때: 안내 메시지
```
### 특수 기능
| 기능 | 설명 |
|------|------|
| 기록 복사 | 이전 운행기록을 새 날짜로 복제 |
| 출발↔도착 교환 | 출발지와 도착지를 스왑, trip_type도 자동 전환 (commute_to ↔ commute_from) |
| 미리 정의 비고 | 버튼 클릭으로 빠른 비고 입력 + 자유 텍스트 |
| 용도별 통계 | 월별 용도별 건수 및 총 거리 집계 |
## HTMX 호환성
- React 기반 페이지이므로 **HX-Redirect 필요**
- `@push('scripts')` 블록에 React/Babel 스크립트 포함

203
docs/features/card-vehicle/vehicle-maintenance.md Normal file
View File

@@ -0,0 +1,203 @@
# 정비이력
## 개요
정비이력은 법인차량의 정비, 주유, 보험, 세차, 주차, 통행료 등 비용을 기록하고 관리하는 기능입니다.
카테고리별 비용 집계, 주행거리 자동 갱신, 기간별 필터링 등을 지원합니다.
- **라우트**: `GET /finance/vehicle-maintenance`
- **UI 기술**: React 18 + Babel (브라우저 트랜스파일링)
## 파일 구조
```
mng/
├── app/Http/Controllers/Finance/
│ └── VehicleMaintenanceController.php # 메인 컨트롤러 (6개 메서드)
├── app/Models/
│ └── VehicleMaintenance.php # 정비이력 모델
└── resources/views/finance/
└── vehicle-maintenance.blade.php # React 기반 단일 페이지
api/
└── database/migrations/
└── 2026_02_03_195000_create_vehicle_maintenances_table.php
```
## 라우트
```php
// routes/web.php (finance prefix 그룹 내)
GET /vehicle-maintenance → index() 페이지 렌더링
GET /vehicle-maintenance/vehicles → vehicles() 차량 목록 (드롭다운용)
GET /vehicle-maintenance/list → list() 정비이력 목록 (JSON)
POST /vehicle-maintenance → store() 정비 등록
PUT /vehicle-maintenance/{id} → update() 정비 수정
DELETE /vehicle-maintenance/{id} → destroy() 정비 삭제
```
## 컨트롤러
### VehicleMaintenanceController
| 메서드 | HTTP | 설명 |
|--------|------|------|
| `index()` | GET | React 페이지 렌더링 (HX-Redirect 적용) |
| `vehicles()` | GET | 전체 차량 목록 (드롭다운 선택용) |
| `list()` | GET | 정비이력 목록 (필터, 검색, 차량 관계 포함) |
| `store()` | POST | 정비 등록 + **차량 주행거리 갱신** |
| `update()` | PUT | 정비 수정 + **차량 주행거리 갱신** |
| `destroy()` | DELETE | 정비 삭제 |
### list() 필터 파라미터
| 파라미터 | 설명 |
|---------|------|
| `vehicle_id` | 차량 ID |
| `category` | 카테고리 (주유, 정비, 보험 등) |
| `start_date` / `end_date` | 기간 (기본: 최근 3개월) |
| `search` | 검색 (설명, 업체명, 메모) |
### 주행거리 자동 갱신
```php
// store() / update() 에서
if ($request->mileage) {
$vehicle = CorporateVehicle::find($request->vehicle_id);
$vehicle->update(['mileage' => $request->mileage]);
}
```
정비 등록/수정 시 입력한 주행거리가 해당 차량의 기준 주행거리(mileage)를 갱신합니다.
## 모델
### VehicleMaintenance
**테이블**: `vehicle_maintenances`
| 필드 | 타입 | 설명 |
|------|------|------|
| `tenant_id` | bigint | 테넌트 ID |
| `vehicle_id` | bigint | 차량 FK (corporate_vehicles) |
| `date` | date | 정비일 |
| `category` | string(20) | 카테고리 |
| `description` | string(200) | 설명 |
| `amount` | bigint | 금액 |
| `mileage` | int | 정비 시 주행거리 |
| `vendor` | string(100) | 업체명 |
| `memo` | text | 메모 |
#### 카테고리 목록
| 카테고리 | 설명 | 아이콘/색상 |
|---------|------|------------|
| `주유` | 연료비 | Fuel / amber |
| `정비` | 차량 정비/수리 | Wrench / blue |
| `보험` | 자동차 보험료 | Shield / emerald |
| `세차` | 세차 비용 | Droplets / cyan |
| `주차` | 주차 비용 | ParkingCircle / purple |
| `통행료` | 고속도로 등 통행료 | Route / orange |
| `검사` | 정기검사/점검 | ClipboardCheck / indigo |
| `기타` | 기타 비용 | MoreHorizontal / gray |
#### Relationships
```php
$maintenance->vehicle // BelongsTo CorporateVehicle
$maintenance->tenant // BelongsTo Tenant
```
#### Static 메서드
```php
VehicleMaintenance::getCategories()
// ['주유', '정비', '보험', '세차', '주차', '통행료', '검사', '기타']
```
## 뷰 구성 (React)
### vehicle-maintenance.blade.php
```
┌─ 페이지 헤더 ──────────────────────
│ 제목: "정비이력"
│ 새로고침 | Excel 다운로드 | 정비 등록 버튼
│
├─ 요약 카드 (4열) ──────────────────
│ 총 정비비용 | 주유비 | 정비비 | 기타비용
│ (기간 내 합산)
│
├─ 필터 영역 ────────────────────────
│ 기간: 시작일 ~ 종료일 (기본: 최근 3개월)
│ 카테고리: 전체 | 주유 | 정비 | 보험 | 세차 | 주차 | 통행료 | 검사 | 기타
│ 차량: 드롭다운 선택
│ 검색: 설명, 업체명 검색
│
├─ 정비이력 테이블 ──────────────────
│ 날짜 | 차량 | 카테고리 | 설명 | 금액 | 주행거리 | 작업
│ └─ 카테고리: 컬러 배지 (카테고리별 고유 색상)
│ └─ 금액: 원 단위 포맷
│ └─ 작업: 수정/삭제 버튼
│
├─ 등록/수정 모달 ───────────────────
│ 차량 선택, 날짜, 카테고리
│ 설명, 금액, 주행거리, 업체명, 메모
│ [삭제] [취소] [등록/저장]
│
└─ 비어있을 때: 안내 메시지
```
## 핵심 로직
### 비용 집계
```
요약 카드 계산:
총 정비비용 = 조회 기간 내 모든 정비 금액 합계
주유비 = category === '주유' 인 금액 합계
정비비 = category === '정비' 인 금액 합계
기타비용 = 나머지 카테고리 금액 합계
```
### 차량 주행거리 연동
```
정비 등록/수정 시 mileage 입력
↓
해당 차량(corporate_vehicles)의 mileage 필드 갱신
↓
차량목록에서 총 주행거리 재계산:
total_mileage = mileage + SUM(vehicle_logs.distance_km)
```
## 데이터베이스 스키마
### vehicle_maintenances
```sql
CREATE TABLE vehicle_maintenances (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
tenant_id BIGINT NOT NULL,
vehicle_id BIGINT NOT NULL,
date DATE NOT NULL,
category VARCHAR(20) NOT NULL,
description VARCHAR(200),
amount BIGINT UNSIGNED DEFAULT 0,
mileage INT UNSIGNED,
vendor VARCHAR(100),
memo TEXT,
created_at TIMESTAMP,
updated_at TIMESTAMP,
deleted_at TIMESTAMP,
INDEX (tenant_id, vehicle_id, date),
INDEX (tenant_id, category),
FOREIGN KEY (tenant_id) REFERENCES tenants(id) ON DELETE CASCADE,
FOREIGN KEY (vehicle_id) REFERENCES corporate_vehicles(id) ON DELETE CASCADE
);
```
## HTMX 호환성
- React 기반 페이지이므로 **HX-Redirect 필요**
- `@push('scripts')` 블록에 React/Babel 스크립트 포함

81
docs/features/crm/README.md Normal file
View File

@@ -0,0 +1,81 @@
# 고객/거래처/채권관리 기능
## 개요
SAM 프로젝트의 고객/거래처/채권관리 모듈은 거래처 및 고객사 정보 관리, 미수금/미지급금 채권·채무 추적,
환불/해지 요청 처리를 종합적으로 관리하는 시스템입니다.
OCR 기반 명함 인식, 부분 수금/지급 처리, 승인 워크플로우를 지원합니다.
## 메뉴 구성
| 메뉴 | 경로 | 설명 | UI 기술 |
|------|------|------|---------|
| [거래처관리](./trading-partners.md) | `/finance/partners` | 거래처(업체/프리랜서) 등록 관리 | React 18 |
| [고객사관리](./customers.md) | `/finance/customers` | 고객사 정보 및 등급 관리 | React 18 |
| [미수금관리](./receivables.md) | `/finance/receivables` | 채권 현황 및 수금 처리 | React 18 |
| [미지급금관리](./payables.md) | `/finance/payables` | 채무 현황 및 지급 처리 | React 18 |
| [환불/해지관리](./refunds.md) | `/finance/refunds` | 환불/해지 요청 및 승인 처리 | React 18 |
## 아키텍처
```
┌───────────────────────────────────────────────────────────────┐
│ 고객/거래처/채권관리 모듈 │
├───────────┬───────────┬───────────┬───────────┬───────────────┤
│ 거래처관리 │ 고객사관리 │ 미수금관리 │ 미지급금관리│ 환불/해지관리 │
│(업체/프리) │(등급관리) │(채권추적) │(채무추적) │(요청/승인) │
│ OCR인식 │ VIP~Brz │ 수금처리 │ 지급처리 │ 워크플로우 │
└─────┬─────┴─────┬─────┴─────┬─────┴─────┬─────┴───────┬──────┘
│ │ │ │ │
▼ ▼ ▼ ▼ ▼
┌───────────────────────────────────────────────────────────────┐
│ 데이터베이스 │
│ trading_partners, customers, │
│ receivables, payables, refunds │
└───────────────────────────────────────────────────────────────┘
```
## 주요 기술 스택
| 기술 | 용도 |
|------|------|
| Laravel 11 (PHP 8.3) | 백엔드 프레임워크 |
| React 18 + Babel | 클라이언트 렌더링 UI (전 페이지) |
| Tailwind CSS + Lucide | 스타일링 및 아이콘 |
| OCR (Claude Vision) | 명함 인식 (거래처관리) |
| MySQL 8.0 | 데이터 저장 |
## 공통 패턴
### 멀티 테넌트
모든 테이블은 `tenant_id` 기반으로 데이터를 격리합니다.
### 부분 수금/지급
미수금과 미지급금은 부분 처리를 지원합니다:
```
수금/지급액 입력 → collected/paid_amount 누적
→ 전액 수금/지급: collected/paid 상태로 변경
→ 부분 수금/지급: partial 상태로 변경
```
### 상태 관리 비교
| 기능 | 상태값 |
|------|--------|
| 거래처 | active / inactive |
| 고객사 | active / inactive |
| 미수금 | outstanding → partial → collected / overdue |
| 미지급금 | unpaid → partial → paid / overdue |
| 환불/해지 | pending → approved → completed / rejected |
## 데이터베이스 테이블 요약
| 테이블 | 역할 |
|--------|------|
| `trading_partners` | 거래처 정보 (업체/프리랜서, 사업자번호, 계좌 등) |
| `customers` | 고객사 정보 (등급, 업종, 담당자 등) |
| `receivables` | 미수금 (고객별 인보이스, 수금액, 연체 추적) |
| `payables` | 미지급금 (업체별 인보이스, 지급액, 세금계산서) |
| `refunds` | 환불/해지 요청 (타입, 사유, 처리상태) |

135
docs/features/crm/customers.md Normal file
View File

@@ -0,0 +1,135 @@
# 고객사관리
## 개요
고객사관리는 회사의 고객사 정보를 등급별로 관리하는 기능입니다.
고객사 CRUD, 등급 분류(VIP/Gold/Silver/Bronze), 업종별 관리, 담당자 정보를 지원합니다.
- **라우트**: `GET /finance/customers`
- **라우트 이름**: `finance.customers`
- **UI 기술**: React 18 + Babel (브라우저 트랜스파일링)
## 파일 구조
```
mng/
├── app/Http/Controllers/Finance/
│ └── CustomerController.php # 메인 컨트롤러 (4개 메서드)
├── app/Models/Finance/
│ └── Customer.php # 고객사 모델
└── resources/views/finance/
└── customers.blade.php # React 기반 단일 페이지
api/
└── database/migrations/
└── 2026_02_04_230001_create_customers_table.php
```
## 라우트
```php
// routes/web.php (finance prefix 그룹 내)
GET /customers → 페이지 렌더링 (HX-Redirect)
// API 라우트 (customers prefix)
GET /customers/list → index() 고객사 목록 (JSON)
POST /customers/store → store() 고객사 등록
PUT /customers/{id} → update() 고객사 수정
DELETE /customers/{id} → destroy() 고객사 삭제
```
## 컨트롤러
### CustomerController
| 메서드 | HTTP | 설명 |
|--------|------|------|
| `index()` | GET | 고객사 목록 (검색, 등급/상태 필터) |
| `store()` | POST | 고객사 등록 (name 필수) |
| `update()` | PUT | 고객사 수정 |
| `destroy()` | DELETE | 고객사 삭제 (Soft Delete) |
### index() 응답 구조
```json
{
"success": true,
"data": [...],
"stats": {
"total": 100,
"active": 85,
"vip": 10,
"inactive": 15
}
}
```
## 모델
### Customer
**테이블**: `customers`
| 필드 | 타입 | 설명 |
|------|------|------|
| `tenant_id` | bigint | 테넌트 ID |
| `name` | string(100) | 고객사명 |
| `biz_no` | string(20) | 사업자번호 |
| `ceo` | string(50) | 대표자명 |
| `industry` | string(50) | 업종 |
| `grade` | string(20) | 등급 (기본: Silver) |
| `contact` | string(50) | 연락처 |
| `email` | string(100) | 이메일 |
| `address` | string(200) | 주소 |
| `manager` | string(50) | 담당자명 |
| `manager_phone` | string(20) | 담당자 연락처 |
| `status` | string(20) | active / inactive |
| `memo` | text | 메모 |
- SoftDeletes 적용
- Scope: `forTenant($tenantId)`
#### 등급 (grade)
| 등급 | 설명 |
|------|------|
| VIP | 최우수 고객 |
| Gold | 우수 고객 |
| Silver | 일반 고객 (기본값) |
| Bronze | 신규/소규모 고객 |
#### 업종 목록
IT/소프트웨어, 제조업, 서비스업, 유통업, 금융업, 기타
## 뷰 구성 (React)
### customers.blade.php
```
┌─ 페이지 헤더 ──────────────────────
│ 제목: "고객사관리"
│ [CSV 내보내기] [등록] 버튼
│
├─ 통계 카드 (4열) ──────────────────
│ 전체 | 활성 | VIP | 비활성
│
├─ 필터 영역 ────────────────────────
│ 검색 (고객사명, 대표자, 담당자) | 등급 필터 | 상태 필터
│
├─ 고객사 목록 테이블 ───────────────
│ 고객사명 | 사업자번호 | 대표자 | 업종 | 등급 | 연락처 | 이메일 | 담당자 | 상태
│ └─ 등급: VIP(보라), Gold(노랑), Silver(회색), Bronze(갈색) 배지
│
├─ 등록/수정 모달 ───────────────────
│ 고객사명, 사업자번호, 대표자명
│ 업종, 등급, 연락처, 이메일, 주소
│ 담당자, 담당자 연락처, 상태, 메모
│
└─ 비어있을 때: 안내 메시지
```
## HTMX 호환성
- React 기반 페이지이므로 **HX-Redirect 필요**
- `@push('scripts')` 블록에 React/Babel 스크립트 포함

150
docs/features/crm/payables.md Normal file
View File

@@ -0,0 +1,150 @@
# 미지급금관리
## 개요
미지급금관리는 공급업체별 채무 현황을 추적하고 지급 처리를 관리하는 기능입니다.
인보이스별 미지급금 등록, 부분/전액 지급 처리, 세금계산서 발행 추적, 연체 관리를 지원합니다.
- **라우트**: `GET /finance/payables`
- **UI 기술**: React 18 + Babel (브라우저 트랜스파일링)
## 파일 구조
```
mng/
├── app/Http/Controllers/Finance/
│ └── PayableController.php # 메인 컨트롤러 (5개 메서드)
├── app/Models/Finance/
│ └── Payable.php # 미지급금 모델
└── resources/views/finance/
└── payables.blade.php # React 기반 단일 페이지
api/
└── database/migrations/
├── 2026_02_04_222513_create_payables_table.php
└── 2026_02_05_600000_add_tax_type_and_payable_fields.php
```
## 라우트
```php
// routes/web.php (finance prefix 그룹 내)
GET /payables → 페이지 렌더링 (HX-Redirect)
GET /payables/list → index() 목록 + 통계 (JSON)
POST /payables/store → store() 등록
PUT /payables/{id} → update() 수정
POST /payables/{id}/pay → pay() 지급 처리
DELETE /payables/{id} → destroy() 삭제
```
## 컨트롤러
### PayableController
| 메서드 | HTTP | 설명 |
|--------|------|------|
| `index()` | GET | 미지급금 목록 (검색, 상태/카테고리 필터) |
| `store()` | POST | 미지급금 등록 |
| `update()` | PUT | 미지급금 수정 |
| `pay()` | POST | **지급 처리** (지급액 입력 → 상태 자동 변경) |
| `destroy()` | DELETE | 삭제 (Soft Delete) |
### pay() 지급 처리 로직
```
지급액 입력
↓
paid_amount += 지급액
↓
paid_amount >= amount ?
→ YES: status = 'paid' (전액 지급)
→ NO: status = 'partial' (부분 지급)
```
### index() 응답 구조
```json
{
"success": true,
"data": [...],
"stats": {
"totalAmount": 30000000,
"paidAmount": 20000000,
"unpaidAmount": 10000000,
"overdueAmount": 3000000,
"count": 18
}
}
```
## 모델
### Payable
**테이블**: `payables`
| 필드 | 타입 | 설명 |
|------|------|------|
| `tenant_id` | bigint | 테넌트 ID |
| `vendor_name` | string(100) | 공급업체명 |
| `invoice_no` | string(50) | 인보이스 번호 |
| `issue_date` | date | 발급일 |
| `due_date` | date | 만기일 |
| `category` | string(50) | 카테고리 |
| `amount` | bigint | 총액 |
| `paid_amount` | bigint | 지급액 |
| `status` | string | unpaid / partial / paid / overdue |
| `description` | string | 설명 |
| `memo` | text | 메모 |
| `tax_invoice_issued` | boolean | 세금계산서 발행 여부 |
- SoftDeletes 적용
- Scope: `forTenant($tenantId)`
- Index: `(tenant_id, status)`, `(tenant_id, due_date)`
#### 상태 흐름
```
unpaid (미지급)
├── pay() (부분) → partial (부분 지급)
├── pay() (전액) → paid (지급 완료)
└── (만기일 경과) → overdue (연체)
```
#### 카테고리
사무용품, 소프트웨어, 서비스, 시설, 장비, 외주, 기타
## 뷰 구성 (React)
### payables.blade.php
```
┌─ 페이지 헤더 ──────────────────────
│ 제목: "미지급금관리"
│ [등록] 버튼
│
├─ 통계 카드 (5열) ──────────────────
│ 총액 | 지급액 | 미지급액 | 연체액 | 건수
│
├─ 필터 영역 ────────────────────────
│ 검색 (공급업체명) | 상태 | 카테고리
│
├─ 미지급금 목록 테이블 ─────────────
│ 공급업체 | 인보이스 | 발급일 | 만기일 | 카테고리 | 금액 | 지급액 | 상태 | 세금계산서 | 작업
│ └─ 상태: 미지급(노랑), 부분(파랑), 지급완료(초록), 연체(빨강) 배지
│ └─ 세금계산서: 발행/미발행 표시
│ └─ 작업: 지급처리, 수정, 삭제
│
├─ 등록/수정 모달 ───────────────────
│ 공급업체명, 인보이스번호, 발급일, 만기일
│ 카테고리, 금액, 설명, 세금계산서 발행 체크박스, 메모
│
└─ 지급 처리 모달 ───────────────────
현재 미지급액 표시, 지급액 입력
```
## HTMX 호환성
- React 기반 페이지이므로 **HX-Redirect 필요**
- `@push('scripts')` 블록에 React/Babel 스크립트 포함

179
docs/features/crm/receivables.md Normal file
View File

@@ -0,0 +1,179 @@
# 미수금관리
## 개요
미수금관리는 고객별 채권 현황을 추적하고 수금 처리를 관리하는 기능입니다.
인보이스별 미수금 등록, 부분/전액 수금 처리, 연체 추적, 통계 기능을 제공합니다.
- **라우트**: `GET /finance/receivables`
- **UI 기술**: React 18 + Babel (브라우저 트랜스파일링)
## 파일 구조
```
mng/
├── app/Http/Controllers/Finance/
│ └── ReceivableController.php # MNG 컨트롤러 (5개 메서드)
├── app/Models/Finance/
│ └── Receivable.php # 미수금 모델
└── resources/views/finance/
└── receivables.blade.php # React 기반 단일 페이지
api/
├── app/Http/Controllers/Api/V1/
│ └── ReceivablesController.php # API 컨트롤러 (월별 채권 현황)
├── app/Services/
│ └── ReceivablesService.php # 비즈니스 로직 서비스
└── database/migrations/
└── 2026_02_04_222005_create_receivables_table.php
```
## 라우트
### MNG 라우트
```php
// routes/web.php (finance prefix 그룹 내)
GET /receivables → 페이지 렌더링 (HX-Redirect)
GET /receivables/list → index() 목록 + 통계 (JSON)
POST /receivables/store → store() 등록
PUT /receivables/{id} → update() 수정
POST /receivables/{id}/collect → collect() 수금 처리
DELETE /receivables/{id} → destroy() 삭제
```
### API 라우트
```php
// routes/api.php (v1/receivables prefix)
GET / → index() 거래처별 월별 채권 현황
GET /summary → summary() 채권 요약 통계
POST /update-overdue → updateOverdueStatus() 연체 상태 일괄 갱신
POST /update-memos → updateMemos() 메모 일괄 수정
```
## 컨트롤러
### ReceivableController (MNG)
| 메서드 | HTTP | 설명 |
|--------|------|------|
| `index()` | GET | 미수금 목록 (검색, 상태/카테고리 필터) |
| `store()` | POST | 미수금 등록 |
| `update()` | PUT | 미수금 수정 |
| `collect()` | POST | **수금 처리** (수금액 입력 → 상태 자동 변경) |
| `destroy()` | DELETE | 삭제 (Soft Delete) |
### collect() 수금 처리 로직
```
수금액 입력
↓
collected_amount += 수금액
↓
collected_amount >= amount ?
→ YES: status = 'collected' (전액 수금)
→ NO: status = 'partial' (부분 수금)
```
### index() 응답 구조
```json
{
"success": true,
"data": [...],
"stats": {
"totalAmount": 50000000,
"collectedAmount": 30000000,
"outstandingAmount": 20000000,
"overdueAmount": 5000000,
"count": 25
}
}
```
## 서비스 클래스 (API)
### ReceivablesService
거래처별 월별 채권 현황을 제공하는 서비스:
| 메서드 | 설명 |
|--------|------|
| `index(params)` | 거래처별 월별 매출/입금/어음/미수금 현황 |
| `summary(params)` | 채권 요약 통계 |
| `getCarryForwardBalance()` | 이월잔액 계산 |
| `getSalesByPeriods()` | 기간별 매출 조회 |
| `getDepositsByPeriods()` | 기간별 입금 조회 |
| `getBillsByPeriods()` | 기간별 어음 조회 |
| `calculateCumulativeReceivables()` | 누적 미수금 계산 |
## 모델
### Receivable
**테이블**: `receivables`
| 필드 | 타입 | 설명 |
|------|------|------|
| `tenant_id` | bigint | 테넌트 ID |
| `customer_name` | string(100) | 고객명 |
| `invoice_no` | string(50) | 인보이스 번호 |
| `issue_date` | date | 발급일 |
| `due_date` | date | 만기일 |
| `category` | string(50) | 카테고리 |
| `amount` | bigint | 총액 |
| `collected_amount` | bigint | 수금액 |
| `status` | string | outstanding / partial / collected / overdue |
| `description` | string | 설명 |
| `memo` | text | 메모 |
- SoftDeletes 적용
- Scope: `forTenant($tenantId)`
- Index: `(tenant_id, status)`, `(tenant_id, due_date)`
#### 상태 흐름
```
outstanding (미수금)
├── collect() (부분) → partial (부분 수금)
├── collect() (전액) → collected (수금 완료)
└── (만기일 경과) → overdue (연체)
```
#### 카테고리
서비스, 상품, 컨설팅, 기타
## 뷰 구성 (React)
### receivables.blade.php
```
┌─ 페이지 헤더 ──────────────────────
│ 제목: "미수금관리"
│ [등록] 버튼
│
├─ 통계 카드 (5열) ──────────────────
│ 총액 | 수금액 | 미수금액 | 연체액 | 건수
│
├─ 필터 영역 ────────────────────────
│ 검색 (고객명, 인보이스번호) | 상태 | 카테고리
│
├─ 미수금 목록 테이블 ───────────────
│ 고객명 | 인보이스 | 발급일 | 만기일 | 카테고리 | 금액 | 수금액 | 상태 | 작업
│ └─ 상태: 미수금(노랑), 부분(파랑), 수금완료(초록), 연체(빨강) 배지
│ └─ 작업: 수금처리, 수정, 삭제
│
├─ 등록/수정 모달 ───────────────────
│ 고객명, 인보이스번호, 발급일, 만기일
│ 카테고리, 금액, 설명, 메모
│
└─ 수금 처리 모달 ───────────────────
현재 미수금액 표시, 수금액 입력
```
## HTMX 호환성
- React 기반 페이지이므로 **HX-Redirect 필요**
- `@push('scripts')` 블록에 React/Babel 스크립트 포함

166
docs/features/crm/refunds.md Normal file
View File

@@ -0,0 +1,166 @@
# 환불/해지관리
## 개요
환불/해지관리는 고객의 환불 또는 해지 요청을 접수하고 승인 프로세스를 관리하는 기능입니다.
요청 등록, 사유 분류, 승인/거절 워크플로우, 환불액 추적을 지원합니다.
- **라우트**: `GET /finance/refunds`
- **UI 기술**: React 18 + Babel (브라우저 트랜스파일링)
## 파일 구조
```
mng/
├── app/Http/Controllers/Finance/
│ └── RefundController.php # 메인 컨트롤러 (5개 메서드)
├── app/Models/Finance/
│ └── Refund.php # 환불/해지 모델
└── resources/views/finance/
└── refunds.blade.php # React 기반 단일 페이지
api/
└── database/migrations/
└── 2026_02_04_223406_create_refunds_table.php
```
## 라우트
```php
// routes/web.php (finance prefix 그룹 내)
GET /refunds → 페이지 렌더링 (HX-Redirect)
GET /refunds/list → index() 목록 + 통계 (JSON)
POST /refunds/store → store() 요청 등록
PUT /refunds/{id} → update() 요청 수정
POST /refunds/{id}/process → process() 요청 처리 (승인/완료/거절)
DELETE /refunds/{id} → destroy() 삭제
```
## 컨트롤러
### RefundController
| 메서드 | HTTP | 설명 |
|--------|------|------|
| `index()` | GET | 목록 (검색, 상태/타입 필터) |
| `store()` | POST | 환불/해지 요청 등록 |
| `update()` | PUT | 요청 수정 |
| `process()` | POST | **요청 처리** (approved/completed/rejected) |
| `destroy()` | DELETE | 삭제 (Soft Delete) |
### process() 처리 로직
```
POST /refunds/{id}/process
{
"action": "approved" | "completed" | "rejected",
"refundAmount": 500000, // (완료 시) 실제 환불액
"note": "처리 비고"
}
↓
status 변경 + process_date 기록
```
### index() 응답 구조
```json
{
"success": true,
"data": [...],
"stats": {
"pendingCount": 5,
"completedCount": 20,
"rejectedCount": 3,
"totalRefundAmount": 15000000
}
}
```
## 모델
### Refund
**테이블**: `refunds`
| 필드 | 타입 | 설명 |
|------|------|------|
| `tenant_id` | bigint | 테넌트 ID |
| `type` | string | **refund**(환불) / **cancel**(해지) |
| `customer_name` | string(100) | 고객명 |
| `request_date` | date | 요청일 |
| `product_name` | string(100) | 상품명 |
| `original_amount` | bigint | 원금액 |
| `refund_amount` | bigint | 환불금액 |
| `reason` | string(100) | 사유 |
| `status` | string | pending / approved / completed / rejected |
| `process_date` | date | 처리일 |
| `note` | text | 비고 |
- SoftDeletes 적용
- Scope: `forTenant($tenantId)`
- Index: `(tenant_id, status)`, `(tenant_id, type)`
#### 요청 타입
| 타입 | 설명 |
|------|------|
| `refund` | 환불 (금액 반환) |
| `cancel` | 해지 (서비스 종료) |
#### 상태 흐름
```
pending (대기)
├── process(approved) → approved (승인)
│ ↓
│ process(completed) → completed (완료) + 환불액/처리일 기록
│
└── process(rejected) → rejected (거절) + 처리일 기록
```
#### 사유 목록
| 사유 | 설명 |
|------|------|
| 서비스 불만족 | 서비스 품질 관련 |
| 결제 오류 | 잘못된 결제 |
| 사업 종료 | 고객 사업 종료 |
| 경쟁사 이전 | 타사 이전 |
| 중복 결제 | 이중 결제 |
| 기타 | 기타 사유 |
## 뷰 구성 (React)
### refunds.blade.php
```
┌─ 페이지 헤더 ──────────────────────
│ 제목: "환불/해지관리"
│ [등록] 버튼
│
├─ 통계 카드 (4열) ──────────────────
│ 대기 | 완료 | 거절 | 총 환불액
│
├─ 필터 영역 ────────────────────────
│ 검색 (고객명, 상품명) | 상태 (전체/대기/승인/완료/거절) | 타입 (환불/해지)
│
├─ 요청 목록 테이블 ─────────────────
│ 타입 | 고객명 | 요청일 | 상품명 | 원금 | 환불액 | 사유 | 상태 | 처리일 | 작업
│ └─ 타입: 환불(빨강), 해지(주황) 배지
│ └─ 상태: 대기(노랑), 승인(파랑), 완료(초록), 거절(빨강) 배지
│ └─ 작업: 처리, 수정, 삭제
│
├─ 등록/수정 모달 ───────────────────
│ 타입(환불/해지), 고객명, 요청일, 상품명
│ 원금액, 환불금액, 사유(드롭다운), 비고
│
└─ 처리 모달 ────────────────────────
요청 정보 표시
액션 선택: 승인 | 완료 | 거절
환불액 (완료 시), 비고
```
## HTMX 호환성
- React 기반 페이지이므로 **HX-Redirect 필요**
- `@push('scripts')` 블록에 React/Babel 스크립트 포함

150
docs/features/crm/trading-partners.md Normal file
View File

@@ -0,0 +1,150 @@
# 거래처관리
## 개요
거래처관리는 회사의 거래처(업체/프리랜서)를 등록하고 관리하는 기능입니다.
업종별 분류, 사업자번호/계좌 관리, OCR 명함 인식을 지원합니다.
- **라우트**: `GET /finance/partners`
- **라우트 이름**: `finance.partners`
- **UI 기술**: React 18 + Babel (브라우저 트랜스파일링)
## 파일 구조
```
mng/
├── app/Http/Controllers/Finance/
│ └── TradingPartnerController.php # 메인 컨트롤러 (5개 메서드)
├── app/Models/Finance/
│ └── TradingPartner.php # 거래처 모델
├── app/Services/
│ └── TradingPartnerOcrService.php # OCR 명함 인식 서비스
└── resources/views/finance/
└── partners.blade.php # React 기반 단일 페이지
api/
└── database/migrations/
└── 2026_02_04_221050_create_trading_partners_table.php
```
## 라우트
```php
// routes/web.php (finance prefix 그룹 내)
GET /partners → 페이지 렌더링 (HX-Redirect)
// API 라우트 (partners prefix)
GET /partners/list → index() 거래처 목록 (JSON)
POST /partners/store → store() 거래처 등록
POST /partners/ocr → ocr() OCR 명함 인식
PUT /partners/{id} → update() 거래처 수정
DELETE /partners/{id} → destroy() 거래처 삭제
```
## 컨트롤러
### TradingPartnerController
| 메서드 | HTTP | 설명 |
|--------|------|------|
| `index()` | GET | 거래처 목록 (검색, 타입/카테고리/상태 필터) |
| `store()` | POST | 거래처 등록 (name, type, category 필수) |
| `update()` | PUT | 거래처 수정 |
| `ocr()` | POST | **OCR 명함 인식** (이미지 → 거래처 정보 추출) |
| `destroy()` | DELETE | 거래처 삭제 (Soft Delete) |
### index() 응답 구조
```json
{
"success": true,
"data": [
{
"id": 1,
"name": "ABC 솔루션",
"type": "vendor",
"category": "IT/소프트웨어",
"bizNo": "123-45-67890",
"bankAccount": "우리은행 1002-xxx-xxxxx",
"contact": "02-1234-5678",
"email": "info@abc.co.kr",
"manager": "김담당",
"managerPhone": "010-1234-5678",
"status": "active",
"memo": ""
}
],
"stats": {
"total": 50,
"vendor": 35,
"freelancer": 15,
"active": 42
}
}
```
## 모델
### TradingPartner
**테이블**: `trading_partners`
| 필드 | 타입 | 설명 |
|------|------|------|
| `tenant_id` | bigint | 테넌트 ID |
| `name` | string(100) | 거래처명 |
| `type` | string | **vendor**(업체) / **freelancer**(프리랜서) |
| `category` | string(50) | 업종 카테고리 |
| `biz_no` | string | 사업자번호 |
| `bank_account` | string | 계좌 정보 |
| `contact` | string | 연락처 |
| `email` | string | 이메일 |
| `manager` | string | 담당자명 |
| `manager_phone` | string | 담당자 연락처 |
| `status` | string | active / inactive |
| `memo` | text | 메모 |
- SoftDeletes 적용
- Scope: `active()`, `forTenant($tenantId)`
## 뷰 구성 (React)
### partners.blade.php
```
┌─ 페이지 헤더 ──────────────────────
│ 제목: "거래처관리"
│ [CSV 내보내기] [OCR 등록] [등록] 버튼
│
├─ 통계 카드 (4열) ──────────────────
│ 전체 | 업체 | 프리랜서 | 활성
│
├─ 필터 영역 ────────────────────────
│ 검색 (거래처명, 담당자) | 타입 (업체/프리랜서) | 카테고리 | 상태
│
├─ 거래처 목록 테이블 ───────────────
│ 거래처명 | 타입 | 카테고리 | 사업자번호 | 계좌 | 담당자 | 상태 | 작업
│ └─ 타입: 업체(파랑), 프리랜서(보라) 배지
│
├─ 등록/수정 모달 ───────────────────
│ 거래처명, 타입(업체/프리랜서), 카테고리
│ 사업자번호, 계좌정보, 연락처, 이메일
│ 담당자, 담당자 연락처, 상태, 메모
│
└─ OCR 모달 ─────────────────────────
명함 이미지 업로드 → AI 인식 → 자동 필드 채우기
```
## OCR 명함 인식
### TradingPartnerOcrService
명함 이미지를 Claude Vision API로 분석하여 거래처 정보를 자동 추출합니다:
- 이미지(Base64) → Claude Vision API 호출
- 회사명, 담당자명, 연락처, 이메일, 주소 등 추출
- 추출 결과를 등록 폼에 자동 입력
## HTMX 호환성
- React 기반 페이지이므로 **HX-Redirect 필요**
- `@push('scripts')` 블록에 React/Babel 스크립트 포함

120
docs/features/documents/README.md Normal file
View File

@@ -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

50
docs/features/equipment/README.md Normal file
View File

@@ -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

101
docs/features/esign/README.md Normal file
View File

@@ -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

115
docs/features/finance/README.md Normal file
View File

@@ -0,0 +1,115 @@
# 재무/자금관리 (Finance)
> **최종 갱신**: 2026-02-27
## 개요
SAM 프로젝트의 재무/자금관리 모듈. 입출금, 급여, 가지급금, 세금계산서, 어음, 악성채권 추심, CEO 대시보드까지 재무 전 영역을 관리한다. 바로빌 API 연동을 통한 실시간 거래 조회 및 전자세금계산서 발행을 지원한다.
## 문서 목록
### 자금관리 (기존)
| 문서 | 설명 |
|------|------|
| [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 대시보드·종합분석·부가세·접대비·복리후생비 |
## 아키텍처
```
┌─────────────────────────────────────────────────────────┐
│ 재무 대시보드 │
│ (총 잔액, 예정 수입/지출, 최근 거래, 계좌별 잔액) │
└──────────┬──────────────────┬──────────────────┬────────┘
│ │ │
┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐
│ 보유계좌관리 │ │ 자금계획일정 │ │ 계좌입출금내역 │
│ (계좌 CRUD) │ │ (일정 CRUD) │ │(바로빌 연동) │
└──────┬──────┘ └──────┬──────┘ └──────┬──────┘
│ │ │
┌──────▼──────────────────▼──────────────────▼──────┐
│ 데이터베이스 │
│ bank_accounts, fund_schedules, │
│ barobill_bank_transactions, journal_entries │
└──────────────────────────────────────────────────────┘
```
## 주요 기술 스택
| 기술 | 용도 |
|------|------|
| Laravel 11 (PHP 8.3) | 백엔드 프레임워크 |
| Blade + Tailwind CSS | 서버 렌더링 UI (대시보드, 계좌관리, 자금일정) |
| React 18 + Babel | 클라이언트 렌더링 UI (자금일보, 입출금내역) |
| HTMX | 부분 페이지 업데이트 (계좌 목록 등) |
| Barobill SOAP API | 은행 거래 실시간 연동 |
| MySQL 8.0 | 데이터 저장 |
## 데이터 흐름
```
바로빌 SOAP API ──→ barobill_bank_transactions ──→ 계좌입출금내역
──→ 일일자금일보
──→ 재무 대시보드
사용자 입력 ──→ bank_accounts ──→ 보유계좌관리
──→ 재무 대시보드
사용자 입력 ──→ fund_schedules ──→ 자금계획일정
──→ 재무 대시보드
```
## 공통 모델
| 모델 | 테이블 | 역할 |
|------|--------|------|
| `Finance\BankAccount` | `bank_accounts` | 보유 계좌 정보 |
| `Finance\FundSchedule` | `fund_schedules` | 자금 일정 |
| `Finance\DailyFundTransaction` | `daily_fund_transactions` | 일일자금 거래 |
| `Finance\DailyFundMemo` | `daily_fund_memos` | 일일자금 메모 |
| `Barobill\BankTransaction` | `barobill_bank_transactions` | 바로빌 거래내역 |
| `Barobill\BankTransactionOverride` | `barobill_bank_transaction_overrides` | 거래 수정 |
| `Barobill\BankTransactionSplit` | `barobill_bank_transaction_splits` | 거래 분개 |
| `Barobill\AccountCode` | `account_codes` | 계정과목 |
## 서비스 클래스
| 서비스 | 파일 | 주요 역할 |
|--------|------|----------|
| `BankAccountService` | `app/Services/BankAccountService.php` | 계좌 CRUD, 통계, 바로빌 연동 |
| `FundScheduleService` | `app/Services/FundScheduleService.php` | 일정 CRUD, 캘린더, 월별 요약 |
| `FcmApiService` | `app/Services/FcmApiService.php` | FCM 푸시 발송 (간접 관련) |

339
docs/features/finance/account-transactions.md Normal file
View File

@@ -0,0 +1,339 @@
# 계좌입출금내역
## 개요
계좌입출금내역은 바로빌 SOAP API를 통해 은행 거래내역을 실시간으로 조회하고,
회계 분류(계정과목 지정), 분개(1거래→N계정과목), 수동 거래 등록 등을 지원하는 기능입니다.
- **라우트**: `GET /finance/account-transactions`
- **UI 기술**: React 18 + Babel (브라우저 트랜스파일링)
- **컨트롤러**: `EaccountController` (1,772줄)
## 파일 구조
```
mng/
├── app/Http/Controllers/Barobill/
│ └── EaccountController.php # 메인 컨트롤러 (1772줄, 16개+ 메서드)
├── app/Models/Barobill/
│ ├── BankTransaction.php # 바로빌 거래내역 모델
│ ├── BankTransactionOverride.php # 거래 수정(적요/내용)
│ ├── BankTransactionSplit.php # 거래 분개
│ ├── AccountCode.php # 계정과목 마스터
│ ├── BarobillConfig.php # 바로빌 API 설정
│ └── BarobillMember.php # 테넌트별 바로빌 연동 정보
└── resources/views/barobill/eaccount/
└── index.blade.php # React 기반 단일 페이지
```
## 라우트
### 웹 라우트
```php
// routes/web.php
Route::get('/finance/account-transactions', [EaccountController::class, 'index']);
```
### API 라우트
```php
// routes/web.php (barobill/eaccount prefix)
GET /accounts → 등록된 계좌 목록 (바로빌)
GET /latest-balances → 계좌별 최신 잔액 (DB)
GET /transactions → 거래내역 조회 (API + DB 병합)
GET /account-codes → 계정과목 목록 (테넌트별)
GET /account-codes/all → 전체 계정과목
POST /account-codes → 계정과목 등록
PUT /account-codes/{id} → 계정과목 수정
DELETE /account-codes/{id} → 계정과목 삭제
POST /save → 거래 저장 (회계 분류)
GET /export → Excel 내보내기
POST /save-override → 거래 적요/내용 수정
POST /manual → 수동 거래 등록
PUT /manual/{id} → 수동 거래 수정
DELETE /manual/{id} → 수동 거래 삭제
GET /splits → 분개 내역 조회
POST /splits → 분개 저장
DELETE /splits → 분개 삭제
```
## 컨트롤러
### EaccountController
| 메서드 | HTTP | 설명 |
|--------|------|------|
| `__construct()` | - | SOAP 클라이언트 초기화 (BarobillConfig) |
| `index()` | GET | React 페이지 렌더링 (HX-Redirect 적용) |
| `accounts()` | GET | 바로빌 등록 계좌 목록 |
| `latestBalances()` | GET | DB 기반 최신 잔액 |
| `transactions()` | GET | **거래내역 조회** (API + DB 병합) |
| `accountCodes()` | GET | 계정과목 목록 |
| `accountCodesAll()` | GET | 전체 계정과목 |
| `accountCodeStore()` | POST | 계정과목 등록 |
| `accountCodeUpdate()` | PUT | 계정과목 수정 |
| `accountCodeDestroy()` | DELETE | 계정과목 삭제 |
| `save()` | POST | 거래 저장 (계정과목 지정) |
| `exportExcel()` | GET | Excel 내보내기 |
| `saveOverride()` | POST | 적요/내용 수정 (override) |
| `storeManual()` | POST | 수동 거래 등록 |
| `updateManual()` | PUT | 수동 거래 수정 |
| `destroyManual()` | DELETE | 수동 거래 삭제 |
| `splits()` | GET | 분개 내역 조회 |
| `saveSplits()` | POST | 분개 저장 |
| `deleteSplits()` | DELETE | 분개 삭제 |
## 바로빌 SOAP API 연동
### 설정 구조
```
BarobillConfig (barobill_configs 테이블)
├─ environment: 'test' 또는 'production'
├─ cert_key: 인증서 키
├─ corp_num: 법인번호
└─ base_url: SOAP URL
BarobillMember (barobill_members 테이블)
├─ tenant_id: 테넌트별 분리
├─ barobill_id: 바로빌 로그인 ID
├─ barobill_pwd: 암호화된 비밀번호
└─ server_mode: 'test' 또는 'production' (테넌트별)
```
### 사용 SOAP 메서드
| WSDL | 메서드 | 기능 |
|------|--------|------|
| BANKACCOUNT.asmx | `GetBankAccountEx` | 등록된 계좌 목록 |
| BANKACCOUNT.asmx | `GetPeriodBankAccountTransLog` | 기간별 거래내역 조회 |
### 에러 코드
| 코드 | 의미 |
|------|------|
| `-25005` | 데이터 없음 (정상) |
| `-25001` | 데이터 없음 (정상) |
| 기타 | 에러 메시지 반환 |
## 핵심 로직
### 거래내역 조회 흐름 (transactions)
```
React 컴포넌트 (날짜/계좌 선택)
↓
GET /barobill/eaccount/transactions
↓
1. BarobillMember 조회 (barobill_id)
↓
2. 테넌트별 서버 모드 적용
└─ BarobillConfig 재로드 → SOAP 클라이언트 재초기화
↓
3. [단일 계좌 조회]
├─ DB 조회: barobill_bank_transactions (저장된 데이터)
├─ SOAP 호출: GetPeriodBankAccountTransLog
├─ Override 데이터 병합 (수정된 적요)
├─ 수동 거래 병합 (중복 제거)
├─ 분개 데이터 병합
├─ 잔액 재계산 (기간 전 잔액 기준)
└─ 정렬 (최신순) + 페이지네이션
↓
4. [전체 계좌 조회]
├─ GetBankAccountEx로 계좌 목록 조회
├─ 각 계좌별로 3번 반복
└─ 모든 거래 병합 및 정렬
↓
5. JSON 응답
```
### 거래 고유 키 (unique_key)
```php
// BankTransaction 모델
return implode('|', [
$this->bank_account_num,
$this->trans_dt, // 거래일시
(int) $this->deposit,
(int) $this->withdraw,
(int) $this->balance,
]);
```
### 분개 저장 흐름
```
React (분개 모달)
↓
POST /barobill/eaccount/splits
{
originalUniqueKey: "계좌번호|거래일시|입금|출금|잔액",
originalData: { bankAccountNum, transDate, ... },
splits: [
{ amount: 50000, accountCode: "1000", accountName: "당좌예금" },
{ amount: 50000, accountCode: "2000", accountName: "미수금" }
]
}
↓
기존 분개 삭제 → 새 분개 생성 × N
```
### Override 저장 로직
```
POST /barobill/eaccount/save-override
{
uniqueKey: "거래 고유 키",
modifiedSummary: "수정된 적요",
modifiedCast: "수정된 내용"
}
↓
BankTransactionOverride::saveOverride()
→ 둘 다 null이면 delete
→ 아니면 upsert
```
## 모델
### BankTransaction (Barobill)
**테이블**: `barobill_bank_transactions`
| 필드 | 설명 |
|------|------|
| `tenant_id` | 테넌트 ID |
| `bank_account_num` | 계좌번호 (하이픈 없음) |
| `bank_code` / `bank_name` | 은행 코드/명 |
| `trans_date` | 거래일 (YYYYMMDD) |
| `trans_time` | 거래시간 (HHMMSS) |
| `trans_dt` | 거래일시 (trans_date + trans_time) |
| `deposit` / `withdraw` | 입금액 / 출금액 |
| `balance` | 거래 후 잔액 |
| `summary` / `cast` | 적요 / 내용 |
| `account_code` / `account_name` | 계정과목 코드/명 |
| `is_manual` | 수동 입력 여부 |
### BankTransactionOverride
**테이블**: `barobill_bank_transaction_overrides`
| 필드 | 설명 |
|------|------|
| `unique_key` | 거래 고유 키 |
| `modified_summary` | 수정된 적요 |
| `modified_cast` | 수정된 내용 |
### BankTransactionSplit
**테이블**: `barobill_bank_transaction_splits`
| 필드 | 설명 |
|------|------|
| `original_unique_key` | 원본 거래 고유 키 |
| `split_amount` | 분개 금액 |
| `account_code` / `account_name` | 계정과목 |
| `description` / `memo` | 설명 / 메모 |
| `sort_order` | 정렬 순서 |
| `bank_account_num` / `trans_dt` / `trans_date` | 원본 거래 정보 |
| `original_deposit` / `original_withdraw` | 원본 금액 |
### AccountCode
**테이블**: `account_codes`
| 필드 | 설명 |
|------|------|
| `code` | 계정과목 코드 (예: "1000") |
| `name` | 계정과목명 (예: "당좌예금") |
| `category` | 분류 (자산, 부채, 자본 등) |
| `sort_order` | 정렬 순서 |
| `is_active` | 활성 여부 |
### BarobillConfig
**테이블**: `barobill_configs`
| 필드 | 설명 |
|------|------|
| `name` | 설정명 |
| `environment` | 'test' 또는 'production' |
| `cert_key` | 바로빌 인증서 키 |
| `corp_num` | 법인번호 |
| `is_active` | 활성 여부 |
### BarobillMember
**테이블**: `barobill_members`
| 필드 | 설명 |
|------|------|
| `tenant_id` | 테넌트 ID |
| `biz_no` | 사업자번호 |
| `barobill_id` / `barobill_pwd` | 바로빌 로그인 정보 |
| `server_mode` | 'test' 또는 'production' |
| `status` | active / inactive / pending |
## 뷰 구성 (React)
### index.blade.php
```
┌─ 테넌트 정보 카드 (Blade) ──────────
│ 회사명, 사업자번호, 바로빌 ID
│ 바로빌 미연동 경고 (조건부)
│
├─ React 앱 (#eaccount-root) ─────────
│ ├─ 계좌 선택 드롭다운
│ ├─ 기간 선택 (이번달, 지난달, D-2~5월 버튼)
│ │
│ ├─ 통계 카드 ──────────
│ │ 총 입금 | 총 출금 | 거래 건수
│ │
│ ├─ 거래 테이블 ────────
│ │ 번호 | 거래일시 | 적요 | 입금 | 출금 | 잔액 | 계정과목
│ │ ├─ 인라인 편집 (적요, 계정과목)
│ │ ├─ 수동 거래: 보라색 표시
│ │ ├─ 숨긴 거래: 회색 처리
│ │ └─ 분개된 거래: 파란색 표시
│ │
│ ├─ 수동 거래 등록 모달 ──
│ │ 날짜, 시간, 입금/출금, 금액, 적요, 계정과목
│ │
│ ├─ 분개 모달 ──────────
│ │ 원본 거래 정보 → N개 분개 항목
│ │
│ └─ 내보내기/저장 버튼
│
└─ API 엔드포인트 상수 (Blade에서 정의)
```
### React 주요 기능
| 기능 | 설명 |
|------|------|
| 계좌별 조회 | 드롭다운에서 계좌 선택 |
| 기간 선택 | 월 단위 버튼 (이번달 ~ D-5월) |
| 인라인 편집 | 적요, 계정과목 직접 수정 |
| 분개 | 1거래 → N계정과목 분할 |
| 수동 입력 | API 미제공 거래 추가 |
| 거래 숨김 | 특정 거래 숨기기/복원 |
| Excel 내보내기 | 조회 데이터 다운로드 |
| 잔액 재계산 | 기간 전 잔액 기준 자동 계산 |
## 데이터베이스 테이블 요약
| 테이블 | 역할 | 마이그레이션 (API) |
|--------|------|-------------------|
| `barobill_bank_transactions` | 거래내역 저장 | `2026_01_23_130000_...` |
| `barobill_bank_transaction_overrides` | 적요/내용 수정 | `2026_02_06_095159_...` |
| `barobill_bank_transaction_splits` | 분개 데이터 | `2026_02_06_200000_...` |
| `account_codes` | 계정과목 마스터 | - |
| `barobill_members` | 테넌트별 연동 정보 | - |
| `barobill_configs` | API 설정 (환경별) | - |
## HTMX 호환성
- React 기반 페이지이므로 **HX-Redirect 필요**
- `@push('scripts')` 블록에 React/Babel 스크립트 포함
- HTMX 네비게이션 시 전체 페이지 리로드 필수

47
docs/features/finance/bad-debts.md Normal file
View File

@@ -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 섹션

254
docs/features/finance/bank-accounts.md Normal file
View File

@@ -0,0 +1,254 @@
# 보유계좌관리
## 개요
보유계좌관리는 회사의 은행계좌 정보를 중앙 집중식으로 관리하는 기능입니다.
계좌 등록/수정/삭제, 잔액 조회, 바로빌 연동 최신 잔액 업데이트를 지원합니다.
- **라우트**: `GET /finance/accounts`
- **라우트 이름**: `finance.accounts.index`
- **UI 기술**: Blade + HTMX
## 파일 구조
```
mng/
├── app/Http/Controllers/
│ ├── Finance/
│ │ └── BankAccountController.php # 웹 컨트롤러
│ └── Api/Admin/
│ └── BankAccountController.php # API 컨트롤러
├── app/Services/
│ └── BankAccountService.php # 비즈니스 로직
├── app/Models/Finance/
│ ├── BankAccount.php # 계좌 모델
│ └── BankTransaction.php # 거래내역 모델
└── resources/views/finance/accounts/
├── index.blade.php # 목록 페이지
├── create.blade.php # 등록 폼
├── edit.blade.php # 수정 폼
├── show.blade.php # 상세 (거래내역 포함)
└── partials/
└── table.blade.php # 테이블 partial (HTMX)
```
## 라우트
### 웹 라우트
```php
// routes/web.php (finance prefix 그룹 내)
Route::get('/accounts', [BankAccountController::class, 'index'])->name('accounts.index');
Route::get('/accounts/create', [..., 'create'])->name('accounts.create');
Route::get('/accounts/{id}', [..., 'show'])->name('accounts.show');
Route::get('/accounts/{id}/edit', [..., 'edit'])->name('accounts.edit');
```
### API 라우트
```php
// routes/api.php (admin/bank-accounts prefix)
GET /all → 전체 계좌 (드롭다운용)
GET /summary → 요약 통계
GET / → 목록 (페이지네이션)
POST / → 신규 등록
GET /{id} → 상세 조회
PUT /{id} → 수정
DELETE /{id} → 삭제 (Soft Delete)
POST /{id}/restore → 복원
DELETE /{id}/force → 영구 삭제 (슈퍼관리자만)
POST /{id}/toggle-active → 활성/비활성 토글
GET /{id}/transactions → 거래내역 조회
POST /bulk-delete → 일괄 삭제
POST /bulk-restore → 일괄 복원
```
## 컨트롤러
### BankAccountController (웹)
| 메서드 | 설명 | 특이사항 |
|--------|------|---------|
| `index()` | 계좌 목록 | HTMX 감지 → HX-Redirect (JS 실행 보장) |
| `create()` | 등록 폼 | - |
| `show(id)` | 상세 + 거래내역 | 바로빌 거래 연동 |
| `edit(id)` | 수정 폼 | 404 에러 처리 |
## 서비스 클래스
### BankAccountService
| 메서드 | 설명 |
|--------|------|
| `getAccounts(filters, perPage)` | 목록 (페이지네이션) + 바로빌 최신 거래일 |
| `getAllAccounts()` | 모든 활성 계좌 (드롭다운용) |
| `getStatsByBank()` | 은행별 통계 |
| `getAccountById(id, withTrashed)` | 단일 조회 |
| `createAccount(data)` | 신규 등록 |
| `updateAccount(account, data)` | 수정 |
| `deleteAccount(account)` | Soft Delete |
| `restoreAccount(account)` | 복원 |
| `forceDeleteAccount(account)` | 영구 삭제 |
| `toggleActive(account)` | 활성/비활성 토글 |
| `getTransactions(accountId, filters, perPage)` | 계좌별 거래내역 |
| `getSummary()` | 전체 요약 (총 계좌 수, 총 잔액) |
| `bulkDelete(ids)` | 일괄 삭제 |
| `bulkRestore(ids)` | 일괄 복원 |
**바로빌 연동**: `getAccounts()` 실행 시 서브쿼리로 `barobill_bank_transactions` 테이블의 최신 거래 날짜/시간을 조회하여 계좌 데이터에 병합합니다.
```php
// 계좌번호 매칭: 하이픈 제거
REPLACE(account_number, '-', '') = barobill_bank_transactions.bank_account_num
```
## 모델
### BankAccount
**테이블**: `bank_accounts`
#### 주요 필드
| 필드 | 타입 | 설명 |
|------|------|------|
| `tenant_id` | bigint | 테넌트 ID |
| `bank_code` | string | 은행 코드 (000=한국은행, 020=우리은행 등) |
| `bank_name` | string | 은행명 |
| `account_number` | string | 계좌번호 (하이픈 포함) |
| `account_holder` | string | 예금주명 |
| `account_name` | string | 계좌 별칭 |
| `account_type` | string | 예금종류 (보통예금, 정기예금, 적금) |
| `balance` | decimal(15,2) | 현재 잔액 |
| `currency` | string | 통화 (KRW) |
| `opened_at` | date | 개설일자 |
| `last_transaction_at` | datetime | 최종 거래일시 |
| `branch_name` | string | 지점명 |
| `memo` | text | 메모 |
| `status` | string | active / inactive |
| `is_primary` | boolean | 대표계좌 여부 |
| `sort_order` | int | 정렬 순서 |
#### Traits
- `BelongsToTenant` - 테넌트 기반 자동 필터링
- `SoftDeletes` - Soft Delete 지원
#### 주요 Scope
```php
->active() // status = 'active'
->primary() // is_primary = true
->byBank($name) // 은행별 필터
->byType($type) // 예금종류별 필터
->ordered() // sort_order 정렬
```
#### 주요 Accessor
```php
$account->formatted_balance // "1억 2,345만원" 형식
$account->masked_account_number // "110-***-5678"
```
## 뷰 구성
### index.blade.php
```
┌─ 페이지 헤더 ──────────────────────
│ 제목: "보유계좌관리"
│ 버튼: "계좌 등록" (파란색)
│
├─ 요약 카드 (3열) ─────────────────
│ 총 계좌 수 | 총 잔액 | 은행 수
│
├─ 테이블 컨테이너 ─────────────────
│ ├─ 헤더: 검색, 상태 필터
│ └─ HTMX 로드 영역 (#accounts-table)
│ └─ GET /admin/bank-accounts/
│
├─ partials/table.blade.php ────────
│ 컬럼: 은행 | 계좌번호 | 예금종류 | 잔액 | 개설일자 | 최종처리일시 | 작업
│ ├─ 활성 항목: 수정/삭제 버튼
│ └─ 삭제된 항목: 복원/영구삭제 (opacity-50 bg-red-50)
│
└─ JavaScript: refreshAccountBalances()
└─ GET /barobill/eaccount/latest-balances
└─ DOM에서 잔액 실시간 업데이트
```
### 테이블 Partial 특징
| 컬럼 | 특이사항 |
|------|---------|
| 은행 | `show/{id}` 링크 |
| 예금종류 | 컬러 배지 (보통예금=파랑, 정기=보라, 적금=초록) |
| 잔액 | `data-account-number` 속성으로 동적 업데이트 |
| 최종처리일시 | 바로빌 거래일 또는 로컬 데이터 |
| 작업 | HTMX 기반 토글/삭제/복원 |
## 데이터 흐름
```
사용자 (브라우저)
↓
BankAccountController::index()
↓
BankAccountService::getSummary()
↓ (bank_accounts: 총 계좌 수, 총 잔액)
View: finance/accounts/index
├─ 요약 카드 표시
├─ HTMX 테이블 로드
│ ↓
│ Api\Admin\BankAccountController
│ ↓
│ BankAccountService::getAccounts()
│ │ ↓
│ │ bank_accounts + 바로빌 최신 거래일 서브쿼리
│ └─ JSON/HTML 반환
│
└─ refreshAccountBalances()
↓
EaccountController::latestBalances()
↓
barobill_bank_transactions (최신 잔액)
↓
DOM 업데이트
```
## 데이터베이스 스키마
### bank_accounts
**마이그레이션**: `api/database/migrations/2025_12_17_120001_create_bank_accounts_table.php`
```sql
CREATE TABLE bank_accounts (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
tenant_id BIGINT NOT NULL,
bank_code VARCHAR(10),
bank_name VARCHAR(50),
account_number VARCHAR(50),
account_holder VARCHAR(100),
account_name VARCHAR(100),
account_type VARCHAR(20),
balance DECIMAL(15,2) DEFAULT 0,
currency VARCHAR(3) DEFAULT 'KRW',
opened_at DATE,
last_transaction_at DATETIME,
branch_name VARCHAR(100),
memo TEXT,
status VARCHAR(20) DEFAULT 'active',
is_primary BOOLEAN DEFAULT FALSE,
sort_order INT DEFAULT 0,
created_by BIGINT, updated_by BIGINT, deleted_by BIGINT,
created_at TIMESTAMP, updated_at TIMESTAMP, deleted_at TIMESTAMP
);
```
## HTMX 호환성
- Blade + HTMX 기반 (HX-Redirect 사용 - JavaScript 있음)
- 테이블은 HTMX partial로 동적 로드
- 토글/삭제/복원 액션은 HTMX로 처리

40
docs/features/finance/bills.md Normal file
View File

@@ -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 섹션

51
docs/features/finance/cards.md Normal file
View File

@@ -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 섹션

49
docs/features/finance/ceo-dashboard.md Normal file
View File

@@ -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 섹션

201
docs/features/finance/daily-fund-report.md Normal file
View File

@@ -0,0 +1,201 @@
# 일일자금일보
## 개요
일일자금일보는 기간별 계좌 입출금 현황을 조회하고 일별 보고서를 생성하는 기능입니다.
바로빌에서 수집된 은행 거래 데이터를 기반으로 날짜별, 계좌별 입출금 집계를 제공합니다.
- **라우트**: `GET /finance/daily-fund`
- **UI 기술**: React 18 + Babel (브라우저 트랜스파일링)
## 파일 구조
```
mng/
├── app/Http/Controllers/Finance/
│ └── DailyFundController.php # 메인 컨트롤러 (6개 메서드)
├── app/Models/Finance/
│ ├── DailyFundTransaction.php # 수동 거래내역 모델
│ └── DailyFundMemo.php # 일별 메모 모델
├── app/Models/Barobill/
│ ├── BankTransaction.php # 바로빌 거래내역 모델
│ └── BankTransactionOverride.php # 거래 수정 이력
└── resources/views/finance/
└── daily-fund.blade.php # React 기반 UI
```
## 라우트
```php
// routes/web.php (finance prefix 그룹 내)
Route::get('/daily-fund', [DailyFundController::class, 'index'])->name('daily-fund');
// API 엔드포인트 (동일 컨트롤러)
Route::get('/daily-fund/period-report', [DailyFundController::class, 'periodReport']);
Route::post('/daily-fund', [DailyFundController::class, 'store']);
Route::put('/daily-fund/{id}', [DailyFundController::class, 'update']);
Route::delete('/daily-fund/{id}', [DailyFundController::class, 'destroy']);
Route::post('/daily-fund/memo', [DailyFundController::class, 'saveMemo']);
```
## 컨트롤러
### DailyFundController
| 메서드 | HTTP | 설명 |
|--------|------|------|
| `index()` | GET | 특정 날짜 거래내역 조회 |
| `store()` | POST | 거래내역 수동 등록 |
| `update()` | PUT | 거래내역 수정 |
| `destroy()` | DELETE | 거래내역 삭제 |
| `saveMemo()` | POST | 일별 메모 저장 |
| `periodReport()` | GET | **기간별 일일자금일보** (핵심) |
### periodReport() 핵심 로직
```
QueryString: start_date, end_date (YYYYMMDD)
↓
BarobillBankTransaction 조회 (trans_date 범위)
↓
BankTransactionOverride 병합 (수정된 적요/내용)
↓
unique_key 기준 중복 제거
↓
날짜별 그룹핑 + 계좌별 입출금 집계
↓
JSON 응답
```
**응답 구조**:
```json
{
"dailyReports": [
{
"date": "20260211",
"dateFormatted": "2026년 2월 11일 수요일",
"accounts": [
{ "bankName": "우리은행", "accountNum": "1002-xxx", "deposit": 5000000, "withdraw": 1000000, "balance": 50000000 }
],
"deposits": [
{ "time": "0930", "bankName": "우리은행", "summary": "급여입금", "cast": "본사", "amount": 5000000, "balance": 50000000 }
],
"withdrawals": [ ... ],
"totalDeposit": 5000000,
"totalWithdraw": 1000000
}
]
}
```
## 뷰 구성 (React)
### daily-fund.blade.php
```
┌─ 기간 선택 컴포넌트 ────────────
│ 날짜 입력 (start_date ~ end_date)
│ 월별 단축키 (이번달, 지난달 등)
│
├─ 일별 보고서 반복 렌더링 ────────
│ ┌─ 날짜 헤더 ──────────
│ │ 2026년 2월 11일 수요일
│ │
│ ├─ 계좌별 요약 테이블 ──
│ │ 은행명 | 계좌번호 | 입금 | 출금 | 잔액
│ │
│ ├─ 입금 상세 내역 ─────
│ │ 시간 | 은행 | 적요 | 내용 | 금액 | 잔액
│ │
│ └─ 출금 상세 내역 ─────
│ 시간 | 은행 | 적요 | 내용 | 금액 | 잔액
│
└─ 인쇄 버튼
```
## 데이터 흐름
```
React Component (기간 선택)
↓ fetch GET /finance/daily-fund/period-report
DailyFundController::periodReport()
↓
BarobillBankTransaction 조회
↓ (trans_date 범위 필터)
BankTransactionOverride 병합
↓ (수정된 적요/내용 덮어쓰기)
unique_key 기준 중복 제거
↓
날짜별 + 계좌별 그룹핑
↓ (입금/출금 분류, 계좌별 집계)
JSON 응답
↓
React 렌더링 (테이블, 통계)
```
## 데이터베이스 테이블
### barobill_bank_transactions (주 데이터)
| 컬럼 | 타입 | 설명 |
|------|------|------|
| `tenant_id` | bigint | 테넌트 ID |
| `bank_account_num` | string | 계좌번호 |
| `bank_name` | string | 은행명 |
| `trans_date` | string | 거래일 (YYYYMMDD) |
| `trans_time` | string | 거래시간 (HHMM) |
| `deposit` | decimal | 입금액 |
| `withdraw` | decimal | 출금액 |
| `balance` | decimal | 거래 후 잔액 |
| `summary` | string | 적요 |
| `cast` | string | 내용 |
### daily_fund_transactions (수동 입력)
| 컬럼 | 타입 | 설명 |
|------|------|------|
| `tenant_id` | bigint | 테넌트 ID |
| `transaction_date` | date | 거래일 |
| `type` | enum | income / expense |
| `amount` | decimal | 금액 |
| `description` | string | 설명 |
### daily_fund_memos
| 컬럼 | 타입 | 설명 |
|------|------|------|
| `tenant_id` | bigint | 테넌트 ID |
| `memo_date` | date | 메모 날짜 |
| `memo` | text | 메모 내용 |
| `author` | string | 작성자 |
## 핵심 로직
### 거래 중복 제거
```php
->unique(fn($tx) => $tx->unique_key)
// unique_key = bank_account_num|trans_dt|deposit|withdraw|balance
```
### 오버라이드 병합
```php
BankTransactionOverride::getByUniqueKeys($keys)
// → modified_summary, modified_cast로 원본 적요/내용 덮어쓰기
// → is_overridden 플래그 설정
```
### 일별 집계
```
거래 목록 → trans_date 기준 그룹핑
→ 각 날짜: 계좌별 분류
→ 입금 합계, 출금 합계 계산
→ 최종 잔액: DESC 정렬 첫 거래의 balance 값
```
## HTMX 호환성
- React 기반 페이지이므로 HX-Redirect 필요
- `@push('scripts')` 블록에 React/Babel 스크립트 포함

44
docs/features/finance/deposits-withdrawals.md Normal file
View File

@@ -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 섹션

32
docs/features/finance/expected-expenses.md Normal file
View File

@@ -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 섹션

190
docs/features/finance/finance-dashboard.md Normal file
View File

@@ -0,0 +1,190 @@
# 재무 대시보드
## 개요
재무 대시보드는 회사의 자금 현황을 한눈에 파악할 수 있는 종합 화면입니다.
총 잔액, 예정 수입/지출, 최근 거래내역, 계좌별 잔액 등을 요약하여 표시합니다.
- **라우트**: `GET /finance/dashboard`
- **라우트 이름**: `finance.dashboard`
- **UI 기술**: Blade + JavaScript (HTMX 불필요)
## 파일 구조
```
mng/
├── app/Http/Controllers/Finance/
│ └── FinanceDashboardController.php # 메인 컨트롤러
├── app/Services/
│ ├── BankAccountService.php # 계좌 데이터 서비스
│ └── FundScheduleService.php # 자금일정 데이터 서비스
├── app/Models/
│ ├── Finance/
│ │ ├── BankAccount.php # 계좌 모델
│ │ └── FundSchedule.php # 자금일정 모델
│ └── Barobill/
│ ├── BankTransaction.php # 바로빌 거래내역
│ ├── BankTransactionOverride.php # 거래 수정 이력
│ └── CardTransaction.php # 바로빌 카드거래
└── resources/views/finance/
└── dashboard.blade.php # 메인 뷰
```
## 라우트
```php
// routes/web.php (finance prefix 그룹 내)
Route::get('/dashboard', [FinanceDashboardController::class, 'index'])->name('dashboard');
```
## 컨트롤러
### FinanceDashboardController
| 메서드 | HTTP | 반환 | 설명 |
|--------|------|------|------|
| `index()` | GET | View | 대시보드 메인 페이지 |
### index() 데이터 수집
```php
public function index(): View
{
// 1. 계좌 요약 (총 잔액, 계좌 수)
$accountSummary = $this->bankAccountService->getSummary();
// 2. 자금일정 요약 (7일 내 일정 건수)
$scheduleSummary = $this->fundScheduleService->getSummary();
// 3. 이번 달 수입/지출 요약
$monthlySummary = $this->fundScheduleService->getMonthlySummary($year, $month);
// 4. 향후 7일 자금 일정
$upcomingSchedules = $this->fundScheduleService->getUpcomingSchedules(7);
// 5. 최근 7일 은행 거래내역 (최대 10건)
$recentTransactions = BarobillBankTransaction::where(...)
->limit(10)->get();
// 6. 최근 7일 카드 사용내역 (최대 10건)
$recentCardTransactions = BarobillCardTransaction::where(...)
->limit(10)->get();
// 7. 활성 계좌 잔액 목록
$accountBalances = BankAccount::active()->ordered()->get();
}
```
## 뷰 구성
### dashboard.blade.php
| 섹션 | 내용 | 데이터 소스 |
|------|------|------------|
| 페이지 헤더 | 제목 + 현재 날짜 + 네비게이션 버튼 | - |
| 요약 카드 (4개) | 총 잔액 / 예정 수입 / 예정 지출 / 7일내 일정 | `accountSummary`, `monthlySummary`, `scheduleSummary` |
| 월별 자금 일정 요약 | 수입/지출/순수익 (완료/예정 분리) | `monthlySummary` |
| 계좌별 잔액 패널 | 활성 계좌 목록 + 잔액 | `accountBalances` |
| 향후 7일 자금 일정 | 예정 일정 (수입/지출 색상 구분) | `upcomingSchedules` |
| 최근 거래내역 | 7일 은행 거래내역 테이블 | `recentTransactions` |
| 최근 카드 사용내역 | 7일 카드 거래 테이블 | `recentCardTransactions` |
### JavaScript 기능
```javascript
// 계좌 잔액 실시간 새로고침
function refreshAccountBalances() {
// GET /barobill/eaccount/latest-balances
// → 바로빌 DB에서 최신 잔액 조회
// → DOM 업데이트 (잔액 수치 변경)
// → 로딩/완료 상태 피드백
}
```
## 데이터 흐름
```
FinanceDashboardController::index()
│
├─ BankAccountService::getSummary()
│ └─ bank_accounts (총 계좌 수, 총 잔액, 은행별 그룹)
│
├─ FundScheduleService::getSummary()
│ └─ fund_schedules (예정 건수, 예정 수입/지출)
│
├─ FundScheduleService::getMonthlySummary()
│ └─ fund_schedules (월별 수입/지출, 완료/예정 분리)
│
├─ FundScheduleService::getUpcomingSchedules(7)
│ └─ fund_schedules (향후 7일 예정 일정)
│
├─ BarobillBankTransaction 조회
│ └─ barobill_bank_transactions (최근 7일, 10건)
│ └─ BankTransactionOverride 병합 (수정된 적요)
│
├─ BarobillCardTransaction 조회
│ └─ barobill_card_transactions (최근 7일, 10건)
│
└─ BankAccount::active()->ordered()
└─ bank_accounts (계좌별 잔액)
```
## 서비스 반환 구조
### BankAccountService::getSummary()
```php
[
'total_accounts' => int, // 활성 계좌 수
'total_balance' => float, // 총 잔액
'formatted_total_balance' => str, // "1,000,000원"
'by_bank' => [ // 은행별 상세
'bank_name' => ['count' => int, 'total' => float]
]
]
```
### FundScheduleService::getSummary()
```php
[
'pending_count' => int, // 예정 건수
'pending_income' => float, // 예정 수입
'pending_expense' => float, // 예정 지출
'upcoming_7days' => int // 7일 내 일정 건수
]
```
### FundScheduleService::getMonthlySummary()
```php
[
'year' => int, 'month' => int,
'total_count' => int,
'income' => [
'count' => int, 'total' => float,
'pending' => float, 'completed' => float
],
'expense' => [
'count' => int, 'total' => float,
'pending' => float, 'completed' => float
],
'net' => float // 순수익 (수입 - 지출)
]
```
## 관련 데이터베이스 테이블
| 테이블 | 용도 |
|--------|------|
| `bank_accounts` | 계좌 잔액, 계좌 수 통계 |
| `fund_schedules` | 자금 일정 요약, 예정 수입/지출 |
| `barobill_bank_transactions` | 최근 은행 거래내역 |
| `barobill_card_transactions` | 최근 카드 사용내역 |
| `barobill_bank_transaction_overrides` | 거래 수정 이력 병합 |
## HTMX 호환성
- 순수 Blade 템플릿 (복잡한 JavaScript 없음)
- HX-Redirect 불필요
- JavaScript는 `refreshAccountBalances()` 함수만 포함

235
docs/features/finance/fund-schedules.md Normal file
View File

@@ -0,0 +1,235 @@
# 자금계획일정
## 개요
자금계획일정은 입금 예정/지급 예정 일정을 등록, 관리하고 월별 캘린더 뷰로 확인하는 기능입니다.
반복 일정, 월별 복사, 상태 관리(예정/완료/취소) 기능을 지원합니다.
- **라우트**: `GET /finance/fund-schedules`
- **라우트 이름**: `finance.fund-schedules.index`
- **UI 기술**: Blade 템플릿
## 파일 구조
```
mng/
├── app/Http/Controllers/
│ ├── Finance/
│ │ └── FundScheduleController.php # 웹 컨트롤러 (5개 메서드)
│ └── Api/Admin/
│ └── FundScheduleController.php # API 컨트롤러
├── app/Services/
│ └── FundScheduleService.php # 비즈니스 로직 (13개+ 공개 메서드)
├── app/Models/Finance/
│ └── FundSchedule.php # ORM 모델
└── resources/views/finance/fund-schedules/
├── index.blade.php # 캘린더 뷰
├── create.blade.php # 등록 폼
├── edit.blade.php # 수정 폼
└── show.blade.php # 상세보기
```
## 라우트
### 웹 라우트
```php
// routes/web.php (finance prefix 그룹 내)
Route::get('/fund-schedules', [FundScheduleController::class, 'index'])->name('fund-schedules.index');
Route::get('/fund-schedules/create', [..., 'create'])->name('fund-schedules.create');
Route::get('/fund-schedules/{id}', [..., 'show'])->name('fund-schedules.show');
Route::get('/fund-schedules/{id}/edit', [..., 'edit'])->name('fund-schedules.edit');
// 호환성 리다이렉트
Route::get('/fund-schedule', fn() => redirect()->route('finance.fund-schedules.index'));
```
### API 라우트
```php
// routes/api.php (admin/fund-schedules prefix)
GET / → index() 목록 (페이지네이션)
GET /calendar → calendar() 월별 캘린더 데이터
GET /summary → summary() 요약 통계
GET /upcoming → upcoming() 예정 일정
POST /copy → copy() 월별 일정 복사
GET /{id} → show() 상세 조회
POST / → store() 생성
PUT /{id} → update() 수정
DELETE /{id} → destroy() 삭제
```
## 컨트롤러
### FundScheduleController (웹)
| 메서드 | 설명 | 데이터 흐름 |
|--------|------|------------|
| `index()` | 캘린더 뷰 | year, month → `getCalendarData()` → `getMonthlySummary()` → View |
| `create()` | 등록 폼 | 계좌 목록, 타입/상태/반복 옵션 → View |
| `edit(id)` | 수정 폼 | ID로 일정 조회 → View |
| `show(id)` | 상세보기 | ID로 일정 조회 → View |
## 서비스 클래스
### FundScheduleService
| 메서드 | 매개변수 | 설명 |
|--------|---------|------|
| `getSchedules()` | filters, perPage | 필터링 목록 (페이지네이션) |
| `getSchedulesForMonth()` | year, month | 월별 일정 조회 |
| `getSchedulesForDate()` | date | 특정 날짜 일정 |
| `getUpcomingSchedules()` | days=30 | 향후 N일 예정 일정 |
| `getScheduleById()` | id, withTrashed | 단일 조회 |
| `createSchedule()` | data | 생성 (tenant_id, created_by 자동) |
| `updateSchedule()` | schedule, data | 수정 (updated_by 자동) |
| `deleteSchedule()` | schedule | Soft Delete |
| `restoreSchedule()` | schedule | 복원 |
| `forceDeleteSchedule()` | schedule | 영구 삭제 |
| `markAsCompleted()` | schedule, amount, date | 완료 처리 |
| `markAsCancelled()` | schedule | 취소 처리 |
| `copySchedulesToMonth()` | src→tgt year/month | 월별 일정 복사 (말일 처리) |
| `bulkDelete()` | ids | 일괄 삭제 |
| `bulkUpdateStatus()` | ids, status | 일괄 상태 변경 |
| `getMonthlySummary()` | year, month | 월별 요약 |
| `getCalendarData()` | year, month | 캘린더용 날짜별 그룹핑 |
| `getSummary()` | - | 전체 요약 |
## 모델
### FundSchedule
**테이블**: `fund_schedules`
#### 상수 정의
```php
// 일정 유형
TYPE_INCOME = 'income' // 입금 예정
TYPE_EXPENSE = 'expense' // 지급 예정
// 상태
STATUS_PENDING = 'pending' // 예정
STATUS_COMPLETED = 'completed' // 완료
STATUS_CANCELLED = 'cancelled' // 취소
// 반복 규칙
RECURRENCE_DAILY = 'daily'
RECURRENCE_WEEKLY = 'weekly'
RECURRENCE_MONTHLY = 'monthly'
RECURRENCE_YEARLY = 'yearly'
```
#### 주요 필드
| 필드 | 타입 | 설명 |
|------|------|------|
| `tenant_id` | bigint | 테넌트 ID |
| `title` | string | 일정 제목 |
| `description` | text | 설명 |
| `schedule_type` | enum | income / expense |
| `scheduled_date` | date | 예정 날짜 |
| `amount` | decimal(15,2) | 예정 금액 |
| `currency` | string | 통화 (KRW) |
| `related_bank_account_id` | bigint | 관련 계좌 ID |
| `counterparty` | string | 거래처 |
| `category` | string | 카테고리 |
| `status` | enum | pending / completed / cancelled |
| `is_recurring` | boolean | 반복 여부 |
| `recurrence_rule` | string | 반복 규칙 |
| `recurrence_end_date` | date | 반복 종료일 |
| `completed_date` | date | 실제 완료일 |
| `completed_amount` | decimal(15,2) | 실제 금액 |
| `created_by` / `updated_by` / `deleted_by` | bigint | 작업자 |
#### 주요 Scope
```php
->income() // TYPE_INCOME만
->expense() // TYPE_EXPENSE만
->pending() // STATUS_PENDING만
->completed() // STATUS_COMPLETED만
->forMonth(year, month) // 특정 월의 일정
->dateBetween(s, e) // 날짜 범위
->ordered() // scheduled_date 정렬
```
#### 주요 Accessor
```php
$schedule->formatted_amount // "100만원" 형식
$schedule->type_label // "입금 예정"
$schedule->status_label // "예정"
$schedule->type_color_class // Tailwind 색상 클래스
$schedule->status_color_class // Tailwind 색상 클래스
```
## 뷰 구성
### index.blade.php (캘린더 뷰)
```
┌─ 페이지 헤더 ──────────────────────
│ 제목: "자금계획일정"
│ 버튼: "일정 등록"
│
├─ 월별 요약 카드 (4열) ────────────
│ 입금 예정 | 지급 예정 | 순 자금 흐름 | 총 일정
│
├─ 캘린더 섹션 ─────────────────────
│ ├─ 헤더: 월 네비게이션 (< 2026년 2월 >)
│ ├─ 요일 헤더 (일~토)
│ └─ 날짜 그리드 (일별 일정 표시)
│ ├─ 입금: 초록 배지
│ ├─ 지출: 빨강 배지
│ └─ 클릭 시 일정 상세
│
└─ 일정 등록/수정 모달 (JavaScript)
```
## 핵심 로직
### 월별 복사 (copySchedulesToMonth)
```
원본 월의 모든 일정 조회
↓
대상 월로 복사 (말일 처리)
예) 1월 31일 → 2월 28일 (윤년이면 29일)
↓
새 일정 생성 (상태: pending으로 초기화)
```
### 월별 요약 (getMonthlySummary)
```php
[
'year' => 2026, 'month' => 2,
'total_count' => 15,
'income' => [
'count' => 5, 'total' => 10000000,
'pending' => 7000000, 'completed' => 3000000
],
'expense' => [
'count' => 10, 'total' => 8000000,
'pending' => 5000000, 'completed' => 3000000
],
'net' => 2000000 // 수입 - 지출
]
```
### 캘린더 데이터 (getCalendarData)
```php
// 날짜별 그룹핑
[
'2026-02-05' => [ {일정1}, {일정2} ],
'2026-02-06' => [ {일정3} ],
...
]
```
## HTMX 호환성
- 순수 Blade 템플릿 (HX-Redirect 불필요)
- JavaScript는 모달 열기/닫기 함수만 포함

54
docs/features/finance/loans.md Normal file
View File

@@ -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 섹션

66
docs/features/finance/payroll.md Normal file
View File

@@ -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 섹션

42
docs/features/finance/receivables-ledger.md Normal file
View File

@@ -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 섹션

40
docs/features/finance/tax-invoices.md Normal file
View File

@@ -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 섹션

340
docs/features/hr/attendance-management-spec.md Normal file
View File

@@ -0,0 +1,340 @@
# 근태관리 기획서
> **작성일**: 2026-02-26
> **상태**: 1차 구현 완료 / 2차 고도화 예정
> **담당**: MNG 인사관리 모듈
---
## 1. 개요
### 1.1 목적
사원의 일별 출퇴근 및 근태 상태를 체계적으로 관리하여, 급여 산정·인사 평가·법정 근로시간 준수의 기초 데이터를 확보한다.
### 1.2 핵심 원칙
| 원칙 | 설명 |
|------|------|
| **정확성** | 출퇴근 시간·상태를 실시간으로 정확히 기록 |
| **자동화** | 지각/정시 자동 판정, 근무시간 자동 계산 |
| **유연성** | 휴가·출장·외근·재택 등 다양한 근무 형태 지원 |
| **감사 추적** | 모든 등록·수정·삭제에 작업자 기록 |
---
## 2. 화면 구성
### 2.1 메뉴 위치
```
인사관리
├── 사원관리
├── 근태관리 ← 현재 문서
├── 달력 관리
└── (향후 확장)
```
### 2.2 메인 화면 레이아웃
```
┌─────────────────────────────────────────────────────────────┐
│ 근태현황 [+ 근태 등록] │
│ 2026년 2월 현재 │
├─────────────────────────────────────────────────────────────┤
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌────────┐│
│ │ 정시출근 │ │ 지각 │ │ 결근 │ │ 휴가 │ │ 기타 ││
│ │ 42건 │ │ 3건 │ │ 0건 │ │ 5건 │ │ 2건 ││
│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └────────┘│
├─────────────────────────────────────────────────────────────┤
│ [검색: 사원명] [부서 ▼] [상태 ▼] [시작일] [종료일] [검색] │
├─────────────────────────────────────────────────────────────┤
│ 날짜 │ 사원 │ 부서 │ 상태 │ 출근 │ 퇴근 │ 비고 │
│──────────┼────────┼────────┼────────┼───────┼───────┼──────│
│ 02-26 │ 홍길동 │ 개발팀 │ 정시 │ 08:55 │ 18:10 │ │
│ 02-26 │ 김철수 │ 영업팀 │ 지각 │ 09:15 │ 18:30 │ │
│ 02-25 │ 이영희 │ 경영 │ 휴가 │ - │ - │ 연차 │
├─────────────────────────────────────────────────────────────┤
│ ◀ 1 2 3 4 5 ▶ │
└─────────────────────────────────────────────────────────────┘
```
### 2.3 근태 등록/수정 모달
```
┌──────────────── 근태 등록 ─────────────────┐
│ │
│ 사원 [홍길동 ▼] │
│ 날짜 [2026-02-26] │
│ 상태 [정시출근 ▼] │
│ 출근시간 [09:00] │
│ 퇴근시간 [18:00] │
│ 비고 [ ] │
│ │
│ [취소] [저장] │
└─────────────────────────────────────────────┘
```
---
## 3. 근태 상태 유형
| 상태 | 코드 | 색상 | 설명 |
|------|------|------|------|
| 정시출근 | `onTime` | 🟢 emerald | 정해진 출근 시간 내 출근 |
| 지각 | `late` | 🟡 amber | 출근 시간 초과 후 출근 |
| 결근 | `absent` | 🔴 red | 무단 미출근 |
| 휴가 | `vacation` | 🔵 blue | 연차·반차·병가 등 |
| 출장 | `businessTrip` | 🟣 purple | 사외 업무 수행 |
| 외근 | `fieldWork` | 🟤 indigo | 외부 근무 |
| 야근 | `overtime` | 🟠 orange | 정규시간 초과 근무 |
| 재택 | `remote` | 🟦 teal | 원격 근무 |
---
## 4. 데이터 구조
### 4.1 attendances 테이블
| 컬럼 | 타입 | 설명 |
|------|------|------|
| `id` | BIGINT PK | 고유 ID |
| `tenant_id` | BIGINT FK | 테넌트 ID |
| `user_id` | BIGINT FK | 사용자 ID |
| `base_date` | DATE | 기준 일자 |
| `status` | ENUM | 근태 상태 (8종) |
| `json_details` | JSON | 상세 정보 (출퇴근 시간, GPS 등) |
| `remarks` | VARCHAR(500) | 비고 |
| `created_by` | BIGINT | 등록자 |
| `updated_by` | BIGINT | 수정자 |
| `deleted_by` | BIGINT | 삭제자 |
| `created_at` | TIMESTAMP | 등록일시 |
| `updated_at` | TIMESTAMP | 수정일시 |
| `deleted_at` | TIMESTAMP | 삭제일시 (Soft Delete) |
**제약 조건**:
- `UNIQUE (tenant_id, user_id, base_date)` — 일자별 사용자당 1건만 허용
### 4.2 json_details 구조
```json
{
"check_in": "09:00:00",
"check_out": "18:00:00",
"check_ins": [
{ "time": "09:00:00", "recorded_at": "2026-02-26T09:00:00+09:00" }
],
"check_outs": [
{ "time": "18:00:00", "recorded_at": "2026-02-26T18:00:00+09:00" }
],
"gps_data": {
"check_in": { "lat": 37.5665, "lng": 126.9780, "accuracy": 10 },
"check_out": { "lat": 37.5665, "lng": 126.9780, "accuracy": 10 }
},
"work_minutes": 480,
"break_minutes": 60,
"overtime_minutes": 0,
"late_minutes": 0,
"early_leave_minutes": 0,
"vacation_type": "annual",
"external_work": {
"location": "고객사",
"purpose": "미팅",
"start_time": "14:00",
"end_time": "16:00"
}
}
```
### 4.3 attendance_settings 테이블
| 컬럼 | 타입 | 설명 |
|------|------|------|
| `tenant_id` | BIGINT UNIQUE | 테넌트별 1건 |
| `use_gps` | BOOLEAN | GPS 출퇴근 사용 여부 |
| `use_auto` | BOOLEAN | 자동 출퇴근 사용 여부 |
| `allowed_radius` | INT | 허용 반경 (m, 기본 100) |
| `hq_address` | VARCHAR(255) | 사업장 주소 |
| `hq_latitude` | DECIMAL(10,8) | 사업장 위도 |
| `hq_longitude` | DECIMAL(11,8) | 사업장 경도 |
---
## 5. 비즈니스 규칙
### 5.1 출퇴근 기록
| 규칙 | 설명 |
|------|------|
| R1 | 같은 날짜 + 사용자 조합은 1건만 존재 (Upsert) |
| R2 | 출근 기록 시 WorkSetting의 `start_time` 기준으로 지각/정시 자동 판정 |
| R3 | 퇴근 기록 시 근무시간 자동 계산: (최초 출근 ~ 최종 퇴근) - 휴게시간 |
| R4 | 다중 출퇴근 기록 지원 — `check_ins`/`check_outs` 배열로 이력 관리 |
| R5 | GPS 기록 시 사업장 반경 내 여부 검증 (Haversine 공식) |
### 5.2 상태 자동 판정
```
출근 시간 기록 시:
├── WorkSetting.start_time 이전 → 상태: 'onTime' (정시출근)
├── WorkSetting.start_time 이후 → 상태: 'late' (지각)
└── WorkSetting 미설정 → 상태: 'onTime' (기본값)
```
### 5.3 근무시간 계산
```
총 근무시간 = (가장 늦은 퇴근시간 - 가장 빠른 출근시간) - 휴게시간
휴게시간 산출:
├── WorkSetting에 break_start/break_end 설정 있음
│ └── 근무시간이 휴게 시간대를 포함하면 차감
└── 미설정 → 휴게시간 0분
```
### 5.4 권한
| 역할 | 조회 | 등록 | 수정 | 삭제 |
|------|:----:|:----:|:----:|:----:|
| 관리자 (admin) | ✅ 전체 | ✅ | ✅ | ✅ |
| 부서장 | ✅ 소속 부서 | ✅ | ✅ | ❌ |
| 일반 사원 | ✅ 본인 | ❌ | ❌ | ❌ |
---
## 6. 기능 목록
### 6.1 1차 구현 (완료)
| 기능 | 상태 | 설명 |
|------|:----:|------|
| 근태 목록 조회 | ✅ | 페이지네이션, 필터링, HTMX 테이블 |
| 근태 등록/수정 | ✅ | 모달 기반 CRUD |
| 근태 삭제 | ✅ | Soft Delete + 확인 대화상자 |
| 월별 통계 카드 | ✅ | 정시/지각/결근/휴가/기타 집계 |
| 필터링 | ✅ | 사원명 검색, 부서/상태/날짜 범위 필터 |
| 출근/퇴근 기록 API | ✅ | check-in/check-out 엔드포인트 |
| 근무시간 자동 계산 | ✅ | 출퇴근 시간 차 - 휴게시간 |
| 상태 자동 판정 | ✅ | WorkSetting 기준 지각/정시 판별 |
| 엑셀 내보내기 | ✅ | 월별 데이터 Excel 다운로드 |
| GPS 설정 | ✅ | 사업장 좌표, 허용 반경 설정 |
| 다중 출퇴근 기록 | ✅ | check_ins/check_outs 배열 관리 |
| 감사 로그 | ✅ | created_by, updated_by, deleted_by |
### 6.2 2차 고도화 (예정)
| 기능 | 우선순위 | 설명 |
|------|:--------:|------|
| 월간 캘린더 뷰 | 🔴 높음 | 달력 형태로 사원별 근태 현황 표시 |
| 일괄 등록 | 🔴 높음 | 다수 사원의 근태를 한 번에 등록 (CSV/엑셀 업로드) |
| 근태 승인 워크플로우 | 🟡 중간 | 휴가/출장 신청 → 부서장 승인 → 확정 |
| 초과근무 알림 | 🟡 중간 | 주 52시간 초과 시 관리자 알림 |
| 사원별 월간 요약 | 🟡 중간 | 개인별 월간 근무일수, 총 근무시간, 지각 횟수 등 |
| GPS 출퇴근 (모바일) | 🟢 낮음 | 모바일 앱에서 GPS 기반 자동 출퇴근 |
| 자동 결근 처리 | 🟢 낮음 | 영업일에 출근 기록 없으면 자동으로 결근 표시 |
| 연차 관리 연동 | 🟢 낮음 | 휴가 상태 등록 시 잔여 연차 자동 차감 |
---
## 7. API 엔드포인트
### 7.1 MNG 내부 API (HTMX)
| Method | Path | 설명 |
|--------|------|------|
| GET | `/api/admin/hr/attendances` | 목록 조회 (HTML/JSON) |
| POST | `/api/admin/hr/attendances` | 등록 |
| PUT | `/api/admin/hr/attendances/{id}` | 수정 |
| DELETE | `/api/admin/hr/attendances/{id}` | 삭제 |
### 7.2 외부 API (sam/api)
| Method | Path | 설명 |
|--------|------|------|
| GET | `/api/v1/attendances` | 목록 조회 (페이지네이션) |
| GET | `/api/v1/attendances/{id}` | 상세 조회 |
| POST | `/api/v1/attendances` | 등록 |
| PATCH | `/api/v1/attendances/{id}` | 수정 |
| DELETE | `/api/v1/attendances/{id}` | 삭제 |
| POST | `/api/v1/attendances/bulk-delete` | 일괄 삭제 |
| POST | `/api/v1/attendances/check-in` | 출근 기록 |
| POST | `/api/v1/attendances/check-out` | 퇴근 기록 |
| GET | `/api/v1/attendances/monthly-stats` | 월별 통계 |
| GET | `/api/v1/attendances/export` | 엑셀 내보내기 |
---
## 8. 프로세스 흐름
### 8.1 관리자 근태 등록
```
관리자 → [근태 등록] 클릭 → 모달 열림
→ 사원 선택, 날짜·상태·시간 입력
→ [저장] 클릭
→ Fetch POST /api/admin/hr/attendances
→ 같은 날짜+사용자 기존 기록 있으면 Upsert
→ 성공 → 테이블 HTMX 새로고침
```
### 8.2 사원 출근 (API)
```
사원(모바일) → [출근] 버튼
→ POST /api/v1/attendances/check-in
{ user_id, check_in_time, gps? }
→ 서버: WorkSetting.start_time 기준 지각/정시 판정
→ 기존 기록 없으면 신규 생성
→ 기존 기록 있으면 check_ins 배열에 추가
→ 응답: 근태 레코드 반환
```
### 8.3 사원 퇴근 (API)
```
사원(모바일) → [퇴근] 버튼
→ POST /api/v1/attendances/check-out
{ user_id, check_out_time, gps? }
→ 서버: 근무시간 자동 계산
(가장 빠른 출근 ~ 가장 늦은 퇴근) - 휴게시간
→ check_outs 배열에 추가
→ work_minutes, overtime_minutes 업데이트
→ 응답: 근태 레코드 반환
```
---
## 9. 관련 파일
### MNG
| 파일 | 설명 |
|------|------|
| `app/Http/Controllers/HR/AttendanceController.php` | 페이지 렌더링 |
| `app/Http/Controllers/Api/Admin/HR/AttendanceController.php` | HTMX API |
| `app/Models/HR/Attendance.php` | 모델 (Accessor 포함) |
| `app/Services/HR/AttendanceService.php` | 비즈니스 로직 |
| `resources/views/hr/attendances/index.blade.php` | 메인 페이지 |
| `resources/views/hr/attendances/partials/table.blade.php` | 테이블 partial |
### API
| 파일 | 설명 |
|------|------|
| `app/Http/Controllers/Api/V1/AttendanceController.php` | RESTful API |
| `app/Models/Tenants/Attendance.php` | 모델 |
| `app/Models/Tenants/AttendanceSetting.php` | GPS/자동 설정 |
| `app/Services/AttendanceService.php` | 서비스 (642줄) |
| `database/migrations/2025_12_09_*` | 테이블 생성 |
### 문서
| 파일 | 설명 |
|------|------|
| `docs/rules/attendance-api.md` | API 비즈니스 규칙 |
| `docs/system/erp-analysis/03-gps-attendance.md` | GPS 출퇴근 스펙 |
| `docs/system/erp-analysis/04-hr-management.md` | HR 시스템 분석 |
---
**최종 업데이트**: 2026-02-26

1003
docs/features/hr/hr-api-analysis.md Normal file
View File

File diff suppressed because it is too large Load Diff

455
docs/features/quotes/README.md Normal file
View File

@@ -0,0 +1,455 @@
# 견적 시스템 분석 문서
> **목적**: 견적 시스템의 비즈니스 로직과 데이터 흐름을 이해하고 검증하기 위한 문서
## 목차
1. [개요](#1-개요)
2. [데이터베이스 구조](#2-데이터베이스-구조)
3. [견적 생성 흐름](#3-견적-생성-흐름)
4. [BOM 계산 로직 (10단계)](#4-bom-계산-로직-10단계)
5. [경동기업 전용 로직](#5-경동기업-전용-로직)
6. [상태 관리](#6-상태-관리)
7. [금액 계산 방식](#7-금액-계산-방식)
8. [관련 파일 목록](#8-관련-파일-목록)
---
## 1. 개요
### 1.1 견적 유형
| 유형 | 코드 | 설명 |
|------|------|------|
| 제조 견적 | `manufacturing` | 스크린/철재 제품 제조 견적 |
| 시공 견적 | `construction` | 현장설명회 기반 시공 견적 |
### 1.2 제품 카테고리
| 카테고리 | 코드 | 설명 |
|----------|------|------|
| 스크린 | `SCREEN` | 방화 스크린 제품 |
| 철재 | `STEEL` | 철재 제품 |
### 1.3 핵심 서비스 클래스
```
QuoteService ← 견적 CRUD, 상태 관리, 수주 전환
├── QuoteNumberService ← 견적번호 생성 (KD-SC-YYMMDD-NN)
├── QuoteCalculationService ← 자동산출 실행, BOM 계산 호출
└── FormulaEvaluatorService ← 수식 평가, 10단계 BOM 계산
└── KyungdongFormulaHandler ← 경동기업(tenant_id=287) 전용 계산
```
---
## 2. 데이터베이스 구조
### 2.1 테이블 관계도
```
┌─────────────────┐
│ quotes │ ← 견적 마스터
├─────────────────┤
│ id │
│ tenant_id │──→ tenants
│ quote_number │
│ quote_type │ ← manufacturing | construction
│ status │ ← pending→draft→finalized→converted
│ client_id │──→ clients
│ item_id │──→ items (완제품)
│ site_briefing_id│──→ site_briefings (시공 견적용)
│ order_id │──→ orders (수주 전환 후)
│ calculation_inputs (JSON) │ ← 자동산출 입력값 + BOM 결과
│ options (JSON) │ ← 세부산출, 비용항목, 할인 정보
└────────┬────────┘
│ 1:N
▼
┌─────────────────┐
│ quote_items │ ← 견적 품목 상세
├─────────────────┤
│ id │
│ quote_id │──→ quotes
│ tenant_id │
│ item_id │──→ items
│ item_code │
│ item_name │
│ calculated_quantity │
│ unit_price │
│ total_price │
│ formula │ ← 수량 계산 수식
│ formula_category│ ← 카테고리 (material/labor/install)
└─────────────────┘
┌─────────────────┐
│ quote_revisions │ ← 수정 이력
├─────────────────┤
│ quote_id │──→ quotes
│ revision_number │
│ previous_data (JSON) │ ← 수정 전 스냅샷
└─────────────────┘
```
### 2.2 quotes 테이블 주요 필드
| 필드명 | 타입 | 설명 |
|--------|------|------|
| `quote_number` | VARCHAR(50) | 견적번호 (예: KD-SC-251204-01) |
| `quote_type` | ENUM | `manufacturing` / `construction` |
| `status` | ENUM | 상태 (pending→draft→finalized→converted) |
| `product_category` | ENUM | `SCREEN` / `STEEL` |
| `open_size_width` | INT | 개구부 폭 (mm) |
| `open_size_height` | INT | 개구부 높이 (mm) |
| `quantity` | INT | 수량 |
| `material_cost` | DECIMAL | 재료비 합계 |
| `labor_cost` | DECIMAL | 노무비 |
| `install_cost` | DECIMAL | 설치비 |
| `subtotal` | DECIMAL | 소계 |
| `discount_rate` | DECIMAL | 할인율 (%) |
| `total_amount` | DECIMAL | 최종 금액 |
| `calculation_inputs` | JSON | 자동산출 입력값 및 BOM 결과 저장 |
| `options` | JSON | 세부산출항목, 비용항목, 할인정보 |
| `is_final` | BOOLEAN | 최종확정 여부 |
### 2.3 calculation_inputs JSON 구조
```json
{
"items": [
{
"floor": "B1",
"code": "A-01",
"openWidth": 3000,
"openHeight": 2500,
"quantity": 2,
"productCategory": "SCREEN",
"productName": "KD-SCREEN-001",
"guideRailType": "wall",
"motorPower": "single"
}
],
"bomResults": [
{
"index": 0,
"finished_goods_code": "KD-SCREEN-001",
"items": [
{
"item_code": "GUIDE-001",
"item_name": "가이드레일",
"quantity": 2.5,
"unit_price": 50000,
"total_price": 125000,
"is_manual": false
}
],
"grand_total": 1250000
}
]
}
```
---
## 3. 견적 생성 흐름
### 3.1 제조 견적 생성 흐름
```
[프론트엔드 - React]
│
▼
1. 기본정보 입력 (거래처, 현장, 제품카테고리)
│
▼
2. 위치별 규격 입력 (층/부호, 개구부 크기, 수량)
│
▼
3. "견적 산출" 버튼 클릭
│
▼
[API 호출: POST /api/v1/quotes/bom/calculate-bulk]
│
▼
4. QuoteCalculationService.calculateBomBulk()
│
├─→ 경동기업(287)? → KyungdongFormulaHandler
│
└─→ 기타 테넌트 → 표준 BOM 계산
│
▼
5. 10단계 계산 결과 반환
│
▼
6. 프론트엔드에서 결과 표시 (세부산출내역)
│
▼
7. "저장" 또는 "최종확정" 버튼
│
▼
[API 호출: POST /api/v1/quotes 또는 PUT /api/v1/quotes/{id}]
│
▼
8. QuoteService.store() / update()
- quotes 테이블에 마스터 정보 저장
- quote_items 테이블에 품목 상세 저장
- calculation_inputs에 입력값 + BOM 결과 저장
```
### 3.2 시공 견적 생성 흐름 (현장설명회 연계)
```
[현장설명회]
│
▼
1. 현장설명회 참석완료 상태 변경
│
▼
2. QuoteService.upsertFromSiteBriefing()
│
▼
3. 견적 자동 생성 (status: pending)
- 거래처, 현장 정보 복사
- 금액 정보는 비어있음
│
▼
4. 담당자가 견적 편집 화면에서 상세 입력
│
▼
5. 저장 시 status: pending → draft 변경
```
---
## 4. BOM 계산 로직 (10단계)
### 4.1 계산 단계 개요
| 단계 | 명칭 | 설명 |
|------|------|------|
| 1 | 입력값수집 | W0, H0, QTY, 옵션값 수집 |
| 2 | 완제품선택 | 완제품 코드로 items 테이블 조회 |
| 3 | 변수계산 | W1, H1, AREA, WEIGHT 등 파생 변수 계산 |
| 4 | BOM전개 | 완제품의 BOM 트리 전개 |
| 5 | 단가출처 | 품목별 단가 조회 (prices 테이블) |
| 6 | 수량계산 | 수량 수식 평가 (변수 치환) |
| 7 | 금액계산 | 수량 × 단가 = 금액 |
| 8 | 카테고리그룹화 | item_category 기준 그룹화 |
| 9 | 소계계산 | 카테고리별 소계 |
| 10 | 최종합계 | 전체 합계 계산 |
### 4.2 변수 계산 (Step 3) 상세
```
기본 변수:
- W0: 개구부 폭 (mm) - 사용자 입력
- H0: 개구부 높이 (mm) - 사용자 입력
- QTY: 수량 - 사용자 입력
파생 변수 (스크린):
- W1 = W0 + 140 (제작 폭, 마진 140mm)
- H1 = H0 + 350 (제작 높이, 마진 350mm)
- M = (W1 × H1) / 1,000,000 (면적, ㎡)
- K = M × 2 + (W0 / 1000) × 14.17 (중량, kg)
파생 변수 (철재):
- W1 = W0 + 110 (마진 110mm)
- H1 = H0 + 350
- M = (W1 × H1) / 1,000,000
- K = M × 25 (철재 중량)
```
### 4.3 수량 수식 예시
BOM의 quantity_formula 필드에 저장된 수식:
```
고정값: "1"
변수참조: "QTY"
계산식: "W1 / 1000" → 가이드레일 길이
"CEIL(H1 / 2000)" → 분할 개수
"M * 1.1" → 면적 기반 수량 (여유 10%)
```
---
## 5. 경동기업 전용 로직
### 5.1 적용 조건
```php
// tenant_id = 287 일 때만 적용
private const KYUNGDONG_TENANT_ID = 287;
if ($tenantId === self::KYUNGDONG_TENANT_ID) {
return $this->calculateKyungdongBom(...);
}
```
### 5.2 KyungdongFormulaHandler 주요 기능
| 기능 | 설명 |
|------|------|
| 모터 용량 계산 | 제품타입 × 인치 × 중량 3차원 조건표 |
| 브라켓 크기 결정 | 중량 기준 브라켓 인치 결정 |
| 절곡품 계산 | 10종 절곡품 (케이스, 가이드레일, 하단바 등) |
| 부자재 계산 | 3종 부자재 (볼트, 너트, 패킹 등) |
### 5.3 경동기업 변수 계산
```
기본 변수:
- W0, H0, QTY: 사용자 입력
- bracket_inch: 브라켓 인치 (5", 6", 7")
- product_type: 제품 타입 (screen/steel)
파생 변수:
- W1 = W0 + 140
- H1 = H0 + 350
- AREA = (W0 × (H0 + 550)) / 1,000,000
- WEIGHT = AREA × 2 + (W0 / 1000) × 14.17 (스크린)
= AREA × 25 (철재)
- MOTOR_CAPACITY: 모터 용량 (조건표 조회)
- BRACKET_SIZE: 브라켓 크기 (조건표 조회)
```
---
## 6. 상태 관리
### 6.1 견적 상태 흐름
```
pending ─────→ draft ─────→ finalized ─────→ converted
(견적대기) (작성중) (최종확정) (수주전환)
│ │ │
│ ▼ │
│ sent ────────────→│
│ (발송됨) │
│ │ │
│ ▼ │
│ approved │
│ (승인됨) │
│ │ │
└──────────────┴──────────────┘
│
▼
rejected
(거절됨)
```
### 6.2 상태별 가능 작업
| 상태 | 수정 | 삭제 | 확정 | 수주전환 |
|------|------|------|------|----------|
| pending | ✓ | ✓ | - | - |
| draft | ✓ | ✓ | ✓ | - |
| sent | ✓ | ✓ | ✓ | - |
| approved | ✓ | ✓ | ✓ | - |
| finalized | - | - | - | ✓ |
| converted | - | - | - | - |
| rejected | ✓ | ✓ | - | - |
---
## 7. 금액 계산 방식
### 7.1 카테고리 기반 단가 계산
CategoryGroup 모델을 사용하여 품목 카테고리별 단가 계산 방식 결정:
| 카테고리 그룹 | 계산 방식 | 수식 |
|--------------|----------|------|
| area_based | 면적 기반 | 단가 × M (면적) |
| weight_based | 중량 기반 | 단가 × K (중량) |
| quantity_based | 수량 기반 | 단가 × 수량 |
### 7.2 총 금액 계산
```
material_cost = SUM(재료비 카테고리 품목의 total_price)
labor_cost = SUM(노무비 카테고리 품목의 total_price)
install_cost = SUM(설치비 카테고리 품목의 total_price)
subtotal = material_cost + labor_cost + install_cost
discount_amount = subtotal × (discount_rate / 100)
total_amount = subtotal - discount_amount
```
### 7.3 단가 조회 우선순위
1. **prices 테이블** (Price::getSalesPriceByItemCode)
2. **items.attributes.salesPrice** (JSON 필드)
3. **기본값 0**
---
## 8. 관련 파일 목록
### 8.1 백엔드 (API)
```
app/Services/Quote/
├── QuoteService.php ← 견적 CRUD, 상태 관리
├── QuoteCalculationService.php ← BOM 계산 진입점
├── QuoteNumberService.php ← 견적번호 생성
├── QuoteDocumentService.php ← 견적서/거래명세서 PDF
├── FormulaEvaluatorService.php ← 수식 평가, 10단계 계산
└── Handlers/
└── KyungdongFormulaHandler.php ← 경동기업 전용
app/Models/Quote/
├── Quote.php ← 견적 마스터 모델
├── QuoteItem.php ← 견적 품목 모델
├── QuoteRevision.php ← 수정 이력 모델
├── QuoteFormula.php ← 수식 정의 모델
├── QuoteFormulaCategory.php
├── QuoteFormulaRange.php
├── QuoteFormulaMapping.php
└── QuoteFormulaItem.php
database/migrations/
├── 2025_12_04_164542_create_quotes_table.php
└── 2025_12_04_133410_create_quote_formula_tables.php
```
### 8.2 프론트엔드 (React)
```
react/src/components/quotes/
├── types.ts ← 타입 정의 (LocationItem, BomCalculationResult)
├── actions.ts ← API 액션 (calculateBomBulk)
├── QuoteFooterBar.tsx ← 하단 버튼바 (견적서보기, 저장, 최종확정)
├── FormulaViewModal.tsx ← 수식 보기 모달 (개발용)
└── ...
```
---
## 9. 검증 체크리스트
### 9.1 데이터 정합성 검증
- [ ] quotes.total_amount = subtotal - discount_amount
- [ ] quotes.subtotal = material_cost + labor_cost + install_cost
- [ ] quote_items의 합계 = quotes의 비용 합계
- [ ] calculation_inputs.bomResults의 grand_total = 품목 합계
### 9.2 상태 전이 검증
- [ ] pending → draft: 첫 수정 시 자동 전환
- [ ] draft → finalized: 확정 버튼 클릭 + total_amount > 0
- [ ] finalized → converted: 수주 전환 시 + order_id 설정
### 9.3 BOM 계산 검증
- [ ] W1 = W0 + 마진값 (SCREEN: 140, STEEL: 110)
- [ ] H1 = H0 + 350
- [ ] 면적(M) = (W1 × H1) / 1,000,000
- [ ] 중량(K) 계산식 제품타입별 확인
- [ ] 수량 수식의 변수 치환 정확성
- [ ] 단가 조회 우선순위 준수
---
*문서 작성일: 2026-01-29*
*작성자: Claude Code*

128
docs/features/sales/README.md Normal file
View File

@@ -0,0 +1,128 @@
# 영업/매출관리
## 개요
영업/매출관리 모듈은 영업파트너 관리, 고객 영업권, 상품 관리, 인터뷰 시나리오 등
영업 전체 프로세스를 관리하는 기능 그룹입니다.
- **라우트 Prefix**: `/sales`
- **미들웨어**: `auth`, `hq.member` (본사 회원 전용)
- **UI 기술**: Blade + HTMX + Alpine.js (일부 React)
## 메뉴 구성
| # | 메뉴명 | 경로 | 문서 | 상태 |
|---|--------|------|------|------|
| 1 | 영업관리 대시보드 | `/sales/salesmanagement/dashboard` | [sales-dashboard.md](sales-dashboard.md) | 구현완료 |
| 2 | 파트너관리 | `/sales/managers` | [partners.md](partners.md) | 구현완료 |
| 3 | 영업파트너승인 | `/sales/managers/approvals` | [partner-approvals.md](partner-approvals.md) | 구현완료 |
| 4 | 상품관리 | `/sales/products` | [products.md](products.md) | 구현완료 |
| 5 | 세일즈사이트 | (외부 링크) | - | 미구현 |
| 6 | 랜딩페이지 | (외부 링크) | - | 미구현 |
| 7 | 고객 관리 | `/sales/admin-prospects` | [admin-prospects.md](admin-prospects.md) | 구현완료 |
| 8 | 영업파트너 고객관리 | `/sales/prospects` | [prospects.md](prospects.md) | 구현완료 |
| 9 | 인터뷰 시나리오 | `/sales/interviews` | [interviews.md](interviews.md) | 구현완료 |
## 아키텍처
```
영업/매출관리
├── 대시보드 ──── 수당 현황, 테넌트 진행률, 파트너 활동
├── 파트너관리
│ ├── 파트너 CRUD ──── 영업파트너 등록/수정/역할 관리
│ └── 파트너 승인 ──── 신규 파트너 신청 승인/반려
├── 상품관리 ──── 카테고리별 상품, 가격/수당률 설정
├── 고객관리
│ ├── 고객 관리(관리자) ──── 전사 고객 현황, 본사 진행상태
│ └── 파트너 고객관리 ──── 명함등록 기반 영업권 관리
└── 인터뷰 시나리오 ──── 질문 템플릿, 인터뷰 세션 기록
```
## 파일 구조
```
mng/
├── app/Http/Controllers/Sales/
│ ├── SalesDashboardController.php # 영업관리 대시보드
│ ├── SalesManagerController.php # 파트너관리 + 승인
│ ├── SalesProductController.php # 상품관리
│ ├── TenantProspectController.php # 영업권(명함등록) 관리
│ ├── AdminProspectController.php # 관리자 전체 고객 관리
│ └── InterviewScenarioController.php # 인터뷰 시나리오
├── app/Models/Sales/
│ ├── SalesPartner.php # 영업파트너
│ ├── SalesTenantManagement.php # 테넌트 영업 관리
│ ├── TenantProspect.php # 가망고객 (영업권)
│ ├── SalesCommission.php # 영업 수수료
│ ├── SalesProduct.php # 영업 상품
│ ├── SalesProductCategory.php # 상품 카테고리
│ └── SalesManagerDocument.php # 파트너 서류
├── app/Models/Interview/
│ ├── InterviewCategory.php # 인터뷰 카테고리
│ ├── InterviewTemplate.php # 인터뷰 템플릿
│ ├── InterviewQuestion.php # 인터뷰 질문
│ ├── InterviewSession.php # 인터뷰 세션
│ └── InterviewAnswer.php # 인터뷰 답변
├── app/Services/Sales/
│ ├── SalesManagerService.php # 파트너 관리 서비스
│ ├── TenantProspectService.php # 영업권 서비스
│ └── InterviewScenarioService.php # 인터뷰 서비스
└── resources/views/sales/
├── dashboard/ # 대시보드 뷰
├── managers/ # 파트너관리 뷰
├── products/ # 상품관리 뷰
├── prospects/ # 영업권 관리 뷰
├── admin-prospects/ # 관리자 고객관리 뷰
└── interviews/ # 인터뷰 시나리오 뷰
api/
└── database/migrations/
├── 2026_01_27_221000_create_tenant_prospects_table.php
├── 2026_01_28_090000_add_attachments_to_tenant_prospects_table.php
├── 2026_01_29_100000_create_sales_partners_table.php
├── 2026_01_29_100100_create_sales_tenant_managements_table.php
├── 2026_01_29_150000_create_sales_products_tables.php
└── 2026_02_06_10000x_create_interview_*_tables.php (5개)
```
## 핵심 데이터 모델 관계
```
User (영업파트너)
│
├── SalesPartner (파트너 정보, 수수료율, 계좌)
│
├── TenantProspect (영업권 = 명함등록)
│ ├── status: active → expired / converted / completed
│ ├── 유효기간: 2개월
│ └── 쿨다운: 만료 후 1개월
│ │
│ ↓ convert()
│ Tenant (계약 고객사)
│ │
│ ↓
│ SalesTenantManagement (영업 관리)
│ ├── status: prospect → approach → negotiation → contracted → onboarding → active
│ ├── hq_status: pending → review → planning → coding → dev_test → dev_done → int_test → handover
│ └── SalesCommission (수당 정보)
│
└── SalesManagerDocument (등록 서류)
SalesProductCategory
└── SalesProduct (개발비, 가입비, 구독료, 수당율)
└── SalesContractProduct (계약별 선택 상품)
InterviewCategory
└── InterviewTemplate
└── InterviewQuestion
└── InterviewSession → InterviewAnswer
```
## 권한 체계
| 역할 | 대시보드 | 파트너관리 | 승인 | 상품 | 고객관리 | 파트너고객 | 인터뷰 |
|------|---------|-----------|------|------|---------|-----------|--------|
| 영업파트너 | O (본인) | - | - | - | - | O (본인) | O |
| 상담매니저 | O (본인) | - | - | - | - | - | O |
| 관리자 | O (전체) | O | O | O | O | O | O |
| 슈퍼관리자 | O (전체) | O | O | O | O (삭제) | O | O |

155
docs/features/sales/admin-prospects.md Normal file
View File

@@ -0,0 +1,155 @@
# 고객 관리 (관리자)
## 개요
고객 관리(관리자)는 본사 관리자가 모든 영업파트너의 고객을 통합 관리하는 기능입니다.
전사 고객 현황 파악, 본사 진행상태 관리, 수당 지급 기록, 상태 변경을 지원합니다.
- **라우트**: `GET /sales/admin-prospects`
- **미들웨어**: `auth`, `hq.member` + 관리자 권한 체크
- **UI 기술**: Blade + HTMX + Tailwind CSS
## 파일 구조
```
mng/
├── app/Http/Controllers/Sales/
│ └── AdminProspectController.php # 메인 컨트롤러 (8개 메서드)
└── resources/views/sales/admin-prospects/
├── index.blade.php # 전체 고객 목록 (460줄)
└── partials/
├── content.blade.php # 콘텐츠 새로고침
└── show-modal.blade.php # 고객 상세 모달
```
## 라우트
```php
// routes/web.php (sales prefix 그룹 내)
GET /admin-prospects → index() 전체 고객 목록
GET /admin-prospects/refresh → refresh() HTMX 새로고침
GET /admin-prospects/{id}/modal-show → modalShow() 상세 모달
POST /admin-prospects/{id}/hq-status → updateHqStatus() 본사 진행상태 변경
POST /admin-prospects/{id}/commission-date → updateCommissionDate() 수당 날짜 기록
DELETE /admin-prospects/{id}/commission-date → clearCommissionDate() 수당 날짜 초기화
DELETE /admin-prospects/{id} → destroy() 삭제 (슈퍼관리자)
POST /admin-prospects/{id}/toggle-status → toggleStatus() 상태 토글
```
## 컨트롤러
### AdminProspectController
| 메서드 | HTTP | 설명 | 권한 |
|--------|------|------|------|
| `index()` | GET | 전체 고객 목록 (필터+통계) | 관리자/슈퍼관리자 |
| `refresh()` | GET | 콘텐츠 새로고침 (HTMX) | 관리자/슈퍼관리자 |
| `modalShow()` | GET | 고객 상세 모달 (진행률 포함) | 관리자/슈퍼관리자 |
| `updateHqStatus()` | POST | 본사 진행상태 변경 | 관리자/슈퍼관리자 |
| `updateCommissionDate()` | POST | 수당 지급 날짜 기록/수정 | 관리자/슈퍼관리자 |
| `clearCommissionDate()` | DELETE | 수당 날짜 초기화 | 관리자/슈퍼관리자 |
| `toggleStatus()` | POST | 상태 토글 (영업중 ↔ 완료) | 관리자/슈퍼관리자 |
| `destroy()` | DELETE | 삭제 | 슈퍼관리자 전용 |
### 본사 진행상태 (HQ Status) 8단계
```
pending (대기)
→ review (검토)
→ planning (기획안작성)
→ coding (개발코드작성)
→ dev_test (개발테스트)
→ dev_done (개발완료)
→ int_test (통합테스트)
→ handover (인계)
```
### 수당 날짜 관리
```
updateCommissionDate():
- 납입일(membership_paid_at) 입력 시
- 자동 지급일 계산: 익월 10일
- commission_paid_at 기록
```
## 모델
### SalesTenantManagement (핵심 모델)
**테이블**: `sales_tenant_managements`
| 필드 | 타입 | 설명 |
|------|------|------|
| `tenant_id` | bigint (FK, unique) | 테넌트 ID (1:1) |
| `tenant_prospect_id` | bigint (FK) | 가망고객 ID |
| `sales_partner_id` | bigint (FK) | 영업 담당자 ID |
| `manager_user_id` | bigint (FK) | 상담매니저 사용자 ID |
| `sales_scenario_step` | int | 영업 시나리오 단계 (1-6) |
| `manager_scenario_step` | int | 매니저 시나리오 단계 (1-6) |
| `status` | enum | 영업 상태 |
| `hq_status` | enum | 본사 진행상태 |
| `first_contact_at` | timestamp | 최초 접촉일 |
| `contracted_at` | timestamp | 계약 체결일 |
| `onboarding_completed_at` | timestamp | 온보딩 완료일 |
| `membership_fee` | decimal | 가입비 |
| `membership_paid_at` | timestamp | 가입비 입금일 |
| `membership_status` | enum | pending / partial / paid / refunded |
| `sales_commission` | decimal | 영업 수당 |
| `manager_commission` | decimal | 관리 수당 |
| `commission_paid_at` | timestamp | 수당 지급일 |
| `sales_progress` | tinyint | 영업 진행률 (%) |
| `manager_progress` | tinyint | 매니저 진행률 (%) |
| `incentive_status` | enum | pending / eligible / paid |
| `notes` | text | 메모 |
#### 영업 상태 흐름
```
prospect (잠재) → approach (접근) → negotiation (협상)
→ contracted (계약) → onboarding (온보딩) → active (활성) / churned (이탈)
```
#### 수당 상태
```
pending (대기) → eligible (지급대상) → paid (지급완료)
```
## 뷰 구성
### index.blade.php
```
┌─ 페이지 헤더 ──────────────────────
│ 제목: "고객 관리"
│ [새로고침] 버튼
│
├─ 통계 카드 ────────────────────────
│ 전체 | 활성 | 완료 | 인계완료
│
├─ 필터 영역 ────────────────────────
│ 검색 (회사명, 사업자번호, 대표자, 연락처)
│ 상태: active / expired / converted / progress_complete
│ 인계: hq_status = 'handover'
│ 영업파트너: registered_by 필터
│
├─ 고객 목록 테이블 ────────────────
│ 회사명 | 사업자번호 | 대표자 | 영업파트너
│ 영업진행률 | 매니저진행률 | 본사상태 | 작업
│ └─ 본사상태: 8단계 프로그레스바
│ └─ 작업: 상세, 상태변경, 삭제
│
└─ 상세 모달 ───────────────────────
기본 정보 (회사명, 사업자번호, 대표자, 연락처)
영업 진행률 (영업 시나리오, 매니저 시나리오)
본사 진행상태 (8단계 프로그레스바 + 변경 드롭다운)
수당 정보 (납입일, 지급일, 자동 계산)
담당 매니저 정보
```
## HTMX 호환성
- Blade + HTMX 기반으로 **HX-Redirect 불필요**
- `hx-get`으로 부분 새로고침
- 모달로 상세 조회 및 상태 변경

281
docs/features/sales/interviews.md Normal file
View File

@@ -0,0 +1,281 @@
# 인터뷰 시나리오
## 개요
인터뷰 시나리오는 영업 상담 시 사용할 질문 템플릿을 관리하고,
인터뷰 세션을 진행/기록하는 기능입니다.
카테고리별 질문 구조, 체크리스트/텍스트 답변, MD 일괄 가져오기를 지원합니다.
- **라우트**: `GET /sales/interviews`
- **미들웨어**: `auth`, `hq.member`
- **UI 기술**: Blade + React/JavaScript (API 기반, 1,076줄)
## 파일 구조
```
mng/
├── app/Http/Controllers/Sales/
│ └── InterviewScenarioController.php # 메인 컨트롤러 (16개 메서드)
├── app/Services/Sales/
│ └── InterviewScenarioService.php # 비즈니스 로직 서비스
├── app/Models/Interview/
│ ├── InterviewCategory.php # 카테고리
│ ├── InterviewTemplate.php # 템플릿 (항목)
│ ├── InterviewQuestion.php # 질문
│ ├── InterviewSession.php # 인터뷰 세션
│ └── InterviewAnswer.php # 답변
└── resources/views/sales/interviews/
└── index.blade.php # 메인 페이지 (1,076줄)
api/
└── database/migrations/
├── 2026_02_06_100000_create_interview_categories_table.php
├── 2026_02_06_100001_create_interview_templates_table.php
├── 2026_02_06_100002_create_interview_questions_table.php
├── 2026_02_06_100003_create_interview_sessions_table.php
└── 2026_02_06_100004_create_interview_answers_table.php
```
## 라우트
```php
// routes/web.php (sales/interviews prefix 그룹 내)
// 페이지
GET /interviews → index() 메인 페이지
// 카테고리 API
GET /interviews/api/categories → categories() 카테고리 목록
POST /interviews/api/categories → storeCategory() 카테고리 생성
PUT /interviews/api/categories/{id} → updateCategory() 카테고리 수정
DELETE /interviews/api/categories/{id} → destroyCategory() 카테고리 삭제
// 트리 API
GET /interviews/api/tree → tree() 전체 계층 구조
// 템플릿(항목) API
POST /interviews/api/templates → storeTemplate() 템플릿 생성
PUT /interviews/api/templates/{id} → updateTemplate() 템플릿 수정
DELETE /interviews/api/templates/{id} → destroyTemplate() 템플릿 삭제
// 질문 API
POST /interviews/api/questions → storeQuestion() 질문 생성
PUT /interviews/api/questions/{id} → updateQuestion() 질문 수정
DELETE /interviews/api/questions/{id} → destroyQuestion() 질문 삭제
// 일괄 가져오기
POST /interviews/api/bulk-import → bulkImport() MD 파일에서 가져오기
// 세션(인터뷰) API
GET /interviews/api/sessions → sessions() 세션 목록 (필터)
POST /interviews/api/sessions → storeSession() 인터뷰 시작
GET /interviews/api/sessions/{id} → showSession() 세션 상세
POST /interviews/api/sessions/toggle-answer → toggleAnswer() 답변 토글
POST /interviews/api/sessions/{id}/complete → completeSession() 인터뷰 완료
```
## 컨트롤러
### InterviewScenarioController
| 메서드 | HTTP | 설명 |
|--------|------|------|
| `index()` | GET | 메인 페이지 |
| `categories()` | GET | 카테고리 목록 |
| `storeCategory()` | POST | 카테고리 생성 |
| `updateCategory()` | PUT | 카테고리 수정 |
| `destroyCategory()` | DELETE | 카테고리 삭제 |
| `tree()` | GET | 전체 계층 구조 (카테고리→템플릿→질문) |
| `storeTemplate()` | POST | 템플릿 생성 |
| `updateTemplate()` | PUT | 템플릿 수정 |
| `destroyTemplate()` | DELETE | 템플릿 삭제 |
| `storeQuestion()` | POST | 질문 생성 |
| `updateQuestion()` | PUT | 질문 수정 |
| `destroyQuestion()` | DELETE | 질문 삭제 |
| `bulkImport()` | POST | MD 파일에서 일괄 가져오기 |
| `sessions()` | GET | 인터뷰 세션 목록 |
| `storeSession()` | POST | 인터뷰 시작 |
| `showSession()` | GET | 세션 상세 |
| `toggleAnswer()` | POST | 답변 토글/기록 |
| `completeSession()` | POST | 인터뷰 완료 |
### InterviewScenarioService
| 메서드 | 설명 |
|--------|------|
| `getCategories()` | 카테고리 목록 |
| `createCategory()` | 카테고리 생성 |
| `updateCategory()` | 카테고리 수정 |
| `deleteCategory()` | 카테고리 삭제 |
| `getTree()` | 전체 계층 구조 조회 |
| `createTemplate()` | 템플릿 생성 |
| `updateTemplate()` | 템플릿 수정 |
| `deleteTemplate()` | 템플릿 삭제 |
| `createQuestion()` | 질문 생성 |
| `updateQuestion()` | 질문 수정 |
| `deleteQuestion()` | 질문 삭제 |
| `bulkImport()` | MD에서 일괄 가져오기 |
| `getSessions()` | 세션 목록 (필터) |
| `startSession()` | 인터뷰 시작 |
| `getSessionDetail()` | 세션 상세 |
| `toggleAnswer()` | 답변 토글 |
| `completeSession()` | 인터뷰 완료 |
## 모델
### 데이터 계층 구조
```
InterviewCategory (카테고리)
└── InterviewTemplate (템플릿/항목)
└── InterviewQuestion (질문)
InterviewSession (인터뷰 세션)
└── InterviewAnswer (답변)
```
### InterviewCategory
**테이블**: `interview_categories`
| 필드 | 타입 | 설명 |
|------|------|------|
| `tenant_id` | bigint | 테넌트 ID |
| `name` | string | 카테고리명 (예: 제조-방화셔터) |
| `description` | text | 설명 |
| `sort_order` | int | 정렬 순서 |
| `is_active` | boolean | 활성 여부 |
| `created_by` | bigint | 등록자 |
- SoftDeletes 적용
- 관계: `templates()`, `sessions()`
### InterviewTemplate
**테이블**: `interview_templates`
| 필드 | 타입 | 설명 |
|------|------|------|
| `tenant_id` | bigint | 테넌트 ID |
| `interview_category_id` | bigint (FK) | 카테고리 ID |
| `name` | string | 항목명 (예: 견적서 제작) |
| `description` | text | 설명 |
| `sort_order` | int | 정렬 순서 |
| `is_active` | boolean | 활성 여부 |
- SoftDeletes 적용
- 관계: `category()`, `questions()`
### InterviewQuestion
**테이블**: `interview_questions`
| 필드 | 타입 | 설명 |
|------|------|------|
| `tenant_id` | bigint | 테넌트 ID |
| `interview_template_id` | bigint (FK) | 템플릿 ID |
| `question_text` | string(500) | 질문 텍스트 |
| `question_type` | string | **checkbox** / **text** |
| `options` | json | 선택지 (배열) |
| `is_required` | boolean | 필수 여부 |
| `sort_order` | int | 정렬 순서 |
| `is_active` | boolean | 활성 여부 |
- SoftDeletes 적용
- 관계: `template()`
#### 질문 타입
| 타입 | 설명 | 답변 방식 |
|------|------|----------|
| `checkbox` | 체크 질문 | is_checked 토글 |
| `text` | 서술형 질문 | answer_text 입력 |
### InterviewSession
**테이블**: `interview_sessions`
| 필드 | 타입 | 설명 |
|------|------|------|
| `tenant_id` | bigint | 테넌트 ID |
| `interview_category_id` | bigint (FK) | 사용한 카테고리 ID |
| `interviewer_id` | bigint (FK) | 면담자(매니저) ID |
| `interviewee_name` | string(100) | 면담 상대 이름 |
| `interviewee_company` | string(200) | 면담 상대 회사 |
| `interview_date` | date | 면담 일자 |
| `status` | string | **in_progress** / **completed** |
| `total_questions` | int | 총 질문 수 |
| `answered_questions` | int | 답변 완료 수 |
| `memo` | text | 메모 |
| `completed_at` | timestamp | 완료 일시 |
- SoftDeletes 적용
- 관계: `category()`, `interviewer()`, `answers()`
### InterviewAnswer
**테이블**: `interview_answers`
| 필드 | 타입 | 설명 |
|------|------|------|
| `tenant_id` | bigint | 테넌트 ID |
| `interview_session_id` | bigint (FK) | 세션 ID |
| `interview_question_id` | bigint (FK) | 질문 ID |
| `interview_template_id` | bigint (FK) | 템플릿 ID |
| `is_checked` | boolean | 체크 여부 (checkbox 유형) |
| `answer_text` | text | 답변 텍스트 (text 유형) |
| `memo` | text | 메모 |
### 인터뷰 진행 흐름
```
1. 카테고리 선택 + 면담 상대 정보 입력
→ storeSession() → 세션 생성 (status: in_progress)
→ 해당 카테고리의 모든 질문에 대해 빈 Answer 생성
2. 질문별 답변 기록
→ toggleAnswer() → is_checked 토글 / answer_text 저장
→ answered_questions 카운트 갱신
3. 인터뷰 완료
→ completeSession() → status: completed, completed_at 기록
```
## 뷰 구성
### index.blade.php
```
┌─ 페이지 헤더 ──────────────────────
│ 제목: "인터뷰 시나리오"
│ [카테고리 추가] [일괄 가져오기] 버튼
│
├─ 좌측 사이드바 ───────────────────
│ 카테고리 트리
│ ├── 카테고리 A
│ │ ├── 템플릿 1 (질문 3개)
│ │ └── 템플릿 2 (질문 5개)
│ └── 카테고리 B
│ └── 템플릿 3 (질문 2개)
│
├─ 우측 메인 영역 ──────────────────
│ ├─ 템플릿 편집 모드
│ │ 질문 목록 + 추가/수정/삭제
│ │ 질문 타입(checkbox/text) + 옵션
│ │
│ └─ 인터뷰 세션 모드
│ 면담 상대 정보 + 날짜
│ 질문별 체크/답변 기록
│ 진행률 표시
│ [완료] 버튼
│
└─ 세션 목록 ───────────────────────
과거 인터뷰 기록 (필터: 카테고리, 날짜)
면담자 | 상대방 | 회사 | 날짜 | 완료율 | 상태
```
## HTMX 호환성
- JavaScript/React 기반 페이지이므로 **HX-Redirect 필요**
- API 호출로 동적 CRUD 관리
- `@push('scripts')` 블록에 스크립트 포함

102
docs/features/sales/partner-approvals.md Normal file
View File

@@ -0,0 +1,102 @@
# 영업파트너승인
## 개요
영업파트너승인은 신규 영업파트너 등록 신청을 검토하고 승인/반려를 처리하는 기능입니다.
본사 관리자 전용 페이지로, 신청자의 정보와 서류를 확인하고 일괄 처리할 수 있습니다.
- **라우트**: `GET /sales/managers/approvals`
- **미들웨어**: `auth`, `hq.member` + 관리자 권한 체크
- **UI 기술**: Blade + HTMX + Tailwind CSS
## 파일 구조
```
mng/
├── app/Http/Controllers/Sales/
│ └── SalesManagerController.php # 파트너관리와 동일 컨트롤러 (승인 메서드 포함)
├── app/Services/Sales/
│ └── SalesManagerService.php # approve(), reject() 로직
└── resources/views/sales/managers/
└── approvals.blade.php # 승인 관리 페이지
```
## 라우트
```php
// routes/web.php (sales prefix 그룹 내, resource 전에 정의)
GET /managers/approvals → approvals() 승인 목록 페이지
POST /managers/approvals/{id}/approve → approveFromList() 목록에서 승인
POST /managers/approvals/{id}/reject → rejectFromList() 목록에서 반려
```
## 컨트롤러
### SalesManagerController (승인 관련 메서드)
| 메서드 | HTTP | 설명 | 권한 |
|--------|------|------|------|
| `approvals()` | GET | 승인 대기 목록 페이지 | 관리자 전용 |
| `approveFromList()` | POST | 목록에서 승인 처리 | 관리자 전용 |
| `rejectFromList()` | POST | 목록에서 반려 처리 | 관리자 전용 |
| `approve()` | POST | 상세에서 승인 | - |
| `reject()` | POST | 상세에서 반려 | - |
### 승인 처리 흐름
```
영업파트너 등록 신청 (store)
↓
approval_status = 'pending' (Users 테이블)
↓
관리자 승인 목록에서 확인
├── approveFromList() → status = 'approved'
│ ├── approved_at 기록
│ └── approved_by 기록
│
└── rejectFromList() → status = 'rejected'
└── rejection_reason 저장 (필수)
```
### 응답 방식
```
HTMX 요청 → JsonResponse (success, message)
일반 요청 → Redirect (redirect back)
```
## 뷰 구성
### approvals.blade.php
```
┌─ 페이지 헤더 ──────────────────────
│ 제목: "영업파트너 승인관리"
│
├─ 통계 카드 ────────────────────────
│ 승인 대기 | 오늘 승인 | 오늘 반려
│
├─ 검색/필터 영역 ──────────────────
│ 검색 (이름, 아이디, 이메일, 전화번호)
│
├─ 2분할 레이아웃 ──────────────────
│ ┌─ 좌: 승인 대기 ────────────┐ ┌─ 우: 승인 완료 ─────────────┐
│ │ 신청자명 | 역할 | 유치자 │ │ 파트너명 | 승인일 | 승인자 │
│ │ └─ [승인] [반려] 버튼 │ │ │
│ └────────────────────────────┘ └─────────────────────────────┘
│
└─ 상세 모달 ───────────────────────
파트너 정보 (이름, 아이디, 이메일, 전화)
계층 정보 (레벨, 추천인)
등록 서류 목록 (다운로드/삭제)
[승인] [반려] 버튼
```
## 반려 처리
```
반려 시:
- rejection_reason (반려 사유) 필수 입력
- 상태: pending → rejected
- 반려 후 재신청 가능
```

166
docs/features/sales/partners.md Normal file
View File

@@ -0,0 +1,166 @@
# 파트너관리
## 개요
파트너관리는 영업파트너(판매자/매니저)의 등록, 수정, 역할 관리, 서류 관리를 수행하는 기능입니다.
파트너 등록 신청, 서류 업로드, 역할 부여/위임, 계층 구조(추천인) 관리를 지원합니다.
- **라우트**: `GET /sales/managers`
- **미들웨어**: `auth`, `hq.member`
- **UI 기술**: Blade + HTMX + Alpine.js + Tailwind CSS
## 파일 구조
```
mng/
├── app/Http/Controllers/Sales/
│ └── SalesManagerController.php # 메인 컨트롤러 (425줄)
├── app/Services/Sales/
│ └── SalesManagerService.php # 비즈니스 로직 서비스
├── app/Models/Sales/
│ ├── SalesPartner.php # 영업파트너 모델
│ └── SalesManagerDocument.php # 파트너 서류 모델
└── resources/views/sales/managers/
├── index.blade.php # 파트너 목록
├── create.blade.php # 등록 폼
├── show.blade.php # 상세 페이지
├── edit.blade.php # 수정 폼
└── partials/
├── show-modal.blade.php # 상세 모달
└── edit-modal.blade.php # 수정 모달
api/
└── database/migrations/
└── 2026_01_29_100000_create_sales_partners_table.php
```
## 라우트
```php
// routes/web.php (sales prefix 그룹 내)
// Resource 라우트
GET /managers → index() 파트너 목록
GET /managers/create → create() 등록 폼
POST /managers → store() 등록 처리
GET /managers/{id} → show() 상세 페이지
GET /managers/{id}/edit → edit() 수정 폼
PUT /managers/{id} → update() 수정 처리
DELETE /managers/{id} → destroy() 비활성화 (관리자)
// 추가 라우트
GET /managers/{id}/modal-show → modalShow() 상세 모달
GET /managers/{id}/modal-edit → modalEdit() 수정 모달
POST /managers/{id}/approve → approve() 승인
POST /managers/{id}/reject → reject() 반려
POST /managers/{id}/delegate-role → delegateRole() 역할 위임
POST /managers/{id}/assign-role → assignRole() 역할 부여
POST /managers/{id}/remove-role → removeRole() 역할 제거
GET /managers/{id}/documents/{docId}/download → downloadDocument() 서류 다운로드
DELETE /managers/{id}/documents/{docId} → deleteDocument() 서류 삭제
```
## 컨트롤러
### SalesManagerController
| 메서드 | HTTP | 설명 |
|--------|------|------|
| `index()` | GET | 파트너 목록 (현재 사용자 유치분) |
| `create()` | GET | 등록 폼 |
| `store()` | POST | 파트너 등록 (서류 업로드 포함) |
| `show()` | GET | 상세 페이지 |
| `edit()` | GET | 수정 폼 |
| `update()` | PUT | 정보 수정 |
| `destroy()` | DELETE | 비활성화 (관리자 전용) |
| `modalShow()` | GET | 상세 모달 (HTMX) |
| `modalEdit()` | GET | 수정 모달 (HTMX) |
| `delegateRole()` | POST | 상담매니저 역할 위임 |
| `assignRole()` | POST | 역할 부여 (sales/manager) |
| `removeRole()` | POST | 역할 제거 |
| `downloadDocument()` | GET | 서류 파일 다운로드 |
| `deleteDocument()` | DELETE | 서류 파일 삭제 |
### SalesManagerService
| 메서드 | 설명 |
|--------|------|
| `getSalesPartners()` | 필터 적용 파트너 목록 조회 |
| `getStats()` | 파트너 통계 계산 |
| `getApprovalStats()` | 승인 관련 통계 |
| `createSalesPartner()` | 파트너 생성 |
| `updateSalesPartner()` | 파트너 수정 |
| `approve()` | 승인 처리 |
| `reject()` | 반려 처리 |
## 모델
### SalesPartner
**테이블**: `sales_partners`
| 필드 | 타입 | 설명 |
|------|------|------|
| `user_id` | bigint (FK) | 연결된 사용자 ID |
| `partner_code` | string | 파트너 고유 코드 (SP + 연도 + 순번) |
| `partner_type` | string | individual(개인) / corporate(법인) |
| `commission_rate` | decimal(5,2) | 기본 수수료율 |
| `manager_commission_rate` | decimal(5,2) | 관리자 수수료율 |
| `bank_name` | string | 은행명 |
| `account_number` | string | 계좌번호 |
| `account_holder` | string | 예금주 |
| `status` | string | pending / active / inactive / suspended |
| `approved_at` | timestamp | 승인 일시 |
| `approved_by` | bigint (FK) | 승인자 ID |
| `total_contracts` | int | 총 계약 건수 (캐시) |
| `total_commission` | decimal | 총 수당 (캐시) |
- SoftDeletes 적용
### SalesManagerDocument
**테이블**: `sales_manager_documents`
- 파트너 등록 시 필수 서류 관리 (신분증, 통장사본 등)
- `DOCUMENT_TYPES` 상수로 서류 타입 정의
### 파트너 계층 구조
```
User 모델의 parent_id를 통한 다단계 구조:
추천인 (parent)
└── 영업파트너 (children)
└── 하위 파트너 (children)
```
## 뷰 구성
```
┌─ 페이지 헤더 ──────────────────────
│ 제목: "파트너관리"
│ [등록] 버튼
│
├─ 통계 카드 ────────────────────────
│ 전체 | 활성 | 대기중 | 비활성
│
├─ 필터 영역 ────────────────────────
│ 검색 (이름, 아이디) | 상태 필터 | 타입 필터
│
├─ 파트너 목록 테이블 ───────────────
│ 이름 | 파트너코드 | 타입 | 수수료율 | 계약수 | 상태 | 작업
│ └─ 작업: 상세, 수정, 역할관리, 승인/반려
│
├─ 등록 폼 ─────────────────────────
│ 사용자 정보, 파트너 타입, 수수료율
│ 계좌 정보, 서류 업로드
│
└─ 상세/수정 모달 ──────────────────
파트너 정보, 계층, 서류 목록, 역할 관리
```
## HTMX 호환성
- Blade + HTMX 기반으로 **HX-Redirect 불필요**
- 모달로 상세/수정 처리
- HTMX 또는 JavaScript AJAX 호출

175
docs/features/sales/products.md Normal file
View File

@@ -0,0 +1,175 @@
# 상품관리
## 개요
상품관리는 영업에 사용되는 상품(프로그램)을 카테고리별로 등록하고 가격/수당률을 설정하는 기능입니다.
카테고리 관리, 상품 CRUD, 순서 조정, 가격/수당률 설정, 영업 시나리오 연동을 지원합니다.
- **라우트**: `GET /sales/products`
- **미들웨어**: `auth`, `hq.member` (본사 전용)
- **UI 기술**: Blade + Alpine.js + HTMX + Tailwind CSS
## 파일 구조
```
mng/
├── app/Http/Controllers/Sales/
│ └── SalesProductController.php # 메인 컨트롤러 (12개 메서드)
├── app/Models/Sales/
│ ├── SalesProduct.php # 상품 모델
│ └── SalesProductCategory.php # 카테고리 모델
└── resources/views/sales/products/
├── index.blade.php # 메인 페이지
└── partials/
└── product-list.blade.php # 상품 목록 파셜 (HTMX)
api/
└── database/migrations/
├── 2026_01_29_150000_create_sales_products_tables.php
├── 2026_01_29_161626_add_partner_manager_commission_to_sales_products_table.php
└── 2026_01_29_162847_add_registration_fee_to_sales_products_table.php
```
## 라우트
```php
// routes/web.php (sales/products prefix 그룹 내)
// 상품 관리
GET /products → index() 메인 페이지
GET /products/list → productList() 카테고리별 상품 목록 (HTMX)
POST /products → store() 상품 등록
PUT /products/{id} → update() 상품 수정
DELETE /products/{id} → destroy() 상품 삭제
POST /products/{id}/toggle → toggleActive() 활성화 토글
POST /products/reorder → reorder() 순서 변경
// 카테고리 관리
GET /products/categories → categories() 카테고리 목록
POST /products/categories → storeCategory() 카테고리 생성
PUT /products/categories/{id} → updateCategory() 카테고리 수정
DELETE /products/categories/{id} → deleteCategory() 카테고리 삭제
// API (영업 시나리오용)
GET /products/api/list → getProductsApi() 활성 상품 목록
```
## 컨트롤러
### SalesProductController
| 메서드 | HTTP | 설명 |
|--------|------|------|
| `index()` | GET | 메인 페이지 (HX-Redirect 처리) |
| `productList()` | GET | 카테고리별 상품 목록 (HTMX 파셜) |
| `store()` | POST | 상품 등록 (코드 중복 체크, 자동 순서) |
| `update()` | PUT | 상품 수정 (부분 업데이트 허용) |
| `destroy()` | DELETE | 상품 삭제 (Soft Delete) |
| `toggleActive()` | POST | 활성화/비활성화 토글 |
| `reorder()` | POST | 다중 상품 순서 변경 (배치) |
| `categories()` | GET | 활성 카테고리 목록 |
| `storeCategory()` | POST | 카테고리 생성 (코드 unique) |
| `updateCategory()` | PUT | 카테고리 수정 |
| `deleteCategory()` | DELETE | 카테고리 삭제 (하위 상품 있으면 실패) |
| `getProductsApi()` | GET | API: 활성 카테고리+상품 (영업 시나리오용) |
## 모델
### SalesProductCategory
**테이블**: `sales_product_categories`
| 필드 | 타입 | 설명 |
|------|------|------|
| `code` | string(50) | 카테고리 코드 (unique) |
| `name` | string(100) | 카테고리명 |
| `description` | text | 설명 |
| `base_storage` | string(20) | 기본 제공 용량 (기본: 100GB) |
| `display_order` | int | 표시 순서 |
| `is_active` | boolean | 활성화 |
- SoftDeletes 적용
- 관계: `products()`, `activeProducts()`
- Scope: `active()`, `ordered()`
### SalesProduct
**테이블**: `sales_products`
| 필드 | 타입 | 설명 |
|------|------|------|
| `category_id` | bigint (FK) | 카테고리 ID |
| `code` | string(50) | 상품 코드 (카테고리별 unique) |
| `name` | string(100) | 상품명 |
| `description` | text | 설명 (프로그램 타입) |
| `development_fee` | decimal(15,2) | 개발비 |
| `registration_fee` | decimal(15,2) | 가입비 (할인가) |
| `subscription_fee` | decimal(15,2) | 월 구독료 |
| `partner_commission_rate` | decimal(5,2) | 영업파트너 수당율 (기본 20%) |
| `manager_commission_rate` | decimal(5,2) | 매니저 수당율 (기본 5%) |
| `allow_flexible_pricing` | boolean | 재량권 허용 여부 |
| `is_required` | boolean | 필수 선택 여부 |
| `display_order` | int | 표시 순서 |
| `is_active` | boolean | 활성화 |
- SoftDeletes 적용
- Unique Key: `(category_id, code)`
- Scope: `active()`, `ordered()`
- Accessor: `total_commission_rate`, `commission`, `formatted_*_fee`
### SalesContractProduct (계약별 선택 상품)
**테이블**: `sales_contract_products`
| 필드 | 타입 | 설명 |
|------|------|------|
| `tenant_id` | bigint (FK, nullable) | 테넌트 ID |
| `management_id` | bigint (FK) | 영업관리 ID |
| `category_id` | bigint (FK) | 선택 카테고리 |
| `product_id` | bigint (FK) | 선택 상품 |
| `development_fee` | decimal(15,2) | 적용 개발비 |
| `registration_fee` | decimal(15,2) | 적용 가입비 |
| `subscription_fee` | decimal(15,2) | 적용 구독료 |
| `discount_rate` | decimal(5,2) | 할인율 (기본 0%) |
| `notes` | text | 비고 |
| `created_by` | bigint (FK) | 등록자 |
## 뷰 구성
### index.blade.php
```
┌─ 페이지 헤더 ──────────────────────
│ 제목: "상품관리"
│ [카테고리 관리] 버튼
│
├─ 카테고리 탭 ──────────────────────
│ [카테고리A] [카테고리B] [카테고리C] ...
│ └─ 선택 시 HTMX로 상품 목록 갱신
│
├─ 상품 영역 ────────────────────────
│ 헤더: 카테고리명 + 기본 용량 + [상품 추가]
│
│ ┌─ 상품 카드 (그리드: 1/2/3열 반응형) ─┐
│ │ 상품명 + 필수/비활성 배지 + 코드 │
│ │ 프로그램 설명 │
│ │ 개발비(취소선) + 가입비(할인가) │
│ │ 월 구독료 │
│ │ 수당: 파트너 20%, 매니저 5% │
│ │ 재량권 허용/고정가 태그 + [삭제] │
│ └───────────────────────────────────────┘
│
├─ 상품 등록/수정 모달 (Alpine.js) ──
│ 코드, 상품명, 설명
│ 개발비, 가입비, 구독료
│ 파트너 수당율, 매니저 수당율
│ 재량권 허용, 필수 선택
│
└─ 카테고리 관리 모달 ──────────────
코드, 카테고리명, 설명, 기본 용량
```
## HTMX 호환성
- Alpine.js 스크립트가 `@push('scripts')`에 있어 **HX-Redirect 필요**
- 카테고리 탭 전환은 HTMX `hx-get`으로 부분 로드

189
docs/features/sales/prospects.md Normal file
View File

@@ -0,0 +1,189 @@
# 영업파트너 고객관리
## 개요
영업파트너 고객관리는 영업파트너가 명함을 등록하여 영업권을 확보하고,
고객과의 계약 진행을 관리하는 기능입니다.
명함 등록, 영업권 유효기간(2개월), 사업자번호 중복 체크, 테넌트 전환을 지원합니다.
- **라우트**: `GET /sales/prospects`
- **미들웨어**: `auth`, `hq.member`
- **UI 기술**: Blade + HTMX + Tailwind CSS
## 파일 구조
```
mng/
├── app/Http/Controllers/Sales/
│ └── TenantProspectController.php # 메인 컨트롤러 (12개 메서드)
├── app/Services/Sales/
│ └── TenantProspectService.php # 비즈니스 로직 서비스
├── app/Models/Sales/
│ └── TenantProspect.php # 가망고객 모델
└── resources/views/sales/prospects/
├── index.blade.php # 영업권 목록
├── create.blade.php # 명함 등록 폼
├── show.blade.php # 상세 페이지
├── edit.blade.php # 수정 폼
└── partials/
├── show-modal.blade.php # 상세 모달
└── edit-modal.blade.php # 수정 모달
api/
└── database/migrations/
├── 2026_01_27_221000_create_tenant_prospects_table.php
└── 2026_01_28_090000_add_attachments_to_tenant_prospects_table.php
```
## 라우트
```php
// routes/web.php (sales prefix 그룹 내)
// Resource 라우트
GET /prospects → index() 영업권 목록 (본인 기준)
GET /prospects/create → create() 명함 등록 폼
POST /prospects → store() 명함 등록 처리
GET /prospects/{id} → show() 상세 페이지
GET /prospects/{id}/edit → edit() 수정 폼
PUT /prospects/{id} → update() 수정 처리
DELETE /prospects/{id} → destroy() 삭제 (관리자)
// 추가 라우트
POST /prospects/{id}/convert → convert() 테넌트 전환
POST /prospects/check-business-number → checkBusinessNumber() 사업자번호 중복 체크
DELETE /prospects/{id}/attachment → deleteAttachment() 첨부파일 삭제
GET /prospects/{id}/modal-show → modalShow() 상세 모달
GET /prospects/{id}/modal-edit → modalEdit() 수정 모달
```
## 컨트롤러
### TenantProspectController
| 메서드 | HTTP | 설명 |
|--------|------|------|
| `index()` | GET | 영업권 목록 (현재 사용자 기준) |
| `create()` | GET | 명함 등록 폼 |
| `store()` | POST | 명함 등록 (등록자 = 현재 사용자) |
| `show()` | GET | 상세 페이지 |
| `edit()` | GET | 수정 폼 |
| `update()` | PUT | 정보 수정 |
| `destroy()` | DELETE | 삭제 (관리자 전용) |
| `convert()` | POST | 영업권 → 테넌트 전환 |
| `checkBusinessNumber()` | POST | 사업자번호 중복 체크 (AJAX) |
| `modalShow()` | GET | 상세 모달 |
| `modalEdit()` | GET | 수정 모달 |
| `deleteAttachment()` | DELETE | 첨부 이미지 삭제 |
### TenantProspectService
| 메서드 | 설명 |
|--------|------|
| `register()` | 명함 등록 (영업권 확보), expires_at = 등록일 + 2개월 |
| `update()` | 정보 수정 + 파일 업로드 (명함/신분증/통장) |
| `convertToTenant()` | 영업권 → 테넌트 전환 (Tenant + user_tenants 생성) |
| `expireOldProspects()` | 만료 영업권 자동 처리 (배치) |
| `canRegister()` | 사업자번호 등록 가능 여부 확인 |
| `getProspects()` | 목록 조회 (검색, 상태, 파트너 필터) |
| `getStats()` | 통계 (total, active, expired, converted) |
| `uploadAttachment()` | 파일 업로드 (tenant disk) |
| `deleteAttachment()` | 파일 삭제 |
## 모델
### TenantProspect
**테이블**: `tenant_prospects`
| 필드 | 타입 | 설명 |
|------|------|------|
| `business_number` | string(20) | 사업자번호 (중복 체크 키) |
| `company_name` | string(100) | 회사명 |
| `ceo_name` | string(50) | 대표자명 |
| `contact_phone` | string(20) | 연락처 |
| `contact_email` | string(100) | 이메일 |
| `address` | string(500) | 주소 |
| `registered_by` | bigint (FK) | 등록한 영업파트너 ID |
| `business_card_path` | string(500) | 명함 이미지 경로 |
| `id_card_path` | string(500) | 신분증 이미지 경로 |
| `bankbook_path` | string(500) | 통장 이미지 경로 |
| `status` | string(20) | active / expired / converted / completed |
| `registered_at` | timestamp | 등록일 |
| `expires_at` | timestamp | 만료일 (등록일 + 2개월) |
| `cooldown_ends_at` | timestamp | 재등록 가능일 (만료일 + 1개월) |
| `tenant_id` | bigint (FK, nullable) | 전환된 테넌트 ID |
| `converted_at` | timestamp | 전환일 |
| `converted_by` | bigint (FK) | 전환 처리자 ID |
| `memo` | text | 메모 |
- SoftDeletes 적용
#### 상태 흐름
```
명함 등록 → active (영업권 유효, 2개월)
│
├── convert() → converted (테넌트 전환 완료)
│ └→ completed (영업 완료)
│
└── (2개월 경과) → expired (만료)
└→ (1개월 쿨다운 후 재등록 가능)
```
#### 영업권 규칙
| 규칙 | 설명 |
|------|------|
| 유효기간 | 등록일로부터 2개월 |
| 쿨다운 | 만료 후 1개월간 재등록 불가 |
| 중복 체크 | 동일 사업자번호 중복 등록 방지 |
| 전환 | 영업권 → Tenant + user_tenants 자동 생성 |
#### 주요 속성/메서드
| 메서드 | 설명 |
|--------|------|
| `isActive()` | 영업권 유효 여부 |
| `isExpired()` | 만료 여부 |
| `isConverted()` | 테넌트 전환 완료 여부 |
| `canReRegister()` | 재등록 가능 여부 |
| `getStatusLabelAttribute()` | 상태 라벨 (영업중/완료/계약완료/대기중/만료) |
| `getStatusColorAttribute()` | Tailwind CSS 색상 |
| `getRemainingDaysAttribute()` | 남은 일수 |
## 뷰 구성
```
┌─ 페이지 헤더 ──────────────────────
│ 제목: "고객관리 (영업권)"
│ [명함 등록] 버튼
│
├─ 통계 카드 ────────────────────────
│ 전체 | 영업중 | 만료 | 전환완료
│
├─ 필터 영역 ────────────────────────
│ 검색 (회사명, 사업자번호) | 상태 필터
│
├─ 영업권 목록 테이블 ──────────────
│ 회사명 | 사업자번호 | 대표자 | 연락처 | 상태 | 남은일수 | 작업
│ └─ 상태: 영업중(초록), 만료(빨강), 전환(파랑), 완료(회색) 배지
│ └─ 작업: 상세, 수정, 전환, 삭제
│
├─ 등록 폼 ─────────────────────────
│ 사업자번호 (중복 체크), 회사명, 대표자명
│ 연락처, 이메일, 주소
│ 명함 이미지 업로드
│ 신분증, 통장사본 (선택)
│
└─ 상세 모달 ───────────────────────
회사 정보 + 첨부파일 미리보기
영업권 상태 + 남은 기간
[테넌트 전환] 버튼
```
## HTMX 호환성
- Blade + HTMX 기반으로 **HX-Redirect 불필요**
- 사업자번호 중복 체크: AJAX 실시간 검증
- 모달로 상세/수정 처리

122
docs/features/sales/sales-dashboard.md Normal file
View File

@@ -0,0 +1,122 @@
# 영업관리 대시보드
## 개요
영업관리 대시보드는 영업파트너/상담매니저의 수당 현황, 테넌트 진행률, 유치 파트너 활동을 종합적으로 보여주는 페이지입니다.
로그인한 사용자 기준의 실적 및 수당 정보를 실시간으로 제공합니다.
- **라우트**: `GET /sales/salesmanagement/dashboard`
- **미들웨어**: `auth`, `hq.member`
- **UI 기술**: Blade + HTMX + Alpine.js + Tailwind CSS
## 파일 구조
```
mng/
├── app/Http/Controllers/Sales/
│ └── SalesDashboardController.php # 메인 컨트롤러 (18개 메서드, 1,073줄)
└── resources/views/sales/dashboard/
├── index.blade.php # 메인 페이지
└── partials/
├── data-container.blade.php # HTMX 새로고침 컨테이너
├── stats.blade.php # 통계 카드
├── commission-by-role.blade.php # 역할별 수당
├── tenant-list.blade.php # 테넌트 목록
├── tenant-stats.blade.php # 테넌트 통계
├── partner-activity.blade.php # 유치 파트너 활동
├── my-commission.blade.php # 내 수당 정보
├── help-modal.blade.php # 도움말
└── prospect-row.blade.php # 가망고객 행
```
## 라우트
```php
// routes/web.php (sales prefix 그룹 내)
GET /salesmanagement/dashboard → index() 메인 페이지
GET /salesmanagement/dashboard/refresh → refresh() HTMX 부분 새로고침
GET /salesmanagement/dashboard/tenants → refreshTenantList() 테넌트 목록 갱신
GET /salesmanagement/dashboard/partner-activity → partnerActivity() 유치 파트너 활동
GET /salesmanagement/dashboard/help → helpGuide() 도움말 모달
GET /salesmanagement/dashboard/prospect/{id}/row → getProspectRow() 가망고객 행
GET /managers/list → getManagers() 매니저 목록
GET /managers/search → searchManagers() 매니저 검색
POST /tenants/{tenant}/assign-manager → assignManager() 매니저 지정
POST /prospects/{prospect}/assign-manager → assignProspectManager() 가망고객 매니저 지정
```
## 컨트롤러
### SalesDashboardController
| 메서드 | HTTP | 설명 |
|--------|------|------|
| `index()` | GET | 대시보드 메인 화면 |
| `refresh()` | GET | HTMX 부분 새로고침 |
| `getDashboardData()` | - | 대시보드 핵심 데이터 조회 (private) |
| `refreshTenantList()` | GET | 테넌트 목록 새로고침 |
| `getManagers()` | GET | 매니저 드롭다운 목록 |
| `searchManagers()` | GET | 매니저 검색 API |
| `partnerActivity()` | GET | 유치 파트너 활동 현황 |
| `getPartnerActivityData()` | - | 파트너 활동 데이터 (private) |
| `calculatePartnerSummaryStats()` | - | 파트너 요약 통계 (private) |
| `getPartnerActivitiesDetail()` | - | 파트너별 상세 활동 (private) |
| `getManagerOnlyProspects()` | - | 매니저 전용 가망고객 (private) |
| `getCommissionData()` | - | 수당 정보 조회 (private) |
| `getAllManagerUsers()` | - | 상담매니저 사용자 목록 (private) |
| `helpGuide()` | GET | 도움말 모달 |
| `getProspectRow()` | GET | 가망고객 개별 행 |
| `assignManager()` | POST | 테넌트 매니저 변경 |
| `assignProspectManager()` | POST | 가망고객 매니저 변경 |
| `calculateExpectedCommissionSummary()` | - | 예상 수당 계산 (private) |
### 수당 계산 로직
```
영업파트너 수당:
- 판매자 수당: 가입비 × 20%
- 협업지원금: 개발비 × 10% (인계 완료 시)
- 1차/2차 분할: 각 50%
매니저 수당:
- 1개월 구독료 (매니저 기본 수당)
- 1차/2차 분할: 각 50%
```
## 뷰 구성
```
┌─ 페이지 헤더 ──────────────────────
│ 제목: "영업관리"
│ [새로고침] 버튼
│
├─ 탭 전환 (Alpine.js) ─────────────
│ [내 활동] | [유치 파트너 현황]
│
├─ 탭1: 내 활동 ─────────────────────
│ ├─ 통계 카드 (수당 요약)
│ │ 총 수당 | 지급완료 | 미지급 | 예상 수당
│ │
│ ├─ 역할별 수당 상세
│ │ 영업파트너 수당 | 매니저 수당
│ │
│ └─ 테넌트/가망고객 목록
│ 회사명 | 상태 | 진행률 | 수당 | 매니저 | 작업
│ └─ 매니저 지정 변경 (드롭다운)
│
├─ 탭2: 유치 파트너 현황 ────────────
│ ├─ 파트너 요약 통계
│ │ 총 파트너 | 활성 | 계약건수 | 총 수당
│ │
│ └─ 파트너별 활동 상세
│ 파트너명 | 등록 고객 | 계약 | 진행중 | 수당
│
└─ 도움말 모달 ──────────────────────
수당 계산 방식, 진행 단계 설명
```
## HTMX 호환성
- Blade + HTMX 기반으로 **HX-Redirect 불필요**
- `hx-get`으로 부분 새로고침 처리
- Alpine.js 탭 전환

102
docs/features/settlement/README.md Normal file
View File

@@ -0,0 +1,102 @@
# 정산관리 기능
## 개요
SAM 프로젝트의 정산관리 모듈은 영업수수료, 컨설팅비용, 고객사별 정산, 구독료 등
다양한 정산 업무를 종합적으로 관리하는 시스템입니다.
입금 등록, 수당 자동 계산, 승인 프로세스, 지급 추적, 통계 기능을 제공합니다.
## 메뉴 구성
| 메뉴 | 경로 | 설명 | UI 기술 |
|------|------|------|---------|
| [영업수수료정산](./sales-commissions.md) | `/finance/sales-commissions` | 영업파트너/매니저 수당 정산 | Blade + HTMX |
| [컨설팅비용정산](./consulting-fees.md) | `/finance/consulting-fee` | 컨설턴트별 상담수수료 관리 | React 18 |
| [고객사정산](./customer-settlements.md) | `/finance/customer-settlement` | 고객사별 매출/비용 정산 | React 18 |
| [구독료정산](./subscriptions.md) | `/finance/subscription` | 구독 플랜별 과금 관리 | React 18 |
## 아키텍처
```
┌───────────────────────────────────────────────────────────────┐
│ 정산관리 모듈 │
├───────────────┬───────────────┬───────────────┬───────────────┤
│ 영업수수료정산 │ 컨설팅비용정산 │ 고객사정산 │ 구독료정산 │
│ (Blade+HTMX) │ (React 18) │ (React 18) │ (React 18) │
│ │ │ │ │
│ 입금등록 │ 상담기록 │ 월별정산 │ 플랜관리 │
│ 수당자동계산 │ 시급계산 │ 매출/비용 │ MRR/ARR │
│ 승인프로세스 │ 상태관리 │ 순정산액 │ 과금주기 │
│ 지급추적 │ │ │ 사용자수 │
└───────┬───────┴───────┬───────┴───────┬───────┴───────┬───────┘
│ │ │ │
▼ ▼ ▼ ▼
┌───────────────────────────────────────────────────────────────┐
│ 데이터베이스 │
│ sales_commissions, sales_commission_details, │
│ consulting_fees, customer_settlements, subscriptions │
└───────────────────────────────────────────────────────────────┘
```
## 주요 기술 스택
| 기술 | 용도 |
|------|------|
| Laravel 11 (PHP 8.3) | 백엔드 프레임워크 |
| Blade + HTMX | 영업수수료정산 UI (부분 업데이트, 모달) |
| React 18 + Babel | 컨설팅/고객사/구독료 UI (브라우저 트랜스파일링) |
| Tailwind CSS + Lucide | 스타일링 및 아이콘 |
| MySQL 8.0 | 데이터 저장 |
## 데이터 흐름
```
영업수수료정산:
sales_tenant_managements (계약) → 입금 등록
↓
sales_commissions (수당 자동 계산)
├── sales_commission_details (상품별 상세)
└── 승인 → 지급완료 프로세스
컨설팅비용정산:
consulting_fees (상담시간 × 시급 = 정산액)
고객사정산:
customer_settlements (매출 - 수수료 - 비용 = 순정산액)
구독료정산:
subscriptions (플랜별 월정액 × 과금주기)
```
## 공통 패턴
### 멀티 테넌트
모든 테이블은 `tenant_id` 기반으로 데이터를 격리합니다.
컨트롤러에서 `session('selected_tenant_id', 1)`로 현재 테넌트를 결정합니다.
### 상태 관리
| 기능 | 상태값 |
|------|--------|
| 영업수수료 | pending → approved → paid / cancelled |
| 컨설팅비용 | pending / paid |
| 고객사정산 | pending / settled |
| 구독료 | active / trial / cancelled / expired / suspended |
### CSV 내보내기
모든 기능에서 CSV 내보내기를 지원합니다:
- 영업수수료: 서버 사이드 (UTF-8 BOM 인코딩)
- 컨설팅/고객사/구독: 클라이언트 사이드 (React)
## 데이터베이스 테이블 요약
| 테이블 | 역할 |
|--------|------|
| `sales_commissions` | 영업수수료 정산 (입금, 수당, 승인, 지급) |
| `sales_commission_details` | 상품별 수당 상세 내역 |
| `consulting_fees` | 컨설팅 상담수수료 기록 |
| `customer_settlements` | 고객사별 월간 정산 |
| `subscriptions` | 구독 플랜 및 과금 관리 |
| `customers` | 고객사 마스터 (참조) |

148
docs/features/settlement/consulting-fees.md Normal file
View File

@@ -0,0 +1,148 @@
# 컨설팅비용정산
## 개요
컨설팅비용정산은 컨설턴트별 상담수수료를 기록하고 관리하는 기능입니다.
상담 시간과 시급 기반의 정산액 계산, 지급 상태 관리, 통계 기능을 제공합니다.
- **라우트**: `GET /finance/consulting-fee`
- **UI 기술**: React 18 + Babel (브라우저 트랜스파일링)
## 파일 구조
```
mng/
├── app/Http/Controllers/Finance/
│ └── ConsultingFeeController.php # 메인 컨트롤러 (4개 메서드)
├── app/Models/Finance/
│ └── ConsultingFee.php # 상담수수료 모델
└── resources/views/finance/
└── consulting-fee.blade.php # React 기반 단일 페이지
api/
└── database/migrations/
└── 2026_02_04_230006_create_consulting_fees_table.php
```
## 라우트
```php
// routes/web.php (finance prefix 그룹 내)
GET /consulting-fee → Blade 페이지 렌더링 (HX-Redirect)
// API 라우트 (consulting-fees prefix)
GET /consulting-fees/list → index() 목록 + 통계 (JSON)
POST /consulting-fees/store → store() 등록
PUT /consulting-fees/{id} → update() 수정
DELETE /consulting-fees/{id} → destroy() 삭제
```
## 컨트롤러
### ConsultingFeeController
| 메서드 | HTTP | 설명 |
|--------|------|------|
| `index()` | GET | 목록 + 통계 (검색, 상태 필터) |
| `store()` | POST | 상담수수료 등록 |
| `update()` | PUT | 수정 |
| `destroy()` | DELETE | 삭제 (Soft Delete) |
### index() 응답 구조
```json
{
"success": true,
"data": [
{
"id": 1,
"date": "2026-02-10",
"consultant": "김컨설턴트",
"customer": "A사",
"service": "기술 컨설팅",
"hours": 4,
"hourlyRate": 150000,
"amount": 600000,
"status": "pending",
"memo": ""
}
],
"stats": {
"totalAmount": 3500000,
"paidAmount": 2000000,
"pendingAmount": 1500000,
"totalHours": 28
}
}
```
## 핵심 로직
### 정산액 계산
```
정산액(amount) = 상담시간(hours) × 시급(hourly_rate)
```
### 상태 관리
```
pending (대기) → paid (지급완료)
```
## 모델
### ConsultingFee
**테이블**: `consulting_fees`
| 필드 | 타입 | 설명 |
|------|------|------|
| `tenant_id` | bigint | 테넌트 ID |
| `date` | date | 상담일 |
| `consultant` | string(50) | 컨설턴트명 |
| `customer` | string(100) | 고객사명 |
| `service` | string(50) | 서비스 유형 (기본: '기술 컨설팅') |
| `hours` | int | 상담 시간 |
| `hourly_rate` | int | 시급 |
| `amount` | bigint | 정산액 |
| `status` | string(20) | pending / paid |
| `memo` | text | 메모 |
- SoftDeletes 적용
- Scope: `forTenant($tenantId)`
## 뷰 구성 (React)
### consulting-fee.blade.php
```
┌─ 페이지 헤더 ──────────────────────
│ 제목: "컨설팅비용정산"
│ [CSV 내보내기] [등록] 버튼
│
├─ 통계 카드 (4열) ──────────────────
│ 총 상담시간 | 총 정산액 | 지급완료 | 미지급
│
├─ 필터 영역 ────────────────────────
│ 검색 (컨설턴트/고객사) | 컨설턴트 필터 | 상태 필터
│ 기간 선택 (시작일 ~ 종료일)
│
├─ 정산 목록 테이블 ─────────────────
│ 날짜 | 컨설턴트 | 고객사 | 서비스 | 시간 | 시급 | 정산액 | 상태 | 작업
│ └─ 상태: 대기(노랑), 지급완료(초록) 배지
│ └─ 작업: 수정/삭제 버튼
│
├─ 등록/수정 모달 ───────────────────
│ 상담일, 컨설턴트, 고객사, 서비스 유형
│ 상담시간, 시급, 정산액 (자동 계산)
│ 상태, 메모
│ [삭제] [취소] [등록/저장]
│
└─ 비어있을 때: 안내 메시지
```
## HTMX 호환성
- React 기반 페이지이므로 **HX-Redirect 필요**
- `@push('scripts')` 블록에 React/Babel 스크립트 포함

165
docs/features/settlement/customer-settlements.md Normal file
View File

@@ -0,0 +1,165 @@
# 고객사정산
## 개요
고객사정산은 고객사별 월간 매출, 수수료, 비용을 집계하여 순정산액을 관리하는 기능입니다.
기간별 정산 현황 추적, 정산 완료 처리, 통계 기능을 제공합니다.
- **라우트**: `GET /finance/customer-settlement`
- **UI 기술**: React 18 + Babel (브라우저 트랜스파일링)
## 파일 구조
```
mng/
├── app/Http/Controllers/Finance/
│ └── CustomerSettlementController.php # 메인 컨트롤러 (4개 메서드)
├── app/Models/Finance/
│ └── CustomerSettlement.php # 고객사정산 모델
└── resources/views/finance/
└── customer-settlement.blade.php # React 기반 단일 페이지
api/
└── database/migrations/
└── 2026_02_04_230007_create_customer_settlements_table.php
```
## 라우트
```php
// routes/web.php (finance prefix 그룹 내)
GET /customer-settlement → Blade 페이지 렌더링 (HX-Redirect)
// API 라우트 (customer-settlements prefix)
GET /customer-settlements/list → index() 목록 + 통계 (JSON)
POST /customer-settlements/store → store() 등록
PUT /customer-settlements/{id} → update() 수정
DELETE /customer-settlements/{id} → destroy() 삭제
```
## 컨트롤러
### CustomerSettlementController
| 메서드 | HTTP | 설명 |
|--------|------|------|
| `index()` | GET | 목록 + 통계 (검색, 기간, 상태 필터) |
| `store()` | POST | 정산 등록 |
| `update()` | PUT | 정산 수정 |
| `destroy()` | DELETE | 삭제 (Soft Delete) |
### index() 응답 구조
```json
{
"success": true,
"data": [
{
"id": 1,
"period": "2026-02",
"customer": "A사",
"totalSales": 10000000,
"commission": 500000,
"expense": 200000,
"netAmount": 9300000,
"status": "pending",
"settledDate": null,
"memo": ""
}
],
"stats": {
"totalSales": 50000000,
"totalCommission": 2500000,
"totalNet": 45000000,
"settledAmount": 30000000
}
}
```
## 핵심 로직
### 순정산액 계산
```
순정산액(net_amount) = 총 매출(total_sales) - 수수료(commission) - 비용(expense)
```
### 상태 관리
```
pending (대기) → settled (정산완료)
→ 정산완료 시 settled_date 기록
```
## 모델
### CustomerSettlement
**테이블**: `customer_settlements`
| 필드 | 타입 | 설명 |
|------|------|------|
| `tenant_id` | bigint | 테넌트 ID |
| `period` | string(7) | 정산월 (YYYY-MM) |
| `customer` | string(100) | 고객사명 |
| `total_sales` | bigint | 총 매출액 |
| `commission` | bigint | 수수료 |
| `expense` | bigint | 비용 |
| `net_amount` | bigint | 순정산액 |
| `status` | string(20) | pending / settled |
| `settled_date` | date | 정산완료일 |
| `memo` | text | 메모 |
- SoftDeletes 적용
- Casts: total_sales, commission, expense, net_amount → integer, settled_date → date
- Scope: `forTenant($tenantId)`
## 뷰 구성 (React)
### customer-settlement.blade.php
```
┌─ 페이지 헤더 ──────────────────────
│ 제목: "고객사정산"
│ [CSV 내보내기] [등록] 버튼
│
├─ 통계 카드 (4열) ──────────────────
│ 총 매출 | 정산금액 | 정산완료 | 총 수수료
│
├─ 필터 영역 ────────────────────────
│ 검색 (고객사명) | 기간 (YYYY-MM) | 상태 (전체/대기/정산완료)
│
├─ 정산 목록 테이블 ─────────────────
│ 기간 | 고객사 | 매출 | 수수료 | 비용 | 정산액 | 상태 | 작업
│ └─ 정산액: 매출-수수료-비용 자동 계산
│ └─ 상태: 대기(노랑), 정산완료(초록) 배지
│ └─ 작업: 수정/삭제 버튼
│
├─ 등록/수정 모달 ───────────────────
│ 정산월(YYYY-MM), 고객사명
│ 총 매출액, 수수료, 비용
│ → 순정산액 (자동 계산 표시)
│ 상태, 정산완료일, 메모
│ [삭제] [취소] [등록/저장]
│
└─ 비어있을 때: 안내 메시지
```
## 데이터 흐름
```
React 컴포넌트
↓ fetch GET /finance/customer-settlements/list
CustomerSettlementController::index()
↓
CustomerSettlement::forTenant()
↓ (search, status, period 필터)
통계 계산 (totalSales, totalCommission, totalNet, settledAmount)
↓
JSON 응답 → React 렌더링
```
## HTMX 호환성
- React 기반 페이지이므로 **HX-Redirect 필요**
- `@push('scripts')` 블록에 React/Babel 스크립트 포함

264
docs/features/settlement/sales-commissions.md Normal file
View File

@@ -0,0 +1,264 @@
# 영업수수료정산
## 개요
영업수수료정산은 영업파트너와 매니저의 수당을 계산하고 승인/지급하는 기능입니다.
입금 등록 시 수당 자동 계산, 승인 프로세스(대기→승인→지급), 지급 추적, 일괄 처리를 지원합니다.
- **라우트**: `GET /finance/sales-commissions`
- **UI 기술**: Blade + HTMX (부분 업데이트, 모달)
- **컨트롤러**: `SalesCommissionController` (13개 메서드)
- **서비스**: `SalesCommissionService` (핵심 비즈니스 로직)
## 파일 구조
```
mng/
├── app/Http/Controllers/Finance/
│ └── SalesCommissionController.php # 메인 컨트롤러 (13개 메서드)
├── app/Services/
│ └── SalesCommissionService.php # 비즈니스 로직 서비스
├── app/Models/Sales/
│ ├── SalesCommission.php # 수수료 정산 모델
│ └── SalesCommissionDetail.php # 상품별 상세 모델
└── resources/views/finance/sales-commission/
├── index.blade.php # 메인 페이지
├── stats-cards.blade.php # 통계 카드 (HTMX partial)
├── commission-table.blade.php # 테이블 (HTMX partial)
└── payment-form.blade.php # 입금 등록 폼 (HTMX partial)
api/
└── database/migrations/
├── 2026_01_29_170000_create_sales_commissions_table.php
└── 2026_01_29_170100_create_sales_commission_details_table.php
```
## 라우트
```php
// routes/web.php (finance prefix 그룹 내)
GET /sales-commissions → index() 목록 페이지
POST /sales-commissions/payment → registerPayment() 입금 등록
GET /sales-commissions/{id} → show() JSON 상세
GET /sales-commissions/{id}/detail → detail() 모달 상세 (HTMX)
POST /sales-commissions/{id}/approve → approve() 승인
POST /sales-commissions/{id}/mark-paid → markPaid() 지급완료
POST /sales-commissions/{id}/cancel → cancel() 취소
POST /sales-commissions/bulk-approve → bulkApprove() 일괄 승인
POST /sales-commissions/bulk-mark-paid → bulkMarkPaid() 일괄 지급완료
GET /sales-commissions/table → table() 테이블 새로고침 (HTMX)
GET /sales-commissions/stats → stats() 통계 새로고침 (HTMX)
GET /sales-commissions/payment-form → paymentForm() 입금 폼 (HTMX)
GET /sales-commissions/export → export() CSV 다운로드
```
## 컨트롤러
### SalesCommissionController
| 메서드 | HTTP | 설명 |
|--------|------|------|
| `index()` | GET | 정산 목록 (필터, 페이지네이션) |
| `show(id)` | GET | JSON 상세 조회 |
| `detail(id)` | GET | 모달 상세 (HTMX partial) |
| `registerPayment()` | POST | **입금 등록 및 수당 자동 생성** |
| `approve(id)` | POST | 단일 승인 처리 |
| `bulkApprove()` | POST | 일괄 승인 (체크박스 선택) |
| `markPaid(id)` | POST | 단일 지급완료 |
| `bulkMarkPaid()` | POST | 일괄 지급완료 |
| `cancel(id)` | POST | 취소 처리 (paid 상태 제외) |
| `table()` | GET | 테이블 부분 새로고침 (HTMX) |
| `stats()` | GET | 통계 카드 부분 새로고침 (HTMX) |
| `paymentForm()` | GET | 입금 등록 폼 모달 (HTMX) |
| `export()` | GET | CSV 엑셀 다운로드 (UTF-8 BOM) |
## 서비스 클래스
### SalesCommissionService
#### 상수
```php
const DEFAULT_PARTNER_RATE = 20.00; // 기본 파트너 수당률 (%)
const DEFAULT_MANAGER_RATE = 5.00; // 기본 매니저 수당률 (%)
```
#### 주요 메서드
| 메서드 | 설명 |
|--------|------|
| `getCommissions(filters, perPage)` | 정산 목록 (페이지네이션, 필터) |
| `getCommissionById(id)` | 정산 상세 (관계 포함) |
| `getPendingPaymentTenants()` | 입금 대기 테넌트 목록 |
| `createCommission(managementId, type, amount, date)` | **입금 등록 + 수당 생성** |
| `approve(id, approverId)` | 승인 처리 |
| `bulkApprove(ids, approverId)` | 일괄 승인 |
| `markAsPaid(id, bankReference?)` | 지급완료 처리 |
| `bulkMarkAsPaid(ids, bankReference?)` | 일괄 지급완료 |
| `cancel(id)` | 취소 처리 |
| `getSettlementStats(year, month)` | 월별 정산 통계 |
| `getPartnerCommissionSummary(partnerId)` | 파트너 수당 요약 |
| `getManagerCommissionSummary(userId)` | 매니저 수당 요약 |
## 핵심 로직
### 수당 자동 계산 (createCommission)
```
입금 등록
↓
1. 계약 상품 목록 조회 (sales_contract_products)
↓
2. 각 상품별 수당 계산:
기본 가입비 = 등록 금액 × 2 (없을 경우)
기준액 = 가입비 × 50%
파트너 수당 = 기준액 × 20%
매니저 수당 = 기준액 × 5% (매니저 있을 경우만)
↓
3. sales_commissions 레코드 생성
+ sales_commission_details (상품별 N건)
↓
4. sales_tenant_managements 입금 정보 업데이트
↓
5. DB 트랜잭션으로 원자적 처리
```
### 승인 프로세스
```
pending (대기)
↓ approve()
approved (승인) ← approved_by, approved_at 기록
↓ markAsPaid()
paid (지급완료) ← actual_payment_date, bank_reference 기록
pending/approved → cancel() → cancelled
(paid 상태에서는 취소 불가)
```
### 지급 추적 (SalesCommission 모델)
```
1차 납입완료일 → first_payment_date
1차 파트너 수당 지급일 → first_partner_paid_date
2차 납입완료일 → second_payment_date
2차 파트너 수당 지급일 → second_partner_paid_date
첫 구독료 입금일 → first_subscription_date
매니저 수당 지급일 → manager_paid_date
```
### 지급예정일 계산
```
1차 파트너 수당: 1차 납입완료 익월 10일
2차 파트너 수당: 2차 납입완료 익월 10일
매니저 수당: 첫 구독료 입금 익월 10일
```
## 모델
### SalesCommission
**테이블**: `sales_commissions`
| 필드 | 타입 | 설명 |
|------|------|------|
| `tenant_id` | bigint | 테넌트 ID |
| `management_id` | bigint | 영업 테넌트 관리 FK |
| `payment_type` | enum | deposit(계약금) / balance(잔금) |
| `payment_amount` | decimal(14,2) | 입금액 |
| `payment_date` | date | 입금일 |
| `base_amount` | decimal(14,2) | 수당 계산 기준액 (가입비 50%) |
| `partner_rate` | decimal(5,2) | 파트너 수당률 (기본 20%) |
| `manager_rate` | decimal(5,2) | 매니저 수당률 (기본 5%) |
| `partner_commission` | decimal(14,2) | 파트너 수당액 |
| `manager_commission` | decimal(14,2) | 매니저 수당액 |
| `scheduled_payment_date` | date | 지급예정일 (입금 익월 10일) |
| `status` | enum | pending / approved / paid / cancelled |
| `actual_payment_date` | date | 실제 지급일 |
| `partner_id` | bigint | 영업파트너 FK |
| `manager_user_id` | bigint | 매니저 사용자 FK |
| `notes` | text | 메모 |
| `bank_reference` | string(100) | 이체 참조번호 |
| `approved_by` | bigint | 승인자 FK |
| `approved_at` | timestamp | 승인 일시 |
#### Relationships
```php
$commission->management // BelongsTo SalesTenantManagement
$commission->partner // BelongsTo SalesPartner
$commission->manager // BelongsTo User
$commission->details // HasMany SalesCommissionDetail
$commission->approver // BelongsTo User
```
#### 주요 Scope
```php
->pending() // 대기 상태
->approved() // 승인 완료
->paid() // 지급 완료
->forPartner($partnerId) // 특정 파트너
->forManager($managerUserId) // 특정 매니저
->forScheduledMonth($year, $month) // 지급예정 월
->paymentDateBetween($startDate, $endDate) // 입금일 기간
```
#### 주요 Accessor
```php
$commission->status_label // "대기", "승인", "지급완료", "취소"
$commission->payment_type_label // "계약금", "잔금"
$commission->total_commission // 파트너 + 매니저 수당 합계
```
### SalesCommissionDetail
**테이블**: `sales_commission_details`
| 필드 | 타입 | 설명 |
|------|------|------|
| `commission_id` | bigint | 정산 FK (cascade delete) |
| `contract_product_id` | bigint | 계약 상품 FK |
| `registration_fee` | decimal(14,2) | 상품 가입비 |
| `base_amount` | decimal(14,2) | 수당 계산 기준액 |
| `partner_rate` / `manager_rate` | decimal(5,2) | 수당률 |
| `partner_commission` / `manager_commission` | decimal(14,2) | 수당액 |
## 뷰 구성
### index.blade.php (메인 페이지)
```
┌─ 페이지 헤더 ──────────────────────
│ 제목: "영업수수료 정산"
│ [입금 등록] [CSV 다운로드] 버튼
│
├─ 필터 영역 ────────────────────────
│ 년/월 선택 | 상태 | 입금구분 | 파트너 | 검색
│
├─ 통계 카드 (HTMX partial) ────────
│ 대기 금액 | 승인 금액 | 지급 금액 | 월간 합계
│ (파트너/매니저 수당 구분)
│
├─ 정산 테이블 (HTMX partial) ──────
│ ☑ | 관리ID | 입금구분 | 금액 | 입금일 | 파트너 | 수당액 | 상태 | 작업
│ └─ 체크박스: 일괄 승인/지급 선택
│ └─ 인라인 작업: 승인, 지급완료, 취소
│ └─ 페이지네이션
│
├─ 입금 등록 모달 (HTMX partial) ───
│ 테넌트 선택 → 계약 상품 표시
│ 입금구분(계약금/잔금) | 입금액 | 입금일
│
└─ 상세 모달 (HTMX partial) ────────
파트너/매니저 정보, 상품별 수당 내역
지급 추적 일정
```
## HTMX 호환성
- Blade + HTMX 기반 (부분 업데이트 활용)
- 테이블, 통계 카드, 모달이 HTMX partial로 동작
- 전체 페이지는 HX-Redirect 필요 (JavaScript 포함)

260
docs/features/settlement/subscriptions.md Normal file
View File

@@ -0,0 +1,260 @@
# 구독료정산
## 개요
구독료정산은 고객사별 구독 플랜과 과금을 관리하는 기능입니다.
플랜별 월정액 관리, 과금주기(월/연), MRR/ARR 집계, 사용자 수 추적을 지원합니다.
- **라우트**: `GET /finance/subscription`
- **UI 기술**: React 18 + Babel (브라우저 트랜스파일링)
## 파일 구조
```
mng/
├── app/Http/Controllers/Finance/
│ └── SubscriptionController.php # MNG 컨트롤러 (4개 메서드)
├── app/Models/Finance/
│ └── Subscription.php # MNG 구독 모델
└── resources/views/finance/
└── subscription.blade.php # React 기반 단일 페이지
api/
├── app/Http/Controllers/Api/V1/
│ └── SubscriptionController.php # API 컨트롤러 (REST)
├── app/Services/
│ └── SubscriptionService.php # 비즈니스 로직 서비스
├── app/Models/Tenants/
│ └── Subscription.php # API 구독 모델 (상세 구현)
└── database/migrations/
├── 2026_02_04_230008_create_subscriptions_table.php
└── 2025_12_22_222722_add_cancel_columns_to_subscriptions_table.php
```
## 라우트
### MNG 라우트
```php
// routes/web.php (finance prefix 그룹 내)
GET /subscription → Blade 페이지 렌더링 (HX-Redirect)
// API 라우트 (subscriptions prefix)
GET /subscriptions/list → index() 목록 + 통계 (JSON)
POST /subscriptions/store → store() 등록
PUT /subscriptions/{id} → update() 수정
DELETE /subscriptions/{id} → destroy() 삭제
```
### API 라우트
```php
// routes/api.php (v1/subscriptions prefix)
GET / → index() 목록 (페이지네이션)
GET /{id} → show() 상세 조회
POST / → store() 생성
PUT /{id} → update() 수정
DELETE /{id} → destroy() 삭제
POST /{id}/cancel → cancel() 구독 취소
POST /{id}/suspend → suspend() 일시정지
POST /{id}/resume → resume() 재개
```
## 컨트롤러
### SubscriptionController (MNG)
| 메서드 | HTTP | 설명 |
|--------|------|------|
| `index()` | GET | 목록 + MRR/ARR 통계 (검색, 상태 필터) |
| `store()` | POST | 구독 등록 |
| `update()` | PUT | 구독 수정 |
| `destroy()` | DELETE | 삭제 (Soft Delete) |
### index() 응답 구조
```json
{
"success": true,
"data": [
{
"id": 1,
"customer": "A사",
"plan": "Business",
"monthlyFee": 500000,
"billingCycle": "monthly",
"startDate": "2026-01-01",
"nextBilling": "2026-03-01",
"status": "active",
"users": 10,
"memo": ""
}
],
"stats": {
"activeCount": 15,
"monthlyRecurring": 7500000,
"yearlyRecurring": 90000000,
"totalUsers": 150
}
}
```
## 핵심 로직
### MRR/ARR 계산
```
MRR (Monthly Recurring Revenue)
= SUM(active 구독의 monthly_fee) (billingCycle=monthly)
+ SUM(active 구독의 monthly_fee / 12) (billingCycle=yearly를 월 환산)
ARR (Annual Recurring Revenue)
= MRR × 12
```
### 구독 상태 관리 (API 모델)
```
pending (대기)
↓ activate()
active (활성)
├── cancel(reason) → cancelled (취소)
├── suspend() → suspended (일시정지)
│ ↓ resume() → active (재활성)
└── (만료) → expired
```
### 구독 플랜
| 플랜 | 설명 |
|------|------|
| Starter | 소규모 기본 플랜 |
| Business | 중규모 비즈니스 플랜 |
| Enterprise | 대규모 기업 플랜 |
### 과금 주기
| 주기 | 설명 |
|------|------|
| monthly | 월간 과금 |
| yearly | 연간 과금 |
## 모델
### Subscription (MNG)
**테이블**: `subscriptions`
| 필드 | 타입 | 설명 |
|------|------|------|
| `tenant_id` | bigint | 테넌트 ID |
| `customer` | string | 고객사명 |
| `plan` | string | 플랜명 (Starter/Business/Enterprise) |
| `monthly_fee` | int | 월 정액 |
| `billing_cycle` | string | monthly / yearly |
| `start_date` | date | 시작일 |
| `next_billing` | date | 다음 과금일 |
| `status` | string | active / trial / cancelled |
| `users` | int | 사용자 수 |
| `memo` | text | 메모 |
| `cancelled_at` | timestamp | 취소 일시 |
| `cancel_reason` | string(500) | 취소 사유 |
- SoftDeletes 적용
- Casts: monthly_fee, users → integer, start_date, next_billing → date
- Scope: `forTenant($tenantId)`
### Subscription (API - 상세 구현)
API 프로젝트의 모델은 더 상세한 구독 라이프사이클을 지원합니다:
#### 상태 상수
```php
const STATUS_ACTIVE = 'active';
const STATUS_CANCELLED = 'cancelled';
const STATUS_EXPIRED = 'expired';
const STATUS_PENDING = 'pending';
const STATUS_SUSPENDED = 'suspended';
```
#### Relationships
```php
$subscription->tenant // BelongsTo Tenant
$subscription->plan // BelongsTo Plan
$subscription->payments // HasMany Payment
```
#### 주요 Accessor
```php
$subscription->statusLabel // 상태 한글 라벨
$subscription->isExpired // 만료 여부
$subscription->remainingDays // 잔여 일수
$subscription->isValid // 유효 여부 (active + 미만료)
$subscription->totalPaid // 총 결제 금액
```
#### 주요 메서드
```php
$subscription->activate() // 활성화
$subscription->renew($newEndDate) // 갱신
$subscription->cancel($reason) // 취소
$subscription->suspend() // 일시정지
$subscription->resume() // 재개
$subscription->isCancellable() // 취소 가능 여부
```
## 서비스 클래스 (API)
### SubscriptionService
| 메서드 | 설명 |
|--------|------|
| `index(params)` | 페이지네이션 목록 (필터, 정렬) |
| `current()` | 현재 활성 구독 조회 |
| `show(id)` | 상세 (플랜, 최근 결제 포함) |
| `store(data)` | 구독 생성 (결제 처리) |
| `update(id, data)` | 구독 수정 |
| `cancel(id, reason)` | 구독 취소 |
| `suspend(id)` | 일시정지 |
| `resume(id)` | 재개 |
| `renew(id, newEndDate)` | 갱신 |
## 뷰 구성 (React)
### subscription.blade.php
```
┌─ 페이지 헤더 ──────────────────────
│ 제목: "구독료정산"
│ [CSV 내보내기] [등록] 버튼
│
├─ 통계 카드 (4열) ──────────────────
│ 활성 구독 | MRR (월간 반복 수익) | ARR (연간 반복 수익) | 총 사용자
│
├─ 필터 영역 ────────────────────────
│ 검색 (고객사명) | 플랜 (Starter/Business/Enterprise) | 상태 (active/trial/cancelled)
│
├─ 구독 목록 테이블 ─────────────────
│ 고객사 | 플랜 | 월정액 | 과금주기 | 다음과금일 | 사용자 | 상태 | 작업
│ └─ 플랜: Starter(회색), Business(파랑), Enterprise(보라) 배지
│ └─ 상태: active(초록), trial(파랑), cancelled(빨강) 배지
│ └─ 작업: 수정/삭제 버튼
│
├─ 등록/수정 모달 ───────────────────
│ 고객사명, 플랜 선택
│ 월정액, 과금주기(월/연)
│ 시작일, 다음 과금일
│ 상태, 사용자 수, 메모
│ [삭제] [취소] [등록/저장]
│
└─ 비어있을 때: 안내 메시지
```
## HTMX 호환성
- React 기반 페이지이므로 **HX-Redirect 필요**
- `@push('scripts')` 블록에 React/Babel 스크립트 포함

897
docs/features/voice-input-stt-guide.md Normal file
View File

@@ -0,0 +1,897 @@
# 음성 입력(STT) 기술 가이드
> **문서 버전**: 1.1
> **작성일**: 2026-02-10
> **적용 페이지**: 공사현장 사진대지, 영업 전략 시나리오, 매니저 상담 프로세스
> **대상 프로젝트**: MNG (React 18 + Alpine.js)
---
## 1. 개요
### 1.1 목적
텍스트 입력 필드(input, textarea)에 **마이크 버튼**을 배치하여, 사용자가 음성으로 텍스트를 입력할 수 있게 하는 브라우저 내장 STT(Speech-to-Text) 기능.
### 1.2 기술 선택
| 방식 | 비용 | 정확도 | 지연 | 채택 |
|------|------|--------|------|------|
| Web Speech API (브라우저 내장) | **무료** | 높음 (Google STT 엔진) | 실시간 | **채택** |
| Google Cloud STT API | 유료 ($0.006/15초) | 매우 높음 | 서버 왕복 | 미채택 |
| Whisper (OpenAI) | 유료 ($0.006/분) | 매우 높음 | 서버 왕복 | 미채택 |
**선택 이유**: 브라우저 내장 Web Speech API는 Chrome 기반에서 Google STT 엔진을 무료로 사용하며, 실시간 스트리밍으로 interim/final 결과를 즉시 받을 수 있다. 비용 없이 충분한 한국어 인식률을 제공한다.
### 1.3 브라우저 지원
| 브라우저 | 지원 | 비고 |
|----------|------|------|
| Chrome (Desktop/Android) | ✅ | 최적 지원, Google STT 엔진 사용 |
| Edge | ✅ | Chromium 기반 |
| Safari (iOS/macOS) | ✅ | `webkitSpeechRecognition` |
| Firefox | ❌ | 미지원 (버튼 자동 숨김) |
---
## 2. 핵심 개념: Interim vs Final
Web Speech API의 핵심은 **미확정(interim)** 텍스트와 **확정(final)** 텍스트의 구분이다.
### 2.1 텍스트 상태 흐름
```
[음성 입력 시작]
│
├─ interim: "안녕하" ← 인식 진행 중 (수정될 수 있음)
├─ interim: "안녕하세" ← 교정 발생 (이전 interim 덮어씀)
├─ interim: "안녕하세요" ← 교정 발생
│
├─ ★ FINAL: "안녕하세요" ← 확정! (절대 삭제 불가)
│
├─ interim: "반갑습" ← 새로운 인식 시작
├─ interim: "반갑습니다"
│
├─ ★ FINAL: "반갑습니다" ← 확정!
│
[음성 입력 종료]
```
### 2.2 렌더링 규칙 (필수 준수)
| 상태 | 스타일 | 동작 | 삭제 가능 |
|------|--------|------|-----------|
| **interim** (미확정) | `italic` + `text-gray-400` | 실시간 교정됨. 이전 interim을 덮어씀 | 교정만 허용 |
| **final** (확정) | `font-normal` + `text-white` | `finalizedSegments[]` 배열에 영구 추가 | **절대 불가** |
### 2.3 input 반영 규칙
- **final 이벤트 발생 시에만** `onResult(transcript)` 호출하여 input에 텍스트 추가
- interim 텍스트는 **프리뷰 패널에만** 표시하고, input에는 반영하지 않음
- input에 추가된 텍스트는 사용자가 직접 수정 가능 (일반 텍스트)
---
## 3. 컴포넌트 아키텍처
### 3.1 VoiceInputButton 컴포넌트
```
┌─────────────────────────────────┐
│ VoiceInputButton │
│ │
│ Props: │
│ onResult: (text) => void │ ← final 텍스트만 전달
│ disabled: boolean │ ← 비활성화 (읽기 모드 등)
│ │
│ State: │
│ recording: boolean │ ← 녹음 중 여부
│ finalizedSegments: string[] │ ← 확정 텍스트 누적 (프리뷰용)
│ interimText: string │ ← 현재 미확정 텍스트
│ │
│ Refs: │
│ recognitionRef │ ← SpeechRecognition 인스턴스
│ startTimeRef │ ← 녹음 시작 시각 (사용량 추적)
│ dismissTimerRef │ ← 프리뷰 닫기 타이머
│ previewRef │ ← 프리뷰 DOM (자동 스크롤)
│ │
│ Output: │
│ [마이크 버튼] + [프리뷰 패널] │
└─────────────────────────────────┘
```
### 3.2 전체 코드
```jsx
function VoiceInputButton({ onResult, disabled }) {
const [recording, setRecording] = useState(false);
const [finalizedSegments, setFinalizedSegments] = useState([]);
const [interimText, setInterimText] = useState('');
const recognitionRef = useRef(null);
const startTimeRef = useRef(null);
const dismissTimerRef = useRef(null);
const previewRef = useRef(null);
// 브라우저 지원 확인
const isSupported = typeof window !== 'undefined' &&
(window.SpeechRecognition || window.webkitSpeechRecognition);
// STT 사용량 로깅 (AI 토큰 사용량 추적)
const logUsage = useCallback((startTime) => {
const duration = Math.max(1, Math.round((Date.now() - startTime) / 1000));
apiFetch(API.logSttUsage, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ duration_seconds: duration }),
}).catch(() => {});
}, []);
// 프리뷰 패널 자동 스크롤
useEffect(() => {
if (previewRef.current) {
previewRef.current.scrollTop = previewRef.current.scrollHeight;
}
}, [finalizedSegments, interimText]);
// 녹음 중지
const stopRecording = useCallback(() => {
recognitionRef.current?.stop();
recognitionRef.current = null;
if (startTimeRef.current) {
logUsage(startTimeRef.current);
startTimeRef.current = null;
}
setRecording(false);
setInterimText('');
// 녹음 종료 후 2초 뒤 프리뷰 닫기
dismissTimerRef.current = setTimeout(() => {
setFinalizedSegments([]);
}, 2000);
}, [logUsage]);
// 녹음 시작
const startRecording = useCallback(() => {
// 이전 타이머 정리
if (dismissTimerRef.current) {
clearTimeout(dismissTimerRef.current);
dismissTimerRef.current = null;
}
const SR = window.SpeechRecognition || window.webkitSpeechRecognition;
const recognition = new SR();
recognition.lang = 'ko-KR'; // 한국어
recognition.continuous = true; // 연속 인식 (자동 종료 안 함)
recognition.interimResults = true; // interim 결과 수신
recognition.maxAlternatives = 1; // 후보 1개만
recognition.onresult = (event) => {
// dismiss 타이머 취소 (아직 인식 중)
if (dismissTimerRef.current) {
clearTimeout(dismissTimerRef.current);
dismissTimerRef.current = null;
}
let currentInterim = '';
for (let i = event.resultIndex; i < event.results.length; i++) {
const transcript = event.results[i][0].transcript;
if (event.results[i].isFinal) {
// ★ 확정: input에 반영 + 프리뷰에 영구 저장
onResult(transcript);
setFinalizedSegments(prev => [...prev, transcript]);
currentInterim = '';
} else {
// 미확정: 교정은 허용하되 이전 확정분은 보존
currentInterim = transcript;
}
}
setInterimText(currentInterim);
};
recognition.onerror = () => stopRecording();
recognition.onend = () => {
// 브라우저가 자동 종료한 경우 처리
if (startTimeRef.current) {
logUsage(startTimeRef.current);
startTimeRef.current = null;
}
setRecording(false);
setInterimText('');
recognitionRef.current = null;
dismissTimerRef.current = setTimeout(() => {
setFinalizedSegments([]);
}, 2000);
};
recognitionRef.current = recognition;
startTimeRef.current = Date.now();
setFinalizedSegments([]);
setInterimText('');
recognition.start();
setRecording(true);
}, [onResult, stopRecording, logUsage]);
// 토글 (시작/중지)
const toggle = useCallback((e) => {
e.preventDefault();
e.stopPropagation();
if (disabled || !isSupported) return;
recording ? stopRecording() : startRecording();
}, [disabled, isSupported, recording, stopRecording, startRecording]);
// 컴포넌트 언마운트 시 정리
useEffect(() => {
return () => {
recognitionRef.current?.stop();
if (dismissTimerRef.current) clearTimeout(dismissTimerRef.current);
};
}, []);
// 미지원 브라우저에서는 렌더링하지 않음
if (!isSupported) return null;
const hasContent = finalizedSegments.length > 0 || interimText;
return (
<div className="relative flex-shrink-0">
{/* 마이크 버튼 */}
<button
type="button"
onClick={toggle}
disabled={disabled}
title={recording ? '녹음 중지 (클릭)' : '음성으로 입력'}
className={`inline-flex items-center justify-center w-8 h-8 rounded-full transition-all
${recording
? 'bg-red-500 text-white shadow-lg shadow-red-200'
: 'bg-gray-100 text-gray-500 hover:bg-blue-100 hover:text-blue-600'}
${disabled ? 'opacity-30 cursor-not-allowed' : 'cursor-pointer'}`}
>
{recording ? (
<span className="relative flex items-center justify-center w-4 h-4">
<span className="absolute inset-0 rounded-full bg-white/30 animate-ping" />
<svg className="w-3.5 h-3.5 relative" fill="currentColor" viewBox="0 0 24 24">
<rect x="6" y="6" width="12" height="12" rx="2" />
</svg>
</span>
) : (
<svg className="w-4 h-4" fill="currentColor" viewBox="0 0 24 24">
<path d="M12 14c1.66 0 3-1.34 3-3V5c0-1.66-1.34-3-3-3S9 3.34
9 5v6c0 1.66 1.34 3 3 3z" />
<path d="M17 11c0 2.76-2.24 5-5 5s-5-2.24-5-5H5c0 3.53 2.61
6.43 6 6.92V21h2v-3.08c3.39-.49 6-3.39 6-6.92h-2z" />
</svg>
)}
</button>
{/* 스트리밍 프리뷰 패널 */}
{(recording || hasContent) && (
<div
ref={previewRef}
className="absolute bottom-full mb-2 right-0 bg-gray-900 rounded-lg
shadow-xl z-50 w-[300px] max-h-[120px] overflow-y-auto px-3 py-2"
style={{ lineHeight: '1.6' }}
>
{/* 확정 텍스트: 일반체 + 흰색 */}
{finalizedSegments.map((seg, i) => (
<span key={i} className="text-white text-xs font-normal
transition-colors duration-300">
{seg}
</span>
))}
{/* 미확정 텍스트: 이탤릭 + 연한 회색 */}
{interimText && (
<span className="text-gray-400 text-xs italic
transition-colors duration-200">
{interimText}
</span>
)}
{/* 녹음 중 + 텍스트 없음: 대기 표시 */}
{recording && !hasContent && (
<span className="text-gray-500 text-xs flex items-center gap-1.5">
<span className="inline-block w-1.5 h-1.5 bg-red-400
rounded-full animate-pulse" />
말씀하세요...
</span>
)}
{/* 녹음 종료 후 확정 텍스트 완료 표시 */}
{!recording && finalizedSegments.length > 0 && !interimText && (
<span className="text-green-400 text-xs ml-1">&#10003;</span>
)}
</div>
)}
</div>
);
}
```
---
## 4. 사용 패턴
### 4.1 기본 사용법 (input 옆에 배치)
```jsx
function MyForm() {
const [value, setValue] = useState('');
return (
<div>
<label className="block text-sm font-medium text-gray-700 mb-1">
현장명 *
</label>
<div className="flex items-center gap-2">
<input
type="text"
value={value}
onChange={e => setValue(e.target.value)}
className="flex-1 px-3 py-2 border border-gray-300 rounded-lg text-sm"
placeholder="입력하세요"
/>
<VoiceInputButton
onResult={(text) => setValue(prev =>
prev ? prev + ' ' + text : text
)}
/>
</div>
</div>
);
}
```
### 4.2 textarea와 함께 사용
```jsx
<div className="flex items-start gap-2"> {/* items-start: 상단 정렬 */}
<textarea
value={description}
onChange={e => setDescription(e.target.value)}
className="flex-1 px-3 py-2 border rounded-lg text-sm"
rows={3}
/>
<VoiceInputButton
onResult={(text) => setDescription(prev =>
prev ? prev + ' ' + text : text
)}
/>
</div>
```
### 4.3 조건부 활성화 (수정 모드에서만)
```jsx
<VoiceInputButton
onResult={(text) => setSiteName(prev => prev ? prev + ' ' + text : text)}
disabled={!editing} // 수정 모드가 아닐 때 비활성화
/>
```
### 4.4 onResult 콜백 패턴
```jsx
// 패턴 1: 기존 텍스트에 이어붙이기 (공백 구분)
onResult={(text) => setValue(prev => prev ? prev + ' ' + text : text)}
// 패턴 2: 덮어쓰기
onResult={(text) => setValue(text)}
// 패턴 3: 커스텀 후처리
onResult={(text) => {
const cleaned = text.trim().replace(/\s+/g, ' ');
setValue(prev => prev + ' ' + cleaned);
}}
```
---
## 5. 프리뷰 패널 UI 상세
### 5.1 위치와 스타일
```
┌─────────────────────────────┐
│ 확정텍스트 미확정텍스트... │ ← 프리뷰 패널
│ (흰색,일반체) (회색,이탤릭) │ bg-gray-900
└─────────────────────────────┘ w-[300px]
┌──┐ max-h-[120px]
│🎤│ line-height: 1.6
└──┘
```
- **위치**: 버튼 상단 (`absolute bottom-full mb-2 right-0`)
- **배경**: 다크 (`bg-gray-900`) - 밝은 폼 위에서 눈에 잘 띔
- **너비**: 300px 고정, 높이 최대 120px (스크롤)
- **자동 스크롤**: 텍스트가 길어지면 하단으로 자동 스크롤
### 5.2 상태별 표시
| 상태 | 표시 내용 |
|------|-----------|
| 녹음 시작 직후 (텍스트 없음) | 🔴 `말씀하세요...` (빨간 점 + 회색 텍스트) |
| interim 수신 중 | 확정 텍스트(흰) + 미확정 텍스트(회색 이탤릭) |
| final 확정 순간 | 이전 확정 + 새 확정(흰) 추가, interim 초기화 |
| 녹음 종료 직후 | 모든 확정 텍스트 + ✓ 표시(녹색) |
| 종료 후 2초 | 패널 자동 닫힘 (`finalizedSegments` 초기화) |
### 5.3 transition 설정
```
확정 텍스트: transition-colors duration-300 (0.3초 색상 전환)
미확정 텍스트: transition-colors duration-200 (0.2초 색상 전환)
line-height: 1.6 고정 (줄 높이 변동 방지)
```
---
## 6. SpeechRecognition 설정 상세
### 6.1 주요 옵션
```javascript
const recognition = new SpeechRecognition();
recognition.lang = 'ko-KR'; // 언어 (한국어)
recognition.continuous = true; // 연속 인식 모드
recognition.interimResults = true; // interim 결과 수신
recognition.maxAlternatives = 1; // 인식 후보 수
```
| 옵션 | 값 | 설명 |
|------|-----|------|
| `lang` | `'ko-KR'` | 한국어 인식. 다국어 필요 시 변경 |
| `continuous` | `true` | 말을 멈춰도 자동 종료하지 않음. 사용자가 직접 중지 |
| `interimResults` | `true` | 미확정 결과를 실시간 수신 (false면 final만) |
| `maxAlternatives` | `1` | 인식 결과 후보 1개만 (속도 최적화) |
### 6.2 이벤트 핸들러
| 이벤트 | 발생 시점 | 처리 |
|--------|-----------|------|
| `onresult` | 인식 결과 수신 | interim/final 구분 후 상태 업데이트 |
| `onerror` | 인식 오류 | 녹음 중지 |
| `onend` | 인식 세션 종료 | 정리 + 사용량 로깅 + 프리뷰 dismiss 타이머 |
### 6.3 onresult 이벤트 상세
```javascript
recognition.onresult = (event) => {
// event.resultIndex: 이번 이벤트에서 변경된 결과의 시작 인덱스
// event.results: SpeechRecognitionResultList (누적)
// event.results[i].isFinal: 확정 여부
// event.results[i][0].transcript: 인식된 텍스트
for (let i = event.resultIndex; i < event.results.length; i++) {
const transcript = event.results[i][0].transcript;
if (event.results[i].isFinal) {
// → input에 반영 + finalizedSegments에 추가
} else {
// → interimText 업데이트 (이전 interim 덮어씀)
}
}
};
```
**주의**: `event.resultIndex`부터 순회해야 한다. 전체(`0`부터)를 순회하면 이미 처리한 final 결과를 중복 처리하게 된다.
---
## 7. 백엔드 (STT 사용량 추적)
### 7.1 라우트
```php
// routes/web.php (juil 그룹 내)
Route::post('/construction-photos/log-stt-usage',
[ConstructionSitePhotoController::class, 'logSttUsage']
)->name('construction-photos.log-stt-usage');
```
### 7.2 컨트롤러
```php
public function logSttUsage(Request $request): JsonResponse
{
$validated = $request->validate([
'duration_seconds' => 'required|integer|min:1',
]);
AiTokenHelper::saveSttUsage(
'공사현장사진대지-음성입력', // 메뉴명 (사용처 식별)
$validated['duration_seconds']
);
return response()->json(['success' => true]);
}
```
### 7.3 AiTokenHelper::saveSttUsage
```php
// App\Helpers\AiTokenHelper
/**
* STT 사용량 기록
* - 과금 기준: $0.009 / 15초
* - Google Cloud Speech-to-Text 기준 단가
*
* @param string $menuName 사용처 메뉴명
* @param int $durationSeconds 녹음 시간(초)
*/
public static function saveSttUsage(string $menuName, int $durationSeconds): void
```
### 7.4 새 페이지에 STT 적용 시 라우트 추가 패턴
```php
// 1. 컨트롤러에 logSttUsage 메서드 추가
public function logSttUsage(Request $request): JsonResponse
{
$validated = $request->validate([
'duration_seconds' => 'required|integer|min:1',
]);
AiTokenHelper::saveSttUsage(
'새메뉴명-음성입력', // ← 메뉴명 변경
$validated['duration_seconds']
);
return response()->json(['success' => true]);
}
// 2. 라우트 등록
Route::post('/new-page/log-stt-usage', [NewController::class, 'logSttUsage'])
->name('new-page.log-stt-usage');
// 3. 프론트엔드 API 객체에 추가
const API = {
logSttUsage: '/path/to/log-stt-usage',
};
```
---
## 8. 새 페이지에 음성 입력 적용 체크리스트
### 8.1 프론트엔드
```
□ 1. VoiceInputButton 컴포넌트 코드 복사 (또는 공통 모듈화 후 import)
□ 2. API 객체에 logSttUsage 엔드포인트 추가
□ 3. input/textarea 옆에 VoiceInputButton 배치
□ 4. onResult 콜백에서 기존 텍스트에 이어붙이기 패턴 적용
□ 5. disabled prop으로 수정 모드에서만 활성화 (필요 시)
□ 6. flex 레이아웃 확인:
- input: items-center gap-2 (한 줄)
- textarea: items-start gap-2 (상단 정렬)
```
### 8.2 백엔드
```
□ 1. 컨트롤러에 logSttUsage 메서드 추가
□ 2. AiTokenHelper::saveSttUsage() 호출 (메뉴명 지정)
□ 3. routes/web.php에 POST 라우트 등록
```
### 8.3 레이아웃 참고
```
┌───────────────────────────────────────────┐
│ label │
│ ┌──────────────────────────────────┐ ┌──┐ │
│ │ input text │ │🎤│ │
│ └──────────────────────────────────┘ └──┘ │
│ │
│ label │
│ ┌──────────────────────────────────┐ ┌──┐ │
│ │ textarea │ │🎤│ │
│ │ │ │ │ │
│ │ │ │ │ │
│ └──────────────────────────────────┘ └──┘ │
└───────────────────────────────────────────┘
```
---
## 9. 주의사항 및 트러블슈팅
### 9.1 HTTPS 필수
Web Speech API는 **HTTPS** 환경에서만 동작한다 (localhost는 예외). HTTP 배포 시 마이크 접근이 차단된다.
### 9.2 브라우저 자동 종료
`continuous: true`로 설정해도, 브라우저가 긴 무음 구간에서 자동으로 인식을 종료할 수 있다. `onend` 이벤트에서 이를 처리한다.
### 9.3 마이크 권한
첫 사용 시 브라우저가 마이크 접근 권한을 요청한다. 사용자가 거부하면 `onerror`가 발생하고 버튼이 중지 상태로 돌아간다.
### 9.4 컴포넌트 언마운트 시 정리
모달 안에서 사용할 경우, 모달이 닫힐 때 컴포넌트가 언마운트된다. `useEffect` cleanup에서 반드시 `recognition.stop()`과 `clearTimeout`을 호출해야 한다.
```javascript
useEffect(() => {
return () => {
recognitionRef.current?.stop();
if (dismissTimerRef.current) clearTimeout(dismissTimerRef.current);
};
}, []);
```
### 9.5 이벤트 전파 방지
마이크 버튼이 form 안에 있으면 클릭 시 form submit이 발생할 수 있다. 반드시 `e.preventDefault()` + `e.stopPropagation()`을 호출한다.
```javascript
const toggle = useCallback((e) => {
e.preventDefault();
e.stopPropagation();
// ...
}, []);
```
### 9.6 다중 VoiceInputButton
한 페이지에 여러 VoiceInputButton을 배치할 수 있다. 각 인스턴스는 독립적인 `recognitionRef`를 가지므로 충돌하지 않는다. 단, **동시에 2개 이상 녹음은 불가**하다 (브라우저 마이크 제한). 한 버튼이 녹음 중일 때 다른 버튼을 누르면 기존 녹음이 중단된다 (브라우저 동작).
### 9.7 onend 자동 재시작 (긴 녹음)
`continuous: true`여도 브라우저가 무음 감지 시 자동으로 `onend`를 호출한다. 녹음이 계속 진행 중이라면 `onend`에서 재시작해야 한다.
```javascript
// Alpine.js 패턴
recognition.onend = () => {
if (this.isRecording && this.recognition) {
try { this.recognition.start(); } catch (e) {}
}
};
// React 패턴 (VoiceInputButton)
// onend에서 logUsage + dismiss 타이머 처리
recognition.onend = () => {
if (startTimeRef.current) {
logUsage(startTimeRef.current);
startTimeRef.current = null;
}
setRecording(false);
dismissTimerRef.current = setTimeout(() => setFinalizedSegments([]), 2000);
};
```
영업 시나리오는 `onend`에서 재시작하여 긴 상담도 끊김 없이 인식한다. 반면 공사현장 사진대지는 짧은 입력이므로 재시작하지 않는다.
---
## 10. Alpine.js 구현 (영업/매니저 시나리오)
영업 전략 시나리오와 매니저 상담 프로세스는 **Alpine.js + Blade** 기반이다. React 없이 동일한 STT 규칙을 적용한다.
### 10.1 적용 파일
| 파일 | 경로 | 용도 |
|------|------|------|
| voice-recorder.blade.php | `resources/views/sales/modals/voice-recorder.blade.php` | 음성 녹음 + STT 컴포넌트 |
| scenario-modal.blade.php | `resources/views/sales/modals/scenario-modal.blade.php` | 시나리오 모달 (voice-recorder 포함) |
| consultation-log.blade.php | `resources/views/sales/modals/consultation-log.blade.php` | 상담 기록 표시/재생 |
### 10.2 React vs Alpine.js 차이점
| 항목 | React (공사현장 사진대지) | Alpine.js (영업 시나리오) |
|------|--------------------------|--------------------------|
| 상태 관리 | `useState`, `useRef` | `x-data` 속성 |
| 확정 텍스트 | `finalizedSegments` state | `finalizedSegments` 배열 |
| 미확정 텍스트 | `interimText` state | `interimTranscript` |
| 자동 스크롤 | `useEffect` + `previewRef` | `$nextTick()` + `$refs` |
| 반복 렌더링 | `{arr.map((seg, i) => <span>)}` | `<template x-for="(seg, i) in arr">` |
| 조건부 표시 | `{condition && <Component />}` | `x-show="condition"` |
| 용도 | input 필드 옆 간단 음성 입력 | 음성 녹음 + 파일 저장 + STT |
### 10.3 핵심 코드 (Alpine.js)
#### x-data 상태 정의
```javascript
x-data="{
// ... 기존 녹음 상태 ...
transcript: '', // 확정 텍스트 합산 (서버 저장용)
interimTranscript: '', // 현재 미확정 텍스트
finalizedSegments: [], // 확정 텍스트 세그먼트 배열 (프리뷰용)
// ...
}"
```
#### startSpeechRecognition()
```javascript
startSpeechRecognition() {
const SpeechRecognition = window.SpeechRecognition || window.webkitSpeechRecognition;
if (!SpeechRecognition) return;
this.recognition = new SpeechRecognition();
this.recognition.lang = 'ko-KR';
this.recognition.continuous = true;
this.recognition.interimResults = true;
this.recognition.maxAlternatives = 1;
this.transcript = '';
this.interimTranscript = '';
this.finalizedSegments = [];
this.recognition.onresult = (event) => {
let currentInterim = '';
// ★ event.resultIndex부터 순회 (중복 방지)
for (let i = event.resultIndex; i < event.results.length; i++) {
const text = event.results[i][0].transcript;
if (event.results[i].isFinal) {
// ★ 확정: finalizedSegments에 영구 저장
this.finalizedSegments.push(text);
currentInterim = '';
} else {
// 미확정: 교정만 허용
currentInterim = text;
}
}
// transcript 합산 (서버 저장용)
this.transcript = this.finalizedSegments.join(' ');
this.interimTranscript = currentInterim;
// 자동 스크롤
this.$nextTick(() => {
if (this.$refs.transcriptContainer) {
this.$refs.transcriptContainer.scrollTop =
this.$refs.transcriptContainer.scrollHeight;
}
});
};
// 긴 녹음 시 자동 재시작
this.recognition.onend = () => {
if (this.isRecording && this.recognition) {
try { this.recognition.start(); } catch (e) {}
}
};
this.recognition.start();
}
```
### 10.4 프리뷰 패널 UI (Alpine.js Blade)
```blade
{{-- 다크 프리뷰 패널 --}}
<div x-show="finalizedSegments.length > 0 || interimTranscript"
class="bg-gray-900 rounded-lg border border-gray-700 overflow-hidden">
{{-- 헤더: 인식 중/완료 상태 표시 --}}
<div class="flex items-center justify-between px-3 py-2 border-b border-gray-700">
<div class="flex items-center gap-2">
<p class="text-xs font-medium text-gray-400">음성 인식 결과</p>
<template x-if="isRecording">
<span class="flex items-center gap-1 text-xs text-red-400">
<span class="w-1.5 h-1.5 bg-red-400 rounded-full animate-pulse"></span>
인식 중
</span>
</template>
<template x-if="!isRecording && finalizedSegments.length > 0">
<span class="text-green-400 text-xs">&#10003; 완료</span>
</template>
</div>
<p class="text-xs text-gray-500" x-text="transcript.length + ' 자'"></p>
</div>
{{-- 텍스트 영역 --}}
<div class="p-3 max-h-32 overflow-y-auto" x-ref="transcriptContainer"
style="line-height: 1.6;">
{{-- 확정: 흰색 일반체 (삭제 불가) --}}
<template x-for="(seg, i) in finalizedSegments" :key="i">
<span class="text-white text-sm font-normal
transition-colors duration-300" x-text="seg"></span>
</template>
{{-- 미확정: 회색 이탤릭 (교정 가능) --}}
<span x-show="interimTranscript"
class="text-gray-400 text-sm italic
transition-colors duration-200"
x-text="interimTranscript"></span>
{{-- 대기: 녹음 중 + 텍스트 없음 --}}
<span x-show="isRecording && finalizedSegments.length === 0 && !interimTranscript"
class="text-gray-500 text-sm flex items-center gap-1.5">
<span class="w-1.5 h-1.5 bg-red-400 rounded-full animate-pulse"></span>
말씀하세요...
</span>
</div>
</div>
```
### 10.5 영업 시나리오만의 추가 기능
영업/매니저 시나리오의 voice-recorder는 단순 STT 외에 다음 기능을 포함한다:
| 기능 | 설명 | API |
|------|------|-----|
| **음성 파일 녹음** | MediaRecorder로 webm 캡처 | `navigator.mediaDevices.getUserMedia()` |
| **파형 시각화** | Canvas + Web Audio API | `AudioContext.createAnalyser()` |
| **자동 저장** | 녹음 중지 시 서버로 FormData 전송 | `ConsultationController::uploadAudio()` |
| **GCS 백업** | 10MB 이상 파일은 GCS에도 저장 | `GoogleCloudStorageService` |
| **Transcript 저장** | STT 결과를 audio 레코드와 함께 DB 저장 | `sales_consultations.transcript` |
| **재생/다운로드** | 저장된 음성 파일 재생 및 다운로드 | `ConsultationController::downloadAudio()` |
### 10.6 데이터 흐름 (영업 시나리오)
```
사용자 마이크
│
├──→ MediaRecorder (webm 녹음)
│ └──→ audioBlob
│
├──→ Web Audio API (파형 시각화)
│ └──→ Canvas 파형 그리기
│
└──→ SpeechRecognition (STT)
│
├──→ finalizedSegments[] (확정 세그먼트)
│ └──→ transcript (합산, 서버 저장용)
│
└──→ interimTranscript (미확정)
└──→ 프리뷰 패널에만 표시
[녹음 중지]
└──→ FormData { audio, transcript, duration }
└──→ POST /sales/consultations/upload-audio
└──→ DB + (GCS if > 10MB)
└──→ HTMX 상담기록 갱신
```
---
## 11. 향후 확장 가능성
| 기능 | 설명 | 난이도 |
|------|------|--------|
| 화자 분리 (Speaker Diarization) | 여러 사람의 음성을 구분하여 각각 텍스트화 | Google Cloud STT API 필요 |
| 다국어 전환 | `recognition.lang`을 동적으로 변경 | 낮음 |
| 음성 명령 | 특정 키워드 인식 시 동작 수행 (예: "저장", "다음") | 중간 |
| 녹음 파일 저장 | MediaRecorder API로 음성 파일을 GCS에 저장 | 중간 |
| 실시간 번역 | STT 결과를 번역 API로 전달 | 중간 |
---
## 부록 A: 참조 구현 파일
### React 구현 (공사현장 사진대지)
| 파일 | 설명 |
|------|------|
| `mng/resources/views/juil/construction-photos.blade.php` | VoiceInputButton 전체 코드 (React) |
| `mng/app/Http/Controllers/Juil/ConstructionSitePhotoController.php` | logSttUsage 엔드포인트 |
| `mng/app/Helpers/AiTokenHelper.php` | saveSttUsage / saveGcsStorageUsage 헬퍼 |
### Alpine.js 구현 (영업/매니저 시나리오)
| 파일 | 설명 |
|------|------|
| `mng/resources/views/sales/modals/voice-recorder.blade.php` | 음성 녹음 + STT (Alpine.js) |
| `mng/resources/views/sales/modals/scenario-modal.blade.php` | 시나리오 모달 (voice-recorder 포함) |
| `mng/resources/views/sales/modals/consultation-log.blade.php` | 상담 기록 재생/표시 |
| `mng/app/Http/Controllers/Sales/ConsultationController.php` | 음성 업로드/다운로드/삭제 |
## 부록 B: CSS 클래스 요약
| 요소 | Tailwind 클래스 |
|------|----------------|
| 마이크 버튼 (대기) | `bg-gray-100 text-gray-500 hover:bg-blue-100 hover:text-blue-600 w-8 h-8 rounded-full` |
| 마이크 버튼 (녹음) | `bg-red-500 text-white shadow-lg shadow-red-200` |
| 프리뷰 패널 | `bg-gray-900 rounded-lg shadow-xl w-[300px] max-h-[120px] overflow-y-auto` |
| 확정 텍스트 | `text-white text-xs font-normal transition-colors duration-300` |
| 미확정 텍스트 | `text-gray-400 text-xs italic transition-colors duration-200` |
| 대기 표시 | `text-gray-500 text-xs` + 빨간 점 `animate-pulse` |
| 완료 표시 | `text-green-400 text-xs` ✓ |
| 비활성화 | `opacity-30 cursor-not-allowed` |