feat: Inventory Investment System (two-stream investor financing)

[Tayebbb]

Inventory Investment System

External investors finance perfume inventory (no equity). Capital is recovered per-ml as funded stock sells; profit is split by a configurable share; investments close via profit-only withdrawals and store buyback. Built across Phases 2–4, hardened and QA'd in Phase 5.

Summary

• Two-stream accounting: Stream A (capital recovery at lot-locked cost/ml, never split, never withdrawable) and Stream B (profit, split investor/business, can go negative on losses).
• Hard invariant enforced in every transaction: amount = recoveredCapital + remainingInventoryCost.
• Fully integrated with the order lifecycle at the existing profit-recognition point (Dispatched), with idempotent processing and exact compensating reversal on cancellation.
• Admin management UI + read-only investor portal with profit-withdrawal requests.

Architecture

• backend/src/lib/investments/finance.ts — pure engine: FIFO allocation, partial-funding planner, sale split, invariant validation, buyback math. Fully unit-tested.
• backend/src/lib/investments/accountingService.ts — createInvestment / processInvestmentSale / recordAdjustment / reverseSalesForOrder, all inside db.runTransaction.
• backend/src/lib/investments/buybackService.ts — quote + atomic execute (per-stream ledger entries; paidProfit = max(0, availableProfit)).
• backend/src/lib/investments/withdrawalService.ts — pending → approved (balance re-validated + deducted in tx) → paid.
• backend/src/lib/investments/orderIntegration.ts — order-lifecycle glue; never throws into order flow.

Business Logic

• Sales consume allocations FIFO (oldest lot first); multi-lot sales prorate revenue/costs by ml, remainder to last lot.
• Oversells use allowPartial: only funded ml is consumed; revenue/costs prorated by funded ml.
• Selling price excludes delivery fee; selling costs = packaging + bottle from the item pricingSnapshot.
• Losses reduce profit (can go negative); capital always recovers in full.
• Personal-collection perfumes can never be investor-funded.

Database / Firestore Changes

New collections (6):

• investors — profile + denormalized totals (ledger-controlled)
• investments — principal, recovered, remaining, availableProfit, withdrawnProfit, status (active|recovering|closed|bought_back)
• investmentAllocations — per-perfume lots: fundedMl / remainingMl / soldMl, locked costPerMlMinor, status (open|depleted|bought_back)
• investmentTransactions — immutable ledger; doc ID = deterministic idempotency key; stream: capital|profit|none; written only via tx.create
• investmentWithdrawals — pending|approved|rejected|paid
• buybacks — closure records

Indexes: none required — all queries are equality-only (merged single-field indexes) or sorted in memory by design.
Rules: unchanged deny-all; Admin SDK is the only writer.

APIs (11 new routes)

Admin: /api/investors (+[id]), /api/investments (+[id], /ledger, /buyback, /reports), /api/investment-withdrawals/[id] (approve/reject/paid).
Investor (session-resolved, IDOR-proof): /api/investor/dashboard, /api/investor/investments/[id], /api/investment-withdrawals (own).
Extended: /api/export?type=investors|investments|investment-ledger; orders/[id] PUT + /cancel wired to investment sale processing/reversal.

Services / Components / Dashboards

• Admin: /admin/investments (tabs: investments / investors / withdrawals, CSV exports) and /admin/investments/[id] (balances, allocations, ledger, buyback, manual adjustments).
• Investor portal: /investor (summary cards, investments table, withdrawal request + history) and /investor/investments/[id] (allocations, stream-filtered ledger).
• Reports endpoint recomputes aggregates on read + invariant health, monthlyBreakdown, byPerfume, withdrawal stats.

Testing

• backend/scripts/test-investments.ts — 84 assertions, all green: golden worked example, FIFO, rounding/integer safety, losses, invariant, buyback math, lifecycle simulation, withdrawal caps, partial-funding planner, reversal restoration, buyback stream separation.
• backend/scripts/check-investments.ts — read-only live reconciliation: invariant, lot capital, ml conservation, full ledger replay (capital + profit streams), investor counters. Exits non-zero on drift.
• Both apps: tsc --noEmit clean, ESLint 0 errors, production builds pass.

Security

• requireInvestor() passes investor OR admin; never satisfies requireAdmin(). All mutating admin endpoints call requireAdmin().
• Investor identity always resolved from the signed session (userId → email), never from query params; foreign investment IDs return 404.
• Replay/duplicate protection: ledger doc IDs are idempotency keys via tx.create + in-transaction ledger query on referenceOrderItemId.
• Defense-in-depth: server-gated layouts + frontend middleware gate on /investor; Firestore client access remains fully denied.

Performance

• All money math is integer minor-units (no float drift).
• Equality-only Firestore queries; no composite indexes needed.
• Ledger/withdrawal listing sorts in memory (documented trade-off to avoid index management at current scale).
• Known tech debt: /api/investments/reports full-scans the investment collections per admin load — fine at current volume, paginate later.

Migration Notes

• No data migration required — all collections are new; existing orders/finances untouched.
• No new environment variables.
• Deploy backend and frontend together (frontend middleware + investor portal expect the new APIs).

Rollback Strategy

• Revert this branch; new collections are additive and inert without the code (no existing feature reads them).
• If investments were created before rollback: export ledger CSVs first (/api/export?type=investment-ledger); balances remain fully reproducible from the immutable ledger at any later date.

Known Limitations

• Store-side owner profit crediting still counts full item profit; investor share is tracked in the parallel investment ledger (business-books netting is a pending product decision).
• Partial refunds are manual admin adjustments only.
• Reversal after buyback is refused (manual adjustment required).
• Re-dispatch after cancellation cannot re-process sales (idempotency keys persist) — unreachable via the order state machine.

Future Improvements

• Aggregate/paginate the reports endpoint at scale.
• Optional netting of investor share out of store owner profit split.
• Email notifications for withdrawal status changes.
• Composite index + server-side ledger ordering if entries per investment exceed ~1k.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
valore-parfums	Ready	Preview	Aug 19, 2026 2:12pm
valore-parfums-backend	Ready	Preview	Aug 19, 2026 2:12pm

[Tayebbb]

Final pre-merge financial review (2026-08-18) ? resolved

Accounting decision: For every investor-funded sale, �ctual net profit = investor profit + Valore (owner) profit. The investor share is carved out of the item's net profit before owner crediting ? the owner P&L never recognises the full net profit while the investor ledger recognises the share on top. Single source: ownerRecognizedItemProfitMajor() in �ackend/src/lib/investments/finance.ts.

Canonical example (tested): Revenue 900, perfume cost 600, direct costs 100 ? net 200 = investor 80 (40%) + Valore 120. Owners are credited 120 (split 60/40 ? 72 + 48); total economic profit is exactly 200.

Recognition event: order status Dispatched (the completed-family key; Delivered/Completed/Fulfilled aliases normalize to it) is THE financial recognition event for both owner P&L and investor ledger. Cancellation from it reverses both sides symmetrically: the owner reversal reuses the per-item investmentRecognition deduction persisted at credit time; the investor ledger reverses via
ev_ compensating entries. The standalone cancel route now gates on the NORMALIZED status (alias-stored orders reverse too).

Buyback (re-verified): positive profit ? remaining inventory cost + available profit; zero ? remaining cost only; negative ? capital only, loss written off with an explicit ledger adjustment (_buyback_writeoff) ? history stays visible (negative profit_generated entries remain in monthly reports and the immutable ledger).

Investor statement: now distinguishes capital invested (original/additional per investment doc), capital recovered through sales vs returned through buyback (splitCapitalBySource), remaining inventory exposure, realized profit, withdrawable profit, and profit already withdrawn.

Tests: 106/106 engine tests pass (�ackend/scripts/test-investments.ts), including new ?12 owner-P&L integration (canonical example, non-interference of funded/unfunded items, loss clamp, partial funding, rounding exactness) and ?13 capital-by-source. Reconciliation check-investments.ts: all checks pass (live DB has no investment data yet ? fix lands before first use). Backend + frontend sc --noEmit clean.

Known limits (documented): lot cost basis is locked at funding; if perfume.purchasePricePerMl drifts, owner-side net uses the store basis while the deduction uses the actual ledgered investor profit ? the identity owner recognised + investor profit = owner-basis net still holds. Items whose investment processing fails produce no investor entries and no deduction (consistent either way).