initial commit

This commit is contained in:
ray
2026-07-12 10:01:39 -04:00
commit fc8290d668
185 changed files with 38831 additions and 0 deletions
@@ -0,0 +1,370 @@
# ShopProQuote — Product Evaluation & Recommendations
_Generated: 2026-07-04 · Based on full codebase review of `spq-v2`_
---
## 1. Current Product State Summary
The app is a **single authenticated React/Vite + PocketBase application** originally designed as a quote generator for an auto repair shop. It has expanded well beyond quotes into operational tools:
- Quotes (generate, save, print, PDF, export as images, AI explanations, priority analysis, AI service suggestions)
- Service Catalog (reusable services with pricing, categories, toggle active/inactive)
- Customers (records, vehicles, linked RO/quote history)
- Repair Orders (full lifecycle: write-up → active → in-progress → waiting parts → waiting pickup → completed → final close; time tracking, clock, audit timeline, financial summary, tech clock, void/unvoid, promised time overrides)
- Appointments (schedule, check-in → create RO, status changes, scan/screenshot OCR extraction)
- Invoices (create, edit, print, generate from RO)
- Financial Dashboard (revenue, costs, profit, customer LTV, warranty analysis, monthly trends)
- Settings (8 tabs: account, business info, advisors, tax/fees, quote defaults, PDF/branding, business ops, notifications)
- PDF generation (both quote PDF and RO work-order PDF, branded with logo, accent color, rich-text footer/payment terms)
- AI integration (DeepSeek for explanations, priority analysis, catalog descriptions, OCR for screenshots)
**Backend**: PocketBase (self-hosted), user-scoped collections, real-time subscriptions, local-only auth.
---
## 2. What Already Fits the Target Audience Well
The product already covers the core workflows that advisors, home mechanics, and mobile mechanics need:
| Feature | Value to Target Users |
|---|---|
| Quote generator | Core service — all users need professional quotes |
| Service catalog | Advisors and mechanics build reusable price lists |
| Professional PDF quotes | Customer-facing output with logo, branding, pricing, disclaimers |
| Customer records | Repeat business tracking |
| Repair order lifecycle | Full shop workflow — works for advisors and mechanics |
| Appointment scheduling | Essential for scheduling mobile/home visits |
| AI-written explanations | Saves time, sounds professional |
| Discount, tax, shop charge | Handles real pricing complexity |
| Phone formatting, VIN notes | Automotive-specific touches |
| PDF export + print + image export | Flexible customer delivery |
| RO → Quote conversion | One job produces both an RO and a customer quote |
| App → RO check-in | Office workflow for physical shops |
---
## 3. What Hurts Professionalism (Fix Immediately)
These issues make the app feel like a development project rather than a polished product:
### 3.1 Developer-Facing Messages Visible to Users
The most damaging issue. Multiple screens show messages like:
- `SetupBanner.tsx`: "Collection Not Found" with a hardcoded admin URL `http://192.168.50.98:8091/_/`
- `Appointments.tsx`: Raw error text about creating PocketBase collections with field types
- `Customers.tsx`, `RepairOrders.tsx`, `Invoices.tsx`, `FinancialDashboard.tsx`: Similar raw setup messages
- `Unknown error` and `Something went wrong` patterns in toast messages
**Fix**: Replace every instance with user-friendly setup prompts or internal-only logs. A first-run setup screen should replace all of these.
### 3.2 Generic Error Handling
`"Something went wrong"` and `"Unknown error"` appear in error states. This erodes trust. Every error path should show a useful message.
### 3.3 Generic SaaS Visual Identity
- Green/gray Tailwind defaults → looks like every other admin panel
- No automotive or service-industry visual cues
- No distinctive typography, iconography, or brand personality
### 3.4 Emojis in UI Buttons and Status Labels
Emojis appear in buttons like `🔧 Labor Only`, `✅ In Stock`, `⚠️ Need Order`, `💡 Aftermarket`, and `🔧 Tech Notes (Internal)`. This reads as casual or unpolished. Replace with text labels or subtle icons.
### 3.5 Product Name and Tagline Are Too Narrow
- The app is called **ShopProQuote** but it does far more than quotes
- Login screen says: `"Sign in to manage your quotes"` — this is misleading for RO, invoices, appointments, etc.
- The product scope has outgrown the name
### 3.6 Empty State Language Is Too Casual
`"Start building your customer database! Add your first customer to get started."` — better to sound professional and specific.
### 3.7 No Onboarding / First-Run Setup
When a new user signs up, they see empty screens and PocketBase errors. There is no guided setup: business name, logo, tax rate, shop charge, labor rate, quote terms, etc.
---
## 4. Missing Features for Advisors, Home Mechanics, and Mobile Mechanics
### 4.1 Customer Authorization / Signature (High Priority)
- Quoted services need a clear **customer authorized** state
- Authorization should include: customer name, timestamp, method (in-person/phone/email/text/signature)
- Declined services should have customer acknowledgment
- **Why**: In auto repair, verbal authorization is common but documentation is critical for liability protection
### 4.2 Customer-Facing Quote Approval Flow (High Priority)
- Currently quotes exist as PDF downloads only
- There is no way to:
- Send a link to a customer for review
- Let customers approve/decline services online
- Track when a customer viewed the quote
- **Why**: Mobile and home mechanics need quick customer approval without printing
### 4.3 Service Location / Mobile Job Fields (High Priority)
- No address for mobile/home service jobs
- No travel fee or diagnostic fee
- No arrival window or estimated travel time
- No "shop", "mobile", "roadside" service type
- **Why**: This is the defining difference between shop software and mobile mechanic software
### 4.4 Photo Attachments (High Priority)
- No ability to attach photos to customers, quotes, repair orders, or services
- No before/after photos
- No inspection evidence (leaks, tire wear, brake thickness, damage)
- **Why**: Photos are standard in professional auto repair estimates and documentation
### 4.5 Payment / Deposit Tracking (High Priority)
- Invoices exist, but:
- No payment method tracking (cash, card, Zelle, PayPal, etc.)
- No deposit/partial payment tracking
- No "paid" vs "unpaid" vs "partial" states on quotes or ROs
- No payment receipt generation
- **Why**: Mobile and home mechanics often collect payment on completion or require deposits
### 4.6 Customer Communication Log (Medium Priority)
- SMS/email buttons exist in RO details but there is no unified log
- No communication history tied to customer or RO
- No sent quote tracking, customer response tracking
- **Why**: Professional service records include customer communication
### 4.7 Legal / Professional Terms (Medium Priority)
No built-in support for:
- Warranty disclaimer text on quotes
- Diagnostic fee disclosure
- Storage fee / lien notice
- Declined-work disclaimer
- Authorization for test drive, additional work, parts ordering
- Mobile service terms (access to property, weather, etc.)
### 4.8 Parts Tracking (Medium Priority)
Current parts status is basic toggles (in stock, need order, aftermarket). Missing:
- Part numbers
- Supplier / vendor
- Cost price vs sell price
- Core charge tracking
- Ordered date and ETA
- Received status
### 4.9 Data Export / Backup (Medium Priority)
- No CSV/JSON export for customers, quotes, ROs
- No PDF archive option
- **Why**: Professionals need to own their data
### 4.10 Route / Calendar Integration (Lower Priority)
- No Google Calendar, iCal, or ICS export for appointments
- No route/map link for mobile service addresses
---
## 5. What May Not Fit (Consider Dual Mode)
### 5.1 "Service Advisor" Language Is Shop-Centric
- Advisors, waiters, drop-offs → these terms fit a dealership or shop
- **Mobile mechanic** does not have an "advisor"; they are the technician
- **Solution**: Make the role label configurable in settings or detect business type
### 5.2 Financial Dashboard May Be Overwhelming for Solo Users
- Customer LTV, warranty GP split, cost breakdown — valuable for a shop owner
- Solo mechanics may find this noisy until they grow
- **Solution**: Show simplified dashboard by default for non-admin users; hide until needed
### 5.3 Waiter / Drop-Off Model Does Not Fit Mobile
- Mobile mechanics need: `on-site`, `driveway`, `shop`, `roadside`, `mobile visit`
- **Solution**: Business type toggle → mobile mode replaces waiter/drop-off with location/time-based fields
---
## 6. Recommended Product Direction
### 6.1 Positioning
```
Professional repair quotes, approvals, and tracking
for shops, advisors, and mobile mechanics.
```
### 6.2 Dual Operating Mode
| Feature | Shop / Advisor Mode | Mobile Mechanic Mode |
|---|---|---|
| Customer type | Waiter / Drop-off | On-site / Mobile / Drop-off |
| Service location | Shop address | Per-job address |
| Travel fee | Disabled | Configurable fee + mileage |
| Advisor field | Service Advisor (configurable) | Technician / Self |
| RO board | Active / All / Completed | Same but simplified |
| Photos | Optional | Core feature |
| Payment | At counter | At job site + deposit |
| Arrival window | Not needed | Estimated arrival window |
---
## 7. Highest-Priority Changes (Ordered by Impact)
### Priority 1 — Trust & Professionalism
1. Remove every developer-facing message (PocketBase collection errors, admin URLs, field type instructions)
2. Replace `"Something went wrong"` and `"Unknown error"` with helpful, specific messages
3. Replace emojis in buttons/status with text or subtle icons
4. Add first-run onboarding: business type, business name, logo, contact, tax rate, labor rate, shop charge, quote terms, payment terms
5. Improve empty state messaging to sound professional and product-ready
### Priority 2 — Mobile Mechanic Foundation
6. Add service address field to ROs and appointments
7. Add travel fee, diagnostic fee, and mileage tracking
8. Add mobile vs shop service type flag
9. Add arrival window / estimated travel time to appointments
### Priority 3 — Customer Trust & Approval
10. Add customer authorization state (name + timestamp + method)
11. Add customer-facing quote approval flow (link or secure page)
12. Add photo attachment to quotes, ROs, and inspections
### Priority 4 — Payments & Financial
13. Add deposit tracking on quotes and ROs
14. Add payment method and payment status
15. Add basic payment receipt
### Priority 5 — Polish
16. Make advisor/technician label configurable
17. Add CSV export for customers, quotes, and ROs
18. Add legal disclaimer placeholders (warranty, fee disclosure, authorization)
19. Refine visual identity toward automotive/service-industry feel
20. Consider product name expansion or tagline update
---
## 8. Suggested Implementation Plan
### Phase 1: Production Proofing (1-2 weeks)
- Replace all `SetupBanner` and collection-not-found errors with onboarding flow
- Rewrite error handling across all pages
- Remove emojis from operational UI
- Improve empty states and error states
- Add first-run setup wizard (business profile)
### Phase 2: Mobile Mechanic Mode (2-3 weeks)
- Add service location, travel fee, diagnostic fee, mileage fields
- Add mobile/shop service type toggle to ROs and appointments
- Create configurable role labels (advisor → technician or self)
- Add arrival window to appointments
### Phase 3: Customer Approval & Photos (2-3 weeks)
- Build customer authorization state
- Build customer-facing quote approval page/link
- Add photo upload to customers, quotes, ROs
- Add photo gallery to RO details
### Phase 4: Payments & Polish (2-3 weeks)
- Add deposit tracking
- Add payment method and status
- Add receipt generation
- Add CSV export
- Add legal disclaimer settings
- Visual identity refinement
---
## 9. What NOT to Build Next
- Do not add more internal dashboards or financial reports (already sufficient)
- Do not add multi-tenant/team features (out of scope)
- Do not add real-time chat or elaborate notification systems
- Do not add inventory management or full parts ordering
- Do not rebuild the existing workflows — polish what works
The app already has strong internal tools. The next investment should be **customer-facing trust**: approvals, photos, mobile jobs, payments, and professional polish.
## Execution Memo: 2026-07-05 - Customer-Facing Quote Approval Flow
- Completed: Built a full public customer-facing quote review and approval flow. Created `src/pages/QuoteApprove.tsx` — a standalone branded page that loads a quote via a secure share token (no login required), displays services with individual Approve/Decline buttons, shows a pricing summary, and records customer decisions back to the quote record. Added `shareToken` field to the quotes PocketBase collection via `pb_migrations/1739999000007_quote_share_token.js` with relaxed view/update rules that allow public access only when the token matches. Added a "Share with Customer" button to the QuoteGenerator sidebar that generates a random UUID token, saves it to the quote, and copies the approval URL to the clipboard. The `authorizedMethod` type now includes `'online'` for decisions made through this flow. Registered the `/quote/approve?token=xxx` route as a public route in `src/App.tsx`.
- Resolved roadmap priority: Priority 3 — Customer Trust & Approval, item 11 by giving shop owners a frictionless way to send quotes to customers for online review and approval without printing or requiring customer accounts.
- Think Tank benefit: The mobile mechanic gained instant on-site customer approvals without printing or face-to-face pressure, the service advisor gained documented online authorization trails that protect against disputes, and the home mechanic gained a simple way to share cost estimates with family members for collaborative decision-making.
## Execution Memo: 2026-07-05 - Login Scope Copy Update
- Completed: Updated the login screen tagline from `Sign in to manage your quotes` to `Sign in to manage your shop` in `src/pages/Login.tsx`.
- Resolved roadmap priority: Priority 1 - Trust & Professionalism, item 1 and item 20 by removing a narrow quotes-only message that no longer reflects the product's broader workflow coverage.
- Think Tank benefit: The service advisor valued the more credible shop-wide positioning, the mobile mechanic valued that the app no longer reads like a quotes-only tool in front of customers, and the home mechanic valued the clearer description of the product's actual scope.
## Execution Memo: 2026-07-05 - Operational UI Emoji Removal
- Completed: Removed emoji-based labels from the quote workflow controls and status text in `src/pages/QuoteGenerator.tsx`, and removed the emoji badge text from the theme mode indicator in `src/pages/Settings.tsx`.
- Resolved roadmap priority: Priority 1 - Trust & Professionalism, item 3 by replacing casual emoji-driven labels with cleaner professional copy while preserving existing workflows and visual states.
- Think Tank benefit: The service advisor saw a more credible customer-facing presentation, the mobile mechanic saw less distracting UI in fast job-site workflows, and the home mechanic saw a more polished tool that reads like professional repair software instead of a casual app.
## Execution Memo: 2026-07-05 - Setup State Professionalization
- Completed: Replaced the remaining generic setup blockers in `src/components/SetupBanner.tsx`, `src/pages/Invoices.tsx`, `src/pages/FinancialDashboard.tsx`, and `src/pages/Settings.tsx` with workflow-specific professional messaging, and replaced the vague verification fallback copy in `src/pages/Verify.tsx` with actionable guidance.
- Resolved roadmap priority: Priority 1 - Trust & Professionalism, item 1 and item 2 by removing the last generic setup-facing UI language and improving a remaining non-specific error state.
- Think Tank benefit: The service advisor valued clearer customer-ready document setup guidance, the mobile mechanic benefited from less confusing blocked-state messaging during active workflows, and the home mechanic benefited from more direct instructions that explain what to do next without exposing internal implementation details.
## Execution Memo: 2026-07-05 - Empty State Copy Refresh
- Completed: Rewrote customer-facing empty and search-empty messaging in `src/pages/Customers.tsx`, `src/pages/Appointments.tsx`, `src/pages/RepairOrders.tsx`, `src/pages/FinancialDashboard.tsx`, `src/pages/Invoices.tsx`, `src/pages/Settings.tsx`, `src/pages/ServiceCatalog.tsx`, and `src/pages/QuoteGenerator.tsx` so each state explains the workflow purpose and next step more professionally.
- Resolved roadmap priority: Priority 1 - Trust & Professionalism, item 5 by replacing casual or sparse no-data language with clearer production-ready guidance across core workflows.
- Think Tank benefit: The service advisor valued cleaner customer-record and invoice messaging, the mobile mechanic benefited from clearer scheduling and quote guidance during day-to-day use, and the home mechanic benefited from empty states that explain what each tool is for without sounding like unfinished software.
## Execution Memo: 2026-07-05 - Appointment And RO Service Address Support
- Completed: Added service-address capture to the standard appointment create/edit flow in `src/pages/Appointments.tsx`, preserved appointment service locations through structured note serialization for schema compatibility, and surfaced service locations in appointment and repair-order search and list views in `src/pages/Appointments.tsx`, `src/pages/RepairOrders.tsx`, and `src/components/ROForm.tsx`.
- Resolved roadmap priority: Priority 2 - Mobile Mechanic Foundation, item 6 by carrying service-address information through appointments and repair orders without requiring PocketBase schema changes.
- Think Tank benefit: The service advisor valued clearer job-site context when preparing work, the mobile mechanic gained a practical on-site address workflow for scheduling and RO handoff, and the home mechanic benefited from being able to record where the work will happen without burying it in general notes.
## Execution Memo: 2026-07-05 - Trip Mileage & Diagnostic Fee Tracking
- Completed: Added `tripMiles` as a first-class concept for mobile mechanic tax-mileage tracking across appointments, repair orders, and PDF documents. Wired through appointment create/edit/check-in flows, RO form create/edit, RO list/row visibility, RO details panel, RO PDF info and totals sections, and appointment card display. Diagnostic fee already existed as the travel-fee field with proper "Travel / Diagnostic Fee" labeling in the UI and settings.
- Resolved roadmap priority: Priority 2 - Mobile Mechanic Foundation, item 7 by making trip mileage and diagnostic/travel fee first-class workflow fields that flow from appointment scheduling through to the tax-ready RO PDF.
- Think Tank benefit: The mobile mechanic gained a practical tax-mileage log that records trip distance per service call and prints on PDFs for deduction records, the service advisor gained trip-distance visibility on RO lists, and the home mechanic benefited from coordinated trip tracking without manual note-keeping.
## Execution Memo: 2026-07-05 - Arrival Window For Appointments
- Completed: Added `arrivalWindowMinutes` to the appointment type, form data, note serialization, and create/edit modal UI in `src/pages/Appointments.tsx`. The arrival window appears as a time-range display on the appointment card (e.g. "8:00 AM — 10:00 AM") when set, and defaults to "Exact time" when zero. Gated behind the mobile/home business-type toggle like other location fields.
- Resolved roadmap priority: Priority 2 - Mobile Mechanic Foundation, item 9 by adding a customer-facing arrival-window concept that tells the customer when to expect the mechanic without pinning it to an exact minute.
- Think Tank benefit: The mobile mechanic valued being able to provide a realistic time range to customers instead of a hard-to-keep exact time, the service advisor benefited from cleaner schedule presentation when communicating with waiting customers, and the home mechanic benefited from a simpler visual schedule layout.
## Execution Memo: 2026-07-05 - Customer Authorization State
- Completed: Added authorization metadata fields (`authorizedBy`, `authorizedAt`, `authorizedMethod`) to the `QuoteService` type in `src/types.ts`. Updated the Zustand quote store (`src/store/quote.ts`) so `toggleApproved` and `toggleDeclined` automatically populate authorization with customer name, current timestamp, and default method ("In Person"), and clear authorization when reverting to pending. Enhanced the QuoteGenerator expanded service row (`src/pages/QuoteGenerator.tsx`) with an inline authorization panel (authorized-by input, method dropdown with in_person/phone/email/text/signature options, and a formatted timestamp) that appears when a service is approved or declined. Updated the quote PDF generator (`src/lib/pdf.ts`) to render the authorization method and authorized-by name as a sub-line beneath the approval/decline badge on each service.
- Resolved roadmap priority: Priority 3 - Customer Trust & Approval, item 10 by giving every quote service a documented authorization trail that captures who approved or declined, when, and through which method.
- Think Tank benefit: The service advisor valued the liability protection of timestamped customer authorization records printed on customer-facing documents, the mobile mechanic valued frictionless on-site authorization capture via method-specific tracking, and the home mechanic valued clear decision documentation without a clunky workflow.
## Execution Memo: 2026-07-05 - Public Quote Approval URL + Signature & Send Improvements
- Completed: Added a full customer-facing quote approval flow via public share link. Created `pb_migrations/1739999000007_quote_share_token.js` adding a `shareToken` field and relaxed list/view/update rules on the `quotes` collection. Created `src/pages/QuoteApprove.tsx` — a branded public page at `/quote/approve?token=xxx` where customers review and approve/decline services. Added a "Share with Customer" button to the QuoteGenerator sidebar and wired the approval page URL generation. Stamped decisions with `authorizedMethod: 'online'` and added the `'online'` value to the authorizedMethod type union. Added the route as public in `src/App.tsx`.
- Then improved the flow in a second pass: added `pb_migrations/1739999000008_quote_viewed_at.js` for first-view tracking. Rewrote the approval page to stage decisions locally, require a typed full-name signature before final submission, and submit all decisions in a single update with correct top-level status (all approved -> `approved`, all declined -> `declined`, mixed -> `sent`). Added a shared `src/lib/contactLinks.ts` helper for `mailto:`/`sms:` draft generation and refactored `RepairOrders.tsx` to use it. Added "Send Email" and "Send Text" buttons to the quote share panel that open device drafts with the approval URL embedded.
- Resolved roadmap priority: Priority 3 - Customer Trust & Approval, item 11.
- Think Tank benefit: The mobile mechanic can now text a live approval link from the job site and get a signed decision record, the service advisor gains a documented online authorization trail with a typed-name signature that prints on PDFs, and the home mechanic gets a simple send-via-email workflow for sharing cost estimates with family.
## Execution Memo: 2026-07-05 - Role-Based Experience Roadmap
- Completed: Created `Roadmap.md` with the full implementation plan for post-onboarding role-based experiences across Advisor, Technician, and Mobile Mechanic users. The plan defines role permissions, route architecture, mobile owner access, technician-safe assignment records, PocketBase schema requirements, security rules, onboarding updates, and verification steps.
- Resolved roadmap priority: RBX architecture planning for strict Advisor, Technician, and Mobile separation while preserving Priority 1 professionalism and preparing safe implementation of future workflow phases.
- Think Tank benefit: The service advisor gains a clear path to full desk tools and technician assignment control, the shop technician gains a protected bay-only workflow with no billing exposure, and the mobile mechanic keeps full owner-level quote, catalog, invoice, and financial access in a field-first interface.