jp_address_complement 0.1.0

data/specs/001-jp-address-complement-gem/quickstart.md

@@ -0,0 +1,151 @@
+# クイックスタート: jp_address_complement
+
+**バージョン**: 0.1.0 (予定)  
+**対応 Ruby**: 3.0 以上  
+**対応 Rails**: 7.0 以上
+
+---
+
+## インストール
+
+```ruby
+# Gemfile
+gem 'jp_address_complement'
+```
+
+```bash
+bundle install
+```
+
+---
+
+## セットアップ（Rails）
+
+### 1. マイグレーションを生成する
+
+```bash
+rails g jp_address_complement:install
+```
+
+`db/migrate/YYYYMMDDHHMMSS_create_jp_address_complement_postal_codes.rb` が生成されます。
+
+### 2. マイグレーションを実行する
+
+```bash
+rails db:migrate
+```
+
+### 3. 郵便番号データをインポートする
+
+日本郵便のサイトから KEN_ALL.CSV をダウンロードします。
+
+- URL: https://www.post.japanpost.jp/zipcode/dl/oogaki/zip/ken_all.zip
+
+```bash
+# ZIP を展開して CSV を取得後（例: ~/Downloads/KEN_ALL.CSV）
+bundle exec rake jp_address_complement:import CSV=/path/to/KEN_ALL.CSV
+```
+
+文字コード（Shift_JIS → UTF-8）変換は自動で行われます。
+ダウンロードしたそのままの CSV を指定してください。
+
+---
+
+## 基本的な使い方
+
+### 郵便番号から住所を取得する
+
+```ruby
+# 7桁（ハイフンなし）
+results = JpAddressComplement.search_by_postal_code("1000001")
+# => [#<data JpAddressComplement::AddressRecord postal_code="1000001", pref="東京都", city="千代田区", town="千代田", ...>]
+
+# ハイフンあり・〒記号あり も自動正規化
+results = JpAddressComplement.search_by_postal_code("100-0001")
+results = JpAddressComplement.search_by_postal_code("〒100-0001")
+
+# 存在しない場合は空配列
+results = JpAddressComplement.search_by_postal_code("0000000")
+# => []
+```
+
+### 先頭4桁以上で候補を取得する
+
+```ruby
+# 先頭4桁で絞り込み
+candidates = JpAddressComplement.search_by_postal_code_prefix("1000")
+# => [#<data ... postal_code="1000001">, #<data ... postal_code="1000002">, ...]
+
+# 先頭3桁以下は空返却（過大結果防止）
+candidates = JpAddressComplement.search_by_postal_code_prefix("100")
+# => []
+```
+
+### 郵便番号と住所の整合性を検証する
+
+```ruby
+# 都道府県名 + 市区町村名 + 町域名が入力住所に部分一致すれば true
+JpAddressComplement.valid_combination?("1000001", "東京都千代田区千代田1-1")
+# => true（番地が付加されていても true）
+
+JpAddressComplement.valid_combination?("1000001", "大阪府大阪市北区")
+# => false
+```
+
+---
+
+## Rails モデルでバリデーションを使う
+
+```ruby
+class Order < ApplicationRecord
+  validates :postal_code, presence: true
+  validates :postal_code, jp_address_complement: { address_field: :address }
+end
+```
+
+```ruby
+order = Order.new(postal_code: "1000001", address: "東京都千代田区千代田1-1 ○○ビル")
+order.valid?  # => true
+
+order2 = Order.new(postal_code: "1000001", address: "大阪府大阪市北区")
+order2.valid?  # => false
+order2.errors[:postal_code]  # => ["と住所が一致しません"]
+```
+
+---
+
+## Rails 以外の環境での使用（Rack / Sinatra）
+
+```ruby
+require 'jp_address_complement'
+require 'my_custom_repository'  # 利用者が用意するリポジトリ実装
+
+# カスタムリポジトリを注入
+JpAddressComplement.configure do |config|
+  config.repository = MyCustomPostalCodeRepository.new
+end
+
+# 以降は通常どおり使用可能
+results = JpAddressComplement.search_by_postal_code("1000001")
+```
+
+---
+
+## データ更新
+
+```bash
+# 最新の KEN_ALL.CSV をダウンロードして再インポート
+bundle exec rake jp_address_complement:import CSV=/path/to/new/KEN_ALL.CSV
+```
+
+既存データは upsert（追加・更新）されます。更新タイミングは利用者が任意に決定してください。
+
+---
+
+## トラブルシューティング
+
+| 問題 | 対処 |
+|------|------|
+| `jp_address_complement_postal_codes` テーブルが存在しない | `rails g jp_address_complement:install && rails db:migrate` を実行 |
+| 検索結果が空になる | `rake jp_address_complement:import` でデータをインポートしているか確認 |
+| 文字化けが起きる | KEN_ALL.CSV はそのまま渡してください（変換は自動） |

data/specs/001-jp-address-complement-gem/research.md

@@ -0,0 +1,139 @@
+# Research: 日本住所補完 Gem — Phase 0 調査結果
+
+**Branch**: `001-jp-address-complement-gem`  
+**Date**: 2026-02-22  
+**Status**: Complete
+
+---
+
+## 1. Repository パターン（Rails 非依存コア）
+
+### Decision
+コア検索ロジックは `PostalCodeRepository` インターフェースを介してデータアクセスする。
+Rails 環境向けに `ActiveRecordPostalCodeRepository` を同梱し、他環境では利用者がアダプターを注入できる設計とする。
+
+### Rationale
+- Repository が返す値は Plain Ruby の `AddressRecord` 構造体（Struct/Data）とする。ActiveRecord インスタンスを返さないことで、コアロジックへの AR 依存を完全に排除できる。
+- テスト時にはメモリ実装（`FakePostalCodeRepository`）を注入することで、DBへの依存なくコアロジックを単体テストできる（TDD 親和性 ◎）。
+
+### Alternatives Considered
+- **ActiveRecord 直接依存**: 最もシンプルだが Rails 以外での利用が不可能になり FR-015 に違反する。
+- **rom-rb (Ruby Object Mapper)**: データマッパーパターンで AR 依存を排除できるが、利用者側にも rom-rb の学習コストが生じ、シンプルさ原則（VI）に反する。
+- **dry-rb/dry-container でのDI**: 本格的な DI コンテナで柔軟性が高いが YAGNI 違反。シンプルなコンストラクタ注入で十分。
+
+### Interface Design
+```ruby
+module JpAddressComplement
+  module Repositories
+    # インターフェース（Duck typing、RBS で型定義も提供）
+    class PostalCodeRepository
+      # @param code [String] 7桁郵便番号
+      # @return [Array<AddressRecord>]
+      def find_by_code(code) = raise NotImplementedError
+
+      # @param prefix [String] 4桁以上の前方一致プレフィックス
+      # @return [Array<AddressRecord>]
+      def find_by_prefix(prefix) = raise NotImplementedError
+    end
+  end
+end
+```
+
+---
+
+## 2. Railtie / Generator 設計
+
+### Decision
+- `JpAddressComplement::Railtie` を通じて Rails に統合する。
+- `rails g jp_address_complement:install` でマイグレーションファイルを `db/migrate/` に生成する（Devise パターン）。
+- Railtie の initializer でデフォルトリポジトリ（`ActiveRecordPostalCodeRepository`）を DI コンテナへ登録する。
+
+### Rationale
+- Railtie は軽量で、モデル・ビューを持たない Gem では Engine より Railtie の方が適切（Constitution I 準拠）。
+- Generator によるマイグレーション生成は Rails コミュニティ標準のパターン（devise, kaminari 等と同様）。
+- Rails 以外の環境では Railtie がロードされないため、コア機能に影響しない。
+
+### Alternatives Considered
+- **Rails::Engine**: 不要なルーティング/ビュー機能が含まれ、オーバースペック。
+- **自動テーブル作成**: 利用者の制御が失われる。standard_procedures に反する。
+
+---
+
+## 3. CSV インポート — 文字コード変換
+
+### Decision
+`CSV.foreach(path, encoding: 'Shift_JIS:UTF-8', ...)` で Shift_JIS→UTF-8 変換をストリーミング処理する。Ruby 標準ライブラリのみで実現可能。
+
+### Rationale
+- Ruby の `CSV.foreach` は `encoding: 'src:dst'` 形式でトランスコードをストリーム処理できる。
+- メモリ効率が高く（全件をメモリに載せない）、12万件程度では問題なし。
+- 外部ライブラリ不要でシンプルさ原則（VI）に合致。
+
+---
+
+## 4. バッチ upsert — パフォーマンス設計
+
+### Decision
+`ActiveRecord::Base.connection.upsert_all`（Rails 6+ 標準）を 1,000 件/バッチで分割実行する。
+
+### Benchmark Evidence
+| 件数 | 手法 | 所要時間 |
+|------|------|---------|
+| 100,000 | `upsert_all` | 約 3〜4 秒 |
+| 100,000 | `activerecord-import` | 約 4.8 秒 |
+| 1,000,000 | `upsert_all` | 約 48.7 秒 |
+
+- 12万件 ✕ upsert_all（1,000件/バッチ）= 推定 **3〜5 秒**。SC-004（60秒以内）を十分に満足。
+- Rails 7 の `upsert_all` は `update_only` / `record_timestamps` オプションで制御が容易。
+
+### Alternatives Considered
+- **activerecord-import gem**: バリデーション付きインポートが必要な場合に検討。今回は Rake タスクが事前バリデーション済み CSV を前提とするため不要。
+- **PostgreSQL COPY コマンド**: 100万件超でメリットが出るが、DB 非依存が必要な本 Gem では採用しない。
+
+### Idempotency Strategy
+- `upsert_all` の unique key: `postal_code` カラム
+- 同一郵便番号が複数レコード（大口事業所等）存在するため、`(postal_code, city, town)` の複合キーを一意制約の対象とする。
+- 削除された郵便番号の検出は初期版では対応しない（Deferred）。
+
+---
+
+## 5. 文字列照合（`valid_combination?`）
+
+### Decision
+`String#include?` で部分一致検索する。照合対象は「都道府県名 + 市区町村名 + 町域名」の連結文字列。
+
+```ruby
+address_string.include?(record.pref + record.city + record.town)
+```
+
+### Rationale
+- DB クエリではなくアプリ層で判定するため、高速かつシンプル。
+- 同一郵便番号に複数レコードがある場合は `any?` で評価。
+- 全角・半角の正規化は照合前に実施（`Unicode::NFC` または `String#unicode_normalize`）。
+
+---
+
+## 6. DB スキーマ設計
+
+### インデックス戦略
+- `postal_codes` テーブル
+  - PK: `id`（`bigint`）
+  - `postal_code VARCHAR(7)`: インデックス（完全一致検索 O(log n)）
+  - `postal_code_prefix VARCHAR(3)`: 前方一致高速化のための派生カラム（先頭3桁）をインデックス化、またはプレフィックス LIKE インデックス
+  - `pref_code VARCHAR(2)`, `pref VARCHAR(10)`, `city VARCHAR(50)`, `town VARCHAR(100)`, `kana_pref`, `kana_city`, `kana_town`
+
+### LIKE インデックス vs. 派生カラム
+- PostgreSQL: `LIKE 'prefix%'` は B-tree インデックスで最適化可能（`text_pattern_ops`）
+- MySQL/MariaDB: `LIKE 'prefix%'` は先頭一致なら B-tree インデックスを使用
+- SQLite: 同様に先頭一致 LIKE は B-tree インデックスが有効
+- **結論**: 追加カラム不要。クエリを `WHERE postal_code LIKE ?` (`'1000%'`)で発行し、`postal_code` への B-tree インデックスで SC-003（50ms）を達成可能。
+
+---
+
+## 7. 未解決事項（Deferred）
+
+| 項目 | 理由 |
+|------|------|
+| 削除済み郵便番号の検出 | 初期版スコープ外。差分インポートの複雑化を避ける（YAGNI） |
+| RBS 型定義の提供 | 実装後に追加可能。初期版では不要 |
+| 差分専用インポート（差分 CSV 活用） | 日本郵便の差分 CSV 形式が変動するリスクがあるため延期 |

data/specs/001-jp-address-complement-gem/spec.md

@@ -0,0 +1,153 @@
+# Feature Specification: 日本住所補完 Gem
+
+**Feature Branch**: `001-jp-address-complement-gem`  
+**Created**: 2026-02-22  
+**Status**: Draft  
+**Input**: User description: "日本国内の住所を郵便番号や住所の一部から補完できるRails 7.x以上向けのgemを作ります"
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - 郵便番号から住所を取得する (Priority: P1)
+
+Rails アプリ開発者が郵便番号（7桁）を入力すると、対応する都道府県・市区町村・町域名を取得できる。
+フォームの住所欄を自動補完したり、入力済み郵便番号と住所の整合性を確認するために使用する。
+
+**Why this priority**: 住所補完の最も基本的な利用パターンであり、この機能だけで即時に利用価値がある。
+
+**Independent Test**: `JpAddressComplement.search_by_postal_code("1000001")` を呼び出し、千代田区千代田の住所データが返ることを確認することで独立してテスト可能。
+
+**Acceptance Scenarios**:
+
+1. **Given** 有効な7桁郵便番号（例: "1000001"）を与えた時、**When** 住所検索を実行すると、**Then** 都道府県・市区町村・町域名を含む住所オブジェクトが返る。
+2. **Given** ハイフンあり郵便番号（例: "100-0001"）を与えた時、**When** 住所検索を実行すると、**Then** ハイフンを除去して検索し、正しい住所が返る。
+3. **Given** 存在しない郵便番号を与えた時、**When** 住所検索を実行すると、**Then** `[]`（空配列）が返る。
+4. **Given** 郵便番号のフォーマットが不正（桁数不足・数字以外含む）の時、**When** 住所検索を実行すると、**Then** エラーを発生させずに空の結果が返る。
+
+---
+
+### User Story 2 - 郵便番号の先頭数字から候補住所を取得する (Priority: P2)
+
+Rails アプリ開発者が郵便番号の先頭4桁以上を入力すると、該当する住所候補の一覧を取得できる。
+ユーザーが郵便番号を入力中にリアルタイムでサジェストを表示するために使用する。
+
+**Why this priority**: インクリメンタルサーチによる補完UXを実現するために必要であり、P1の検索機能をベースに拡張できる。
+
+**Independent Test**: `JpAddressComplement.search_by_postal_code_prefix("1000")` を呼び出し、"1000" で始まる複数の住所候補が返ることを確認することで独立してテスト可能。
+
+**Acceptance Scenarios**:
+
+1. **Given** 先頭4桁以上の郵便番号（例: "1000"）を与えた時、**When** 候補検索を実行すると、**Then** その番号から始まる複数の住所候補リストが返る。
+2. **Given** 先頭4桁未満の文字列（例: "10"）を与えた時、**When** 候補検索を実行すると、**Then** 空の結果が返る（候補が多すぎるため最低桁数制限）。
+3. **Given** 7桁の完全な郵便番号を与えた時、**When** 候補検索を実行すると、**Then** 対応する住所のみ（1件または0件）が返る。
+
+---
+
+### User Story 3 - 郵便番号と住所の整合性を検証する (Priority: P3)
+
+Rails アプリ開発者が郵便番号と住所文字列のペアを渡すと、それらが整合しているかどうかを検証できる。
+入力フォームのバリデーションやデータクレンジングに使用する。
+
+**Why this priority**: 単体の住所補完よりも活用ケースは限定されるが、データ品質担保の観点で重要な機能。
+
+**Independent Test**: `JpAddressComplement.valid_combination?("1000001", "東京都千代田区千代田")` を呼び出し、`true` が返ることを確認することで独立してテスト可能。
+
+**Acceptance Scenarios**:
+
+1. **Given** 正しい郵便番号と、対応レコードの「都道府県名」「市区町村名」「町域名」を含む住所文字列を与えた時、**When** 整合性検証を実行すると、**Then** `true` が返る（番地・建物名等が付加されていても `true`）。
+2. **Given** 郵便番号に対応しない住所を与えた時、**When** 整合性検証を実行すると、**Then** `false` が返る。
+3. **Given** 存在しない郵便番号を与えた時、**When** 整合性検証を実行すると、**Then** `false` が返る。
+
+---
+
+### User Story 4 - Rails モデルでバリデーションを使用する (Priority: P4)
+
+Rails アプリ開発者が ActiveRecord モデルに1行のバリデーション宣言を追加するだけで、郵便番号と住所フィールドの整合性チェックを自動化できる。
+
+**Why this priority**: Rails エコシステムへの統合を提供し、日常的な開発ワークフローに組み込みやすくする。
+
+**Independent Test**: `validates :postal_code, jp_address_complement: { address_field: :address }` を記述したモデルをテストし、不整合データのバリデーション失敗を確認することで独立してテスト可能。
+
+**Acceptance Scenarios**:
+
+1. **Given** Rails モデルに住所バリデーターを設定し、整合する郵便番号と住所を持つレコードを与えた時、**When** バリデーションを実行すると、**Then** バリデーションが通過する。
+2. **Given** Rails モデルに住所バリデーターを設定し、不整合な郵便番号と住所を持つレコードを与えた時、**When** バリデーションを実行すると、**Then** バリデーションが失敗し、エラーメッセージが付与される。
+3. **Given** Rails モデルに住所バリデーターを設定し、郵便番号フィールドが空のレコードを与えた時、**When** バリデーションを実行すると、**Then** 住所補完バリデーターはスキップされる（他のバリデーターに委ねる）。
+
+---
+
+### Edge Cases
+
+- 郵便番号が全角数字で入力された場合はどうなるか？（半角変換して処理する）
+- 同一郵便番号に複数の町域が対応する場合（大口事業所専用番号など）は全件返す。
+- データが存在しない過去・廃止された郵便番号を与えた場合は空を返す。
+- 住所文字列に読みがなや英数字が混在する場合でも、漢字表記部分で照合する。
+- データファイルが破損・欠損している場合は明確なエラーを発生させる。
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: Gem は郵便番号（7桁、数字のみ）から都道府県・市区町村・町域名を含む住所データを返せなければならない。
+- **FR-002**: Gem はハイフン（"〒100-0001" 形式）を含む郵便番号を自動で正規化（除去）して処理しなければならない。
+- **FR-003**: Gem は郵便番号の先頭4桁以上を引数として受け取り、それに該当する住所候補の一覧を返せなければならない。
+- **FR-004**: 先頭4桁未満の入力に対する候補検索は、空の結果を返さなければならない（過大結果の防止）。
+- **FR-005**: Gem は郵便番号と住所文字列を受け取り、両者の整合性を boolean で返せなければならない。整合性の判定は、郵便番号に対応するレコードの「都道府県名」「市区町村名」「町域名」を連結した文字列が、入力住所文字列に『部分一致』するかどうかで行う。番地・建物名等が付加されていても一致とみなす。
+  - 同一郵便番号に複数レコードがある場合は、いずれか一件に一致すれば `true` を返す。
+- **FR-006**: Gem は Rails 7.x 以上で利用できる ActiveModel バリデーターを提供しなければならない。
+- **FR-007**: バリデーターは郵便番号フィールドと住所フィールドを関連付けて整合性を自動チェックしなければならない。
+- **FR-008**: 住所データは日本郵便が公開する郵便番号データ（KEN_ALL.CSV）を元に、利用アプリケーションのDBに保持しなければならない。Gem 自体はデータファイルをバンドルしない。
+- **FR-009**: 住所データの更新は、Gem が提供する Rake タスク（例: `jp_address_complement:import`）の実行により完結しなければならない。更新タイミングの判断と実行は利用者に委ねる。
+- **FR-013**: Rake タスクは KEN_ALL.CSV のパスを引数として受け取り、Shift_JIS から UTF-8 への文字コード変換を自動で行いながら DB に全件インポート（既存データは upsert）する機能を提供しなければならない。利用者は日本郵便からダウンロードした CSV をそのまま指定するだけでよい。
+- **FR-014**: Gem は Rails Generator（`rails g jp_address_complement:install`）を提供し、住所テーブル用マイグレーションファイルを利用者アプリの `db/migrate/` 配下に生成しなければならない。テーブルの適用は利用者が `rails db:migrate` を実行することで行う。
+- **FR-010**: Gem のコア検索ロジックは ActiveRecord に直接依存せず、Repository インターフェースを介してデータアクセスを行わなければならない。Rails 環境では ActiveRecord 実装のリポジトリを Gem が同梱し、Rack/Sinatra 等の環境では利用者が任意のアダプターを注入できる設計とする。
+- **FR-015**: Gem は Rails 以外の環境でも、Repository アダプターを注入することでコア検索機能（郵便番号検索・候補検索・整合性検証）を利用できなければならない。
+- **FR-011**: 検索結果の住所データは、少なくとも郵便番号・都道府県名・市区町村名・町域名の4フィールドを含まなければならない。
+- **FR-012**: 不正な入力（nil、空文字、数字以外）に対してはエラーを発生させず、空の結果を返さなければならない。
+
+### Key Entities
+
+- **住所レコード (AddressRecord)**: 郵便番号・都道府県コード・都道府県名・市区町村名・町域名・読みがなを保持するデータ単位。郵便番号をキーに一意または複数存在しうる。DBの1行に対応する。
+- **住所テーブル (`jp_address_complement_postal_codes`)**: 利用アプリケーションのDBに存在する住所レコードの永続化テーブル。KEN_ALL.CSV からインポートされた全レコードを格納し、検索クエリに使用される。`PostalCode` ActiveRecord モデルに対応する。起動時のメモリ読み込みは行わない。
+- **住所バリデーター (AddressValidator)**: ActiveModel::Validator を継承し、モデルの郵便番号フィールドと住所フィールドの整合性を検証する Rails コンポーネント。
+- **インストールジェネレーター (InstallGenerator)**: `rails g jp_address_complement:install` で呼び出される Rails Generator。住所テーブル用マイグレーションファイルを利用者アプリの `db/migrate/` に生成する。
+- **郵便番号リポジトリ (PostalCodeRepository)**: データアクセスを抽象化するインターフェース層。郵便番号完全一致検索・前方一致検索のメソッドを定義する。Gem は Rails 向け ActiveRecord 実装（`ActiveRecordPostalCodeRepository`）を同梱し、他環境では利用者が任意の実装を注入する。
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: 郵便番号による住所検索の応答が、DBインポート済みの状態で 10 ミリ秒以内に完了する（99パーセンタイル、適切なインデックスが設定されていること前提）。
+- **SC-002**: 日本郵便の公式データに収録されている全郵便番号（約12万件）について、正しい住所が返る。
+- **SC-003**: 先頭4桁による候補検索が 50 ミリ秒以内に完了する（候補件数に関わらず）。
+- **SC-004**: Gem はアプリケーション起動時にメモリへのデータ読み込みを行わないため、Rails アプリの起動時間に影響を与えない。Rake タスクによる全件インポート（約12万件）は完了まで最大 60 秒を許容する。
+- **SC-005**: コード品質として自動テストカバレッジ 90% 以上を達成する。
+- **SC-006**: 住所バリデーターを Rails モデルに組み込む手順が 3 行以内のコードで完結する。
+
+### Constitution Compliance Criteria
+
+> これらの基準は Constitution に基づく必須成功条件です。
+
+- **CC-001**: `bundle exec rspec` が全テスト PASS し、SimpleCov カバレッジが **90% 以上**である。
+- **CC-002**: `bundle exec rubocop` が PASS（警告・エラーゼロ、`rubocop:disable` コメントなし）。
+- **CC-003**: すべての実装コードは先にテストを書き、Red-Green-Refactor サイクルを経ている（TDD）。
+- **CC-004**: gem は `JpAddressComplement` 名前空間に閉じており、コア検索ロジックは Repository インターフェースを介してデータアクセスし、ActiveRecord への直接依存を持たない。Rails 環境向けに ActiveRecord 実装を同梱し、他環境ではアダプター注入で動作する。
+
+## Assumptions
+
+- 住所データのソースは日本郵便が無償で公開する KEN_ALL.CSV（全国版）とする。
+- 住所データは利用アプリケーションのDBに保持する。Gem はデータファイルをバンドルしない。データの投入・更新タイミングは利用者が任意に決定し、Gem が提供する Rake タスクを実行することで反映する。
+- 住所の文字コードは UTF-8 とする。Rake タスクが KEN_ALL.CSV（Shift_JIS）を読み込む際に自動で UTF-8 へ変換する。利用者は日本郵便から直接ダウンロードした CSV をそのまま Rake タスクへ渡すだけでよい。
+- 全角数字の郵便番号は自動で半角に正規化して処理する（追加コストが小さいため）。
+- 読みがなフィールドは返却データに含めるが、読みがなによる検索機能は本仕様のスコープ外とする。
+- 大口事業所・私書箱向けの専用郵便番号も同一データに含め、同様に検索可能とする。
+- Rails への依存は ActiveModel バリデーター提供部分のみに限定し、コア検索ロジックは Rack/Sinatra でも利用可能とする。
+
+## Clarifications
+
+### Session 2026-02-22
+
+- Q: データ保持のライフサイクル方針（起動時メモリロード / DB永続化 / 都度ファイル読み込み）はどれか？ → A: データはDBに保持し、更新はRakeタスクのみ提供、更新のトリガーは利用者に委ねる。起動時にメモリへの住所情報読み込みは行わない。
+- Q: DBテーブルのスキーマ管理方法（自動作成 / Generator＋db:migrate / 専用DB分離）はどれか？ → A: Generator（`rails g jp_address_complement:install`）でマイグレーションファイルを利用者アプリに生成し、`rails db:migrate` で適用するRails標準パターン。
+- Q: Rails非依存コアの実現方針（Repository抽象化 / ActiveRecord gem直接依存 / Rails尢用に割り切り）はどれか？ → A: Repository パターンで抽象化。Rails環境はActiveRecord実装を同梱し、Rack/Sinatra等では利用者がアダプターを注入する疎結合設計。
+- Q: 整合性検証（`valid_combination?`）の照合粒度はどれか？ → A: 郵便番号対応レコードの都道府県名＋市区町村名＋町域名の連結含文字列が入力住所に部分一致すれば `true`。番地・建物名を含む文字列でも `true` とみなす。
+- Q: Rakeタスクインポート時の文字コード変換責務はどこか？ → A: Rakeタスクが Shift_JIS→UTF-8 変換を自動実行。利用者はダウンロードしたままの CSV をそのまま指定するだけでよい。