docs(gift): 운송장 구현 검증을 기록한다

2026-10-08 12:33:15 +09:00
parent f2f4d4d59e
commit fc52c5e5a5
3 changed files with 235 additions and 0 deletions
@@ -0,0 +1,140 @@
+# Phase 6 운송장 등록 진입 검증 리뷰
+
+## 1. 리뷰 정보
+
+| 항목 | 내용 |
+|---|---|
+| 리뷰 대상 | Phase 6 / `P6-T1`, `P6-R1` |
+| 기준 commit 또는 working tree | 미커밋 working tree |
+| 리뷰 일자 | `2026-10-06` |
+| 리뷰어 | Sisyphus, Oracle 기능 리뷰, Oracle 정적 UI 리뷰 |
+| 기준 문서 | `prd.md`, `plan-task.md` |
+| 리뷰 상태 | 수정 검증 완료 |
+
+## 2. 리뷰 목적과 범위
+
+### 목적
+
+- 운송장 등록 화면이 상세를 재조회하고 등록 가능 조건을 fail-closed로 판정하는지 확인한다.
+- 개인정보 경계, guarded navigation, 반응형 너비와 긴 한국어 문구 접근성을 확인한다.
+
+### 포함 범위
+
+- 코드: `SodaLive/Sources/V2/Gift/Tracking/**`, 관련 display policy와 route helper.
+- 테스트: production ViewModel을 직접 컴파일하는 임시 assertion harness.
+- 문서: `TRACK-001`, `TRACK-002`, `P6-T1`.
+- 수동 검증: 소스 기반 상태 전이와 정적 SwiftUI 검토.
+
+### 제외 범위
+
+- `P6-T2` 택배사·운송장 입력 UI와 `P6-T3` 등록 mutation.
+- 로그인·실서버·시뮬레이터 screenshot·VoiceOver 실행 검증.
+
+## 3. 판정 기준
+
+| 심각도 | 기준 |
+|---|---|
+| Blocker | 핵심 흐름 불능, 개인정보 노출 또는 완료 판정 무효 |
+| High | 확정 요구사항·API 계약 위반 또는 주요 회귀 |
+| Medium | 제한된 lifecycle·화면 크기·접근성 조건의 기능 문제 |
+| Low | 비핵심 유지보수성 또는 문서 정합성 문제 |
+
+## 4. 검토한 근거
+
+### 문서와 코드
+
+- 요구사항: `TRACK-001`, `TRACK-002`.
+- 계획: `P6-T1`, `P6-R1`.
+- 코드: `GiftTrackingRegistrationViewModel.swift`, `GiftTrackingRegistrationView.swift`, `GiftDisplayPolicy.swift`, `AppState.swift`, `BaseView.swift`.
+
+### 실행 환경
+
+```text
+OS: macOS
+Xcode SDK: iOS 26.0
+대상: generic/platform=iOS, Debug, CODE_SIGNING_ALLOWED=NO
+Browser/viewport: 해당 없음
+```
+
+### 실행한 검증
+
+| 명령 또는 수동 검증 | 결과 | 핵심 증거 |
+|---|---|---|
+| production ViewModel `swiftc` harness | 성공 | `GREEN assertions: 56` |
+| `xcodebuild` / `SodaLive-dev` | 성공 | `BUILD SUCCEEDED` |
+| `xcodebuild` / `SodaLive` | 성공 | `BUILD SUCCEEDED` |
+| `plutil -lint SodaLive.xcodeproj/project.pbxproj` | 성공 | `OK` |
+| `swiftc -parse` / `git diff --check` | 성공 | exit code 0 |
+| Oracle 기능 재리뷰 | 성공 | `APPROVE`, Blocker/High/Medium 없음 |
+| Oracle 정적 UI 재리뷰 | 성공 | `APPROVED_STATIC`, 차단 항목 없음 |
+| screenshot·VoiceOver·실서버 | 불가 | 인증 가능한 runtime 미확보 |
+
+## 5. 발견 사항 요약
+
+| ID | 심각도 | 상태 | 제목 | 소유 Task | 후속 goal |
+|---|---|---|---|---|---|
+| `REV-P6-001` | Medium | 수정 완료 | 비활성 중 toast 종료 시 상세 복귀 유실 | `P6-R1` | 완료 |
+| `REV-P6-002` | Medium | 수정 완료 | 긴 오류 문구에서 재시도 버튼 세로 overflow 가능 | `P6-R1` | 완료 |
+
+## 6. 발견 사항 상세
+
+### REV-P6-001 — 비활성 중 toast 종료 시 상세 복귀 유실
+
+- **심각도:** Medium
+- **상태:** 수정 완료
+- **관련 요구사항:** `TRACK-001`
+- **소유 Task:** `P6-R1`
+
+**관찰 내용**
+
+비활성 상태에서 toast가 닫히면 `shouldReturnToDetail`이 남아도 기존 `hasAppeared` guard 때문에 재등장 시 callback을 소비하지 못할 수 있었다.
+
+**권장 조치와 결과**
+
+모든 appearance에서 최초 조회 guard보다 먼저 `errorToastDidDismiss()`를 호출하고, ViewModel의 guard와 선행 flag 해제로 exactly-once를 유지했다. 수정 후 기능 재리뷰가 승인됐다.
+
+### REV-P6-002 — 긴 오류 문구에서 재시도 버튼 세로 overflow 가능
+
+- **심각도:** Medium
+- **상태:** 수정 완료
+- **관련 요구사항:** `TRACK-002`
+- **소유 Task:** `P6-R1`
+
+**관찰 내용**
+
+서버 오류 문구는 길이 제한이 없지만 오류 분기가 scroll되지 않아 작은 화면·큰 글자에서 재시도 버튼이 화면 밖으로 밀릴 수 있었다.
+
+**권장 조치와 결과**
+
+오류 메시지와 재시도 버튼을 기존 스타일 그대로 세로 `ScrollView`에 배치했다. 수정 후 정적 UI 재리뷰가 승인됐다.
+
+## 7. 확정 항목의 plan·goal 전환
+
+- 두 확정 항목을 `plan-task.md`의 완료된 회귀 Task `P6-R1`로 기록했다.
+
+## 8. 리뷰 종료 판정
+
+| 판정 항목 | 결과 | 근거 |
+|---|---|---|
+| 리뷰 범위 전체 확인 | 충족 | 코드·문서·검증 결과 대조 |
+| 후보 항목 판정 완료 | 충족 | 두 Medium 항목 수정 완료 |
+| 확정 항목 plan 반영 | 충족 | `P6-R1` |
+| 보류 항목의 담당·재개 조건 기록 | 충족 | 인증 runtime 확보 후 screenshot·VoiceOver·실서버 확인 |
+| 검증 명령과 결과 기록 | 충족 | 56 assertions, 양 스킴 build, lint·parse·diff check |
+
+**최종 결론:** 수정 검증 완료.
+
+**남은 항목:** 로그인·실서버·screenshot·VoiceOver 검증은 최종 Gate에서 수행한다.
+
+## 9. 수정 후 검증 기록
+
+### 1차 수정 검증 — 2026-10-06
+
+- 무엇을: `REV-P6-001`, `REV-P6-002`를 수정했다.
+- 왜: 화면 lifecycle과 큰 글자에서 상세 복귀·재시도 접근성을 유지하기 위해서다.
+- 어떻게:
+  - production-source harness — 56 assertions 성공.
+  - `SodaLive-dev`, `SodaLive` generic iOS Debug build — 성공.
+  - Oracle 기능 재리뷰 — `APPROVE`.
+  - Oracle 정적 UI 재리뷰 — `APPROVED_STATIC`.
+- 남은 항목: 인증 runtime 기반 실제 화면·VoiceOver·실서버 검증.