# Work entries (HR)

Work entries (*Leistungen*) are HR's record of worked time that can be billed. They live in the HR module
(`/api/hr/v1`); desk books through them and reads spent time from HR's totals. Every operation is in the
[HR reference](/reference/hr).

## Book your own work

`createWorkEntry` (`POST /work-entries`, permission `tenant:access`, an active employee record, else
`403 no_employee`) books an entry that is a work day and a length (see below), a work kind and billing type (`kind`, `billing`), a description and a **subject**: the thing the work belongs
to, e.g. a desk ticket, a forge item, a project or a customer interaction. `updateWorkEntry` and
`deleteWorkEntry` change your own entries as long as they are not approved. `listWorkEntries` lists them,
`getWorkSummary` gives the booked, billable and internal minutes of a day and `getMyDay` the whole day with attendance
and what is not booked yet. `createWorkEntry` takes no `Idempotency-Key`: a retried create of the same span is
refused with `409 overlap`, so read the day before booking again.

The kinds and billing types and the tenant's rules are the work settings: `getWorkEntrySettings` (read) and
`setWorkEntrySettings` (`hr:work:manage`).

### Length, span and work date

An entry needs no clock times. Send **one** of: `minutes` (1–1440) with an optional `workDate` (default today in the
tenant's time zone; a day in the future is `400 workDate`), a span `startedAt` + `endedAt` (the minutes follow from it
and a sent `minutes` is ignored; a `workDate` must be the start's day, for a span across midnight the end's day is allowed too), or a `startedAt` with `minutes` and no end.
`endedAt` without `startedAt` is `400 startedAt`, a start alone without `minutes` is `400 minutes`. The work date is
the day the work counts for. Entries without a span never overlap; only two spans of one person do (`409 overlap`).
The response has `workDate`, `minutes` (what sums and billing use), `durationSeconds` (the exact length) and
`startedAt` / `endedAt`, which may be `null`. There is no break: nothing is deducted. A list is ordered by work date,
then start (entries with a start first), then creation. Without a `customer` in the request, the customer follows from
the subject: the customer of a desk item or, for a forge item or project, the project's `workCustomer` (internal or a
customer, set in forge). Work on a customer-only subject names the `customer` itself.

## Stopwatch

`startStopwatch`, `getStopwatch` and `stopStopwatch` run one stopwatch per person; starting a new one stops the
running one. Stopping it (optionally with `endedAt` and `description`) books an entry from the start
to now or to `endedAt`; stopping with `discard: true` books nothing. The exact seconds are kept in `durationSeconds`.
`minutes` are rounded once when the stopwatch stops, by the tenant's `rounding` in the work settings
(`direction` `up`, `down` or `nearest`, `stepMinutes` 1, 5, 10, 15, 30 or 60; default nearest and 1; always returned
by `getWorkEntrySettings`). An explicit `endedAt` and manual changes are not rounded. A run that rounds to 0 stays as a
0-minute entry; a stopwatch running longer than 24 hours stops only with an explicit `endedAt`
(`422 stopwatch_too_long`). Starting a new stopwatch keeps the running one as an entry, also when it ran under a
minute.

## Subjects

An entry points to a subject `<module>:<kind>:<id>`: `desk:item:<id>`, `forge:item:<id>`, `crm:activity:<id>`,
or a project `desk:project:<id>` / `forge:project:<id>` (empty for
work on the customer only). HR checks it with its module before booking (`422 subject_not_bookable`,
`503 subject_access_unavailable` when the module cannot answer – nothing is booked); a call or appointment is the `origin`
(`comms:interaction:<id>` or `comms:calendar:<id>`, the caller's own, `400` field `origin`) – never a `subject` – and is booked
once (`409 already_booked`). `listWorkEntries` with `subject=` lists the entries on one subject. The totals desk and
forge show as spent time come from HR through internal routes that API keys cannot call.

## Approval

Line managers and deputies approve the entries of their team, `hr:work:manage` those of everyone:
`listApprovableWorkEntries` (each entry with the person's `employeeName`), `approveWorkEntries` and
`unapproveWorkEntries`. `listEmployeeWorkEntries` and `getEmployeeMyDay` show a team member's entries, `getWorkEntry`
one entry (the owner's or one the caller decides for; `404` otherwise). An approved or billed entry is not edited; `correctWorkEntry` books a
correction that refers to it.

## Rates and billing

Rates (`listWorkRates`, `createWorkRate`, `updateWorkRate`, `deleteWorkRate`) are per default, customer, contract or
project, and need `hr:work:billing`. With it, `getWorkBilling` shows the open billing units outside projects, `createWorkBatch` bills a unit's
approved entries in a period and hands the batch to trade, `sendWorkBatch` sends a requested batch again,
`withdrawWorkBatch` takes back one trade has not taken yet, and `listWorkBatches` / `listProjectWorkBatches` list them.
