Preveil Frontend

사용자가 갤러리에서 선택한 사진을 안전점검하고, 보호 옵션을 적용한 뒤 저장/게시 흐름으로 이어가는 React Native Expo 기반 모바일 앱 프론트엔드.

컴포넌트	역할
app (Expo / React Native)	모바일 UI, 갤러리 권한, 사진 선택, 안전점검/처리 결과 화면
web preview (React Native Web)	Vercel 배포용 모바일 너비 웹 미리보기
apiClient	FastAPI 서버 공통 fetch 클라이언트
modelService	현재 mock 이미지 처리, 추후 백엔드 업로드/폴링 연동 지점
ProcessingContext	처리 결과, 기록, 보호 옵션 전역 상태

• 백엔드 서버: http://13.124.131.167:8000
• 헬스체크: GET /api/v1/health/ai
• 배포 방식: Vercel 정적 웹 배포 (expo export --platform web)

아키텍처

[Expo React Native App]
        |
        | ImagePicker / 앱 갤러리
        v
[Gallery] -> [RiskReview] -> [ProtectionOptions] -> [Processing]
                                                        |
                                                        | REST API 예정
                                                        v
                                             [FastAPI Backend :8000]
                                                        |
                                                        v
                                                [AI Processing Server]
                                                        |
                                                        v
[History] <- [ProcessingContext] <- [Results] <- processed image result
        |
        v
[InstagramPublish] / 저장 / 재게시 업데이트

현재 플로우는 UI 프로토타입과 mock 모델 처리까지 구현되어 있습니다. 실제 백엔드 연결 시 src/services/modelService.ts를 업로드/상태 폴링/결과 수신 로직으로 교체하면 됩니다.

개발 환경

요구사항: Node.js, npm, Expo CLI는 npx expo 또는 npm script로 실행.

npm install
npm run typecheck
npm run export:web

로컬 실행

cp .env.example .env
npm run start

Expo 터미널에서 실행 대상을 선택하거나 아래 명령어를 직접 사용합니다.

대상	명령어
Expo 개발 서버	npm run start
iOS 시뮬레이터	npm run ios
Android 에뮬레이터	npm run android
Web 미리보기	npm run web
Web 정적 빌드	npm run export:web
TypeScript 검사	npm run typecheck

환경 변수

EXPO_PUBLIC_API_BASE_URL=http://13.124.131.167:8000

환경 변수 파일은 .env.example을 복사해서 사용합니다.

cp .env.example .env

Vercel 배포 시 같은 값을 Project Environment Variables에 등록합니다.

백엔드 연동 / API 사용 명령어

BASE를 환경에 맞게 설정합니다. 현재 공유받은 메인 서버는 http://13.124.131.167:8000입니다.

BASE=http://13.124.131.167:8000

# AI 서버 프록시 헬스체크
curl -s $BASE/api/v1/health/ai

프론트 코드의 API 진입점:

파일	용도
src/services/apiClient.ts	EXPO_PUBLIC_API_BASE_URL 기반 공통 요청 함수
src/services/modelService.ts	현재 mock 처리. 실제 이미지 처리 API 연결 대상
src/types/media.ts	프론트 미디어/옵션/결과 타입
src/context/ProcessingContext.tsx	처리 결과와 기록 상태 저장
src/screens/ProcessingScreen.tsx	처리 진행 UI
src/screens/ResultsScreen.tsx	처리 결과 UI

권장 백엔드 연결 흐름:

1. 앱에서 GalleryAsset[] + ProtectionOptions 준비
2. 이미지 업로드 요청
3. task_id 또는 job_id 수신
4. 상태 폴링
5. 완료 시 결과 이미지 URL 수신
6. ProcessedAsset[]로 매핑 후 Results 화면 표시

현재 프론트 보호 옵션 타입:

type ProtectionOptions = {
  blurBuildingNames: boolean;
  blurLicensePlates: boolean;
  removePersonNames: boolean;
  aiCleanup: boolean;
};

현재 프론트 결과 타입:

type ProcessedAsset = {
  id: string;
  sourceId: string;
  originalUri: string;
  resultUri: string;
  processedAt: string;
  appliedOptions: ProtectionOptions;
  defenseModelVersion?: string;
  template?: 'building-number';
};

화면 플로우

화면	역할
Home	첫 화면, 기기 갤러리 사진 가져오기, 기존 게시물 관리 진입
Gallery	앱 갤러리, 여러 사진 선택, 안전점검 시작
RiskReview	사진별 위험 요소 확인
ProtectionOptions	건물명/번호판/민감정보/AI 편집 보정 옵션 선택
Processing	모델 처리 로딩 화면
Results	Before/After 결과 확인, 저장/게시 진입
InstagramPublish	게시 프롬프트 입력과 게시 완료 흐름
History	기존 처리 기록 선택 후 업데이트
HistoryUpdateComplete	기존 게시물 업데이트 완료 화면
Settings	다크모드, 개인정보, 백엔드, 게시 설정

Vercel 배포

vercel.json에 빌드 설정과 SPA rewrite가 포함되어 있습니다.

설정	값
Framework Preset	Other
Install Command	npm install
Build Command	npm run vercel-build
Output Directory	dist

수동 빌드:

npm run vercel-build

데스크탑 웹에서도 앱은 모바일 화면 폭으로 보이도록 구성되어 있습니다.

권한 / 플랫폼 설정

app.json에 사진 접근 권한 문구가 포함되어 있습니다.

플랫폼	설정
iOS	NSPhotoLibraryUsageDescription, NSPhotoLibraryAddUsageDescription
Android	READ_MEDIA_IMAGES, READ_EXTERNAL_STORAGE, WRITE_EXTERNAL_STORAGE
Expo plugin	expo-image-picker 사진 접근 문구

EAS 배포는 현재 사용하지 않으므로 eas.json과 EAS script는 제거되어 있습니다.

CI/CD

현재 프론트 저장소에는 별도 GitHub Actions 워크플로우가 없습니다. PR 또는 push 전 최소 검증은 아래 두 명령어입니다.

npm run typecheck
npm run export:web

Vercel GitHub 연동 시 main 브랜치 push 후 자동 배포되도록 설정할 수 있습니다.

디렉토리 구조

├── assets/             # 로고 SVG 시안
├── src/
│   ├── components/     # 공용 UI 컴포넌트
│   ├── context/        # 처리 결과와 기록 상태
│   ├── navigation/     # 탭/화면 라우팅
│   ├── screens/        # 화면 단위 컴포넌트
│   ├── services/       # API 클라이언트, mock 모델 처리, 저장 서비스
│   ├── theme/          # 색상, 간격, 타이포그래피 토큰
│   ├── types/          # 미디어/처리 타입
│   └── utils/          # 보호 옵션 라벨 유틸
├── app.json            # Expo 앱 설정/권한
├── package.json        # 실행 script와 의존성
└── vercel.json         # Vercel 웹 배포 설정

보안 / 연동 주의사항

• 사진 원본 URI, 결과 URL, presigned URL은 로그에 남기지 않는 것을 권장합니다.
• 실제 API 연결 시 timeout, 실패 상태, 재시도 UX를 ProcessingScreen에 반영해야 합니다.
• 백엔드 API 스키마가 확정되면 src/services/modelService.ts와 src/types/media.ts를 함께 갱신합니다.
• Instagram API 실제 게시 연동 시 OAuth token과 사용자 입력 프롬프트는 별도 보안 저장소/서버 흐름으로 관리해야 합니다.