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 서명 키는 저장소 밖의 비밀이다. 지금 build.gradle.kts 의 release 는 debug 키로 서명한다 — 배포 전에 업로드 키(keystore)를 만들고 key.properties 로 읽게 한다. keystore · key.properties 는 커밋하지 않고(android/.gitignore 가 무시한다) 비밀번호 관리자에 둔다(잃으면 같은 앱으로 업데이트를 올릴 수 없다 — Play 앱 서명을 켜 두면 업로드 키는 다시 받을 수 있다).
• 안드로이드: 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)는 앱의 [설정] → [앱 정보] → [오픈소스 라이선스]에 보인다.