# 주일기업 기획 메뉴

> **작성일**: 2026-03-06
> **상태**: 운영 중
> **프로젝트**: SAM MNG (관리자 웹)
> **라우트 접두사**: `/juil`

---

## 1. 개요

### 1.1 목적

블라인드/스크린 제조업체의 현장 관리를 위한 기획 도구 모음. 견적부터 공사, 준공까지의 업무 흐름과 현장 기록(사진대지), 회의 기록(STT/AI 요약)을 제공한다.

### 1.2 문서 구조

| 문서 | 설명 |
|------|------|
| **README.md** (이 문서) | 전체 개요, 메뉴 구조, 아키텍처 |
| [construction-photos.md](construction-photos.md) | 공사현장 사진대지 기술 명세 |
| [meeting-minutes.md](meeting-minutes.md) | 회의록 작성 기술 명세 (STT/AI 통합) |
| [planning-views.md](planning-views.md) | 견적/프로젝트/워크플로우 화면 명세 |

### 1.3 하위 메뉴 구조

```
주일기업 기획
├── 견적/입찰/공사관리        /juil/estimate
├── 프로젝트관리/기성청구     /juil/project
├── 업무 Workflow            /juil/workflow
├── 공사현장 사진대지         /juil/construction-photos
└── 회의록 작성              /juil/meeting-minutes
```

---

## 2. 아키텍처

### 2.1 기술 스택

| 계층 | 기술 | 설명 |
|------|------|------|
| 뷰 | Blade + React (인라인) + Babel | 브라우저 트랜스파일 React 컴포넌트 |
| API | Laravel Controller + Service | JSON API (AJAX) |
| 모델 | Eloquent ORM | Multi-tenant (BelongsToTenant) |
| 파일 저장 | Google Cloud Storage | 사진, 오디오 파일 |
| AI | Gemini API (Vertex AI) | 요약, 화자 분리 |
| STT | Google Speech-to-Text V1/V2 + Web Speech API | 음성 인식 |

### 2.2 프로젝트 파일 구조

```
mng/
├── app/Http/Controllers/
│   ├── PlanningController.php                   ← 견적/프로젝트/워크플로우
│   ├── ConstructionSitePhotoController.php      ← 사진대지 CRUD + 파일 관리
│   └── MeetingMinuteController.php              ← 회의록 CRUD + AI 기능
├── app/Services/
│   ├── ConstructionSitePhotoService.php         ← 사진대지 비즈니스 로직
│   └── MeetingMinuteService.php                 ← 회의록 + AI 통합 로직
├── app/Models/
│   ├── ConstructionSitePhoto.php                ← 사진대지 모델
│   ├── ConstructionSitePhotoRow.php             ← 사진 행 모델
│   ├── MeetingMinute.php                        ← 회의록 모델
│   └── MeetingMinuteSegment.php                 ← 회의 세그먼트 모델
└── resources/views/juil/
    ├── estimate.blade.php                       ← 견적/입찰/공사관리
    ├── project.blade.php                        ← 프로젝트관리/기성청구
    ├── workflow.blade.php                       ← 업무 Workflow
    ├── construction-photos.blade.php            ← 사진대지 SPA
    └── meeting-minutes.blade.php                ← 회의록 SPA
```

### 2.3 기능별 구현 현황

| 기능 | 구현 방식 | 백엔드 | DB |
|------|----------|--------|-----|
| 견적/입찰/공사관리 | React 뷰 (목데이터) | PlanningController (뷰 반환만) | 없음 |
| 프로젝트관리/기성청구 | React 뷰 (목데이터) | PlanningController (뷰 반환만) | 없음 |
| 업무 Workflow | React 뷰 (정적 데이터) | PlanningController (뷰 반환만) | 없음 |
| 공사현장 사진대지 | React SPA + API | Controller + Service | 2 테이블 |
| 회의록 작성 | React SPA + API | Controller + Service + AI | 2 테이블 |

---

## 3. 외부 서비스 의존성

| 서비스 | 용도 | 추적 |
|--------|------|------|
| **Google Cloud Storage** | 사진/오디오 파일 저장 | `AiTokenHelper::saveGcsStorageUsage()` |
| **Google Speech-to-Text V2 (Chirp2)** | 자동 화자 분리 (최우선) | `AiTokenHelper::saveSttUsage()` |
| **Google Speech-to-Text V1** | 화자 분리 (V2 실패 시 폴백) | `AiTokenHelper::saveSttUsage()` |
| **Gemini API (Vertex AI)** | 요약 생성 + 화자 재분배 | `AiTokenHelper::saveGeminiUsage()` |
| **Web Speech API** | 브라우저 음성 입력 (현장명/설명) | `logSttUsage()` |

### 3.1 도메인 용어 힌트 (STT 정확도 향상)

```
블라인드, 스크린, 롤스크린, 허니콤, 버티컬,
원단, 바텀레일, 헤드레일, 브라켓,
주일, 경동, 주일블라인드, 경동블라인드,
수주, 발주, 납기, 출하, 재고, 원가, 단가,
SAM, ERP, MES
```

---

## 4. HTMX 전체 페이지 로드 규칙

모든 `/juil/*` 페이지는 React 인라인 컴포넌트를 사용하므로, HTMX 부분 로드 시 스크립트가 실행되지 않는다. 각 컨트롤러 메서드에서 HTMX 요청 감지 시 **HX-Redirect로 전체 페이지 리로드를 강제**한다.

```php
if ($request->header('HX-Request')) {
    return response('', 200)->header('HX-Redirect', route('juil.estimate'));
}
```

---

## 5. 관련 문서

- [공사현장 사진대지](construction-photos.md) — GCS 파일 관리, 행 구조, 음성 입력
- [회의록 작성](meeting-minutes.md) — STT/화자분리/AI 요약, 오디오 녹음
- [견적/프로젝트/워크플로우](planning-views.md) — React 뷰 구성, 업무 프로세스 정의

---

**최종 업데이트**: 2026-03-06