---
title: "🚀 운영규칙 — 앱 릴리스(Capgo OTA 무선 웹 업데이트 + 웹/네이티브 구분)"
category: "guide"
parent: "운영지침"
updated: "2026-07-03"
priority: "High"
purpose: "달록 앱(Capacitor) 스토어 등록 이후 수정 수요가 생겼을 때 어떻게 반영하는가의 표준 규칙. 웹 코드 수정은 Capgo OTA(capacitor-updater)로 스토어 심사 없이 즉시 반영, 네이티브 변경만 스토어 재배포. 블록3(앱화) 세팅 시 OTA 채널을 처음부터 구성. server.url 상시 웹뷰 방식은 금지."
read_when: ["앱 수정 반영","Capacitor OTA","capacitor-updater","Capgo","라이브 업데이트","스토어 심사 없이 반영","웹 네이티브 릴리스 구분","블록3 앱화","앱 업데이트 안 됨"]
document_type: "운영지침"
source_status: "generated"
knowledge_group: "01_rules"
work_timestamp: "20260703_183834"
source_of_truth: "https://dallog-tools.hansbridge.co.kr/knowledge/"
context: "달록본레포CC (D:\\dallog\\dallog_git)."
---

> 배경: 앱이 스토어에 등록된 뒤 수정 수요가 생기면, 데스크탑/모바일 웹(CF Pages)은 배포 즉시 반영되지만 **설치된 앱은 자기 안에 번들된 옛 웹 코드를 그대로 쓴다**(자동으로 안 바뀜). 이 격차를 어떻게 메우는가의 표준 규칙.

## 0. 핵심 한 줄
**웹 코드 수정 = Capgo OTA로 심사 없이 즉시 반영 / 네이티브 변경 = 스토어 재배포·심사.** OTA 채널을 블록3에서 처음부터 세팅해 둔다.

## 1. 구조 이해 — 앱은 두 겹
Capacitor 앱 = **React 웹 코드(HTML/JS/CSS)** 를 **안드로이드 네이티브 껍데기** 안에 번들해 넣은 것.
- 기본 Capacitor: 빌드 시점에 `dist`(Vite 빌드)를 앱에 복사(`npx cap sync`). → 웹 배포해도 설치된 앱엔 반영 안 됨.
- 그래서 "웹처럼 앱도 즉시 반영"하려면 **OTA(무선 웹 번들 업데이트)** 가 필요.

## 2. Capgo OTA 세팅 (capacitor-updater)
달록은 이미 Capgo 생태계(`@capgo/capacitor-health`) 사용 중 → 자연스럽게 연동.
- 설치: `npm i @capgo/capacitor-updater`
- 앱 진입 시 `CapacitorUpdater.notifyAppReady()` 호출(부팅 성공 통지 → 실패 시 이전 번들 자동 롤백).
- `capacitor.config`에 자동 업데이트(앱 실행/재개 시 체크) 설정.
- **`server.url`(앱이 상시 dallog.kr 로드) 방식은 금지** — 즉시 반영되나 ① 스토어가 '단순 웹뷰'로 반려 위험 ② 오프라인/초기로딩 문제. **번들 + OTA 조합이 정석.**

## 3. 배포 파이프라인 (웹 빌드 → OTA 채널 업로드)
- 기존: `npm run build`(dist) → `npx cap sync`(네이티브 번들).
- 추가: 웹 변경 배포 시 `npx @capgo/cli bundle upload --channel production` 으로 dist 번들을 OTA 채널에 업로드 → 설치된 앱이 실행 시 새 웹 번들 수신.
- CF Pages 웹 배포와 **같은 dist**를 OTA에도 올려 웹/앱 동기화.

## 4. 릴리스 구분 규칙 ★
| 변경 종류 | 반영 경로 |
|---|---|
| 화면·기능·버그·문구 등 **웹 코드만** (수정의 대부분) | **Capgo OTA 업로드** — 스토어 심사 X, 앱 재실행 시 몇 분 내 반영 |
| 헬스커넥트·권한·플러그인 추가/변경·Android SDK 상향·앱 아이콘/설정 등 **네이티브** | **앱 버전업 빌드 + Play 스토어 재등록·심사** (OTA 불가) |

## 5. 주의사항
- Google 정책상 **웹(해석형 JS/HTML/CSS)만 OTA 허용** — 네이티브 코드는 절대 OTA로 밀지 말 것.
- 네이티브 릴리스 시 앱 버전 코드 상향 필수. OTA 번들은 **호환 네이티브 버전에만** 적용되도록 채널/버전 게이팅.
- OTA 실패 자동 롤백(`notifyAppReady`) 동작을 반드시 검증.

## 6. 완료·검증 기준
- 웹 코드 한 줄 수정 → OTA 업로드 → **설치된 앱 재실행 시 반영** 확인(스토어 미경유).
- 롤백 동작(고의로 깨진 번들 → 이전 번들 복귀) 확인.
- 네이티브 변경은 스토어 릴리스로만 반영됨을 팀 규칙으로 문서화.

## 7. 관련
- 앱화 착수 작업보고: `Capacitor 폰앱 네이티브 착수(헬스커넥트)` KB 참조.
- 본레포 트래커: `docs/final_touch_260629/_02_WEARABLE_APP_PLAN.md`(앱화 계획).