Module: RideMate / Cab & Bike (cab_bike / rides)
Status: 🟡 Partially implemented (rides work; commission not recorded to the ledger) · Last validated: 2026-09-06 · Priority: P0
On-demand cab/bike rides: partner/driver onboarding, fare estimation, booking, driver dispatch, live location, cancellation. Validated against classs/VehicleModule.php (~6,200 lines) + schema.
A. Purpose
Customers book rides; vehicle owners onboard vehicles + drivers; drivers accept and fulfil. Revenue = 5% (rule active) but not wired into the commission ledger (see gap).
B. Actors
Customer/rider; vehicle owner (company); driver (assigned to vehicle); admin. Enrollment type rides.
C. Entry points
Consumer: /ride.php, /rideriquestnow.php. Partner: management/partner onboarding (vehicle_partner_signup.php, hopin_vehicle_signup.php). Driver: driver app surfaces.
D. Onboarding
registerPartner(userId, data) (:565) → ensureOwnerCompany (:831) → addOrUpdateVehicle (:1054) → addOrUpdateDriver (:1382) → assignDriverToVehicle (:1485). Module cab_bike on; owner enrolled.
E. Feature registry (prefix RIDE-)
| ID | Feature | Actor | Method | Tables | Status |
|---|---|---|---|---|---|
| RIDE-001 | Onboard partner/company | owner | registerPartner :565 | company + owner profile | 🟢 |
| RIDE-002 | Add/edit vehicle | owner | addOrUpdateVehicle :1054 | vehicles_master | 🟢 |
| RIDE-003 | Add/assign driver | owner | addOrUpdateDriver :1382, assignDriverToVehicle :1485 | driver + assignment | 🟢 |
| RIDE-004 | Toggle availability | owner/driver | toggleVehicleAvailability :1353, setDriverAvailability :4481 | vehicle/driver flags | 🟢 |
| RIDE-005 | Estimate fare | customer | estimateFare :3086 | — | 🟢 |
| RIDE-006 | Create booking | customer | createBooking :3301 | vehicle_bookings | 🟢 (money) |
| RIDE-007 | Driver: list open, arrive | driver | listOpenBookingsForDriver :4509, driverMarkArrived :4582 | vehicle_bookings | 🟢 |
| RIDE-008 | Live driver location | driver | updateDriverLocation :4433 | location store | 🟢 |
| RIDE-009 | Booking status (rider) | customer | getBookingStatusForUser :4618 | vehicle_bookings | 🟢 |
| RIDE-010 | Cancel (rider/driver) | both | userCancelBooking :4726, driverCancelBooking :4791 | vehicle_bookings | 🟢 |
F. Booking flow (RIDE-006)
ride.php → estimateFare(userId, data) :3086 (distance × rate)
→ createBooking(userId, data) :3301 → INSERT vehicle_bookings
→ dispatch: listOpenBookingsForDriver (radius) → driver accepts → driverMarkArrived
→ ride → completion → fare settled via wallet_ledger (see gap)G. Data model (2026-09-06)
| Table | Rows | Role |
|---|---|---|
vehicles_master | 9 | onboarded vehicles |
vehicle_bookings | 9 | ride bookings |
Driver/status-history/ride-request tables exist under different names than guessed (vehicle_booking_status_history,ride_requests,driver_masterare not the live names) — re-derive with_tools/before documenting those; drivers are stored via the owner/driver methods above, not adriver_mastertable.
H. Financial impact — the gap (validated)
5% commission rule is active and VehicleModule computes it, but no ride file calls CommissionEngineModule — settlement goes to wallet_ledger instead, so 0 commission rows are recorded for rides. Platform take on rides is invisible to finance. To fix: call computeAndRecord('cab_bike', …, 'vehicle_bookings', bookingId, …) in the completion path. See ../../40-financial/commission.md.
K. State machine (vehicle_bookings)
Correction (2026-09-06): the previous transition list used names that don't exist in the live code — code wins. vehicle_bookings actually carries two parallel status columns:
booking_status:requested → broadcasted → accepted (VehicleModule.php:5313`) → arrived
(:4594) → started (:5461) → completed (:6097), or terminal no_driver (unmatched — set at :113, reachable via archiveUnmatchedBooking :77) / cancelled`.
status: set tocancelled_by_user(not "cancelled_by_rider" —userCancelBooking:4756) or
cancelled_by_driver (driverCancelBooking :4821) on cancellation; also carries cancelled_by_owner, no_show, pending, offered_to_driver, completed elsewhere in the class. There is no expired value on the live path — an unmatched booking becomes no_driver, not expired. A code comment at VehicleModule.php:5167-5174 itself flags this two-column status/booking_status vocabulary as a known source of confusion.
L. Errors (prefix RIDE-E)
RIDE-E001no driver found — no open driver in radius (listOpenBookingsForDriver); booking may
be archived unmatched.
RIDE-E002ride commission not in ledger — see the financial gap.
M / N. Dependencies & change-impact
Wallet, wallet_ledger (settlement), location/geo, notifications. Wiring commission changes the finance ledger — re-test the completion → settlement path and add exactly one commission row.