# 📘 인슈위키(InsuWiki) 사용자 가이드

인슈위키는 보험 전문가를 위한 **집단지성 지식 관리 시스템**입니다.
이 가이드는 인슈위키의 핵심 철학인 **"지식의 공유와 보존"**을 실현하기 위한 기능과 규칙을 설명합니다.

---

## 1. 세 가지 작업 공간 (Workspaces)

인슈위키는 목적에 따라 세 가지의 명확히 구분된 작업 공간을 제공합니다.

| 공간 이름 | 아이콘 | 목적 | 기본 공개 범위 | 특징 |
| :--- | :---: | :--- | :--- | :--- |
| **Knowledge Wiki** | 🌏 | **완성된 지식**의 공유 | **팀 전체 (Public)** | 동료들과 함께 만들어가는 정제된 지식 창고입니다. |
| **My Private Space** | 🔒 | **개인적인 초안** 및 생각 | **비공개 (Private)** | 나만 볼 수 있는 공간입니다. 아이디어를 정리하고 다듬는 인큐베이터입니다. |
| **Daily Notes** | 📅 | **매일의 업무** 및 기록 | **비공개 (Private)** | 날짜별로 자동 생성되는 업무 일지입니다. 절대 공유되지 않습니다. |

---

## 2. 공개 범위와 지식 보존 원칙 (Visibility Rules)

인슈위키는 **"한 번 공유된 지식은 모두의 자산"**이라는 철학을 가지고 있습니다. 이에 따라 다음과 같은 독특한 보안 규칙이 적용됩니다.

### 🔒 비공개 (Private)
*   **나만 볼 수 있습니다.** (작성자 본인)
*   아직 정리되지 않은 생각이나 개인적인 메모를 적는 상태입니다.
*   언제든지 **'공유(Team)'** 버튼을 눌러 위키로 발행할 수 있습니다.

### 🌏 팀 공유 (Public) - "Contributor Lock"
*   **팀원 전체가 볼 수 있습니다.**
*   **⚠️ 중요 규칙**: 문서가 공개된 후, **다른 팀원이 한 글자라도 기여(수정)하는 순간**, 해당 문서는 **다시 비공개로 되돌릴 수 없습니다.**
    *   *이유: 동료의 지식이 섞인 문서를 개인이 독점하거나 숨기는 것을 방지하기 위함입니다.*
*   **예외**: 나 혼자만 작성한 상태라면, 언제든지 다시 비공개로 되돌릴 수 있습니다. (오타 수정 등 단순 변심 허용)

---

## 3. 에디터 활용법 (Smart Editor)

### 🔗 위키 링크 (WikiLink)
문서 간의 연결은 인슈위키의 핵심입니다.
*   **사용법**: `[[`를 입력하면 자동으로 문서 검색/생성 메뉴가 뜹니다.
*   **✨ 실시간 자동 백링크 (Zero-Friction Link)**:
    -   본문을 타이핑하는 동안 이미 존재하는 위키 문서의 제목이 감지되면 **파란색 점선**이 자동으로 표시됩니다.
    -   **클릭 한 번**: 점선이 표시된 단어를 클릭하면 즉시 공식 위키 링크(`[[제목]]`)로 변환됩니다. 검색할 필요조차 없는 지능형 연결 기능입니다.
*   **새 문서 만들기**: 존재하지 않는 제목을 `[[새로운 개념]]` 처럼 입력하고 클릭하면, 즉시 새 문서가 생성됩니다.
*   **똑똑한 상속**:
    *   **비공개 문서**나 **데일리 노트**에서 만든 새 문서는 자동으로 **비공개(Private)**로 생성됩니다.
    *   작성 중인 생각의 흐름을 끊지 않고 안전하게 새 문서를 만들 수 있습니다.

> [!TIP]
> **초성 검색 지원**: 위키 링크 입력 시 전체 단어를 칠 필요 없이 초성만 입력해도 문서를 찾아줍니다. (예: `[[ㄴㅅㅍㄹ` 입력 시 "누수플랜" 검색)

### 📝 마크다운 (Markdown) 지원
익숙한 마크다운 문법을 그대로 사용할 수 있습니다.
*   `# 제목 1`, `## 제목 2`
*   `- 리스트`, `1. 번호 매기기`
*   `**굵게**`, `_기울임_`
*   `> 인용구`

---

## 4. 자주 묻는 질문 (FAQ)

**Q. 데일리 노트도 공유할 수 있나요?**
A. 아니요. 데일리 노트는 시스템적으로 **영구 비공개**로 설계되었습니다. 공유가 필요한 내용은 위키 문서로 새로 작성하거나, 내용을 복사해서 옮겨주세요.

**Q. 실수로 문서를 공개해버렸어요!**
A. 걱정하지 마세요. 아직 다른 팀원이 보거나 수정하지 않았다면, 상단의 **'비공개(Private)'** 버튼을 눌러 다시 숨길 수 있습니다.

**Q. 문서를 삭제하고 싶어요.**
A. 본인이 작성한 **비공개 문서**는 언제든 삭제할 수 있습니다. 하지만 **공개된 문서**는 지식 파괴를 방지하기 위해 **관리자에게 요청**해야 삭제할 수 있습니다. (내용을 비우는 것은 가능합니다)

---

## 5. 회원 권한 및 로그인 (Login & Roles)

인슈위키의 모든 문서는 보안을 위해 **승인된 회원**만 열람할 수 있습니다.

### 👥 회원 승인제 (Approval System)
1.  **가입 직후 (Guest)**: 구글 로그인을 해도 처음에는 **'승인 대기'** 상태가 됩니다. 이 상태에서는 문서를 볼 수 없습니다.
2.  **관리자 승인**: 관리자가 가입을 확인하고 승인해야 **'정회원(Member)'**이 됩니다.
3.  **정회원 (Member)**: 승인 후에는 자유롭게 문서를 열람하고 작성할 수 있습니다.

### 🔗 공유 링크 (Shared Links)
*   **카카오톡/문자로 링크를 받았을 때**:
    1.  링크를 클릭하면 **"로그인이 필요합니다"** 화면이 뜹니다.
    2.  **[로그인 하러 가기]** 버튼을 누르면 구글 로그인 페이지로 이동합니다.
    3.  로그인(및 승인)이 완료되면, **원래 보려던 문서로 자동으로 다시 이동**합니다.
*   **주의사항**: 카카오톡 등 인앱 브라우저에서는 구글 로그인이 원활하지 않을 수 있어, 자동으로 **크롬(Chrome)이나 사파리(Safari)** 등 외부 브라우저가 열릴 수 있습니다. 이는 정상적인 동작입니다.

---

## 7. 문서 삭제 및 복원 (Delete & Restore)

실수로 문서를 삭제했더라도 걱정하지 마세요. 인슈위키는 안전한 **휴지통(Soft Delete)** 기능을 제공합니다.

### 🗑️ 문서 삭제 (Soft Delete)
*   **방법**: 문서 상세 페이지에서 **[삭제]** 버튼을 클릭합니다.
*   **결과**: 문서가 즉시 사라지지 않고 **'휴지통'** 상태로 변경됩니다. 목록이나 검색에서는 더 이상 보이지 않습니다.
*   **권한**:
    *   **Public Wiki**: 관리자(Admin)만 삭제 가능합니다.
    *   **Private / Daily**: 작성자 본인이 삭제할 수 있습니다.

### 🗂️ 휴지통 페이지 (/trash)
헤더 우측 상단의 **사용자 프로필을 클릭**한 뒤, 드롭다운 메뉴에서 **'휴지통'**을 선택하면 이동합니다.

*   **일반 사용자**: 본인이 삭제한 문서 목록 확인 + 복원
*   **관리자**: 전체 삭제 문서 목록 확인 + 복원 + 영구 삭제
*   삭제 날짜 최신순으로 정렬되며, Wiki / My / Daily 타입이 배지로 표시됩니다.

### ♻️ 문서 복원 (Restore)
삭제된 문서를 다시 살릴 수 있는 방법은 두 가지입니다.

**방법 1 — 휴지통 페이지 이용 (권장)**:
1.  프로필 메뉴 → 휴지통 선택 → 복원할 문서 찾기 → **[복원]** 버튼 클릭

**방법 2 — URL 직접 접근**:
1.  삭제된 문서의 URL로 직접 접속합니다.
2.  문서 상단에 붉은색의 **"이 문서는 휴지통에 있습니다"** 배너가 표시됩니다.
3.  배너 내의 **[문서 복원하기]** 버튼을 클릭하면 즉시 복구됩니다.

---

## 8. 변경 이력 및 복원 (Revision History & Restore)

문서가 수정될 때마다 자동으로 스냅샷이 저장되어, 언제든지 과거 버전으로 되돌릴 수 있습니다.

### 🕒 변경 이력 확인
*   **방법**: 문서 페이지 상단의 **히스토리(🕒)** 버튼을 클릭합니다.
*   **목록**: 최근 수정된 순서대로 버전(v1, v2...)과 작성자, 수정 시간이 표시됩니다.
*   **Squash 전략**: 5분 이내에 동일한 작성자가 연속으로 수정하는 경우, 목록이 너무 길어지는 것을 방지하기 위해 하나의 이력으로 합쳐집니다.

### ♻️ 버전 복원 (Restore)
*   **방법**: 히스토리 목록에서 복원하고 싶은 버전의 **[이 버전으로 복원]** 버튼을 클릭합니다.
*   **작동 방식**: 현재 내용이 새로운 버전으로 자동 저장된 후, 선택한 과거 버전의 내용으로 본문이 교체됩니다.

---

## 9. 관리자 기능 (Admin Features)

관리자 권한을 가진 사용자에게만 제공되는 기능입니다.

### 👥 사용자 관리 (User Management)
*   **접속 방법**: 우측 상단 프로필 메뉴 > **[사용자 관리]** 클릭 (또는 `/admin/users` 접속)
*   **기능**:
    *   **가입 승인**: 'Guest' 상태의 사용자를 'Member'로 변경하여 문서를 볼 수 있게 합니다.
    *   **권한 회수**: 퇴사자 등의 접근을 차단하려면 'Member' -> 'Guest'로 변경합니다.
    *   **관리자 임명**: 'Member' -> 'Admin'으로 변경하여 관리자 권한을 부여할 수 있습니다.

### 🗑️ 문서 관리
*   공개된 문서(Knowledge Wiki)를 삭제할 수 있는 권한이 있습니다.
*   삭제 시 복구가 불가능하므로 신중하게 결정해야 합니다.

---

## 10. 파일 첨부 (File Attachments)

문서에 이미지나 PDF 등의 파일을 첨부할 수 있습니다.

*   **업로드**:
    *   문서 하단의 **[파일 업로드]** 버튼을 클릭하여 파일을 선택합니다.
    *   **제한**: 최대 **50MB**까지 업로드 가능합니다.
    *   **권한**: 정회원(Member) 이상만 업로드가 가능합니다.
*   **조회 및 다운로드**:
    *   첨부된 파일 목록에서 파일명을 클릭하여 내용을 확인하거나 다운로드할 수 있습니다.
*   **삭제**:
    *   작성자 본인 또는 관리자만 첨부된 파일을 삭제할 수 있습니다.

### ⚙️ 시스템 관리자 정보 (System Admin Note)
*   인슈위키의 모든 파일은 **Google Drive**를 저장소 백엔드로 사용합니다.
*   관리자는 개인 구글 계정의 용량(5TB 등)을 활용하여 무제한에 가까운 저장 공간을 확보할 수 있습니다.
*   상세 세팅 방법은 [Google Drive OAuth2 설정 가이드](../specs/260215-16.10-google-drive-oauth2-setup.md)를 참고하세요.
---

## 11. AI 문서 어시스턴트 (AI Document Assistant ✨)

Gemini AI를 활용하여 문서를 요약하거나 최적의 구조로 정리할 수 있습니다.

### 🔑 개인 API 키 설정 (BYOK)
인슈위키는 사용자의 개인 API 키를 사용하는 **BYOK(Bring Your Own Key)** 방식을 채택합니다.
1.  헤더 우측 상단의 **사용자 프로필 메뉴를 클릭**한 뒤 **'AI 설정'**을 선택합니다.
2.  [Google AI Studio](https://aistudio.google.com/app/apikey)에서 발급받은 **Gemini API Key**를 입력하고 저장합니다.
3.  키는 암호화되어 안전하게 보관되며, 언제든지 변경하거나 삭제할 수 있습니다.

### ✨ AI 핵심 기능
데스크톱 환경에서는 메뉴의 **AI 설정**에서, 모바일에서는 문서의 하단(버튼 그룹)에 있는 **AI 로고(✨)**를 눌러 AI 패널을 열 수 있습니다.
*   **📝 요약하기**: 긴 문서를 핵심 위주로 3~5문장으로 요약합니다.
*   **🪜 구조화**: 마크다운 계층 구조를 분석하여 가독성이 높은 구조로 제안합니다.
*   **🔍 정보 추출**: 문서 내의 중요한 키워드와 데이터를 요약 정리합니다.
*   **✅ 문서에 적용**: AI가 생성한 내용을 현재 편집 중인 문서에 즉시 삽입할 수 있습니다.

> [!TIP]
> **보험 약관 요약**이나 **고객 상담 일지 정리** 시에 활용하면 작업 효율을 극대화할 수 있습니다.

---

## 12. 📄 약관 PDF AI 검색 (Insurance PDF Query)

보험 약관 PDF를 AI가 직접 읽고 사용자의 질문에 답변하는 **롱 컨텍스트 질의 기능**입니다.

> [!IMPORTANT]  
> 이 기능을 사용하기 위해서는 Google Drive에 보험사/상품 약관 PDF가 등록되어 있어야 합니다. 등록은 관리자가 담당합니다.

### 🚀 사용 방법

1. **검색 모달 열기** (`Ctrl+K` 또는 화면 상단 검색 아이콘 클릭)
2. 상단 탭에서 **📄 약관 PDF** 탭을 선택합니다.
3. **보험사** 드롭다운에서 회사를 선택합니다.
4. **상품** 드롭다운에서 질의할 상품을 선택합니다.
5. 질문을 입력하고 **[AI에게 물어보기]** 버튼을 클릭합니다.
6. 최대 3분 내로 AI 분석 결과가 표시됩니다.

> [!TIP]
> **질문 예시**:  
> - "35세 남성 기준 3대 질병 진단비 보험료가 얼마인가요?"  
> - "이 상품의 면책 기간은 어떻게 되나요?"  
> - "보험료 납입 면제 조건을 설명해 주세요."

### ⏳ 처리 시간

- 약관 PDF 크기 및 서버 상황에 따라 **30초 ~ 3분** 소요될 수 있습니다.
- 처음 질의 시에는 PDF를 서버에 업로드하는 시간이 추가됩니다. 같은 상품을 반복 질의할 때는 **캐시**가 적용되어 훨씬 빠릅니다.
- 3분이 초과되면 자동으로 타임아웃 처리됩니다. 이 경우 [다시 시도] 버튼을 클릭하세요.

---

## 13. 🎙️ 음성 인식 기능 (Voice Recognition)

인슈위키는 Web Speech API를 활용하여 **음성으로 검색, 받아쓰기, 명령**을 수행할 수 있습니다.

### 🔍 음성 검색
1.  검색 모달(Ctrl+K)을 열면 검색창 옆에 **마이크(🎤) 버튼**이 표시됩니다.
2.  마이크 버튼을 탭하면 음성 인식이 시작됩니다.
3.  검색하고 싶은 내용을 말하면 **자동으로 검색어가 입력**되고 검색이 실행됩니다.

### 📝 음성 받아쓰기 (편집 모드)
문서 편집 중 우측 하단에 **보라색 마이크 FAB 버튼**이 표시됩니다.
1.  FAB 버튼을 탭하면 받아쓰기가 시작됩니다.
2.  말하는 내용이 **실시간으로 에디터에 입력**됩니다.
3.  다시 탭하면 받아쓰기가 중지됩니다.

> [!TIP]
> **상담 내용 기록** 시 음성 받아쓰기를 활용하면 타이핑 없이 빠르게 메모할 수 있습니다.

### 🗣️ 음성 명령
앱 전체에서 다음과 같은 음성 명령을 사용할 수 있습니다 (25개, 5개 그룹):

#### 내비게이션
| 음성 명령 | 동작 |
|-----------|------|
| "새 문서" / "새문서" / "문서 만들어" | 새 문서 작성 페이지로 이동 |
| "홈으로" / "메인" | 메인 페이지로 이동 |
| "뒤로" / "이전 페이지" | 이전 페이지로 이동 |
| "데일리 노트" / "오늘 일지" | 데일리 노트 이동 |

#### 검색
| 음성 명령 | 동작 |
|-----------|------|
| "검색" / "검색해줘" / "찾아줘" | 검색 모달 열기 |
| "AI 검색" / "인텔리서치" | AI 검색 모달 열기 |
| "위키 검색" / "일반 검색" | 일반 검색 모달 열기 |
| "음성 검색" / "말로 검색" | 음성 검색 시작 |

#### 에디터 제어 (문서 편집 중)
| 음성 명령 | 동작 |
|-----------|------|
| "편집" / "편집 모드" / "수정" | 편집 시작 |
| "편집 취소" / "취소" | 편집 취소 |
| "저장" / "저장해줘" | 현재 문서 저장 |
| "줄 바꿔" / "다음 줄" / "엔터" | 줄 바꿈 삽입 |
| "새 문단" / "문단 나눠" | 새 문단 삽입 |
| "할 일" / "체크리스트" | 체크리스트 항목 삽입 |
| "되돌려" / "실행 취소" / "언두" | 실행 취소 |

#### 문서 관리
| 음성 명령 | 동작 |
|-----------|------|
| "공개해" / "위키로 공개" | 문서 공개(Public)로 전환 |
| "비공개" / "비공개로" / "잠가" | 문서 비공개로 전환 |
| "삭제" / "삭제해" / "지워줘" | 문서 삭제 |
| "히스토리" / "수정 이력" | 수정 이력 모달 열기 |
| "AI 열어" / "AI 도우미" | AI 사이드 패널 열기 |

#### 녹음 제어
| 음성 명령 | 동작 |
|-----------|------|
| "받아쓰기" / "받아쓰기 시작" | 받아쓰기 시작 |
| "받아쓰기 중지" / "중단" | 받아쓰기 중지 |
| "잠깐" / "일시정지" / "멈춰" | 일시정지 |
| "녹취 시작" / "녹음해" | 동의 녹취 모달 → 녹음 시작 |
| "녹취 종료" / "녹음 끝" | 녹취 종료 |

> [!WARNING]
> **녹취 기능**은 통신비밀보호법에 의거, 상대방의 동의 확인 체크박스 2개를 모두 체크해야 녹음이 시작됩니다.

### 📱 모바일 AI 바 (Mobile AI Bar & Smart Insert)
모바일 환경에서는 하단에 **"AI 비서"** 플로팅 버튼이 표시됩니다.
1.  **스마트 삽입 (Smart Insert)**:
    *   **읽기 모드**에서 음성 인식 후 **[본문 삽입]** 버튼을 누르면, **자동으로 편집 모드로 전환**되어 내용이 즉시 추가됩니다.
    *   삽입 후에는 **AI 바가 자동으로 닫히며**, 결과물을 바로 확인하고 이어서 작성할 수 있습니다. (Auto-close)
2.  **✨ AI 다듬기 (Magic Wand)**:
    *   **[요술봉]** 버튼을 누르면, 두서없는 구어체를 **완벽한 문어체로 재작성(Rewrite)**해줍니다.
    *   **[New] 자동 리스트 변환**: "1번", "첫째"나 "2의 1번"이라고 말하면, AI가 문맥을 파악하여 자동으로 `1.`, `-`, `2.1.` 등의 마크다운 리스트 문법으로 깔끔하게 정리해줍니다.
    *   단순 오타 교정을 넘어, 문장 구조를 전문가스럽게 바꿔줍니다. (Rewrite)
3.  **스마트 자동 번호 매기기 (Auto-Numbering)**:
    *   텍스트뿐만 아니라 **상담 녹음 파일(🎙️)**을 삽입할 때도 앞줄의 번호 형식을 인식하여 자연스럽게 이어집니다.
    *   (예: `1. 개요` -> `2. [내용]`, `1.1. 상세` -> `1.2. [녹음파일]`)
    *   **[New] 빈 문서 자동 생성**: 새 데일리 노트에서 바로 녹음을 해도, 문서가 자동으로 생성되며 안전하게 저장됩니다.
4.  **권한 자동 감지**:
    *   내 문서가 아니거나 편집 권한이 없는 경우, [본문 삽입] 버튼 대신 **[복사]** 버튼이 표시되어 실수를 방지합니다.

### 📱 지원 환경

| 환경 | 지원 여부 |
|------|:---------:|
| Android Chrome | ✅ |
| iOS Safari (14.5+) | ✅ |
| PC Chrome / Edge | ✅ |
| Firefox | ❌ |

> [!NOTE]
> 음성 데이터는 Google(Chrome) 또는 Apple(Safari)의 STT 서버로 전송됩니다. 민감한 고객 정보가 포함된 상담 내용을 음성 입력할 때는 주의하시기 바랍니다.