basho 0.2.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c5c51563bcdb143a92a3dd9e3a639b45b0fdf91911f792444421fc1b5ec26b6c
-  data.tar.gz: c95190b949c602b9e462a4d625e05e2d2e706b7c763b1b0e18dd4409a7fd358c
+  metadata.gz: a14446b90ac21440261e1558b52c2341bbe32fb4ab719c2b04932c3a7b34a5cf
+  data.tar.gz: 4416cb182886440853437ebc63c85d60028063fb9d282edd9a61883cb90060e5
 SHA512:
-  metadata.gz: a9fb8dbf6572c8e1a7803743789a559bdaad88af2614c94a707ad4dc5bc445ec491d0bcf4c3e5a03fe3db472d18b80329bf2adff7d4c37b59909a6f653ff3a9c
-  data.tar.gz: 4ea4a2d23dfbe54d4250577154aff29d27ad80443a59a5d6fc24d67dcb51aeee592f8d51f303e8208a2efe9407f4e3135321b19b8fa61e8fda652f4e94d6799b
+  metadata.gz: 01632dfab1fcbd4c3186cf289ceb9bcd0ddbe6aee1ad8253306e1c2cb08ea676b0d84cda27c7c7bbff7de47dd802c651eb876104e4d221793e0cffe7c868936d
+  data.tar.gz: cda91a973465799bc067da98d038339ad71cd9095be33fe7f86f7ab0679de57ad7c7927798bce0451a1a65c6d174bddaad9ae4eea086568035558a4269d2942e

data/.yardopts

@@ -0,0 +1,8 @@
+--markup markdown
+--charset utf-8
+--output-dir doc
+lib/**/*.rb
+-
+README.md
+CHANGELOG.md
+LICENSE.txt

data/CHANGELOG.md

@@ -5,6 +5,53 @@ 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.4.0] - 2026-02-11
+
+### Added
+
+- オプションDBバックエンド（`basho_prefectures` / `basho_cities` テーブル）
+- `rails generate basho:install_tables` マイグレーションジェネレータ
+- `rails basho:seed` Rakeタスク（冪等、JSON→DB一括投入）
+- `Basho::DB::Prefecture` / `Basho::DB::City` ActiveRecordモデル
+- `Basho.db?` によるDB自動検出（スレッドセーフ、キャッシュ付き）
+- テーブルが存在すれば公開API（`Prefecture.find`, `City.where`等）が自動でDB経由に切り替わる
+- READMEにDB Backendセクション追加（EN/JA）
+
+## [0.3.0] - 2026-02-11
+
+### Changed
+
+- **BREAKING**: `PostalCode.find()` が配列ではなく単一の `PostalCode` または `nil` を返すように変更
+- **BREAKING**: `PostalCode.where()` がキーワード引数 `where(code:)` に変更
+- **BREAKING**: カスケードセレクト機能を削除（Stimulusコントローラー、都道府県/市区町村JSON API、フォームヘルパー）
+- **BREAKING**: 郵便番号JSONのキー名 `city` → `city_name`、都道府県JSONのキー名 `region` → `region_name` に統一
+- `auto_fill_controller.js` をTurboイベント駆動にシンプル化（デバウンス削除）
+- `PostalAutoResolve` をシンプルなcase文ベースに簡素化
+- 市区町村データソースを `jp_local_gov` gem から KEN_ALL.CSV に変更（外部gem依存を撤廃）
+- `districts.rb` のロジックを `cities.rb` に統合
+
+### Added
+
+- `PostalCode.where(code:)` - 配列で結果を返す検索メソッド
+- Engine initializerでフォームヘルパーを自動インクルード
+- `Data::Loader` にパストラバーサル防御を追加
+
+### Fixed
+
+- KEN_ALL.CSVインポートの複数行町域名結合バグを修正（208件）
+- 「の次に番地がくる場合」の町域名が空にならないバグを修正（17件）
+- 名古屋市・大阪市・広島市の不正なdistrictデータを修正
+- 市区町村カナを正規化（旧式カタカナ → 正式カタカナ、15件）
+
+### Removed
+
+- `Basho::PrefecturesController` （都道府県/市区町村JSON API）
+- `basho_cascade_data` フォームヘルパーメソッド
+- `cascade_select_controller.js` Stimulusコントローラー
+- `/basho/prefectures` ルート
+- `tasks/import/districts.rb`（`cities.rb` に統合）
+- `jp_local_gov` gem への依存
+
 ## [0.2.2] - 2026-02-09
 
 ### Fixed
@@ -50,6 +97,8 @@ 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.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
 [0.2.2]: https://github.com/wagai/basho/releases/tag/v0.2.2
 [0.2.1]: https://github.com/wagai/basho/releases/tag/v0.2.1
 [0.2.0]: https://github.com/wagai/basho/releases/tag/v0.2.0

data/README.ja.md

@@ -15,10 +15,14 @@
 
 Bashoはこれらをまとめて解決します。
 
-- **DBマイグレーション不要** — 全データをJSON同梱。`gem install`だけで使える
-- **ActiveRecord統合** — `include Basho` + 1行のマクロで郵便番号→住所の自動保存
-- **Hotwire対応** — 郵便番号自動入力・カスケードセレクトをビルトインEngine提供
-- **軽量** — `Data.define`によるイミュータブルモデル、遅延読み込み、外部依存なし
+## 特徴
+
+- **DBマイグレーション不要** -- 全データをJSON同梱。`gem install`だけで使える
+- **オプションDBバックエンド** -- テーブル生成でJOINや外部キー制約に対応。APIは自動で切り替わる
+- **フレームワーク非依存** -- 素のRuby、Sinatra、Rails API only、どこでも動く
+- **ActiveRecord統合** -- `include Basho` + 1行のマクロで郵便番号→住所の自動保存
+- **Hotwire対応** -- Turbo Frame + Stimulusによる郵便番号自動入力をビルトインEngine提供
+- **軽量** -- `Data.define`によるイミュータブルモデル、遅延読み込み、外部依存なし
 
 ## 対応バージョン
 
@@ -40,7 +44,7 @@ bundle install
 ### 郵便番号から住所を引く
 
 ```ruby
-postal = Basho::PostalCode.find("154-0011").first
+postal = Basho::PostalCode.find("154-0011")
 postal.prefecture_name  # => "東京都"
 postal.city_name        # => "世田谷区"
 postal.town             # => "上馬"
@@ -77,70 +81,109 @@ Basho::City.find("131016").name            # => "千代田区"
 ### Prefecture（都道府県）
 
 ```ruby
-Basho::Prefecture.find(13)             # コードで検索
-Basho::Prefecture.find(name: "東京都")  # 名前で検索
-Basho::Prefecture.all                   # 全47件
-Basho::Prefecture.where(region: "関東") # 地方で絞り込み
+# クラスメソッド
+Basho::Prefecture.find(13)                 # コードで検索（Integer）
+Basho::Prefecture.find(name: "東京都")      # 日本語名で検索
+Basho::Prefecture.find(name_en: "Tokyo")   # 英語名で検索
+Basho::Prefecture.all                      # 全47件
+Basho::Prefecture.where(region: "関東")     # 地方名で絞り込み
+```
 
+```ruby
+# インスタンスメソッド / メンバー
 pref = Basho::Prefecture.find(13)
-pref.code          # => 13
-pref.name          # => "東京都"
-pref.name_en       # => "Tokyo"
-pref.name_kana     # => "トウキョウト"
-pref.name_hiragana # => "とうきょうと"
-pref.type          # => "都"
-pref.region        # => Region
-pref.cities        # => Array<City>
-pref.capital       # => City（県庁所在地）
+pref.code          # => 13            (Integer)
+pref.name          # => "東京都"       (String)
+pref.name_en       # => "Tokyo"       (String)
+pref.name_kana     # => "トウキョウト"  (String, カタカナ)
+pref.name_hiragana # => "とうきょうと"  (String, ひらがな)
+pref.region_name   # => "関東"         (String)
+pref.type          # => "都"           (String: "都" / "道" / "府" / "県")
+pref.capital_code  # => "131016"       (String, 6桁自治体コード)
+pref.region        # => Basho::Region
+pref.cities        # => Array<Basho::City>
+pref.capital       # => Basho::City（県庁所在地）
 ```
 
 ### City（市区町村）
 
 ```ruby
-Basho::City.find("131016")              # 自治体コードで検索
-Basho::City.where(prefecture_code: 13)  # 都道府県で絞り込み
-Basho::City.valid_code?("131016")       # チェックディジット検証
+# クラスメソッド
+Basho::City.find("131016")              # 6桁自治体コードで検索（String）
+Basho::City.where(prefecture_code: 13)  # 都道府県コードで絞り込み（Integer）
+Basho::City.valid_code?("131016")       # JIS X 0401 チェックディジット検証
+```
 
+```ruby
+# インスタンスメソッド / メンバー
 city = Basho::City.find("131016")
-city.code             # => "131016"
-city.prefecture_code  # => 13
-city.name             # => "千代田区"
-city.name_kana        # => "チヨダク"
-city.capital?         # => false
-city.prefecture       # => Prefecture
+city.code             # => "131016"    (String, 6桁)
+city.prefecture_code  # => 13          (Integer)
+city.name             # => "千代田区"   (String)
+city.name_kana        # => "チヨダク"   (String, カタカナ)
+city.district         # => nil         (String or nil, 例: "島尻郡")
+city.capital          # => false       (Boolean, 生のメンバー)
+city.capital?         # => false       (Boolean, 県庁所在地か?)
+city.full_name        # => "千代田区"   (String, 郡名がある場合は先頭に付与)
+city.prefecture       # => Basho::Prefecture
+```
+
+`district`は郡に属する町村にのみ設定されます。例:
+
+```ruby
+city = Basho::City.find("473821")
+city.name       # => "八重瀬町"
+city.district   # => "島尻郡"
+city.full_name  # => "島尻郡八重瀬町"
 ```
 
 ### PostalCode（郵便番号）
 
+`find`は単一の`PostalCode`または`nil`を返します。`where`は`Array`を返します（共有郵便番号の場合、複数件返ることがあります）。
+
 ```ruby
-results = Basho::PostalCode.find("154-0011")  # 常にArrayを返す
-results = Basho::PostalCode.find("1540011")    # ハイフンなしも可
+# クラスメソッド
+Basho::PostalCode.find("154-0011")         # => PostalCode or nil（最初の1件）
+Basho::PostalCode.find("1540011")          # ハイフンなしも可
+Basho::PostalCode.where(code: "154-0011")  # => Array<PostalCode>
+```
 
-postal = results.first
-postal.code              # => "1540011"
-postal.formatted_code    # => "154-0011"
-postal.prefecture_code   # => 13
-postal.prefecture_name   # => "東京都"
-postal.city_name         # => "世田谷区"
-postal.town              # => "上馬"
-postal.prefecture        # => Prefecture
+```ruby
+# インスタンスメソッド / メンバー
+postal = Basho::PostalCode.find("154-0011")
+postal.code              # => "1540011"   (String, 7桁, ハイフンなし)
+postal.formatted_code    # => "154-0011"  (String, ハイフン付き)
+postal.prefecture_code   # => 13          (Integer)
+postal.city_name         # => "世田谷区"   (String)
+postal.town              # => "上馬"       (String)
+postal.prefecture_name   # => "東京都"     (String)
+postal.prefecture        # => Basho::Prefecture
 ```
 
 ### Region（地方区分）
 
+9地方: 北海道、東北、関東、中部、近畿、中国、四国、九州、沖縄。
+
 ```ruby
-Basho::Region.all                # 8地方
-Basho::Region.find("関東")       # 名前で検索
+# クラスメソッド
+Basho::Region.all                # => 9地方の配列
+Basho::Region.find("関東")       # 日本語名で検索
+Basho::Region.find("Kanto")     # 英語名で検索
+```
 
+```ruby
+# インスタンスメソッド / メンバー
 region = Basho::Region.find("関東")
-region.name             # => "関東"
-region.name_en          # => "Kanto"
-region.prefectures      # => Array<Prefecture>
-region.prefecture_codes # => [8, 9, 10, 11, 12, 13, 14]
+region.name             # => "関東"     (String)
+region.name_en          # => "Kanto"   (String)
+region.prefecture_codes # => [8, 9, 10, 11, 12, 13, 14]  (Array<Integer>)
+region.prefectures      # => Array<Basho::Prefecture>
 ```
 
 ## ActiveRecord統合
 
+モデルに`include Basho`を追加すると、`basho`と`basho_postal`マクロが使えるようになります。
+
 ### 自治体コードから都道府県・市区町村を引く
 
 ```ruby
@@ -149,11 +192,19 @@ class Shop < ApplicationRecord
   basho :local_gov_code
 end
 
-shop.prefecture   # => Prefecture
-shop.city         # => City
+shop.city         # => Basho::City
+shop.prefecture   # => Basho::Prefecture
 shop.full_address # => "東京都千代田区"
 ```
 
+`basho :column`は3つのインスタンスメソッドを定義します:
+
+| メソッド | 戻り値 |
+|---------|--------|
+| `city` | カラム値で検索した`Basho::City` |
+| `prefecture` | `city.prefecture`経由の`Basho::Prefecture` |
+| `full_address` | `"#{prefecture.name}#{city.name}"` または `nil` |
+
 ### 郵便番号から住所文字列を取得
 
 ```ruby
@@ -165,9 +216,11 @@ end
 shop.postal_address # => "東京都世田谷区上馬"
 ```
 
+`basho_postal :column`（マッピングオプションなし）は`postal_address`メソッドを定義します。戻り値は`"#{prefecture_name}#{city_name}#{town}"`または`nil`です。
+
 ### 郵便番号から住所カラムを自動保存
 
-`basho_postal`にマッピングオプションを渡すと、`before_save`で郵便番号から住所カラムを自動入力します。
+`basho_postal`にマッピングオプションを渡すと、`before_save`コールバックを登録し、郵便番号カラムの変更時に住所カラムを自動入力します。
 
 ```ruby
 class User < ApplicationRecord
@@ -179,29 +232,44 @@ class User < ApplicationRecord
 end
 ```
 
-- `postal_code`が変更された時だけ解決を実行
+利用可能なマッピングキー:
+
+| キー | 解決される値 |
+|------|-------------|
+| `prefecture:` | 都道府県名（例: "東京都"） |
+| `city:` | 市区町村名（例: "世田谷区"） |
+| `town:` | 町域名（例: "上馬"） |
+| `prefecture_code:` | 都道府県コード（例: 13） |
+| `city_code:` | 6桁自治体コード（例: "131130"） |
+
+- 解決は郵便番号カラムが保存時に変更される場合のみ実行
 - マッピングは部分指定可能（`prefecture:`だけでもOK）
-- オプションなしの場合は`postal_address`メソッドのみ定義（後方互換）
+- `postal_address`メソッドはマッピングオプションの有無に関わらず常に定義される
 
 ## Hotwire Engine
 
-Turbo Frame + Stimulusによる住所自動入力・カスケードセレクトをビルトインで提供するRails Engineです。自前でコントローラーを書かずに使えます。
+Turbo Frame + Stimulusによる郵便番号自動入力をビルトインで提供するRails Engineです。
 
 ### セットアップ
 
-```ruby
-# config/application.rb
-require "basho/engine"
-```
+Engineをルーティングにマウントします:
 
 ```ruby
 # config/routes.rb
 mount Basho::Engine, at: "/basho"
 ```
 
+Engineが提供するルート:
+
+| メソッド | パス | コントローラー#アクション |
+|---------|------|------------------------|
+| GET | `/basho/postal_codes/lookup?code=1540011` | `Basho::PostalCodesController#lookup` |
+
+Stimulusコントローラーとフォームヘルパーはimportmapと`ActionView`のinitializerにより自動登録されます。
+
 ### 郵便番号自動入力
 
-郵便番号を入力すると都道府県・市区町村・町域フィールドを自動入力します。
+7桁の郵便番号を入力すると、都道府県・市区町村・町域フィールドを自動入力します。
 
 ```erb
 <%= form_with(model: @shop) do |f| %>
@@ -213,83 +281,184 @@ mount Basho::Engine, at: "/basho"
                   "basho--auto-fill-target": "input" } %>
 
     <turbo-frame id="basho-result"
-                 data-basho--auto-fill-target="frame"></turbo-frame>
-
-    <%= f.text_field :prefecture,
-          data: { "basho--auto-fill-target": "prefecture" } %>
-    <%= f.text_field :city,
-          data: { "basho--auto-fill-target": "city" } %>
-    <%= f.text_field :town,
-          data: { "basho--auto-fill-target": "town" } %>
+                 data-basho--auto-fill-target="frame"
+                 data-action="turbo:frame-load->basho--auto-fill#fill"></turbo-frame>
+
+    <div data-basho--auto-fill-target="fields" hidden>
+      <%= f.text_field :prefecture, disabled: true,
+            data: { "basho--auto-fill-target": "prefecture" } %>
+      <%= f.text_field :city, disabled: true,
+            data: { "basho--auto-fill-target": "city" } %>
+      <%= f.text_field :town, disabled: true,
+            data: { "basho--auto-fill-target": "town" } %>
+    </div>
   </div>
 <% end %>
 ```
 
-1. ユーザーが郵便番号を入力（7桁）
-2. 300msデバウンス後、Turbo Frameでサーバーに問い合わせ
-3. Stimulusが都道府県・市区町村・町域フィールドを自動入力
+動作の流れ:
 
-### 都道府県・市区町村カスケードセレクト
+1. ユーザーが7桁の郵便番号を入力
+2. Turbo FrameでEngineのlookupエンドポイントに問い合わせ
+3. Stimulusが都道府県・市区町村・町域フィールドを自動入力し、`fields`コンテナを表示
+4. 郵便番号をクリア・変更するとフィールドは非表示に
 
-都道府県を選択すると、対応する市区町村がJSON APIで動的に読み込まれます。
+`fields`ターゲットはオプションです。なければフィールドは常に表示され、値のクリアのみ行います。
+
+`basho_autofill_frame_tag`ヘルパーで`<turbo-frame>`タグを簡潔に書けます:
 
 ```erb
-<%= form_with(model: @shop) do |f| %>
-  <div data-controller="basho--cascade-select"
-       data-basho--cascade-select-prefectures-url-value="<%= basho.prefectures_path %>"
-       data-basho--cascade-select-cities-url-template-value="<%= basho.cities_prefecture_path(':code') %>">
-
-    <select data-basho--cascade-select-target="prefecture"
-            data-action="change->basho--cascade-select#prefectureChanged">
-      <option value="">都道府県を選択</option>
-    </select>
-
-    <select data-basho--cascade-select-target="city">
-      <option value="">市区町村を選択</option>
-    </select>
-  </div>
-<% end %>
+<%= basho_autofill_frame_tag %>
 ```
 
-`basho_cascade_data`ヘルパーでdata属性を簡潔に書けます。
+これは以下をレンダリングします:
 
-```erb
-<div <%= tag.attributes(data: basho_cascade_data) %>>
-  ...
-</div>
+```html
+<turbo-frame id="basho-result"
+             data-basho--auto-fill-target="frame"
+             data-action="turbo:frame-load->basho--auto-fill#fill"></turbo-frame>
 ```
 
-1. ページ読み込み時、都道府県セレクトが空ならAPIから47件を取得
-2. 都道府県を選択すると、市区町村セレクトをAPIから再構築
-3. 都道府県を変更すると、市区町村セレクトがリセットされ再取得
+#### Stimulusコントローラーのターゲットとバリュー
 
-### JSON APIエンドポイント
+| 種類 | 名前 | 説明 |
+|------|------|------|
+| Value | `url` (String) | lookupエンドポイントのURL（必須） |
+| Target | `input` | 郵便番号入力フィールド |
+| Target | `frame` | サーバーレスポンス用Turbo Frame |
+| Target | `prefecture` | 都道府県出力フィールド |
+| Target | `city` | 市区町村出力フィールド |
+| Target | `town` | 町域出力フィールド |
+| Target | `fields` | 表示/非表示コンテナ（オプション） |
 
-Engineをマウントすると以下のエンドポイントが利用可能になります。
+### 都道府県・市区町村カスケードセレクト
+
+Bashoはデータを提供します。UIはアプリ側でTurbo Frameを使って実装してください。
+
+```ruby
+# app/controllers/cities_controller.rb
+class CitiesController < ApplicationController
+  def index
+    @cities = Basho::City.where(prefecture_code: params[:prefecture_code].to_i)
+  end
+end
+```
 
+```erb
+<%# app/views/cities/index.html.erb %>
+<turbo-frame id="city-select">
+  <%= f.select :city_code,
+        @cities.map { |c| [c.name, c.code] },
+        { include_blank: "市区町村を選択" } %>
+</turbo-frame>
 ```
-GET /basho/prefectures           # => [{"code":1,"name":"北海道"}, ...]
-GET /basho/prefectures/13/cities  # => [{"code":"131016","name":"千代田区"}, ...]
-GET /basho/postal_codes/lookup?code=1540011  # => Turbo Frame HTML
+
+```erb
+<%# フォーム内 %>
+<%= f.select :prefecture_code,
+      Basho::Prefecture.all.map { |p| [p.name, p.code] },
+      { include_blank: "都道府県を選択" },
+      data: { action: "change->auto-submit#submit",
+              turbo_frame: "city-select" } %>
+
+<turbo-frame id="city-select">
+  <%= f.select :city_code, [], include_blank: "市区町村を選択" %>
+</turbo-frame>
 ```
 
-## Engine不要の場合
+HTMLとスタイリングの自由度はアプリ側にあります。
 
-Engineを使わず、`PostalCode.find`で自由にエンドポイントを作ることもできます。
+## Hotwireなしでの利用
+
+データAPIとActiveRecord統合はHotwireなしで動きます。Engineをマウントしなければ、ルーティングもStimulus controllerも読み込まれません。
 
 ```ruby
-# JSON API
-class PostalCodesController < ApplicationController
-  def lookup
-    results = Basho::PostalCode.find(params[:code])
-
-    render json: results.map { |r|
-      { prefecture: r.prefecture_name, city: r.city_name, town: r.town }
-    }
-  end
+# データAPIだけ -- どのRubyアプリでも動く
+require "basho"
+
+Basho::PostalCode.find("154-0011").town         # => "上馬"
+Basho::Prefecture.find(13).name                 # => "東京都"
+Basho::City.where(prefecture_code: 13)          # => Array<City>
+```
+
+```ruby
+# ActiveRecord統合 -- Hotwireの有無に関係なく、どのRailsアプリでも動く
+class Shop < ApplicationRecord
+  include Basho
+  basho_postal :postal_code, city_code: :city_code, town: :town
 end
 ```
 
+## DBバックエンド（オプション）
+
+デフォルトではBashoは同梱のJSONファイルからデータを読み込みます。DB不要です。JOINや外部キー制約が必要な場合、または自前のテーブルから`basho_prefectures` / `basho_cities`を参照したい場合は、オプションでDBテーブルを生成できます。
+
+### セットアップ
+
+```bash
+rails generate basho:install_tables
+rails db:migrate
+rails basho:seed
+```
+
+2つのテーブルが作成されます:
+
+| テーブル | 主キー | 件数 |
+|---------|--------|------|
+| `basho_prefectures` | `code` (integer) | 47 |
+| `basho_cities` | `code` (string, 6桁) | 約1,900 |
+
+### 透過的な自動切り替え
+
+テーブルが存在すれば、公開API（`Basho::Prefecture.find`、`Basho::City.where`等）は自動的にDBバックエンドを使います。**コード変更は不要です。**
+
+```ruby
+# DBテーブルの有無に関わらず同じコードで動く
+Basho::Prefecture.find(13).name           # => "東京都"
+Basho::City.find("131016").full_name      # => "千代田区"
+Basho::City.where(prefecture_code: 13)    # => Array
+```
+
+検出は初回アクセス時に1度だけ行われ、プロセスの生存期間中キャッシュされます。
+
+### 自前テーブルからの外部キー
+
+```ruby
+# アプリ側のマイグレーション
+add_foreign_key :shops, :basho_cities, column: :city_code, primary_key: :code
+add_foreign_key :shops, :basho_prefectures, column: :prefecture_code, primary_key: :code
+```
+
+### DBモデルの直接利用
+
+ActiveRecordの機能（JOIN、スコープ、eager loading）が必要な場合は、DBモデルを直接使います:
+
+```ruby
+# JOIN
+Basho::DB::City.joins(:prefecture).where(basho_prefectures: { region_name: "関東" })
+
+# Eager loading
+Basho::DB::Prefecture.includes(:cities).find(13)
+
+# アソシエーション
+prefecture = Basho::DB::Prefecture.find(13)
+prefecture.cities    # => ActiveRecord::Relation
+prefecture.capital   # => Basho::DB::City
+```
+
+### 再シード
+
+`basho:seed`は冪等です。gem更新後に再実行すればデータが更新されます:
+
+```bash
+rails basho:seed
+```
+
+### 補足
+
+- 郵便番号はDBテーブルに**含まれません**（12万件以上、月次更新のため）。常にJSONファイルから提供されます。
+- `Basho.db?`はスレッドセーフでキャッシュされます。再検出が必要な場合（テスト中のマイグレーション後など）は`Basho.reset_db_cache!`を使ってください。
+
 ## データソース
 
 | データ | ソース | 更新頻度 |
@@ -297,7 +466,7 @@ end
 | 都道府県 | 総務省 JIS X 0401 | ほぼ変わらない |
 | 市区町村 | 総務省 全国地方公共団体コード | 年に数回 |
 | 郵便番号 | 日本郵便 KEN_ALL.csv | 月次（GitHub Actions自動更新） |
-| 地方区分 | 8地方（ハードコード） | 変わらない |
+| 地方区分 | 9地方（ハードコード） | 変わらない |
 
 ## 開発