WorkTracker/plan.md

# WorkTracker Implementation Plan (AI-Ready)

## 1) Chosen stack
- **Frontend + backend host**: ASP.NET Core + Blazor Web App (.NET 9)
- **Database**: Couchbase Lite (local embedded database)

Why this stack:
- Fits CRUD-heavy workflow with strong typing and server-side calculations.
- Couchbase Lite keeps the app self-contained while still storing immutable daily snapshots locally.
- Blazor provides responsive desktop/mobile UI in one codebase.

---

## 2) Product scope summary
The app tracks daily work data and computes projected exit, worked time, gross and net income with configurable defaults per day.

Required day fields:
- Date
- Start time
- Projected exit time (`start + 8h + 1h lunch` by default)
- Actual exit time (stored, not used in calculations)
- Location/status (`None, Home, Work, Closure, Illness, DayOff, Holiday`)
- Extra hours delta (positive or negative)

Required outputs:
- Daily gross income (`workedHoursFinal * hourlyRate`)
- Daily net income using saved coefficients
- Monthly totals: worked hours, office days, home days, holiday days, sick days, hours off, gross income, net income
- Calendar view + grid view

---

## 3) Data model design (Couchbase Lite)

### 3.1 `AppSettings` (configurable defaults)
- `id`
- `standardWorkHoursPerDay` (default `8`)
- `lunchBreakHours` (default `1`)
- `hourlyGrossRate` (default `17.5`)
- `profitabilityCoefficient` (default `0.67`)
- `inpsRate` (default `0.2607`)
- `substituteTaxRate` (default `0.15`)
- `currency` (`EUR`)
- `locale` (`it-IT`)
- `createdAt`, `updatedAt`

### 3.2 `WorkDay`
- `id`
- `date` (unique per user)
- `startTime`
- `projectedExitTime`
- `actualExitTime` (not used in formulas)
- `dayType` (`None, Home, Work, Closure, Illness, DayOff, Holiday`)
- `extraHoursDelta`
- `workedHoursBase`
- `workedHoursFinal`
- `hoursOff`
- `grossIncome`
- `netIncome`
- `isWeekend`
- `isItalianFestivity`
- `notes`
- `coeffSnapshot`:
  - `standardWorkHoursPerDay`
  - `lunchBreakHours`
  - `hourlyGrossRate`
  - `profitabilityCoefficient`
  - `inpsRate`
  - `substituteTaxRate`
- `createdAt`, `updatedAt`

### 3.3 `MonthlySummary` (optional materialized cache)
- `year`, `month`
- all monthly totals
- recompute on demand or save snapshot after month close

Indexes:
- Unique index on `WorkDay.date`
- Compound index on `(year, month, dayType)` for reporting

---

## 4) Business rules (source of truth)

### 4.1 Daily calculations
- `projectedExitTime = startTime + standardWorkHoursPerDay + lunchBreakHours`
- `workedHoursFinal = workedHoursBase + extraHoursDelta`
- `hoursOff = max(0, standardWorkHoursPerDay - workedHoursFinal)` (for workdays)
- `grossIncome = workedHoursFinal * hourlyGrossRate`
- `netIncome = grossIncome - (grossIncome * profitabilityCoefficient * inpsRate) - (grossIncome * profitabilityCoefficient * substituteTaxRate)`

### 4.2 Immutable historical correctness
When saving each `WorkDay`:
- Persist all computed values (`grossIncome`, `netIncome`, etc.).
- Persist `coeffSnapshot` copied from settings (or day overrides).
- Future changes to defaults must not mutate historical records.

---

## 5) UI plan

### 5.1 Phase 1 (this iteration)
- Responsive app shell (desktop/mobile)
- Authentication enabled and wired
- Configurable settings domain model + persistence abstraction
- Localization/currency defaults (`it-IT`, EUR)

### 5.2 Upcoming views
- Daily entry/editor
- Calendar view with day badges/colors
- Grid view with date-first layout and row colors:
  - weekend/festivity: red
  - closure: brown
  - illness/dayoff/holiday: distinct colors
- Monthly totals view

---

## 6) API/service contracts
- `GET /settings`
- `PUT /settings`
- `GET /workdays/{date}`
- `PUT /workdays/{date}`
- `GET /workdays?from=...&to=...`
- `GET /reports/monthly?year=YYYY&month=MM`

For Blazor Server/Web App, these can be implemented as internal services first and surfaced as minimal APIs if needed.

---

## 7) Validation and quality gates
- Unit tests for formulas and snapshot logic
- Integration tests for monthly aggregation
- UI verification for responsive behavior and status coloring
- Ensure `actualExitTime` is excluded from all calculations

---

## 8) Delivery roadmap
1. Scaffold Blazor app + Identity + Couchbase Lite wiring
2. Implement Settings and defaults
3. Implement WorkDay model and calculation service
4. Build daily entry page
5. Build calendar and grid pages
6. Build monthly totals page
7. Add tests and finalize responsive polish