DryCleanPlus

Changelog — DryCleanPlus

All notable changes to this app are recorded here. Newest entries on top.

[2026-05-13 — Settings expanded]

• "Share these links" panel. Settings now surfaces the canonical sign-in URL, public order-tracking URL, and Paystack webhook URL — each with a one-tap copy button. All three honour custom domains automatically (verified track.mybiz.com swaps in for the platform fallback). A helper line tells the admin every role uses the same sign-in URL; phone+PIN routes them to the right home.
• Labels editor. A new Settings section lets the platform owner rename every customer-facing status (Awaiting payment / Paid / Picked up / Washing / Ready / Delivered / Cancelled), the five role names, the order-code prefix, and the four login-screen strings (phone prompt, PIN prompt, sign-in button, forgot-PIN help). Defaults show as grey placeholders; leaving a field blank uses the default.
• Business contact pair. Business name + support phone now editable; support phone appears wherever views surface a "call us" link.

Internal

• POST /api/admin/update-settings now accepts any label_* key (with a 96-char cap) on top of the existing allowlist.
• New dcp_status_label($status) helper in [helpers.php](helpers.php) wraps the platform's get_label() with sensible English defaults. Wired into [login.php](views/public/login.php), [track.php](views/public/track.php), [customer-home.php](views/public/customer-home.php), and [agent-home.php](views/public/agent-home.php) — overrides flow through immediately.
• Verified end-to-end: setting label_status_washing = "Cleaning in progress" instantly changes the wording on the public /track progress ladder.

[2026-05-13 — Bag CRUD]

• Per-vendor branded-bag inventory. Vendors and managers can add, mark-lost, retire, and restore bags via [/p/{uid}/drycleanplus/vendor-bags](apps/drycleanplus/views/public/vendor-bags.php) and [/p/{uid}/drycleanplus/manager-bags](apps/drycleanplus/views/public/manager-bags.php). Each bag belongs to one vendor; the manager only sees bags from their own downline; vendors only edit their own.
• Bag picker in the agent flow. Step 1 of the new-order screen now lists every available bag across the agent's manager's downline. The agent must pick one, and the bag's vendor becomes the order's vendor (overriding round-robin). The bag tag in the step header swaps to the picked bag number.
• Automatic state transitions. Bag flips available → in_use when payment confirms; flips back to available when the vendor marks the order delivered. Status lost / retired are manual.

Internal

• New [api/bags.php](api/bags.php) with role-scoped list (vendor: own; manager: downline; agent: available across downline; admin: all), add, mark-lost, retire, restore. UNIQUE(vendor_user_id, bag_number) returns 409 on duplicates.
• Webhook handler now reads the order's preset vendor_user_id (from the agent's bag pick) and only round-robins when null. Bag is set in_use in the same transaction that flips the order to paid.
• transition-status to delivered flips the order's bag back to available (only if it was in_use — defensive against manual fiddling).
• Manager home links to /manager-bags; vendor home's bottom-nav "Bags" tab now routes to /vendor-bags.

[2026-05-13 — Milestone B + C]

• Five-way Paystack transfer splits. When an order is paid, the system enqueues 4 outbound transfers (vendor 60 / agent 15 / manager 10 / director 3 percent) and keeps the platform owner's 12% in the Paystack balance. Stamp duty (₦50) is added on transfers ≥ ₦10,000. The brand-new /app/drycleanplus/transfers view shows the full log, retry queue, and a "Run cron now" button.
• Dry-run mode by default. The app ships with paystack_dry_run = 1 so demos work without real Paystack keys — every transfer / refund is recorded with a synthetic DRYRUN_* reference. Flip it off in /app/drycleanplus/settings once you've pasted in your sk_live keys.
• Retry queue with backoff. Failed transfers retry on a 1m → 5m → 30m → 2h → 12h schedule. After 5 attempts they're held permanent-fail and an admin "↻ Retry" button on /transfers resets the counter.
• Auto-suspend health check. If 3+ transfers permanently fail in 24h the app sets intake_suspended — new order drafts return HTTP 503 with a friendly message and the admin sees a rose banner on /settings with a "Resume intake" button.
• Refunds + wallet-offset. Customers submit at /customer-refund-new, vendor + agent get 48h to respond, manager (or platform owner) approves/denies at /manager-refunds (or admin /refunds). On approval the refund amount is debited proportionally from every party's wallet, the customer is paid out via Paystack Refund API (or a DRYRUN_REF_* reference in test mode), and the wallet-offset engine withholds debt-recovery from each party's share on future orders. Held money stays in the platform owner's Paystack balance.
• Onboarding now creates Paystack recipients. When you onboard a Director / Manager / Vendor / Agent with bank account fields, the platform calls /transferrecipient and stores the paystack_recipient_code against their profile. In dry-run mode a deterministic DRYRUN_RCP_* code is stored instead.
• Admin dashboard surfaces: /app/drycleanplus/orders (every order across the network, filterable by status), /app/drycleanplus/order?id=… (full detail + items + splits + event log), /app/drycleanplus/transfers (cron + retry queue), /app/drycleanplus/refunds (queue with override), /app/drycleanplus/settings (Paystack keys, splits %, markup %, NTFY).
• Manager dashboard touch-ups. Manager home now surfaces the "X refunds awaiting your decision" rose banner above the recruit CTAs.
• Customer touch-ups. Customer home now shows an inline "Something off? Ask for a refund →" link when they have any past orders.
• Cron wired into platform scheduler. cron_drycleanplus_tick registered in [core/cron.php](../../core/cron.php) and [core/cron/tasks.php](../../core/cron/tasks.php) — runs the transfer queue + health check across every install. Admins can also fire it on demand via POST /app/drycleanplus/api/cron/run.

Internal

• Added dcp_paystack_request, dcp_paystack_create_recipient, dcp_paystack_initiate_transfer to [helpers.php](helpers.php). All three honour paystack_dry_run and return synthetic IDs when set.
• Added dcp_enqueue_splits which checks each recipient's wallet at queue time — if negative, holds up to that debt amount from the transfer and emits a recovery_credit ledger row. Platform owner's share also runs through the same offset logic without a transfer row (their money stays in Paystack balance).
• Added dcp_run_transfer_queue (called by both the platform cron tick and the admin "Run cron now" button) with the 5-step backoff schedule and auto-suspend check.
• Added dcp_wallet_post (atomic balance update + ledger entry) and dcp_refund_debit_split (proportional debits matching the original split percentages).
• New tables / columns picked up via guarded dcp_safe_alter(): transfers.last_attempt_at, transfers.next_attempt_at. The lazy migrator's static-flag pattern means each ALTER fires at most once per process.
• dcp_process_transfer synthesises a DRYRUN_RCP_USER{id} recipient when none is on file in dry-run mode, so seeded demo data works out of the box.
• api/orders.php create-draft now refuses with HTTP 503 when intake_suspended = '1'.
• api/admin.php exposes: update-settings, resume-intake, retry-transfer, reassign-vendor.

Audit pass

End-to-end smoke test ran clean: 5 role logins all 200, agent draft → Paystack webhook → 4 transfers success in dry-run, customer refund → manager approval → 5 wallets debited proportionally (-₦720/-₦180/-₦120/-₦36/-₦144 on a ₦1200 refund of a ₦2400 subtotal), follow-up order → wallet holds recover all but vendor's debt (because round-robin picked the other vendor). Admin views all 200 with a real Pancho session. Role-mismatch checks return 403.

[2026-05-13]

• Pixel-faithful design pass. Every screen now matches the JSX mockups in [sources/designs/](sources/designs/) — login (Pancho. wordmark + 84×84 terra mark + blinking cursor + 4 PIN tiles), agent home (greeting + hero terra "Start a new order" card with decorative bag silhouette + KPI tiles + recent orders strip + bottom nav), agent new-order (3-step flow with pictogram tiles + qty steppers + "in the bag" peek strip + dark dock + day cards with Express/Priority/Standard tones + Paystack inline), vendor queue (tabbed counters + sun bag tags + NEW ribbon + green "Mark as picked up" button), customer track (dark hero, cream bag card with bag illustration, ETA strip, terra/sun progress ladder, terra agent-call CTA), director (dark money headline with tilted ₦ watermark, 3 KPIs, flag bar, vendor health list with util bars), manager (money tile + onboarding CTAs + vendor list), onboarding screens (uniform card layout with dark dock + terra/green submit + dark PIN reveal panel).
• Vendor status workflow. Vendor can tap "Mark as picked up / washing / ready / delivered" on each order; transitions are role-gated, append to order_events, fire NTFY to the customer and agent, and log to audit_log.
• End-to-end agent flow works. Agent creates an order draft → Paystack inline checkout → webhook signature-verified (HMAC-SHA512) → order persisted as paid with round-robin vendor assignment → public /track?code=… shows the progress ladder.

Internal

• Fixed platform_owner identity bridge to resolve from $_PS_CURRENT_USER_ID (set by both /app/{appId} and /p/{uuid}/{appId} dispatchers) instead of $_SESSION['user_id'] — in-app users on /p routes have no Pancho session, so the old check broke the recruitment-chain attribution. New helper dcp_owner_uuid() centralises the lookup.
• Fixed ambiguous status column in vendor-home's JOIN (orders.status vs users.status) — qualified the WHERE-clause status references with the o. prefix.
• Added transition-status action to [api/orders.php](api/orders.php) for vendor + manager + platform_owner workflows. Forward-only chain paid → picked_up → washing → ready → delivered with corresponding *_at column writes.
• Added sources/_install.php throwaway tool — re-runnable installer that wires drycleanplus onto the owner UUID and seeds the demo chain (call php apps/drycleanplus/sources/_install.php or pass a UUID as the first arg).

[2026-05-13 — earlier]

• Initial scaffold. Set up DryCleanPlus marketplace app with the recruitment chain (Platform Owner → Director → Manager → Vendor + Agent → Customer), phone+PIN login for every in-app role, and the agent order-draft flow with Paystack webhook persistence.
• Onboarding flows. Platform Owner can onboard their first Director from the admin dashboard; Directors recruit Managers, Managers recruit Vendors and Agents. Each onboarding shows the new user's PIN on-screen so the recruiter can pass it on in person — no SMS sending in v1.
• Order draft + Paystack inline. Agents pick items via a pictogram grid, select delivery/schedule, and the customer pays via Paystack inline checkout. On charge.success, the webhook verifies the HMAC-SHA512 signature and persists the order as paid. Five-way Transfer API splits land in Milestone B.
• Public order tracking. /p/{owner_uuid}/drycleanplus/track?code=DP-7K2X resolves an order without login and shows its current status.

Internal

• Schema covers all tables needed for Milestones B + C (transfers, wallets, wallet_ledger, refund_requests) so future phases ship as code-only deltas.
• Platform Owner identity bridge: dcp_resolve_platform_owner() in [helpers.php](helpers.php) INSERT OR IGNOREs a users row with role='platform_owner' keyed off the Pancho install owner's UUID. Cached in $GLOBALS['_DCP_PLATFORM_OWNER_ID'] for the request.
• Order code format: DP-{4-char base32}, generated by dcp_generate_order_code() with retry on collision.
• NTFY notifications via dcp_notify() POST to settings.ntfy_server (default https://ntfy.sh). Topic = pancho-drycleanplus-{sha256(phone)[:12]}. Best-effort; failures swallowed.
• All money in kobo (integer). Split percentages, markup percentage, draft timeout configurable in settings table. Default split: vendor 60 / agent 15 / manager 10 / director 3 / platform_owner 12.
• Direct Paystack integration is allowed for this app (same exception as Donately) because it's end-customer payment to the install owner's own Paystack account, not Pancho subscription billing.