guardia-docs/34_GUARDiA_Messenger_개발_배포_가이드.md

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. 필수 설치

# 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. 로컬 개발 서버

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회)

cd C:\GUARDiA\app

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

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

3-2. 빌드 명령어

# 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 생성

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

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