109 lines
5.5 KiB
Markdown
109 lines
5.5 KiB
Markdown
# 📘 프로젝트 명세서 (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이 아닌 실제 동작 가능한 코드로 구현.
|
|
- **사용자 친화적:** 복잡한 설정 없이 실행만으로 동작하도록 구성 (보안 모듈 자동 등록 등).
|