@kernhq/module-hr 0.18.1 → 0.20.0

package/src/contract/rosters.ts

@@ -0,0 +1,156 @@
+import { Timestamp, WorkspaceId } from '@kernhq/contracts'
+import { z } from 'zod'
+import { IsoDate, WallClock } from './models.js'
+
+const ws = { workspaceId: WorkspaceId }
+
+/**
+ * Rosters: which shift a person works on a **date**.
+ *
+ * A `Schedule` is a week that repeats for ever, so `ScheduleWeek` is keyed by weekday name. That is
+ * the right shape for an office and cannot express a factory: 4-on-4-off has no weekly period at
+ * all, and neither does any 2- or 3-week rotation, so there is no length of `ScheduleWeek` that
+ * describes one. A roster is keyed by the calendar instead, and adds exactly three things a
+ * schedule does not have:
+ *
+ * - **A shift on a date.** The key is the day, not a modulus of seven.
+ * - **Coverage** — "who is on Early on Tuesday" is a question about an office-day, not about a
+ *   person, and it cannot be asked of a set of weekly schedules without walking everybody's week.
+ * - **A one-day exception that survives.** A schedule change is effective-dated and rewrites every
+ *   day after it; a roster override changes one day and leaves the rotation alone.
+ *
+ * Everything else attendance already does — grace, rounding, overnight shifts, night-shift business
+ * date attribution, the auto-close sweep — stays where it is. A roster is not a second computation
+ * of hours; it is a different answer to "what was this person meant to work today".
+ *
+ * **The rotation is computed, never stored per day.** A `RosterPattern` is a cycle of days and the
+ * date `days[0]` falls on; what somebody works on any date at all is arithmetic from those two.
+ * Generating a year of rows per person is what makes a roster impossible to change afterwards —
+ * moving a crew forward by a day becomes a bulk rewrite of thousands of rows with no way to say
+ * which of them a human had touched. Only the exceptions are rows.
+ */
+
+/**
+ * A named shift: Early, Late, Night.
+ *
+ * Named rather than inlined into each pattern because coverage groups by it — "Early" in the
+ * warehouse pattern and "Early" in the picking pattern have to be the same column of the same grid.
+ * `graceInMinutes` / `graceOutMinutes` sit here rather than on the schedule for the same reason a
+ * night shift usually has a wider grace than a day one: they are properties of the shift.
+ */
+export const RosterShift = z.object({
+  id: z.uuid(),
+  ...ws,
+  name: z.string().min(1).max(80),
+  /** A one- or two-letter code, for a grid too dense to carry a name. */
+  code: z.string().max(8).nullable(),
+  start: WallClock,
+  /** Earlier than `start` for a shift that ends the next morning — the same rule `ShiftSpec` uses. */
+  end: WallClock,
+  breakMinutes: z.number().int().min(0).max(480),
+  graceInMinutes: z.number().int().min(0).max(240),
+  graceOutMinutes: z.number().int().min(0).max(240),
+  color: z.string().max(32).nullable(),
+  archivedAt: Timestamp.nullable(),
+})
+export type RosterShift = z.infer<typeof RosterShift>
+
+/**
+ * One position in a rotation: the shifts worked on that day of the cycle.
+ *
+ * An **array**, so a split shift — 06:00–10:00 and 16:00–20:00, ordinary in hospitality — is a
+ * cycle day with two entries rather than something the model forbids. An empty array is a rest day,
+ * which is a different fact from "nothing is rostered": a rest day is planned.
+ */
+export const RosterCycleDay = z.array(z.uuid()).max(4)
+export type RosterCycleDay = z.infer<typeof RosterCycleDay>
+
+/**
+ * A rotation, as a cycle and the date it starts from.
+ *
+ * The cycle length is `days.length` and is not stored separately — two numbers that must agree is
+ * one number and a bug. `anchorDate` is the date `days[0]` applies to; every other date is
+ * `(dayNumber(date) - dayNumber(anchorDate) + cycleOffset) mod days.length`, which answers for
+ * dates before the anchor as readily as after it.
+ */
+export const RosterPattern = z.object({
+  id: z.uuid(),
+  ...ws,
+  name: z.string().min(1).max(120),
+  /** The date `days[0]` falls on. Moving it rotates every assignment on this pattern at once. */
+  anchorDate: IsoDate,
+  days: z.array(RosterCycleDay).min(1).max(56),
+  archivedAt: Timestamp.nullable(),
+})
+export type RosterPattern = z.infer<typeof RosterPattern>
+
+/**
+ * A person on a rotation, over a period.
+ *
+ * Effective-dated like every other assignment here, and at most one may be in force on a day — the
+ * exclusion constraint in migration 0012 is what guarantees that rather than the handler, because
+ * two concurrent requests cannot both win against a constraint.
+ *
+ * `cycleOffset` is what puts two crews on one pattern out of phase: crew B on a 4-on-4-off cycle
+ * with `cycleOffset: 4` works exactly the days crew A is off. Without it every crew needs its own
+ * copy of the same rotation, and a change to the rotation has to be made once per crew.
+ */
+export const RosterAssignment = z.object({
+  id: z.uuid(),
+  ...ws,
+  personId: z.uuid(),
+  patternId: z.uuid(),
+  effectiveFrom: IsoDate,
+  effectiveTo: IsoDate.nullable(),
+  cycleOffset: z.number().int().min(0).max(55),
+  createdAt: Timestamp,
+})
+export type RosterAssignment = z.infer<typeof RosterAssignment>
+
+/**
+ * Where a rostered day came from.
+ *
+ * `none` is not the same as a rest day: it means nothing rosters this person on this date at all,
+ * and a screen that renders it identically to a planned day off is telling somebody their absence
+ * was intended. A rest day is `pattern` with no shifts.
+ */
+export const RosterDaySource = z.enum(['pattern', 'override', 'none'])
+export type RosterDaySource = z.infer<typeof RosterDaySource>
+
+export const RosterDay = z.object({
+  personId: z.uuid(),
+  businessDate: IsoDate,
+  shifts: z.array(RosterShift),
+  source: RosterDaySource,
+  /** Why this day differs from the rotation. Only ever set on an override. */
+  note: z.string().max(500).nullable(),
+})
+export type RosterDay = z.infer<typeof RosterDay>
+
+/** Enough of a person to fill a coverage grid. The name every member may already read. */
+export const RosterPerson = z.object({ personId: z.uuid(), displayName: z.string() })
+export type RosterPerson = z.infer<typeof RosterPerson>
+
+/**
+ * One office-day, which is the question a roster exists to answer.
+ *
+ * `off` carries the people a pattern covers on this date and does not put on a shift — the answer
+ * to "who could I call in", which is the second thing anybody looking at a coverage grid wants and
+ * the one a list of who is working cannot give.
+ */
+export const RosterCoverageDay = z.object({
+  businessDate: IsoDate,
+  slots: z.array(z.object({ shift: RosterShift, people: z.array(RosterPerson) })),
+  off: z.array(RosterPerson),
+})
+export type RosterCoverageDay = z.infer<typeof RosterCoverageDay>
+
+/**
+ * How long a roster range may be.
+ *
+ * Expansion is arithmetic and cheap; the cost is the person-days a coverage grid resolves and the
+ * size of what comes back. A quarter covers the longest rotation anybody plans by hand, and
+ * coverage is capped tighter because it multiplies by the population of an office.
+ */
+export const MAX_ROSTER_DAYS = 186
+export const MAX_COVERAGE_DAYS = 42

package/src/contract/router.ts

@@ -18,6 +18,7 @@ import {
   ScheduleAssignment,
   ScheduleWeek,
 } from './attendance.js'
+import { PayrollExport, PayrollExportPreview } from './exports.js'
 import {
   DayPart,
   LeaveBalance,
@@ -51,6 +52,7 @@ import {
   RegionCode,
   ResolvedCalendarDay,
   TimeZone,
+  WallClock,
   WorkingWeek,
 } from './models.js'
 import {
@@ -76,6 +78,14 @@ import {
   OvertimeReport,
   ReportSliceBy,
 } from './reports.js'
+import {
+  RosterAssignment,
+  RosterCoverageDay,
+  RosterCycleDay,
+  RosterDay,
+  RosterPattern,
+  RosterShift,
+} from './rosters.js'
 
 const ws = z.object({ workspaceId: WorkspaceId })
 const t = ['hr'] as const
@@ -973,6 +983,180 @@ export const hrContract = {
     },
   },
 
+  // ---------------------------------------------------------------- rosters
+  /**
+   * Who works which shift on which **date**.
+   *
+   * Separate from `attendance.schedules` rather than folded into it, because the two answer
+   * different questions and only one of them has a weekly period. A schedule is a week that repeats
+   * for ever; a rotation is a cycle of any length anchored to a date, which is the only shape
+   * 4-on-4-off has. Nothing here recomputes hours — grace, rounding, overnight attribution and the
+   * auto-close sweep all stay in attendance, and a roster only decides what the day was meant to be.
+   */
+  rosters: {
+    shifts: {
+      list: baseContract
+        .route({ method: 'GET', path: '/rosters/shifts', tags: t })
+        .input(ws.extend({ includeArchived: z.boolean().default(false) }))
+        .output(z.array(RosterShift)),
+      create: baseContract
+        .route({ method: 'POST', path: '/rosters/shifts', tags: t })
+        .input(
+          ws.extend({
+            name: z.string().min(1).max(80),
+            code: z.string().max(8).nullish(),
+            start: WallClock,
+            end: WallClock,
+            breakMinutes: z.number().int().min(0).max(480).default(0),
+            graceInMinutes: z.number().int().min(0).max(240).default(0),
+            graceOutMinutes: z.number().int().min(0).max(240).default(0),
+            color: z.string().max(32).nullish(),
+          }),
+        )
+        .output(RosterShift),
+      update: baseContract
+        .route({ method: 'PATCH', path: '/rosters/shifts/{shiftId}', tags: t })
+        .input(
+          ws.extend({
+            shiftId: z.uuid(),
+            name: z.string().min(1).max(80).optional(),
+            code: z.string().max(8).nullish(),
+            start: WallClock.optional(),
+            end: WallClock.optional(),
+            breakMinutes: z.number().int().min(0).max(480).optional(),
+            graceInMinutes: z.number().int().min(0).max(240).optional(),
+            graceOutMinutes: z.number().int().min(0).max(240).optional(),
+            color: z.string().max(32).nullish(),
+          }),
+        )
+        .output(RosterShift),
+      /**
+       * Archive, never delete. Patterns and stored overrides point at a shift by id, so deleting
+       * one would empty out every day it appears on — past days included.
+       */
+      archive: baseContract
+        .route({ method: 'DELETE', path: '/rosters/shifts/{shiftId}', tags: t })
+        .input(ws.extend({ shiftId: z.uuid() }))
+        .output(ok),
+    },
+
+    patterns: {
+      list: baseContract
+        .route({ method: 'GET', path: '/rosters/patterns', tags: t })
+        .input(ws.extend({ includeArchived: z.boolean().default(false) }))
+        .output(z.array(RosterPattern)),
+      create: baseContract
+        .route({ method: 'POST', path: '/rosters/patterns', tags: t })
+        .input(
+          ws.extend({
+            name: z.string().min(1).max(120),
+            anchorDate: IsoDate,
+            days: z.array(RosterCycleDay).min(1).max(56),
+          }),
+        )
+        .output(RosterPattern),
+      /**
+       * Editing a rotation moves every crew on it, on every date, at once — which is the point of a
+       * rotation being computed rather than generated, and worth saying out loud on the screen that
+       * does it.
+       */
+      update: baseContract
+        .route({ method: 'PATCH', path: '/rosters/patterns/{patternId}', tags: t })
+        .input(
+          ws.extend({
+            patternId: z.uuid(),
+            name: z.string().min(1).max(120).optional(),
+            anchorDate: IsoDate.optional(),
+            days: z.array(RosterCycleDay).min(1).max(56).optional(),
+          }),
+        )
+        .output(RosterPattern),
+      archive: baseContract
+        .route({ method: 'DELETE', path: '/rosters/patterns/{patternId}', tags: t })
+        .input(ws.extend({ patternId: z.uuid() }))
+        .output(ok),
+    },
+
+    /** Who is on which rotation, and when. `attendance.schedules` has no equivalent and should. */
+    assignments: baseContract
+      .route({ method: 'GET', path: '/rosters/assignments', tags: t })
+      .input(ws.extend({ personId: z.uuid().optional(), patternId: z.uuid().optional() }))
+      .output(z.array(RosterAssignment)),
+
+    /**
+     * Put a crew on a rotation.
+     *
+     * Takes a list of people because a rotation is a crew's, not a person's — assigning eleven
+     * people one at a time is eleven chances to get the offset wrong. The previous assignment is
+     * closed the day before, so "which rotation was she on in March" stays answerable.
+     */
+    assign: baseContract
+      .route({ method: 'POST', path: '/rosters/assign', tags: t })
+      .input(
+        ws.extend({
+          patternId: z.uuid(),
+          personIds: z.array(z.uuid()).min(1).max(200),
+          effectiveFrom: IsoDate,
+          /** The last day covered, inclusive. Null leaves the assignment open. */
+          effectiveTo: IsoDate.nullish(),
+          /** Which position of the cycle `effectiveFrom` starts at — how two crews run out of phase. */
+          cycleOffset: z.number().int().min(0).max(55).default(0),
+        }),
+      )
+      .output(z.array(RosterAssignment)),
+
+    /** Take a crew off its rotation, from the day after `effectiveTo`. Nothing is deleted. */
+    unassign: baseContract
+      .route({ method: 'POST', path: '/rosters/unassign', tags: t })
+      .input(
+        ws.extend({
+          personIds: z.array(z.uuid()).min(1).max(200),
+          /** The last day the rotation still applies. */
+          effectiveTo: IsoDate,
+        }),
+      )
+      .output(z.object({ closed: z.number().int() })),
+
+    /** One person's roster over a range, rotation and overrides already resolved. */
+    days: baseContract
+      .route({ method: 'GET', path: '/rosters/days', tags: t })
+      .input(ws.extend({ personId: z.uuid().optional(), from: IsoDate, to: IsoDate }))
+      .output(z.array(RosterDay)),
+
+    /**
+     * Change one day, leaving the rotation alone.
+     *
+     * An empty `shiftIds` is "off that day" and is stored — a planned rest day and a day nothing
+     * rosters at all are different facts, and only one of them is somebody's decision.
+     */
+    set: baseContract
+      .route({ method: 'POST', path: '/rosters/days', tags: t })
+      .input(
+        ws.extend({
+          personId: z.uuid(),
+          businessDate: IsoDate,
+          shiftIds: RosterCycleDay,
+          note: z.string().max(500).nullish(),
+        }),
+      )
+      .output(RosterDay),
+
+    /** Drop the exception and let the rotation speak for that day again. */
+    clear: baseContract
+      .route({ method: 'DELETE', path: '/rosters/days', tags: t })
+      .input(ws.extend({ personId: z.uuid(), businessDate: IsoDate }))
+      .output(ok),
+
+    /**
+     * Who is on which shift, per day — the question a roster exists for and the one a set of weekly
+     * schedules cannot be asked without walking everybody's week.
+     */
+    coverage: baseContract
+      .route({ method: 'GET', path: '/rosters/coverage', tags: t })
+      .input(ws.extend({ from: IsoDate, to: IsoDate, officeId: z.uuid().optional() }))
+      .output(z.array(RosterCoverageDay)),
+  },
+
   // ---------------------------------------------------------------- leave
   leave: {
     types: {
@@ -1382,6 +1566,78 @@ export const hrContract = {
       .output(LeaveBalanceReport),
   },
 
+  // ---------------------------------------------------------------- payroll export
+  /**
+   * The monthly handover to whoever runs payroll, per legal entity, frozen at v1.
+   *
+   * `exports.ts` carries the reasoning; three things about the *shape of the surface* belong here:
+   *
+   * **`legalEntityId` is required, and `periodId` is the range.** `reportInput` makes its slice
+   * optional with a `workspace` default and takes free `from`/`to` dates; neither is available here.
+   * A workspace is not an employer, and a half-month export is a question about a boundary this
+   * module already has an answer for — letting a caller draw their own reintroduces the mixed-finality
+   * problem `ReportFinality` exists to name.
+   *
+   * **`v1` is a procedure, not a parameter.** A later column set ships as `payroll.export.v2` beside
+   * this one, with this one unchanged, and both live through at least one deprecation window. A
+   * `?version=` on one mutable procedure would make the frozen path a branch inside a function three
+   * people will edit, and freezing by intention has never worked.
+   *
+   * **Both cost three keys.** `hr.payroll.export`, which ships granted to nobody, plus
+   * `hr.attendance.view_team` for the hours file and `hr.leave.view_team` for the leave file — the
+   * same second-check rule the reports follow, because an export must not answer what the row-level
+   * procedure would refuse.
+   */
+  payroll: {
+    export: {
+      /**
+       * One entity, one period, two CSVs and a manifest.
+       *
+       * Refuses an open period unless `draft` is set, refuses an entity with nobody in it, and
+       * refuses a person with no employment row covering their days here — because a row of zeros is
+       * something a payroll clerk will pay from, and an error is not.
+       */
+      v1: baseContract
+        .route({ method: 'GET', path: '/payroll/export/v1', tags: t })
+        .input(
+          ws.extend({
+            /** Required. There is no workspace-wide export: a workspace is not an employer. */
+            legalEntityId: z.uuid(),
+            /** The range is the period's, never the caller's. */
+            periodId: z.uuid(),
+            /**
+             * Export an open period anyway, and stamp the file as a draft.
+             *
+             * Not a permission — a statement the caller made, which the file then repeats in its
+             * manifest, its filename and its `open_days`. Defaults to false: `reconcile-days` rebuilds
+             * every day a period does not close, so the same export at 18:00 and at 09:00 the next
+             * morning can differ with nobody having touched anything.
+             */
+            draft: z.boolean().default(false),
+          }),
+        )
+        .output(PayrollExport),
+
+      /**
+       * The same rows as JSON, with no file written and no refusal thrown.
+       *
+       * So the screen shows the totals and the reasons the export would be refused before anybody
+       * downloads anything. Deliberately not versioned: a preview is this module talking to its own
+       * screen, and nothing outside Kern parses it.
+       */
+      preview: baseContract
+        .route({ method: 'GET', path: '/payroll/export/preview', tags: t })
+        .input(
+          ws.extend({
+            legalEntityId: z.uuid(),
+            periodId: z.uuid(),
+            draft: z.boolean().default(false),
+          }),
+        )
+        .output(PayrollExportPreview),
+    },
+  },
+
   // ---------------------------------------------------------------- privacy
   privacy: {
     /**