11c670f2a0
- 37개 파일 IP → zioinfo.co.kr 치환 (소스/매뉴얼/설정/하네스) - Manager DrConsole/NetworkConsole/CsapConsole 빌드 + /var/www/manager/ 배포 - 테스트: Manager HTTP 200, ITSM 신규 API 7개 전체 200 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
289 lines
7.9 KiB
Markdown
289 lines
7.9 KiB
Markdown
# 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*
|