# tdc114plus 테스트 정책

작성일: 2026-07-02
상태: v1.0 1차 개발 기준 확정

목적: `tdc114plus` Flutter 앱 개발 중 적용할 테스트 기준, 자동화 원칙, 단계별 검증 범위를 정의한다. 본 문서는 `docs/references/ai-testing/ai_testing_policy_draft.md`의 일반 원칙 중 `tdc114plus`에 적용 가능한 부분을 앱/API/보안 중심으로 재해석한 정식 정책이다.

## 1. 적용 범위

본 정책은 아래 영역에 적용한다.

- Flutter 앱 화면, 라우팅, 상태관리
- API client, repository, provider
- API 계약 기반 model, DTO, JSON 변환
- Baron SSO 로그인 연동
- orgFront 직원/조직 데이터 연동
- 전화번호, 개인정보, 즐겨찾기 로컬 저장
- 전화걸기, 문자보내기 등 플랫폼 액션

현재 `tdc114plus`는 LLM/AI 추론 기능을 포함하지 않으므로 아래 항목은 1차 적용 대상에서 제외한다.

- AI 모델 추론 결과 평가
- Evaluator LLM 기반 자동 채점
- multi-engine AI 교차 검증
- 프롬프트 jailbreak/redteam matrix
- PSI 기반 AI 학습 데이터 drift 계산

위 항목은 향후 앱에 실제 AI 기능이 추가될 경우 별도 정책으로 확장한다.

## 2. 기본 검증 게이트

Flutter 앱 코드를 변경한 모든 작업은 아래 검증을 통과해야 한다.

```bash
./scripts/flutter-docker.sh analyze
./scripts/flutter-docker.sh test
```

추가로 Dart 파일을 많이 수정했거나 새 파일을 추가한 경우 formatter를 적용한다.

```bash
docker run --rm -u 0:0 \
  -v /home/ubuntu/workspace/tdc114plus:/workspace \
  -w /workspace/app \
  ghcr.io/cirruslabs/flutter:stable \
  sh -lc "flutter pub get && dart format lib test && chown -R 1000:1000 /workspace/app"
```

검증 실패 상태의 코드는 `main` 브랜치에 반영하지 않는다.

## 3. 테스트 강도 기준

### 3.1 강한 테스트가 필요한 영역

아래 영역은 결정론적 로직으로 보고 단위 테스트를 우선 작성한다.

- API model `fromJson`, `toJson`
- API error parsing
- 전화번호 입력 검증 및 정규화
- 로그인 성공/실패 상태 전이
- 인증 token 저장/삭제
- 직원검색 query/filter 생성
- 가족사/조직 필터 상태
- 즐겨찾기 추가/삭제/조회
- 개인정보 표시/마스킹 정책
- API 실패, 401, 403, 404, timeout 처리

이 영역의 테스트는 통과율 100%를 기준으로 한다.

### 3.2 화면 테스트가 필요한 영역

아래 화면 흐름은 widget test 또는 integration test로 검증한다.

- 앱 실행 후 로그인 화면 표시
- 전화번호 입력 후 로그인 성공/실패 흐름
- 직원목록 진입
- 직원 검색어 입력과 결과 표시
- 가족사 필터 선택/해제
- 조직도 화면 탐색
- 직원 상세 화면 표시
- 전화걸기/문자보내기 액션 노출
- 즐겨찾기 토글

Phase 3에서는 실제 API가 없으므로 mock 데이터와 fake repository를 사용한다.

## 4. 단계별 테스트 전략

### 4.1 Phase 3: Mock 기반 1차 UI

목표:

- API 없이 앱의 핵심 화면 흐름을 검증한다.
- 확정 API 계약과 Dart model이 화면에서 자연스럽게 사용되는지 확인한다.

필수 테스트:

- mock 직원 목록 렌더링
- 검색어 입력 시 목록 필터링
- 가족사 필터 선택 시 목록 필터링
- 직원 상세 진입
- 즐겨찾기 토글 상태 변경
- 로그인 화면에서 직원목록 화면으로 이동

완료 기준:

- `flutter analyze` 통과
- `flutter test` 통과
- 주요 mock 시나리오 widget test 추가

### 4.2 Phase 4: 실제 API 연동

목표:

- Baron SSO와 orgFront 연동 시 계약 불일치를 조기에 발견한다.
- 인증/권한/오류 처리 흐름을 검증한다.

필수 테스트:

- API response parsing
- 로그인 성공/실패
- 미등록 사용자 오류
- session token 저장/삭제
- 직원목록 API 성공/실패
- 조직도 API 성공/실패
- 401/403 발생 시 재로그인 또는 오류 안내
- 네트워크 timeout 대응

완료 기준:

- API client/repository 단위 테스트
- staging 또는 mock server 기반 연동 테스트
- API 계약 문서와 구현 응답 필드 일치 확인

### 4.3 Phase 5: 핵심 액션

목표:

- 전화걸기, 문자보내기, 즐겨찾기 기능을 사용자 흐름 기준으로 검증한다.

필수 테스트:

- 전화번호가 없는 직원의 call/sms 액션 비활성
- 전화번호가 있는 직원의 call/sms URL 생성
- 즐겨찾기 로컬 저장/삭제/복원
- 앱 재실행 후 즐겨찾기 유지

완료 기준:

- 플랫폼 액션 wrapper 테스트
- 즐겨찾기 repository 테스트
- 수동 검증 체크리스트 작성

### 4.4 Phase 6: 빌드/배포 준비

목표:

- Android APK와 최소 iOS 준비 상태를 확인한다.
- 운영 배포 전 보안 민감 영역을 재검토한다.

필수 테스트:

- Android debug APK 빌드
- 앱 시작 smoke test
- 로그인/검색/상세/즐겨찾기 주요 흐름 수동 검증
- token 저장 위치 검토
- 전화번호/이메일/직급 노출 범위 검토

완료 기준:

- APK 빌드 성공
- 주요 수동 검증 체크리스트 통과
- 운영 배포 전 보안 재검토 항목 문서화

## 5. 커버리지 정책

초기 개발 속도를 고려하여 전체 라인 커버리지 수치를 즉시 강제하지 않는다.

단계별 기준:

| 단계 | 기준 |
| --- | --- |
| Phase 3 | 핵심 model과 mock UI 흐름 테스트 확보 |
| Phase 4 | API client/repository/error 처리 테스트 확보 |
| Phase 5 | 즐겨찾기와 연락 액션 테스트 확보 |
| Phase 6 | 주요 기능 회귀 테스트와 수동 검증 체크리스트 확보 |

장기 목표:

- 핵심 도메인/model/repository 라인 커버리지 80% 이상
- 로그인, 개인정보, token 처리 영역 테스트 누락 없음
- 주요 사용자 시나리오 90% 이상 테스트 또는 수동 체크리스트로 관리

## 6. 보안 민감 영역 테스트

아래 항목은 일반 UI 변경보다 높은 기준으로 검증한다.

- 전화번호 로그인
- SSO 미등록 사용자 처리
- session token 저장/삭제
- 로그아웃
- 개인정보 노출 필드
- 직원 검색/상세 조회
- 네트워크 오류와 인증 만료

원칙:

- 미등록 사용자 여부를 과도하게 드러내는 메시지를 피한다.
- 전화번호 원문을 로그에 남기지 않는다.
- token 값을 테스트 fixture나 로그에 실제값으로 남기지 않는다.
- 개인정보 마스킹 정책이 변경되면 model, UI, test를 함께 갱신한다.

## 7. Mock 데이터 정책

Mock 데이터는 확정 API 계약과 같은 field 이름을 사용한다.

필수 mock case:

- 로그인 성공 사용자
- 로그인 실패 사용자
- 직원목록 0건
- 직원목록 다건
- 가족사 2개 이상
- 조직도 parent/child 구조
- 전화번호가 없는 직원
- 이메일이 없는 직원
- 즐겨찾기 등록된 직원

Mock 데이터가 API 계약과 달라지는 경우 API 계약 문서를 먼저 확인하고, 필요한 경우 계약 문서와 model/test를 함께 수정한다.

## 8. 리포트 및 기록

자동화 검증 결과는 커밋 메시지 또는 작업 완료 보고에 아래 형식으로 기록한다.

```text
검증:
- ./scripts/flutter-docker.sh analyze
- ./scripts/flutter-docker.sh test
```

실행하지 못한 검증이 있으면 이유를 함께 기록한다.

## 9. 참고 문서와 우선순위

참고 원문:

- `docs/references/ai-testing/ai_testing_policy_draft.md`
- `docs/references/ai-testing/tdc114plus_test_strategy.md`

본 문서는 위 참고문서보다 `tdc114plus` 개발에 우선 적용한다.

정책 우선순위:

1. `docs/tdc114plus-development-decision-brief-2026-07-01.md`
2. `docs/tdc114plus-work-progress-timetable-2026-07-02.md`
3. `docs/tdc114plus-development-policy-2026-07-02.md`
4. `docs/tdc114plus-testing-policy-2026-07-02.md`
5. `docs/tdc114plus-api-contract-2026-07-02.md`
6. `docs/baron-sso-reference-source-policy-2026-07-02.md`
7. `docs/references/`