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

lib/core/config/environment.dart

@@ -1,6 +1,8 @@
 import 'package:flutter/foundation.dart';
 import 'package:flutter_dotenv/flutter_dotenv.dart';
 
+import 'package:superport_v2/core/config/feature_flags.dart';
+
 /// 환경 설정 로더
 ///
 /// - .env.development / .env.production 파일을 로드하여 런타임 설정을 주입한다.
@@ -57,6 +59,7 @@ class Environment {
     }
 
     baseUrl = dotenv.maybeGet('API_BASE_URL') ?? 'http://localhost:8080';
+    FeatureFlags.initialize();
     _loadPermissions();
   }
 

lib/core/config/feature_flags.dart

@@ -0,0 +1,75 @@
+import 'package:flutter_dotenv/flutter_dotenv.dart';
+
+/// 기능 토글을 중앙에서 관리한다.
+///
+/// - `Environment.initialize` 후 `FeatureFlags.initialize()`가 호출되어야 한다.
+/// - 백엔드의 `feature.*` 키와 기존 `FEATURE_*` 키를 모두 지원한다.
+class FeatureFlags {
+  FeatureFlags._();
+
+  static final Map<String, bool> _values = {};
+
+  /// 승인 화면 노출 여부.
+  static bool get approvalsEnabled => _values['approvals_enabled'] ?? false;
+
+  /// 재고 전표 화면 노출 여부.
+  static bool get stockTransitionsEnabled =>
+      _values['stock_transitions_enabled'] ?? false;
+
+  /// Approval Flow v2 기능 토글.
+  static bool get approvalFlowV2 => _values['approval_flow_v2'] ?? false;
+
+  /// 기능 토글을 환경 변수에서 읽어 초기화한다.
+  static void initialize() {
+    _values
+      ..clear()
+      ..addAll({
+        'approvals_enabled': _readFlag(
+          'FEATURE_APPROVALS_ENABLED',
+          defaultValue: false,
+        ),
+        'stock_transitions_enabled': _readFlag(
+          'FEATURE_STOCK_TRANSITIONS_ENABLED',
+          defaultValue: true,
+        ),
+        'approval_flow_v2': _readFlag(
+          'FEATURE_APPROVAL_FLOW_V2',
+          aliases: const ['feature.approval_flow_v2'],
+          defaultValue: false,
+        ),
+      });
+  }
+
+  /// 논리 키 기반으로 토글 값을 조회한다.
+  static bool isEnabled(String logicalKey) =>
+      _values[logicalKey.toLowerCase()] ?? false;
+
+  static bool _readFlag(
+    String key, {
+    bool defaultValue = false,
+    List<String> aliases = const [],
+  }) {
+    for (final candidate in <String>{key, ...aliases}) {
+      final raw = dotenv.maybeGet(candidate);
+      if (raw == null) {
+        continue;
+      }
+      final normalized = raw.trim().toLowerCase();
+      switch (normalized) {
+        case '1':
+        case 'y':
+        case 'yes':
+        case 'true':
+          return true;
+        case '0':
+        case 'n':
+        case 'no':
+        case 'false':
+          return false;
+        default:
+          continue;
+      }
+    }
+    return defaultValue;
+  }
+}

lib/core/network/api_client.dart

@@ -1,3 +1,5 @@
+import 'dart:collection';
+
 import 'package:dio/dio.dart';
 
 import 'api_error.dart';
@@ -14,6 +16,116 @@ class ApiClient {
   final ApiErrorMapper _errorMapper;
   static const _dataKey = 'data';
 
+  /// 경로 세그먼트를 조합해 일관된 요청 경로를 생성한다.
+  ///
+  /// - 각 세그먼트의 선행/후행 `/`를 제거한 뒤 단일 슬래시로 결합한다.
+  /// - 첫 번째 세그먼트가 `/`로 시작하면 결과 역시 `/`를 유지한다.
+  static String buildPath(
+    Object base, [
+    Iterable<Object?> segments = const [],
+  ]) {
+    final joined = <String>[];
+    var leadingSlash = false;
+
+    void append(Object? value, {bool isFirst = false}) {
+      if (value == null) {
+        return;
+      }
+      var text = value.toString();
+      if (text.isEmpty) {
+        return;
+      }
+      if (isFirst && text.startsWith('/')) {
+        leadingSlash = true;
+      }
+      text = text.replaceAll(RegExp(r'^/+'), '').replaceAll(RegExp(r'/+$'), '');
+      if (text.isEmpty) {
+        return;
+      }
+      joined.add(text);
+    }
+
+    append(base, isFirst: true);
+    for (final segment in segments) {
+      append(segment);
+    }
+
+    if (joined.isEmpty) {
+      return leadingSlash ? '/' : '';
+    }
+    final path = joined.join('/');
+    return leadingSlash ? '/$path' : path;
+  }
+
+  /// 페이지네이션/검색/필터 파라미터를 표준 규칙에 맞춰 구성한다.
+  ///
+  /// - 문자열은 trim 후 빈 값이면 제외한다.
+  /// - `include`는 중복 제거 후 콤마로 연결한다.
+  /// - `DateTime`은 UTC ISO8601 문자열로 직렬화한다.
+  /// - [filters]가 동일 키를 포함하면 앞선 설정을 덮어쓴다.
+  static Map<String, dynamic> buildQuery({
+    int? page,
+    int? pageSize,
+    String? q,
+    String? sort,
+    String? order,
+    Iterable<String>? include,
+    DateTime? updatedSince,
+    Map<String, dynamic>? filters,
+  }) {
+    final query = <String, dynamic>{};
+
+    void put(String key, dynamic value) {
+      if (value == null) {
+        return;
+      }
+      if (value is String) {
+        final trimmed = value.trim();
+        if (trimmed.isEmpty) {
+          return;
+        }
+        query[key] = trimmed;
+        return;
+      }
+      if (value is DateTime) {
+        query[key] = value.toUtc().toIso8601String();
+        return;
+      }
+      if (value is Iterable) {
+        final sanitized = <String>[];
+        for (final element in value) {
+          if (element == null) {
+            continue;
+          }
+          final text = element.toString().trim();
+          if (text.isEmpty) {
+            continue;
+          }
+          sanitized.add(text);
+        }
+        if (sanitized.isEmpty) {
+          return;
+        }
+        final unique = LinkedHashSet<String>.from(sanitized);
+        query[key] = unique.join(',');
+        return;
+      }
+      query[key] = value;
+    }
+
+    put('page', page);
+    put('page_size', pageSize);
+    put('q', q);
+    put('sort', sort);
+    put('order', order?.trim().toLowerCase());
+    put('include', include);
+    put('updated_since', updatedSince);
+
+    filters?.forEach(put);
+
+    return Map.unmodifiable(query);
+  }
+
   /// 내부에서 사용하는 Dio 인스턴스
   /// 외부에서 Dio 직접 사용을 최소화하고, 가능하면 아래 헬퍼 메서드를 사용한다.
   Dio get dio => _dio;

lib/core/network/api_routes.dart

@@ -5,4 +5,21 @@ class ApiRoutes {
 
   /// API v1 prefix
   static const apiV1 = '/api/v1';
+
+  /// 결재(Approval) 관련 엔드포인트
+  static const approvals = '$apiV1/approvals';
+  static const approvalRoot = '$apiV1/approval';
+  static const approvalSteps = '$apiV1/approval-steps';
+  static const approvalHistory = '$apiV1/approval/history';
+  static const approvalActions = '$apiV1/approval-actions';
+  static const approvalDrafts = '$apiV1/approval-drafts';
+
+  /// 결재 행위 전용 경로(`/approval/{action}`)를 반환한다.
+  static String approvalAction(String action) {
+    final sanitized = action
+        .trim()
+        .replaceAll(RegExp(r'^/+'), '')
+        .replaceAll(RegExp(r'/+$'), '');
+    return '$approvalRoot/$sanitized';
+  }
 }

lib/core/routing/app_router.dart

@@ -24,6 +24,8 @@ import '../../features/reporting/presentation/pages/reporting_page.dart';
 import '../../features/util/postal_search/presentation/pages/postal_search_page.dart';
 import '../../widgets/app_shell.dart';
 import '../constants/app_sections.dart';
+import '../permissions/permission_manager.dart';
+import 'auth_guard.dart';
 
 /// 전역 네비게이터 키(로그인/셸 라우터 공용).
 final _rootNavigatorKey = GlobalKey<NavigatorState>(debugLabel: 'root');
@@ -122,21 +124,41 @@ final appRouter = GoRouter(
         GoRoute(
           path: '/approvals/requests',
           name: 'approvals-requests',
+          redirect: AuthGuard.require(
+            resource: '/approvals/requests',
+            action: PermissionAction.view,
+            fallback: dashboardRoutePath,
+          ),
           builder: (context, state) => ApprovalRequestPage(routeUri: state.uri),
         ),
         GoRoute(
           path: '/approvals/steps',
           name: 'approvals-steps',
+          redirect: AuthGuard.require(
+            resource: '/approvals/steps',
+            action: PermissionAction.view,
+            fallback: dashboardRoutePath,
+          ),
           builder: (context, state) => const ApprovalStepPage(),
         ),
         GoRoute(
           path: '/approvals/history',
           name: 'approvals-history',
+          redirect: AuthGuard.require(
+            resource: '/approvals/history',
+            action: PermissionAction.view,
+            fallback: dashboardRoutePath,
+          ),
           builder: (context, state) => const ApprovalHistoryPage(),
         ),
         GoRoute(
           path: '/approvals/templates',
           name: 'approvals-templates',
+          redirect: AuthGuard.require(
+            resource: '/approvals/templates',
+            action: PermissionAction.view,
+            fallback: dashboardRoutePath,
+          ),
           builder: (context, state) => const ApprovalTemplatePage(),
         ),
         GoRoute(

lib/core/routing/auth_guard.dart

@@ -0,0 +1,39 @@
+import 'package:flutter/widgets.dart';
+import 'package:get_it/get_it.dart';
+import 'package:go_router/go_router.dart';
+
+import '../permissions/permission_manager.dart';
+
+typedef RouteGuard = String? Function(BuildContext, GoRouterState);
+
+/// 라우트 접근 시 권한을 검사하는 가드.
+class AuthGuard {
+  const AuthGuard._();
+
+  /// [resource]와 [action]에 대한 접근 권한을 확인한다.
+  static bool can(
+    String resource, {
+    PermissionAction action = PermissionAction.view,
+  }) {
+    if (!GetIt.I.isRegistered<PermissionManager>()) {
+      return false;
+    }
+    return GetIt.I<PermissionManager>().can(resource, action);
+  }
+
+  /// 권한이 없을 경우 [fallback] 경로로 리다이렉트하는 Guard를 생성한다.
+  static RouteGuard require({
+    required String resource,
+    PermissionAction action = PermissionAction.view,
+    required String fallback,
+  }) {
+    return (context, state) {
+      if (!GetIt.I.isRegistered<PermissionManager>()) {
+        return null;
+      }
+      final manager = GetIt.I<PermissionManager>();
+      final allowed = manager.can(resource, action);
+      return allowed ? null : fallback;
+    };
+  }
+}

lib/core/services/token_storage_native.dart

@@ -4,6 +4,7 @@ import 'token_storage.dart';
 
 /// 안전한 스토리지에 저장할 액세스 토큰 키.
 const _kAccessTokenKey = 'access_token';
+
 /// 안전한 스토리지에 저장할 리프레시 토큰 키.
 const _kRefreshTokenKey = 'refresh_token';
 

lib/core/services/token_storage_web.dart

@@ -5,6 +5,7 @@ import 'token_storage.dart';
 
 /// 웹 로컬스토리지에 저장할 액세스 토큰 키.
 const _kAccessTokenKey = 'access_token';
+
 /// 웹 로컬스토리지에 저장할 리프레시 토큰 키.
 const _kRefreshTokenKey = 'refresh_token';