Calendar (CAL)

The cal submodule of com provides the calendar primitives the rest of the ERP uses for date arithmetic that needs to skip weekends, holidays, and unavailable delivery slots. It owns the Calendar and CalendarEntry reference data and exposes a "move business days" service that shifts a date forward or backward by a given number of business days while honouring the calendar’s holiday entries and per-day delivery-slot rules. The submodule depends only on the sys term types.

Concepts

Calendar: A named time-line owned by some domain object (a country, a warehouse, a supplier). Multiple calendars can coexist; callers pick which one to consult.
Calendar Type: A reference type that classifies calendars. Each type has an interval type that says whether its entries describe periods of availability or unavailability.
Calendar Entry: A dated period attached to a calendar. Depending on the calendar’s interval type, the entry represents a working interval or a closed interval (typically a holiday).
Business Day: A day on which work is performed. Whether weekends or holidays count as business days is decided per move request.
Delivery Slot: A weekday-of-week marker (IsWeekDaySlot) that callers can pass into a move request to skip days that do not match any of their valid weekday slots.
Move Direction: Forward or backward — selects whether the calculated end date sits after or before the start date.

Entities

Calendar Type (`CalendarType`)

A classification of calendars. Carries the interval semantics for every entry of a calendar of this type.

Field Description

Field	Description
`code`	Business key (up to 8 characters).
`description`	Human-readable name.
`intervalType`	Whether entries describe Available or Unavailable periods. Default `U`.

code

Business key (up to 8 characters).

description

Human-readable name.

intervalType

Whether entries describe Available or Unavailable periods. Default U.

Calendar Interval Types (`CalendarIntervalType`)

Code Name Meaning

Code	Name	Meaning
`A`	Available	Entries describe periods that are working/open; the rest of the time is closed.
`U`	Unavailable	Entries describe periods that are closed/holidays; the rest of the time is working.

A

Available

Entries describe periods that are working/open; the rest of the time is closed.

U

Unavailable

Entries describe periods that are closed/holidays; the rest of the time is working.

Calendar (`Calendar`)

A named calendar attached (loosely) to a domain object such as a country, warehouse, or supplier.

Field Description

Field	Description
`code`	Business key (up to 20 characters).
`calendarType`	The type of calendar (Available or Unavailable interval semantics).
`domainEntityType`	Optional domain-object class name the calendar belongs to.
`domainEntityKey`	Optional domain-object id.
`domainEntityCode`	Optional domain-object business code (used for searching).

code

Business key (up to 20 characters).

calendarType

The type of calendar (Available or Unavailable interval semantics).

domainEntityType

Optional domain-object class name the calendar belongs to.

domainEntityKey

Optional domain-object id.

domainEntityCode

Optional domain-object business code (used for searching).

Calendar Entry (`CalendarEntry`)

A dated period within a calendar. The aggregate is parented on the calendar.

Field Description

Field	Description
`calendar`	Owning calendar (composite business key with `firstDate`).
`firstDate`	Inclusive start of the period (a `PlanDate`).
`lastDate`	Optional inclusive end of the period; absent means the entry is single-day.

calendar

Owning calendar (composite business key with firstDate).

firstDate

Inclusive start of the period (a PlanDate).

lastDate

Optional inclusive end of the period; absent means the entry is single-day.

Functionality

Period overlap query

COM_CAL_QueryApi.findEntriesOverlappingPeriod returns every CalendarEntry of a calendar whose [firstDate, lastDate] overlaps the supplied DatePeriod. Used by callers that need to enumerate the holiday entries that touch a given window — typically to display them or to short-circuit calendar checks.

Move-business-days

The flagship operation. COM_CAL_QueryApi.moveBusinessDays advances a start date by a number of business days, walking one calendar day at a time and counting only those days that pass the request’s filters. The same call works for any DomainDate subtype.

A move request specifies:

Field Description

Field	Description
`holidayCalendar`	The calendar whose entries are consulted for holidays.
`moveStartDate`	The start date to walk away from.
`moveBusinessDays`	Number of business days to count (must be non-negative).
`moveDirection`	`FORWARD` (toward the future) or `BACKWARD` (toward the past).
`weekend`	Whether weekends are business days (`WEEKEND_IS_BUSINESSDAY`) or holidays (`WEEKEND_IS_HOLIDAY`).
`holiday`	Whether calendar holiday entries are business days (`HOLIDAY_IS_BUSINESSDAY`) or not (`HOLIDAY_NOT_A_BUSINESSDAY`).
`deliverySlots`	Optional list of `IsWeekDaySlot` markers; days whose weekday matches none of these slots are skipped.

holidayCalendar

The calendar whose entries are consulted for holidays.

moveStartDate

The start date to walk away from.

moveBusinessDays

Number of business days to count (must be non-negative).

moveDirection

FORWARD (toward the future) or BACKWARD (toward the past).

weekend

Whether weekends are business days (WEEKEND_IS_BUSINESSDAY) or holidays (WEEKEND_IS_HOLIDAY).

holiday

Whether calendar holiday entries are business days (HOLIDAY_IS_BUSINESSDAY) or not (HOLIDAY_NOT_A_BUSINESSDAY).

deliverySlots

Optional list of IsWeekDaySlot markers; days whose weekday matches none of these slots are skipped.

The result carries the start request, the computed end date, and a textual move description (for audit/logging). Callers can ask whether the date actually moved.

When moveBusinessDays is positive the start date itself is treated as a business day; when it is zero the start date is returned only if it is itself a valid business day.

Date helpers

COM_CAL_Util is a thin static facade for a handful of date operations that do not need the database:

Helper Effect

Helper	Effect
`moveToDayOfWeekAfterDate(start, dow)`	Returns the first occurrence of the given day-of-week strictly after `start`.
`moveToDayOfWeekBeforeDate(start, dow)`	Returns the latest occurrence of the given day-of-week strictly before `start`.
`moveToDayOfWeekForward(start, dow, …)`	Returns the first occurrence of `dow` on or after `start`.
`moveToDayOfWeekBackward(start, dow, …)`	Returns the latest occurrence of `dow` on or before `start`.
`plusWeeks(reason, start, weeks, report)`	Adds whole weeks to the date, optionally appending a line to an `HtmlReport`.
`minusWeeks(reason, start, weeks, report)`	Subtracts whole weeks, optionally with a report line.

moveToDayOfWeekAfterDate(start, dow)

Returns the first occurrence of the given day-of-week strictly after start.

moveToDayOfWeekBeforeDate(start, dow)

Returns the latest occurrence of the given day-of-week strictly before start.

moveToDayOfWeekForward(start, dow, …)

Returns the first occurrence of dow on or after start.

moveToDayOfWeekBackward(start, dow, …)

Returns the latest occurrence of dow on or before start.

plusWeeks(reason, start, weeks, report)

Adds whole weeks to the date, optionally appending a line to an HtmlReport.

minusWeeks(reason, start, weeks, report)

Subtracts whole weeks, optionally with a report line.

Plan-week constants

Plan weeks run from Monday to Sunday by convention. The two constants FIRST_DAY_OF_PLANWEEK = MONDAY and LAST_DAY_OF_PLANWEEK = SUNDAY on COM_CAL_Constant are the source of truth for any caller that needs to know where a plan week begins or ends. By the same convention, ex-mill is always Sunday and ex-works is the next working day (typically Monday).

Public API

`COM_CAL_QueryApi`

Read-side facade.

Method Description

Method	Description
`findEntriesOverlappingPeriod(Calendar, DatePeriod<PlanDate>)`	Calendar entries that overlap the given period.
`moveBusinessDays(CalendarRequest<T>)`	Shifts a date by a number of business days, honouring weekends, holidays, and delivery slots.

findEntriesOverlappingPeriod(Calendar, DatePeriod<PlanDate>)

Calendar entries that overlap the given period.

moveBusinessDays(CalendarRequest<T>)

Shifts a date by a number of business days, honouring weekends, holidays, and delivery slots.

`COM_CAL_CommandApi`

This submodule does not provide a command API class. Calendars and calendar entries are maintained through the standard CRUD UI, not through a cross-module write seam.

`COM_CAL_Util`

Static utility (see Date helpers above).

`IsWeekDaySlot` extension

IsWeekDaySlot is the seam used to plug delivery-slot constraints into a move request. Any module that owns weekday slots (delivery windows, shift definitions, …) can implement the interface so its rows are accepted by CalendarRequest.create.

ViewModel actions

The submodule defines view models for Calendar, CalendarType, and CalendarEntry but does not declare any custom UI actions.

Calendar (CAL)

Concepts

Entities

Calendar Type (CalendarType)

Calendar Interval Types (CalendarIntervalType)

Calendar (Calendar)

Calendar Entry (CalendarEntry)

Functionality

Period overlap query

Move-business-days

Date helpers

Plan-week constants

Public API

COM_CAL_QueryApi

COM_CAL_CommandApi

COM_CAL_Util

IsWeekDaySlot extension

ViewModel actions

Calendar Type (`CalendarType`)

Calendar Interval Types (`CalendarIntervalType`)

Calendar (`Calendar`)

Calendar Entry (`CalendarEntry`)

`COM_CAL_QueryApi`

`COM_CAL_CommandApi`

`COM_CAL_Util`

`IsWeekDaySlot` extension