jp_address_complement 0.1.0

data/README.md

@@ -0,0 +1,274 @@
+# JpAddressComplement
+
+日本郵便の郵便番号データ（KEN_ALL 形式、UTF-8 版 utf_ken_all.csv）を用いて、Rails アプリで住所の補完・検索・検証を行うための gem です。
+
+## 特徴
+
+- **自前の RDB に住所情報を登録し、それを利用する**  
+  外部 API や別サービスに問い合わせるのではなく、アプリのデータベース内に郵便番号・住所データを保持し、そのテーブルに対して検索・検証を行います。
+
+- **運用時に外部サービスに依存しない**  
+  住所補完や検証はすべて自前 DB に対して行うため、外部 API の障害・レート制限・仕様変更の影響を受けず、オフライン環境でも利用できます。
+
+- **RDB のリレーションを活用できる**  
+  郵便番号テーブルを自前で持つため、都道府県コードや市区町村名で他のテーブルと JOIN したり、アプリ固有のマスタと組み合わせたりしやすい設計です。
+
+- **CSV を直接利用する方式も選べる**  
+  データベースを使わず、ローカルに配置した KEN_ALL 形式の UTF-8 CSV（`utf_ken_all.csv`）をそのまま読み込んで検索する `CsvPostalCodeRepository` も利用できます。CSV のパスは設定で指定できます。
+
+### 主な機能
+
+- **郵便番号から住所を検索**（7桁完全一致・先頭4桁以上のプレフィックス検索）
+- **住所から郵便番号の逆引き**
+- **郵便番号と住所文字列の整合性検証**（フォーム用バリデーション）
+- **都道府県コード（JIS X 0401）と都道府県名の相互変換**
+
+## 必要環境
+
+- Ruby 3.2 以上
+- Rails 7.1 以上
+- ActiveRecord 利用を前提としています
+
+## インストール
+
+### 1. Gem の追加
+
+アプリの `Gemfile` に追加して `bundle install` します。
+
+```ruby
+gem 'jp_address_complement'
+```
+
+Bundler を使わない場合:
+
+```bash
+gem install jp_address_complement
+```
+
+### 2. テーブルの作成
+
+郵便番号データを格納するマイグレーションを生成し、マイグレートします。
+
+```bash
+rails g jp_address_complement:install
+rails db:migrate
+```
+
+### 3. 住所データのインポート
+
+日本郵便の KEN_ALL 形式 CSV（UTF-8 版 `utf_ken_all.csv`）をインポートする必要があります。
+
+**方法A: 公式サイトから UTF-8 版を自動ダウンロードしてインポート**
+
+```bash
+DOWNLOAD=1 rake jp_address_complement:import
+```
+
+**方法B: 手元の UTF-8 CSV ファイルを指定してインポート**
+
+[郵便番号データダウンロード](https://www.post.japanpost.jp/zipcode/dl/utf-zip.html) から UTF-8 版の `utf_ken_all.zip` を取得し、展開した `utf_ken_all.csv` のパスを指定します。
+
+```bash
+CSV=/path/to/utf_ken_all.csv rake jp_address_complement:import
+```
+
+インポートには数分かかる場合があります。完了後、`jp_address_complement_postal_codes` テーブルにデータが入っている状態になります。
+
+---
+
+## 利用方法
+
+### 郵便番号から住所を検索（7桁完全一致）
+
+```ruby
+# 郵便番号はハイフン・全角・〒記号があっても自動で正規化されます
+records = JpAddressComplement.search_by_postal_code('1000001')
+# => [#<Data AddressRecord ...>, ...]
+
+records.each do |r|
+  puts "#{r.pref} #{r.city} #{r.town}"  # 例: 東京都 千代田区 千代田
+  puts r.postal_code   # "1000001"
+  puts r.pref_code     # "13" (JIS都道府県コード)
+end
+```
+
+### 町域の表示用文字列（括弧等を除く）
+
+郵便番号データの町域（`town` / `kana_town`）には、「大通西（１〜１９丁目）」「常盤（その他）」「以下に掲載がない場合」のように、通常の住所表記には含まれない括弧付きの情報などが含まれる場合があります。フォームの候補表示やラベル用に「住所としてそのまま使える町域名」だけ欲しいときは、`normalized_town` と `normalized_kana_town` を使ってください。
+
+- **除去されるもの**: 全角括弧（）で囲まれた部分全体、「以下に掲載がない場合」およびそのカナ表記
+- 元の `town` / `kana_town` が `nil` のとき、または除去後に空になる場合は `nil` を返します。
+
+```ruby
+records = JpAddressComplement.search_by_postal_code('0600042')
+records.each do |r|
+  # 括弧付きの生データ
+  r.town         # => "大通西（１〜１９丁目）"
+  r.kana_town    # => "オオドオリニシ（１〜１９チョウメ）"
+
+  # 表示用（括弧・「以下に掲載がない場合」等を除いた町域名）
+  r.normalized_town      # => "大通西"
+  r.normalized_kana_town # => "オオドオリニシ"
+
+  puts "#{r.pref} #{r.city} #{r.normalized_town}"  # 例: 北海道 札幌市中央区 大通西
+end
+```
+
+### 郵便番号のプレフィックス検索（4桁以上）
+
+入力中の郵便番号の先頭から候補を絞り込むときに使えます。
+
+```ruby
+records = JpAddressComplement.search_by_postal_code_prefix('1000')
+# 先頭が "1000" で始まる郵便番号の住所レコードの配列
+```
+
+### 郵便番号と住所の整合性チェック
+
+「この郵便番号とこの住所の組み合わせは正しいか？」を判定します。フォームのバリデーションに利用できます。
+
+```ruby
+JpAddressComplement.valid_combination?('1000001', '東京都千代田区千代田')
+# => true
+
+JpAddressComplement.valid_combination?('1000001', '大阪府大阪市北区')
+# => false
+```
+
+**注意**: 複数の郵便番号で丁目や番地のみ違う町域が存在する場合や、記載以外のその他の町域となっている郵便番号は、異なる町域や丁目、番地の郵便番号でも正しいと判定される場合があります。
+
+### モデルでのバリデーション（AddressValidator）
+
+`ActiveModel::Validations` と組み合わせて、郵便番号と住所フィールドの組み合わせを検証できます。
+
+```ruby
+class Order
+  include ActiveModel::Model
+  include ActiveModel::Validations
+
+  attr_accessor :postal_code, :address
+
+  validates :postal_code, presence: true
+  validates :address, presence: true
+  validates_with JpAddressComplement::AddressValidator,
+                 postal_code_field: :postal_code,
+                 address_field: :address
+end
+```
+
+`postal_code_field` / `address_field` を省略すると、それぞれ `:postal_code` / `:address` が使われます。
+
+### 都道府県コードと都道府県名の変換
+
+JIS X 0401 の都道府県コード（01〜47）と都道府県名の相互変換ができます。
+
+```ruby
+JpAddressComplement.prefecture_name_from_code(13)
+# => "東京都"
+JpAddressComplement.prefecture_name_from_code('13')
+# => "東京都"
+
+JpAddressComplement.prefecture_code_from_name('東京都')
+# => "13"
+```
+
+### 住所から郵便番号を逆引き
+
+都道府県・市区町村・町域を指定して、対応する郵便番号の一覧を取得します。
+
+```ruby
+codes = JpAddressComplement.search_postal_codes_by_address(
+  pref: '東京都',
+  city: '千代田区',
+  town: '千代田'
+)
+# => ["1000001"] など、該当する郵便番号の配列
+```
+
+`town` は省略可能です。その場合は都道府県＋市区町村で検索されます。
+
+### 設定のカスタマイズ（任意）
+
+リポジトリ（データ取得の実装）を差し替えたい場合は、Rails の初期化処理などで設定できます。
+
+```ruby
+# config/initializers/jp_address_complement.rb
+JpAddressComplement.configure do |config|
+  config.repository = MyApp::CustomPostalCodeRepository.new
+  # PostalCode モデルの継承元（未設定時は ActiveRecord::Base）
+  config.postal_code_model_base = ApplicationRecord
+  # 郵便番号テーブル名（未設定時は 'jp_address_complement_postal_codes'）。マイグレーションで別名のテーブルを作った場合に指定
+  config.postal_code_table_name = 'my_postal_codes'
+end
+```
+
+### CSV をローカルに配置して利用する（DB を使わない場合）
+
+RDB やマイグレーションを使わず、KEN_ALL 形式（UTF-8 版 `utf_ken_all.csv`）の CSV をローカルに置いたまま検索だけ行いたい場合は、`CsvPostalCodeRepository` を使います。CSV のパスは任意に指定できます。
+
+```ruby
+require 'jp_address_complement'
+require 'jp_address_complement/repositories/csv_postal_code_repository'
+
+# CSV ファイルのパスを設定して Repository を差し替える
+JpAddressComplement.configure do |config|
+  config.repository = JpAddressComplement::Repositories::CsvPostalCodeRepository.new(
+    '/path/to/utf_ken_all.csv'   # 任意のパスを指定可能（UTF-8 版）
+  )
+end
+
+# 以降は search_by_postal_code など、既存の API をそのまま利用できる
+records = JpAddressComplement.search_by_postal_code('1000001')
+```
+
+- 初回の検索時に CSV を読み込み、メモリ上にインデックスを構築します（2回目以降はメモリ検索のみ）。
+- CSV は日本郵便の KEN_ALL 形式と同じ列構成を前提とし、UTF-8 版 `utf_ken_all.csv` を想定しています。
+
+---
+
+## Development
+
+リポジトリをクローンしたあと、`bin/setup` で依存関係を入れます。`bin/console` で対話的にコードを試せます。
+
+### 型チェック（RBS / Steep）
+
+本 gem は [RBS](https://github.com/ruby/rbs) と [Steep](https://github.com/soutaro/steep) で静的型チェックを行っています。
+
+```bash
+bundle install
+bundle exec rbs collection install   # 任意: サードパーティ RBS のインストール
+bundle exec rake rbs:generate        # sig/ を rbs-inline から生成
+bundle exec rake steep               # 型チェック（CI では exit 0 が必須）
+```
+
+### RuboCop / RSpec
+
+コードスタイルのチェックとテストの実行は次のとおりです。
+
+```bash
+bundle exec rubocop
+bundle exec rspec
+```
+
+詳細は [specs/002-rbs-type-annotations/quickstart.md](specs/002-rbs-type-annotations/quickstart.md) を参照してください。
+
+ローカルに gem をインストールするには `bundle exec rake install` を実行します。
+
+### リリース（RubyGems への公開）
+
+1. `lib/jp_address_complement/version.rb` のバージョン（例: `1.0.0`）を更新してコミット・push する。
+2. `v1.0.0` のように **v + バージョン** のタグを push する。
+
+```bash
+git tag v1.0.0
+git push origin v1.0.0
+```
+
+3. GitHub Actions の [Release to RubyGems](.github/workflows/release.yml) ワークフローが動き、[RubyGems.org](https://rubygems.org) に自動で公開される。
+
+**事前準備（リポジトリのオーナー／管理者向け）:**  
+[RubyGems.org の Trusted Publisher](https://guides.rubygems.org/trusted-publishing/adding-a-publisher/) を設定する。手順: [RubyGems.org のプロフィール](https://rubygems.org/profile/me) → 対象の gem → **Trusted publishers** → **Create** で、リポジトリオーナー・リポジトリ名・ワークフロー名（`release.yml`）を登録する。API キーや GitHub Secrets は不要。
+
+## Contributing
+
+バグ報告やプルリクエストは [GitHub のリポジトリ](https://github.com/naokirin/jp_address_complement) で歓迎しています。

data/Rakefile

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+load 'lib/tasks/jp_address_complement.rake'
+task default: %i[]
+
+# RBS 型定義の生成（research.md §5, FR-005）
+# steep/rbs:generate は Rails 不要のため :environment 依存にしない（Rails/RakeEnvironment 除外理由）
+namespace :rbs do
+  desc 'rbs-inline で sig/ を生成する'
+  task generate: [] do
+    sh 'bundle exec rbs-inline --output sig/ lib/'
+  end
+end
+
+# 型チェック（research.md §5, FR-006）
+task steep: [] do
+  sh 'bundle exec steep check'
+end

data/Steepfile

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# Steep configuration for jp_address_complement (research.md §2, plan.md)
+# signature "sig" includes sig/*.rbs, sig/jp_address_complement/**/*.rbs, sig/manual/*.rbs
+# Rails/ActiveRecord types from rbs-rails and gem_rbs_collection
+target :lib do
+  signature 'sig'
+  check 'lib'
+end

data/examples/rails/jp_address_complement_demo/.gitignore

@@ -0,0 +1,15 @@
+# Rails credentials (master key must not be committed)
+config/master.key
+
+# sqlite database
+storage/*.sqlite3*
+
+# log files
+log/
+!log/.keep
+
+# temporary backup (e.g. moved during git history rewrite)
+.backup/
+
+# temporary files
+tmp/*

data/examples/rails/jp_address_complement_demo/.ruby-version

@@ -0,0 +1 @@
+3.4.1

data/examples/rails/jp_address_complement_demo/Gemfile

@@ -0,0 +1,22 @@
+source "https://rubygems.org"
+
+# Bundle edge Rails instead: gem "rails", github: "rails/rails", branch: "main"
+gem "rails", "~> 8.1.2"
+# Use sqlite3 as the database for Active Record
+gem "sqlite3", ">= 2.1"
+# Use the Puma web server [https://github.com/puma/puma]
+gem "puma", ">= 5.0"
+
+# OpenSSL 3.6.0 での CRL チェックエラー回避（openssl gem 3.1.2+ で CRL がデフォルト無効に）
+gem "openssl", ">= 3.3.1"
+
+# 郵便番号→住所検索（親リポジトリの gem を参照）
+gem "jp_address_complement", path: "../../../"
+
+# Windows does not include zoneinfo files, so bundle the tzinfo-data gem
+gem "tzinfo-data", platforms: %i[ windows jruby ]
+
+group :development, :test do
+  # See https://guides.rubyonrails.org/debugging_rails_applications.html#debugging-with-the-debug-gem
+  gem "debug", platforms: %i[ mri windows ], require: "debug/prelude"
+end

data/examples/rails/jp_address_complement_demo/Gemfile.lock

@@ -0,0 +1,252 @@
+PATH
+  remote: ../../..
+  specs:
+    jp_address_complement (0.1.0)
+      activerecord (>= 7.0)
+      csv (>= 3.0)
+      railties (>= 7.0)
+      rubyzip (>= 2.3)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    action_text-trix (2.1.16)
+      railties
+    actioncable (8.1.2)
+      actionpack (= 8.1.2)
+      activesupport (= 8.1.2)
+      nio4r (~> 2.0)
+      websocket-driver (>= 0.6.1)
+      zeitwerk (~> 2.6)
+    actionmailbox (8.1.2)
+      actionpack (= 8.1.2)
+      activejob (= 8.1.2)
+      activerecord (= 8.1.2)
+      activestorage (= 8.1.2)
+      activesupport (= 8.1.2)
+      mail (>= 2.8.0)
+    actionmailer (8.1.2)
+      actionpack (= 8.1.2)
+      actionview (= 8.1.2)
+      activejob (= 8.1.2)
+      activesupport (= 8.1.2)
+      mail (>= 2.8.0)
+      rails-dom-testing (~> 2.2)
+    actionpack (8.1.2)
+      actionview (= 8.1.2)
+      activesupport (= 8.1.2)
+      nokogiri (>= 1.8.5)
+      rack (>= 2.2.4)
+      rack-session (>= 1.0.1)
+      rack-test (>= 0.6.3)
+      rails-dom-testing (~> 2.2)
+      rails-html-sanitizer (~> 1.6)
+      useragent (~> 0.16)
+    actiontext (8.1.2)
+      action_text-trix (~> 2.1.15)
+      actionpack (= 8.1.2)
+      activerecord (= 8.1.2)
+      activestorage (= 8.1.2)
+      activesupport (= 8.1.2)
+      globalid (>= 0.6.0)
+      nokogiri (>= 1.8.5)
+    actionview (8.1.2)
+      activesupport (= 8.1.2)
+      builder (~> 3.1)
+      erubi (~> 1.11)
+      rails-dom-testing (~> 2.2)
+      rails-html-sanitizer (~> 1.6)
+    activejob (8.1.2)
+      activesupport (= 8.1.2)
+      globalid (>= 0.3.6)
+    activemodel (8.1.2)
+      activesupport (= 8.1.2)
+    activerecord (8.1.2)
+      activemodel (= 8.1.2)
+      activesupport (= 8.1.2)
+      timeout (>= 0.4.0)
+    activestorage (8.1.2)
+      actionpack (= 8.1.2)
+      activejob (= 8.1.2)
+      activerecord (= 8.1.2)
+      activesupport (= 8.1.2)
+      marcel (~> 1.0)
+    activesupport (8.1.2)
+      base64
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.3.1)
+      connection_pool (>= 2.2.5)
+      drb
+      i18n (>= 1.6, < 2)
+      json
+      logger (>= 1.4.2)
+      minitest (>= 5.1)
+      securerandom (>= 0.3)
+      tzinfo (~> 2.0, >= 2.0.5)
+      uri (>= 0.13.1)
+    base64 (0.3.0)
+    bigdecimal (4.0.1)
+    builder (3.3.0)
+    concurrent-ruby (1.3.6)
+    connection_pool (3.0.2)
+    crass (1.0.6)
+    csv (3.3.5)
+    date (3.5.1)
+    debug (1.11.1)
+      irb (~> 1.10)
+      reline (>= 0.3.8)
+    drb (2.2.3)
+    erb (6.0.1)
+    erubi (1.13.1)
+    globalid (1.3.0)
+      activesupport (>= 6.1)
+    i18n (1.14.8)
+      concurrent-ruby (~> 1.0)
+    io-console (0.8.2)
+    irb (1.17.0)
+      pp (>= 0.6.0)
+      prism (>= 1.3.0)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
+    json (2.18.1)
+    logger (1.7.0)
+    loofah (2.25.0)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.12.0)
+    mail (2.9.0)
+      logger
+      mini_mime (>= 0.1.1)
+      net-imap
+      net-pop
+      net-smtp
+    marcel (1.1.0)
+    mini_mime (1.1.5)
+    minitest (6.0.1)
+      prism (~> 1.5)
+    net-imap (0.6.3)
+      date
+      net-protocol
+    net-pop (0.1.2)
+      net-protocol
+    net-protocol (0.2.2)
+      timeout
+    net-smtp (0.5.1)
+      net-protocol
+    nio4r (2.7.5)
+    nokogiri (1.19.1-aarch64-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.19.1-aarch64-linux-musl)
+      racc (~> 1.4)
+    nokogiri (1.19.1-arm-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.19.1-arm-linux-musl)
+      racc (~> 1.4)
+    nokogiri (1.19.1-arm64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.19.1-x86_64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.19.1-x86_64-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.19.1-x86_64-linux-musl)
+      racc (~> 1.4)
+    openssl (4.0.1)
+    pp (0.6.3)
+      prettyprint
+    prettyprint (0.2.0)
+    prism (1.9.0)
+    psych (5.3.1)
+      date
+      stringio
+    puma (7.2.0)
+      nio4r (~> 2.0)
+    racc (1.8.1)
+    rack (3.2.5)
+    rack-session (2.1.1)
+      base64 (>= 0.1.0)
+      rack (>= 3.0.0)
+    rack-test (2.2.0)
+      rack (>= 1.3)
+    rackup (2.3.1)
+      rack (>= 3)
+    rails (8.1.2)
+      actioncable (= 8.1.2)
+      actionmailbox (= 8.1.2)
+      actionmailer (= 8.1.2)
+      actionpack (= 8.1.2)
+      actiontext (= 8.1.2)
+      actionview (= 8.1.2)
+      activejob (= 8.1.2)
+      activemodel (= 8.1.2)
+      activerecord (= 8.1.2)
+      activestorage (= 8.1.2)
+      activesupport (= 8.1.2)
+      bundler (>= 1.15.0)
+      railties (= 8.1.2)
+    rails-dom-testing (2.3.0)
+      activesupport (>= 5.0.0)
+      minitest
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.6.2)
+      loofah (~> 2.21)
+      nokogiri (>= 1.15.7, != 1.16.7, != 1.16.6, != 1.16.5, != 1.16.4, != 1.16.3, != 1.16.2, != 1.16.1, != 1.16.0.rc1, != 1.16.0)
+    railties (8.1.2)
+      actionpack (= 8.1.2)
+      activesupport (= 8.1.2)
+      irb (~> 1.13)
+      rackup (>= 1.0.0)
+      rake (>= 12.2)
+      thor (~> 1.0, >= 1.2.2)
+      tsort (>= 0.2)
+      zeitwerk (~> 2.6)
+    rake (13.3.1)
+    rdoc (7.2.0)
+      erb
+      psych (>= 4.0.0)
+      tsort
+    reline (0.6.3)
+      io-console (~> 0.5)
+    rubyzip (3.2.2)
+    securerandom (0.4.1)
+    sqlite3 (2.9.0-aarch64-linux-gnu)
+    sqlite3 (2.9.0-aarch64-linux-musl)
+    sqlite3 (2.9.0-arm-linux-gnu)
+    sqlite3 (2.9.0-arm-linux-musl)
+    sqlite3 (2.9.0-arm64-darwin)
+    sqlite3 (2.9.0-x86_64-darwin)
+    sqlite3 (2.9.0-x86_64-linux-gnu)
+    sqlite3 (2.9.0-x86_64-linux-musl)
+    stringio (3.2.0)
+    thor (1.5.0)
+    timeout (0.6.0)
+    tsort (0.2.0)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
+    uri (1.1.1)
+    useragent (0.16.11)
+    websocket-driver (0.8.0)
+      base64
+      websocket-extensions (>= 0.1.0)
+    websocket-extensions (0.1.5)
+    zeitwerk (2.7.5)
+
+PLATFORMS
+  aarch64-linux-gnu
+  aarch64-linux-musl
+  arm-linux-gnu
+  arm-linux-musl
+  arm64-darwin
+  x86_64-darwin
+  x86_64-linux-gnu
+  x86_64-linux-musl
+
+DEPENDENCIES
+  debug
+  jp_address_complement!
+  openssl (>= 3.3.1)
+  puma (>= 5.0)
+  rails (~> 8.1.2)
+  sqlite3 (>= 2.1)
+  tzinfo-data
+
+BUNDLED WITH
+   2.6.2

data/examples/rails/jp_address_complement_demo/README.md

@@ -0,0 +1,57 @@
+# jp_address_complement デモ（Rails）
+
+[jp_address_complement](https://github.com/naokirin/jp_address_complement) の公開インターフェースを試せるサンプル Rails アプリです。
+
+## 前提
+
+- Ruby 3.2+
+- 親リポジトリ（`jp_address_complement_rb`）のルートで `bundle install` 済みであること
+
+## セットアップ
+
+```bash
+cd examples/rails/jp_address_complement_demo
+bundle install
+bin/rails db:create db:migrate db:seed
+```
+
+## 起動
+
+```bash
+bin/rails server
+```
+
+ブラウザで http://localhost:3000 を開くと、画面上部のナビから次の5つのデモを試せます。
+
+| デモ | 対応 API | 説明 |
+|------|----------|------|
+| 郵便番号→住所（7桁） | `search_by_postal_code` | 7桁完全一致で住所を検索 |
+| プレフィックス検索 | `search_by_postal_code_prefix` | 先頭4桁以上で候補を絞り込み |
+| 整合性チェック | `valid_combination?` | 郵便番号と住所の組み合わせが正しいか判定 |
+| 都道府県コード⇔名 | `prefecture_name_from_code` / `prefecture_code_from_name` | JIS都道府県コードと都道府県名の相互変換 |
+| 住所→郵便番号の逆引き | `search_postal_codes_by_address` | 都道府県・市区町村・町域から郵便番号一覧を取得 |
+
+## サンプルデータ
+
+`db:seed` で次の郵便番号が登録されます。
+
+| 郵便番号   | 住所例                 |
+|-----------|------------------------|
+| 1000001   | 東京都千代田区千代田 等 |
+| 0600000   | 北海道札幌市中央区      |
+| 1500002   | 東京都渋谷区渋谷        |
+
+## 本番用データの投入（任意）
+
+[日本郵便の郵便番号データ](https://www.post.japanpost.jp/zipcode/download.html) から **KEN_ALL.CSV** をダウンロードし、次で一括投入できます。
+
+```bash
+CSV=/path/to/KEN_ALL.CSV bin/rails jp_address_complement:import
+```
+
+## 構成
+
+- **ルート** `/` … 各デモへのナビと郵便番号→住所（7桁）のフォーム
+- **コントローラ** `AddressesController` … 各アクションで `JpAddressComplement` の API を呼び出し
+- **DB** SQLite（`storage/development.sqlite3`）
+- **gem** `jp_address_complement` を Gemfile の `path: "../../../"` で参照

data/examples/rails/jp_address_complement_demo/Rakefile

@@ -0,0 +1,6 @@
+# Add your own tasks in files placed in lib/tasks ending in .rake,
+# for example lib/tasks/capistrano.rake, and they will automatically be available to Rake.
+
+require_relative "config/application"
+
+Rails.application.load_tasks

data/examples/rails/jp_address_complement_demo/app/assets/stylesheets/application.css

@@ -0,0 +1 @@
+/* Application styles */