# 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 에이전트 간의 일관된 개발을 위한 핵심 문서임)*
