tdc114plus/docs/dev_env_tdc114plus_setup_plan_2026-07-02.md

# tdc114plus 개발환경 구성 작업순서

작성일: 2026-07-02

목적: 신규 앱 `tdc114plus` 개발환경 구성을 시작하기 전, Baron SSO 저장소에 임시로 보관할 작업순서를 정리한다. 추후 `tdc114plus` 저장소의 Flutter 앱 골격이 갖춰지면 본 문서를 해당 저장소의 `docs/` 경로로 복사 이관한다.

## 1. 저장소 확인

Gitea 저장소:

- https://gitea.hmac.kr/kevin/tdc114plus

확인 결과:

- `git ls-remote https://gitea.hmac.kr/kevin/tdc114plus.git` 접근은 성공했다.
- 출력 ref가 없으므로 현재 저장소는 아직 커밋/브랜치가 없는 빈 저장소이거나, 기본 브랜치가 아직 생성되지 않은 상태로 판단한다.

## 2. 기본 추진 방향

`tdc114plus`는 Baron Safe에서 검토했던 Flutter 기반 모바일 앱 구성 방식을 참고해 개발환경을 구성한다.

1차 개발은 아래 범위에 집중한다.

- Baron SSO 전화번호 로그인
- Baron SSO 등록 사용자만 앱 사용 허용
- Baron SSO `orgFront` 기반 개인/조직 정보 연계
- 직원검색
- 전화번호검색
- 가족사 필터
- 조직도
- 직원목록
- 전화걸기
- 문자보내기
- 즐겨찾기

1차 보류 기능은 아래와 같다.

- 공지사항
- 전자결재
- 수신전화식별
- 수신팝업

## 3. 단계별 개발환경 구성 순서

### 3.1 저장소 초기화

1. `tdc114plus` 저장소를 clone한다.
2. 기본 브랜치를 `main` 또는 `develop`으로 생성한다.
3. `README.md`, `.gitignore`, `docs/`, `scripts/` 기본 구조를 생성한다.
4. Baron SSO 저장소에 임시 보관한 신규 앱 결정 문서와 본 문서를 `tdc114plus/docs/`로 복사 이관한다.

### 3.2 Flutter 앱 스캐폴딩

1. Flutter 프로젝트를 생성한다.
2. Android/iOS 타겟을 활성화한다.
3. 앱 패키지명을 확정한다.
   - 예: `kr.co.baron.tdc114plus`
4. 앱 이름, 앱 아이콘, splash, 기본 권한 설정을 정리한다.
5. Baron Safe 때 검토한 방식처럼 Flutter 기반 Android/iOS 공통 앱 구조로 시작한다.

### 3.3 기술스택 기본 구성

| 영역 | 권장 |
| --- | --- |
| Framework | Flutter |
| Language | Dart |
| 상태관리 | `flutter_riverpod` |
| Routing | `go_router` |
| HTTP | 기존 방식이면 `http`, 확장성 필요 시 `dio` 검토 |
| 로컬 설정 | `shared_preferences` |
| 보안 저장 | 후속 단계에서 `flutter_secure_storage` 검토 |
| 다국어 | `easy_localization` |
| 로깅 | `logging` 또는 `logger` |
| 전화/문자 | `url_launcher` |
| 즐겨찾기 저장 | 1차는 로컬 저장, 후속 서버 동기화 검토 |

### 3.4 환경 분리

1. `dev`, `staging`, `prod` API endpoint를 분리한다.
2. Baron SSO backend URL을 환경별로 설정한다.
3. orgFront API URL 또는 Baron SSO backend proxy 경로를 설정한다.
4. Flutter `--dart-define` 또는 환경 설정 파일 방식 중 하나를 선택한다.
5. Android/iOS별 네트워크 보안 설정을 정리한다.

### 3.5 앱 기본 구조

권장 디렉터리 예시는 다음과 같다.

```text
lib/
  core/
    config/
    router/
    network/
    storage/
    logging/
  features/
    auth/
    directory/
    organization/
    favorites/
    profile/
  shared/
    widgets/
    models/
```

각 영역의 역할은 다음과 같이 둔다.

| 경로 | 역할 |
| --- | --- |
| `core/config` | 앱 환경, API endpoint, 빌드 설정 |
| `core/router` | `go_router` 기반 화면 라우팅 |
| `core/network` | Baron SSO 및 orgFront API client |
| `core/storage` | 로컬 설정, 즐겨찾기, 보안 저장 추상화 |
| `core/logging` | 앱 로그 정책 |
| `features/auth` | Baron SSO 전화번호 로그인 |
| `features/directory` | 직원검색, 전화번호검색, 직원목록, 직원 상세 |
| `features/organization` | 가족사 필터, 조직도 |
| `features/favorites` | 즐겨찾기 |
| `features/profile` | 내 정보, 향후 설정 화면 |
| `shared/widgets` | 공통 UI 컴포넌트 |
| `shared/models` | 공통 모델 |

### 3.6 1차 기능 개발 순서

1. Baron SSO 전화번호 로그인 화면
2. 로그인 성공/실패 처리
3. orgFront 기반 직원 목록 API 연동
4. 직원검색
5. 전화번호검색
6. 가족사 필터
7. 조직도
8. 직원 상세
9. 전화걸기/문자보내기
10. 즐겨찾기

### 3.7 검증 및 배포 준비

1. `flutter analyze` 기준을 정리한다.
2. 기본 widget/unit test 실행 방식을 정리한다.
3. Android debug APK 빌드를 확인한다.
4. iOS 빌드는 macOS 환경에서 별도 확인한다.
5. `README.md`에 개발 실행 방법을 기록한다.
6. Gitea Actions 또는 수동 빌드 절차를 정리한다.
7. 개발 중간 산출물 기준 APK 배포 방식을 결정한다.

### 3.8 Android emulator / WSL ADB 연동 기준

Windows Android Studio emulator를 WSL 또는 Docker 기반 Flutter CLI에서 사용할 때는 별도 ADB 연동 정책을 따른다.

- 정책 문서: `docs/troubleshooting/policy_android_studio_wsl_adb_2026-07-03.md`
- 실행 기록: `docs/troubleshooting/android-studio-wsl-adb-timetable-260703.md`
- 통합테스트 시나리오: `docs/scenario_android_emulator_device_integration_test_2026-07-03.md`

핵심 기준:

- `adb -a -P 5037 nodaemon server`는 1차 시도만 한다.
- `10048` bind 실패가 재현되면 즉시 Windows `portproxy` 방식으로 전환한다.
- Android emulator에서 host API는 `127.0.0.1`이 아니라 `10.0.2.2`를 사용한다.
- Docker Flutter에서 Windows ADB를 사용할 때는 `ADB_SERVER_SOCKET=tcp:<WINDOWS_HOST_IP>:5037`을 명시한다.

## 4. 작업 원칙

- 1차 개발은 전화번호부/조직도 기본 기능 완성에 집중한다.
- 공지사항, 전자결재, 수신전화식별, 수신팝업은 골격 단계에서 제외한다.
- 기존 Baron SSO backend와 orgFront 데이터를 우선 활용한다.
- 앱 자체 회원가입 기능은 만들지 않는다.
- Baron SSO 등록 인원 확인 실패 시 앱 사용을 허용하지 않는다.
- 기기 등록, 푸시, 자동 로그인, 공지/전자결재 연동은 후속 단계에서 별도 검토한다.

## 5. 추후 이관 항목

`tdc114plus` 저장소 골격이 갖춰지면 아래 문서를 복사 이관한다.

- `docs/guide_tdc114plus_development_decision_brief_2026-07-01.md`
- `docs/dev_env_tdc114plus_setup_plan_2026-07-02.md`

이관 후 Baron SSO 저장소의 문서는 회의 및 초기 검토 기록으로 보존한다.