Interface BusinessCalendar

public interface BusinessCalendar

營業行事曆——日期可選性的單一事實來源（ADR-012）

核心抽象是「日期 → DayStatus」的函數。應用層以 Calendars 組合子宣告具名 行事曆（如「配送行事曆」= 政府行事曆 + 週一店休 + 非過去），同一個實例同時服務 兩個消費點，前後端日期限制語意因此不可能漂移：

「事件行事曆」（會議室 / 個人排程：時段粒度、重複規則、衝突偵測）是不同 domain、 不在本抽象範圍；其可與本抽象橋接——把「當天已無空檔」投影成 DayStatus(selectable=false, reasonCode="FULLY_BOOKED") 供日期選擇消費。

Since:
4.0

  • Field Details

  • Method Details

    • statusOf

      DayStatus statusOf(LocalDate date)
      取得指定日期的可選性狀態
      Parameters:
      date - 日期
      Returns:
      DayStatus（含不可選原因）

    • isSelectable

      default boolean isSelectable(LocalDate date)
      指定日期是否可選
      Parameters:
      date - 日期
      Returns:
      可選為 true

    • resolve

      default List<DayStatus> resolve(LocalDate from, LocalDate to)
      解算日期範圍的可選性（前端渲染用）
      Parameters:
      from - 起日（含）
      to - 迄日（含）
      Returns:
      範圍內每一天的 DayStatus（依日期排序）
      Throws:
      IllegalArgumentException - 若 to 早於 from

    • validate

      default void validate(LocalDate date)
      驗證日期可選（提交時的後端權威驗證）
      Parameters:
      date - 日期
      Throws:
      DateNotSelectableException - 日期不可選（由框架錯誤處理映射為 400）

    • plusSelectableDays

      default LocalDate plusSelectableDays(LocalDate from, long days)

      自基準日往後（或往前）數 N 個可選日

      泛化上一代「工作日加減」運算到任何組合後的行事曆：對純政府行事曆即 plusWorkingDays；對組合了店休的配送行事曆則是「加 N 個可配送日」。 days 為負數時往前數；days = 0 回傳基準日本身（不檢查其可選性）。

      Parameters:
      from - 基準日（不計入）
      days - 可選日數（可為負）
      Returns:
      第 N 個可選日
      Throws:
      IllegalStateException - 掃描超過 MAX_SCAN_DAYS 仍未湊滿（前方再無可選日）