# 상세 팝업 정보 영역 통합 계획

## 1. 배경
- 현재 모든 상세 팝업(마스터·결재·재고 등)은 `SuperportDetailDialog` 상단 summary/metadata(정보1)와 탭 섹션(정보2)에서 동일한 엔티티 데이터를 중복 노출한다.
- 사용자는 정보가 하나의 블록에서 완결되길 기대하지만, 구현상 개요(summary)와 `_OverviewSection` 사이에 필드가 분산되어 정보1/정보2가 따로 보이게 된다.
- 같은 API 데이터를 두 영역에 반복 표기하면서도 정보 간 일관성이 떨어져 UX 혼란이 발생한다.

## 2. 대상 팝업
| 분류 | 파일 |
| --- | --- |
| 결재 템플릿 | `lib/features/approvals/template/presentation/dialogs/approval_template_detail_dialog.dart` |
| 결재 단계 | `lib/features/approvals/step/presentation/dialogs/approval_step_detail_dialog.dart` |
| 벤더 | `lib/features/masters/vendor/presentation/dialogs/vendor_detail_dialog.dart` |
| 그룹 | `lib/features/masters/group/presentation/dialogs/group_detail_dialog.dart` |
| 그룹 메뉴 권한 | `lib/features/masters/group_permission/presentation/dialogs/group_permission_detail_dialog.dart` |
| 고객사 | `lib/features/masters/customer/presentation/dialogs/customer_detail_dialog.dart` |
| 메뉴 | `lib/features/masters/menu/presentation/dialogs/menu_detail_dialog.dart` |
| 제품 | `lib/features/masters/product/presentation/dialogs/product_detail_dialog.dart` |
| 사용자 | `lib/features/masters/user/presentation/dialogs/user_detail_dialog.dart` |
| 창고 | `lib/features/masters/warehouse/presentation/dialogs/warehouse_detail_dialog.dart` |

> ※ `SuperportDetailDialog` 자체(`lib/widgets/components/superport_detail_dialog.dart`)를 공통으로 수정해야 하므로 목록에 포함.

## 3. 목표 UX
1. 정보1(상단 summary+metadata)에서 모든 읽기 전용 필드를 완결성 있게 노출한다.
2. 정보2(탭 영역)는 액션 중심(수정/삭제/히스토리 등)으로 단순화한다.
3. 동일 필드는 단 한 곳(정보1)에만 표시되도록 하여 중복을 제거한다.

## 4. 단계별 플랜

### 4.1 구조 파악 & 정리
- [x] 대상 다이얼로그마다 현재 summary/metadata/overview에 배치된 필드를 표로 정리한다.
- [x] 중복 필드, 정보1에 반드시 남겨야 할 핵심 필드(이름, 코드, 상태, 타임스탬프 등)를 분류한다.
- [x] 추가 데이터 소스 유무 확인(현행은 단일 엔티티 전달 → 별도 API 불필요).

#### 4.1.1 필드 배치 매핑
| 팝업 | Summary 필드 | Metadata 필드 | Overview/기타 섹션 필드 | 중복 & 정보1 핵심 정리 |
| --- | --- | --- | --- | --- |
| 결재 템플릿 | 템플릿명<br>설명 | ID<br>코드<br>생성일시<br>변경일시<br>비고 | 템플릿명<br>코드<br>설명<br>사용 여부<br>생성일시<br>변경일시<br>비고 | 중복: 이름/코드/설명/타임스탬프/비고. 핵심: summary=템플릿명·설명 유지, metadata=ID/코드/생성·변경/비고, 사용 여부는 summaryBadges에 집중. |
| 결재 단계 | 단계 순번<br>승인자 이름+사번<br>비고 | 결재 ID<br>트랜잭션번호<br>템플릿명<br>승인자 사번<br>배정일시<br>결정일시 | 단계 순서<br>승인자 이름<br>승인자 사번<br>상태<br>배정/결정일시<br>비고 | 중복: 승인자 사번·배정/결정 시각·비고. 핵심: summary=단계 제목+승인자, metadata=결재/템플릿 식별자+승인자 사번+상태+배정/결정/비고로 통합. |
| 벤더 | 벤더명<br>벤더코드 | ID<br>생성일시<br>변경일시<br>비고 | 벤더코드<br>벤더명<br>사용 여부<br>삭제 여부<br>비고<br>생성/변경일시 | 중복: 코드·이름·비고·타임스탬프. 핵심: summary=벤더명·코드, metadata=ID/코드/생성·변경/비고와 사용·삭제 상태(배지 또는 metadata)만 유지. |
| 그룹 | 그룹명<br>설명 | ID<br>생성일시<br>변경일시<br>비고 | 그룹명<br>설명<br>기본 여부<br>사용 여부<br>삭제 여부<br>비고<br>생성/변경일시 | 중복: 그룹명·설명·비고·타임스탬프. 핵심: summary=그룹명·설명, metadata=ID/상태/타임스탬프/비고, 기본 여부는 metadata로 이동. |
| 그룹 권한 | 그룹명 → 메뉴명 | ID<br>메뉴 경로<br>비고<br>생성일시<br>변경일시 | 그룹<br>메뉴<br>경로<br>CRUD 권한 4종<br>사용 여부<br>삭제 여부<br>비고<br>생성/변경일시 | 중복: 경로·비고·타임스탬프. 핵심: summary=그룹/메뉴 페어, metadata=ID/경로/CRUD 권한/상태/비고/타임스탬프, 삭제 시 배지. |
| 고객사 | 고객사명<br>고객코드 | ID<br>담당자<br>연락처<br>이메일<br>생성일시<br>수정일시 | 고객코드<br>유형(파트너/일반)<br>사용/삭제 여부<br>담당자<br>연락처<br>이메일<br>우편번호<br>주소<br>비고<br>생성/수정일시 | 중복: 담당자·연락처·이메일·타임스탬프. 핵심: summary=이름·코드, metadata=ID/유형/담당·연락·이메일/주소/상태/타임스탬프/비고. |
| 메뉴 | 메뉴명<br>경로 | ID<br>메뉴코드<br>표시순서<br>비고<br>생성일시<br>변경일시 | 메뉴코드<br>메뉴명<br>상위메뉴<br>경로<br>표시순서<br>사용 여부<br>삭제 여부<br>비고<br>생성/변경일시 | 중복: 코드·경로·표시순서·비고·타임스탬프. 핵심: summary=메뉴명+경로, metadata=ID/코드/상위/표시순서/상태/타임스탬프/비고. |
| 제품 | 제품명<br>제품코드 | ID<br>제조사<br>단위<br>생성일시<br>변경일시<br>비고 | 기본 정보: 제품코드·제품명·사용/삭제 여부·비고·생성/변경일시<br>관계 섹션: 제조사·단위<br>히스토리 섹션: 안내 문구 | 중복: 제조사/단위, 비고, 타임스탬프. 핵심: summary=이름·코드, metadata=ID/제조사/단위/상태/타임스탬프/비고, 관계 섹션은 액션/링크 중심으로 축소. |
| 사용자 | 직원명<br>사번 | ID<br>그룹<br>이메일<br>연락처<br>비고<br>비밀번호 변경일시<br>생성/수정일시 | 개요: 사번·이메일·연락처·그룹·사용/삭제 여부·비고·생성/수정일시<br>보안 섹션: 비밀번호 변경일시·강제 변경 여부 | 중복: 이메일·연락처·그룹·비고·타임스탬프·비밀번호 변경일시. 핵심: summary=직원명·사번, metadata=ID/그룹/연락처/이메일/비고/비밀번호 정보/상태/타임스탬프. |
| 창고 | 창고명<br>창고코드 | ID<br>우편번호<br>기본주소<br>상세주소<br>생성일시<br>변경일시<br>비고 | 기본 정보: 창고코드·창고명·사용/삭제 여부·비고·생성/변경일시<br>주소 섹션: 우편번호·주소·상세주소 | 중복: 주소 3종·타임스탬프·비고. 핵심: summary=이름·코드, metadata=ID/주소/상태/타임스탬프/비고, 별도 주소 섹션은 지도/편집 가이드를 위한 설명만 남김. |

- 모든 상세 다이얼로그가 단일 엔티티를 인자로 전달받고 있으며, 별도의 추가 API 호출이나 비동기 데이터 로딩 없이 summary/metadata/overview를 구성한다. 따라서 정보1에 필드를 통합할 때도 데이터 소스 확장이 필요 없다.
- 공통 컴포넌트 `SuperportDetailDialog`는 summary·metadata·섹션을 세로로 쌓는 단일 레이아웃으로, 현재 1열 `_MetadataTable`만 지원한다. 고객/창고처럼 필드가 10개 이상인 경우 스크롤이 길어지므로 2열화 또는 그룹 헤더 도입 필요성이 확인됐다.

### 4.2 공통 레이아웃 개편안 확정
- [x] `SuperportDetailDialog`에서 summary/metadata 블록이 “정보1”로 인지되도록 레이아웃/간격/구분선을 다듬는다.
- [x] metadata를 2열 테이블 또는 Grid로 확장해 더 많은 필드를 수용할 수 있도록 옵션 검토.
- [x] 탭 섹션에는 개요를 제외하고, 폼·위험 액션·히스토리 등 행위 중심 요소만 남기는 가이드 작성.

#### 4.2.1 닫기 인터랙션 정리
- 상세보기 계열 팝업은 기본적으로 세 가지 닫기 방식을 제공한다.
  1. 팝업 우상단의 X 버튼
  2. 팝업 바깥 영역 클릭(barrier dismissible)
  3. 팝업 우하단 액션 영역의 “닫기” 버튼
- 3번 “닫기” 버튼은 X 버튼과 동일한 동작을 반복해서 정보 과밀감을 유발하므로 UI에서 제거한다. 필요 시 개별 화면에서만 액션 버튼을 추가하도록 하고, 공통 다이얼로그에서는 닫기 버튼을 렌더링하지 않는다.

#### 4.2.2 정보1 레이아웃 스펙
- `SuperportDetailDialog` 상단 영역을 `infoPanel`(summary + metadata)로 묶어 `ShadCard` 스타일로 렌더링한다. 좌우/상하 여백을 통일해 summary/metadata가 하나의 덩어리(정보1)로 인지되도록 했다.
- summary 영역은 기존 `summary` 슬롯을 그대로 사용하며, 대표 타이틀/보조 텍스트 → 배지 순의 수직 스택을 유지한다. summary/metadata 사이 여백은 카드 내부에서만 관리해 섹션과 시각적으로 분리된다.
- metadata는 `_MetadataGrid`로 교체해 2열 레이아웃을 기본값(`metadataColumns = 2`)으로 제공한다. 가로폭이 520px 미만이거나 열 수가 항목 수보다 많으면 자동으로 1열로 접어 UX를 보장한다.
- metadata 항목은 라벨/아이콘/값이 세로 정렬된 카드 타일로 렌더링되며, 값 영역은 `Widget` 그대로 머지되어 텍스트·뱃지·아이콘 등 자유로운 구성을 유지한다.
- `infoPanelPadding` 파라미터를 추가해 summary+metadata 블록과 탭 섹션 사이 간격을 한 번에 조절할 수 있도록 했고, `metadataColumns` 파라미터로 팝업 별 열 수 튜닝도 가능하다.

#### 4.2.3 탭 구성 가이드
- 탭 영역은 “행위 중심 정보2”로 재정의한다. 읽기 전용 필드는 summary/metadata에 모두 흡수하고, 탭에는 폼, 수정/위험 액션, 히스토리, 관계 관리 등 상호작용성 있는 콘텐츠만 남긴다.
- `SuperportDetailDialogSection`에 overview 전용 빌더를 남겨두지 않고, 각 다이얼로그는 `_OverviewSection` 파일을 제거하면서 해당 필드를 `metadata` 리스트로 옮긴다.
- 탭이 한 개만 남는 경우 자동으로 단일 패널 모드로 전환되므로, 최소 “폼/위험/히스토리” 중 필요한 섹션만 남겨도 된다. 이때 `initialSectionId`는 남은 섹션 ID 중 하나로 업데이트한다.

### 4.3 다이얼로그별 코드 수정
- [ ] 각 다이얼로그에서 `_OverviewSection`(읽기 전용)을 제거하고 해당 필드를 metadata 배열로 이동.
- [ ] summary에는 대표 타이틀/보조 텍스트만 남기고 상태 배지는 `summaryBadges`로 유지.
- [ ] 탭 목록에서 제거된 섹션을 반영하여 ID 상수·초기 선택 로직을 정리.
- [ ] 필요 시 metadata 행 구성을 위한 헬퍼(예: `_KeyValueRow`)를 공통 유틸로 승격하거나 삭제.

#### 4.3 진행 현황
- [x] 결재 템플릿 팝업: `_TemplateOverviewSection` 제거, metadata에 상태/코드/타임스탬프/비고를 통합하고 초기 탭을 `steps`로 변경했다. `_KeyValueRow` 유틸은 더 이상 사용하지 않아 삭제 완료.
- [x] 결재 단계 팝업: `_ApprovalStepOverviewSection` 제거, 단계 순서·승인자·상태·배정/결정일시·비고를 metadata로 이동하고 탭은 수정/삭제(복구)만 남겼다. 권한에 따라 섹션이 없을 수 있으므로 info panel만으로도 정보가 완결된다.
- [x] 벤더 팝업: `_VendorOverviewSection`과 `_KeyValueRow` 삭제, ID/코드/상태/삭제 상태/타임스탬프/비고를 metadata로 통합하고 summary에는 이름만 남겼다. 초기 탭은 생성/수정으로 변경되어 정보1+액션 분리가 완료됐다.
- [x] 그룹 팝업: `_GroupOverviewSection` 제거, 기본 여부/사용·삭제 여부/타임스탬프/비고를 metadata로 이동했으며 summary는 이름·설명만 유지한다. 탭은 등록/수정과 삭제/복구만 남겨 행위 중심 구조를 맞췄다.
- [x] 그룹 권한 팝업: `_GroupPermissionOverviewSection`을 삭제하고 그룹/메뉴/경로/CRUD 권한/상태/삭제 여부/노트/타임스탬프를 metadata에 넣었다. summary에는 `그룹 → 메뉴`만 남기고 탭은 수정, 삭제/복구(또는 등록)만 유지한다.
- [x] 고객사 팝업: `_CustomerOverviewSection` 제거, 고객 코드/유형/연락처/주소/상태/삭제 여부/타임스탬프/비고를 metadata로 통합하고 summary는 이름만 남겼다. 탭은 등록/수정+삭제/복구만 유지해 정보1과 액션을 분리했다.
- [x] 제품 팝업: `_ProductOverviewSection` 제거, 제품 코드/상태/삭제 여부/제조사/단위/비고/타임스탬프를 metadata로 이동하고 summary에는 제품명만 남겼다. 탭은 연결 관계·히스토리(행위 가이드)와 등록/수정·삭제/복구만 남도록 조정했다.
- [x] 창고 팝업: `_WarehouseOverviewSection`/`_WarehouseAddressSection` 삭제, ID/창고코드/상태/삭제 여부/주소/비고/타임스탬프를 metadata로 결합했고 탭은 등록·수정과 삭제/복구만 남겼다. 상세 모드 초기 탭을 `edit`으로 지정해 정보1과 행위 영역이 명확히 구분된다.
- [x] 재고 입출고/대여 팝업: 재고 상세 공통 다이얼로그를 `SuperportDetailDialog`로 교체하고 입고/출고/대여 레코드의 상태·창고·금액/수량·반납 예정일을 metadata로 옮겼다. 탭은 라인 품목(고객/관계 포함)만 남겨 info1과 행위 영역이 분리되었다.
- [ ] 나머지 결재/마스터 팝업: 동일한 패턴으로 순차 대응 예정.

#### 4.3.1 재고 현황 상세 시트 적용 스냅샷
- Inventory Summary 화면(`lib/features/inventory/summary/presentation/pages/inventory_summary_page.dart`)은 통합 가이드를 따라 summary/metadata/본문을 재구성했다.
  - summary 카드: 제품명·코드, 총 수량, 뷰 리프레시 시각만 남겨 정보1에서 전체 상태를 빠르게 파악한다.
  - metadata 영역: 창고 선택, 이벤트 개수(`event_limit`), 0 수량 포함 토글, 오류 배너가 모두 상단에 배치돼 중복 필드를 없앴다.
  - 본문: 창고 잔량 그래프 + Tag, 최근 이벤트 타임라인만 유지하며 모든 필드는 한 번만 노출된다.
- Golden 산출물
  - 목록 기본 상태: `test/features/inventory/summary/presentation/pages/goldens/inventory_summary_page_default.png`
  - 상세 시트 오픈 상태: `test/features/inventory/summary/presentation/pages/goldens/inventory_summary_detail_sheet.png`
- 검증 명령: `flutter test --update-goldens test/features/inventory/summary/presentation/pages/inventory_summary_page_golden_test.dart`

### 4.4 검증 & 테스트
- [ ] 기존 위젯 테스트 업데이트: overview 탭 삭제, metadata 렌더링 검증 등.
- [ ] 신규 테스트 케이스 추가: summary+metadata에 필드가 모두 나타나는지, 탭이 최소 한 개만 남았을 때 동작하는지 확인.
- [ ] `flutter analyze`, `flutter test` 전 프로젝트 실행.
- [ ] 스타일 변경 시 주요 화면 캡처를 남겨 리뷰 참고자료로 사용.

## 5. 예상 산출물
- 수정된 상세 다이얼로그 10여 개 및 공통 컴포넌트 1개.
- 테스트 업데이트(다이얼로그 위젯 테스트 최소 1개 이상).
- 필요 시 설계 문서(본 문서 갱신 포함) 및 회고 노트.

## 6. 리스크 및 대응
| 리스크 | 대응 |
| --- | --- |
| metadata 영역에 필드가 많아져 가독성 저하 | 2열 레이아웃, 섹션 헤더, collapse 등 UI 개선 옵션 검토 |
| 탭 제거로 인한 라우팅/초기 섹션 ID 로직 오류 | `initialSectionId` 사용 여부 재확인 및 단위 테스트 작성 |
| 테스트 스냅샷/Golden 미존재 시 회귀 미포착 | 주요 다이얼로그에 대한 Widget 테스트 보강 |

## 7. 이후 액션
1. 4.1의 필드 매핑 표를 작성해 본 문서를 업데이트.
2. 공통 레이아웃 확정 후 시놉시스/디자인 확인.
3. 다이얼로그-by-다이얼로그로 리팩토링 진행, 각 단계 완료 시 테스트/리포트 공유.
