superport_v2/doc/IMPLEMENTATION_TASKS.md

# Superport v2 프론트엔드 구현 Task List (UI First → API Integration)

본 체크리스트는 PRD(`doc/PRD_입출고_결재_v2.md`)를 기준으로 shadcn_ui 스타일과 반응형 패턴을 준수하여 화면을 구현하기 위한 단계별 작업 목록입니다. 작업 순서는 ① 코드 시작 전 최종 확인 → ② UI 스캐폴딩/상호작용 구현 → ③ 실제 API 연동(Dio/ApiClient/DI)입니다. Mock 데이터는 사용하지 않습니다.

## 0) 코드 시작 전 최종 확인(Repository/환경)
- [x] Flutter 버전/채널 확인, `flutter pub get`
- [x] `pubspec.yaml` 확인: `go_router`, `shadcn_ui`, `intl`, `two_dimensional_scrollables`, `lucide_icons_flutter` 포함
- [x] `Environment.initialize()` 호출 및 `.env.development`/`.env.production`에서 `API_BASE_URL`/`TIMEOUT_MS`/`LOG_LEVEL` 로드
- [x] 라우팅 스켈레톤(go_router) 구성: 로그인/대시보드/입·출·대여/마스터/결재/보고서
- [x] 글로벌 테마/ShadTheme 확인(폰트/간격/배지/버튼 일관)

## 1) 공통 컴포넌트/레이아웃(UI)
- [x] AppLayout(좌 사이드바/상단 헤더/본문) 적용, 브레드크럼·타이틀·툴바 영역 정리 (현황: 입·출·대여와 전 마스터 실화면에 `AppLayout`/브레드크럼/툴바 적용 완료, 결재/보고서 등 잔여 SpecPage 전환만 남음)
- [ ] 테이블: `ShadTable.list` 표준화(고정 헤더/가로 스크롤/소팅/페이지네이션 UI만) (현황: `SuperportTable` 컴포넌트 정의만 있고 실제 화면에서는 직접 `ShadTable.list`를 호출함)
- [ ] 모달: `SuperportShadDialog`(헤더/본문/푸터 분리, 모바일 풀스크린) 공통 wrapper (현황: 화면별로 `showDialog`를 직접 구성하며 공통 래퍼 미사용)
- [ ] 입력 위젯: `ShadInput/Select/Switch`, `SuperportShadDatePicker/RangePicker` 적용 가이드 (현황: 기본 입력 위젯 사용은 있으나 DatePicker 등 공통 컴포넌트/가이드 부재)
- [ ] 필터바(검색/기간/상태/창고/Reset) 공통 위젯 (현황: `FilterBar`를 입/출/대여 + 벤더/제품 화면에 적용했으나 나머지 화면 전파 및 필터 상태 표준화 필요)
- [ ] 반응형 프리셋: 데스크톱/태블릿/모바일 열 가시성 설정(섹션 12 규칙 반영) (현황: `responsive.dart`에 상수만 있고 실제 적용 사례 없음)
- [ ] 토스트/스낵바/스켈레톤/Empty 상태 공통 처리 (현황: 개별 화면에서 `SnackBar`와 임시 문구만 사용, 공통 처리 미정)

## 2) 인증/대시보드(UI)
- [ ] 로그인 화면(`/login`): 아이디/비밀번호 UI(제출/로딩/에러 표시 흐름) (현황: 텍스트 필드/버튼만 있고 로딩, 에러 메시지, 실제 인증 연동 없음)
- [ ] 대시보드(`/`): KPI 카드, 최근 트랜잭션, 내 결재 대기 리스트 — 스켈레톤/Empty 상태 구현 (현황: `SpecPage`로 요구사항만 노출, 실제 대시보드 UI 미구현)

## 3) 입고(`/inbounds`) UI
- [x] 라우트/네비게이션 연결 (현황: GoRouter에 `/inventory/inbound` 경로 등록, `AppShell` 내에서 진입 가능)
- [ ] 목록 테이블: 번호/처리일자/창고/트랜잭션번호/상태/작성자/품목수/총수량/비고 (현황: `ShadTable.list`를 직접 구성하지만 모의 데이터 기반이며 컬럼 구성이 사양과 다르고 고정 헤더/페이징 부재)
- [ ] 필터: 기간/창고/상태/검색, 소팅/페이지네이션 (현황: 검색어와 기간만 제공, 창고/상태/소팅/페이지네이션 미구현)
- [ ] 신규 모달: 헤더(처리일자/창고/상태/작성자/비고) + 시스템 필드(`transaction_type_id=입고` RO/숨김) (현황: 개별 `Dialog`에서 입력 필드 작성만 가능하며 `transaction_type_id` 처리 및 시스템 필드 구분 없음)
- [ ] 라인 테이블: 제품(자동완성)→제조사/단위 자동, 수량/단가/비고, (+)/(−) 행 편집 (현황: 수동 입력 필드만 제공되고 자동완성·연동 로직 부재)
- [ ] 검증: 필수/수량>=1/단가>=0, 상단 요약 + 인라인 에러 (현황: 품목명 비어 있음만 검사, 수량/단가 검증 및 요약/인라인 에러 미구현)
- [ ] 수정 모달: 작성자/트랜잭션번호 RO, 종결 상태 수정 제한 (현황: 동일 폼 재사용으로 모든 필드 편집 가능, 상태 제한 없음)

## 4) 출고(`/outbounds`) UI
- [ ] 목록 테이블: 번호/처리일자/창고/트랜잭션번호/상태/작성자/고객수/품목수/총수량/비고 (현황: 모의 데이터 기반 테이블이며 컬럼 구성이 사양과 다르고 페이징/소팅 없음)
- [ ] 필터: 기간/창고/상태/고객/검색 (현황: 검색어·기간만 제공, 창고/상태/고객 필터 부재)
- [ ] 신규/수정 모달: 헤더(…)+ 시스템 필드(`transaction_type_id=출고` RO/숨김) (현황: 공통 모달 없이 개별 `Dialog` 구성, `transaction_type_id` 자동 주입 처리 없음)
- [ ] 고객 연결(멀티): 고객사 자동완성 → 토큰/칩 UI, 최소 1건 검증 (현황: `ShadSelect.multiple`로 선택 UI는 있으나 자동완성/최소 1건 검증/실제 데이터 연동 미구현)
- [ ] 라인 테이블: 제품/제조사RO/단위RO/수량/단가/비고 (현황: 수동 입력 필드만 존재, 제조사/단위 자동 채움 및 읽기 전용 처리 미구현)

## 5) 대여(`/rentals`) UI
- [ ] 목록 테이블: 번호/처리일자/창고/대여구분/트랜잭션번호/상태/반납예정일/고객수/품목수/비고 (현황: 모의 데이터 테이블로 사양 대비 컬럼/정렬/페이징 미충족)
- [ ] 필터: 기간/창고/상태/대여구분/반납예정일 범위/검색 (현황: 검색어·기간만 제공, 나머지 필터 미구현)
- [ ] 신규/수정 모달: 헤더(…/대여구분/반납예정일) + 시스템 필드(`transaction_type_id` 대여/반납 자동 매핑) (현황: 개별 `Dialog` 구성으로 필드 입력만 가능하며 시스템 필드/자동 매핑 로직 없음)
- [ ] 고객 연결(멀티) + 라인 테이블(입고·출고와 동일) (현황: 멀티 선택 UI는 있으나 자동완성/검증/공통 라인 테이블 추출 미완료)
- [ ] 규칙: 대여구분은 종결 후 변경 불가, 반납예정일은 진행 중 수정 가능 (현황: 상태별 편집 제한 로직 전혀 없음)

## 6) 마스터(UI)
- [x] 벤더: 목록/필터(q/사용여부), 신규/수정(코드RO), 삭제/복구 UI (현황: `FEATURE_VENDORS_ENABLED=true`일 때 `VendorController` 기반 CRUD/삭제·복구/상태필터 동작, API 경로 `/vendors` 연결은 실제 백엔드 준비 필요)
- [x] 제품: 목록/필터(q/제조사/단위/사용), 신규/수정(코드RO) (현황: `ProductController`가 벤더·단위 lookup을 선로드하고 CRUD 처리, `FEATURE_PRODUCTS_ENABLED` 플래그가 꺼져 있으면 SpecPage만 노출)
- [ ] 창고: 목록/필터(q/사용), 신규/수정(우편번호 검색 모달 UI 연동) (현황: `WarehouseController` CRUD·상태 필터는 구현됐으나 우편번호 검색 모달/`PostalSearchPage` 연동이 없어 텍스트 수기 입력 상태)
- [x] 고객사: 목록/필터(q/유형/사용), 신규/수정(유형→is_partner/is_general 매핑 UI) (현황: 유형 스위치가 `is_partner/is_general`로 매핑되며 CRUD 흐름 구현, 우편번호 검색은 미연동)
- [x] 사용자: 목록/필터(q/그룹/사용), 신규/수정(사번RO) (현황: 그룹 lookup을 선로드하고 사번 필드 읽기 전용 처리, `FEATURE_USERS_ENABLED` 플래그 필요)
- [x] 그룹: 목록/필터(q/기본/사용), 신규/수정(그룹명RO) (현황: `GroupController`가 페이지네이션/검색/토스트까지 처리, 실제 API 응답 필요)
- [x] 메뉴: 목록/필터(q/상위/사용), 신규/수정(메뉴코드RO) (현황: 메뉴 트리 CRUD UI 구현, feature flag false 시 SpecPage 표시)
- [x] 그룹 권한: 목록/필터(그룹/메뉴/사용), 체크박스 매트릭스 편집 UI (현황: 그룹·메뉴 lookup + 권한 매트릭스 편집/일괄 저장 흐름 구현, 실제 API 응답 미연결)

## 7) 결재(UI)
- [x] 결재(`/approvals`): 목록/필터, 상세(개요/단계/이력 탭) (현황: `/approvals/requests` 라우트를 `ApprovalPage`로 연결하고 AppLayout/FilterBar·단계 탭/이력 탭 UI와 단계 행위·템플릿 적용까지 연동 완료, 신규 결재 버튼은 API 연동 시 확장 예정)
- [x] 템플릿 불러오기: 단계 탭에서 템플릿 선택 UI(단계 리스트 반영) (현황: 템플릿 목록 로딩·선택·확인 다이얼로그·`assignSteps` 호출로 단계 일괄 적용까지 구현, 템플릿 CRUD 화면과 연동되어 최신 목록/단계 구성이 반영됨)
- [x] 단계 행위: 승인/반려/코멘트 버튼(가능 여부 상태에 따라 비활성/툴팁) (현황: 단계 버튼·툴팁·행위 다이얼로그를 구현했고 `ApprovalRepository.performStepAction` 연동 완료, 권한 기반 노출/후속 알림은 TODO)
- [x] 단계 관리(`/approval-steps`): 목록/편집(신규/수정) (현황: 목록/필터 + 상세/신규/수정 모달 UI를 구현하고 컨트롤러에서 생성·수정 호출까지 연동, 삭제/권한 제어는 후속 예정)
- [x] 이력(`/approval-histories`): 조회 전용 테이블 (현황: AppLayout 기반 필터·페이지네이션 테이블과 기간 선택/엑셀 비활성 버튼까지 구현, 다운로드 API 연동은 후속 예정)
- [x] 템플릿(`/approval-templates`): 목록/헤더+단계 반복 폼 (현황: AppLayout + FilterBar + 페이지네이션 테이블과 생성/수정/삭제/복구 플로우를 구현했고 단계 등록 API까지 연동 완료, 승인자 자동완성·권한 제어 등 추가 UX는 후속 예정)

## 8) 우편번호 검색 모달(UI)
- [ ] 입력: 검색어 텍스트 (현황: `/utilities/postal-search` 라우트가 SpecPage만 노출, 실제 모달 위젯/상호작용 없음)
- [ ] 결과 테이블: 우편번호/시도/시군구/도로명/건물번호 (현황: 결과 렌더링 미구현)
- [ ] 선택 시: 부모 폼 `zipcode`/주소 구성요소 채움 (현황: Warehouse/Customer 폼과의 데이터 바인딩 미구현)

## 9) 보고서(`/reports`) UI
- [ ] 조건 폼: 기간/유형/창고/상태 (현황: `ReportingPage`를 AppLayout + FilterBar 플레이스홀더로 전환, 조건 버튼은 비활성 상태로 안내만 제공)
- [ ] 액션: XLSX/PDF 버튼 — 미제공 시 버튼 비활성 UI(연동은 API 단계에서) (현황: 헤더 액션에 비활성 버튼 배치, 실제 다운로드 연동과 상태 제어는 미구현)

## 10) 데이터 계층/상태 관리
- [ ] 리포지토리 인터페이스(domain) 정의 및 구현(data): 트랜잭션/결재/마스터/룩업/우편번호 (현황: 마스터·결재·UOM에 대한 domain/data 레이어만 존재하고 입·출·대여/보고서/우편번호 리포지토리 미정의)
- [ ] DTO ↔ 도메인 엔티티 매핑(응답 `{ items }`/`{ data }` 구조 표준화) (현황: 마스터/결재 DTO는 작성됐으나 인벤토리/보고서 DTO 부재, `{ data }` fallback 처리 통일 미완료)
- [ ] 페이지네이션 상태(현재 페이지/사이즈/전체) 및 필터 상태 싱크(go_router querystring 연동) (현황: 각 Controller가 내부 `PaginatedResult`만 유지하고 라우터 querystring과 동기화되지 않음)
- [ ] 정렬/검색/Include 옵션 직렬화 및 유지 (현황: 검색어만 로컬 상태로 보관하며 sort/include 파라미터 직렬화/복원 로직 없음)

## 11) API 연동 단계(Dio/ApiClient/DI)
- [ ] 네트워킹 패키지 추가: `dio:^5.x`, `pretty_dio_logger`(dev 선택), 토큰 저장용 `flutter_secure_storage`(모바일)/웹 스토리지 (현황: `dio`/`pretty_dio_logger`는 추가되어 사용 중이나 `flutter_secure_storage` 및 웹 스토리지 분기 미도입)
- [x] `ApiClient`/`AuthInterceptor` 스켈레톤 작성(설계: `doc/API_CLIENT_SPEC.md`) (현황: `lib/core/network/api_client.dart`, `interceptors/auth_interceptor.dart`에 기본 뼈대 구현, 토큰 주입/401 재시도 로직은 TODO 상태)
- [x] `Environment.initialize()` → `get_it` DI에서 ApiClient 생성/주입 (현황: `main.dart`에서 초기화 후 `injection_container.dart`가 `ApiClient`와 각 리포지토리를 등록)
- [ ] 공통 에러 매핑(400/404/409/422) 및 토스트/필드 바인딩 연결 (현황: Dio 예외 처리 공통화 미구현, 화면에서 개별 SnackBar만 사용)
- [ ] 메뉴/권한 로딩 → 버튼/액션 노출 제어 (현황: 권한 기반 노출 제어 미구현, feature flag만 사용)
- [ ] 각 화면 API 연결:
  - 입고/출고/대여: 목록/상세/생성/수정/삭제/복구 + include/필터/정렬/페이지네이션 (현황: `ShadTable`에 Mock 데이터 하드코딩, 리포지토리/DTO 부재)
  - 마스터: vendors/products/warehouses/customers/employees/menus/groups/group-permissions(+ 일괄 저장) (현황: 모든 마스터 화면이 `ApiClient` 기반 리포지토리로 CRUD/삭제·복구까지 호출하도록 작성되어 있으나 실제 엔드포인트 유효성 검증 필요)
  - 결재: approvals(+steps/histories), actions, can-proceed, 템플릿 CRUD/단계 배치 (현황: 템플릿 DTO/리포지토리/컨트롤러를 구현해 CRUD·단계 등록까지 API 연동이 완료됐고 나머지 결재 목록/이력/권한 제어는 진행 중)
  - 우편번호: `GET /zipcodes?...` (현황: 리포지토리/네트워킹 미구현)
  - 보고서: 다운로드 엔드포인트 연동(제공 시) (현황: 보고서 화면은 AppLayout 플레이스홀더 상태, API 연동과 다운로드 흐름 미구현)

## 12) 검증/접근성/상호작용
- [ ] 필수/형식/업무 규칙 검증(출고/대여 고객 최소 1건 등) (현황: 필수값 일부만 검사하고 수량/단가 ≥ 조건, 고객 최소 1건, 상태별 제한 등 업무 규칙 미구현)
- [ ] 키보드: Esc 닫기, Enter 제출/셀 이동, Tab 포커스 이동, 포커스 트랩 (현황: 기본 포커스만 제공되며 단축키/포커스 트랩 처리 미구현)
- [ ] 합계/요약 배지 실시간 반영(수량/단가 변경 시) (현황: 상세 카드에서 합계를 보여주지만 폼 입력 시 실시간 합산/배지 업데이트 없음)

## 13) 반응형/열 가시성
- [ ] 데스크톱/태블릿/모바일 프리셋 구현(PRD 섹션 12 규칙 적용) (현황: `widgets/components/responsive.dart`에 breakpoint 상수만 정의되어 있고 화면 적용 미진행)
- [ ] 모바일 카드형 요약(핵심 3~4필드) 구성 (현황: 모든 목록이 데스크톱 테이블만 제공)

## 14) 테스트/품질
- [x] `flutter analyze` 경고 0 (현황: 현재 소스는 analyzer 경고 없이 유지되나 기능 추가 시 재검증 필요)
- [x] 위젯 테스트: 테이블 렌더/필터/페이지네이션/모달 열기/검증 메시지 (현황: 마스터 위젯과 ApprovalTemplatePage 위젯 테스트까지 확보됐으며 인벤토리/보고서 영역은 여전히 미작성)
- [ ] 내비 통합 테스트(선택): 로그인 → 대시보드 → 입/출/대여 → 결재 → 마스터 (현황: 통합 테스트 미구현)
- [ ] `dart format .` 적용 (현황: 포맷 명령 자동화/검증 절차 부재)

## 15) Definition of Done(DoD)
- [ ] 모든 목록/폼/모달/필터/페이지네이션 동작 (현황: 마스터 일부 기능만 CRUD 동작, 인벤토리/결재/보고서는 스켈레톤 단계)
- [ ] 모바일/태블릿/데스크톱 레이아웃 검증(핵심 열 가시성) (현황: 반응형 레이아웃 미구현)
- [ ] 실제 API로 주요 플로우(신규/수정/삭제/복구) 검증 완료 (현황: 실제 백엔드와의 통합 테스트 결과 미확인)
- [ ] 문서 최신화(PRD/체크리스트) (현황: IMPLEMENTATION_TASKS.md는 진행 중이나 PRD/사양 문서와의 싱크 필요)

## 참고
- PRD: `doc/PRD_입출고_결재_v2.md`
- 사양: `doc/stock_approval_system_spec_v4.md`, `doc/stock_approval_system_api_v4.md`
- 네트워킹 설계: `doc/API_CLIENT_SPEC.md`
- 스타일 참조: `/Users/maximilian.j.sul/Documents/flutter/superport`