# GUARDiA Messenger 개발 및 배포 가이드

> **버전**: 1.0.0 | **작성일**: 2026-05-31  
> **기술 스택**: React Native + Expo SDK 51 + EAS Build  
> **EAS 계정**: zioinfo | **성공 빌드**: 51096ada

---

## 1. 앱 개요

GUARDiA Messenger는 (주)지오정보기술의 GUARDiA ITSM 플랫폼과 연동하는 공식 모바일 앱입니다.

### 주요 기능

| 화면 | 기능 |
|------|------|
| 로그인 | GUARDiA ITSM JWT 인증 |
| 대시보드 | SR 통계, 서비스 상태, 배포 이력 |
| SR 관리 | 서비스 요청 목록 조회 및 신규 등록 |
| AI 챗봇 | Ollama LLM 기반 자연어 인프라 명령 |
| 알림 | 인시던트·SLA·배포 알림 수신 |
| 설정 | 프로필, 알림 설정, 로그아웃 |

### 기술 스택

| 항목 | 기술 |
|------|------|
| 프레임워크 | React Native 0.74.5 + Expo SDK 51 |
| 언어 | TypeScript (strict) |
| 라우터 | Expo Router 3.5.x |
| 인증 저장소 | expo-secure-store (보안 키체인) |
| HTTP 클라이언트 | Axios |
| 빌드 시스템 | EAS Build (Expo Application Services) |
| 서버 연결 | https://zioinfo.co.kr:8443 |

---

## 2. 개발 환경 설정

### 2-1. 필수 설치

```bash
# Node.js 20 LTS
node --version  # v20 이상

# Expo CLI
npm install -g expo-cli eas-cli

# 프로젝트 설치
cd C:\GUARDiA\app
npm install --legacy-peer-deps
```

### 2-2. 로컬 개발 서버

```bash
cd C:\GUARDiA\app
npx expo start

# QR 코드 스캔 → Expo Go 앱에서 실행 (개발 전용)
# 또는 npx expo start --android (에뮬레이터)
```

### 2-3. 프로젝트 구조

```
C:\GUARDiA\app\
├── app/
│   ├── _layout.tsx          ← 루트 레이아웃 (인증 라우팅)
│   ├── (auth)/login.tsx     ← 로그인
│   └── (tabs)/
│       ├── _layout.tsx      ← 탭 네비게이터
│       ├── index.tsx        ← 대시보드
│       ├── sr.tsx           ← SR 관리
│       ├── chat.tsx         ← AI 챗봇
│       ├── notifications.tsx← 알림
│       └── settings.tsx     ← 설정
├── components/              ← 공통 컴포넌트
├── constants/Config.ts      ← 서버 URL, 컬러 시스템
├── hooks/useAuth.ts         ← JWT 인증 훅
├── services/api.ts          ← GUARDiA ITSM API 클라이언트
├── plugins/
│   └── withGradleProps.js   ← Gradle 빌드 최적화
├── assets/                  ← 아이콘, 스플래시 이미지
├── app.json                 ← Expo 앱 설정
├── eas.json                 ← EAS 빌드 프로필
├── babel.config.js          ← Babel 설정
└── .easignore               ← EAS 업로드 제외 목록
```

---

## 3. EAS Build 가이드

### 3-1. EAS 초기 설정 (최초 1회)

```bash
cd C:\GUARDiA\app

# EAS 로그인
npx eas-cli login
# → expo.dev 계정 입력

# 프로젝트 초기화
npx eas-cli init
# → 프로젝트 ID 자동 등록
```

### 3-2. 빌드 명령어

```bash
# Android APK (테스트 배포 — 약 10~15분)
npx eas-cli build --platform android --profile preview

# Android AAB (Play Store 제출용)
npx eas-cli build --platform android --profile production

# iOS IPA (App Store 제출용, Apple Developer $99/년 필요)
npx eas-cli build --platform ios --profile production
```

### 3-3. 빌드 전 필수 체크리스트

| 항목 | 확인 방법 | 올바른 상태 |
|------|---------|-----------|
| android/ 폴더 없음 | `ls android/` | 없어야 함 |
| .easignore 설정 | `cat .easignore` | `android/`, `ios/` 포함 |
| PNG Crunching 비활성화 | `cat plugins/withGradleProps.js` | `false` 확인 |
| babel.config.js | `cat babel.config.js` | `babel-preset-expo`만 |
| EAS 로그인 | `npx eas-cli whoami` | `zioinfo` 표시 |

### 3-4. APK 폰 설치 방법

1. 안드로이드 폰에서 **Expo 빌드 URL** 열기
2. **Download** 버튼 탭
3. 설정 → 보안 → 알 수 없는 앱 설치 허용 (최초 1회)
4. APK 설치 완료

> **주의**: `adb` / Android Studio 불필요 — 브라우저 직접 다운로드로 설치

---

## 4. 빌드 이슈 이력 및 해결책

> 이 섹션은 실제 빌드 과정에서 발생한 이슈와 해결책입니다. 동일한 이슈 재발 시 이 섹션을 참조하세요.

### 이슈 1: android/ 폴더 → EAS Bare Workflow 오인

**증상**: `EAS_BUILD_UNKNOWN_GRADLE_ERROR` (반복 실패)

**원인 흐름**:
```
로컬 expo prebuild 실행
  → android/ 폴더 생성
  → EAS 업로드에 포함
  → EAS: "Bare Workflow 프로젝트" 인식
  → 로컬 android/ 그대로 사용 (EAS 환경과 불일치)
  → Gradle 빌드 실패
```

**해결**: `.easignore` 파일에 추가
```
android/
ios/
```

### 이슈 2: PIL PNG + AAPT2 PNG Crunching 충돌

**증상**: `expo-splash-screen:packageReleaseResources` 단계 실패

**원인**: Python PIL 생성 PNG + `enablePngCrunchInReleaseBuilds=true` → AAPT2 처리 불가

**해결**: `plugins/withGradleProps.js` 생성
```javascript
const { withGradleProperties } = require('@expo/config-plugins')
module.exports = function(config) {
  return withGradleProperties(config, (cfg) => {
    const set = (key, value) => {
      const idx = cfg.modResults.findIndex(p => p.key === key)
      idx !== -1 ? cfg.modResults[idx].value = value
                 : cfg.modResults.push({ type:'property', key, value })
    }
    set('android.enablePngCrunchInReleaseBuilds', 'false')
    set('reactNativeArchitectures', 'arm64-v8a')
    set('org.gradle.jvmargs', '-Xmx4096m -XX:MaxMetaspaceSize=1024m')
    return cfg
  })
}
```

### 이슈 3: expo-notifications 플러그인 빌드 실패

**증상**: Firebase 관련 Gradle 오류

**원인**: `expo-notifications` 플러그인이 `google-services.json` 파일 필요

**해결**: `app.json` plugins에서 `expo-notifications` 제거. 푸시 알림 추가 시 Firebase 설정 후 재등록.

### 이슈 4: expo-router/babel deprecated

**증상**: Babel 경고, 일부 환경에서 빌드 오류

**해결**: `babel.config.js`
```javascript
module.exports = function(api) {
  api.cache(true)
  return { presets: ['babel-preset-expo'] }
}
```

### 최종 성공한 빌드

| 항목 | 값 |
|------|-----|
| 빌드 ID | 51096ada-9735-4ea8-9e81-5f5991731ea8 |
| 플랫폼 | Android (APK) |
| EAS 계정 | zioinfo |
| 소요 시간 | 약 12분 |

---

## 5. 스토어 등록 절차

### 5-1. 사전 준비

| 항목 | Google Play | Apple App Store |
|------|------------|-----------------|
| 개발자 계정 | $25 (1회) | $99/년 |
| Privacy Policy | 필수 | 필수 |
| 스크린샷 | 최소 2개 | 최소 3개 (6.7인치) |
| APK/IPA | AAB 파일 | IPA 파일 |

### 5-2. Google Play Store 등록

```
1. play.google.com/console 접속
2. [앱 만들기] → 패키지명: kr.co.zioinfo.guardia
3. 스토어 등록정보 → 메타데이터 입력
4. 콘텐츠 등급 → 모든 연령 (비즈니스 앱)
5. 프로덕션 트랙 → AAB 업로드
6. 검토 제출 (2~7 영업일)
```

### 5-3. Apple App Store 등록

```
1. appstoreconnect.apple.com 접속
2. [새 앱] → 번들 ID: kr.co.zioinfo.guardia
3. 앱 정보 + 스크린샷 업로드
4. Privacy Policy URL 등록 (필수!)
5. npx eas-cli submit --platform ios --profile production
6. 심사 제출 (1~3 영업일)
```

---

## 6. 앱 로그인 정보

| 항목 | 값 |
|------|-----|
| 서버 URL | https://zioinfo.co.kr:8443 |
| 관리자 계정 | admin |
| 비밀번호 | Admin@zioinfo2026! |

---

## 7. 하네스 사용법

이 프로젝트는 `.claude/` 하네스가 구성되어 있습니다.

```
기능 개발 요청: "SR 상세 화면 추가해줘"
  → messenger-orchestrator 스킬 트리거
  → rn-developer가 화면 구현
  → eas-engineer가 빌드 검증

빌드 요청: "Android APK 빌드해줘"
  → eas-build-deploy 스킬 참조
  → 체크리스트 확인 후 빌드 실행

스토어 등록: "Play Store 등록 도와줘"
  → store-publish 스킬 참조
  → 메타데이터 + 절차 가이드
```

---

*GUARDiA Messenger v1.0.0 | (주)지오정보기술 | 2026-05-31*