4111c3acf1
- Add guides: quick-start, installation, configuration, grower, consumer, transport, vertical-farm - Add API references: REST, demand, vertical-farming - Add concepts: blockchain, seasonal-planning, carbon-footprint - Add architecture: data-flow, transport-tracking - Add vertical-farming: environmental-control, automation, integration - Add examples: seed-to-harvest, demand-driven-planting, vertical-farm-setup Completes Agent_5 documentation tasks from AGENT_REPORT.md
426 lines
13 KiB
Markdown
426 lines
13 KiB
Markdown
# Transport Guide
|
||
|
||
Complete guide to recording and tracking transport events in LocalGreenChain.
|
||
|
||
## Transport Event Types
|
||
|
||
LocalGreenChain tracks 9 types of transport events covering the complete seed-to-seed lifecycle:
|
||
|
||
| Event Type | Description | When to Use |
|
||
|------------|-------------|-------------|
|
||
| `seed_acquisition` | Receiving seeds from any source | Purchasing, trading, or harvesting seeds |
|
||
| `planting` | Planting seeds or transplanting | Starting new plants |
|
||
| `growing_transport` | Moving plants during growth | Transplanting, hardening off |
|
||
| `harvest` | Collecting produce from plants | Harvest day |
|
||
| `processing` | Processing harvested produce | Washing, cutting, packaging |
|
||
| `distribution` | Moving to distribution points | To markets, hubs, restaurants |
|
||
| `consumer_delivery` | Final delivery to consumer | Last mile delivery |
|
||
| `seed_saving` | Collecting seeds from plants | End of growing cycle |
|
||
| `seed_sharing` | Sharing seeds with others | Trading, gifting seeds |
|
||
|
||
## Recording Transport Events
|
||
|
||
### Seed Acquisition
|
||
|
||
```typescript
|
||
POST /api/transport/seed-acquisition
|
||
|
||
{
|
||
// Required fields
|
||
seedBatchId: "seeds-tomato-2024-001",
|
||
sourceType: "purchase", // seed_bank, previous_harvest, trade, purchase, wild_collected, gift
|
||
species: "Solanum lycopersicum",
|
||
quantity: 500,
|
||
quantityUnit: "seeds",
|
||
generation: 1,
|
||
|
||
// Location (from → to)
|
||
fromLocation: {
|
||
latitude: 38.9072,
|
||
longitude: -77.0369,
|
||
locationType: "seed_bank",
|
||
facilityName: "Heritage Seeds"
|
||
},
|
||
toLocation: {
|
||
latitude: 40.7128,
|
||
longitude: -74.0060,
|
||
locationType: "farm",
|
||
facilityName: "Green Valley Farm"
|
||
},
|
||
|
||
// Transport details
|
||
transportMethod: "local_delivery",
|
||
durationMinutes: 120,
|
||
|
||
// Optional details
|
||
variety: "Cherokee Purple",
|
||
certifications: ["organic", "heirloom"],
|
||
germinationRate: 92,
|
||
harvestDate: "2023-10-15",
|
||
geneticLineageId: "lineage-abc123"
|
||
}
|
||
```
|
||
|
||
### Planting Event
|
||
|
||
```typescript
|
||
POST /api/transport/planting
|
||
|
||
{
|
||
seedBatchId: "seeds-tomato-2024-001",
|
||
plantIds: ["plant-001", "plant-002"], // Can be auto-generated
|
||
quantityPlanted: 50,
|
||
plantingMethod: "transplant", // direct_sow, transplant, indoor_start, hydroponic, aeroponic
|
||
growingEnvironment: "greenhouse", // outdoor, greenhouse, indoor, vertical_farm
|
||
|
||
fromLocation: {
|
||
latitude: 40.7128,
|
||
longitude: -74.0060,
|
||
locationType: "greenhouse",
|
||
facilityName: "Seed Starting House"
|
||
},
|
||
toLocation: {
|
||
latitude: 40.7130,
|
||
longitude: -74.0065,
|
||
locationType: "greenhouse",
|
||
facilityName: "Growing Greenhouse"
|
||
},
|
||
|
||
expectedHarvestDate: "2024-08-15",
|
||
sowingDepth: 6, // mm
|
||
spacing: 60 // cm
|
||
}
|
||
```
|
||
|
||
### Growing Transport
|
||
|
||
For transplanting or moving plants:
|
||
|
||
```typescript
|
||
POST /api/transport/growing
|
||
|
||
{
|
||
plantIds: ["plant-001", "plant-002"],
|
||
reason: "transplant", // transplant, relocation, hardening_off, seasonal_move, upgrade_facility
|
||
plantStage: "seedling", // seed, germinating, seedling, vegetative, flowering, fruiting, mature
|
||
handlingMethod: "potted", // bare_root, potted, root_ball, hydroponic_transfer
|
||
|
||
rootDisturbance: "minimal", // none, minimal, moderate, significant
|
||
acclimatizationRequired: true,
|
||
acclimatizationDays: 7,
|
||
|
||
fromLocation: { ... },
|
||
toLocation: { ... },
|
||
|
||
transportMethod: "walking",
|
||
environmentalConditions: {
|
||
temperatureMin: 15,
|
||
temperatureMax: 22,
|
||
temperatureAvg: 18,
|
||
humidityMin: 60,
|
||
humidityMax: 80,
|
||
humidityAvg: 70,
|
||
lightExposure: "ambient"
|
||
}
|
||
}
|
||
```
|
||
|
||
### Harvest Event
|
||
|
||
```typescript
|
||
POST /api/transport/harvest
|
||
|
||
{
|
||
plantIds: ["plant-001", "plant-002"],
|
||
harvestBatchId: "harvest-2024-001",
|
||
harvestType: "full", // full, partial, continuous, selective
|
||
produceType: "tomatoes",
|
||
|
||
// Weights
|
||
grossWeight: 50,
|
||
netWeight: 47,
|
||
weightUnit: "kg",
|
||
itemCount: 200,
|
||
|
||
// Quality
|
||
qualityGrade: "A", // A, B, C, processing
|
||
qualityNotes: "Excellent color and firmness",
|
||
|
||
// Storage requirements
|
||
packagingType: "cardboard_flat",
|
||
temperatureRequired: {
|
||
min: 10,
|
||
max: 15,
|
||
optimal: 12,
|
||
unit: "celsius"
|
||
},
|
||
shelfLifeHours: 168,
|
||
|
||
// Seed saving
|
||
seedsSaved: true,
|
||
seedBatchIdCreated: "seeds-tomato-2024-002",
|
||
|
||
fromLocation: { ... },
|
||
toLocation: { ... }
|
||
}
|
||
```
|
||
|
||
### Distribution Event
|
||
|
||
```typescript
|
||
POST /api/transport/distribution
|
||
|
||
{
|
||
batchIds: ["harvest-2024-001"],
|
||
destinationType: "market", // consumer, market, restaurant, processor, distributor, vertical_farm
|
||
customerType: "business", // individual, business, cooperative, institution
|
||
|
||
orderId: "order-456",
|
||
deliveryWindow: {
|
||
start: "2024-08-02T06:00:00Z",
|
||
end: "2024-08-02T08:00:00Z"
|
||
},
|
||
deliveryAttempts: 1,
|
||
handoffVerified: true,
|
||
recipientName: "Brooklyn Farmers Market",
|
||
|
||
transportMethod: "electric_vehicle",
|
||
fromLocation: { ... },
|
||
toLocation: { ... }
|
||
}
|
||
```
|
||
|
||
### Seed Saving Event
|
||
|
||
```typescript
|
||
POST /api/transport/seed-saving
|
||
|
||
{
|
||
parentPlantIds: ["plant-001", "plant-005"],
|
||
newSeedBatchId: "seeds-tomato-2024-002",
|
||
|
||
// Collection details
|
||
collectionMethod: "wet_seed", // dry_seed, wet_seed, fermentation, threshing
|
||
seedCount: 250,
|
||
seedWeight: 15,
|
||
seedWeightUnit: "grams",
|
||
|
||
// Quality testing
|
||
viabilityTestDate: "2024-08-20",
|
||
germinationRate: 94,
|
||
purityPercentage: 98,
|
||
|
||
// Storage
|
||
storageConditions: {
|
||
temperature: 4,
|
||
humidity: 30,
|
||
lightExposure: "dark",
|
||
containerType: "vacuum_sealed",
|
||
desiccant: true,
|
||
estimatedViability: 5 // years
|
||
},
|
||
storageLocationId: "storage-vault-001",
|
||
|
||
// Lineage
|
||
newGenerationNumber: 2,
|
||
geneticNotes: "Selected for disease resistance and flavor",
|
||
|
||
// Sharing
|
||
availableForSharing: true,
|
||
sharingTerms: "trade"
|
||
}
|
||
```
|
||
|
||
## Carbon Footprint Calculation
|
||
|
||
### Carbon Factors by Transport Method
|
||
|
||
| Method | kg CO2 per km per kg |
|
||
|--------|---------------------|
|
||
| walking | 0 |
|
||
| bicycle | 0 |
|
||
| electric_vehicle | 0.02 |
|
||
| hybrid_vehicle | 0.08 |
|
||
| gasoline_vehicle | 0.12 |
|
||
| diesel_truck | 0.15 |
|
||
| electric_truck | 0.03 |
|
||
| refrigerated_truck | 0.25 |
|
||
| rail | 0.01 |
|
||
| ship | 0.008 |
|
||
| air | 0.5 |
|
||
| drone | 0.01 |
|
||
| local_delivery | 0.05 |
|
||
| customer_pickup | 0.1 |
|
||
|
||
### Calculation Formula
|
||
|
||
```
|
||
Carbon (kg CO2) = Factor × Distance (km) × Weight (kg)
|
||
```
|
||
|
||
### Example
|
||
|
||
```
|
||
Tomatoes: 20 kg
|
||
Distance: 25 km
|
||
Method: electric_vehicle (factor: 0.02)
|
||
|
||
Carbon = 0.02 × 25 × 20 = 10 kg CO2
|
||
```
|
||
|
||
## Querying Transport Data
|
||
|
||
### Get Plant Journey
|
||
|
||
```typescript
|
||
GET /api/transport/journey/plant-001
|
||
```
|
||
|
||
Response:
|
||
|
||
```json
|
||
{
|
||
"plantId": "plant-001",
|
||
"seedBatchOrigin": "seeds-tomato-2024-001",
|
||
"currentStage": "harvesting",
|
||
"events": [...],
|
||
"totalFoodMiles": 45,
|
||
"totalCarbonKg": 2.5,
|
||
"daysGrowing": 85,
|
||
"generation": 1,
|
||
"ancestorPlantIds": []
|
||
}
|
||
```
|
||
|
||
### Get Environmental Impact
|
||
|
||
```typescript
|
||
GET /api/transport/footprint/user-123
|
||
```
|
||
|
||
Response:
|
||
|
||
```json
|
||
{
|
||
"totalCarbonKg": 45.5,
|
||
"totalFoodMiles": 320,
|
||
"carbonPerKgProduce": 0.18,
|
||
"breakdownByMethod": {
|
||
"electric_vehicle": { "distance": 200, "carbon": 20 },
|
||
"walking": { "distance": 50, "carbon": 0 }
|
||
},
|
||
"comparisonToConventional": {
|
||
"carbonSaved": 580,
|
||
"milesSaved": 22500,
|
||
"percentageReduction": 93
|
||
}
|
||
}
|
||
```
|
||
|
||
### Verify Block
|
||
|
||
```typescript
|
||
GET /api/transport/verify/abc123def456
|
||
```
|
||
|
||
## QR Code Integration
|
||
|
||
### Generate QR Data
|
||
|
||
```typescript
|
||
GET /api/transport/qr/plant-001
|
||
```
|
||
|
||
Response:
|
||
|
||
```json
|
||
{
|
||
"plantId": "plant-001",
|
||
"blockchainAddress": "0x1234...",
|
||
"quickLookupUrl": "https://localgreenchain.org/track/plant-001",
|
||
"lineageHash": "sha256...",
|
||
"currentCustodian": "grower-123",
|
||
"lastEventType": "harvest",
|
||
"verificationCode": "A1B2C3D4"
|
||
}
|
||
```
|
||
|
||
## Data Flow Diagram
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────────┐
|
||
│ TRANSPORT DATA FLOW │
|
||
├─────────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ ┌───────────┐ │
|
||
│ │ SEED │ seed_acquisition │
|
||
│ │ ACQUISITION│────────────┐ │
|
||
│ └───────────┘ │ │
|
||
│ │ ▼ │
|
||
│ │ ┌───────────────┐ │
|
||
│ │ │ TRANSPORT │ │
|
||
│ │ │ CHAIN │ │
|
||
│ │ │ BLOCKCHAIN │ │
|
||
│ │ └───────┬───────┘ │
|
||
│ ▼ │ │
|
||
│ ┌───────────┐ │ │
|
||
│ │ PLANTING │─────────────┤ planting │
|
||
│ └───────────┘ │ │
|
||
│ │ │ │
|
||
│ ▼ │ │
|
||
│ ┌───────────┐ │ │
|
||
│ │ GROWING │─────────────┤ growing_transport │
|
||
│ │ TRANSPORT │ │ │
|
||
│ └───────────┘ │ │
|
||
│ │ │ │
|
||
│ ▼ │ │
|
||
│ ┌───────────┐ │ │
|
||
│ │ HARVEST │─────────────┤ harvest │
|
||
│ └───────────┘ │ │
|
||
│ │ │ │
|
||
│ ├───────────────┐ │ │
|
||
│ ▼ ▼ │ │
|
||
│ ┌───────────┐ ┌─────────┐│ │
|
||
│ │DISTRIBUTE │ │ SEED ││ distribution / seed_saving │
|
||
│ │ │ │ SAVING ││─────────────────────────────────────────│
|
||
│ └───────────┘ └─────────┘│ │
|
||
│ │ │ │ │
|
||
│ ▼ ▼ │ │
|
||
│ ┌───────────┐ ┌─────────┐│ │
|
||
│ │ CONSUMER │ │ SEED ││ consumer_delivery / seed_sharing │
|
||
│ │ DELIVERY │ │ SHARING ││ │
|
||
│ └───────────┘ └─────────┘│ │
|
||
│ │ │ │
|
||
│ └─────┼──→ Next Generation │
|
||
│ │ │
|
||
└────────────────────────────┴─────────────────────────────────────────┘
|
||
```
|
||
|
||
## Best Practices
|
||
|
||
### Recording Events
|
||
|
||
1. **Be Timely** - Record events as they happen
|
||
2. **Be Accurate** - Correct coordinates and weights
|
||
3. **Be Complete** - Include all optional fields when possible
|
||
4. **Verify Locations** - Double-check GPS coordinates
|
||
|
||
### Transport Methods
|
||
|
||
1. **Choose Low Carbon** - Electric and human-powered preferred
|
||
2. **Combine Trips** - Reduce total distance
|
||
3. **Optimize Routes** - Shortest path reduces footprint
|
||
4. **Use Local First** - Minimize distance overall
|
||
|
||
### Quality Assurance
|
||
|
||
1. **Track Conditions** - Temperature, humidity, handling
|
||
2. **Note Issues** - Record any problems immediately
|
||
3. **Grade Honestly** - Accurate quality ratings
|
||
4. **Verify Handoffs** - Confirm custody changes
|
||
|
||
## Next Steps
|
||
|
||
- [Grower Guide](./grower-guide.md) - Complete grower workflow
|
||
- [Consumer Guide](./consumer-guide.md) - Consumer perspective
|
||
- [Vertical Farm Guide](./vertical-farm-guide.md) - Indoor growing
|