jp_address_complement 0.1.0

data/lib/jp_address_complement/ken_all_downloader.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require 'fileutils'
+require 'net/http'
+require 'tempfile'
+require 'tmpdir'
+require 'uri'
+require 'zip'
+
+module JpAddressComplement
+  # 郵便番号データ（utf_ken_all.zip）を公式URLからダウンロードし、展開して CSV のパスを返す
+  class KenAllDownloader
+    # @rbs String
+    DEFAULT_URL = 'https://www.post.japanpost.jp/zipcode/dl/utf/zip/utf_ken_all.zip'
+    # @rbs String
+    CSV_FILENAME = 'utf_ken_all.csv'
+
+    class DownloadError < JpAddressComplement::Error; end
+
+    # @rbs (?String url) -> void
+    # @param url [String] ダウンロードする zip の URL（省略時は DEFAULT_URL）
+    def initialize(url = DEFAULT_URL)
+      @url = url
+    end
+
+    # zip をダウンロードして一時ディレクトリに展開し、KEN_ALL.CSV の絶対パスを返す。
+    # 呼び出し元でインポート完了まで一時ディレクトリは削除されない（プロセス終了時に OS が削除）。
+    # @rbs () -> String
+    # @return [String] 展開された KEN_ALL.CSV の絶対パス
+    # @raise [DownloadError] ダウンロード・展開・ファイルが見つからない場合
+    def download_and_extract
+      zip_path = download_zip
+      extract_zip(zip_path)
+    ensure
+      File.unlink(zip_path) if zip_path && File.exist?(zip_path)
+    end
+
+    private
+
+    # @rbs () -> String
+    def download_zip
+      tmp = Tempfile.new(['ken_all', '.zip'])
+      tmp.binmode
+      tmp.close
+      path = tmp.path or raise 'Tempfile#path is nil'
+      fetch_to_path(path)
+      path
+    rescue SocketError, Timeout::Error, Errno::ENOENT => e
+      raise DownloadError, "ダウンロードに失敗しました: #{e.message}"
+    end
+
+    # @rbs (String path) -> void
+    def fetch_to_path(path)
+      uri = URI.parse(@url)
+      host = uri.host or raise DownloadError, "URL に host がありません: #{@url}"
+      port = uri.port || (uri.scheme == 'https' ? 443 : 80)
+      use_ssl = uri.scheme == 'https'
+      Net::HTTP.start(host, port, use_ssl: use_ssl, read_timeout: 60, open_timeout: 10) do |http|
+        request = Net::HTTP::Get.new(uri)
+        http.request(request) { |response| write_response_to_path(response, path) }
+      end
+    end
+
+    # @rbs (Net::HTTPResponse response, String path) -> void
+    def write_response_to_path(response, path)
+      raise DownloadError, "HTTP error: #{response.code} #{response.message}" unless response.is_a?(Net::HTTPSuccess)
+
+      File.open(path, 'wb') do |f|
+        if response.respond_to?(:body_io)
+          IO.copy_stream(response.body_io, f)
+        else
+          # Net::HTTPResponse#body は stdlib RBS で型が不足することがある
+          body = response.body # steep:ignore
+          f.write(body)
+        end
+      end
+    end
+
+    # @rbs (String zip_path) -> String
+    def extract_zip(zip_path)
+      tmpdir = Dir.mktmpdir('jp_address_complement_ken_all')
+      tmpdir = File.expand_path(tmpdir) # 相対の場合は絶対パスに正規化（realpath はシンボリックリンク解決で別パスになるため使わない）
+      csv_path = extract_zip_entries(zip_path, tmpdir)
+      csv_path ||= find_csv_in_dir(tmpdir)
+      raise DownloadError, "ZIP 内に #{CSV_FILENAME} が見つかりません" if csv_path.nil?
+
+      csv_path
+    rescue Zip::Error => e
+      raise DownloadError, "ZIP の展開に失敗しました: #{e.message}"
+    end
+
+    # @rbs (String zip_path, String tmpdir) -> String?
+    def extract_zip_entries(zip_path, tmpdir)
+      csv_path = nil
+      Zip::File.open(zip_path) do |zip_file|
+        Dir.chdir(tmpdir) do
+          zip_file.each do |entry|
+            name = entry.name.delete_prefix('/')
+            dir = File.dirname(name)
+            FileUtils.mkdir_p(dir) unless dir == '.'
+            # RubyZip::Entry#extract(dest_path = nil) を使い、既存ファイルがあればブロックで上書き許可する。
+            entry.extract(name) { true } # steep:ignore
+            dest = File.join(tmpdir, name)
+            csv_path = dest if entry_csv?(name, dest)
+          end
+        end
+      end
+      csv_path
+    end
+
+    # @rbs (String entry_name, String dest) -> bool
+    def entry_csv?(entry_name, dest)
+      File.basename(entry_name) == CSV_FILENAME && File.file?(dest)
+    end
+
+    # @rbs (String tmpdir) -> String?
+    def find_csv_in_dir(tmpdir)
+      Dir.glob(File.join(tmpdir, '**', CSV_FILENAME)).find { |p| File.file?(p) }
+    end
+  end
+end

data/lib/jp_address_complement/models/postal_code.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# rbs_inline: disabled — 継承元が base_record_class で可変のため型は sig/manual/ で手動管理
+require 'active_record'
+
+module JpAddressComplement
+  # 住所テーブルに対応する ActiveRecord モデル
+  # 継承元は JpAddressComplement.base_record_class（未設定時は ActiveRecord::Base）
+  # テーブル名は JpAddressComplement.postal_code_table_name（未設定時は 'jp_address_complement_postal_codes'）。initializer で変更可能。
+  class PostalCode < base_record_class
+    # initializer がモデル読み込み後に実行されるため、参照のたびに設定を読む
+    def self.table_name
+      JpAddressComplement.postal_code_table_name
+    end
+
+    validates :postal_code, presence: true, format: { with: /\A\d{7}\z/ }
+    validates :pref_code, presence: true
+    validates :pref, presence: true
+    validates :city, presence: true
+  end
+end

data/lib/jp_address_complement/normalizer.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module JpAddressComplement
+  # 郵便番号の正規化処理を担当するクラス
+  # 全角→半角変換・〒記号除去・ハイフン除去を行う
+  class Normalizer
+    # 半角数字以外の文字を除去するためのパターン
+    DIGIT_ONLY = /\A\d{7}\z/ #: Regexp
+    PREFIX_MIN_LENGTH = 4 #: Integer
+
+    # 町域から除去する「通常住所に含まれない」固定文字列（漢字・かな両方）
+    TOWN_DISPLAY_REMOVAL_STRINGS = [
+      '以下に掲載がない場合',
+      'イカニケイサイガナイバアイ' # 以下に掲載がない場合（カナ）
+    ].freeze
+
+    class << self
+      # 郵便番号文字列を正規化して7桁の半角数字文字列を返す
+      # @rbs (String?) -> String?
+      # @param code [String, nil] 郵便番号文字列（ハイフン・全角・〒記号を自動除去）
+      # @return [String, nil] 正規化後の7桁郵便番号。不正な場合は nil
+      def normalize_postal_code(code)
+        return nil if code.blank?
+
+        normalized = normalize_string(code)
+        return nil unless normalized.match?(DIGIT_ONLY)
+
+        normalized
+      end
+
+      # 郵便番号プレフィックスを正規化する
+      # @rbs (String?) -> String?
+      # @param prefix [String, nil] 郵便番号の先頭部分（4桁以上）
+      # @return [String, nil] 正規化後の数字文字列。4桁未満または不正な場合は nil
+      def normalize_prefix(prefix)
+        return nil if prefix.blank?
+
+        normalized = normalize_string(prefix)
+        return nil if normalized.empty?
+        return nil unless normalized.match?(/\A\d+\z/)
+        return nil if normalized.length < PREFIX_MIN_LENGTH
+
+        normalized
+      end
+
+      # 町域文字列から「通常住所に含まれない情報」を除いた表示用文字列を返す
+      # 除去対象: 「以下に掲載がない場合」、全角括弧（）で囲まれた部分全体
+      # @rbs (String?) -> String?
+      # @param town_str [String, nil] 町域（漢字）または町域カナ
+      # @return [String, nil] 除去後の文字列。nil または空になった場合は nil
+      def normalize_town_for_display(town_str)
+        return nil if town_str.nil?
+
+        s = town_str.to_s.strip
+        return nil if s.empty?
+
+        # 全角括弧（）で囲まれた部分をすべて除去
+        s = s.gsub(/（[^）]*）/, '')
+        TOWN_DISPLAY_REMOVAL_STRINGS.each { |rem| s = s.gsub(rem, '') }
+        s = s.strip
+        s.empty? ? nil : s
+      end
+
+      private
+
+      # @rbs (String) -> String
+      def normalize_string(str)
+        str
+          .tr('〒', '')
+          .tr('０-９', '0-9')
+          .tr('-ー－', '')
+          .strip
+      end
+    end
+  end
+end

data/lib/jp_address_complement/prefecture.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module JpAddressComplement
+  # JIS X 0401 都道府県コード（01–47）⇔都道府県名の変換
+  module Prefecture
+    # JIS X 0401 都道府県コード → 都道府県名（正式名称）
+    CODE_TO_NAME = {
+      '01' => '北海道',
+      '02' => '青森県',
+      '03' => '岩手県',
+      '04' => '宮城県',
+      '05' => '秋田県',
+      '06' => '山形県',
+      '07' => '福島県',
+      '08' => '茨城県',
+      '09' => '栃木県',
+      '10' => '群馬県',
+      '11' => '埼玉県',
+      '12' => '千葉県',
+      '13' => '東京都',
+      '14' => '神奈川県',
+      '15' => '新潟県',
+      '16' => '富山県',
+      '17' => '石川県',
+      '18' => '福井県',
+      '19' => '山梨県',
+      '20' => '長野県',
+      '21' => '岐阜県',
+      '22' => '静岡県',
+      '23' => '愛知県',
+      '24' => '三重県',
+      '25' => '滋賀県',
+      '26' => '京都府',
+      '27' => '大阪府',
+      '28' => '兵庫県',
+      '29' => '奈良県',
+      '30' => '和歌山県',
+      '31' => '鳥取県',
+      '32' => '島根県',
+      '33' => '岡山県',
+      '34' => '広島県',
+      '35' => '山口県',
+      '36' => '徳島県',
+      '37' => '香川県',
+      '38' => '愛媛県',
+      '39' => '高知県',
+      '40' => '福岡県',
+      '41' => '佐賀県',
+      '42' => '長崎県',
+      '43' => '熊本県',
+      '44' => '大分県',
+      '45' => '宮崎県',
+      '46' => '鹿児島県',
+      '47' => '沖縄県'
+    }.freeze
+
+    NAME_TO_CODE = CODE_TO_NAME.invert.freeze
+
+    # 都道府県コードから都道府県名を返す
+    # @rbs (String | Integer | nil) -> String?
+    # @param code [String, Integer, nil] 都道府県コード（01–47）。数値またはゼロパディング文字列
+    # @return [String, nil] 都道府県名。該当なし・不正入力時は nil
+    def self.name_from_code(code)
+      return nil if code.nil?
+      return nil if code.is_a?(String) && code.strip.empty?
+
+      key = normalize_code(code)
+      return nil unless key
+      return nil if key.to_i < 1 || key.to_i > 47
+
+      CODE_TO_NAME[key]
+    end
+
+    # 都道府県名（正式名称）から都道府県コードを2桁文字列で返す
+    # @rbs (String?) -> String?
+    # @param name [String, nil] 都道府県の正式名称
+    # @return [String, nil] 2桁のコード（例: "13"）。該当なし時は nil
+    def self.code_from_name(name)
+      return nil if name.nil?
+      return nil if name.is_a?(String) && name.strip.empty?
+
+      NAME_TO_CODE[name]
+    end
+
+    def self.normalize_code(code)
+      case code
+      when Integer
+        (1..47).cover?(code) ? format('%02d', code) : nil
+      when String
+        normalize_code_string(code.strip)
+      end
+    end
+    private_class_method :normalize_code
+
+    def self.normalize_code_string(stripped)
+      return nil if stripped.empty?
+      return nil unless stripped.match?(/\A\d{1,2}\z/)
+
+      n = stripped.to_i
+      (1..47).cover?(n) ? format('%02d', n) : nil
+    end
+    private_class_method :normalize_code_string
+  end
+end

data/lib/jp_address_complement/railtie.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require 'rails'
+
+module JpAddressComplement
+  # Rails との統合を担う Railtie
+  # @rbs inherits Rails::Railtie
+  class Railtie < Rails::Railtie
+    railtie_name :jp_address_complement
+
+    rake_tasks do
+      load File.expand_path('../tasks/jp_address_complement.rake', __dir__.to_s)
+    end
+
+    initializer 'jp_address_complement.setup_repository' do # steep:ignore
+      require_relative 'repositories/active_record_postal_code_repository'
+      require_relative 'models/postal_code'
+      JpAddressComplement.configuration.repository ||=
+        Repositories::ActiveRecordPostalCodeRepository.new
+    end
+
+    generators do
+      require_relative '../generators/jp_address_complement/install_generator'
+    end
+  end
+end

data/lib/jp_address_complement/repositories/active_record_postal_code_repository.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require_relative 'postal_code_repository'
+require_relative '../address_record'
+
+module JpAddressComplement
+  module Repositories
+    # ActiveRecord を使用した PostalCodeRepository の実装
+    # Rails 環境向けにバンドルされる標準実装
+    class ActiveRecordPostalCodeRepository < PostalCodeRepository
+      # @rbs (String code) -> Array[AddressRecord]
+      # @param code [String] 正規化済み7桁郵便番号
+      # @return [Array<AddressRecord>]
+      def find_by_code(code)
+        postal_code_model.where(postal_code: code).map { |ar| to_record(ar) } # steep:ignore
+      end
+
+      # @rbs (String prefix) -> Array[AddressRecord]
+      # @param prefix [String] 4桁以上の郵便番号プレフィックス
+      # @return [Array<AddressRecord>]
+      def find_by_prefix(prefix)
+        postal_code_model.where('postal_code LIKE ?', "#{prefix}%").map { |ar| to_record(ar) } # steep:ignore
+      end
+
+      # @rbs (pref: String?, city: String?, ?town: String?) -> Array[AddressRecord]
+      def find_postal_codes_by_address(pref:, city:, town: nil)
+        relation = address_relation(pref: pref, city: city, town: town)
+        return [] unless relation
+
+        relation.map { |ar| to_record(ar) } # steep:ignore
+      end
+
+      private
+
+      # @rbs (pref: String?, city: String?, ?town: String?) -> untyped
+      def address_relation(pref:, city:, town: nil)
+        return nil if pref.nil? || pref.to_s.strip.empty?
+        return nil if city.nil? || city.to_s.strip.empty?
+
+        relation = postal_code_model.where(pref: pref, city: city)
+        return relation if town.blank?
+
+        pattern = "#{escape_like(town.to_s.strip)}%"
+        relation.where('town LIKE ?', pattern)
+      end
+
+      # @rbs () -> singleton(PostalCode)
+      def postal_code_model
+        JpAddressComplement::PostalCode
+      end
+
+      # LIKE 句用に % _ \ をエスケープする
+      # @rbs (String) -> String
+      def escape_like(str)
+        str.gsub(/[%_\\]/) { "\\#{Regexp.last_match(0)}" }
+      end
+
+      # ActiveRecord の動的属性のため Steep の型が不足する。理由明記で抑制（research §7）
+      # @rbs (untyped postal_code_ar) -> AddressRecord
+      def to_record(postal_code_ar)
+        AddressRecord.new(
+          postal_code: postal_code_ar.postal_code,
+          pref_code: postal_code_ar.pref_code,
+          pref: postal_code_ar.pref,
+          city: postal_code_ar.city,
+          town: postal_code_ar.town,
+          kana_pref: postal_code_ar.kana_pref,
+          kana_city: postal_code_ar.kana_city,
+          kana_town: postal_code_ar.kana_town,
+          has_alias: postal_code_ar.has_alias,
+          is_partial: postal_code_ar.is_partial,
+          is_large_office: postal_code_ar.is_large_office
+        )
+      end
+    end
+  end
+end

data/lib/jp_address_complement/repositories/csv_postal_code_repository.rb

@@ -0,0 +1,200 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require 'csv'
+require_relative 'postal_code_repository'
+require_relative '../address_record'
+
+module JpAddressComplement
+  module Repositories
+    # UTF-8 版 KEN_ALL（utf_ken_all.csv）形式の CSV ファイルを直接読み込んで検索を行う Repository 実装
+    #
+    # - ActiveRecord や DB に依存せず、純粋に CSV から AddressRecord を構築する
+    # - 初回アクセス時に CSV 全体を読み込み、インメモリでインデックスを構築する（2回目以降はメモリ検索のみ）
+    # - CSV は日本郵便公式の KEN_ALL.CSV（UTF-8 版 utf_ken_all.csv）と同じ列構成を前提とする
+    #
+    # 典型的な利用例:
+    #
+    #   require 'jp_address_complement/repositories/csv_postal_code_repository'
+    #
+    #   JpAddressComplement.configure do |c|
+    #     c.repository = JpAddressComplement::Repositories::CsvPostalCodeRepository.new('/path/to/utf_ken_all.csv')
+    #   end
+    #
+    class CsvPostalCodeRepository < PostalCodeRepository
+      # 列インデックス（KEN_ALL.CSV 形式）
+      COL_PREF_CODE = 0 # : Integer
+      COL_POSTAL_CODE = 2 # : Integer
+      COL_KANA_PREF = 3 # : Integer
+      COL_KANA_CITY = 4 # : Integer
+      COL_KANA_TOWN = 5 # : Integer
+      COL_PREF = 6 # : Integer
+      COL_CITY = 7 # : Integer
+      COL_TOWN = 8 # : Integer
+      COL_IS_PARTIAL = 9 # : Integer
+      COL_HAS_ALIAS = 12 # : Integer
+      COL_IS_LARGE_OFFICE = 13 # : Integer
+
+      # @rbs (String csv_path) -> void
+      # @param csv_path [String] 読み込む KEN_ALL 形式 UTF-8 CSV のパス
+      def initialize(csv_path)
+        super()
+        @csv_path = csv_path
+        @loaded = false
+        @records = [] # : Array[AddressRecord]
+        @by_code = Hash.new { |h, k| h[k] = [] } # : Hash[String, Array[AddressRecord]]
+      end
+
+      # @rbs (String code) -> Array[AddressRecord]
+      def find_by_code(code)
+        ensure_loaded
+        @by_code[code] || []
+      end
+
+      # @rbs (String prefix) -> Array[AddressRecord]
+      def find_by_prefix(prefix)
+        ensure_loaded
+        @records.select { |r| r.postal_code.start_with?(prefix) }
+      end
+
+      # @rbs (pref: String?, city: String?, ?town: String?) -> Array[AddressRecord]
+      def find_postal_codes_by_address(pref:, city:, town: nil)
+        ensure_loaded
+        return [] if blank?(pref) || blank?(city)
+
+        town_query = town&.to_s&.strip
+        pref_s = pref.to_s
+        city_s = city.to_s
+        @records.select { |record| address_match?(record, pref_s, city_s, town_query) }
+      end
+
+      private
+
+      # @rbs () -> void
+      def ensure_loaded
+        return if @loaded
+
+        load_csv
+        @loaded = true
+      end
+
+      # @rbs () -> void
+      def load_csv
+        validate_csv_path!
+        @records.clear
+        @by_code.clear
+        each_csv_row { |row| append_record(row) }
+      rescue Errno::ENOENT
+        raise JpAddressComplement::Error, "CSV ファイルが見つかりません: #{@csv_path}"
+      rescue Encoding::InvalidByteSequenceError, Encoding::UndefinedConversionError, CSV::InvalidEncodingError => e
+        raise JpAddressComplement::Error, "CSV のエンコーディング変換に失敗しました: #{e.message}"
+      end
+
+      # @rbs () -> void
+      def validate_csv_path!
+        raise JpAddressComplement::Error, 'CSV ファイルが指定されていません' if @csv_path.nil? || @csv_path.to_s.empty?
+        raise JpAddressComplement::Error, "CSV ファイルが見つかりません: #{@csv_path}" unless File.exist?(@csv_path)
+      end
+
+      # @rbs () { (Array[String?]) -> void } -> void
+      def each_csv_row(&)
+        CSV.foreach(@csv_path, encoding: 'UTF-8', &)
+      end
+
+      # @rbs (Array[String?] row) -> void
+      def append_record(row)
+        record = build_record_from_row(row)
+        return if record.nil?
+
+        @records << record
+        @by_code[record.postal_code] << record
+      end
+
+      # @rbs (AddressRecord record, String pref, String city, String? town_query) -> bool
+      def address_match?(record, pref, city, town_query)
+        return false unless record.pref == pref && record.city == city
+        return true if town_query.nil? || town_query.empty?
+
+        record.town.to_s.start_with?(town_query)
+      end
+
+      # @rbs (Array[String?] row) -> (AddressRecord | nil)
+      def build_record_from_row(row)
+        attrs = parse_row_attrs(row)
+        return nil unless attrs
+
+        AddressRecord.new(
+          postal_code: attrs[:postal_code],
+          pref_code: attrs[:pref_code],
+          pref: attrs[:pref],
+          city: attrs[:city],
+          town: attrs[:town],
+          kana_pref: attrs[:kana_pref],
+          kana_city: attrs[:kana_city],
+          kana_town: attrs[:kana_town],
+          has_alias: attrs[:has_alias],
+          is_partial: attrs[:is_partial],
+          is_large_office: attrs[:is_large_office]
+        )
+      end
+
+      # @rbs (Array[String?] row) -> (Hash[Symbol, untyped] | nil)
+      def parse_row_attrs(row)
+        required = extract_required_fields(row)
+        return nil unless required && valid_postal_code_format?(required[0])
+
+        build_row_attrs(row, required[0], required[1], required[2], required[3])
+      end
+
+      # @rbs (Array[String?] row) -> (Array[String] | nil)
+      def extract_required_fields(row)
+        postal_code = strip_cell(row[COL_POSTAL_CODE])
+        pref_code = strip_cell(row[COL_PREF_CODE])&.slice(0, 2)
+        pref = strip_cell(row[COL_PREF])
+        city = strip_cell(row[COL_CITY])
+        return nil if [postal_code, pref_code, pref, city].any?(&:nil?)
+
+        # 上記ガードで nil は除外済み。型を Array[String] に合わせるため to_s で明示
+        [postal_code.to_s, pref_code.to_s, pref.to_s, city.to_s]
+      end
+
+      # @rbs (String? cell) -> (String | nil)
+      def strip_cell(cell)
+        cell&.strip
+      end
+
+      # @rbs (String? postal_code) -> bool
+      def valid_postal_code_format?(postal_code)
+        !postal_code.nil? && postal_code.match?(/\A\d{7}\z/)
+      end
+
+      # @rbs (Array[String?], String, String, String, String) -> Hash[Symbol, untyped]
+      def build_row_attrs(row, postal_code, pref_code, pref, city)
+        {
+          postal_code: postal_code,
+          pref_code: pref_code,
+          pref: pref,
+          city: city,
+          town: row[COL_TOWN]&.strip,
+          kana_pref: row[COL_KANA_PREF]&.strip,
+          kana_city: row[COL_KANA_CITY]&.strip,
+          kana_town: row[COL_KANA_TOWN]&.strip,
+          has_alias: flag?(row[COL_HAS_ALIAS]),
+          is_partial: flag?(row[COL_IS_PARTIAL]),
+          is_large_office: flag?(row[COL_IS_LARGE_OFFICE])
+        }
+      end
+
+      # @rbs (String? cell) -> bool
+      def flag?(cell)
+        cell&.strip == '1'
+      end
+
+      # @rbs (untyped value) -> bool
+      def blank?(value)
+        value.nil? || value.to_s.strip.empty?
+      end
+    end
+  end
+end

data/lib/jp_address_complement/repositories/postal_code_repository.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module JpAddressComplement
+  module Repositories
+    # データアクセスを抽象化するインターフェース基底クラス
+    # 具体的な実装は ActiveRecordPostalCodeRepository またはユーザー定義アダプターで行う
+    class PostalCodeRepository
+      # 7桁郵便番号で完全一致検索する
+      # @rbs (String code) -> Array[AddressRecord]
+      # @param code [String] 正規化済み7桁郵便番号
+      # @return [Array<AddressRecord>]
+      def find_by_code(code)
+        raise NotImplementedError, "#{self.class}#find_by_code を実装してください"
+      end
+
+      # 郵便番号プレフィックスで前方一致検索する
+      # @rbs (String prefix) -> Array[AddressRecord]
+      # @param prefix [String] 4桁以上の郵便番号プレフィックス
+      # @return [Array<AddressRecord>]
+      def find_by_prefix(prefix)
+        raise NotImplementedError, "#{self.class}#find_by_prefix を実装してください"
+      end
+
+      # 都道府県・市区町村・町域で検索する（逆引き）。町域は前方一致。
+      # @rbs (pref: String?, city: String?, ?town: String?) -> Array[AddressRecord]
+      # @param pref [String] 都道府県名（正式名称）
+      # @param city [String] 市区町村名
+      # @param town [String, nil] 町域名。省略時は都道府県＋市区町村のみ。指定時は前方一致で候補を返す
+      # @return [Array<AddressRecord>] 該当レコードの配列。該当なし・入力不十分時は []
+      def find_postal_codes_by_address(pref:, city:, town: nil)
+        raise NotImplementedError, "#{self.class}#find_postal_codes_by_address を実装してください"
+      end
+    end
+  end
+end