Price-Sensitive Bulk Tea Pricing — Domain + CRM Modeling Research
Date: 2026-07-16 Prepared by: R&D — internal use Trigger: Post-Gate-1 client meeting (2026-07-16). Client stated bulk tea is price-sensitive, prices change weekly, are most likely connected to region, and that we should maintain a history of price changes (with ideas around per-product price trend tracking and expiry dates on bulk-deal prices). Status: Research synthesis for CRM design. Facts are labelled by confidence (see legend). Sections marked [VERIFY WITH CLIENT] require confirmation from Empire Teas directly.
Confidence legend
- [V] Verified — independently confirmed during research (2+ concurring sources or an adversarial-verification pass).
- [S] Sourced — drawn from a fetched primary/secondary source but not independently re-verified (the deep-research verification pass was truncated by an org spend limit; see §9).
- [K] Established engineering knowledge — standard, well-documented software patterns.
- [VC] Needs client confirmation — a business fact only Empire Teas can settle; each maps to a proposed open question in §8.
Relationship to existing research: this file extends
sri-lanka-tea-industry.md(which already covers the auction, grades, regions, Incoterms, the cost build-up, and why quotes expire). It does not repeat that material — it goes deeper on price formation mechanics and adds the CRM data-modeling half the earlier file did not cover.
1. Executive Summary
-
Bulk tea price is a moving weekly baseline, not a fixed catalog number. The Colombo Tea Auction runs a two-day sale every week [V] and sets the baseline cost of tea; exporters build a quote on top of it (auction cost + processing + certs + packaging + docs + freight + margin — see
sri-lanka-tea-industry.md §4). Because the baseline moves weekly, a bulk price and any quote built on it are inherently perishable. -
“Region” means the destination market — the market the tea is sold into (Middle East, EU, Russia/CIS…), not where it was grown. This is the selling-price axis, and it is Empire’s own, entirely downstream of the auction: the Colombo auction itself does not price by destination — it prices a lot by growing region/elevation and grade (§2.2–2.3), with no visibility into where the winning exporter will later resell it. Empire buys at that one auction-set cost, then sets its own selling price per destination market — a normal export-pricing decision driven by freight cost, market demand, and destination-specific certification costs, not by anything the auction does. Source region/elevation and grade are separate product attributes on the cost side; they are not the key on the selling price. The price model accordingly uses a single region dimension — destination market — and it lives entirely on Empire’s side of the transaction.
-
The current CRM model cannot represent any of this. The
Productentity today holdsunit price(s) per currency, cost, tax— a single current price with no history, no validity/expiry, and no region dimension (see PRD §Domain Model; prototypeProductfields). Quote-expiry is acknowledged in prose (“quote aging clock… expiry matters — auction price drift”) but has no data model behind it. This is the gap the meeting surfaced. -
Recommended shape (details in §7): keep the catalog
Productas the stable identity, and move price into an effective-datedproduct_pricetable (one row per price, withvalid_from/valid_to, an optionalmarket_regiondimension, currency, and Incoterm). Snapshot the chosen price onto the quote line item at quote time (immutable), while keeping a link back to the price row so the system can detect staleness (“catalog price changed / this quote’s price has expired — re-confirm”). This one pattern delivers all three asks at once: price history, expiry, and region-linked pricing — and unlocks the analytics (price trend, margin-over-time, region comparison).
2. How Bulk Tea Price Is Formed (Domain)
2.1 The auction is a weekly, two-day, sequentially-numbered sale
- The Colombo Tea Auction runs as a two-day weekly sale; each weekly market report covers a consecutive two-day sale (e.g. “Sale of 14 & 15 July 2026”) and sales are numbered sequentially week over week (e.g. “SALE NO: 26 – 07TH/08TH JULY 2026”; “SALE NO 46 25TH/26TH NOVEMBER 2025”). [V — forbestea.com/market-reports, teasrilanka.org/week-market-reports]
- Correction to earlier research:
sri-lanka-tea-industry.md §4says the auction is “typically Tuesday for low-grown, Wednesday for high and mid-grown.” A claim that the auction is fixed to “every Tuesday and Wednesday” was refuted during verification [V-refuted — srilankabusiness.com]. The observed sale days actually shift week to week (Sale 46 = Tue/Wed 25–26 Nov 2025; the following Sale 47 = Mon/Tue 1–2 Dec 2025). Takeaway for the CRM: do not hard-code auction weekdays. Treat “the weekly sale” as a numbered, dated event, not a fixed day-of-week. - Days within a sale are segmented by elevation / grade category (Ex-Estate, High & Medium, Low Grown leafy/semi-leafy/tippy, Premium Flowery, Off Grades, Dust), each catalogued by brokers. [S — forbestea.com PDF sale report]
CRM implication: the natural cadence unit for a bulk price is “the week” / “the sale”, not a calendar day. A weekly price-update workflow (§6.4) aligns to this rhythm.
2.2 Price differs by growing region / elevation — within the same week
- Within a single weekly sale, prices move in region/elevation-specific increments — e.g. Low Grown varieties appreciating ~Rs. 40/kg while High & Mid Grown PF1s appreciated selectively up to Rs. 50/kg in the same sale. [V — teasrilanka.org]
- Named growing regions carry distinct prices in the same sale — e.g. Nuwara Eliya largely unsold while Uva clean-leaf teas were Rs. 20/kg dearer. [V — teasrilanka.org] → region is a first-class dimension of bulk price formation.
- Elevation categories publish distinct weekly sale averages (High vs Mid vs Low Grown, in Rs/kg), and these move independently week to week — one band can fall while another rises in the same week. [S — economynext.com auction reports] Illustrative figures from one 2023 sale: High Grown ~840, Mid Grown ~848, Low Grown ~1,088 LKR/kg (overall avg ~983). [S — economynext.com] (Figures illustrative of the spread, not current.)
- Do not assume elevation ordering. Low-grown frequently prices above high-grown (that same sale: Low ~1,088 vs High ~840 LKR/kg) because strong, full-bodied low-grown teas carry the heaviest Middle East / CIS demand. The CRM must not bake in “high-grown = premium = higher price.” [S — economynext.com]
- Brokers further segment by an auction quality grouping (e.g. “Western” = Dimbula/Dickoya high-grown) and by quality tiers (Best / Select-Best / Below-Best) within a region×grade. An academic price-prediction model keys Colombo prices at exactly (elevation/region × grade × week) — independent validation of that composite as the natural price key. [S — forbestea.com PDF; researchgate.net]
CRM implication: a single “current price” per product is structurally wrong for bulk. Price varies along (source region/elevation × grade) at minimum, and moves every week.
2.3 Price also differs by grade — within the same region and week
-
Within one elevation band and week, movement is grade-specific: e.g. for high growns BOP/BOPF fell ~50, BP1 ~70, PF1 ~100 rupees while for low growns BOP1 rose ~50 and PEK fell ~100 in the same week. [S — economynext.com]
-
This matches the existing grade research (
sri-lanka-tea-industry.md §5): grade drives price, use, and which auction lots are relevant. -
Volume also tiers the price. Bulk is quoted by order size — from ~500 kg trial pallets up to full 40 ft containers — and per-kg price varies with quantity, so volume is a real (if secondary) pricing axis on top of region×grade. [S — srilankaexport.com]
CRM implication: grade is a required price dimension alongside region. The price key is effectively (product/grade × source-region × week), quoted per kg; order volume is a secondary pricing factor but not treated as a required price-key dimension here.
2.4 What moves the price week to week
From the domain corpus + this research: crop volume / seasonality (quality seasons per region — sri-lanka-tea-industry.md §6), demand by destination market (Middle East vs EU vs Russia/CIS pull different grades — §7 of that file), quality of the specific invoice, FX (LKR/USD) since exports are typically quoted in USD while the auction clears in LKR, freight (Incoterm-dependent), and macro demand shocks. [S / domain knowledge] The practical consequence is only that prices are volatile weekly and cannot be treated as static — the CRM does not need to model the drivers, only to capture the resulting price with its validity window and let a human re-price.
2.5 The auction price is the dominant slice of the exporter’s cost
- One trade source estimates the producer’s share of the average FOB price at ~75–80%, leaving ~20–25% to the exporter — i.e. the auction/purchase cost is the dominant component of the FOB baseline. [S — historyofceylontea.com] Treat the exact ratio as indicative, not a constant to hard-code.
- Concrete 2024 benchmark: the Colombo auction averaged ~USD 4.08/kg (all teas) while Sri Lanka’s tea exports averaged ~USD 5.83/kg FOB (USD 1.43 bn / 245.79 M kg) — the exporter’s value-add sits on top of an auction baseline that is the dominant cost slice. [S — historyofceylontea.com] Order-of-magnitude only, not live prices.
- Auction average ≠ export/FOB price — they are not directly comparable; comparing average FOB bulk prices against average high-grown auction prices distorts the picture. [S — historyofceylontea.com]
CRM implication: if we ever store an auction reference price and a selling price, label them distinctly and never compute margin by subtracting non-comparable figures. Margin = (selling price under a given Incoterm) − (this exporter’s landed cost build-up), not (FOB − auction average).
2.6 Published price references exporters actually watch
- Forbes & Walker (
forbestea.com) — weekly Tea Market Reports, National Tea Sale Averages, and Weekly Tea Auction Quantities & Averages. The canonical public reference. [V — forbestea.com/market-reports] - teasrilanka.org — weekly market reports (sale number + dates + per-category commentary). [V]
- John Keells, Ceylon Tea Brokers PLC, Eastern Brokers and the rest of the 8 registered brokers each publish parallel weekly reports — an exporter typically watches several. [S — ceylonteabrokers.com] → schema implication: allow a broker/source attribution on each recorded baseline (the
sourcecolumn in §7), not a single assumed feed. - economynext.com — secondary press coverage that quotes per-elevation weekly averages. [S]
CRM implication (optional, later): these are candidate inputs for an auction-reference feed a rep consults when setting a weekly price. V1 can be manual entry (“this week’s baseline for low-grown BOP is X”); an import/scrape of broker reports is a future enhancement, and the system must never auto-set a customer price from them (human-in-the-loop governance, PRD §Governance).
2.7 Quoting against a moving baseline
- Because the baseline moves weekly, quotes carry an expiry — the earlier research cites the industry-standard ~30-day quote validity (“a quote given today may not be viable if auction prices spike next week”;
sri-lanka-tea-industry.md §4, §10 step 9). [VC] whether Empire uses 30 days, “valid until next auction” (~1 week), or per-deal negotiated windows. - Incoterm changes the number: the same tea is a different price at FOB Colombo vs CIF Hamburg (freight + insurance to destination). Every price and every quote line must carry its Incoterm (already noted in PRD; reinforced here). [V — domain corpus]
- Practitioner rule of thumb: CIF ≈ FOB Colombo + ~12–18% for freight/insurance to destination; bulk is quoted FOB Colombo in USD, with CIF/other Incoterms “agreed in writing per order.” Exporters explicitly do not publish fixed list prices, because “the market moves with each auction.” [S — srilankaexport.com, esilkroute.com.lk]
- Lead-time context: auction groundwork begins ~2 weeks before a sale (samples distributed, buyers appraise) — part of why a quote’s validity window is measured in weeks, not months. [S — impratea.com]
- Re-quote triggers: price expiry, an auction move beyond a threshold, FX move, or a change in requested grade/volume. The CRM’s job is to surface that a quote’s underlying price is stale and prompt a human to re-confirm/re-quote — not to auto-adjust.
3. The Gap in the Current CRM Model
| Concern | Current model (PRD §Domain Model + prototype) | Gap |
|---|---|---|
| Price shape | Product.unit price(s) per currency, cost, tax — a single current price |
No history, no validity/expiry, no region dimension |
| Price over time | none | Cannot answer “how has product X’s price changed over time” |
| Region-linked | Account.region, prototype Regions enum exist, but price is not keyed on region |
Price cannot differ by region |
| Quote line price | Quote line items reference products; age on quote |
Price is not snapshotted with an expiry; no stale-price detection |
| Analytics | dashboards (F17) exist | No price-trend / margin-over-time / region-comparison because there’s no price history to chart |
The three meeting asks map cleanly onto three missing capabilities: history, expiry/validity, region-keying — all of which the pattern in §7 provides together.
4. CRM / Software Modeling Options (Half B)
The core problem is temporal (effective-dated) pricing: a value that changes over time where you must retain and query what it was on any given date. This is a well-trodden pattern. [K]
4.1 Option comparison
| Pattern | How it works | Pros | Cons | Fit for us |
|---|---|---|---|---|
| A. Effective-dated rows (valid_from / valid_to) — a.k.a. SCD Type 2 | One row per price version; each row has valid_from + valid_to; the current row has valid_to = NULL (or a is_current flag). Point-in-time lookup: WHERE d >= valid_from AND (d < valid_to OR valid_to IS NULL). [K, S — dbt docs, Wikipedia SCD] |
Simple, relational, universally understood, trivial history + point-in-time queries, plays perfectly with JPA/Flyway | Must keep valid_from/valid_to consistent (close old row when inserting new); lookups need an index |
✅ Recommended base pattern |
| B. PostgreSQL range types + exclusion constraint | Store validity as a single tstzrange/daterange column; a GiST exclusion constraint forbids overlapping ranges for the same key. [S — clarkdave.net, PG docs] |
Type-level guarantee start<end; DB enforces non-overlap (no two active prices for the same key at once); atomic interval | Slightly more advanced; ORM mapping of range types needs care | ✅ Recommended enforcement layer on top of A |
C. temporal_tables extension / SQL:2011 system-versioning |
A trigger auto-writes prior row state to a history table on every UPDATE (sys_period tstzrange). [S — clarkdave.net, temporal_tables] |
History maintained automatically, no app code | Adds an extension dependency; RDS may not offer it; conflates system time with business validity (we need business/valid time) | ⚠️ Not for the primary price table — see §4.2 |
| D. Event-sourced price changes | Store an append-only log of “price changed to X effective D” events; project current price. | Perfect audit; natural fit if prices arrive as a stream | Heavier; overkill for weekly manual updates; every read needs a projection | ❌ Overkill for ~weekly cadence |
| E. Bitemporal (valid time × transaction time) | Two independent time axes: when the price was true in the business and when it was recorded; supports retroactive corrections with full auditability. [S — aiven.io, softwarepatternslexicon] | Answers “what did we think the price was on date D, as known on date D2” — retroactive correction without losing history | Real complexity cost; most teams don’t need the second axis | ◐ Defer. Note it as a possible future upgrade if audit/retro-correction of prices becomes a hard requirement |
4.2 Recommendation on approach
- Use A + B: effective-dated
product_pricerows (valid_from/valid_to, current =valid_to IS NULL) enforced by a PostgreSQL exclusion constraint so two prices can never overlap for the same(product, region, currency, incoterm)key. This is the minimum that satisfies history + expiry + region and is idiomatic Postgres + Flyway + JPA. [K] Newer PostgreSQL versions add a native temporal primary key (PRIMARY KEY (product_no, valid_at WITHOUT OVERLAPS)) which also needs thebtree_gistextension [S — PG docs] — but confirm availability on the target RDS engine version before relying on it; the plainEXCLUDE … USING gistconstraint works on all current versions and is the safe default. ABEFORE INSERTtrigger can auto-close the prior open row on each price change so the app never does the two-step update-then-insert by hand. [S — SCD2-in-Postgres] - Do not rely on
temporal_tables/system-versioning for the price itself — we need business/valid time (a price is “valid from next Monday”), which is a different axis from “when the row was inserted.” System/transaction time is better served by the existing audit trail NFR (who changed what when). Bitemporal (E) is the union of both and is a deliberate later upgrade, not V1. - Catalog vs transactional line item [S — HubSpot, DealHub]: keep a clean split — the catalog
Productis the reusable identity + its price history; a quote line item is a transactional row that snapshots the price it used at quote time (immutable) and links back to the source price row. This is standard CRM/CPQ modeling and is what makes stale-price detection possible.
5. Price Expiry & Stale-Price Detection
Two distinct clocks — keep them separate:
- Catalog price validity — on the
product_pricerow:valid_from…valid_to. For weekly bulk pricing, a rep sets a price “valid from this week’s sale” and either setsvalid_toexplicitly (e.g. +7 days, or the next sale date) or leaves it open (NULL) until superseded by the next weekly update. A separate optionalexpires_atcan encode “hard expiry even if not yet superseded” (the client’s expiry-date idea). - Quote-line price snapshot — when a rep adds a product to a quote, copy the unit price, currency, Incoterm, and the
price_valid_untilonto the quote line, plus a FK to the sourceproduct_pricerow and aprice_captured_at. The quote’s own validity window (the ~30-day quote) is a header-level field on the quote.
Stale flags (surfaced in the UI; never auto-corrected):
- Expired-by-time:
now > quote_line.price_valid_until→ “This quoted price has expired — re-confirm before sending.” - Drift: the product’s current active
product_price≠ the price snapshotted on the quote line → “Catalog price for this product changed since this quote was drafted.” - Approaching expiry:
price_valid_untilwithin N days → soft warning.
Re-pull / refresh action: mirroring CPQ practice, provide an explicit “refresh price” action that re-pulls the current active catalog price onto a stale quote line (human-initiated, logged) rather than silently auto-updating — CPQ tools handle staleness by an explicit recalculate step, not automatic time-based mutation. [S — dealhub.io]
These feed the existing surfaces: F7 quote readiness checklist (a stale price should block/flag submission), F14 AI quote assistant (flags the gap, surfaces recent comparable prices — read-only, never sets price), and F17/F18 dashboards/alerts (quotes aging with $-at-risk, already present, now backed by real expiry data).
Prototype note: the client-facing prototype (see §9) demonstrates a deliberately simplified version of this — one price-validity status per quote (the worst status across its bulk-priced lines), shown as a single banner/chip, rather than per line item as recommended above. That’s a legibility simplification for a demo, not a schema change: the real build should still snapshot price_valid_until/source_price_id per line item as specified, and can roll those up to a quote-level “worst status” badge for display exactly as the prototype shows.
6. Region-Linked Pricing
6.1 What “region” means here
“Region” is the destination market the tea is sold into — a Middle East buyer and an EU buyer get different prices for the “same” tea. This is Empire’s own selling price, set after the auction — the auction itself does not price by destination (it prices by growing region/elevation and grade, per §2.2–2.3, with no knowledge of where the tea will later be resold). Source region/elevation + grade stay as product attributes — they describe what the tea is and drive its cost at auction, but they are not the selling-price key. The schema below carries source_region/grade on the product (for cost/description) and keys the price row on market_region = destination market, which is purely Empire’s downstream commercial pricing.
6.2 Modeling region tiers
- A
market_regionreference table (seed from the prototype’s existingRegionsenum: EU–Northern, EU–Western, Middle East, East Asia, North America, Eastern Europe). - Price rows key on
(product_id, market_region_id, currency, incoterm, validity). ANULLmarket_region_id= a base/list price applying where no region-specific price exists (fallback resolution: prefer the region-specific active row; else the base row). - This gives region price comparison for free (group active prices by region) and keeps the model open if the client later says price is not region-linked (they just never create region-specific rows).
7. Recommended Data Model (PostgreSQL)
Consistent with AD #3 (single-tenant relational schema, Flyway/JPA) and AD #8 (admin custom fields via JSONB — but price history is core domain data, so it is relational, not JSONB). Illustrative DDL sketch (names/types to be finalized in the spec):
-- Catalog identity (stable). No price columns live here anymore.
CREATE TABLE product (
id BIGSERIAL PRIMARY KEY,
code TEXT NOT NULL UNIQUE,
name TEXT NOT NULL,
category TEXT NOT NULL, -- 'bulk' | 'private_label' | ...
tea_grade TEXT, -- OP/BOP/BOPF/Dust/CTC... (ref list)
source_region TEXT, -- growing region/elevation (ref list) — COST side
unit_of_measure TEXT NOT NULL DEFAULT 'kg',
held_certs TEXT[], -- feeds F9 cert-mismatch
custom_fields JSONB NOT NULL DEFAULT '{}', -- AD #8 admin custom fields
is_active BOOLEAN NOT NULL DEFAULT TRUE
);
CREATE TABLE market_region ( -- DESTINATION market — SELLING side
id BIGSERIAL PRIMARY KEY,
code TEXT NOT NULL UNIQUE,
name TEXT NOT NULL
);
-- Effective-dated price history (Option A + B). One row per price version.
CREATE TABLE product_price (
id BIGSERIAL PRIMARY KEY,
product_id BIGINT NOT NULL REFERENCES product(id),
market_region_id BIGINT REFERENCES market_region(id), -- NULL = base/list price
currency TEXT NOT NULL, -- 'USD' typical for export
incoterm TEXT NOT NULL, -- 'FOB' | 'CIF' | ...
unit_price NUMERIC(12,2) NOT NULL, -- per unit_of_measure (per kg)
cost NUMERIC(12,2), -- optional landed-cost basis for margin
validity DATERANGE NOT NULL, -- [valid_from, valid_to)
expires_at DATE, -- optional hard expiry (client's idea)
source TEXT, -- 'manual' | 'auction_ref:<sale_no>' ...
note TEXT,
created_by BIGINT NOT NULL REFERENCES app_user(id),
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
-- No two overlapping prices for the same product/region/currency/incoterm:
EXCLUDE USING gist (
product_id WITH =,
currency WITH =,
incoterm WITH =,
COALESCE(market_region_id, 0) WITH =,
validity WITH &&
)
);
CREATE INDEX ON product_price (product_id, market_region_id, currency, incoterm);
-- Quote line snapshots the price it used, but links back to detect drift/staleness.
CREATE TABLE quote_line_item (
id BIGSERIAL PRIMARY KEY,
quote_id BIGINT NOT NULL REFERENCES quote(id),
product_id BIGINT NOT NULL REFERENCES product(id),
market_region_id BIGINT REFERENCES market_region(id),
quantity NUMERIC(14,2) NOT NULL,
currency TEXT NOT NULL,
incoterm TEXT NOT NULL,
unit_price NUMERIC(12,2) NOT NULL, -- SNAPSHOT (immutable once quoted)
source_price_id BIGINT REFERENCES product_price(id), -- provenance
price_captured_at TIMESTAMPTZ NOT NULL DEFAULT now(),
price_valid_until DATE -- snapshot of the source's expiry
);
-- Additional costs on a quote — freight, certification retrieval, export documentation, or any other named cost
-- the deal needs, layered on top of the tea line items (completes the cost build-up: auction cost + processing +
-- certs + packaging + export docs + freight + margin, §2.7). A flexible list rather than a fixed set of categories,
-- since bulk vs private-label deals carry different cost drivers. Human-entered amounts only — never computed
-- automatically. Available on any quote, bulk or private-label (see OQ-G).
CREATE TABLE quote_cost_line (
id BIGSERIAL PRIMARY KEY,
quote_id BIGINT NOT NULL REFERENCES quote(id),
label TEXT NOT NULL, -- e.g. 'Halal certification retrieval', 'Freight & insurance — CIF Jebel Ali'
amount NUMERIC(12,2) NOT NULL, -- whole-currency amount, same currency as the quote
created_by BIGINT NOT NULL REFERENCES app_user(id),
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
Point-in-time / current-price query [K, S — dbt point-in-time join]:
-- Active price for a product+region today (region-specific preferred, else base):
SELECT * FROM product_price
WHERE product_id = :pid
AND currency = :ccy AND incoterm = :inco
AND (market_region_id = :region OR market_region_id IS NULL)
AND validity @> CURRENT_DATE
AND (expires_at IS NULL OR expires_at >= CURRENT_DATE)
ORDER BY market_region_id NULLS LAST -- prefer region-specific
LIMIT 1;
Price history / trend for product X = SELECT unit_price, lower(validity) FROM product_price WHERE product_id=:pid ORDER BY lower(validity). Margin over time = unit_price - cost across rows. Region comparison = active rows grouped by market_region_id.
Current/expiring/expired is a computed value, not a stored column — it’s derived at query/render time by comparing CURRENT_DATE to validity/expires_at (as in the point-in-time query above), never written to the row. Prototype note: the demo prototype has no live clock (it’s a static file), so it stores a literal status string instead and flips it via explicit actions (“publish this week’s price” → current; “refresh” → recomputed from the live catalog row). That’s a prototype-only stand-in for the real computed check, not a schema recommendation to persist status.
Why this satisfies all four asks: history = the row set per product; expiry = validity/expires_at + quote snapshot; region = market_region_id; additional costs = quote_cost_line layered on top of the tea line items. And it stays inside AD #3/#8 (relational core, JSONB only for admin custom fields).
8. New Features & Open Questions This Implies
Proposed feature/scope changes (to route through PRD signals → decomposition)
- F26 (Products Catalog) — extend: replace the single-price product with effective-dated
product_pricehistory, region-keyed, with validity/expiry. New admin surface: weekly bulk-price update workflow (bulk-set this week’s prices with a validity window). - F7 (Quotes) — extend: snapshot price onto quote lines; add stale-price / expired-price flags to the readiness checklist and quote UI; header-level quote validity window; a flexible additional-cost-line list (freight, certification retrieval, export documentation, etc.) on any quote, completing the cost build-up from §2.7.
- F14 (AI Quote Assistant) — extend: surface recent price trend + comparable recent prices as read-only decision support (still never sets price).
- F17 / F35 (Dashboards/Analytics) — extend: price-trend over time, margin-over-time, region price comparison widgets.
- Optional/Deferred: an auction-reference feed (manual entry V1; broker-report import later) — strictly a reference for the human pricer, never an auto-price source.
Open questions (propose adding to project-prd-signals.md)
- OQ-B — price granularity: is a bulk price set per product/SKU, per product × grade, per product × region, per product × grade × region, or ad-hoc per deal? Fixes the price key. [VC]
- OQ-C — validity window: how long is a bulk price valid — 1 week / until next auction, ~30 days, or per-negotiation? And is quote validity the same clock or separate? [VC] (The prototype illustrates one candidate: an editable “effective from” date with validity computed as +7 days from it — a concrete design to react to, not a confirmed answer.)
- OQ-G — private-label pricing: does private-label pricing share this model (per-unit finished-goods price with its own build-up) or is it quoted bespoke per deal only? Scopes whether the price model is bulk-only or catalog-wide. [VC] (Partially touched: the prototype’s additional-cost-line mechanism is available on any quote, bulk or private-label — but private-label catalog pricing itself remains flat/single-price, not region-linked.)
9. Research Method & Caveats
- Method: synthesis of the existing discovery corpus (esp.
sri-lanka-tea-industry.md), the current PRD/prototype model, a partial automated deep-research run (fan-out web search + adversarial verification), and established data-modeling patterns. - The deep-research run was truncated by an org monthly spend limit partway through verification: of 25 claims queued, 6 were independently confirmed [V], 1 refuted, 18 could not complete verification (marked [S] here — they come from real fetched sources but were not adversarially re-verified). Domain price figures are illustrative of spreads/behaviour, not current market values.
- Post-run recovery: the run’s search + source-fetch + claim-extraction phases did complete before the limit hit. The full set of extracted claims from all completed fetch agents was subsequently recovered from the run’s
journal.jsonland folded into §2 and §4–§7 — so no fetched source content was lost. Only the automated adversarial re-verification of the [S] claims and the auto-synthesis step were skipped (synthesis was done here by hand). - Everything price-business-specific to Empire is [VC] and gated behind the §8 open questions — the schema is designed to flex to whichever answers come back.
- Prototype build (2026-07-17): a client-facing prototype (
.forge/design/prototypes/crm/) was built to demonstrate this design — the bulk vs. finished-goods catalog distinction, a price-by-destination-market table with a line-graph history (filterable by region) and a full-history drawer, a weekly “Update this week’s price” workflow, market-linked quote pricing, additional cost lines, and stale-price refresh. Building it surfaced one net-new feature (quote_cost_line, §7) and two deliberate simplifications versus the schema above (per-quote vs. per-line-item staleness, §5; stored vs. computed status, §7) — all folded into this document. Everything else in the prototype (numbers, dates) is illustrative demo data, not real Empire figures.
10. Sources
Domain (bulk tea pricing):
- Forbes & Walker — Weekly Tea Market Reports / National Sale Averages —
forbestea.com/market-reports(+ sale PDF) [primary] - teasrilanka.org — weekly market reports [primary]
- economynext.com — per-elevation weekly auction averages [secondary]
- historyofceylontea.com — auction-vs-FOB price relationship + 2024 USD benchmarks [secondary]
- esilkroute.com.lk — Ceylon BOP/FBOP procurement primer (exporter voice) [blog]
- srilankaexport.com — bulk quoting mechanics (FOB/CIF delta, order sizing) [practitioner]
- impratea.com — auction cadence + ~2-week sample-to-sale lead time [blog]
- ceylonteabrokers.com — corroborates multiple parallel broker weekly reports [primary broker]
- ceylongoodness.com — grade taxonomy (second price axis) [secondary]
- dailymirror.lk — FX / LKR depreciation driver [secondary]
- researchgate.net — academic model keying CTA prices at (elevation × grade × week) [academic]
- Existing internal research:
sri-lanka-tea-industry.md,tea-export-domain-notes.md
CRM / temporal-pricing modeling:
- PostgreSQL docs — range types / temporal tables [primary]
- clarkdave.net — historical records with PG range types + SQL:2011 [blog]
- dbt docs — effective-dated dimensions / point-in-time join [secondary]
- Wikipedia — Slowly Changing Dimension (Type 2) [secondary]
- aiven.io / softwarepatternslexicon.com — bitemporal modeling [blog]
- HubSpot developer docs — product vs line-item model, snapshot/tiered pricing [primary]; dealhub.io — quote-line structure + price-refresh action [secondary]
- cybertec-postgresql.com — products/prices/orders schema in Postgres [vendor]; marclinster.medium.com — SCD2 in Postgres (daterange + btree_gist EXCLUDE) [blog]; naveennegi (Medium) — valid-from/to vs event-sourced vs range trade-offs [blog]