Skip to content

MILESTONE_DELIVERY_TRANSITION.md

Latest commit

 

History

History
130 lines (97 loc) · 4.58 KB

MILESTONE_DELIVERY_TRANSITION.md

File metadata and controls

130 lines (97 loc) · 4.58 KB

Milestone Delivery Transition Implementation

This document describes the implementation of automatic trade deal status transition to "delivered" when the importer milestone is recorded.

Feature Overview

When a trader records the final "importer" milestone for a funded trade deal, the system automatically:

  1. Updates the trade deal status from "funded" to "delivered"
  2. Enqueues a deal.delivered job to trigger escrow release
  3. Ensures atomicity through database transactions

Implementation Details

Requirements Addressed

  • 5.5: Recording the importer milestone transitions the deal status to delivered

Key Components Modified

1. ShipmentsService (backend/src/shipments/shipments.service.ts)

  • Transaction Atomicity: Wrapped milestone recording in database transaction
  • Status Transition: Added logic to update deal status when milestone is "importer"
  • Job Enqueueing: Triggers deal.delivered job for escrow release
  • Logging: Added transition logging for monitoring

2. QueueService (backend/src/queue/queue.service.ts)

  • Dedicated Method: Added enqueueDealDelivered() method for type safety
  • Error Handling: Maintains existing error handling patterns

3. ShipmentsModule (backend/src/shipments/shipments.module.ts)

  • Dependency Injection: Added QueueModule import for job enqueueing

Business Logic Flow

1. Trader records "importer" milestone
2. System validates:
   - Deal exists and is in "funded" status
   - User is the assigned trader
   - Milestone follows correct sequence (farm → warehouse → port → importer)
3. Within database transaction:
   a. Anchor milestone on Stellar blockchain
   b. Save milestone record
   c. Update trade deal status to "delivered"
   d. Enqueue deal.delivered job
4. Log successful transition
5. Return milestone record

Database Transaction Atomicity

The implementation ensures that if any step fails:

  • Milestone record is rolled back
  • Deal status remains unchanged
  • No job is enqueued
  • Error is propagated to caller

This prevents partial state where a milestone exists but the deal status wasn't updated.

Milestone Sequence

The system enforces strict milestone sequence:

  1. farm - Goods collected from farm
  2. warehouse - Goods stored in warehouse
  3. port - Goods shipped from port
  4. importer - Goods received by importer (triggers delivery)

Only the "importer" milestone triggers the status transition and job enqueueing.

Queue Job Details

Job Pattern: deal.delivered Payload:

{
  "tradeDealId": "uuid-of-trade-deal"
}

This job will be consumed by the escrow release processor (implemented in task 11).

Error Handling

Validation Errors

  • Deal Not Found: Returns 404 if trade deal doesn't exist
  • Invalid Status: Returns 422 if deal is not in "funded" status
  • Unauthorized: Returns 403 if user is not the assigned trader
  • Sequence Error: Returns 422 if milestone is out of sequence

Transaction Failures

  • Database transaction ensures atomicity
  • Stellar anchoring failures roll back the entire operation
  • Queue job failures roll back milestone and status changes

Testing

Unit Tests (backend/src/shipments/shipments.service.spec.ts)

  • Importer Milestone: Verifies status transition and job enqueueing
  • Non-Importer Milestones: Verifies no status change occurs
  • Transaction Atomicity: Ensures rollback on failures

Integration Testing

To test the complete flow:

  1. Create a funded trade deal
  2. Record milestones in sequence: farm → warehouse → port
  3. Record importer milestone
  4. Verify deal status changed to "delivered"
  5. Verify deal.delivered job was enqueued

Monitoring and Logging

The system logs the following events:

  • Successful Transition: Deal {id} transitioned to delivered — escrow release job enqueued
  • Job Enqueueing: Emitted event: deal.delivered (from QueueService)
  • Errors: All validation and transaction errors are logged

Future Considerations

  1. Idempotency: Consider adding checks to prevent duplicate processing
  2. Retry Logic: Implement retry mechanisms for failed job enqueueing
  3. Notifications: Add user notifications for status transitions
  4. Audit Trail: Enhanced logging for compliance and debugging

Dependencies

This implementation depends on:

  • Task 10: POST /shipments/milestones endpoint
  • Task 8: Deal funding and status management
  • Task 11: Escrow release job consumer (future implementation)

The deal.delivered job produced by this implementation will be consumed by the escrow release system in task 11.5.