# WorkTracker Implementation Plan (AI-Ready)

## 1) Chosen stack
- **Frontend + backend host**: ASP.NET Core + Blazor Web App (.NET 8)
- **Database**: MongoDB
- **Auth approach (single user)**: ASP.NET Core Identity configured and enabled now; registration can be disabled later and one seeded account can be used.

Why this stack:
- Fits CRUD-heavy workflow with strong typing and server-side calculations.
- MongoDB maps well to immutable daily snapshots (store coefficients used for each day).
- 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 (MongoDB)

### 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 + Mongo 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
