# 📘 프로젝트 명세서 (Project Specification)

**프로젝트명:** VOC Notification System (부산교통공사 VOC 수집/알림/보고서 생성기)
**버전:** v1.2
**아키텍처:** MVC 패턴 (Model-View-Controller)
**프레임워크:** CustomTkinter (UI), DrissionPage (Scraping), SQLite (DB), ReportLab/HWP Automation (Report)

---

## 🏗️ 1. 아키텍처 개요 (Architecture Overview)

이 프로젝트는 부산교통공사 홈페이지의 '고객의 소리(VOC)' 게시판을 자동 수집하고, 특정 키워드/부서 관련 게시글이 발생하면 사용자에게 알림을 제공하며, 이를 바탕으로 HWP/PDF 보고서를 생성하는 데스크톱 애플리케이션이다.

### 📦 디렉토리 구조 (Directory Structure)

```
d:\py_train\voc_noti\app\
├── main.py              # 🚀 [Entry Point] 앱 실행 진입점. Controller 초기화 및 실행.
├── assets\              # 🎨 [Assets] 아이콘, 폰트, DLL 등 정적 자원
│   ├── app_icon.png     # 애플리케이션 아이콘
│   ├── GmarketSansTTFMedium.ttf # 커스텀 폰트
│   ├── FilePathCheckerModule.dll # HWP 보안 승인 모듈
│   └── VOC_Sample.hwp   # 보고서 템플릿
├── data\                # 💾 [Data] 설정 파일 및 DB
│   ├── config.json      # 사용자 설정 (역명 리스트 등)
│   ├── settings.json    # 앱 실행 설정 (로그인 정보, 키워드 등)
│   └── voc.db           # SQLite 데이터베이스
├── controllers\         # 🎮 [Controller]
│   └── controller.py    # 메인 컨트롤러 (AppController)
├── models\              # 🧠 [Model]
│   └── model.py         # Pydantic 데이터 모델 (VOCPost)
├── services\            # 🕵️ [Service] 비즈니스 로직
│   ├── scraper_service.py # 웹 스크래핑 (DrissionPage)
│   └── report_service.py  # 보고서 생성 (HWP/PDF Automation)
├── utils\               # 🛠️ [Utils]
│   └── database.py      # DB 접근 (DAO)
└── view\                # 🎨 [View] UI 레이어 (CustomTkinter)
    ├── __init__.py
    ├── theme.py         # 폰트(Gmarket Sans) 및 테마 관리
    ├── ui_utils.py      # 자산 로더 (AssetLoader)
    ├── components\      # 재사용 컴포넌트
    └── dialogs\         # 각종 팝업 다이얼로그
```

---

## 🧠 2. 데이터 모델 (Data Model) : `VOCPost`

`app/models/model.py`에 정의된 Pydantic 모델을 사용한다.

| 필드명 | 타입 | 설명 |
|---|---|---|
| `id` | `str` | 접수 번호 (PK) |
| `title` | `str` | 게시글 제목 |
| `writer` | `str` | 작성자 |
| `date` | `str` | 작성 일자 |
| `department` | `str` | 담당 부서 |
| `is_public` | `int` | 공개 여부 (1/0) |
| `status` | `str` | 처리 상태 |
| `content` | `str` | 본문 내용 |
| `answer` | `str` | 답변 내용 |
| `line_str` | `str` | 호선 (유추 정보) |
| `train_details` | `dict` | 열차 상세 정보 |

---

## 🎮 3. 주요 기능 및 구현 상세 (Key Features)

### 3.1 🕵️‍♂️ 웹 스크래핑 (`VOCScraper`)
- **라이브러리:** `DrissionPage`
- **기능:** 
    - 관리자 페이지 로그인 및 세션 유지.
    - 목록 페이지 순회 및 신규/업데이트 감지.
    - 상세 페이지 파싱 (본문, 답변).

### 3.2 📄 보고서 생성 (`ReportService`)
- **HWP 보고서:** 
    - **보안 모듈:** `app/assets/FilePathCheckerModule.dll`을 사용하여 파일 접근 경고창을 억제함.
    - **동작 방식:** 레지스트리에 DLL 등록 후 `hwp.RegisterModule("FilePathCheckDLL", "FilePathCheckDLL")` 호출.
    - **자동화:** 템플릿(`VOC_Sample.hwp`)의 누름틀(Field)에 데이터를 자동 입력.
    - **정보 유추:** 본문 텍스트 분석을 통해 관련 호선(1호선 등) 및 열차 방향(상선/하선)을 자동 판단.
- **PDF 보고서:** 
    - **라이브러리:** `ReportLab`
    - `Malgun Gothic` 폰트를 사용하여 한글 깨짐 방지.

### 3.3 🎨 UI 및 테마 (`ThemeManager`)
- **폰트:** `app/assets/GmarketSansTTFMedium.ttf`를 동적으로 로드하여 애플리케이션 전반에 적용.
- **스타일:** 다크/라이트 모드 지원, `blue` 컬러 테마.

### 3.4 🔔 알림 시스템 (Notification)
- **라이브러리:** `winotify`
- **시작 알림:** 앱 실행 시 윈도우 토스트(Popup) 알림을 통해 백그라운드 실행 여부를 사용자에게 즉시 인지시킴.
- **트레이 아이콘:** `pystray`를 사용하여 시스템 트레이에 상주하며, 아이콘 우클릭으로 창 열기/종료 제어 가능.

## 📦 4. 빌드 및 배포 (Build & Deployment)

### 4.1 cx_Freeze 설정
- **기반:** `setup.py`를 통해 exe 파일 생성.
- **경로 처리:** `utils/path_utils.py`를 사용하여 개발 환경(`__file__` 기준)과 빌드 환경(`sys.executable` 기준)의 에셋/설정 파일 경로 차이를 자동으로 보정.
- **포함 파일:**
  - `assets/`: 아이콘, 폰트, HWP 보안 DLL, 보고서 템플릿 포함.
  - `data/`: 사용자 설정(settings.json) 및 초기 데이터 포함.
- **주의사항:** `setup.py`의 `include_files` 옵션이 빌드된 exe 폴더 루트에 해당 폴더들을 복사하도록 설정됨.

### 5. 바이브 코딩 (Vibe Coding) 원칙 준수
- **한국어 우선:** 모든 문서, 주석, 로그는 한국어로 작성.
- **완결성:** 모든 기능은 Mock이 아닌 실제 동작 가능한 코드로 구현.
- **사용자 친화적:** 복잡한 설정 없이 실행만으로 동작하도록 구성 (보안 모듈 자동 등록 등).