Rafael Foster
22ec13e559
* Adding flexible reminder options to birthdays * Fix database migration merge conflict * Truncate calendar popup descriptions * Log app version on backend startup * Add host-mounted data and backup folders * feat: add housekeeping module * fix: align housekeeping UI and add task creation * refactor: rebuild housekeeping experience * feat: support multiple housekeeping staff * feat: integrate housekeeping visits with calendar * feat: refine housekeeping visits and payments * feat: add housekeeping staff visit logs * feat: add housekeeping receipts and document folders * feat: localize housekeeping folders and chores * feat: refine housekeeping tabs and document folders * fix: sync housekeeping tab active state * feat: use configured app name in onboarding and manifest
135 lines
4.0 KiB
Markdown
135 lines
4.0 KiB
Markdown
# Housekeeping Design
|
|
|
|
## Goal
|
|
|
|
Housekeeping adds a simplified mobile/PWA module for the cleaner workflow in Oikos. It keeps the existing private-network, authenticated-session security model and exposes no public endpoints.
|
|
|
|
## User Experience
|
|
|
|
The `/housekeeping` route is a focused module that follows the same toolbar, tab, card, and chip patterns used by the rest of Oikos:
|
|
|
|
- **Dashboard**: staff-specific check-in/check-out actions, visits this month, last visit, pending/finished chores, pending payments, and a compact monthly payment chart.
|
|
- **Tasks**: suggested chore templates, custom chore creation, urgency-sorted recurring tasks, and one-tap completion.
|
|
- **Reports**: camera upload plus text description for maintenance occurrences.
|
|
- **Staff**: one or more housekeeper people, contact data, profile pictures, daily rates, and payment schedules.
|
|
|
|
Accessibility constraints:
|
|
|
|
- Primary actions are at least 44px high.
|
|
- Check-in/out is a compact top-toolbar action, matching the small action pattern used elsewhere in the app.
|
|
- Status is communicated by text and color, not color alone.
|
|
- Inputs and buttons have explicit labels or accessible names.
|
|
- Icons use the locally bundled Lucide runtime; no external CDN is introduced.
|
|
|
|
## Data Model
|
|
|
|
### `housekeeping_work_sessions`
|
|
|
|
Stores point/finance records:
|
|
|
|
- `id`
|
|
- `worker_id`
|
|
- `check_in`
|
|
- `check_out`
|
|
- `daily_rate`
|
|
- `extras`
|
|
- `calendar_event_id`
|
|
- `created_by`
|
|
- `created_at`
|
|
- `updated_at`
|
|
|
|
Monthly amount is calculated as `SUM(daily_rate + extras)` for sessions whose `check_in` belongs to the requested month.
|
|
Each check-in creates a linked local calendar event for the selected staff member. Check-out updates that event end time.
|
|
|
|
### `housekeeping_decay_tasks`
|
|
|
|
Stores dynamic recurring cleaning tasks:
|
|
|
|
- `id`
|
|
- `name`
|
|
- `area`
|
|
- `frequency_days`
|
|
- `last_completed`
|
|
- `created_by`
|
|
- `created_at`
|
|
- `updated_at`
|
|
|
|
Urgency is computed at read time:
|
|
|
|
```text
|
|
urgency = (now - last_completed) / frequency_days
|
|
```
|
|
|
|
Status mapping:
|
|
|
|
- `overdue`: due date is before today.
|
|
- `today`: due date is today.
|
|
- `ok`: due date is in the future.
|
|
|
|
Rows with no `last_completed` are treated as overdue.
|
|
|
|
### `housekeeping_supply_requests`
|
|
|
|
Stores quick supply requests and links each request to an Oikos shopping item:
|
|
|
|
- `id`
|
|
- `name`
|
|
- `quantity`
|
|
- `shopping_item_id`
|
|
- `created_by`
|
|
- `created_at`
|
|
|
|
The supply request transaction always appends an item to the main `shopping_items` table. If no shopping list exists, the backend creates a private authenticated list named `Housekeeping`.
|
|
|
|
### `housekeeping_maintenance_log`
|
|
|
|
Stores maintenance occurrences:
|
|
|
|
- `id`
|
|
- `description`
|
|
- `photo_url`
|
|
- `created_by`
|
|
- `created_at`
|
|
- `updated_at`
|
|
|
|
`photo_url` accepts self-contained `data:image/png|jpeg|webp;base64,...` values only, keeping uploaded camera photos inside the authenticated Oikos database boundary.
|
|
|
|
### `housekeeping_workers`
|
|
|
|
Stores housekeeper-specific employment/payment settings while keeping the person unified with Oikos user/contact/birthday data:
|
|
|
|
- `id`
|
|
- `user_id`
|
|
- `daily_rate`
|
|
- `payment_schedule`
|
|
- `calendar_color`
|
|
- `notes`
|
|
- `created_at`
|
|
- `updated_at`
|
|
|
|
The linked `users` row is excluded from normal Family Management and Family APIs through the `housekeeping_workers` association, but remains synchronized with contacts and birthdays.
|
|
Multiple housekeepers can be registered; each has its own linked `users` row.
|
|
`calendar_color` controls the default color used for housekeeping visit events. Visit events use the cleaning icon (`sparkles`).
|
|
|
|
## REST API
|
|
|
|
All endpoints are mounted under `/api/v1/housekeeping` and inherit the existing `requireAuth` and CSRF middleware.
|
|
|
|
- `GET /summary?month=YYYY-MM`
|
|
- `GET /dashboard`
|
|
- `GET /task-templates`
|
|
- `GET /worker`
|
|
- `GET /workers`
|
|
- `POST /worker`
|
|
- `GET /work-sessions?month=YYYY-MM`
|
|
- `POST /work-sessions/check-in`
|
|
- `POST /work-sessions/check-out`
|
|
- `GET /decay-tasks`
|
|
- `POST /decay-tasks`
|
|
- `PATCH /decay-tasks/:taskId`
|
|
- `POST /decay-tasks/:taskId/complete`
|
|
- `DELETE /decay-tasks/:taskId`
|
|
- `POST /supply-requests`
|
|
- `GET /maintenance-log`
|
|
- `POST /maintenance-log`
|