oikos/IMPLEMENTATION.md

Housekeeping Implementation

Backend

The module is implemented in server/routes/housekeeping.js and registered in server/index.js under:

/api/v1/housekeeping

The registration happens after the global authenticated /api/v1 middleware, so the module follows the existing Oikos security model:

• Session or API-token authentication required.
• CSRF required for state-changing session requests.
• API rate limiting inherited from /api/.
• No unauthenticated housekeeping route.

Database schema is migration 33 in server/db.js. The migration creates:

• housekeeping_work_sessions
• housekeeping_decay_tasks
• housekeeping_supply_requests
• housekeeping_maintenance_log

Migration 34 adds:

• housekeeping_workers
• housekeeping_work_sessions.paid_at

Migration 35 adds per-staff visit tracking:

• housekeeping_workers.calendar_color
• housekeeping_work_sessions.worker_id
• housekeeping_work_sessions.calendar_event_id

Each staff profile links to users.id. These users are hidden from the normal family list by filtering rows associated with housekeeping_workers, while contact and birthday sync remains shared with the existing family-member artifact flow.

The quick supply endpoint uses a SQLite transaction:

1. Resolve the first existing shopping list, or create Housekeeping.
2. Insert a shopping_items row.
3. Insert a housekeeping_supply_requests row linked to the shopping item.

If any step fails, the transaction rolls back.

Frontend

The SPA route /housekeeping is registered in public/router.js and loads:

• public/pages/housekeeping.js
• public/styles/housekeeping.css

The page uses the existing API wrapper in public/api.js, so CSRF tokens and auth expiry behavior remain centralized. The UI now follows the standard Oikos module layout: sticky toolbar, horizontal tab chips, and regular cards. Check-in/check-out actions live beside each staff member on the Dashboard and are disabled until at least one staff member exists.

Calendar integration creates a local calendar event at check-in, assigns it to the staff user, uses the staff calendar color, and updates the end time on check-out. Calendar event icon selection now opens a dedicated icon picker dialog instead of expanding inline inside the event modal.

The UI intentionally avoids innerHTML; rendering uses replaceChildren() and insertAdjacentHTML() with escaped dynamic values.

Localization

The module adds:

• nav.housekeeping
• housekeeping.*

to every JSON locale under public/locales.

Portuguese is the primary text for the cleaner-facing target workflow, with localized strings for the most common existing languages and English fallback text for remaining locales.

Validation

Backend validation covers:

• Required strings and max lengths.
• Positive integer frequency_days.
• Non-negative daily_rate and extras.
• YYYY-MM month filters.
• Maintenance photos limited to PNG, JPEG, or WebP data URLs under 6 MB.

Manual Use

1. Navigate to /housekeeping.
2. Use the check-in/check-out button next to the staff member on the Dashboard.
3. Review the Dashboard metrics and payment chart.
4. On Tasks, choose suggested chores or create a custom recurring chore.
5. On Reports, take/upload a photo and submit a maintenance description.
6. On Staff, create or update one or more housekeepers, contacts, birthdays, rates, and payment schedules.