# Coffee trading - samples and quality Mirror page: [coffee.md](coffee.md) ## BR-PT-COF-001 - Coffee sample phase 1 Status: active Source: project decision on 2026-06-29 ### Business rule Coffee trading must track samples linked to purchase and sale lines. Each sample stores:

• a sample type: offer, pre-shipment, shipment, arrival, stock, customer or retained;
• a purchase or sale direction;
• a lifecycle: requested, received, sent to lab, under review, approved, rejected, expired, archived;
• an expiry date computed from the request/receipt date and the sample shelf life;
• physical quality values and links to cupping sessions.

Coffee compatibility is disabled by default and must be enabled on `purchase_trade.configuration` with the `Active coffee compatibility` field. While the option is disabled, coffee menus and coffee quality pages on lines must not be visible. Cupping results are entered through sessions:

• cupping properties/criteria are configurable;
• a session defines the room cup capacity and the number of cups per sample;
• each sample added to the session generates several blind-coded cups;
• multiple cuppers can enter a result for each cup;
• cuppers see only the origin and coffee type, not the contract or supplier;
• the preparation order proposes arabicas first, blends/other coffees next and robustas at the end of the session;
• the final decision remains global on the session sample: approved, rejected or re-cup.

`purchase.line` and `sale.line` store the target coffee quality specifications: origin, process, variety, crop year, screen size, maximum moisture, maximum defect count and minimum cup score. ### Developer notes

• Models/fields:
  • coffee.sample
  • coffee.cupping.criterion
  • coffee.cupping.session
  • coffee.cupping.session.sample
  • coffee.cupping.cup
  • coffee.cupping.result
  • coffee.cupping.result.line
  • purchase_trade.configuration.active_coffee_compatibility
  • purchase.line.coffee_samples
  • sale.line.coffee_samples
  • coffee_* fields on purchase.line and sale.line
• Files:
  • modules/purchase_trade/coffee.py
  • modules/purchase_trade/coffee.xml
  • modules/purchase_trade/view/coffee_sample_*.xml
  • modules/purchase_trade/view/coffee_cupping_*.xml
  • modules/purchase_trade/view/purchase_line_form.xml
  • modules/purchase_trade/view/sale_line_form.xml
• Caveats:
  • expiry is monitored through the Expired and Expiring soon domains;
  • phase 1 does not block shipment or contract validation;
  • lab delegation is a tracking field, not a complete lab workflow yet;
  • coffee menus are inactive by default and synchronized when the configuration is saved.

## BR-PT-COF-002 - Phase 2 lab delegation Status: active Source: project decision on 2026-06-29 ### Business rule A coffee sample can be delegated to a laboratory. The delegation creates and tracks lab analyses linked to the sample:

• analysis lifecycle: draft, sent, received, accepted, rejected, cancelled;
• request, sent, due and received dates;
• lab report reference;
• physical and organoleptic results: moisture, screen size, defect count and cup score;
• compliance check against the target purchase/sale line thresholds.

The sample `Send to lab` button creates an active lab request when a lab is set and no open analysis already exists. ## BR-PT-COF-003 - Phase 3 consolidated quality decision Status: active Source: project decision on 2026-06-29 ### Business rule The quality decision of a sample is consolidated from:

• the target line quality thresholds;
• the latest non-cancelled lab analysis;
• the average cupping results;
• cupping session decisions, including re-cup and rejected.

The sample exposes a quality status (`pending`, `pass`, `warning`, `fail`) and a recommended decision (`approve`, `re-cup`, `reject`). The `Evaluate quality` button applies the recommendation: approval, rejection or review when the sample must be cupped again. These features remain under `Active coffee compatibility` and do not add a cross-flow blocking rule for non-coffee flows.