gendesign/data/sql/129_cad_parcels_quarter_cad_trigger.sql

-- 129_cad_parcels_quarter_cad_trigger.sql
-- FIX (prod, CRITICAL) — on-demand НСПД-ингест роняет POST /analyze для «нового» участка:
--   NotNullViolation на cad_parcels.quarter_cad_number → геометрия не сохраняется навсегда.
--
-- БАГ (ground-truth, измерено на prod):
--   cad_parcels.quarter_cad_number — NOT NULL (м.92, строка 53). On-demand-ингест НСПД
--   (backend/app/services/cadastre/bulk_harvest.py :: upsert_parcel, вызывается parcels-fetch
--   воркером для участков, которых НЕТ в предзагруженной БД) ИНОГДА пишет
--   quarter_cad_number = NULL в рантайме →
--     psycopg.errors.NotNullViolation: null value in column "quarter_cad_number"
--                                      of relation "cad_parcels"
--   → fetch-таргет участка падает → geom НЕ персистится → POST /parcels/{cad}/analyze
--   для этого участка навсегда залипает в «Геометрия загружается из НСПД…» и пере-ставит
--   задачу при каждом вызове. Ломает базовый сценарий «пользователь вводит новый/произвольный
--   РЕАЛЬНЫЙ кадастровый номер». Воспроизведено на РЕАЛЬНОМ НСПД-участке 66:41:0610029:83
--   (упавшая строка несёт валидный geom-blob + NSPD raw_props; null только quarter_cad_number).
--
--   Код ПЫТАЕТСЯ вывести квартал сам:
--     quarter_cad = opts.quarter_cad_number or _derive_quarter_cad(cad_num)   (bulk_harvest.py:462)
--   и _derive_quarter_cad (там же :1288) даёт '66:41:0610029:83' → '66:41:0610029'.
--   Но null всё равно доезжает до INSERT в рантайме (вероятно grid-walk / отдельный feature-путь,
--   где quarter попадает в параметр уже как None в обход этой ветки). Вместо охоты за каждым
--   код-путём чиним на уровне БД: quarter_cad_number — ЧИСТАЯ производная от cad_num (первые
--   3 colon-сегмента), поэтому пусть БД её и гарантирует — для ВСЕХ путей записи разом.
--
-- ПОЧЕМУ ТРИГГЕР (а не CHECK / GENERATED / правка кода):
--   • Производное поле → его можно детерминированно достроить из cad_num прямо на write.
--   • BEFORE INSERT OR UPDATE FOR EACH ROW чинит ВСЕ пути записи разом: on-demand fetch (тот
--     самый неуловимый рантайм-путь), upsert_parcel/bulk_harvest, bulk-загрузчики, ручной SQL —
--     никому не нужно знать про вывод квартала. Один инвариант в БД вместо N мест в коде.
--   • GENERATED ALWAYS AS не подходит: (а) колонка уже существует как обычная NOT NULL
--     (нельзя «доконвертить» в generated через ALTER без пересоздания), (б) generated-колонку
--     нельзя писать явно, а ON CONFLICT DO UPDATE воркера (bulk_harvest.py:500) присваивает
--     quarter_cad_number = EXCLUDED.quarter_cad_number — это бы сломалось. Триггер же
--     прозрачно достраивает NULL и не мешает явным не-NULL значениям.
--
-- ПОВЕДЕНИЕ ТРИГГЕРА (ровно один инвариант):
--   Если NEW.quarter_cad_number IS NULL И NEW.cad_num IS NOT NULL И cad_num содержит ≥3
--   colon-сегмента → NEW.quarter_cad_number := первые 3 сегмента через ':'
--     array_to_string((string_to_array(NEW.cad_num, ':'))[1:3], ':')
--   Проверено на prod: '66:41:0610029:83' → '66:41:0610029'. Зеркалит Python-семантику
--   _derive_quarter_cad (split(':'), len≥3 → ':'.join(parts[:3])).
--
-- БЕЗОПАСНОСТЬ <3 сегментов (НАМЕРЕННОЕ расхождение с Python, документируется):
--   Если cad_num содержит <3 сегментов (валидный квартал из него НЕ собрать) → НЕ трогаем
--   NEW.quarter_cad_number (остаётся NULL) → NOT NULL-констрейнт по-прежнему ОТКЛОНЯЕТ такую
--   строку. Это СОЗНАТЕЛЬНО строже Python-ветки (_derive_quarter_cad на <3 возвращает cad_num
--   КАК ЕСТЬ, т.е. протащил бы мусор как «квартал»): не маскируем реально-битые кадастровые
--   номера фейковым кварталом, пусть падают громко. Корректные НСПД-участки ВСЕГДА имеют ≥3
--   сегмента (РР:ОО:КККККК[:УУ]), поэтому легитимный on-demand-ингест НИКОГДА в эту ветку не
--   попадает — он всегда получает выведенный квартал.
--
-- BACKFILL НЕ нужен: quarter_cad_number — NOT NULL с м.92, поэтому существующих null-строк НЕТ
--   (БД бы их не приняла). Триггер закрывает ВСЕ будущие INSERT/UPDATE из любого код-пути.
--
-- Сосуществование с существующим триггером cad_parcels_set_updated_at (м.92, BEFORE UPDATE,
--   set_updated_at()): два BEFORE ROW-триггера на одной таблице легальны; PG вызывает их в
--   АЛФАВИТНОМ порядке по имени. Они независимы (один достраивает quarter_cad_number, другой
--   ставит updated_at = NOW()) → порядок не важен, конфликта нет. Имя нового — отдельное
--   (cad_parcels_derive_quarter_cad), существующий триггер не трогаем.
--
-- ПРОИЗВОДИТЕЛЬНОСТЬ: тривиально — на строку лишь string_to_array/срез/array_to_string по
--   короткой строке, только когда quarter_cad_number IS NULL (для уже-заполненных значений —
--   ранний выход по условию, цена ~ноль). Пренебрежимо на любом объёме ингеста/bulk-загрузки.
--
-- Idempotent (acceptance — ре-applied чисто ДВАЖДЫ): CREATE OR REPLACE FUNCTION (переопределяет
--   на месте) + DROP TRIGGER IF EXISTS перед CREATE TRIGGER (PG16 не имеет CREATE OR REPLACE
--   TRIGGER → паттерн DROP-IF-EXISTS+CREATE, как в м.90). BEGIN/COMMIT — атомарно. НИКАКИХ
--   DROP TABLE/TRUNCATE, никаких INSERT/строк.
--
-- Deploy order: чистая СХЕМА, БЕЗ зависимости от кода — безопасно катить в любой момент
--   (auto-applied by deploy.yml через _schema_migrations tracking, ровно один раз по NN).
--   Эффект мгновенный: со следующего же on-demand-ингеста NULL-quarter достраивается в БД,
--   NotNullViolation на легитимном НСПД-участке становится НЕВОЗМОЖНОЙ. Правки backend НЕ
--   требуется (существующий or _derive_quarter_cad остаётся как есть и не конфликтует).

BEGIN;

-- ── 1. Триггер-функция: достроить quarter_cad_number из cad_num (если NULL) ─────────
-- Зеркалит _derive_quarter_cad (bulk_harvest.py:1288), НО на <3 сегментов оставляет NULL
-- (см. «БЕЗОПАСНОСТЬ <3 сегментов» в шапке) — чтобы NOT NULL отсекал реально-битые cad_num.
-- CREATE OR REPLACE → re-apply переопределяет тело на месте (idempotent).
CREATE OR REPLACE FUNCTION cad_parcels_derive_quarter_cad() RETURNS TRIGGER AS $$
BEGIN
    -- Достраиваем ТОЛЬКО когда квартал не задан, cad_num есть и из него собирается
    -- валидный квартал (≥3 colon-сегмента: РР:ОО:КККККК[...]). Иначе NEW не трогаем:
    --  • quarter уже задан → уважаем явное значение (в т.ч. ON CONFLICT EXCLUDED.*);
    --  • cad_num NULL / <3 сегментов → оставляем quarter_cad_number = NULL, пусть NOT NULL
    --    отклонит строку (не маскируем мусор фейковым кварталом).
    IF NEW.quarter_cad_number IS NULL
       AND NEW.cad_num IS NOT NULL
       AND array_length(string_to_array(NEW.cad_num, ':'), 1) >= 3
    THEN
        -- '66:41:0610029:83' → '66:41:0610029' (первые 3 сегмента; проверено на prod).
        NEW.quarter_cad_number :=
            array_to_string((string_to_array(NEW.cad_num, ':'))[1:3], ':');
    END IF;
    RETURN NEW;
END;
$$ LANGUAGE plpgsql;

COMMENT ON FUNCTION cad_parcels_derive_quarter_cad() IS
    'BEFORE INSERT OR UPDATE-триггер cad_parcels (#fix on-demand-ингест): достраивает '
    'NOT NULL quarter_cad_number из первых 3 colon-сегментов cad_num, когда он NULL '
    '(пример: 66:41:0610029:83 → 66:41:0610029). Чинит NotNullViolation во ВСЕХ путях '
    'записи (on-demand fetch / bulk_harvest / bulk-загрузчики). На cad_num с <3 сегментов '
    'НАМЕРЕННО оставляет NULL → NOT NULL отклоняет реально-битые номера (не маскирует мусор).';

-- ── 2. Триггер BEFORE INSERT OR UPDATE на cad_parcels ──────────────────────────────
-- INSERT — основной путь бага (on-demand-ингест роняет именно INSERT). UPDATE — тоже под
-- защитой: ON CONFLICT DO UPDATE воркера присваивает quarter_cad_number = EXCLUDED.* (мог бы
-- быть NULL при ре-ингесте). PG16 не имеет CREATE OR REPLACE TRIGGER → DROP IF EXISTS + CREATE
-- (idempotent; паттерн м.90). Существующий cad_parcels_set_updated_at (м.92) не трогаем —
-- независимый BEFORE-триггер, сосуществует (см. шапку).
DROP TRIGGER IF EXISTS cad_parcels_derive_quarter_cad ON cad_parcels;
CREATE TRIGGER cad_parcels_derive_quarter_cad
    BEFORE INSERT OR UPDATE ON cad_parcels
    FOR EACH ROW EXECUTE FUNCTION cad_parcels_derive_quarter_cad();

COMMIT;