- core/core-utils 모듈 신규 생성 (namespace: bums.lunatic.launcher.core.utils): * AlphabetToChosungMap, APILevel, BitmapConverter, CategoryManualMapper, CommonUtils, CompressStringUtil, EnToKo, FileUtils, HashUtils, ImageUtils, JsoupUtils, KoreanTrans, MediaBitmapUtil, PlayCategory, PreferencesUtil, RssList, StringEscapeUtils 총 17종 이관 * (@GlideModule 어노테이션 프로세서 제약이 있는 CustomOkHttpGlideModule.kt만 :app에 유지) - settings.gradle.kts, app/build.gradle.kts, ARCHITECTURE.md 갱신 - 검증: ./gradlew :app:compileDebugKotlin 빌드 성공 확인 (11s, 133 actionable tasks)
108 lines
10 KiB
Markdown
108 lines
10 KiB
Markdown
# LunarLauncher 아키텍처 개요
|
|
|
|
`LunarLauncher`는 Android 홈 런처를 중심으로 RSS/커뮤니티 피드, 웹 리더(GeckoView/WebView), 토렌트 및 미디어 다운로드, 네이티브 FFmpeg 기반 미디어/문서/이미지 뷰어, 라이브 월페이퍼, Google Drive 백업, Wear OS 제스처 연동을 통합한 멀티 모듈 Android 프로젝트입니다.
|
|
|
|
---
|
|
|
|
## 1. Gradle 모듈 구성
|
|
|
|
`settings.gradle.kts` 기준 모듈 구성은 다음과 같습니다.
|
|
|
|
| 모듈 | 역할 | 비고 |
|
|
| :--- | :--- | :--- |
|
|
| `:app` | 메인 Android 애플리케이션 (`bums.lunatic.launcher`) | `compileSdk 35`, `minSdk 26`, `arm64-v8a` 네이티브(C++/CMake) 포함 |
|
|
| `:core:core-common` | 공통 로거(`Blog`), 유틸(`JamoUtils`, `DataUtils`), ML Kit 헬퍼(`MlKitTranslationHelper`) | `:app`, `:core:core-database`, `:feature:*`에서 참조 |
|
|
| `:core:core-database` | Realm Kotlin 모델(`model/*`, `TokizModels`, `RecentCall`), `WorkersDb`, `CustMigration` | `io.realm.kotlin` api 노출 |
|
|
| `:core:core-network` | 공용 `OkHttpClient` 싱글톤(`NetworkClient`) | OkHttp3 커넥션 풀 공유 |
|
|
| `:core:core-utils` | 파일/이미지/인코딩/Jsoup/한글변환/설정/카테고리 유틸리티 17종 | `:core:core-common`, `:core:core-network` 의존 |
|
|
| `:feature:feature-player` | `NativePlayer`, `PageIndexer`, `ImageViewerActivity` 미디어/이미지 뷰어 코어 | `PhotoView`, `ExifInterface`, `Glide` |
|
|
| `:feature:feature-reader` | `WebReaderActivity`, `PagedTextLayout`, `TouchArea` 리더 코어 | `:core:core-common` 의존 |
|
|
| `:feature:feature-torrent` | `TorrentService`/`TorrentTask` 및 `jlibtorrent` JAR 격리 모듈 | `:core:core-common` 의존 |
|
|
| `:feature:feature-wallpaper` | `MyWallpaperService`/`NativeRenderer` 라이브 월페이퍼 모듈 | `:core:core-common`, `:core:core-database` 의존 |
|
|
| `:gdrive` | Google Drive `appDataFolder` 기반 로그인 및 백업 모듈 | `:app`에서 `implementation(project(":gdrive"))`로 참조 |
|
|
| `:lun_launcher` | Wear OS 컴패니언 앱 (`bums.lunatic.launcher`, `minSdk 30`, `compileSdk 36`) | Compose for Wear OS, Tile, Complication, 제스처 전송(`MessageClient`) |
|
|
|
|
---
|
|
|
|
## 2. `:app` 패키지 구조 (`bums.lunatic.launcher`)
|
|
|
|
```text
|
|
app/src/main/
|
|
├── cpp/ # C++ 네이티브 엔진 (FFmpeg, AAudio, Sonic, Live Wallpaper 렌더러)
|
|
└── kotlin/bums/lunatic/launcher/
|
|
├── LunaticLauncher.kt # Application 클래스 (GeckoRuntime, Picasso, 로그 초기화)
|
|
├── LauncherActivity.kt # 메인 홈 런처 Activity (HOME/LAUNCHER)
|
|
├── apps/ # 앱 서랍, 앱/연락처 어댑터, 아이콘 팩, 검색 메뉴
|
|
├── behavior/ # 화면 전환/동작 인터랙션 전략 패턴
|
|
├── common/ # 공통 Activity 기반 클래스, 리모트 제스처 Fragment, 타입 별칭
|
|
├── feeds/ # 시스템 상태, 앱 위젯 호스트(WidgetHost), RSS 파서/어댑터
|
|
├── helpers/ # ForegroundService, WorkManager 워치독, 설정(PrefHelper), 잠금/수신기
|
|
├── home/ # 홈 피드(RssHome), NeoRssActivity, 파일/웹/번역 화면 및 각종 BottomSheet
|
|
│ ├── adapters/ # 북마크, 알림, 통화/SMS, RSS, 토렌트, 날씨 RecyclerView 어댑터
|
|
│ ├── tokiz/ # 텍스트/웹툰/소설 리더(TokiFragment, HistoryManager, PagedTextLayout)
|
|
│ └── weather/ # 날씨 API 클라이언트 및 파서
|
|
├── model/ # Realm Kotlin 데이터 모델 (AppInfo, RssData, WeatherForcast 등)
|
|
├── player/ # 네이티브 미디어 플레이어, 문서/이미지 뷰어 Activity
|
|
├── qaccess/ # 퀵 액세스 패널
|
|
├── receiver/ # NotificationListenerService(NLService), 전화/SMS/패키지/연락처 리시버
|
|
├── settings/ # 런처 및 하위 카테고리별 설정 Activity/Fragment
|
|
├── utils/ # 한글 초성/자모 변환, 파일/이미지/인코딩/Jsoup 유틸리티
|
|
├── view/ # 커스텀 UI 뷰 (FloatingActionMenu, LunaticBrowserLayout, ZoomImageView 등)
|
|
├── wall/ # 라이브 월페이퍼 서비스(MyWallpaperService) 및 JNI 브리지(NativeRenderer)
|
|
└── workers/ # Realm DB(WorkersDb), 백그라운드 수집기(*Getter), 토렌트/위치/워치 서비스
|
|
```
|
|
|
|
---
|
|
|
|
## 3. 핵심 컴포넌트 역할 요약
|
|
|
|
### 3.1. Activity
|
|
- **`LauncherActivity`**: `MAIN` / `HOME` / `LAUNCHER` 인텐트를 처리하는 메인 홈 런처. 앱 위젯 호스트, 앱 서랍(`AppDrawerBottomSheet`), 키보드/게임패드/리모트 입력 및 `SEND`/`SEND_MULTIPLE` 공유 수신을 담당합니다.
|
|
- **`NeoRssActivity`**: RSS/커뮤니티 피드(`RssHome`), 웹/콘텐츠 리더(`TokiFragment`) 등을 호스팅하며 `WEB_SEARCH` 및 `SEND` 인텐트를 처리합니다.
|
|
- **`WebReaderActivity`**: 별도 런처 아이콘(`리더`)으로 실행되는 WebView 기반 웹 리더. 파일 업로드/백업 복원(`ActivityResultContracts`) 및 JS 브리지를 제공합니다.
|
|
- **`CompletedFilesActivity`**: 별도 런처 아이콘(`파일즈`)으로 실행되는 다운로드/완료 파일 탐색기. 파일 목록 조회, 미리보기, 문서/이미지 뷰어 연동을 수행합니다.
|
|
- **`TranslatorActivity`**: ML Kit 언어 식별(`LanguageIdentification`) 및 번역(`Translation`), Android `TextToSpeech`를 연동한 번역기 화면입니다.
|
|
- **`PlayerActivity`**: `TextureView`와 `NativePlayer`를 사용해 동영상을 재생하는 플레이어. 외부/내장 자막 동기화 및 ML Kit 기반 자막 실시간 번역, 재생 오류 시 엔진 복구(`rebootEngine`)를 지원합니다.
|
|
- **`DocumentViewerActivity`**: `PageIndexer`와 `PagedTextLayout`을 이용해 대용량 텍스트 문서를 인코딩 감지 후 페이지 단위로 렌더링하는 뷰어입니다.
|
|
- **`ImageViewerActivity`**: `PhotoView`와 `ExifInterface`를 이용해 이미지 확대/축소 및 EXIF 메타데이터 오버레이를 제공합니다.
|
|
- **`SettingsActivity` / `home.tokiz.Settings`**: 런처 전반 설정(`APPLICATION_PREFERENCES`) 및 리더 전용 설정 화면입니다.
|
|
|
|
### 3.2. 주요 Fragment & BottomSheet
|
|
- **`RssHome` / `RssViewer` / `BookmarkPagerFragment`**: 홈 피드, RSS 기사 뷰어, 북마크 페이저 UI.
|
|
- **`CompletedFilesFragment` / `TorrentListFragment` / `SystemStatusFragment` / `LearningFragment`**: 완료 파일 목록, 토렌트 진행 목록, 시스템 상태, 학습/단어장 화면.
|
|
- **`TokiFragment` / `RemoteGestureFragment`**: 텍스트/웹 콘텐츠 리더 및 워치/리모트 제스처 연동 Fragment.
|
|
- **`AppDrawer` / `AppDrawerBottomSheet` / `SearchBottomSheet` / `WebBottomSheet` / `VideoPreviewBottomSheet`**: 앱 서랍, 통합 검색, 인앱 웹 바텀시트, 영상 미리보기 시트.
|
|
|
|
### 3.3. Service & BroadcastReceiver
|
|
- **`ForeGroundService`**: `youtubedl-android`(yt-dlp) 및 OkHttp를 활용한 영상/파일 다운로드, 블루투스/미디어 버튼 처리, WorkManager 작업 스케줄링을 담당하는 포그라운드 서비스.
|
|
- **`TorrentService`** (`workers/TorrentManager.kt`): `jlibtorrent` 기반 토렌트 다운로드 포그라운드 서비스. Wi-Fi 및 충전 상태에 따라 세션을 제어하고, 미리보기용 핵심 피스 우선 다운로드(`previewPiecesMap`)를 지원합니다.
|
|
- **`MyWallpaperService`**: `WallpaperService` 구현체로, C++ `NativeRenderer`를 통해 라이브 월페이퍼 표면을 렌더링하고 날씨 비트맵/미디어 전환을 처리합니다.
|
|
- **`NLService`**: `NotificationListenerService`로 외부 앱 알림을 수집·가공하여 Realm DB 및 로그에 기록합니다.
|
|
- **`WatchGestureService`**: `WearableListenerService`로 Wear OS 앱(`:lun_launcher`)에서 보낸 `/gesture/next`, `/gesture/prev` 등의 메시지를 수신합니다.
|
|
- **`LocationUpdateService`**: 위치 변경을 수신하고 `Geocoder`로 주소를 변환해 Realm `LocationLog`에 저장합니다.
|
|
- **기타 리시버**: `CallReceiver`(통화 상태), `SmsReceiver`(SMS/WAP Push), `PackageEventReceiver`(앱 설치/삭제), `ContactReceiver`, `AdminReceiver`, `BatteryReceiver`, `HeadsetActionButtonReceiver`.
|
|
|
|
### 3.4. 미디어·렌더링 네이티브 모듈 (`app/src/main/cpp/`)
|
|
`CMakeLists.txt`에서 `native_renderer` 공유 라이브러리로 빌드되며 `libavformat`, `libavcodec`, `libavutil`, `libswscale`, `libswresample`, `aaudio`, `jnigraphics`를 링크합니다.
|
|
- **미디어 플레이어 엔진 (`PlayerEngine.cpp/.h`, `native_player.cpp`, `sonic.c`, `PacketQueue.h`)**:
|
|
- Kotlin `NativePlayer`와 JNI로 연결됩니다.
|
|
- FFmpeg 기반 비디오/오디오 디코딩, `AAudio` 네이티브 오디오 출력, `sonic` 기반 배속 재생, 내장/외부 자막 트랙 추출 및 탐색(`seekTo`/`seekBy`)을 처리합니다.
|
|
- **라이브 월페이퍼 렌더러 (`Renderer.cpp/.h`, `native_renderer.cpp`, `Preloader.cpp/.h`, `MediaAsset.cpp/.h`, `AnimationStrategy`, `TransitionStrategy`)**:
|
|
- Kotlin `NativeRenderer`와 JNI로 연결됩니다.
|
|
- 미디어 에셋 프리로딩, 전환/애니메이션 전략 적용, `Surface` 직접 렌더링을 수행합니다.
|
|
|
|
### 3.5. 데이터 계층 및 백그라운드 수집기 (`workers/`, `model/`)
|
|
- **`WorkersDb`**: Realm Kotlin(`io.realm.kotlin`) 싱글톤/스키마 관리 및 `CustMigration`을 담당합니다.
|
|
- **`TaskAggregator` & `*Getter.kt`**: 앱 목록(`AppInfoGetter`), 연락처(`ContactInfoGetter`), 통화/SMS(`RecentCallGetter`, `RecentSmsGetter`), 캘린더(`CalendarGetter`), 위치(`LocationGetter`), 날씨(`OpenWeatherGetter`), 커뮤니티/RSS/유튜브/텔레그램(`DCGetter`, `FmKoreaGetter`, `ClienGetter`, `ArcaGetter`, `RuliWebGetter`, `RedditGetter`, `TheQooGetter`, `DotaxGetter`, `NewsFeedsGetter`, `YoutubeGetter`, `TelegramBotGetter`) 데이터를 비동기로 수집해 Realm에 병합합니다.
|
|
|
|
---
|
|
|
|
## 4. 서브 모듈 요약
|
|
|
|
- **`:gdrive` (`kr.gdrive.bums.lunatic.utils`)**:
|
|
- `GDriveLoginManager`: `GoogleSignIn`과 `DriveScopes.DRIVE_APPDATA` 권한 요청을 캡슐화합니다.
|
|
- `GDriveBackupTask`: `appDataFolder`에 `manifest.json` 및 백업 대상 JSON 파일들을 업로드하는 코루틴 기반 백업 태스크입니다.
|
|
- **`:lun_launcher` (Wear OS)**:
|
|
- `MainActivity`: Wear OS Compose UI 및 센서 리스너를 통해 런처로 제스처 메시지를 전송합니다.
|
|
- `MainTileService`, `MainComplicationService`, `TileActionReceiver`: 워치 페이스 컴플리케이션 및 Wear Tile을 제공합니다.
|