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
2025-10-31 01:05:39 +09:00
parent 259b056072
commit d76f765814
133 changed files with 13878 additions and 947 deletions
--- a/lib/features/inventory/inbound/domain/entities/create_inbound_request_input.dart
+++ b/lib/features/inventory/inbound/domain/entities/create_inbound_request_input.dart
@@ -0,0 +1,43 @@
+import '../../../transactions/domain/entities/stock_transaction_input.dart';
+
+/// 입고 생성 요청 입력 값.
+///
+/// - 재고 트랜잭션 생성에 필요한 필드와 결재 구성을 함께 전달한다.
+class CreateInboundRequestInput {
+  CreateInboundRequestInput({
+    required this.transactionTypeId,
+    required this.transactionStatusId,
+    required this.warehouseId,
+    required this.transactionDate,
+    required this.createdById,
+    required this.approval,
+    this.note,
+    this.lines = const [],
+    this.customers = const [],
+  });
+
+  final int transactionTypeId;
+  final int transactionStatusId;
+  final int warehouseId;
+  final DateTime transactionDate;
+  final int createdById;
+  final String? note;
+  final List<TransactionLineCreateInput> lines;
+  final List<TransactionCustomerCreateInput> customers;
+  final StockTransactionApprovalInput approval;
+
+  /// 재고 트랜잭션 생성 입력 모델로 변환한다.
+  StockTransactionCreateInput toTransactionInput() {
+    return StockTransactionCreateInput(
+      transactionTypeId: transactionTypeId,
+      transactionStatusId: transactionStatusId,
+      warehouseId: warehouseId,
+      transactionDate: transactionDate,
+      createdById: createdById,
+      note: note,
+      lines: lines,
+      customers: customers,
+      approval: approval,
+    );
+  }
+}
--- a/lib/features/inventory/inbound/presentation/controllers/inbound_controller.dart
+++ b/lib/features/inventory/inbound/presentation/controllers/inbound_controller.dart
@@ -1,8 +1,13 @@
+import 'dart:async';
 import 'dart:collection';

 import 'package:flutter/foundation.dart';
 import 'package:superport_v2/core/common/models/paginated_result.dart';
 import 'package:superport_v2/core/network/failure.dart';
+import 'package:superport_v2/features/approvals/domain/entities/approval_draft.dart';
+import 'package:superport_v2/features/approvals/domain/usecases/get_approval_draft_use_case.dart';
+import 'package:superport_v2/features/approvals/domain/usecases/list_approval_drafts_use_case.dart';
+import 'package:superport_v2/features/approvals/domain/usecases/save_approval_draft_use_case.dart';
 import 'package:superport_v2/features/inventory/inbound/presentation/models/inbound_record.dart';
 import 'package:superport_v2/features/inventory/lookups/domain/entities/lookup_item.dart';
 import 'package:superport_v2/features/inventory/lookups/domain/repositories/inventory_lookup_repository.dart';
@@ -20,10 +25,16 @@ class InboundController extends ChangeNotifier {
    required InventoryLookupRepository lookupRepository,
    List<String> fallbackStatusOptions = const ['작성중', '승인대기', '승인완료'],
    List<String> transactionTypeKeywords = const ['입고', 'inbound'],
+    SaveApprovalDraftUseCase? saveDraftUseCase,
+    GetApprovalDraftUseCase? getDraftUseCase,
+    ListApprovalDraftsUseCase? listDraftsUseCase,
  }) : _transactionRepository = transactionRepository,
       _lineRepository = lineRepository,
       _customerRepository = customerRepository,
       _lookupRepository = lookupRepository,
+       _saveDraftUseCase = saveDraftUseCase,
+       _getDraftUseCase = getDraftUseCase,
+       _listDraftsUseCase = listDraftsUseCase,
       _fallbackStatusOptions = List<String>.unmodifiable(
         fallbackStatusOptions,
       ),
@@ -37,6 +48,9 @@ class InboundController extends ChangeNotifier {
  final TransactionLineRepository _lineRepository;
  final TransactionCustomerRepository _customerRepository;
  final InventoryLookupRepository _lookupRepository;
+  final SaveApprovalDraftUseCase? _saveDraftUseCase;
+  final GetApprovalDraftUseCase? _getDraftUseCase;
+  final ListApprovalDraftsUseCase? _listDraftsUseCase;
  final List<String> _fallbackStatusOptions;
  final List<String> _transactionTypeKeywords;

@@ -51,6 +65,7 @@ class InboundController extends ChangeNotifier {
  final Set<int> _processingTransactionIds = <int>{};
  List<LookupItem> _approvalStatuses = const [];
  LookupItem? _defaultApprovalStatus;
+  StockTransactionApprovalInput? _approvalDraft;

  UnmodifiableListView<String> get statusOptions =>
      UnmodifiableListView(_statusOptions);
@@ -78,6 +93,7 @@ class InboundController extends ChangeNotifier {

  UnmodifiableSetView<int> get processingTransactionIds =>
      UnmodifiableSetView(_processingTransactionIds);
+  StockTransactionApprovalInput? get approvalDraft => _approvalDraft;

  /// 트랜잭션 상태 목록을 서버에서 읽어온다.
  Future<void> loadStatusOptions() async {
@@ -139,6 +155,64 @@ class InboundController extends ChangeNotifier {
    }
  }

+  /// 결재 구성 초안 상태를 갱신한다.
+  void updateApprovalDraft(StockTransactionApprovalInput approval) {
+    _approvalDraft = approval;
+    notifyListeners();
+    _persistApprovalDraft(approval);
+  }
+
+  /// 결재 구성 초안을 초기화한다.
+  void clearApprovalDraft() {
+    if (_approvalDraft == null) {
+      return;
+    }
+    _approvalDraft = null;
+    notifyListeners();
+  }
+
+  Future<void> loadApprovalDraftFromServer({
+    required int requesterId,
+    int? transactionId,
+  }) async {
+    final listUseCase = _listDraftsUseCase;
+    final getUseCase = _getDraftUseCase;
+    if (listUseCase == null || getUseCase == null) {
+      return;
+    }
+    try {
+      final result = await listUseCase.call(
+        ApprovalDraftListFilter(
+          requesterId: requesterId,
+          transactionId: transactionId,
+          pageSize: 10,
+        ),
+      );
+      if (result.items.isEmpty) {
+        return;
+      }
+      final sessionKey = _draftSessionKey(
+        requesterId,
+        transactionId: transactionId,
+      );
+      final summary = result.items.firstWhere(
+        (item) => item.sessionKey == sessionKey,
+        orElse: () => result.items.first,
+      );
+      final detail = await getUseCase.call(
+        id: summary.id,
+        requesterId: requesterId,
+      );
+      if (detail == null) {
+        return;
+      }
+      _approvalDraft = _toTransactionApproval(detail);
+      notifyListeners();
+    } catch (error, stackTrace) {
+      debugPrint('[InboundController] 초안 복구 실패: $error\n$stackTrace');
+    }
+  }
+
  /// 필터에 맞는 입고 트랜잭션 목록을 조회한다.
  Future<void> fetchTransactions({
    required StockTransactionListFilter filter,
@@ -179,6 +253,84 @@ class InboundController extends ChangeNotifier {
    await fetchTransactions(filter: target);
  }

+  void _persistApprovalDraft(StockTransactionApprovalInput approval) {
+    final useCase = _saveDraftUseCase;
+    if (useCase == null) {
+      return;
+    }
+    if (approval.steps.isEmpty) {
+      return;
+    }
+    final input = _buildApprovalDraftSaveInput(approval);
+    if (!input.hasSteps) {
+      return;
+    }
+    unawaited(
+      Future<void>(() async {
+        try {
+          await useCase.call(input);
+        } catch (error, stackTrace) {
+          debugPrint('[InboundController] 초안 저장 실패: $error\n$stackTrace');
+        }
+      }),
+    );
+  }
+
+  ApprovalDraftSaveInput _buildApprovalDraftSaveInput(
+    StockTransactionApprovalInput approval,
+  ) {
+    final steps = approval.steps
+        .map(
+          (step) => ApprovalDraftStep(
+            stepOrder: step.stepOrder,
+            approverId: step.approverId,
+            note: step.note,
+          ),
+        )
+        .toList(growable: false);
+    return ApprovalDraftSaveInput(
+      requesterId: approval.requestedById,
+      transactionId: null,
+      templateId: approval.templateId,
+      title: approval.title,
+      summary: approval.summary,
+      note: approval.note,
+      metadata: approval.metadata,
+      sessionKey: _draftSessionKey(approval.requestedById),
+      statusId: approval.approvalStatusId,
+      steps: steps,
+    );
+  }
+
+  String _draftSessionKey(int requesterId, {int? transactionId}) {
+    final base = 'inventory_inbound_$requesterId';
+    if (transactionId == null) {
+      return base;
+    }
+    return '${base}_$transactionId';
+  }
+
+  StockTransactionApprovalInput _toTransactionApproval(
+    ApprovalDraftDetail detail,
+  ) {
+    final submission = detail.toSubmissionInput(defaultStatusId: null);
+    return StockTransactionApprovalInput(
+      requestedById: submission.requesterId,
+      approvalStatusId: submission.statusId == 0 ? null : submission.statusId,
+      templateId: submission.templateId,
+      finalApproverId: submission.finalApproverId,
+      requestedAt: submission.requestedAt,
+      decidedAt: submission.decidedAt,
+      cancelledAt: submission.cancelledAt,
+      lastActionAt: submission.lastActionAt,
+      title: submission.title,
+      summary: submission.summary,
+      note: submission.note,
+      metadata: submission.metadata,
+      steps: submission.steps,
+    );
+  }
+
  LookupItem? _resolveDefaultApprovalStatus(List<LookupItem> items) {
    for (final item in items) {
      if (item.isDefault) {
@@ -194,6 +346,7 @@ class InboundController extends ChangeNotifier {
    bool refreshAfter = true,
    StockTransactionListFilter? refreshFilter,
  }) {
+    _approvalDraft = input.approval;
    return _executeMutation(
      () => _transactionRepository.create(input),
      refreshAfter: refreshAfter,
--- a/lib/features/inventory/inbound/presentation/pages/inbound_page.dart
+++ b/lib/features/inventory/inbound/presentation/pages/inbound_page.dart
@@ -17,6 +17,13 @@ import 'package:superport_v2/widgets/components/superport_date_picker.dart';
 import 'package:superport_v2/features/inventory/shared/widgets/partner_select_field.dart';
 import 'package:superport_v2/features/inventory/shared/widgets/product_autocomplete_field.dart';
 import 'package:superport_v2/features/inventory/shared/widgets/warehouse_select_field.dart';
+import 'package:superport_v2/features/approvals/request/presentation/controllers/approval_request_controller.dart';
+import 'package:superport_v2/features/approvals/request/presentation/utils/approval_form_initializer.dart';
+import 'package:superport_v2/features/approvals/request/presentation/widgets/approval_step_configurator.dart';
+import 'package:superport_v2/features/approvals/request/presentation/widgets/approval_template_picker.dart';
+import 'package:superport_v2/features/approvals/domain/usecases/get_approval_draft_use_case.dart';
+import 'package:superport_v2/features/approvals/domain/usecases/list_approval_drafts_use_case.dart';
+import 'package:superport_v2/features/approvals/domain/usecases/save_approval_draft_use_case.dart';
 import 'package:superport_v2/core/config/environment.dart';
 import 'package:superport_v2/core/network/failure.dart';
 import 'package:superport_v2/core/permissions/permission_manager.dart';
@@ -126,6 +133,15 @@ class _InboundPageState extends State<InboundPage> {
      lookupRepository: getIt<InventoryLookupRepository>(),
      fallbackStatusOptions: InboundTableSpec.fallbackStatusOptions,
      transactionTypeKeywords: InboundTableSpec.transactionTypeKeywords,
+      saveDraftUseCase: getIt.isRegistered<SaveApprovalDraftUseCase>()
+          ? getIt<SaveApprovalDraftUseCase>()
+          : null,
+      getDraftUseCase: getIt.isRegistered<GetApprovalDraftUseCase>()
+          ? getIt<GetApprovalDraftUseCase>()
+          : null,
+      listDraftsUseCase: getIt.isRegistered<ListApprovalDraftsUseCase>()
+          ? getIt<ListApprovalDraftsUseCase>()
+          : null,
    );
  }

@@ -137,6 +153,10 @@ class _InboundPageState extends State<InboundPage> {
    Future.microtask(() async {
      await controller.loadStatusOptions();
      await controller.loadApprovalStatuses();
+      final requester = _resolveCurrentWriter();
+      if (requester != null) {
+        await controller.loadApprovalDraftFromServer(requesterId: requester.id);
+      }
      final hasType = await controller.resolveTransactionType();
      if (!mounted) {
        return;
@@ -1483,6 +1503,25 @@ class _InboundPageState extends State<InboundPage> {
      return '${suggestion.name} (${suggestion.employeeNo})';
    }

+    final approvalController = ApprovalRequestController();
+    final defaultRequester = () {
+      final writer = writerSelection;
+      if (writer == null) {
+        return null;
+      }
+      return ApprovalRequestParticipant(
+        id: writer.id,
+        name: writer.name,
+        employeeNo: writer.employeeNo,
+      );
+    }();
+    ApprovalFormInitializer.populate(
+      controller: approvalController,
+      existingApproval: initial?.raw?.approval,
+      draft: _controller?.approvalDraft,
+      defaultRequester: defaultRequester,
+    );
+
    final writerController = TextEditingController(
      text: writerLabel(writerSelection),
    );
@@ -1718,6 +1757,23 @@ class _InboundPageState extends State<InboundPage> {
          return;
        }

+        StockTransactionApprovalInput approvalInput;
+        try {
+          approvalInput = approvalController.buildTransactionApprovalInput(
+            approvalStatusId: approvalStatusId,
+            note: approvalNoteValue.isEmpty ? null : approvalNoteValue,
+          );
+        } on StateError catch (error) {
+          updateSaving(false);
+          SuperportToast.error(context, error.message);
+          return;
+        } catch (_) {
+          updateSaving(false);
+          SuperportToast.error(context, '결재 구성을 확인하고 다시 시도하세요.');
+          return;
+        }
+        controller.updateApprovalDraft(approvalInput);
+
        final createLines = lineDrafts
            .map(
              (draft) => TransactionLineCreateInput(
@@ -1738,11 +1794,7 @@ class _InboundPageState extends State<InboundPage> {
          note: remarkValue,
          lines: createLines,
          customers: createCustomers,
-          approval: StockTransactionApprovalInput(
-            requestedById: createdById,
-            approvalStatusId: approvalStatusId,
-            note: approvalNoteValue.isEmpty ? null : approvalNoteValue,
-          ),
+          approval: approvalInput,
        );
        assert(() {
          debugPrint(
@@ -1995,6 +2047,15 @@ class _InboundPageState extends State<InboundPage> {
                    ),
                  ],
                ),
+                const SizedBox(height: 16),
+                if (initial == null) ...[
+                  ApprovalTemplatePicker(controller: approvalController),
+                  const SizedBox(height: 16),
+                ],
+                ApprovalStepConfigurator(
+                  controller: approvalController,
+                  readOnly: initial != null,
+                ),
                const SizedBox(height: 24),
                if (headerNotice != null)
                  Padding(
@@ -2112,6 +2173,7 @@ class _InboundPageState extends State<InboundPage> {
    final disposeApprovalNoteController = approvalNoteController;
    final disposeTransactionTypeController = transactionTypeController;
    final disposeProcessedAt = processedAt;
+    final disposeApprovalController = approvalController;

    WidgetsBinding.instance.addPostFrameCallback((_) {
      for (final draft in disposeDrafts) {
@@ -2123,6 +2185,7 @@ class _InboundPageState extends State<InboundPage> {
      disposeApprovalNoteController.dispose();
      disposeTransactionTypeController.dispose();
      disposeProcessedAt.dispose();
+      disposeApprovalController.dispose();
    });

    return result;