jp_address_complement 0.1.0

data/sig/manual/stdlib_net_http.rbs

@@ -0,0 +1,33 @@
+# net/http の Steep 用スタブ（KenAllDownloader で使用）
+module Net
+  class HTTPError < StandardError
+  end
+
+  class OpenTimeout < Timeout::Error
+  end
+
+  class ReadTimeout < Timeout::Error
+  end
+
+  class HTTP
+    def self.start: (String host, Integer port, ?use_ssl: bool, ?read_timeout: Integer, ?open_timeout: Integer) { (Net::HTTP) -> untyped } -> untyped
+
+    def request: (Net::HTTPRequest request) { (Net::HTTPResponse) -> void } -> Net::HTTPResponse
+  end
+
+  class HTTP::Get < Net::HTTPRequest
+    def initialize: (URI::Generic uri) -> void
+  end
+
+  class HTTPSuccess < Net::HTTPResponse
+  end
+
+  class HTTPResponse
+    attr_reader code: String
+    attr_reader message: String
+    attr_reader body_io: IO
+  end
+
+  class HTTPRequest
+  end
+end

data/sig/manual/stdlib_openuri.rbs

@@ -0,0 +1,9 @@
+# open-uri が URI に追加するメソッド（Steep 用スタブ）
+module URI
+  def self.open: (String uri, ?read_timeout: Integer, ?open_timeout: Integer) { (untyped) -> untyped } -> untyped
+end
+
+module OpenURI
+  class HTTPError < StandardError
+  end
+end

data/sig/manual/stdlib_tmpdir.rbs

@@ -0,0 +1,4 @@
+# tmpdir が Dir に追加するメソッド（Steep 用スタブ）
+class Dir
+  def self.mktmpdir: (?String prefix_suffix, ?String tmpdir) -> String
+end

data/specs/001-jp-address-complement-gem/checklists/requirements.md

@@ -0,0 +1,36 @@
+# Specification Quality Checklist: 日本住所補完 Gem
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning  
+**Created**: 2026-02-22  
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- Constitution Compliance Criteria（CC-001〜CC-004）は、プロジェクト憲章に基づく必須成功条件として意図的に技術用語（RSpec, RuboCop）を含んでいるため、技術非依存の通常成功基準とは区別して評価している。
+- 全チェック項目が1回目のバリデーションで通過した（2026-02-22 実施）。
+- `/speckit.plan` または `/speckit.clarify` への移行の準備が整っている。

data/specs/001-jp-address-complement-gem/contracts/public-api.md

@@ -0,0 +1,209 @@
+# Public API Contract: JpAddressComplement
+
+**Gem**: `jp_address_complement`  
+**Namespace**: `JpAddressComplement`  
+**Contract Type**: Ruby Public API（ライブラリの公開インターフェース定義）
+
+---
+
+## モジュールメソッド（`JpAddressComplement.*`）
+
+### `search_by_postal_code(code) → Array<AddressRecord>`
+
+郵便番号（7桁）に対応する住所レコードを返す。
+
+**引数**
+
+| 名前 | 型 | 説明 |
+|-----|----|------|
+| `code` | `String` | 郵便番号。ハイフンあり（`"100-0001"`）・全角数字・`〒` 記号はすべて自動正規化する |
+
+**戻り値**: `Array<AddressRecord>`
+
+- 一致するレコードが存在しない場合は `[]`（空配列）
+- 同一郵便番号に複数レコードが存在する場合（大口事業所等）は全件返す
+
+**エラー**: 不正入力（`nil`・空文字・数字以外を含む文字列）に対しては例外を発生させず `[]` を返す。
+
+```ruby
+# 成功例
+JpAddressComplement.search_by_postal_code("1000001")
+# => [#<data JpAddressComplement::AddressRecord
+#           postal_code="1000001",
+#           pref_code="13",
+#           pref="東京都",
+#           city="千代田区",
+#           town="千代田",
+#           kana_pref="トウキョウト",
+#           kana_city="チヨダク",
+#           kana_town="チヨダ",
+#           has_alias=false,
+#           is_partial=false,
+#           is_large_office=false>]
+
+# 正規化される入力例
+JpAddressComplement.search_by_postal_code("100-0001")  # ハイフンあり
+JpAddressComplement.search_by_postal_code("〒100-0001") # 〒付き
+JpAddressComplement.search_by_postal_code("１０００００１")  # 全角数字
+
+# 存在しない場合
+JpAddressComplement.search_by_postal_code("0000000")  # => []
+
+# 不正入力（エラーなし）
+JpAddressComplement.search_by_postal_code(nil)        # => []
+JpAddressComplement.search_by_postal_code("")         # => []
+JpAddressComplement.search_by_postal_code("abc")      # => []
+```
+
+---
+
+### `search_by_postal_code_prefix(prefix) → Array<AddressRecord>`
+
+郵便番号の先頭4桁以上に一致する住所候補一覧を返す。
+
+**引数**
+
+| 名前 | 型 | 説明 |
+|-----|----|------|
+| `prefix` | `String` | 郵便番号の先頭部分（4桁以上）。全角数字は自動正規化 |
+
+**戻り値**: `Array<AddressRecord>`
+
+- 先頭4桁未満の場合は `[]`（過大結果防止のガード）
+- 7桁完全一致の場合は `search_by_postal_code` と同等の結果
+
+```ruby
+# 先頭4桁
+JpAddressComplement.search_by_postal_code_prefix("1000")
+# => [#<data ... postal_code="1000001">, #<data ... postal_code="1000002">, ...]
+
+# 先頭6桁
+JpAddressComplement.search_by_postal_code_prefix("100000")
+# => [#<data ... postal_code="1000001">]
+
+# 先頭3桁以下 → 空返却
+JpAddressComplement.search_by_postal_code_prefix("100")   # => []
+JpAddressComplement.search_by_postal_code_prefix("10")    # => []
+```
+
+---
+
+### `valid_combination?(postal_code, address) → Boolean`
+
+郵便番号と住所文字列が整合しているかを検証する。
+
+**引数**
+
+| 名前 | 型 | 説明 |
+|-----|----|------|
+| `postal_code` | `String` | 郵便番号（自動正規化） |
+| `address` | `String` | 住所文字列（番地・建物名が含まれていても可） |
+
+**戻り値**: `Boolean`
+
+- 郵便番号に対応するレコードの「都道府県名 + 市区町村名 + 町域名」が `address` に**部分一致**する場合は `true`
+- 同一郵便番号に複数レコードがある場合はいずれか1件が一致すれば `true`
+- 郵便番号が不正・存在しない場合は `false`
+
+```ruby
+JpAddressComplement.valid_combination?("1000001", "東京都千代田区千代田1-1 ○○ビル")  # => true
+JpAddressComplement.valid_combination?("1000001", "東京都千代田区千代田")             # => true
+JpAddressComplement.valid_combination?("1000001", "大阪府大阪市北区梅田")            # => false
+JpAddressComplement.valid_combination?("0000000", "東京都千代田区千代田")            # => false（存在しない）
+JpAddressComplement.valid_combination?(nil, "東京都...")                             # => false
+```
+
+---
+
+### `configure { |config| ... }` — 設定ブロック
+
+```ruby
+JpAddressComplement.configure do |config|
+  # カスタムリポジトリを注入（Rails 以外の環境向け）
+  config.repository = MyCustomPostalCodeRepository.new
+end
+```
+
+**設定オプション**
+
+| オプション | 型 | デフォルト | 説明 |
+|-----------|-----|-----------|------|
+| `repository` | `PostalCodeRepository` 準拠オブジェクト | `ActiveRecordPostalCodeRepository.new` | データアクセス実装 |
+
+---
+
+## 値オブジェクト: `AddressRecord`
+
+`search_by_postal_code` および `search_by_postal_code_prefix` が返す値オブジェクト。
+
+```ruby
+record = JpAddressComplement.search_by_postal_code("1000001").first
+
+record.postal_code      # => "1000001"  (String)
+record.pref_code        # => "13"       (String)
+record.pref             # => "東京都"   (String)
+record.city             # => "千代田区" (String)
+record.town             # => "千代田"   (String or nil)
+record.kana_pref        # => "トウキョウト" (String or nil)
+record.kana_city        # => "チヨダク"    (String or nil)
+record.kana_town        # => "チヨダ"      (String or nil)
+record.has_alias        # => false      (Boolean) 通称あり
+record.is_partial       # => false      (Boolean) 丁目区分あり
+record.is_large_office  # => false      (Boolean) 大口事業所専用
+```
+
+---
+
+## ActiveModel バリデーター
+
+```ruby
+validates :postal_code_field, jp_address_complement: { address_field: :address_field_name }
+```
+
+**オプション**
+
+| キー | 型 | 必須 | 説明 |
+|-----|----|------|------|
+| `address_field` | `Symbol` | ✅ | 住所文字列が格納されているモデルの属性名 |
+
+**バリデーションの動作**
+
+| 条件 | 結果 |
+|------|------|
+| `postal_code` フィールドが空 | バリデーターをスキップ（他バリデーターに委ねる） |
+| 整合している | 通過 |
+| 整合しない | `errors.add(:postal_code_field, "と住所が一致しません")` |
+
+---
+
+## Rake タスク
+
+```bash
+# インポート（Shift_JIS → UTF-8 変換を自動実行）
+bundle exec rake jp_address_complement:import CSV=/path/to/KEN_ALL.CSV
+
+# インポート進捗ログ付き
+bundle exec rake jp_address_complement:import CSV=/path/to/KEN_ALL.CSV VERBOSE=true
+```
+
+**環境変数**
+
+| 変数 | 必須 | 説明 |
+|------|------|------|
+| `CSV` | ✅ | KEN_ALL.CSV へのパス |
+| `VERBOSE` | ❌ | `true` で進捗ログを出力（デフォルト: `false`） |
+| `BATCH_SIZE` | ❌ | バッチ件数（デフォルト: `1000`） |
+
+---
+
+## Rails Generator
+
+```bash
+rails g jp_address_complement:install
+```
+
+**生成ファイル**
+
+| ファイル | 説明 |
+|---------|------|
+| `db/migrate/YYYYMMDDHHMMSS_create_jp_address_complement_postal_codes.rb` | 住所テーブルマイグレーション |

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

@@ -0,0 +1,207 @@
+# Data Model: 日本住所補完 Gem
+
+**Branch**: `001-jp-address-complement-gem`  
+**Date**: 2026-02-22
+
+---
+
+## エンティティ一覧
+
+### 1. `postal_codes` テーブル（DB永続化）
+
+利用アプリケーションの DB に作成される住所データテーブル。Gem からマイグレーションを提供する。
+
+#### スキーマ定義
+
+```ruby
+# db/migrate/YYYYMMDDHHMMSS_create_jp_address_complement_postal_codes.rb
+create_table :jp_address_complement_postal_codes do |t|
+  t.string :postal_code,  limit: 7,   null: false  # 郵便番号（7桁、数字のみ）
+  t.string :pref_code,    limit: 2,   null: false  # 都道府県コード（JIS X 0401）
+  t.string :pref,         limit: 10,  null: false  # 都道府県名（漢字）
+  t.string :city,         limit: 50,  null: false  # 市区町村名（漢字）
+  t.string :town,         limit: 100, null: true   # 町域名（漢字）- nil 可（大口事業所等）
+  t.string :kana_pref,    limit: 20,  null: true   # 都道府県名（カナ）
+  t.string :kana_city,    limit: 100, null: true   # 市区町村名（カナ）
+  t.string :kana_town,    limit: 200, null: true   # 町域名（カナ）
+  t.boolean :has_alias,   default: false            # 通称あり（KEN_ALL フラグ）
+  t.boolean :is_partial,  default: false            # 丁目区分あり
+  t.boolean :is_large_office, default: false        # 大口事業所専用フラグ
+  t.timestamps
+end
+
+# インデックス
+add_index :jp_address_complement_postal_codes, :postal_code          # 完全一致
+add_index :jp_address_complement_postal_codes, [:postal_code, :pref_code, :city, :town],
+          unique: true, name: 'idx_jp_address_complement_unique'     # 冪等性保証
+```
+
+#### フィールド定義
+
+| カラム名 | 型 | NOT NULL | 説明 |
+|---------|-----|----------|------|
+| `id` | bigint | ✅ | PK（自動採番） |
+| `postal_code` | varchar(7) | ✅ | ハイフンなし7桁郵便番号 |
+| `pref_code` | varchar(2) | ✅ | 都道府県コード（01〜47） |
+| `pref` | varchar(10) | ✅ | 都道府県名（漢字） |
+| `city` | varchar(50) | ✅ | 市区町村名（漢字） |
+| `town` | varchar(100) | ❌ | 町域名（漢字）、以下一律で適用 |
+| `kana_pref` | varchar(20) | ❌ | 都道府県カナ |
+| `kana_city` | varchar(100) | ❌ | 市区町村カナ |
+| `kana_town` | varchar(200) | ❌ | 町域カナ |
+| `has_alias` | boolean | ✅ | 通称フラグ |
+| `is_partial` | boolean | ✅ | 丁目区分フラグ |
+| `is_large_office` | boolean | ✅ | 大口事業所フラグ |
+| `created_at` | datetime | ✅ | 作成日時 |
+| `updated_at` | datetime | ✅ | 更新日時 |
+
+#### インデックス戦略
+
+| インデックス名 | カラム | 用途 |
+|--------------|--------|------|
+| `idx_postal_code` | `(postal_code)` | US-1: 完全一致検索 O(log n) |
+| `idx_jp_address_complement_unique` | `(postal_code, pref_code, city, town)` | 冪等 upsert の一意性制約 |
+
+**先頭4桁前方一致**: `postal_code` への B-tree インデックスは `LIKE '1000%'` の先頭一致クエリに対して有効（PostgreSQL/MySQL/SQLite 共通）。追加インデックス不要。
+
+---
+
+### 2. `AddressRecord` — Plain Ruby 値オブジェクト
+
+DB から取得したデータを Repository が返す際の値オブジェクト。ActiveRecord インスタンスを返さないことでコアロジックの AR 依存を排除する。
+
+```ruby
+module JpAddressComplement
+  # Ruby 3.2+ Data クラス（immutable struct）
+  AddressRecord = Data.define(
+    :postal_code,     # String  — 7桁、ハイフンなし
+    :pref_code,       # String  — 都道府県コード
+    :pref,            # String  — 都道府県名
+    :city,            # String  — 市区町村名
+    :town,            # String? — 町域名（nilable）
+    :kana_pref,       # String? — 都道府県カナ
+    :kana_city,       # String? — 市区町村カナ
+    :kana_town,       # String? — 町域カナ
+    :has_alias,       # Boolean
+    :is_partial,      # Boolean
+    :is_large_office  # Boolean
+  )
+end
+```
+
+- **不変（Immutable）**: `Data.define` により凍結された値オブジェクト。
+- **Ruby 3.0 互換**: `Data` クラスは Ruby 3.2 以降。3.0/3.1 では `Struct.new(..., keyword_init: true)` にフォールバック。
+
+---
+
+### 3. `PostalCodeRepository` — データアクセス抽象化インターフェース
+
+```ruby
+module JpAddressComplement
+  module Repositories
+    class PostalCodeRepository
+      # @param code [String] 正規化済み7桁郵便番号
+      # @return [Array<AddressRecord>]
+      def find_by_code(code)
+        raise NotImplementedError, "#{self.class}#find_by_code is not implemented"
+      end
+
+      # @param prefix [String] 4桁以上の郵便番号プレフィックス
+      # @return [Array<AddressRecord>]
+      def find_by_prefix(prefix)
+        raise NotImplementedError, "#{self.class}#find_by_prefix is not implemented"
+      end
+    end
+  end
+end
+```
+
+---
+
+### 4. `ActiveRecordPostalCodeRepository` — Rails 向け実装
+
+```ruby
+module JpAddressComplement
+  module Repositories
+    class ActiveRecordPostalCodeRepository < PostalCodeRepository
+      MODEL_CLASS = "JpAddressComplement::PostalCode"  # AR モデル（遅延定数参照）
+
+      def find_by_code(code)
+        model.where(postal_code: code).map { to_record(_1) }
+      end
+
+      def find_by_prefix(prefix)
+        model.where("postal_code LIKE ?", "#{prefix}%").map { to_record(_1) }
+      end
+
+      private
+
+      def model = Object.const_get(MODEL_CLASS)
+
+      def to_record(ar)
+        AddressRecord.new(
+          postal_code: ar.postal_code,
+          pref_code:   ar.pref_code,
+          pref:        ar.pref,
+          city:        ar.city,
+          town:        ar.town,
+          kana_pref:   ar.kana_pref,
+          kana_city:   ar.kana_city,
+          kana_town:   ar.kana_town,
+          has_alias:   ar.has_alias,
+          is_partial:  ar.is_partial,
+          is_large_office: ar.is_large_office
+        )
+      end
+    end
+  end
+end
+```
+
+---
+
+### 5. `PostalCode` — ActiveRecord モデル（Rails 環境のみ）
+
+```ruby
+module JpAddressComplement
+  class PostalCode < ActiveRecord::Base
+    self.table_name = "jp_address_complement_postal_codes"
+
+    validates :postal_code, presence: true, format: { with: /\A\d{7}\z/ }
+    validates :pref, :city, presence: true
+  end
+end
+```
+
+---
+
+## エンティティ関係図
+
+```
+KEN_ALL.CSV (Shift_JIS, 外部ファイル)
+    │
+    │ Rake Task (Shift_JIS→UTF-8 変換 + upsert_all, 1,000件/バッチ)
+    ▼
+jp_address_complement_postal_codes (利用アプリの DB テーブル)
+    │
+    │ ActiveRecordPostalCodeRepository#find_by_code / find_by_prefix
+    ▼
+AddressRecord（Plain Ruby 値オブジェクト）
+    │
+    │ JpAddressComplement::Searcher (コアロジック)
+    ▼
+呼び出し元（Rails アプリ / Rack アプリ / RSpec テスト）
+```
+
+---
+
+## データ検証ルール
+
+| ルール | 適用箇所 |
+|--------|---------|
+| 郵便番号は7桁数字のみ（正規化後） | `Normalizer` クラス、`PostalCode` モデル |
+| 全角数字→半角正規化 | `Normalizer` クラス（入力受付時） |
+| ハイフン除去（〒100-0001 → 1000001） | `Normalizer` クラス（入力受付時） |
+| 4桁未満プレフィックスは空返却 | `Searcher#search_by_prefix` のガード節 |
+| nil/空文字/数字以外はエラーなしで空返却 | `Normalizer` では nil 返却、`Searcher` でガード |
+| 不正 CSV 行は警告ログ出力してスキップ | `Importer` クラス |

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

@@ -0,0 +1,124 @@
+# Implementation Plan: 日本住所補完 Gem
+
+**Branch**: `001-jp-address-complement-gem` | **Date**: 2026-02-22 | **Spec**: [spec.md](./spec.md)  
+**Input**: Feature specification from `/specs/001-jp-address-complement-gem/spec.md`
+
+---
+
+## Summary
+
+日本国内の住所を郵便番号から補完・検証できる Rails 7.x 以上向け Ruby gem を実装する。  
+**技術方針**: 住所データは利用アプリケーションの DB に永続化し（メモリロードなし）、インポートは Rake タスク経由とする。コア検索ロジックは Repository パターンで ActiveRecord 依存を排除し、Rails 以外の環境でも動作可能な設計とする。
+
+---
+
+## Technical Context
+
+**Language/Version**: Ruby 3.0+（3.2 以上推奨）  
+**Primary Dependencies**: Rails 7.x 以上、RSpec、SimpleCov、RuboCop  
+**Storage**: 利用アプリケーションの DB（ActiveRecord 対応 DB であれば何でも可）。開発・テスト環境は SQLite。  
+**Testing**: RSpec（カバレッジ 90% 以上、SimpleCov 計測）  
+**Target Platform**: Ruby gem（Rail Engine ではなく Railtie を使用）  
+**Project Type**: Ruby gem（Rails 組み込み型ライブラリ）  
+**Performance Goals**:
+- 郵便番号完全一致検索: < 10ms p99（DBインデックス使用前提）  
+- 先頭4桁前方一致検索: < 50ms  
+- Rake インポート（12万件）: < 60秒  
+**Constraints**: Rubocop 100% PASS（disable 禁止）、TDD 必須  
+**Scale/Scope**: 全国郵便番号（約12万件）を管理  
+**Encoding**: KEN_ALL.CSV は Shift_JIS。Rake タスクが UTF-8 に自動変換。  
+**Batch Strategy**: `upsert_all` + 1,000件/バッチ分割。冪等性は `(postal_code, pref_code, city, town)` の一意制約で保証。
+
+---
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+- [x] **I. Gem-First**: `JpAddressComplement` 名前空間に閉じる。Railtie 経由で Rails 統合。Rails 非依存コアロジックを Repository パターンで実現。
+- [x] **II. TDD**: テストを先に書く。RSpec + SimpleCov カバレッジ 90%+ の計画あり。FakeRepository でコアロジックを DB なしテスト可能。
+- [x] **III. Rubocop**: `rubocop:disable` 使用禁止。`.rubocop.yml` で設定変更時は理由明記。CI に Rubocop ゲートを設定。
+- [x] **IV. データ整合性**: `upsert_all`（ON CONFLICT DO UPDATE）で冪等インポート。1,000件/バッチで DB ロック最小化。Shift_JIS→UTF-8 変換を Rake タスクで自動実行。
+- [x] **V. 機能要件**: 3機能（`search_by_postal_code` / `search_by_postal_code_prefix` / `valid_combination?`）のインターフェースを contracts/public-api.md で明確化。引数バリデーション・空返却挙動を定義済み。
+- [x] **VI. シンプルさ**: Repository パターンの採用は FR-010/FR-015（Rails 非依存要件）で正当化済み。DI は Devise/Kaminari と同レベルのシンプルなコンストラクタ注入で実現。YAGNI 遵守（差分インポート・RBS・rom-rb は Deferred）。
+
+**Constitution Check Result**: ✅ 全ゲート PASS
+
+---
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/001-jp-address-complement-gem/
+├── plan.md              ✅ このファイル
+├── spec.md              ✅ 機能仕様
+├── research.md          ✅ Phase 0 調査結果
+├── data-model.md        ✅ データモデル設計
+├── quickstart.md        ✅ 利用者向けガイド
+├── contracts/
+│   └── public-api.md    ✅ 公開 API コントラクト
+└── tasks.md             （/speckit.tasks コマンドで生成）
+```
+
+### Source Code (repository root)
+
+```text
+jp_address_complement.gemspec
+lib/
+├── jp_address_complement.rb              # エントリポイント・モジュールメソッド定義
+├── jp_address_complement/
+│   ├── version.rb                        # VERSION 定数
+│   ├── configuration.rb                  # Config クラス（repository DI 設定）
+│   ├── railtie.rb                        # Rails Railtie（Rails 統合・initializer）
+│   ├── address_record.rb                 # AddressRecord 値オブジェクト（Data/Struct）
+│   ├── normalizer.rb                     # 郵便番号正規化（全角→半角・ハイフン除去）
+│   ├── searcher.rb                       # コア検索ロジック（Repository 経由）
+│   ├── repositories/
+│   │   ├── postal_code_repository.rb     # 抽象基底クラス（インターフェース）
+│   │   └── active_record_postal_code_repository.rb   # ActiveRecord 実装
+│   ├── models/
+│   │   └── postal_code.rb               # ActiveRecord モデル
+│   ├── validators/
+│   │   └── jp_address_complement_validator.rb  # ActiveModel バリデーター
+│   ├── importers/
+│   │   └── csv_importer.rb              # CSV インポートロジック
+│   └── generators/
+│       └── jp_address_complement/
+│           ├── install_generator.rb      # rails g jp_address_complement:install
+│           └── templates/
+│               └── create_postal_codes.rb.erb  # マイグレーションテンプレート
+
+lib/tasks/
+└── jp_address_complement.rake            # jp_address_complement:import タスク
+
+spec/
+├── spec_helper.rb
+├── jp_address_complement_spec.rb         # トップレベルモジュールメソッドの統合テスト
+├── normalizer_spec.rb
+├── searcher_spec.rb
+├── repositories/
+│   └── active_record_repository_spec.rb
+├── validators/
+│   └── jp_address_complement_validator_spec.rb
+├── importers/
+│   └── csv_importer_spec.rb
+├── generators/
+│   └── install_generator_spec.rb
+└── support/
+    ├── fake_repository.rb                # テスト用 FakeRepository
+    └── database_helper.rb
+```
+
+**Structure Decision**: Ruby gem の標準構成（`lib/`, `spec/`, `lib/tasks/`）を採用。Generator テンプレートは Rails のコンベンションに従い `lib/generators/` 配下に配置。
+
+---
+
+## Complexity Tracking
+
+| 複雑化要素 | 正当化理由 | より単純な代替案が却下される理由 |
+|-----------|-----------|-------------------------------|
+| Repository パターン | FR-010/FR-015: Rails 非依存コアが必須 | ActiveRecord 直接依存では Rack/Sinatra 環境での利用不可 |
+| Railtie + Generator | FR-014: Rails 標準のマイグレーション管理 | 自動テーブル作成は利用者の制御を奪い、既存マイグレーション設計に干渉する |
+| upsert_all バッチ分割 | SC-004: 60秒以内インポート＋ Constitution IV の冪等性要件 | 逐次 `find_or_create_by` では12万件に数分かかり SC-004 を満足できない |