feat(approvals): Approval Flow v2 프런트엔드 전면 개편
- 환경/라우터 모듈에 approval_flow_v2 토글을 추가하고 FeatureFlags 초기화를 연결 (.env*, lib/core/**) - ApiClient 빌더·ApiRoutes 확장과 ApprovalRepositoryRemote 리팩터링으로 include·액션 시그니처를 정합화 - ApprovalFlow·ApprovalDraft 엔티티/레포/유즈케이스를 도입해 서버 초안과 단계 액션(승인·회수·재상신)을 지원 - Approval 컨트롤러·히스토리·템플릿 페이지와 공유 위젯을 재작성해 감사 로그·회수 UX·템플릿 CRUD를 반영 - Inbound/Outbound/Rental 컨트롤러·페이지에 결재 섹션을 삽입하고 대시보드 pending 카드 요약을 갱신 - SuperportDialog·FormField 등 공통 위젯을 보강하고 승인 위젯 가이드를 추가해 UI 가이드를 정리 - 결재/재고 테스트 픽스처와 단위·위젯·통합 테스트를 확장하고 flutter_test_config로 스테이징 호스트를 허용 - Approval Flow 레포트/플랜 문서를 업데이트하고 ApprovalFlow_System_Integration_and_ChangePlan.md를 추가 - 실행: flutter analyze, flutter test
This commit is contained in:
JiWoong Sul
82
lib/widgets/components/approval_widgets_guide.md
Normal file
82
lib/widgets/components/approval_widgets_guide.md
Normal file
@@ -0,0 +1,82 @@
|
||||
# 결재 UI 컴포넌트 가이드
|
||||
|
||||
입·출·대여 등록 화면과 결재 템플릿/이력 화면에서 재사용하는 결재 전용 위젯 모음이다. `ApprovalRequestController` 등 프레젠테이션 계층 컨트롤러와 결합하도록 설계됐으며, 공통 UI 구성 요소(`SuperportDialog`, `SuperportTable`, `SuperportFormField`)와 함께 사용하는 것을 전제로 한다.
|
||||
|
||||
## 1. 결재 단계 구성 섹션 — `ApprovalStepConfigurator`
|
||||
- 경로: `lib/features/approvals/request/presentation/widgets/approval_step_configurator.dart`
|
||||
- `ApprovalRequestController`를 주입하면 상신자·최종 승인자·중간 단계 목록을 요약 카드로 노출하고, “단계 구성 편집” 버튼을 통해 모달 편집기를 연다.
|
||||
- `readOnly`를 `true`로 설정하면 카드만 렌더링하고 편집 트리거는 비활성화된다.
|
||||
|
||||
```dart
|
||||
final controller = ApprovalRequestController(
|
||||
approvalUseCases: context.read<ApprovalUseCases>(),
|
||||
templateController: context.read<ApprovalTemplateController>(),
|
||||
);
|
||||
|
||||
ApprovalStepConfigurator(
|
||||
controller: controller,
|
||||
readOnly: state.isReadOnly,
|
||||
);
|
||||
```
|
||||
|
||||
모달은 `SuperportDialog` 위에서 동작하며, 승인자 검색에는 `ApproverAutocompleteField`를 재사용한다. 편집 완료 후 `controller.steps`에 반영된 값을 입·출·대여 제출 DTO 변환 시 그대로 넘겨야 한다.
|
||||
|
||||
## 2. 승인자 셀·상태 배지·메모 툴팁
|
||||
- 경로: `lib/features/approvals/shared/widgets/approval_ui_helpers.dart`
|
||||
- `ApprovalApproverCell`은 아바타(이니셜)·이름·사번을 테이블/다이얼로그에서 일관되게 표시하는 셀이다.
|
||||
- `ApprovalStatusBadge`는 백엔드에서 내려오는 HEX 색상에 맞춰 배경/테두리/텍스트색을 구성한다.
|
||||
- `ApprovalNoteTooltip`은 메모를 아이콘 툴팁으로 노출하고, 값이 없으면 플레이스홀더를 출력한다.
|
||||
|
||||
```dart
|
||||
final header = [
|
||||
ShadTableCell.header(child: const Text('승인자')),
|
||||
ShadTableCell.header(child: const Text('결재 상태')),
|
||||
ShadTableCell.header(child: const Text('메모')),
|
||||
];
|
||||
|
||||
final rows = approvals.map((approval) {
|
||||
return [
|
||||
ShadTableCell(
|
||||
child: ApprovalApproverCell(
|
||||
name: approval.approver.name,
|
||||
employeeNo: approval.approver.employeeNo,
|
||||
subtitle: approval.approver.role,
|
||||
),
|
||||
),
|
||||
ShadTableCell(
|
||||
child: ApprovalStatusBadge(
|
||||
label: approval.status.label,
|
||||
colorHex: approval.status.colorHex,
|
||||
),
|
||||
),
|
||||
ShadTableCell(
|
||||
child: ApprovalNoteTooltip(note: approval.note),
|
||||
),
|
||||
];
|
||||
}).toList();
|
||||
|
||||
return ShadTable.list(header: header, children: rows);
|
||||
```
|
||||
|
||||
## 3. 모달 편집기 구성 요소
|
||||
- `ApprovalStepRow`(`lib/features/approvals/request/presentation/widgets/approval_step_row.dart`): 단계 순서, 승인자 오토컴플릿, 역할, 삭제 버튼을 한 행으로 묶는다. `ApprovalRequestController`가 노출하는 `updateStep`/`removeStep` 콜백을 그대로 연결한다.
|
||||
- `ApprovalTemplatePicker`(`lib/features/approvals/request/presentation/widgets/approval_template_picker.dart`): 템플릿 목록과 미리보기를 제공하며, `ApprovalTemplateController`에서 주입된 상태를 바인딩한다. 저장 성공 시 `SuperportToast.success`로 토스트가 자동 표시된다.
|
||||
- `widgets.dart` 배럴 파일을 통해 `ApprovalStepConfigurator`, `ApprovalTemplatePicker`, `ApprovalStepRow`를 한 번에 export하므로 화면에서는 `import 'package:superport_v2/features/approvals/request/presentation/widgets/widgets.dart';` 형태로 불러온다.
|
||||
|
||||
```dart
|
||||
ApprovalTemplatePicker(
|
||||
controller: controller.templateController,
|
||||
onTemplateApplied: controller.applyTemplate,
|
||||
onTemplateCleared: controller.clearTemplate,
|
||||
);
|
||||
```
|
||||
|
||||
## 4. 도입 체크리스트
|
||||
- 결재 섹션을 추가하는 페이지에서는 `ApprovalRequestController.initializeWithTransaction`를 호출해 상신자/템플릿 스냅샷을 먼저 로딩한다.
|
||||
- 제출 단계에서 `controller.validate()` 결과를 확인하고, 실패 시 `errorMessage`를 `ApprovalStepConfigurator`가 표시해 준다.
|
||||
- 결재 이력/대시보드 테이블은 위 2절의 UI 헬퍼 조합을 사용해 승인자·상태·메모 UI를 통일한다.
|
||||
|
||||
샘플 구현 경로:
|
||||
- `lib/features/approvals/presentation/pages/approval_page.dart`
|
||||
- `lib/features/approvals/template/presentation/pages/approval_template_page.dart`
|
||||
- `lib/features/inventory/inbound/presentation/pages/inbound_page.dart` (결재 섹션 탭)
|
||||
@@ -116,10 +116,13 @@ class SuperportSkeletonList extends StatelessWidget {
|
||||
|
||||
/// 렌더링할 스켈레톤 행 개수.
|
||||
final int itemCount;
|
||||
|
||||
/// 각 항목 높이.
|
||||
final double height;
|
||||
|
||||
/// 행 사이 간격.
|
||||
final double gap;
|
||||
|
||||
/// 전체 패딩.
|
||||
final EdgeInsetsGeometry padding;
|
||||
|
||||
|
||||
@@ -19,16 +19,22 @@ class SuperportFormField extends StatelessWidget {
|
||||
|
||||
/// 폼 필드 라벨 텍스트.
|
||||
final String label;
|
||||
|
||||
/// 입력 영역으로 렌더링할 위젯.
|
||||
final Widget child;
|
||||
|
||||
/// 필수 여부. true면 라벨 옆에 `*` 표시를 추가한다.
|
||||
final bool required;
|
||||
|
||||
/// 보조 설명 문구. 에러가 없을 때만 출력된다.
|
||||
final String? caption;
|
||||
|
||||
/// 에러 메시지. 존재하면 캡션 대신 우선적으로 노출된다.
|
||||
final String? errorText;
|
||||
|
||||
/// 라벨 우측에 배치할 추가 위젯(예: 도움말 버튼).
|
||||
final Widget? trailing;
|
||||
|
||||
/// 라벨과 본문 사이 간격.
|
||||
final double spacing;
|
||||
|
||||
@@ -88,22 +94,31 @@ class SuperportTextInput extends StatelessWidget {
|
||||
});
|
||||
|
||||
final TextEditingController? controller;
|
||||
|
||||
/// 입력 없을 때 보여줄 플레이스홀더 위젯.
|
||||
final Widget? placeholder;
|
||||
|
||||
/// 입력 변경 콜백.
|
||||
final ValueChanged<String>? onChanged;
|
||||
|
||||
/// 제출(Enter) 시 호출되는 콜백.
|
||||
final ValueChanged<String>? onSubmitted;
|
||||
|
||||
/// 키보드 타입. 숫자/이메일 등으로 지정 가능.
|
||||
final TextInputType? keyboardType;
|
||||
|
||||
/// 입력 활성 여부.
|
||||
final bool enabled;
|
||||
|
||||
/// 읽기 전용 여부. true면 수정 불가.
|
||||
final bool readOnly;
|
||||
|
||||
/// 최대 줄 수. 1보다 크면 멀티라인 입력을 지원한다.
|
||||
final int maxLines;
|
||||
|
||||
/// 앞에 붙일 위젯 (아이콘 등).
|
||||
final Widget? leading;
|
||||
|
||||
/// 뒤에 붙일 위젯 (버튼 등).
|
||||
final Widget? trailing;
|
||||
|
||||
@@ -136,10 +151,13 @@ class SuperportSwitchField extends StatelessWidget {
|
||||
|
||||
/// 스위치 현재 상태.
|
||||
final bool value;
|
||||
|
||||
/// 상태 변경 시 호출되는 콜백.
|
||||
final ValueChanged<bool> onChanged;
|
||||
|
||||
/// 스위치 상단에 표시할 제목.
|
||||
final String? label;
|
||||
|
||||
/// 보조 설명 문구.
|
||||
final String? caption;
|
||||
|
||||
|
||||
@@ -2,6 +2,7 @@ import 'package:flutter/widgets.dart';
|
||||
|
||||
/// 데스크톱 레이아웃으로 간주할 최소 너비(px).
|
||||
const double desktopBreakpoint = 1200;
|
||||
|
||||
/// 태블릿 레이아웃을 구분하는 최소 너비(px).
|
||||
const double tabletBreakpoint = 960;
|
||||
|
||||
@@ -47,13 +48,16 @@ class ResponsiveBreakpoints {
|
||||
|
||||
/// 현재 뷰 가로 너비.
|
||||
final double width;
|
||||
|
||||
/// 너비에서 계산된 분기값.
|
||||
final DeviceBreakpoint breakpoint;
|
||||
|
||||
/// 모바일 범위인지 여부.
|
||||
bool get isMobile => breakpoint == DeviceBreakpoint.mobile;
|
||||
|
||||
/// 태블릿 범위인지 여부.
|
||||
bool get isTablet => breakpoint == DeviceBreakpoint.tablet;
|
||||
|
||||
/// 데스크톱 범위인지 여부.
|
||||
bool get isDesktop => breakpoint == DeviceBreakpoint.desktop;
|
||||
|
||||
@@ -75,8 +79,10 @@ class ResponsiveLayoutBuilder extends StatelessWidget {
|
||||
|
||||
/// 모바일 뷰에서 사용할 빌더.
|
||||
final WidgetBuilder mobile;
|
||||
|
||||
/// 태블릿 뷰에서 사용할 빌더. 제공되지 않으면 데스크톱 빌더를 재사용한다.
|
||||
final WidgetBuilder? tablet;
|
||||
|
||||
/// 데스크톱 뷰에서 사용할 빌더.
|
||||
final WidgetBuilder desktop;
|
||||
|
||||
@@ -114,8 +120,10 @@ class ResponsiveVisibility extends StatelessWidget {
|
||||
|
||||
/// 조건을 만족할 때 보여줄 실제 위젯.
|
||||
final Widget child;
|
||||
|
||||
/// 조건을 만족하지 않을 때 대체로 렌더링할 위젯.
|
||||
final Widget replacement;
|
||||
|
||||
/// 어떤 분기에서 child를 노출할지 정의한 집합.
|
||||
final Set<DeviceBreakpoint> visibleOn;
|
||||
|
||||
|
||||
@@ -42,6 +42,7 @@ class SuperportDialog extends StatelessWidget {
|
||||
this.insetPadding,
|
||||
this.onSubmit,
|
||||
this.enableFocusTrap = true,
|
||||
this.headerActions,
|
||||
});
|
||||
|
||||
final String title;
|
||||
@@ -62,6 +63,11 @@ class SuperportDialog extends StatelessWidget {
|
||||
final FutureOr<void> Function()? onSubmit;
|
||||
final bool enableFocusTrap;
|
||||
|
||||
/// 헤더 우측에 표시할 추가 액션 위젯 목록.
|
||||
///
|
||||
/// - 닫기 버튼 왼쪽에 순서대로 렌더링된다.
|
||||
final List<Widget>? headerActions;
|
||||
|
||||
/// 공통 다이얼로그를 노출하는 헬퍼. `showDialog`와 동일하게 동작한다.
|
||||
static Future<T?> show<T>({
|
||||
required BuildContext context,
|
||||
@@ -97,6 +103,7 @@ class SuperportDialog extends StatelessWidget {
|
||||
description: description,
|
||||
showCloseButton: showCloseButton,
|
||||
onClose: handleClose,
|
||||
actions: headerActions,
|
||||
);
|
||||
final resolvedFooter = footer ?? _buildFooter(context);
|
||||
|
||||
@@ -243,12 +250,14 @@ class _SuperportDialogHeader extends StatelessWidget {
|
||||
this.description,
|
||||
required this.showCloseButton,
|
||||
required this.onClose,
|
||||
this.actions,
|
||||
});
|
||||
|
||||
final String title;
|
||||
final String? description;
|
||||
final bool showCloseButton;
|
||||
final VoidCallback onClose;
|
||||
final List<Widget>? actions;
|
||||
|
||||
@override
|
||||
Widget build(BuildContext context) {
|
||||
@@ -276,6 +285,11 @@ class _SuperportDialogHeader extends StatelessWidget {
|
||||
],
|
||||
),
|
||||
),
|
||||
if (actions != null && actions!.isNotEmpty)
|
||||
Padding(
|
||||
padding: const EdgeInsets.only(right: 4, top: 2),
|
||||
child: Wrap(spacing: 8, runSpacing: 8, children: actions!),
|
||||
),
|
||||
if (showCloseButton)
|
||||
IconButton(
|
||||
icon: const Icon(lucide.LucideIcons.x, size: 18),
|
||||
@@ -306,6 +320,7 @@ Future<T?> showSuperportDialog<T>({
|
||||
VoidCallback? onClose,
|
||||
FutureOr<void> Function()? onSubmit,
|
||||
bool enableFocusTrap = true,
|
||||
List<Widget>? headerActions,
|
||||
}) {
|
||||
return SuperportDialog.show<T>(
|
||||
context: context,
|
||||
@@ -324,6 +339,7 @@ Future<T?> showSuperportDialog<T>({
|
||||
onClose: onClose,
|
||||
onSubmit: onSubmit,
|
||||
enableFocusTrap: enableFocusTrap,
|
||||
headerActions: headerActions,
|
||||
child: body,
|
||||
),
|
||||
);
|
||||
|
||||
Reference in New Issue
Block a user