Carton / Variant Split & Stock Transformation

Overview

The Variant Split / Stock Transformation tool turns one item you already have in stock into one or more other products you can sell or use. Cartons become bottles, kilograms become grams, whole carcasses become cuts, gift hampers become their contents. Stock and cost move together automatically.

Who it is for

• Shop staff — open cartons, weigh portions, break bulk goods into sellable units.
• Supervisors — oversee changes and sign off when stock is lost.
• Store managers — need every gram, naira and piece to add up.

Four presets at a glance

What the tool guarantees

• Cost follows the goods. Money never lost, never invented.
• Measures convert correctly. 2 kg → exactly 2,000 g — not “2”.
• Loss shown before you commit. “200 kg in − 145 kg out = 55 kg loss (27.5%)” — visible live.
• Approval only when stock is actually lost. Clean conversions save instantly; lossy ones create a reviewable record.
• All-or-nothing. The whole transformation goes through, or none of it does.

Watch out: If a measure conversion isn’t set up (e.g. kg → g unknown), the tool stops and tells you rather than guess. Ask an admin to add it in Unit Conversions.

Key Concepts

Source item and Target item(s)

The source item is what you start with (the carton, the cow). The target item(s) are what you end up with (the bottles, the cuts). Always exactly one source; can be one or many targets.

Cost follows the goods

The money you paid for the source moves with the stock into the targets. A ₦1,200 carton of 12 bottles means each bottle carries ₦100. Nothing disappears.

Value weight

A number that says how valuable a target is relative to others. Higher = bigger share of the total cost. Defaults to the selling price. Fillet at 5.0 carries far more of a cow’s ₦400,000 than Bone at 0.2.

Conserving vs Lossy

• Conserving: Nothing lost — everything that goes in comes out (carton → bottles, kg → g). Saves instantly, no approval.
• Lossy: Some stock genuinely gone (cow → cuts with 27.5% loss). Creates a reviewable record for supervisor approval.

Unit conversion / conversion rate

When a target uses a different unit from the source (kg → g), the conversion rate (1 kg = 1,000 g) calculates the new quantity automatically. Set up once by an admin.

Walkthrough — Break a Carton into Units

Example: 1 carton of soft drinks = 12 single bottles. Carton cost ₦1,200 → each bottle should be ₦100.

1. Open Break Carton from the inventory menu.
2. Select “Soft Drink — Carton”. Header shows available stock.
3. Enter 1 carton to break. This is the only quantity you type.
4. Form shows target product (“Soft Drink — Bottle”) — existing or newly created.
5. Auto-fills: 1 × 12 = 12 bottles.
6. Footer shows: ₦1,200 total cost ÷ 12 = ₦100 per bottle.
7. After-balance: Cartons 5 → 4. Bottles 0 → 12.
8. Confirm and save.

Why no approval: This is conserving — nothing is lost. Every bit of stock and value lands in the bottles.

What you end up with

• 1 carton gone.
• 12 bottles added, each valued at ₦100.
• The ₦1,200 preserved across them.
• No approval document — saved and final.

Walkthrough — Convert Kilograms to Grams

Example: 10 kg sack of rice at ₦1,000/kg. Convert 2 kg into grams.

Key idea: You tell the screen how much to take from the sack in the sack’s measure (kg). The system knows the conversion and calculates the grams. You never type the grams.

1. Open Convert Measure.
2. Select the rice (sold by kg). Header shows 10 kg available.
3. Choose “to” measure — grams.
4. In “amount to take” field, type 2 (kg).
5. System calculates: 2 × 1,000 = 2,000 g.
6. Cost: 2 kg × ₦1,000 = ₦2,000 ÷ 2,000 g = ₦1 per gram.
7. Sack now reads 8 kg.
8. Loss = 0. Saves instantly.
9. Click Save.

If no conversion exists: The screen stops you and points to Unit Conversions admin screen. Nothing is saved — the system will never guess a conversion rate.

Walkthrough — Portion a Carcass into Cuts

Example: 200 kg cow at ₦400,000 → Fillet, Shin, Ribs, Bone + 55 kg loss.

This is the heavyweight mode. Breaking a carton or converting a measure is tidy — what goes in matches what comes out. Portioning a carcass is different: one thing goes in, several different things come out, and some is genuinely lost.

Before you start

• The whole item in stock (cow, 200 kg, ₦400,000).
• Rough idea of cuts and selling prices.
• A scale — this screen runs on actual weights.

Step by step

1. Open Disassemble / Portion. Select the cow. Header shows 200 kg available.

2. Enter source consumed: Type 200 (kg). This is what gets taken out of the cow’s stock — NOT the sum of cut weights. The gap between input and output IS the loss.

3. Add a row for each cut. Four rows:

   Cut	Actual weight	Value weight
   Fillet	30 kg	5.0
   Shin	40 kg	2.0
   Ribs	35 kg	1.5
   Bone	40 kg	0.2

   Each cut becomes its own separate product. Value weight defaults from selling price — override if needed.

4. Watch the cost split live. The footer divides ₦400,000 by value weight:

   Cut	Cost carried	Per kg
   Fillet	≈ ₦206,540	≈ ₦6,885/kg
   Shin	≈ ₦110,150	≈ ₦2,754/kg
   Ribs	≈ ₦72,290	≈ ₦2,065/kg
   Bone	≈ ₦11,020	≈ ₦276/kg
   Total	₦400,000

   The four always add back to ₦400,000.

5. Read the loss readout: Input 200 kg − Output 145 kg = 55 kg lost (27.5%). Live, before commit. Turns amber when loss exceeds threshold.

6. Give a loss reason. E.g. “Trim & wastage — normal carcass trim, blood, bone dust.”

7. Submit. Creates a reviewable record marked Awaiting review. A supervisor approves, then stock moves.

Incommensurable case: If a cut uses a different measure (e.g. hide = 1 piece), the system gives you the loss field to type in yourself, labelled as operator-entered.

Why the recorded loss matters

You can compare batches over time:

Spot patterns, ask questions, protect margins.

Walkthrough — Unbundle a Composite Pack

Example: 1 Breakfast Hamper = 1 cereal + 2 milk + 1 honey → separate sellable items.

Big reassurance: The hamper’s recipe is permanent. Opening unbundling never changes or deletes it. Cancel freely with zero damage.

1. Open Unbundle Composite. Select Breakfast Hamper.
2. Check header — name, barcode, available quantity.
3. Enter quantity: 1.
4. Review auto-filled contents from recipe: 1 cereal, 2 milk, 1 honey.
5. Confirm quantities. Cost is shared by item value — pricier items carry more. Always adds back to hamper’s cost.
6. Check loss line: No loss (green) → saves instantly. Loss (amber) → reviewable record with reason.
7. Submit.

What you end up with

• 1 fewer Breakfast Hamper.
• 1 cereal, 2 milk, 1 honey as separate sellable items with fair cost shares.
• Recipe intact for future use.

Cost Sharing in Depth

When you split one item into several, two questions arise: “What does each new product cost?” and “How much did I lose?”

How cost is shared

Each cut gets a slice of the ₦400,000 by qty × value weight, not just by weight.

Step 1 — Share points:

Step 2 — Each cut’s share: Points ÷ total points × ₦400,000

What if all weights are zero? The sharing only works if at least one target has value weight > 0. If all are zero, the form stops you. A weight of zero on one row means pure waste (carries quantity but no cost).

Loss in your real measure

Important: The cost still stays in the cuts. The loss line records missing weight, not a second money deduction.

Approvals, Corrections and the Record Trail

When approval is needed

• No loss → no approval needed. Saves instantly.
• Loss → needs approval. Stock is held pending until a supervisor signs off.

The approval flow

1. Staff submits lossy transformation → Pending Approval.
2. Supervisor reviews: source consumed, outputs with costs, loss amount and %, reason.
3. Approve (stock moves) or reject (stock stays, fix and resubmit).

Making corrections

• Before submission: Clear the form and start over.
• After submission, before approval: Withdraw, fix, resubmit.
• After approval: Use a reversal document (stock adjustment).

What the record contains

• Date, time, user performing the transformation.
• Source: item, qty consumed, unit cost, total cost.
• Each target: item, qty added, allocated cost, cost per unit.
• Loss: quantity, percentage, reason.
• Approval: status, approver, timestamp.
• Reversal reference (if later corrected).

Common Problems

Quick Glossary

Stock Transformation — Test & Training Walkthrough

For: shop staff, supervisors and store managers testing the new
Stock Transformation tool for the first time.
You do not need to be technical. If you can count cartons, read a
weighing scale and follow numbered steps, you can complete every test here.

This guide walks you through five real jobs, one click at a time. For
each one it tells you exactly what to click, what to type, and — just as
important — what you should see on the screen so you can confirm it
worked. Tick the ✅ checklist at the end of each case.

What this tool does, in one line: it takes one thing you already have
in stock (a carton, a sack, a whole cow, a gift hamper) and turns it into
one or more other products, moving the stock and the money correctly and
automatically.

Table of contents

1. Before you start
2. A quick tour of the screen
3. Use Case 1 — Break a carton into single units
4. Use Case 2 — Convert kilograms into grams
5. Use Case 3 — Portion a whole cow into cuts
6. Use Case 4 — Unbundle a composite hamper
7. Use Case 5 — Safety checks (the tool protecting you)
8. Final acceptance checklist
9. Quick glossary

Before you start

Have these ready before you begin testing:

• A few test products in stock at your working location:
  • a carton item with a known “units per carton” (e.g. Soft Drink — Carton, 12 per carton),
  • a bulk-by-weight item (e.g. Rice, sold in kg, with stock on hand),
  • a whole item to cut up (e.g. Beef — Whole, in kg),
  • a composite/bundle item with a saved recipe (e.g. Breakfast Hamper).
• Permission to manage stock. If the item is a raw material, the tool
  will ask you to confirm extra permission before it opens — that is normal.
• A manager/approver name handy for the cases that record a loss (you can
  also leave approval for later).

Note: These transformation actions appear on a classic-account
setup. If you don’t see them, check with your administrator.

Where to find the tool

You don’t hunt through menus — the tool lives on the item:

1. Open your inventory list (your list of products).
2. Click the item you want to transform so it is selected/highlighted.
3. Right-click the item (or open the actions sidebar) and choose the
   action for the job:
   • Break Carton — open a carton into single units
   • Convert Measure — change a measure into a finer one (kg → g)
   • Disassemble / Portion — cut one whole thing into several products
   • Unbundle Composite — break a bundle back into its contents

Each opens the same form, already set up for the job you picked.

A quick tour of the screen (read once)

Every transformation opens the same window. Learn it once and all five cases
feel familiar.

┌───────────────────────────────────────────────────────────────────────┐
│ Break Carton                                                           │  ← title = the job
│ Open one or more cartons into their single sellable units.             │  ← one-line description
│ ┌──────────┐ ┌──────────┐ ┌────────────┐ ┌────────────┐               │
│ │ SOURCE   │ │ SKU      │ │ SOURCE UOM │ │ AVAILABLE  │               │  ← read-only info cards
│ │ Soft…    │ │ 60012…   │ │ carton     │ │ 5 carton   │               │
│ └──────────┘ └──────────┘ └────────────┘ └────────────┘               │
│ Cartons to break: [ 1 ]            Approver: [ (optional) ▼ ]          │  ← what YOU enter
│ ─────────────────────────────────────────────────────────────────────│
│ Child | SKU | Variant | Size | Child UoM | Qty | Value Weight | …| →   │  ← the target table
│ Soft Drink — Bottle | … |     |      | unit | 12 | 100 | ₦100 | ₦1,200 │
│                                                                        │
│ Conserving — no loss. Saves directly, no approval needed.   (green)    │  ← the LIVE loss readout
│ ┌────────────────────┐ ┌──────────────┐                               │
│ │ TOTAL SOURCE COST  │ │ SOURCE AFTER │           [ Cancel ] [ Save ] │  ← totals + buttons
│ │ ₦1,200             │ │ 4 carton     │                               │
│ └────────────────────┘ └──────────────┘                               │
└───────────────────────────────────────────────────────────────────────┘

Three things to keep your eye on before you click Save:

• The loss readout (the coloured line in the middle): green = nothing
  lost, saves straight away; amber = some stock is lost, this becomes a
  record a manager reviews; red = something is wrong (fix it before
  saving).
• SOURCE AFTER: what the original item will read after you save. If it
  turns red, you’re trying to use more than you have — stop.
• TOTAL SOURCE COST: the money being carried over into the new products.

Golden rule: You only ever type how much of the source to use. The
tool works out the new product quantities, the costs and the loss for you.

Use Case 1 — Break a carton into single units

The job: open 1 carton of soft drinks into 12 single bottles.
The carton cost ₦1,200, so each bottle should carry ₦100. Nothing is lost.

Steps

1. In the inventory list, click Soft Drink — Carton to select it.
2. Right-click → Break Carton. The form opens with the title “Break Carton”.
3. Check the info cards at the top:
   • SOURCE = Soft Drink — Carton
   • SOURCE UOM = carton
   • AVAILABLE = your current cartons (say 5 carton)
4. In “Cartons to break:” type 1.
5. Look at the table row underneath — you did not type this, the tool
   filled it in:
   • Child = Soft Drink — Bottle, Child UoM = unit, Qty = 12
6. (Optional) In Selling Price type the bottle’s price, e.g. 100.
   (You may also leave it — it just sets the cost-sharing weight.)
7. Read the green line: “Conserving — no loss. Saves directly, no approval needed.”
8. Check the footer: TOTAL SOURCE COST ≈ ₦1,200, SOURCE AFTER = 4 carton.
9. Click Save Transformation.
10. You should see: “Transformation saved. 1 target(s) updated.”

✅ Test checklist

• [ ] The Qty filled itself in as 12 when you typed 1 carton.
• [ ] The loss line was green (“no loss”).
• [ ] No approver was needed — it saved immediately.
• [ ] Back in inventory: Soft Drink — Carton dropped by 1 (5 → 4).
• [ ] Soft Drink — Bottle now shows 12 in stock (created if it
  didn’t exist), each carrying about ₦100 cost.
• [ ] Add it up: 12 × ₦100 = ₦1,200 — the carton’s full value carried over.

Try also: change “Cartons to break” to 2 and watch Qty jump to
24 and SOURCE AFTER drop to 3 on its own.

Use Case 2 — Convert kilograms into grams

The job: take 2 kg from a 10 kg sack of Rice (₦1,000/kg) and turn
it into a 2,000 g loose-rice product. Nothing is lost.

Steps

1. Select Rice in the inventory list.
2. Right-click → Convert Measure. Title reads “Convert Measure”.
3. Cards show SOURCE UOM = kg, AVAILABLE = 10 kg.
4. In “Amount to take (kg):” type 2.
5. In “Convert to:” type the smaller unit — g (grams).
6. Watch the single table row fill in: Qty = 2000, Child UoM = g.
   • This used the saved rule 1 kg = 1,000 g. You did not calculate it.
7. Read the green line: “Conserving — no loss…”.
8. Footer: TOTAL SOURCE COST ≈ ₦2,000; SOURCE AFTER = 8 kg.
9. (Optional) set the new product’s Selling Price per gram.
10. Click Save Transformation → “Transformation saved. 1 target(s) updated.”

✅ Test checklist

• [ ] Typing 2 (kg) produced 2,000 (g) automatically.
• [ ] The sack reads 8 kg afterwards (it dropped by the 2 kg you took,
  not by 2,000).
• [ ] The 2,000 g product carries ₦2,000 total (about ₦1 per gram).
• [ ] Loss line was green; no approval needed.

🔴 Important sub-test — what happens with no conversion set up

Try converting to a unit the system doesn’t know yet (e.g. scoop):

1. In “Convert to:” type scoop.
2. The middle line turns red: “No conversion kg → scoop. Add it on the
   Unit Conversions screen.”
3. Click Save Transformation. It refuses, and nothing is changed —
   the sack is still 10 kg.

• [ ] The tool stopped you rather than guessing a wrong amount.
• [ ] Your stock was untouched.
• [ ] (Admin) After adding the kg → scoop conversion on the Unit Conversions
  screen, repeating the steps now works.

Use Case 3 — Portion a whole cow into cuts

The job (the big one): cut a 200 kg cow (bought for ₦400,000) into
four different products. Some weight is genuinely lost as trim — that is
normal, and the screen shows it to you before you save.

(30 + 40 + 35 + 40 = 145 kg out of 200 kg → 55 kg lost.)

Steps

1. Select Beef — Whole in the inventory list.

2. Right-click → Disassemble / Portion. Title reads “Disassemble / Portion”.

   • If asked to confirm raw-material permission, authorise it.

3. In “Whole processed (kg):” type 200 (the whole cow).

   This is the amount taken out of the cow — not the sum of the cuts.

4. The table starts with a few blank rows. Use Add Target / Remove
   Selected to get exactly four rows. For each row type:

   Child (name)	SKU	Child UoM	Qty	Value Weight	Selling Price
   Beef Fillet	BEEF-FIL	kg	30	5.0	(your price)
   Beef Shin	BEEF-SHN	kg	40	2.0	(your price)
   Beef Ribs	BEEF-RIB	kg	35	1.5	(your price)
   Beef Bone	BEEF-BON	kg	40	0.2	(your price)

   Tip: if you set sensible selling prices, you can leave Value
   Weight at 0 and it will default from the price. Here we type the
   weights so the numbers match the example.

5. Watch the → Allocated Cost column fill in live. Fillet should carry the
   biggest slice (≈ ₦206,540) and Bone the smallest (≈ ₦11,000). The
   Total row adds back to ₦400,000.

6. Read the middle line — it is now amber:
   “Input 200 kg − Output 145 kg = 55 kg loss (27.5%) — reviewable loss document.”

7. A Loss reason box has appeared. Type a reason, e.g. trim & bone dust.

8. Choose how it gets approved:

   • To post it now, pick a manager in “Approver:”.
   • To send it for review later, leave Approver blank.

9. Click Save Transformation.

   • With an approver: “Transformation approved and posted (55 kg loss).”
   • Without: “Recorded with 55 kg loss — awaiting review.”

✅ Test checklist

• [ ] The loss line showed 55 kg (27.5%) before you saved — no surprise.
• [ ] It turned amber and required a loss reason.
• [ ] Allocated Cost for the cuts added back to ₦400,000 (Fillet ≫ Bone).
• [ ] The cow dropped by 200 kg (only on approval, if you left it for review).
• [ ] Each cut became its own product with its own real cost per kg.
• [ ] If left for review: it appears in the review queue as AWAITING_REVIEW;
  a manager approving it then moves the stock.

Try also: delete a weight so the cuts add up to 200 — the loss
drops to 0 and the line turns green (“saves directly”). Put it back
and the amber loss returns. This shows the readout is live.

Use Case 4 — Unbundle a composite hamper

The job: break 1 Breakfast Hamper back into its contents — 1 cereal,
2 milk, 1 honey — using the hamper’s saved recipe.

Steps

1. Select Breakfast Hamper in the inventory list.
2. Right-click → Unbundle Composite. Title reads “Unbundle Composite”.
3. The table is pre-filled from the recipe — you’ll see Cereal, Milk and
   Honey already listed. (You don’t retype these.)
4. In “Packs to unbundle:” type 1.
5. Watch the recipe quantities multiply by your number:
   • Cereal 1, Milk 2, Honey 1. (Type 3 packs and they become
     3 / 6 / 3.)
6. Read the loss line. For a clean hamper it is green
   (“Conserving — no loss”) and will save directly.
7. Check SOURCE AFTER = your hampers minus what you entered.
8. Click Save Transformation → “Transformation saved. N target(s) updated.”

✅ Test checklist

• [ ] The contents were filled in from the recipe (you didn’t type them).
• [ ] Entering 1 pack suggested 1 cereal, 2 milk, 1 honey.
• [ ] Hamper count dropped by the number you entered; the 3 contents went up
  by the right amounts, each carrying a fair share of the hamper’s cost.
• [ ] Most importantly — the recipe is safe: click Cancel (or
  re-open the form) and confirm the Breakfast Hamper still knows its
  recipe (1 cereal, 2 milk, 1 honey). Clearing or cancelling must
  never delete the recipe.

Use Case 5 — Safety checks (the tool protecting you)

These are quick tests to prove the tool refuses to do anything dangerous.
None of them should change your stock.

5a. You can’t use more than you have

1. Open Break Carton (or any mode) on an item with, say, 5 on hand.
2. In the amount field type 9999.
3. Watch SOURCE AFTER turn red (it would go negative).
4. Click Save Transformation → you get “You only have 5 … available.”
   and nothing is saved.

• [ ] Over-using is blocked; stock unchanged.

5b. Every output can’t be worth nothing

1. Open Disassemble / Portion, enter a source amount, add a couple of cuts
   with Qty but leave every Value Weight = 0 and no selling prices.
2. Click Save Transformation → it refuses (it has no way to share the cost).

• [ ] You’re prompted to give at least one price or weight; nothing is saved.

5c. Mixed units it can’t compare (the hide example)

Some by-products are counted differently from the carcass — e.g. a hide
sold as 1 piece while the cuts are in kg.

1. In Disassemble / Portion, add the kg cuts plus a hide row with
   Child UoM = piece, Qty = 1.
2. Because pieces can’t be weighed against kilograms, the loss line says
   “Mixed units — enter the loss in kg…” and a Loss (kg) box appears.
3. Type the trim you actually lost, e.g. 50, and a loss reason.
4. Save (with or without an approver as in Use Case 3).

• [ ] When it can’t work the loss out itself, it asks you rather than
  inventing a number.

5d. Nothing half-finishes

• [ ] If anything fails during a save, no part of it is applied — the
  source is not reduced and no new products appear. It is always safe to
  simply correct the inputs and try again.

Final acceptance checklist

Tick these once across all the cases above:

Quick glossary

• Source — the item you start with (the carton, sack, cow, hamper).
• Target / child — each product you end up with; its own name, barcode,
  price and stock balance.
• Value weight — how prized a target is, used to share the source’s cost.
  Higher weight = bigger slice of the cost. Defaults from selling price.
• Conserving — nothing lost; saves straight away, no approval.
• Lossy — some stock is genuinely lost (trim, wastage); creates a
  reviewable record and asks for a reason.
• Loss readout — the live coloured line: green = no loss, amber = loss
  (review), red = fix something first.
• SOURCE AFTER — what the original item will read once you save.
• Approver — choose one to post a lossy job immediately; leave blank to
  send it for a manager’s review.

Companion documents: design/inventory/inventory_variant_split_tutorial.md
(the in-depth story behind these jobs) and
design/inventory/variant_split.md (the technical specification).