feat(api,rider): COD debt cap — pause dispatch when a rider owes too much

Prevents a rider accumulating unbounded platform cash (COD they collected but
haven't deposited) and absconding. New platform-config field riderCodCapPhp
(default ₱1,500, env RIDER_COD_CAP_PHP): once a rider's outstanding COD
(collected − deposited) reaches the cap, they stop receiving new jobs until
they deposit.

- platform-config: riderCodCapPhp added to CONFIG_FIELDS, defaults, and the
  grouped values; migration adds the column (default 1500).
- orders.repository: riderOutstandingCod(rider) for the manual gate;
  pickAutoDispatchRider now filters over-cap riders (batched two-groupBy, no
  per-rider round-trip) so auto-dispatch skips them too.
- orders.service.assignRider: rejects an over-cap rider (parity with the
  auto-dispatch filter) — BadRequest naming the limit.
- rider-cash: /me/cash now returns capPhp; the Cash tab shows "new jobs pause
  once you owe ₱X" and flips to "over the limit — deposit to resume" when hit.

Note: ₱100 (as floated) would block a rider after one order — a single wash's
COD exceeds it. ₱1,500 (~4-7 orders) bounds abscond loss while allowing a normal
batch. The ~₱100 "carry allowance" (auto-net small debt vs weekly earnings) is a
separate remittance-netting feature, deferred.

New tests: over-cap assign rejected, just-under-cap allowed, balance carries the
cap, config default. 136 api unit tests green.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: Banyel3

apps/api/prisma/migrations/20260806000000_rider_cod_cap/migration.sql

@@ -0,0 +1,2 @@
+-- Rider COD debt cap: max outstanding cash a rider may carry before dispatch pauses.
+ALTER TABLE "PlatformConfig" ADD COLUMN "riderCodCapPhp" DECIMAL(12,2) NOT NULL DEFAULT 1500;

apps/api/prisma/schema.prisma

@@ -368,6 +368,9 @@ model PlatformConfig {
   // P4a dispatch toggle: 1 = auto-assign a rider on Express booking, 0 = manual
   // dispatch only. Flag (0/1) to fit the numeric config pipeline.
   autoDispatchEnabled      Int      @default(0)
+  // Max outstanding COD (collected − deposited) a rider may carry before new
+  // jobs pause. Bounds the platform's exposure if a rider absconds with cash.
+  riderCodCapPhp           Decimal  @default(1500) @db.Decimal(12, 2)
   updatedAt                DateTime @updatedAt
 }
 

apps/api/src/orders/orders.repository.ts

@@ -98,14 +98,22 @@ export class OrdersRepository {
   // or null if none. Runs inside the create tx so the load count is consistent.
   async pickAutoDispatchRider(
     tx: Prisma.TransactionClient,
+    codCapPhp: number,
   ): Promise<string | null> {
     const riders = await tx.user.findMany({
       // VERIFIED riders only — auto-dispatch never assigns an unverified rider.
       where: { roles: { has: 'RIDER' }, disabledAt: null, riderProfile: { status: 'VERIFIED' } },
       select: { id: true },
     });
     if (riders.length === 0) return null;
-    const ids = riders.map((r) => r.id);
+    // Drop riders over the COD debt cap — same gate as manual assign, so a
+    // rider holding too much platform cash stops receiving new jobs.
+    const ids = await this.filterUnderCodCap(
+      tx,
+      riders.map((r) => r.id),
+      codCapPhp,
+    );
+    if (ids.length === 0) return null;
     const grouped = await tx.order.groupBy({
       by: ['assignedRiderId'],
       where: {
@@ -121,6 +129,51 @@ export class OrdersRepository {
     return selectLeastLoadedRider(ids, load);
   }
 
+  // Outstanding COD a rider still owes = cash they collected (paid COD on their
+  // orders) minus what they've deposited back. Used by the debt-cap gate.
+  async riderOutstandingCod(riderId: string): Promise<Prisma.Decimal> {
+    const [collected, deposited] = await Promise.all([
+      this.prisma.order.aggregate({
+        _sum: { customerTotalPhp: true },
+        where: { assignedRiderId: riderId, paidCashAt: { not: null } },
+      }),
+      this.prisma.riderCashDeposit.aggregate({
+        _sum: { amountPhp: true },
+        where: { riderId },
+      }),
+    ]);
+    const c = collected._sum.customerTotalPhp ?? new Prisma.Decimal(0);
+    const d = deposited._sum.amountPhp ?? new Prisma.Decimal(0);
+    return c.minus(d);
+  }
+
+  // Keep only rider ids whose outstanding COD is strictly under the cap. Batched
+  // (two groupBys) so auto-dispatch stays one round-trip per table, not per rider.
+  private async filterUnderCodCap(
+    tx: Prisma.TransactionClient,
+    ids: string[],
+    codCapPhp: number,
+  ): Promise<string[]> {
+    const [collected, deposited] = await Promise.all([
+      tx.order.groupBy({
+        by: ['assignedRiderId'],
+        where: { assignedRiderId: { in: ids }, paidCashAt: { not: null } },
+        _sum: { customerTotalPhp: true },
+      }),
+      tx.riderCashDeposit.groupBy({
+        by: ['riderId'],
+        where: { riderId: { in: ids } },
+        _sum: { amountPhp: true },
+      }),
+    ]);
+    const dep = new Map(deposited.map((d) => [d.riderId, Number(d._sum.amountPhp ?? 0)]));
+    const col = new Map<string, number>();
+    for (const c of collected) {
+      if (c.assignedRiderId) col.set(c.assignedRiderId, Number(c._sum.customerTotalPhp ?? 0));
+    }
+    return ids.filter((id) => (col.get(id) ?? 0) - (dep.get(id) ?? 0) < codCapPhp);
+  }
+
   async isShopMember(userId: string, shopId: string): Promise<boolean> {
     const m = await this.prisma.shopMember.findUnique({
       where: { shopId_userId: { shopId, userId } },

apps/api/src/orders/orders.service.spec.ts

@@ -136,6 +136,7 @@ describe('OrdersService', () => {
       isShopMember: jest.fn(),
       userHasRole: jest.fn(),
       isRiderVerified: jest.fn().mockResolvedValue(true),
+      riderOutstandingCod: jest.fn().mockResolvedValue(D('0')),
       lockShopDay: jest.fn().mockResolvedValue(undefined),
       countExpressOrdersForShopDay: jest.fn(),
       pickAutoDispatchRider: jest.fn().mockResolvedValue(null),
@@ -171,6 +172,7 @@ describe('OrdersService', () => {
       minOrderPricePhp: '0',
       platformFeePhp: '0',
       autoDispatchEnabled: 0, // OFF by default — existing tests stay BOOKED
+      riderCodCapPhp: 1500,
       updatedAt: new Date(),
     };
     const config = {
@@ -560,6 +562,27 @@ describe('OrdersService', () => {
       ).rejects.toBeInstanceOf(BadRequestException);
     });
 
+    it('rejects a rider over the COD debt cap (outstanding ≥ cap)', async () => {
+      repo.userHasRole.mockResolvedValue(true);
+      repo.isRiderVerified.mockResolvedValue(true);
+      repo.riderOutstandingCod.mockResolvedValue(D('1500')); // == cap (1500)
+      await expect(
+        service.assignRider(makeUser(['ADMIN']), 'o1', { riderId: 'in-debt' }),
+      ).rejects.toBeInstanceOf(BadRequestException);
+    });
+
+    it('allows a rider just under the cap', async () => {
+      repo.userHasRole.mockResolvedValue(true);
+      repo.isRiderVerified.mockResolvedValue(true);
+      repo.riderOutstandingCod.mockResolvedValue(D('1499.99'));
+      repo.findByIdForUpdate.mockResolvedValue(makeOrder({ status: 'BOOKED' }));
+      repo.updateOrder.mockResolvedValue(makeOrder({ status: 'ASSIGNED' }));
+      const out = await service.assignRider(makeUser(['ADMIN']), 'o1', {
+        riderId: 'rider1',
+      });
+      expect(out.status).toBe('ASSIGNED');
+    });
+
     it('assigns and transitions BOOKED → ASSIGNED', async () => {
       repo.userHasRole.mockResolvedValue(true);
       repo.findByIdForUpdate.mockResolvedValue(makeOrder({ status: 'BOOKED' }));

apps/api/src/orders/orders.service.ts

@@ -348,7 +348,7 @@ export class OrdersService {
       // available rider immediately; if none free (or disabled), the order stays
       // BOOKED for manual admin dispatch — the exception path.
       if (cfg.autoDispatchEnabled > 0) {
-        const riderId = await this.repo.pickAutoDispatchRider(tx);
+        const riderId = await this.repo.pickAutoDispatchRider(tx, cfg.riderCodCapPhp);
         if (riderId) {
           await this.repo.updateOrder(tx, order.id, {
             status: OrderStatus.ASSIGNED,
@@ -499,6 +499,16 @@ export class OrdersService {
     // draft/rejected rider (no verified license/ID) is never handed platform cash.
     const verified = await this.repo.isRiderVerified(dto.riderId);
     if (!verified) throw new BadRequestException('Rider is not verified yet');
+    // Debt cap: a rider holding more than the configured outstanding COD stops
+    // receiving new jobs until they deposit — bounds abscond risk. Parity with
+    // the auto-dispatch filter below.
+    const { riderCodCapPhp } = await this.config.getValues();
+    const outstanding = await this.repo.riderOutstandingCod(dto.riderId);
+    if (Number(outstanding) >= riderCodCapPhp) {
+      throw new BadRequestException(
+        `Rider is over the ₱${riderCodCapPhp} cash limit — they must deposit before taking new jobs`,
+      );
+    }
 
     return this.prisma.$transaction(async (tx) => {
       const order = await this.repo.findByIdForUpdate(tx, orderId);

apps/api/src/platform-config/platform-config.service.spec.ts

@@ -18,6 +18,7 @@ const row = (over: Partial<Record<string, unknown>> = {}) => ({
   minOrderPricePhp: 0,
   platformFeePhp: 0,
   autoDispatchEnabled: 0,
+  riderCodCapPhp: 1500,
   updatedAt: new Date('2026-07-19T00:00:00Z'),
   toString() {
     return String((this as Record<string, unknown>).__v);

apps/api/src/platform-config/platform-config.service.ts

@@ -29,6 +29,7 @@ export const CONFIG_FIELDS = [
   'minOrderPricePhp',
   'platformFeePhp',
   'autoDispatchEnabled',
+  'riderCodCapPhp',
 ] as const;
 
 export type ConfigField = (typeof CONFIG_FIELDS)[number];
@@ -47,6 +48,7 @@ export interface PlatformConfigValues {
   minOrderPricePhp: string;
   platformFeePhp: string;
   autoDispatchEnabled: number; // 1 = auto-assign rider on Express booking
+  riderCodCapPhp: number; // max outstanding COD before a rider's dispatch pauses
   updatedAt: Date;
 }
 
@@ -105,6 +107,7 @@ export class PlatformConfigService {
       minOrderPricePhp: this.envNum('MIN_ORDER_PRICE_PHP', 0),
       platformFeePhp: this.envNum('PLATFORM_FEE_PHP', 0),
       autoDispatchEnabled: this.envNum('AUTO_DISPATCH_ENABLED', 0),
+      riderCodCapPhp: this.envNum('RIDER_COD_CAP_PHP', 1500),
     };
   }
 
@@ -147,6 +150,7 @@ export class PlatformConfigService {
       minOrderPricePhp: r.minOrderPricePhp.toString(),
       platformFeePhp: r.platformFeePhp.toString(),
       autoDispatchEnabled: Number(r.autoDispatchEnabled),
+      riderCodCapPhp: Number(r.riderCodCapPhp),
       updatedAt: r.updatedAt,
     };
   }

apps/api/src/riders/rider-cash.service.spec.ts

@@ -2,6 +2,12 @@ import { BadRequestException, NotFoundException } from '@nestjs/common';
 import { Prisma } from '@prisma/client';
 import { RiderCashService } from './rider-cash.service';
 import type { RiderCashRepository } from './rider-cash.repository';
+import type { PlatformConfigService } from '../platform-config/platform-config.service';
+
+// Config stub — only riderCodCapPhp is read by RiderCashService.balance().
+const configStub = {
+  getValues: jest.fn().mockResolvedValue({ riderCodCapPhp: 1500 }),
+} as unknown as PlatformConfigService;
 
 const D = (v: Prisma.Decimal.Value) => new Prisma.Decimal(v);
 
@@ -20,18 +26,19 @@ describe('RiderCashService', () => {
       listDeposits: jest.fn(),
       findRider: jest.fn(),
     } as unknown as jest.Mocked<RiderCashRepository>;
-    service = new RiderCashService(repo);
+    service = new RiderCashService(repo, configStub);
   });
 
   describe('balance', () => {
-    it('computes outstanding = collected − deposited', async () => {
+    it('computes outstanding = collected − deposited, and includes the cap', async () => {
       repo.sumCollected.mockResolvedValue(D('1250.50'));
       repo.sumDeposited.mockResolvedValue(D('800.00'));
       expect(await service.balance('r1')).toEqual({
         riderId: 'r1',
         collectedPhp: '1250.50',
         depositedPhp: '800.00',
         outstandingPhp: '450.50',
+        capPhp: '1500',
       });
     });
 

apps/api/src/riders/rider-cash.service.ts

@@ -1,13 +1,15 @@
 import { BadRequestException, Injectable, NotFoundException } from '@nestjs/common';
 import { Prisma } from '@prisma/client';
 import { isUniqueViolation } from '../common/prisma-errors';
+import { PlatformConfigService } from '../platform-config/platform-config.service';
 import { RiderCashRepository } from './rider-cash.repository';
 
 export interface RiderCashBalance {
   riderId: string;
   collectedPhp: string; // COD taken from customers
   depositedPhp: string; // handed back to the platform
   outstandingPhp: string; // still owed to the platform (collected − deposited)
+  capPhp?: string; // max outstanding before dispatch pauses (rider's own view)
 }
 
 /*
@@ -18,12 +20,18 @@ export interface RiderCashBalance {
  */
 @Injectable()
 export class RiderCashService {
-  constructor(private readonly repo: RiderCashRepository) {}
+  constructor(
+    private readonly repo: RiderCashRepository,
+    private readonly config: PlatformConfigService,
+  ) {}
 
   async balance(riderId: string): Promise<RiderCashBalance> {
-    const collected = await this.repo.sumCollected(riderId);
-    const deposited = await this.repo.sumDeposited(riderId);
-    return this.shape(riderId, collected, deposited);
+    const [collected, deposited, cfg] = await Promise.all([
+      this.repo.sumCollected(riderId),
+      this.repo.sumDeposited(riderId),
+      this.config.getValues(),
+    ]);
+    return { ...this.shape(riderId, collected, deposited), capPhp: String(cfg.riderCodCapPhp) };
   }
 
   // All riders who have collected any COD, with their outstanding balance.

apps/api/src/riders/riders.module.ts

@@ -1,5 +1,6 @@
 import { Module } from '@nestjs/common';
 import { NotificationsModule } from '../notifications/notifications.module';
+import { PlatformConfigModule } from '../platform-config/platform-config.module';
 import { RidersController } from './riders.controller';
 import { RidersService } from './riders.service';
 import { RiderCashController } from './rider-cash.controller';
@@ -12,7 +13,7 @@ import { AdminRidersController } from './admin-riders.controller';
 import { AdminRidersService } from './admin-riders.service';
 
 @Module({
-  imports: [NotificationsModule], // AdminRidersService notifies riders on verify/reject
+  imports: [NotificationsModule, PlatformConfigModule], // notify on verify/reject; config for the COD cap
   controllers: [
     RidersController,
     RiderCashController,