domain/retail/
mod.rs

1//! Retail service-line models for POS sale eligibility, inventory position, reorder workflows, vendor partnerships, and care-safe product recommendations.
2//!
3//! Operator summary: this module supports staff queues for retail sale drafts, checkout attachments, customer-safe recommendation drafts, low-stock reorder work, and vendor-managed notices. It reduces front-desk and manager labor by turning SKU/catalog facts, stock counts, customer preference, care sensitivity, checkout source, price exceptions, and reorder thresholds into typed decisions instead of ad hoc manual review.
4//!
5//! It is not a live automation layer. `domain::retail` does not send customer messages, promise medical outcomes, place vendor orders, mutate POS/Gingr transactions, reconcile payments, approve comps/refunds, or attach products to reservations. Provider DTOs/endpoints, storage records/codes, and source/provenance facts remain authoritative in their own layers; this module only evaluates promoted domain facts.
6//!
7//! Review gates protect pets, customers, and staff: unavailable or non-sellable items are denied, opted-out customers and unavailable products suppress recommendations, supplement/diet and care-plan conflicts require staff or manager review, medical-claim customer copy is rejected or approval-gated, reservation-checkout attachments require customer-message approval, price exceptions require manager approval, impossible stock math is rejected, and reorder actions become threshold-backed manager tasks or vendor notices rather than automatic purchases.
8
9use bon::Builder;
10use serde::{Deserialize, Serialize};
11
12/// Inventory models stock position, available units, reorder thresholds, and oversell checks for retail staff workflows.
13pub mod inventory;
14/// POS models standalone sales, reservation-checkout attachments, price exceptions, and comps so checkout writes stay approval-gated.
15pub mod pos;
16/// Product catalog models SKUs, location offerings, sellability, and in-house consumable use for staff-facing retail decisions.
17pub mod product;
18/// Recommendation models personalized upsells with inventory, preference, and care-safety gates before any customer copy is approved.
19pub mod recommendation;
20/// Reorder models manager tasks, vendor-managed notices, and no-action outcomes from location stock thresholds.
21pub mod reorder;
22/// Vendor models partner-product catalog relationships and externally managed assortments without placing orders.
23pub mod vendor;
24
25pub use product::{LocationOffering, OfferingStatus, Product, Sku, SkuError};
26pub use vendor::Partner;
27
28/// Result type returned by fallible retail operations.
29pub type Result<T> = std::result::Result<T, Error>;
30
31#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
32/// Retail validation failures that prevent impossible stock math or unsupported recommendations from becoming workflow facts.
33pub enum Error {
34    #[error("retail inventory position cannot reserve more units than are on hand")]
35    /// Blocks impossible stock math before POS drafts, recommendations, or reorder tasks use the inventory count.
36    ReservedUnitsExceedOnHand,
37    #[error("retail recommendation rationale is required")]
38    /// Blocks recommendation candidates that lack a staff-readable reason for the suggested product.
39    MissingRationale,
40}
41
42#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Builder)]
43/// Location retail policy bundle tying catalog product, POS policy, inventory policy, recommendation rule, and reorder policy together.
44pub struct Contract {
45    /// Product SKU/category facts used by sale, recommendation, inventory, and reorder decisions.
46    pub product: Product,
47    /// POS policy that decides which sale sources are allowed and which price actions require manager approval.
48    pub pos: pos::Policy,
49    /// Inventory policy that tells staff whether stock is tracked and where reorder attention begins.
50    pub inventory: inventory::Policy,
51    /// Recommendation rule that can create an internal upsell candidate only after safety gates pass.
52    pub recommendation: recommendation::Rule,
53    /// Reorder policy that routes threshold findings to manager review, staff tasks, or vendor notices.
54    pub reorder: reorder::Policy,
55}
56
57impl Contract {
58    /// Reports whether the contracted inventory threshold indicates manager/vendor reorder attention is due.
59    pub fn should_reorder(&self) -> bool {
60        matches!(self.inventory, inventory::Policy::Tracked { on_hand, reorder_at } if on_hand.get() <= reorder_at.get())
61    }
62
63    /// Builds a representative PetSuites-style retail policy bundle for docs/tests without claiming it is live policy.
64    pub fn standard_petsuites() -> Self {
65        Self::builder()
66            .product(Product::new(
67                Sku::try_new("PETSUITES-RETAIL").unwrap(),
68                product::Category::PersonalizedUpsell,
69            ))
70            .pos(pos::Policy::IntegratedWithReservationCheckout)
71            .inventory(inventory::Policy::Tracked {
72                on_hand: inventory::UnitCount::try_new(1).unwrap(),
73                reorder_at: inventory::UnitCount::try_new(10).unwrap(),
74            })
75            .recommendation(recommendation::Rule::AnxietySupportAfterBoarding)
76            .reorder(reorder::Policy::AutoCreateManagerTask)
77            .build()
78    }
79}
domain/retail/mod.rs

domain/retail/
mod.rs
