5.5 KiB

Raw Blame History

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

5.5 KiB Raw Blame History