-- 292_cbr_macro_series.sql
-- Макро-ряды ЦБ РФ: ипотека по субъектам + ключевая ставка.
--
-- Context:
--   ЦБ РФ публикует месячную статистику по ипотечным жилищным кредитам (объём выдач,
--   ставки, задолженность) в разрезе субъектов РФ — три XLSX-дашборда на cbr.ru
--   (см. app/services/cbr_macro.py::CBR_MORTGAGE_SERIES) — и дневную ключевую ставку
--   через SOAP-сервис DailyInfoWebServ. Обе серии нужны как макро-контекст для
--   продукта (региональная динамика ипотечного рынка); загрузку в estimator этот
--   PR не делает — только данные и их сбор (app/tasks/cbr_macro_pull.py).
--
-- Schema notes:
--   cbr_mortgage_series
--     * region        — территория как в источнике (РФ целиком / федеральный округ /
--                        субъект), без нормализации кодов ОКАТО.
--     * period_month  — первое число отчётного месяца (шапка XLSX «Месяц Год»).
--     * series        — slug серии (rate_rub / new_loans_rub / debt_rub, конфиг —
--                        CBR_MORTGAGE_SERIES в коде).
--     * PRIMARY KEY (region, period_month, series) — одно значение на территорию×месяц×серию.
--     * fetched_at    — «когда мы ВПЕРВЫЕ увидели этот период» (не время последней
--                        загрузки — источник даёт всю серию целиком, отсечки по
--                        периоду нет). Урок #2846 у sber_price_index: НЕ обновлять
--                        fetched_at в ON CONFLICT DO UPDATE, иначе один прогон
--                        перезаписывает метку у всех периодов, включая 2019-01.
--   cbr_key_rate
--     * rate_date — дата действия ключевой ставки (PRIMARY KEY).
--     * rate      — значение ставки, % годовых.
--     * fetched_at — по той же логике, что и выше: не трогаем в DO UPDATE.
--
-- Idempotent: CREATE TABLE IF NOT EXISTS — безопасно переприменять. Только ADDITIVE.
--
-- Dependencies: нет (самостоятельные таблицы).
-- Deploy order: применить до app/services/cbr_macro.py + app/tasks/cbr_macro_pull.py
--   + миграции 291 (сид scrape_schedules).

BEGIN;
SET LOCAL lock_timeout = '5s';

CREATE TABLE IF NOT EXISTS cbr_mortgage_series (
    region       text               NOT NULL,
    period_month date               NOT NULL,
    series       text               NOT NULL,
    value        double precision   NOT NULL,
    source       text               NOT NULL DEFAULT 'cbr',
    fetched_at   timestamptz        NOT NULL DEFAULT now(),
    PRIMARY KEY (region, period_month, series)
);

COMMENT ON TABLE cbr_mortgage_series IS
    'Месячные ряды ипотечной статистики ЦБ РФ по территориям (РФ / ФО / субъекты): '
    'объём выдач, ставки, задолженность. Источник — XLSX-дашборды cbr.ru/vfs/statistics/'
    'BankSector/Mortgage/. Загружается app/tasks/cbr_macro_pull.py через in-app '
    'планировщик (scrape_schedules.source=''cbr_macro_pull'').';

COMMENT ON COLUMN cbr_mortgage_series.region IS
    'Территория как в источнике (например «РОССИЙСКАЯ ФЕДЕРАЦИЯ», «ЦЕНТРАЛЬНЫЙ '
    'ФЕДЕРАЛЬНЫЙ ОКРУГ», «Свердловская область»). Без нормализации ОКАТО/ISO.';
COMMENT ON COLUMN cbr_mortgage_series.period_month IS
    'Первое число отчётного месяца (нормализовано из шапки «Месяц Год» XLSX).';
COMMENT ON COLUMN cbr_mortgage_series.series IS
    'Slug серии, см. CBR_MORTGAGE_SERIES в app/services/cbr_macro.py '
    '(rate_rub, new_loans_rub, debt_rub).';
COMMENT ON COLUMN cbr_mortgage_series.value IS
    'Значение серии в единицах источника (% годовых для ставки, млн руб для объёмов).';
COMMENT ON COLUMN cbr_mortgage_series.fetched_at IS
    'Когда мы ВПЕРВЫЕ увидели этот период (не время последней загрузки). '
    'НЕ обновляется в ON CONFLICT DO UPDATE — см. урок #2846 у sber_price_index.';

CREATE INDEX IF NOT EXISTS idx_cbr_mortgage_series_region_series_period
    ON cbr_mortgage_series (region, series, period_month DESC);

CREATE TABLE IF NOT EXISTS cbr_key_rate (
    rate_date  date               PRIMARY KEY,
    rate       double precision   NOT NULL,
    fetched_at timestamptz        NOT NULL DEFAULT now()
);

COMMENT ON TABLE cbr_key_rate IS
    'Ключевая ставка ЦБ РФ по датам действия. Источник — SOAP-метод KeyRate '
    'сервиса https://www.cbr.ru/DailyInfoWebServ/DailyInfo.asmx. Загружается '
    'app/tasks/cbr_macro_pull.py.';
COMMENT ON COLUMN cbr_key_rate.rate_date IS 'Дата, с которой действует значение ставки.';
COMMENT ON COLUMN cbr_key_rate.rate IS 'Ключевая ставка, % годовых.';
COMMENT ON COLUMN cbr_key_rate.fetched_at IS
    'Когда мы ВПЕРВЫЕ увидели эту дату. НЕ обновляется в ON CONFLICT DO UPDATE.';

COMMIT;