Add tdc114plus testing policy

2026-07-02 13:14:13 +09:00
parent 6d05f36dcc
commit 0a427da636
3 changed files with 276 additions and 8 deletions
@@ -0,0 +1,259 @@
+# 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/`