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 형식:

{
  "versionCode": 100,
  "versionName": "1.0.0",
  "apkUrl": "https://git.webpluss.net/sanjeok77/ShiftRing/releases/download/v1.0.0/app.apk",
  "changelog": "버그 수정 및 성능 개선"
}

3.3 릴리즈 순서

버전 업데이트: build.gradle.kts에서 versionCode와 versionName을 올린다.
- 예: versionCode = 101, versionName = "1.0.1"
빌드: 릴리즈 빌드 수행
```
./gradlew assembleRelease
```

릴리즈 생성: GitLab 웹 인터페이스 또는 CLI 사용

# 1) ShiftRing 리포지토리에 푸시
git push shiftring main

# 2) 기존 릴리즈 삭제 (필요시)
gh release delete v1.0.1 --repo sanjeok77/ShiftRing -y

# 3) 신규 릴리즈 생성
gh release create v1.0.1 \
  --repo sanjeok77/ShiftRing \
  --title "v1.0.1 - 릴리즈 제목" \
  --notes "릴리즈 노트 내용" \
  app/build/outputs/apk/release/app-release.apk

version.json 업데이트: ShiftRing 리포지토리 루트에 version.json 파일 생성/수정

{
  "versionCode": 101,
  "versionName": "1.0.1",
  "apkUrl": "https://git.webpluss.net/sanjeok77/ShiftRing/releases/download/v1.0.0/app.apk",
  "changelog": "수정사항 요약"
}

소스 코드 커밋: 코드 저장소에 변경 사항 푸시

git add -A
git commit -m "Release v1.0.1"
git push origin main
git push shiftring main

3.4 저장소 정보 (단일 저장소 전략)

메인 저장소: https://git.webpluss.net/sanjeok77/ShiftRing.git
역할: 코드 관리 + APK 릴리즈 (통합)

Git Remote 설정:

git remote add origin https://git.webpluss.net/sanjeok77/ShiftRing.git

3.5 업데이트 체크 로직 (AppUpdateManager.kt)

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

6.2 KiB Raw Blame History