minimum_wage_jp 1.1.0

//! 日本の地域別最低賃金（都道府県別）をシンプルに扱うクレート。
//!
//! 指定日に適用される最低賃金（円）の取得と、時給がそれを満たすかの判定を提供します。
//! データは埋め込み済みで、外部通信や設定ファイルは不要です。
//!
//! # 使い方
//!
//! ```
//! use chrono::NaiveDate;
//! use minimum_wage_jp::{MinimumWageJp, MinimumWageJpCompliance};
//!
//! let date = NaiveDate::from_ymd_opt(2025, 10, 4).unwrap();
//!
//! // 北海道（都道府県コード 1）の 2025-10-04 時点の最低賃金
//! assert_eq!(MinimumWageJp::rate_on_date(date, 1).unwrap(), 1075);
//!
//! // 時給 1020 円は最低賃金を満たさない
//! assert_eq!(
//!     MinimumWageJp::is_compliant_on_date(date, 1, 1020).unwrap(),
//!     MinimumWageJpCompliance::Short { shortage_yen: 55, required_yen: 1075 }
//! );
//! ```
//!
//! # 発効日とフォールバック
//!
//! 最低賃金の発効日は都道府県ごとに異なります（例: 2025 年版は
//! 2025-10-01 の栃木県から 2026-03-31 の秋田県まで分散）。
//! 本クレートは県別の発効日を収録しており、指定日にまだ新年版が発効していない場合は
//! 前年版の額を自動的に返します。データ収録範囲より前の日付は
//! [`MinimumWageJpErr::DatasetNotFoundForDate`] エラーになります。
//!
//! # タイムゾーン
//!
//! [`MinimumWageJp::rate`] と [`MinimumWageJp::is_compliant`] は
//! ローカル日付（[`chrono::Local`]）を使用します。サーバ・クライアント間で
//! タイムゾーンが異なる環境では [`MinimumWageJp::rate_on_date`] /
//! [`MinimumWageJp::is_compliant_on_date`] の使用を推奨します。
//!
//! # データ出典
//!
//! 厚生労働省「[地域別最低賃金の全国一覧](https://www.mhlw.go.jp/stf/seisakunitsuite/bunya/koyou_roudou/roudoukijun/minimumichiran/)」
#![forbid(unsafe_code)]
#![warn(missing_docs)]

mod dataset;

use crate::dataset::all_datasets;
use chrono::NaiveDate;

/// 都道府県コード（JIS X 0401 準拠）
///
/// | コード | 都道府県 | コード | 都道府県 | コード | 都道府県 |
/// |:-----:|:-------|:-----:|:-------|:-----:|:-------|
/// | 1 | 北海道 | 17 | 石川県 | 33 | 岡山県 |
/// | 2 | 青森県 | 18 | 福井県 | 34 | 広島県 |
/// | 3 | 岩手県 | 19 | 山梨県 | 35 | 山口県 |
/// | 4 | 宮城県 | 20 | 長野県 | 36 | 徳島県 |
/// | 5 | 秋田県 | 21 | 岐阜県 | 37 | 香川県 |
/// | 6 | 山形県 | 22 | 静岡県 | 38 | 愛媛県 |
/// | 7 | 福島県 | 23 | 愛知県 | 39 | 高知県 |
/// | 8 | 茨城県 | 24 | 三重県 | 40 | 福岡県 |
/// | 9 | 栃木県 | 25 | 滋賀県 | 41 | 佐賀県 |
/// | 10 | 群馬県 | 26 | 京都府 | 42 | 長崎県 |
/// | 11 | 埼玉県 | 27 | 大阪府 | 43 | 熊本県 |
/// | 12 | 千葉県 | 28 | 兵庫県 | 44 | 大分県 |
/// | 13 | 東京都 | 29 | 奈良県 | 45 | 宮崎県 |
/// | 14 | 神奈川県 | 30 | 和歌山県 | 46 | 鹿児島県 |
/// | 15 | 新潟県 | 31 | 鳥取県 | 47 | 沖縄県 |
/// | 16 | 富山県 | 32 | 島根県 | | |
pub type PrefCode = u8;

#[derive(Debug, Clone)]
pub(crate) struct YearDataset {
    /// 改定年（年版）
    pub year: u16,
    /// この年版で最も早い発効日
    pub effective_from: NaiveDate,
    /// (都道府県コード, 県別発効日, 最低賃金額)
    pub rates: Vec<(PrefCode, NaiveDate, u16)>,
}

/// 最低賃金の適合判定結果
///
/// [`MinimumWageJp::is_compliant`] / [`MinimumWageJp::is_compliant_on_date`] が返します。
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum MinimumWageJpCompliance {
    /// 最低賃金を満たしている
    Compliant,
    /// 最低賃金に不足している
    Short {
        /// 不足額（円）
        shortage_yen: u32,
        /// 必要な最低賃金額（円）
        required_yen: u32,
    },
}

/// エラー時に提示する、参考となる年版の情報
///
/// [`MinimumWageJpErr::DatasetNotFoundForDate`] の `prev` / `next` として、
/// 指定日の前後に適用される年版を示します。
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct MinimumWageJpSuggestion {
    /// 改定年（年版）
    pub year: u16,
    /// 当該都道府県での発効日
    pub effective_from: NaiveDate,
    /// 最低賃金額（円）
    pub rate: u16,
}

/// 本クレートのエラー型
#[derive(thiserror::Error, Debug, Eq, PartialEq)]
pub enum MinimumWageJpErr {
    /// 都道府県コードが 1〜47 の範囲外
    #[error("invalid pref code: {0}")]
    InvalidPrefCode(PrefCode),

    /// 指定日に適用可能なデータが存在しない
    #[error("no dataset found for date {date}; prev={prev:?} next={next:?}")]
    DatasetNotFoundForDate {
        /// 指定した日付
        date: NaiveDate,
        /// 指定日より前に適用されていた年版（存在する場合）
        prev: Option<MinimumWageJpSuggestion>,
        /// 指定日より後に適用される年版（存在する場合）
        next: Option<MinimumWageJpSuggestion>,
    },

    /// 指定年版のデータが存在しない
    #[error("no dataset found for year {year}")]
    DatasetNotFoundForYear {
        /// 指定した改定年
        year: u16,
    },
}

/// 地域別最低賃金の取得・判定を行うエントリポイント
pub struct MinimumWageJp;

impl MinimumWageJp {
    /// ローカル日付（今日）における地域別最低賃金（円）を取得
    ///
    /// [`rate_on_date`](Self::rate_on_date) の今日版です。日付の扱いは
    /// [タイムゾーン](crate#タイムゾーン)を参照してください。
    ///
    /// # Examples
    ///
    /// ```
    /// use minimum_wage_jp::MinimumWageJp;
    ///
    /// // 東京都（13）の今日時点の最低賃金
    /// let rate = MinimumWageJp::rate(13).unwrap();
    /// assert!(rate >= 1163);
    /// ```
    ///
    /// # Errors
    ///
    /// - [`MinimumWageJpErr::InvalidPrefCode`] — `pref` が 1〜47 の範囲外
    /// - [`MinimumWageJpErr::DatasetNotFoundForDate`] — 今日がデータ収録範囲より前
    pub fn rate(pref: PrefCode) -> Result<u16, MinimumWageJpErr> {
        Self::rate_on_date(today(), pref)
    }

    /// ローカル日付（今日）における適合判定を行う
    ///
    /// [`is_compliant_on_date`](Self::is_compliant_on_date) の今日版です。
    ///
    /// # Examples
    ///
    /// ```
    /// use minimum_wage_jp::{MinimumWageJp, MinimumWageJpCompliance};
    ///
    /// // 時給 3000 円は全都道府県で最低賃金を満たす
    /// assert_eq!(
    ///     MinimumWageJp::is_compliant(13, 3000).unwrap(),
    ///     MinimumWageJpCompliance::Compliant
    /// );
    /// ```
    ///
    /// # Errors
    ///
    /// - [`MinimumWageJpErr::InvalidPrefCode`] — `pref` が 1〜47 の範囲外
    /// - [`MinimumWageJpErr::DatasetNotFoundForDate`] — 今日がデータ収録範囲より前
    pub fn is_compliant(
        pref: PrefCode,
        hourly_yen: u32,
    ) -> Result<MinimumWageJpCompliance, MinimumWageJpErr> {
        Self::is_compliant_on_date(today(), pref, hourly_yen)
    }

    /// 指定年版（改定年）・都道府県の最低賃金（円）を取得
    ///
    /// 発効日は考慮せず、その年版に収録されている額をそのまま返します。
    /// 指定日に実際に適用される額が必要な場合は
    /// [`rate_on_date`](Self::rate_on_date) を使用してください。
    ///
    /// # Examples
    ///
    /// ```
    /// use minimum_wage_jp::MinimumWageJp;
    ///
    /// assert_eq!(MinimumWageJp::rate_for_revision(2024, 13).unwrap(), 1163);
    /// assert_eq!(MinimumWageJp::rate_for_revision(2025, 13).unwrap(), 1226);
    /// ```
    ///
    /// # Errors
    ///
    /// - [`MinimumWageJpErr::InvalidPrefCode`] — `pref` が 1〜47 の範囲外
    /// - [`MinimumWageJpErr::DatasetNotFoundForYear`] — `year` の年版が未収録
    pub fn rate_for_revision(year: u16, pref: PrefCode) -> Result<u16, MinimumWageJpErr> {
        check_pref(pref)?;
        let ds = all_datasets()
            .iter()
            .find(|d| d.year == year)
            .ok_or(MinimumWageJpErr::DatasetNotFoundForYear { year })?;
        Ok(pref_entry(ds, pref)?.2)
    }

    /// 指定日における地域別最低賃金（円）を取得
    ///
    /// 指定日に当該都道府県でまだ新年版が発効していない場合は前年版の額を返します。
    ///
    /// # Examples
    ///
    /// ```
    /// use chrono::NaiveDate;
    /// use minimum_wage_jp::MinimumWageJp;
    ///
    /// // 東京都（13）の 2025 年版発効日は 2025-10-03
    /// let before = NaiveDate::from_ymd_opt(2025, 10, 2).unwrap();
    /// let after = NaiveDate::from_ymd_opt(2025, 10, 3).unwrap();
    /// assert_eq!(MinimumWageJp::rate_on_date(before, 13).unwrap(), 1163);
    /// assert_eq!(MinimumWageJp::rate_on_date(after, 13).unwrap(), 1226);
    /// ```
    ///
    /// # Errors
    ///
    /// - [`MinimumWageJpErr::InvalidPrefCode`] — `pref` が 1〜47 の範囲外
    /// - [`MinimumWageJpErr::DatasetNotFoundForDate`] — `date` がデータ収録範囲より前
    ///   （前年版が存在せずフォールバックできない場合を含む。次に適用される年版を
    ///   [`MinimumWageJpSuggestion`] として提示）
    pub fn rate_on_date(date: NaiveDate, pref: PrefCode) -> Result<u16, MinimumWageJpErr> {
        check_pref(pref)?;
        let Some(ds) = dataset_prev_or_equal(date) else {
            return Err(MinimumWageJpErr::DatasetNotFoundForDate {
                date,
                prev: None,
                next: dataset_next_after(date).and_then(|n| suggestion_for(n, pref)),
            });
        };

        let (_, eff, rate) = pref_entry(ds, pref)?;
        if date >= eff {
            return Ok(rate);
        }

        // 当該県の発効日前は直前の年版へフォールバック
        match dataset_prev_before(ds.effective_from) {
            Some(prev) => Ok(pref_entry(prev, pref)?.2),
            // 前年版が無い場合、未発効の額をそのまま返さずエラーとする
            None => Err(MinimumWageJpErr::DatasetNotFoundForDate {
                date,
                prev: None,
                next: Some(MinimumWageJpSuggestion {
                    year: ds.year,
                    effective_from: eff,
                    rate,
                }),
            }),
        }
    }

    /// 指定日における適合判定を行う（不足額つき）
    ///
    /// # Examples
    ///
    /// ```
    /// use chrono::NaiveDate;
    /// use minimum_wage_jp::{MinimumWageJp, MinimumWageJpCompliance};
    ///
    /// let date = NaiveDate::from_ymd_opt(2025, 10, 3).unwrap();
    ///
    /// // 東京都（13）の 2025-10-03 時点の最低賃金は 1226 円
    /// assert_eq!(
    ///     MinimumWageJp::is_compliant_on_date(date, 13, 1226).unwrap(),
    ///     MinimumWageJpCompliance::Compliant
    /// );
    /// assert_eq!(
    ///     MinimumWageJp::is_compliant_on_date(date, 13, 1200).unwrap(),
    ///     MinimumWageJpCompliance::Short { shortage_yen: 26, required_yen: 1226 }
    /// );
    /// ```
    ///
    /// # Errors
    ///
    /// - [`MinimumWageJpErr::InvalidPrefCode`] — `pref` が 1〜47 の範囲外
    /// - [`MinimumWageJpErr::DatasetNotFoundForDate`] — `date` がデータ収録範囲より前
    pub fn is_compliant_on_date(
        date: NaiveDate,
        pref: PrefCode,
        hourly_yen: u32,
    ) -> Result<MinimumWageJpCompliance, MinimumWageJpErr> {
        let required_yen = u32::from(Self::rate_on_date(date, pref)?);
        if hourly_yen >= required_yen {
            Ok(MinimumWageJpCompliance::Compliant)
        } else {
            Ok(MinimumWageJpCompliance::Short {
                shortage_yen: required_yen - hourly_yen,
                required_yen,
            })
        }
    }
}

/// ローカル日付（NaiveDate）を返す
fn today() -> NaiveDate {
    chrono::Local::now().date_naive()
}

fn check_pref(pref: PrefCode) -> Result<(), MinimumWageJpErr> {
    if (1..=47).contains(&pref) {
        Ok(())
    } else {
        Err(MinimumWageJpErr::InvalidPrefCode(pref))
    }
}

/// 年版データから当該都道府県のエントリを取り出す
fn pref_entry(
    ds: &YearDataset,
    pref: PrefCode,
) -> Result<(PrefCode, NaiveDate, u16), MinimumWageJpErr> {
    ds.rates
        .iter()
        .find(|(p, _, _)| *p == pref)
        .copied()
        .ok_or(MinimumWageJpErr::InvalidPrefCode(pref))
}

fn suggestion_for(ds: &YearDataset, pref: PrefCode) -> Option<MinimumWageJpSuggestion> {
    ds.rates
        .iter()
        .find(|(p, _, _)| *p == pref)
        .map(|&(_, effective_from, rate)| MinimumWageJpSuggestion {
            year: ds.year,
            effective_from,
            rate,
        })
}

/// 指定日以前に開始した最新の年版を返す
fn dataset_prev_or_equal(date: NaiveDate) -> Option<&'static YearDataset> {
    all_datasets()
        .iter()
        .take_while(|ds| ds.effective_from <= date)
        .last()
}

/// 指定日より後に開始する最初の年版を返す
fn dataset_next_after(date: NaiveDate) -> Option<&'static YearDataset> {
    all_datasets().iter().find(|ds| ds.effective_from > date)
}

/// 指定された開始日より前に開始した最新の年版を返す
fn dataset_prev_before(effective_from: NaiveDate) -> Option<&'static YearDataset> {
    all_datasets()
        .iter()
        .take_while(|ds| ds.effective_from < effective_from)
        .last()
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::dataset::nd;

    /// 各年版のデータ整合性（47都道府県・重複なし・発効日と額の妥当性）
    #[test]
    fn test_dataset_integrity() {
        let datasets = all_datasets();
        assert!(!datasets.is_empty());

        for w in datasets.windows(2) {
            assert!(w[0].year < w[1].year, "years must be ascending");
            assert!(
                w[0].effective_from < w[1].effective_from,
                "effective_from must be ascending"
            );
        }

        for ds in datasets {
            let mut prefs: Vec<PrefCode> = ds.rates.iter().map(|(p, _, _)| *p).collect();
            prefs.sort_unstable();
            assert_eq!(
                prefs,
                (1..=47).collect::<Vec<PrefCode>>(),
                "year {} must contain all 47 prefectures exactly once",
                ds.year
            );

            let min_eff = ds.rates.iter().map(|(_, e, _)| *e).min().unwrap();
            assert_eq!(
                ds.effective_from, min_eff,
                "year {}: effective_from must equal the earliest prefecture date",
                ds.year
            );

            for (p, eff, rate) in &ds.rates {
                assert!(
                    *rate > 0,
                    "year {} pref {}: rate must be positive",
                    ds.year,
                    p
                );
                assert!(
                    *eff >= ds.effective_from,
                    "year {} pref {}: date before dataset start",
                    ds.year,
                    p
                );
            }
        }
    }

    #[test]
    fn test_rate_for_revision() {
        assert_eq!(MinimumWageJp::rate_for_revision(2024, 13).unwrap(), 1163);
        assert_eq!(MinimumWageJp::rate_for_revision(2025, 1).unwrap(), 1075);
        assert_eq!(MinimumWageJp::rate_for_revision(2025, 13).unwrap(), 1226);
        assert_eq!(MinimumWageJp::rate_for_revision(2025, 47).unwrap(), 1023);
        assert_eq!(
            MinimumWageJp::rate_for_revision(2020, 1).unwrap_err(),
            MinimumWageJpErr::DatasetNotFoundForYear { year: 2020 }
        );
    }

    #[test]
    fn test_rate_on_date() {
        // 全国一斉日に発効する県はその日から新額
        assert_eq!(
            MinimumWageJp::rate_on_date(nd(2024, 10, 1), 13).unwrap(),
            1163
        );
        // 東京の 2025 年版発効日は 2025-10-03
        assert_eq!(
            MinimumWageJp::rate_on_date(nd(2025, 10, 2), 13).unwrap(),
            1163
        );
        assert_eq!(
            MinimumWageJp::rate_on_date(nd(2025, 10, 3), 13).unwrap(),
            1226
        );
        // 北海道の 2025 年版発効日は 2025-10-04
        assert_eq!(
            MinimumWageJp::rate_on_date(nd(2025, 10, 2), 1).unwrap(),
            1010
        );
        assert_eq!(
            MinimumWageJp::rate_on_date(nd(2025, 10, 4), 1).unwrap(),
            1075
        );
        // 秋田の 2025 年版発効日は 2026-03-31（年度をまたぐフォールバック）
        assert_eq!(
            MinimumWageJp::rate_on_date(nd(2026, 3, 30), 5).unwrap(),
            951
        );
        assert_eq!(
            MinimumWageJp::rate_on_date(nd(2026, 3, 31), 5).unwrap(),
            1031
        );
        // 最新年版の発効日以降はその額のまま
        assert_eq!(
            MinimumWageJp::rate_on_date(nd(2030, 1, 1), 13).unwrap(),
            1226
        );
    }

    /// 収録範囲より前の日付はエラー（次に適用される年版を提示）
    #[test]
    fn test_rate_on_date_before_first_dataset() {
        assert_eq!(
            MinimumWageJp::rate_on_date(nd(2024, 9, 30), 13).unwrap_err(),
            MinimumWageJpErr::DatasetNotFoundForDate {
                date: nd(2024, 9, 30),
                prev: None,
                next: Some(MinimumWageJpSuggestion {
                    year: 2024,
                    effective_from: nd(2024, 10, 1),
                    rate: 1163,
                }),
            }
        );
    }

    /// 最初の年版の発効日前（前年版なし）は未発効の額を返さずエラー
    #[test]
    fn test_rate_on_date_before_pref_effective_without_prev() {
        // 岩手の 2024 年版発効日は 2024-10-27
        assert_eq!(
            MinimumWageJp::rate_on_date(nd(2024, 10, 15), 3).unwrap_err(),
            MinimumWageJpErr::DatasetNotFoundForDate {
                date: nd(2024, 10, 15),
                prev: None,
                next: Some(MinimumWageJpSuggestion {
                    year: 2024,
                    effective_from: nd(2024, 10, 27),
                    rate: 952,
                }),
            }
        );
        assert_eq!(
            MinimumWageJp::rate_on_date(nd(2024, 10, 27), 3).unwrap(),
            952
        );
    }

    #[test]
    fn test_is_compliant_on_date() {
        // 東京 2025-10-03（発効日当日）
        assert_eq!(
            MinimumWageJp::is_compliant_on_date(nd(2025, 10, 3), 13, 1226).unwrap(),
            MinimumWageJpCompliance::Compliant
        );
        assert_eq!(
            MinimumWageJp::is_compliant_on_date(nd(2025, 10, 3), 13, 1225).unwrap(),
            MinimumWageJpCompliance::Short {
                shortage_yen: 1,
                required_yen: 1226
            }
        );
        // 北海道 2025-10-03（発効日前は前年版 1010 円で判定）
        assert_eq!(
            MinimumWageJp::is_compliant_on_date(nd(2025, 10, 3), 1, 1010).unwrap(),
            MinimumWageJpCompliance::Compliant
        );
        assert_eq!(
            MinimumWageJp::is_compliant_on_date(nd(2025, 10, 4), 1, 1020).unwrap(),
            MinimumWageJpCompliance::Short {
                shortage_yen: 55,
                required_yen: 1075
            }
        );

        // 2025 年版が全県発効済みの日付では、全県 1000 円は不足・3000 円は適合
        for pref in 1..=47 {
            assert!(matches!(
                MinimumWageJp::is_compliant_on_date(nd(2026, 4, 1), pref, 1000).unwrap(),
                MinimumWageJpCompliance::Short { .. }
            ));
            assert_eq!(
                MinimumWageJp::is_compliant_on_date(nd(2026, 4, 1), pref, 3000).unwrap(),
                MinimumWageJpCompliance::Compliant
            );
        }
    }

    #[test]
    fn test_invalid_pref_code() {
        for pref in [0, 48, 255] {
            assert_eq!(
                MinimumWageJp::rate_for_revision(2025, pref).unwrap_err(),
                MinimumWageJpErr::InvalidPrefCode(pref)
            );
            assert_eq!(
                MinimumWageJp::rate_on_date(nd(2025, 10, 1), pref).unwrap_err(),
                MinimumWageJpErr::InvalidPrefCode(pref)
            );
        }
    }

    /// today 系 API はデータ収録範囲内の現在日付なら常に成功する
    #[test]
    fn test_today_apis() {
        for pref in 1..=47 {
            assert!(MinimumWageJp::rate(pref).is_ok());
            assert!(MinimumWageJp::is_compliant(pref, 1000).is_ok());
        }
    }

    #[test]
    fn test_error_display() {
        assert_eq!(
            MinimumWageJpErr::InvalidPrefCode(48).to_string(),
            "invalid pref code: 48"
        );
        assert_eq!(
            MinimumWageJpErr::DatasetNotFoundForYear { year: 2020 }.to_string(),
            "no dataset found for year 2020"
        );
    }
}