648 lines
22 KiB
Markdown
648 lines
22 KiB
Markdown
# 📋 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 알림 사이클 (v2.1 개선)
|
|
|
|
#### 3.2.1 신규 알림 사이클 (기본 3분, 설정 가능)
|
|
```
|
|
1. 마지막 체크 이후 신규 데이터 조회 (get_new_posts_since)
|
|
- 설정 `noti.use_related_filter = true`: 관심글(is_related=1)만 조회
|
|
- 설정 `noti.use_related_filter = false`: 신규글 전체 조회
|
|
2. 중복 알림 필터링 (notified_post_ids 체크)
|
|
3. 모든 관심글(is_related=1)에 대해 알림 ⭐ 변경: 키워드 필터링 제거
|
|
4. 소리 재생 (설정 시)
|
|
5. 토스트 알림 및 팝업 표시
|
|
6. last_check_time 영속화 저장 ⭐ 신규
|
|
```
|
|
|
|
#### 3.2.2 미확인 알림 사이클 (기본 10분, 설정 가능) ⭐ 신규
|
|
```
|
|
1. 확인하지 않은 관심글 조회 (get_unchecked_related_posts)
|
|
- 설정 `noti.use_related_filter = true`: 관심글(is_related=1)의 미확인만 조회
|
|
- 설정 `noti.use_related_filter = false`: 전체 미확인글 조회
|
|
2. 30분 경과 조건 ON/OFF에 따라 필터링
|
|
- ON: 30분 이상 지난 글만 알림
|
|
- OFF: 미확인 글 전체 알림
|
|
3. 미확인 알림 발송 (⚠️ 표시)
|
|
4. 사용자가 확인할 때까지 반복 알림
|
|
```
|
|
|
|
#### 3.2.3 알림 개선 사항
|
|
- **키워드 필터링 제거**: 모든 관심글에 대해 알림 발송
|
|
- **중복 방지**: notified_post_ids 세트로 동일 글 중복 알림 방지
|
|
- **영속화**: last_check_time을 scheduler_state.json에 저장하여 프로그램 재시작 시에도 유지
|
|
- **미확인 체크**: 사용자가 확인하지 않은 글에 대해 주기적 재알림
|
|
- **주기 설정화**: 신규 알림 주기 및 미확인 알림 주기를 설정 UI에서 변경 가능
|
|
- **미확인 조건 토글**: "30분 경과 후 알림" 옵션 ON/OFF 지원
|
|
- **관심조건 토글**: "관심 조건(키워드/부서)만 알림" 옵션 ON/OFF 지원
|
|
|
|
### 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 계층 구조 (v3.0 - Manager 패턴 적용)
|
|
```
|
|
┌─────────────────────────────────────────────────────┐
|
|
│ View (CustomTkinter) │
|
|
│ HistoryDialog, SettingsDialog, Notification │
|
|
└─────────────────────────────────────────────────────┘
|
|
↕
|
|
┌─────────────────────────────────────────────────────┐
|
|
│ Controller (MVC) - 위임 패턴 │
|
|
│ │
|
|
│ AppController (487줄) │
|
|
│ ├── SchedulerManager : 크롤링, DB 체크, 스케줄링│
|
|
│ ├── NotificationManager : 토스트/팝업 알림 │
|
|
│ ├── ReportManager : 보고서 생성/인쇄/PDF │
|
|
│ ├── FileManager : 첨부파일 다운로드/열기 │
|
|
│ └── UIManager : UI 창 관리 │
|
|
└─────────────────────────────────────────────────────┘
|
|
↕
|
|
┌─────────────────────────────────────────────────────┐
|
|
│ Services (Business Logic) │
|
|
│ ReportService, ScraperService, TimetableService │
|
|
└─────────────────────────────────────────────────────┘
|
|
↕
|
|
┌─────────────────────────────────────────────────────┐
|
|
│ Utils & Models (Data) │
|
|
│ VOCParser, TrainAnalyzer, VOCDatabase, ... │
|
|
└─────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### 9.2 주요 모듈 책임
|
|
|
|
| 모듈 | 책임 | 라인 수 |
|
|
|------|------|---------|
|
|
| `AppController` | 전체 흐름 제어, Manager 위임 | 487줄 |
|
|
| `SchedulerManager` | 크롤링 사이클, DB 체크, 스케줄링 | 399줄 |
|
|
| `NotificationManager` | Windows 토스트 알림, 팝업 다이얼로그 | 192줄 |
|
|
| `ReportManager` | 보고서 생성 요청, 인쇄, PDF 생성 위임 | 283줄 |
|
|
| `FileManager` | 첨부파일 다운로드 및 열기 | 151줄 |
|
|
| `UIManager` | UI 창 생성 및 포커스 관리 | 198줄 |
|
|
| `VOCScraper` | 웹 크롤링, 로그인 관리 | - |
|
|
| `ReportService` | HWP/PDF 생성, 인쇄 | 691줄 |
|
|
| `TimetableService` | 시각표 조회, 열차 검색 | - |
|
|
| `VOCParser` | VOC 텍스트 파싱 | - |
|
|
| `TrainAnalyzer` | 열차 정보 분석, 입고지 추적 | 355줄 |
|
|
| `DateScheduleUtils` | 날짜 처리, 공휴일 판별 | - |
|
|
|
|
---
|
|
|
|
## 10. 자동 업데이트 시스템 (Auto Update System) ⭐ 신규
|
|
|
|
### 10.1 개요
|
|
|
|
**목표**: 프로그램의 자동 업데이트 기능 구현
|
|
- Supabase 기반 원격 버전 관리
|
|
- 1시간마다 자동 업데이트 체크
|
|
- 사용자友好的 업데이트 알림 및 설치
|
|
- **멀티프로젝트 지원**: 다른 프로젝트에서도 재사용 가능한 모듈 설계
|
|
|
|
---
|
|
|
|
### 10.2 데이터베이스 테이블 정의 (Supabase)
|
|
|
|
**테이블명**: `program_version`
|
|
|
|
| 필드명 | 타입 | 설명 | 필수 |
|
|
|--------|------|------|------|
|
|
| `id` | SERIAL | Primary Key | ✅ |
|
|
| `program_id` | TEXT | 프로그램 식별자 (예: "voc_monitor") | ✅ |
|
|
| `version` | TEXT | 버전 번호 (예: "3.1.0") | ✅ |
|
|
| `is_stable` | BOOLEAN | 안정版 여부 | ✅ |
|
|
| `release_note` | TEXT | 배포 노트 | ❌ |
|
|
| `download_url` | TEXT | 다운로드 URL | ✅ |
|
|
| `min_required_version` | TEXT | 최소 요구 버전 (업그레이드 시) | ❌ |
|
|
| `created_at` | TIMESTAMP | 생성일시 | ✅ |
|
|
| `updated_at` | TIMESTAMP | 수정일시 | ✅ |
|
|
|
|
**예시 데이터**:
|
|
```json
|
|
{
|
|
"program_id": "voc_monitor",
|
|
"version": "3.1.0",
|
|
"is_stable": true,
|
|
"release_note": "- 크롤링 필터링 개선\n- Z-order 문제 해결\n- 자동 업데이트 기능 추가",
|
|
"download_url": "https://example.com/releases/voc_monitor_3.1.0.exe",
|
|
"min_required_version": "2.0.0",
|
|
"created_at": "2026-02-18T10:00:00Z"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### 10.3 로컬 버전 관리 파일
|
|
|
|
**1. `__version__.py`**
|
|
```python
|
|
"""
|
|
버전 정보
|
|
|
|
이 파일은 프로그램의 현재 버전을 정의합니다.
|
|
업데이트 시 이 파일의 VERSION과 비교하여进行检查합니다.
|
|
"""
|
|
VERSION = "3.0.0"
|
|
PROGRAM_ID = "voc_monitor"
|
|
APP_NAME = "VOC 모니터링"
|
|
```
|
|
|
|
**2. `updatelog.md`** (위치: `app/updater/updatelog.md`)
|
|
```markdown
|
|
# 업데이트 로그
|
|
|
|
## v3.1.0 (2026-02-18)
|
|
- 크롤링 필터링 개선 (AND/OR 모드 지원)
|
|
- Z-order 문제 해결
|
|
- 자동 업데이트 기능 추가
|
|
|
|
## v3.0.0 (2026-02-17)
|
|
- Controller 리팩토링
|
|
- Manager 패턴 적용
|
|
```
|
|
|
|
> **중요**: `updatelog.md`는 `app/updater/` 모듈 내에 위치하며, 개발 과정에서 발생한 변경사항을 기록하는 용도입니다. 모든 버전 업데이트 시 이 파일을 최신화해야 합니다.
|
|
|
|
---
|
|
|
|
### 10.4 모듈 설계 (utils/auto_updater.py)
|
|
|
|
```python
|
|
class AutoUpdater:
|
|
"""
|
|
자동 업데이트 관리자
|
|
|
|
Supabase에서 버전 정보를 조회하고 업데이트를 처리합니다.
|
|
|
|
Attributes:
|
|
program_id: 프로그램 식별자
|
|
current_version: 현재 버전
|
|
supabase_url: Supabase 프로젝트 URL
|
|
supabase_key: Supabase API 키
|
|
check_interval: 업데이트 체크 간격 (기본: 1시간)
|
|
|
|
주요 메서드:
|
|
check_for_updates: 업데이트 확인
|
|
download_update: 업데이트 파일 다운로드
|
|
install_update: 업데이트 설치
|
|
start_background_check: 백그라운드 업데이트 체크 시작
|
|
"""
|
|
```
|
|
|
|
---
|
|
|
|
### 10.5 업데이트 체크 주기
|
|
|
|
```
|
|
1시간마다 (기본값, 설정 가능)
|
|
├── Supabase에서 최신 버전 조회
|
|
├── 현재 버전과 비교
|
|
├── 업데이트 필요 시:
|
|
│ ├── 알림 다이얼로그 표시
|
|
│ ├── 사용자가 "지금 설치" 선택
|
|
│ │ ├── temp 폴더에 다운로드
|
|
│ │ ├── 현재 프로세스 종료
|
|
│ │ ├── 새 프로세스 실행 (업데이터)
|
|
│ │ └── 업데이터가 기존 파일 교체
|
|
│ └── "나중에" 선택 → 다음 주기까지 대기
|
|
└── 업데이트 없음 → 로그만 기록
|
|
```
|
|
|
|
**통합 동작 (v3.2.2 반영):**
|
|
- 앱 시작 시 `UpdateManager` 초기화 후 백그라운드 체크 시작
|
|
- 트레이 메뉴에 `업데이트 확인` 수동 항목 제공
|
|
- 업데이트 발견 시 사용자 확인 다이얼로그 표시
|
|
- 사용자 승인 시 `prepare_update()` -> `launch_updater()` -> 메인 앱 종료
|
|
|
|
**로그 명세 (필수 기록):**
|
|
- 초기화 성공/실패
|
|
- 백그라운드 체크 시작/오류
|
|
- 수동 확인 수행/결과(최신/업데이트 필요)
|
|
- 준비 실패/실행 실패 원인
|
|
|
|
---
|
|
|
|
### 10.6 아키텍처: updater.exe 분리 ⭐ 중요
|
|
|
|
**구조**:
|
|
```
|
|
메인 프로젝트 (cx_freeze 패킹)
|
|
├── updater.exe (별도 패킹, 최소 GUI 포함)
|
|
├── app/
|
|
│ └── updater/
|
|
│ ├── __init__.py
|
|
│ ├── __version__.py # 버전 정보
|
|
│ ├── update_manager.py # 메인 프로그램용 업데이트 관리자
|
|
│ ├── updater_gui.py # updater.exe용 GUI
|
|
│ └── updatelog.md # 업데이트 로그
|
|
└── ...
|
|
```
|
|
|
|
**실행 흐름**:
|
|
```
|
|
1. update_manager.py (메인 프로그램 내):
|
|
├── Supabase에서 새 버전 확인
|
|
├── 업데이트 config.json 생성 (%TEMP%/voc_updater_config.json)
|
|
│ {
|
|
│ "download_url": "https://supabase.../voc_noti_3.2.0.zip",
|
|
│ "target_path": "C:/Program Files/voc_noti",
|
|
│ "version": "3.2.0",
|
|
│ "restart_exe": "voc_noti.exe"
|
|
│ }
|
|
├── updater.exe를 %TEMP%로 복사
|
|
└── updater.exe 실행 후 메인 프로그램 종료
|
|
|
|
2. updater.exe (별도 프로세스):
|
|
├── config.json 읽기
|
|
├── zip 다운로드 (진행률 표시 - CustomTkinter GUI)
|
|
├── 압축 해제 → 파일 교체
|
|
└── 메인 프로그램 재실행
|
|
```
|
|
|
|
**updater.exe UI**:
|
|
- CustomTkinter 기반 최소 GUI 창
|
|
- 다운로드 진행률 표시 (Progress Bar)
|
|
- 상태 메시지 표시 (다운로드 중, 압축 해제 중, 완료)
|
|
- 성공/실패 결과 표시
|
|
|
|
**파일 교체 방식**:
|
|
- **전체 교체**: zip 다운로드 후 압축 해제
|
|
- 백업 폴더 생성 (이전 버전 보존)
|
|
- 실패 시 롤백 가능
|
|
|
|
**통신 방식**:
|
|
- 임시 JSON 파일 (`%TEMP%/voc_updater_config.json`)
|
|
- 메인 프로그램이 파일 생성 → updater.exe가 읽기
|
|
|
|
---
|
|
|
|
### 10.7 예외 케이스 처리
|
|
|
|
| 상황 | 처리 방법 |
|
|
|------|-----------|
|
|
| 네트워크 오류 | 업데이트 체크 건너뛰기, 로그 기록 |
|
|
| Supabase 연결 실패 | 재시도 (3회), 실패 시 다음 주기까지 대기 |
|
|
| 다운로드 실패 | 에러 메시지 표시, 재시도 옵션 제공 |
|
|
| 설치 중 오류 | 롤백 (백업 파일 활용), 에러 로그 기록 |
|
|
| 자기 자신 업데이트 | temp 폴더에 복사 후 별도 프로세스로 실행 |
|
|
| 버전 불일치 | min_required_version 기준 판단 |
|
|
|
|
**추가 안정화 반영 (통합 전 단독 검증 단계)**:
|
|
- Supabase URL/KEY 누락 시 사전 설정 오류 반환
|
|
- `voc_updater_config.json` 원자적 저장(`.tmp` -> 교체)
|
|
- updater.exe 누락 시 준비 단계에서 즉시 실패 반환
|
|
- 압축 해제 시 임시 폴더 사용 후 대상 경로에 단계적 복사
|
|
- 설치 실패 시 백업 롤백 + 임시 폴더 정리
|
|
|
|
---
|
|
|
|
### 10.8 멀티프로젝트 지원
|
|
|
|
**설계 원칙**:
|
|
- `program_id` 기반으로 동적 설정
|
|
- Supabase 테이블 구조的统一
|
|
- 설정 파일로 URL/Key 관리
|
|
|
|
**사용 예시**:
|
|
```python
|
|
# VOC 모니터링
|
|
updater = AutoUpdater(
|
|
program_id="voc_monitor",
|
|
current_version=VERSION,
|
|
settings=settings
|
|
)
|
|
|
|
# 다른 프로젝트
|
|
updater = AutoUpdater(
|
|
program_id="other_app",
|
|
current_version="1.0.0",
|
|
settings=settings
|
|
)
|
|
```
|
|
|
|
---
|
|
|
|
### 10.9 의존성
|
|
|
|
```json
|
|
{
|
|
"supabase": "^2.0.0",
|
|
"requests": "^2.31.0"
|
|
}
|
|
```
|
|
|
|
### 10.10 연결 설정 관리 (하드코딩 금지)
|
|
|
|
- Supabase 연결 정보는 `app/updater/config.json`에서 관리
|
|
- `config_url`: 원격 설정 URL
|
|
- `fallback.supabase_url`, `fallback.anon_key`: 원격 실패 시 대체값
|
|
- 런타임 동작 설정은 `settings.json`의 `update` 섹션에서 관리
|
|
- `connection_config_path`, `environment`, `check_interval_hours`, `program_id`, `version_table`
|
|
- 버전 체크 시 테이블 자동 폴백 지원
|
|
- `program_version` 조회 실패(404) 시 `program_versions` 재시도
|
|
|
|
### 10.11 테스트 모드 검증 옵션
|
|
|
|
- `python app/main.py --test --test-update-now`
|
|
- 테스트 DB 모드로 앱을 실행하면서 updater 연결 확인을 시작 직후 1회 수행
|
|
- 네트워크/설정 오류 시 사용자 메시지 + 로그 기록
|
|
|
|
### 10.12 업데이터 빌드/통합 절차
|
|
|
|
1. 업데이터 단독 빌드
|
|
- `python app/update_build_setup.py`
|
|
- 결과: `app/updater_build/dist/updater.exe`
|
|
2. 메인 패키징
|
|
- `python app/setup.py build`
|
|
- 포함 항목:
|
|
- `updater.exe` (메인 exe와 동일 경로)
|
|
- `app/updater/config.json` (연결 설정)
|
|
3. 런타임
|
|
- `UpdateManager.prepare_update()`가 설치 경로의 `updater.exe`를 `%TEMP%`로 복사 후 실행
|
|
|
|
---
|
|
|
|
## 11. 향후 개선 사항 (Roadmap 참조)
|
|
|
|
- [ ] 다중 호선 지원 (2호선, 3호선)
|
|
- [ ] 통계 대시보드
|
|
- [ ] 엑셀 내보내기
|
|
- [ ] 자동 응답 템플릿
|
|
|
|
---
|
|
|
|
작성자: KH.Choi
|
|
최종 수정: 2026-02-18
|
|
버전: 3.3
|