date-aware rates

@see also payroll-and-invoicing.md and location_geo.md files

Location (geo) rates

CATS-591 and related called for the ability to create rate values for specific locations. The rate values should be assigned to dates for which the rate becomes effective.

Example

Location	EffectiveDate	Rate
NY_Manhattan	Jan 1, 2021	$120
NY_Manhattan	Jan 1, 2022	$125
NC_Raleigh	Jan 5, 2021	$100
NC_Raleigh	Jan 1, 2022	$110

Shifts scheduled for a hospital in NY_Manhattan location during Jan 1 - Dec 31, 2021 would have a ‘base rate’ (used as initial starting point for calculations) of $120. Any shift starting on or after Jan 1, 2022 would have a ‘base rate’ of $125.

technical

This is achieved with a ‘location_rates’ table

create table location_rates
(
    id               serial primary key,
    core_id          varchar(255) not null,
    location_core_id varchar(255) not null,
    effective_date   date         not null,
    rate             double precision,
    actor_id         varchar(255),
    note             text,
    deleted_at       timestamp(0),
    created_at       timestamp(0),
    updated_at       timestamp(0)
);

RateService has a number of internal methods

getAllGeoRateAt
getAllGeoRateNow
getGeoRateAt
getGeoRateNow
getHospitalGeoRateAt
getHospitalGeoRateNow
getLocationRateObjectAt
getShiftGeoRate
getShiftGeoRateAt
insertGeoRateAt
insertGeoRateNow
getRateForShift

which all take a carbon date or the ‘now’ current date/time.

Hospital site overrides

CATS-597 and CATS-598 describe wanting the ability to set individual hospital rate override values (currently possible), but in a date-aware fashion (currently not possible).

CATS-598 describes wanting the ability to set a date when an override would ‘stop’ being effective, with the goal of the original location rate taking effect again.

CATS-597 describes wanting a ‘site rate override’ to be similar to the ‘employee rate override’ behaviour. However, wanting a ‘stop override date’, from 598, is incompatible with this notion of ‘behave like other date-aware rates’.

Every other date-aware rate has no end date - we just have “effective date”, and whatever the current ‘effective date’ rate is wins.

To accomodate 598, this will need to have an ‘end date’ for each site-specific override. The ‘end date’ maybe null (as in ‘unknown’) when it’s created, but the ‘end override date’ means that the site override date object would need to be editable (at least the end date). It might need to be able to look for conflicts with other future dates, and prevent dates prior to the start date.

The UI for individual site overrides will need an overhaul.

technical

To achieve this, we’ll need a site_rates table, similar to location_rates, but with a nullable end_date.

12/7/21

php artisan fix:cats-591

This script will migrate the earlier ‘bi’ data to location_rate. In anticipation of site_rate perhaps not being done, the script will also reset the overridden hospital/site rate by modifying the hourly_rate field.

If date-aware site_rate work can be done then the ‘hourly_rate’ value wouldn’t be looked at anyway, and the deletion is moot.
The deletion value would be captured in activity log, but clearing out the value regardless may be useful from a integrity POV.

12/8/21

getRateForShift() is a combined call to get the ‘real’ base rate for a shift, which will use a site override if it’s applicable, or use the site’s location rate that’s applicable for the shift’s start_time.