모바일 앱 아키텍처

Akan 모바일 앱은 CSR 웹 클라이언트를 Capacitor 네이티브 shell 안에서 열고, 이를 Android와 iOS 앱으로 패키징하는 방식입니다. 화면은 같은 Akan UI 시스템으로 개발하고, Capacitor가 네이티브 프로젝트, 앱 식별 정보, 디바이스 브리지를 제공합니다.

Akan mobile architecture

앱이 여러 basePath를 선언하면 하나의 Akan app에서 여러 모바일 패키지를 릴리즈할 수 있습니다. 예를 들어 고객 앱, 관리자 재고 앱, 현장 작업자 앱은 서로 다른 basePath를 열면서도 같은 service, permission, database rule, generated fetch 호출을 공유할 수 있습니다.

apps/myapp/akan.config.ts

CSR 웹 표면: 앱은 별도 네이티브 UI를 다시 작성하는 것이 아니라 Single Page Application 클라이언트를 엽니다.

Capacitor 패키지: Capacitor는 CSR 클라이언트를 Android/iOS 프로젝트 파일, 앱 메타데이터, 디바이스 API와 함께 감쌉니다.

공유 비즈니스 로직: 웹과 모바일은 같은 Akan service, signal, document, auth, generated client helper를 사용합니다.

CSR 웹 작업

Akan 모바일 작업은 일반 UI 작업에서 시작합니다. page, component, st 상태, fetch 호출, dictionary 문구를 웹과 같은 방식으로 개발합니다. 그 다음 Android나 iOS로 패키징하기 전에 CSR Single Page Application으로 테스트합니다.

Open a CSR page in the browser

csr=true search parameter는 브라우저에서 SPA 내비게이션, 클라이언트 상태, page transition, 모바일과 유사한 동작을 확인할 때 유용합니다. 작은 UI 변경마다 시뮬레이터를 여는 것보다 빠르게 확인할 수 있습니다.

page/store/product/[productId].tsx

transition: 화면이 어떻게 이동하는지 정합니다. 상세 페이지는 보통 stack, 탭 루트는 보통 none을 사용합니다.

safeArea: 콘텐츠가 노치, 홈 인디케이터, 시스템 바와 겹치지 않게 합니다.

topInset / bottomInset: 고정 헤더, 탭바, 키보드, 하단 액션을 위한 공간을 확보합니다.

cache: 목록이나 탭 화면으로 돌아올 때 CSR 페이지 상태를 유지합니다.

Akan CSR 페이지는 pageConfig를 통해 모바일 앱처럼 보이는 페이지 전환 효과를 적용할 수 있습니다. 아래 데모에서 4가지 transition preset을 브라우저 CSR 환경에서 비교한 뒤, 같은 페이지를 네이티브 shell로 패키징할 수 있습니다.

bottomup

모달에 가까운 흐름이나 아래에서 올라오는 화면에 어울립니다.

fade

화면 계층보다 맥락 전환이 중요한 경우 차분하게 화면을 교체합니다.

scale

다음 페이지로 집중해서 진입하는 느낌의 가벼운 확대 모션을 더합니다.

stack

목록이나 상위 화면 위로 상세 화면이 쌓이는 흐름에 적합합니다.

FAQ: 하이브리드 앱이면 네이티브 앱보다 별로인가요?

Akan은 page transition, safe-area 처리, inset 지원, CSR page cache, 모바일 pageConfig로 사용자 경험을 개선합니다. 기능 면에서도 하이브리드 모델이 제약이 되지 않습니다. 필요하면 Capacitor plugin을 통해 카메라, 블루투스, 디바이스, 햅틱, 키보드, safe area 등 네이티브 API를 사용할 수 있습니다.

Android 패키징 작업

CSR 클라이언트를 에뮬레이터/디바이스에서 실행하거나, 네이티브 Android 프로젝트를 검증하거나, Play Store 산출물을 준비할 때 Android 흐름을 사용합니다. Akan은 Capacitor 프로젝트를 준비하고, Android를 sync하고, 메타데이터를 적용한 뒤 APK 또는 AAB 산출물을 빌드합니다.

Run on emulator or device: 화면을 개발하고 live reload를 확인할 때 startAndroid를 사용합니다.

Build native package: Android 프로젝트를 준비하고 릴리즈 번들을 검증할 때 buildAndroid를 사용합니다.

Release for Play Store: local이 아닌 env와 aab 같은 스토어 제출용 assemble type으로 releaseAndroid를 사용합니다.

Android commands

Android 릴리즈에는 안정적인 패키지 식별 정보와 서명이 필요합니다. 릴리즈 후 appId는 안정적으로 유지하고, 네이티브 릴리즈마다 buildNum을 올리며, Play Store 산출물을 위한 release keystore 설정을 준비하세요.

디바이스 API와 Capacitor 상세는 네이티브 브리지 참고 문서로 Capacitor 문서를 확인하세요. Capacitor 문서

iOS 패키징 작업

CSR 클라이언트를 iOS 시뮬레이터/디바이스에서 실행하거나, Xcode 프로젝트를 검증하거나, App Store 산출물을 준비할 때 iOS 흐름을 사용합니다. Akan은 Capacitor 프로젝트를 준비하고, iOS를 sync하고, bundle 메타데이터를 적용한 뒤 네이티브 프로젝트를 열거나 빌드합니다.

Run on simulator or device: 화면을 개발하고 live reload를 확인할 때 startIos를 사용합니다.

Build native project: iOS 프로젝트를 준비하고 Capacitor를 sync하며 네이티브 빌드를 검증할 때 buildIos를 사용합니다.

Release for App Store: local이 아닌 env로 releaseIos를 사용하고, 이후 Apple 도구에서 signing, archive, submission을 마무리합니다.

iOS commands

iOS 릴리즈에는 안정적인 bundle 식별 정보와 Apple signing 설정이 필요합니다. 릴리즈 후 appId는 안정적으로 유지하고, 네이티브 릴리즈마다 buildNum을 올리며, 제출 전에 provisioning, certificate, App Store Connect 설정을 확인하세요.