Plan: Fair Hearings and Appeals

CREATE TABLE appeal_requests (
    id UUID PRIMARY KEY,
    household_id UUID NOT NULL,
    requestor_person_id UUID NOT NULL,
    program TEXT NOT NULL,                  -- Program enum value
    application_id UUID,
    determination_id UUID NOT NULL,         -- the determination being appealed
    notice_id UUID,                         -- the NOA that triggered the appeal (optional)
    request_date DATE NOT NULL,
    request_method TEXT NOT NULL,           -- 'phone', 'mail', 'in_person', 'online'
    adverse_action_effective_date DATE,     -- date of adverse action; used for continued benefits check
    hearing_scheduled_date DATE,
    hearing_officer_id UUID,
    decision_due_date DATE NOT NULL,        -- request_date + decision_clock_days (from jurisdiction.toml per program)
    -- SNAP: 90 days (7 CFR 273.15). Medicaid: 90 days (42 CFR 431.244).
    -- TANF: state-determined (Georgia: 90 days). CAPS/WIC: state-determined.
    -- Load from jurisdiction.toml [appeals] decision_clock_days_snap = 90, etc.
    decision_date DATE,
    decision TEXT,
    -- 'upheld_agency', 'reversed_household', 'withdrawn', 'dismissed'
    decision_basis TEXT,                    -- narrative summary of hearing officer's decision
    continued_benefits_eligible BOOLEAN GENERATED ALWAYS AS
        (adverse_action_effective_date IS NOT NULL
         AND request_date < adverse_action_effective_date) STORED,
    continued_benefits_granted BOOLEAN NOT NULL DEFAULT false,
    continued_benefits_start_date DATE,
    continued_benefits_end_date DATE,
    overpayment_amount NUMERIC(10,2),       -- set when agency upheld and continued benefits were paid
    overpayment_claim_id UUID,
    status TEXT NOT NULL DEFAULT 'pending',
    -- 'pending', 'scheduled', 'decided', 'withdrawn', 'dismissed'
    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    active BOOLEAN NOT NULL DEFAULT true
);

CREATE INDEX appeals_household_idx ON appeal_requests (household_id);
CREATE INDEX appeals_status_idx ON appeal_requests (status, decision_due_date) WHERE status = 'pending';

CREATE TABLE appeal_timeline_events (
    id UUID PRIMARY KEY,
    appeal_id UUID NOT NULL REFERENCES appeal_requests(id),
    event_type TEXT NOT NULL,
    -- 'request_received', 'acknowledged', 'continued_benefits_granted',
    -- 'hearing_scheduled', 'hearing_held', 'decision_issued',
    -- 'overpayment_assessed', 'withdrawn', 'dismissed'
    event_date TIMESTAMPTZ NOT NULL DEFAULT now(),
    recorded_by UUID,                       -- worker person_id; null for system events
    notes TEXT
);

// appeal.filed
{ "appeal_id": "uuid", "household_id": "uuid", "program": "snap", "request_date": "2026-07-15" }

// appeal.continued_benefits_granted
{ "appeal_id": "uuid", "household_id": "uuid", "program": "snap",
  "start_date": "2026-07-20", "determination_id": "uuid" }

// appeal.decision_issued
{ "appeal_id": "uuid", "household_id": "uuid", "decision": "upheld_agency",
  "determination_id": "uuid" }

// appeal.overpayment_assessed
{ "appeal_id": "uuid", "household_id": "uuid" }

// appeal.decision_reversed
{ "appeal_id": "uuid", "household_id": "uuid", "program": "snap" }

// SPDX-License-Identifier: AGPL-3.0-or-later

use canopy_mq::publisher::EventPublisher;
use chrono::{NaiveDate, Utc};
use sqlx::PgPool;
use uuid::Uuid;

pub struct DecisionClock {
    pool: PgPool,
    publisher: EventPublisher,
}

impl DecisionClock {
    pub fn new(pool: PgPool, publisher: EventPublisher) -> Self {
        Self { pool, publisher }
    }

    /// Run the daily clock check. Finds appeals approaching or past their decision deadline.
    pub async fn run_daily_check(&self) -> Result<ClockCheckResult> {
        let today = Utc::now().date_naive();
        let approaching = self.find_approaching_deadline(today, 14).await?;
        let overdue = self.find_overdue(today).await?;

        for appeal in &approaching {
            let days_remaining = (appeal.decision_due_date - today).num_days();
            self.publisher.publish(
                "appeal.decision_deadline_approaching",
                &serde_json::json!({
                    "appeal_id": appeal.id,
                    "household_id": appeal.household_id,
                    "decision_due_date": appeal.decision_due_date,
                    "days_remaining": days_remaining
                }),
            ).await?;
        }

        for appeal in &overdue {
            self.publisher.publish(
                "appeal.overdue",
                &serde_json::json!({
                    "appeal_id": appeal.id,
                    "household_id": appeal.household_id,
                    "decision_due_date": appeal.decision_due_date
                }),
            ).await?;
        }

        Ok(ClockCheckResult { approaching: approaching.len(), overdue: overdue.len() })
    }

    /// Find appeals where decision_due_date <= today + lookahead_days AND status IN ('pending', 'scheduled').
    async fn find_approaching_deadline(&self, today: NaiveDate, lookahead_days: i64) -> Result<Vec<AppealRequest>> { /* sqlx query */ }

    /// Find appeals where decision_due_date < today AND status NOT IN ('decided', 'withdrawn', 'dismissed').
    async fn find_overdue(&self, today: NaiveDate) -> Result<Vec<AppealRequest>> { /* sqlx query */ }
}

pub struct ClockCheckResult {
    pub approaching: usize,
    pub overdue: usize,
}

// SPDX-License-Identifier: AGPL-3.0-or-later

use axum::{Router, routing::{get, post, put}, extract::{Path, Query, State}, Json};
use canopy_api::AppState;
use uuid::Uuid;

pub fn routes() -> Router<AppState> {
    Router::new()
        .route("/v1/appeals", post(file_appeal))
        .route("/v1/appeals", get(list_appeals))            // Query: household_id
        .route("/v1/appeals/:id", get(get_appeal))
        .route("/v1/appeals/:id/schedule", put(schedule_hearing))
        .route("/v1/appeals/:id/decision", put(record_decision))
        .route("/v1/appeals/:id/withdraw", put(withdraw_appeal))
        .route("/v1/appeals/queue", get(appeals_queue))
}

// SPDX-License-Identifier: AGPL-3.0-or-later

use canopy_test_lib::{setup_test_db, setup_test_mq, mock_event_publisher};

#[tokio::test]
async fn test_appeal_before_effective_date_grants_continued_benefits() {
    // Setup: determination with adverse_action_effective_date = today + 10
    // POST /v1/appeals with request_date = today
    // Assert: continued_benefits_eligible = true, continued_benefits_granted = true
    // Assert: continued_benefits_start_date = adverse_action_effective_date
    // Assert: appeal.continued_benefits_granted event published
    // Assert: timeline event "continued_benefits_granted" created
}

#[tokio::test]
async fn test_appeal_after_effective_date_no_continued_benefits() {
    // Setup: determination with adverse_action_effective_date = today - 5
    // POST /v1/appeals with request_date = today
    // Assert: continued_benefits_eligible = false, continued_benefits_granted = false
    // Assert: no appeal.continued_benefits_granted event published
}

#[tokio::test]
async fn test_appeal_outside_90_day_window() {
    // Setup: adverse action notice_date = today - 100
    // POST /v1/appeals
    // Assert: 422 response with ProblemDetail citing 7 CFR 273.15(b)
}

#[tokio::test]
async fn test_decision_upheld_calculates_overpayment() {
    // Setup: appeal with continued_benefits_granted = true, 2 months of benefits paid
    // PUT /v1/appeals/{id}/decision with decision = "upheld_agency"
    // Assert: overpayment_amount = sum of continued benefit issuances
    // Assert: appeal.overpayment_assessed event published
    // Assert: timeline event "overpayment_assessed" created
}

#[tokio::test]
async fn test_decision_reversed_publishes_event() {
    // PUT /v1/appeals/{id}/decision with decision = "reversed_household"
    // Assert: appeal.decision_reversed event published
    // Assert: no overpayment calculated
    // Assert: timeline event "decision_issued" created
}

#[tokio::test]
async fn test_withdraw_appeal() {
    // PUT /v1/appeals/{id}/withdraw
    // Assert: status = "withdrawn"
    // Assert: continued_benefits_end_date set if benefits were granted
    // Assert: timeline event "withdrawn" created
}

#[tokio::test]
async fn test_90_day_clock_approaching_deadline() {
    // Setup: appeal with decision_due_date = today + 10, status = "pending"
    // Run DecisionClock::run_daily_check()
    // Assert: appeal.decision_deadline_approaching event published with days_remaining = 10
}

#[tokio::test]
async fn test_90_day_clock_overdue() {
    // Setup: appeal with decision_due_date = today - 3, status = "scheduled"
    // Run DecisionClock::run_daily_check()
    // Assert: appeal.overdue event published
}

#[tokio::test]
async fn test_appeals_queue_sorted_by_deadline() {
    // Insert 3 appeals with different decision_due_dates
    // GET /v1/appeals/queue
    // Assert: sorted ascending by decision_due_date (most urgent first)
}