Key Features

• Farm and Plot Registration — register farms with GPS, soil characteristics, and multiple plots per farmer.
• Crop and Season Management — define crops with expected yields and manage seasonal farming periods (auto-closed by cron).
• Farming Contracts — create contracts linking farmers, farms, crops, and seasons with yield expectations and pricing terms.
• Input Financing — track seeds, fertilizer, and other inputs provided on credit, with automatic loan recovery during settlement.
• Field Monitoring — record field officer visits with crop stage assessments, yield estimates, pest/disease observations, and photo evidence.
• Settlement Integration — automatic input loan deductions and side-selling penalties during commodity settlement calculations.
• Farmer Credit Profiles — auto-computed score, grade and limit; credit gate enforced on contract approval.
• Side-Selling Detection — real-time detection on commodity deliveries with penalty workflow.
• Quarterly Scorecards — five-dimension performance scorecards rebuilt automatically by cron.
• Production Analytics — SQL-based reporting with pivot and graph views for yield analysis, input recovery, and financial performance.

Crops

Define crops that link to existing commodity types:

1. Navigate to :menuselection:`Commodity --> Configuration --> Crops`
2. Click :guilabel:`Create`
3. Enter crop name, code, and link to a commodity type
4. Set expected yield per hectare and harvest cycle days
5. Click :guilabel:`Save`

Seasons

Create seasonal periods for farming contracts:

1. Navigate to :menuselection:`Commodity --> Configuration --> Seasons`
2. Click :guilabel:`Create`
3. Enter season name, dates, and associated crops
4. Click :guilabel:`Activate` when the season begins

Commodity User

Group: grev_od_commodity_base.group_commodity_user

Permissions:

• View all contract farming data (farms, contracts, monitoring, credit, scorecards)

Commodity Officer

Group: grev_od_commodity_base.group_commodity_officer

Permissions:

• Create and manage farms, contracts, monitoring visits and credit profiles
• Mark inputs as delivered and submit monitoring reports
• Confirm or dismiss side-selling events

Commodity Manager

Group: grev_od_commodity_base.group_commodity_manager

Permissions:

• Full access including delete
• Approve and close contracts
• Manage credit suspensions, blacklists and penalty applications
• Configure crops and seasons

Registering a Farm

1. Navigate to :menuselection:`Commodity --> Contract Farming --> Farms`
2. Click :guilabel:`Create`
3. Select the farmer and enter farm details (location, soil type, GPS)
4. Add plots in the :guilabel:`Plots` tab with area and characteristics
5. Click :guilabel:`Save`

Creating a Farming Contract

1. Navigate to :menuselection:`Commodity --> Contract Farming --> Farming Contracts`
2. Click :guilabel:`Create`
3. Select farmer, farm, crop, season, and contracted area
4. Set base price and pricing formula
5. Add input financing lines (seeds, fertilizer, chemicals)
6. Click :guilabel:`Approve` — the credit gate runs and a commodity contract is auto-created
7. Click :guilabel:`Activate` when the contract period begins

Recording Field Visits

1. Navigate to :menuselection:`Commodity --> Contract Farming --> Farm Monitoring`
2. Click :guilabel:`Create`
3. Select the farming contract and record observations:
   • Crop stage (germination through harvest ready)
   • Plant health assessment
   • Pest/disease observations
   • Estimated yield per hectare
   • Weather and soil moisture conditions
   • Photos and recommendations
4. Click :guilabel:`Submit` for review

Managing Farmer Credit

1. Navigate to :menuselection:`Commodity --> Contract Farming --> Farmer Credit`
2. Open or create a credit profile for the farmer
3. Click :guilabel:`Recompute` to refresh the score, grade and recovery rate
4. Use :guilabel:`Apply Suggested Limit` to adopt the auto-computed limit
5. Suspend or blacklist farmers using the dedicated state actions

Reviewing Side-Selling Events

1. Navigate to :menuselection:`Commodity --> Contract Farming --> Side-Selling Events`
2. Filter open events and inspect the linked delivery
3. Confirm, dispute, or dismiss based on investigation
4. Apply a penalty — this creates a deduction line on the next settlement

Input Loan Recovery

When a settlement is calculated for a delivery linked to a farming contract, the system automatically:

1. Identifies the farming contract via the commodity contract
2. Calculates the outstanding input loan balance
3. Creates an "Input Loan Recovery" deduction on the settlement
4. Applies any confirmed side-selling penalties as separate deduction lines
5. Caps the total deduction at the settlement net amount

The farming contract tracks total recovered amounts and recovery percentage in real time.

Models

Scheduled Actions

• Close Expired Seasons — auto-closes seasons past their end date (daily).
• Monitoring Follow-up Alerts — activities for overdue follow-ups (daily).
• Detect Side-Selling — backstop scan over recent deliveries (daily).
• Build Quarterly Scorecards — rebuild farmer scorecards (weekly).

Public APIs

• grev.contract.farming.farmer.credit.check_loan_capacity(partner_id, amount)
• grev.contract.farming.farmer.scorecard._build_scorecard_for_partner(partner_id)

Commodity Modules

• Extends grev.commodity.contract with a farming contract backlink
• Extends grev.commodity.delivery with side-selling detection on done state
• Extends grev.commodity.settlement with input loan and penalty deduction hooks
• Extends grev.commodity.settlement.deduction with input_loan and side_selling_penalty deduction types
• Reuses commodity delivery, quality testing, and payment workflows