basho 0.2.2 → 0.4.0

data/lib/basho/active_record/postal_auto_resolve.rb

@@ -2,68 +2,62 @@
 
 module Basho
   module ActiveRecord
-    # 郵便番号変更時にbefore_saveで住所カラムを自動解決する
+    # 郵便番号変更時に +before_save+ で住所カラムを自動解決する。
+    # {Base#basho_postal} のマッピングオプション指定時に使用される。
+    #
+    # @api private
     module PostalAutoResolve
+      # サポートするマッピングキーの一覧
       MAPPING_KEYS = %i[prefecture city town prefecture_code city_code].freeze
-      RESOLVERS = {
-        prefecture: :prefecture_name,
-        city: :city_name,
-        town: :town,
-        prefecture_code: :prefecture_code,
-        city_code: :resolve_city_code
-      }.freeze
 
       module_function
 
+      # モデルに +before_save+ コールバックを登録する。
+      #
+      # @param model_class [Class] ActiveRecordモデルクラス
+      # @param postal_column [String] 郵便番号カラム名
+      # @param mappings [Hash] マッピング設定
+      # @return [void]
       def install(model_class, postal_column, mappings)
-        validate_model!(model_class)
+        unless model_class.respond_to?(:before_save)
+          raise Basho::Error, "#{model_class} does not support before_save callbacks"
+        end
 
         postal_col = postal_column.to_s
-        resolved = build_mappings(mappings)
-
-        register_callback(model_class, postal_col, resolved)
-      end
-
-      def validate_model!(model_class)
-        return if model_class.respond_to?(:before_save)
-
-        raise Basho::Error, "#{model_class} does not support before_save callbacks"
-      end
-
-      def build_mappings(mappings)
-        mappings.slice(*MAPPING_KEYS).transform_values(&:to_s).freeze
-      end
+        resolved = mappings.slice(*MAPPING_KEYS).transform_values(&:to_s).freeze
 
-      def register_callback(model_class, postal_col, resolved_mappings)
         model_class.before_save do
           next unless will_save_change_to_attribute?(postal_col)
 
-          postal = PostalAutoResolve.resolve_postal(send(postal_col))
+          postal = Basho::PostalCode.find(send(postal_col))
 
-          resolved_mappings.each do |key, target_col|
+          resolved.each do |key, target_col|
             send(:"#{target_col}=", PostalAutoResolve.resolve_value(postal, key))
           end
         end
       end
 
-      def resolve_postal(code)
-        return nil unless code
-
-        normalized = code.to_s.delete("-")
-        return nil unless normalized.match?(/\A\d{7}\z/)
-
-        Basho::PostalCode.find(normalized).first
-      end
-
+      # マッピングキーに対応する値を郵便番号データから解決する。
+      #
+      # @param postal [PostalCode, nil] 郵便番号データ
+      # @param key [Symbol] マッピングキー
+      # @return [String, Integer, nil]
       def resolve_value(postal, key)
         return nil unless postal
 
-        method_name = RESOLVERS[key]
-        return nil unless method_name
-
-        respond_to?(method_name, true) ? send(method_name, postal) : postal.public_send(method_name)
+        case key
+        when :prefecture      then postal.prefecture_name
+        when :city            then postal.city_name
+        when :town            then postal.town
+        when :prefecture_code then postal.prefecture_code
+        when :city_code       then resolve_city_code(postal)
+        end
       end
 
+      # 郵便番号データから自治体コードを逆引きする。
+      #
+      # @param postal [PostalCode] 郵便番号データ
+      # @return [String, nil] 6桁自治体コード
       def resolve_city_code(postal)
         City.where(prefecture_code: postal.prefecture_code)
             .find { |c| c.full_name == postal.city_name }&.code

data/lib/basho/city.rb

@@ -1,47 +1,76 @@
 # frozen_string_literal: true
 
 module Basho
+  # 市区町村を表すイミュータブルなデータクラス。
+  #
+  # DBバックエンドが有効な場合、クラスメソッドは自動的に {DB::City} 経由で検索する。
+  #
+  # @!attribute [r] code
+  #   @return [String] 6桁自治体コード（JIS X 0401 + チェックディジット、例: "131016"）
+  # @!attribute [r] prefecture_code
+  #   @return [Integer] 都道府県コード（1〜47）
+  # @!attribute [r] name
+  #   @return [String] 市区町村名（例: "千代田区"）
+  # @!attribute [r] name_kana
+  #   @return [String] カタカナ名（例: "チヨダク"）
+  # @!attribute [r] district
+  #   @return [String, nil] 郡名（例: "島尻郡"）。郡に属する町村のみ設定
+  # @!attribute [r] capital
+  #   @return [Boolean] 県庁所在地フラグ
   City = ::Data.define(:code, :prefecture_code, :name, :name_kana, :district, :capital) do
     def initialize(district: nil, capital: false, **)
       super
     end
 
+    # 県庁所在地かどうかを返す。
+    #
+    # @return [Boolean]
     def capital? = capital
 
+    # 郡名付きの正式名を返す。郡がない場合は {#name} と同じ。
+    #
+    # @return [String] 例: "島尻郡八重瀬町"
     def full_name
       district ? "#{district}#{name}" : name
     end
 
+    # 所属する都道府県を返す。
+    #
+    # @return [Prefecture, DB::Prefecture]
     def prefecture
       Prefecture.find(prefecture_code)
     end
 
     class << self
+      # 6桁自治体コードで市区町村を検索する。
+      #
+      # @param code [String] 6桁自治体コード（例: "131016"）
+      # @return [City, DB::City, nil]
       def find(code)
         return nil unless code.is_a?(String) && code.size == 6
+        return DB::City.find_by(code: code) if Basho.db?
 
-        prefecture_code = code[0..1].to_i
-        where(prefecture_code: prefecture_code).find { |city| city.code == code }
+        pref_code = code[0..1].to_i
+        where(prefecture_code: pref_code).find { |city| city.code == code }
       end
 
+      # 都道府県コードで市区町村を絞り込む。
+      #
+      # @param prefecture_code [Integer] 都道府県コード
+      # @return [Array<City>, Array<DB::City>]
       def where(prefecture_code:)
-        cities_cache[prefecture_code] ||=
-          Data::Loader.cities(prefecture_code).map { |data| new(**data) }.freeze
+        return DB::City.where(prefecture_code: prefecture_code).to_a if Basho.db?
+
+        Data::Loader.cities(prefecture_code).map { |data| new(**data) }
       end
 
+      # JIS X 0401 チェックディジットで自治体コードを検証する。
+      #
+      # @param code [String] 6桁自治体コード
+      # @return [Boolean]
       def valid_code?(code)
         CodeValidator.valid?(code)
       end
-
-      def reset!
-        @cities_cache = nil
-      end
-
-      private
-
-      def cities_cache
-        @cities_cache ||= {}
-      end
     end
   end
 end

data/lib/basho/code_validator.rb

@@ -1,14 +1,25 @@
 # frozen_string_literal: true
 
 module Basho
-  # JIS X 0401 チェックディジットによる自治体コード検証
+  # JIS X 0401 チェックディジットによる6桁自治体コードの検証。
+  #
+  # @example
+  #   Basho::CodeValidator.valid?("131016") # => true
+  #   Basho::CodeValidator.valid?("131019") # => false
   module CodeValidator
+    # チェックディジットの桁位置（0始まり）
     CHECK_DIGITS_INDEX = 5
+    # モジュラス演算の基数
     CHECK_BASE = 11
+    # 有効な都道府県コード範囲
     PREFECTURE_RANGE = (1..47)
 
     module_function
 
+    # 自治体コードの形式とチェックディジットを検証する。
+    #
+    # @param code [String] 6桁自治体コード
+    # @return [Boolean]
     def valid?(code)
       return false unless code.is_a?(String) && code.match?(/\A\d{6}\z/)
       return false unless PREFECTURE_RANGE.cover?(code[0..1].to_i)
@@ -16,6 +27,10 @@ module Basho
       code[CHECK_DIGITS_INDEX].to_i == compute_check_digit(code)
     end
 
+    # チェックディジットを計算する。
+    #
+    # @param code [String] 6桁自治体コード
+    # @return [Integer] 0〜9のチェックディジット
     def compute_check_digit(code)
       sub_total = code.chars
                       .take(CHECK_DIGITS_INDEX)

data/lib/basho/data/loader.rb

@@ -3,24 +3,43 @@
 require "json"
 
 module Basho
+  # 同梱データの読み込みに関する名前空間。
   module Data
-    # 組み込みJSONデータの遅延読み込みとキャッシュ
+    # 同梱JSONデータの遅延読み込みとキャッシュ。
+    # 各メソッドは初回呼び出し時にJSONファイルを読み込み、以降はキャッシュを返す。
+    #
+    # @api private
     class Loader
+      # 同梱JSONデータのディレクトリパス
       DATA_DIR = File.expand_path("../../../data", __dir__)
 
       class << self
+        # 全47都道府県データを返す。
+        #
+        # @return [Array<Hash>]
         def prefectures
           @prefectures ||= load_json("prefectures.json")
         end
 
+        # 指定した都道府県の市区町村データを返す。
+        #
+        # @param prefecture_code [Integer] 都道府県コード
+        # @return [Array<Hash>]
         def cities(prefecture_code)
           cities_cache[prefecture_code] ||= load_json("cities/#{format("%02d", prefecture_code)}.json")
         end
 
+        # 指定したプレフィックスの郵便番号データを返す。
+        #
+        # @param prefix [String] 3桁プレフィックス（例: "154"）
+        # @return [Array<Hash>]
         def postal_codes(prefix)
           postal_cache[prefix] ||= load_json("postal_codes/#{prefix}.json")
         end
 
+        # 全キャッシュをクリアする。
+        #
+        # @return [void]
         def reset!
           instance_variables.each { |var| remove_instance_variable(var) }
         end
@@ -37,7 +56,7 @@ module Basho
 
         def load_json(relative_path)
           path = File.join(DATA_DIR, relative_path)
-          return [] unless File.exist?(path)
+          return [] unless path.start_with?("#{DATA_DIR}/") && File.exist?(path)
 
           JSON.parse(File.read(path), symbolize_names: true)
         end

data/lib/basho/db/city.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Basho
+  module DB
+    # 市区町村のActiveRecordモデル（+basho_cities+ テーブル）。
+    # メモリ版 {Basho::City} と同じAPI（+full_name+, +capital?+）を提供する。
+    class City < ::ActiveRecord::Base
+      self.table_name = "basho_cities"
+      self.primary_key = "code"
+
+      belongs_to :prefecture,
+                 class_name: "Basho::DB::Prefecture",
+                 foreign_key: :prefecture_code,
+                 inverse_of: :cities
+
+      # 郡名付きの正式名を返す。
+      #
+      # @return [String]
+      def full_name
+        district ? "#{district}#{name}" : name
+      end
+    end
+  end
+end

data/lib/basho/db/prefecture.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Basho
+  module DB
+    # 都道府県のActiveRecordモデル（+basho_prefectures+ テーブル）。
+    # メモリ版 {Basho::Prefecture} と同じAPI（+type+, +region+, +capital+）を提供する。
+    class Prefecture < ::ActiveRecord::Base
+      self.table_name = "basho_prefectures"
+      self.primary_key = "code"
+
+      has_many :cities,
+               class_name: "Basho::DB::City",
+               foreign_key: :prefecture_code,
+               inverse_of: :prefecture
+
+      # @return [String] 種別（"都" / "道" / "府" / "県"）
+      def type = prefecture_type
+
+      # @return [Region]
+      def region = Region.find(region_name)
+
+      # @return [DB::City, nil] 県庁所在地
+      def capital = capital_code && Basho::DB::City.find_by(code: capital_code)
+    end
+  end
+end

data/lib/basho/db.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "active_record"
+require_relative "db/prefecture"
+require_relative "db/city"
+
+module Basho
+  # ActiveRecordバックエンド（オプション）。
+  # +basho_prefectures+ / +basho_cities+ テーブルへのアクセスとシードを提供する。
+  module DB
+    # JSONデータをDBに一括投入する。冪等（何度実行しても同じ結果）。
+    #
+    # @return [Hash{Symbol => Integer}] 投入件数（+:prefectures+, +:cities+）
+    def self.seed!
+      prefs = prefecture_rows
+      cities = city_rows
+
+      ::ActiveRecord::Base.transaction do
+        City.delete_all
+        Prefecture.delete_all
+
+        Prefecture.insert_all!(prefs)
+        City.insert_all!(cities)
+      end
+
+      { prefectures: prefs.size, cities: cities.size }
+    end
+
+    def self.prefecture_rows
+      Data::Loader.prefectures.map do |pref|
+        pref.except(:type).merge(prefecture_type: pref[:type])
+      end
+    end
+    private_class_method :prefecture_rows
+
+    def self.city_rows
+      (1..47).flat_map do |code|
+        Data::Loader.cities(code).map do |city|
+          { district: nil, capital: false, **city }
+        end
+      end
+    end
+    private_class_method :city_rows
+  end
+end

data/lib/basho/engine.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Basho
-  # Hotwire自動入力・カスケードセレクトを提供するRails Engine
+  # Hotwire郵便番号自動入力を提供するRails Engine
   class Engine < ::Rails::Engine
     isolate_namespace Basho
 
@@ -9,8 +9,18 @@ module Basho
       app.config.importmap.paths << root.join("config/importmap.rb") if app.config.respond_to?(:importmap)
     end
 
+    initializer "basho.helpers" do
+      ActiveSupport.on_load(:action_view) do
+        include Basho::FormHelper
+      end
+    end
+
     initializer "basho.assets" do |app|
       app.config.assets.paths << root.join("app/assets/javascripts") if app.config.respond_to?(:assets)
     end
+
+    rake_tasks do
+      load File.expand_path("../../tasks/basho.rake", __dir__)
+    end
   end
 end

data/lib/basho/postal_code.rb

@@ -1,25 +1,53 @@
 # frozen_string_literal: true
 
 module Basho
+  # 郵便番号を表すイミュータブルなデータクラス。
+  # 常にJSONファイルから読み込む（DBバックエンド対象外）。
+  #
+  # @!attribute [r] code
+  #   @return [String] 7桁郵便番号（ハイフンなし、例: "1540011"）
+  # @!attribute [r] prefecture_code
+  #   @return [Integer] 都道府県コード（1〜47）
+  # @!attribute [r] city_name
+  #   @return [String] 市区町村名（例: "世田谷区"）
+  # @!attribute [r] town
+  #   @return [String] 町域名（例: "上馬"）
   PostalCode = ::Data.define(:code, :prefecture_code, :city_name, :town) do
-    def initialize(city: nil, city_name: nil, **attrs)
-      super(city_name: city || city_name, **attrs)
-    end
-
+    # ハイフン付きの郵便番号を返す。
+    #
+    # @return [String] 例: "154-0011"
     def formatted_code
       "#{code[0..2]}-#{code[3..]}"
     end
 
+    # 都道府県名を返す。
+    #
+    # @return [String, nil] 例: "東京都"
     def prefecture_name
       prefecture&.name
     end
 
+    # 所属する都道府県を返す。
+    #
+    # @return [Prefecture, DB::Prefecture, nil]
     def prefecture
       Prefecture.find(prefecture_code)
     end
 
     class << self
+      # 郵便番号で検索する。ハイフン有無どちらも可。
+      #
+      # @param code [String] 郵便番号（例: "154-0011", "1540011"）
+      # @return [PostalCode, nil]
       def find(code)
+        where(code: code).first
+      end
+
+      # 郵便番号で検索し、配列で返す。共有郵便番号の場合は複数件。
+      #
+      # @param code [String] 郵便番号
+      # @return [Array<PostalCode>]
+      def where(code:)
         normalized = code.to_s.delete("-")
         return [] unless normalized.match?(/\A\d{7}\z/)
 

data/lib/basho/prefecture.rb

@@ -1,53 +1,94 @@
 # frozen_string_literal: true
 
 module Basho
+  # 都道府県を表すイミュータブルなデータクラス。
+  #
+  # DBバックエンドが有効な場合、クラスメソッドは自動的に {DB::Prefecture} 経由で検索する。
+  #
+  # @!attribute [r] code
+  #   @return [Integer] JIS X 0401 都道府県コード（1〜47）
+  # @!attribute [r] name
+  #   @return [String] 都道府県名（例: "東京都"）
+  # @!attribute [r] name_en
+  #   @return [String] 英語名（例: "Tokyo"）
+  # @!attribute [r] name_kana
+  #   @return [String] カタカナ名（例: "トウキョウト"）
+  # @!attribute [r] name_hiragana
+  #   @return [String] ひらがな名（例: "とうきょうと"）
+  # @!attribute [r] region_name
+  #   @return [String] 地方名（例: "関東"）
+  # @!attribute [r] type
+  #   @return [String] 種別（"都" / "道" / "府" / "県"）
+  # @!attribute [r] capital_code
+  #   @return [String] 県庁所在地の6桁自治体コード（例: "131041"）
   Prefecture = ::Data.define(:code, :name, :name_en, :name_kana, :name_hiragana, :region_name, :type, :capital_code) do
-    def initialize(region: nil, region_name: nil, **attrs)
-      super(region_name: region || region_name, **attrs)
-    end
-
+    # 所属する地方を返す。
+    #
+    # @return [Region]
     def region
       Region.find(region_name)
     end
 
+    # 所属する市区町村の一覧を返す。
+    #
+    # @return [Array<City>, Array<DB::City>]
     def cities
       City.where(prefecture_code: code)
     end
 
+    # 県庁所在地を返す。
+    #
+    # @return [City, DB::City, nil]
     def capital
       City.find(capital_code)
     end
 
     class << self
+      # 全47都道府県を返す。
+      #
+      # @return [Array<Prefecture>, Array<DB::Prefecture>]
       def all
-        @all ||= Data::Loader.prefectures.map { |data| new(**data) }
+        return DB::Prefecture.all.to_a if Basho.db?
+
+        @all ||= Data::Loader.prefectures.map { |data| new(**data) }.freeze
       end
 
-      def find(code_or_options = nil, **options)
-        case code_or_options
-        when Integer
-          all.find { |pref| pref.code == code_or_options }
-        when Hash
-          find_by_options(code_or_options)
-        else
-          find_by_options(options) if options.any?
-        end
+      # 都道府県を検索する。
+      #
+      # @overload find(code)
+      #   @param code [Integer] 都道府県コード
+      # @overload find(name:)
+      #   @param name [String] 日本語名（例: "東京都"）
+      # @overload find(name_en:)
+      #   @param name_en [String] 英語名（例: "Tokyo"）
+      # @return [Prefecture, DB::Prefecture, nil]
+      def find(code = nil, **options)
+        attrs = code.nil? ? options : { code: code }
+        return if attrs.empty?
+
+        key, value = attrs.first
+        return DB::Prefecture.find_by(key => value) if Basho.db?
+
+        all.find { |pref| pref.public_send(key) == value }
       end
 
+      # 都道府県を地方名で絞り込む。引数なしで全件返す。
+      #
+      # @param region [String, nil] 地方名（例: "関東"）
+      # @return [Array<Prefecture>, Array<DB::Prefecture>]
       def where(region: nil)
         return all unless region
+        return DB::Prefecture.where(region_name: region).to_a if Basho.db?
 
-        all.select { |pref| pref.region&.name == region }
+        all.select { |pref| pref.region_name == region }
       end
 
-      private
-
-      def find_by_options(options)
-        if options[:name]
-          all.find { |pref| pref.name == options[:name] }
-        elsif options[:name_en]
-          all.find { |pref| pref.name_en == options[:name_en] }
-        end
+      # メモリキャッシュをクリアする。
+      #
+      # @return [void]
+      # @api private
+      def reset_cache!
+        remove_instance_variable(:@all) if defined?(@all)
       end
     end
   end

data/lib/basho/region.rb

@@ -1,12 +1,27 @@
 # frozen_string_literal: true
 
 module Basho
+  # 地方区分を表すイミュータブルなデータクラス。
+  # 北海道、東北、関東、中部、近畿、中国、四国、九州、沖縄の9地方。
+  #
+  # @!attribute [r] name
+  #   @return [String] 地方名（例: "関東"）
+  # @!attribute [r] name_en
+  #   @return [String] 英語名（例: "Kanto"）
+  # @!attribute [r] prefecture_codes
+  #   @return [Array<Integer>] 所属する都道府県コードの配列
   Region = ::Data.define(:name, :name_en, :prefecture_codes) do
+    # 所属する都道府県の一覧を返す。
+    #
+    # @return [Array<Prefecture>]
     def prefectures
       prefecture_codes.map { |code| Prefecture.find(code) }
     end
 
     class << self
+      # 全9地方を返す。
+      #
+      # @return [Array<Region>]
       def all
         @all ||= [
           new(name: "北海道", name_en: "Hokkaido", prefecture_codes: [1]),
@@ -21,6 +36,10 @@ module Basho
         ].freeze
       end
 
+      # 日本語名または英語名で地方を検索する。
+      #
+      # @param name [String] 地方名（例: "関東", "Kanto"）
+      # @return [Region, nil]
       def find(name)
         all.find { |region| region.name == name || region.name_en == name }
       end

data/lib/basho/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module Basho
-  VERSION = "0.2.2"
+  # @return [String] 現在のgemバージョン
+  VERSION = "0.4.0"
 end