# 🛠️ Phase 1 & 2 기술 심층 명세 및 에러 방지 전략

Phase 1(텍스트 고도화)과 Phase 2(음성 혁신)의 성공적인 구현을 위해 발생 가능한 기술적 병목과 해결책을 심층적으로 정의합니다.

---

## 🏗️ 1. 공통 기반 아키텍처 (Shared Foundation)

### 🔐 1.1. 보안 및 암호화 강화
*   **문제**: 서버 사이드 대칭키(`AI_ENCRYPTION_KEY`) 분실 시 모든 사용자의 API 키 복구 불가능.
*   **해결책**: 
    1.  Key Rotation 정책 수립.
    2.  암호화 실패 시 사용자에게 "설정 재등록" 가이드를 명확히 노출하는 Error Boundary 구축.
*   **에러 방지**: `encryption.ts`에서 `Buffer.from(ENCRYPTION_KEY)` 시 32바이트 길이 체크 로직 추가.

---

## 📝 2. Phase 1: 텍스트 지능 고도화 (Deep Dive)

### 2.1. 자동 백링크 시스템 (Auto-Backlinking)
*   **작동 원리**: 에디터에 타이핑 시, 서버가 DB의 모든 문서 제목/헤더를 인덱싱하여 현재 문구와 일치하는 부분을 `[[ ]]`로 변환 제안.
*   **코딩 포인트**: 
    -   **Performance**: 매 타이핑마다 전체 DB 검색은 불가능. 클라이언트 측에 `WikiMap` (Title-ID 매핑 데이터)을 캐싱하고 Web Worker에서 비교 수행.
    -   **Conflict**: 이미 수동으로 걸어둔 링크와 중복 처리되지 않도록 정규표현식(`(?<!\[)\[\[...\]\]`) 정밀 설계.

### 2.2. 보험 도메인 특화 프롬프트 큐레이션
*   **작동 원리**: 단순 요약이 아닌 '손해사정', '설계안 분석' 등 5가지 프리셋 제공.
*   **에러 방지**: 프롬프트가 너무 길어질 경우 토큰 손실 발생. 시스템 프롬프트를 공통 모듈화하여 관리.

---

## 🎙️ 3. Phase 2: AI Whispers (Voice Innovation)

### 3.1. 실시간 오디오 스트리밍 (WebRTC/WebSockets)
*   **문제**: HTTP POST 방식으로는 '실시간성' 확보 불가 (2~3초 지연 발생).
*   **해결책**: 
    1.  **Next.js API Route 한계**: 서버리스 환경에서는 긴 연결(WebSocket) 유지가 어려움.
    2.  **대안**: 외부 오디오 처리 전용 실시간 서버(예: Node.js/Socket.io on Fly.io) 또는 구글의 **Gemini Live SDK**를 클라이언트에서 직접 통신(Edge-to-Google) 방식으로 설계.
*   **에러 방지**: 네트워크 단절 시 오디오 버퍼를 유실하지 않도록 IndexedDB에 임시 저장 후 재전송 시도.

### 3.2. VAD (Voice Activity Detection) 및 노이즈 필터링
*   **작동 원리**: 브라우저 단에서 말소리가 들릴 때만 서버에 데이터 전송.
*   **코딩 포인트**: `analyzerNode`의 `getByteFrequencyData`를 활용하여 에너지 임계값(Threshold) 기반 패킷 전송 로직 구현. (비용 50% 절감 효과)

### 3.3. PII (개인정보) 실시간 마스킹
*   **작동 원리**: 음성이 텍스트로 변환되는 즉시 정규식과 LLM을 통해 주민번호, 폰번호 감지.
*   **에러 방지**: 텍스트가 DB(`Daily Notes`)에 저장되기 전, API Proxy 레이어에서 반드시 마스킹 함수를 거치도록 'Pipe' 구조 설계.

---

## 📱 4. 멀티 디바이스 시너지 (Mobile-PC Handover)

사용자가 핸드폰으로 음성 기록(AI Whispers)을 하고 PC에서 즉시 편집하는 시나리오를 위한 기술적 장치입니다.

### 4.1. 실시간 상태 동기화 (Firestore Real-time)
*   **작동 원리**: 핸드폰에서 생성되는 음성 텍스트가 `Daily Notes` 컬렉션에 조각 단위로 저장되면, PC 화면이 이를 리얼타임 리스너(`onSnapshot`)로 감시하여 화면에 즉시 렌더링.
*   **코딩 포인트**: 불필요한 전체 문서 렌더링을 방지하기 위해 `transcriptionChunks`라는 서브 컬렉션 또는 배열 필드를 활용하여 증분 업데이트(Incremental Update) 수행.

### 4.2. 모바일 친화적 보이스 UI (PWA & MediaRecorder)
*   **작동 원리**: 모바일 브라우저의 전원 관리 정책으로 인해 화면이 꺼지면 녹음이 중단될 수 있음.
*   **해결책**: **PWA(Progressive Web App)** 기술을 적용하여 서비스 워커 기반의 백그라운드 오디오 캡처 안정성 확보.
*   **코딩 포인트**: iOS와 Android의 `MediaRecorder` API 구현 차이를 흡수하는 `AudioProvider` 추상화 레이어 구축.

### 4.3. 세션 핸드오버 (Active Session Indicator)
*   **작동 원리**: PC로 접속 시 "현재 핸드폰에서 AI Whispers가 진행 중입니다"라는 알림과 함께 실시간 스트리밍 가로채기(Takeover) 또는 동시 모니터링 기능 제공.

---

## 🛠️ 5. 고급 신뢰성 장치 (Advanced Reliability)

### 5.1. 화자 분리 및 출처 표기 (Diarization & Citation)
*   **작동 원리**: 멀티모달 오디오 스트림에서 설계사와 고객의 인코딩을 분리하여 기록. 요약 결과에는 해당 약관의 원본 PDF 페이지 링크를 자동 첨부.
*   **코딩 포인트**: Gemini 응답 시 `metadata` 필드에 인용된 문서의 ID와 Page 정보를 포함하도록 프롬프트 엔지니어링 수행.

### 5.2. 하이브리드 오프라인 모드 (Hybrid Offline)
*   **작동 원리**: 네트워크 감지 API(`navigator.onLine`) 연동. 오프라인 시 Blob 객체로 로컬 캐싱 후 온라인 복구 시 즉시 업로드 및 서버 사이드 추론 시작.

---

## ⚠️ 6. 에러 대응 및 복원력 (Robustness)

| 발생 가능한 에러 | 대응 전략 (Strategy) | 구현 위치 |
| :--- | :--- | :---: |
| API Rate Limit 초과 | 429 에러 감지 시 큐(Queue)에 적재 후 지수 백오프(Exponential Backoff) 재시도 | API Proxy |
| 오디오 패킷 손실 | 프레임 번호를 부여하여 누락된 구간 재요청 또는 무음 처리 | Unified AI Hub |
| 암호화 키 불일치 | `decryption` 실패 시 `aiSettings` 초기화 권장 배너 노출 | Settings Page |
| Gemini 모델 응답 지연 | 낙관적 UI(Optimistic UI) - "분석 중..." 상태를 실시간 음파와 연동하여 체감 지연 제거 | AISidepanel |

---

## 🚀 5. 구현 단계별 체크리스트

- [ ] **Step 7**: 화자 분리(Diarization) 테스트 및 UI 반영
- [ ] **Step 8**: 오프라인 하이브리드 싱크 로직 구현
- [ ] **Step 9**: 모바일 발열 제어를 위한 오디오 인코딩 최적화