# GLOBEAU.KR 파일 기반 마크다운 뷰어 시스템 통합 명세서

## 1. 개요 및 기술 스택
* **시스템 명칭:** 파일 기반 마크다운 뷰어 시스템 (File-based Markdown Viewer System)
* **목적:** 데이터베이스 없이 서버 저장소에 위치한 마크다운(`.md`) 파일을 직접 읽어와 웹에서 체계적으로 조회, 장별 그룹화, 수동 정렬, 맞춤형 타이틀 매핑 및 다중 키워드 검색을 수행하는 자체 문서 센터 구축
* **Tech Stack:**
  * **Backend:** Laravel 13, PHP 8.4, Apache Web Server, Laravel Storage Facade
  * **Frontend UI:** Bootstrap 5, FontAwesome 6, GitHub Official Markdown CSS (`github-markdown-light.min.css`)
  * **Markdown & Highlighting Engine:** `marked.js` (클라이언트 마크다운 파서), `highlight.js` (소스코드 신택스 하이라이팅)

---

## 2. 파일 명명 규칙 및 디렉토리 구조
* **파일명 표준:** 대소문자 혼동 및 URL 인코딩 오류를 방지하기 위해 **모두 소문자와 언더바(`_`)를 조합한 형태**를 원칙으로 채택합니다. (예: `globeau_document.md`, `architecture.md`, `database.md`, `deployment.md`)
* **저장소 경로:** `storage/app/public/documents/*.md`

### 라우트 설정 (`routes/web.php`)
    use App\Http\Controllers\DocumentController;

    Route::get('/docs', [DocumentController::class, 'index']);       // 문서 목록, 장별 그룹화 및 다중 키워드 검색
    Route::get('/docs/{page}', [DocumentController::class, 'show']); // 개별 문서 상세 보기 및 자동 스크롤/하이라이팅

---

## 3. 백엔드 핵심 제어기 명세 (`DocumentController.php`)

### ① 맞춤형 타이틀 매핑 (`$titleMap`)
파일 슬러그별로 직관적인 한글 제목을 매핑하여 사용자 친화적인 목록 및 헤더 타이틀을 제공합니다.
    private function getDocumentTitle($slug)
    {
        $titleMap = [
            'architecture'    => '시스템 아키텍처 및 구조 설계',
            'database'        => '데이터베이스 설계 및 스키마',
            'deployment'      => '서버 배포 및 운영 가이드',
            'globeau_document'=> 'GLOBEAU.KR 기술 문서 구축 통합 명세서',
        ];
        return $titleMap[$slug] ?? ucfirst(str_replace('_', ' ', $slug));
    }

### ② 장별 챕터 분류 메타데이터 (`getDocumentSection`)
컨트롤러 레벨에서 문서 슬러그를 분석하여 1장, 2장, 부록 등의 섹션 메타데이터(`key`, `label`)를 동적으로 주입합니다.
    private function getDocumentSection($slug)
    {
        if (in_array($slug, ['architecture', 'database'])) {             return ['key' => 'chapter_1', 'label' => '제1장 - 시스템 및 데이터베이스 설계'];         } elseif (in_array($slug, ['deployment'])) {
            return ['key' => 'chapter_2', 'label' => '제2장 - 배포 및 운영'];
        } else {
            return ['key' => 'appendix', 'label' => '부록'];
        }
    }

### ③ 수동 정렬 순서 정의 (`$customOrder`)
개발자가 원하는 문서 우선순위 순서대로 목록 배열을 제어합니다.
    $customOrder = ['architecture', 'database', 'deployment', 'globeau_document'];

### ④ 다중 키워드 검색 및 파일당 매칭 제한
* 사용자가 입력한 검색어(`q`)를 분석하여 원본 구문, 공백 제거 형태, 2글자 이상의 개별 단어 조합으로 파싱합니다.
* 한 문서 내에서 검색 결과가 난립하지 않도록 **파일당 최대 5개 매칭 제한** 및 중복 위치 방지 로직을 적용하고, 주변 전후 텍스트를 발췌한 `snippet`과 고유 순번(`match_index`)을 부여합니다.

---

## 4. 프론트엔드 뷰 파이프라인

### ① 문서 목록 및 검색 뷰 (`resources/views/documents/index.blade.php`)
* 컨트롤러에서 전달받은 `section_key`를 기준으로 장별 구분 바(Header)를 동적으로 렌더링합니다.
* 실시간 검색 폼, 매칭 스니펫 미리보기, 업데이트 일시, 상세 보기 링크(`?highlight=...&index=N`)를 제공합니다.

### ② 개별 상세 뷰 및 자동 하이라이팅 (`resources/views/documents/show.blade.php`)
* `marked.js`를 통해 마크다운 문자열을 GitHub 스타일의 HTML로 안전하게 렌더링합니다.
* URL 파라미터에 검색어와 순번이 포함되어 있는 경우, 브라우저 내장 탐색 로직(`window.find()`)을 활용하여 지정된 N번째 위치를 정확히 탐색합니다.
* 선택된 영역을 주황-노란색 계열의 배경색을 가진 `mark` 요소로 동적 래핑하고, 해당 위치로 부드럽게 스크롤(`scrollIntoView`)하여 가독성을 극대화했습니다.