Feature: Shifts

[Vidarte-Alberto]

Summary

Rework Shifts (Turnos) end-to-end: modernize the frontend UX and
enforce robust business rules/validations on the backend. Ensure
a clean flow to start/close shifts, prevent overlaps, and prepare
reliable shift data for cashier closing (corte de caja).

Goals

• Provide clear, usable shift management UI (list, start, close,
  edit notes).
• Enforce business rules: one active shift per user, no overlaps,
  valid times.
• Align API and validations with existing Ktor patterns and tests.
• Integrate permissions: shifts_read, shifts_create, shifts_update,
  shifts_delete, shifts_close.

Scope

• Server (Ktor):
  • Review and harden shift business logic in ShiftService and
    Shifts.kt.
  • Add explicit “start” and “close” actions or enforce
    validations within existing CRUD.
  • Ensure all routes require auth; align 204/404 semantics with
    current style.
  • Unit tests mirroring DishServiceTest patterns.
• Client (Next.js):
  • Frontend rework: dedicated shifts UI under client/src/modules/
    cashier or new client/src/modules/shifts.
  • Create/edit/close flows with inline validations and
    permission-based gating.
  • Filter by date/user; highlight current active shift; show
    state clearly.
• Docs:
  • Update shifts usage and validation rules; describe permission
    checks.

Out of Scope

• Full cashier closing printing/report (handled in “Cashier Closing”
  feature).
• Complex scheduling (multi-location, overlapping roles).

Acceptance Criteria

• Backend validations:
  • Exactly one active shift per user at a time.
  • No overlapping shifts for the same user/date.
  • end_time must be after start_time.
  • Can’t close an already closed shift.
• API and security:
  • All shift endpoints require auth-jwt.
  • Consistent responses: 200/201, 204, 404, 409 for conflicts.
  • OpenAPI updated for request/response schemas and errors.
• Client:
  • Shifts list with filters (date range, user).
  • Start shift (required: date, start time; optional: notes).
  • Close shift (sets end_time; confirm dialog).
  • Edit notes for existing shift if allowed.
  • UI respects permissions and shows validation errors.
• Tests:
  • Unit tests for service validations (overlap, single active,
    invalid close).
  • Route smoke tests for 200/404/409 paths.
• Docs:
  • Business rules documented and examples provided.

Tasks

1. Backend: Business Logic
   • Add overlap checks in ShiftService:
     • Prevent creating a shift when another is active for the
       same user.
     • Prevent time overlaps on same user_id and shift_date.
   • Enforce close rules in update/close:
     • end_time > start_time, disallow re-closing.
   • Return 409 Conflict for business-rule violations.
   • Ensure GET /shifts is under authenticate("auth-jwt")
     (align with others).
   • Add indices to improve queries: (user_id, shift_date)
     (migration optional).
2. Backend: API and Docs
   • Option A: Keep CRUD but document validations.
   • Option B: Add explicit actions:
     • POST /shifts/start (body: user_id, shift_date, start_time,
       notes?)
     • POST /shifts/{id}/close (body: end_time, notes?).
3. Tests (Server)
   • Create ShiftServiceTest.kt:
     • Create success; overlap conflict; single active per user;
       close success; double-close conflict; invalid end time.
   • Route tests for start/close (200/409/404).
4. Frontend Rework
   • New module: client/src/modules/shifts (or extend cashier):
     • Shifts.js (list with filters, active badge).
     • ShiftManager.js (start/close/edit form).
     • shiftsService.js (API calls).
   • Permission checks for actions (shifts_*).
   • Validation UX: disabled actions + inline error messages.
5. Docs
   • Add page/section in web/ with:
     • Business rules, examples, API usage.
     • Permissions mapping and UI gating.

Business Rules

• One active shift per user at any time.
• No overlapping shifts for the same user on the same date.
• Close requires end_time > start_time.
• Only authorized users can create/close shifts; admins can manage
  any user’s shifts (if policy requires).

API Contract (Draft)

• GET /shifts → 200 list | 204 none
• GET /shifts/{id} → 200 item | 404
• POST /shifts (start, if using CRUD) → 201 | 409 on overlap/active
• PUT /shifts/{id} (close via update or notes edit) → 200 | 409
  invalid close | 404
• Optional explicit:
  • POST /shifts/start → 201 | 409
  • POST /shifts/{id}/close → 200 | 409 | 404

Implementation Notes

• Server: follow Shifts.kt/service patterns; keep responses
  consistent with Dishes.kt/Suppliers.kt.
• DB: SQLite overlap is validated in service; consider indices for
  performance.
• Client: mirror structure/patterns used in client/src/modules/
  dishes; 2-space indent; show active shift prominently in cashier
  context.

Risks

• Overlap detection edge cases with time boundaries; add unit tests
  for equality at boundaries.
• Existing clients may rely on current unauthenticated GET /shifts;
  coordinate change.
• Partial data if client starts but never closes; surface in UI and
  allow admin remediation.

Labels

type:feature area:shifts area:frontend area:backend area:auth
priority:medium