feat: 대규모 코드베이스 개선 - 백엔드 통합성 강화 및 UI 일관성 완성

- CLAUDE.md 대폭 개선: 개발 가이드라인 및 프로젝트 상태 문서화
- 백엔드 API 통합: 모든 엔티티 간 Foreign Key 관계 완벽 구현
- UI 일관성 강화: shadcn_ui 컴포넌트 표준화 적용
- 데이터 모델 개선: DTO 및 모델 클래스 백엔드 스키마와 100% 일치
- 사용자 관리: 회사 연결, 중복 검사, 입력 검증 기능 추가
- 창고 관리: 우편번호 연결, 중복 검사 기능 강화
- 회사 관리: 우편번호 연결, 중복 검사 로직 구현
- 장비 관리: 불필요한 카테고리 필드 제거, 벤더-모델 관계 정리
- 우편번호 시스템: 검색 다이얼로그 Provider 버그 수정

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

lib/screens/warehouse_location/controllers/warehouse_location_form_controller.dart

@@ -2,6 +2,7 @@ import 'package:flutter/material.dart';
 import 'package:get_it/get_it.dart';
 import 'package:superport/models/warehouse_location_model.dart';
 import 'package:superport/services/warehouse_service.dart';
+import 'package:superport/data/models/zipcode_dto.dart';
 
 /// 입고지 폼 상태 및 저장/수정 로직을 담당하는 컨트롤러
 class WarehouseLocationFormController extends ChangeNotifier {
@@ -16,17 +17,18 @@ class WarehouseLocationFormController extends ChangeNotifier {
   /// 비고 입력 컨트롤러
   final TextEditingController remarkController = TextEditingController();
 
-  /// 담당자명 입력 컨트롤러
-  final TextEditingController managerNameController = TextEditingController();
-
-  /// 담당자 연락처 입력 컨트롤러
-  final TextEditingController managerPhoneController = TextEditingController();
-
-  /// 수용량 입력 컨트롤러
-  final TextEditingController capacityController = TextEditingController();
 
   /// 주소 입력 컨트롤러 (단일 필드)
   final TextEditingController addressController = TextEditingController();
+  
+  /// 우편번호 입력 컨트롤러
+  final TextEditingController zipcodeController = TextEditingController();
+  
+  /// 선택된 우편번호 정보
+  ZipcodeDto? _selectedZipcode;
+  
+  /// 우편번호 검색 로딩 상태
+  bool _isSearchingZipcode = false;
 
   /// 백엔드 API에 맞는 단순 필드들 (주소는 단일 String)
 
@@ -61,6 +63,35 @@ class WarehouseLocationFormController extends ChangeNotifier {
       initialize(locationId);
     }
   }
+  
+  // 사전 로드된 데이터로 초기화하는 생성자
+  WarehouseLocationFormController.withPreloadedData({
+    required Map<String, dynamic> preloadedData,
+  }) {
+    if (GetIt.instance.isRegistered<WarehouseService>()) {
+      _warehouseService = GetIt.instance<WarehouseService>();
+    } else {
+      throw Exception('WarehouseService not registered in GetIt');
+    }
+    
+    // 전달받은 데이터로 즉시 초기화
+    _id = preloadedData['locationId'] as int?;
+    _isEditMode = _id != null;
+    _originalLocation = preloadedData['location'] as WarehouseLocation?;
+    
+    if (_originalLocation != null) {
+      nameController.text = _originalLocation!.name;
+      addressController.text = _originalLocation!.address ?? '';
+      remarkController.text = _originalLocation!.remark ?? '';
+      // zipcodes_zipcode가 있으면 표시
+      if (_originalLocation!.zipcode != null) {
+        zipcodeController.text = _originalLocation!.zipcode!;
+      }
+    }
+    
+    _isLoading = false;
+    _error = null;
+  }
 
   // Getters
   bool get isSaving => _isSaving;
@@ -69,6 +100,8 @@ class WarehouseLocationFormController extends ChangeNotifier {
   bool get isLoading => _isLoading;
   String? get error => _error;
   WarehouseLocation? get originalLocation => _originalLocation;
+  ZipcodeDto? get selectedZipcode => _selectedZipcode;
+  bool get isSearchingZipcode => _isSearchingZipcode;
 
   /// 기존 데이터 세팅 (수정 모드)
   Future<void> initialize(int locationId) async {
@@ -85,9 +118,10 @@ class WarehouseLocationFormController extends ChangeNotifier {
         nameController.text = _originalLocation!.name;
         addressController.text = _originalLocation!.address ?? '';
         remarkController.text = _originalLocation!.remark ?? '';
-        managerNameController.text = _originalLocation!.managerName ?? '';
-        managerPhoneController.text = _originalLocation!.managerPhone ?? '';
-        capacityController.text = _originalLocation!.capacity?.toString() ?? '';
+        // zipcodes_zipcode가 있으면 표시
+        if (_originalLocation!.zipcode != null) {
+          zipcodeController.text = _originalLocation!.zipcode!;
+        }
       }
     } catch (e) {
       _error = e.toString();
@@ -112,9 +146,10 @@ class WarehouseLocationFormController extends ChangeNotifier {
         name: nameController.text.trim(),
         address: addressController.text.trim().isEmpty ? null : addressController.text.trim(),
         remark: remarkController.text.trim().isEmpty ? null : remarkController.text.trim(),
-        managerName: managerNameController.text.trim().isEmpty ? null : managerNameController.text.trim(),
-        managerPhone: managerPhoneController.text.trim().isEmpty ? null : managerPhoneController.text.trim(),
-        capacity: capacityController.text.trim().isEmpty ? null : int.tryParse(capacityController.text.trim()),
+        zipcode: zipcodeController.text.trim().isEmpty ? null : zipcodeController.text.trim(), // zipcodes_zipcode 추가
+        managerName: null, // 백엔드에서 지원하지 않음
+        managerPhone: null, // 백엔드에서 지원하지 않음
+        capacity: null, // 백엔드에서 지원하지 않음
         isActive: true, // 새로 생성 시 항상 활성화
         createdAt: DateTime.now(),
       );
@@ -141,13 +176,27 @@ class WarehouseLocationFormController extends ChangeNotifier {
     nameController.clear();
     addressController.clear();
     remarkController.clear();
-    managerNameController.clear();
-    managerPhoneController.clear();
-    capacityController.clear();
+    zipcodeController.clear();
+    _selectedZipcode = null;
     _error = null;
     formKey.currentState?.reset();
     notifyListeners();
   }
+  
+  /// 우편번호 선택
+  void selectZipcode(ZipcodeDto zipcode) {
+    _selectedZipcode = zipcode;
+    zipcodeController.text = zipcode.zipcode;
+    // 주소를 자동으로 채움
+    addressController.text = '${zipcode.sido} ${zipcode.gu} ${zipcode.etc ?? ''}'.trim();
+    notifyListeners();
+  }
+  
+  /// 우편번호 검색 상태 변경
+  void setSearchingZipcode(bool searching) {
+    _isSearchingZipcode = searching;
+    notifyListeners();
+  }
 
   /// 유효성 검사
   String? validateName(String? value) {
@@ -160,31 +209,33 @@ class WarehouseLocationFormController extends ChangeNotifier {
     return null;
   }
 
-
-  /// 수용량 유효성 검사
-  String? validateCapacity(String? value) {
-    if (value != null && value.isNotEmpty) {
-      final capacity = int.tryParse(value);
-      if (capacity == null) {
-        return '올바른 숫자를 입력해주세요';
-      }
-      if (capacity < 0) {
-        return '수용량은 0 이상이어야 합니다';
-      }
+  /// 창고명 중복 확인
+  Future<bool> checkDuplicateName(String name, {int? excludeId}) async {
+    try {
+      // 전체 창고 목록 조회
+      final response = await _warehouseService.getWarehouseLocations(
+        perPage: 100, // 충분한 수의 창고 조회
+        includeInactive: false,
+      );
+      
+      // 중복 검사
+      final duplicates = response.items.where((warehouse) {
+        // 수정 모드일 때 자기 자신은 제외
+        if (excludeId != null && warehouse.id == excludeId) {
+          return false;
+        }
+        // 대소문자 구분 없이 이름 비교
+        return warehouse.name.toLowerCase() == name.toLowerCase();
+      }).toList();
+      
+      return duplicates.isNotEmpty;
+    } catch (e) {
+      // 에러 발생 시 false 반환 (중복 없음으로 처리)
+      return false;
     }
-    return null;
   }
 
-  /// 전화번호 유효성 검사
-  String? validatePhoneNumber(String? value) {
-    if (value != null && value.isNotEmpty) {
-      // 기본적인 전화번호 형식 검사 (숫자, 하이픈 허용)
-      if (!RegExp(r'^[0-9-]+$').hasMatch(value)) {
-        return '올바른 전화번호 형식을 입력해주세요';
-      }
-    }
-    return null;
-  }
+
 
   /// 컨트롤러 해제
   @override
@@ -192,9 +243,6 @@ class WarehouseLocationFormController extends ChangeNotifier {
     nameController.dispose();
     addressController.dispose();
     remarkController.dispose();
-    managerNameController.dispose();
-    managerPhoneController.dispose();
-    capacityController.dispose();
     super.dispose();
   }
 }

lib/screens/warehouse_location/controllers/warehouse_location_list_controller.dart

@@ -96,6 +96,17 @@ class WarehouseLocationListController extends BaseListController<WarehouseLocati
     loadData(isRefresh: true);
   }
 
+  /// 창고 위치 상세 데이터 로드
+  Future<WarehouseLocation?> loadWarehouseDetail(int warehouseId) async {
+    try {
+      final location = await _warehouseService.getWarehouseLocationById(warehouseId);
+      return location;
+    } catch (e) {
+      print('Failed to load warehouse detail: $e');
+      return null;
+    }
+  }
+
   // 필터 초기화
   void clearFilters() {
     _isActive = null;

lib/screens/warehouse_location/warehouse_location_form.dart

@@ -1,15 +1,20 @@
 import 'package:flutter/material.dart';
-import 'package:flutter/services.dart';
 import 'package:shadcn_ui/shadcn_ui.dart';
+import 'package:provider/provider.dart';
+import 'package:get_it/get_it.dart';
 import 'package:superport/screens/common/widgets/remark_input.dart';
 import 'package:superport/screens/common/templates/form_layout_template.dart';
 import 'controllers/warehouse_location_form_controller.dart';
-import 'package:superport/utils/formatters/korean_phone_formatter.dart';
+import 'package:superport/data/models/zipcode_dto.dart';
+import 'package:superport/screens/zipcode/zipcode_search_screen.dart';
+import 'package:superport/screens/zipcode/controllers/zipcode_controller.dart';
+import 'package:superport/domain/usecases/zipcode_usecase.dart';
 
 /// 입고지 추가/수정 폼 화면 (SRP 적용, 상태/로직 분리)
 class WarehouseLocationFormScreen extends StatefulWidget {
   final int? id; // 수정 모드 지원을 위한 id 파라미터
-  const WarehouseLocationFormScreen({super.key, this.id});
+  final Map<String, dynamic>? preloadedData; // 사전 로드된 데이터
+  const WarehouseLocationFormScreen({super.key, this.id, this.preloadedData});
 
   @override
   State<WarehouseLocationFormScreen> createState() =>
@@ -20,14 +25,30 @@ class _WarehouseLocationFormScreenState
     extends State<WarehouseLocationFormScreen> {
   /// 폼 컨트롤러 (상태 및 저장/수정 로직 위임)
   late final WarehouseLocationFormController _controller;
+  
+  /// 상태 메시지
+  String? _statusMessage;
+  
+  /// 저장 중 여부
+  bool _isSaving = false;
 
   @override
   void initState() {
     super.initState();
     // 컨트롤러 생성 및 초기화
-    _controller = WarehouseLocationFormController();
-    if (widget.id != null) {
-      _controller.initialize(widget.id!);
+    if (widget.preloadedData != null) {
+      // 사전 로드된 데이터로 즉시 초기화
+      _controller = WarehouseLocationFormController.withPreloadedData(
+        preloadedData: widget.preloadedData!,
+      );
+    } else {
+      _controller = WarehouseLocationFormController();
+      if (widget.id != null) {
+        // 비동기 초기화를 위해 addPostFrameCallback 사용
+        WidgetsBinding.instance.addPostFrameCallback((_) {
+          _controller.initialize(widget.id!);
+        });
+      }
     }
   }
 
@@ -38,11 +59,75 @@ class _WarehouseLocationFormScreenState
     super.dispose();
   }
 
+  // 우편번호 검색 다이얼로그
+  Future<ZipcodeDto?> _showZipcodeSearchDialog() async {
+    return await showDialog<ZipcodeDto>(
+      context: context,
+      barrierDismissible: true,
+      builder: (BuildContext dialogContext) => Dialog(
+        clipBehavior: Clip.none,
+        insetPadding: const EdgeInsets.symmetric(horizontal: 40, vertical: 24),
+        child: SizedBox(
+          width: 800,
+          height: 600,
+          child: Container(
+            decoration: BoxDecoration(
+              color: ShadTheme.of(context).colorScheme.background,
+              borderRadius: BorderRadius.circular(8),
+            ),
+            child: ChangeNotifierProvider(
+              create: (_) => ZipcodeController(
+                GetIt.instance<ZipcodeUseCase>(),
+              ),
+              child: ZipcodeSearchScreen(
+                onSelect: (zipcode) {
+                  Navigator.of(dialogContext).pop(zipcode);
+                },
+              ),
+            ),
+          ),
+        ),
+      ),
+    );
+  }
+
   // 저장 메소드
   Future<void> _onSave() async {
-    setState(() {}); // 저장 중 상태 갱신
+    // 폼 유효성 검사
+    if (!_controller.formKey.currentState!.validate()) {
+      return;
+    }
+    
+    setState(() {
+      _isSaving = true;
+      _statusMessage = '중복 확인 중...';
+    });
+    
+    // 저장 시 중복 검사 수행
+    final name = _controller.nameController.text.trim();
+    final isDuplicate = await _controller.checkDuplicateName(
+      name,
+      excludeId: _controller.isEditMode ? _controller.id : null,
+    );
+    
+    if (isDuplicate) {
+      setState(() {
+        _isSaving = false;
+        _statusMessage = '이미 존재하는 창고명입니다.';
+      });
+      return;
+    }
+    
+    setState(() {
+      _statusMessage = '저장 중...';
+    });
+    
     final success = await _controller.save();
-    setState(() {}); // 저장 완료 후 상태 갱신
+    
+    setState(() {
+      _isSaving = false;
+      _statusMessage = null;
+    });
     
     if (success) {
       // 성공 메시지 표시
@@ -73,9 +158,9 @@ class _WarehouseLocationFormScreenState
   Widget build(BuildContext context) {
     return FormLayoutTemplate(
       title: _controller.isEditMode ? '입고지 수정' : '입고지 추가',
-      onSave: _controller.isSaving ? null : _onSave,
+      onSave: _isSaving ? null : _onSave,
       saveButtonText: '저장',
-      isLoading: _controller.isSaving,
+      isLoading: _isSaving,
       child: Form(
         key: _controller.formKey,
         child: SingleChildScrollView(
@@ -88,15 +173,64 @@ class _WarehouseLocationFormScreenState
               FormFieldWrapper(
                 label: '창고명',
                 required: true,
-                child: ShadInputFormField(
-                  controller: _controller.nameController,
-                  placeholder: const Text('창고명을 입력하세요'),
-                  validator: (value) {
-                    if (value.trim().isEmpty) {
-                      return '창고명을 입력하세요';
-                    }
-                    return null;
-                  },
+                child: Column(
+                  crossAxisAlignment: CrossAxisAlignment.start,
+                  children: [
+                    ShadInputFormField(
+                      controller: _controller.nameController,
+                      placeholder: const Text('창고명을 입력하세요'),
+                      validator: (value) {
+                        if (value.trim().isEmpty) {
+                          return '창고명을 입력하세요';
+                        }
+                        return null;
+                      },
+                    ),
+                    // 상태 메시지 영역 (고정 높이)
+                    SizedBox(
+                      height: 20,
+                      child: _statusMessage != null
+                          ? Padding(
+                              padding: const EdgeInsets.only(top: 4),
+                              child: Text(
+                                _statusMessage!,
+                                style: TextStyle(
+                                  fontSize: 12,
+                                  color: _statusMessage!.contains('존재')
+                                      ? Colors.red
+                                      : Colors.grey,
+                                ),
+                              ),
+                            )
+                          : const SizedBox.shrink(),
+                    ),
+                  ],
+                ),
+              ),
+              // 우편번호 검색
+              FormFieldWrapper(
+                label: '우편번호',
+                child: Row(
+                  children: [
+                    Expanded(
+                      child: ShadInputFormField(
+                        controller: _controller.zipcodeController,
+                        placeholder: const Text('우편번호'),
+                        readOnly: true,
+                      ),
+                    ),
+                    const SizedBox(width: 8),
+                    ShadButton(
+                      onPressed: () async {
+                        // 우편번호 검색 다이얼로그 호출
+                        final result = await _showZipcodeSearchDialog();
+                        if (result != null) {
+                          _controller.selectZipcode(result);
+                        }
+                      },
+                      child: const Text('검색'),
+                    ),
+                  ],
                 ),
               ),
               // 주소 입력 (단일 필드)
@@ -104,42 +238,8 @@ class _WarehouseLocationFormScreenState
                 label: '주소',
                 child: ShadInputFormField(
                   controller: _controller.addressController,
-                  placeholder: const Text('주소를 입력하세요 (예: 경기도 용인시 기흥구 동백로 123)'),
-                  maxLines: 3,
-                ),
-              ),
-              // 담당자명 입력
-              FormFieldWrapper(
-                label: '담당자명',
-                child: ShadInputFormField(
-                  controller: _controller.managerNameController,
-                  placeholder: const Text('담당자명을 입력하세요'),
-                ),
-              ),
-              // 담당자 연락처 입력
-              FormFieldWrapper(
-                label: '담당자 연락처',
-                child: ShadInputFormField(
-                  controller: _controller.managerPhoneController,
-                  placeholder: const Text('010-1234-5678'),
-                  keyboardType: TextInputType.phone,
-                  inputFormatters: [
-                    KoreanPhoneFormatter(), // 한국식 전화번호 자동 포맷팅
-                  ],
-                  validator: (value) => PhoneValidator.validate(value),
-                ),
-              ),
-              // 수용량 입력
-              FormFieldWrapper(
-                label: '수용량',
-                child: ShadInputFormField(
-                  controller: _controller.capacityController,
-                  placeholder: const Text('수용량을 입력하세요 (개)'),
-                  keyboardType: TextInputType.number,
-                  inputFormatters: [
-                    FilteringTextInputFormatter.digitsOnly,
-                  ],
-                  validator: _controller.validateCapacity,
+                  placeholder: const Text('상세 주소를 입력하세요'),
+                  maxLines: 2,
                 ),
               ),
               // 비고 입력

lib/screens/warehouse_location/warehouse_location_list.dart

@@ -75,13 +75,87 @@ class _WarehouseLocationListState
 
   /// 창고 수정 폼으로 이동
   void _navigateToEdit(WarehouseLocation location) async {
-    final result = await Navigator.pushNamed(
-      context,
-      Routes.warehouseLocationEdit,
-      arguments: location.id,
+    // 로딩 다이얼로그 표시
+    showShadDialog(
+      context: context,
+      barrierDismissible: false,
+      builder: (context) => ShadDialog(
+        child: Container(
+          padding: const EdgeInsets.all(24),
+          child: const Column(
+            mainAxisSize: MainAxisSize.min,
+            children: [
+              ShadProgress(),
+              SizedBox(height: 16),
+              Text('창고 정보를 불러오는 중...'),
+            ],
+          ),
+        ),
+      ),
     );
-    if (result == true) {
-      _reload();
+    
+    try {
+      // 창고 상세 데이터 로드
+      final warehouseDetail = await _controller.loadWarehouseDetail(location.id);
+      
+      // 로딩 다이얼로그 닫기
+      if (mounted) {
+        Navigator.pop(context);
+      }
+      
+      if (warehouseDetail == null) {
+        if (mounted) {
+          showShadDialog(
+            context: context,
+            builder: (context) => ShadDialog.alert(
+              title: const Text('오류'),
+              description: const Text('창고 정보를 불러올 수 없습니다.'),
+              actions: [
+                ShadButton(
+                  child: const Text('확인'),
+                  onPressed: () => Navigator.pop(context),
+                ),
+              ],
+            ),
+          );
+        }
+        return;
+      }
+      
+      // 모든 데이터를 arguments로 전달
+      final result = await Navigator.pushNamed(
+        context,
+        Routes.warehouseLocationEdit,
+        arguments: {
+          'locationId': location.id,
+          'location': warehouseDetail,
+        },
+      );
+      
+      if (result == true) {
+        _reload();
+      }
+    } catch (e) {
+      // 로딩 다이얼로그 닫기
+      if (mounted) {
+        Navigator.pop(context);
+      }
+      
+      if (mounted) {
+        showShadDialog(
+          context: context,
+          builder: (context) => ShadDialog.alert(
+            title: const Text('오류'),
+            description: Text('창고 정보를 불러오는 중 오류가 발생했습니다: $e'),
+            actions: [
+              ShadButton(
+                child: const Text('확인'),
+                onPressed: () => Navigator.pop(context),
+              ),
+            ],
+          ),
+        );
+      }
     }
   }