arasystem/flutter

ARA SYSTEM 앱 (Flutter)

ARA SYSTEM 그룹웨어의 모바일 앱이다. 식별자 kr.it.arasystem.app · 이름 "ARA SYSTEM", 안드로이드 먼저(Play 내부 테스트).

• 구조 · 구현 규칙: .claude/skills/flutter/SKILL.md
• 앱 로그인(앱 전용 토큰 경로 — 서버는 아직 없다): 계약 docs/mail/api-contract.md 1절 "앱 로그인"
• 화면 기준: docs/design/app/README.md (보드 사본 docs/design/webmail/App1*.dc.html)

이 문서는 개발 PC · 배포에서 알아 둘 사실만 적는다.

개발 실행

cd flutter
cp .env.example .env      # 없으면 analyze 가 asset 경고를 낸다
flutter pub get
flutter analyze           # 0건이어야 한다
flutter test
flutter run               # 에뮬레이터 · USB 실기기

• API 주소는 .env 의 API_URL 하나다(루트 env 를 따르지 않는다). .env 는 앱 안에 그대로 들어가므로 비밀은 넣지 않는다.
  • Android 에뮬레이터: http://10.0.2.2:3000/api — 에뮬레이터의 10.0.2.2 가 PC 의 127.0.0.1 이다.
  • USB 실기기: adb reverse tcp:3000 tcp:3000 뒤 http://localhost:3000/api. 개발 백엔드는 127.0.0.1 에만 열려 있어 같은 와이파이의 휴대폰은 닿지 않는다(docker 스킬 "호스트 포트").
• 개발 PC 의 안드로이드 도구: Android Studio 의 JDK 21 · SDK 36 · NDK 28.2(Flutter 기본)로 빌드된다. SDK 라이선스 동의(flutter doctor --android-licenses)는 사람이 직접 한다.

Flutter 판

3.41.9 stable (Dart 3.11.5) 으로 고정이다 — 개발 PC 와 CI 가 같은 판이어야 한다. 판을 바꿀 때 함께 고치는 곳:

• .github/workflows/ci-flutter.yml 의 flutter-version (CI 는 flutter pub get --enforce-lockfile — lock 그대로)
• pubspec.yaml 의 environment.sdk, intl(flutter_localizations 가 SDK 마다 정확한 판으로 고정한다 — 새 SDK 의 packages/flutter_localizations/pubspec.yaml 값으로)
• .claude/skills/docker/SKILL.md 이미지 버전 표의 "Flutter SDK" 줄 · flutter 스킬 "Flutter 판" · 이 문서
• 개발 PC 의 Flutter 는 다른 프로젝트도 함께 쓴다 — 올리기는 사용자가 정한다.

빌드

flutter build apk --debug          # 2~3분 · 약 160MB (build/ 는 git 이 무시한다)
flutter build appbundle --release  # Play 에 올리는 꼴 — 아래 서명 키가 먼저다

• release 매니페스트(android/app/src/main/AndroidManifest.xml)에 INTERNET 권한이 있어야 네트워크가 된다(flutter create 기본은 debug · profile 에만 둔다).
• release 빌드는 android/app/google-services.json 이 없으면 멈춘다(아래 "새 메일 알림") — 배포 판이 새 메일 알림 없이 나가지 않게. debug 빌드는 없어도 된다. Gradle 이 실행할 작업 그래프를 본다 — flutter build apk · appbundle 뿐 아니라 ./gradlew assemble · bundle · build(모든 변형) · 줄여 쓴 이름(aR)도 멈춘다. debug · release 를 다른 Firebase 프로젝트로 나누려면(app/src/debug · app/src/release 에 따로) build.gradle.kts 의 조건도 함께 바꾼다(지금은 app/google-services.json 하나만 본다).

새 메일 알림 (Firebase Cloud Messaging)

• 의존성은 firebase_core · firebase_messaging 둘뿐이다(Analytics · 로컬 알림 · 권한 플러그인은 넣지 않는다). 알림은 FCM 이 그리는 알림 메시지이고, 앱은 채널 · 지우기 · 휴대폰 설정 열기만 한다(MainActivity.kt 의 NewMailNotifications.kt — 채널 kr.it.arasystem.app/notifications).
• google-services.json: Firebase 콘솔에서 안드로이드 앱(패키지 kr.it.arasystem.app)을 만들고 받은 파일을 flutter/android/app/google-services.json 에 둔다. 커밋하지 않는다(android/.gitignore). 키가 들어 있지만 비밀은 아니다(앱 안에 그대로 들어간다) — 그래도 저장소 밖에서 나눈다. 파일이 있을 때만 Gradle 이 com.google.gms.google-services(4.4.4)를 건다.
  • 파일 없이 만든 debug 판은 Firebase 를 띄우지 못해 설정 › 새 메일 알림이 "이 휴대폰에서는 … 받을 수 없습니다"로 보인다(나머지는 그대로 된다). 서버 쪽 발송 키(서비스 계정)는 백엔드 설정이다.
• 매니페스트: 알림 권한(POST_NOTIFICATIONS), 기본 채널 new_mail(이름 · 설명은 res/values/strings.xml), 작은 아이콘 @drawable/ic_stat_ara, 강조색 @color/notification_accent, FCM 자동 초기화 끔(firebase_messaging_auto_init_enabled — 로그인한 뒤에만 등록한다), 광고 ID 권한은 빼 둔다(tools:node="remove" — 어느 라이브러리도 넣지 않지만 들어오지 않게).
• 등록은 FID 로 한다(FirebaseMessaging.register() · onRegistered) — 토큰 · FID 를 로그 · 디버그 출력에 남기지 않는다. 서버 경로 · 규칙은 계약 1절 "앱 새 메일 알림 · 앱 설정".

앱 아이콘 · 알림 아이콘

보드 App1Push ⑨ · ⑪(2026-11-07 확정). 그림은 docs/brand/logo_arasystem_white.png 의 ARA 마크만 잘라 만들었다(만드는 스크립트는 저장소에 두지 않는다 — 의존성을 늘리지 않으려고). 다시 만들 때의 치수:

• 앱 아이콘(적응형 — 안드로이드 8 이상): res/mipmap-anydpi-v26/ic_launcher.xml · ic_launcher_round.xml = 배경색 @color/ic_launcher_background(#0B3640) + 앞면 @mipmap/ic_launcher_foreground + monochrome(안드로이드 13 테마 아이콘 — 같은 앞면 그림). 앞면은 108dp 칸(투명)에 흰 마크 폭 46.5dp(보이는 72dp 의 0.646 — 잘리지 않는 가운데 66dp 안)를 가운데에. mdpi 108px · hdpi 162 · xhdpi 216 · xxhdpi 324 · xxxhdpi 432.
• 옛 아이콘(안드로이드 7 — minSdk 24 · 25): mipmap-*/ic_launcher.png(48dp 칸에 44dp 둥근 네모 · 모서리 30%) · ic_launcher_round.png(동그라미) — 같은 남색 · 마크 비율. 48 · 72 · 96 · 144 · 192px.
• 알림 작은 아이콘 ic_stat_ara: res/drawable-*/ic_stat_ara.png — 24dp 칸(투명)에 흰 마크 폭 22dp, 알파만 쓴다(휴대폰이 색을 칠한다). 24 · 36 · 48 · 72 · 96px, mdpi · hdpi 는 획을 반 픽셀 굵게. 봉투로 바꾸려면 이 다섯 장만 같은 이름으로 바꾼다 — 매니페스트의 기본 아이콘(default_notification_icon)이 이 이름 하나를 가리킨다. 서버 메시지는 아이콘 · 색을 싣지 않는다 — 휴대폰이 매니페스트의 기본값(아이콘 · default_notification_color · 채널 new_mail)으로 그린다.

배포 준비

• release 서명 키는 저장소 밖의 비밀이다. 지금 build.gradle.kts 의 release 는 debug 키로 서명한다 — 배포 전에 업로드 키(keystore)를 만들고 key.properties 로 읽게 한다. keystore · key.properties 는 커밋하지 않고(android/.gitignore 가 무시한다) 비밀번호 관리자에 둔다(잃으면 같은 앱으로 업데이트를 올릴 수 없다 — Play 앱 서명을 켜 두면 업로드 키는 다시 받을 수 있다).
• Play 데이터 보안 신고: 새 메일 알림 때문에 Firebase 설치 ID(FID)를 서버에 보낸다 — Play Console 의 데이터 보안 양식에 "기기 또는 기타 ID"(수집 · 앱 기능, 공유하지 않음 · 전송 중 암호화)로 적는다. 메일 내용 · 주소는 알림에 싣지 않는다(글은 "새 메일 N통"뿐). 광고 ID 는 쓰지 않는다(매니페스트에서 뺐다 — tools:node="remove").
• 안드로이드: Play 내부 테스트 — Play Console 계정(1회 25달러, 법인 계정은 D-U-N-S 번호), 테스터 100명까지 메일 목록으로 · 심사 없이 · 업데이트가 저절로. 식별자(kr.it.arasystem.app)는 올린 뒤 바꿀 수 없다. APK 를 직접 나눠 주는 길도 있지만 Google 의 "인증된 개발자만 설치" 정책(2026-09 부터 나라별)이 한국에 언제 걸리는지 확인이 필요하다.
• iOS: 맥 · Apple 개발자 계정이 먼저다 — 빌드 · 서명 · 시뮬레이터가 모두 맥(Xcode)에서만 되고, 배포 · 푸시(APNs 키)는 Apple Developer Program(연 99달러, 법인은 D-U-N-S)이 든다. 내부 배포는 TestFlight 내부 테스터(빌드 90일 만료). 맥에서 처음 빌드할 때 ios/Runner/Info.plist 에 CFBundleLocalizations(ko)가 있는지 확인한다 — 없으면 복사 · 붙여 넣기 같은 시스템 글이 한국어로 나오지 않는다. bundle id 는 kr.it.arasystem.app 으로 맞춰 두었다(맥에서 확인 전).

보안 메모

• 토큰: 리프레시 토큰만 flutter_secure_storage(Android Keystore · iOS Keychain), 액세스 토큰은 메모리. 비밀번호 · 토큰을 로그에 남기지 않는다(LogInterceptor 를 넣지 않는다).
• Android 백업을 껐다(android:allowBackup="false" · res/xml/data_extraction_rules.xml) — 보안 저장소의 값은 이 기기의 Keystore 키로 암호화되어 다른 기기로 복원되면 읽지 못하고, 첫 실행 표시까지 복원되면 남은 토큰 지우기가 돌지 않는다.
• iOS Keychain 은 앱을 지워도 남는다 — 일반 저장소(shared_preferences)의 첫 실행 표시가 없으면 앱을 띄우기 전에 보안 저장소를 모두 지운다(core/storage/token_store.dart 의 prepare).
• 만료는 기기 시계로 보지 않는다 — 응답의 Date(서버 시각)로 남은 시간을 잰다.
• 받은 메일 본문(WebView): 앱이 한 번 더 정화한 문서(features/mail/domain/mail_html.dart — 허용 목록 · CSP default-src 'none'; img-src data:)만 넣고, 스크립트 · 파일 · content 주소 접근을 끄고, 주 틀의 탐색은 모두 막는다(링크는 바깥 브라우저 · mailto 는 쓰기 화면). 아래 틀(iframe)의 탐색은 안드로이드가 판정에 넘기지 않는다 — 아래 틀은 정화(iframe 을 내용째 버림)와 CSP(default-src 'none' — frame-src)가 막는다. 외부 이미지는 앱이 Dio(Bearer)로 받아 data: 로 넣는다 — 토큰이 WebView 에 가지 않는다. 문서에 싣는 그림 글은 같은 그림이 여러 번 나오면 나온 만큼 세어 10MB 에서 멈춘다.
• 받은 첨부: 앱 임시 폴더(cacheDir)의 downloads/ 에 받고, 다른 앱으로 열 때는 FileProvider(${applicationId}.downloads — 그 폴더만)의 주소와 읽기 권한 1회로 ACTION_VIEW 한다(MainActivity.kt 의 파일 채널). 앱을 띄울 때(지난 실행이 남긴 것) · 메일을 보는 직원이 바뀔 때 모두 지운다. 파일 이름은 경로 · 제어 · 방향 제어 글자를 지우고 줄인다(core/files/file_names.dart). 열 형식은 정리한 이름의 확장자에서 먼저 정하고(보낸 쪽 형식은 확장자를 모를 때만), 웹 문서 · SVG · 설치 파일 · 인증서 · 키 묶음은 받지 않고 알린다(core/files/file_types.dart). 고르는 창(createChooser)으로 열지 않는다 — 직원이 고른 브라우저가 스크립트를 돌린다.

나중에 넣을 때 주의

• build_runner(freezed · json_serializable · riverpod_generator): 같은 폴더의 lib/core/api/error_lexicon.g.dart(백엔드 레지스트리에서 만든 사전 — 직접 고치지 않는다)를 build_runner 가 자기 출력으로 보고 지울 수 있다. 넣을 때는 build.yaml 의 generate_for 를 모델 폴더로 좁히고, 처음 한 번 돌린 뒤 사전이 그대로인지(git diff) 확인한다.
• 첨부 받기(스트림 · 바이트 응답): 실패 응답의 본문은 ResponseInterceptor.onError 가 64KB 까지 읽어 UTF-8 · JSON 으로 풀고 표준 실패의 error.code 를 꺼낸다 (decodeRawErrorBody — 그 전에는 HTTP 상태로만 정해 FILE_007 · FILE_008 같은 코드를 잃었다). 성공 본문은 풀지 않고 그대로 넘긴다(시험이 지킨다). 받는 도중 끊기거나 조각 사이 받기 한도(receiveTimeout — Dio 가 스트림에 싣는다)를 넘기면 응답이 이미 인터셉터를 지나 아무도 알리지 않으므로 부르는 쪽이 SYS_001 로 알린다(DownloadInterrupted).

라이선스

글꼴 Pretendard 1.3.9(SIL OFL 1.1 — assets/licenses/pretendard-ofl.txt)는 앱의 [설정] → [앱 정보] → [오픈소스 라이선스]에 보인다.