demandoverridesep

type CreateDemandOverrideEndpoint struct{}

type CreateDemandOverrideRequest struct {
	// What the override targets.
	//
	// - `item`: a single item.
	// - `product_line`: every item sold under one product line.
	// - `account`: every item in the plan, which is how a blanket assumption such as "plan for double demand" is expressed.
	ScopeType constants.DemandOverrideScope `json:"scope_type" validate:"required"`
	// ID of the item or product line the override targets.
	//
	// Omit it for an `account`-wide override, which targets every planned item rather than one thing. The ID is checked against the account's items and product lines, so an override cannot be created against something that does not exist.
	ScopeRefID string `json:"scope_ref_id,omitzero" validate:"omitempty"`
	// First day of the demand period the override applies to.
	//
	// Overrides are applied month by month, so every calendar month the period touches is adjusted and any time of day is ignored.
	PeriodStartsAt time.Time `json:"period_starts_at" validate:"required"`
	// Last day of the demand period the override applies to.
	//
	// Must fall on or after `period_starts_at`.
	PeriodEndsAt time.Time `json:"period_ends_at" validate:"required"`
	// How the value adjusts the forecast.
	//
	// - `absolute`: replaces the forecast for each month in the period.
	// - `delta_units`: adds the value to each month in the period.
	// - `delta_percent`: scales each month in the period by the value as a percentage.
	//
	// When several overrides land on the same month they are applied in that order, so a percentage always acts on the already-adjusted number.
	Adjustment constants.DemandOverrideAdjustment `json:"adjustment" validate:"required"`
	// The amount of the adjustment, interpreted according to `adjustment`.
	//
	// A `delta_percent` value is a number of percent, so `-25` plans a quarter less than the forecast; it cannot go below `-100`. An `absolute` value cannot be negative, while a `delta_units` value can, so that a cancelled program removes demand.
	Value float64 `json:"value" validate:"required"`
	// ID of the unit the value is expressed in.
	//
	// Recorded for context only: the value is applied to the planned demand without unit conversion, so a unit adjustment should be stated in the unit the item is planned in.
	UnitID field.Optional[string] `json:"unit_id,omitzero"`
	// Why the adjustment was made.
	//
	// The reason is carried into each schedule the override changes, so a plan can explain why a month departs from history.
	Reason field.Optional[constants.DemandOverrideReason] `json:"reason,omitzero"`
	// Free-form notes about the adjustment.
	//
	// This is the text the free-text search on the list endpoint matches against.
	Note field.Optional[string] `json:"note,omitzero" validate:"omitempty,max=2000"`
	// When the override starts being applied to newly generated schedules.
	//
	// When omitted, the override starts applying straight away.
	EffectiveAt field.Optional[time.Time] `json:"effective_at,omitzero"`
	// When the override stops being applied to newly generated schedules.
	//
	// When omitted, the override keeps applying until it is deactivated or deleted.
	ExpiresAt field.Optional[time.Time] `json:"expires_at,omitzero"`
	// Whether the override is taken into account when a schedule is generated.
	//
	// Send `false` to stage an adjustment that should not affect schedules yet; an override is otherwise created ready to apply.
	Active field.Optional[bool] `json:"active,omitzero"`
}

type DeleteDemandOverrideEndpoint struct{}

type DeleteDemandOverrideRequest struct {
	// ID of the demand override.
	DemandOverrideID string `path:"id" validate:"required"`
}

type DemandOverridesSvc interface {
	ListDemandOverrideTypes(ctx context.Context, req *ListDemandOverrideTypesRequest) (*apiresource.List[apiresource.DemandOverrideType], *apierror.APIError)
	ListDemandOverrides(ctx context.Context, req *ListDemandOverridesRequest) (*apiresource.List[apiresource.DemandOverride], *apierror.APIError)
	GetDemandOverride(ctx context.Context, req *RetrieveDemandOverrideRequest) (*apiresource.DemandOverride, *apierror.APIError)
	CreateDemandOverride(ctx context.Context, req *CreateDemandOverrideRequest) (*apiresource.DemandOverride, *apierror.APIError)
	UpdateDemandOverride(ctx context.Context, req *UpdateDemandOverrideRequest) (*apiresource.DemandOverride, *apierror.APIError)
	DeleteDemandOverride(ctx context.Context, req *DeleteDemandOverrideRequest) (*apiresource.EmptyResource, *apierror.APIError)
}

type DemandOverridesSvcConfig struct {
	// CoreClient (required) is the core-service demand-override gRPC client.
	CoreClient pb.CoreDemandOverrideServiceClient
}

type ListDemandOverrideTypesEndpoint struct{}

type ListDemandOverrideTypesRequest struct{}

type ListDemandOverridesEndpoint struct{}

type ListDemandOverridesRequest struct {
	apiresource.PaginationRequest
	// Only return overrides with these kinds of target.
	ScopeTypes []constants.DemandOverrideScope `query:"scope_types"`
	// Only return overrides targeting these items or product lines.
	ScopeRefIDs []string `query:"scope_ref_ids"`
	// Only return overrides making these kinds of adjustment.
	Adjustments []constants.DemandOverrideAdjustment `query:"adjustments"`
	// Only return overrides in these activation states.
	Statuses []constants.ActivationStatus `query:"statuses"`
	// The start of the window to match against. Only return overrides whose period ends on or after this timestamp, formatted as RFC3339.
	PeriodStart *string `query:"starts_at"`
	// The end of the window to match against. Only return overrides whose period starts on or before this timestamp, formatted as RFC3339.
	PeriodEnd *string `query:"ends_at"`
}

type RetrieveDemandOverrideEndpoint struct{}

type RetrieveDemandOverrideRequest struct {
	// ID of the demand override.
	DemandOverrideID string `path:"id" validate:"required"`
}

type UpdateDemandOverrideEndpoint struct{}

type UpdateDemandOverrideRequest struct {
	// ID of the demand override.
	DemandOverrideID string `path:"id" validate:"required"`
	// First day of the demand period the override applies to.
	//
	// Overrides are applied month by month, so every calendar month the period touches is adjusted and any time of day is ignored.
	PeriodStartsAt field.Optional[time.Time] `json:"period_starts_at,omitzero"`
	// Last day of the demand period the override applies to.
	//
	// Must fall on or after the override's start, whether that is sent here or already stored.
	PeriodEndsAt field.Optional[time.Time] `json:"period_ends_at,omitzero"`
	// How the value adjusts the forecast.
	//
	// - `absolute`: replaces the forecast for each month in the period.
	// - `delta_units`: adds the value to each month in the period.
	// - `delta_percent`: scales each month in the period by the value as a percentage.
	Adjustment field.Optional[constants.DemandOverrideAdjustment] `json:"adjustment,omitzero"`
	// The amount of the adjustment, interpreted according to `adjustment`.
	//
	// It is validated against the adjustment the override ends up with, so switching a stored unit delta to `delta_percent` without sending a new value requires the existing value to be a legal percentage.
	Value field.Optional[float64] `json:"value,omitzero"`
	// ID of the unit the value is expressed in.
	//
	// Recorded for context only: the value is applied to the planned demand without unit conversion.
	UnitID field.Clearable[string] `json:"unit_id,omitzero"`
	// Why the adjustment was made.
	//
	// The reason is carried into each schedule the override changes, so a plan can explain why a month departs from history.
	Reason field.Clearable[constants.DemandOverrideReason] `json:"reason,omitzero"`
	// Free-form notes about the adjustment.
	Note field.Clearable[string] `json:"note,omitzero" validate:"omitempty,max=2000"`
	// When the override stops being applied to newly generated schedules.
	//
	// Clear it to keep the override applying until it is deactivated or deleted.
	ExpiresAt field.Clearable[time.Time] `json:"expires_at,omitzero"`
	// Whether the override is taken into account when a schedule is generated.
	//
	// Deactivating parks the override without losing it; it is skipped whatever its effective window says, and can be reactivated later.
	Active field.Optional[bool] `json:"active,omitzero"`
}