115 lines
5.9 KiB
Markdown
115 lines
5.9 KiB
Markdown
# AI Agent 지시서 (Shiftring 프로젝트 - v1.0.0)
|
|
|
|
## 1. 기본 원칙
|
|
- 모든 브리핑, 문서, 커밋 메시지 초안은 **한글**로 작성한다.
|
|
- 수정 시 항상 원본 대비 전체 코드/문서 기준으로 설명하며 거짓말하지 않는다.
|
|
- 안드로이드 앱은 Play Store 없이도 릴리즈 빌드 및 업데이트가 가능한 구조를 유지한다.
|
|
- 앱 공식 명칭: **교대링 (Shiftring)**
|
|
- **버전 넘버링 규칙**:
|
|
- 버전은 `X.Y.Z` 형식을 따른다.
|
|
- `Z`(마지막 자리)는 **9**가 최대치이며, 9 다음에는 `Y`(가운데 자리)를 1 올리고 `Z`를 0으로 초기화한다.
|
|
- 예: `1.0.9` -> `1.1.0`, `1.1.9` -> `1.2.0`.
|
|
- `Y`가 9가 되면 `X`를 1 올리고 `Y`, `Z`를 0으로 초기화한다.
|
|
- 예: `1.9.9` -> `2.0.0`.
|
|
|
|
---
|
|
|
|
## 2. 프로젝트 핵심 아키텍처 및 상태
|
|
### 2.1 데이터 정밀도 (Precision & Sync)
|
|
- **Timezone**: 모든 시간 계산(알람, 근무 로직, DB 저장)은 반드시 **'Asia/Seoul'** 표준 시간대를 사용한다 (`java.time.ZoneId.of("Asia/Seoul")`).
|
|
- **Manual Override**: 사용자가 수동으로 설정한 근무 및 알람 시간(Room DB의 `manualAlarmTime`)은 시스템의 자동 스케줄러(`AlarmWorker`)보다 우선하며, 절대 덮어씌워져서는 안 된다.
|
|
- **백업/복구**: `BackupManager`를 통해 JSON 형식으로 백업한다. 복구 시 **설정(SharedPreferences)을 DB보다 먼저 복원**하여 근무 데이터 유실 및 매칭 오류를 방지한다.
|
|
|
|
### 2.2 알람 가이드 (Engine v4.5)
|
|
- **Exact Timing**: `setAlarmClock` API를 표준으로 사용하여 Doze 모드와 배터리 최적화를 무시하고 정시에 알람을 실행한다.
|
|
- **Reliability Check**: 앱 실행 시 `AlarmPermissionUtil`과 `checkBatteryOptimization`을 통해 권한 상태를 검증하고 사용자에게 안내한다.
|
|
- **Wake-Up Strategy**: Android 8.0~15 전 버전에 대응하는 `FullScreenIntent` + `setShowWhenLocked` 조합으로 잠금화면 위에서도 즉시 점등 및 전체화면 알람을 보장한다.
|
|
|
|
---
|
|
|
|
## 3. 리모트 릴리즈 프로세스 (Deployment)
|
|
### 3.1 단일 저장소 전략 (GitLab 웹플러스)
|
|
- **메인 저장소**: `https://git.webpluss.net/sanjeok77/ShiftRing`
|
|
- 코드와 APK 릴리즈를같은 저장소에서 관리합니다.
|
|
|
|
### 3.2 업데이트 시스템 (Auto-Update)
|
|
- **업데이트 체크 URL**: `https://git.webpluss.net/sanjeok77/ShiftRing/version.json`
|
|
- **AppUpdateManager 위치**: `app/src/main/java/com/example/shiftalarm/AppUpdateManager.kt`
|
|
- **version.json 형식**:
|
|
```json
|
|
{
|
|
"versionCode": 100,
|
|
"versionName": "1.0.0",
|
|
"apkUrl": "https://git.webpluss.net/sanjeok77/ShiftRing/releases/download/v1.0.0/app.apk",
|
|
"changelog": "버그 수정 및 성능 개선"
|
|
}
|
|
```
|
|
|
|
### 3.3 릴리즈 순서
|
|
|
|
> **참고**: Gitea Release APK 업로드 방법은 [RELEASE_UPLOAD_GUIDE.md](./RELEASE_UPLOAD_GUIDE.md) 문서를 참조하세요.
|
|
|
|
1. **버전 업데이트**: `build.gradle.kts`에서 `versionCode`와 `versionName`을 올린다.
|
|
- 예: `versionCode = 1120`, `versionName = "1.2.0"`
|
|
2. **빌드**: 릴리즈 빌드 수행
|
|
```bash
|
|
./gradlew assembleRelease
|
|
```
|
|
3. **릴리즈 생성**: Gitea API 또는 웹 인터페이스 사용
|
|
- 자세한 방법은 [RELEASE_UPLOAD_GUIDE.md](./RELEASE_UPLOAD_GUIDE.md) 참조
|
|
4. **version.json 업데이트**: ShiftRing 리포지토리 루트에 `version.json` 파일 생성/수정
|
|
```json
|
|
{
|
|
"versionCode": 1120,
|
|
"versionName": "1.2.0",
|
|
"apkUrl": "https://git.webpluss.net/sanjeok77/ShiftRing/releases/download/v1.2.0/app.apk",
|
|
"changelog": "수정사항 요약"
|
|
}
|
|
```
|
|
5. **소스 코드 커밋**: 코드 저장소에 변경 사항 푸시
|
|
```bash
|
|
git add -A
|
|
git commit -m "Release v1.2.0"
|
|
git push origin main
|
|
```
|
|
|
|
### 3.4 저장소 정보 (단일 저장소 전략)
|
|
- **메인 저장소**: `https://git.webpluss.net/sanjeok77/ShiftRing.git`
|
|
- **역할**: 코드 관리 + APK 릴리즈 (통합)
|
|
- **Git Remote 설정**:
|
|
```bash
|
|
git remote add origin https://git.webpluss.net/sanjeok77/ShiftRing.git
|
|
```
|
|
|
|
### 3.5 업데이트 체크 로직 (AppUpdateManager.kt)
|
|
```kotlin
|
|
object AppUpdateManager {
|
|
private const val VERSION_URL = "https://git.webpluss.net/sanjeok77/ShiftRing/version.json"
|
|
|
|
fun checkUpdate(activity: Activity, silent: Boolean = false) {
|
|
// version.json에서 최신 버전 확인
|
|
// 새 버전 있으면 다이얼로그 표시 → APK 다운로드 → 설치
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 4. UI/UX 디자인 가이드 (One UI 8.x Focus)
|
|
- **Aesthetics**: Glassmorphism 및 Mesh Gradient 기반의 프리미엄 디자인 + 28dp 표준 곡률 적용.
|
|
- **Pill-Style Grid**: 달력의 근무 표시(주/석/야 등)는 텍스트만 표시하지 않고, 고유 색상이 적용된 'Pill(알약)' 형태의 배경을 사용하여 시인성을 극대화한다.
|
|
- **Header System**: 모든 화면의 상단에는 32sp 크기의 볼드체 타이틀과 충분한 수직 여백(32dp padding top)을 갖춘 헤더를 배치한다.
|
|
- **Spacing Rule**: 달력 내부 메모 및 텍스트는 `includeFontPadding = false`를 적용하여 수직 간격을 최소화하고 정보 밀도를 높인다.
|
|
- **Iconography**: **Lucide Icons** 스타일의 SVG(VectorDrawable)만 사용 (`ic_` 접두사).
|
|
|
|
---
|
|
|
|
## 5. 현재 버전 (v1.0.2) 주요 변경 사항
|
|
- **One UI 8.x 정체성 확립**: 단순 테마 적용을 넘어, 대형 헤더와 28dp 곡률 시스템을 앱 전체 레이아웃에 통합.
|
|
- **고가독성 달력 시스템**: 격자 테두리를 제거하고 알약 형태의 근무 인디케이터를 적용하여 훨씬 깔끔한 그리드 구현.
|
|
- **통합 디자인 언어**: 메인, 설정, 공지사항, 매뉴얼 등 모든 액티비티의 헤더와 패널 스타일을 통일.
|
|
- **알람 엔진 안정화**: `setAlarmClock` 기반의 Doze 모드 완벽 대응 로직 유지 및 성능 최적화.
|
|
|
|
---
|
|
*(이 지침서는 AI 에이전트 간의 일관된 개발을 위한 핵심 문서임)*
|