# 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.