From 6f29d4cf860f631c9b5641afd7fe9878108a412a Mon Sep 17 00:00:00 2001 From: "AzureAD\\SylvainDUVERNAY" Date: Sun, 31 May 2026 13:59:02 +0200 Subject: [PATCH] ITSA Workflow --- .../purchase_trade/process_documentation.xml | 6 +- .../practice_book_guideline.md | 212 +++++ .../screen_reference_fees_pricing_mtm.md | 236 +++++ ...creen_reference_logistics_lots_matching.md | 208 +++++ .../screen_reference_party_price_curve.md | 131 +++ ...creen_reference_purchase_sale_contracts.md | 199 ++++ .../ITSA/Interacid_Tradon_Practice_Book.html | 880 ++++++++++++++++++ .../process_documentation/README.md | 11 + 8 files changed, 1880 insertions(+), 3 deletions(-) create mode 100644 modules/purchase_trade/process_documentation/00_document_generation_instructions/practice_book_guideline.md create mode 100644 modules/purchase_trade/process_documentation/07_trade_commodity_management/screen_reference_fees_pricing_mtm.md create mode 100644 modules/purchase_trade/process_documentation/07_trade_commodity_management/screen_reference_logistics_lots_matching.md create mode 100644 modules/purchase_trade/process_documentation/07_trade_commodity_management/screen_reference_party_price_curve.md create mode 100644 modules/purchase_trade/process_documentation/07_trade_commodity_management/screen_reference_purchase_sale_contracts.md create mode 100644 modules/purchase_trade/process_documentation/ITSA/Interacid_Tradon_Practice_Book.html diff --git a/modules/purchase_trade/process_documentation.xml b/modules/purchase_trade/process_documentation.xml index e8714df..3652c8b 100644 --- a/modules/purchase_trade/process_documentation.xml +++ b/modules/purchase_trade/process_documentation.xml @@ -20,10 +20,10 @@ this repository contains the full copyright notices and license terms. --> - ITSA Operations Workflow + Interacid Practice Book purchase_trade.process.documentation id="menu_tradon_processes"/> The two reference books deliberately **share section 1 verbatim**. Keep this discipline: +> write the fundamentals once per client and paste identically into each book so staff get +> the same grounding regardless of which manual they open. + +--- + +## 3. Content building blocks (the repeatable units) + +### 3.1 Field-reference table +Used for every data-entry screen. The leading number ties each row to a numbered red +callout on the adjacent screenshot. + +``` +| # | Attribute | Description | +| - | --------- | ----------- | +| 1 | | What it is, how it is used, who fills it, defaulting rules, worked example | +``` + +Rules: +- Descriptions are **operational**, not just definitional — say *who* enters it, *when*, *why*, and any calculation. Long cells with embedded examples are normal and expected. +- Use a `???` / `@vendor: to complete` placeholder for fields not yet finalised rather than omitting the row. +- Keep field labels in **bold** when referenced in prose. + +### 3.2 Step sequence +Process actions as a bulleted list, in execution order, each meaningful step followed by a +screenshot: + +``` +- Trader clicks **Insert** … [screenshot] +- A new window opens; enter the line details [field-reference table] +- Click **Save** — system allocates the number (e.g. PC- / SC- prefix) +``` + +### 3.3 Annotated screenshot +The dominant visual. Conventions to reproduce: +- Real captures of the *configured* system populated with the client's data. +- **Numbered red circular callouts** placed on the fields, matching `#` in the field table. +- Placed immediately after the prose/table that describes them, never front-loaded. +- For exception flows, before/after captures. + +### 3.4 Notes, examples, open items +- **Note / Important Note:** bolded inline callouts for rules, warnings, responsibilities. +- *Italic worked examples* with concrete numbers (e.g. freight 4500 USD ÷ 19.2 MT = 234.38 USD/MT). +- `[@vendor: …]` inline tags for open questions, bugs, or future enhancements — kept visible in the draft. +- Footnotes (`[^n]`) for edge cases that would interrupt the main flow. + +### 3.5 Worked-calculation block +For any computed value (freight, finance, insurance, FX), show the **formula then a fully +numeric example**: + +``` +Finance cost = Principal × Rate × Days / 365 + = 87 848.77 × 2.0% × 60 / 365 = 288.82 USD +``` + +--- + +## 4. Formatting & style conventions + +| Element | Convention | +|---------|-----------| +| Field / column names | **Bold** | +| Buttons / actions | **Bold** (e.g. click **Save**, **Insert**, **Allocate**) | +| Worked examples | *Italic*, with real numbers | +| System term being defined | **Bold** on first use | +| Open questions / vendor actions | `[@vendor: …]` inline, left in the text | +| Edge cases | Footnotes | +| Process / status names | Capitalised exactly as in the system (In-Transit, Spot, In-Store) | +| Headings | H1 = chapter, H2 = process, H3/H4 = sub-process or scenario variant | +| Voice | Future/target tense ("we will create…", "the Trader will enter…") | + +Keep the **client's real master data** in every example: company/location names, +commodities, ports, incoterms, banks, grades, packaging (e.g. 69 kg bags). This grounding +is what makes the book usable and is the single most important thing to localise. + +--- + +## 5. How to adapt for a new customer / commodity / workflow + +> **INSTRUCTION — ask before generating.** Before producing a new Practice Book, do **not** +> assume answers from the reference documents. First **ask the customer the questions +> below and wait for their answers.** Only once the answers are provided should the output +> document be generated. Pose the questions grouped as listed; where a question has a small +> fixed set of choices, offer them as selectable options, otherwise ask for free text. + +**Questions to ask the customer:** + +1. **Glossary entities.** What are the company/location name(s), the commodity set being + traded (e.g. coffee, cocoa, cotton, sugar, grains, iron ore, steel, copper, aluminium, + zinc/lead), and the line-of-business dimension? Are there any agreed structural limits + (e.g. maximum number of contract sequences/lines)? + +2. **Pricing types.** Which pricing types does the client use — *Priced*, *Basis + (differential)*, *formula-priced*, or a combination? Which underlying markets and terms + apply (e.g. ICE, LME, SHFE, GAFTA/FOSFA references)? + +3. **Cost matrix & route logic.** What are the real incoterms, typical loading and + destination places, and the cost types to budget (e.g. freight, insurance, finance, + fumigation, inland, demurrage)? Which costs are auto-calculated vs. manually entered? + +4. **Logistics flows in scope.** Which flows apply — Inbound (origin → warehouse), + Outbound (warehouse → buyer), Drop Ship (direct), Transfer (location to location)? Are + the goods bagged or bulk (affecting packaging, weights, draft survey, moisture/outturn), + and is tolerance/franchise handling required for the commodity family? + +5. **Hedging & FX scope.** What should the book cover — *physical only (no hedging/FX)*, + *futures hedging only*, *futures + FX hedging*, or *FX only*? Front-office and physical + mechanics must be kept in clearly separate chapters. + +6. **Worked scenarios.** Which dimensions matter for this client's scenario variants + (e.g. location, commodity, contract type, packaging, exception type)? Which exception + flows must be covered (rejections, claims, transhipment …) and which are out of + scope / later phase? + +7. **Screenshots.** Will annotated screenshots be supplied from the client's configured + environment, or should the document leave numbered placeholders for them? (Never reuse + another client's captures.) + +8. **Target ERP.** Which ERP is the target — Tryton, iRely, or another system? If it + differs from the reference (iRely), provide the equivalent term/model mapping (e.g. + Tryton models, wizards, states) so iRely-specific terms (Voucher, Sequence, Blotter) + can be replaced. The pedagogical structure — fundamentals, field tables, illustrated + steps, worked scenarios — is ERP-agnostic and must be preserved regardless. + +--- + +## 6. Quality bar (acceptance criteria) + +A generated Practice Book is "done" when: +- A new staff member could execute each process end-to-end using only the book. +- Every data-entry screen has a matching numbered field table + annotated screenshot. +- Every computed figure shows its formula and a numeric worked example. +- All examples use the client's real master data. +- Open items are visibly tagged, not silently dropped. +- The fundamentals chapter is identical across the client's set of books. +- Scope boundaries (what is in / out / later phase) are stated explicitly. diff --git a/modules/purchase_trade/process_documentation/07_trade_commodity_management/screen_reference_fees_pricing_mtm.md b/modules/purchase_trade/process_documentation/07_trade_commodity_management/screen_reference_fees_pricing_mtm.md new file mode 100644 index 0000000..b332c9b --- /dev/null +++ b/modules/purchase_trade/process_documentation/07_trade_commodity_management/screen_reference_fees_pricing_mtm.md @@ -0,0 +1,236 @@ +# Screen reference - Fees, pricing and MTM + +Parent process: Trade & Commodity Management + +Source screens and models reviewed: + +- `modules/purchase_trade/view/fee_form.xml` +- `modules/purchase_trade/view/component_form.xml` +- `modules/purchase_trade/view/component_form2.xml` +- `modules/purchase_trade/view/pricing_form.xml` +- `modules/purchase_trade/view/trigger_form.xml` +- `modules/purchase_trade/view/period_form.xml` +- `modules/purchase_trade/view/mtm_strategy_form.xml` +- `modules/purchase_trade/view/mtm_scenario_form.xml` +- `modules/purchase_trade/view/price_matrix_form.xml` +- `modules/purchase_trade/fee.py` +- `modules/purchase_trade/pricing.py` + +Database note: table names below follow the Tryton convention of replacing dots with underscores. + +## Fees on contract lines or shipments + +Model: `fee.fee` +Table: `fee_fee` +Main view: `fee_form` + +The compact `fee_form` currently displays `type`, `product`, lot links and lot count. The model also contains the full calculation fields used by tree views and automatic amount computation. + +| Field | Required | Usage | +| --- | --- | --- | +| `line` | No | Purchase line that owns the fee. | +| `sale_line` | No | Sale line that owns the fee. This field is added by the sale extension of `fee.fee`. | +| `shipment_in` | No | Inbound shipment that owns the fee. | +| `shipment_out` | No | Outbound shipment that owns the fee. | +| `shipment_internal` | No | Internal shipment that owns the fee. | +| `supplier` | Yes | Fee supplier/vendor. | +| `type` | Yes | Fee state: budgeted, ordered or actual. | +| `p_r` | Yes | Pay/receive indicator: `PAY` or `REC`. | +| `product` | Yes | Service product being charged. Domain restricts to service products. | +| `currency` | No | Fee currency. | +| `price` | No | Unit price, percentage, rate or lump-sum value depending on `mode`. | +| `mode` | Yes | Calculation mode: lump sum, per quantity, percent of price/rate/cost, or per packing. | +| `auto_calculation` | No | Automatically calculates packing quantity when mode is `ppack`. | +| `inherit_qt` | No | Indicates quantity is inherited, enabled mainly for packing mode. | +| `quantity` | No | Quantity used for calculation; read-only outside packing/manual contexts. | +| `unit` | No | Unit for quantity or packing calculation. | +| `packing_category` | Computed | Packing UoM category used to restrict `unit`. | +| `inherit_shipment` | No | Links the fee to shipment quantities when applicable. | +| `purchase` | No | Purchase header link for fee aggregation. | +| `qt_state` | No | Quantity state used for calculation, defaulting to `BL` when available. | +| `amount` | Computed | Calculated fee amount. | +| `fee_lots` | Computed | Eligible lots for the fee. | +| `lots` | No | Lots explicitly linked through `fee.lots`. | +| `lots_cp` | No | Count of linked lots. | +| `state` | Read-only | Invoice status: not invoiced or invoiced. | +| `fee_landed_cost` | Computed | Indicates whether the fee is posted to inventory/landed cost. | +| `inv` | Computed | Invoice linked to the fee. | +| `weight_type` | No | Net or gross weight basis for calculation. | +| `fee_date` | No | Fee date; defaults to current date. | + +### Fee lots + +Model: `fee.lots` +Table: `fee_lots` + +| Field | Required | Usage | +| --- | --- | --- | +| `fee` | Yes | Fee being allocated. | +| `lot` | Yes | Lot receiving the fee allocation. | + +## Pricing component + +Model: `pricing.component` +Table: `pricing_component` +Views: `component_form`, `component_form2` + +Components define how a contract line or MTM strategy gets market prices. + +| Field | Required | Usage | +| --- | --- | --- | +| `strategy` | No | MTM strategy that owns the component when used in MTM setup. | +| `price_source_type` | Yes | Price source: curve or matrix. | +| `fix_type` | No | Fixation type, such as official quotation or settlement. | +| `ratio` | No | Percentage weight applied to the component. | +| `price_index` | No | Price curve (`price.price`) used when source type is curve. | +| `price_matrix` | No | Price matrix used when source type is matrix. | +| `currency` | Computed | Currency derived from the selected curve. | +| `auto` | No | Marks component as automatically generated or updated. | +| `fallback` | No | Allows fallback pricing logic. | +| `calendar` | No | Price calendar used for valid quotation dates. | +| `nbdays` | Computed | Number of quotation/application days from period rules. | +| `pricing_date` | No | Maximum pricing date. | +| `triggers` | No | Period rules defining the quotation window and application window. | + +## Pricing fixing records + +Model: `pricing.pricing` +Table: `pricing_pricing` +View: `pricing_form` + +| Field | Required | Usage | +| --- | --- | --- | +| `pricing_date` | No | Date of the market price/fixing. | +| `price_component` | No | Component being fixed. | +| `quantity` | No | Quantity fixed on this date. Default `0`. | +| `settl_price` | No | Settlement/fixing price for the date. Default `0`. | +| `fixed_qt` | Read-only | Cumulative fixed quantity at this row. | +| `fixed_qt_price` | Read-only | Weighted average price of fixed quantity. | +| `unfixed_qt` | Read-only | Remaining unfixed quantity. | +| `unfixed_qt_price` | Read-only | Price assigned to unfixed quantity. | +| `eod_price` | Read-only | End-of-day price. | +| `last` | No | Use last available quotation when applicable. | + +## Pricing period rules + +Model: `pricing.trigger` +Table: `pricing_trigger` +View: `trigger_form` + +| Field | Required | Usage | +| --- | --- | --- | +| `component` | No | Parent pricing component. | +| `pricing_period` | No | Named period rule for quotation dates. | +| `from_p` | No | Manual pricing window start, read-only when `pricing_period` is selected. | +| `to_p` | No | Manual pricing window end, read-only when `pricing_period` is selected. | +| `average` | No | Average quotations in the pricing window. | +| `last` | No | Use last available price. | +| `application_period` | No | Named period rule for applying the price. Defaults from `pricing_period` when empty. | +| `from_a` | No | Manual application window start. | +| `to_a` | No | Manual application window end. | + +Model: `pricing.period` +Table: `pricing_period` +View: `period_form` + +| Field | Required | Usage | +| --- | --- | --- | +| `name` | No | Period rule name. | +| `trigger` | No | Business trigger used to anchor the date calculation. | +| `include` | No | Includes the trigger date in generated date lists. | +| `every` | No | Weekday selection for generated quotation dates. | +| `nb_quotation` | No | Number of quotations. | +| `startday` | No | Start-day offset type. | +| `nbds` | No | Number of start-day offsets. Default `0`. | +| `nbms` | No | Starting month offset. Default `0`. | +| `endday` | No | End-day offset type. | +| `nbde` | No | Number of end-day offsets. Default `0`. | +| `nbme` | No | Ending month offset. Default `0`. | + +## MTM scenario and strategy + +Model: `mtm.scenario` +Table: `mtm_scenario` +View: `mtm_scenario_form` + +| Field | Required | Usage | +| --- | --- | --- | +| `name` | Yes | Scenario name. | +| `valuation_date` | Yes | Date used to value market prices. | +| `use_last_price` | No | Allows valuation to use the last available curve price. | +| `calendar` | No | Calendar used to determine valid quotation dates. | + +Model: `mtm.strategy` +Table: `mtm_strategy` +View: `mtm_strategy_form` + +| Field | Required | Usage | +| --- | --- | --- | +| `name` | Yes | Strategy name. | +| `scenario` | Yes | Scenario used for valuation. | +| `currency` | No | Valuation currency. | +| `active` | No | Strategy is active; default `True`. | +| `components` | No | Pricing components used to calculate MTM. | + +Model: `mtm.component` +Table: `mtm_component` + +| Field | Required | Usage | +| --- | --- | --- | +| `strategy` | Yes | Parent MTM strategy. | +| `name` | Yes | Component label. | +| `component_type` | Yes | Commodity, freight, quality, FX, storage or other. | +| `fix_type` | No | Fixation type. | +| `price_source_type` | Yes | Curve, matrix or manual source. | +| `price_index` | No | Price curve used for curve source. | +| `price_matrix` | No | Matrix used for matrix source. | +| `ratio` | No | Percentage applied to the source price. | +| `manual_price` | No | Manual price when source type is manual. | +| `currency` | No | Component currency derived from curve or matrix where possible. | + +## Price matrix + +Model: `price.matrix` +Table: `price_matrix` +View: `price_matrix_form` + +| Field | Required | Usage | +| --- | --- | --- | +| `name` | Yes | Matrix name. | +| `matrix_type` | Yes | Freight, location spread, quality, storage or other. | +| `unit` | No | Unit for matrix values. | +| `currency` | No | Matrix currency. | +| `calendar` | No | Calendar for matrix validity. | +| `valid_from` | No | Validity start date. | +| `valid_to` | No | Validity end date. | +| `lines` | No | Matrix rows. | + +Model: `price.matrix.line` +Table: `price_matrix_line` + +| Field | Required | Usage | +| --- | --- | --- | +| `matrix` | Yes | Parent matrix. | +| `origin` | No | Origin location used for lookup. | +| `destination` | No | Destination location used for lookup. | +| `product` | No | Product criterion. | +| `quality` | No | Product category/quality criterion. | +| `price_value` | No | Matrix price value. | + +## Related tables + +| Model | PostgreSQL table | Purpose | +| --- | --- | --- | +| `fee.fee` | `fee_fee` | Fees on purchase lines, sale lines or shipments. | +| `fee.lots` | `fee_lots` | Fee-to-lot allocation. | +| `pricing.component` | `pricing_component` | Price curve/matrix components. | +| `pricing.pricing` | `pricing_pricing` | Pricing/fixing records. | +| `pricing.trigger` | `pricing_trigger` | Pricing and application period windows. | +| `pricing.period` | `pricing_period` | Reusable period rules. | +| `mtm.scenario` | `mtm_scenario` | MTM valuation scenario. | +| `mtm.strategy` | `mtm_strategy` | MTM strategy. | +| `mtm.component` | `mtm_component` | MTM component definition. | +| `mtm.snapshot` | `mtm_snapshot` | Stored MTM valuation snapshots. | +| `price.matrix` | `price_matrix` | Matrix header. | +| `price.matrix.line` | `price_matrix_line` | Matrix lookup lines. | + diff --git a/modules/purchase_trade/process_documentation/07_trade_commodity_management/screen_reference_logistics_lots_matching.md b/modules/purchase_trade/process_documentation/07_trade_commodity_management/screen_reference_logistics_lots_matching.md new file mode 100644 index 0000000..de227a9 --- /dev/null +++ b/modules/purchase_trade/process_documentation/07_trade_commodity_management/screen_reference_logistics_lots_matching.md @@ -0,0 +1,208 @@ +# Screen reference - Shipments, physical lots and matching + +Parent process: Trade & Commodity Management + +Source screens and models reviewed: + +- `modules/purchase_trade/view/shipment_in_form.xml` +- `modules/purchase_trade/view/shipment_out_form.xml` +- `modules/purchase_trade/view/shipment_internal_form.xml` +- `modules/purchase_trade/view/lot_add_start_form.xml` +- `modules/purchase_trade/view/lot_matching_start_form.xml` +- `modules/purchase_trade/stock.py` +- `modules/purchase_trade/lot.py` + +Database note: models with `PoolMeta` extend existing Tryton tables. The most important tables are `stock_shipment_in`, `stock_shipment_out`, `stock_shipment_internal`, `stock_shipment_container`, `lot_lot` and `lot_qt`. Wizard-only screens such as matching and adding physical lots use transient `ModelView` records and do not create stable business tables by themselves. + +## Inbound shipment + +Model: `stock.shipment.in` +Table: `stock_shipment_in` +Main view extension: `shipment_in_form` + +### Header and logistics fields + +| Field | Required | Usage | +| --- | --- | --- | +| `carrier_` | No | Carrier party used for transport execution. | +| `from_location` | No | Loading/origin location. | +| `to_location` | No | Destination location; replaces the base warehouse display. | +| `transport_type` | No | Transport mode: vessel, truck or other. | +| `vessel` | No | Vessel master reference. | +| `vessel_type` | Computed | Vessel type derived from selected vessel. | +| `cargo_mode` | Yes | Shipment mode: bulk or container. | +| `del_from` | No | Delivery period start date. | +| `del_to` | No | Delivery period end date. | +| `bl_number` | No | Bill of lading number. | +| `bl_date` | No | Bill of lading date. | +| `travel_nb` | No | Voyage/travel number. | +| `eta` | No | Estimated loading/POL date shown by the form. | +| `etd` | No | Estimated departure/discharge date, depending on context. | +| `etad` | No | Estimated arrival at destination. | +| `receive_date` | No | Actual reception date. | +| `receive_nb` | No | Reception reference number. | +| `info` | Computed | HTML vessel information. | +| `carte` | Computed | HTML map/IMO output for the vessel. | + +### Tabs + +| Tab | Field/model | Usage | +| --- | --- | --- | +| `Lots` | `lotqt` / `lot.qt` | Executed quantities/lots loaded or received on the shipment. | +| `Fees` | `fees` / `fee.fee` | Shipment-level freight, control or logistics charges. | +| `Estimated dates` | `pricing.estimated` | Estimated dates available to pricing rules. | +| `Shipping Infos` | `booking`, `ref`, `booking_date`, `agent`, `note` | Booking reference and free-text shipping notes. | +| `Container` | `stock.shipment.container` | Container equipment and seal information. | +| `Demurrage` | `sof.statement` | Statement of facts and demurrage calculation. | +| `Weight Report` | `shipment.wr`, controller fields | Controller instructions and linked weight reports. | + +## Outbound shipment + +Model: `stock.shipment.out` +Table: `stock_shipment_out` +Main view extension: `shipment_out_form` + +| Field | Required | Usage | +| --- | --- | --- | +| `from_location` | No | Origin/loading location. | +| `to_location` | No | Customer or discharge location. | +| `transport_type` | No | Transport mode; default `vessel`. | +| `vessel` | No | Vessel reference. | +| `fees` | No | Sale shipment fees. | +| `lotqt` | No | Lot quantity records linked to the shipment. | +| `quantity` | Computed | Sum of incoming move quantities. | +| `unit` | Computed | Unit from the first incoming move. | +| `etl`, `eta`, `etd`, `unloaded` | No | Estimated and actual logistics milestones. | +| `booking` | No | Booking reference. | +| `ref` | No | Internal shipment reference. | +| `note` | No | Free-text logistics notes. | + +## Internal shipment + +Model: `stock.shipment.internal` +Table: `stock_shipment_internal` +Main view extension: `shipment_internal_form` + +| Field | Required | Usage | +| --- | --- | --- | +| `fees` | No | Fees attached to the internal movement. | + +The rest of the internal shipment form is inherited from the base stock module. + +## Shipment containers + +Model: `stock.shipment.container` +Table: `stock_shipment_container` + +| Field | Required | Usage | +| --- | --- | --- | +| `shipment` | Yes | Parent inbound shipment. | +| `container_type` | Yes | Container type/equipment. | +| `container_no` | No | Container number. | +| `quantity` | Yes | Number of containers of this type. | +| `seal_no` | No | Seal number. | +| `is_reefer` | No | Marks refrigerated equipment. | + +## Add physical lots + +Wizard: `lot.add` +Start model: `lot.add.lot` +Line model: `lot.add.line` +Action: `Add physical lots` from `lot.report` + +This screen creates physical lot lines from available quantity on an inbound, outbound or internal shipment selection. + +### Header fields + +| Field | Required | Usage | +| --- | --- | --- | +| `quantity` | Read-only | Available quantity to split into physical lots. | +| `unit` | Read-only | Unit for the available quantity. | +| `shipment_in` | No | Inbound shipment being split; visible only when present. | +| `shipment_internal` | No | Internal shipment being split; visible only when present. | +| `shipment_out` | No | Outbound shipment being split; visible only when present. | +| `lots` | No | Editable split lines. | + +### Lot line fields + +| Field | Required | Usage | +| --- | --- | --- | +| `lot_qt` | No | Quantity for the split line. | +| `lot_unit` | Yes | Unit for the split quantity. | +| `lot_quantity` | No | Net weight of the physical lot. | +| `lot_gross_quantity` | No | Gross weight of the physical lot. | +| `lot_unit_line` | Yes | Commercial line unit used for contract valuation. | +| `lot_premium` | No | Premium or discount carried by the physical lot. | +| `lot_chunk_key` | No | Chunk key used to group or trace imported/split lots. | + +## Matching purchase and sale lots + +Wizard: `lot.matching` +Start model: `lot.matching.start` +Line model: `lot.matching.lot` +Action: `Apply matching` from `lot.report` + +The matching wizard compares available purchase-side and sale-side quantities and lets the user enter the quantity to match. + +### Matching header fields + +| Field | Required | Usage | +| --- | --- | --- | +| `purchase` | No | Restricts purchase-side lots to one purchase contract. | +| `sale` | No | Restricts sale-side lots to one sale contract. | +| `qt_type` | No | Quantity type filter: open, physical or all. Default `all`. | +| `lot_p` | No | Purchase lot candidates populated from `lot.qt` query output. | +| `tot_p` | Computed | Sum of purchase quantities entered in `lot_matched_qt`. | +| `lot_s` | No | Sale lot candidates populated from `lot.qt` query output. | +| `tot_s` | Computed | Sum of sale quantities entered in `lot_matched_qt`. | + +### Filter fields + +| Field | Required | Usage | +| --- | --- | --- | +| `product_p` | No | Purchase product filter. | +| `location_p` | No | Purchase destination filter. | +| `cp_p` | No | Supplier filter. | +| `inc_p` | No | Purchase Incoterm filter. | +| `product_s` | No | Sale product filter. | +| `location_s` | No | Sale loading/location filter. | +| `cp_s` | No | Client filter. | +| `inc_s` | No | Sale Incoterm filter. | + +### Matching line fields + +| Field | Required | Usage | +| --- | --- | --- | +| `lot_id` | No | Physical or virtual lot selected for matching. | +| `lot_r_id` | No | Source `lot.qt` quantity record. | +| `lot_purchase` | No | Purchase contract linked to the candidate. | +| `lot_sale` | No | Sale contract linked to the candidate. | +| `lot_name` | Read-only | Display lot name. | +| `lot_type` | No | Quantity type: open, physical or loss. | +| `lot_shipment_in` | No | Inbound shipment context. | +| `lot_shipment_internal` | No | Internal shipment context. | +| `lot_shipment_out` | No | Outbound shipment context. | +| `lot_product` | Read-only | Product carried by the lot. | +| `lot_quantity` | Read-only | Available quantity. Sale rows are shown as positive matching candidates after sign handling. | +| `lot_unit` | Read-only | Unit of the displayed quantity. | +| `lot_matched_qt` | No | Quantity the user wants to match. | +| `lot_cp` | No | Supplier or client counterparty. | +| `lot_shipment_origin` | Computed | Reference to inbound, outbound or internal shipment. | + +## Related tables + +| Model | PostgreSQL table | Purpose | +| --- | --- | --- | +| `stock.shipment.in` | `stock_shipment_in` | Inbound shipment header. | +| `stock.shipment.out` | `stock_shipment_out` | Outbound shipment header. | +| `stock.shipment.internal` | `stock_shipment_internal` | Internal transfer header. | +| `stock.shipment.container` | `stock_shipment_container` | Shipment container details. | +| `shipment.wr` | `shipment_wr` | Link between shipment and weight report. | +| `sof.statement` | `sof_statement` | Statement of facts/demurrage record. | +| `lot.lot` | `lot_lot` | Lot master and purchase_trade extensions. | +| `lot.qt` | `lot_qt` | Lot quantity state records used for available/open/matched quantities. | +| `lot.add.lot` | transient | Add-lot wizard header; no persistent business table. | +| `lot.add.line` | transient | Add-lot wizard split line; no persistent business table. | +| `lot.matching.start` | transient | Matching wizard header; no persistent business table. | +| `lot.matching.lot` | transient | Matching wizard candidate line; no persistent business table. | + diff --git a/modules/purchase_trade/process_documentation/07_trade_commodity_management/screen_reference_party_price_curve.md b/modules/purchase_trade/process_documentation/07_trade_commodity_management/screen_reference_party_price_curve.md new file mode 100644 index 0000000..65f5699 --- /dev/null +++ b/modules/purchase_trade/process_documentation/07_trade_commodity_management/screen_reference_party_price_curve.md @@ -0,0 +1,131 @@ +# Screen reference - Party and price curve master data + +Parent process: Trade & Commodity Management + +Source screens and models reviewed: + +- `modules/purchase_trade/view/party_form.xml` +- `modules/purchase_trade/view/party_exec_sla_form.xml` +- `modules/purchase_trade/view/party_exec_place_tree.xml` +- `modules/purchase_trade/party.py` +- `modules/price/view/price_form.xml` +- `modules/price/price.py` +- `modules/price/price_value.py` + +Database note: `party.party` and `price.price` are shared master data models. The party fields listed here are the `purchase_trade` extensions on top of the base party screen. Price curves live in the `price` module but are consumed by `purchase_trade` pricing, derivatives and MTM. + +## Party contract and execution data + +Model: `party.party` +Table: `party_party` +Main view extension: `party_form` + +### Contract tab + +| Field | Required | Usage | +| --- | --- | --- | +| `tol_min` | No | Default negative tolerance percentage for contracts involving the party. | +| `tol_max` | No | Default positive tolerance percentage for contracts involving the party. | +| `wb` | No | Default weight basis for contracts involving the party. | +| `association` | No | Default trade association/rule set for the party. | +| `origin` | No | Default product or geographic origin. | +| `initial` | No | Party initials used for internal references or reporting. | + +### Execution tab + +| Field | Required | Usage | +| --- | --- | --- | +| `sla` | No | Service-level agreement records for locations/costs. | +| `execution` | No | Execution target records by area. | + +## Party execution target + +Model: `party.execution` +Table: `party_execution` + +| Field | Required | Usage | +| --- | --- | --- | +| `party` | No | Parent party. | +| `area` | No | Country/region area. | +| `percent` | No | Target percentage for execution allocation. | +| `achieved_percent` | Computed | Achieved percentage. Current implementation returns a placeholder value. | + +## Party execution SLA + +Model: `party.execution.sla` +Table: `party_execution_sla` + +| Field | Required | Usage | +| --- | --- | --- | +| `party` | No | Parent party. | +| `reference` | No | SLA reference. | +| `product` | No | Product covered by the SLA. | +| `date_from` | No | SLA validity start date. | +| `date_to` | No | SLA validity end date. | +| `places` | No | Location-specific SLA costs. | + +Model: `party.execution.place` +Table: `party_execution_place` + +| Field | Required | Usage | +| --- | --- | --- | +| `pes` | No | Parent SLA record. | +| `location` | No | Location where the SLA cost applies. | +| `cost` | No | Cost value for the location. | +| `mode` | Yes | Cost calculation mode: lump sum, per quantity, percentage or per packing. | +| `currency` | No | Currency for the SLA cost. | +| `unit` | No | Unit for packing mode. | + +## Price curve + +Model: `price.price` +Table: `price_price` +Main view: `price_form` + +Price curves are selected in `pricing.component.price_index`, `mtm.component.price_index` and derivative records. The curve provides quotation values, units, currency conversion and contract-size calculations. + +| Field | Required | Usage | +| --- | --- | --- | +| `price` | No | Composite parent curve when the curve is built from other curves. | +| `price_index` | Yes | Curve/index code, used as the record name. | +| `price_desc` | Yes | Human-readable curve description. | +| `price_period` | No | Product month/period attached to the curve. | +| `price_curve_type` | No | Spot, future or composite curve type. | +| `price_type` | No | Fixation type. | +| `price_unit` | No | Unit in which quotations are expressed. | +| `price_currency` | No | Currency in which quotations are expressed. | +| `price_area` | No | Market area. | +| `price_calendar` | No | Quotation calendar. | +| `price_values` | No | Historical or future quotation values. | +| `price_composite` | No | Components of a composite curve. | +| `price_product` | No | Products linked to the curve. | +| `price_ct_size` | No | Contract size for derivative and amount calculations. | + +## Price values + +Model: `price.price_value` +Table: `price_price_value` + +| Field | Required | Usage | +| --- | --- | --- | +| `price` | Yes | Parent price curve. | +| `price_index` | Computed | Display of the parent curve index. | +| `price_date` | No | Quotation date. The model validates uniqueness by curve/date when both are present. | +| `price_value` | No | Settlement or reference quotation value. | +| `open_price` | No | Open price for the date. | +| `low_price` | No | Low price for the date. | +| `high_price` | No | High price for the date. | + +## Related tables + +| Model | PostgreSQL table | Purpose | +| --- | --- | --- | +| `party.party` | `party_party` | Shared party master data plus purchase_trade contract defaults. | +| `party.execution` | `party_execution` | Execution target by area. | +| `party.execution.sla` | `party_execution_sla` | Party SLA header. | +| `party.execution.place` | `party_execution_place` | SLA location/cost details. | +| `price.price` | `price_price` | Price curve/index master. | +| `price.price_value` | `price_price_value` | Curve quotation values. | +| `price.calendar` | `price_calendar` | Quotation calendar used by curves and pricing rules. | +| `price.fixtype` | `price_fixtype` | Fixation type reference. | + diff --git a/modules/purchase_trade/process_documentation/07_trade_commodity_management/screen_reference_purchase_sale_contracts.md b/modules/purchase_trade/process_documentation/07_trade_commodity_management/screen_reference_purchase_sale_contracts.md new file mode 100644 index 0000000..39ebc4b --- /dev/null +++ b/modules/purchase_trade/process_documentation/07_trade_commodity_management/screen_reference_purchase_sale_contracts.md @@ -0,0 +1,199 @@ +# Screen reference - Purchase and sale contracts + +Parent process: Trade & Commodity Management + +Source screens and models reviewed: + +- `modules/purchase_trade/view/purchase_form.xml` +- `modules/purchase_trade/view/purchase_line_form.xml` +- `modules/purchase_trade/view/sale_form.xml` +- `modules/purchase_trade/view/sale_line_form.xml` +- `modules/purchase_trade/purchase.py` +- `modules/purchase_trade/sale.py` + +Database note: Tryton model names normally map to PostgreSQL table names by replacing dots with underscores. Contract headers write to `purchase_purchase` and `sale_sale`; contract lines write to `purchase_line` and `sale_line`. These models extend base Tryton purchase/sale screens, so this document focuses on the fields added or materially used by `purchase_trade`. + +## Purchase contract + +Model: `purchase.purchase` +Table: `purchase_purchase` +Main view extension: `purchase_form` + +### Header fields + +| Field | Required | Usage | +| --- | --- | --- | +| `lc_date` | No | Letter of credit date used for contract documentation and trade finance follow-up. | +| `wb` | Yes | Weight basis applied to the contract; defaulted from the first `purchase.weight.basis` record. | +| `certif` | Yes | Certification attached to the contract; hidden for company `MELYA` by `company_visible`. | +| `broker` | No | Broker party for the contract. Domain restricts to broker-related categories. | +| `operator` | No | Operational owner responsible for execution follow-up. | +| `trader` | No | Trader responsible for the commercial position. | +| `our_reference` | No | Internal reference displayed on the contract. | +| `association` | Yes | Trade association or rule set linked to the contract; hidden for company `MELYA`. | +| `crop` | No | Crop/campaign information for commodity contracts. | +| `tol_min` | Yes | Negative quantity tolerance percentage; default `0`. | +| `tol_max` | Yes | Positive quantity tolerance percentage; default `0`. | +| `from_location` | Yes | Origin/loading location. Supplier locations are allowed; customer locations are excluded. | +| `to_location` | Yes | Destination/discharge location. Customer locations are allowed; supplier locations are excluded. | +| `incoterm` | Inherited | Delivery term from the base purchase model, shown in the trade header. | +| `incoterm_location` | Inherited | Named place for the Incoterm. | +| `product_origin` | No | Free-text origin statement for reports or documentation. | +| `bank_account` | No | Bank account selected from the supplier bank accounts, defaulted by currency when possible. | +| `doc_template` | No | Document template used to populate required contract documents. | +| `required_documents` | No | Required document types for the contract. | +| `analytic_dimensions` | No | Analytic allocation dimensions attached to the contract. | + +### Header tabs + +| Tab | Field/model | Usage | +| --- | --- | --- | +| `Derivative` | `derivatives` / `derivative.derivative` | Paper hedge or derivative records linked to the purchase. | +| `Pnl` | `pnl_`, `pnl` | Contract valuation lines or grouped dynamic P&L. | +| `Forex` | `forex.cover.physical.contract` | FX covers linked to the physical purchase. | +| `Execution plan` | `plan` | Execution workflow plan reference. | +| `Estimated dates` | `pricing.estimated` | Estimated dates used by pricing period rules. | +| `Required documents` | `contract.document.type` | Document checklist generated manually or from a template. | +| `Dimensions` | `analytic.dimension.assignment` | Analytic dimensions for reporting and control. | + +## Purchase contract line + +Model: `purchase.line` +Table: `purchase_line` +Main view extension: `purchase_line_form` + +### Line fields + +| Field | Required | Usage | +| --- | --- | --- | +| `quantity_theorical` | No | Contractual quantity reference, distinct from executed physical lot quantities. | +| `finished` | No | Operational flag marking the line as finished. Default `False`. | +| `enable_linked_currency` | No | Enables alternate linked currency pricing fields. Default `False`. | +| `linked_price` | No | Linked-currency price, visible only when linked currencies are enabled. | +| `linked_currency` | No | Linked currency used with `linked_price`. | +| `linked_unit` | No | Unit used with `linked_price`. | +| `price_type` | No | Pricing mode: `cash`, `priced`, `basis`, or `efp`. Default `priced`. | +| `progress` | Computed | Fixation progress, shown for basis-priced lines. | +| `premium` | No | Premium or discount applied to the line price. | +| `inherit_tol` | No | If checked, line tolerances inherit contract tolerances. Default `True`. | +| `tol_min` | No | Line-level negative tolerance percentage when not inherited. | +| `tol_min_v` | Computed | Computed minimum quantity after tolerance. | +| `tol_max` | No | Line-level positive tolerance percentage when not inherited. | +| `tol_max_v` | Computed | Computed maximum quantity after tolerance. | +| `tol_min_qt` | No | Absolute negative tolerance quantity. | +| `tol_max_qt` | No | Absolute positive tolerance quantity. | +| `inherit_cer` | No | If checked, line certification inherits contract certification. Default `True`. | +| `certif` | No | Line-level certification when not inherited. | +| `del_period` | No | Delivery period reference used by pricing period rules. | +| `from_del` | No | Delivery period start date. | +| `to_del` | No | Delivery period end date. | +| `period_at` | No | Business event used to interpret the delivery period, such as loading, discharge, title transfer or arrival. | +| `concentration` | No | Concentration value for concentrate contracts. | +| `term` | No | Incoming document representing the contract term source. | +| `update_pricing` | No | Requests pricing update from assay/term information. | +| `assay_state` | No | Assay/pricing status: provisional, final or umpire. | + +### Line tabs + +| Tab | Field/model | Usage | +| --- | --- | --- | +| `Concentrate / Assays` | `assay.assay`, `assay.line` | Stores assay references and detailed elemental analysis. | +| `Concentrate / Term` | `concentrate.term` | Payable or penalty terms used to price concentrate material. | +| `Lots` | `lot.lot` | Physical and virtual lots attached to the purchase line. | +| `Fees` | `fee.fee` | Service or logistics fees attached to the purchase line. | +| `Mtm` | `purchase.strategy` | MTM strategies selected for the line. | +| `Derivatives` | `derivative.derivative` | Hedge records at line level. | +| `Pricing / Components` | `pricing.component` | Price curve or matrix components used by the line. | +| `Pricing / Pricing dates` | `pricing.pricing` | Daily or fixing price records. | +| `Pricing / Summary` | `purchase.pricing.summary` | Computed fixed/unfixed summary. | +| `Estimated dates` | `pricing.estimated` | Estimated business dates used by period rules. | +| `Optionals Scenarios` | `optional.scenario` | Optional pricing/execution scenarios. | + +## Sale contract + +Model: `sale.sale` +Table: `sale_sale` +Main view extension: `sale_form` + +The sale contract mirrors most purchase-trade header controls. `from_location` and `to_location` are also required; in the sale form the base `warehouse` field is replaced by `to_location`. + +### Header fields + +| Field | Required | Usage | +| --- | --- | --- | +| `lc_date` | No | Letter of credit date for customer contract follow-up. | +| `wb` | Yes | Weight basis; defaulted from `purchase.weight.basis`. | +| `certif` | Yes | Certification, hidden for company `MELYA`. | +| `agent` | No | Sale-side commercial/logistics agent shown on the header. | +| `operator` | No | Execution owner. | +| `trader` | No | Trader responsible for the sale. | +| `our_reference` | No | Internal reference. | +| `association` | Yes | Trade association or rule set, hidden for company `MELYA`. | +| `crop` | No | Crop/campaign information. | +| `tol_min` | Yes | Negative quantity tolerance percentage. Default `0`. | +| `tol_max` | Yes | Positive quantity tolerance percentage. Default `0`. | +| `from_location` | Yes | Sale loading/origin location. | +| `to_location` | Yes | Sale destination/discharge location; replaces base warehouse display. | +| `incoterm` | Inherited | Sale Incoterm. | +| `incoterm_location` | Inherited | Named Incoterm place. | +| `product_origin` | No | Product origin statement. | +| `bank_account` | No | Bank account selected from customer/party bank accounts, defaulted by currency when possible. | +| `doc_template` | No | Template used to populate required contract documents. | +| `required_documents` | No | Customer contract document checklist. | +| `analytic_dimensions` | No | Analytic reporting dimensions. | + +### Header tabs + +| Tab | Field/model | Usage | +| --- | --- | --- | +| `Derivative` | `derivative.derivative` | Sale-linked hedge or derivative records. | +| `Pnl` | `valuation.valuation.line`, `valuation.valuation.dyn` | Sale P&L and valuation output. | +| `Forex` | `forex.cover.physical.sale` | FX covers for the sale contract. | +| `Required documents` | `contract.document.type` | Required documents for sale execution. | +| `Dimensions` | `analytic.dimension.assignment` | Analytic allocation dimensions. | + +## Sale contract line + +Model: `sale.line` +Table: `sale_line` +Main view extension: `sale_line_form` + +The sale line uses the same pricing, tolerance, linked currency, lot, fee, MTM and derivative patterns as the purchase line. It adds a `Price composition` tab for reporting sale price build-up. + +| Field | Required | Usage | +| --- | --- | --- | +| `quantity_theorical` | No | Theoretical quantity for the sale line. | +| `finished` | No | Operational completion flag. | +| `enable_linked_currency` | No | Enables linked-currency fields. | +| `linked_price` | No | Alternate price when linked currency is enabled. | +| `linked_currency` | No | Linked currency. | +| `linked_unit` | No | Linked price unit. | +| `price_type` | No | Pricing mode: `cash`, `priced`, `basis`, or `efp`. Default `priced`. | +| `progress` | Computed | Fixing progress for basis-priced lines. | +| `premium` | No | Premium or discount. | +| `inherit_tol` | No | Inherits header tolerances when checked. Default `True`. | +| `tol_min`, `tol_max` | No | Line-level tolerance percentages when not inherited. | +| `tol_min_v`, `tol_max_v` | Computed | Computed min/max quantities after tolerance. | +| `tol_min_qt`, `tol_max_qt` | No | Absolute tolerance quantities. | +| `inherit_cer` | No | Inherits header certification when checked. Default `True`. | +| `certif` | No | Line-level certification. | +| `pricing_rule` | No | Free-text pricing rule shown on reports. | + +## Related tables + +| Model | PostgreSQL table | Purpose | +| --- | --- | --- | +| `purchase.purchase` | `purchase_purchase` | Purchase contract header. | +| `purchase.line` | `purchase_line` | Purchase contract lines. | +| `sale.sale` | `sale_sale` | Sale contract header. | +| `sale.line` | `sale_line` | Sale contract lines. | +| `contract.document.type` | `contract_document_type` | Relation object for required contract documents. | +| `doc.template` | `doc_template` | Contract document templates. | +| `pricing.estimated` | `pricing_estimated` | Estimated dates used by pricing and logistics rules. | +| `pricing.component` | `pricing_component` | Pricing components attached to contract lines or MTM strategies. | +| `pricing.pricing` | `pricing_pricing` | Price fixing records. | +| `fee.fee` | `fee_fee` | Contract, shipment or line fees. | +| `lot.lot` | `lot_lot` | Physical/virtual lots linked to contract lines. | +| `purchase.strategy` | `purchase_strategy` | Purchase MTM strategy link model. | +| `sale.strategy` | `sale_strategy` | Sale MTM strategy link model. | + diff --git a/modules/purchase_trade/process_documentation/ITSA/Interacid_Tradon_Practice_Book.html b/modules/purchase_trade/process_documentation/ITSA/Interacid_Tradon_Practice_Book.html new file mode 100644 index 0000000..cdda475 --- /dev/null +++ b/modules/purchase_trade/process_documentation/ITSA/Interacid_Tradon_Practice_Book.html @@ -0,0 +1,880 @@ + + + + + +Interacid Trading S.A - Tradon Practice Book + + + +
+
+
Practice Book - Tradon / Tryton
+

Interacid Trading S.A
Sulfuric Acid Drop Ship Trading Operations

+
+ Avenue des Baumettes 5, 1020 Renens, Switzerland + Commodity: Sulfuric acid + Currency: USD + Scope: Physical trading only +
+
+ +

Document Status

+
+

This Practice Book describes how Interacid Trading S.A will run sulfuric acid drop-ship transactions in Tradon. It is written as a target operating manual: the Trader, Back-office, Operations and Finance teams should be able to follow the lifecycle from master data and contract entry through budgeted costs, shipment execution, lot creation, matching, pricing and settlement.

+

The scope deliberately excludes futures hedging and FX hedging. Interacid's activity is treated as USD-denominated physical trading. Pricing covers mostly Priced contracts and selected Basis contracts, with Argus as the principal market reference. The public Interacid service positioning emphasizes global sulfuric acid trading, shipping/logistics capability, terminal services, safety and reliability; those themes are reflected in the operating controls in this book.

+
+ +
+
Company
Interacid Trading S.A
+
ERP
Tryton / Tradon
+
Commodity
Sulfuric acid
+
Flow
Drop Ship
+
Default Tolerance
5%
+
Market
Argus
+
Currency
USD
+
+ +
+

Contents

+
+ +
+
+ +
+

1. Fundamentals and Glossary

+
+

Operating principles

+

Interacid will use Tradon to control physical sulfuric acid trading from contract capture to final settlement. The core business pattern is Drop Ship: the purchase and sale are commercially matched, and the product moves directly from supplier/loading point to customer/destination without an Interacid warehouse storage step.

+

Each physical flow will be represented by a purchase contract, a sale contract, one or more shipment records, and physical lots that carry executed quantity, cost allocation, invoice status and matching status. The default contract tolerance is 5% unless a customer, supplier or specific contract requires another tolerance.

+
+ Important Note: Hedging, derivatives and FX cover tabs may exist in the configured application, but they are out of scope for Interacid's operational book. The teams will keep pricing and physical mechanics separate from hedging chapters because no hedging/FX process is expected for this scope. +
+ +

Key term mapping

+
+ + + + + + + + + + + + + +
Business termTradon term / modelUse in this book
Purchase contractpurchase.purchaseSupplier-side commercial contract.
Sale contractsale.saleCustomer-side commercial contract.
Physical lotlot.lotExecuted quantity used for matching, costing and invoicing.
Lot quantity statelot.qtOpen, physical, matched or shipped quantity status used by matching screens.
Shipmentstock.shipment.inOperational record for shipment milestones, BL data, costs and lots.
Budgeted/ordered/actual costfee.feeCost entered first at contract level, then ordered at shipment level, then allocated to physical lots.
Price curveprice.priceArgus index or other market reference used by Basis/formula pricing.
+
+
+
+ +
+

2. Master Data Setup

+
+

Party defaults and price curves

+

Before entering the trade, Back-office will make sure the supplier, customer, service providers and Argus curves exist. Party defaults reduce repeated entry on contracts and enforce Interacid's default tolerance discipline.

+ +

Party screen - Contract and Execution tabs

+
+ + + + + + + + + + + + +
#AttributeRequiredOperational description
1Tol - in %NoDefault negative tolerance for contracts with the party. For Interacid sulfuric acid trading, enter 5 when the commercial relationship accepts +/-5% tolerance.
2Tol + in %NoDefault positive tolerance. It should normally mirror the negative tolerance unless a supplier/customer agreement says otherwise.
3Weight basisNoDefault commercial weight basis for the party, used when creating purchase or sale contracts.
4AssociationNoDefault trade rule or association reference. Use only when the commercial terms require it.
5OriginNoDefault product/geographic origin for documentation. For sulfuric acid, this should reflect the supplier or plant origin where relevant.
6SLA placesNoOptional execution service cost matrix by location. Use for service providers where standard control, terminal or logistics costs are known by place.
+
+
+
Screenshot placeholder - Party Contract tab
+ Expected capture: open a supplier or customer party in Tradon, display the Contract tab with numbered red callouts on tolerance, weight basis, association, origin and initials. A second capture should show the Execution tab if SLA costs are configured. +
+ +

Price curve screen - Argus reference

+
+ + + + + + + + + + + + + +
#AttributeRequiredOperational description
1Price indexYesShort index code used in pricing components. Example: ARGUS_SA_USD_MT or the final Interacid-approved Argus index naming convention.
2DescriptionYesHuman-readable description of the Argus sulfuric acid reference.
3Index typeNoSet to Spot or Future depending on the Argus source used. For regular physical sulfuric acid pricing, Spot will usually be sufficient unless monthly/future periods are configured.
4UnitNoCommercial unit for the quotation, normally metric ton.
5CurrencyNoEnter USD. All Interacid activity in this scope is USD-denominated.
6CalendarNoQuotation calendar controlling valid price dates.
7Prices ValuesNoDaily or period values imported or keyed for Argus. Basis contracts and formula-priced lines will read these values.
+
+
+
Screenshot placeholder - Price curve and price values
+ Expected capture: show the Argus sulfuric acid curve header and the Prices Values tab with at least three dated quotation rows. Number the index, description, unit, currency, calendar and price values table. +
+
+
+ +
+

3. Purchase Contract Entry

+
+

The Trader or Back-office will create the purchase contract first. For drop ship, the purchase location and sale destination must be entered carefully because they drive matching, shipment, cost allocation and reporting.

+
    +
  1. Open the purchase contract screen and click New.
    2. +
  2. Enter the supplier, purchase date, currency USD, payment term and commercial reference.
    3. +
  3. Enter the Interacid trade fields listed below.
    4. +
  4. Add one purchase line for sulfuric acid, including quantity, tolerance, price type and concentration if concentration adjustment applies.
    5. +
  5. Enter the budgeted costs on the purchase line or contract cost tab before shipment execution.
    6. +
  6. Click Save, then follow the normal approval/confirmation process.
    7. +
+ +

Purchase contract header field reference

+
+ + + + + + + + + + + + + + +
#AttributeRequiredOperational description
1Weight basisYesCommercial weight basis used for the sulfuric acid quantity. Back-office confirms the value from the supplier contract.
2CertificationYesCertification attached to the physical contract if required for product documentation. Use the default if no special certificate is agreed.
3OperatorNoOperations owner who will follow the shipment and physical lot execution.
4TraderNoCommercial owner of the purchase. This is used for internal follow-up and P&L ownership.
5Our ReferenceNoInteracid internal reference. Example: ITSA-SA-P-0001.
6Tol - in % / Tol + in %YesEnter 5 and 5 by default unless the supplier contract specifies another tolerance.
7From locationYesSupplier loading location or origin terminal.
8To locationYesCustomer destination or discharge point. For drop ship, this should align with the sale contract destination.
9Incoterm / Incoterm LocationInheritedCommercial delivery rule and named place, copied from the supplier agreement.
10OriginNoOrigin statement used for contract documentation and product traceability.
+
+
+
Screenshot placeholder - Purchase contract header
+ Expected capture: purchase contract form populated with an Interacid sulfuric acid supplier, USD currency, 5% tolerance, loading and destination locations, Incoterm and Interacid reference. Add numbered red callouts matching the table above. +
+ +

Purchase line field reference

+
+ + + + + + + + + + + + +
#AttributeRequiredOperational description
1ProductBaseSelect the sulfuric acid product configured in Tradon.
2Quantity / UnitBaseEnter the contractual quantity in metric tons. Physical lots will later carry the executed quantity.
3Price typeNoSelect Priced for fixed USD price. Select Basis when the line references Argus plus/minus a differential.
4Premium/DiscountNoUsed for basis or differential pricing. Example: Argus + 2.50 USD/MT.
5ConcentrationNoEnter contractual concentration when price must be adjusted by sulfuric acid concentration.
6Inherit toleranceNoLeave checked for the default 5% contract tolerance. Untick only when the line has its own tolerance.
7FeesNoEnter budgeted costs at contract level before shipment. These will later be ordered at shipment level and allocated to lots.
8Pricing / ComponentsNoFor Basis contracts, add the Argus curve component and period rules. For Priced contracts, this tab may be minimal.
+
+
+
Screenshot placeholder - Purchase line tabs
+ Expected capture: purchase line showing sulfuric acid, quantity, price type, 5% inherited tolerance, concentration field, Fees tab and Pricing Components tab. Number the fields used in the table. +
+
+
+ +
+

4. Sale Contract Entry

+
+

The sale contract represents the customer side of the drop-ship transaction. In the regular scenario it will match one purchase. In the split scenario, three sale contracts will be matched against the same purchase physical quantity.

+
    +
  1. Create the sale contract from the sale menu or from the commercial workflow agreed with Trading.
    2. +
  2. Enter the customer, USD currency, payment term and Incoterm.
    3. +
  3. Use the same destination logic as the purchase contract so the drop-ship route is consistent.
    4. +
  4. Add the sale line with sulfuric acid quantity, price type and concentration assumptions.
    5. +
  5. Save and confirm the sale contract before lot matching.
    6. +
+ +

Sale contract header field reference

+
+ + + + + + + + + + + + +
#AttributeRequiredOperational description
1Weight basisYesWeight basis agreed with customer.
2Agent / Operator / TraderNoCommercial and execution owners. Fill when ownership must be visible in reporting.
3Our ReferenceNoInteracid sale reference. Example: ITSA-SA-S-0001.
4Tol - in % / Tol + in %YesEnter 5 and 5 unless the customer contract says otherwise.
5From locationYesDrop-ship loading/origin location, aligned with the purchase when possible.
6To locationYesCustomer discharge/destination location. This replaces the base warehouse display in the sale form.
7Incoterm / Incoterm LocationInheritedCustomer delivery term and named place.
8Required documentsNoDocument checklist for customer execution when a template is used.
+
+
+
Screenshot placeholder - Sale contract header
+ Expected capture: sale contract form populated with an Interacid customer, USD currency, 5% tolerance, from/to locations and customer Incoterm. Number the fields above. +
+ +

Sale line field reference

+
+ + + + + + + + + + + +
#AttributeRequiredOperational description
1Quantity / UnitBaseCustomer contractual quantity. In the three-sales scenario, enter each sale quantity separately.
2Price typeNoUsually Priced; use Basis where the customer price references Argus plus/minus a differential.
3Premium/DiscountNoBasis adjustment or commercial differential.
4ConcentrationNoCustomer-side concentration assumption where price adjustment applies.
5LotsAfter matchingDisplays lots allocated/matched to the sale after the matching wizard is completed.
6FeesNoUse when sale-side costs or recoveries must be attached to the sale line.
7Pricing ruleNoFree-text explanation shown on reports for Basis or formula-priced customer lines.
+
+
+
+ +
+

5. Costs: Budgeted, Ordered and Lot-Specific

+
+

Interacid will control costs in three steps. First, Trading or Back-office enters budgeted costs at contract level. Second, Operations creates or updates ordered costs at shipment level when the service is committed. Third, final or specific costs are allocated to the physical lots contained in the shipment.

+ +
+ Example cost allocation:
+ Freight budget = 80.00 USD/MT x 10,000 MT = 800,000.00 USD
+ Ordered freight = 82.50 USD/MT x 10,000 MT = 825,000.00 USD
+ Difference to monitor = 25,000.00 USD unfavorable +
+ +

Fee screen field reference

+
+ + + + + + + + + + + + + +
#AttributeRequiredOperational description
1TypeYesSelect Budgeted at contract level, Ordered at shipment level and Actual when final invoice information is known.
2P/RYesPay/receive indicator. Freight, inspection and service costs are normally PAY.
3ProductYesService product, such as Maritime freight, inspection, terminal service, demurrage or other configured cost type.
4SupplierYesService provider or vendor responsible for the cost.
5ModeYesCalculation mode: lump sum, per quantity, percentage of price/rate/cost, or per packing.
6PriceNoRate or amount according to mode. For freight per metric ton, enter the USD/MT rate.
7Quantity / UnitNoQuantity used to calculate the amount. It can be inherited from lots or shipment depending on setup.
8LotsNoSpecific physical lots receiving the cost. Use this when a cost applies only to part of the shipment.
9AmountComputedCalculated amount used for accrual, invoice checking and P&L.
+
+
+
Screenshot placeholder - Fee entry and lot allocation
+ Expected capture: show a budgeted contract fee, then an ordered shipment fee, then the fee lots selection with one or several physical lots selected. Number Type, Product, Supplier, Mode, Price, Quantity, Unit, Lots and Amount. +
+
+
+ +
+

6. Drop-Ship Shipment Execution

+
+

For Interacid's drop-ship process, the shipment record is the operational bridge between the purchase, the sale and the physical lots. Operations will maintain carrier, vessel, BL, ETA, booking, receipt and control information.

+
    +
  1. From Lots Management, select open purchase/sale quantities to ship.
    2. +
  2. Create or open the shipment record.
    3. +
  3. Enter carrier, transport type, vessel, cargo mode, BL details and logistics dates.
    4. +
  4. Convert budgeted costs into ordered shipment costs where service commitments are known.
    5. +
  5. Create physical lots for the shipment once quantities are known.
    6. +
+ +

Inbound/drop-ship shipment field reference

+
+ + + + + + + + + + + + + + +
#AttributeRequiredOperational description
1CarrierNoCarrier party or logistics provider responsible for movement.
2From locationNoLoading point/origin terminal.
3To locationNoCustomer destination/discharge point.
4Transport typeNoSelect vessel, truck or other. Sulfuric acid seaborne movements will generally use vessel.
5VesselNoVessel master record when applicable.
6Cargo ModeYesSelect bulk or container. Sulfuric acid is expected to be bulk unless a specific containerized flow is confirmed.
7BL number / BL dateNoBill of lading reference and date. These drive pricing and invoicing milestones where contract terms depend on BL.
8ETA / ETD / ArrivalNoOperational milestone dates used by Operations to track shipment status and by Back-office for expected invoicing.
9FeesNoOrdered freight and logistics costs attached to the shipment.
10LotsAfter lot creationShipment lot quantities created from the open contract quantities.
+
+
+
Screenshot placeholder - Drop-ship shipment
+ Expected capture: shipment form with carrier, from/to locations, vessel, cargo mode, BL date/number, ETA/ETD and the Fees and Lots tabs. Number the fields above. +
+
+
+ +
+

7. Physical Lots and Matching

+
+

Create physical lots

+

Physical lots are created when shipment quantities are known. They are the operational unit used to allocate ordered costs, match purchase to sale and support invoicing.

+
+ + + + + + + + + + +
#AttributeRequiredOperational description
1Quantity availableRead-onlyOpen quantity available to split into physical lots.
2Shipment In / Internal / OutNoShipment source selected by the workflow. For drop ship, use the relevant shipment carrying the direct movement.
3Lot quantityNoQuantity to create for each physical lot. In the three-sales scenario, create lot quantities aligned with the sale splits.
4Net weight / Gross weightNoExecuted lot weights. Use net weight for commercial valuation unless the contract specifies otherwise.
5UnitYesCommercial unit, normally metric ton.
6PremiumNoLot-specific premium or discount if commercial terms differ by lot.
+
+
+
Screenshot placeholder - Add physical lots
+ Expected capture: Add physical lots wizard with the available quantity and one or more lot rows. For the split scenario, show three rows matching the three sale contracts. +
+ +

Match purchase and sale lots

+

The matching wizard links purchase-side quantities to sale-side quantities. The total quantity entered on the purchase side should equal the total quantity entered on the sale side before the user applies matching.

+
+ + + + + + + + + + + +
#AttributeRequiredOperational description
1PurchaseNoFilter purchase candidates to the contract being matched.
2SaleNoFilter sale candidates to one sale contract, or leave filters broader when matching one purchase to several sales.
3Qt typeNoUse Open for open contract quantities, Physic for physical lots or All for broad review.
4Purchase lot tableComputedShows available purchase lots and quantities.
5Qt to matchNoQuantity entered by Operations or Back-office for each purchase and sale candidate.
6Sale lot tableComputedShows sale-side candidates. In the split scenario, enter quantities against three sale rows.
7Total purchase / Total saleComputedControl totals. Apply matching only when totals agree within accepted tolerance.
+
+
+
Screenshot placeholder - Matching wizard
+ Expected capture: Matching wizard with purchase and sale filters, purchase lot rows, sale lot rows and total quantities. For the second scenario, show one purchase quantity split across three sale rows. +
+
+
+ +
+

8. Pricing and Concentration Adjustment

+
+

Most Interacid sulfuric acid contracts will be Priced, but Basis pricing is also in scope. Basis lines use a pricing component linked to an Argus price curve and a premium/discount. Where agreed, the final price can be adjusted according to concentration.

+
+ Basis price example:
+ Final price = Argus reference + premium/discount
+ Final price = 95.00 USD/MT + 2.50 USD/MT = 97.50 USD/MT +
+
+ Concentration adjustment example:
+ Adjusted price = Contract price x Actual concentration / Contract concentration
+ Adjusted price = 100.00 x 98.5 / 98.0 = 100.51 USD/MT
+ [@vendor: confirm final Interacid concentration adjustment formula and rounding rule] +
+ +

Pricing component field reference

+
+ + + + + + + + + + +
#AttributeRequiredOperational description
1Price SourceYesSelect Curve when pricing from Argus. Select Matrix only if a configured route/quality matrix is used.
2Fixation typeNoReference fixation type for the curve, for example official quotation or settlement.
3RatioNoComponent weighting percentage. Use 100% for a single Argus reference unless the contract specifies a blend.
4CurveNoSelect the approved Argus sulfuric acid price curve.
5CalendarNoQuotation calendar used to decide valid pricing dates.
6Period rulesNoRules that define pricing and application windows, such as dates before BL or a monthly quotation window.
+
+ +

Pricing record field reference

+
+ + + + + + + + + + +
#AttributeRequiredOperational description
1DateNoQuotation or fixing date.
2ComponentNoPrice component being fixed.
3QtNoQuantity fixed on the date.
4Settl. priceNoArgus or final settlement price for the date.
5Fixed qt priceComputedWeighted average price for fixed quantities.
6Unfixed qtComputedRemaining quantity still to be priced.
+
+
+
Screenshot placeholder - Pricing component and fixing records
+ Expected capture: contract line Pricing tab with an Argus component, period rule and pricing dates. Number the curve, ratio, calendar, date, quantity and settlement price fields. +
+
+
+ +
+

9. Worked Scenario 1 - One Purchase Matched with One Sale

+
+
+ Scenario 1 + Regular Drop Ship +
+
+
+ + + + + + + + + + + +
StepActorExpected result
Create purchase contractTrader / Back-officeOne USD purchase contract for sulfuric acid, 5% tolerance, supplier route and budgeted costs.
Create sale contractTrader / Back-officeOne USD sale contract with matching product, route, quantity and price type.
Create drop-ship shipmentOperationsShipment contains carrier/vessel or logistics reference, BL data, ETA and ordered costs.
Create physical lotOperationsOne physical lot carries the executed shipment quantity.
Apply matchingBack-officePurchase lot quantity equals sale lot quantity and both are linked.
Allocate costs to lotBack-office / FinanceOrdered freight and services are allocated to the physical lot for P&L and invoice control.
Finalize pricing and invoicingFinancePriced line invoices directly; Basis line uses Argus pricing records and concentration adjustment if applicable.
+
+
+
Screenshot placeholder - Scenario 1 flow evidence
+ Expected captures: purchase contract, sale contract, shipment, add physical lot wizard, matching wizard with one purchase row and one sale row, and fee allocation on the physical lot. +
+
+
+ +
+

10. Worked Scenario 2 - One Purchase Matched with Three Sales

+
+
+ Scenario 2 + Purchase Split Across Three Sales +
+
+

In this variant, one purchase shipment is commercially allocated to three customer sale contracts. Operations creates physical lots or lot quantities that match the commercial split, then Back-office matches the purchase quantity against the three sale quantities.

+
+ + + + + + + + + + + +
StepActorExpected result
Create one purchase contractTrader / Back-officePurchase quantity covers the combined expected sale quantities plus tolerance.
Create three sale contractsTrader / Back-officeEach sale contract has its own customer, price, delivery terms and quantity.
Create shipmentOperationsShipment represents the full purchase movement.
Split physical lotsOperationsPhysical lot rows are created to mirror the three sale quantities, or one lot is matched in three quantities depending on operational choice.
Apply matchingBack-officeThe purchase total equals the combined total of the three sale rows.
Allocate costsBack-office / FinanceShipment costs are allocated to the specific physical lots so each sale carries its correct cost share.
Invoice each saleFinanceEach customer invoice reflects its matched lot quantity, price type and any concentration adjustment.
+
+
+ Example split:
+ Purchase lot = 30,000 MT
+ Sale A = 10,000 MT, Sale B = 8,000 MT, Sale C = 12,000 MT
+ Matching control = 10,000 + 8,000 + 12,000 = 30,000 MT +
+
+
Screenshot placeholder - Scenario 2 matching
+ Expected capture: matching wizard showing one purchase contract/lot and three sale rows. The Total purchase and Total sale fields must agree before applying matching. +
+
+
+ +
+

11. Appendix - Models and Tables

+
+

Primary models used by this book

+
+ + + + + + + + + + + + + + + + + + + + +
Screen / functionTryton modelPostgreSQL tableRole
Purchase contractpurchase.purchasepurchase_purchaseSupplier-side contract header.
Purchase linepurchase.linepurchase_lineSupplier product, quantity, price and cost line.
Sale contractsale.salesale_saleCustomer-side contract header.
Sale linesale.linesale_lineCustomer product, quantity, price and cost line.
Shipmentstock.shipment.instock_shipment_inDrop-ship execution, BL, dates, fees and lots.
Physical lotlot.lotlot_lotExecuted physical quantity used for matching and costing.
Lot quantitylot.qtlot_qtAvailable, physical, matched and shipment quantity state.
Matching wizardlot.matching.startTransientMatches purchase quantities to sale quantities.
Add physical lots wizardlot.add.lotTransientSplits available shipment quantity into physical lots.
Feesfee.feefee_feeBudgeted, ordered and actual costs.
Fee allocationfee.lotsfee_lotsFee-to-lot allocation.
Pricing componentpricing.componentpricing_componentArgus curve or matrix component for Basis pricing.
Pricing fixingpricing.pricingpricing_pricingPricing/fixing values by date and quantity.
Price curveprice.priceprice_priceArgus market index master data.
Price valueprice.price_valueprice_price_valueCurve quotation values.
Partyparty.partyparty_partyCustomer, supplier and service provider master data.
+
+
+ Open item: Screenshots must be replaced with annotated captures from Interacid's configured Tradon environment. Never reuse another client's captures. +
+
+
+ +
+ Sources: Tradon screen reference Markdown files and Interacid public service page. + Generated for Interacid Trading S.A - Practice Book draft. +
+
+ + + + diff --git a/modules/purchase_trade/process_documentation/README.md b/modules/purchase_trade/process_documentation/README.md index 7603205..890de06 100644 --- a/modules/purchase_trade/process_documentation/README.md +++ b/modules/purchase_trade/process_documentation/README.md @@ -149,6 +149,17 @@ End-to-end commodity trading operations. - [Settlements & final P&L](07_trade_commodity_management/16_settlements_and_final_p_and_l.md) - [Regulatory reporting (position limits, trade reporting)](07_trade_commodity_management/17_regulatory_reporting_position_limits_trade_reporting.md) +Screen and table references: + +- [Purchase and sale contract screens](07_trade_commodity_management/screen_reference_purchase_sale_contracts.md) +- [Shipment, physical lot and matching screens](07_trade_commodity_management/screen_reference_logistics_lots_matching.md) +- [Fee, pricing and MTM screens](07_trade_commodity_management/screen_reference_fees_pricing_mtm.md) +- [Party and price curve master data screens](07_trade_commodity_management/screen_reference_party_price_curve.md) + +Generated HTML practice books: + +- [Interacid Tradon Practice Book](ITSA/Interacid_Tradon_Practice_Book.html) + ## Hire to Retire (H2R) / Human Capital Management From talent acquisition through employee lifecycle to separation.