data/sql/127_analysis_runs.sql

@@ -0,0 +1,146 @@
+-- 127_analysis_runs.sql
+-- #993 (961-C2, Site Finder v2 / «GG-форсайт» ТЗ §22, EPIC 17 «Анализ-раны / история») — PR: durable analysis-run store.
+--
+-- Создаёт долговременную, версионированную, ПЕРЕ-открываемую таблицу analysis_runs —
+-- frozen-снапшот одного завершённого анализа участка (результат §22 API + прогноз/
+-- рекомендация/отчёт), плюс read-view v_analysis_runs_latest (последний ран на участок).
+-- Это фундамент: #994 строит persist-логику поверх неё, #992 — контракт; UI/чат/экспорт
+-- ПЕРЕ-открывают раны отсюда БЕЗ пересчёта (история / версионирование / re-open).
+--
+-- Что это ЗАМЕНЯЕТ:
+--   parcel.py:387 / parcels.py:1026,1092 — заглушку last_analysis_date=None
+--   (placeholder «real after B2 auth #307»). Теперь «дата последнего анализа» и «текущий
+--   анализ участка» берутся из v_analysis_runs_latest (max(created_at) на cad_num).
+--
+-- Что хранит строка (grain: ОДНА строка = ОДИН ран анализа участка):
+--   frozen-снапшот завершённого анализа — чтобы history/versioning/re-open/export
+--   работали БЕЗ повторного вычисления. result jsonb = SiteFinderReport.as_dict()
+--   (backend/app/services/forecasting/report.py, #987) ЛИБО dict результата analyze
+--   (POST /parcels/{cad_num}/analyze). schema_version = report._SCHEMA_VERSION ("1.0") —
+--   для версионированного re-open (бамп при несовместимом изменении формы as_dict()).
+--   advisory ВСЕГДА TRUE — весь форсайт-стек советующий (зеркало report._ADVISORY).
+--
+-- ПОЧЕМУ TABLE (append-mostly), а не materialized view:
+--   раны — это ИСТОРИЯ. Каждый запуск analyze добавляет НОВУЮ строку (никогда не затирает
+--   прошлую) → версионирование / re-open прежних ранов / аудит. MV (выводимый запросом)
+--   тут невозможен: result/params/segment — это снапшот вычисленного выхода, не агрегат
+--   источников. id BIGSERIAL — суррогатный PK; «последний ран на участок» — по индексу
+--   (cad_num, created_at DESC), а не по UNIQUE-ключу (намеренно НЕТ dedup: два анализа
+--   одного участка в один день — две легитимные версии, обе сохраняются).
+--
+-- created_by — БЕЗ FK (намеренно): в системе НЕТ таблицы users. Идентичность приходит
+--   из Caddy basic_auth → заголовок X-Authenticated-User → RBAC (auth/roles.yaml,
+--   backend/app/core/auth.py). Прецедент в репо — user-scoped таблицы хранят identity
+--   плоским TEXT без FK: user_weight_profiles.user_id (м.90), parcel_user_status.user_id
+--   (м.119). created_by NULLABLE TEXT: фоновый/системный ран (Celery) или header-less
+--   путь не обязан иметь идентичность — re-open не должен падать на NULL автора.
+--
+-- result/params/segment — JSONB (а не jsonb-в-text / отдельные колонки): форма отчёта
+--   §13/§22 эволюционирует (8 секций, под-сервисные as_dict()), нормализовать её в
+--   реляционные колонки преждевременно и хрупко. Денормализуем НАРУЖУ лишь то, по чему
+--   фильтруют/сортируют без JSON-разбора: district, confidence, status, advisory.
+--
+-- Deploy: auto-applied by deploy.yml через _schema_migrations tracking (ровно один раз по NN).
+--   Idempotent (acceptance #1 — должен ре-applied чисто ДВАЖДЫ без ошибки): CREATE TABLE/INDEX
+--   IF NOT EXISTS + CREATE OR REPLACE VIEW. CHECK'и объявлены ИНЛАЙН в CREATE TABLE: на уже
+--   существующей таблице CREATE TABLE IF NOT EXISTS пропускает весь statement целиком, поэтому
+--   инлайн-CHECK'и НЕ передобавляются (re-apply safe; не нужен guarded DO-блок, как в м.125,
+--   т.к. здесь НЕТ отдельно добавляемых UNIQUE/FK — всё в инлайн CREATE TABLE).
+-- Migration order: эта SQL-миграция применяется ПЕРВОЙ; persist-логика #994 / контракт #992 /
+--   UI/чат/экспорт — следом. НИКАКИХ строк здесь не вставляется (раны пишет #994 на analyze).
+-- НИКАКИХ DROP/TRUNCATE.
+
+BEGIN;
+
+-- ── 1. Таблица analysis_runs ─────────────────────────────────────────────────────
+-- PK и CHECK'и объявлены инлайн (re-apply пропускает весь CREATE TABLE на сущ. таблице).
+-- Плохие данные writer'а (#994) должны падать ГРОМКО на write через CHECK, не молча.
+CREATE TABLE IF NOT EXISTS analysis_runs (
+    id             BIGSERIAL PRIMARY KEY,
+    cad_num        TEXT NOT NULL,                 -- проанализированный участок (кадастровый номер)
+    district       TEXT,                          -- денормализовано из result.meta.district (фильтрация без JSON-разбора)
+    segment        JSONB,                         -- спецификация сегмента (class/room/price), если задан; NULL = без сегмента
+    params         JSONB NOT NULL DEFAULT '{}',   -- параметры запроса (horizon_months, profile_id, веса POI, ...)
+    result         JSONB NOT NULL,                -- снапшот SiteFinderReport.as_dict() (#987) / dict результата analyze
+    schema_version TEXT NOT NULL,                 -- report._SCHEMA_VERSION ("1.0") — для версионированного re-open
+    advisory       BOOLEAN NOT NULL DEFAULT TRUE, -- весь форсайт-стек советующий (зеркало report._ADVISORY); всегда TRUE
+    confidence     TEXT,                          -- отчётный уровень high/medium/low (денормализовано из result.confidence)
+    status         TEXT NOT NULL DEFAULT 'complete',  -- complete | partial | error
+    created_by     TEXT,                          -- идентичность X-Authenticated-User (NULLABLE; БЕЗ FK — нет таблицы users)
+    created_at     timestamptz NOT NULL DEFAULT now(),  -- момент сохранения рана (powers last_analysis_date + latest-view)
+    -- status ограничен 3 known-значениями (зеркало форсайт-стека complete|partial|error):
+    CONSTRAINT analysis_runs_status_chk
+        CHECK (status IN ('complete', 'partial', 'error')),
+    -- confidence NULLABLE; если задана — только high/medium/low (зеркало report ReportConfidenceLevel):
+    CONSTRAINT analysis_runs_confidence_chk
+        CHECK (confidence IS NULL OR confidence IN ('high', 'medium', 'low'))
+);
+
+COMMENT ON TABLE analysis_runs IS
+    'Durable версионированный store анализ-ранов Site Finder (#993, ТЗ §22, EPIC 17). '
+    'Grain: одна строка = один завершённый ран анализа участка (frozen-снапшот §22-результата '
+    '+ прогноз/рекомендация/отчёт). result jsonb = SiteFinderReport.as_dict() (#987) или dict '
+    'результата analyze; schema_version = report _SCHEMA_VERSION для версионированного re-open. '
+    'Append-mostly (история/версионирование — НЕ затираем прошлые раны, поэтому TABLE, не MV). '
+    'Заменяет заглушку last_analysis_date (parcels.py:1026,1092). created_by = X-Authenticated-User '
+    'без FK (нет таблицы users; прецедент — м.90/м.119). Последний ран на участок — v_analysis_runs_latest. '
+    'persist-логику пишет #994, контракт — #992, re-open — UI/чат/экспорт.';
+
+COMMENT ON COLUMN analysis_runs.cad_num IS 'Кадастровый номер проанализированного участка (NOT NULL; не FK — cad-номера приходят и до загрузки участка в cad_parcels).';
+COMMENT ON COLUMN analysis_runs.result IS 'Снапшот SiteFinderReport.as_dict() (#987, 8 секций §13) или dict результата POST /analyze. JSONB — форма §22-отчёта эволюционирует, не нормализуем.';
+COMMENT ON COLUMN analysis_runs.schema_version IS 'report._SCHEMA_VERSION ("1.0") на момент рана — для версионированного re-open (бамп при несовместимом изменении формы as_dict()).';
+COMMENT ON COLUMN analysis_runs.advisory IS 'Весь форсайт-стек советующий (зеркало report._ADVISORY). Всегда TRUE — ран НЕ основание для инвест-решения.';
+COMMENT ON COLUMN analysis_runs.confidence IS 'Отчётный уровень high|medium|low, денормализован из result.confidence (CHECK-ограничено; NULL = не оценено).';
+COMMENT ON COLUMN analysis_runs.status IS 'complete|partial|error (CHECK-ограничено). partial = graceful-частичный анализ (дух форсайт-стека); error = ран зафиксирован с ошибкой.';
+COMMENT ON COLUMN analysis_runs.created_by IS 'Идентичность X-Authenticated-User (Caddy basic_auth → RBAC). NULLABLE, БЕЗ FK — нет таблицы users; фоновый/системный ран автора не имеет.';
+COMMENT ON COLUMN analysis_runs.created_at IS 'Момент сохранения рана. Powers last_analysis_date (max на cad_num) + latest-view; tiebreak с id DESC.';
+
+-- ── 2. Индексы ───────────────────────────────────────────────────────────────────
+-- Primary read-path: «последний ран на участок» (powers last_analysis_date + re-open
+-- текущего анализа + история по участку). Compound (cad_num, created_at DESC) — точечный
+-- фильтр по участку + сортировка/«самый свежий» без отдельного сорта; используется
+-- DISTINCT ON во v_analysis_runs_latest.
+CREATE INDEX IF NOT EXISTS idx_analysis_runs_cad_created
+    ON analysis_runs (cad_num, created_at DESC);
+-- Глобальная лента недавних ранов (дашборд «последние анализы» / housekeeping по дате).
+CREATE INDEX IF NOT EXISTS idx_analysis_runs_created
+    ON analysis_runs (created_at DESC);
+-- Фильтр по району (денормализованный district) + свежесть — для районных списков ранов.
+-- Partial (district IS NOT NULL): region-wide/без-района раны индекс не раздувают.
+CREATE INDEX IF NOT EXISTS idx_analysis_runs_district_created
+    ON analysis_runs (district, created_at DESC) WHERE district IS NOT NULL;
+
+-- ── 3. Read-view: последний ран на участок ───────────────────────────────────────
+-- Canonical read-path для last_analysis_date + «текущий анализ участка» (UI/чат/экспорт).
+-- DISTINCT ON (cad_num) → ровно одна строка на участок — самая свежая по created_at.
+-- Tiebreak ПОЛНОСТЬЮ детерминирован: при равном created_at берём бОльший id (последний
+-- вставленный ран). DISTINCT ON требует, чтобы ведущие ORDER BY-выражения совпадали с
+-- DISTINCT-ключом (cad_num), затем — порядок отбора «последнего» (created_at DESC, id DESC).
+-- Зеркалит v_supply_layers_latest (м.125): DISTINCT ON + детерминир. tiebreak по id DESC.
+CREATE OR REPLACE VIEW v_analysis_runs_latest AS
+SELECT DISTINCT ON (cad_num)
+    id,
+    cad_num,
+    district,
+    segment,
+    params,
+    result,
+    schema_version,
+    advisory,
+    confidence,
+    status,
+    created_by,
+    created_at
+FROM analysis_runs
+ORDER BY
+    cad_num,
+    created_at DESC,
+    id DESC;
+
+COMMENT ON VIEW v_analysis_runs_latest IS
+    'Последний ран analysis_runs на участок (DISTINCT ON cad_num, max(created_at), '
+    'детерминир. tiebreak id DESC). Canonical read-path для last_analysis_date '
+    '(parcels.py:1026,1092) + «текущий анализ участка» (UI/чат/экспорт, re-open). '
+    'Пустая таблица → 0 строк.';
+
+COMMIT;