-- 069_trade_in_estimates_dadata_fields.sql
-- PR Q1: DaData on-demand enrichment в estimate flow.
--
-- После geocode() estimator зовёт dadata.clean_address(target) и сохраняет
-- результат рядом с расчётом, чтобы:
--   1) frontend мог показать canonical-форму адреса + ближайшее метро
--   2) house_cadnum / house_fias_id могли быть переиспользованы в будущем
--      для tier T0_per_house (точный matching сделок Росреестра по дому,
--      когда / если ЕГРН direct enrichment станет доступен).
--
-- Все поля nullable — DaData может быть disabled (нет ENV) либо вернуть
-- partial payload (qc_geo / qc_house без cadnum). Estimator продолжает работу
-- даже если все DaData-поля NULL (graceful degradation).

BEGIN;

ALTER TABLE trade_in_estimates
    ADD COLUMN IF NOT EXISTS canonical_address text,
    ADD COLUMN IF NOT EXISTS house_cadnum text,
    ADD COLUMN IF NOT EXISTS house_fias_id text,
    ADD COLUMN IF NOT EXISTS dadata_qc_geo integer,
    ADD COLUMN IF NOT EXISTS dadata_qc_house integer,
    ADD COLUMN IF NOT EXISTS dadata_metro jsonb;

COMMENT ON COLUMN trade_in_estimates.canonical_address IS
    'DaData /clean/address result field — canonical form, напр. "г Екатеринбург, ул Малышева, д 125"';
COMMENT ON COLUMN trade_in_estimates.house_cadnum IS
    'DaData house_cadnum — кадастровый номер дома (формат "66:41:0704045:350"). '
    'Может быть NULL если DaData не нашёл (qc_house != 2) или service disabled.';
COMMENT ON COLUMN trade_in_estimates.house_fias_id IS
    'DaData house_fias_id — UUID дома в ФИАС.';
COMMENT ON COLUMN trade_in_estimates.dadata_qc_geo IS
    'DaData qc_geo — quality code геокодинга: 0=exact, 1=street, 2=settlement, ...';
COMMENT ON COLUMN trade_in_estimates.dadata_qc_house IS
    'DaData qc_house — quality code дома: 2=в ФИАС, 10=на картах, ...';
COMMENT ON COLUMN trade_in_estimates.dadata_metro IS
    'Список ближайших станций метро от DaData: [{"name","line","distance"},...]';

COMMIT;
