baron-safe-app/docs/flutter-project-expansion-timetable-2026-06-30.md

Baron Safe Flutter 프로젝트 확장 작업 타임테이블

작성일: 2026-06-30

1. 목적

본 문서는 현재 baron-safe-app repository의 초기 scaffold를 정식 Flutter 기반 Android/iOS 하이브리드 앱 프로젝트로 확장하기 위한 단계별 작업 계획과 진행 기록을 남기기 위한 문서이다.

현재 repository는 정책 문서, 기본 디렉터리, Docker/VS Code/Gitea Actions 설정, Flutter 앱 자리 구조를 갖춘 초기 scaffold 상태이다. 아직 현재 환경의 PATH에 flutter 명령이 확인되지 않았으므로, 실제 flutter create로 생성되는 Android/iOS 네이티브 프로젝트 확장은 Flutter SDK 사용 가능 여부 확인 후 진행한다.

2. 진행 원칙

• 각 단계는 사용자 승인 후 진행한다.
• 진행 관리는 본 문서의 목차와 단계 번호를 기준으로 한다.
• 단계별 결과는 본 문서의 진행 기록에 남긴다.
• 문제 발생 후 해결된 단순 시행착오, 임시 오류, 중간 실패 로그는 저장하지 않는다.
• 문서에는 최종 결정사항, 현재 단계, 완료 결과, 미해결 이슈만 간단히 남긴다.
• 대규모 파일 생성 또는 덮어쓰기 전에는 변경 범위를 먼저 확인한다.
• 기존 userfront repository는 수정하지 않는다.
• baron-safe-app repository 안에서만 작업한다.
• Android/iOS 정식 프로젝트 생성은 임시 디렉터리에서 먼저 생성한 뒤 필요한 파일을 병합하는 방식을 우선한다.
• 검증 가능한 단계마다 git status, 필요 시 flutter analyze, flutter test를 수행한다.
• 커밋과 push는 사용자 승인 후 진행한다.

3. 현재 기준 상태

항목	상태
Gitea repository	kevin/baron-safe-app 생성 완료
로컬 경로	/home/ubuntu/workspace/baron-safe-app
기본 scaffold	생성 완료
정책 문서 복사	완료
최초 커밋	5f7b9a7 Initial Baron Safe app scaffold
정책 문서 커밋	684cf87 Add Baron Safe planning documents
Flutter SDK	현재 PATH에서 미확인
정식 Android/iOS Flutter 프로젝트	아직 미생성

4. 단계별 타임테이블

단계	작업명	예상 작업	승인 필요	산출물	완료 기준
0단계	사전 상태 확인	현재 repo 상태, branch, remote, Flutter/Dart/FVM 설치 여부 확인	예	환경 확인 결과	상태 확인 결과를 문서에 기록
1단계	Flutter SDK 준비 방식 결정	Flutter SDK 설치 여부, 기존 SDK 경로, FVM 사용 여부 결정	예	SDK 준비 방식	flutter --version 실행 가능
2단계	정식 프로젝트 생성 방식 확정	flutter create . 직접 실행 또는 임시 디렉터리 생성 후 병합 방식 결정	예	생성 방식 결정	덮어쓰기 위험 파일 목록 확인
3단계	임시 Flutter 프로젝트 생성	/tmp 또는 작업 외부 임시 경로에 Flutter 프로젝트 생성	예	임시 Flutter 프로젝트	Android/iOS 기본 파일 생성 확인
4단계	기존 scaffold와 병합	android/, ios/, linux/mac/windows 필요 여부, pubspec.yaml, lib/ 병합	예	정식 Flutter 앱 구조	기존 정책/문서/설정 보존
5단계	의존성 정리	WebView, Riverpod, GoRouter, local_auth, secure storage, Firebase Messaging 의존성 정리	예	정리된 pubspec.yaml	flutter pub get 성공
6단계	기본 앱 실행 구조 정리	main.dart, 앱 이름, 기본 theme, WebView 진입 화면 skeleton 구성	예	기본 실행 앱	앱 entrypoint 빌드 가능
7단계	WebView 컨테이너 skeleton	Baron Safe route 로드용 WebView 화면과 오류/로딩 UI 구성	예	WebView 화면 skeleton	analyze 통과
8단계	Native bridge skeleton	bridge command enum/interface, device info, biometric placeholder 구성	예	bridge skeleton	테스트 가능한 인터페이스
9단계	Push skeleton	FCM/APNs 초기화 placeholder, push token 등록 service skeleton 구성	예	push service skeleton	플랫폼별 TODO 명확화
10단계	Secure storage skeleton	device id, 민감 설정 저장 abstraction 구성	예	secure storage service	단위 테스트 가능
11단계	검증	flutter pub get, flutter analyze, flutter test 실행	예	검증 결과	실패 시 원인 기록
12단계	커밋 및 push	변경 파일 확인, 커밋 메시지 작성, Gitea push	예	Git commit	원격 main 반영

5. 세부 진행 계획

5.1 0단계: 사전 상태 확인

확인 항목:

• git status --short
• git branch --show-current
• git remote -v
• which flutter
• which dart
• which fvm
• flutter --version
• dart --version

주의:

• Flutter가 설치되어 있지 않거나 PATH에 없으면 설치 또는 SDK 경로 설정 방식을 먼저 결정한다.
• 이 단계에서는 파일을 수정하지 않는다.

5.2 1단계: Flutter SDK 준비 방식 결정

선택지:

안	방식	장점	단점
1안	시스템 Flutter SDK 사용	단순함	버전 고정이 약함
2안	FVM 사용	프로젝트별 Flutter 버전 고정 가능	FVM 설치 필요
3안	기존 userfront와 동일 SDK 사용	Baron SSO 개발 환경과 일관성 높음	기존 SDK 위치 확인 필요

권장:

• 기존 userfront 개발에 사용하던 Flutter SDK 또는 FVM 방식이 있으면 그 방식을 따른다.
• 없다면 FVM 기반 버전 고정을 검토한다.

5.3 2단계: 정식 프로젝트 생성 방식 확정

권장 방식:

1. 임시 디렉터리에 flutter create를 실행한다.
2. 생성된 Android/iOS 파일을 검토한다.
3. 기존 scaffold와 충돌하지 않는 범위에서 병합한다.

직접 app/에서 flutter create .를 실행하는 방식은 빠르지만, 기존 pubspec.yaml, lib/main.dart, 설정 파일이 덮어써질 수 있으므로 신중히 사용한다.

5.4 3단계: 임시 Flutter 프로젝트 생성

예상 명령:

flutter create --project-name baron_safe_app --org kr.hmac.baron.safe /tmp/baron-safe-app-create

확인 항목:

• android/
• ios/
• lib/main.dart
• pubspec.yaml
• test/widget_test.dart

5.5 4단계: 기존 scaffold와 병합

병합 원칙:

• docs/, docker/, scripts/, .vscode/, .gitea/는 보존한다.
• app/android/, app/ios/는 Flutter 생성 결과를 반영한다.
• app/pubspec.yaml은 기존 Baron Safe 의존성을 유지하면서 Flutter 생성값과 병합한다.
• app/lib/main.dart는 Baron Safe scaffold 내용을 유지하고 필요한 import만 정리한다.

5.6 5단계: 의존성 정리

초기 의존성 후보:

• flutter_riverpod
• go_router
• http
• webview_flutter
• local_auth
• flutter_secure_storage
• firebase_core
• firebase_messaging
• logging

주의:

• Firebase 설정 파일은 운영 key가 포함될 수 있으므로 repository 반영 여부를 별도 결정한다.
• APNs key, FCM server key, 앱 서명키는 repository에 넣지 않는다.

5.7 6단계 이후: 기능 skeleton 구성

초기 skeleton 범위:

• 앱 entrypoint
• WebView route
• 세션 목록 placeholder
• 연결 앱 placeholder
• native bridge interface
• biometric prompt placeholder
• push token service placeholder
• secure storage service placeholder

실제 API 연동과 네이티브 구현은 별도 이슈 또는 후속 단계로 분리한다.

6. 진행 기록

진행 기록은 목차의 단계 번호를 기준으로 관리한다. 해결된 임시 오류나 중간 시행착오는 기록하지 않고, 최종 결과와 다음 결정이 필요한 사항만 남긴다.

일시	단계	진행 내용	결과	비고
2026-06-30	준비	Gitea kevin/baron-safe-app repository 생성 확인	완료	빈 repository 접근 확인
2026-06-30	준비	초기 scaffold 생성 및 push	완료	commit 5f7b9a7
2026-06-30	준비	Baron Safe 관련 정책/참고 문서 복사 및 push	완료	commit 684cf87
2026-06-30	계획	Flutter 정식 프로젝트 확장 타임테이블 문서 작성	완료	본 문서
2026-06-30	0단계	사전 상태 확인	완료	branch main, remote origin, 미커밋 문서 1건 확인. flutter, dart, fvm은 현재 PATH에서 command not found
2026-06-30	1단계	Flutter SDK 준비 방식 확정	완료	userfront와 동일한 ghcr.io/cirruslabs/flutter:3.38.0 Docker 기반 Flutter 사용. 컨테이너에서 Flutter 3.38.0, Dart 3.10.0 실행 확인
2026-06-30	2단계	정식 프로젝트 생성 방식 확정	완료	임시 디렉터리에 flutter create --platforms=android,ios 실행 후 app/에 병합하는 방식으로 확정. 주요 충돌 대상은 app/pubspec.yaml, app/lib/main.dart, .gitkeep 파일
2026-06-30	3단계	임시 Flutter 프로젝트 생성	완료	/tmp/baron-safe-app-create-20260630-154742에 Android/iOS 전용 Flutter 프로젝트 생성 완료. 병합 대상은 android/, ios/, .metadata, analysis_options.yaml, pubspec.lock, 필요 시 test 파일
2026-06-30	4단계	기존 scaffold와 병합	완료	app/android, app/ios, app/.metadata, app/analysis_options.yaml 병합 완료. 기존 app/pubspec.yaml, app/lib/main.dart는 보존. 빈 디렉터리용 .gitkeep 제거
2026-06-30	5단계	의존성 정리	완료	app/pubspec.yaml SDK 제약을 Flutter 3.38.0 Docker 이미지 기준으로 정리하고 초기 의존성 확인. flutter pub get 성공 및 app/pubspec.lock 생성 완료
2026-06-30	6단계	기본 앱 실행 구조 정리	완료	go_router 기반 앱 entrypoint, 기본 Material 3 theme, 홈 화면 placeholder 구성 완료. Docker Flutter 컨테이너에서 dart format lib, flutter analyze 통과
2026-06-30	7단계	WebView 컨테이너 skeleton	완료	Baron Safe WebView route, 로딩 progress, 오류 상태, reload 동작 skeleton 구성 완료. WebView URL은 BARON_SAFE_WEB_URL dart-define으로 주입 가능. Docker Flutter 컨테이너에서 dart format lib, flutter analyze 통과
2026-06-30	8단계	Native bridge skeleton	완료	정책 문서의 허용 command 기준으로 bridge enum, request/response 모델, device info 및 biometric placeholder service 구성 완료. Docker Flutter 컨테이너에서 dart format lib test, flutter analyze, bridge 단위 테스트 통과
2026-06-30	9단계	Push skeleton	완료	FCM/APNs 초기화 placeholder, push token provider/registrar service, bridge registerPushToken 연결, 플랫폼별 TODO 문서 구성 완료. Docker Flutter 컨테이너에서 dart format lib test, flutter analyze, bridge/push 단위 테스트 통과
2026-06-30	10단계	Secure storage skeleton	완료	device id, app lock, biometric 설정 저장 abstraction과 flutter_secure_storage adapter, memory test store 구성 완료. Docker Flutter 컨테이너에서 dart format lib test, flutter analyze, secure storage 단위 테스트 통과
2026-06-30	11단계	검증	완료	Docker Flutter 컨테이너에서 flutter pub get, flutter analyze, 전체 flutter test 통과. 전체 테스트 10건 성공
2026-06-30	12단계	커밋 및 push	완료	Flutter Android/iOS 프로젝트 병합 및 앱 skeleton 변경분을 커밋하고 Gitea origin/main push 진행
2026-06-30	13단계	WebView URL 및 실행 환경 분리	완료	BARON_SAFE_WEB_URL dart-define 기반 WebView URL 주입 방식과 local/staging/production 예시, 검증 방법을 docs/runtime-config.md에 정리
2026-06-30	14단계	WebView 보안 정책 보강	완료	허용 host 기반 WebView navigation policy와 차단 UI를 구성하고 URL 허용/차단 단위 테스트 추가
2026-06-30	15단계	Bridge 메시지 연결	완료	WebView BaronSafeBridge JavaScript channel, bridge JSON request/response envelope, command parsing 및 허용 command 검증 테스트 추가
2026-06-30	16단계	Device registration skeleton	완료	device id 생성/저장 service, device register API client interface, push token 포함 등록 request skeleton 및 단위 테스트 추가
2026-06-30	17단계	Session API skeleton	완료	세션 목록/상세 DTO, session client/repository interface, mock session client 및 목록/상세 단위 테스트 추가
2026-06-30	18단계	Session 화면 skeleton	완료	최근 세션 목록 route, 세션 상세 route, mock repository 기반 세션 목록/상세 화면과 홈 진입 타일 구성
2026-06-30	19단계	Session block skeleton	완료	세션 차단 request/response/result 모델, 생체 인증 placeholder 기반 block workflow, bridge blockSession service 주입 경로, 상세 화면 차단 버튼 연결 및 관련 단위 테스트 추가. Docker Flutter 컨테이너에서 dart format lib test, flutter analyze, 관련 테스트 15건 통과

7. 다음 승인 요청 예정

다음 단계는 20단계: Linked apps skeleton이다.

승인 후 결정할 작업:

1. 연결 앱 목록/차단 DTO와 service interface를 정의한다.
2. mock 기반 연결 앱 목록/상세 또는 차단 진입 화면 placeholder를 구성한다.
3. 연결 앱 목록/차단 workflow 단위 테스트를 추가한다.

8. 후속 개발 단계

정식 Flutter Android/iOS scaffold와 앱 skeleton이 원격 main에 반영된 이후의 후속 개발 단계이다. 각 단계는 기존 원칙과 동일하게 사용자 승인 후 진행하며, 검증 가능한 단위마다 Docker Flutter 컨테이너에서 flutter analyze와 필요한 테스트를 수행한다.

단계	작업명	주요 작업	산출물	완료 기준
13단계	WebView URL 및 실행 환경 분리	BARON_SAFE_WEB_URL 사용법 문서화, local/staging/production URL 관리 방식 정리	실행 환경 설정 문서	환경별 WebView URL 주입 방식 확인
14단계	WebView 보안 정책 보강	허용 origin 목록, navigation delegate 차단 정책, 외부 링크 처리 기준 정리	WebView policy 코드/문서	허용되지 않은 URL 이동 차단 테스트 가능
15단계	Bridge 메시지 연결	WebView JavaScript channel, bridge request parsing, response envelope 구성	WebView-native bridge 연결 skeleton	허용 command만 처리되는 테스트 통과
16단계	Device registration skeleton	device id 생성/저장, device register API client interface 구성	기기 등록 service skeleton	device id 저장 및 등록 요청 테스트 통과
17단계	Session API skeleton	세션 목록/상세 DTO, API client interface, mock repository 구성	session service skeleton	mock 기반 목록/상세 테스트 통과
18단계	Session 화면 skeleton	최근 로그인/세션 목록, 상세, 차단 진입 UI 구성	Flutter session 화면	analyze 통과 및 화면 route 동작
19단계	Session block skeleton	생체 인증 placeholder와 세션 차단 service 연결	block workflow skeleton	생체 인증 후 차단 요청 흐름 테스트 통과
20단계	Linked apps skeleton	연결 앱 목록/차단 DTO, service, 화면 placeholder 구성	linked apps feature skeleton	mock 기반 목록/차단 테스트 통과
21단계	Firebase/FCM Android 준비	Android Firebase 설정 파일 반영 정책, Gradle 설정, 알림 권한 확인	Android push 준비 변경	secret 제외 여부 확인 및 analyze 통과
22단계	iOS APNs 준비	bundle id, entitlement, APNs/FCM 설정 방식 문서화 및 iOS 설정 skeleton	iOS push 준비 변경	secret 제외 여부 확인 및 analyze 통과
23단계	앱 실행/빌드 검증	Docker Flutter 기반 Android debug build 가능성 확인, 필요 시 iOS 설정 정합성 점검	빌드 검증 결과	Android debug build 또는 명확한 차단 사유 기록
24단계	후속 커밋 및 push	13-23단계 변경 목록 확인, 검증, 커밋, Gitea push	Git commit	원격 main 반영