backbone_inventory/application/service/
inventory_read.rs

1//! Inventory read-models (hand-authored, user-owned) — the availability/stock-balance surface the
2//! brief names as consumed by selling + buying (`docs/erp/modules/backbone-inventory.md:11,51-52`).
3//!
4//! These project the `Bin` running balance into the DTOs a consumer actually needs:
5//!   - `AvailabilityView { item_id, warehouse_id, available_qty }` — `actual_qty − reserved_qty`,
6//!     the quantity a Sales Order may commit against.
7//!   - `StockBalance { item_id, warehouse_id, actual_qty, valuation_rate, stock_value }`.
8//! Re-exported from `crate::exports` as the stable public read surface.
9//!
10//! Tenancy (ADR-0029): the module is tenant-agnostic. Every read rides the ambient org scope
11//! the composing service set per request; the composing decorator owns isolation.
12
13use std::sync::Arc;
14
15use rust_decimal::Decimal;
16use serde::{Deserialize, Serialize};
17use sqlx::PgPool;
18use uuid::Uuid;
19
20use crate::infrastructure::persistence::{BinRepository, QuantRepository};
21
22/// The available-to-commit view over a bin: `available_qty = actual_qty − reserved_qty`.
23#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
24pub struct AvailabilityView {
25    pub item_id: Uuid,
26    pub warehouse_id: Uuid,
27    pub actual_qty: Decimal,
28    pub reserved_qty: Decimal,
29    pub available_qty: Decimal,
30}
31
32/// The quant-grain availability view at one LOCATION (the reservation triangle's READ arm, spec
33/// stock-business-logic §3 / stock.hook.yaml T2): `available_qty = quantity − reserved_quantity`
34/// summed over the location's quant rows — the authoritative pair, read off; never a second
35/// writer. `quant_count` is the dimension-tuple spread (item x lot x package x owner rows).
36#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
37pub struct QuantAvailability {
38    pub item_id: Uuid,
39    pub location_id: Uuid,
40    pub on_hand_qty: Decimal,
41    pub reserved_qty: Decimal,
42    pub available_qty: Decimal,
43    pub quant_count: i64,
44}
45
46/// The valuation view over a bin.
47#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
48pub struct StockBalance {
49    pub item_id: Uuid,
50    pub warehouse_id: Uuid,
51    pub actual_qty: Decimal,
52    pub valuation_rate: Decimal,
53    pub stock_value: Decimal,
54}
55
56/// Read-only queries over inventory balances (the consumer-facing read port).
57///
58/// This service only projects — the SQL lives in [`BinRepository`], per the module's 4-layer rule.
59#[derive(Clone)]
60pub struct InventoryReadService {
61    db_pool: PgPool,
62    bins: Arc<BinRepository>,
63    quants: Arc<QuantRepository>,
64}
65
66impl InventoryReadService {
67    pub fn new(db_pool: PgPool) -> Self {
68        Self {
69            bins: Arc::new(BinRepository::new(db_pool.clone())),
70            quants: Arc::new(QuantRepository::new(db_pool.clone())),
71            db_pool,
72        }
73    }
74
75    /// Availability for one item in one warehouse. Returns a zeroed view (available 0) when no bin
76    /// exists yet — an un-received item is simply unavailable, not an error.
77    pub async fn availability(&self, item_id: Uuid, warehouse_id: Uuid) -> Result<AvailabilityView, sqlx::Error> {
78        let row = self.bins.fetch_availability(&self.db_pool, item_id, warehouse_id).await?;
79        let (actual, reserved) = match row {
80            Some(r) => (r.actual_qty, r.reserved_qty),
81            None => (Decimal::ZERO, Decimal::ZERO),
82        };
83        Ok(AvailabilityView { item_id, warehouse_id, actual_qty: actual, reserved_qty: reserved, available_qty: actual - reserved })
84    }
85
86    /// Availability for one item across every warehouse that holds a bin for it.
87    pub async fn availability_across_warehouses(&self, item_id: Uuid) -> Result<Vec<AvailabilityView>, sqlx::Error> {
88        let rows = self.bins.fetch_availability_across_warehouses(&self.db_pool, item_id).await?;
89        Ok(rows.into_iter().map(|r| {
90            let actual = r.actual_qty;
91            let reserved = r.reserved_qty;
92            AvailabilityView { item_id, warehouse_id: r.warehouse_id, actual_qty: actual, reserved_qty: reserved, available_qty: actual - reserved }
93        }).collect())
94    }
95
96    /// Valuation balance for one item in one warehouse (None if no bin exists).
97    pub async fn stock_balance(&self, item_id: Uuid, warehouse_id: Uuid) -> Result<Option<StockBalance>, sqlx::Error> {
98        let row = self.bins.fetch_balance(&self.db_pool, item_id, warehouse_id).await?;
99        Ok(row.map(|r| StockBalance {
100            item_id, warehouse_id,
101            actual_qty: r.actual_qty, valuation_rate: r.valuation_rate, stock_value: r.stock_value,
102        }))
103    }
104
105    /// Quant-grain availability at one location: `available = quantity − reserved` over the
106    /// location's quant rows (T2 — the READ arm of the reservation triangle; the warehouse-grain
107    /// [`Self::availability`] above projects the same invariant off the Bin balance). Zeroed view
108    /// when no quant exists — an unreceived item is unavailable, not an error.
109    pub async fn quant_availability(&self, item_id: Uuid, location_id: Uuid) -> Result<QuantAvailability, sqlx::Error> {
110        let row = self.quants.fetch_on_hand(&self.db_pool, item_id, location_id).await?;
111        Ok(QuantAvailability {
112            item_id,
113            location_id,
114            on_hand_qty: row.on_hand_qty,
115            reserved_qty: row.reserved_qty,
116            available_qty: row.on_hand_qty - row.reserved_qty,
117            quant_count: row.quant_count,
118        })
119    }
120}
backbone_inventory/application/service/inventory_read.rs

backbone_inventory/application/service/
inventory_read.rs
