basho 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 60bd164ce175bcaf79c4039521edc6a51712fc979edf3ae9a02c10841f624949
-  data.tar.gz: c00ec624a6523026bb2d1f219d8d301cdf1bd7488bc542d31b644e264989201d
+  metadata.gz: 0d571071cfeea78be4b3afdb28200668b434c582a17382a170e25db60c9e5939
+  data.tar.gz: 61a142f2363cce678572ca3815c5bcf3754a8722afa6437321c5999beab8d454
 SHA512:
-  metadata.gz: '00694bd8ed6fd2e1f7a385aa1051cdaba6cb89b8636c65793a6da5f43f586ce9c7f52b7ed6caf1e1947ea5f1185e74509b515b45d5df6c479a6a4eb30efcf7d3'
-  data.tar.gz: be33e1e0f6c0fa08284e84e7d70c5b1cb3b5d84bf6745cf7b88048ffed96dad8b256e62bc4a483d120162250f9b9ce4fbec2ce0704db4fd26ed1764dfe9f0a06
+  metadata.gz: 3ba4b016103fd8d4564080729dd82c20d0da5bdaa01ebc41a05438b94066abb9f7d38d8820b344ce622e426d735623d3f44972d01a4957def4fb3e3af2e8d639
+  data.tar.gz: 590d049ff6bde79407682e06806232841b3d40249588c09dd128cc6cf1b8f06afac66e2bbbe80473142ab6aff4178cf5bef81de6db2b69d7c980f4d4a57d273b

data/CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2026-02-11
+
+### Added
+
+- `with_basho` スコープ — city・prefectureをeager loadしN+1クエリを防止（メモリモードではno-op）
+- `has_one :basho_prefecture` — prefecture直接プリロード対応（DBモード）
+- `Basho::DB::City` に廃止・合併管理機能（`deprecated_at`, `successor_code`, `#current`, `.active`, `.deprecated`）
+- `Basho::City`（メモリモード）にも同等の廃止・合併API（`#deprecated?`, `#active?`, `#successor`, `#current`）
+- `Basho::DB.seed_fresh?` — DBデータの鮮度チェック（Rails起動時に自動警告）
+- `rails generate basho:upgrade_deprecation` — 既存テーブルに廃止管理カラムを追加するマイグレーションジェネレータ
+- `MAX_SUCCESSOR_DEPTH` — 合併チェーン探索の深度制限（ループ検出に加えた安全弁）
+
+### Changed
+
+- `Basho::DB.seed!` を `delete_all` + `insert_all!` から `upsert_all` に変更（手動設定の `successor_code` / `deprecated_at` を保持）
+- gemデータから消えた市区町村を物理削除ではなく論理削除（`deprecated_at` を設定）に変更
+- `basho` マクロのリファクタリング（DB/メモリモードの分離、メソッド分割）
+
 ## [0.4.1] - 2026-02-11
 
 ### Fixed
@@ -103,6 +121,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - GitHub Actions CI（Ruby 3.2/3.3/3.4）
 - 月次データ自動更新ワークフロー
 
+[0.5.0]: https://github.com/wagai/basho/releases/tag/v0.5.0
 [0.4.1]: https://github.com/wagai/basho/releases/tag/v0.4.1
 [0.4.0]: https://github.com/wagai/basho/releases/tag/v0.4.0
 [0.3.0]: https://github.com/wagai/basho/releases/tag/v0.3.0

data/README.ja.md

@@ -197,13 +197,28 @@ shop.prefecture   # => Basho::Prefecture
 shop.full_address # => "東京都千代田区"
 ```
 
-`basho :column`は3つのインスタンスメソッドを定義します:
+`basho :column`は3つのインスタンスメソッドとスコープを定義します:
 
 | メソッド | 戻り値 |
 |---------|--------|
 | `city` | カラム値で検索した`Basho::City` |
 | `prefecture` | `city.prefecture`経由の`Basho::Prefecture` |
 | `full_address` | `"#{prefecture.name}#{city.name}"` または `nil` |
+| `with_basho` | city・prefectureをプリロードするスコープ（N+1防止） |
+
+#### N+1防止
+
+複数レコードで`city`や`prefecture`にアクセスする場合は`with_basho`スコープを使います:
+
+```ruby
+# なし: N+1クエリ（1 + N×2）
+Shop.all.each { |s| s.full_address }
+
+# あり: 合計3クエリ
+Shop.with_basho.each { |s| s.full_address }
+```
+
+`with_basho`はメモリモード・DBモード両方で動きます。メモリモードではno-op、DBモードではアソシエーションをeager loadします。DB切り替え前から書いておけば、切り替え後にコード変更は不要です。
 
 ### 郵便番号から住所文字列を取得
 

data/README.md

@@ -197,13 +197,28 @@ shop.prefecture   # => Basho::Prefecture
 shop.full_address # => "東京都千代田区"
 ```
 
-`basho :column` defines three instance methods:
+`basho :column` defines three instance methods and a scope:
 
 | Method | Return value |
 |--------|-------------|
 | `city` | `Basho::City` found by the column value |
 | `prefecture` | `Basho::Prefecture` via `city.prefecture` |
 | `full_address` | `"#{prefecture.name}#{city.name}"` or `nil` |
+| `with_basho` | Scope that preloads city and prefecture (N+1 prevention) |
+
+#### N+1 Prevention
+
+Use the `with_basho` scope when loading multiple records that access `city` or `prefecture`:
+
+```ruby
+# Without: N+1 queries (1 + N×2)
+Shop.all.each { |s| s.full_address }
+
+# With: 3 queries total
+Shop.with_basho.each { |s| s.full_address }
+```
+
+`with_basho` works in both memory and DB mode. In memory mode it is a no-op; in DB mode it eager-loads the associations. This means you can add it before switching to DB mode -- no code changes needed later.
 
 ### Get an address string from a postal code
 

data/data/deprecated_cities.json

@@ -0,0 +1 @@
+[]

data/lib/basho/active_record/base.rb

@@ -15,20 +15,19 @@ module Basho
     #     basho_postal :postal_code, prefecture: :pref_name, city: :city_name
     #   end
     module Base
-      # 自治体コードカラムから +city+, +prefecture+, +full_address+ メソッドを定義する。
+      # 自治体コードカラムから +city+, +prefecture+, +full_address+ メソッドと
+      # +with_basho+ スコープを定義する。
+      #
+      # DBモードでは +belongs_to :basho_city+ と +has_one :basho_prefecture+ を追加し、
+      # +with_basho+ スコープでN+1クエリを防止する。
+      # メモリモードでは +with_basho+ はno-op（+all+）となる。
       #
       # @param column [Symbol, String] 6桁自治体コードを格納するカラム名
       # @return [void]
       def basho(column)
         column_name = column.to_s
-
-        define_method(:city) { (c = send(column_name)) && Basho::City.find(c) }
-        define_method(:prefecture) { city&.prefecture }
-        define_method(:full_address) do
-          pref = prefecture
-          cty = city
-          "#{pref.name}#{cty.name}" if pref && cty
-        end
+        Basho.db? ? basho_db_mode(column_name) : basho_memory_mode(column_name)
+        basho_define_full_address
       end
 
       # 郵便番号カラムから +postal_address+ メソッドを定義する。
@@ -57,6 +56,57 @@ module Basho
 
         PostalAutoResolve.install(self, column_name, mappings) if mappings.any?
       end
+
+      private
+
+      # @private DBモードのアソシエーションとスコープを定義する。
+      def basho_db_mode(column_name)
+        basho_db_associations(column_name)
+        scope :with_basho, -> { includes(basho_city: :prefecture) }
+        basho_db_methods
+      end
+
+      # @private DBモードのアソシエーションを定義する。
+      def basho_db_associations(column_name)
+        belongs_to :basho_city,
+                   class_name: "Basho::DB::City",
+                   foreign_key: column_name,
+                   primary_key: "code",
+                   optional: true
+
+        has_one :basho_prefecture,
+                through: :basho_city,
+                source: :prefecture
+      end
+
+      # @private DBモードのインスタンスメソッドを定義する。
+      def basho_db_methods
+        define_method(:city) { basho_city }
+        define_method(:prefecture) do
+          if association(:basho_prefecture).loaded?
+            basho_prefecture
+          else
+            basho_city&.prefecture
+          end
+        end
+      end
+
+      # @private メモリモードのスコープ・メソッドを定義する。
+      def basho_memory_mode(column_name)
+        scope(:with_basho, -> { all }) if respond_to?(:scope)
+
+        define_method(:city) { (c = send(column_name)) && Basho::City.find(c) }
+        define_method(:prefecture) { city&.prefecture }
+      end
+
+      # @private full_addressメソッドを定義する。
+      def basho_define_full_address
+        define_method(:full_address) do
+          pref = prefecture
+          cty = city
+          "#{pref.name}#{cty.name}" if pref && cty
+        end
+      end
     end
   end
 end

data/lib/basho/city.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Basho
+  MAX_SUCCESSOR_DEPTH = 10
   # 市区町村を表すイミュータブルなデータクラス。
   #
   # DBバックエンドが有効な場合、クラスメソッドは自動的に {DB::City} 経由で検索する。
@@ -17,8 +18,13 @@ module Basho
   #   @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, **)
+  # @!attribute [r] deprecated_at
+  #   @return [String, nil] 廃止日（例: "2025-04-01"）。現行自治体は +nil+
+  # @!attribute [r] successor_code
+  #   @return [String, nil] 合併先の6桁自治体コード。合併先がない場合は +nil+
+  City = ::Data.define(:code, :prefecture_code, :name, :name_kana, :district, :capital,
+                       :deprecated_at, :successor_code) do
+    def initialize(district: nil, capital: false, deprecated_at: nil, successor_code: nil, **)
       super
     end
 
@@ -34,6 +40,43 @@ module Basho
       district ? "#{district}#{name}" : name
     end
 
+    # 廃止済みかどうかを返す。
+    #
+    # @return [Boolean]
+    def deprecated? = !deprecated_at.nil?
+
+    # 現行（未廃止）かどうかを返す。
+    #
+    # @return [Boolean]
+    def active? = deprecated_at.nil?
+
+    # 合併先の市区町村を返す。
+    #
+    # @return [City, nil]
+    def successor
+      City.find(successor_code) if successor_code
+    end
+
+    # 合併チェーンをたどり、現行の市区町村を返す。
+    # アクティブ市区町村は即座に自身を返す。ループ検出・深度制限付き。
+    #
+    # @return [City]
+    def current
+      return self unless successor_code
+
+      city = self
+      seen = Set.new
+      while city.successor_code && seen.add?(city.successor_code)
+        break if seen.size > MAX_SUCCESSOR_DEPTH
+
+        next_city = City.find(city.successor_code)
+        break unless next_city
+
+        city = next_city
+      end
+      city
+    end
+
     # 所属する都道府県を返す。
     #
     # @return [Prefecture, DB::Prefecture]
@@ -51,7 +94,8 @@ module Basho
         return DB::City.find_by(code: code) if Basho.db?
 
         pref_code = code[0..1].to_i
-        where(prefecture_code: pref_code).find { |city| city.code == code }
+        where(prefecture_code: pref_code).find { |city| city.code == code } ||
+          find_deprecated(code)
       end
 
       # 都道府県コードで市区町村を絞り込む。
@@ -71,6 +115,12 @@ module Basho
       def valid_code?(code)
         CodeValidator.valid?(code)
       end
+
+      private
+
+      def find_deprecated(code)
+        Data::Loader.deprecated_city(code)&.then { |data| new(**data) }
+      end
     end
   end
 end

data/lib/basho/data/loader.rb

@@ -29,6 +29,21 @@ module Basho
           cities_cache[prefecture_code] ||= load_json("cities/#{format("%02d", prefecture_code)}.json")
         end
 
+        # 廃止された市区町村データを返す。
+        #
+        # @return [Array<Hash>]
+        def deprecated_cities
+          @deprecated_cities ||= load_json("deprecated_cities.json")
+        end
+
+        # 廃止コードで1件検索する（ハッシュインデックスによる O(1) ルックアップ）。
+        #
+        # @param code [String] 6桁自治体コード
+        # @return [Hash, nil]
+        def deprecated_city(code)
+          deprecated_cities_by_code[code]
+        end
+
         # 指定したプレフィックスの郵便番号データを返す。
         #
         # @param prefix [String] 3桁プレフィックス（例: "154"）
@@ -54,6 +69,10 @@ module Basho
           @postal_cache ||= {}
         end
 
+        def deprecated_cities_by_code
+          @deprecated_cities_by_code ||= deprecated_cities.to_h { |c| [c[:code], c] }
+        end
+
         def load_json(relative_path)
           path = File.join(DATA_DIR, relative_path)
           return [] unless path.start_with?("#{DATA_DIR}/") && File.exist?(path)

data/lib/basho/db/city.rb

@@ -13,6 +13,35 @@ module Basho
                  foreign_key: :prefecture_code,
                  inverse_of: :cities
 
+      belongs_to :successor,
+                 class_name: "Basho::DB::City",
+                 foreign_key: :successor_code,
+                 primary_key: :code,
+                 optional: true
+
+      scope :active, -> { where(deprecated_at: nil) }
+      scope :deprecated, -> { where.not(deprecated_at: nil) }
+
+      def deprecated? = deprecated_at.present?
+      def active? = deprecated_at.nil?
+
+      # 合併チェーンをたどって現行の自治体を返す（ループ検出・深度制限付き）。
+      #
+      # @return [Basho::DB::City]
+      def current
+        city = self
+        seen = Set.new
+        while city.successor_code.present? && seen.add?(city.successor_code)
+          break if seen.size > MAX_SUCCESSOR_DEPTH
+
+          next_city = city.successor
+          break unless next_city
+
+          city = next_city
+        end
+        city
+      end
+
       # 郡名付きの正式名を返す。
       #
       # @return [String]

data/lib/basho/db.rb

@@ -9,6 +9,7 @@ module Basho
   # +basho_prefectures+ / +basho_cities+ テーブルへのアクセスとシードを提供する。
   module DB
     # JSONデータをDBに一括投入する。冪等（何度実行しても同じ結果）。
+    # upsert_allで既存レコードを保持しつつ更新し、gemデータから消えた市区町村は論理削除する。
     #
     # @return [Hash{Symbol => Integer}] 投入件数（+:prefectures+, +:cities+）
     def self.seed!
@@ -16,16 +17,41 @@ module Basho
       cities = city_rows
 
       ::ActiveRecord::Base.transaction do
-        City.delete_all
-        Prefecture.delete_all
-
-        Prefecture.insert_all!(prefs)
-        City.insert_all!(cities)
+        Prefecture.upsert_all(prefs, unique_by: :code)
+        upsert_cities(cities)
+        deprecate_removed_cities(cities)
       end
 
       { prefectures: prefs.size, cities: cities.size }
     end
 
+    # DBのアクティブな市区町村件数がgemの同梱データと一致するか判定する。
+    # 市区町村の合併・分割で件数が変わるため、不一致はシード更新が必要なサイン。
+    #
+    # @return [Boolean]
+    def self.seed_fresh?
+      expected = (1..47).sum { |code| Data::Loader.cities(code).size }
+      City.active.count == expected
+    rescue ::ActiveRecord::ActiveRecordError
+      false
+    end
+
+    def self.upsert_cities(cities)
+      City.upsert_all(
+        cities,
+        unique_by: :code,
+        update_only: %i[prefecture_code name name_kana district capital]
+      )
+    end
+    private_class_method :upsert_cities
+
+    def self.deprecate_removed_cities(cities)
+      gem_codes = cities.to_set { |c| c[:code] }
+      stale_codes = City.where(deprecated_at: nil).pluck(:code).reject { |c| gem_codes.include?(c) }
+      City.where(code: stale_codes).update_all(deprecated_at: Time.current) if stale_codes.any?
+    end
+    private_class_method :deprecate_removed_cities
+
     def self.prefecture_rows
       Data::Loader.prefectures.map do |pref|
         pref.except(:type).merge(prefecture_type: pref[:type])

data/lib/basho/engine.rb

@@ -19,6 +19,20 @@ module Basho
       app.config.assets.paths << root.join("app/assets/javascripts") if app.config.respond_to?(:assets)
     end
 
+    initializer "basho.seed_freshness_check" do
+      config.after_initialize do
+        next unless Basho.db?
+        next if Basho::DB.seed_fresh?
+
+        Rails.logger.warn(
+          "[basho] DBのアクティブな市区町村件数がgemのデータと一致しません。" \
+          "`rails basho:seed` を実行してください"
+        )
+      rescue ::ActiveRecord::ActiveRecordError
+        # DB未接続・マイグレーション前は無視
+      end
+    end
+
     rake_tasks do
       load File.expand_path("../tasks/basho.rake", __dir__)
     end

data/lib/basho/version.rb

@@ -2,5 +2,5 @@
 
 module Basho
   # @return [String] 現在のgemバージョン
-  VERSION = "0.4.1"
+  VERSION = "0.5.0"
 end

data/lib/generators/basho/install_tables/templates/create_basho_cities.rb.erb

@@ -7,6 +7,8 @@ class CreateBashoCities < ActiveRecord::Migration[<%= ActiveRecord::Migration.cu
       t.string :name_kana, null: false
       t.string :district
       t.boolean :capital, null: false, default: false
+      t.datetime :deprecated_at
+      t.string :successor_code, limit: 6
     end
 
     add_index :basho_cities, :prefecture_code

data/lib/generators/basho/upgrade_deprecation/templates/add_deprecation_to_basho_cities.rb.erb

@@ -0,0 +1,6 @@
+class AddDeprecationToBashoCities < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    add_column :basho_cities, :deprecated_at, :datetime
+    add_column :basho_cities, :successor_code, :string, limit: 6
+  end
+end

data/lib/generators/basho/upgrade_deprecation/upgrade_deprecation_generator.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Basho
+  module Generators
+    # 既存の +basho_cities+ テーブルに +deprecated_at+ / +successor_code+ を追加するマイグレーションジェネレータ。
+    #
+    # @example
+    #   rails generate basho:upgrade_deprecation
+    class UpgradeDeprecationGenerator < Rails::Generators::Base
+      include ::ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "basho_cities テーブルに deprecated_at / successor_code カラムを追加"
+
+      def create_migration_file
+        migration_template(
+          "add_deprecation_to_basho_cities.rb.erb",
+          "db/migrate/add_deprecation_to_basho_cities.rb"
+        )
+      end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: basho
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Hirotaka Wagai
@@ -76,6 +76,7 @@ files:
 - data/cities/45.json
 - data/cities/46.json
 - data/cities/47.json
+- data/deprecated_cities.json
 - data/postal_codes/001.json
 - data/postal_codes/002.json
 - data/postal_codes/003.json
@@ -1042,6 +1043,8 @@ files:
 - lib/generators/basho/install_tables/install_tables_generator.rb
 - lib/generators/basho/install_tables/templates/create_basho_cities.rb.erb
 - lib/generators/basho/install_tables/templates/create_basho_prefectures.rb.erb
+- lib/generators/basho/upgrade_deprecation/templates/add_deprecation_to_basho_cities.rb.erb
+- lib/generators/basho/upgrade_deprecation/upgrade_deprecation_generator.rb
 - lib/tasks/basho.rake
 - sig/basho.rbs
 homepage: https://github.com/wagai/basho
@@ -1066,7 +1069,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.4
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Japanese address data (prefectures, cities, postal codes, regions) in a single
   gem