Expand Flutter app scaffold

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

@@ -0,0 +1,192 @@
+# 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 프로젝트 생성
+
+예상 명령:
+
+```bash
+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 진행 |
+
+## 7. 다음 승인 요청 예정
+
+다음 단계는 후속 개발 범위 확정 후 별도 승인으로 진행한다.
+
+승인 후 결정할 작업:
+
+1. Baron Safe WebView 실제 URL과 환경 분리 방식을 확정한다.
+2. Firebase/FCM Android 설정과 iOS APNs 설정 방식을 확정한다.
+3. native bridge와 backend API 연동 순서를 확정한다.