feat: Implement ShippingProcessHandler Example (Phase 7.2)

[artcava]

Description

Summary

This PR implements ShippingProcessHandler as an example handler demonstrating shipping and logistics operations. The handler complements OrderProcessHandler by showcasing a different process type with distinct business logic focused on carrier management, shipping cost calculation, and warehouse coordination.

Motivation and Context

This implementation provides a second concrete example of the process handler pattern, demonstrating how different business domains (shipping vs order processing) can be implemented using the same IProcessHandler interface. It shows alternative patterns for validation (whitelist approach), return values (tracking numbers), and external service integration (carrier APIs).

Link to related issue(s): Fixes #106

Type of Change

• New feature (non-breaking change which adds functionality)
• Documentation update
• Test additions/updates

---

Changes Made

Key Changes

• ShippingProcessHandler: Implemented handler for "shipping" process type with 5-step workflow
• Unit Tests: Added comprehensive test suite with >90% coverage (11 tests)
• Documentation: Created shipping process examples with API requests and testing instructions
• DI Registration: Registered handler in ProcessHandlerServiceCollectionExtensions

Technical Details

Architecture changes:

• Added new handler implementing IProcessHandler interface
• Registered handler in DI container with auto-registration pattern
• Follows same architectural pattern as OrderProcessHandler

Handler Implementation:

• Process Type: "shipping"
• Required Metadata: shipmentId, orderId, destination, carrier
• Carrier Whitelist: UPS, FEDEX, DHL, USPS (case-insensitive)
• Workflow Steps:
  1. Calculate shipping cost (~150ms) - carrier-based pricing with variation
  2. Reserve carrier capacity (~200ms) - 2% simulated failure rate
  3. Generate shipping label (~100ms) - tracking number format TRK{timestamp}{shipmentId}
  4. Notify warehouse (~50ms) - async message to WMS
  5. Update shipment status (~50ms) - set to "ReadyToShip"

Validation Strategy:

• Whitelist validation for carriers (fail-fast approach)
• Required field validation with descriptive error messages
• Case-insensitive carrier matching

Error Handling:

• InvalidOperationException for validation failures (non-retryable)
• HttpRequestException for capacity issues (retryable)
• OperationCanceledException for cancellation support
• Structured logging at all steps with named parameters

Return Values:

• Demonstrates handler with return value (tracking number)
• Contrast with OrderProcessHandler (void return)

---

Testing

Test Coverage

• Unit tests added/updated
• All tests passing locally
• Code coverage maintained/improved (>90% for handler)

Test Suite Details

ShippingProcessHandlerTests (11 tests):

1. ✅ ProcessType_Should_ReturnShipping - Validates process type
2. ✅ ExecuteAsync_Should_ThrowInvalidOperationException_WhenShipmentIdMissing - Required field validation
3. ✅ ExecuteAsync_Should_ThrowInvalidOperationException_WhenOrderIdMissing - Required field validation
4. ✅ ExecuteAsync_Should_ThrowInvalidOperationException_WhenDestinationMissing - Required field validation
5. ✅ ExecuteAsync_Should_ThrowInvalidOperationException_WhenCarrierMissing - Required field validation
6. ✅ ExecuteAsync_Should_ThrowInvalidOperationException_WhenCarrierInvalid - Whitelist validation
7. ✅ ExecuteAsync_Should_AcceptValidCarriers - Theory test (4 data points: UPS, FEDEX, DHL, USPS)
8. ✅ ExecuteAsync_Should_AcceptCarriersInLowercase - Theory test (4 data points: case-insensitive)
9. ✅ ExecuteAsync_Should_ThrowOperationCanceledException_WhenCancellationRequested - Cancellation support
10. ✅ ExecuteAsync_Should_CompleteSuccessfully_WithValidData - Happy path
11. ✅ Constructor_Should_ThrowArgumentNullException_WhenLoggerIsNull - Null guard

Manual Testing

Testing instructions provided in docs/examples/shipping-process-examples.md:

1. Unit Tests: Run with dotnet test --filter "FullyQualifiedName~ShippingProcessHandler"
2. API Testing: curl examples for all carriers (UPS, FEDEX, DHL, USPS)
3. Error Scenarios: Examples for missing fields, invalid carriers, capacity failures
4. Bulk Testing: Bash script to test all carriers in loop

Test Evidence

# Run handler tests
dotnet test tests/StarGate.Server.Tests --filter "FullyQualifiedName~ShippingProcessHandler"

# Expected: All 11 tests pass

---

Checklist

Before requesting review, confirm:

• Code follows coding conventions
  • PascalCase for classes/methods, camelCase for parameters
  • Async/await pattern with Async suffix
  • XML documentation for public APIs
  • Structured logging with named parameters
• Code has been formatted with dotnet format
• Self-review completed
• Comments added for complex logic
• XML documentation added for public APIs
• No compiler warnings
• All tests pass
• Documentation updated (shipping-process-examples.md)
• No sensitive data in code or commits

---

Implementation Details

Files Created/Modified

Created:

1. src/StarGate.Server/Handlers/ShippingProcessHandler.cs (8.4 KB)

   • Implements IProcessHandler with ProcessType = "shipping"
   • 5-step shipping workflow
   • Comprehensive error handling and logging

2. tests/StarGate.Server.Tests/Handlers/ShippingProcessHandlerTests.cs (8.3 KB)

   • 11 unit tests with >90% coverage
   • Theory tests for carrier validation
   • Cancellation and error scenario tests

3. docs/examples/shipping-process-examples.md (13.6 KB)

   • API request examples for all carriers
   • Error scenarios with expected results
   • Testing instructions (unit tests, API, bash scripts)
   • Production considerations and extension examples
   • Comparison table with OrderProcessHandler

Modified:
4. src/StarGate.Server/Extensions/ProcessHandlerServiceCollectionExtensions.cs

• Added ShippingProcessHandler registration
• Auto-registration with ProcessHandlerFactory

Commits

1. cc755fe - feat: implement ShippingProcessHandler for shipping operations
2. fb1bef7 - test: add comprehensive unit tests for ShippingProcessHandler
3. d924f99 - docs: add shipping process API examples and documentation
4. 4f642c1 - feat: register ShippingProcessHandler in DI container

---

Comparison with OrderProcessHandler

This handler demonstrates alternative implementation patterns:

Aspect	OrderProcessHandler	ShippingProcessHandler
Process Type	"order"	"shipping"
Primary Focus	Payment and fulfillment	Logistics and carriers
Validation	Amount format (decimal)	Carrier whitelist
External Services	Payment gateway, inventory	Carrier API, warehouse
Return Value	None (void)	Tracking number (string)
Failure Rate	5% inventory, 3% payment	2% capacity
Steps	4 steps	5 steps
Average Duration	~400ms	~550ms

---

Additional Notes

Simulated Failures:

• 2% random failure rate in carrier capacity reservation
• Demonstrates retry behavior with HttpRequestException
• Production implementation would replace with real carrier API calls

Extension Points:

• Easy to add new carriers (update whitelist array)
• Weight-based pricing can be added via metadata
• International shipping support via additional metadata fields
• See documentation for extension examples

Production Considerations (documented):

• Replace simulated delays with real API calls
• Integrate actual carrier APIs (UPS, FedEx, DHL, USPS)
• Add weight/dimension calculations
• Implement address validation
• Support international shipping with customs data

---

Review Focus Areas

• Handler Pattern: Verify alignment with OrderProcessHandler pattern and IProcessHandler interface usage
• Error Handling: Review exception types and retry behavior for different failure scenarios
• Test Coverage: Validate Theory tests for carrier validation and error scenario coverage
• Documentation: Check clarity of examples and testing instructions
• DI Registration: Confirm proper registration and auto-registration with factory

---

Related Issues:

• Implements Phase 7.2: Implement ShippingProcessHandler Example #106
• Depends on Phase 7.2: Implement ProcessHandlerFactory with Handler Registration #104 (ProcessHandlerFactory - merged)
• Follows pattern from Phase 7.2: Implement OrderProcessHandler Example #105 (OrderProcessHandler - merged)
• Part of Phase 7.2: Process Handlers

Documentation References:

• TECHNICAL-ANALYSIS.md - Phase 7.2
• CODING-CONVENTIONS.md
• GIT-FLOW.md
• PULL-REQUEST-PROCESS.md