jp_address_complement 0.1.0

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

@@ -0,0 +1,120 @@
+# Feature Specification: 都道府県コード変換・住所逆引き（住所→郵便番号）
+
+**Feature Branch**: `004-prefecture-code-reverse-lookup`  
+**Created**: 2026-02-23  
+**Status**: Draft  
+**Input**: User description: "都道府県のコード変換、逆引き（住所→郵便番号）の機能を提供します"
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - 都道府県コードから都道府県名を取得する (Priority: P1)
+
+利用者が都道府県コード（2桁の数値またはゼロパディング文字列）を渡すと、対応する都道府県名（例: 「東京都」）を取得できる。外部システムや既存DBが都道府県をコードで保持している場合に、表示用の名称へ変換するために使用する。
+
+**Why this priority**: コード→名称の変換は、表示・帳票・API応答で頻出する基本ニーズであり、この機能単体で即時価値がある。
+
+**Independent Test**: 都道府県コード「13」を渡して「東京都」が返ることを確認することで、独立してテスト可能。
+
+**Acceptance Scenarios**:
+
+1. **Given** 有効な都道府県コード（例: 13 または "13"）を与えた時、**When** コードから名称を取得すると、**Then** 対応する都道府県名（「東京都」）が返る。
+2. **Given** ゼロパディングされた文字列（例: "01"）を与えた時、**When** コードから名称を取得すると、**Then** 対応する都道府県名（「北海道」）が返る。
+3. **Given** 存在しないコード（例: 99）または範囲外を与えた時、**When** コードから名称を取得すると、**Then** nil が返る（例外は発生しない）。
+4. **Given** nil や空文字を与えた時、**When** コードから名称を取得すると、**Then** エラーを発生させず、nil が返る。
+
+---
+
+### User Story 2 - 都道府県名から都道府県コードを取得する (Priority: P2)
+
+利用者が都道府県名（例: 「東京都」「北海道」）を渡すと、対応する都道府県コードを2桁の文字列（例: "13", "01"）で取得できる。フォームで都道府県名を選択した後に、DB保存用のコードへ変換するために使用する。
+
+**Why this priority**: 名称→コードは、既存の「郵便番号→住所」フローと組み合わせてデータ正規化に使われるため、P1の次に重要。
+
+**Independent Test**: 都道府県名「東京都」を渡して2桁の文字列「13」が返ることを確認することで、独立してテスト可能。
+
+**Acceptance Scenarios**:
+
+1. **Given** 正式な都道府県名（例: 「東京都」「北海道」）を与えた時、**When** 名称からコードを取得すると、**Then** 対応する都道府県コードが2桁の文字列（例: "13", "01"）で返る。
+2. **Given** 省略表記（例: 「東京」「北海」）や正式名称以外の文字列を与えた時、**When** 名称からコードを取得すると、**Then** nil が返る（正式名称のみ受け付けるため）。
+3. **Given** 存在しない都道府県名や曖昧な文字列を与えた時、**When** 名称からコードを取得すると、**Then** nil が返る（例外は発生しない）。
+4. **Given** nil や空文字を与えた時、**When** 名称からコードを取得すると、**Then** エラーを発生させず、nil が返る。
+
+---
+
+### User Story 3 - 住所（分離フィールド）から郵便番号（候補）を取得する（逆引き） (Priority: P3)
+
+利用者が都道府県名・市区町村名・町域名を**分離した形**（連結した1文字列ではなく、それぞれ別フィールド）で渡すと、その住所に対応する郵便番号の候補一覧を取得できる。最低限、都道府県と市区町村が揃っている場合にのみ検索を行う。町域は任意で、指定されていれば結果を絞り込む。住所は分かっているが郵便番号が不明なデータの補完や、バリデーション・データ整形に使用する。
+
+**Why this priority**: 既存の「郵便番号→住所」の逆方向の検索であり、データ入力の双方向補完や既存データの正規化に役立つ。
+
+**Independent Test**: 都道府県「東京都」、市区町村「千代田区」、町域「千代田」を分離して渡し、対応する郵便番号（例: 1000001）が候補に含まれることを確認することで、独立してテスト可能。
+
+**Acceptance Scenarios**:
+
+1. **Given** 都道府県・市区町村・町域を分離したフィールドで渡し（例: 都道府県「東京都」、市区町村「千代田区」、町域「千代田」）、**When** 住所から郵便番号を検索すると、**Then** その住所に対応する郵便番号の候補（1件以上）が返る。
+2. **Given** 都道府県と市区町村のみを渡し、町域は省略した時、**When** 住所から郵便番号を検索すると、**Then** その都道府県・市区町村に属する郵便番号の候補一覧が返る。
+3. **Given** 都道府県のみ、または市区町村が欠けているなど、都道府県＋市区町村が揃っていない時、**When** 住所から郵便番号を検索すると、**Then** 空の候補リストが返る（検索は行わない）。
+4. **Given** 複数の町域が同一の都道府県・市区町村・町域の組み合わせで存在する場合、**When** 住所から郵便番号を検索すると、**Then** 該当する複数の郵便番号が候補として返る。
+5. **Given** 存在しないまたはデータにない住所の組み合わせを与えた時、**When** 住所から郵便番号を検索すると、**Then** 空の候補リストが返る。
+6. **Given** 必須フィールド（都道府県・市区町村）が nil や空の時、**When** 住所から郵便番号を検索すると、**Then** エラーを発生させず、空の結果が返る。
+
+---
+
+### Edge Cases
+
+- 都道府県コードの体系が複数ある場合（JIS X 0401 等）、どの体系を採用するかは仕様で明示し、一貫して同じ体系でコード⇔名称を扱う。
+- 都道府県名は正式名称（「東京都」「北海道」等）のみを受け付ける。省略表記（「東京」「北海」等）は許容しない。
+- 逆引きで、住所が複数郵便番号にまたがる場合（例: 大口事業所と一般町域）は、該当する郵便番号をすべて候補として返す。
+- 逆引きの入力は、連結した住所文字列ではなく、都道府県名・市区町村名・町域名を**分離したフィールド**で受け取る。都道府県＋市区町村が揃っている場合にのみ検索を実行し、それ未満（都道府県のみ等）の場合は空の候補リストを返す。町域は任意で、指定時は結果を絞り込む。照合は都道府県・市区町村・町域の各フィールドと住所データの対応する項目を**完全一致**で行う。入力は住所データと同じ表記を前提とする。
+- 不正入力（nil、空文字、型の不一致）に対しては例外を投げず、空の結果で応答する。コード→名称・名称→コードで該当なしのときは nil を返す。逆引きで該当なしや入力不十分のときは空の候補リスト（0件のリスト）を返す。
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: システムは都道府県コード（2桁、01–47 の範囲を想定）を受け取り、対応する都道府県名を返さなければならない。
+- **FR-002**: 都道府県コードは数値またはゼロパディングされた文字列（例: "01", "13"）のいずれでも受け付け、同一の都道府県名を返さなければならない。
+- **FR-003**: 存在しない都道府県コードや範囲外の値を渡された場合、例外を発生させず、nil を返さなければならない。
+- **FR-004**: システムは都道府県名を**正式名称のみ**受け取り、対応する都道府県コードを返さなければならない。戻り値は2桁の文字列（例: "01", "13"）とし、ゼロパディングを維持する。省略表記（「東京」「北海」等）は受け付けない。
+- **FR-005**: 都道府県名の照合は正式名称（「東京都」「北海道」等）と完全一致で行い、省略表記は許容しない。
+- **FR-006**: 正式名称に一致しない都道府県名や曖昧な文字列を渡された場合、例外を発生させず、nil を返さなければならない。
+- **FR-007**: システムは逆引きの入力として、都道府県名・市区町村名・町域名を**分離したフィールド**（連結文字列ではない）で受け取り、その住所に対応する郵便番号の候補一覧を返さなければならない。
+- **FR-008**: 逆引きは都道府県＋市区町村が揃っている場合にのみ検索を実行する。都道府県・市区町村・町域の各フィールドは住所データの対応する項目と**完全一致**で照合しなければならない。町域が指定されていない場合は都道府県＋市区町村のみで照合する。入力は住所データと同じ表記を前提とする。
+- **FR-009**: 一つの住所（都道府県・市区町村・町域の組み合わせ）に複数の郵便番号が対応する場合、該当するすべての郵便番号を候補として返さなければならない。
+- **FR-010**: 逆引きで都道府県または市区町村が欠けている場合、該当する住所が存在しない場合、または必須フィールドが空の場合は、検索を行わず空の候補リストを返さなければならない。
+- **FR-011**: コード→名称・名称→コードでは、該当なし・不正入力時は例外を発生させず nil を返さなければならない。逆引きでは、該当なし・入力不十分時は空の候補リストを返し、不正入力時は例外を発生させず空の候補リストを返さなければならない。
+- **FR-012**: 都道府県コードの体系（例: JIS X 0401）は仕様で明示し、コード変換はその体系に従って一貫して動作しなければならない。
+
+### Key Entities
+
+- **都道府県 (Prefecture)**: 都道府県コードと都道府県名の対応を表す。47都道府県分のコード・名称ペアが存在する。既存の住所データ（郵便番号データ）と整合したコード体系を用いる。名称→コードの戻り値は2桁の文字列（ゼロパディング維持）とする。
+- **逆引き入力 (Reverse lookup input)**: 都道府県名・市区町村名・町域名を**分離したフィールド**で受け取る構造。連結した1文字列ではなく、住所レコードの都道府県名・市区町村名・町域名に相当する属性を個別に指定する。都道府県＋市区町村が必須で、町域は任意。各フィールドは住所データと完全一致で照合されるため、データと同じ表記で渡すことを前提とする。
+- **郵便番号候補 (Postal code candidates)**: 逆引きの結果として返される、住所に対応する郵便番号のリスト。1件または複数件となりうる。
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: 都道府県コードから名称への変換が 5 ミリ秒以内に完了する（単一呼び出し）。コード⇔名称は DB に依存しないため、常に満たすことを想定する。
+- **SC-002**: 都道府県名からコードへの変換が 5 ミリ秒以内に完了する（単一呼び出し）。同上。
+- **SC-003**: 住所（都道府県・市区町村・町域を分離した入力）からの郵便番号逆引きが、既存の住所データとインデックスが利用可能な状態で 50 ミリ秒以内に完了する（99パーセンタイル）。
+- **SC-004**: 47都道府県すべてについて、コード⇔名称の変換が正しく行える。
+- **SC-005**: 日本郵便の公式データに含まれる代表的な住所について、分離フィールドで逆引きした際に正しい郵便番号候補が返る（サンプル検証で確認可能）。
+
+## Assumptions
+
+- 都道府県コードは JIS X 0401（2桁、01–47）を採用する。既存の住所テーブルに都道府県コードが含まれている場合は、そのコード体系に合わせる。都道府県名→コードの戻り値は2桁の文字列（"01", "13" 等）とし、ゼロパディングを維持する。
+- 逆引きに用いる住所データは、既存機能（郵便番号→住所）と同じデータソース（日本郵便の郵便番号データに基づくDB）を利用する。新たに別データソースを導入しない。
+- 都道府県名は正式名称（「東京都」「北海道」等）のみを受け付ける。省略表記（「東京」「北海」等）は許容しない。
+- 逆引きの入力は都道府県・市区町村・町域を分離したフィールドで渡し、各フィールドは UTF-8 の文字列を前提とする。照合は完全一致のため、住所データ（郵便番号データ）と同じ表記で渡すことを前提とする。読みがなのみの検索は本機能のスコープ外とする。
+- 該当なし・不正入力時は例外を発生させず、スカラー検索は nil、リスト検索は空配列で返す。Constitution 原則 V の「戻り値の型の一貫性」は、この nil / 空配列の使い分けで満たすものとする。
+
+## Clarifications
+
+### Session 2026-02-23
+
+- Q: 逆引きで住所が短すぎる場合（都道府県のみ等）の扱い（件数上限 vs 最低一致条件）はどうするか？ → A: 都道府県＋市区町村を必須とする（B）。さらに、入力は連結した1文字列ではなく、都道府県・市区町村・町域を分離した構造（住所レコードの都道府県名・市区町村名・町域名に相当するフィールド）で受け取るインターフェースとする。
+- Q: 都道府県名の省略表記（「東京」等）の許容範囲を仕様でどう決めるか？ → A: 正式名称のみ受け付ける。省略表記は許容しない（C）。
+- Q: 都道府県コード→名称・名称→コードで該当なしのときの戻り値の形はどうするか？ → A: 該当なしのときは nil を返す（名称・コードどちらも）（A）。
+- Q: 逆引きで都道府県・市区町村・町域の各フィールドを住所データとどう照合するか？ → A: 各フィールドとも**完全一致**で照合する。入力はデータと同じ表記を前提とする（A）。
+- Q: 都道府県名→コードの戻り値の型（数値か文字列か）はどうするか？ → A: 2桁の文字列で返す（例: "13", "01"）。ゼロパディングを維持する（B）。

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

@@ -0,0 +1,190 @@
+# Tasks: 都道府県コード変換・住所逆引き（住所→郵便番号）
+
+**Input**: Design documents from `/specs/004-prefecture-code-reverse-lookup/`  
+**Prerequisites**: plan.md, spec.md, research.md, data-model.md, contracts/
+
+**Tests**: Constitution に従い TDD を採用。各ユーザーストーリーでテストを先に書き、失敗を確認してから実装する。
+
+**Organization**: ユーザーストーリーごとにタスクをグループ化し、各ストーリーを独立して実装・テストできるようにする。
+
+## Format: `[ID] [P?] [Story?] Description`
+
+- **[P]**: 並列実行可能（別ファイル、未完了タスクへの依存なし）
+- **[Story]**: ユーザーストーリー（US1, US2, US3）
+- 説明には対象ファイルパスを含める
+
+## Path Conventions
+
+- ライブラリ: `lib/jp_address_complement/`, `spec/` をリポジトリルートに使用（plan.md に準拠）
+
+---
+
+## Phase 1: Setup（ベースライン確認）
+
+**Purpose**: 既存 gem のテスト・Lint が通ることを確認し、004 実装の前提を満たす
+
+- [x] T001 [P] 既存の RSpec がすべてパスすることを確認する（`bundle exec rspec`）
+- [ ] T002 [P] 既存の Rubocop がパスすることを確認する（`bundle exec rubocop`）
+- [x] T003 既存の SimpleCov カバレッジを確認し、90% 以上であることを記録する
+
+**Checkpoint**: 現状の green ベースラインが取れていること
+
+---
+
+## Phase 2: Foundational（全ストーリー共通の前提）
+
+**Purpose**: 本機能では新規 DB や共通インフラは追加しない。Phase 1 完了後、各ユーザーストーリーに進める。
+
+**Checkpoint**: Phase 1 完了後、User Story 1 から順に実装開始可能
+
+---
+
+## Phase 3: User Story 1 - 都道府県コードから都道府県名を取得する (Priority: P1) 🎯 MVP
+
+**Goal**: 都道府県コード（2桁・数値または文字列）を渡すと都道府県名を返す。該当なし・不正入力時は nil。
+
+**Independent Test**: `JpAddressComplement.prefecture_name_from_code("13")` が `"東京都"` を返すことを確認する。
+
+### Tests for User Story 1（TDD: 先にテストを書き、失敗を確認する）
+
+- [x] T004 [P] [US1] `prefecture_name_from_code` のスペックを追加する（有効コード・ゼロパッド・存在しないコード・nil・空文字。47都道府県すべてのコード⇔名称が正しく動作することを 1 件以上の代表例で検証し、必要に応じて全件ループで検証する） in `spec/jp_address_complement/prefecture_spec.rb`
+
+### Implementation for User Story 1
+
+- [x] T005 [US1] JIS X 0401 の 47 都道府県マッピング定数と `name_from_code` を実装する in `lib/jp_address_complement/prefecture.rb`
+- [x] T006 [US1] モジュールメソッド `JpAddressComplement.prefecture_name_from_code` を追加する in `lib/jp_address_complement.rb`
+
+**Checkpoint**: User Story 1 が単体で動作し、`prefecture_name_from_code("13")` で "東京都" が返る
+
+---
+
+## Phase 4: User Story 2 - 都道府県名から都道府県コードを取得する (Priority: P2)
+
+**Goal**: 都道府県の正式名称を渡すと 2 桁のコード文字列を返す。該当なし・省略表記・不正入力時は nil。
+
+**Independent Test**: `JpAddressComplement.prefecture_code_from_name("東京都")` が `"13"` を返すことを確認する。
+
+### Tests for User Story 2（TDD: 先にテストを書き、失敗を確認する）
+
+- [x] T007 [P] [US2] `prefecture_code_from_name` のスペックを追加する（正式名称・省略表記で nil・存在しない・nil・空文字。47都道府県すべて名称→コードが正しく動作することを代表例または全件で検証する） in `spec/jp_address_complement/prefecture_spec.rb`
+
+### Implementation for User Story 2
+
+- [x] T008 [US2] `code_from_name` と名称→コード用マッピングを追加する in `lib/jp_address_complement/prefecture.rb`
+- [x] T009 [US2] モジュールメソッド `JpAddressComplement.prefecture_code_from_name` を追加する in `lib/jp_address_complement.rb`
+
+**Checkpoint**: User Story 2 が単体で動作し、`prefecture_code_from_name("東京都")` で "13" が返る
+
+---
+
+## Phase 5: User Story 3 - 住所（分離フィールド）から郵便番号候補を取得する（逆引き） (Priority: P3)
+
+**Goal**: pref・city・town（任意）を分離引数で渡すと、完全一致で検索し郵便番号の配列を返す。入力不十分・該当なし時は []。
+
+**Independent Test**: `JpAddressComplement.search_postal_codes_by_address(pref: "東京都", city: "千代田区", town: "千代田")` で対応する郵便番号が含まれることを確認する。
+
+### Tests for User Story 3（TDD: 先にテストを書き、失敗を確認する）
+
+- [x] T010 [P] [US3] `find_postal_codes_by_address` のスペックを追加する（pref+city+town / pref+city のみ / 入力不十分で [] / 該当なしで []） in `spec/repositories/active_record_postal_code_repository_spec.rb`
+- [x] T011 [P] [US3] `search_postal_codes_by_address` のスペックを追加する（FakeRepository に `find_postal_codes_by_address` をスタブまたは実装して使用。正常・空・nil/空文字で [] のケースを含める） in `spec/searcher_spec.rb`
+
+### Implementation for User Story 3
+
+- [x] T012 [US3] `find_postal_codes_by_address(pref:, city:, town: nil)` をインターフェースに追加する in `lib/jp_address_complement/repositories/postal_code_repository.rb`
+- [x] T013 [US3] `find_postal_codes_by_address` を完全一致クエリで実装する（重複除く） in `lib/jp_address_complement/repositories/active_record_postal_code_repository.rb`
+- [x] T014 [US3] `search_postal_codes_by_address(pref:, city:, town: nil)` を追加し Repository を呼ぶ in `lib/jp_address_complement/searcher.rb`
+- [x] T015 [US3] モジュールメソッド `JpAddressComplement.search_postal_codes_by_address` を追加する in `lib/jp_address_complement.rb`
+
+**Checkpoint**: User Story 3 が単体で動作し、逆引きで郵便番号配列が返る
+
+---
+
+## Phase 6: Polish & Cross-Cutting Concerns
+
+**Purpose**: 複数ストーリーにまたがる仕上げ
+
+- [x] T016 [P] 新規 API 3 件（prefecture_name_from_code, prefecture_code_from_name, search_postal_codes_by_address）を CHANGELOG に追記する
+- [ ] T017 全ファイルで `bundle exec rubocop` を実行し、警告・エラーを解消する
+- [x] T018 全テストを実行し、SimpleCov でカバレッジ 90% 以上を満たすことを確認する（`bundle exec rspec`）
+- [ ] T019 [P] quickstart.md の手順で 3 API の動作を手動確認する（任意）
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+- **Phase 1 (Setup)**: 依存なし。即時開始可能。
+- **Phase 2 (Foundational)**: 本機能ではタスクなし。Phase 1 完了後に Phase 3 へ。
+- **Phase 3 (US1)**: Phase 1 完了後開始。他ストーリーに非依存。
+- **Phase 4 (US2)**: Phase 3 完了後推奨（同一 Prefecture モジュールを拡張）。独立テスト可能。
+- **Phase 5 (US3)**: Phase 1 完了後開始可能（Repository/Searcher は既存）。Phase 3/4 と並行も可。
+- **Phase 6 (Polish)**: 実装したいストーリーがすべて完了してから実施。
+
+### User Story Dependencies
+
+- **US1 (P1)**: Phase 1 完了後から開始可能。他ストーリーに非依存。
+- **US2 (P2)**: Prefecture モジュールを拡張するため、US1 完了後の方が自然。独立テスト可能。
+- **US3 (P3)**: 既存 Repository/Searcher の拡張のため、Phase 1 完了後から開始可能。US1/US2 と並行可能。
+
+### Within Each User Story
+
+- テストを先に追加し、失敗することを確認してから実装する（TDD）。
+- 実装は contracts/data-model に従う。
+
+### Parallel Opportunities
+
+- T001 と T002 は並列可能。
+- Phase 3 の T004 と、Phase 4 の T007、Phase 5 の T010・T011 はそれぞれ別ファイルのため、ストーリー単位で並列化可能。
+- Phase 6 の T016 と T019 は他と並列可能。
+
+---
+
+## Parallel Example: User Story 1
+
+```bash
+# Phase 3: まずテストを追加して RED を確認
+Task T004: spec/jp_address_complement/prefecture_spec.rb に prefecture_name_from_code のスペックを追加
+
+# 続けて実装で GREEN
+Task T005: lib/jp_address_complement/prefecture.rb に定数と name_from_code を実装
+Task T006: lib/jp_address_complement.rb に prefecture_name_from_code を追加
+```
+
+---
+
+## Implementation Strategy
+
+### MVP First（User Story 1 のみ）
+
+1. Phase 1 を完了する。
+2. Phase 3（US1）のテストを追加し、失敗を確認する。
+3. Phase 3（US1）の実装を完了する。
+4. **STOP and VALIDATE**: `prefecture_name_from_code("13")` が "東京都" を返すことを確認する。
+5. 必要ならデモ・コミットする。
+
+### Incremental Delivery
+
+1. Phase 1 → ベースライン確認。
+2. Phase 3（US1）→ コード→名称を検証してリリース候補。
+3. Phase 4（US2）→ 名称→コードを追加して検証。
+4. Phase 5（US3）→ 逆引きを追加して検証。
+5. Phase 6 → CHANGELOG・Rubocop・カバレッジで仕上げ。
+
+### Parallel Team Strategy
+
+- Phase 1 を共有で完了したあと、
+  - 担当 A: Phase 3（US1）→ Phase 4（US2）（Prefecture を順に拡張）
+  - 担当 B: Phase 5（US3）（Repository + Searcher + モジュールメソッド）
+- 各ストーリーは独立してテスト可能。
+
+---
+
+## Notes
+
+- [P] タスクは別ファイルで依存がなければ並列実行可能。
+- [USn] は spec.md のユーザーストーリーとの対応を示す。
+- 各ストーリーは単体で完了・テストできるようにする。
+- 実装前にテストの失敗を確認する（TDD）。
+- タスクまたは論理的なまとまりごとにコミットする。
+- チェックポイントでストーリー単位の動作確認を行う。