@axova/shared 1.0.0

package/src/schemas/inventory/lot-tables.ts

@@ -0,0 +1,799 @@
+import { createId } from "@paralleldrive/cuid2";
+import {
+    boolean,
+    date,
+    decimal,
+    index,
+    integer,
+    jsonb,
+    pgEnum,
+    pgTable,
+    text,
+    timestamp,
+    unique,
+    varchar,
+} from "drizzle-orm/pg-core";
+
+//  =====================================================
+// LOT & BATCH MANAGEMENT ENUMS
+// =====================================================
+
+export const lotStatusEnum = pgEnum("lot_status", [
+    "PO_INCOMING",  // Incoming from purchase order, not yet received
+    "PENDING",      // Just received, not yet QC'd
+    "ACTIVE",       // Available for use
+    "QUARANTINED",  // Held for investigation
+    "ALLOCATED",    // Reserved for orders
+    "EXPIRED",      // Past expiry date
+    "RECALLED",     // Subject to recall
+    "DEPLETED",     // Fully consumed
+    "RETURNED",     // Returned to supplier
+    "DISPOSED",     // Disposed/destroyed
+]);
+
+export const qcStatusEnum = pgEnum("qc_status", [
+    "NOT_REQUIRED",
+    "PENDING",
+    "PASSED",
+    "FAILED",
+]);
+
+// Quality status is handled via relation to quality_controls table
+// We don't need a separate enum for lots
+
+export const lotMovementTypeEnum = pgEnum("lot_movement_type", [
+    "RECEIPT",
+    "SALE",
+    "TRANSFER",
+    "ADJUSTMENT",
+    "ADJUSTMENT_INCREASE",
+    "ADJUSTMENT_DECREASE",
+    "RETURN_FROM_CUSTOMER",
+    "RETURN_TO_SUPPLIER",
+    "QUARANTINE",
+    "RELEASE",
+    "SPLIT",
+    "MERGE",
+    "DISPOSAL",
+    "RECALL",
+    "EXPIRY",
+    "PRODUCTION_USE",
+    "SAMPLE",
+    "DAMAGED",
+    "RESERVE",
+    "UNRESERVE",
+    "CYCLE_COUNT_ADJUSTMENT",
+    "PO_INCOMING",
+]);
+
+export const alertTypeEnum = pgEnum("alert_type", [
+    "EXPIRY_WARNING",
+    "EXPIRING_SOON",
+    "EXPIRED",
+    "LOW_QUANTITY",
+    "QUALITY_ISSUE",
+    "RECALL_REQUIRED",
+    "TEMPERATURE_BREACH",
+    "STORAGE_VIOLATION",
+    "COMPLIANCE_DUE",
+]);
+
+export const alertSeverityEnum = pgEnum("alert_severity", [
+    "INFO",
+    "WARNING",
+    "CRITICAL",
+]);
+
+export const alertStatusEnum = pgEnum("alert_status", [
+    "PENDING",
+    "ACKNOWLEDGED",
+    "RESOLVED",
+    "DISMISSED",
+]);
+
+// =====================================================
+// INVENTORY LOTS TABLE
+// =====================================================
+
+export const inventoryLots = pgTable(
+    "inventory_lots",
+    {
+        // Identification
+        id: text("id")
+            .primaryKey()
+            .$defaultFn(() => createId()),
+        storeId: text("store_id").notNull(),
+        lotNumber: varchar("lot_number", { length: 255 }).notNull(),
+        batchNumber: varchar("batch_number", { length: 255 }),
+        internalCode: varchar("internal_code", { length: 255 }),
+
+        // Product Association
+        productId: text("product_id").notNull(),
+        variantId: text("variant_id"),
+        sku: varchar("sku", { length: 255 }).notNull(),
+        
+        // Barcode (unique identifier for scanning and tracking)
+        barcode: varchar("barcode", { length: 255 }),
+
+        // Location Information (REQUIRED - Lots are location-based)
+        locationId: text("location_id").notNull(), // Warehouse or POS location ID
+        locationType: varchar("location_type", { length: 20 }).notNull(), // WAREHOUSE or POS
+
+        // Supplier Information
+        supplierId: text("supplier_id"),
+        supplierLotNumber: varchar("supplier_lot_number", { length: 255 }),
+        supplierBatchNumber: varchar("supplier_batch_number", { length: 255 }),
+        supplierInvoiceNumber: varchar("supplier_invoice_number", { length: 255 }),
+
+        // Quantities
+        originalQuantity: integer("original_quantity").notNull(),
+        currentQuantity: integer("current_quantity").notNull(),
+        allocatedQuantity: integer("allocated_quantity").notNull().default(0),
+        quarantinedQuantity: integer("quarantined_quantity").notNull().default(0),
+        damagedQuantity: integer("damaged_quantity").notNull().default(0),
+        soldQuantity: integer("sold_quantity").notNull().default(0),
+        returnedQuantity: integer("returned_quantity").notNull().default(0),
+
+        // Enhanced Inventory Management Fields
+        availableQuantity: integer("available_quantity").notNull().default(0), // currentQuantity - allocatedQuantity - quarantinedQuantity - damagedQuantity
+        reservedQuantity: integer("reserved_quantity").notNull().default(0), // Reserved for specific orders/customers
+
+        // Stock Level Management
+        reorderPoint: integer("reorder_point"), // Minimum quantity before reorder alert
+        maxStockLevel: integer("max_stock_level"), // Maximum allowed quantity
+        safetyStock: integer("safety_stock").notNull().default(0), // Buffer quantity
+
+        // Unit of Measure
+        unitOfMeasure: varchar("unit_of_measure", { length: 50 }).notNull().default("EACH"), // EACH, CASE, PALLET, etc.
+
+        // Serial Number Tracking
+        trackSerial: boolean("track_serial").notNull().default(false), // Enable serial number tracking
+        serialNumbers: jsonb("serial_numbers").$type<Array<{
+            serialNumber: string;
+            status: "AVAILABLE" | "SOLD" | "RESERVED" | "DAMAGED" | "RETURNED";
+            soldTo?: string;
+            soldDate?: string;
+            reservedFor?: string;
+            reservedDate?: string;
+        }>>(), // Individual serial numbers when trackSerial=true
+
+        // Initial Inventory Flag
+        isInitialInventory: boolean("is_initial_inventory").notNull().default(false), // Marks lots created during product setup
+
+
+        // Dates
+        manufactureDate: date("manufacture_date"),
+        expiryDate: date("expiry_date"),
+        bestBeforeDate: date("best_before_date"),
+        receivedDate: timestamp("received_date", { withTimezone: true }).notNull(),
+        firstUseDate: timestamp("first_use_date", { withTimezone: true }),
+        lastMovementDate: timestamp("last_movement_date", { withTimezone: true }),
+
+        // Status
+        status: lotStatusEnum("status").notNull().default("PENDING"),
+        qcStatus: qcStatusEnum("qc_status").notNull().default("NOT_REQUIRED"),
+
+        // Quality Control (via relation to quality_controls table)
+        qualityControlId: text("quality_control_id"), // FK to quality_controls
+        lastQcDate: timestamp("last_qc_date", { withTimezone: true }),
+
+        // Traceability
+        parentLotId: text("parent_lot_id"),
+        genealogy: jsonb("genealogy").$type<{
+            ancestors?: Array<{
+                lotId: string;
+                lotNumber: string;
+                generation: number;
+                splitDate: string;
+            }>;
+            descendants?: Array<{
+                lotId: string;
+                lotNumber: string;
+                generation: number;
+                splitDate: string;
+            }>;
+        }>(),
+        splitCount: integer("split_count").notNull().default(0),
+
+        // Quality Control metadata (detailed QC in quality_controls table)
+        qcCertificateNumber: varchar("qc_certificate_number", { length: 255 }),
+        qcNotes: text("qc_notes"),
+
+        // Compliance
+        regulatoryCompliance: jsonb("regulatory_compliance").$type<{
+            fda?: { approved: boolean; number?: string };
+            iso?: { certified: boolean; number?: string };
+            gmp?: { compliant: boolean; auditDate?: string };
+        }>(),
+        certificates: jsonb("certificates").$type<Array<{
+            type: string;
+            number: string;
+            issuedDate: string;
+            expiryDate?: string;
+            issuer: string;
+        }>>(),
+        requiresRecall: boolean("requires_recall").notNull().default(false),
+        recallDate: timestamp("recall_date", { withTimezone: true }),
+        recallReason: text("recall_reason"),
+
+        // Storage Conditions
+        storageLocationId: text("storage_location_id"),
+        storageZone: varchar("storage_zone", { length: 255 }),
+        storageTempMin: decimal("storage_temp_min", { precision: 5, scale: 2 }),
+        storageTempMax: decimal("storage_temp_max", { precision: 5, scale: 2 }),
+        storageHumidityMin: decimal("storage_humidity_min", { precision: 5, scale: 2 }),
+        storageHumidityMax: decimal("storage_humidity_max", { precision: 5, scale: 2 }),
+        specialHandling: jsonb("special_handling").$type<{
+            refrigerated?: boolean;
+            frozen?: boolean;
+            hazardous?: boolean;
+            fragile?: boolean;
+            instructions?: string;
+        }>(),
+
+        // Cost & Value
+        unitCost: decimal("unit_cost", { precision: 15, scale: 4 }),
+        landedCost: decimal("landed_cost", { precision: 15, scale: 4 }),
+        totalCost: decimal("total_cost", { precision: 15, scale: 4 }),
+        currency: varchar("currency", { length: 3 }).notNull().default("USD"),
+
+        // Alerts & Notifications
+        expiryAlertDays: integer("expiry_alert_days").notNull().default(30),
+        lowQuantityAlert: integer("low_quantity_alert"),
+        alertRecipients: jsonb("alert_recipients").$type<Array<{
+            type: "email" | "sms" | "push";
+            address: string;
+        }>>(),
+
+        // Metadata
+        customAttributes: jsonb("custom_attributes").$type<Record<string, any>>().default({}),
+        tags: text("tags").array(),
+        notes: text("notes"),
+
+        // Timestamps
+        createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+        updatedAt: timestamp("updated_at", { withTimezone: true }).defaultNow().notNull(),
+        createdBy: text("created_by"),
+        updatedBy: text("updated_by"),
+
+        // Soft Delete
+        isActive: boolean("is_active").notNull().default(true),
+        deletedAt: timestamp("deleted_at", { withTimezone: true }),
+        deletedBy: text("deleted_by"),
+    },
+    (table) => ({
+        storeIdIndex: index("idx_lots_store_id").on(table.storeId),
+        lotNumberIndex: index("idx_lots_lot_number").on(table.lotNumber),
+        productIdIndex: index("idx_lots_product_id").on(table.productId),
+        skuIndex: index("idx_lots_sku").on(table.sku),
+        barcodeIndex: index("idx_lots_barcode").on(table.barcode),
+        statusIndex: index("idx_lots_status").on(table.status),
+        expiryDateIndex: index("idx_lots_expiry_date").on(table.expiryDate),
+        qualityControlIdIndex: index("idx_lots_quality_control_id").on(table.qualityControlId),
+        locationIndex: index("idx_lots_location").on(table.locationId, table.locationType),
+
+        // New Inventory Management Indexes
+        availableQuantityIndex: index("idx_lots_available_quantity").on(table.availableQuantity),
+        reorderPointIndex: index("idx_lots_reorder_point").on(table.reorderPoint),
+        isInitialInventoryIndex: index("idx_lots_is_initial_inventory").on(table.isInitialInventory),
+        storeProductLocationIndex: index("idx_lots_store_product_location").on(table.storeId, table.productId, table.locationId),
+
+        // Unique Constraints
+        uniqueLotNumber: unique("idx_lots_lot_number_unique").on(table.storeId, table.lotNumber),
+        uniqueBarcode: unique("idx_lots_barcode_unique").on(table.storeId, table.barcode),
+    }),
+);
+
+// =====================================================
+// INVENTORY LOT MOVEMENTS TABLE
+// =====================================================
+
+export const inventoryLotMovements = pgTable(
+    "inventory_lot_movements",
+    {
+        id: text("id")
+            .primaryKey()
+            .$defaultFn(() => createId()),
+        lotId: text("lot_id").notNull(),
+        storeId: text("store_id").notNull(),
+
+        // Movement Details
+        movementType: lotMovementTypeEnum("movement_type").notNull(),
+        quantityMoved: integer("quantity_moved").notNull(),
+        quantityBefore: integer("quantity_before").notNull(),
+        quantityAfter: integer("quantity_after").notNull(),
+
+        // Source & Destination
+        fromLocationId: text("from_location_id"),
+        toLocationId: text("to_location_id"),
+        fromStatus: lotStatusEnum("from_status"),
+        toStatus: lotStatusEnum("to_status"),
+
+        // Related Transactions
+        orderId: text("order_id"),
+        transferId: text("transfer_id"),
+        adjustmentId: text("adjustment_id"),
+        returnId: text("return_id"),
+
+        // User & Context
+        performedBy: text("performed_by").notNull(),
+        reason: text("reason"),
+        notes: text("notes"),
+
+        // Timestamps
+        movementDate: timestamp("movement_date", { withTimezone: true }).defaultNow().notNull(),
+        createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+    },
+    (table) => ({
+        lotIdIndex: index("idx_lot_movements_lot_id").on(table.lotId),
+        storeIdIndex: index("idx_lot_movements_store_id").on(table.storeId),
+        movementDateIndex: index("idx_lot_movements_date").on(table.movementDate),
+        movementTypeIndex: index("idx_lot_movements_type").on(table.movementType),
+    }),
+);
+
+// =====================================================
+// INVENTORY LOT SPLITS TABLE
+// =====================================================
+
+export const inventoryLotSplits = pgTable(
+    "inventory_lot_splits",
+    {
+        id: text("id")
+            .primaryKey()
+            .$defaultFn(() => createId()),
+        parentLotId: text("parent_lot_id").notNull(),
+
+        // Split Details
+        splitDate: timestamp("split_date", { withTimezone: true }).notNull(),
+        splitReason: text("split_reason"),
+        originalQuantity: integer("original_quantity").notNull(),
+
+        // Child Lots
+        childLots: jsonb("child_lots").$type<Array<{
+            lotId: string;
+            lotNumber: string;
+            quantity: number;
+        }>>().notNull(),
+
+        // User
+        performedBy: text("performed_by").notNull(),
+        notes: text("notes"),
+
+        createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+    },
+    (table) => ({
+        parentLotIdIndex: index("idx_lot_splits_parent_lot_id").on(table.parentLotId),
+        splitDateIndex: index("idx_lot_splits_date").on(table.splitDate),
+    }),
+);
+
+// =====================================================
+// INVENTORY LOT MERGES TABLE
+// =====================================================
+
+export const inventoryLotMerges = pgTable(
+    "inventory_lot_merges",
+    {
+        id: text("id")
+            .primaryKey()
+            .$defaultFn(() => createId()),
+        targetLotId: text("target_lot_id").notNull(),
+
+        // Merge Details
+        mergeDate: timestamp("merge_date", { withTimezone: true }).notNull(),
+        mergeReason: text("merge_reason"),
+
+        // Source Lots
+        sourceLots: jsonb("source_lots").$type<Array<{
+            lotId: string;
+            lotNumber: string;
+            quantity: number;
+        }>>().notNull(),
+        totalQuantity: integer("total_quantity").notNull(),
+
+        // Validation
+        compatibilityCheck: jsonb("compatibility_check").$type<{
+            compatible: boolean;
+            checks: Array<{
+                criterion: string;
+                passed: boolean;
+                details: string;
+            }>;
+        }>(),
+        approvedBy: text("approved_by"),
+
+        // User
+        performedBy: text("performed_by").notNull(),
+        notes: text("notes"),
+
+        createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+    },
+    (table) => ({
+        targetLotIdIndex: index("idx_lot_merges_target_lot_id").on(table.targetLotId),
+        mergeDateIndex: index("idx_lot_merges_date").on(table.mergeDate),
+    }),
+);
+
+// =====================================================
+// INVENTORY LOT ALERTS TABLE
+// =====================================================
+
+export const inventoryLotAlerts = pgTable(
+    "inventory_lot_alerts",
+    {
+        id: text("id")
+            .primaryKey()
+            .$defaultFn(() => createId()),
+        lotId: text("lot_id").notNull(),
+        storeId: text("store_id").notNull(),
+
+        // Alert Details
+        alertType: alertTypeEnum("alert_type").notNull(),
+        severity: alertSeverityEnum("severity").notNull(),
+        message: text("message").notNull(),
+
+        // Status
+        status: alertStatusEnum("status").notNull().default("PENDING"),
+        acknowledged: boolean("acknowledged").notNull().default(false),
+        acknowledgedBy: text("acknowledged_by"),
+        acknowledgedAt: timestamp("acknowledged_at", { withTimezone: true }),
+
+        // Resolution
+        resolved: boolean("resolved").notNull().default(false),
+        resolvedBy: text("resolved_by"),
+        resolvedAt: timestamp("resolved_at", { withTimezone: true }),
+        resolutionNotes: text("resolution_notes"),
+
+        // Notification
+        notificationSent: boolean("notification_sent").notNull().default(false),
+        notificationChannels: jsonb("notification_channels").$type<Array<"email" | "sms" | "push">>(),
+        recipients: jsonb("recipients").$type<Array<string>>(),
+
+        createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+    },
+    (table) => ({
+        lotIdIndex: index("idx_lot_alerts_lot_id").on(table.lotId),
+        storeIdIndex: index("idx_lot_alerts_store_id").on(table.storeId),
+        statusIndex: index("idx_lot_alerts_status").on(table.status),
+        alertTypeIndex: index("idx_lot_alerts_type").on(table.alertType),
+        severityIndex: index("idx_lot_alerts_severity").on(table.severity),
+    }),
+);
+
+// =====================================================
+// ZOD VALIDATION SCHEMAS
+// =====================================================
+
+import { z } from "zod";
+
+// Base Lot Schema
+export const LotSchema = z.object({
+    id: z.string().cuid2(),
+    storeId: z.string(),
+    lotNumber: z.string(),
+    batchNumber: z.string().optional(),
+    internalCode: z.string().optional(),
+
+    // Product Association
+    productId: z.string(),
+    variantId: z.string().optional(),
+    sku: z.string(),
+
+    // Location
+    locationId: z.string(),
+    locationType: z.enum(["WAREHOUSE", "POS"]),
+
+    // Supplier
+    supplierId: z.string().optional(),
+    supplierLotNumber: z.string().optional(),
+    supplierBatchNumber: z.string().optional(),
+    supplierInvoiceNumber: z.string().optional(),
+
+    // Quantities
+    originalQuantity: z.number().int().nonnegative(),
+    currentQuantity: z.number().int().nonnegative(),
+    availableQuantity: z.number().int().nonnegative(),
+    allocatedQuantity: z.number().int().nonnegative().default(0),
+    reservedQuantity: z.number().int().nonnegative().default(0),
+    quarantinedQuantity: z.number().int().nonnegative().default(0),
+    damagedQuantity: z.number().int().nonnegative().default(0),
+    soldQuantity: z.number().int().nonnegative().default(0),
+    returnedQuantity: z.number().int().nonnegative().default(0),
+
+    // Stock Management
+    reorderPoint: z.number().int().nonnegative().optional(),
+    maxStockLevel: z.number().int().nonnegative().optional(),
+    safetyStock: z.number().int().nonnegative().default(0),
+    unitOfMeasure: z.string().default("EACH"),
+
+    // Serial Tracking
+    trackSerial: z.boolean().default(false),
+    serialNumbers: z.array(z.object({
+        serialNumber: z.string(),
+        status: z.enum(["AVAILABLE", "SOLD", "RESERVED", "DAMAGED", "RETURNED"]),
+        soldTo: z.string().optional(),
+        soldDate: z.string().optional(),
+        reservedFor: z.string().optional(),
+        reservedDate: z.string().optional(),
+    })).optional(),
+
+    // Flags
+    isInitialInventory: z.boolean().default(false),
+
+    // Dates
+    manufactureDate: z.coerce.date().optional(),
+    expiryDate: z.coerce.date().optional(),
+    bestBeforeDate: z.coerce.date().optional(),
+    receivedDate: z.coerce.date(),
+    firstUseDate: z.coerce.date().optional(),
+    lastMovementDate: z.coerce.date().optional(),
+
+    // Status
+    status: z.enum(["PENDING", "ACTIVE", "QUARANTINED", "ALLOCATED", "EXPIRED", "RECALLED", "DEPLETED", "RETURNED", "DISPOSED"]),
+
+    // Quality Control
+    qualityControlId: z.string().optional(),
+    qcCertificateNumber: z.string().optional(),
+    qcNotes: z.string().optional(),
+
+    // Cost
+    unitCost: z.number().nonnegative().optional(),
+    landedCost: z.number().nonnegative().optional(),
+    totalCost: z.number().nonnegative().optional(),
+    currency: z.string().length(3).default("USD"),
+
+    // Metadata
+    notes: z.string().optional(),
+    tags: z.array(z.string()).optional(),
+    customAttributes: z.record(z.any()).optional(),
+
+    // Timestamps
+    createdAt: z.coerce.date(),
+    updatedAt: z.coerce.date(),
+    createdBy: z.string().optional(),
+    updatedBy: z.string().optional(),
+    isActive: z.boolean().default(true),
+});
+
+// Initialize Product Inventory Schema (for product_svc integration)
+export const InitializeProductInventorySchema = z.object({
+    productId: z.string().cuid2(),
+    variantId: z.string().cuid2().optional(),
+    sku: z.string().optional(), // Auto-generated if not provided
+    locations: z.array(z.object({
+        locationId: z.string(),
+        locationType: z.enum(["WAREHOUSE", "POS"]),
+        initialQuantity: z.number().int().nonnegative(),
+        
+        // Barcode for lot tracking
+        barcode: z.string().optional(),
+
+        // Stock Management
+        reorderPoint: z.number().int().nonnegative().optional(),
+        maxStockLevel: z.number().int().nonnegative().optional(),
+        safetyStock: z.number().int().nonnegative().default(0),
+        unitOfMeasure: z.string().default("EACH"),
+
+        // Cost
+        unitCost: z.number().nonnegative().optional(),
+        landedCost: z.number().nonnegative().optional(),
+
+        // Dates
+        expiryDate: z.coerce.date().optional(),
+        manufactureDate: z.coerce.date().optional(),
+
+        // Supplier
+        supplierId: z.string().optional(),
+        supplierLotNumber: z.string().optional(),
+
+        // Serial Tracking
+        trackSerial: z.boolean().default(false),
+        serialNumbers: z.array(z.string()).optional(), // List of serial numbers to assign
+
+        // Metadata
+        notes: z.string().optional(),
+        tags: z.array(z.string()).optional(),
+    })).min(1),
+});
+
+// Create Lot Schema
+export const CreateLotSchema = z.object({
+    storeId: z.string(),
+    lotNumber: z.string().optional(), // Auto-generated if not provided
+    batchNumber: z.string().optional(),
+
+    // Product
+    productId: z.string(),
+    variantId: z.string().optional(),
+    sku: z.string(),
+    barcode: z.string().optional(),
+
+    // Location
+    locationId: z.string(),
+    locationType: z.enum(["WAREHOUSE", "POS"]),
+
+    // Supplier
+    supplierId: z.string().optional(),
+    supplierLotNumber: z.string().optional(),
+    supplierBatchNumber: z.string().optional(),
+    supplierInvoiceNumber: z.string().optional(),
+
+    // Quantities
+    originalQuantity: z.number().int().positive(),
+    reorderPoint: z.number().int().nonnegative().optional(),
+    maxStockLevel: z.number().int().nonnegative().optional(),
+    safetyStock: z.number().int().nonnegative().default(0),
+    unitOfMeasure: z.string().default("EACH"),
+
+    // Dates
+    expiryDate: z.coerce.date().optional(),
+    manufactureDate: z.coerce.date().optional(),
+    receivedDate: z.coerce.date().default(() => new Date()),
+
+    // Cost
+    unitCost: z.number().nonnegative().optional(),
+    landedCost: z.number().nonnegative().optional(),
+
+    // Storage
+    storageLocationId: z.string().optional(),
+    storageZone: z.string().optional(),
+    storageTempMin: z.number().optional(),
+    storageTempMax: z.number().optional(),
+
+    // Serial Tracking
+    trackSerial: z.boolean().default(false),
+    serialNumbers: z.array(z.string()).optional(),
+
+    // Flags
+    isInitialInventory: z.boolean().default(false),
+
+    // Metadata
+    notes: z.string().optional(),
+    tags: z.array(z.string()).optional(),
+    customAttributes: z.record(z.any()).optional(),
+
+    // User
+    createdBy: z.string(),
+});
+
+// Reserve Lot Quantity Schema
+export const ReserveLotQuantitySchema = z.object({
+    lotId: z.string().cuid2(),
+    quantity: z.number().int().positive(),
+    orderId: z.string().optional(),
+    customerId: z.string().optional(),
+    reason: z.string(),
+    expiresAt: z.coerce.date().optional(), // Reservation expiry
+    notes: z.string().optional(),
+    performedBy: z.string(),
+});
+
+// Release Lot Reservation Schema
+export const ReleaseLotReservationSchema = z.object({
+    lotId: z.string().cuid2(),
+    quantity: z.number().int().positive(),
+    reservationId: z.string().optional(),
+    reason: z.string(),
+    performedBy: z.string(),
+});
+
+// Adjust Lot Quantity Schema
+export const AdjustLotQuantitySchema = z.object({
+    lotId: z.string().cuid2(),
+    quantityChange: z.number().int(), // Can be positive or negative
+    adjustmentType: z.enum([
+        "CYCLE_COUNT",
+        "DAMAGE",
+        "FOUND",
+        "LOST",
+        "CORRECTION",
+        "THEFT",
+        "WASTE",
+        "SAMPLE",
+        "EXPIRED",
+        "RETURNED",
+    ]),
+    reason: z.string().min(1),
+    notes: z.string().optional(),
+    performedBy: z.string(),
+});
+
+// Transfer Lot Schema
+export const TransferLotSchema = z.object({
+    lotId: z.string().cuid2(),
+    toLocationId: z.string(),
+    toLocationType: z.enum(["WAREHOUSE", "POS"]),
+    quantity: z.number().int().positive().optional(), // If not provided, transfer entire lot
+    splitIfPartial: z.boolean().default(true), // Create new lot for partial transfer
+    reason: z.string().min(1),
+    notes: z.string().optional(),
+    expectedArrivalDate: z.coerce.date().optional(),
+    performedBy: z.string(),
+});
+
+// Merge Lots Schema
+export const MergeLotsSchema = z.object({
+    targetLotId: z.string().cuid2(),
+    sourceLotIds: z.array(z.string().cuid2()).min(1),
+    reason: z.string().min(1),
+    performedBy: z.string(),
+    approvedBy: z.string().optional(),
+    notes: z.string().optional(),
+});
+
+// Split Lot Schema
+export const SplitLotSchema = z.object({
+    parentLotId: z.string().cuid2(),
+    splits: z.array(z.object({
+        quantity: z.number().int().positive(),
+        locationId: z.string().optional(), // If different from parent
+        locationType: z.enum(["WAREHOUSE", "POS"]).optional(),
+        notes: z.string().optional(),
+    })).min(1),
+    reason: z.string().min(1),
+    performedBy: z.string(),
+});
+
+// Get Lots Query Schema
+export const GetLotsQuerySchema = z.object({
+    storeId: z.string(),
+    productId: z.string().optional(),
+    variantId: z.string().optional(),
+    sku: z.string().optional(),
+    status: z.enum(["PENDING", "ACTIVE", "QUARANTINED", "ALLOCATED", "EXPIRED", "RECALLED", "DEPLETED", "RETURNED", "DISPOSED"]).optional(),
+    locationId: z.string().optional(),
+    locationType: z.enum(["WAREHOUSE", "POS"]).optional(),
+    qualityControlId: z.string().optional(),
+    expiringBefore: z.coerce.date().optional(),
+    isInitialInventory: z.boolean().optional(),
+    lowStock: z.boolean().optional(), // currentQuantity < reorderPoint
+    page: z.coerce.number().int().positive().default(1),
+    limit: z.coerce.number().int().positive().max(100).default(20),
+    sortBy: z.enum(["lotNumber", "receivedDate", "expiryDate", "currentQuantity", "availableQuantity", "status"]).default("receivedDate"),
+    sortOrder: z.enum(["asc", "desc"]).default("desc"),
+});
+
+// Get Available Lots for Order (FIFO) Schema
+export const GetAvailableLotsSchema = z.object({
+    storeId: z.string(),
+    productId: z.string(),
+    variantId: z.string().optional(),
+    quantity: z.number().int().positive(),
+    locationId: z.string().optional(),
+    selectionMethod: z.enum(["FIFO", "FEFO", "LIFO"]).default("FIFO"),
+});
+
+// Lot Analytics Response Schema
+export const LotAnalyticsSchema = z.object({
+    productId: z.string(),
+    totalLots: z.number().int(),
+    totalQuantity: z.number().int(),
+    availableQuantity: z.number().int(),
+    allocatedQuantity: z.number().int(),
+    reservedQuantity: z.number().int(),
+    quarantinedQuantity: z.number().int(),
+    damagedQuantity: z.number().int(),
+    byLocation: z.array(z.object({
+        locationId: z.string(),
+        locationType: z.enum(["WAREHOUSE", "POS"]),
+        lotCount: z.number().int(),
+        totalQuantity: z.number().int(),
+        availableQuantity: z.number().int(),
+    })),
+    byStatus: z.record(z.string(), z.number().int()),
+    expiringLots: z.array(z.object({
+        lotId: z.string(),
+        lotNumber: z.string(),
+        expiryDate: z.coerce.date(),
+        daysUntilExpiry: z.number().int(),
+        currentQuantity: z.number().int(),
+    })),
+    lowStockLots: z.array(z.object({
+        lotId: z.string(),
+        lotNumber: z.string(),
+        currentQuantity: z.number().int(),
+        reorderPoint: z.number().int(),
+        shortfall: z.number().int(),
+    })),
+});