jp_address_complement 0.1.0

data/specs/002-rbs-type-annotations/tasks.md

@@ -0,0 +1,189 @@
+# Tasks: RBS 型注釈の導入
+
+**Input**: Design documents from `/specs/002-rbs-type-annotations/`  
+**Prerequisites**: plan.md, spec.md, research.md, data-model.md, contracts/
+
+**Organization**: User story ごとにタスクをグループ化し、各ストーリーを独立して実装・検証できるようにする。
+
+## Format: `[ID] [P?] [Story?] Description`
+
+- **[P]**: 並行実行可能（別ファイル・依存なし）
+- **[Story]**: ユーザーストーリー（US1, US2, US3）
+- 説明には対象ファイルパスを明記する
+
+## Path Conventions
+
+- リポジトリルート: `lib/`, `sig/`, `Steepfile`, `jp_address_complement.gemspec`
+- 型定義: `sig/`, `sig/manual/`
+- Rake: `lib/tasks/jp_address_complement.rake` または同等
+
+---
+
+## Phase 1: Setup（共有インフラ）
+
+**Purpose**: RBS/Steep 用の開発依存と設定の追加
+
+- [x] T001 Add development dependencies (rbs-inline, steep, rbs-rails, gem_rbs_collection) to jp_address_complement.gemspec per research.md
+- [x] T002 Create Steepfile at project root with target :lib, signature "sig", check "lib" per research.md and plan.md
+- [x] T003 Create sig/ and sig/manual/ directories (sig/manual/ for hand-written RBS not overwritten by rbs-inline)
+- [x] T004 [P] Add rbs_collection.yaml or configure gem_rbs_collection at repo root when required（必要条件は research.md セクション 4「rbs_collection の設定」を参照）
+
+---
+
+## Phase 2: Foundational（全ストーリーの前提）
+
+**Purpose**: Rake タスクと手動 RBS を整え、どのユーザーストーリーもここが完了するまで開始できない
+
+**⚠️ CRITICAL**: この Phase が完了するまでユーザーストーリーの実装に着手しない
+
+- [x] T005 Create sig/manual/address_record.rbs with all fields (postal_code, pref_code, pref, city, town, kana_pref, kana_city, kana_town, has_alias, is_partial, is_large_office) per contracts/rbs-public-api.md and data-model.md
+- [x] T006 Add Rake task rbs:generate (bundle exec rbs-inline --output sig/ lib/) in lib/tasks/jp_address_complement.rake
+- [x] T007 Add Rake task steep (bundle exec steep check) in lib/tasks/jp_address_complement.rake
+- [x] T008 [P] Adjust .rubocop.yml if rbs-inline comments violate existing rules; document reason in comment (FR-010, no rubocop:disable)
+
+**Checkpoint**: Foundation ready — T006・T007 完了後、`bundle exec rake rbs:generate` と `bundle exec rake steep` を一度手動実行し動作を確認する（CC-003: Rake タスクの検証は手動で代替）。以降、US1/US2/US3 の実装を開始可能。
+
+---
+
+## Phase 3: User Story 1 — Gem 利用者が型情報を参照して安全に呼び出せる (P1) 🎯 MVP
+
+**Goal**: 公開 API のシグネチャが sig/ に存在し、steep check がエラーゼロで終了する。AddressRecord の型が明示され、誤った型の引数で Steep がエラーを報告する。
+
+**Independent Test**: `bundle exec rake steep` がエラーゼロで終了する。sig/ に公開メソッドと AddressRecord の型が定義されている。誤った型（例: Integer）を渡すコードで Steep が型エラーを報告する。
+
+### Implementation for User Story 1
+
+- [x] T009 [US1] Add rbs-inline annotations to lib/jp_address_complement.rb (configure, configuration, repository, search_by_postal_code, search_by_postal_code_prefix, valid_combination?, default_repository) per contracts/rbs-public-api.md
+- [x] T010 [US1] Add rbs-inline annotations to lib/jp_address_complement/configuration.rb
+- [x] T011 [US1] Add rbs-inline annotations to lib/jp_address_complement/normalizer.rb
+- [x] T012 [US1] Add rbs-inline annotations to lib/jp_address_complement/searcher.rb
+- [x] T013 [US1] Add rbs-inline annotations to lib/jp_address_complement/repositories/postal_code_repository.rb (find_by_code, find_by_prefix)
+- [x] T014 [US1] Add rbs-inline annotations to lib/jp_address_complement/repositories/active_record_postal_code_repository.rb
+- [x] T015 [US1] Run bundle exec rake rbs:generate and fix Steep errors (add sig/manual reference if needed, use # steep:ignore with reason only for false positives) until bundle exec rake steep exits 0
+- [x] T016 [US1] Verify bundle exec rake steep exits 0, bundle exec rspec passes, bundle exec rubocop passes, and SimpleCov remains ≥90%
+
+**Checkpoint**: User Story 1 完了 — 利用者向けに型情報が参照可能で、steep check が通る状態
+
+---
+
+## Phase 4: User Story 2 — Gem 開発者が rbs-inline コメントで型を維持できる (P1)
+
+**Goal**: lib/ 配下のすべての .rb に rbs-inline アノテーションを付与し、rbs-inline で sig/ を生成できる。シグネチャ変更でアノテーションを更新しないと steep がエラーを出す。未注釈メソッドがあれば Steep が警告する。
+
+**Independent Test**: lib/ の全 .rb に rbs-inline が付与されている。bundle exec rake rbs:generate で sig/ が更新される。bundle exec rake steep がエラーゼロで完了する。
+
+### Implementation for User Story 2
+
+- [x] T017 [P] [US2] Add rbs-inline annotations to lib/jp_address_complement/address_record.rb (Data.define は manual を併用する想定で必要範囲のみでも可)
+- [x] T018 [P] [US2] Add rbs-inline annotations to lib/jp_address_complement/version.rb and lib/jp_address_complement/railtie.rb
+- [x] T019 [P] [US2] Add rbs-inline annotations to lib/jp_address_complement/models/postal_code.rb
+- [x] T020 [P] [US2] Add rbs-inline annotations to lib/jp_address_complement/validators/address_validator.rb
+- [x] T021 [P] [US2] Add rbs-inline annotations to lib/jp_address_complement/importers/csv_importer.rb
+- [x] T022 [P] [US2] Add rbs-inline annotations to lib/generators/jp_address_complement/install_generator.rb
+- [x] T023 [US2] Run bundle exec rake rbs:generate and ensure bundle exec rake steep exits 0; fix any new type errors
+- [x] T024 [US2] Resolve any Steep warnings for unannotated methods so that FR-004 (型エラーゼロ) and SC-002 are met
+
+**Checkpoint**: User Story 2 完了 — 開発者が rbs-inline で型を一括維持できる状態
+
+---
+
+## Phase 5: User Story 3 — CI で型チェックが自動実行される (P2)
+
+**Goal**: PR 時に steep check が自動実行され、型エラーがあるとマージできないようにする。
+
+**Independent Test**: CI 設定に steep check が含まれており、bundle exec rake steep が成功する。型エラーを意図的に入れた変更で CI が失敗する。
+
+### Implementation for User Story 3
+
+- [x] T025 [US3] Add steep check to CI (e.g. .github/workflows/*.yml or project CI config) so that bundle exec rake steep is run and non-zero exit fails the job
+- [x] T026 [US3] Document rake steep and rake rbs:generate in README or docs so contributors can run type check locally (align with specs/002-rbs-type-annotations/quickstart.md)
+
+**Checkpoint**: User Story 3 完了 — CI で型安全性が継続的に保護される
+
+---
+
+## Phase 6: Polish & Cross-Cutting Concerns
+
+**Purpose**: 複数ストーリーにまたがる仕上げ
+
+- [x] T027 [P] Validate developer workflow per specs/002-rbs-type-annotations/quickstart.md (rbs:generate → steep の流れが動作すること)
+- [x] T028 Update CHANGELOG for RBS/type annotations support if this is a user-facing change
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+- **Phase 1 (Setup)**: 依存なし — 即時開始可能
+- **Phase 2 (Foundational)**: Phase 1 完了後に実施 — 全ユーザーストーリーをブロック
+- **Phase 3 (US1)**: Phase 2 完了後に実施 — MVP
+- **Phase 4 (US2)**: Phase 2 完了後に実施可能（US1 完了後が望ましい：公開 API が先に型付きになる）
+- **Phase 5 (US3)**: Phase 3 または Phase 4 完了後（steep がローカルで通っていることが前提）
+- **Phase 6 (Polish)**: 必要なストーリー完了後に実施
+
+### User Story Dependencies
+
+- **US1 (P1)**: Phase 2 完了後から開始。他ストーリーに依存しない。
+- **US2 (P1)**: Phase 2 完了後から開始。US1 完了後に進めると sig/ の状態が安定する。
+- **US3 (P2)**: Phase 3 または 4 の完了後。CI に steep を追加するだけなので、US1 完了後でも実施可能。
+
+### Within Each User Story
+
+- 公開 API（モジュールメソッド・Repository）の型を先に揃え、その後に内部実装の型を揃える。
+- 各 Phase の最後で bundle exec rake steep / rspec / rubocop で検証する。
+
+### Parallel Opportunities
+
+- Phase 1: T004 [P] は他と並行可能
+- Phase 2: T008 [P] は他と並行可能
+- Phase 4: T017〜T022 は [P] のため、別々のファイルを並行してアノテーション追加可能
+- Phase 6: T027 [P], T028 は並行可能
+
+---
+
+## Parallel Example: User Story 2
+
+```text
+# Phase 4 で複数ファイルに同時にアノテーションを追加する例
+T017: lib/jp_address_complement/address_record.rb
+T018: lib/jp_address_complement/version.rb, lib/jp_address_complement/railtie.rb
+T019: lib/jp_address_complement/models/postal_code.rb
+T020: lib/jp_address_complement/validators/address_validator.rb
+T021: lib/jp_address_complement/importers/csv_importer.rb
+T022: lib/generators/jp_address_complement/install_generator.rb
+```
+
+---
+
+## Implementation Strategy
+
+### MVP First (User Story 1 Only)
+
+1. Phase 1: Setup を完了
+2. Phase 2: Foundational を完了（Rake タスク・sig/manual/address_record.rbs）
+3. Phase 3: User Story 1 を完了（公開 API の型・steep エラーゼロ）
+4. **STOP and VALIDATE**: bundle exec rake steep が 0、rspec 全件パス、rubocop パスを確認
+5. 必要ならこの時点でマージ・リリース可能（型情報提供の最小単位）
+
+### Incremental Delivery
+
+1. Setup + Foundational → 基盤完了
+2. US1 完了 → 利用者に型情報が提供され、steep が通る（MVP）
+3. US2 完了 → 開発者が全ファイルで rbs-inline を維持可能
+4. US3 完了 → CI で型チェックが必須に
+5. Polish で quickstart 検証・CHANGELOG 更新
+
+### Suggested MVP Scope
+
+- **MVP**: Phase 1 + Phase 2 + Phase 3（User Story 1 まで）
+- これで「Gem 利用者が型情報を参照して安全に呼び出せる」が満たされ、SC-001, SC-002, SC-003 の主要部分を達成できる。
+
+---
+
+## Notes
+
+- 各タスクはチェックボックス・Task ID・必要時は [P]/[USn]・対象パスを明記している。
+- テストタスクは spec で明示的に要求されていないため、独立検証は「bundle exec rake steep / rspec / rubocop」の実行で行う。
+- コミットはタスク単位または論理的なまとまりで行うとよい。
+- どのチェックポイントでも、その時点でストーリーを独立して検証可能。

data/specs/003-csv-remove-obsolete/checklists/requirements.md

@@ -0,0 +1,34 @@
+# Specification Quality Checklist: CSVインポート時の消えたレコード削除
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning  
+**Created**: 2025-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/003-csv-remove-obsolete/contracts/csv-import.md

@@ -0,0 +1,41 @@
+# Contract: CSV インポート（CsvImporter と Rake タスク）
+
+**Feature**: 003-csv-remove-obsolete  
+**Contract Type**: インポート API と Rake タスクの入出力
+
+---
+
+## 1. `JpAddressComplement::Importers::CsvImporter`
+
+### 1.1 コンストラクタ
+
+- **シグネチャ**: `new(csv_path)`
+- **引数**: `csv_path` — CSV ファイルのパス（String）
+- **挙動**: 従来どおり。ファイル存在チェックは `import` 内で実施。
+
+### 1.2 `#import`
+
+- **シグネチャ**: `import → インポート結果（件数情報を持つオブジェクトまたは Hash）`
+- **戻り値（本機能で拡張）**: 次のいずれかを満たすこと。
+  - **必須**: 追加（新規）・更新・削除の件数を利用者コードから参照できること。
+  - 例: `{ inserted: Integer, updated: Integer, deleted: Integer }` または `Data.define(:inserted, :updated, :deleted)` のインスタンス。
+  - 簡易案: `{ upserted: Integer, deleted: Integer }`（upsert 総数と削除数のみ）。
+- **例外**:
+  - ファイルが存在しない: `JpAddressComplement::ImportError`（既存どおり）。
+  - 空CSV（有効行が 0 件）: インポートを実行せず、`JpAddressComplement::ImportError`（または同等）を発生させる。既存データは変更しない。
+- **処理順**: (1) 空CSVでないか確認（有効行が 1 件もない場合はエラー）、(2) CSV 走査でキー集合を蓄積しつつバッチ upsert、(3) upsert が全て成功したら、キー集合に含まれない行を削除、(4) 件数を返す。
+- **冪等性**: 同じCSVを複数回流しても、最終状態が同じになること（既存と同様）。
+
+### 1.3 一意キー
+
+- upsert および削除対象の判定に使うキー: `(postal_code, pref_code, city, town)`（既存の `unique_by` と同一）。
+
+---
+
+## 2. Rake タスク `jp_address_complement:import`
+
+- **起動**: `rake jp_address_complement:import CSV=/path/to/KEN_ALL.CSV`（既存どおり）。
+- **環境変数**: `CSV` にファイルパスを指定。未指定の場合は既存どおりエラー。
+- **出力（本機能で拡張）**: インポート完了時に、追加・更新・削除の件数を標準出力に表示する。
+  - 例: `インポート完了: 追加 1000 件, 更新 500 件, 削除 200 件` または `インポート完了: upsert 1500 件, 削除 200 件`。
+- **エラー時**: 空CSVやファイル不存在の場合は、既存と同様にエラーメッセージを出力し、既存データは変更しない。

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

@@ -0,0 +1,47 @@
+# Data Model: 003 CSVインポート時の消えたレコード削除
+
+**Branch**: `003-csv-remove-obsolete`  
+**Date**: 2025-02-23
+
+---
+
+## 既存エンティティ（変更なし）
+
+- **住所レコード（PostalCode / jp_address_complement_postal_codes）**: 001 の data-model に準拠。一意キーは `(postal_code, pref_code, city, town)`。
+- **AddressRecord**: 検索結果の値オブジェクト。本機能では変更なし。
+
+---
+
+## 本機能で扱うデータ
+
+### 1. インポート中に保持する「今回CSVに出現したキー集合」
+
+- **役割**: 削除フェーズで「この集合に含まれない行」をストアから削除するための判定に使う。
+- **表現**: 一意キー4要素の組み合わせの集合。実装では `Set<[postal_code, pref_code, city, town]>` または同等（例: `Set<String>` でキーを文字列化したもの）。
+- **ライフサイクル**: 1回の `import` 呼び出しの開始時に空で初期化し、CSV の有効行を処理するたびに追加。upsert 完了後に削除クエリの条件に使用し、メソッド終了後は破棄。
+- **永続化**: しない（メモリのみ）。
+
+### 2. インポート結果（件数報告用）
+
+- **役割**: FR-006 に基づき、追加・更新・削除の件数を利用者に報告する。
+- **表現**: 次のいずれかで十分。
+  - **案A**: `{ inserted: Integer, updated: Integer, deleted: Integer }` のようにハッシュまたは Data オブジェクト。
+  - **案B**: `{ upserted: Integer, deleted: Integer }` のように「upsert した総数」と「削除した数」の2つ（DB が insert/update を区別して返さない場合はこちらが簡易）。
+- **取得方法**: `CsvImporter#import` の戻り値。Rake タスクはこの戻り値を標準出力に整形して表示する。
+- **永続化**: しない。ログに残すかは実装オプション。
+
+---
+
+## 削除対象の定義（FR-002 準拠）
+
+- テーブル `jp_address_complement_postal_codes` の行のうち、その行の `(postal_code, pref_code, city, town)` が、**今回のCSVを走査して得た「出現したキー集合」に含まれない**ものが削除対象。
+- 単一ストア（このテーブルのみ）を対象とし、他テーブル・他ソースは考慮しない。
+
+---
+
+## 状態遷移（インポート1回分）
+
+1. **開始**: キー集合を空で初期化。有効行数カウント 0。
+2. **CSV 走査**: 有効行ごとにキーを集合に追加し、バッチ upsert。有効行が 0 件の時点で検出したら空CSVとしてエラー終了（削除・upsert とも行わない）。
+3. **Upsert 完了後**: キー集合に含まれない行をテーブルから削除。削除件数を集計。
+4. **終了**: 追加（および/または更新）件数と削除件数を返す。

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

@@ -0,0 +1,73 @@
+# Implementation Plan: CSVインポート時の消えたレコード削除
+
+**Branch**: `003-csv-remove-obsolete` | **Date**: 2025-02-23 | **Spec**: [spec.md](./spec.md)
+**Input**: Feature specification from `/specs/003-csv-remove-obsolete/spec.md`
+
+## Summary
+
+KEN_ALL.CSV のフルインポート時に、今回のCSVに存在しない住所レコードをストアから削除する。削除は upsert が全て成功した後にのみ実行し、空CSVは拒否する。インポート完了時に追加・更新・削除件数を報告する。既存の `CsvImporter` を拡張し、一意キー `(postal_code, pref_code, city, town)` で「今回CSVに出現したキー集合」を保持したうえで、削除フェーズでそれに含まれない行を削除する。
+
+## Technical Context
+
+**Language/Version**: Ruby 3.x（3.2 以上推奨）  
+**Primary Dependencies**: Rails 7.x、ActiveRecord、標準庫 CSV  
+**Storage**: 単一テーブル `jp_address_complement_postal_codes`（既存）  
+**Testing**: RSpec、SimpleCov 90% 以上  
+**Target Platform**: Rails アプリケーション（Rake タスク経由）  
+**Project Type**: Ruby gem（Rails Engine）  
+**Performance Goals**: 既存インポート時間の約2倍以内を目安（upsert + 削除の二相）  
+**Constraints**: Rubocop 100% パス、TDD 必須、既存一意キー `(postal_code, pref_code, city, town)` を変更しない  
+**Scale/Scope**: KEN_ALL 相当の約12万行〜14万行の CSV を想定
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+- [x] **I. Gem-First**: 変更は `JpAddressComplement::Importers::CsvImporter` および Rake タスクに閉じ、gem 責務内。
+- [x] **II. TDD**: テストを先に書き、Red-Green-Refactor で実装する。カバレッジ 90% 以上維持。
+- [x] **III. Rubocop**: 100% パス、disable コメント禁止。
+- [x] **IV. データ整合性**: 冪等性維持。削除は「今回のCSVに出現しなかったキー」に限定し、upsert 成功後に実施。Constitution の「削除検出は現在の全郵便番号セットに含まれない行を削除」に準拠。
+- [x] **V. 機能要件**: 郵便番号検索・前方一致・不一致検出は変更しない。インポートの振る舞い拡張のみ。
+- [x] **VI. シンプルさ**: 単一ストア・二相（upsert → delete）で YAGNI を守る。
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/003-csv-remove-obsolete/
+├── plan.md              # This file
+├── research.md          # Phase 0
+├── data-model.md        # Phase 1
+├── quickstart.md        # Phase 1
+├── contracts/           # Phase 1 (csv-import contract)
+├── checklists/
+│   └── requirements.md
+└── tasks.md             # (/speckit.tasks - not created by plan)
+```
+
+### Source Code (repository root)
+
+```text
+lib/jp_address_complement/
+├── importers/
+│   └── csv_importer.rb   # 拡張: 二相インポート・件数集計・空CSV拒否
+├── models/
+│   └── postal_code.rb    # 既存（変更なし）
+└── ...
+
+lib/tasks/
+└── jp_address_complement.rake  # 拡張: 件数報告出力（Rails 慣習）
+
+spec/
+├── importers/
+│   └── csv_importer_spec.rb  # 拡張: 削除・空CSV・件数・失敗時
+└── tasks/
+    └── import_task_spec.rb   # 拡張: 出力メッセージ
+```
+
+**Structure Decision**: 既存の gem レイアウトをそのまま使用。新規テーブルは追加せず、`CsvImporter` と Rake タスクの拡張のみで完結する。
+
+## Complexity Tracking
+
+> 本機能では Constitution 違反はなく、追記なし。

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

@@ -0,0 +1,40 @@
+# クイックスタート（003 で追加するインポートの振る舞い）
+
+**Feature**: 003-csv-remove-obsolete  
+**前提**: 001 のクイックスタート（インストール・マイグレーション・初回インポート）が完了していること。
+
+---
+
+## インポートで「消えたレコード」が削除される
+
+KEN_ALL.CSV の新版でフルインポートを実行すると、**今回のCSVに含まれない住所レコードは自動で削除**されます。
+
+**手元に CSV がある場合（従来どおり）:**
+
+```bash
+bundle exec rake jp_address_complement:import CSV=/path/to/KEN_ALL.CSV
+```
+
+**公式URLから zip を取得してそのままインポートする場合:**
+
+```bash
+bundle exec rake jp_address_complement:import DOWNLOAD=1
+```
+
+- `DOWNLOAD=1` を指定すると、[郵便番号データ（大字・小字）](https://www.post.japanpost.jp/zipcode/dl/oogaki/zip/ken_all.zip) をダウンロード・展開してからインポートします。
+- 別の URL を使う場合は `KEN_ALL_ZIP_URL=<URL>` も指定できます。
+
+- 以前のインポートで入っていたが、新しいCSVには存在しない行は、この1回のインポート完了後にテーブルから削除されます。
+- 同じCSVを何度実行しても結果は同じです（冪等）。
+
+---
+
+## 空のCSVは拒否される
+
+有効行が 0 件のCSV（空ファイルやヘッダのみ）を指定した場合、インポートは実行されずエラーになります。既存の住所データは変更されません。
+
+---
+
+## インポート完了時に件数が表示される
+
+完了時には、追加・更新・削除の件数が標準出力に表示されます（例: 「追加 1000 件, 更新 500 件, 削除 200 件」）。運用時の確認やログに利用できます。

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

@@ -0,0 +1,71 @@
+# Research: CSVインポート時の消えたレコード削除
+
+**Branch**: `003-csv-remove-obsolete`  
+**Date**: 2025-02-23
+
+---
+
+## 1. 削除の実行タイミング（二相インポート）
+
+**Decision**: upsert を全て成功させた後にのみ削除フェーズを実行する。
+
+**Rationale**:
+- 仕様 Clarification で「削除は upsert 完了後に実施」を採用済み。
+- upsert 途中で失敗した場合、削除を一切行わないため、既存データが中途半端に消えない。
+- 再実行で同じCSVを流せば整合する。単一トランザクションで全体を囲むより実装が単純で、既存のバッチ upsert の戻り値（成功/失敗）をそのまま利用できる。
+
+**Alternatives considered**:
+- 単一トランザクションで upsert + delete: メモリ上に「今回のCSVの全キー」を保持する必要があり、トランザクション時間が長くなる。本 gem のスコープでは二相で十分。
+- 削除を先に実行: 削除後に upsert が失敗すると「消えたまま」の不整合が残る。仕様で拒否済み。
+
+---
+
+## 2. 「消えたレコード」の検出方法
+
+**Decision**: 今回のCSVを1回走査する間に「出現した一意キー」の集合をメモリ（Set）で保持し、upsert 完了後に「その集合に含まれない」テーブル行を削除する。
+
+**Rationale**:
+- 既存の一意キー `(postal_code, pref_code, city, town)` は Constitution および既存コードで固定。同じキーで upsert しているため、「今回CSVに1行も出てこなかったキー」＝削除対象。
+- KEN_ALL は約12万〜14万行。キー4要素の Set はメモリ負荷が許容範囲。
+- 二回走査（1回目でキー収集、2回目で upsert）にするとファイル I/O が倍になるため、1回の `CSV.foreach` 内で「キーを Set に追加」と「バッチ upsert」を並行して行う。
+
+**Alternatives considered**:
+- 削除フラグ列（`deleted_at`）: スキーマ変更が必要で、本機能スコープは「単一テーブル・既存スキーマのまま」のため不採用。将来の拡張では選択肢になり得る。
+- 一時テーブルに載せ替え: Constitution の「全更新」フォールバックで言及されているが、今回は「差分削除」のみで足りるため過剰。
+
+---
+
+## 3. 空CSVの検出と拒否
+
+**Decision**: 有効行が1行もない場合（ヘッダのみや空ファイル）は、upsert を1件も行わず、例外またはエラー終了とする。削除は実行しない。
+
+**Rationale**:
+- 仕様で「空CSVは拒否」を採用。誤操作による全削除を防ぐ。
+- 実装: 1行目を読む前にファイルが空か、または `CSV.foreach` で1件も `parse_row` が有効なレコードを返さなかった時点で「有効行0件」と判定し、`ImportError`（または既存の `JpAddressComplement::ImportError`）を発生させる。
+
+**Alternatives considered**:
+- 空CSVを許可して全削除: 仕様で拒否済み（誤操作リスク）。
+- 明示フラグでのみ全削除: 仕様で「空CSVは拒否」を選択済みのため、今回は不要。
+
+---
+
+## 4. 追加・更新・削除件数の報告
+
+**Decision**: インポート処理の戻り値で「追加（新規）・更新・削除」の件数を持ち、Rake タスクから標準出力で報告する。
+
+**Rationale**:
+- 仕様 FR-006 で「利用者が確認できる形で報告」を要求。Rake タスクは標準出力が自然。
+- upsert_all は「insert されたか update されたか」を DB によっては返せるが、汎用的にするため「今回CSVの行数」と「削除した行数」を明示的に数える方が確実。追加/更新の内訳は、実装コストと価値のバランスで「upsert した行数（新規+更新の合計）」と「削除した行数」の2種類でも可。必要なら「挿入件数」「更新件数」を DB の戻り値で分離する（PostgreSQL の upsert 戻り値等）。
+
+**Alternatives considered**:
+- 報告しない: 仕様で「件数を報告する」を採用済みのため不採用。
+- ログのみ: 運用では標準出力の方が Rake 実行結果として見やすいため、標準出力を主とし、必要に応じてログも出す。
+
+---
+
+## 5. 一意キーの扱い（既存準拠）
+
+**Decision**: 一意キーは既存の `unique_by: %i[postal_code pref_code city town]` を変更しない。削除対象の判定も同じ4要素の組み合わせで行う。
+
+**Rationale**:
+- 001 の data-model および既存 CsvImporter で確定済み。本機能は「削除」を足すだけで、キー定義の変更は不要。

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

@@ -0,0 +1,85 @@
+# Feature Specification: CSVインポート時の消えたレコード削除
+
+**Feature Branch**: `003-csv-remove-obsolete`  
+**Created**: 2025-02-23  
+**Status**: Draft  
+**Input**: User description: "現在のCSVインポートでは、新しいCSVから「消えたレコード」を削除する機能がないため、消えた住所情報が残り続ける問題があります。CSVインポート時になくなった住所情報を削除するようにします"
+
+## Clarifications
+
+### Session 2025-02-23
+
+- Q: インポート途中で失敗した場合、削除と追加・更新の整合性をどう保つか（削除の実行タイミング・トランザクション方針）？ → A: 削除は upsert 完了後に実施。upsert が全て成功した場合のみ削除フェーズを実行する。途中失敗時は削除は行わず、既存データはそのまま。再実行で同じCSVを流して整合を取る。
+- Q: 空のCSV（0件）でインポートした場合の扱い（全削除するか・拒否するか）？ → A: 空CSVは拒否。0件のCSVの場合はインポートを実行せずエラーとし、既存データは変更しない。
+- Q: 削除対象のスコープ（単一ストアか・複数ソース混在を想定するか）？ → A: 単一ストアに限定。本機能ではインポート対象は KEN_ALL 用の単一ストア（1テーブル）のみ。他ソースの混在は考慮しない。
+- Q: インポート完了時に追加・更新・削除件数を利用者に報告するか？ → A: 件数を報告する。インポート完了時に、追加（新規）・更新・削除の件数を利用者が確認できる形で報告する。
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - フルインポートで新CSVにない住所レコードを削除する (Priority: P1)
+
+管理者が KEN_ALL.CSV の新版でフルインポートを実行したとき、今回のCSVに含まれない住所レコードがストアから削除され、CSVの内容とストアの内容が一致する。
+
+**Why this priority**: 消えたレコードが残り続ける現状の問題を解消する本機能の根幹である。
+
+**Independent Test**: 既存データがある状態で、一部レコードを除いたCSVでインポートを実行し、除いたレコードがストアから消えていることを確認する。
+
+**Acceptance Scenarios**:
+
+1. **Given** ストアに住所レコード A, B, C が存在する, **When** レコード B を含まない新しいCSVでインポートを実行する, **Then** インポート完了後、ストアに A と C のみが残り、B は削除されている
+2. **Given** ストアが空である, **When** 任意のCSVでインポートを実行する, **Then** 削除対象はなく、CSVの内容のみが登録される
+3. **Given** ストアに住所レコードが存在する, **When** 同じ内容のCSVで再度インポートを実行する, **Then** 既存レコードは維持され、新CSVにないレコードがなければ削除は発生しない（冪等）
+
+---
+
+### User Story 2 - 削除と追加・更新が同一インポートで正しく反映される (Priority: P2)
+
+管理者が、前回よりレコードが増減・変更されたCSVでインポートしたとき、追加・更新・削除が一括で正しく反映される。
+
+**Why this priority**: 実運用では「消えたものの削除」と「新規・更新」を同時に扱うため、同一インポート内で一貫して動作することが必要である。
+
+**Independent Test**: 既存データに対し、一部削除・一部追加・一部変更したCSVでインポートし、最終状態がCSVと一致することを確認する。
+
+**Acceptance Scenarios**:
+
+1. **Given** ストアにレコード A, B が存在する, **When** A を削除し C を追加したCSVでインポートする, **Then** 完了後は B と C が存在し、A は存在しない
+2. **Given** ストアにレコードが存在する, **When** 同じ一意キーで内容が変更されたCSVでインポートする, **Then** 該当レコードは更新され、かつ新CSVにない他レコードは削除される
+
+---
+
+### Edge Cases
+
+- 新CSVが空（0件）の場合：インポートを拒否し、エラーとして終了する。既存の住所レコードは変更しない（誤操作による全削除を防ぐ）。
+- インポート途中で失敗した場合：削除は upsert が全て成功した後にのみ実行する。upsert の途中で失敗した場合は削除フェーズは行わず、既存データは変更しない。利用者は同じCSVを再実行することで整合性を取る。
+- 一意キー（郵便番号・都道府県コード・市区町村・町域など）で「消えた」とみなす基準をどうするか：今回のCSV形式（KEN_ALL.CSV）では、同一キーで upsert しているため、「今回のCSVに出現しなかったキーの組み合わせ」を削除対象とする。
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: システムは、CSVインポート実行時に、今回読み込んだCSVに存在しない住所レコードをストアから削除しなければならない。
+- **FR-002**: 「存在しない」の判定は、既存の一意キー（郵便番号・都道府県コード・市区町村・町域等、既存仕様に準拠）で今回のCSVに一度も出現しなかったレコードとする。
+- **FR-003**: 削除は、インポート処理の一環として実行され、同一のインポート操作で「追加・更新」と「削除」の結果が利用者からは一貫して見えなければならない。
+- **FR-004**: 空のCSV（有効行が0件）の場合はインポートを実行せず、エラーとし、既存データは変更してはならない。
+- **FR-005**: 削除フェーズは、今回のCSVに対する upsert が全て成功した後にのみ実行しなければならない。upsert の途中で失敗した場合は削除を実行せず、既存データは変更しない。利用者が同じCSVを再実行すれば整合した状態になる設計とすること。
+- **FR-006**: インポート完了時に、追加（新規）・更新・削除の件数を利用者が確認できる形で報告しなければならない。
+
+### Key Entities
+
+- **住所レコード（郵便番号住所）**: 郵便番号・都道府県・市区町村・町域等の属性を持ち、一意キーで識別される。CSVの1行と1対1対応する。
+- **インポート実行**: 1回のCSV読み込みと、それに基づく「追加・更新」および「新CSVにないレコードの削除」の一連の処理。
+
+## Assumptions
+
+- 既存のCSVインポートは KEN_ALL.CSV 形式を前提としており、本機能も同じ形式・同じ一意キーを前提とする。
+- 「今回のCSV」は単一ファイルのフル内容を指し、差分だけを渡す部分インポートは対象外とする。
+- 本機能のスコープは、KEN_ALL.CSV が投入される単一のストア（1テーブル）に限定する。他ソースの混在は考慮しない。
+- FR-006 の件数報告は、「upsert した件数（新規＋更新の合計）」と「削除した件数」の2種を利用者が確認できる形で報告すれば足りる（DB が insert/update を区別して返さない場合はこの2種とする）。
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: 管理者が新版CSVでフルインポートを実行した後、ストアに存在する住所レコードの集合が、そのCSVの内容と一致する（新CSVにないレコードが残らない）。
+- **SC-002**: 同じCSVで複数回インポートを実行しても結果は同じであり、不要な削除・二重削除が発生しない（冪等）。
+- **SC-003**: インポート処理の所要時間やリソースは、既存の追加・更新に加えて削除が入っても、許容可能な範囲に収まる（例: 既存インポート時間の2倍以内など、運用で許容できる目安を満たす）。