11 KiB

Raw Permalink Blame History

📋 Project Specification: VOC 모니터링 시스템

1. 프로젝트 비전

목표

부산교통공사 1호선 차량 관련 VOC(Voice of Customer)를 실시간으로 모니터링하고, 자동으로 보고서를 생성하여 업무 효율을 극대화합니다.

핵심 가치

자동화: 수동으로 웹사이트를 확인하던 작업을 자동화
신속성: 신규 VOC 발생 시 즉시 알림
정확성: 열차 정보 자동 추출 및 시각표 기반 검증
편의성: 한글(HWP) 보고서 자동 생성

핵심 페르소나

직무: 부산교통공사 차량 부서 직원
환경: Windows 10/11, 사내망
사용 패턴: 백그라운드 상시 실행, 알림 기반 대응

2. 시스템 범위 (Scope)

포함 기능

웹 크롤링: 부산교통공사 VOC 게시판 자동 수집
데이터베이스: SQLite 기반 로컬 저장
실시간 알림: Windows 토스트 알림
보고서 생성: HWP/PDF 자동 작성
열차 정보 분석: 시각표 기반 열차번호, 입고지 자동 추출
히스토리 관리: 과거 VOC 조회 및 필터링
설정 관리: 크롤링 주기, 알림 키워드 등

제외 기능 (Out of Scope)

❌ 웹 기반 UI (데스크톱 전용)
❌ 다중 사용자 지원 (1인 사용 전제)
❌ 클라우드 동기화
❌ 모바일 앱

3. 핵심 비즈니스 로직 (Core Logic)

3.1 크롤링 사이클

1. 로그인 세션 확인 (만료 시 재로그인)
2. 목록 페이지 수집 (최대 N페이지)
3. 키워드/부서 필터링
4. DB 저장 (Upsert)
5. 상세 내용 수집 (조건부)

3.2 알림 사이클

1. 마지막 체크 이후 신규 데이터 조회
2. 알림 키워드 필터링
3. 소리 재생 (설정 시)
4. 토스트 알림 표시

3.3 보고서 생성 프로세스

1. VOC 데이터 수신
2. VOCParser로 기본 정보 추출 (호선, 편성, 호차, 열차번호)
3. DateScheduleUtils로 날짜 타입 판별 (평일/주말/휴일)
4. TrainAnalyzer로 열차 정보 분석 (종별, 방향, 입고지)
5. TimetableService로 시각표 조회 및 검증
6. HWP 템플릿에 데이터 입력
7. 파일 저장 (중복 체크)

3.4 통계 분석 프로세스 (신규)

1. 사용자 입력 수신 (기간, 분석 옵션)
2. 입력 검증 (날짜 형식, 기간 제한)
3. DB에서 데이터 집계
   ├── 기간별 통계 (일/주/월/년)
   ├── 부서별 분포
   ├── 상태별 현황
   └── 키워드 빈도 분석
4. 차트 생성 (matplotlib/plotly)
   ├── 막대 그래프 (부서별, 상태별)
   ├── 선 그래프 (시계열 추이)
   ├── 파이 차트 (비율)
   └── 워드 클라우드 (키워드)
5. 보고서 생성 (Excel/PDF)
6. 파일 저장 및 열기

3.4.1 데이터 집계 로직

기간별 통계:

SELECT 
    DATE(date) as day,
    COUNT(*) as count
FROM voc_posts
WHERE date BETWEEN ? AND ?
GROUP BY DATE(date)
ORDER BY day

부서별 분포:

SELECT 
    department,
    COUNT(*) as count,
    ROUND(COUNT(*) * 100.0 / (SELECT COUNT(*) FROM voc_posts WHERE date BETWEEN ? AND ?), 2) as percentage
FROM voc_posts
WHERE date BETWEEN ? AND ?
GROUP BY department
ORDER BY count DESC

키워드 빈도 분석:

# 1. 모든 제목 + 내용 추출
# 2. 형태소 분석 (선택, 한글 처리)
# 3. 불용어 제거 ("의", "를", "이" 등)
# 4. 빈도 계산
# 5. TOP 10 추출

3.4.2 예외 케이스 처리

예외 상황	처리 방법	사용자 메시지
기간 내 데이터 없음	빈 보고서 생성	"선택한 기간에 VOC 데이터가 없습니다."
기간이 너무 긺 (1년 초과)	기간 제한	"최대 1년까지만 조회 가능합니다."
차트 생성 실패	텍스트 표만 생성	"차트 생성 실패. 표 형식으로 제공됩니다."
메모리 부족	데이터 샘플링	"데이터가 많아 일부만 표시됩니다."
Excel/PDF 생성 실패	에러 다이얼로그	"보고서 생성 중 오류 발생: [상세 메시지]"

3.4.3 성능 최적화

인덱스 추가:

CREATE INDEX IF NOT EXISTS idx_date ON voc_posts(date);
CREATE INDEX IF NOT EXISTS idx_department ON voc_posts(department);
CREATE INDEX IF NOT EXISTS idx_status ON voc_posts(status);
CREATE INDEX IF NOT EXISTS idx_date_department ON voc_posts(date, department);

쿼리 최적화:

기간 제한: 최대 1년
페이징: 대량 데이터 시 배치 처리
캐싱: 동일 기간 재조회 시 캐시 사용 (선택)

메모리 관리:

차트 생성 후 즉시 파일 저장
plt.close() 호출하여 메모리 해제
대용량 데이터 시 청크 단위 처리

4. 에러 처리 전략

4.1 부분 실패 허용 원칙

보고서 생성 시 일부 정보 조회 실패는 전체 작업을 중단하지 않습니다.

실패 유형	처리 방법	사용자 경험
열차번호 조회 실패	필드 비움	드롭박스 비활성화
시각표 조회 실패	"정보 없음" 표시	경고 로그
템플릿 파일 없음	전체 중단	에러 다이얼로그

4.2 로그 레벨 구분

INFO: 정상 동작 (크롤링 완료, 보고서 생성 등)
WARNING: 부분 실패 (열차 정보 미조회 등)
ERROR: 전체 실패 (로그인 실패, DB 오류 등)

4.3 사용자 친화적 메시지

모든 에러 메시지는 한국어로 작성하며, 기술적 용어를 최소화합니다.

예시:

❌ (Bad) TimetableServiceError: train_number not found in dataframe
✅ (Good) 열차 정보를 조회할 수 없습니다. 보고서는 생성되지만 열차번호 필드가 비어있습니다.

5. 보고서 생성 규칙

5.1 필수 정보 vs 선택 정보

구분	필드	실패 시 처리
필수	제목, 내용, 날짜, 부서	전체 중단
선택	열차번호, 편성, 호차	필드 비움
선택	입고 정보, 비고	"정보 없음" 표시

5.2 UI 동작 규칙

열차번호 조회 성공: 드롭박스에 후보 목록 표시
열차번호 조회 실패: 드롭박스 비활성화 + 수동 입력 허용
시각표 미로드: 관련 기능 전체 비활성화

5.3 파일명 규칙

[날짜]_[부서]_[제목(정제)].hwp
예: 2026-02-17_차량_1호선_서면역_소음발생.hwp

6. 데이터 모델

6.1 VOCPost (Pydantic)

class VOCPost(BaseModel):
    id: str                    # 게시글 ID
    title: str                 # 제목
    writer: str                # 작성자
    department: str            # 담당 부서
    date: str                  # 작성일 (YYYY-MM-DD HH:MM:SS)
    status: str                # 처리 상태
    channel: str               # 접수 경로
    is_public: int             # 공개 여부 (0/1)
    content: Optional[str]     # 상세 내용
    attachment: Optional[str]  # 첨부파일명
    is_related: int = 0        # 관심글 여부

6.2 데이터베이스 스키마

CREATE TABLE voc_posts (
    id TEXT PRIMARY KEY,
    title TEXT NOT NULL,
    writer TEXT,
    department TEXT,
    date TEXT,
    status TEXT,
    channel TEXT,
    is_public INTEGER DEFAULT 1,
    content TEXT,
    attachment TEXT,
    is_related INTEGER DEFAULT 0,
    checked_at TEXT,
    created_at TEXT DEFAULT CURRENT_TIMESTAMP
);

7. UI/UX 요구사항

7.1 메인 화면 (트레이 아이콘)

시스템 트레이에 상주
우클릭 메뉴: 수동 크롤링, 목록 보기, 설정, 종료

7.2 히스토리 다이얼로그

테이블 뷰: ID, 제목, 작성자, 부서, 날짜, 상태
필터: 부서별, 키워드, 날짜 범위
더블클릭: 상세 팝업
우클릭 메뉴: 보고서 생성, 인쇄, 첨부파일 보기

7.3 보고서 옵션 다이얼로그

사업소 선택 (신평/노포)
팀 선택 (검수1/검수2/...)
작성자 정보
열차번호 드롭박스 (자동 추출 시)

8. 제약 및 요구사항

8.1 기술 제약

Python: 3.8 이상
OS: Windows 10/11
필수 라이브러리:
- customtkinter: UI
- selenium: 크롤링
- pywin32: HWP 자동화
- pydantic: 데이터 검증
- pandas: 시각표 처리

8.2 성능 목표

크롤링 주기: 10분 (설정 가능)
알림 지연: 5분 이내
보고서 생성: 3초 이내
DB 조회: 1초 이내

8.3 보안 요구사항

로그인 정보: 로컬 JSON 파일 (평문 저장, 사내망 전제)
HWP 보안 모듈: 레지스트리 자동 등록

9. 시스템 아키텍처

9.1 계층 구조

┌─────────────────────────────────────┐
│          View (CustomTkinter)       │
│  HistoryDialog, SettingsDialog, ... │
└─────────────────────────────────────┘
                  ↕
┌─────────────────────────────────────┐
│         Controller (MVC)            │
│  AppController, SchedulerManager    │
└─────────────────────────────────────┘
                  ↕
┌─────────────────────────────────────┐
│      Services (Business Logic)      │
│  ReportService, ScraperService, ... │
└─────────────────────────────────────┘
                  ↕
┌─────────────────────────────────────┐
│      Utils & Models (Data)          │
│  VOCParser, TrainAnalyzer, DB, ...  │
└─────────────────────────────────────┘

9.2 주요 모듈 책임

모듈	책임
`AppController`	전체 흐름 제어, UI 이벤트 처리
`VOCScraper`	웹 크롤링, 로그인 관리
`ReportService`	HWP/PDF 생성, 인쇄
`TimetableService`	시각표 조회, 열차 검색
`VOCParser`	VOC 텍스트 파싱
`TrainAnalyzer`	열차 정보 분석, 입고지 추적
`DateScheduleUtils`	날짜 처리, 공휴일 판별

10. 향후 개선 사항 (Roadmap 참조)

다중 호선 지원 (2호선, 3호선)
통계 대시보드
엑셀 내보내기
자동 응답 템플릿

작성자: KH.Choi 최종 수정: 2026-02-17 버전: 2.0

11 KiB Raw Permalink Blame History