-- 057: Traffic study FCC compliance + LNPA region allocations
--
-- 2026 FCC Form 499-A Section IV.C.5.h: filers relying on a traffic study
-- must:
--   (a) Sample with 1% margin of error @ 95% confidence
--   (b) Submit the study to USAC alongside the 499-A filing
--   (c) Stamp every page with Filer ID + Company Name + Affiliated Filers Name
--
-- The existing cdr_traffic_studies table (migration 050) tracks studies
-- but lacks the FCC-compliance metadata (sample size, margin of error,
-- methodology narrative) and the stamped-PDF path + USAC submission ID.
-- Add them here.
--
-- Block 5 Lines 503-510 are percentage splits across 10 LNPA regions for
-- both Block 3 (resale) and Block 4 (end user) revenue. Must sum to 100%
-- per column (or 0% if no revenue in that block). Stored per
-- (entity, year, period, region).

-- ── Traffic study FCC-compliance metadata ───────────────────────────────
ALTER TABLE cdr_traffic_studies
    ADD COLUMN IF NOT EXISTS methodology_narrative TEXT;
ALTER TABLE cdr_traffic_studies
    ADD COLUMN IF NOT EXISTS sample_size INTEGER;
ALTER TABLE cdr_traffic_studies
    ADD COLUMN IF NOT EXISTS margin_of_error_pct NUMERIC(4,2);
ALTER TABLE cdr_traffic_studies
    ADD COLUMN IF NOT EXISTS confidence_level_pct NUMERIC(4,2) DEFAULT 95.0;

-- Stamped PDF (Filer ID + Company Name + Affiliated Filers Name on every page)
ALTER TABLE cdr_traffic_studies
    ADD COLUMN IF NOT EXISTS stamped_pdf_minio_path TEXT;

-- USAC submission tracking
ALTER TABLE cdr_traffic_studies
    ADD COLUMN IF NOT EXISTS usac_submitted_at TIMESTAMPTZ;
ALTER TABLE cdr_traffic_studies
    ADD COLUMN IF NOT EXISTS usac_submission_id TEXT;

-- Computed flag — TRUE when sample_size + margin_of_error + methodology_narrative
-- + stamped_pdf_minio_path are all populated AND margin_of_error_pct ≤ 1.0
-- AND confidence_level_pct ≥ 95.0. Maintained in application code (not
-- generated column — we want explicit state).
ALTER TABLE cdr_traffic_studies
    ADD COLUMN IF NOT EXISTS fcc_compliance_ok BOOLEAN DEFAULT FALSE;

-- ── LNPA region allocations (Block 5 Lines 503-510) ─────────────────────
-- The 10 NANPA/LNPA regions as defined by iconectiv NPAC. Stored per
-- reporting period so historical filings remain reconstructible.
CREATE TABLE IF NOT EXISTS lnpa_region_allocations (
    id                 BIGSERIAL PRIMARY KEY,
    telecom_entity_id  INTEGER NOT NULL REFERENCES telecom_entities(id)
                               ON DELETE CASCADE,
    reporting_year     SMALLINT NOT NULL,
    reporting_period   TEXT NOT NULL DEFAULT 'annual'
                       CHECK (reporting_period IN ('annual','Q1','Q2','Q3','Q4')),

    region_code        TEXT NOT NULL CHECK (region_code IN (
        'NE',   -- Northeast: CT, MA, ME, NH, NY (parts), RI, VT
        'MA',   -- Mid-Atlantic: DC, DE, MD, NJ, PA, VA, WV
        'SE',   -- Southeast: AL, FL, GA, KY, MS, NC, SC, TN
        'SC',   -- Southern: AR, LA, NM, OK
        'TX',   -- Texas
        'MW',   -- Midwest: IL, IN, MI, OH, WI
        'IA',   -- Iowa / Plains: IA, KS, MN, MO, ND, NE, SD
        'RM',   -- Rocky Mountain: CO, MT, UT, WY, ID
        'NW',   -- Northwest: AK, OR, WA
        'WC'    -- West Coast: AZ, CA, HI, NV
    )),

    block_3_pct        NUMERIC(5,2) NOT NULL DEFAULT 0   -- Lines 503-510 col (a)
                       CHECK (block_3_pct >= 0 AND block_3_pct <= 100),
    block_4_pct        NUMERIC(5,2) NOT NULL DEFAULT 0   -- Lines 503-510 col (b)
                       CHECK (block_4_pct >= 0 AND block_4_pct <= 100),

    created_at         TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at         TIMESTAMPTZ NOT NULL DEFAULT NOW(),

    UNIQUE (telecom_entity_id, reporting_year, reporting_period, region_code)
);

CREATE INDEX IF NOT EXISTS idx_lnpa_region_entity_year
    ON lnpa_region_allocations (telecom_entity_id, reporting_year);

-- Validator: the 10 rows for a given (entity, year, period) must sum to
-- 100% per column (or 0% if no revenue in that block). Not enforced at
-- DB level — checked in application code before submission to USAC.