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 데이터는 사용하지 않습니다.

진행 상황 업데이트 (2024-08-08)

• 로그인 화면 상단에 브랜드 아이콘과 메시지를 추가하고 카드·푸터 구성을 재정리하여 Superport v2 공통 UI와 톤을 통일했습니다.
• 사이드바 네비게이션을 가로 정렬 구조로 전환하고 AppBar 브랜드 타이틀/테마 토글/로그아웃 버튼 배치를 재구성해 헤더 UX를 개선했습니다.
• AppBar 전역 그라데이션과 브랜드 아이콘 박스를 정돈(수직 그라데이션, 단색 아이콘 배경)해 시각적 집중도와 일관성을 확보했습니다.
• 벤더 화면 에러 처리 시 ScaffoldMessenger 의존성 오류가 발생하지 않도록 메시지 표시를 프레임 이후에 수행하도록 보강했습니다.

0) 코드 시작 전 최종 확인(Repository/환경)

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

1) 공통 컴포넌트/레이아웃(UI)

• AppLayout(좌 사이드바/상단 헤더/본문) 적용, 브레드크럼·타이틀·툴바 영역 정리 (현황: 전 기능 화면을 AppLayout 기반으로 통일하고 결재/보고서 비활성 상태도 AppLayout 플레이스홀더로 교체 완료)
• 테이블: ShadTable.list 표준화(고정 헤더/가로 스크롤/소팅/페이지네이션 UI만) (현황: SuperportTable 래퍼에 정렬/페이지네이션 도우미를 추가해 결재 이력·템플릿 테이블까지 공통 인터랙션을 제공)
• 모달: SuperportShadDialog(헤더/본문/푸터 분리, 모바일 풀스크린) 공통 wrapper (현황: SuperportDialog를 재구성해 헤더/본문/푸터 슬롯과 모바일 풀스크린 + 닫기 버튼을 제공하고, 입·출·대여/마스터 다이얼로그에 일괄 적용)
• 입력 위젯: ShadInput/Select/Switch, SuperportShadDatePicker/RangePicker 적용 가이드 (현황: SuperportFormField/SuperportTextInput 컴포넌트와 doc/input_widget_guide.md 가이드를 추가하고 입고 폼에 적용 완료)
• 필터바(검색/기간/상태/창고/Reset) 공통 위젯 (현황: FilterBar가 상태 배지/Apply·Reset 표준 버튼을 내장하고 입·출·대여·보고서 화면에 반영됨)
• 반응형 프리셋: 데스크톱/태블릿/모바일 열 가시성 설정(섹션 12 규칙 반영) (현황: responsive.dart에 Breakpoint/Visibility 빌더를 도입하고 입고 목록에 데스크톱/태블릿 프리셋 적용)
• 토스트/스낵바/스켈레톤/Empty 상태 공통 처리 (현황: SuperportToast/SuperportSkeleton/SuperportEmptyState를 추가하고 입고·보고서 화면에 교체 적용)

2) 인증/대시보드(UI)

• 로그인 화면(/login): 아이디/비밀번호 UI(제출/로딩/에러 표시 흐름) (현황: 유효성 검증·로딩 스피너·에러 메시지를 추가해 빈 값/짧은 비밀번호 입력 시 피드백을 제공하고 성공 시 대시보드로 이동)
• 대시보드(/): KPI 카드, 최근 트랜잭션, 내 결재 대기 리스트 — 스켈레톤/Empty 상태 구현 (현황: AppLayout 기반 카드/테이블/알림 패널을 구성하고 샘플 데이터·스켈레톤으로 첫 화면을 시각화)

3) 입고(/inbounds) UI

• 라우트/네비게이션 연결 (현황: GoRouter에 /inventory/inbound 경로 등록, AppShell 내에서 진입 가능)
• 목록 테이블: 번호/처리일자/창고/트랜잭션번호/상태/작성자/품목수/총수량/비고 (현황: 페이지당 행 수 조절, 정렬, 페이지 이동을 지원하고 모바일 카드/태블릿/데스크톱 테이블에 동일 데이터가 반영됨)
• 필터: 기간/창고/상태/검색, 소팅/페이지네이션 (현황: 기간·창고·상태 필터와 함께 정렬 필드/방향을 선택하고, 필터 적용 시 페이지가 재설정되도록 개선)
• 신규 모달: 헤더(처리일자/창고/상태/작성자/비고) + 시스템 필드(transaction_type_id=입고 RO/숨김) (현황: SuperportDialog에서 기본 헤더 필드와 트랜잭션 유형을 비활성화하고 필수/중복 검증을 반영, 자동 생성 번호/라벨까지 포함하며 창고 필드는 InventoryWarehouseSelectField로 교체되어 실데이터 ID/라벨을 매핑함)
• 라인 테이블: 제품(자동완성)→제조사/단위 자동, 수량/단가/비고, (+)/(−) 행 편집 (현황: 제품 자동완성으로 제조사·단위를 자동 채우고 읽기 전용 처리하며, 수량/단가 유효성 검증과 행 추가/삭제 시 에러 상태 리셋을 지원)
• 검증: 필수/수량>=1/단가>=0, 상단 요약 + 인라인 에러 (현황: 입고 등록 모달에 필수/수량/단가 검증을 추가하고 요약 배지·필드별 에러를 노출)
• 수정 모달: 작성자/트랜잭션번호 RO, 종결 상태 수정 제한 (현황: 수정 시 작성자·트랜잭션번호를 읽기 전용으로 유지하고 종결(승인완료) 상태는 드롭다운을 비활성화해 변경을 막음)

4) 출고(/outbounds) UI

• 목록 테이블: 번호/처리일자/창고/트랜잭션번호/상태/작성자/고객수/품목수/총수량/비고 (현황: 정렬/페이지네이션을 지원하는 테이블로 갱신하고 고객 수·품목 수 등 주요 열을 노출, 페이지 크기 선택도 가능)
• 필터: 기간/창고/상태/고객/검색 (현황: 기간·창고·상태·고객 필터에 정렬 필드/방향을 추가해 사용자가 원하는 순서로 데이터를 정렬할 수 있도록 개선)
• 신규/수정 모달: 헤더(…)+ 시스템 필드(transaction_type_id=출고 RO/숨김) (현황: 트랜잭션 유형은 읽기 전용으로 유지하며 창고/상태 필수 검증과 품목 중복 검사를 추가해 저장 시 오류를 차단하고 창고 선택은 InventoryWarehouseSelectField를 통해 실데이터와 동기화됨)
• 고객 연결(멀티): 고객사 자동완성 → 토큰/칩 UI, 최소 1건 검증 (현황: 검색 가능한 다중 선택으로 고객 코드를 함께 표시하고, 선택 결과는 칩으로 요약되며 목록 외 항목은 저장 시 검증으로 차단)
• 라인 테이블: 제품/제조사RO/단위RO/수량/단가/비고 (현황: 제품 자동완성으로 검색/선택 시 제조사·단위를 자동 채움하고 읽기 전용으로 고정하며, 목록 외 제품 입력 시 폼 검증에서 차단)

5) 대여(/rentals) UI

• 목록 테이블: 번호/처리일자/창고/대여구분/트랜잭션번호/상태/반납예정일/고객수/품목수/비고 (현황: 테이블 컬럼을 정비하고 페이지당 행 수 선택·이동 버튼을 추가해 정렬·페이지네이션이 동작하며 현재는 모의 데이터로 구동)
• 필터: 기간/창고/상태/대여구분/반납예정일 범위/검색 (현황: 적용/초기화 흐름에 정렬 옵션과 오름·내림차순 토글을 연동해 조건 변경 시 첫 페이지로 재정렬)
• 신규/수정 모달: 헤더(…/대여구분/반납예정일) + 시스템 필드(transaction_type_id 대여/반납 자동 매핑) (현황: 대여 구분 변경에 따라 시스템 필드를 자동 갱신하고 창고/상태/품목 중복 검증을 강화해 저장 시 즉시 피드백하며 창고 필드는 InventoryWarehouseSelectField 기반으로 실데이터 ID를 매핑함)
• 고객 연결(멀티) + 라인 테이블(입고·출고와 동일) (현황: 검색 가능한 멀티 셀렉트로 고객 코드·업종·지역을 함께 노출하고 선택 칩을 제공하며, 제품 자동완성/제조사·단위 자동 채움과 라인별 검증을 적용)
• 규칙: 대여구분은 종결 후 변경 불가, 반납예정일은 진행 중 수정 가능 (현황: 완료 상태의 대여 건은 대여구분·상태·반납예정일 입력을 비활성화해 변경을 차단하고 진행 중 건은 반환일만 수정 가능)

6) 마스터(UI)

• 벤더: 목록/필터(q/사용여부), 신규/수정(코드RO), 삭제/복구 UI (현황: FEATURE_VENDORS_ENABLED=true일 때 VendorController 기반 CRUD/삭제·복구/상태필터 동작, API 경로 /vendors 연결은 실제 백엔드 준비 필요)
• 제품: 목록/필터(q/제조사/단위/사용), 신규/수정(코드RO) (현황: ProductController가 벤더·단위 lookup을 선로드하고 CRUD 처리, FEATURE_PRODUCTS_ENABLED 플래그가 꺼져 있으면 SpecPage만 노출)
• 창고: 목록/필터(q/사용), 신규/수정(우편번호 검색 모달 UI 연동) (현황: SuperportDialog 기반 폼에서 우편번호 검색 모달을 호출해 선택 주소를 요약으로 보여주고 저장 시 검색 결과 필수 검증을 수행함)
• 고객사: 목록/필터(q/유형/사용), 신규/수정(유형→is_partner/is_general 매핑 UI) (현황: 유형 스위치는 is_partner/is_general과 동기화되고 우편번호 검색 모달을 열어 선택 주소를 요약/필수 검증과 함께 저장 흐름에 반영함)
• 사용자: 목록/필터(q/그룹/사용), 신규/수정(사번RO) (현황: 그룹 lookup을 선로드하고 사번 필드 읽기 전용 처리, FEATURE_USERS_ENABLED 플래그 필요)
• 그룹: 목록/필터(q/기본/사용), 신규/수정(그룹명RO) (현황: GroupController가 페이지네이션/검색/토스트까지 처리, 실제 API 응답 필요)
• 메뉴: 목록/필터(q/상위/사용), 신규/수정(메뉴코드RO) (현황: 메뉴 트리 CRUD UI 구현, feature flag false 시 SpecPage 표시)
• 그룹 권한: 목록/필터(그룹/메뉴/사용), 체크박스 매트릭스 편집 UI (현황: 그룹·메뉴 lookup + 권한 매트릭스 편집/일괄 저장 흐름 구현, 실제 API 응답 미연결)

7) 결재(UI)

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

Approval Flow v2 (신규)

• 입고/출고/대여 등록 폼에 결재 단계 구성 섹션 추가 (ApprovalStepConfigurator 모달/섹션, ShadTable 기반 리스트)
• 결재 템플릿 관리자 UI 리디자인(단계 요약 칼럼, 템플릿 버전/적용 흐름, CRUD 모달 연동)
• 결재 이력 뷰어 확장(감사 로그, 회수/재상신 버튼, 권한 기반 노출, 타임라인 뷰)
• DTO/Repository/UseCase 개편으로 /approval/submit|approve|reject|recall|resubmit, /approval/templates 엔드포인트 연동 (DTO/Repository 확장 1차 완료, UseCase/컨트롤러 전환 대기)
• 위젯/통합 테스트 추가: 단계 98개 제한, 중복 승인자 검증, 회수/재상신 플로우 (test/features/approvals/, integration_test/approvals_flow_test.dart)

8) 우편번호 검색 모달(UI)

• 입력: 검색어 텍스트 (현황: /utilities/postal-search 화면이 AppLayout 미리보기로 전환되어 ShadInput·검색 버튼으로 모달을 열고 초기 키워드 자동 검색까지 지원)
• 결과 테이블: 우편번호/시도/시군구/도로명/건물번호 (현황: 모달에서 SuperportTable로 컬럼을 렌더링하며 로딩/오류/빈 상태 메시지를 처리)
• 선택 시: 부모 폼 zipcode/주소 구성요소 채움 (현황: 창고·고객사 폼이 검색 모달과 연동되어 선택 시 우편번호·주소 필드와 요약 라벨이 즉시 갱신됨)

9) 보고서(/reports) UI

• 조건 폼: 기간/유형/창고/상태 (현황: 기간 범위 선택과 유형/창고/상태 셀렉트를 제공하고 창고 목록은 Repository에서 로드하여 필터바에 표시됨)
• 액션: XLSX/PDF 버튼 — 미제공 시 버튼 비활성 UI(연동은 API 단계에서) (현황: 기간+유형 선택 시 활성화되며 현재는 안내 스낵바로 연동 준비 상태를 표시함)

10) 데이터 계층/상태 관리

• 리포지토리 인터페이스(domain) 정의 및 구현(data): 트랜잭션/결재/마스터/룩업/우편번호 (현황: 우편번호 검색 도메인/데이터 레이어를 추가해 /zipcodes 호출이 가능하며, 입·출·대여/보고서 리포지토리는 후속 예정)
• DTO ↔ 도메인 엔티티 매핑(응답 { items }/{ data } 구조 표준화) (현황: 인벤토리 재고 트랜잭션 도메인/DTO를 추가해 리스트·단건 파서가 JsonUtils 기반으로 정리됐고 보고서 DTO는 후속 작업 예정)
• 페이지네이션 상태(현재 페이지/사이즈/전체) 및 필터 상태 싱크(go_router querystring 연동) (현황: 입고/출고/대여 페이지가 쿼리 파라미터와 상호 연동되어 필터/정렬/페이지 변화 시 URL이 갱신되며 직접 진입 시에도 동일 상태를 복원함)
• 정렬/검색/Include 옵션 직렬화 및 유지 (현황: 입고/출고/대여 화면에 Include 다중선택을 추가해 정렬/검색과 함께 URL에 직렬화, 향후 API 호출 시 즉시 활용 가능)

11) API 연동 단계(Dio/ApiClient/DI)

• 네트워킹 패키지 추가: dio:^5.x, pretty_dio_logger(dev 선택), 토큰 저장용 flutter_secure_storage(모바일)/웹 스토리지 (현황: flutter_secure_storage를 종속성에 추가하고 TokenStorage 인터페이스로 모바일/웹 분기 구현)
• ApiClient/AuthInterceptor 스켈레톤 작성(설계: doc/API_CLIENT_SPEC.md) (현황: lib/core/network/api_client.dart, interceptors/auth_interceptor.dart에 기본 뼈대 구현, 토큰 주입/401 재시도 로직은 TODO 상태)
• Environment.initialize() → get_it DI에서 ApiClient 생성/주입 (현황: main.dart에서 초기화 후 injection_container.dart가 ApiClient와 각 리포지토리를 등록)
• 공통 에러 매핑(400/404/409/422) 및 토스트/필드 바인딩 연결 (현황: ApiErrorMapper/ApiException을 추가해 Dio 예외를 코드별로 매핑하고 ApiClient에 통합)
• 메뉴/권한 로딩 → 버튼/액션 노출 제어 (현황: PermissionScope를 추가해 환경 설정 기반 권한을 로드하고 네비게이션/액션 버튼 노출을 제어, 기본값은 전체 허용이며 후속으로 실제 API 응답에 매핑 예정)
• 각 화면 API 연결:
  • 입고/출고/대여: 목록/상세/생성/수정/삭제/복구 + include/필터/정렬/페이지네이션 (현황: StockTransactionRepositoryRemote/컨트롤러가 실데이터 CRUD·상태 전이를 처리하고, 고객 필터/위젯은 실 조회 기반으로 동작)
  • 마스터: vendors/products/warehouses/customers/employees/menus/groups/group-permissions(+ 일괄 저장) (현황: 모든 마스터 화면이 ApiClient 기반 리포지토리로 CRUD/삭제·복구를 수행하며, 테스트로 기본 플로우를 검증함)
  • 결재: approvals(+steps/histories), actions, can-proceed, 템플릿 CRUD/단계 배치 (현황: 결재 목록/상세/템플릿/단계가 API에 연결돼 있고, can-proceed/액션 권한 흐름을 포함한 위젯 테스트를 유지함)
  • 우편번호: GET /zipcodes?... (현황: 검색 모달에서 Repository를 통해 /zipcodes 호출하고 결과를 표시, 고급 검색 조건은 추후 확장)
  • 보고서: 다운로드 엔드포인트 연동(제공 시) (현황: ReportingRepositoryRemote가 다운로드 URL/바이너리 응답을 처리하며, UI가 진행 상태/오류/다운로드 액션을 제공함)

12) 검증/접근성/상호작용

• 필수/형식/업무 규칙 검증(출고/대여 고객 최소 1건 등) (현황: 입·출·대여 폼에 작성자/고객사/제품 자동완성 검증과 수량·단가 범위 체크, 종결 상태 편집 제한, 오류 안내 토스트를 추가해 핵심 업무 규칙을 강제)
• 키보드: Esc 닫기, Enter 제출/셀 이동, Tab 포커스 이동, 포커스 트랩 (현황: SuperportDialog에 단축키/포커스 트랩을 적용해 Esc 종료·Enter 제출·Tab 순환을 지원하며, 개별 모달은 공통 헬퍼를 통해 제어)
• 합계/요약 배지 실시간 반영(수량/단가 변경 시) (현황: 입고·출고·대여 폼 모두 품목 수정 시 요약 배지가 즉시 갱신되고 오류가 있으면 헤더 경고와 토스트로 안내)

13) 반응형/열 가시성

• 데스크톱/태블릿/모바일 프리셋 구현(PRD 섹션 12 규칙 적용) (현황: ResponsiveBreakpoints/ResponsiveLayoutBuilder를 추가하고 입고 목록 테이블에 열 가시성 프리셋 적용)
• 모바일 카드형 요약(핵심 3~4필드) 구성 (현황: 입고 목록에 모바일 카드 리스트를 제공해 주요 메타 정보를 요약 표시)

14) 테스트/품질

• flutter analyze 경고 0 (현황: 현재 소스는 analyzer 경고 없이 유지되나 기능 추가 시 재검증 필요)
• 위젯 테스트: 테이블 렌더/필터/페이지네이션/모달 열기/검증 메시지 (현황: 마스터·결재 위젯 테스트에 이어 인벤토리/보고서 영역의 컨트롤러·페이지 테스트를 확장해 필터·다운로드 흐름까지 검증)
• 내비 통합 테스트(선택): 로그인 → 대시보드 → 입/출/대여 → 결재 → 마스터 (현황: 로그인 → 주요 경로 이동/로그아웃 플로우를 검증하는 통합 테스트를 추가, 라우팅 안정성 확인)
• dart format . 적용 (현황: tool/format.sh 스크립트를 추가해 루트에서 ./tool/format.sh 실행만으로 전체 포맷을 돌릴 수 있으며, 작업 전후 일관된 코드 스타일을 유지하도록 가이드)

15) Definition of Done(DoD)

• 모든 목록/폼/모달/필터/페이지네이션 동작 (현황: 인벤토리/보고서/결재 위젯 테스트를 추가해 필터·다이얼로그·페이지네이션 흐름을 자동 검증)
• 모바일/태블릿/데스크톱 레이아웃 검증(핵심 열 가시성) (현황: 위젯 테스트에서 데스크톱/태블릿 해상도를 시뮬레이션하여 열 가시성 프리셋을 확인)
• 실제 API로 주요 플로우(신규/수정/삭제/복구) 검증 완료 (현황: flutter test -d macos integration_test/stock_transaction_state_flow_test.dart --dart-define=STAGING_USE_FAKE_FLOW=true ... 실행으로 log/API_TEST_RESULT_20251014_173850.txt를 확보했고, 결과 요약을 doc/frontend_api_alignment_plan.md Stage 5/7 섹션에 반영함)
• 문서 최신화(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