parent
420cda2831
commit
33ecbda689
1 changed files with 177 additions and 0 deletions
177
data/sql/125_supply_layers.sql
Normal file
177
data/sql/125_supply_layers.sql
Normal file
|
|
@ -0,0 +1,177 @@
|
|||
-- 125_supply_layers.sql
|
||||
-- #950 (Site Finder v2 / 3-layer склад предложения, EPIC 6, «GG-форсайт») — PR B: durable supply store.
|
||||
--
|
||||
-- Создаёт долговременную таблицу supply_layers — единый склад для 3 слоёв будущего/скрытого
|
||||
-- предложения по districts (и опционально per-ЖК), плюс read-view v_supply_layers_latest
|
||||
-- (свежий снапшот на логический ключ). Это фундамент future-supply-pressure (#950 Step 6).
|
||||
--
|
||||
-- layer=1 (open) — открытое предложение в текущей продаже (Objective / выставлено сейчас).
|
||||
-- layer=2 (hidden) — скрытый запас застройщика: flat_count − free_flats по ПД (#950 PR A / м.124).
|
||||
-- layer=3 (future) — будущее предложение, ещё НЕ на рынке: граддок-stubs (#956, позже),
|
||||
-- multiphase-проекты ДОМ.РФ, ручные insider-строки.
|
||||
--
|
||||
-- Почему TABLE, а не materialized view:
|
||||
-- Layer1/Layer2 ПЕРЕсчитываются worker'ом (#950 Step 5) из источников и UPSERT-ятся сюда.
|
||||
-- НО Layer3 держит строки, КОТОРЫЕ НЕЛЬЗЯ вывести запросом — граддок-stubs (#956) и ручной
|
||||
-- insider-ввод. MV каждый refresh затёр бы их. Поэтому это реальная таблица: worker UPSERT-ит
|
||||
-- свои layer1/2 строки, layer3 живёт независимо (вставляется отдельно, переживает пересчёт).
|
||||
-- Future-supply-pressure индекс считается НА ЛЕТУ в #950 Step 6 (future_supply.py) — здесь НЕ хранится.
|
||||
--
|
||||
-- Зерно (grain): primary — district_name; optional — complex_id (per-ЖК, в основном L3-stubs /
|
||||
-- reviewed L2). NO per-flat строк (это склад агрегатов, не сделок). district_name/complex_id/
|
||||
-- obj_class — NULLABLE (region-wide / класс-agnostic строки допустимы).
|
||||
--
|
||||
-- Зависимости:
|
||||
-- • complexes(id) (м.73, BIGSERIAL PK) — FK complex_id → complexes(id) ON DELETE SET NULL
|
||||
-- (complex_id — опциональное обогащение; удаление ЖК НЕ должно удалять supply-строку).
|
||||
-- • PostgreSQL 16 (postgis/postgis:16-3.4, docker-compose.prod.yml) — нужен для
|
||||
-- UNIQUE NULLS NOT DISTINCT (PG15+). Прецедент в репо: м.110 (uq_infra_dedupe).
|
||||
--
|
||||
-- Логический UPSERT-ключ (что таргетит ON CONFLICT в worker'е #950 Step 5):
|
||||
-- (layer, district_name, complex_id, obj_class, source, snapshot_date)
|
||||
-- КРИТИЧНО: district_name/complex_id/obj_class NULLABLE. По умолчанию Postgres в UNIQUE
|
||||
-- считает NULL DISTINCT → (а) дубли region-wide строк (district_name IS NULL) проскочили бы,
|
||||
-- (б) ON CONFLICT НЕ матчил бы их (NULL <> NULL). Поэтому ключ объявлен
|
||||
-- UNIQUE NULLS NOT DISTINCT — NULL'ы сравниваются как РАВНЫЕ, дубли ловятся, ON CONFLICT
|
||||
-- по этому column-list срабатывает. Constraint именованный (uq_supply_layers_logical) —
|
||||
-- ON CONFLICT (<column list>) таргетит его по списку колонок (имя для diagnostics/idempotency).
|
||||
--
|
||||
-- Deploy: auto-applied by deploy.yml через _schema_migrations tracking (ровно один раз по NN).
|
||||
-- Idempotent (acceptance #1 — должен ре-applied чисто ДВАЖДЫ без ошибки): CREATE TABLE/INDEX
|
||||
-- IF NOT EXISTS + CREATE OR REPLACE VIEW. Ловушка идемпотентности — повторное добавление
|
||||
-- UNIQUE и FK (их нельзя добавить дважды): обёрнуты в guarded DO-блоки с проверкой
|
||||
-- pg_constraint (прецедент — м.40). Re-apply конвергентен даже если таблица была создана
|
||||
-- руками без этих constraint'ов.
|
||||
-- Migration order: эта SQL-миграция применяется ПЕРВОЙ; worker/reader (#950 Step 5/6) — следом.
|
||||
-- НИКАКИХ строк здесь не вставляется (layer3-stubs приходят из #956; layer1/2 — из worker'а).
|
||||
|
||||
BEGIN;
|
||||
|
||||
-- ── 1. Таблица supply_layers ───────────────────────────────────────────────────
|
||||
-- PK и CHECK-и объявлены инлайн: CREATE TABLE IF NOT EXISTS на существующей таблице
|
||||
-- пропускает весь statement целиком, поэтому инлайн-CHECK'и НЕ передобавляются (re-apply safe).
|
||||
-- UNIQUE и FK вынесены в DO-блоки ниже (их нельзя добавить дважды → guard по pg_constraint).
|
||||
CREATE TABLE IF NOT EXISTS supply_layers (
|
||||
id BIGSERIAL PRIMARY KEY,
|
||||
layer SMALLINT NOT NULL, -- 1=open | 2=hidden | 3=future
|
||||
district_name TEXT, -- primary grain (NULLABLE: region-wide строки)
|
||||
complex_id BIGINT, -- optional per-ЖК grain (L3-stubs / reviewed L2); FK complexes(id)
|
||||
obj_class TEXT, -- эконом..премиум (NULLABLE: класс-agnostic)
|
||||
units_estimate INTEGER, -- оценка кол-ва квартир (NULLABLE)
|
||||
area_estimate NUMERIC, -- оценка площади, м² (NULLABLE)
|
||||
expected_online_date DATE, -- когда предложение выйдет на рынок (L3); NULL для L1/L2
|
||||
source TEXT NOT NULL, -- 'objective'|'domrf_declared'|'domrf_multiphase'|'graddoc_stub'|'insider_manual'
|
||||
confidence TEXT NOT NULL, -- 'high'|'medium'|'low' (зеркало market_metrics.py)
|
||||
method TEXT, -- короткая provenance-строка (как считалось/откуда)
|
||||
snapshot_date DATE NOT NULL DEFAULT CURRENT_DATE, -- дата пересчёта/ввода; часть логического ключа
|
||||
computed_at timestamptz NOT NULL DEFAULT now(), -- момент записи строки (tiebreak для latest-view)
|
||||
-- CHECK'и: плохие данные worker'а должны падать ГРОМКО на write.
|
||||
CONSTRAINT supply_layers_layer_chk
|
||||
CHECK (layer IN (1, 2, 3)),
|
||||
CONSTRAINT supply_layers_confidence_chk
|
||||
CHECK (confidence IN ('high', 'medium', 'low')),
|
||||
-- source ограничен 5 known-значениями — новый источник = осознанное расширение CHECK
|
||||
-- отдельной миграцией (не молчаливый free-text). Если появится потребность в произвольном
|
||||
-- источнике — этот CHECK снять отдельной ревизией с комментарием.
|
||||
CONSTRAINT supply_layers_source_chk
|
||||
CHECK (source IN ('objective', 'domrf_declared', 'domrf_multiphase',
|
||||
'graddoc_stub', 'insider_manual'))
|
||||
);
|
||||
|
||||
COMMENT ON TABLE supply_layers IS
|
||||
'Durable 3-layer склад предложения (#950 EPIC 6, GG-форсайт). layer 1=open / 2=hidden / '
|
||||
'3=future. Grain: district_name (+ optional complex_id per-ЖК). NO per-flat строк. '
|
||||
'Layer1/2 UPSERT-ятся worker''ом (#950 Step5) по uq_supply_layers_logical; layer3 — '
|
||||
'граддок-stubs (#956) + ручной insider-ввод (поэтому TABLE, не MV — refresh не должен '
|
||||
'затирать невыводимые строки). Future-supply-pressure считается на лету (#950 Step6), тут НЕ '
|
||||
'хранится. Читать свежий снапшот через v_supply_layers_latest.';
|
||||
|
||||
COMMENT ON COLUMN supply_layers.layer IS '1=open (в продаже) | 2=hidden (запас ПД) | 3=future (ещё не на рынке)';
|
||||
COMMENT ON COLUMN supply_layers.expected_online_date IS 'Когда предложение выйдет на рынок (L3-прогноз); NULL для L1/L2 (уже/скрыто на рынке)';
|
||||
COMMENT ON COLUMN supply_layers.source IS 'objective|domrf_declared|domrf_multiphase|graddoc_stub|insider_manual (CHECK-ограничено)';
|
||||
COMMENT ON COLUMN supply_layers.confidence IS 'high|medium|low — зеркало market_metrics.py (CHECK-ограничено)';
|
||||
COMMENT ON COLUMN supply_layers.snapshot_date IS 'Дата пересчёта/ввода; часть логического UPSERT-ключа. Latest-view берёт max(snapshot_date) на ключ.';
|
||||
|
||||
-- ── 2. Логический UNIQUE-ключ (NULLS NOT DISTINCT, PG15+) ──────────────────────
|
||||
-- Цель ON CONFLICT для worker'а (#950 Step5). NULLS NOT DISTINCT — чтобы region-wide
|
||||
-- строки (district_name/complex_id/obj_class IS NULL) НЕ дублировались и ON CONFLICT их матчил
|
||||
-- (иначе NULL <> NULL → дубли + промах UPSERT). Guard по pg_constraint → idempotent re-apply
|
||||
-- (constraint нельзя добавить дважды). Прецедент паттерна: м.110 (uq_infra_dedupe), м.40 (FK guard).
|
||||
DO $$
|
||||
BEGIN
|
||||
IF NOT EXISTS (
|
||||
SELECT 1 FROM pg_constraint WHERE conname = 'uq_supply_layers_logical'
|
||||
) THEN
|
||||
ALTER TABLE supply_layers
|
||||
ADD CONSTRAINT uq_supply_layers_logical
|
||||
UNIQUE NULLS NOT DISTINCT
|
||||
(layer, district_name, complex_id, obj_class, source, snapshot_date);
|
||||
END IF;
|
||||
END
|
||||
$$;
|
||||
|
||||
-- ── 3. FK complex_id → complexes(id) (ON DELETE SET NULL) ──────────────────────
|
||||
-- complex_id — опциональное per-ЖК обогащение; удаление ЖК НЕ должно удалять supply-строку,
|
||||
-- поэтому SET NULL (не CASCADE). Guard по pg_constraint → re-apply не падает «constraint already
|
||||
-- exists». DELETE CASCADE здесь был бы неверен: потеряли бы агрегат предложения из-за чистки ЖК.
|
||||
DO $$
|
||||
BEGIN
|
||||
IF NOT EXISTS (
|
||||
SELECT 1 FROM pg_constraint WHERE conname = 'fk_supply_layers_complex'
|
||||
) THEN
|
||||
ALTER TABLE supply_layers
|
||||
ADD CONSTRAINT fk_supply_layers_complex
|
||||
FOREIGN KEY (complex_id) REFERENCES complexes(id) ON DELETE SET NULL;
|
||||
END IF;
|
||||
END
|
||||
$$;
|
||||
|
||||
-- ── 4. Индексы ─────────────────────────────────────────────────────────────────
|
||||
-- Primary read-path: фильтр по слою + району + дате (consumer'ы Step6 / UI / forecast).
|
||||
CREATE INDEX IF NOT EXISTS idx_supply_layers_layer_district_date
|
||||
ON supply_layers (layer, district_name, snapshot_date DESC);
|
||||
-- FK-lookups + per-ЖК выборки (и ускоряет ON DELETE SET NULL).
|
||||
CREATE INDEX IF NOT EXISTS idx_supply_layers_complex
|
||||
ON supply_layers (complex_id) WHERE complex_id IS NOT NULL;
|
||||
-- snapshot_date в одиночку — для latest-view (отбор max-снапшота) и housekeeping по дате.
|
||||
CREATE INDEX IF NOT EXISTS idx_supply_layers_snapshot_date
|
||||
ON supply_layers (snapshot_date DESC);
|
||||
|
||||
-- ── 5. Read-view: свежий снапшот на логический ключ ────────────────────────────
|
||||
-- Что читают #950 Step6 (future_supply.py) и любой UI/forecast-consumer. Возвращает по одной
|
||||
-- строке на логический ключ БЕЗ snapshot_date (layer, district_name, complex_id, obj_class,
|
||||
-- source) — самую свежую по snapshot_date. Tiebreak полностью детерминирован: при равной
|
||||
-- snapshot_date берём бОльший computed_at, затем бОльший id (на случай двух записей в день).
|
||||
-- DISTINCT ON требует, чтобы ведущие ORDER BY-выражения совпадали с DISTINCT-ключом.
|
||||
CREATE OR REPLACE VIEW v_supply_layers_latest AS
|
||||
SELECT DISTINCT ON (layer, district_name, complex_id, obj_class, source)
|
||||
id,
|
||||
layer,
|
||||
district_name,
|
||||
complex_id,
|
||||
obj_class,
|
||||
units_estimate,
|
||||
area_estimate,
|
||||
expected_online_date,
|
||||
source,
|
||||
confidence,
|
||||
method,
|
||||
snapshot_date,
|
||||
computed_at
|
||||
FROM supply_layers
|
||||
ORDER BY
|
||||
layer,
|
||||
district_name,
|
||||
complex_id,
|
||||
obj_class,
|
||||
source,
|
||||
snapshot_date DESC,
|
||||
computed_at DESC,
|
||||
id DESC;
|
||||
|
||||
COMMENT ON VIEW v_supply_layers_latest IS
|
||||
'Свежий снапшот supply_layers на логический ключ (layer, district_name, complex_id, '
|
||||
'obj_class, source) — max(snapshot_date), детерминир. tiebreak computed_at→id DESC. '
|
||||
'Это canonical read-path для future-supply (#950 Step6) и UI/forecast. Пустая таблица → 0 строк.';
|
||||
|
||||
COMMIT;
|
||||
Loading…
Add table
Reference in a new issue