updates on the ai agents and time series prediction and updates on the api to

constants/delivery_category.go

@@ -0,0 +1,56 @@
+package constants
+
+// What a client delivers, and what that implies operationally.
+//
+// ─── One vocabulary, not two ───────────────────────────────────────────────
+//
+// These eight values already existed as `validCategories` in
+// controllers/doormilePricingController.go and as the comment on
+// models.DoormilePricing.Category. Tenants now carry one too, so the set is
+// promoted here rather than copied: a second list would drift, and a tenant
+// whose category is not a pricing category cannot be priced.
+var DeliveryCategories = map[string]bool{
+	"General":     true,
+	"Documents":   true,
+	"Electronics": true,
+	"Clothing":    true,
+	"Fragile":     true,
+	"Medical":     true,
+	"Automotive":  true,
+	"Food":        true,
+}
+
+// DeliveryCategoryList is the same set, ordered, for anything that renders a
+// choice. General first because it is the safe default; Food last because it
+// is the one that turns a capability off.
+var DeliveryCategoryList = []string{
+	"General", "Documents", "Electronics", "Clothing",
+	"Fragile", "Medical", "Automotive", "Food",
+}
+
+// CategoryDefault is what a client with no category recorded is treated as.
+// Every tenant onboarded before this field existed has an empty string, and
+// they must keep behaving exactly as they did — which means reverse logistics
+// stays available to them.
+const CategoryDefault = "General"
+
+// ReverseLogisticsAllowed reports whether a return journey makes sense for
+// what this client ships.
+//
+// Food is the exception: a meal that comes back is waste, not inventory. There
+// is nothing to restock, nothing to refund against a returned item, and a
+// rider carrying it to a hub is carrying rubbish. Offering RTO there is not a
+// harmless extra button — it invites an operator to start a return journey
+// that can only end in disposal, and it puts a return charge on a client's
+// invoice for a parcel nobody can resell.
+//
+// Everything else can come back: clothing is the canonical case (wrong size),
+// and electronics, documents and automotive parts all have a real return path.
+//
+// An UNKNOWN or empty category allows returns. That is deliberate: this field
+// is new, every existing tenant has no value for it, and a default of "off"
+// would silently withdraw a working capability from every client already using
+// it. New information must not change old behaviour.
+func ReverseLogisticsAllowed(category string) bool {
+	return category != "Food"
+}

constants/delivery_category_test.go

@@ -0,0 +1,52 @@
+package constants
+
+import "testing"
+
+// The rule the whole feature exists for: a returned meal is waste, not
+// inventory, so Food clients get no reverse-logistics path.
+func TestFoodIsTheOnlyCategoryWithoutReturns(t *testing.T) {
+	if ReverseLogisticsAllowed("Food") {
+		t.Error("Food allows returns; a returned meal can only be disposed of")
+	}
+	for _, c := range DeliveryCategoryList {
+		if c == "Food" {
+			continue
+		}
+		if !ReverseLogisticsAllowed(c) {
+			t.Errorf("%s does not allow returns; only Food should be excluded", c)
+		}
+	}
+}
+
+// New information must not change old behaviour. Every tenant onboarded before
+// this field existed has an empty category, and they were all using returns.
+func TestUnknownAndEmptyCategoriesKeepReturns(t *testing.T) {
+	for _, c := range []string{"", "   ", "Groceries", "SomethingNew"} {
+		if !ReverseLogisticsAllowed(c) {
+			t.Errorf("category %q withdrew returns; an unrecognised category must not "+
+				"silently remove a capability an existing client is already using", c)
+		}
+	}
+}
+
+// The tenant category and the pricing category must stay ONE vocabulary: a
+// tenant whose category is not a pricing category cannot be priced.
+func TestListAndSetAgree(t *testing.T) {
+	if len(DeliveryCategoryList) != len(DeliveryCategories) {
+		t.Fatalf("list has %d, set has %d", len(DeliveryCategoryList), len(DeliveryCategories))
+	}
+	for _, c := range DeliveryCategoryList {
+		if !DeliveryCategories[c] {
+			t.Errorf("%s is in the list but not the set", c)
+		}
+	}
+}
+
+func TestDefaultIsAValidCategoryThatAllowsReturns(t *testing.T) {
+	if !DeliveryCategories[CategoryDefault] {
+		t.Errorf("CategoryDefault %q is not a valid category", CategoryDefault)
+	}
+	if !ReverseLogisticsAllowed(CategoryDefault) {
+		t.Error("the default category must not withdraw returns")
+	}
+}