# 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 진행 |
| 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` 반영 |
