Cost sales first-in-first-out per branch instead of at an average

Cost of goods sold used each product's average buying price across the
whole business. Ten jerrycans bought at 100 and ten at 140, with 15 sold,
cost 1,800 instead of the 1,700 actually paid for those units; a branch
that bought dearer was costed like one that bought cheaper; and units
moved between branches lost their cost.

src/lib/server/costing.ts replays the stock ledger in order with cost
layers per branch and product:
- purchases add stock at their unit cost; transfers carry the sending
  branch's layers to the receiving branch; opening stock and upward counts
  are valued at the product's purchase price at the time;
- sales take the oldest layers first, and that is cost of goods sold;
- stock written off by counts or adjustments is a separate "stock losses"
  figure, now deducted in net profit;
- a sale recorded before its stock (stock gone negative) is costed by the
  next stock to arrive at that branch, even after the period ended; until
  then it is reported as units with no purchase cost on record.

The report shows the method and a Stock losses card. Sales recorded
before the stock ledger existed are counted as uncosted.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

src/app/admin/reports/page.tsx

@@ -18,6 +18,7 @@ interface ProfitReport {
   unitsSold: number;
   costOfGoodsSold: number;
   unitsWithoutCost: number;
+  stockLosses: number;
   grossProfit: number;
   expenses: number;
   expenseCount: number;
@@ -121,8 +122,9 @@ export default function ReportsPage() {
       ["  M-Pesa", report.mpesaTotal],
       ["Sales count", report.salesCount],
       ["Units sold", report.unitsSold],
-      ["Cost of goods sold (average purchase cost)", report.costOfGoodsSold],
+      ["Cost of goods sold (FIFO per branch)", report.costOfGoodsSold],
       ["Units sold with no purchase cost on record", report.unitsWithoutCost],
+      ["Stock losses (counts and write-offs)", report.stockLosses],
       ["Gross profit", report.grossProfit],
       ["Expenses", report.expenses],
       ["Estimated net profit", report.netProfit],
@@ -248,7 +250,7 @@ export default function ReportsPage() {
                 <p className="text-xs uppercase tracking-wide text-depth-500">Cost of goods sold</p>
                 <p className="mt-1 font-display text-2xl font-bold text-depth-900">{money(report.costOfGoodsSold)}</p>
                 <p className="mt-1 text-xs text-depth-500">
-                  {report.unitsSold} units sold x average buying price
+                  {report.unitsSold} units sold, each at what its branch paid for its oldest stock (first in, first out)
                   {report.unitsWithoutCost > 0 && ` · ${report.unitsWithoutCost} units have no purchase cost on record`}
                 </p>
               </div>
@@ -272,11 +274,11 @@ export default function ReportsPage() {
                 >
                   {money(report.netProfit)}
                 </p>
-                <p className="mt-1 text-xs text-depth-500">Gross profit − expenses</p>
+                <p className="mt-1 text-xs text-depth-500">Gross profit − expenses − stock losses</p>
               </div>
             </div>
 
-            <div className="grid grid-cols-1 gap-3 sm:grid-cols-2">
+            <div className="grid grid-cols-1 gap-3 sm:grid-cols-2 lg:grid-cols-3">
               <div className="rounded-xl2 bg-white p-5 shadow-soft">
                 <p className="text-xs uppercase tracking-wide text-depth-500">Stock purchased</p>
                 <p className="mt-1 font-display text-2xl font-bold text-depth-900">{money(report.stockPurchases)}</p>
@@ -290,6 +292,15 @@ export default function ReportsPage() {
                 <p className="mt-1 font-display text-2xl font-bold text-depth-900">{money(report.cashSurplus)}</p>
                 <p className="mt-1 text-xs text-depth-500">Sales − stock purchased − expenses</p>
               </div>
+              <div className="rounded-xl2 bg-white p-5 shadow-soft">
+                <p className="text-xs uppercase tracking-wide text-depth-500">Stock losses</p>
+                <p className={"mt-1 font-display text-2xl font-bold " + (report.stockLosses > 0 ? "text-alert-600" : "text-depth-900")}>
+                  {money(report.stockLosses)}
+                </p>
+                <p className="mt-1 text-xs text-depth-500">
+                  Cost of stock written off by counts, breakage or adjustments. Deducted in net profit.
+                </p>
+              </div>
             </div>
 
             <div className="flex items-center justify-between rounded-xl2 border border-depth-200 bg-sand-100 px-4 py-3">

src/app/api/reports/profit/route.ts

@@ -6,6 +6,7 @@ import { Purchase } from "@/lib/server/models/Purchase";
 import { Expense } from "@/lib/server/models/Expense";
 import { authorize, badRequest, branchParam, MANAGERS } from "@/lib/server/auth";
 import { dayRangeNairobi, isBusinessDate, startOfMonthNairobi } from "@/lib/server/businessDay";
+import { costOfGoodsSold as fifoCost } from "@/lib/server/costing";
 
 export const runtime = "nodejs";
 export const dynamic = "force-dynamic";
@@ -15,11 +16,13 @@ export const dynamic = "force-dynamic";
  *
  * Management overview, NOT accounting (full accounting is out of the PRD's scope).
  *   Revenue            SUCCESS sales in the period
- *   Cost of goods sold units sold x that product's average purchase cost
- *                      (all purchases up to the end of the period)
+ *   Cost of goods sold first-in-first-out per branch: each unit sold costs
+ *                      what that branch paid for its oldest stock on hand
+ *                      (see src/lib/server/costing.ts)
  *   Gross profit       revenue - cost of goods sold
  *   Expenses           operating expenses in the period
- *   Net profit         gross profit - expenses
+ *   Stock losses       cost of stock written off by counts and adjustments
+ *   Net profit         gross profit - expenses - stock losses
  * Shown separately, because buying stock is not the same as using it:
  *   Stock purchased    cash spent on stock in the period
  *   Cash surplus       revenue - stock purchased - expenses
@@ -47,7 +50,7 @@ export async function GET(req: NextRequest) {
   const branchObjId = branchId ? new mongoose.Types.ObjectId(branchId) : null;
   const inPeriod = { businessId: businessObjId, createdAt: { $gte: from, $lt: to }, ...(branchObjId ? { branchId: branchObjId } : {}) };
 
-  const [salesByProduct, avgCosts, purchaseAgg, expenseAgg] = await Promise.all([
+  const [salesByProduct, cost, purchaseAgg, expenseAgg] = await Promise.all([
     Transaction.aggregate<{
       _id: Types.ObjectId;
       revenue: number;
@@ -68,12 +71,7 @@ export async function GET(req: NextRequest) {
         },
       },
     ]),
-    // Average buying price per product across the business (suppliers
-    // charge every branch alike), using everything bought up to period end.
-    Purchase.aggregate<{ _id: Types.ObjectId; cost: number; qty: number }>([
-      { $match: { businessId: businessObjId, productId: { $ne: null }, createdAt: { $lt: to } } },
-      { $group: { _id: "$productId", cost: { $sum: "$totalCost" }, qty: { $sum: "$quantity" } } },
-    ]),
+    fifoCost(auth.businessId, { from, to, branchId }),
     Purchase.aggregate<{ total: number; count: number }>([
       { $match: inPeriod },
       { $group: { _id: null, total: { $sum: "$totalCost" }, count: { $sum: 1 } } },
@@ -84,19 +82,18 @@ export async function GET(req: NextRequest) {
     ]),
   ]);
 
-  const avgCost = new Map(avgCosts.filter((c) => c.qty > 0).map((c) => [c._id.toString(), c.cost / c.qty]));
-  let revenue = 0, cashTotal = 0, mpesaTotal = 0, salesCount = 0, unitsSold = 0, unitsWithoutCost = 0, costOfGoodsSold = 0;
+  let revenue = 0, cashTotal = 0, mpesaTotal = 0, salesCount = 0, unitsSold = 0;
   for (const s of salesByProduct) {
     revenue += s.revenue;
     cashTotal += s.cashTotal;
     mpesaTotal += s.mpesaTotal;
     salesCount += s.lines;
     unitsSold += s.units;
-    const unitCost = avgCost.get(s._id.toString());
-    if (unitCost === undefined) unitsWithoutCost += s.units;
-    else costOfGoodsSold += s.units * unitCost;
   }
-  costOfGoodsSold = Math.round(costOfGoodsSold * 100) / 100;
+  const costOfGoodsSold = cost.costOfGoodsSold;
+  // Sales recorded before the stock ledger existed have no stock movement,
+  // so FIFO cannot cost them: count them as uncosted too.
+  const unitsWithoutCost = Math.max(cost.unitsWithoutCost, unitsSold - cost.unitsCosted);
 
   const stockPurchases = purchaseAgg[0]?.total ?? 0;
   const expenses = expenseAgg[0]?.total ?? 0;
@@ -111,13 +108,15 @@ export async function GET(req: NextRequest) {
     salesCount,
     unitsSold,
     costOfGoodsSold,
-    // Units sold of products never bought through Purchases: their cost
-    // is unknown, so gross profit overstates by their cost.
+    costMethod: "FIFO per branch",
+    // Units sold whose cost is unknown (no purchase price for that stock on
+    // record): gross profit overstates by their cost.
     unitsWithoutCost,
+    stockLosses: cost.stockLosses,
     grossProfit,
     expenses,
     expenseCount: expenseAgg[0]?.count ?? 0,
-    netProfit: Math.round((grossProfit - expenses) * 100) / 100,
+    netProfit: Math.round((grossProfit - expenses - cost.stockLosses) * 100) / 100,
     stockPurchases,
     purchaseCount: purchaseAgg[0]?.count ?? 0,
     cashSurplus: Math.round((revenue - stockPurchases - expenses) * 100) / 100,

src/lib/server/costing.ts

@@ -0,0 +1,194 @@
+import mongoose, { Types } from "mongoose";
+import { StockMovement, type MovementType } from "@/lib/server/models/StockMovement";
+import { Purchase } from "@/lib/server/models/Purchase";
+
+/**
+ * Cost of goods sold, first-in-first-out, per branch.
+ *
+ * The stock ledger is replayed in order. Each branch keeps, per product, a
+ * queue of cost layers (quantity at a unit cost). Stock coming in adds a
+ * layer; stock going out takes from the oldest layers first:
+ *
+ *   PURCHASE      in, at the purchase's unit cost
+ *   TRANSFER_IN   in, at the cost of the layers the sending branch gave up
+ *   ADJUSTMENT +  in (opening stock, a count that found more), at an
+ *                 estimated cost: the latest purchase price for the product
+ *                 at that time, or the first one after it if none yet
+ *   SALE          out: its cost is cost of goods sold
+ *   TRANSFER_OUT  out: its cost travels with the stock to the other branch
+ *   ADJUSTMENT -  out (breakage, a count that found less): its cost is a
+ *                 stock loss, reported separately from cost of goods
+ *
+ * Stock can go negative (an offline sale recorded before the stock it came
+ * from). The units sold short wait as a deficit and are costed by the next
+ * stock that arrives at that branch, which is where they must have come
+ * from. Units still uncosted at the end are reported as unitsWithoutCost.
+ *
+ * The replay reads the whole history, in order, so a sale is costed against
+ * what was actually on hand when it happened, whatever period is being
+ * reported; only events inside the period (and branch) are added up. A sale
+ * made short in the period is costed by stock that arrived later, even
+ * after the period ended.
+ */
+
+type Id = Types.ObjectId | string;
+
+interface Layer {
+  qty: number;
+  unitCost: number | null; // null: cost unknown
+}
+
+interface Deficit {
+  qty: number;
+  kind: "sale" | "loss" | "transfer";
+  counts: boolean; // inside the reported period and branch
+}
+
+interface Position {
+  layers: Layer[];
+  deficits: Deficit[];
+}
+
+export interface CostOfGoods {
+  costOfGoodsSold: number;
+  unitsCosted: number; // units sold in the period that have a cost
+  unitsWithoutCost: number; // units sold in the period whose cost is unknown
+  stockLosses: number; // cost of stock written off by counts or adjustments in the period
+}
+
+// Process transfers' outgoing side before the incoming side, so the cost is known.
+const TYPE_ORDER: Record<MovementType, number> = {
+  PURCHASE: 0,
+  ADJUSTMENT: 1,
+  TRANSFER_OUT: 2,
+  TRANSFER_IN: 3,
+  SALE: 4,
+};
+
+const round2 = (n: number) => Math.round(n * 100) / 100;
+
+/** Take `qty` units from the front of `layers`; returns what was taken and the shortfall. */
+function take(layers: Layer[], qty: number): { taken: Layer[]; short: number } {
+  const taken: Layer[] = [];
+  let need = qty;
+  while (need > 0 && layers.length > 0) {
+    const head = layers[0];
+    const n = Math.min(head.qty, need);
+    taken.push({ qty: n, unitCost: head.unitCost });
+    head.qty -= n;
+    need -= n;
+    if (head.qty === 0) layers.shift();
+  }
+  return { taken, short: need };
+}
+
+export async function costOfGoodsSold(
+  businessId: Id,
+  period: { from: Date; to: Date; branchId?: Id | null }
+): Promise<CostOfGoods> {
+  const biz = new mongoose.Types.ObjectId(businessId.toString());
+  const branchFilter = period.branchId ? period.branchId.toString() : null;
+
+  const [movements, purchases] = await Promise.all([
+    StockMovement.find({ businessId: biz })
+      .select("branchId productId type quantity refId createdAt")
+      .sort({ createdAt: 1, _id: 1 })
+      .lean(),
+    Purchase.find({ businessId: biz, productId: { $ne: null } })
+      .select("productId unitCost createdAt")
+      .sort({ createdAt: 1 })
+      .lean(),
+  ]);
+  movements.sort(
+    (a, b) => a.createdAt.getTime() - b.createdAt.getTime() || TYPE_ORDER[a.type] - TYPE_ORDER[b.type]
+  );
+
+  const purchaseCost = new Map(purchases.map((p) => [p._id.toString(), p.unitCost]));
+  const priceHistory = new Map<string, { at: number; unitCost: number }[]>();
+  for (const p of purchases) {
+    const key = p.productId!.toString();
+    if (!priceHistory.has(key)) priceHistory.set(key, []);
+    priceHistory.get(key)!.push({ at: p.createdAt.getTime(), unitCost: p.unitCost });
+  }
+  const estimateCost = (productId: string, at: number): number | null => {
+    const history = priceHistory.get(productId);
+    if (!history || history.length === 0) return null;
+    let latest: number | null = null;
+    for (const h of history) {
+      if (h.at <= at) latest = h.unitCost;
+      else break;
+    }
+    return latest ?? history[0].unitCost;
+  };
+
+  const positions = new Map<string, Position>();
+  const position = (branch: string, product: string) => {
+    const key = `${branch}:${product}`;
+    if (!positions.has(key)) positions.set(key, { layers: [], deficits: [] });
+    return positions.get(key)!;
+  };
+  const inTransit = new Map<string, Layer[]>(); // transfer refId -> layers given up by the sender
+
+  const result = { costOfGoodsSold: 0, unitsCosted: 0, unitsWithoutCost: 0, stockLosses: 0 };
+  const charge = (kind: Deficit["kind"], layers: Layer[]) => {
+    for (const l of layers) {
+      if (kind === "sale") {
+        if (l.unitCost === null) result.unitsWithoutCost += l.qty;
+        else {
+          result.costOfGoodsSold += l.qty * l.unitCost;
+          result.unitsCosted += l.qty;
+        }
+      } else if (kind === "loss" && l.unitCost !== null) {
+        result.stockLosses += l.qty * l.unitCost;
+      }
+    }
+  };
+
+  for (const m of movements) {
+    const branch = m.branchId.toString();
+    const product = m.productId.toString();
+    const pos = position(branch, product);
+    const at = m.createdAt.getTime();
+    const counts =
+      at >= period.from.getTime() && at < period.to.getTime() && (!branchFilter || branch === branchFilter);
+
+    if (m.quantity > 0) {
+      let incoming: Layer[];
+      if (m.type === "PURCHASE") incoming = [{ qty: m.quantity, unitCost: purchaseCost.get(m.refId) ?? null }];
+      else if (m.type === "TRANSFER_IN") incoming = (inTransit.get(m.refId) ?? [{ qty: m.quantity, unitCost: null }]).map((l) => ({ ...l }));
+      else incoming = [{ qty: m.quantity, unitCost: estimateCost(product, at) }];
+
+      // Stock that was already sold short is covered first, at this stock's cost.
+      while (pos.deficits.length > 0 && incoming.length > 0) {
+        const d = pos.deficits[0];
+        const { taken, short } = take(incoming, d.qty);
+        if (d.counts) charge(d.kind, taken);
+        d.qty = short;
+        if (d.qty === 0) pos.deficits.shift();
+      }
+      pos.layers.push(...incoming);
+    } else if (m.quantity < 0) {
+      const kind: Deficit["kind"] = m.type === "SALE" ? "sale" : m.type === "TRANSFER_OUT" ? "transfer" : "loss";
+      const { taken, short } = take(pos.layers, -m.quantity);
+      if (kind === "transfer") {
+        // The receiving branch inherits this cost; any shortfall arrives with no known cost.
+        inTransit.set(m.refId, short > 0 ? [...taken, { qty: short, unitCost: null }] : taken);
+      } else if (counts) {
+        charge(kind, taken);
+      }
+      if (short > 0) pos.deficits.push({ qty: short, kind, counts: counts && kind !== "transfer" });
+    }
+  }
+
+  // Short sales in the period that no later stock has covered yet.
+  for (const pos of positions.values()) {
+    for (const d of pos.deficits) if (d.counts && d.kind === "sale") result.unitsWithoutCost += d.qty;
+  }
+
+  return {
+    costOfGoodsSold: round2(result.costOfGoodsSold),
+    unitsCosted: result.unitsCosted,
+    unitsWithoutCost: result.unitsWithoutCost,
+    stockLosses: round2(result.stockLosses),
+  };
+}