Reporting Period Service

This is a medium-complexity shared component that serves as a foundational dependency for both the aggregation pipeline and the export workflow. Because virtually every other data query in the reporting feature is scoped by a reporting period ID, this component should be delivered and tested early in the sprint sequence — it is a blocking dependency even though it carries medium complexity. The createReportingPeriod() and closeReportingPeriod() interfaces suggest an administrative workflow that needs to be coordinated with the product team to define who can create/close periods and whether any approval gates exist. The multi-organization scope (each org maintains its own periods) requires careful testing of period isolation to ensure Organization A's closed period doesn't affect Organization B's active aggregation.

The service wraps the BufdirMetricsRepository for period metadata persistence and exposes a clean domain interface to callers. The isWithinPeriod(date, periodId) method is called frequently during aggregation filtering and should be optimized — consider caching period boundary lookups in memory for the duration of an aggregation run to avoid repeated database reads. The listReportingPeriods(orgId) method supports historical re-aggregation by providing the full period history per organization. The closeReportingPeriod() call should enforce a state machine transition (open → closed) with database-level constraints to prevent mutation of closed-period data.

Ensure period start/end dates are stored and compared in UTC to avoid timezone edge cases when organizations span multiple time zones. The getCurrentReportingPeriod() method needs a defined behavior when no active period exists — return null or throw — document this contract explicitly for callers.