# app-distribution-dev

## 핵심 역할
**GUARDiA Messenger 앱 직접 배포 시스템**을 구현한다.
Manager 관리자가 APK 파일을 업로드하면 QR 코드가 자동 생성되고,
사용자는 QR 스캔만으로 앱을 설치할 수 있다 (앱스토어 불필요).

## 구현 범위

### Manager 신규 페이지: `AppDistribution.tsx`

```
/app-distribution 페이지:
  - APK 파일 업로드 (또는 외부 URL 설정)
  - QR 코드 이미지 표시 (자동 생성)
  - 버전 이력 관리
  - 다운로드 통계 (횟수, 디바이스)
  - iOS TestFlight / MDM URL 설정
```

### ITSM 신규 라우터: `app_deploy.py`

```python
# 엔드포인트
POST /api/app/upload            — APK 파일 업로드 + QR 생성
GET  /api/app/latest            — 최신 버전 정보 + QR 코드 URL
GET  /api/app/download          — APK 다운로드 (리다이렉트)
GET  /api/app/landing           — 사용자용 앱 다운로드 랜딩 페이지 (HTML)
POST /api/app/url               — 외부 URL로 QR 생성 (EAS 빌드 URL 등)
GET  /api/app/qr                — QR 코드 이미지 반환 (PNG)
GET  /api/app/versions          — 버전 이력
DELETE /api/app/versions/{id}   — 구버전 삭제
GET  /api/app/stats             — 다운로드 통계
```

### QR 코드 생성
```python
import qrcode
from io import BytesIO

def generate_qr(url: str) -> bytes:
    qr = qrcode.QRCode(version=1, box_size=10, border=5)
    qr.add_data(url)
    qr.make(fit=True)
    img = qr.make_image(fill_color="#003366", back_color="white")
    buf = BytesIO()
    img.save(buf, format='PNG')
    return buf.getvalue()
```

### 앱 다운로드 랜딩 페이지
```html
<!-- /api/app/landing 에서 반환하는 HTML -->
<!-- 사용자가 QR 스캔 시 보이는 화면 -->
Android: APK 직접 다운로드 버튼
iOS: TestFlight 링크 또는 공식 앱스토어 링크
- 설치 가이드 (알 수 없는 소스 허용 방법)
- 버전 정보 표시
- 설치 전 보안 안내
```

### DB 모델
```python
class AppVersion(Base):
    __tablename__ = "tb_app_version"
    id           = Column(Integer, primary_key=True)
    version      = Column(String(20))     # "1.2.3"
    platform     = Column(String(20))     # ANDROID | IOS | BOTH
    file_path    = Column(String(500))    # 서버 저장 경로
    download_url = Column(String(500))    # 외부 URL (EAS 등)
    qr_data      = Column(Text)           # QR 코드 base64 PNG
    release_notes = Column(Text)
    download_count = Column(Integer, default=0)
    is_latest    = Column(Boolean, default=True)
    uploaded_by  = Column(Integer)
    created_at   = Column(DateTime)
```

## 작업 원칙
1. APK 파일은 `/opt/guardia/app/uploads/apk/` 에 저장
2. QR 코드는 랜딩 페이지 URL을 인코딩 (APK 직접 URL 아닌 랜딩 페이지)
3. 랜딩 페이지에서 Android/iOS 자동 감지하여 분기
4. APK 최대 크기 200MB (기존 첨부파일 20MB와 별도)
5. 다운로드 시 디바이스 정보 수집 (통계용)
6. `qrcode` 라이브러리 pip install 필요

## 팀 통신 프로토콜
- **발신**: Manager AppDistribution.tsx 구현 요청
- **협업**: notification-ui-dev와 앱 업데이트 알림 연동