diff --git a/docs/GOVERNANCE_INDEX.md b/docs/GOVERNANCE_INDEX.md index f777a60..b799fd5 100644 --- a/docs/GOVERNANCE_INDEX.md +++ b/docs/GOVERNANCE_INDEX.md @@ -1,8 +1,40 @@ # Governance Index -This repository-local index maps durable Core task IDs to their owning parent -issues so implementation children can be checked against the intended roadmap. +이 문서는 JamIssue Web Front 레포에서 현재 진행 중인 작업 축과 책임 범위를 빠르게 찾기 위한 색인입니다. -| Core | Parent Issue | Responsibility | Keywords | Misroute Examples | +## 현재 기준 + +| Scope | Parent Issue | 책임 범위 | 구현 브랜치 원칙 | 완료 근거 | | --- | --- | --- | --- | --- | -| `TSK-012-00` | https://github.com/STH-1-Class-One-Group/JamIssue/issues/380 | JamIssue app-transition UI/UX redesign for the Web Front. | uiux; app shell; safe area; bottom sheet; five tab; event tab; design tokens; qa matrix | Backend API contract changes; DB schema migration; OAuth flow changes; unrelated tourism contract work | +| `TSK-012` | [#404](https://github.com/STH-1-Class-One-Group/JamIssue/issues/404) | 2차 UI/UX 구현 명세 적용. 헤더 슬롯, 서브내비 flow, 행사 탭 정리, KTO 지도 레이어, CSS offset 정리, 문서 추적성 | child issue별 목적형 브랜치 | PR 링크, merge SHA, CI 링크, QA 문서, release candidate 문서 | +| `TSK-009` | [#323](https://github.com/STH-1-Class-One-Group/JamIssue/issues/323) | UI/UX 기대 동작 추적과 TypeScript 테스트 커버리지 | coverage slice 단위 브랜치 | coverage summary, 테스트 명령, CI 링크 | + +## TSK-012 Child Issues + +| Child | Branch | 상태 | 핵심 증거 | +| --- | --- | --- | --- | +| [#405](https://github.com/STH-1-Class-One-Group/JamIssue/issues/405) | `second-uiux-audit-baseline` | 완료 | PR #412, merge `dc0c5027` | +| [#406](https://github.com/STH-1-Class-One-Group/JamIssue/issues/406) | `app-header-slot-integration` | 완료 | PR #413, merge `edac1e31` | +| [#407](https://github.com/STH-1-Class-One-Group/JamIssue/issues/407) | `app-shell-subnav-grid-layout` | 완료 | PR #414, merge `bcd1284` | +| [#408](https://github.com/STH-1-Class-One-Group/JamIssue/issues/408) | `event-tab-festival-only-cleanup` | 완료 | PR #415, merge `3ee8f77` | +| [#409](https://github.com/STH-1-Class-One-Group/JamIssue/issues/409) | `kto-tourism-map-layer-infosheet` | 완료 | PR #416, merge `b89b7fc` | +| [#410](https://github.com/STH-1-Class-One-Group/JamIssue/issues/410) | `app-shell-css-offset-cleanup` | 완료 | PR #417, merge `fa67c88` | +| [#411](https://github.com/STH-1-Class-One-Group/JamIssue/issues/411) | `second-uiux-traceability-docs` | 진행 중 | repo docs, Wiki, QA matrix, release candidate note | + +## Scope Guard + +TSK-012는 Web Front UI/UX 구현 축입니다. 다음 항목은 TSK-012에 섞지 않습니다. + +| 제외 대상 | 처리 기준 | +| --- | --- | +| Backend provider contract 변경 | 별도 backend/admin 레포 또는 합의된 contract issue에서 처리 | +| DB schema 변경 | 별도 migration issue에서 처리 | +| OAuth 성공 경로 변경 | auth 전용 issue에서 처리 | +| 사용자-facing copy 스타일 정리 | 명시 요청이 있을 때만 별도 issue에서 처리 | +| KTO/OpenAPI 직접 브라우저 호출 | 금지. Web Front는 consumer contract만 사용 | + +## 문서 기준 + +- Repo 문서: [UI/UX QA 매트릭스](ui-ux-qa-matrix.md), [UI/UX 기준선](ui-ux-redesign-baseline.md), [UI/UX 추적성](ui-ux-redesign-traceability.md) +- Wiki 문서: `Home`, `UI-UX-QA-Matrix`, `UI-UX-Redesign-Traceability`, `Release-Notes-1.3.3` +- Release candidate: [JamIssue 1.3.3 후보](release-candidate-1.3.3.md) diff --git a/docs/release-candidate-1.3.3.md b/docs/release-candidate-1.3.3.md new file mode 100644 index 0000000..ab34a70 --- /dev/null +++ b/docs/release-candidate-1.3.3.md @@ -0,0 +1,68 @@ +# JamIssue 1.3.3 후보 + +상태: 후보 +기준 Scope: `TSK-012` +Parent Issue: [#404](https://github.com/STH-1-Class-One-Group/JamIssue/issues/404) + +## 요약 + +`1.3.3` 후보는 2차 UI/UX 구현 명세를 Web Front에 반영한 UI/UX 구조 정리 릴리즈입니다. 주요 변경은 AppHeader 슬롯 통합, AppShell subNav flow, EventTab festival-only 정리, KTO 지도 정보 레이어, legacy CSS offset 제거, 문서 추적성 보강입니다. + +## 사용자 관점 변화 + +- 상단 액션과 뒤로가기가 헤더 내부에 정리되어 화면 위 floating 요소가 줄어듭니다. +- 지도 필터가 지도 위에 겹치는 overlay가 아니라 앱 셸의 보조 내비게이션 흐름에 배치됩니다. +- 행사 탭은 행사 정보에 집중하고, 관광장소 정보는 지도에서 선택적으로 켤 수 있습니다. +- KTO 정보성 관광장소는 스탬프/후기 장소와 구분된 정보 시트로 표시됩니다. + +## 운영/보안/품질 변화 + +- Web Front는 KTO consumer contract만 소유하며, provider contract나 admin import 흐름은 변경하지 않습니다. +- API path, response shape, DB schema, OAuth 성공 경로는 변경하지 않았습니다. +- UI/UX 기대 동작은 `UIUX-###` ID와 E2E/unit 테스트로 추적합니다. +- legacy CSS offset과 무효화된 override를 줄여 레이아웃 회귀 가능성을 낮췄습니다. + +## 포함 PR / 커밋 + +| PR | 내용 | Merge SHA | +| --- | --- | --- | +| [#412](https://github.com/STH-1-Class-One-Group/JamIssue/pull/412) | 2차 UI/UX 기준선 audit | `dc0c5027` | +| [#413](https://github.com/STH-1-Class-One-Group/JamIssue/pull/413) | AppHeader slot 통합 | `edac1e31` | +| [#414](https://github.com/STH-1-Class-One-Group/JamIssue/pull/414) | AppShell subNav grid flow | `bcd1284` | +| [#415](https://github.com/STH-1-Class-One-Group/JamIssue/pull/415) | EventTab festival-only cleanup | `3ee8f77` | +| [#416](https://github.com/STH-1-Class-One-Group/JamIssue/pull/416) | KTO tourism map layer와 InfoSheet | `b89b7fc` | +| [#417](https://github.com/STH-1-Class-One-Group/JamIssue/pull/417) | App shell CSS offset cleanup | `fa67c88` | +| TBD | TSK-012 traceability docs | TBD | + +## 검증 근거 + +공통 검증 기준: + +```powershell +npm.cmd run check:numeric-literals +npm.cmd run lint +npm.cmd run typecheck +npm.cmd run test:unit +npm.cmd run test:integration +npm.cmd run test:regression +npm.cmd run test:e2e +npm.cmd run build +git diff --check +``` + +각 PR의 실제 실행 결과와 원격 CI 링크는 child issue 완료 댓글과 PR checks에 기록합니다. + +## 제외 범위 + +- Backend provider contract 변경 +- DB schema 변경 +- OAuth 성공 경로 변경 +- KTO/OpenAPI 브라우저 직접 호출 +- 사용자-facing copy 스타일 정리 + +## 관련 문서 + +- [UI/UX 구현 기준선](ui-ux-redesign-baseline.md) +- [UI/UX 추적성](ui-ux-redesign-traceability.md) +- [UI/UX QA 매트릭스](ui-ux-qa-matrix.md) +- [Governance Index](GOVERNANCE_INDEX.md) diff --git a/docs/ui-ux-qa-matrix.md b/docs/ui-ux-qa-matrix.md index ecf61c6..a738ff8 100644 --- a/docs/ui-ux-qa-matrix.md +++ b/docs/ui-ux-qa-matrix.md @@ -1,56 +1,54 @@ # UI/UX 기대 동작 QA 매트릭스 -## 목적 - -화면이 사용자가 기대하는 방식으로 동작하는지 `UIUX-###` ID로 추적한다. - -UI/UX 관련 이슈와 PR은 영향을 받는 기대 동작 ID, 재현 경로, 자동 테스트 여부, 수동 QA 여부, 관련 PR/issue를 기록한다. 근거 없이 UI/UX 이슈를 닫지 않는다. +이 문서는 Web Front에서 사용자가 기대하는 화면 동작을 `UIUX-###` ID로 추적합니다. UI/UX 관련 PR은 영향을 받는 ID, 자동 테스트, 수동 QA 여부, 관련 issue/PR을 남겨야 합니다. ## 운영 규칙 | 항목 | 기준 | | --- | --- | | ID 형식 | `UIUX-###` | -| 단위 | 사용자가 인지하는 화면 동작 하나 | +| 단위 | 사용자가 체감하는 화면 동작 하나 | | 자동화 기준 | unit, integration, regression, E2E 중 하나로 재현 가능하면 자동 테스트에 연결 | -| 수동 QA 기준 | iPhone Safari/WebView처럼 자동화가 불완전한 항목은 수동 확인 근거 기록 | +| 수동 QA 기준 | 실제 iPhone Safari/WebView처럼 자동화가 불완전한 항목은 기기, 브라우저, 일시, 확인자를 기록 | | 완료 기준 | 자동 테스트 또는 수동 QA 근거 없이 close 금지 | ## 기대 동작 ID -| ID | 영역 | 기대 동작 | 재현 경로 | 자동화 상태 | 수동 QA | -| --- | --- | --- | --- | --- | --- | -| `UIUX-001` | 전역 앱 셸 | 모바일 기준 폭에서 하단 탭은 화면 하단에 고정되고 주요 패널과 겹치지 않는다. | 앱 진입 -> 탭 전환 | Playwright: `test/e2e/app-shell.spec.ts` | 필요 | -| `UIUX-002` | 탭 전환 | `지도` 외 탭에서는 지도 배경이 보이지 않고 각 탭이 독립 화면처럼 보인다. | 지도 -> 행사/피드/코스/마이 | Playwright: `test/e2e/app-shell.spec.ts` | 선택 | -| `UIUX-003` | 지도 레이어 | 상단 카드, 필터, 지도, 드로워, 알림/피드백 진입점, Naver attribution이 서로 잘못 올라오지 않는다. | 지도 -> 알림/피드백 열기 | Playwright + 수동 QA 필요 | 필요 | -| `UIUX-004` | 장소 시트 | 장소/행사 선택 후 시트가 `hidden / peek / half / full` 상태 계약을 유지한다. | 지도 -> 마커 선택 -> 시트 전환 | `test/unit/map-sheet-state.test.ts`, Playwright | 필요 | -| `UIUX-005` | 장소 정보 | 장소 시트는 장소명, 구, 요약, 카테고리, 방문/스탬프 상태, 후기 작성 가능 여부, 후기 목록을 보여준다. | 지도 -> 장소 선택 | Playwright: `test/e2e/critical-ui-flow.spec.ts` | 선택 | -| `UIUX-006` | 행사 정보 | 행사 탭은 독립 탭으로 접근되고 지도 배경과 섞이지 않는다. | 행사 탭 진입 | Playwright: `test/e2e/app-shell.spec.ts` | 선택 | -| `UIUX-007` | 스탬프 버튼 | 로그아웃, 반경 밖, 반경 안, 오늘 완료 상태가 각각 기대 상태로 표시된다. | 지도 -> 장소 선택 -> 스탬프 버튼 | service/E2E 추가 필요 | 필요 | -| `UIUX-008` | 후기 작성 진입 | 후기는 당일 해당 장소 스탬프가 있을 때만 열리고, GPS 진입만으로는 열리지 않는다. | 스탬프 전/후 -> 후기 작성 | Playwright: `test/e2e/critical-ui-flow.spec.ts` | 필요 | -| `UIUX-009` | 모바일 키보드 | 리뷰 작성 textarea focus 시 키보드가 떠도 하단 탭과 드로워가 화면 중간으로 떠오르지 않는다. | 지도 -> 장소 -> 스탬프 완료 -> 후기 textarea focus | unit/integration + Playwright | 필수 | -| `UIUX-010` | 피드 탭 | 피드 탭은 실제 방문 후기 소비 중심이며 댓글, 좋아요, 장소 이동 CTA가 동작한다. | 피드 -> 댓글/좋아요/장소 이동 | Playwright: `test/e2e/critical-ui-flow.spec.ts` | 선택 | -| `UIUX-011` | 코스 탭 | 코스 탭은 정렬, 추천 코스 카드, 코스 상세 진입을 제공한다. | 코스 -> 정렬 -> 카드 선택 | Playwright: `test/e2e/critical-ui-flow.spec.ts` | 선택 | -| `UIUX-012` | 마이 탭 | 로그인 전에는 로그인 유도만, 로그인 후에는 개인 통계와 내 활동이 표시된다. | 마이 -> 로그인 전/후 | Playwright: `test/e2e/critical-ui-flow.spec.ts` | 선택 | -| `UIUX-013` | 5탭 IA | 하단 탭은 `지도 / 행사 / 피드 / 코스 / 마이` 5개를 유지하고 비지도 탭에서 지도 stage를 숨긴다. | 탭 전환 | Playwright: `test/e2e/app-shell.spec.ts` | 선택 | -| `UIUX-014` | 탭 콘텐츠 surface | 행사/피드/코스/마이 콘텐츠는 앱 셸 content slot 안에서 접근 가능하다. | 행사/피드/코스/마이 탭 전환 | Playwright: `test/e2e/app-shell.spec.ts` | 선택 | -| `UIUX-015` | 앱 헤더 | 앱 헤더는 safe area 아래에 있고 주요 액션은 앱 셸 슬롯 안에서 관리된다. | 앱 진입 -> 탭 전환 | Playwright: `test/e2e/app-shell.spec.ts` | 필요 | -| `UIUX-016` | 서브 내비게이션 | 카테고리/필터 칩은 Sub Navigation 성격으로 콘텐츠와 시각적으로 분리된다. | 지도/행사 -> 필터 확인 | 추가 E2E 필요 | 필요 | -| `UIUX-017` | Peek 시트 | Peek 시트는 탭바 위 간격을 두고 floating card처럼 보인다. | 지도 -> 마커 선택 | Playwright: `test/e2e/critical-ui-flow.spec.ts` | 필수 | -| `UIUX-018` | Half/Full 시트 | Half/Full 시트에서는 탭바가 숨고 시트와 탭바가 동시에 겹쳐 보이지 않는다. | Peek -> Full 전환 | Playwright: `test/e2e/critical-ui-flow.spec.ts` | 필수 | -| `UIUX-019` | 내 위치 FAB | 내 위치 찾기 버튼은 지도 조작과 시트 상태를 방해하지 않는다. | 지도 -> 마커 선택 | 추가 E2E 필요 | 필요 | -| `UIUX-020` | 디자인 토큰 | shell, spacing, sheet, tabbar 값은 token/config 기준으로 관리된다. | UI PR diff 검토 | `npm.cmd run check:numeric-literals` | 필요 | +| ID | 영역 | 기대 동작 | 자동 테스트 | 수동 QA | +| --- | --- | --- | --- | --- | +| `UIUX-001` | 앱 셸 | 모바일 기준 헤더, 콘텐츠, 하단 탭이 겹치지 않고 shell flow에 배치된다. | `test/e2e/app-shell.spec.ts` | 필요 | +| `UIUX-002` | 탭 전환 | 비지도 탭에서는 지도 배경이 노출되지 않고 각 탭이 독립 화면처럼 보인다. | `test/e2e/app-shell.spec.ts` | 선택 | +| `UIUX-003` | 지도 레이아웃 | 헤더, 서브내비, 지도, 시트, Naver attribution이 서로 겹치지 않는다. | `test/e2e/app-shell.spec.ts` | 필요 | +| `UIUX-004` | 장소 시트 | 장소/정보 시트는 `hidden / peek / half / full` 상태 계약을 유지한다. | `test/unit/map-sheet-state.test.ts` | 필요 | +| `UIUX-005` | 장소 정보 | 장소 시트에는 장소명, 카테고리, 스탬프/후기 상태, 후기 목록이 표시된다. | `test/e2e/critical-ui-flow.spec.ts` | 선택 | +| `UIUX-006` | 행사 탭 | 행사 탭은 행사 콘텐츠만 표시하고 관광장소 세그먼트를 노출하지 않는다. | `test/e2e/event-tab.spec.ts` | 선택 | +| `UIUX-007` | 스탬프 | 로그인, 반경, 완료 상태별 스탬프 버튼 상태가 올바르게 표시된다. | E2E 보강 대상 | 필요 | +| `UIUX-008` | 후기 작성 | 후기 작성은 해당 장소 스탬프 완료 상태에서만 진입된다. | `test/e2e/critical-ui-flow.spec.ts` | 필요 | +| `UIUX-009` | 모바일 키보드 | 리뷰 작성 textarea focus 시 키보드가 떠도 하단 탭과 드로워가 화면 중간으로 떠오르지 않는다. | unit/integration + E2E | 필수 | +| `UIUX-010` | 피드 | 피드 탭에서 댓글, 좋아요, 장소 이동 CTA가 동작한다. | `test/e2e/critical-ui-flow.spec.ts` | 선택 | +| `UIUX-011` | 코스 | 코스 탭에서 정렬, 추천 코스 카드, 상세 진입이 동작한다. | `test/e2e/critical-ui-flow.spec.ts` | 선택 | +| `UIUX-012` | 마이 | 로그인 전/후 마이 탭 상태가 구분되고 내 활동으로 진입할 수 있다. | `test/e2e/critical-ui-flow.spec.ts` | 선택 | +| `UIUX-013` | 5탭 IA | 하단 탭은 `지도 / 행사 / 피드 / 코스 / 마이` 5개를 유지한다. | `test/e2e/app-shell.spec.ts` | 선택 | +| `UIUX-014` | 탭 콘텐츠 | 행사/피드/코스/마이 콘텐츠는 공통 content slot 안에서 접근 가능하다. | `test/e2e/app-shell.spec.ts` | 선택 | +| `UIUX-015` | 앱 헤더 | 뒤로가기, 설정, 알림, 피드백 액션은 absolute utility slot이 아니라 header slot에서 관리된다. | `test/e2e/app-shell.spec.ts` | 필요 | +| `UIUX-016` | 서브내비 | 지도 필터와 탭별 보조 조작은 content 위 absolute overlay가 아니라 subNav flow에 배치된다. | `test/e2e/app-shell.spec.ts` | 필요 | +| `UIUX-017` | Peek 시트 | Peek 시트는 하단 탭과 간격을 두고 floating card처럼 보인다. | `test/e2e/critical-ui-flow.spec.ts` | 필수 | +| `UIUX-018` | Half/Full 시트 | Half/Full 시트에서는 하단 탭이 숨고 시트와 탭바가 동시에 겹쳐 보이지 않는다. | `test/e2e/critical-ui-flow.spec.ts` | 필수 | +| `UIUX-019` | 지도 FAB | 현재 위치 버튼과 지도 보조 액션은 지도 조작과 시트 상태를 방해하지 않는다. | E2E 보강 대상 | 필요 | +| `UIUX-020` | 디자인 토큰 | shell, spacing, sheet, tabbar 값은 token/config 기준으로 관리된다. | `npm.cmd run check:numeric-literals` | 필요 | +| `UIUX-021` | KTO 지도 레이어 | KTO 정보성 레이어는 기본 OFF이며, 사용자가 켤 때만 관광장소를 불러온다. | `test/e2e/tourism-map-layer.spec.ts` | 필요 | +| `UIUX-022` | KTO 정보 시트 | `isCurated: false` 관광장소 선택 시 스탬프/후기 액션 없는 정보 시트가 열린다. | `test/e2e/tourism-map-layer.spec.ts` | 필요 | ## TSK-012 구현 근거 -| Child issue | PR | Merge SHA | 핵심 근거 | +| Child issue | PR | Merge SHA | 고정된 기대 동작 | | --- | --- | --- | --- | -| #381 | #396 | `c7f4c71` | 기준선 문서와 UIUX ID 체계 | -| #382 | #397 | `8d85a67` | 앱 셸 safe-area layout | -| #383 | #398 | `ed5b817` | `hidden / peek / half / full` sheet state | -| #384 | #399 | `e3f8481` | 5탭 IA regression | -| #385 | #400 | `7ed1af2` | 탭 content surface E2E | -| #386 | #401 | `90f6cec` | layout token gate와 `check:numeric-literals` | +| [#405](https://github.com/STH-1-Class-One-Group/JamIssue/issues/405) | [#412](https://github.com/STH-1-Class-One-Group/JamIssue/pull/412) | `dc0c5027` | 2차 UI/UX 기준선과 코드 증거 | +| [#406](https://github.com/STH-1-Class-One-Group/JamIssue/issues/406) | [#413](https://github.com/STH-1-Class-One-Group/JamIssue/pull/413) | `edac1e31` | `UIUX-015` header slot | +| [#407](https://github.com/STH-1-Class-One-Group/JamIssue/issues/407) | [#414](https://github.com/STH-1-Class-One-Group/JamIssue/pull/414) | `bcd1284` | `UIUX-016` subNav flow | +| [#408](https://github.com/STH-1-Class-One-Group/JamIssue/issues/408) | [#415](https://github.com/STH-1-Class-One-Group/JamIssue/pull/415) | `3ee8f77` | `UIUX-006` 행사 탭 festival-only | +| [#409](https://github.com/STH-1-Class-One-Group/JamIssue/issues/409) | [#416](https://github.com/STH-1-Class-One-Group/JamIssue/pull/416) | `b89b7fc` | `UIUX-021`, `UIUX-022` KTO 지도 레이어 | +| [#410](https://github.com/STH-1-Class-One-Group/JamIssue/issues/410) | [#417](https://github.com/STH-1-Class-One-Group/JamIssue/pull/417) | `fa67c88` | legacy absolute/fixed offset 제거 | ## 이슈 템플릿 @@ -84,15 +82,9 @@ UI/UX 관련 이슈와 PR은 영향을 받는 기대 동작 ID, 재현 경로, - CI: ``` -## PR 체크 기준 - -- UI/UX 관련 PR은 영향을 받는 `UIUX-###` ID를 PR 본문에 기록한다. -- 자동 테스트가 있으면 테스트 파일과 명령을 기록한다. -- 자동화가 불완전한 항목은 수동 기기, 브라우저, 일시, 확인자를 기록한다. -- 기대 동작이 새로 생기면 이 문서에 ID를 먼저 추가한다. - ## 관련 문서 - [화면 설계 기준](screen-spec.md) -- [앱 전환 UI/UX 개편 기준선](ui-ux-redesign-baseline.md) +- [UI/UX 개편 기준선](ui-ux-redesign-baseline.md) +- [UI/UX 추적성](ui-ux-redesign-traceability.md) - [테스트 커버리지 운영 기준](testing-coverage.md) diff --git a/docs/ui-ux-redesign-baseline.md b/docs/ui-ux-redesign-baseline.md index 752faa7..1a49007 100644 --- a/docs/ui-ux-redesign-baseline.md +++ b/docs/ui-ux-redesign-baseline.md @@ -1,67 +1,54 @@ -# JamIssue 앱 전환 UI/UX 개편 기준선 +# JamIssue 2차 UI/UX 구현 기준선 -기준일: 2026-06-12 +기준일: 2026-06-13 Scope-ID: `TSK-012` -Parent Issue: https://github.com/STH-1-Class-One-Group/JamIssue/issues/380 +Parent Issue: [#404](https://github.com/STH-1-Class-One-Group/JamIssue/issues/404) ## 목적 -`JAM_ISSUE_UIUX_개편안.docx`를 기준으로 현재 Web Front를 앱 셸 구조에 맞춰 정리한다. 이 문서는 구현 세부가 아니라 기준선과 추적 기준을 고정한다. +2차 구현 명세인 `서브내비 헤더 통합 및 KTO 지도 통합`을 Web Front 코드 기준으로 추적합니다. 이 문서는 구현 결과를 포장하는 문서가 아니라, 어떤 화면 구조와 테스트 근거를 기준으로 다음 작업을 검토할지 고정합니다. -## 문서 우선 결정 +## 기준 결정 -앱 전환 UI/UX 개편안의 정보 구조를 우선 기준으로 둔다. +| 항목 | 현재 기준 | +| --- | --- | +| 화면 구조 | `Status Safe Area -> App Header -> Sub Navigation -> Content -> Bottom Tab Bar` | +| 앱 헤더 | 뒤로가기, 설정, 알림, 피드백 액션을 header slot에서 관리 | +| 서브내비 | 지도 필터와 보조 조작을 content 위 absolute overlay가 아니라 shell flow 안에서 관리 | +| 하단 탭 | `지도 / 행사 / 피드 / 코스 / 마이` 5탭 유지 | +| 행사 탭 | 행사 콘텐츠만 표시. 관광장소 세그먼트는 지도 KTO 레이어로 이동 | +| KTO 지도 레이어 | 기본 OFF. 사용자가 토글할 때만 Web Front consumer contract로 관광장소를 조회 | +| KTO 정보 시트 | `isCurated: false` 관광장소는 스탬프/후기 액션 없는 `TourismInfoSheet`로 표시 | +| CSS offset | legacy absolute/fixed 누적 offset과 무효화된 `!important` 패치를 제거 | -| 항목 | 기존 상태 | 개편 기준 | 담당 issue | -| --- | --- | --- | --- | -| 앱 셸 | `phone-shell` 내부에 status, utility, body, bottom nav가 섞여 있음 | `Status Safe Area -> App Header -> Sub Navigation -> Content -> Bottom Tab Bar` | #382 | -| 하단 탭 | 타입은 5탭을 지원했지만 일부 문서가 4탭 기준으로 남아 있었음 | `지도 / 행사 / 피드 / 코스 / 마이` 5탭 | #384 | -| 설정 진입 | 전역 floating utility slot 중심 | 앱 셸 slot과 마이 탭 설정 진입을 충돌 없이 유지 | #382, #385 | -| 지도 필터 | 지도 내부 `map-filter-strip` | Sub Navigation 성격으로 유지 | #382, #384 | -| 장소/행사 시트 | `closed / partial / full` 중심 | `hidden / peek / half / full` 앱 시트 상태 계약 | #383 | -| 탭 콘텐츠 | 일부 탭 surface 검증이 약함 | 각 탭 content surface를 E2E로 고정 | #385 | -| 디자인 토큰 | CSS 변수와 config가 일부 존재하지만 반복 layout literal이 남아 있었음 | bottom nav, sheet gap, 기본 sheet height token/gate | #386 | +## 코드 기준 -## 현재 구현 기준 - -| 영역 | 구현 근거 | 판단 | +| 영역 | 기준 파일 | 판단 | | --- | --- | --- | -| Tab type | `src/types/core.ts`의 `Tab = 'map' | 'event' | 'feed' | 'course' | 'my'` | 5탭을 지원 | -| BottomNav | `src/components/BottomNav.tsx` | 5탭 버튼 렌더링 | -| App shell | `src/components/app-shell/AppShell.tsx` | slot 기반 앱 셸 구조 | -| Map sheet | `src/components/map-stage/mapSheetState.ts` | 앱 sheet state와 legacy drawer state adapter | -| Tab surfaces | `data-page-surface` E2E contract | 행사/피드/코스/마이 content slot 검증 | -| Layout token | `src/index.css`, `src/styles/refinements.css` | 반복 bottom/sheet spacing token화 | -| QA gate | `test/e2e/app-shell.spec.ts`, `test/e2e/critical-ui-flow.spec.ts`, `test/unit/layout-token-source-quality.test.ts` | 핵심 UX regression 고정 | - -## TSK-012 구현 추적 - -| Child issue | Branch | PR | Merge SHA | 결과 | -| --- | --- | --- | --- | --- | -| #381 | `uiux-redesign-audit` | #396 | `c7f4c71` | 기준선과 UIUX matrix 추가 | -| #382 | `app-shell-safe-area-layout` | #397 | `8d85a67` | 앱 셸 safe-area layout | -| #383 | `map-bottom-sheet-state-machine` | #398 | `ed5b817` | 시트 상태 계약 | -| #384 | `five-tab-information-architecture` | #399 | `e3f8481` | 5탭 IA 회귀 방지 | -| #385 | `tab-content-layout-polish` | #400 | `7ed1af2` | 탭 content surface E2E | -| #386 | `design-token-layout-system` | #401 | `90f6cec` | design token/layout constant gate | -| #387 | `uiux-redesign-traceability-docs` | #402 | TBD | 문서와 Wiki traceability | +| App shell | `src/components/app-shell/AppShell.tsx` | header, subNav, content, bottomNav slot 소유 | +| Header | `src/components/app-shell/AppHeader.tsx` | leading back button과 action slot 소유 | +| Map stage props | `src/hooks/usePageStageProps.ts` | KTO 상태와 shell slot props 전달 | +| Tourism API consumer | `src/api/tourismClient.ts`, `src/tourismTypes.ts` | Web Front가 소유하는 consumer contract | +| Tourism markers | `src/components/naver-map/useNaverTourismMarkers.ts` | KTO 정보성 마커 레이어 | +| Tourism info sheet | `src/components/TourismInfoSheet.tsx` | 비큐레이션 관광장소 정보 표시 | +| Event tab | `src/components/EventTab.tsx` | festival-only | +| CSS cleanup | `src/index.css`, `src/styles/refinements.css` | legacy utility/back/filter offset 제거 | -## 후속 PR 체크리스트 +## API/DB/OAuth 범위 -UI/UX 개편 PR은 PR 본문에 아래 항목을 기록한다. +TSK-012는 Web Front UI/UX 구현 축입니다. -- 영향받는 `UIUX-###` ID -- 변경한 앱 셸/탭/시트/token 영역 -- 사용자-facing copy 변경 여부와 사유 -- API/DB/OAuth 변경 없음 확인 -- 실행한 검증 명령 -- Playwright 또는 수동 QA 근거 -- 관련 child issue와 parent #380 링크 +- API path 변경 없음 +- response shape 변경 없음 +- DB schema 변경 없음 +- Kakao/Naver OAuth 성공 경로 변경 없음 +- KTO/OpenAPI를 브라우저에서 직접 호출하지 않음 ## 완료 기준 -- [x] 앱 전환 기준선 문서가 repo에 추가됨 -- [x] `screen-spec.md`가 5탭 기준과 충돌하지 않게 갱신됨 -- [x] `ui-ux-qa-matrix.md`가 `UIUX-###` ID 기준으로 정리됨 -- [x] 앱 셸, 시트, 5탭, tab surface, token gate가 PR/merge SHA로 추적됨 -- [ ] Wiki와 release candidate 문서가 #387에서 최종 갱신됨 +| 조건 | 근거 | +| --- | --- | +| child issue별 PR과 merge SHA 기록 | [UI/UX 추적성](ui-ux-redesign-traceability.md) | +| 기대 동작 ID와 테스트 연결 | [UI/UX QA 매트릭스](ui-ux-qa-matrix.md) | +| release candidate 기록 | [JamIssue 1.3.3 후보](release-candidate-1.3.3.md) | +| Wiki 반영 | `UI-UX-QA-Matrix`, `UI-UX-Redesign-Traceability`, `Release-Notes-1.3.3` | diff --git a/docs/ui-ux-redesign-traceability.md b/docs/ui-ux-redesign-traceability.md index 5078af4..9672014 100644 --- a/docs/ui-ux-redesign-traceability.md +++ b/docs/ui-ux-redesign-traceability.md @@ -1,51 +1,52 @@ -# JamIssue 앱 전환 UI/UX 개편 추적성 +# JamIssue 2차 UI/UX 구현 추적성 -Scope-ID: `TSK-012` -Parent Issue: https://github.com/STH-1-Class-One-Group/JamIssue/issues/380 -상태: `1.3.x 후보 문서화 대상` +Scope-ID: `TSK-012` +Parent Issue: [#404](https://github.com/STH-1-Class-One-Group/JamIssue/issues/404) +릴리즈 후보: `1.3.3` ## 요약 -TSK-012는 `JAM_ISSUE_UIUX_개편안.docx`를 기준으로 Web Front의 화면 구조를 앱 셸 기준으로 재정리한 작업 묶음이다. +TSK-012는 2차 구현 명세인 `서브내비 헤더 통합 및 KTO 지도 통합`을 Web Front 코드에 반영한 작업 묶음입니다. -핵심 방향은 다음과 같다. +핵심 방향은 다음과 같습니다. -- `Status Safe Area -> App Header -> Sub Navigation -> Content -> Bottom Tab Bar` 구조를 공식 화면 기준으로 둔다. -- 하단 탭은 `지도 / 행사 / 피드 / 코스 / 마이` 5탭을 유지한다. -- 지도 장소/행사 시트는 `hidden / peek / half / full` 상태 계약으로 관리한다. -- UI/UX 기대 동작은 `UIUX-###` ID와 Playwright/Vitest 근거로 추적한다. -- 외부 API path, response shape, DB schema, OAuth 경로는 변경하지 않는다. +- 앱 셸을 header, subNav, content, bottomNav 슬롯으로 정리합니다. +- 설정/알림/피드백/뒤로가기 액션을 floating absolute UI가 아니라 header slot으로 통합합니다. +- 지도 필터를 subNav flow로 이동합니다. +- 행사 탭은 festival-only로 정리하고, 관광장소는 지도 KTO 레이어에서 다룹니다. +- KTO 정보성 장소는 스탬프/후기 액션이 없는 정보 시트로 분리합니다. +- legacy CSS offset과 무효화된 override를 제거합니다. ## 구현 PR -| Child issue | PR | Merge SHA | 내용 | 검증 근거 | -| --- | --- | --- | --- | --- | -| #381 | #396 | `c7f4c71` | UI/UX 기준선과 QA matrix | docs readback, UTF-8 | -| #382 | #397 | `8d85a67` | App shell safe-area layout | E2E app shell | -| #383 | #398 | `ed5b817` | Map bottom sheet state machine | unit + E2E | -| #384 | #399 | `e3f8481` | Five-tab information architecture | E2E five-tab IA | -| #385 | #400 | `7ed1af2` | Tab content layout surfaces | E2E `UIUX-014` | -| #386 | #401 | `90f6cec` | Design token and layout constant gate | `check:numeric-literals` | -| #387 | #402 | TBD | Repo/Wiki traceability docs | docs readback | +| Child issue | Branch | PR | Merge SHA | 내용 | 검증 근거 | +| --- | --- | --- | --- | --- | --- | +| [#405](https://github.com/STH-1-Class-One-Group/JamIssue/issues/405) | `second-uiux-audit-baseline` | [#412](https://github.com/STH-1-Class-One-Group/JamIssue/pull/412) | `dc0c5027` | 기준선 audit | code evidence, E2E baseline | +| [#406](https://github.com/STH-1-Class-One-Group/JamIssue/issues/406) | `app-header-slot-integration` | [#413](https://github.com/STH-1-Class-One-Group/JamIssue/pull/413) | `edac1e31` | AppHeader slot 통합 | unit, E2E | +| [#407](https://github.com/STH-1-Class-One-Group/JamIssue/issues/407) | `app-shell-subnav-grid-layout` | [#414](https://github.com/STH-1-Class-One-Group/JamIssue/pull/414) | `bcd1284` | AppShell subNav grid flow | unit, E2E | +| [#408](https://github.com/STH-1-Class-One-Group/JamIssue/issues/408) | `event-tab-festival-only-cleanup` | [#415](https://github.com/STH-1-Class-One-Group/JamIssue/pull/415) | `3ee8f77` | EventTab festival-only | E2E | +| [#409](https://github.com/STH-1-Class-One-Group/JamIssue/issues/409) | `kto-tourism-map-layer-infosheet` | [#416](https://github.com/STH-1-Class-One-Group/JamIssue/pull/416) | `b89b7fc` | KTO 지도 레이어와 정보 시트 | unit, E2E | +| [#410](https://github.com/STH-1-Class-One-Group/JamIssue/issues/410) | `app-shell-css-offset-cleanup` | [#417](https://github.com/STH-1-Class-One-Group/JamIssue/pull/417) | `fa67c88` | legacy CSS offset 정리 | unit, E2E, source-quality | +| [#411](https://github.com/STH-1-Class-One-Group/JamIssue/issues/411) | `second-uiux-traceability-docs` | TBD | TBD | repo/Wiki 추적성 문서 | docs readback, UTF-8 | ## UIUX ID 연결 -| ID | 고정된 기대 동작 | 근거 | +| ID | 고정한 기대 동작 | 근거 | | --- | --- | --- | -| `UIUX-001` | 앱 셸과 하단 탭 anchoring | #382, #397 | -| `UIUX-004` | sheet state contract | #383, #398 | -| `UIUX-009` | 모바일 키보드 입력 중 nav/sheet anchoring | existing E2E | -| `UIUX-010` | 피드 댓글/좋아요/장소 CTA | existing E2E | -| `UIUX-011` | 코스 정렬/카드 진입 | existing E2E | -| `UIUX-012` | 마이 탭 로그인 전/후 상태 | existing E2E | -| `UIUX-013` | 5탭 IA와 비지도 탭 지도 숨김 | #384, #399 | -| `UIUX-014` | 탭 content surface 접근성 | #385, #400 | -| `UIUX-017` | Peek 시트와 탭바 간격 | #383, #398 | -| `UIUX-018` | Full 시트에서 탭바 숨김 | #383, #398 | -| `UIUX-020` | layout token/config gate | #386, #401 | +| `UIUX-001` | 앱 셸과 하단 탭 anchoring | #407, PR #414 | +| `UIUX-003` | 지도 레이아웃 겹침 방지 | #407, #410 | +| `UIUX-004` | sheet state contract | 기존 `map-sheet-state` 테스트 | +| `UIUX-006` | 행사 탭 festival-only | #408, PR #415 | +| `UIUX-013` | 5탭 IA 유지 | 기존 app-shell E2E | +| `UIUX-015` | header slot 통합 | #406, PR #413 | +| `UIUX-016` | subNav flow | #407, PR #414 | +| `UIUX-021` | KTO 레이어 기본 OFF와 토글 조회 | #409, PR #416 | +| `UIUX-022` | KTO 정보 시트 분리 | #409, PR #416 | ## 검증 명령 +TSK-012 구현 PR 공통 검증 기준입니다. + ```powershell npm.cmd run check:numeric-literals npm.cmd run lint @@ -54,22 +55,15 @@ npm.cmd run test:unit npm.cmd run test:integration npm.cmd run test:regression npm.cmd run test:e2e -npm.cmd run test:coverage:ts npm.cmd run build git diff --check ``` -UTF-8 integrity check는 변경 파일 strict decode 기준으로 수행한다. +문서 PR은 UTF-8 strict read와 Wiki link readback을 추가로 확인합니다. ## 문서 링크 -- [화면 설계 기준](screen-spec.md) -- [UI/UX 기대 동작 QA 매트릭스](ui-ux-qa-matrix.md) -- [앱 전환 UI/UX 개편 기준선](ui-ux-redesign-baseline.md) -- [테스트 커버리지 운영 기준](testing-coverage.md) - -## 완료 전 남은 작업 - -- #387 PR merge 후 이 문서의 #387 merge SHA를 이슈 완료 근거에 기록한다. -- Wiki `Home`, `Development-Guide`, `UI-UX-QA-Matrix`, `Release Notes`에 같은 traceability를 연결한다. -- Parent #380에 최종 main SHA, CI, CodeQL, production-smoke 링크를 기록한다. +- [Governance Index](GOVERNANCE_INDEX.md) +- [UI/UX QA 매트릭스](ui-ux-qa-matrix.md) +- [UI/UX 구현 기준선](ui-ux-redesign-baseline.md) +- [JamIssue 1.3.3 후보](release-candidate-1.3.3.md) diff --git a/reports/completion/TSK-012-07-second-uiux-traceability-docs.md b/reports/completion/TSK-012-07-second-uiux-traceability-docs.md new file mode 100644 index 0000000..52e5f20 --- /dev/null +++ b/reports/completion/TSK-012-07-second-uiux-traceability-docs.md @@ -0,0 +1,42 @@ +# TSK-012-07 Second UI/UX Traceability Docs + +## 메타데이터 + +| 항목 | 값 | +| --- | --- | +| Scope-ID | `TSK-012-07-SECOND-UIUX-TRACEABILITY-DOCS` | +| Parent Issue | [#404](https://github.com/STH-1-Class-One-Group/JamIssue/issues/404) | +| Child Issue | [#411](https://github.com/STH-1-Class-One-Group/JamIssue/issues/411) | +| Branch | `second-uiux-traceability-docs` | +| PR | TBD | +| Merge SHA | TBD | +| Status | PR 전 로컬 문서 정리 | + +## 변경 요약 + +- repo 문서의 UI/UX QA 매트릭스, 기준선, 추적성 문서를 TSK-012 기준으로 복구했습니다. +- `1.3.3` 후보 릴리즈 노트를 추가했습니다. +- TSK-012 child issue #405~#410의 PR과 merge SHA를 문서 근거로 연결했습니다. +- Wiki 반영 대상 문서는 `Home`, `_Sidebar`, `UI-UX-QA-Matrix`, `UI-UX-Redesign-Traceability`, `Release-Notes-1.3.3`입니다. +- 현재 `origin/main`의 `src/hooks` 추적 파일 수가 88개인데 source-quality gate 기준선이 87개로 남아 있어, 제품 동작 변경 없이 기준선을 실제 코드 상태와 맞췄습니다. + +## Architecture Boundary Gate + +| 항목 | 근거 | +| --- | --- | +| Responsibility map | repo docs는 Web Front 구현 추적성, Wiki는 운영자가 보는 정본 링크, issue는 완료 증거를 소유합니다. | +| Dependency direction | 문서는 코드 계약을 바꾸지 않고, 구현 PR과 issue 증거를 참조만 합니다. | +| Test seam | docs readback, UTF-8 strict decode, markdown diff check, Wiki slug link 확인입니다. | +| Scope map | TSK-012 문서/추적성만 포함합니다. API/DB/OAuth/provider contract는 제외합니다. | +| Architecture risk | 문서가 구현보다 앞서가면 false traceability가 생기므로 PR/merge SHA가 있는 항목만 완료로 표기합니다. | + +## 검증 + +PR 생성 전 실행 예정: + +```powershell +git diff --check +npm.cmd run test:unit -- second-uiux-audit-baseline +``` + +최종 PR 전 UTF-8 strict read와 Wiki link readback을 추가로 확인합니다. diff --git a/test/unit/architecture-readability-source-quality.test.ts b/test/unit/architecture-readability-source-quality.test.ts index 299492c..3477cbe 100644 --- a/test/unit/architecture-readability-source-quality.test.ts +++ b/test/unit/architecture-readability-source-quality.test.ts @@ -46,7 +46,7 @@ describe('architecture readability source quality baseline', () => { const directRootHookFiles = hookFiles.filter((path) => path.split('/').length === 3); const tinyDirectRootHookFiles = directRootHookFiles.filter((path) => countLines(path) <= 15); - expect(hookFiles.length).toBeLessThanOrEqual(87); + expect(hookFiles.length).toBeLessThanOrEqual(88); expect(directRootHookFiles.length).toBeLessThanOrEqual(35); expect(tinyDirectRootHookFiles.length).toBeLessThanOrEqual(9); });