-- 058: Past-due 499-A filings + revisions (amendments)
--
-- Three filing modes for the fcc-499a service:
--   1. current  — the default: annual 499-A for last calendar year
--   2. past_due — late filing for a reporting year earlier than (current-1)
--   3. revised  — amendment to a previously-filed 499-A (Line 612
--                 filing_type = revised_registration | revised_revenue)
--
-- USAC accepts all three through forms.universalservice.org; the
-- Playwright path differs (prior-year selector + penalty acknowledgment
-- for past-due; "Revise Filing" flow with confirmation # for revisions).
--
-- Past-due USF contributions are calculated at the *reporting year's*
-- contribution factor, not the current quarter's — so the handler must
-- use fcc_deminimis_factors[reporting_year] + the correct safe-harbor
-- row per year.

-- ── Compliance order fields ─────────────────────────────────────────────
ALTER TABLE compliance_orders
  ADD COLUMN IF NOT EXISTS filing_mode TEXT NOT NULL DEFAULT 'current'
    CHECK (filing_mode IN ('current','past_due','revised'));

-- form_year_override lets the filer target a year other than (now-1)
-- for past-due filings, or the original year for a revision.
ALTER TABLE compliance_orders
  ADD COLUMN IF NOT EXISTS form_year_override SMALLINT
    CHECK (form_year_override IS NULL OR form_year_override BETWEEN 2015 AND 2035);

-- revises_order_number: points at the prior compliance_order whose 499-A
-- this filing amends. The new order inherits intake_data + the prior
-- confirmation number (so USAC knows which filing to revise).
ALTER TABLE compliance_orders
  ADD COLUMN IF NOT EXISTS revises_order_number TEXT;

-- Line 612 filing-type reason when filing_mode='revised'. USAC requires
-- this on the revised filing so the reviewer knows whether fields other
-- than revenue changed.
ALTER TABLE compliance_orders
  ADD COLUMN IF NOT EXISTS revised_reason TEXT
    CHECK (revised_reason IS NULL OR revised_reason IN ('registration','revenue','both'));

-- Prior-confirmation number recorded after a successful revision submit.
-- Links revised filings together so admin can see the full amendment chain.
ALTER TABLE compliance_orders
  ADD COLUMN IF NOT EXISTS prior_confirmation_number TEXT;

-- Index on revises_order_number for "show all amendments of order X" queries
CREATE INDEX IF NOT EXISTS idx_compliance_orders_revises
  ON compliance_orders(revises_order_number)
  WHERE revises_order_number IS NOT NULL;

-- ── Penalty estimate persistence ────────────────────────────────────────
-- For past-due filings we estimate retroactive USF owed so the customer
-- knows the magnitude before clicking "File". FCC forfeitures are
-- separately assessed and NOT estimated here — only the retroactive
-- contribution.
ALTER TABLE compliance_orders
  ADD COLUMN IF NOT EXISTS late_filing_retroactive_usf_cents BIGINT;
ALTER TABLE compliance_orders
  ADD COLUMN IF NOT EXISTS late_filing_notes TEXT;

-- ── Prior-year de minimis factors ───────────────────────────────────────
-- Each calendar year's 499-A has its own Appendix A Line 10 factor. Past
-- years MUST be seeded before a past-due filing can be validated. Values
-- below are placeholders — before enabling a past-due filing for year N,
-- look up N's actual factor from USAC's 499-A instructions archive at
-- https://www.usac.org/service-providers/contributing-to-the-usf/forms-to-file/
-- and INSERT or UPDATE the correct value.
--
-- 2025 factor (for 2025 revenues filed on 2026-04-01): 0.2560 (already in 054).
-- Placeholder seeds for prior years — leave commented out until verified:
-- INSERT INTO fcc_deminimis_factors (form_year, factor, source_citation) VALUES
--   (2025, 0.xxxx, '2025 Form 499-A Appendix A'),
--   (2024, 0.xxxx, '2024 Form 499-A Appendix A'),
--   (2023, 0.xxxx, '2023 Form 499-A Appendix A')
-- ON CONFLICT (form_year) DO NOTHING;

-- ── Prior-year safe-harbor percentages ──────────────────────────────────
-- Safe harbor has been unchanged at 64.9% VoIP / 37.1% wireless /
-- 12.0% paging / 1.0% SMR since the 2006 Contribution Methodology
-- Reform Order. Seed prior years at the same values so handlers filing
-- past-due can look them up. If the FCC changes safe harbors in the
-- future, prior-year rows will still return correct historical values.
INSERT INTO fcc_safe_harbor_percentages (form_year, line_105_category, interstate_pct, source_citation)
SELECT y, c, v,
       CONCAT(y::text, ' Form 499-A IV.C.5.g (back-seeded from 2006 Contribution Reform Order)')
  FROM (VALUES
    ('voip_interconnected', 64.9),
    ('cellular_pcs',        37.1),
    ('paging',              12.0),
    ('smr_dispatch',         1.0)
  ) AS sh(c, v),
       generate_series(2020, 2025) AS y
ON CONFLICT (form_year, line_105_category) DO NOTHING;