171 lines
6.5 KiB
Markdown
171 lines
6.5 KiB
Markdown
<!-- Generated from docs_source/business by docs/tools/render_business_docs.py. -->
|
|
|
|
# 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:
|
|
|
|
<ul style="margin:0.65rem 0 1rem 1.1rem; padding-left:1rem; list-style-type:disc;">
|
|
<li style="margin:0.38rem 0;">a sample type: offer, pre-shipment, shipment, arrival, stock, customer or retained;
|
|
</li>
|
|
<li style="margin:0.38rem 0;">a purchase or sale direction;
|
|
</li>
|
|
<li style="margin:0.38rem 0;">a lifecycle: requested, received, sent to lab, under review, approved, rejected, expired, archived;
|
|
</li>
|
|
<li style="margin:0.38rem 0;">an expiry date computed from the request/receipt date and the sample shelf life;
|
|
</li>
|
|
<li style="margin:0.38rem 0;">physical quality values and links to cupping sessions.
|
|
</li>
|
|
</ul>
|
|
|
|
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:
|
|
|
|
<ul style="margin:0.65rem 0 1rem 1.1rem; padding-left:1rem; list-style-type:disc;">
|
|
<li style="margin:0.38rem 0;">cupping properties/criteria are configurable;
|
|
</li>
|
|
<li style="margin:0.38rem 0;">a session defines the room cup capacity and the number of cups per sample;
|
|
</li>
|
|
<li style="margin:0.38rem 0;">each sample added to the session generates several blind-coded cups;
|
|
</li>
|
|
<li style="margin:0.38rem 0;">multiple cuppers can enter a result for each cup;
|
|
</li>
|
|
<li style="margin:0.38rem 0;">cuppers see only the origin and coffee type, not the contract or supplier;
|
|
</li>
|
|
<li style="margin:0.38rem 0;">the preparation order proposes arabicas first, blends/other coffees next and robustas at the end of the session;
|
|
</li>
|
|
<li style="margin:0.38rem 0;">the final decision remains global on the session sample: approved, rejected or re-cup.
|
|
</li>
|
|
</ul>
|
|
|
|
`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
|
|
|
|
<ul style="margin:0.65rem 0 1rem 1.1rem; padding-left:1rem; list-style-type:disc;">
|
|
<li style="margin:0.38rem 0;">Models/fields:
|
|
<ul style="margin:0.65rem 0 1rem 1.35rem; padding-left:1rem; list-style-type:circle;">
|
|
<li style="margin:0.38rem 0;"><code>coffee.sample</code>
|
|
</li>
|
|
<li style="margin:0.38rem 0;"><code>coffee.cupping.criterion</code>
|
|
</li>
|
|
<li style="margin:0.38rem 0;"><code>coffee.cupping.session</code>
|
|
</li>
|
|
<li style="margin:0.38rem 0;"><code>coffee.cupping.session.sample</code>
|
|
</li>
|
|
<li style="margin:0.38rem 0;"><code>coffee.cupping.cup</code>
|
|
</li>
|
|
<li style="margin:0.38rem 0;"><code>coffee.cupping.result</code>
|
|
</li>
|
|
<li style="margin:0.38rem 0;"><code>coffee.cupping.result.line</code>
|
|
</li>
|
|
<li style="margin:0.38rem 0;"><code>purchase_trade.configuration.active_coffee_compatibility</code>
|
|
</li>
|
|
<li style="margin:0.38rem 0;"><code>purchase.line.coffee_samples</code>
|
|
</li>
|
|
<li style="margin:0.38rem 0;"><code>sale.line.coffee_samples</code>
|
|
</li>
|
|
<li style="margin:0.38rem 0;"><code>coffee_*</code> fields on <code>purchase.line</code> and <code>sale.line</code>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li style="margin:0.38rem 0;">Files:
|
|
<ul style="margin:0.65rem 0 1rem 1.35rem; padding-left:1rem; list-style-type:circle;">
|
|
<li style="margin:0.38rem 0;"><code>modules/purchase_trade/coffee.py</code>
|
|
</li>
|
|
<li style="margin:0.38rem 0;"><code>modules/purchase_trade/coffee.xml</code>
|
|
</li>
|
|
<li style="margin:0.38rem 0;"><code>modules/purchase_trade/view/coffee_sample_*.xml</code>
|
|
</li>
|
|
<li style="margin:0.38rem 0;"><code>modules/purchase_trade/view/coffee_cupping_*.xml</code>
|
|
</li>
|
|
<li style="margin:0.38rem 0;"><code>modules/purchase_trade/view/purchase_line_form.xml</code>
|
|
</li>
|
|
<li style="margin:0.38rem 0;"><code>modules/purchase_trade/view/sale_line_form.xml</code>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li style="margin:0.38rem 0;">Caveats:
|
|
<ul style="margin:0.65rem 0 1rem 1.35rem; padding-left:1rem; list-style-type:circle;">
|
|
<li style="margin:0.38rem 0;">expiry is monitored through the <code>Expired</code> and <code>Expiring soon</code> domains;
|
|
</li>
|
|
<li style="margin:0.38rem 0;">phase 1 does not block shipment or contract validation;
|
|
</li>
|
|
<li style="margin:0.38rem 0;">lab delegation is a tracking field, not a complete lab workflow yet;
|
|
</li>
|
|
<li style="margin:0.38rem 0;">coffee menus are inactive by default and synchronized when the configuration is saved.
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
## 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:
|
|
|
|
<ul style="margin:0.65rem 0 1rem 1.1rem; padding-left:1rem; list-style-type:disc;">
|
|
<li style="margin:0.38rem 0;">analysis lifecycle: draft, sent, received, accepted, rejected, cancelled;
|
|
</li>
|
|
<li style="margin:0.38rem 0;">request, sent, due and received dates;
|
|
</li>
|
|
<li style="margin:0.38rem 0;">lab report reference;
|
|
</li>
|
|
<li style="margin:0.38rem 0;">physical and organoleptic results: moisture, screen size, defect count and cup score;
|
|
</li>
|
|
<li style="margin:0.38rem 0;">compliance check against the target purchase/sale line thresholds.
|
|
</li>
|
|
</ul>
|
|
|
|
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:
|
|
|
|
<ul style="margin:0.65rem 0 1rem 1.1rem; padding-left:1rem; list-style-type:disc;">
|
|
<li style="margin:0.38rem 0;">the target line quality thresholds;
|
|
</li>
|
|
<li style="margin:0.38rem 0;">the latest non-cancelled lab analysis;
|
|
</li>
|
|
<li style="margin:0.38rem 0;">the average cupping results;
|
|
</li>
|
|
<li style="margin:0.38rem 0;">cupping session decisions, including <code>re-cup</code> and <code>rejected</code>.
|
|
</li>
|
|
</ul>
|
|
|
|
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.
|