# Feature Roadmap

## Build Order
1. SaaS foundation: tenant workspace, subscription plans, usage limits, invitations, billing events, feature flags, and workspace/subscription screens.
2. Workflow-aware jobs: statuses, blockers, checklist items, timeline events, and exception dashboard visibility.
3. Customer portal: secure token links, quote approvals, appointment visibility, invoice/payment visibility, uploads, and messages.
4. Inventory and truck stock: item catalog, stock locations, usage capture from jobs, low-stock alerts, and cost rollups.
5. Scheduling intelligence: assignment rules, technician availability, skill matching, conflict detection, route-aware daily boards, and ETA messages.
6. Automation: recurring jobs, reminders, post-visit follow-ups, invoice nudges, and saved notification templates.
7. Reporting: saved reports, exports, technician utilisation, job profitability, quote conversion, and aged receivables.
8. Accounting integrations: OAuth connections, customer/contact sync, quote/estimate sync, invoice export, payment import, item/tax mappings, and sync audit logs for Xero, QuickBooks Online, Sage Accounting, Zoho Books, MYOB, FreeAgent, Reckon, SMEPlus, FreshBooks, and Wave Accounting.
9. Calendar integrations: two-way Google Calendar and Outlook calendar sync, external event links, webhook notification prompts, sync queues, and conflict review.
10. Import intelligence: data-type selection, mandatory field validation, saved mapping profiles, LLM mapping assistant, redacted sample approval, and row-level validation reports.
11. Live billing: Stripe Billing subscriptions, Checkout Sessions, Customer Portal, signed webhooks, and idempotent billing-event processing after test credentials are confirmed.

## Database Contracts Added
- `tenants`, `subscription_plans`, `tenant_subscriptions`, `tenant_usage_counters`, `tenant_invitations`, `tenant_feature_flags`, and `billing_events` support SaaS workspace, billing, onboarding, and plan-control foundations.
- `jobs` now includes blocker, workflow stage, customer-visible status, and completion percent fields.
- `job_checklist_items` stores required technician steps and completion audit data.
- `job_timeline_events` stores status changes, notes, customer events, and other job history.
- `inventory_items` and `truck_stock` prepare for parts and van stock tracking.
- `customer_portal_tokens` supports secure customer approval and visibility links.
- `automation_rules` and `saved_reports` support configurable follow-up workflows and owner reporting.
- `accounting_connections`, `accounting_sync_jobs`, and `accounting_sync_logs` support tenant-scoped accounting provider connections and auditable sync retries.
- `calendar_connections`, `calendar_event_links`, `calendar_sync_jobs`, and `calendar_webhook_events` support tenant-scoped Google/Outlook calendar connections, external event mapping, retryable two-way sync, webhook prompts, and conflict audit state.
- `llm_connections`, `llm_usage_logs`, `import_mapping_profiles`, and `import_validation_reports` support encrypted LLM API configuration, non-sensitive AI audit logs, saved import mappings, and validation reports.

## UX Contracts Added
- `/jobs` shows workflow stats, status filtering, job progress, blockers, next actions, and checklist defaults.
- `/jobs/create` captures title, client, status, priority, scheduled date, blocker reason, and technician notes.
- `/dashboard` highlights blocked and urgent workflow exceptions.
- `/settings/accounting` lists all requested accounting providers, supported capabilities, provider status, active connection slots, and official documentation links where available.
- `/settings/calendar` lists Google Calendar and Outlook calendar providers, connection slots, two-way sync rules, linked event examples, and provider sync strategies.
- `/settings/llm` lists supported LLM API providers and import AI guardrails.
- `/import-data` now supports data-type selection, mandatory field display, validation preview, LLM mapping assistant entry point, and import protocol rules.
- `/pricing`, `/workspace`, and `/subscription` introduce SaaS pricing, tenant workspace, onboarding, usage, and plan-management views.
- Replit-inspired operating shell added: persistent sidebar, demo role bar, KPI dashboard, card grids, search/status filters, schedule planner, AI assistant, import/export, team, reports, and settings pages.

## Screenshot Feature Incorporation
- Dashboard: KPI cards, recent jobs, pending quotes, and quick actions.
- Jobs: searchable card grid with status badges, due dates, clients, addresses, and blocker visibility.
- Schedule: weekly planning strip, unscheduled jobs, and an AI optimize entry point.
- Quotes, invoices, and clients: card-based searchable operating views.
- AI assistant: quote helper, schedule optimizer, general assistant modes, job context selector, and response panel.
- Import/export: CSV workflow steps, upload drop zone, export selection cards, and export details.
- Admin: team member table, reports cards, profile/settings, notification toggles, security panel.

## Next Implementation Steps
- Wire authenticated tenant context through all repository methods before production data entry.
- Add tenant creation, invite acceptance, plan enforcement, and audit logging for SaaS workspace changes.
- Wire `JobRepository` to live MySQL in `public/index.php` after local XAMPP credentials are confirmed.
- Add job detail routes once the router supports path parameters.
- Add customer portal controller, token hashing service, and approval audit events.
- Add inventory usage capture on job completion and report material cost on invoices.
- Add tests around repository SQL using an isolated test database.
- Implement live OAuth flows only after provider app credentials, redirect URLs, encryption key management, and sandbox tenants are confirmed.
- Implement Google Calendar and Microsoft Graph OAuth, webhook receivers, delta/sync-token workers, and conflict-resolution UI only after app credentials and HTTPS callback URLs are confirmed.
- Replace demo-only AI/import/export actions with live services only after provider credentials, upload validation rules, redacted-sample approval, and review/commit flows are confirmed.
- Implement live Stripe billing only after Stripe test credentials, webhook signing secret, success/cancel URLs, and subscription price ids are confirmed.