286 lines
11 KiB
Markdown
286 lines
11 KiB
Markdown
# Client Targets v2 — Feature Requirements
|
||
|
||
## Overview
|
||
|
||
This document defines the requirements for the second iteration of the Client Targets feature. The main additions are:
|
||
|
||
- Targets can be set on a **weekly or monthly** period.
|
||
- Each target defines a **fixed weekly working-day pattern** (e.g. Mon + Wed).
|
||
- The balance for the **current period** is calculated proportionally based on elapsed working days, so the user can see at any point in time whether they are ahead or behind.
|
||
- The **start date** can be any calendar day (no longer restricted to Mondays).
|
||
- Manual **balance corrections** are preserved and continue to work as before.
|
||
|
||
---
|
||
|
||
## 1. Target Configuration
|
||
|
||
| Field | Type | Constraints |
|
||
|---|---|---|
|
||
| `periodType` | `WEEKLY \| MONTHLY` | Required |
|
||
| `weeklyOrMonthlyHours` | positive float, ≤ 168 | Required; represents hours per week or per month |
|
||
| `workingDays` | array of day names | At least one of `MON TUE WED THU FRI SAT SUN`; fixed repeating pattern |
|
||
| `startDate` | `YYYY-MM-DD` | Any calendar day; no longer restricted to Mondays |
|
||
| `clientId` | UUID | Must belong to the authenticated user |
|
||
|
||
**One active target per client** — the unique `(userId, clientId)` constraint is preserved. To change period type, hours, or working days the user creates a new target with a new `startDate`; the old target is soft-deleted. History from the old target is retained as-is and is no longer recalculated.
|
||
|
||
---
|
||
|
||
## 2. Period Definitions
|
||
|
||
| `periodType` | Period start | Period end |
|
||
|---|---|---|
|
||
| `WEEKLY` | Monday 00:00 of the calendar week | Sunday 23:59 of that same calendar week |
|
||
| `MONTHLY` | 1st of the calendar month 00:00 | Last day of the calendar month 23:59 |
|
||
|
||
---
|
||
|
||
## 3. Balance Calculation — Overview
|
||
|
||
The total balance is the **sum of individual period balances** from the period containing `startDate` up to and including the **current period** (the period that contains today).
|
||
|
||
Each period is classified as either **completed** or **ongoing**.
|
||
|
||
```
|
||
total_balance_seconds = SUM( balance_seconds ) over all periods
|
||
```
|
||
|
||
Positive = overtime. Negative = undertime.
|
||
|
||
---
|
||
|
||
## 4. Completed Period Balance
|
||
|
||
A period is **completed** when its end date is strictly before today.
|
||
|
||
```
|
||
balance = tracked_hours + correction_hours - period_target_hours
|
||
```
|
||
|
||
- `period_target_hours` — see §5 (pro-ration) for the first period; full `weeklyOrMonthlyHours` for all subsequent periods.
|
||
- `tracked_hours` — sum of all time entries for this client whose date falls within `[period_start, period_end]`.
|
||
- `correction_hours` — sum of manual corrections whose `date` falls within `[period_start, period_end]`.
|
||
|
||
No working-day logic is applied to completed periods. The target is simply the (optionally pro-rated) hours for that period.
|
||
|
||
---
|
||
|
||
## 5. First Period Pro-ration
|
||
|
||
If `startDate` does not fall on the natural first day of a period (Monday for weekly, 1st for monthly), the target hours for that first period are pro-rated by calendar days.
|
||
|
||
### Monthly
|
||
|
||
```
|
||
full_period_days = total calendar days in that month
|
||
remaining_days = (last day of month) − startDate + 1 // inclusive
|
||
period_target_hours = (remaining_days / full_period_days) × weeklyOrMonthlyHours
|
||
```
|
||
|
||
**Example:** startDate = Jan 25, target = 40 h/month, January has 31 days.
|
||
`remaining_days = 7`, `period_target_hours = (7 / 31) × 40 = 9.032 h`
|
||
|
||
### Weekly
|
||
|
||
```
|
||
full_period_days = 7
|
||
remaining_days = Sunday of that calendar week − startDate + 1 // inclusive
|
||
period_target_hours = (remaining_days / 7) × weeklyOrMonthlyHours
|
||
```
|
||
|
||
**Example:** startDate = Wednesday, target = 40 h/week.
|
||
`remaining_days = 5 (Wed–Sun)`, `period_target_hours = (5 / 7) × 40 = 28.571 h`
|
||
|
||
All periods after the first use the full `weeklyOrMonthlyHours`.
|
||
|
||
---
|
||
|
||
## 6. Ongoing Period Balance (Current Period)
|
||
|
||
The current period is **ongoing** when today falls within it. The balance reflects how the user is doing *so far* — future working days within the current period are not considered.
|
||
|
||
### Step 1 — Period target hours
|
||
|
||
Apply §5 if this is the first period; otherwise use full `weeklyOrMonthlyHours`.
|
||
|
||
### Step 2 — Daily rate
|
||
|
||
```
|
||
working_days_in_period = COUNT of days in [period_start, period_end]
|
||
that match the working day pattern
|
||
daily_rate_hours = period_target_hours / working_days_in_period
|
||
```
|
||
|
||
The rate is fixed at the start of the period and does not change as time passes.
|
||
|
||
### Step 3 — Elapsed working days
|
||
|
||
```
|
||
elapsed_working_days = COUNT of days in [period_start, TODAY] (both inclusive)
|
||
that match the working day pattern
|
||
```
|
||
|
||
- If today matches the working day pattern, it is counted as a **full** elapsed working day.
|
||
- If today does not match the working day pattern, it is not counted.
|
||
|
||
### Step 4 — Expected hours so far
|
||
|
||
```
|
||
expected_hours = elapsed_working_days × daily_rate_hours
|
||
```
|
||
|
||
### Step 5 — Balance
|
||
|
||
```
|
||
tracked_hours = SUM of time entries for this client in [period_start, today]
|
||
correction_hours = SUM of manual corrections whose date ∈ [period_start, today]
|
||
balance = tracked_hours + correction_hours − expected_hours
|
||
```
|
||
|
||
### Worked example
|
||
|
||
> Target: 40 h/month. Working days: Mon + Wed.
|
||
> Current month has 4 Mondays and 4 Wednesdays → `working_days_in_period = 8`.
|
||
> `daily_rate_hours = 40 / 8 = 5 h`.
|
||
> 3 working days have elapsed → `expected_hours = 15 h`.
|
||
> Tracked so far: 13 h, no corrections.
|
||
> `balance = 13 − 15 = −2 h` (2 hours behind).
|
||
|
||
---
|
||
|
||
## 7. Manual Balance Corrections
|
||
|
||
| Field | Type | Constraints |
|
||
|---|---|---|
|
||
| `date` | `YYYY-MM-DD` | Must be ≥ `startDate`; not more than one period in the future |
|
||
| `hours` | signed float | Positive = extra credit (reduces deficit). Negative = reduces tracked credit |
|
||
| `description` | string | Optional, max 255 chars |
|
||
|
||
- The system automatically assigns a correction to the period that contains its `date`.
|
||
- Corrections in **completed periods** are included in the completed period formula (§4).
|
||
- Corrections in the **ongoing period** are included in the ongoing balance formula (§6).
|
||
- Corrections in a **future period** (not yet started) are stored and will be applied when that period becomes active.
|
||
- A correction whose `date` is before `startDate` is rejected with a validation error.
|
||
|
||
---
|
||
|
||
## 8. Edge Cases
|
||
|
||
| Scenario | Behaviour |
|
||
|---|---|
|
||
| `startDate` = 1st of month / Monday | No pro-ration; `period_target_hours = weeklyOrMonthlyHours` |
|
||
| `startDate` = last day of period | `remaining_days = 1`; target is heavily reduced (e.g. 1/31 × hours) |
|
||
| Working pattern has no matches in the partial first period | `elapsed_working_days = 0`; `expected_hours = 0`; balance = `tracked + corrections` |
|
||
| Current period has zero elapsed working days | `expected_hours = 0`; balance = `tracked + corrections` (cannot divide by zero — guard required) |
|
||
| `working_days_in_period = 0` | Impossible by validation (at least one day required), but system must guard: treat as `daily_rate_hours = 0` |
|
||
| Today is not a working day | `elapsed_working_days` does not include today |
|
||
| Correction date before `startDate` | Rejected with a validation error |
|
||
| Correction date in future period | Accepted and stored; applied when that period is ongoing or completed |
|
||
| User changes working days or period type | Must create a new target with a new `startDate`; old target history is frozen |
|
||
| Two periods with the same client exist (old soft-deleted, new active) | Only the active target's periods contribute to the displayed balance |
|
||
| A month with only partial working day coverage (e.g. all Mondays are public holidays) | No automatic holiday handling; user adds manual corrections to compensate |
|
||
|
||
---
|
||
|
||
## 9. Data Model Changes
|
||
|
||
### `ClientTarget` table — additions / changes
|
||
|
||
| Column | Change | Notes |
|
||
|---|---|---|
|
||
| `period_type` | **Add** | Enum: `WEEKLY`, `MONTHLY` |
|
||
| `working_days` | **Add** | Array/bitmask of day names: `MON TUE WED THU FRI SAT SUN` |
|
||
| `start_date` | **Modify** | Remove "must be Monday" validation constraint |
|
||
| `weekly_hours` | **Rename** | → `target_hours` (represents hours per week or per month depending on `period_type`) |
|
||
|
||
### `BalanceCorrection` table — no structural changes
|
||
|
||
Date-to-period assignment is computed at query time, not stored.
|
||
|
||
---
|
||
|
||
## 10. API Changes
|
||
|
||
### `ClientTargetWithBalance` response shape
|
||
|
||
```typescript
|
||
interface ClientTargetWithBalance {
|
||
id: string
|
||
clientId: string
|
||
clientName: string
|
||
userId: string
|
||
periodType: "weekly" | "monthly"
|
||
targetHours: number // renamed from weeklyHours
|
||
workingDays: string[] // e.g. ["MON", "WED"]
|
||
startDate: string // YYYY-MM-DD
|
||
createdAt: string
|
||
updatedAt: string
|
||
corrections: BalanceCorrection[]
|
||
totalBalanceSeconds: number // running total across all periods
|
||
currentPeriodTrackedSeconds: number // replaces currentWeekTrackedSeconds
|
||
currentPeriodTargetSeconds: number // replaces currentWeekTargetSeconds
|
||
periods: PeriodBalance[] // replaces weeks[]
|
||
}
|
||
|
||
interface PeriodBalance {
|
||
periodStart: string // YYYY-MM-DD (Monday or 1st of month)
|
||
periodEnd: string // YYYY-MM-DD (Sunday or last of month)
|
||
targetHours: number // pro-rated for first period
|
||
trackedSeconds: number
|
||
correctionHours: number
|
||
balanceSeconds: number
|
||
isOngoing: boolean
|
||
// only present when isOngoing = true
|
||
dailyRateHours?: number
|
||
workingDaysInPeriod?: number
|
||
elapsedWorkingDays?: number
|
||
expectedHours?: number
|
||
}
|
||
```
|
||
|
||
### Endpoint changes
|
||
|
||
| Method | Path | Change |
|
||
|---|---|---|
|
||
| `POST /client-targets` | Create | Accepts `periodType`, `workingDays`, `targetHours`; `startDate` unconstrained |
|
||
| `PUT /client-targets/:id` | Update | Accepts same new fields |
|
||
| `GET /client-targets` | List | Returns updated `ClientTargetWithBalance` shape |
|
||
| `POST /client-targets/:id/corrections` | Add correction | No change to signature |
|
||
| `DELETE /client-targets/:id/corrections/:corrId` | Delete correction | No change |
|
||
|
||
### Zod schema changes
|
||
|
||
- `CreateClientTargetSchema` / `UpdateClientTargetSchema`:
|
||
- Add `periodType: z.enum(["weekly", "monthly"])`
|
||
- Add `workingDays: z.array(z.enum(["MON","TUE","WED","THU","FRI","SAT","SUN"])).min(1)`
|
||
- Rename `weeklyHours` → `targetHours`
|
||
- Remove Monday-only regex constraint from `startDate`
|
||
|
||
---
|
||
|
||
## 11. Frontend Changes
|
||
|
||
### Types (`frontend/src/types/index.ts`)
|
||
- `ClientTargetWithBalance` — add `periodType`, `workingDays`, `targetHours`; replace `weeks` → `periods: PeriodBalance[]`; replace `currentWeek*` → `currentPeriod*`
|
||
- Add `PeriodBalance` interface
|
||
- `CreateClientTargetInput` / `UpdateClientTargetInput` — same field additions
|
||
|
||
### Hook (`frontend/src/hooks/useClientTargets.ts`)
|
||
- No structural changes; mutations pass through new fields
|
||
|
||
### API client (`frontend/src/api/clientTargets.ts`)
|
||
- No structural changes; payload shapes updated
|
||
|
||
### `ClientsPage` — `ClientTargetPanel`
|
||
- Working day selector (checkboxes: Mon–Sun, at least one required)
|
||
- Period type selector (Weekly / Monthly)
|
||
- Label for hours input updates dynamically: "Hours/week" or "Hours/month"
|
||
- Start date picker: free date input (no week-picker)
|
||
- Balance display: label changes from "this week" to "this week" or "this month" based on `periodType`
|
||
- Expanded period list replaces the expanded week list
|
||
|
||
### `DashboardPage`
|
||
- "Weekly Targets" widget renamed to "Targets"
|
||
- "This week" label becomes "This week" / "This month" dynamically
|
||
- `currentWeek*` fields replaced with `currentPeriod*`
|