WFDASH-WEBAPP/docs/sops/collection-driver.md

Collection Driver — SOP

Owns: picking up goods from suppliers, delivering to customers, capturing proof of collection and delivery. Runs on the WFDASHDRIVER-APP (mobile) and /collection-confirm (browser fallback).

Tools (mobile): WFDASHDRIVER-APP, /collection-confirm. Tools (office view): /collection-pool, /collection-map.

Handoffs:

• From Order Operator → PO is po_generated, item is in collection_pool or assigned to you.
• To Order Operator → you mark collected on the way back to the office, or on delivery.
• To Stock Controller → surplus or damaged goods need to be booked.

Note: drv_status and drv_id are the driver-side fields on order_items. The status used here is the item-level item_status (see Decision Tree for the exact mapping).

---

1. Daily / Weekly Checklist

Every working day (start of shift, 07:00 SAST)

• Open WFDASHDRIVER-APP — Today's Run. Review the supplier list, the order of pickups, and any urgent adds from the Order Operator.
• Check the truck: fuel, waybills, blank GRN books, packing tape, camera (phone), and a power bank.
• Confirm any special instructions on items (oversize, fragile, supplier with restricted hours).
• Phone the first supplier if you haven't worked with them in a while. Confirm they're open and the order is ready.

Every working day (mid-day, 12:00 SAST — or at lunch)

• Triage anything blocking you. Phone the Order Operator if a supplier can't fulfil today, if a customer can't receive, or if you have a route problem.
• Update the app with any deviations (supplier short, customer closed, etc).

Every working day (end of shift, 17:00 SAST)

• Mark all today's items with their final status. No item should be left "in flight" overnight. If a customer can't receive, mark assigned (not delivered) and add a note.
• Park any surplus / damage with the Stock Controller. Don't leave it on the truck.
• Sync the app — verify all photos uploaded, all confirmations saved. Mobile data can be patchy; the sync indicator in the top-right is the truth.

Every Monday morning

• Review your KPIs (see §4). Look at last week's collection rate, on-time rate, and error rate.
• Walk the truck. Inventory the packing materials, reusable crates, etc. Report any missing.

Every Friday afternoon

• Triage any open collections — items still collection_pool over the weekend are at risk of supplier closure or customer cancellation. Flag to the Order Operator.

---

2. Step-by-Step Procedures

2.1 View your assigned run

When: you arrive for your shift.

1. Open WFDASHDRIVER-APP.
2. Tap Today's Run. You see a list grouped by supplier, in the order the Order Operator suggested (usually optimised by proximity — see /collection-map).
3. For each supplier, you see:
   • Supplier name, address, contact.
   • Items to collect, with qty + description.
   • The PO number (so the supplier can match).
   • Any special instructions.

If you need to re-order the run: tap the supplier row, Re-order. The Order Operator gets a notification.

2.2 Navigate to a supplier

When: you're at the first pickup.

1. Tap the supplier row in the app.
2. Tap Navigate. The app opens your default maps app with the supplier's address.
3. If the address is wrong: tap Report Wrong Address on the supplier row. Don't try to find the supplier yourself — the Order Operator needs to fix the master data.

2.3 Confirm collection (the happy path)

When: you arrive at the supplier and the order is ready.

1. Tap Confirm Collection on the supplier row.
2. The app shows each line item. For each:
   • Scan the barcode if the supplier labels have them (faster, more accurate). The app matches against the expected SKU.
   • Or tap to mark received if no barcode.
3. If the supplier gave you a delivery note / invoice (paper or PDF), tap Attach. Photograph it. The app stores it with the standard supplier_invoice_ filename prefix.
4. Review the totals at the bottom. The qty received should match the qty ordered.
5. Tap Submit. The order items flip to collected and the supplier invoice is attached to the PO.

Don't:

• Don't submit without attaching the supplier's invoice. The Order Operator needs it to do the diff/receive.
• Don't submit with the wrong qty. If the supplier shorted you, see §3.1.

2.4 Confirm a partial collection

When: the supplier delivered less than ordered.

1. Follow §2.3 up to step 3.
2. For each line, enter the actual qty received (not the full qty). The app shows the difference.
3. In the Note field, write the reason ("supplier short by 2, ETA TBD" or "supplier out of stock on this SKU").
4. Continue. Tap Submit.
5. The items flip to collected with qty_collected set to the partial amount. The Order Operator creates a continuation order for the missing qty (see Order Operator §2.6).

2.5 Report a wrong / damaged item

When: the supplier gave you the wrong item, or it's damaged.

1. Don't accept the goods (refuse at the supplier).
2. In the app, on the line, tap Report Problem.
3. Choose: wrong_item, damaged, expired, or other.
4. Take photos — at least 2 (whole item + close-up of the problem). The app attaches them with a damage_ or wrong_item_ filename prefix.
5. Add a note explaining the situation.
6. Get the supplier's rep to sign the delivery note with the discrepancy. Photograph the signed note.
7. Tap Submit. The item stays in collection_pool (not flipped to collected). The Order Operator handles the dispute.

2.6 Deliver to a customer

When: you're at the customer's site with their order.

1. Tap the order row in the app.
2. Tap Confirm Delivery.
3. For each line:
   • Mark delivered (qty matches).
   • Or partial delivery (customer accepts less — see §3.4).
   • Or refused (customer won't accept — see §3.5).
4. Take a photo of the delivered goods at the customer's site (best practice for disputes).
5. Get the customer's signature. The app captures the signature on screen. Alternatively, photograph the signed waybill.
6. Tap Submit. Items flip to delivered.

Don't:

• Don't deliver without a signature / photo. A "delivered" item without proof is a dispute magnet.

2.7 Report a surplus

When: the supplier gave you MORE than ordered (e.g. 12 instead of 10).

1. Follow §2.3, but for the over-delivered qty, tap Surplus.
2. Enter the surplus qty (e.g. 2).
3. The system splits the line: customer qty (10) stays on the order, surplus qty (2) is booked to stock. A stock_ledger entry is written with reason: "purchase_surplus".
4. Continue with §2.3 for the rest.

2.8 Hand off a damaged delivery to stock

When: a customer refuses damaged goods on arrival.

1. Take photos at the customer's site (see §2.5).
2. Get the customer's signature on the refusal note.
3. Bring the goods back to the office. Don't book them to stock yourself — hand to the Stock Controller. They'll inspect, decide return-to-vendor vs write-off, and book the ledger entry.

---

3. Decision Tree

3.1 Supplier short / partial

Did the supplier know they were short (pre-called you)?
├── Yes → log partial qty, attach their note, submit. Order
│         Operator creates the continuation.
└── No
    ├── Did they offer a back-order ETA?
    │   ├── Yes (within 1 week) → take the partial, log the
    │   │   ETA, Order Operator schedules the back-order.
    │   └── No / vague → take what they have. Order Operator
    │                    phones the supplier for an ETA, may
    │                    source from a backup.
    └── Is the partial critical (customer waiting, no
        substitute)?
        ├── Yes → phone the Order Operator NOW. They may
        │         source from a backup supplier while you're
        │         still at the supplier.
        └── No → take the partial, log it, continue the run.

3.2 Supplier closed / not ready

Can you reach the supplier by phone?
├── Yes
    ├── "Order not ready, will be in 2 hours" → wait if your
    │   schedule allows. If not, re-order your run.
    ├── "Order not ready, will be tomorrow" → re-order your
    │   run, do the other suppliers first. Phone the Order
    │   Operator if it means the customer won't get it today.
    └── "Closed for the day" → re-order, mark `assigned` not
                                 `collected`, phone the Order
                                 Operator.
└── No → re-order your run. Phone the Order Operator. Don't
         wait — every minute parked is a minute not delivering.

3.3 Wrong address (supplier or customer)

Is the address in the app matching what you see?
├── No (typo in the app, building really exists)
│   └── Tap **Report Wrong Address**. Don't try to find it
│       yourself — the master data needs fixing. Wait for
│       the Order Operator.
└── The address is right but you can't find the place
    ├── Phone the contact on the row.
    ├── If no answer, ask locals / security.
    └── If still can't find → mark `assigned`, note "couldn't
        locate", return to the office. Order Operator
        resolves.

3.4 Customer wants partial delivery (not what we brought)

Is the customer a strategic account?
├── Yes → call the Order Operator before doing anything. Don't
│         make a delivery decision on the customer's porch.
└── No
    ├── Will they accept what they need and leave the rest?
    │   ├── Yes → deliver the partial, note the refused qty
    │   │         and reason, return the rest to the office.
    │   └── No (must be all or nothing) → mark `assigned`,
    │                                      return the whole
    │                                      delivery to the
    │                                      office. Phone the
    │                                      Order Operator.
    └── Is the partial a "while you're here" ask (can they
        take an extra qty)?
        └── Phone the Order Operator. Don't unilaterally
            add to the delivery.

3.5 Customer refuses (damaged, wrong, "changed my mind")

Why are they refusing?
├── Damaged → §2.5 / §2.8. Take photos, get signature, return
│              to office.
├── Wrong item → §2.5. Same process.
├── Customer changed mind (no defect)
│   ├── Customer pays restocking fee per policy?
│   │   ├── Yes → take the refusal, return to office, note
│   │   │         the fee on the order.
│   │   └── No / unclear → phone the Order Operator. Don't
│   │                       bring the goods back without
│   │                       confirming the restocking fee.
│   └── Customer wants to keep it but at a discount?
│       └── Phone the Order Operator. Don't unilaterally
            discount.
└── Other
    └── Phone the Order Operator. Get instruction.

3.6 Customer not on site when you arrive

Have you called ahead?
├── Yes (no answer) → wait 15 min. Try again. If still
│                      nothing, leave a card / note, mark
│                      `assigned` with "not on site", return
│                      to office. Order Operator reschedules.
└── No → call now. If no answer, same as above.

3.7 Truck breakdown / accident

Is anyone hurt?
├── Yes → emergency services first. Then phone the Order
│         Operator. The goods are secondary.
└── No
    ├── Is the truck driveable?
    │   ├── Yes → drive to a safe spot. Phone the Order
    │   │         Operator. They'll re-assign the rest of
    │   │         your run to another driver.
    │   └── No → road service. Phone the Order Operator.
    │            They'll re-assign.
    └── Can the goods be salvaged? → assess, take photos,
        continue if possible.

3.8 Bad weather

Is the road to the customer / supplier safe?
├── No → don't go. Phone the Order Operator. They'll
│        re-schedule. Customer/supplier gets a weather
│        delay note on the order.
└── Yes → continue. Take extra care.

---

4. KPIs

All KPIs measured per working day unless noted.

KPI	Target	How it's measured
On-time collection rate	> 90% of assigned items collected same day	count(items where item_status=collected AND collected_at date = assigned_at date) / count(assigned items)
On-time delivery rate	> 95% of ready_delivery items delivered within the customer-promised window	per-order delivery_date vs delivered_at
Error rate (wrong item / damaged)	< 2% of line items	count(items with damage/wrong_item photo attached) / total items handled
Photo proof rate	100% of collections + deliveries have at least one photo	count(photos) / count(items handled) — should be 1:1 minimum
Signature capture rate	100% of deliveries have a signature	same as above, for the signature field
Surplus booking rate	100% of surpluses booked same day	stock_ledger entries with reason="purchase_surplus" per day vs supplier delivery notes flagged with surplus
Refusal rate	< 3% of attempted deliveries	count(customer refusals) / count(delivery attempts)
Re-run rate	< 5% of items needing a second visit	count(items with 2+ collection attempts)
App sync success	100% (all confirmations uploaded by EOD)	count(items confirmed offline more than 4h) / total items confirmed — should be zero
Cost per collection	tracked, target stable	total driver cost (incl truck, fuel) / number of collections per month

How KPIs feed into your review

• Daily (end of shift): the app's home screen shows your day's KPI snapshot. If any are red, the supervisor gets an alert.
• Weekly (Monday standup): one-pager with the week's KPIs. On-time rate and error rate are the headline numbers.
• Monthly (1st of month): 1-page review with the supervisor. Photo proof rate and signature capture rate must be 100% — these are the dispute-defence evidence. Anything below is a process failure.
• Quarterly: top performers on on-time + zero-error are eligible for the senior-driver tier (they can take the high-value / strategic-account runs).

What the system does NOT measure (yet)

• Customer satisfaction (no NPS yet)
• Fuel efficiency per route
• Truck wear-and-tear

If a KPI is unfair, raise it. The supervisor can adjust targets, but the metric stays.