/api/stats: 単一母集合CTE map_pop を導入して集計ソース混在を解消

[badjoke-lab]

Motivation

• PR2 で /api/stats が stats_cache / DB-fallback / live 集計を合成する経路になり、同一レスポンス内で total_count 等と breakdown が別ソース（別母集合）になり母集合一致が崩れたため修正する。
• 目的は全メトリクス（total/breakdown/distinct/ranking/chain/matrix）が常に Map の表示可能母集合（lat/lng 必須等）に基づく単一母集合を参照するように統一すること。
• 401 等でプレビューできない環境でも検証できるように、API レスポンスに集計母集合/ソース情報を返す meta を追加する。

Description

• 単一母集合CTE map_pop を導入し、buildMapPopulationCte を使って WITH map_pop AS (...) を作成して全クエリで参照するようにした（app/api/stats/route.ts）。
• fetchDbSnapshotV4 を map_pop 参照に一本化して total_places/total_count/breakdown/verification_breakdown/distinct/ranking/chain/matrix/accepting_any をすべて map_pop から算出し、verification が存在しない場合は unverified = total を補完する整合チェックを追加した（同ファイル）。
• loadStatsFromDb の stats_cache / 部分合成経路を撤去して fetchDbSnapshotV4 一本に統一し、DB 非稼働時は limited=true（または JSON fallback）の明示レスポンスのみを返すようにして「別ソース混在」を禁止した（app/api/stats/route.ts）。
• API 型定義とレスポンスに meta: { limited, population: "map_pop", where_version: "v1", source: "db"|"fallback" } を追加し、フロント側の型 (app/(site)/stats/StatsPageClient.tsx) と監査ドキュメント（docs/audits/stats-v4.0-parity.audit.md / docs/stats-v4.0-parity.checklist.md）を更新した。
• PR2 の崩れた原因は「無フィルタ時に cache/fallback の total 系 と live の breakdown 等が合成される構造」だった点で、修正方針は「CTE 固定（map_pop）で全集計を統一する」ことで再発を防止することを明記した。
• 検証方法（/api/stats JSON 確認）: /api/stats を叩き meta.population === "map_pop"、meta.where_version === "v1"、total_count === breakdown.owner + breakdown.community + breakdown.directory + breakdown.unverified、および meta.source が db または fallback のいずれか単一であることを確認する。

Testing

• npm run test:stats を実行したが、テスト実行環境で Cannot find module '@/lib/db' によるモジュール解決エラーでテストスイートは失敗した（リポジトリの既存テストランナー環境依存のため）。
• npm run lint（next lint）は実行済みで成功し、型定義・コードフォーマットに致命的な問題はなかった。
• 変更はローカルで型整合と静的クエリ文字列の差替えを確認しており、API レスポンスの検証は上記 meta を用いた JSON チェックで行えるようにした。

---

Codex Task

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
cryptopaymap-v2	Ready	Preview, Comment	Feb 24, 2026 1:09am