Request supplies and close the delivery loop.

Configure operating scopes, create store requests, record partial deliveries, export the evidence, and troubleshoot safe retry behavior.

01 / Apply the release

Database and access setup

1
Apply migrations in order
Run 202608020012_phase_4_5_supplies_needed.sql after all earlier migrations.
2
Create districts and stores
Admins can use Supplies → Locations. Store codes and district codes become stable operating references.
3
Assign scopes
Add store users to user_store_access and district managers to user_district_access. Admins retain organization-wide visibility.

02 / Store workflow

Create a request

Open Supplies, choose the store, then add one or more item rows. Each row requires a description and a positive whole-number quantity; SKU and unit are optional. The server derives the district and requester.

Rate control: a store can create up to 20 supply requests per rolling hour. The database enforces the limit even when more than one client submits at once.

03 / District workflow

Record delivery without losing the remainder

District managers see requests for their assigned districts. Use partial delivery to record quantities that arrived, or mark all delivered to complete every remaining line. Both operations lock the request row and item rows inside a single transaction.

Requested → partially delivered → delivered is supported.
Requested → delivered is supported.
A delivered or cancelled request cannot be delivered again.
A delivery date cannot predate the request or be materially in the future.
Every action records the actor, timestamp, and affected quantities.

04 / API and export

Stable integration surface

GET /api/v1/suppliesPOST /api/v1/suppliesGET /api/v1/supplies/:idPUT /api/v1/supplies/:idPOST /api/v1/supplies/:id/mark_partialPOST /api/v1/supplies/:id/mark_deliveredPOST /api/v1/supplies/:id/cancelGET /api/v1/supplies/export

Use the narrowest API-key scope: supplies:read, supplies:write, supplies:deliver, or supplies:export.

05 / Rollback and troubleshooting

Preserve evidence first

If the workflow must be disabled, remove the Supplies navigation entry and revoke supply permissions first. Keep the three supply tables read-only for audit retention. Drop them only after an approved export and retention review; no asset or work-order rollback is required.

A 409 means the request is already final or the state transition is no longer valid. A 403 means the user or key does not have the required store/district scope. A 429 means the store’s request rate limit was reached.

Ready to use it?Open Supplies →