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

## 1. 프로젝트 비전

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

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

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

---

## 2. 시스템 범위 (Scope)

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

### 제외 기능 (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 데이터 집계 로직

**기간별 통계**:
```python
SELECT 
    DATE(date) as day,
    COUNT(*) as count
FROM voc_posts
WHERE date BETWEEN ? AND ?
GROUP BY DATE(date)
ORDER BY day
```

**부서별 분포**:
```python
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
```

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

#### 3.4.2 예외 케이스 처리

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

#### 3.4.3 성능 최적화

**인덱스 추가**:
```sql
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)
```python
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 데이터베이스 스키마
```sql
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