ac93368e9a
This comprehensive update implements: Transport Tracking System: - Complete seed-to-seed lifecycle tracking with 9 event types - TransportChain blockchain for immutable transport records - Carbon footprint calculation per transport method - Food miles tracking with Haversine distance calculation - QR code generation for full traceability Demand Forecasting System: - Consumer preference registration and aggregation - Regional demand signal generation - Supply gap identification and market matching - Grower planting recommendations with risk assessment - Seasonal planning integration Vertical Farming Module: - Multi-zone facility management - Environmental control systems (HVAC, CO2, humidity, lighting) - Growing recipes with stage-based environment targets - Crop batch tracking with health scoring - Farm analytics generation Documentation: - Complete docs/ folder structure for Turborepo - Seed-to-seed transport concept documentation - Demand forecasting and seasonal planning guides - System architecture and user blockchain design - Transport API reference - Vertical farming integration guide Agent Report: - AGENT_REPORT.md with 5 parallel agent tasks for continued development - API routes implementation task - UI components task - Vertical farming pages task - Testing suite task - Documentation completion task
476 lines
9.3 KiB
Markdown
476 lines
9.3 KiB
Markdown
# Transport API Reference
|
|
|
|
The Transport API enables seed-to-seed tracking of all plant movement and transformation events within the LocalGreenChain ecosystem.
|
|
|
|
## Base URL
|
|
|
|
```
|
|
Development: http://localhost:3001/api/transport
|
|
Production: https://api.localgreenchain.org/transport
|
|
```
|
|
|
|
## Authentication
|
|
|
|
All transport endpoints require authentication:
|
|
|
|
```http
|
|
Authorization: Bearer <user_token>
|
|
X-Wallet-Address: <wallet_address>
|
|
```
|
|
|
|
## Endpoints
|
|
|
|
### Record Seed Acquisition
|
|
|
|
Record the acquisition of seeds from any source.
|
|
|
|
```http
|
|
POST /api/transport/seed-acquisition
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"seedBatchId": "batch-2025-001",
|
|
"sourceType": "seed_bank",
|
|
"species": "Solanum lycopersicum",
|
|
"variety": "Cherokee Purple",
|
|
"quantity": 50,
|
|
"quantityUnit": "seeds",
|
|
"geneticLineageId": "lineage-tomato-cp-001",
|
|
"generation": 0,
|
|
"fromLocation": {
|
|
"latitude": 40.7128,
|
|
"longitude": -74.0060,
|
|
"locationType": "seed_bank",
|
|
"facilityName": "Baker Creek Seeds"
|
|
},
|
|
"toLocation": {
|
|
"latitude": 40.7589,
|
|
"longitude": -73.9851,
|
|
"locationType": "farm",
|
|
"facilityName": "Urban Farm NYC"
|
|
},
|
|
"transportMethod": "local_delivery",
|
|
"certifications": ["organic", "heirloom"]
|
|
}
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"event": {
|
|
"id": "evt-seed-acq-123",
|
|
"timestamp": "2025-01-15T10:30:00Z",
|
|
"eventType": "seed_acquisition",
|
|
"status": "verified"
|
|
},
|
|
"block": {
|
|
"index": 5,
|
|
"hash": "0000abc123...",
|
|
"carbonFootprintKg": 0.02,
|
|
"foodMiles": 5.2
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### Record Planting
|
|
|
|
Record when seeds are planted.
|
|
|
|
```http
|
|
POST /api/transport/planting
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"seedBatchId": "batch-2025-001",
|
|
"plantIds": ["plant-001", "plant-002", "plant-003"],
|
|
"plantingMethod": "transplant",
|
|
"quantityPlanted": 25,
|
|
"growingEnvironment": "vertical_farm",
|
|
"location": {
|
|
"latitude": 40.7589,
|
|
"longitude": -73.9851,
|
|
"locationType": "vertical_farm",
|
|
"facilityName": "Urban Farm NYC"
|
|
},
|
|
"expectedHarvestDate": "2025-03-15T00:00:00Z"
|
|
}
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"event": {
|
|
"id": "evt-planting-124",
|
|
"timestamp": "2025-01-20T08:00:00Z",
|
|
"eventType": "planting",
|
|
"plantIds": ["plant-001", "plant-002", "plant-003"]
|
|
},
|
|
"block": {
|
|
"index": 6,
|
|
"hash": "0000def456..."
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### Record Growing Transport
|
|
|
|
Record plant movement during growing (transplanting, relocating).
|
|
|
|
```http
|
|
POST /api/transport/growing
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"plantIds": ["plant-001", "plant-002"],
|
|
"reason": "transplant",
|
|
"plantStage": "seedling",
|
|
"handlingMethod": "potted",
|
|
"fromLocation": {
|
|
"latitude": 40.7589,
|
|
"longitude": -73.9851,
|
|
"locationType": "greenhouse",
|
|
"facilityName": "Seedling House A"
|
|
},
|
|
"toLocation": {
|
|
"latitude": 40.7589,
|
|
"longitude": -73.9852,
|
|
"locationType": "vertical_farm",
|
|
"facilityName": "Main Growing Tower"
|
|
},
|
|
"transportMethod": "walking",
|
|
"rootDisturbance": "minimal",
|
|
"acclimatizationRequired": true,
|
|
"acclimatizationDays": 3
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### Record Harvest
|
|
|
|
Record harvest events with yield data.
|
|
|
|
```http
|
|
POST /api/transport/harvest
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"plantIds": ["plant-001", "plant-002", "plant-003"],
|
|
"harvestBatchId": "harvest-2025-050",
|
|
"harvestType": "full",
|
|
"produceType": "tomatoes",
|
|
"grossWeight": 15.5,
|
|
"netWeight": 14.2,
|
|
"weightUnit": "kg",
|
|
"qualityGrade": "A",
|
|
"packagingType": "compostable_clamshell",
|
|
"temperatureRequired": {
|
|
"min": 10,
|
|
"max": 15,
|
|
"optimal": 12,
|
|
"unit": "celsius"
|
|
},
|
|
"shelfLifeHours": 168,
|
|
"seedsSaved": true,
|
|
"seedBatchIdCreated": "batch-2025-002"
|
|
}
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"event": {
|
|
"id": "evt-harvest-125",
|
|
"timestamp": "2025-03-15T06:00:00Z",
|
|
"eventType": "harvest",
|
|
"harvestBatchId": "harvest-2025-050",
|
|
"netWeight": 14.2
|
|
},
|
|
"block": {
|
|
"index": 25,
|
|
"hash": "0000ghi789...",
|
|
"carbonFootprintKg": 0.1
|
|
},
|
|
"seedBatch": {
|
|
"id": "batch-2025-002",
|
|
"parentPlants": ["plant-001", "plant-002", "plant-003"],
|
|
"generation": 1
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### Record Distribution
|
|
|
|
Record movement through distribution chain.
|
|
|
|
```http
|
|
POST /api/transport/distribution
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"batchIds": ["harvest-2025-050"],
|
|
"destinationType": "consumer",
|
|
"fromLocation": {
|
|
"latitude": 40.7589,
|
|
"longitude": -73.9851,
|
|
"locationType": "vertical_farm"
|
|
},
|
|
"toLocation": {
|
|
"latitude": 40.7614,
|
|
"longitude": -73.9776,
|
|
"locationType": "consumer"
|
|
},
|
|
"transportMethod": "bicycle",
|
|
"orderId": "order-2025-1234",
|
|
"customerType": "individual",
|
|
"deliveryWindow": {
|
|
"start": "2025-03-15T14:00:00Z",
|
|
"end": "2025-03-15T18:00:00Z"
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### Record Seed Saving
|
|
|
|
Record seed saving from harvested plants.
|
|
|
|
```http
|
|
POST /api/transport/seed-saving
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"parentPlantIds": ["plant-001", "plant-002"],
|
|
"newSeedBatchId": "batch-2025-003",
|
|
"collectionMethod": "fermentation",
|
|
"seedCount": 200,
|
|
"seedWeight": 15,
|
|
"seedWeightUnit": "grams",
|
|
"storageConditions": {
|
|
"temperature": 10,
|
|
"humidity": 40,
|
|
"lightExposure": "dark",
|
|
"containerType": "vacuum_sealed",
|
|
"desiccant": true,
|
|
"estimatedViability": 5
|
|
},
|
|
"newGenerationNumber": 2,
|
|
"availableForSharing": true,
|
|
"sharingTerms": "trade"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### Record Seed Sharing
|
|
|
|
Record when seeds are shared with others.
|
|
|
|
```http
|
|
POST /api/transport/seed-sharing
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"seedBatchId": "batch-2025-003",
|
|
"quantityShared": 25,
|
|
"quantityUnit": "seeds",
|
|
"sharingType": "trade",
|
|
"tradeDetails": "Traded for 25 basil seeds",
|
|
"recipientId": "user-xyz-456",
|
|
"fromLocation": {...},
|
|
"toLocation": {...},
|
|
"recipientAgreement": true,
|
|
"growingCommitment": "Will grow and report back",
|
|
"reportBackRequired": true
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Query Endpoints
|
|
|
|
### Get Plant Journey
|
|
|
|
Get complete transport history for a plant.
|
|
|
|
```http
|
|
GET /api/transport/journey/:plantId
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"plantId": "plant-001",
|
|
"seedBatchOrigin": "batch-2025-001",
|
|
"currentCustodian": "user-abc-123",
|
|
"currentLocation": {
|
|
"latitude": 40.7614,
|
|
"longitude": -73.9776,
|
|
"locationType": "consumer"
|
|
},
|
|
"currentStage": "post_harvest",
|
|
"events": [
|
|
{
|
|
"eventType": "seed_acquisition",
|
|
"timestamp": "2025-01-15T10:30:00Z",
|
|
"fromLocation": {...},
|
|
"toLocation": {...}
|
|
},
|
|
{
|
|
"eventType": "planting",
|
|
"timestamp": "2025-01-20T08:00:00Z",
|
|
...
|
|
},
|
|
...
|
|
],
|
|
"totalFoodMiles": 12.5,
|
|
"totalCarbonKg": 0.35,
|
|
"daysInTransit": 2,
|
|
"daysGrowing": 54,
|
|
"generation": 1,
|
|
"ancestorPlantIds": ["parent-plant-001"],
|
|
"descendantSeedBatches": ["batch-2025-003"]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### Get Environmental Impact
|
|
|
|
Get carbon footprint and food miles for a user.
|
|
|
|
```http
|
|
GET /api/transport/footprint/:userId
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"totalCarbonKg": 15.5,
|
|
"totalFoodMiles": 250,
|
|
"carbonPerKgProduce": 0.25,
|
|
"milesPerKgProduce": 4.0,
|
|
"breakdownByMethod": {
|
|
"bicycle": { "distance": 50, "carbon": 0 },
|
|
"electric_vehicle": { "distance": 150, "carbon": 3.0 },
|
|
"walking": { "distance": 50, "carbon": 0 }
|
|
},
|
|
"breakdownByEventType": {
|
|
"seed_acquisition": { "count": 5, "carbon": 0.5 },
|
|
"distribution": { "count": 50, "carbon": 10.0 },
|
|
...
|
|
},
|
|
"comparisonToConventional": {
|
|
"carbonSaved": 140.5,
|
|
"milesSaved": 74750,
|
|
"percentageReduction": 90
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### Verify Block
|
|
|
|
Verify a transport block's integrity.
|
|
|
|
```http
|
|
GET /api/transport/verify/:blockHash
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"valid": true,
|
|
"block": {
|
|
"index": 25,
|
|
"hash": "0000ghi789...",
|
|
"previousHash": "0000fgh678...",
|
|
"timestamp": "2025-03-15T06:00:00Z"
|
|
},
|
|
"chainValid": true,
|
|
"crossReferences": [
|
|
{
|
|
"userId": "user-xyz-456",
|
|
"blockIndex": 12,
|
|
"type": "receiver",
|
|
"verified": true
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### Generate QR Code
|
|
|
|
Generate QR code data for a plant or batch.
|
|
|
|
```http
|
|
GET /api/transport/qr/:plantId
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"plantId": "plant-001",
|
|
"blockchainAddress": "0x1234567890abcdef...",
|
|
"quickLookupUrl": "https://localgreenchain.org/track/plant-001",
|
|
"lineageHash": "a1b2c3d4e5f6...",
|
|
"currentCustodian": "user-abc-123",
|
|
"lastEventType": "distribution",
|
|
"lastEventTimestamp": "2025-03-15T14:30:00Z",
|
|
"verificationCode": "A1B2C3D4",
|
|
"qrCodeImage": "data:image/png;base64,..."
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Error Codes
|
|
|
|
| Code | Message | Description |
|
|
|------|---------|-------------|
|
|
| 400 | Invalid request | Missing or invalid parameters |
|
|
| 401 | Unauthorized | Invalid or missing auth token |
|
|
| 403 | Forbidden | Not authorized for this resource |
|
|
| 404 | Not found | Plant/batch/block not found |
|
|
| 409 | Conflict | Duplicate event or chain conflict |
|
|
| 422 | Validation error | Data validation failed |
|
|
| 500 | Server error | Internal server error |
|
|
|
|
## Rate Limits
|
|
|
|
| Endpoint Type | Limit | Window |
|
|
|---------------|-------|--------|
|
|
| Read (GET) | 100 | per minute |
|
|
| Write (POST) | 20 | per minute |
|
|
| Batch operations | 5 | per minute |
|
|
|
|
## Webhooks
|
|
|
|
Subscribe to transport events:
|
|
|
|
```http
|
|
POST /api/transport/webhooks
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"url": "https://your-server.com/webhook",
|
|
"events": ["seed_acquisition", "harvest", "distribution"],
|
|
"filters": {
|
|
"plantIds": ["plant-001", "plant-002"],
|
|
"userId": "user-abc-123"
|
|
}
|
|
}
|
|
```
|