# Staged Default Hours Change with Conflict Resolution

## Overview

When an admin edits default working hours, instead of applying changes immediately:
1. Run conflict resolution (same pattern as holiday hours/time blockers)
2. Stage the change with a future effective date (admin picks, default +2 weeks)
3. Current hours continue to apply until the switch-over date
4. At midnight on the effective date, the change auto-applies and triggers a notification
5. Contact page shows "These opening hours will change from [date]"
6. Available hours use current hours before the date, new hours after

---

## What Changes

### New DB Table: `default_hours_scheduled_changes`

```sql
CREATE TABLE default_hours_scheduled_changes (
    id SERIAL PRIMARY KEY,
    effective_date DATE NOT NULL,           -- London midnight date to switch over
    created_by CHAR(12) NOT NULL REFERENCES users(id),
    created_at TIMESTAMPTZ DEFAULT NOW(),
    applied_at TIMESTAMPTZ,                 -- NULL until cron applies it
    cancelled_at TIMESTAMPTZ,               -- NULL unless admin cancels
    hours JSONB NOT NULL                    -- [{weekday, startTime, endTime, isOpen}]
);
```

Only ONE pending change is allowed at a time. If a pending change exists and the admin tries to create another, they must cancel the existing one first.

### New `admin_notification_reason` enum value

```sql
ALTER TYPE admin_notification_reason ADD VALUE 'default_hours_changed';
```

Used by the cron job when it applies the change — creates a single notification for admin review.

---

## Files to Create/Modify

### Backend

| # | File | Action |
|---|---|---|
| 1 | `init-scripts/init-script.sql` | Add new table and enum value |
| 2 | `backend/handlers/scheduling/default-hours.go` | Add `ScheduleDefaultHoursChange`, `GetScheduledDefaultHoursChange`, `CancelScheduledDefaultHoursChange` handlers |
| 3 | `backend/handlers/scheduling/default-hours.go` | Modify `GetDefaultHours` — return both current and pending future hours |
| 4 | `backend/handlers/scheduling/default-hours.go` | Modify `computeAvailableHours` / `GetWorkingHours` — inject future hours for dates >= effective_date |
| 5 | `backend/handlers/scheduling/scheduled-cleanup.go` | Add `ApplyScheduledDefaultHours` cron handler |
| 6 | `backend/internal/jobs/cleanup.go` | Register `apply-default-hours` cron job (daily at 00:05) |
| 7 | `backend/main.go` | Register new routes |

### Frontend

| # | File | Action |
|---|---|---|
| 8 | `frontend/src/lib/components/admin/WeeklySchedule.svelte` | Add conflict resolution UI + date picker + staged save flow |
| 9 | `frontend/src/lib/components/layout/BusinessHours.svelte` | Show upcoming hours change with date |
| 10 | `frontend/src/routes/admin/+page.svelte` | Wire modal props if needed |

---

## Detail: Backend Design

### Handler: `ScheduleDefaultHoursChange` (POST)

`PUT /api/admin/default-hours` → replaced with a staging flow:

```
POST /api/admin/default-hours/schedule
Content-Type: application/json

{
    "hours": [{"weekday": 0, "startTime": "10:00", "endTime": "18:00", "isOpen": true}, ...],
    "effective_date": "2026-08-17"   // optional, defaults to +14 days from today London
}
```

**Flow:**
1. Parse + validate input
2. Check for existing pending change — return 409 if one exists
3. Run conflict detection between current bookings and the proposed hours
4. If conflicts exist → return 409 with `{error: "conflicts exist", bookings: [...]}` (same format as holiday hours)
5. If no conflicts → store the pending change, return 201 with `{effective_date: "2026-08-17"}`

### Handler: `GetScheduledDefaultHoursChange` (GET)

```
GET /api/admin/default-hours/scheduled
```

Returns the pending change or 404:
```json
{
    "effective_date": "2026-08-17",
    "hours": [...],
    "created_at": "...",
    "created_by": "..."
}
```

### Handler: `CancelScheduledDefaultHoursChange` (DELETE)

```
DELETE /api/admin/default-hours/scheduled
```

Sets `cancelled_at` on the pending change. Returns 200.

### Handler: `ApplyScheduledDefaultHours` (cron)

Runs at "5 0 * * *" (00:05 daily — 5 minutes after midnight to avoid midnight race conditions).

**Flow:**
1. Query `default_hours_scheduled_changes` where `effective_date <= CURRENT_DATE` (London time) AND `applied_at IS NULL` AND `cancelled_at IS NULL`
2. For each due change:
   a. BEGIN transaction
   b. DELETE all existing `working_hours` rows
   c. INSERT new rows from the change's hours JSON
   d. INSERT an `admin_notifications` with reason `default_hours_changed` (details: "Default hours changed from [old summary] to [new summary]")
   e. SET `applied_at = NOW()`
   f. COMMIT

### Modified: `GetDefaultHours`

Current: returns `SELECT weekday, start_time, end_time, is_open FROM working_hours ORDER BY weekday`

New: if a pending change exists with `effective_date > today`, include an extra field:
```json
[
    {"weekday": 0, "startTime": "00:00", "endTime": "00:00", "isOpen": false, ...},
    ...
]
```
Response changes to include optional `scheduled_change` field:
```json
{
    "current": [...],
    "scheduled_change": {
        "effective_date": "2026-08-17",
        "hours": [...]
    }
}
```

This is backwards-compatible for existing consumers — they read the array from `current`.

### Modified: `computeAvailableHours` / `GetWorkingHours`

The hours resolution currently goes: proposed > exceptional > default > closed.

For the staged hours feature, I need to inject the **scheduled future default hours** for dates >= effective_date:

Priority order: proposed > exceptional > scheduled_future_default > default > closed

In `computeAvailableHours` (the per-day loop), after looking up the `defaultMap` entry:

```go
// Before falling through to default/closed, check if there's a staged future change
if scheduledChangeHours != nil && d.In(londonLocation).Format("2006-01-02") >= scheduledEffectiveDate {
    if fh, ok := scheduledChangeHours[weekday]; ok {
        baseStart = fh.StartTime
        baseEnd = fh.EndTime
        isOpen = fh.IsOpen
        day.Source = "scheduled_change"
    }
} else if def, ok := defaultMap[weekday]; ok {
    // existing default logic...
}
```

This means:
- Today → current working hours apply
- Between today and effective_date → current working hours apply (no change)
- On/after effective_date → new scheduled hours apply
- Exceptional hours always override (higher priority)

For `GetWorkingHours`, same logic applies — it needs to return the correct hours for each date in the range.

---

## Detail: Frontend Design

### WeeklySchedule.svelte — "Edit Schedule" Modal

The modal gets a new top section (same pattern as HolidayHours conflict resolution):

**Step 1: Admin opens modal, edits hours**
Same time picker interface as today. No change to the editing UX.

**Step 2: Conflict resolution (new)**
- A date picker for "Apply from" (defaults to +14 days from today in London)
- A `checkConflictingBookings()` function that:
  - Takes the proposed hours + effective date range (from effective_date to effective_date + 90 days or so)
  - Calls `POST /api/admin/default-hours/schedule` with a dry-run flag or a dedicated conflict endpoint
  - Shows amber warning with conflicting bookings + "View Booking" / "View Client" buttons
- Guard: submit button disabled while conflicts exist

**Step 3: Submit**
- Button text: `Schedule Change for [date]` 
- On success toast: `Default hours will change at 23:59 on 17/08/2026`
- The modal closes, admin sees a "Pending change" indicator on the WeeklySchedule card

**Step 4: Pending change indicator**
- After a change is scheduled, the WeeklySchedule card shows:
  - An amber banner: "Default hours are scheduled to change on 17/08/2026"
  - A "Cancel" button that calls `DELETE /api/admin/default-hours/scheduled`
- The `fetchDefaultHours` response now includes `scheduled_change` — display it

### BusinessHours.svelte — Contact Page

Add a new section below the current "Upcoming Holiday Hours" section:

```svelte
{#if scheduledChange}
    <hr class="my-2 border-gray-200" />
    <p class="mb-2 text-center text-xs font-medium text-amber-600">
        Opening hours will change from {formattedDate}
    </p>
    {#each scheduledChange.hours as h}
        <div class="flex items-center justify-between text-sm">
            <span class="font-medium text-gray-700">{dayNames[h.weekday]}</span>
            <span class="text-gray-500">
                {#if h.isOpen}
                    {formatTime(h.startTime)} – {formatTime(h.endTime)}
                {:else}
                    Closed
                {/if}
            </span>
        </div>
    {/each}
{/if}
```

To load this, the `fetchData` function needs an additional API call:
```
GET /api/admin/default-hours/scheduled  (public, or a new public endpoint)
```

Since this is shown on the public contact page, the endpoint should be under the public read-only group (OptionalAuth) — similar to how `GET /scheduling/working-hours` is public.

### admin/+page.svelte

If `WeeklySchedule` needs `openUserModal` / `openBookingModal` for conflict resolution, wire the same props. Currently `WeeklySchedule` does not accept these props, but the conflict resolution flow needs "View Client" and "View Booking" buttons.

---

## Conflict Resolution vs Holiday Hours — Reusing the Pattern

The conflict detection for default hours changes reuses the EXACT same pattern as the holiday hours conflict handler, but with a date range instead of week starts:

```
POST /api/admin/default-hours/conflicting-bookings
{
    "proposed_hours": [{"weekday": 0, "startTime": "10:00", "endTime": "18:00", "isOpen": true}, ...],
    "start_date": "2026-08-17",
    "end_date": "2026-11-17"   // default: +90 days from effective date
}
```

This reuses the same `parseTimeToMinutes` comparison logic and the `ActiveBookingStatuses` filter. The response is the same `OverlappingBookingsResponse` format.

**Note:** The availability-for-reschedule logic is simpler than holiday hours because:
- Default hours changes apply PERMANENTLY (not per-week like holiday hours)
- The "what hours apply for rescheduling" is just: current hours until effective_date, future hours after
- No per-week mapping needed

---

## Risks

| Risk | Mitigation |
|---|---|
| Admin sets effective_date in the past | Validate: must be >= tomorrow (London date + 1) |
| Cron miss at midnight doesn't apply change | Cron runs 00:05 to avoid midnight race. Query uses `<= CURRENT_DATE` so it catches any missed days |
| Two admins try to schedule simultaneously | Unique constraint on `(applied_at IS NULL AND cancelled_at IS NULL)` — use a partial unique index |
| Notification is an admin-only todo placeholder | Add `default_hours_changed` to the enum, create one notification. Future work: user notification |
| Scheduling a change far in the future (6+ months) | Conflicts only checked against existing bookings in the window. Long-range changes may need re-checking when new bookings are made — acceptable for v1 |