Plan: SNAP Renewals and Certification Period Management

fn certification_type(start: NaiveDate, end: NaiveDate) -> &'static str {
    let months = (end.year() - start.year()) * 12 + (end.month() as i32 - start.month() as i32);
    if months >= 22 { "elderly_disabled" } else { "standard" }
}

active ──────────────────────────────────────────────────────────► expired
  │                                                                    ▲
  │   (renewal application submitted)                                  │
  ├──► recertifying ──► (renewed, new cert created) ──► active        │
  │                 └──► (denied or not timely) ──────────────────────┘
  │
  └──► terminated (adverse action completed)

pub async fn check_income_threshold(
    pool: &PgPool,
    persons_client: &PersonsClient,
    cert: &SnapCertification,
    reported_income: Decimal,
) -> Result<ThresholdCheckResult, ApiError> {
    let fpl_limit = get_fpl_threshold(pool, cert.household_size, 1.30).await?;
    if reported_income > fpl_limit {
        Ok(ThresholdCheckResult::ExceedsLimit { fpl_limit })
    } else {
        Ok(ThresholdCheckResult::WithinLimit)
    }
}

CREATE TABLE snap_certifications (
    id UUID PRIMARY KEY,
    household_id UUID NOT NULL,
    application_id UUID NOT NULL,
    determination_id UUID NOT NULL,
    certification_start_date DATE NOT NULL,
    certification_end_date DATE NOT NULL,
    certification_type TEXT NOT NULL DEFAULT 'standard',
    reporting_model TEXT NOT NULL DEFAULT 'simplified',
    interim_contact_due_date DATE,
    interim_contact_completed_at TIMESTAMPTZ,
    renewal_notice_sent_date DATE,
    renewal_application_id UUID,
    renewal_submitted_at TIMESTAMPTZ,
    renewal_determination_id UUID,
    status TEXT NOT NULL DEFAULT 'active',
    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    active BOOLEAN NOT NULL DEFAULT true
);

CREATE TABLE snap_change_reports (
    id UUID PRIMARY KEY,
    certification_id UUID NOT NULL REFERENCES snap_certifications(id),
    household_id UUID NOT NULL,
    reported_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    report_method TEXT NOT NULL,
    change_type TEXT NOT NULL,
    description TEXT,
    requires_redetermination BOOLEAN NOT NULL DEFAULT false,
    redetermination_application_id UUID,
    processed_at TIMESTAMPTZ,
    processed_by UUID,
    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE INDEX idx_snap_certs_household ON snap_certifications(household_id);
CREATE INDEX idx_snap_certs_status ON snap_certifications(status);
CREATE INDEX idx_snap_certs_end_date ON snap_certifications(certification_end_date);
CREATE INDEX idx_snap_certs_interim_due ON snap_certifications(interim_contact_due_date)
    WHERE interim_contact_due_date IS NOT NULL;
CREATE INDEX idx_snap_change_reports_cert ON snap_change_reports(certification_id);
CREATE INDEX idx_snap_change_reports_household ON snap_change_reports(household_id);
CREATE INDEX idx_snap_change_reports_type ON snap_change_reports(change_type);

CREATE TABLE fpl_thresholds (
    id UUID PRIMARY KEY,
    effective_year INTEGER NOT NULL,
    household_size INTEGER NOT NULL,
    annual_fpl_amount NUMERIC(10,2) NOT NULL,
    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    UNIQUE (effective_year, household_size)
);

-- Seed 2026 federal poverty guidelines (48 contiguous states + DC)
-- USDA SNAP uses 130% FPL for gross income test.
INSERT INTO fpl_thresholds (id, effective_year, household_size, annual_fpl_amount) VALUES
    (gen_random_uuid(), 2026, 1,  15060.00),
    (gen_random_uuid(), 2026, 2,  20440.00),
    (gen_random_uuid(), 2026, 3,  25820.00),
    (gen_random_uuid(), 2026, 4,  31200.00),
    (gen_random_uuid(), 2026, 5,  36580.00),
    (gen_random_uuid(), 2026, 6,  41960.00),
    (gen_random_uuid(), 2026, 7,  47340.00),
    (gen_random_uuid(), 2026, 8,  52720.00);
-- For households larger than 8: add $5,380 per additional member.

// SPDX-License-Identifier: AGPL-3.0-or-later
// services/canopy-renewals/src/store/models.rs

use chrono::{DateTime, NaiveDate, Utc};
use rust_decimal::Decimal;
use serde::{Deserialize, Serialize};
use uuid::Uuid;

#[derive(Debug, Clone, Serialize, Deserialize, sqlx::FromRow)]
pub struct SnapCertification {
    pub id: Uuid,
    pub household_id: Uuid,
    pub application_id: Uuid,
    pub determination_id: Uuid,
    pub certification_start_date: NaiveDate,
    pub certification_end_date: NaiveDate,
    pub certification_type: String,
    pub reporting_model: String,
    pub interim_contact_due_date: Option<NaiveDate>,
    pub interim_contact_completed_at: Option<DateTime<Utc>>,
    pub renewal_notice_sent_date: Option<NaiveDate>,
    pub renewal_application_id: Option<Uuid>,
    pub renewal_submitted_at: Option<DateTime<Utc>>,
    pub renewal_determination_id: Option<Uuid>,
    pub status: String,
    pub created_at: DateTime<Utc>,
    pub updated_at: DateTime<Utc>,
    pub active: bool,
}

#[derive(Debug, Clone, Serialize, Deserialize, sqlx::FromRow)]
pub struct SnapChangeReport {
    pub id: Uuid,
    pub certification_id: Uuid,
    pub household_id: Uuid,
    pub reported_at: DateTime<Utc>,
    pub report_method: String,
    pub change_type: String,
    pub description: Option<String>,
    pub requires_redetermination: bool,
    pub redetermination_application_id: Option<Uuid>,
    pub processed_at: Option<DateTime<Utc>>,
    pub processed_by: Option<Uuid>,
    pub created_at: DateTime<Utc>,
}

// SPDX-License-Identifier: AGPL-3.0-or-later
// services/canopy-renewals/src/store/mod.rs

pub mod models;
use models::{SnapCertification, SnapChangeReport};
use sqlx::PgPool;
use uuid::Uuid;
use chrono::NaiveDate;

pub async fn create_certification(
    pool: &PgPool,
    cert: &SnapCertification,
) -> Result<SnapCertification, sqlx::Error> {
    sqlx::query_as::<_, SnapCertification>(
        r#"INSERT INTO snap_certifications
           (id, household_id, application_id, determination_id,
            certification_start_date, certification_end_date,
            certification_type, reporting_model, interim_contact_due_date, status)
           VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10)
           RETURNING *"#,
    )
    .bind(cert.id)
    .bind(cert.household_id)
    .bind(cert.application_id)
    .bind(cert.determination_id)
    .bind(cert.certification_start_date)
    .bind(cert.certification_end_date)
    .bind(&cert.certification_type)
    .bind(&cert.reporting_model)
    .bind(cert.interim_contact_due_date)
    .bind(&cert.status)
    .fetch_one(pool)
    .await
}

pub async fn get_active_certification(
    pool: &PgPool,
    household_id: Uuid,
) -> Result<Option<SnapCertification>, sqlx::Error> {
    sqlx::query_as::<_, SnapCertification>(
        "SELECT * FROM snap_certifications WHERE household_id = $1 AND status = 'active' AND active = true LIMIT 1",
    )
    .bind(household_id)
    .fetch_optional(pool)
    .await
}

pub async fn list_due_for_renewal(
    pool: &PgPool,
    within_days: i32,
) -> Result<Vec<SnapCertification>, sqlx::Error> {
    sqlx::query_as::<_, SnapCertification>(
        r#"SELECT * FROM snap_certifications
           WHERE status = 'active'
             AND active = true
             AND certification_end_date <= (CURRENT_DATE + $1::int * INTERVAL '1 day')
           ORDER BY certification_end_date ASC"#,
    )
    .bind(within_days)
    .fetch_all(pool)
    .await
}

pub async fn list_interim_contacts_due(
    pool: &PgPool,
) -> Result<Vec<SnapCertification>, sqlx::Error> {
    sqlx::query_as::<_, SnapCertification>(
        r#"SELECT * FROM snap_certifications
           WHERE status = 'active'
             AND active = true
             AND interim_contact_due_date IS NOT NULL
             AND interim_contact_due_date <= CURRENT_DATE
             AND interim_contact_completed_at IS NULL
           ORDER BY interim_contact_due_date ASC"#,
    )
    .fetch_all(pool)
    .await
}

pub async fn record_interim_contact(
    pool: &PgPool,
    id: Uuid,
) -> Result<SnapCertification, sqlx::Error> {
    sqlx::query_as::<_, SnapCertification>(
        r#"UPDATE snap_certifications
           SET interim_contact_completed_at = now(), updated_at = now()
           WHERE id = $1
           RETURNING *"#,
    )
    .bind(id)
    .fetch_one(pool)
    .await
}

pub async fn create_change_report(
    pool: &PgPool,
    report: &SnapChangeReport,
) -> Result<SnapChangeReport, sqlx::Error> {
    sqlx::query_as::<_, SnapChangeReport>(
        r#"INSERT INTO snap_change_reports
           (id, certification_id, household_id, report_method, change_type,
            description, requires_redetermination)
           VALUES ($1,$2,$3,$4,$5,$6,$7)
           RETURNING *"#,
    )
    .bind(report.id)
    .bind(report.certification_id)
    .bind(report.household_id)
    .bind(&report.report_method)
    .bind(&report.change_type)
    .bind(&report.description)
    .bind(report.requires_redetermination)
    .fetch_one(pool)
    .await
}

// SPDX-License-Identifier: AGPL-3.0-or-later
// services/canopy-renewals/src/events/determination_handler.rs

use chrono::NaiveDate;
use serde::Deserialize;
use uuid::Uuid;

use crate::store::{self, models::SnapCertification};
use crate::errors::ApiError;
use sqlx::PgPool;

#[derive(Debug, Deserialize)]
pub struct DeterminationCompletedEvent {
    pub determination_id: Uuid,
    pub application_id: Uuid,
    pub household_id: Uuid,
    pub program: String,
    pub status: String,
    pub effective_date: Option<NaiveDate>,
    pub expiration_date: Option<NaiveDate>,
}

pub async fn handle_determination_completed(
    pool: &PgPool,
    event: DeterminationCompletedEvent,
) -> Result<(), ApiError> {
    if event.program != "snap" || event.status != "approved" {
        return Ok(());
    }

    let Some(start) = event.effective_date else {
        tracing::warn!(
            determination_id = %event.determination_id,
            "snap determination.completed missing effective_date; skipping certification creation"
        );
        return Ok(());
    };
    let Some(end) = event.expiration_date else {
        tracing::warn!(
            determination_id = %event.determination_id,
            "snap determination.completed missing expiration_date; skipping certification creation"
        );
        return Ok(());
    };

    let cert_type = certification_type(start, end);
    let interim_due = match cert_type {
        "standard" => Some(add_months(start, 6)),
        _ => None,
    };

    // Check whether this is a recertification by looking for an existing
    // active certification for the household.
    let existing = store::get_active_certification(pool, event.household_id).await
        .map_err(|e| ApiError::Internal(format!("store error: {e}")))?;

    if let Some(ref prev) = existing {
        // Renewal approved: close prior certification, create new one.
        store::update_certification_status(pool, prev.id, "expired").await
            .map_err(|e| ApiError::Internal(format!("store error: {e}")))?;
    }

    let cert = SnapCertification {
        id: Uuid::now_v7(),
        household_id: event.household_id,
        application_id: event.application_id,
        determination_id: event.determination_id,
        certification_start_date: start,
        certification_end_date: end,
        certification_type: cert_type.to_string(),
        reporting_model: "simplified".to_string(),
        interim_contact_due_date: interim_due,
        interim_contact_completed_at: None,
        renewal_notice_sent_date: None,
        renewal_application_id: None,
        renewal_submitted_at: None,
        renewal_determination_id: None,
        status: "active".to_string(),
        created_at: chrono::Utc::now(),
        updated_at: chrono::Utc::now(),
        active: true,
    };

    store::create_certification(pool, &cert).await
        .map_err(|e| ApiError::Internal(format!("failed to create certification: {e}")))?;

    tracing::info!(
        certification_id = %cert.id,
        household_id = %event.household_id,
        cert_type = cert_type,
        end_date = %end,
        "snap certification created"
    );

    Ok(())
}

fn certification_type(start: NaiveDate, end: NaiveDate) -> &'static str {
    let months = (end.year() - start.year()) * 12
        + (end.month() as i32 - start.month() as i32);
    if months >= 22 { "elderly_disabled" } else { "standard" }
}

fn add_months(date: NaiveDate, months: u32) -> NaiveDate {
    let month = date.month() + months;
    let year_add = (month - 1) / 12;
    let new_month = ((month - 1) % 12) + 1;
    NaiveDate::from_ymd_opt(date.year() + year_add as i32, new_month, 1)
        .unwrap_or(date) // first day of target month; interim contact due the first of month 7
}

// SPDX-License-Identifier: AGPL-3.0-or-later
// services/canopy-renewals/src/scheduler/renewal_notices.rs

pub async fn run_renewal_notice_scheduler(
    pool: PgPool,
    publisher: Arc<EventPublisher>,
) {
    loop {
        let next_run = next_daily_run_at(2, 0); // 02:00 UTC
        tokio::time::sleep_until(next_run).await;

        if let Err(e) = check_and_send_renewal_notices(&pool, &publisher).await {
            tracing::error!(error = %e, "renewal notice scheduler error");
        }
    }
}

async fn check_and_send_renewal_notices(
    pool: &PgPool,
    publisher: &EventPublisher,
) -> Result<(), ApiError> {
    // 75-day notice: due date approaching, first notice not yet sent.
    let due_75 = store::list_certs_needing_notice(pool, 75, false).await?;
    for cert in due_75 {
        publisher.publish("renewal.snap_due", &serde_json::json!({
            "certification_id": cert.id,
            "household_id": cert.household_id,
            "renewal_due_date": cert.certification_end_date,
        })).await?;
        store::mark_renewal_notice_sent(pool, cert.id, chrono::Local::now().date_naive()).await?;
    }

    // 30-day notice: first notice sent but renewal_application_id still null.
    let due_30 = store::list_certs_needing_second_notice(pool, 30).await?;
    for cert in due_30 {
        publisher.publish("renewal.snap_due", &serde_json::json!({
            "certification_id": cert.id,
            "household_id": cert.household_id,
            "renewal_due_date": cert.certification_end_date,
        })).await?;
    }

    // Overdue: past certification_end_date, still active, no timely renewal.
    let overdue = store::list_overdue_certifications(pool).await?;
    for cert in overdue {
        publisher.publish("renewal.snap_overdue", &serde_json::json!({
            "certification_id": cert.id,
            "household_id": cert.household_id,
            "termination_date": cert.certification_end_date,
        })).await?;
        store::update_certification_status(pool, cert.id, "expired").await?;
    }

    Ok(())
}

// SPDX-License-Identifier: AGPL-3.0-or-later
// services/canopy-renewals/src/handlers/change_reports.rs

#[derive(Debug, Deserialize)]
pub struct ChangeReportRequest {
    pub report_method: String,
    pub change_type: String,
    pub description: Option<String>,
    pub reported_income: Option<Decimal>, // present only for income_change type
}

pub async fn post_change_report(
    State(state): State<AppState>,
    Path(cert_id): Path<Uuid>,
    Json(body): Json<ChangeReportRequest>,
) -> Result<(StatusCode, Json<SnapChangeReport>), ApiError> {
    let cert = store::get_certification(&state.pool, cert_id).await?
        .ok_or(ApiError::NotFound("certification not found".into()))?;

    let mut requires_redetermination = false;

    if body.change_type == "income_change" {
        if let Some(reported) = body.reported_income {
            let result = income_threshold::check(
                &state.pool,
                cert.household_id,
                reported,
            ).await?;
            if matches!(result, ThresholdCheckResult::ExceedsLimit { .. }) {
                requires_redetermination = true;
            }
        }
    }

    let report = SnapChangeReport {
        id: Uuid::now_v7(),
        certification_id: cert_id,
        household_id: cert.household_id,
        reported_at: chrono::Utc::now(),
        report_method: body.report_method,
        change_type: body.change_type,
        description: body.description,
        requires_redetermination,
        redetermination_application_id: None,
        processed_at: None,
        processed_by: None,
        created_at: chrono::Utc::now(),
    };

    let saved = store::create_change_report(&state.pool, &report).await
        .map_err(|e| ApiError::Internal(format!("store error: {e}")))?;

    if requires_redetermination {
        state.publisher.publish(
            "renewal.snap_income_threshold_exceeded",
            &serde_json::json!({
                "certification_id": cert_id,
                "household_id": cert.household_id,
                "reported_at": saved.reported_at,
            }),
        ).await?;
    }

    Ok((StatusCode::CREATED, Json(saved)))
}

// SPDX-License-Identifier: AGPL-3.0-or-later
// services/canopy-renewals/src/handlers/certifications.rs

pub async fn get_certification_for_household(
    State(state): State<AppState>,
    Query(params): Query<HouseholdQuery>,
) -> Result<Json<SnapCertification>, ApiError> {
    let cert = store::get_active_certification(&state.pool, params.household_id)
        .await
        .map_err(|e| ApiError::Internal(format!("store error: {e}")))?
        .ok_or_else(|| ApiError::NotFound("no active SNAP certification for household".into()))?;
    Ok(Json(cert))
}

pub async fn post_interim_contact(
    State(state): State<AppState>,
    Path(cert_id): Path<Uuid>,
    Json(body): Json<InterimContactRequest>,
) -> Result<Json<SnapCertification>, ApiError> {
    let cert = store::get_certification(&state.pool, cert_id).await
        .map_err(|e| ApiError::Internal(format!("{e}")))?
        .ok_or_else(|| ApiError::NotFound("certification not found".into()))?;

    if cert.interim_contact_due_date.is_none() {
        return Err(ApiError::UnprocessableEntity(
            "this certification does not require interim contact (elderly/disabled 24-month)".into()
        ));
    }
    if cert.interim_contact_completed_at.is_some() {
        return Err(ApiError::Conflict("interim contact already recorded".into()));
    }

    let updated = store::record_interim_contact(&state.pool, cert_id)
        .await
        .map_err(|e| ApiError::Internal(format!("{e}")))?;

    // Insert a change report as the audit record.
    let report = SnapChangeReport {
        id: Uuid::now_v7(),
        certification_id: cert_id,
        household_id: cert.household_id,
        reported_at: chrono::Utc::now(),
        report_method: body.contact_method,
        change_type: "interim_contact".to_string(),
        description: body.notes,
        requires_redetermination: false,
        ..Default::default()
    };
    store::create_change_report(&state.pool, &report).await
        .map_err(|e| ApiError::Internal(format!("{e}")))?;

    Ok(Json(updated))
}

pub fn router(state: AppState) -> Router {
    Router::new()
        .route("/v1/renewals/snap/certifications", get(certifications::get_certification_for_household))
        .route("/v1/renewals/snap/certifications/:id", get(certifications::get_certification))
        .route("/v1/renewals/snap/certifications/:id/interim-contact", post(certifications::post_interim_contact))
        .route("/v1/renewals/snap/certifications/:id/change-report", post(change_reports::post_change_report))
        .route("/v1/renewals/snap/due", get(certifications::list_due))
        .route("/v1/renewals/snap/interim-contacts/due", get(certifications::list_interim_contacts_due))
        .route("/healthz", get(health::healthz))
        .route("/metrics", get(metrics::metrics))
        .with_state(state)
}

// certification_lifecycle.rs

#[tokio::test]
async fn test_create_standard_certification_sets_interim_contact_due() { ... }
// Assert: 12-month cert gets interim_contact_due_date = start + 6 months

#[tokio::test]
async fn test_create_elderly_disabled_certification_no_interim_contact() { ... }
// Assert: 24-month cert has interim_contact_due_date IS NULL

#[tokio::test]
async fn test_renewal_approved_creates_new_cert_and_expires_old() { ... }
// Assert: old cert status = 'expired', new cert status = 'active'

#[tokio::test]
async fn test_list_due_for_renewal_within_90_days() { ... }

#[tokio::test]
async fn test_record_interim_contact_updates_completed_at() { ... }

#[tokio::test]
async fn test_record_interim_contact_on_elderly_disabled_cert_returns_error() { ... }

// change_reports.rs

#[tokio::test]
async fn test_income_above_threshold_sets_requires_redetermination() { ... }
// Mock canopy-persons with wiremock; inject income > 130% FPL.

#[tokio::test]
async fn test_income_below_threshold_does_not_trigger_redetermination() { ... }

#[tokio::test]
async fn test_non_income_change_report_stored_without_redetermination() { ... }