jp_address_complement 0.1.0

data/specs/003-csv-remove-obsolete/tasks.md

@@ -0,0 +1,167 @@
+# Tasks: CSVインポート時の消えたレコード削除
+
+**Input**: Design documents from `/specs/003-csv-remove-obsolete/`  
+**Prerequisites**: plan.md, spec.md, research.md, data-model.md, contracts/
+
+**Tests**: Constitution で TDD 必須のため、各 User Story でテストを先に記載。Red-Green-Refactor で実装する。
+
+**Organization**: User Story ごとに Phase を分け、US1 を MVP として独立検証可能にする。
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: 並行実行可能（別ファイル・未完了タスクへの依存なし）
+- **[US1/US2]**: 対応する User Story
+- 各タスクの説明に **ファイルパス** を明記する
+
+## Path Conventions
+
+- 本リポジトリ: `lib/jp_address_complement/`, `spec/` をリポジトリルート基準で使用
+- Rake: `lib/tasks/jp_address_complement.rake`
+
+---
+
+## Phase 1: Setup（ベースライン確認）
+
+**Purpose**: 003 着手前の既存テスト・Lint が通る状態を確認する
+
+- [x] T001 既存の CsvImporter と Rake タスクのテストがパスすることを確認する（spec/importers/csv_importer_spec.rb, spec/tasks/import_task_spec.rb）
+- [x] T002 ベースラインとして bundle exec rubocop がパスすることを確認する
+
+**Checkpoint**: 既存インポート仕様が GREEN の状態
+
+---
+
+## Phase 2: Foundational（全 User Story の前提）
+
+**Purpose**: インポート戻り値の型を定義し、US1/US2 の実装で共通利用する
+
+**⚠️ CRITICAL**: この Phase 完了まで User Story 実装に着手しない
+
+- [x] T003 [P] CsvImporter の import 戻り値用の型（例: Data.define(:upserted, :deleted) または Hash）を lib/jp_address_complement/importers/csv_importer.rb に定義する
+
+**Checkpoint**: 戻り値型が定義済み。US1 実装で import の戻り値をこの型に差し替え可能
+
+---
+
+## Phase 3: User Story 1 - フルインポートで新CSVにない住所レコードを削除する (Priority: P1) 🎯 MVP
+
+**Goal**: 今回のCSVに含まれない住所レコードをストアから削除し、CSV とストアの内容を一致させる。
+
+**Independent Test**: 既存データがある状態で、一部レコードを除いたCSVでインポートを実行し、除いたレコードがストアから消えていることを確認する。
+
+### Tests for User Story 1（先に書き、RED を確認してから実装）
+
+- [x] T004 [P] [US1] 新CSVに含まれないレコードが削除されることを spec/importers/csv_importer_spec.rb で検証する（Given 3件存在, When B を除くCSVでインポート, Then A,C のみ残る）
+- [x] T005 [P] [US1] 空CSV（有効行0件）で ImportError が発生し既存データが変更されないことを spec/importers/csv_importer_spec.rb で検証する
+- [x] T006 [P] [US1] 同じCSVで再インポートしても冪等であることを spec/importers/csv_importer_spec.rb で検証する
+- [x] T007 [P] [US1] upsert 途中で失敗した場合は削除フェーズを実行せず既存データが維持されることを spec/importers/csv_importer_spec.rb で検証する（モックまたはスタブで失敗を再現）
+
+### Implementation for User Story 1
+
+- [x] T008 [US1] CSV 走査中に出現した一意キー (postal_code, pref_code, city, town) を Set で保持する処理を lib/jp_address_complement/importers/csv_importer.rb に追加する
+- [x] T009 [US1] 有効行が1件もない場合に空CSVと判定し JpAddressComplement::ImportError を発生させる処理を lib/jp_address_complement/importers/csv_importer.rb に追加する
+- [x] T010 [US1] upsert が全て成功した後に、キー集合に含まれない行を jp_address_complement_postal_codes から削除する処理を lib/jp_address_complement/importers/csv_importer.rb に追加する
+- [x] T011 [US1] import の戻り値を Phase 2 で定義した型（upserted 件数・deleted 件数）に変更する処理を lib/jp_address_complement/importers/csv_importer.rb に実装する
+
+**Checkpoint**: User Story 1 が単体で動作し、削除・空CSV拒否・冪等・失敗時不削除がテストで確認できる状態
+
+---
+
+## Phase 4: User Story 2 - 削除と追加・更新が同一インポートで正しく反映される (Priority: P2)
+
+**Goal**: 追加・更新・削除が一括で正しく反映され、インポート完了時に件数が報告される。
+
+**Independent Test**: 既存データに対し、一部削除・一部追加・一部変更したCSVでインポートし、最終状態がCSVと一致し、件数が表示されることを確認する。
+
+### Tests for User Story 2
+
+- [x] T012 [P] [US2] 同一インポートで削除・追加・更新が正しく反映される統合テストを spec/importers/csv_importer_spec.rb に追加する（例: A 削除・C 追加 → B,C のみ残る）
+- [x] T013 [P] [US2] Rake タスク実行時に標準出力に upserted/deleted 件数が含まれることを spec/tasks/import_task_spec.rb で検証する
+
+### Implementation for User Story 2
+
+- [x] T014 [US2] jp_address_complement:import タスクで CsvImporter#import の戻り値を受け取り、標準出力に「インポート完了: upsert N 件, 削除 M 件」を表示する処理を lib/tasks/jp_address_complement.rake に追加する
+
+**Checkpoint**: User Story 1 と 2 がともに動作し、Rake から件数が確認できる状態
+
+---
+
+## Phase 5: Polish & Cross-Cutting Concerns
+
+**Purpose**: 品質ゲートとドキュメントの最終確認
+
+- [x] T015 [P] 全テストが GREEN であることと bundle exec rubocop がパスすることを確認する
+- [x] T016 [P] SimpleCov でカバレッジ 90% 以上を確認する
+- [x] T017 公開 API 変更（CsvImporter#import の戻り値が Integer → 件数オブジェクト）に合わせて CHANGELOG を更新する（Constitution Quality Gates 準拠）
+- [x] T018 quickstart.md の手順（インポートで消えたレコード削除・空CSV拒否・件数表示）を手動で確認し、必要なら docs を更新する
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+- **Phase 1 (Setup)**: 依存なし。即時開始可能。
+- **Phase 2 (Foundational)**: Phase 1 完了後に開始。全 User Story の前提となる。
+- **Phase 3 (US1)**: Phase 2 完了後に開始。MVP。
+- **Phase 4 (US2)**: Phase 3 完了後に開始。US1 の拡張（件数報告・Rake 出力）。
+- **Phase 5 (Polish)**: Phase 4 完了後に実施。T017（CHANGELOG）は Constitution Quality Gates 必須。
+
+### User Story Dependencies
+
+- **User Story 1 (P1)**: Phase 2 完了後から開始可能。他ストーリーに依存しない。
+- **User Story 2 (P2)**: Phase 3 完了後から開始可能。US1 の import 戻り値を Rake が表示するだけなので、US1 実装に依存。
+
+### Within Each User Story
+
+- テストを先に書き、失敗を確認してから実装（TDD）。
+- T004〜T007 が RED の状態で T008〜T011 を実装して GREEN にする。
+- T012〜T013 が RED の状態で T014 を実装して GREEN にする。
+
+### Parallel Opportunities
+
+- Phase 1: T001 と T002 は順不同（T002 は Lint のみ）。
+- Phase 2: T003 のみ。
+- Phase 3: T004, T005, T006, T007 は [P] のため並行してテストを記述可能。T008〜T011 は順序あり（キー保持→空CSV→削除→戻り値）。
+- Phase 4: T012 と T013 は [P] で並行してテスト記述可能。
+- Phase 5: T015 と T016 は [P] で並行可能。T017（CHANGELOG）と T018（quickstart 確認）は順不同で実施。
+
+---
+
+## Parallel Example: User Story 1
+
+```text
+# テストを並行して追加（いずれも spec/importers/csv_importer_spec.rb）:
+T004: 新CSVにないレコード削除の example
+T005: 空CSVで ImportError の example
+T006: 冪等の example
+T007: upsert 失敗時は削除しない example
+```
+
+---
+
+## Implementation Strategy
+
+### MVP First（User Story 1 のみ）
+
+1. Phase 1 完了 → ベースライン確認
+2. Phase 2 完了 → 戻り値型定義
+3. Phase 3 完了 → 削除・空CSV拒否・冪等・戻り値
+4. **STOP and VALIDATE**: CsvImporter のテストのみで US1 を検証
+5. 必要ならデモまたはコミット
+
+### Incremental Delivery
+
+1. Phase 1 + 2 → 基盤のみ
+2. Phase 3 (US1) → 削除機能が単体で動作（MVP）
+3. Phase 4 (US2) → 件数報告と Rake 出力
+4. Phase 5 → 品質ゲートと quickstart 確認
+
+### Notes
+
+- [P] タスクは別ファイル・依存なしで並行可能。
+- [US1]/[US2] でストーリーとタスクを対応付ける。
+- 各 User Story は独立して完了・検証可能。
+- テストは必ず先に書き、失敗を確認してから実装する。
+- チェックポイントでストーリー単位の検証を行う。
+- **SC-003（許容可能な範囲）**: パフォーマンスは plan 上の目安（既存インポート時間の約2倍以内）とする。本 tasks では専用の計測・検証タスクは設けず、必要に応じて手動またはベンチで確認する。

data/specs/004-prefecture-code-reverse-lookup/checklists/requirements.md

@@ -0,0 +1,34 @@
+# Specification Quality Checklist: 都道府県コード変換・住所逆引き（住所→郵便番号）
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning  
+**Created**: 2026-02-23  
+**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
+
+- すべてのチェック項目をクリアしています。`/speckit.clarify` または `/speckit.plan` へ進んでください。

data/specs/004-prefecture-code-reverse-lookup/contracts/public-api-prefecture-and-reverse.md

@@ -0,0 +1,122 @@
+# Public API Contract: 都道府県コード変換・住所逆引き（004 追加 API）
+
+**Gem**: `jp_address_complement`  
+**Namespace**: `JpAddressComplement`  
+**Contract Type**: Ruby Public API（004 で追加する公開インターフェース）
+
+---
+
+## 追加するモジュールメソッド
+
+既存の `search_by_postal_code` / `search_by_postal_code_prefix` / `valid_combination?` に加え、以下 3 つを提供する。
+
+---
+
+### `prefecture_name_from_code(code) → String | nil`
+
+都道府県コード（JIS X 0401、2桁）から都道府県名を返す。
+
+**引数**
+
+| 名前 | 型 | 説明 |
+|-----|----|------|
+| `code` | `String`, `Integer`, `nil` | 都道府県コード。数値（例: 13）またはゼロパディング文字列（例: "13", "01"）。 |
+
+**戻り値**: `String` または `nil`
+
+- 有効なコード（01–47）の場合は対応する都道府県名（例: "東京都"）。
+- 存在しないコード・範囲外・nil・空文字の場合は `nil`。例外は発生しない。
+
+**例**
+
+```ruby
+JpAddressComplement.prefecture_name_from_code("13")   # => "東京都"
+JpAddressComplement.prefecture_name_from_code(13)     # => "東京都"
+JpAddressComplement.prefecture_name_from_code("01")   # => "北海道"
+JpAddressComplement.prefecture_name_from_code(99)     # => nil
+JpAddressComplement.prefecture_name_from_code(nil)    # => nil
+JpAddressComplement.prefecture_name_from_code("")     # => nil
+```
+
+---
+
+### `prefecture_code_from_name(name) → String | nil`
+
+都道府県名（正式名称）から都道府県コードを 2 桁の文字列で返す。
+
+**引数**
+
+| 名前 | 型 | 説明 |
+|-----|----|------|
+| `name` | `String`, `nil` | 都道府県の正式名称（例: "東京都", "北海道"）。省略表記は受け付けない。 |
+
+**戻り値**: `String` または `nil`
+
+- 正式名称に一致する場合は 2 桁の文字列（例: "13", "01"）。ゼロパディングを維持する。
+- 一致しない場合・nil・空文字の場合は `nil`。例外は発生しない。
+
+**例**
+
+```ruby
+JpAddressComplement.prefecture_code_from_name("東京都")  # => "13"
+JpAddressComplement.prefecture_code_from_name("北海道")  # => "01"
+JpAddressComplement.prefecture_code_from_name("東京")    # => nil（省略表記は不可）
+JpAddressComplement.prefecture_code_from_name("不明")    # => nil
+JpAddressComplement.prefecture_code_from_name(nil)       # => nil
+JpAddressComplement.prefecture_code_from_name("")        # => nil
+```
+
+---
+
+### `search_postal_codes_by_address(pref:, city:, town: nil) → Array<String>`
+
+都道府県・市区町村・町域（任意）を指定し、該当する郵便番号の候補一覧を返す（逆引き）。
+
+**引数**
+
+| 名前 | 型 | 必須 | 説明 |
+|-----|----|------|------|
+| `pref` | `String` | ✅ | 都道府県名（正式名称）。住所データの `pref` と完全一致。 |
+| `city` | `String` | ✅ | 市区町村名。住所データの `city` と完全一致。 |
+| `town` | `String` | ❌ | 町域名。省略時は都道府県＋市区町村のみで検索。指定時は完全一致で絞り込む。 |
+
+**戻り値**: `Array<String>`
+
+- 該当する郵便番号（7桁文字列）の配列。重複は除く。
+- 該当なし・pref または city が nil/空・入力不十分の場合は `[]`。例外は発生しない。
+
+**照合**: 各フィールドは既存の住所データ（`pref`, `city`, `town`）と **完全一致**。入力はデータと同じ表記を前提とする。
+
+**例**
+
+```ruby
+# 都道府県・市区町村・町域を指定
+JpAddressComplement.search_postal_codes_by_address(pref: "東京都", city: "千代田区", town: "千代田")
+# => ["1000001", ...]
+
+# 町域は省略（都道府県＋市区町村のみ）
+JpAddressComplement.search_postal_codes_by_address(pref: "東京都", city: "千代田区")
+# => ["1000001", "1000002", ...]
+
+# 該当なし
+JpAddressComplement.search_postal_codes_by_address(pref: "東京都", city: "存在しない区")
+# => []
+
+# 入力不十分（検索しない）
+JpAddressComplement.search_postal_codes_by_address(pref: "東京都", city: nil)
+# => []
+JpAddressComplement.search_postal_codes_by_address(pref: "東京都", city: "")
+# => []
+```
+
+---
+
+## Repository の拡張（内部契約）
+
+`JpAddressComplement::Repositories::PostalCodeRepository` に以下を追加する。
+
+### `find_postal_codes_by_address(pref:, city:, town: nil) → Array<String>`
+
+- 都道府県・市区町村・町域で完全一致検索し、郵便番号の配列を返す。
+- pref または city が nil/空の場合は `[]` を返す。
+- 実装は `ActiveRecordPostalCodeRepository` で、既存の `postal_codes` テーブルに対して `WHERE pref = ? AND city = ? AND (town = ? OR town IS NULL)` に相当するクエリを発行し、結果の postal_code を重複排除して返す。

data/specs/004-prefecture-code-reverse-lookup/data-model.md

@@ -0,0 +1,81 @@
+# Data Model: 都道府県コード変換・住所逆引き
+
+**Branch**: `004-prefecture-code-reverse-lookup`  
+**Date**: 2026-02-23
+
+---
+
+## 概要
+
+本機能では **新規の DB テーブルは追加しない**。都道府県コード⇔名称はメモリ内の定数、逆引きは既存の `jp_address_complement_postal_codes` テーブルを利用する。
+
+---
+
+## 1. 都道府県マッピング（論理エンティティ）
+
+コード⇔名称の対応は、gem 内の静的なデータとして保持する。
+
+### 属性
+
+| 属性 | 型 | 説明 |
+|------|-----|------|
+| コード | String (2桁) | JIS X 0401。01–47。ゼロパディング（"01", "13"）。 |
+| 名称 | String | 都道府県名（正式名称）。例: "東京都", "北海道"。 |
+
+### 制約
+
+- コードは 01–47 の範囲のみ有効。それ以外は該当なしとして nil を返す。
+- 名称は正式名称のみ有効。省略表記は受け付けない（該当なし → nil）。
+- 入力が nil または空文字の場合は例外を投げず nil を返す。
+
+### 実装上の表現
+
+- Ruby ではハッシュ 2 つ、または 1 つのハッシュで双方向参照可能にする。
+  - 例: `CODE_TO_NAME = { "01" => "北海道", ... }` と `NAME_TO_CODE = CODE_TO_NAME.invert`（または 47 件の定数マッピング）。
+
+---
+
+## 2. 逆引き入力（Reverse Lookup Input）
+
+API の引数として渡す構造。DB の形ではなく、メソッドのキーワード引数として表現する。
+
+### フィールド
+
+| フィールド | 型 | 必須 | 説明 |
+|-----------|-----|------|------|
+| pref | String | ✅ | 都道府県名（正式名称）。住所データの `pref` と完全一致。 |
+| city | String | ✅ | 市区町村名。住所データの `city` と完全一致。 |
+| town | String | ❌ | 町域名。省略時は都道府県＋市区町村のみで検索。指定時は `town` と完全一致で絞り込む。 |
+
+### 検索条件
+
+- pref と city が両方揃っている場合のみ検索を実行する。
+- 各フィールドは既存の `jp_address_complement_postal_codes` の `pref`, `city`, `town` と **完全一致** で照合する。
+- 入力は UTF-8。住所データ（郵便番号データ）と同じ表記を前提とする。
+
+---
+
+## 3. 逆引き結果（郵便番号候補）
+
+逆引きの戻り値は **郵便番号（7桁文字列）の配列**。
+
+### 制約
+
+- 該当する郵便番号を重複なく返す。同一郵便番号に複数レコード（町域違い等）がある場合は 1 つにまとめる。
+- 該当なし・入力不十分（pref または city が空など）の場合は空配列 `[]` を返す。
+- 不正入力時も例外を投げず `[]` を返す。
+
+---
+
+## 4. 既存テーブルとの関係
+
+既存の `jp_address_complement_postal_codes` のカラム `pref_code`, `pref`, `city`, `town` をそのまま利用する。
+
+### 逆引き用のインデックス（推奨）
+
+パフォーマンス要件（SC-003: 50ms p99）を満たすため、次の複合インデックスの追加を推奨する。
+
+- カラム: `(pref, city, town)` または `(pref_code, city, town)`
+- 用途: `WHERE pref = ? AND city = ? AND (town = ? OR town IS NULL)` のような逆引きクエリの高速化
+
+既存の 001 マイグレーションを変更しない方針とする場合は、別マイグレーションまたはドキュメント上の「推奨インデックス」として案内する。

data/specs/004-prefecture-code-reverse-lookup/plan.md

@@ -0,0 +1,92 @@
+# Implementation Plan: 都道府県コード変換・住所逆引き（住所→郵便番号）
+
+**Branch**: `004-prefecture-code-reverse-lookup` | **Date**: 2026-02-23 | **Spec**: [spec.md](./spec.md)  
+**Input**: Feature specification from `/specs/004-prefecture-code-reverse-lookup/spec.md`
+
+---
+
+## Summary
+
+都道府県コード⇔都道府県名の相互変換と、住所（都道府県・市区町村・町域を分離した入力）から郵便番号候補を取得する逆引き機能を追加する。  
+**技術方針**: コード⇔名称は JIS X 0401（01–47）の静的なマッピングで実装し、DB 不要で即時応答する。逆引きは既存の `PostalCodeRepository` に `find_postal_codes_by_address(pref:, city:, town:)` を追加し、既存の `postal_codes` テーブルに対して都道府県・市区町村・町域の完全一致で検索する。既存の Searcher / モジュールメソッドと同様に、Repository 経由で Rails 非依存のコアロジックを保つ。
+
+---
+
+## Technical Context
+
+**Language/Version**: Ruby 3.0+（3.2 以上推奨）  
+**Primary Dependencies**: Rails 7.x 以上（オプション）、RSpec、SimpleCov、RuboCop  
+**Storage**: 都道府県コード⇔名称はメモリ内の定数マッピング。逆引きは既存の `jp_address_complement_postal_codes` テーブルを利用。  
+**Testing**: RSpec（カバレッジ 90% 以上、SimpleCov 計測）  
+**Target Platform**: Ruby gem（Rails 組み込み時は Railtie 経由）  
+**Project Type**: Ruby gem（ライブラリ）  
+**Performance Goals**:
+- 都道府県コード⇔名称: < 5ms（定数参照のため trivial）
+- 逆引き: < 50ms p99（既存 DB インデックス活用、後述の複合インデックス追加を推奨）
+**Constraints**: Rubocop 100% PASS（disable 禁止）、TDD 必須  
+**Scale/Scope**: 47 都道府県のマッピング、逆引きは既存の約 12 万件の郵便番号データに対して完全一致検索。  
+**Encoding**: 入力・出力とも UTF-8。既存仕様と同一。
+
+---
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+- [x] **I. Gem-First**: 機能はすべて `JpAddressComplement` 名前空間に閉じる。都道府県マッピングは gem 内の定数、逆引きは既存 Repository の拡張のみ。責務は「住所・郵便番号の補完・変換」の範囲内。
+- [x] **II. TDD**: 新機能に対し先にテストを書き、Red-Green-Refactor を厳守。既存の FakeRepository パターンを拡張して逆引きをテスト可能にする。
+- [x] **III. Rubocop**: 新規・変更コードは `rubocop:disable` なしで 100% パス。
+- [x] **IV. データ整合性**: 新規テーブルは追加しない。既存の郵便番号データと JIS X 0401 の都道府県コード体系を一致させて使用。インポート戦略は変更なし。
+- [x] **V. 機能要件**: 都道府県コード→名称・名称→コード・逆引きの 3 機能を明確なインターフェースで提供。該当なし時は仕様どおりコード⇔名称は `nil`、逆引きは `[]`。不正入力は例外を投げず `nil` / `[]` で応答。
+- [x] **VI. シンプルさ**: 都道府県マッピングは 47 件の静的なハッシュ/定数で足りる（YAGNI）。逆引きは既存 Repository に 1 メソッド追加で対応。
+
+**Constitution Check Result**: ✅ 全ゲート PASS
+
+---
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/004-prefecture-code-reverse-lookup/
+├── plan.md              # このファイル
+├── spec.md              # 機能仕様
+├── research.md          # Phase 0 調査
+├── data-model.md        # Phase 1 データモデル
+├── quickstart.md        # Phase 1 利用者向けガイド
+├── contracts/           # Phase 1 API コントラクト
+│   └── public-api-prefecture-and-reverse.md
+└── tasks.md             # （/speckit.tasks で生成）
+```
+
+### Source Code (repository root)
+
+既存構造を拡張するのみ。新規ディレクトリは作らない。
+
+```text
+lib/jp_address_complement/
+├── jp_address_complement.rb     # モジュールメソッド 3 つ追加（後述）
+├── searcher.rb                  # 逆引きメソッド 1 つ追加
+├── prefecture.rb                # 新規: 都道府県コード⇔名称（定数＋メソッド）
+├── repositories/
+│   ├── postal_code_repository.rb           # find_postal_codes_by_address を追加
+│   └── active_record_postal_code_repository.rb  # 上記の実装
+└── （その他既存ファイルは変更なし）
+
+spec/
+├── jp_address_complement/
+│   └── prefecture_spec.rb        # 新規: 都道府県変換のユニットテスト
+├── searcher_spec.rb              # 逆引きのテストを追加
+├── repositories/
+│   └── active_record_postal_code_repository_spec.rb  # find_postal_codes_by_address のテスト
+└── （既存テストは必要に応じて拡張）
+```
+
+**Structure Decision**: 既存の gem レイアウトを維持。都道府県ロジックは `Prefecture` モジュール（定数＋クラスメソッド）に集約し、逆引きは `Searcher` と `PostalCodeRepository` に追加する。
+
+---
+
+## Complexity Tracking
+
+（本機能では Constitution 違反はなく、記録不要）

data/specs/004-prefecture-code-reverse-lookup/quickstart.md

@@ -0,0 +1,91 @@
+# クイックスタート: 都道府県コード変換・住所逆引き（004）
+
+**前提**: 001 のセットアップ（マイグレーション・郵便番号データのインポート）が完了していること。  
+逆引き機能は既存の `jp_address_complement_postal_codes` テーブルを利用します。都道府県コード⇔名称は DB 不要で利用できます。
+
+---
+
+## 都道府県コードから都道府県名を取得する
+
+```ruby
+# 2桁の文字列（ゼロパディング）
+JpAddressComplement.prefecture_name_from_code("13")
+# => "東京都"
+
+JpAddressComplement.prefecture_name_from_code("01")
+# => "北海道"
+
+# 数値も受け付ける
+JpAddressComplement.prefecture_name_from_code(13)
+# => "東京都"
+
+# 該当しないコード・nil・空文字の場合は nil（例外なし）
+JpAddressComplement.prefecture_name_from_code(99)  # => nil
+JpAddressComplement.prefecture_name_from_code(nil) # => nil
+```
+
+---
+
+## 都道府県名から都道府県コードを取得する
+
+```ruby
+# 正式名称のみ有効（省略表記は不可）
+JpAddressComplement.prefecture_code_from_name("東京都")
+# => "13"
+
+JpAddressComplement.prefecture_code_from_name("北海道")
+# => "01"
+
+# 戻り値は常に 2 桁の文字列（ゼロパディング維持）
+JpAddressComplement.prefecture_code_from_name("北海道")
+# => "01"
+
+# 該当しない名称・省略表記・nil・空の場合は nil
+JpAddressComplement.prefecture_code_from_name("東京") # => nil
+JpAddressComplement.prefecture_code_from_name(nil)   # => nil
+```
+
+---
+
+## 住所から郵便番号を検索する（逆引き）
+
+都道府県・市区町村・町域を **分離した引数** で渡します。都道府県と市区町村は必須、町域は任意です。各フィールドは住所データと **完全一致** で照合されます（データと同じ表記で渡してください）。
+
+```ruby
+# 都道府県・市区町村・町域を指定
+JpAddressComplement.search_postal_codes_by_address(
+  pref: "東京都",
+  city: "千代田区",
+  town: "千代田"
+)
+# => ["1000001", ...]
+
+# 町域は省略（都道府県＋市区町村に属する郵便番号をすべて返す）
+JpAddressComplement.search_postal_codes_by_address(
+  pref: "東京都",
+  city: "千代田区"
+)
+# => ["1000001", "1000002", ...]
+
+# 該当なし・入力不十分の場合は空配列（例外なし）
+JpAddressComplement.search_postal_codes_by_address(pref: "東京都", city: "存在しない区")
+# => []
+
+JpAddressComplement.search_postal_codes_by_address(pref: "東京都", city: nil)
+# => []
+```
+
+---
+
+## パフォーマンス（逆引き）
+
+逆引きの応答時間を 50ms 以下に保つため、次の複合インデックスの追加を推奨します（未追加の場合は data-model.md を参照）。
+
+```ruby
+# マイグレーション例（推奨）
+add_index :jp_address_complement_postal_codes,
+          [:pref, :city, :town],
+          name: "idx_jp_address_complement_reverse_lookup"
+```
+
+既存の郵便番号テーブルに上記インデックスがない場合、データ量によってはクエリが遅くなる可能性があります。

data/specs/004-prefecture-code-reverse-lookup/research.md

@@ -0,0 +1,62 @@
+# Research: 都道府県コード変換・住所逆引き
+
+**Branch**: `004-prefecture-code-reverse-lookup`  
+**Date**: 2026-02-23
+
+---
+
+## 1. 都道府県コード⇔名称の保持場所
+
+**Decision**: 47 都道府県のコード・名称マッピングは **gem 内の静的な定数（ハッシュまたは配列）** で保持する。DB や外部ファイルは使わない。
+
+**Rationale**:
+- JIS X 0401 の都道府県コード（01–47）は国で定められた固定データであり、郵便番号データの更新とは独立している。
+- 47 件のみのためメモリ負荷は無視でき、参照も O(1) で 5ms 以下の応答を満たせる。
+- DB に依存しないため、未インポート状態でもコード⇔名称だけは利用可能になり、利用者にとって分かりやすい。
+- 既存の `postal_codes` テーブルの `pref_code` / `pref` と体系を揃えるため、JIS X 0401 の正式な 01–47 のマッピングを採用する。
+
+**Alternatives considered**:
+- **DB の distinct から取得**: 郵便番号データに依存し、未インポート時は使えない。また毎回クエリする必要があり、定数参照より遅い。
+- **外部 YAML/JSON**: ファイル I/O とパースが発生し、定数より遅く、配布・バージョン管理も複雑になる。
+
+---
+
+## 2. 逆引きの実装経路（Repository 拡張）
+
+**Decision**: 既存の `PostalCodeRepository` に **`find_postal_codes_by_address(pref:, city:, town: nil)`** を追加する。戻り値は郵便番号の配列（`Array<String>` または仕様に合わせて `Array<AddressRecord>` の postal_code のみ返すかは contracts で定義）。実装は `ActiveRecordPostalCodeRepository` で `WHERE pref = ? AND city = ? AND (town = ? OR town IS NULL)` のような完全一致クエリとする。
+
+**Rationale**:
+- 既存の「郵便番号→住所」と対になる逆方向の検索であり、同じ Repository に置くことで一貫したデータアクセス層を保てる。
+- 仕様で「都道府県＋市区町村必須、町域は任意」「各フィールド完全一致」とあるため、1 メソッドで表現できる。
+- Rails 非依存のコアを保つため、Repository インターフェースにだけ依存し、Searcher がそれを呼ぶ形は既存パターンと同じ。
+
+**Alternatives considered**:
+- **専用の ReverseLookupRepository**: 現時点では 1 クエリで完結するため、YAGNI の観点で既存 Repository の拡張で十分。
+- **連結文字列で検索**: 仕様で分離入力・完全一致に決まっているため不採用。
+
+---
+
+## 3. 逆引きクエリのインデックス
+
+**Decision**: 逆引きのパフォーマンス（SC-003: 50ms p99）を満たすため、**`(pref, city, town)` の複合インデックス**（または `(pref_code, city, town)`）を推奨する。既存の `postal_code` 単一インデックスと一意制約 `(postal_code, pref_code, city, town)` だけでは、逆引きはフルスキャンに近くなる可能性がある。
+
+**Rationale**:
+- 逆引きは `WHERE pref = ? AND city = ? AND (town = ? OR town IS NULL)` のような条件になるため、`pref, city, town` の順の複合インデックスが有効。
+- 既存テーブルに対する追加インデックスは、マイグレーションまたは quickstart で「推奨インデックス」として案内する。001 で既存のマイグレーションに含めていないため、004 で「逆引き用推奨インデックス」をドキュメントと optional マイグレーションで提供するか、既存マイグレーションを変更しない場合は data-model と quickstart に記載のみとする（実装時に判断）。
+
+**Alternatives considered**:
+- **インデックスなし**: 12 万件程度ならフルスキャンでも 50ms を下回る可能性はあるが、保証は難しい。インデックスを推奨する方が安全。
+- **全文検索**: 仕様は完全一致のため不要。
+
+---
+
+## 4. 戻り値の型（逆引き）
+
+**Decision**: 逆引きの戻り値は **郵便番号の文字列の配列 `Array<String>`** とする。`AddressRecord` の配列でも要件は満たせるが、仕様が「郵便番号の候補一覧」としているため、呼び出し側がそのまま使える `["1000001", "1000002"]` の形を採用する。必要なら後から `Array<AddressRecord>` を返す API を追加可能。
+
+**Rationale**:
+- 仕様の「郵便番号の候補一覧」に素直に対応し、既存の `search_by_postal_code`（AddressRecord 配列）とは用途が違うため、シンプルに文字列配列で揃える。
+- 一意化は仕様どおり「該当するすべての郵便番号を候補として返す」で、同一郵便番号が複数レコード（町域違い）で存在する場合は 1 つにまとめる。
+
+**Alternatives considered**:
+- **Array<AddressRecord>**: 将来的に住所詳細も必要になった場合の拡張用。現仕様では「郵便番号候補」のみなので、まずは `Array<String>` で十分。