Skip to main content

JunkBox 네이티브 앱 junkbox-app 가이드

1. 프로젝트 역할과 구현 범위​

  • JunkBox는 웹·서버와 설치형 클라이언트를 포함하는 생태계 이름임. Android 앱은 운영 prodRelease의 JunkBox App과 개발 devDebug의 JunkBox App Dev로 구분함. 두 앱은 열린 상자 형태를 공유하며 개발 adaptive icon은 주황 계열 배경색을 사용함.
  • junkbox는 기존 웹앱·백엔드·공통 라이브러리 저장소를 의미하며, junkbox-app은 별도의 네이티브 클라이언트 프로젝트를 의미함. 전체 명칭은 docs/junkbox/common/guide-jb-overview.md, 웹 우선·기능 병행 운영 원칙은 docs/junkbox/common/guide-jb-core.md를 따름.
  • 네이티브 앱은 통합 로그인·홈·기능 메뉴를 갖고 기기 기능이 필요한 작업을 제공함. Health 러닝 실행과 운동 세트 완료 뒤의 휴식 타이머를 지원함.
  • 별도 junkbox-app 저장소에 Kotlin·Jetpack Compose Android 소스, Gradle Wrapper, GitHub Actions 릴리스 워크플로와 전용 서명 설정이 있음. 앱 홈의 첫 타일은 Health 러닝 기능으로 연결되며 화면에는 러닝으로 표시함.
  • Hub 웹 로그인 인계, Health 웹 계획 선택, Foreground Service 러닝 실행, 단계별 서버 진행 반영과 로컬 복구가 구현돼 있음. 서명 APK는 비공개 GitHub Release로 게시함. 실기기 음성·절전·Obtainium 설치는 검증되지 않은 상태임.
  • 앱 소스와 게시 APK의 상태는 구분함. 소스에 있는 기능이 게시 APK에 포함됐다고 가정하지 않으며, 게시 범위는 앱 docs/android/RELEASE.md와 실제 Release를 확인함.

2. 워크스페이스 구조​

/home/sleepzz/dev/workspaces/
├── junkbox/ # AI 작업 창구·웹·서버
│ ├── AGENTS.md # 웹·서버·Android 통합 지침
│ ├── .agents/skills/
│ │ ├── junkbox-dev-finalize/ # 공통 흐름과 조건부 참고 문서
│ │ └── junkbox-app-dev-apk/ # 휴대폰 테스트 APK 생성·검증
│ └── docs/junkbox-app/
│ ├── PROJECT-PLAN.md
│ ├── NATIVE-FEATURE-REVIEW.md
│ └── RUNNING-UI-PARITY-PLAN.md
└── junkbox-app/ # 독립 Git·앱 빌드·릴리스
├── README.md
├── .gitignore
├── .github/workflows/
├── apps/android/
│ ├── app/
│ ├── assets/
│ ├── gradle/
│ ├── scripts/
│ └── gradlew
└── docs/android/ # 구현·검증·홈 메뉴·배포
  • junkbox-app/apps/android/는 Android Studio 프로젝트 루트이며 단일 app 모듈과 Gradle Wrapper를 포함함.
  • OS별 디렉터리는 apps/<os>/ 계약임. 현재 Android만 대상이며 iOS·Windows 소스와 공통 멀티플랫폼 모듈은 없음.
  • AI 코딩은 /home/sleepzz/dev/workspaces/junkbox에서 시작하며 웹·서버·앱 모두 해당 루트의 AGENTS.md와 .agents/skills/를 사용함. 앱 저장소에는 에이전트 지침·스킬·후속 시작 프롬프트를 두지 않음.
  • /home/sleepzz/dev/workspaces/junkbox/docs/junkbox-app/PROJECT-PLAN.md는 제품 취지·합의·상세 구현 순서·검증 기준·후속 AI 시작 요청문을 소유하는 인계 문서임. 같은 폴더의 NATIVE-FEATURE-REVIEW.md와 RUNNING-UI-PARITY-PLAN.md는 기능 확장 검토와 러닝 화면 작업 계획을 소유함. 구현 전 현재 코드·환경과 함께 읽는 기준 문서임.
  • 앱 저장소의 docs/android/IMPLEMENTATION.md, HOME-MENU.md, BUILD-PROFILES.md, RELEASE.md는 앱 소스와 함께 관리할 구현·검증·홈 메뉴·서명·배포 계약임. 두 Git 저장소와 CI는 독립 유지하며 명령 실행 위치·Git 범위를 저장소별로 명시함.
  • Vault의 이 문서는 생태계에서의 현재 위치·책임·진입점만 설명하며 상세 미래 실행 계획을 복제하지 않음.

3. 웹·네이티브 기능 배치 기준​

기능책임 및 현재 상태
사용자·자격 검증·세션·권한기존 Hub가 소유하는 서버 기능임
로그인 화면기존 Hub 웹 화면을 Custom Tabs로 열고 일회용 코드·PKCE로 앱 세션을 발급받음
러닝 계획 목록·상세·생성·수정·삭제현재 Health 웹·API가 제공하는 기능이며 네이티브의 재사용 대상임
현재 러닝 실행Health 웹의 /running-run/{planId}가 제공하는 기능임
네이티브 러닝 실행Android Foreground Service가 시간·단계·음성·진동·알림을 담당함
운동 세션 기록·타이머 연결Health 웹·API가 저장 성공과 세트 순서를 판단하고 휴식 초와 선택적인 종료 전 안내 초만 앱에 전달함
운동 휴식 타이머Android 앱이 사용자별 세트 간·운동 간 휴식 초와 선택적인 종료 전 안내 초를 API로 관리하고 서비스에서 초 단위 실행·음성·효과음·알림을 담당함
도메인 영속 데이터기존 Health API와 Health SQLite가 소유함
앱 인증 연결·웹 연결·API 소비Hub 앱 인증과 Health API 소비를 네이티브 앱에서 공유함
  • 단순 조회·입력·관리는 웹을 우선하고 백그라운드 실행이나 기기 연동의 효용이 큰 부분만 네이티브로 구현하는 기준임.
  • 웹과 네이티브에서 같은 기능을 병행 운영할 수 있으며, 실제 사용성과 안정성에 따라 보완하거나 한쪽 구현으로 통합·제거하는 정책임. 기능별 병행 구현은 계정·기준정보·업무 데이터의 독립적인 이중 관리와 구분함.
  • 현재 웹 러닝은 유지됨. 네이티브 프로젝트가 준비됐다는 이유로 웹 실행을 제거하거나 모든 계획 관리 화면을 네이티브로 다시 작성하지 않음. 책임 재배치는 구체적인 후속 요청과 영향 검증을 기준으로 함.
  • 공통화는 기존 인증·API·기기 개발 도구를 재사용하는 책임 분리임. 사용하지 않는 플랫폼·새 사용자 관리 체계·범용 앱 프레임워크를 선행 구축하는 근거로 사용하지 않음.

3.1 모바일 화면 액션 배치 기준​

  • 모바일 기능 개선 전에 현재 소스의 유사 화면과 JunkboxDesign.kt·공통 Compose 컴포넌트를 먼저 확인함. 주요 액션의 하단 고정 배치·버튼 순서·폭 정책은 공통 UI 가이드 7.4절의 웹·네이티브 공통 원칙을 따름.
  • 러닝 계획 선택 전에는 홈 아이콘 → 웹에서 계획 선택, 선택 후 준비 화면에는 홈 아이콘 → 계획 다시 선택 → 러닝 시작을 하단에 배치함. 계획 다시 선택은 미시작 계획의 앱 선택·저장된 선택 ID·진행 중 조회 결과를 무효화하고 선택 전 화면으로 돌아감. 그 화면의 웹 버튼으로 다시 선택하며 서버 계획·기록·동기화 대기는 변경하지 않음. 실행·일시정지 중에는 기존 러닝 조작을 유지함.
  • 운동 설정 화면에는 홈 아이콘 → 저장을 하단에 배치함.
    • 집 모양 홈 아이콘과 저장 텍스트 버튼의 폭은 공통 혼합형 원칙을 따름.
    • 세트 간·운동 간 휴식과 선택적인 종료 전 안내 초를 라벨이 있는 입력칸으로 받으며 저장·실패·안내 결과는 하단 버튼 바로 위의 일시적인 토스트로 표시하며 성공·오류·안내는 3.2절의 형태 구분을 따름.
    • 타이머 상태와 숫자는 가운데 정렬하고 우측 상단의 작은 연동 배지에서 연결 상태를 확인하거나 연동 해제를 요청함.
    • 일시정지·재개와 취소는 타이머 카드의 윤곽 버튼 조작으로 두고 취소·연동 해제에는 확인을 받음.
    • 저장만 민트 채움 버튼임.
  • 앱 홈으로 이동하는 버튼은 집 모양 아이콘을 사용하며, 세 줄 목록 아이콘은 실제 목록으로 이동하는 경우에만 사용함.
  • 선택·준비·설정 화면은 앱의 JunkboxBottomActionBar를 재사용함. Scaffold.bottomBar의 실제 크기를 본문 contentPadding에 반영하고 시스템 내비게이션·키보드 inset을 처리하여 스크롤 마지막 입력과 안내를 가리지 않음. 실행 중 타이머의 기존 JunkboxRunControls는 실행 조작 패턴으로 유지함.
  • 홈 타일 아이콘은 공통 40dp로 오른쪽 위, 제목은 왼쪽 아래, 진행 상태 점은 왼쪽 위에 배치함. 세부 타일·메뉴 등록 기준은 앱 docs/android/HOME-MENU.md와 현재 공통 토큰을 확인함.

3.2 앱 색상 원칙: 검정·흰색·민트 3색​

  • 앱의 모든 화면은 검정·흰색·민트 3색만 사용하며, 이는 신규 기능 추가와 이후의 모든 수정에 예외 없이 적용하는 원칙임. 이 절이 규칙의 원본임. 웹의 4색(흰색·빨강·노랑·검정)과 jb-* 클래스는 네이티브에 쓰지 않음. 구현 기록은 앱 docs/android/IMPLEMENTATION.md의 3색 팔레트와 버튼 의미 기준, 색 정의는 앱 JunkboxDesign.kt가 소유함.
  • 3색은 검정 background(0B0D10), 흰색 text(F2F5F4), 민트 primary(9DE7D7, 홈 타일 배경과 같은 앱 강조색)임.
    • 카드 면·구분선·보조 글자·비활성은 검정 위에 흰색을 알파로 얹은 파생 톤(surface·softSurface·outline·muted·progressTrack·disabledFill)으로만 만들며 새 색상값을 추가하지 않음.
    • 빨강·노랑 등 별도 색상과 그 토큰(warning·danger 등)을 정의하거나 Color(0x...)·Color.White 같은 값을 화면 코드에 직접 쓰지 않음.
구분앱 표현적용 대상
즉시 저장·완료·종료가 확정되는 버튼 (웹의 흰색·빨강·노랑)민트 채움 JunkboxButton운동 타이머 저장, 러닝 운동 완료, 러닝 종료와 그 확인창 확정, 서버 반영 다시 시도
저장소 변경이 없는 버튼 (웹의 검정)검정 윤곽 JunkboxOutlineButton로그인, 러닝 시작, 계획 다시 선택, 일시정지·재개, 타이머 취소, 연동 해제, 홈 타일 편집 완료, 그 밖의 모든 화면 전환·조회
성공·오류·경고·안내색 대신 형태·표식성공 민트 채움+✓, 오류 흰색 채움+!, 경고 민트 테두리+!, 안내 어두운 면
진행·연결 상태민트·흰색·회색 파생 톤과 문구실행 중 민트, 일시정지 흰색, 연결 중·재연결 중 민트 테두리 점
  • 화면·알림의 단위 표기는 공통 UI 가이드 2.8을 따르며 JunkboxUnits.withUnit을 사용함. 음성 안내 문구는 적용하지 않음.
  • 버튼 색 의미는 공통 UI 가이드 7.1의 판단 순서를 그대로 따르되 색은 둘로 줄임.
    • 클릭이 곧바로 저장·완료·종료·삭제 등 저장소·서버 반영을 확정하면 민트 채움 버튼(JunkboxButton)임.
    • 저장소 변경 없이 화면 전환·조회·새로고침·패널 열기·임시 상태 변경이면 검정 윤곽 버튼(JunkboxOutlineButton)임.
    • 실행 조작용 아이콘 버튼도 JunkboxControlSurface의 emphasized 여부로 같은 기준을 따름.
    • 삭제가 생겨도 빨강을 정의하지 않고 민트 채움 버튼과 확인창으로 표현함.
  • 확인창의 확정 버튼도 같은 기준임. 확정이 곧바로 저장·종료를 일으키면 JunkboxConfirmDialog(emphasized = true)(민트 채움), 아니면 윤곽 버튼임. 취소 버튼은 항상 윤곽·글자 버튼임.
  • 판단 기준은 지금 이 클릭이 즉시 서버·저장소에 반영되는가임. 홈 타일 배치처럼 기기 로컬 설정은 서버 저장이 아니므로 윤곽 버튼임. 한 액션 영역의 민트 채움 버튼은 가능하면 1개로 두고, 반영이 없는 버튼을 민트로 만들지 않음. 앱에는 삭제 버튼이 없어 빨강을 정의하지 않음.
  • 진행 상태 배지와 점은 민트(활성)·흰색(일시정지)·회색 파생 톤(비활성)과 문구로 구분하며, 연결 중·재연결 중은 민트 테두리 점으로 표시함.
  • 오류·경고는 색만으로 구분하지 않고 JunkboxMark와 문구를 함께 사용함. 토스트·상태 박스·배지는 JunkboxDesign.kt의 공통 컴포넌트를 재사용하며 화면에서 색을 직접 지정하지 않음.
  • 예외는 앱이 직접 그리지 않는 Android 시스템 UI(권한·배터리 최적화 대화상자, 시스템 토스트, 알림 소형 아이콘 처리)와 런처 아이콘 자산(개발 프로필의 주황 배경 등 환경 구분 색)뿐임. 화면 안에서 3색 밖의 색이 필요해 보이면 임의로 추가하지 않고 사용자와 원칙 변경을 먼저 합의함.
  • 앱의 신규 화면·기능·수정 작업은 구현 전에 이 절을 확인하고, 구현 후 rg 'Color\(0x|Color\.(White|Black|Red)'로 색상값이 JunkboxDesign.kt 밖에 없는지 점검한 뒤 devDebug 화면에서 3색 적용을 확인함. 신규 기능 계획을 세울 때도 버튼 분류(민트 채움·윤곽)와 오류 표시 방식을 계획에 포함함.

4. 인증과 데이터 소유권​

  • Hub는 JWT·쿠키·세션 상태·갱신·revoke·사용자 권한을 소유함. 네이티브 앱용 별도 비밀번호 검증이나 사용자 DB를 만들지 않는 기준임.
  • 기존 브라우저 쿠키 로그인과 네이티브 API 클라이언트 인증은 별개의 통신 상태임. 브라우저 로그인만으로 앱 API 인증이 자동 공유된다고 가정하지 않음.
  • 앱은 브라우저 Custom Tabs에서 Hub 웹 로그인을 재사용함.
    • Hub의 /api/auth/app/authorize가 일회용 코드와 PKCE challenge를 검증하고 운영에서는 junkbox://auth, 검증된 local/docker-local 개발 UI 요청에서는 junkbox-dev://auth로 복귀시킴.
    • scheme 선택은 공통 native_app_scheme(request)를 사용하며 운영 profile은 개발 origin 헤더가 있어도 운영 scheme을 유지함.
    • 앱은 /api/auth/app/exchange로 코드를 토큰으로 교환하고 /api/auth/app/refresh로 세션을 갱신함.
  • 네이티브 제품 진입은 일반 JunkBox 사용자 인증을 기준으로 하며 관리자 HUB 권한을 일괄 요구하지 않는 기준임. 러닝 API는 기존 HEALTH 권한과 현재 사용자 소유권을 따름.
  • 도메인 데이터·기준정보는 API로 소비하고 Hub·Health DB 파일을 직접 읽거나 앱에 복사해 업무 저장소로 사용하지 않음. 운동 실행용 snapshot·경과 시간·전송 대기는 로컬 실행 상태이며 서버 업무 데이터 소유권을 대체하지 않음.
  • 앱 인증·API·DB 계약 변경은 junkbox/AGENTS.md의 사전 조사와 마스터데이터와 DB 변경 절을 따름. Hub 앱 인증 코드 해시는 tb_app_auth_code_n에 저장되며 신규 권한 코드를 등록하지 않음.

4.1 날짜와 시간​

  • 네이티브 앱의 신규·변경 기능도 업무 날짜, 기본 입력, 일정 판단과 사용자 표시를 Asia/Seoul 기준으로 처리함. 네이티브에서 업무 일시가 필요하면 앱 내부 공통 코드에서 ZoneId.of("Asia/Seoul")을 명시하고, 기기 기본 시간대가 달라도 같은 업무 날짜와 시각을 표시함.
  • 서버가 제공하는 업무 날짜는 그대로 사용하고, offset 포함 일시는 KST로 변환함. API가 offset 없는 값을 KST로 정의한 경우 기기의 로컬 시각으로 파싱하지 않음. 한국 자정 직전·직후를 KST 이외의 기기 시간대로 검증함.
  • 러닝·휴식 타이머의 경과 시간은 SystemClock.elapsedRealtime() 기준으로 계산함. 버전 토큰으로 받은 서버의 updated_at은 비교 계약에 맞춰 보존함.

5. 러닝 연계의 현재 계약과 구현 기준​

  • Health API는 계획 상세 GET /api/health/running/plans/{plan_id}, 단계 유형 GET /api/health/running/meta/steps, 진행 갱신 PUT /api/health/running/plans/{plan_id}/progress, 웹 수행 완료 POST /api/health/running/plans/{plan_id}/performed, 앱 조건부 완료 POST /api/health/running/plans/{plan_id}/performed/conditional을 제공함.
  • 현재 진행 저장은 상태·timeline 단계 번호 중심임. 정확한 경과 시간·일시정지 상태나 네이티브 실행 세션 이력이 서버에 저장된다고 가정하지 않음.
  • 현재 웹 러닝은 실제 시각 기준으로 단계 위치를 계산하고 visible 복귀 시 상태를 보정함. 브라우저 백그라운드에서 단계 안내를 제때 실행하는 보장과 구분함.
  • Android 러닝과 운동 타이머는 앱의 AnnouncementPlayer로 음성을 재생함. 웹과 앱의 러닝 안내 문구·시점은 Health UI 가이드의 음성 안내를 따름.
  • Health PWA는 웹 설치형 실행이며 Android Foreground Service를 갖는 네이티브 앱이 아님. Service Worker와 Screen Wake Lock을 네이티브 백그라운드 서비스의 대체 수단으로 취급하지 않음.
  • 운동 휴식 타이머 서비스는 수신 스트림이 끊기면 사유(수신 시간 초과·네트워크 오류·서버 응답 오류·서버가 연결을 닫음·로그인 만료·서버 연동 종료)를 기록하고 1~10초 백오프로 자동 재접속함.
    • 서버 유예 시간과 같은 10분을 넘기거나 로그인 만료·서버 연동 종료이면 재접속을 중단하고 안내함.
    • 기본 네트워크가 바뀌거나 복구되면 대기를 건너뛰어 즉시 다시 맺고, 연동 중에는 partial wake lock과 Wi-Fi 락을 유지하며, 서비스가 정리돼도 저장된 연동으로 10분 안에 재접속함.
    • 운동 화면은 최근 끊김·복구 기록과 배터리 제한 해제 안내를 표시함.
    • 화면 꺼짐 중 Wi-Fi 락의 효과와 제조사 절전 동작은 실기기 검증 대상임.
  • 사용자가 시작한 운동은 폰의 Foreground Service가 소유하며 화면·네트워크와 독립적으로 시간·단계·안내를 처리함. 서버 Automation 예약 작업으로 만들지 않음.
  • Android는 Kotlin·Jetpack Compose·Coroutines/Flow를 사용함. 서비스는 센서 없는 타이머에 specialUse 타입과 실행 중 partial wake lock을 사용함. 실제 음성·블루투스·절전 제한은 실기기 검증 대상임.
  • Health 웹 계획 카드의 시작 (App)은 서버가 검증해 페이지 초기 데이터로 전달한 nativeAppScheme에 따라 운영 junkbox://run?plan_id=... 또는 개발 junkbox-dev://run?plan_id=...로 식별자만 전달함. 앱은 계획·소유권·권한을 Health API로 다시 확인한 뒤 사용자 조작으로 실행함. 시작 (Web)은 기존 웹 러닝을 유지함.
  • 앱은 단계 전환마다 expected_updated_at 조건과 함께 IN_PROGRESS 및 현재 timeline index를 서버에 저장하고, 종료 시 READY와 빈 index를 저장함. 마지막 단계 완료 시에는 조건부 완료 API로 COMPLETED를 반영함. 충돌은 409로 처리하며 오래된 상태로 서버를 덮어쓰지 않음.
  • 앱 실행 snapshot은 계획 제목·블록명·반복 회차와 평탄화된 구간을 보존하며 구버전 JSON 배열도 읽음. Compose는 서비스의 현재·다음 구간 상태를 표시하고, 마지막 구간의 다음 조작은 웹과 같이 완료 경로를 사용함. 실제 동기화 실패·충돌이 확인됐을 때만 보류 안내와 재시도 동작을 표시함.
  • 러닝 준비 화면은 하단에 홈 아이콘·계획 다시 선택·러닝 시작 조작을 나란히 두며, 시작은 사용자 조작으로만 수행함. 실행 화면은 Health 웹과 같은 계획 제목·상태·남은 시간·유형·속도·경사도·블록 회차·전체 구간·다음 구간·진행 시간과 일곱 조작을 표시함.
  • Android 홈은 어두운 JunkBox 테마 위에 한 줄 3개 배치의 정사각형 민트색 러닝 타일을 표시함.
    • 타일에는 오른쪽 위의 공통 40dp 채워진 단색 러너 실루엣과 하단 왼쪽 러닝 제목을 두고 진행 상태 점은 왼쪽 위에 표시하며 러닝 화면 제목도 러닝으로 표시함.
    • 색상·타일 치수·글자 스타일·패널·조작 버튼의 공통 외형은 앱의 JunkboxDesign.kt에서 관리함.
    • 이 아이콘 변경은 현재 소스와 devDebug 빌드에 반영됐으며 Android 16 에뮬레이터에서 배치·화면을 확인함.
    • 실제 휴대폰 화면 확인은 별도 검증 대상임.
    • 새 메뉴의 배치·아이콘·제목·접근성·권한 기준은 앱 저장소의 docs/android/HOME-MENU.md를 따름.

6. 공통 로컬 개발 환경​

  • 앱의 apps/android/app-profiles.json이 환경별 이름·패키지·scheme과 서비스의 운영 URL·개발 UI 포트를 관리함. 임시 패키지 접미사 옵션은 사용하지 않으며, 개발 프로필·아이콘·APK를 운영 설정으로 덮어쓰지 않음.
    • 활성 빌드 조합은 prodRelease·devDebug 두 개임.
    • 운영은 JunkBox App·dev.junkbox.app·junkbox와 Hub https://hub.sleepzz.xyz, Health API·웹 https://health.sleepzz.xyz를 사용함.
    • 개발은 JunkBox App Dev·dev.junkbox.app.test·junkbox-dev와 https://serverzz.tailc830ea.ts.net:15001의 Hub, :15003의 Health API·웹을 사용함.
  • 개발 URL은 dev 프로필에서만 Gradle junkboxHubUrl·junkboxHealthUrl·junkboxHealthWebUrl 또는 junkboxTailnetHost로 조정함. .test는 프로필에 자동 적용되어 이전 junkboxDebugSuffix는 사용하지 않음. 운영 빌드는 개발 URL·호스트 옵션을 거부함. 개발 프로필을 운영값으로 덮어쓰는 복구를 하지 않음. 프로필과 앱 연결 분리는 업무 DB 격리를 의미하지 않음.
  • 공통 SDK·Emulator·ADB 경로는 /home/sleepzz/Android/Sdk임. 프로젝트 내부 SDK를 별도로 설치하지 않는 기준임.
  • 호스트 공통 환경은 /home/sleepzz/.config/android-dev/env.sh, 실행 도구는 /home/sleepzz/.local/bin/android-dev, 도구 설명은 /home/sleepzz/dev/tools/android/README.md임.
  • AVD 저장 위치는 /home/sleepzz/.android/avd임. junkbox-api36은 JunkBox용 Android 16(API 36) 테스트 기기이며 TVMON 테스트 기기와 사용자 데이터를 분리함. 권장 콘솔 포트는 5580, ADB serial은 emulator-5580임.
  • 공통 android-dev start는 Docker에 KVM 장치를 전달하는 창·오디오 없는 실행 방식임. 낮은 파일 열기 제한에서는 SDK·JDK·Gradle 캐시를 공유하는 일회용 빌드 컨테이너를 제공함. 앱별 Gradle 버전·서명·빌드 산출물은 별도 책임임.
  • sleepzz 계정은 kvm 그룹에 등록돼 있으며 해당 그룹이 적용된 프로세스는 호스트 KVM 직접 가속을 사용할 수 있음. 기존 IDE·Codex·터미널의 실제 상속 그룹은 계정 등록 상태와 구분해 확인함. 공통 실행 도구가 자동으로 호스트 직접 실행 방식으로 바뀌는 것은 아님.
  • 에뮬레이터에서는 로그인·웹 인계·백그라운드 러닝·오프라인 반영을 검증함. 실제 음성·미디어 간섭·블루투스·제조사 절전 동작은 휴대폰 검증 대상임.

6.1 프로필별 APK와 휴대폰 테스트 제공​

  • 프로필별 구성·명령·출력 계약은 앱 docs/android/BUILD-PROFILES.md가 소유함. 개발 아이콘 배경은 src/dev/res/values/launcher_colors.xml의 #7C2D12, 운영은 공통 #0B0D10임. 실제 휴대폰 런처 외형·병행 설치·로그인 왕복 확인은 별도 검증 대상임.
  • 개발 빌드는 :app:assembleDevDebug, 단위 검증은 :app:testDevDebugUnitTest, lint는 :app:lintDevDebug임.
    • 운영 빌드는 :app:assembleProdRelease·:app:lintProdRelease임.
    • Gradle 출력은 각각 app/build/outputs/apk/dev/debug/app-dev-debug.apk, app/build/outputs/apk/prod/release/app-prod-release.apk이며 서명 없는 로컬 운영 검증 APK는 app-prod-release-unsigned.apk임.
  • 앱 scripts/verify_profile.py는 APK의 이름·패키지·debuggable·Manifest scheme·내장 서비스 URL과 다른 환경 주소 혼입을 검사함. 운영 scripts/prepare-release.py는 이를 기존 인증서·버전·정렬 검사와 함께 사용함. 운영 릴리스 Actions는 prodRelease만 빌드함.
  • 휴대폰 테스트 APK는 JunkBox의 .agents/skills/junkbox-app-dev-apk/SKILL.md에서 생성함. 도우미가 프로필·현재 Vite 포트·Tailnet 호스트·UI Serve 프록시·HTTPS API 응답을 확인하고 devDebug 빌드·실제 APK 검증 뒤 제공 파일을 갱신함. UI 프록시를 통해 API에 접근하며 API의 루프백 포트를 직접 외부 개방하지 않음.
  • 개발 APK 접근 경로는 /home/sleepzz/dev/workspaces/junkbox-app/debug-apk/app-dev-debug.apk, 제공용 복사본은 /home/sleepzz/dev/workspaces/junkbox/ai-outputs/android-dev-apk/JunkBox-App-Dev.apk, 주소·SHA-256·검증 범위 기록은 같은 폴더의 BUILD.json임. 네트워크 검사 생략·휴대폰 미검증 여부를 별도로 기록하고 APK·캐시는 Git에 포함하지 않음.
  • APK와 제공용 링크는 웹앱의 public·소스·빌드 입력 폴더에 두지 않음. 휴대폰용 HTTP 다운로드가 필요하면 웹 빌드와 독립된 제공 경로를 사용하며 서버·파일의 유지 기간을 함께 정함. 유지할 다운로드 링크의 원본은 /tmp에 두지 않음. JunkBox Docker 빌드 컨텍스트에서는 APK를 제외함.

7. 앱 개발 세션 마무리와 배포​

  • 웹만·앱만·양쪽 변경 모두 junkbox/.agents/skills/junkbox-dev-finalize/SKILL.md에서 마무리를 시작함.
    • 세션 범위 확인, 해당 변경 검증·관련 문서 갱신·벡터 사전 확인, 유효한 결정의 번호형 통합 질문, 승인된 동기화·환경 정리·저장소별 커밋/푸시·조건부 환경 파일 복사·임시 파일 보관, 조건부 앱 릴리스와 최종 보고의 5단계를 진행함.
    • Android 세부 절차는 같은 스킬의 references/android.md에서 해당 절만 읽음.
    • 프로필 확인과 앱 검증은 APK·빌드·릴리스 계약에 영향이 있을 때 수행하고, 릴리스 결정은 다른 결정과 같은 통합 질문에서 받고 실행은 앱 커밋·푸시가 확인된 뒤 수행함.
    • 문서·벡터·환경 정리는 공통 흐름에서 한 번 처리하며 Vault 문서는 소스 커밋에 포함하지 않음.
  • 커밋 검토 전에 최종 prodRelease의 운영 주소·이름·패키지·scheme과 개발 옵션 거부를 확인하고 dev 프로필·개발 APK는 보존함. 같은 최종 내용의 빌드·APK 검사 결과는 재사용함.
  • 커밋 범위와 접두어·한글 제목의 추천 메시지는 변경 저장소별로 사용자 결정을 받은 뒤 확정함. 일반 개발 작업에서는 AI가 임의로 커밋·푸시하지 않음. 이 마무리 스킬은 저장소별 범위·메시지와 AI의 커밋·푸시 실행 여부를 함께 추가 승인받고 승인된 저장소만 실행함. 범위·메시지만 승인한 답변이나 스킬 호출 자체는 실행 승인이 아니며, 사용자가 직접 처리하기로 선택한 경우에는 그 결과를 기다림. 필수 질문에 명확한 답변이 없으면 다음 단계와 전체 완료 보고를 보류함.
  • APK에 영향을 주는 앱 변경·릴리스 계약 변경 또는 명시적 릴리스 요청에서는 통합 질문에 릴리스 결정을 포함하는 절차가 필수임.
    • 실제 릴리스 실행은 커밋·푸시와 별개 항목의 선택 사항이며 웹만·문서만 변경한 경우에는 해당 없음으로 기록함.
    • 질문 전에 just dev-finalize-release-check로 조회한 KST 형식의 태그, 같은 값의 versionName, 직전 게시 Release APK에서 계산한 다음 versionCode, 대상 커밋을 보여 줌.
    • 대상 커밋은 추가 앱 커밋이 없으면 원격 main의 전체 해시, 있으면 승인된 앱 커밋을 푸시한 직후의 원격 main임.
    • 태그의 시각은 질문 시점에 확정하며 실제 생성 시각과 달라도 그대로 사용함.
    • 사용자가 생성·푸시를 선택하면 앱 커밋·푸시 확인 뒤 추가 질문 없이 제시한 태그로 실행하고, 전제가 바뀐 경우에만 새 값을 제시해 다시 선택받음.
    • 답변 부재를 릴리스 생략으로 처리하지 않음.
  • 태그 푸시 시 GitHub Actions가 앱 전용 서명 APK를 비공개 GitHub Release에 게시함. APK versionCode는 직전 게시 Release APK의 실제 값에서 1 증가하며(최초 릴리스는 1), 실패한 태그는 코드를 소비하지 않음. 앱 저장소의 docs/android/RELEASE.md가 키·시크릿·검증·Obtainium 설치 절차를 설명함.
  • 세션 중 실행한 에뮬레이터와 앱 연동 로컬 서버는 소유와 실행 상태를 확인하고, 커밋·릴리스 전에 사용자의 유지·종료 답변을 받아 선택을 적용·검증함. 개발 중 서버 실행 요청만으로 마무리 후 유지가 선택됐다고 해석하지 않음.

8. 관련 문서​

  • 전체 생태계·저장소 명칭은 docs/junkbox/common/guide-jb-overview.md, 웹/네이티브 운영 원칙은 docs/junkbox/common/guide-jb-core.md를 따름.
  • 현재 Health 웹 실행과 PWA는 docs/junkbox/apps/guide-apps-health-ui.md를 따름.
  • 러닝 API·데이터 소유권은 docs/junkbox/apps/guide-apps-health-api.md를 따름.
  • 기존 인증·세션은 docs/junkbox/apps/guide-apps-hub-api.md, docs/junkbox/libs/guide-lib-shared-core.md를 따름.