Prototype Specification Refinement Derived from observable frontend behavior, local store logic, and mock simulation flows
| Field | Value |
|---|---|
| System | AutoWash Pro / AURA CAR CARE |
| Repository Type | Frontend prototype |
| Primary Sources | UI logic, route behavior, local stores, mock module state |
| Enforcement Model | Frontend-only simulation |
| Persistence | Browser localStorage plus module-local in-memory mock state |
| Specification Basis | Observable prototype behavior only |
- 1. Prototype Scope
- 2. Prototype Architecture Notes
- 3. Role-Based Main Flows
- 4. Business Rules
- 4.1 Authentication, Access, and Localization
- 4.2 Customer Registration and Profile
- 4.3 Vehicle Management
- 4.4 Customer Booking and Payment Simulation
- 4.5 Shared Booking and Operational Simulation
- 4.6 Staff Operations
- 4.7 Loyalty, Points, and Membership
- 4.8 Promotions, Vouchers, and Combos
- 4.9 Admin Management UI
- 4.10 Notifications, Support Chat, and Live Tracking
- 5. Function to Business Rule Mapping
- 6. Reconciliation with Baseline README
- 7. Open Assumptions and Prototype Notes
This repository is a prototype that simulates a smart car wash system through frontend pages, local stores, and mock data. There is no real backend, no database, no external API enforcement, and no production payment integration.
Observable behavior comes from:
- route guards and page navigation
- React component state
- shared portal store logic in
src/lib/carwash-store.tsx - module-local customer booking state in
src/modules/customer-booking/routes.tsx - browser localStorage persistence for the shared portal store
- form validation, conditional rendering, and local notifications
- public homepage for unauthenticated visitors
- demo login, registration, OTP verification, and guest-only routing
- role-based workspaces for
Customer,Staff, andAdmin - customer profile editing
- customer vehicle management
- customer booking checkout flow with simulated upfront payment choice
- customer loyalty, combo, voucher, booking, wash, and transaction views
- staff check-in, wash start, and wash completion simulation
- admin dashboards, bookings, accounts, loyalty, promotions, reports, and settings
- customer notification bell behavior
- customer-staff/admin support chat simulation
- live wash progress tracker on customer home
- real backend/API validation
- real payment processing
- real OTP delivery
- real email delivery
- database persistence
- hardware integration
- a single perfectly unified business state model shared across every module
This prototype currently uses two different business state models.
src/lib/carwash-store.tsx
- powers authentication, staff operations, admin pages, settings, ledger, reminders, notifications, support chat, transactions, and most portal-level business logic
- persists to browser localStorage
src/modules/customer-booking/routes.tsx
- powers
/customer/home,/customer/vehicles,/customer/bookings,/customer/history, and/customer/loyalty - keeps its own mock vehicles, bookings, packages, combos, and vouchers
- customer booking pages and admin/staff pages are not fully synchronized to one source of truth
- admin package and promotion edits affect the shared portal store only
- customer booking pages still use their own mock package/combo/voucher catalog
- several flows are therefore valid inside their own module, but not fully connected end to end
This README documents observable prototype behavior exactly as implemented, including those splits.
- Visitor lands on
/. - If not authenticated, the public homepage renders.
- Visitor can browse services, combos, testimonials, and theme/language toggles.
- Visitor can open
Sign InorRegister. - If already authenticated, guest routes redirect to the appropriate role workspace.
- Customer registers with full name, Vietnamese phone number, password, and password confirmation.
- Registration creates a pending local OTP challenge and redirects to
/verify. - OTP verification activates the account locally.
- Customer lands in
/customer/home. - Customer can manage profile and vehicles.
- Customer can create a booking through a checkout-like flow.
- Customer chooses:
SINGLE_PACKAGE, with package, add-ons, voucher, and payment methodCOMBO, using the active combo and linked vehicle
- Payment is simulated inside booking creation:
- zero-amount combo bookings are treated as paid
- bank transfer and e-wallet are mock paid flows
- cash at counter is stored as pay-later
- Confirming the form creates a module-local booking with status
CONFIRMED. - Customer can view booking/wash/point history, redeem point vouchers, receive local notifications, and open the floating support chat.
- Staff signs in and lands on
/staff/dashboard. - Staff opens
/staff/operationsor/staff/check-in. - Staff filters the queue by status, time bucket, hour, and assigned staff.
- Staff verifies the plate before check-in.
- Check-in creates or refreshes an operational wash session and assigns an active available staff member.
- Staff starts washing.
- Staff completes the wash.
- Staff can also open the shared support inbox and reply to customer chat threads.
- Admin signs in and lands on
/admin/dashboard. - Admin reviews KPIs, operational bookings, assignments, and status summaries.
- Admin opens
/admin/bookingsto filter bookings and inspect operational state. - Admin opens
/admin/customers, now labeledAccounts, to inspect customers, staff, and admin accounts in one directory. - Admin manages loyalty rules, promotions, reports, and settings in the shared portal store.
- Admin can also reply in the shared support chat inbox.
| BR ID | Rule |
|---|---|
| BR-01 | / is the public landing page for unauthenticated users. |
| BR-02 | Authenticated users are redirected away from guest pages to their role home path. |
| BR-03 | Role home paths are /customer/home, /staff/dashboard, and /admin/dashboard. |
| BR-04 | Protected routes redirect unauthenticated users to /login. |
| BR-05 | Protected routes render an access denied state when the signed-in role is not allowed. |
| BR-06 | Customer login succeeds only if credentials match a local auth account and the linked customer record is active. |
| BR-07 | Staff login succeeds only if an active staff record can be resolved. |
| BR-08 | Demo role switching exists in the shell and can replace the current workspace role without backend auth. |
| BR-09 | Customer-facing copy supports English and Vietnamese toggles. |
| BR-10 | The customer booking module persists its selected language in localStorage. |
| BR ID | Rule |
|---|---|
| BR-11 | Registration form requires full name, Vietnamese phone number, password, and confirm password. |
| BR-12 | Registration form does not collect email in the current UI. |
| BR-13 | Password must be at least 6 characters. |
| BR-14 | Confirm password must match password. |
| BR-15 | Phone number must match local Vietnamese format 0 followed by 9 digits. |
| BR-16 | Registration starts a local OTP challenge before account activation. |
| BR-17 | OTP must be verified before the account is activated. |
| BR-18 | OTP can be resent while a pending registration exists. |
| BR-19 | Completing registration creates a new Customer account with tier Member, 0 points, and active status in the shared store. |
| BR-20 | If no email is supplied during registration, the shared store generates a placeholder local email from the phone number. |
| BR-21 | Phone numbers must be unique among active customers and auth accounts. |
| BR-22 | Profile editing requires non-empty name, valid email shape, and 8-11 numeric phone digits. |
| BR-23 | Profile page displays phone and email as verified; this is presentation behavior only. |
| BR-24 | The shared store contains a pending phone-change OTP flow, but the current customer profile page does not expose it. |
| BR-25 | Forgot password is a standalone UI simulation using hardcoded OTP 123456; it does not update shared auth credentials. |
| BR ID | Rule |
|---|---|
| BR-26 | Customer booking pages cannot proceed to booking when the module-local vehicle list is empty. |
| BR-27 | Vehicle form in the customer booking module requires a license plate. |
| BR-28 | Vehicle form selects brand first, then model from a brand-specific catalog. |
| BR-29 | Vehicle type is auto-derived from the selected brand-model mapping and is read-only in the form. |
| BR-30 | Vehicle color is optional. |
| BR-31 | Vehicle photo upload is optional, but uploaded files must be images. |
| BR-32 | The first customer-booking vehicle becomes default automatically. |
| BR-33 | Marking a vehicle as default unsets other defaults in the customer booking module. |
| BR-34 | Deleting the default vehicle in the customer booking module promotes the first remaining vehicle to default. |
| BR-35 | Shared-store vehicle plates are normalized to uppercase without spaces before matching. |
| BR-36 | Shared-store vehicle plates must match Vietnamese plate format. |
| BR-37 | In the shared store, an active customer cannot take a plate already owned by another active customer. |
| BR-38 | In the shared store, a plate from an inactive owner can be transferred and logged into ownership history. |
| BR-39 | Shared-store vehicle deletion is blocked when the customer would be left with zero vehicles. |
| BR ID | Rule |
|---|---|
| BR-40 | The customer booking form supports SINGLE_PACKAGE and COMBO booking modes. |
| BR-41 | Only service packages with status ACTIVE appear in the customer booking checkout flow. |
| BR-42 | Combo mode is disabled when there is no active combo or remaining combo uses are zero. |
| BR-43 | Combo mode locks the booking to the combo-linked vehicle and combo-supported package. |
| BR-44 | Single-package mode allows add-on selection; combo mode does not expose add-ons. |
| BR-45 | Customer booking schedule defaults to tomorrow at 10:30. |
| BR-46 | Booking time picker blocks slots already occupied by module-local bookings in CONFIRMED, CHECKED_IN, or IN_PROGRESS. |
| BR-47 | Customer booking supports one voucher per booking. |
| BR-48 | Manual voucher entry works only if the code matches a currently usable customer voucher. |
| BR-49 | A usable voucher must be owned by the customer, active, not expired, within usage limit, eligible for the customer's tier, and valid for new-customer targeting if flagged. |
| BR-50 | Single-package payment methods are CASH_AT_COUNTER, BANK_TRANSFER, and E_WALLET. |
| BR-51 | BANK_TRANSFER, E_WALLET, or zero-amount bookings are marked paid immediately in the booking snapshot. |
| BR-52 | Cash bookings are stored with payment status PAY_AT_COUNTER. |
| BR-53 | Combo bookings always store final amount 0 and are treated as paid via combo credit. |
| BR-54 | Confirming the customer booking form creates a module-local booking with status CONFIRMED. |
| BR-55 | Confirming a customer booking immediately marks the selected voucher as used and increments its usage count. |
| BR-56 | Customer booking success screen displays booking code, vehicle, service, schedule, voucher, payment method/status, booking status, and final amount. |
| BR ID | Rule |
|---|---|
| BR-57 | Shared-store booking creation is blocked for blocked customers. |
| BR-58 | Shared-store booking creation is blocked while bookingSuspendedUntil is still in the future. |
| BR-59 | Shared-store booking dates cannot be in the past for non-walk-in bookings. |
| BR-60 | Shared-store booking window depends on the customer tier's bookingWindowDays. |
| BR-61 | Shared-store non-walk-in customers can hold at most 3 active bookings at once. |
| BR-62 | Shared-store duplicate booking by same vehicle, date, and time slot is not allowed while any matching booking is still active. |
| BR-63 | Shared-store slot capacity is limited by shop capacity. |
| BR-64 | Shared-store reserves the last open slot for Platinum customers when no Platinum customer has already booked that slot. |
| BR-65 | Shared-store customer notes are sanitized through a profanity mask before storage. |
| BR-66 | Shared-store cancellation is only allowed from Pending or Confirmed. |
| BR-67 | Shared-store cancellation is blocked when the booking starts in less than 2 hours. |
| BR-68 | Shared-store auto-ban can block a customer after too many cancellations within a rolling window using settings-driven thresholds. |
| BR-69 | Shared-store operational check-in is allowed only from Confirmed or Pending. |
| BR-70 | Shared-store operational check-in marks a booking No-show if arrival is more than 20 minutes late. |
| BR-71 | Legacy session preparation marks a booking No-show if arrival is more than 15 minutes late. |
| BR-72 | Two no-shows inside 30 days in the legacy preparation path trigger a 14-day booking suspension. |
| BR-73 | Shared-store operational check-in creates or refreshes a wash session in Queued state and assigns an active available staff member. |
| BR-74 | Shared-store operational wash start is allowed only after a booking is Checked-in. |
| BR-75 | Starting a wash updates booking wash status to In Progress. |
| BR-76 | Completing an operational wash is allowed only when booking status is Checked-in and wash status is In Progress. |
| BR-77 | Completing an operational wash records completion time, transaction references, and earned points in the shared store. |
| BR ID | Rule |
|---|---|
| BR-78 | Staff dashboard links to Operations and Check-in Queue only. |
| BR-79 | Staff pages are accessible only to the Staff role. |
| BR-80 | Operations board shows booking code, customer, plate, service package, staff, scheduled time, check-in time, estimated finish time, status, and next action. |
| BR-81 | Staff queue supports filtering by status, time bucket, hour, staff, and free-text query. |
| BR-82 | The check-in panel requires a manual plate verification checkbox before enabling check-in. |
| BR-83 | Start washing is enabled only when the booking is already checked in. |
| BR-84 | Complete wash is enabled only when the booking is in progress. |
| BR-85 | Staff assignment uses only staff whose status is Active. |
| BR-86 | A busy staff member cannot be assigned to another non-completed wash session. |
| BR ID | Rule |
|---|---|
| BR-87 | The customer booking module uses customer tiers Silver, Gold, and Diamond. |
| BR-88 | The shared portal store uses tiers Member, Silver, Gold, and Platinum. |
| BR-89 | Customer point-to-voucher redemption requires at least 50 points and at most 200 points per voucher. |
| BR-90 | Customer point-to-voucher redemption rate is 1 point = 1,000 VND voucher value in the customer booking module. |
| BR-91 | A customer can hold at most 3 active point-redeem vouchers at the same time in the customer booking module. |
| BR-92 | Customer point-voucher redemption immediately subtracts available points and adds a REDEEM transaction in the customer booking module. |
| BR-93 | Combo upgrade in the customer booking module awards a fixed bonus of 250 points. |
| BR-94 | Shared-store checkout calculates earned points from floor(finalAmount / 10000) * tier multiplier. |
| BR-95 | Shared-store checkout can redeem only whole loyalty points and caps redemption by customer balance and payable amount. |
| BR-96 | Shared-store reward redemption is blocked for blocked customers or insufficient balances. |
| BR-97 | Shared-store monthly tier review applies pending rule edits on the next review date and recalculates tiers from rolling 12-month points. |
| BR-98 | Shared-store earned loyalty lots expire after 365 days and can trigger 30-day and 7-day warning notifications. |
| BR ID | Rule |
|---|---|
| BR-99 | The customer booking module treats promotions as voucher-like discounts, not as a separate pricing engine. |
| BR-100 | New-customer vouchers are usable only when the local customer profile is marked isNewCustomer. |
| BR-101 | Combo upgrade in customer booking is allowed only when the target combo is more expensive than the current active combo. |
| BR-102 | Combo upgrade requires at least one known vehicle to link the upgraded combo. |
| BR-103 | Shared-store promotions are validated by active flag, date range, and eligible shared-store tier at checkout. |
| BR-104 | Admin promotion form presents three targeting modes in UI: all members, selected tiers, and new customers only. |
| BR-105 | Admin promotion form requires a name, 1-100 discount percent, start date, end date, and at least one tier when targeting selected tiers. |
| BR-106 | In the shared store, the admin form's new customers only mode is currently translated into Member tier targeting rather than a true completed-booking history check. |
| BR-107 | Shared-store promotion creation is blocked when start date is after end date. |
| BR-108 | Shared-store package removal is blocked if an active booking still references that package name. |
| BR-109 | Shared-store package status can be set to ACTIVE or INACTIVE. |
| BR ID | Rule |
|---|---|
| BR-110 | Admin dashboard KPI cards are derived from live shared-store bookings, transactions, and promotions. |
| BR-111 | Admin dashboard booking list can be filtered by date and paginated. |
| BR-112 | Admin bookings page supports filters for status, date, and customer name. |
| BR-113 | Admin bookings page maps In Progress from shared booking status Checked-in plus wash status In Progress. |
| BR-114 | Admin bookings page does not let users manually set IN_PROGRESS; that state is presented as operationally derived. |
| BR-115 | Booking detail drawer shows staff assignment as editable only when a linked wash session exists and that session status is In Progress. |
| BR-116 | Admin Accounts directory supports search, role filter, tier filter, status filter, and pagination. |
| BR-117 | The Accounts directory merges customer, staff, and admin records into one admin list. |
| BR-118 | Customer detail tabs are Profile, Vehicles, Bookings, Wash History, Point Transactions, and Tier History. |
| BR-119 | Non-customer accounts open a lighter summary panel rather than the full customer detail view. |
| BR-120 | Customer status changes persist to the shared store from admin detail view. |
| BR-121 | Customer role changes in admin detail view are presentation-only and are not persisted in this prototype. |
| BR-122 | Admin settings persist to browser localStorage on the current device. |
| BR-123 | Reports are computed from the shared store and include booking trends, promotion effectiveness, point summaries, no-show metrics, and daily staff wash counts. |
| BR-124 | The daily staff wash counts report supports date filtering and pagination. |
| BR ID | Rule |
|---|---|
| BR-125 | Customer reminder watcher polls every 30 seconds and fires local reminder notifications for due shared-store bookings. |
| BR-126 | Reminder notifications are deduplicated via reminder keys stored in localStorage. |
| BR-127 | Shared-store booking confirmation, checkout completion, auto-suspension, loyalty expiry warnings, and support replies push local notification items into the store. |
| BR-128 | Customer shell shows a notification bell that opens a local notification list. |
| BR-129 | Customer notification entries navigate to customer history when selected. |
| BR-130 | A floating support chat button is shown in the shell for all roles. |
| BR-131 | Opening customer support chat ensures a thread exists for the current customer. |
| BR-132 | The first customer support thread is seeded with a system greeting message. |
| BR-133 | Staff and admin share one support inbox listing all customer support threads. |
| BR-134 | Any staff or admin user can reply to any customer support thread in the prototype inbox. |
| BR-135 | Sending a customer support message increments unread count for staff; staff/admin replies increment unread count for the customer. |
| BR-136 | Support threads are normalized on load and persisted in shared localStorage state. |
| BR-137 | Customer home renders a live wash progress tracker only when there is an active tracked booking or wash session. |
| BR-138 | The live wash progress tracker recalculates every second from session start time plus package/service durations. |
| BR-139 | The live wash progress tracker derives its stage presentation from shared wash session status and elapsed ratio, not from a fixed hardcoded value. |
| BR-140 | Audit-like records such as vehicle ownership transfers, tier changes, ledger entries, and adjustments are stored as local records rather than immutable backend audit logs. |
| Function / Area | Related BRs |
|---|---|
| Public homepage and guest routing | BR-01 to BR-05 |
| Demo login and role routing | BR-06 to BR-10 |
| Registration, OTP, and profile | BR-11 to BR-25 |
| Vehicle management | BR-26 to BR-39 |
| Customer booking checkout flow | BR-40 to BR-56 |
| Shared booking rules and operational lifecycle | BR-57 to BR-77 |
| Staff queue and check-in workflow | BR-78 to BR-86 |
| Loyalty, rewards, and tier handling | BR-87 to BR-98 |
| Promotions, vouchers, combos, and package governance | BR-99 to BR-109 |
| Admin dashboards, accounts, and management pages | BR-110 to BR-124 |
| Notifications, support chat, and live tracking | BR-125 to BR-140 |
The baseline README described a more unified business specification than the current prototype actually implements. The current repository diverges in the following observable ways:
| Baseline Expectation | Actual Prototype Behavior |
|---|---|
| Registration supports full name, email or phone, and password. | Current registration UI collects full name, phone, password, and OTP only. |
| Customer, staff, and admin share one booking domain model. | The repository still splits customer booking logic and admin/staff portal logic across different stores. |
| Booking lifecycle is one consistent path from customer booking to staff completion. | Customer booking pages simulate upfront payment and create module-local bookings, while staff/admin lifecycle runs on shared-store bookings. |
| Customer directory is customer-only. | Admin sidebar now labels this module Accounts, and the page merges customers, staff, and admin accounts. |
| Customer support is only hotline/static help content. | The shell now includes a shared support chat widget with per-customer threads and unread counts. |
| Customer home wash tracker is a static presentation card. | The live wash progress tracker now updates in real time from session timing and package/service durations. |
| Reports focus only on bookings and promotions. | Reports now also include daily staff wash count reporting with date filtering and pagination. |
| Promotion targeting semantics are fully aligned with the UI label. | The admin UI offers new customers only, but shared-store enforcement currently translates that choice into Member tier targeting rather than a true completed-booking history check. |
| Admin role/permission changes are system-wide. | Admin customer status updates persist, but role changes in customer detail remain presentation-only in the current UI. |
Because of these differences, this README should be treated as the specification of actual prototype behavior, not as a production-ready normalized system design.
-
The repository still has a hybrid architecture. Customer booking pages and admin/staff pages do not yet share a fully unified booking, loyalty, package, promotion, and history state model.
-
Upfront payment simulation exists in the customer booking module, while operational checkout and loyalty posting also exist in the shared portal store. These are parallel prototype tracks rather than one integrated payment lifecycle.
-
Shared-store booking rules are stricter than what the current customer booking UI exposes. Examples include tier booking windows, max 3 active bookings, slot capacity, Platinum priority, cancellation auto-ban, and ownership transfer handling.
-
Admin package and promotion edits are live inside the shared portal store, but they do not fully drive the customer booking module's own package/combo/voucher mocks yet.
-
The admin promotion form is still slightly ahead of the enforcement logic:
- the UI offers
new customers only - shared-store enforcement currently maps that choice to
Membertier targeting only
- the UI offers
-
The customer area mixes module-local history and shared-store history:
/customer/bookingsand/customer/historyrely mainly on customer-booking mock state/customer/transactionsreads shared operational transactions
-
OTP, forgot password, payment success, browser notifications, support chat, and audit-like records are all local simulations only.
-
The support chat is intentionally broad in this prototype:
- customer opens a single personal thread
- all staff and admin users share the same inbox
- there is no routing, assignment, SLA, or backend message delivery
-
If the team wants a single production-ready specification later, the first cleanup step should be consolidating customer booking, staff operations, admin governance, support chat, and reporting onto one shared business state model.