고객사 목록 쿼리스트링 연동 및 공통 JSON 파서 도입

lib/features/util/postal_search/domain/entities/postal_code.dart

@@ -0,0 +1,36 @@
+/// 우편번호 검색 결과의 도메인 모델.
+///
+/// - `zipcode`: 5자리 우편번호.
+/// - `sido`/`sigungu`: 시도 및 시군구 행정 구역.
+/// - `roadName`: 도로명 주소 구성 요소.
+/// - `buildingMainNo`/`buildingSubNo`: 건물 번호 본번/부번(없으면 null).
+class PostalCode {
+  PostalCode({
+    required this.zipcode,
+    this.sido,
+    this.sigungu,
+    this.roadName,
+    this.buildingMainNo,
+    this.buildingSubNo,
+  });
+
+  final String zipcode;
+  final String? sido;
+  final String? sigungu;
+  final String? roadName;
+  final int? buildingMainNo;
+  final int? buildingSubNo;
+
+  /// 건물 번호 문자열을 반환한다. 본번만 존재하면 해당 값만 반환한다.
+  String get buildingNumber {
+    final main = buildingMainNo;
+    final sub = buildingSubNo;
+    if (main == null) {
+      return '';
+    }
+    if (sub == null || sub == 0) {
+      return '$main';
+    }
+    return '$main-$sub';
+  }
+}

lib/features/util/postal_search/domain/repositories/postal_search_repository.dart

@@ -0,0 +1,10 @@
+import '../entities/postal_code.dart';
+
+/// 우편번호 검색 기능을 추상화한 저장소 인터페이스.
+abstract class PostalSearchRepository {
+  /// 키워드를 기반으로 우편번호 목록을 검색한다.
+  ///
+  /// [keyword]는 우편번호/도로명/건물번호 중 하나의 문자열을 전달한다.
+  /// [limit]을 지정하면 최대 반환 건수를 제한한다.
+  Future<List<PostalCode>> search({required String keyword, int limit = 20});
+}