Initial commit: HotDeal Alarm Android App

Features: - Multi-site hot deal scraping (Ppomppu, Clien, Ruriweb, Coolenjoy) - Site filter with color-coded badges - Board display names (e.g., ppomppu8 -> 알리뽐뿌) - Anti-bot protection with request delays and User-Agent rotation - Keyword matching and notifications - Material Design 3 UI
2026-03-04 01:29:34 +09:00
commit 25a349f273
84 changed files with 6455 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,234 @@
+# 핫딜 알람 Android 앱
+
+## 프로젝트 개요
+
+Android 12 (API 31) ~ Android 16 최신 버전을 지원하는 프로덕션 수준의 핫딜 알람 앱입니다.
+
+### 지원 사이트
+- **뽐뿌** (ppomppu, ppomppu4, ppomppu8, money)
+- **클리앙** (allsell, jirum)
+- **루리웹** (1020, 600004)
+- **쿨엔조이** (jirum)
+- ~~퀘이사존~~ (제거됨 - Cloudflare 보호)
+
+- **뽐뿌** (ppomppu, ppomppu4, ppomppu8, money)
+- **클리앙** (allsell, jirum)
+- **루리웹** (1020, 600004)
+- **쿨엔조이** (jirum)
+- **퀘이사존** (qb_saleinfo)
+
+### 주요 기능
+- ✅ 사이트/게시판 선택적 모니터링
+- ✅ 키워드 기반 필터링 알림
+- ✅ 백그라운드 폴링 (WorkManager)
+- ✅ 로컬 알림 시스템
+- ✅ 핫딜 히스토리 관리
+- ✅ Android 12-16 완벽 지원
+
+---
+
+## 기술 스택
+
+### Core
+- **Kotlin 1.9.22**
+- **Coroutines + Flow** (비동기 처리)
+- **Hilt** (의존성 주입)
+- **Jetpack Compose** (UI)
+
+### Data
+- **Room 2.6.1** (로컬 데이터베이스)
+- **DataStore** (설정 저장)
+- **OkHttp 4.12.0** (HTTP 클라이언트)
+- **Jsoup 1.17.2** (HTML 파싱)
+
+### Background
+- **WorkManager 2.9.0** (주기적 폴링)
+
+### Architecture
+- **MVVM + Clean Architecture (3-layer)**
+- **Repository Pattern**
+- **Single Activity Architecture**
+
+---
+
+## 프로젝트 구조
+
+```
+com.hotdeal.alarm/
+├── di/                          # Hilt DI 모듈
+│   ├── DatabaseModule.kt
+│   └── NetworkModule.kt
+│
+├── data/
+│   ├── local/db/               # Room 데이터베이스
+│   │   ├── entity/             # Entity 클래스
+│   │   ├── dao/                # DAO 인터페이스
+│   │   ├── AppDatabase.kt
+│   │   └── Converters.kt
+│   └── remote/
+│       ├── scraper/            # 사이트별 스크래퍼
+│       └── interceptor/        # OkHttp 인터셉터
+│
+├── domain/
+│   └── model/                  # 도메인 모델
+│       ├── HotDeal.kt
+│       ├── SiteConfig.kt
+│       ├── Keyword.kt
+│       └── SiteType.kt
+│
+├── presentation/
+│   ├── main/                   # 메인 화면
+│   ├── settings/               # 설정 화면
+│   ├── deallist/               # 핫딜 목록 화면
+│   └── components/             # 재사용 컴포넌트
+│
+├── worker/                     # WorkManager Worker
+│   ├── HotDealPollingWorker.kt
+│   └── WorkerScheduler.kt
+│
+├── service/                    # 서비스
+│   └── NotificationService.kt
+│
+└── util/                       # 유틸리티
+    ├── Constants.kt
+    └── BootReceiver.kt
+```
+
+---
+
+## 빌드 방법
+
+### 요구사항
+- Android Studio Hedgehog 이상
+- JDK 17
+- Android SDK 35
+
+### 빌드 명령어
+```bash
+cd android_app
+./gradlew assembleDebug
+```
+
+### APK 설치 (WSL 환경)
+WSL에서 Windows ADB를 사용하여 설치:
+```bash
+# Windows ADB 경로 (WSL에서)
+/mnt/c/Users/$USER/AppData/Local/Android/Sdk/platform-tools/adb.exe install app/build/outputs/apk/debug/app-debug.apk
+```
+
+또는 PowerShell/CMD에서:
+```powershell
+adb install "\\wsl.localhost\Ubuntu\home\work\hotdeal_alarm\app\build\outputs\apk\debug\app-debug.apk"
+```
+
+```bash
+cd android_app
+./gradlew assembleDebug
+```
+
+### 릴리즈 빌드
+```bash
+./gradlew assembleRelease
+```
+
+---
+
+## 권한
+
+### 필수 권한
+| 권한 | 용도 | Android 버전 |
+|------|------|--------------|
+| INTERNET | 웹 스크래핑 | 모든 버전 |
+| FOREGROUND_SERVICE | 백그라운드 폴링 | 모든 버전 |
+| POST_NOTIFICATIONS | 알림 표시 | Android 13+ |
+| SCHEDULE_EXACT_ALARM | 정확한 알람 | Android 12+ |
+| RECEIVE_BOOT_COMPLETED | 부팅 시 자동 시작 | 모든 버전 |
+
+---
+
+## 백그라운드 폴링 전략
+
+### WorkManager 기반
+| 간격 | 전략 | 설명 |
+|------|------|------|
+| 1-2분 | Foreground Service | 빈번한 폴링 (알림 표시) |
+| 3-5분 | PeriodicWorkManager | 표준 폴링 |
+| 15분+ | PeriodicWorkManager | 배터리 최적화 모드 |
+
+### Constraints
+- 네트워크 연결 필요
+- 배터리 부족 시 실행 안 함
+- Doze 모드 대응
+
+---
+
+## 알림 시스템
+
+### Notification Channels
+| Channel | 중요도 | 용도 |
+|---------|--------|------|
+| hotdeal_urgent | HIGH | 키워드 매칭 핫딜 |
+| hotdeal_normal | DEFAULT | 새로운 핫딜 |
+| hotdeal_background | LOW | 폴링 상태 |
+
+---
+
+## 스크래핑 구현
+
+### Anti-Bot 대응
+1. **User-Agent 회전**: Android Chrome, Desktop Chrome 등 번갈아 사용
+2. **Rate Limiting**: 요청 간 최소 3초 대기
+3. **Retry with Backoff**: 실패 시 지수 백오프로 재시도
+4. **Header 조작**: Referer, Accept-Language 등 추가
+
+### Cloudflare 대응
+- ~~퀘이사존~~ 제거됨
+
+- 퀘이사존은 Cloudflare 보호가 적용될 수 있음
+- 일반 HTTP 요청으로 차단될 경우 WebView 기반 bypass 고려
+
+---
+
+## 테스트
+
+### Unit Tests
+```bash
+./gradlew test
+```
+
+### Instrumentation Tests
+```bash
+./gradlew connectedAndroidTest
+```
+
+---
+
+## 향후 계획
+
+### Phase 2
+- [x] FCM 기반 서버 푸시 (로컬 알림으로 대체)
+- [x] 위젯 지원
+- [x] 다크 모드 개선
+- [x] 공유 기능
+
+### Phase 3
+- [x] 디자인 시스템 구축
+- [x] 로딩 스켈레톤 (Shimmer Effect)
+- [x] 빈 상태 컴포넌트
+- [x] 애니메이션 컴포넌트
+
+### Phase 4
+- [ ] 가격 비교 기능
+- [ ] 즐겨찾기 기능
+- [ ] 알림 그룹화
+---
+
+## 라이선스
+
+MIT License
+
+---
+
+## 기여
+
+버그 리포트나 기능 제안은 GitHub Issues를 이용해주세요.