AI Prompt: Forma3D.Connect — Inventory & Stock Replenishment¶

┌──────────────────────────────────────────────────────────────┐
│  Frontend (apps/web)  →  Gateway (apps/gateway, port 3000)   │
│                              │                                │
│              ┌───────────────┼───────────────┐                │
│              ▼               ▼               ▼                │
│     order-service     print-service    shipping-service       │
│     (port 3001)       (port 3002)      (port 3003)           │
│                                                               │
│     gridflock-service                                        │
│     (port 3004)                                              │
└──────────────────────────────────────────────────────────────┘

Shopify Order Webhook → Gateway → Order Service
  → OrdersService.createFromShopify()
    → Create Order (PENDING)
    → Create LineItems
    → Emit ORDER_EVENTS.CREATED (NestJS EventEmitter)

OrchestrationService (listens @OnEvent(ORDER_EVENTS.CREATED))
  → Order → PROCESSING
  → For each LineItem:
      → ProductMappingService.findMappingForLineItem()
      → If GridFlock product → gridflockServiceClient.getMappingStatus()
      → Otherwise: PrintJobsService.createPrintJobsForLineItem()
          → For each AssemblyPart × quantity × quantityPerProduct:
              → Create PrintJob (QUEUED)
  → EventPublisherService bridges → BullMQ "order.created"
  → Print Service receives via EventSubscriberService

Print Service
  → Creates print jobs in SimplyPrint queue (addToQueue)
  → SimplyPrint Webhook → SimplyPrintService.handleWebhook()
      → Idempotency check → emit SIMPLYPRINT_EVENTS.JOB_STATUS_CHANGED
      → PrintJobsService.handleSimplyPrintStatusChange()
      → Update PrintJob status
      → Emit PRINT_JOB_EVENTS.COMPLETED|FAILED|CANCELLED
      → EventPublisherService → BullMQ "print-job.completed"

Order Service (receives BullMQ "print-job.completed")
  → EventSubscriberService → re-emit as local PRINT_JOB_EVENTS.COMPLETED
  → OrchestrationService.handlePrintJobCompleted()
      → recalculatePartCounts()
      → checkOrderCompletion()
      → If all parts done → Order COMPLETED → emit ORDER_READY_FOR_FULFILLMENT

FulfillmentService
  → Create Shopify fulfillment
  → Shipping Service → Create Sendcloud shipment

// apps/order-service/src/orders/events/order.events.ts
export const ORDER_EVENTS = {
  CREATED: 'order.created',
  STATUS_CHANGED: 'order.status_changed',
  CANCELLED: 'order.cancelled',
  READY_FOR_FULFILLMENT: 'order.ready-for-fulfillment',
  FULFILLED: 'order.fulfilled',
  FAILED: 'order.failed',
} as const;

// apps/order-service/src/print-jobs/events/print-job.events.ts
export const PRINT_JOB_EVENTS = {
  CREATED: 'printjob.created',
  STATUS_CHANGED: 'printjob.status-changed',
  COMPLETED: 'printjob.completed',
  FAILED: 'printjob.failed',
  CANCELLED: 'printjob.cancelled',
  RETRY_REQUESTED: 'printjob.retry-requested',
} as const;

// libs/service-common/src/lib/events/event-types.ts
export const SERVICE_EVENTS = {
  ORDER_CREATED: 'order.created',
  ORDER_READY_FOR_FULFILLMENT: 'order.ready-for-fulfillment',
  ORDER_CANCELLED: 'order.cancelled',
  PRINT_JOB_COMPLETED: 'print-job.completed',
  PRINT_JOB_FAILED: 'print-job.failed',
  PRINT_JOB_STATUS_CHANGED: 'print-job.status-changed',
  PRINT_JOB_CANCELLED: 'print-job.cancelled',
  // ... gridflock, shipment events ...
} as const;

// apps/order-service/src/auth/permissions.ts (duplicated per service)
export const PERMISSIONS = {
  ORDERS_READ: 'orders.read',
  ORDERS_WRITE: 'orders.write',
  PRINT_JOBS_READ: 'printJobs.read',
  PRINT_JOBS_WRITE: 'printJobs.write',
  MAPPINGS_READ: 'mappings.read',
  MAPPINGS_WRITE: 'mappings.write',
  SETTINGS_READ: 'settings.read',
  SETTINGS_WRITE: 'settings.write',
  ADMIN: 'admin.operations',
  // ...
} as const;

// libs/domain-contracts/src/lib/print-jobs.interface.ts
export interface IPrintJobsService {
  findByOrderId(orderId: string): Promise<PrintJobDto[]>;
  findByLineItemId(lineItemId: string): Promise<PrintJobDto[]>;
  areAllJobsComplete(orderId: string): Promise<boolean>;
  cancelJobsForOrder(orderId: string): Promise<void>;
  getJobCountByStatus(orderId: string, status: PrintJobStatusType): Promise<number>;
}

┌─────────────────────────────────────────────────────────────┐
│  order-service (apps/order-service)                          │
│    ├─ InventoryModule (NEW)                                  │
│    │   ├─ InventoryController — REST endpoints               │
│    │   ├─ InventoryService — business logic                  │
│    │   └─ InventoryRepository — Prisma DB access             │
│    ├─ StockReplenishmentModule (NEW)                              │
│    │   ├─ StockReplenishmentService — scheduling + deficit calc    │
│    │   └─ StockReplenishmentScheduler — cron job                  │
│    └─ OrchestrationModule (UPDATED)                          │
│        └─ OrchestrationService — stock-aware fulfillment     │
│                                                              │
│  print-service (apps/print-service)                          │
│    └─ PrintJobsModule (UPDATED)                              │
│        └─ Handle STOCK purpose job completion                │
│           → BullMQ event → order-service                     │
│                                                              │
│  libs/domain (UPDATED)                                       │
│    └─ New enums: PrintJobPurpose, StockBatchStatus, etc.     │
│                                                              │
│  libs/domain-contracts (UPDATED)                             │
│    └─ New API types, updated PrintJobDto                     │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│                     Order Fulfillment                        │
│                                                              │
│  Shopify Order → Gateway → Order Service                     │
│    OrchestrationService (updated)                            │
│    ├─ For each LineItem → find ProductMapping                │
│    ├─ Check ProductMapping.currentStock                      │
│    ├─ If stock ≥ quantity → consume units (InventoryTx)      │
│    │   (complete units — all parts already printed)           │
│    ├─ If stock < quantity → consume available, print rest    │
│    │   PrintJobs created for ALL parts × remaining units     │
│    │   → Published via BullMQ to print-service               │
│    └─ If stock = 0 → print-to-order (existing behavior)     │
│                                                              │
├─────────────────────────────────────────────────────────────┤
│                   Stock Replenishment Engine                       │
│                                                              │
│  Cron Schedule → StockReplenishmentService (order-service)        │
│    ├─ Find ProductMappings WHERE minimumStock > 0            │
│    │   AND currentStock < minimumStock                       │
│    ├─ target = maximumStock ?? minimumStock                   │
│    ├─ Calculate deficit (target - currentStock               │
│    │                      - pendingStockBatches)             │
│    ├─ If deficit > 0 → create StockBatch + PrintJobs         │
│    │   (1 PrintJob per AssemblyPart × quantityPerProduct)    │
│    │   → Published via BullMQ to print-service               │
│    └─ Respect maxConcurrentStockJobs limit                   │
│                                                              │
├─────────────────────────────────────────────────────────────┤
│                   Print Job Completion                        │
│                                                              │
│  SimplyPrint webhook → print-service                         │
│    → PrintJobsService handles status update                  │
│    → EventPublisher → BullMQ "print-job.completed"           │
│    → order-service EventSubscriber receives                  │
│    ├─ If purpose=ORDER → existing flow (recalculate parts)   │
│    └─ If purpose=STOCK → InventoryService                    │
│        → StockBatch.completedJobs++                          │
│        └─ If all batch jobs done →                           │
│           ProductMapping.currentStock++ + InventoryTx        │
│                                                              │
├─────────────────────────────────────────────────────────────┤
│                   Inventory Management                        │
│                                                              │
│  InventoryService (order-service)                            │
│    ├─ getStockLevels() → dashboard data (per ProductMapping) │
│    ├─ recordBatchCompletion() → stock IN from completed batch│
│    ├─ consumeStock() → stock OUT for order fulfillment       │
│    ├─ adjustStock() → manual correction (admin)              │
│    ├─ scrapStock() → damaged/wasted units                    │
│    └─ getTransactionHistory() → audit trail                  │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Order arrives → OrchestrationService.handleOrderCreated()
  │
  ├─ For each LineItem:
  │   │
  │   ├─ Find ProductMapping for this LineItem
  │   ├─ unitsNeeded = lineItem.quantity
  │   │
  │   ├─ InventoryService.tryConsumeStock(tenantId, productMappingId, unitsNeeded)
  │   │   ├─ Returns: { consumed: number, remaining: number }
  │   │   ├─ Uses: UPDATE "ProductMapping"
  │   │   │         SET "currentStock" = "currentStock" - consumed
  │   │   │         WHERE id = ? AND "currentStock" >= consumed
  │   │   └─ Creates: InventoryTransaction (type=CONSUMED)
  │   │
  │   ├─ If consumed == unitsNeeded:
  │   │   └─ All units fulfilled from stock (no print jobs needed)
  │   │       completedParts += consumed × partsPerUnit
  │   │
  │   ├─ If consumed > 0 but < unitsNeeded:
  │   │   ├─ completedParts += consumed × partsPerUnit
  │   │   └─ For remaining (unitsNeeded - consumed) units:
  │   │       └─ Create PrintJobs for ALL AssemblyParts × remaining
  │   │           └─ PrintJob.purpose = ORDER
  │   │
  │   └─ If consumed == 0:
  │       └─ Create PrintJobs for all (current print-to-order behavior)
  │           └─ PrintJob.purpose = ORDER
  │
  └─ Update order totalParts / completedParts
     (units fulfilled from stock → all their parts count as completed)

Note: partsPerUnit = sum of quantityPerProduct across all AssemblyParts
      for the ProductMapping. Consuming 1 stock unit means ALL parts
      for that product are already printed and on the shelf.

Cron trigger (e.g., every 15 minutes) → StockReplenishmentService.evaluateAndSchedule()
  │
  ┌─── LOOP (one product per iteration, re-check all conditions each time) ──┐
  │                                                                           │
  │  ├─ Check preconditions:                                                  │
  │  │   ├─ Is stock replenishment globally enabled? (STOCK_REPLENISHMENT_ENABLED env)  │
  │  │   ├─ Is it within allowed hours? (configurable schedule)               │
  │  │   └─ How many ORDER print jobs are currently queued/printing?          │
  │  │       └─ If above threshold → exit (printers are busy with orders)     │
  │  │                                                                        │
  │  ├─ Check current stock job count                                         │
  │  │   └─ If maxConcurrentStockJobs reached → exit                          │
  │  │                                                                        │
  │  ├─ Pick next ProductMapping WHERE minimumStock > 0                       │
  │  │   AND currentStock < minimumStock                                      │
  │  │   └─ If none found → exit (all stock levels satisfied)                 │
  │  │                                                                        │
  │  ├─ target = maximumStock ?? minimumStock                                 │
  │  │   (if maximumStock is set, replenish up to that; otherwise up to min)  │
  │  ├─ deficit = target - currentStock - pendingStockBatches                 │
  │  │   pendingStockBatches = COUNT(StockBatch WHERE productMappingId = ?    │
  │  │                          AND status = IN_PROGRESS)                     │
  │  │                                                                        │
  │  ├─ If deficit > 0:                                                       │
  │  │   └─ Create a StockBatch for this ProductMapping:                      │
  │  │       ├─ For each AssemblyPart in the ProductMapping:                  │
  │  │       │   └─ Create PrintJob × quantityPerProduct                      │
  │  │       │       ├─ PrintJob.purpose = STOCK                              │
  │  │       │       ├─ PrintJob.lineItemId = NULL                            │
  │  │       │       ├─ PrintJob.stockBatchId = batch.id                      │
  │  │       │       └─ Publish to print-service via BullMQ                   │
  │  │       └─ StockBatch.totalJobs = sum of all PrintJobs created           │
  │  │                                                                        │
  │  └─ Loop back to re-check all conditions ────────────────────────────┘    │
  │     (stock replenishment may have been disabled, new orders may have           │
  │      arrived, or max concurrent may now be reached)                       │
  │                                                                           │
  └───────────────────────────────────────────────────────────────────────────┘
  │
  └─ Emit "stock-replenishment.scheduled" event (for logging/monitoring)

Note: One StockBatch = one complete sellable unit. When ALL PrintJobs
      in a batch complete → ProductMapping.currentStock++ and
      InventoryTransaction (PRODUCED) is created.

prisma/
├── schema.prisma                               # UPDATE: new models + PrintJob changes
└── migrations/                                 # NEW: migration for inventory models

apps/order-service/src/
├── inventory/
│   ├── inventory.module.ts                     # NEW: module definition
│   ├── inventory.controller.ts                 # NEW: REST endpoints for stock management
│   ├── inventory.service.ts                    # NEW: business logic for stock operations
│   ├── inventory.repository.ts                 # NEW: database access for inventory
│   ├── dto/
│   │   ├── product-stock.dto.ts                # NEW: response DTOs
│   │   ├── update-stock-config.dto.ts          # NEW: update minimum stock, priority, batch size
│   │   ├── adjust-stock.dto.ts                 # NEW: manual adjustment input
│   │   └── inventory-transaction.dto.ts        # NEW: transaction history response
│   └── __tests__/
│       ├── inventory.service.spec.ts           # NEW: unit tests
│       └── inventory.repository.spec.ts        # NEW: unit tests
│
├── stock-replenishment/
│   ├── stock-replenishment.module.ts                # NEW: module definition
│   ├── stock-replenishment.service.ts               # NEW: scheduling + deficit calculation
│   ├── stock-replenishment.scheduler.ts             # NEW: cron job definitions
│   ├── stock-replenishment.config.ts                # NEW: configuration (schedule, limits)
│   └── __tests__/
│       └── stock-replenishment.service.spec.ts      # NEW: unit tests

apps/order-service/src/
├── orchestration/
│   └── orchestration.service.ts                # UPDATE: stock-aware fulfillment logic
├── print-jobs/
│   └── events/print-job.events.ts              # UPDATE: handle STOCK job purpose routing
├── events/
│   └── event-subscriber.service.ts             # UPDATE: route STOCK completions to InventoryService
├── app/
│   └── app.module.ts                           # UPDATE: import InventoryModule, StockReplenishmentModule

apps/print-service/src/
├── print-jobs/
│   ├── print-jobs.service.ts                   # UPDATE: support nullable lineItemId, purpose field
│   └── print-jobs.repository.ts                # UPDATE: query by purpose, count by purpose+status

libs/service-common/src/lib/events/
└── event-types.ts                              # UPDATE: add inventory/stock replenishment events

libs/domain/src/
├── enums/
│   ├── print-job-purpose.ts                    # NEW: ORDER | STOCK
│   ├── stock-batch-status.ts                   # NEW: IN_PROGRESS | COMPLETED | FAILED
│   ├── inventory-transaction-type.ts           # NEW: PRODUCED | CONSUMED | ADJUSTMENT_IN | etc.
│   └── index.ts                                # UPDATE: export new enums
├── entities/
│   └── print-job.ts                            # UPDATE: add purpose, stockBatchId, nullable lineItemId

libs/domain-contracts/src/
├── api/
│   └── inventory.api.ts                        # NEW: API request/response types
├── lib/
│   ├── inventory.interface.ts                  # NEW: IInventoryService interface
│   └── types.ts                                # UPDATE: add inventory DTOs, update PrintJobDto

apps/web/src/
├── pages/
│   └── inventory/
│       ├── index.tsx                            # NEW: stock levels overview (dashboard)
│       ├── config.tsx                           # NEW: configure min stock per product
│       ├── transactions.tsx                     # NEW: transaction history/audit
│       └── replenishment.tsx                         # NEW: replenishment queue status
│
├── hooks/
│   └── use-inventory.ts                        # NEW: TanStack Query hooks
│
├── lib/
│   └── api-client.ts                           # UPDATE: add inventory API methods
│
├── components/layout/
│   └── sidebar.tsx                             # UPDATE: add Inventory nav item
│
└── router.tsx                                  # UPDATE: add inventory routes

// ============================================================================
// Inventory — Fields added to ProductMapping
// ============================================================================

model ProductMapping {
  // ... existing fields (id, tenantId, shopifyProductId, etc.) ...

  // Inventory configuration
  currentStock              Int       @default(0)    // Complete sellable units on shelf
  minimumStock              Int       @default(0)    // Reorder point: replenishment triggers when stock drops below this (0 = no stock mgmt)
  maximumStock              Int?                     // Order-up-to level: replenish until stock reaches this (null = defaults to minimumStock)
  replenishmentPriority     Int       @default(0)    // Higher = replenish first
  replenishmentBatchSize    Int       @default(1)    // Max StockBatches to create per cycle

  // ... existing relations ...
  stockBatches              StockBatch[]
  inventoryTransactions     InventoryTransaction[]
}

// ============================================================================
// StockBatch — Groups PrintJobs that produce one complete stock unit
// ============================================================================

model StockBatch {
  id                String           @id @default(uuid())
  tenantId          String
  productMappingId  String

  status            StockBatchStatus @default(IN_PROGRESS)
  totalJobs         Int              // Total PrintJobs in this batch
  completedJobs     Int              @default(0)

  createdAt         DateTime         @default(now())
  completedAt       DateTime?

  // Relations
  tenant            Tenant           @relation(fields: [tenantId], references: [id], onDelete: Cascade)
  productMapping    ProductMapping   @relation(fields: [productMappingId], references: [id], onDelete: Cascade)
  printJobs         PrintJob[]

  @@index([tenantId])
  @@index([tenantId, productMappingId, status])
}

enum StockBatchStatus {
  IN_PROGRESS   // PrintJobs still running
  COMPLETED     // All jobs done → currentStock incremented
  FAILED        // One or more jobs failed irrecoverably
}

// ============================================================================
// InventoryTransaction — Audit trail for all stock movements
// ============================================================================

model InventoryTransaction {
  id                String                    @id @default(uuid())
  tenantId          String
  productMappingId  String

  // Transaction details
  transactionType   InventoryTransactionType
  quantity          Int                       // Always positive (units)
  direction         StockDirection            // IN or OUT

  // Reference to what caused this transaction
  referenceType     InventoryReferenceType
  referenceId       String?                   // StockBatch ID, Order ID, or null for manual

  notes             String?
  createdAt         DateTime                  @default(now())
  createdBy         String?                   // User ID for manual adjustments

  // Relations
  tenant            Tenant                    @relation(fields: [tenantId], references: [id], onDelete: Cascade)
  productMapping    ProductMapping            @relation(fields: [productMappingId], references: [id], onDelete: Cascade)

  @@index([tenantId])
  @@index([productMappingId])
  @@index([tenantId, productMappingId])
  @@index([createdAt])
}

enum InventoryTransactionType {
  PRODUCED        // StockBatch completed → stock increases by 1 unit
  CONSUMED        // Units taken from stock for order → stock decreases
  ADJUSTMENT_IN   // Manual stock increase (found units, received transfer)
  ADJUSTMENT_OUT  // Manual stock decrease (correction)
  SCRAPPED        // Unit damaged/wasted → stock decreases
}

enum StockDirection {
  IN
  OUT
}

enum InventoryReferenceType {
  STOCK_BATCH     // Linked to a completed StockBatch
  ORDER           // Linked to an order that consumed stock
  LINE_ITEM       // Linked to a specific line item
  MANUAL          // Manual adjustment by operator
}

enum PrintJobPurpose {
  ORDER           // Fulfilling a customer order (existing behavior)
  STOCK           // Stock replenishment to build inventory
}

model PrintJob {
  id                      String          @id @default(uuid())
  tenantId                String
  lineItemId              String?         // ← CHANGE: nullable (null for STOCK jobs)
  assemblyPartId          String?
  purpose                 PrintJobPurpose @default(ORDER)  // ← NEW
  stockBatchId            String?         // ← NEW: set for STOCK purpose jobs

  // ... rest of existing fields unchanged ...

  // Relations
  tenant                  Tenant          @relation(fields: [tenantId], references: [id], onDelete: Cascade)
  lineItem                LineItem?       @relation(fields: [lineItemId], references: [id], onDelete: Cascade)  // ← CHANGE: optional
  assemblyPart            AssemblyPart?   @relation(fields: [assemblyPartId], references: [id], onDelete: SetNull)
  stockBatch              StockBatch?     @relation(fields: [stockBatchId], references: [id])  // ← NEW

  @@index([stockBatchId])  // ← NEW
}

model Tenant {
  // ... existing relations ...
  stockBatches              StockBatch[]
  inventoryTransactions     InventoryTransaction[]
}

pnpm prisma migrate dev --name add-inventory-stock-management

export const PrintJobPurpose = {
  ORDER: 'ORDER',
  STOCK: 'STOCK',
} as const;

export type PrintJobPurposeType = (typeof PrintJobPurpose)[keyof typeof PrintJobPurpose];

export const StockBatchStatus = {
  IN_PROGRESS: 'IN_PROGRESS',
  COMPLETED: 'COMPLETED',
  FAILED: 'FAILED',
} as const;

export type StockBatchStatusType = (typeof StockBatchStatus)[keyof typeof StockBatchStatus];

export const InventoryTransactionType = {
  PRODUCED: 'PRODUCED',
  CONSUMED: 'CONSUMED',
  ADJUSTMENT_IN: 'ADJUSTMENT_IN',
  ADJUSTMENT_OUT: 'ADJUSTMENT_OUT',
  SCRAPPED: 'SCRAPPED',
} as const;

export type InventoryTransactionTypeValue =
  (typeof InventoryTransactionType)[keyof typeof InventoryTransactionType];

export const InventoryReferenceType = {
  STOCK_BATCH: 'STOCK_BATCH',
  ORDER: 'ORDER',
  LINE_ITEM: 'LINE_ITEM',
  MANUAL: 'MANUAL',
} as const;

export type InventoryReferenceTypeValue =
  (typeof InventoryReferenceType)[keyof typeof InventoryReferenceType];

export const StockDirection = {
  IN: 'IN',
  OUT: 'OUT',
} as const;

export type StockDirectionType = (typeof StockDirection)[keyof typeof StockDirection];

export interface PrintJob {
  id: string;
  lineItemId: string | null;     // ← CHANGE: nullable
  assemblyPartId: string | null;
  purpose: PrintJobPurposeType;  // ← NEW
  stockBatchId: string | null;   // ← NEW
  // ... rest of existing fields unchanged
}

import type { PrintJobPurposeType, StockBatchStatusType, InventoryTransactionTypeValue, StockDirectionType, InventoryReferenceTypeValue } from '@forma3d/domain';

export interface ProductStockApiResponse {
  productMappingId: string;
  tenantId: string;
  productName: string;
  sku: string | null;
  assemblyPartCount: number;
  currentStock: number;
  minimumStock: number;                 // Reorder point (trigger)
  maximumStock: number | null;          // Order-up-to level (target); null = defaults to minimumStock
  replenishmentTarget: number;          // Resolved target: maximumStock ?? minimumStock
  deficit: number;                      // replenishmentTarget - currentStock (clamped to 0)
  replenishmentPriority: number;
  replenishmentBatchSize: number;
  pendingBatches: number;
  updatedAt: string;
}

export interface StockBatchApiResponse {
  id: string;
  tenantId: string;
  productMappingId: string;
  productName: string;
  status: StockBatchStatusType;
  totalJobs: number;
  completedJobs: number;
  createdAt: string;
  completedAt: string | null;
}

export interface InventoryTransactionApiResponse {
  id: string;
  tenantId: string;
  productMappingId: string;
  productName: string;
  transactionType: InventoryTransactionTypeValue;
  quantity: number;
  direction: StockDirectionType;
  referenceType: InventoryReferenceTypeValue;
  referenceId: string | null;
  notes: string | null;
  createdAt: string;
  createdBy: string | null;
}

export interface UpdateStockConfigRequest {
  minimumStock: number;                // Reorder point (0 = disable stock management)
  maximumStock?: number | null;        // Order-up-to level (null = defaults to minimumStock; must be >= minimumStock when set)
  replenishmentPriority?: number;
  replenishmentBatchSize?: number;
}

export interface AdjustStockRequest {
  quantity: number;
  reason: string;
}

export interface ScrapStockRequest {
  quantity: number;
  reason: string;
}

export interface InventoryTransactionListApiResponse {
  transactions: InventoryTransactionApiResponse[];
  total: number;
}

export interface StockReplenishmentStatusApiResponse {
  enabled: boolean;
  nextRunAt: string | null;
  lastRunAt: string | null;
  activeStockBatches: number;
  activeStockJobs: number;
  maxConcurrentStockJobs: number;
  productsNeedingReplenishment: ProductStockApiResponse[];
}

export interface PrintJobDto {
  id: string;
  lineItemId: string | null;          // ← CHANGE: nullable
  orderId: string | null;             // ← CHANGE: nullable (derived from lineItem)
  purpose: PrintJobPurposeType;       // ← NEW
  stockBatchId: string | null;        // ← NEW
  // ... rest of existing fields unchanged
}

export const SERVICE_EVENTS = {
  // ... existing events ...

  // Inventory / Stock Replenishment (order-service publishes)
  STOCK_BATCH_COMPLETED: 'inventory.stock-batch-completed',
  STOCK_REPLENISHMENT_SCHEDULED: 'inventory.stock-replenishment-scheduled',
} as const;

import { Injectable } from '@nestjs/common';
import { BadRequestException } from '@nestjs/common';
import { PrismaService } from '../prisma/prisma.service';

@Injectable()
export class InventoryRepository {
  constructor(private readonly prisma: PrismaService) {}

  async tryConsumeStock(
    tenantId: string,
    productMappingId: string,
    quantity: number,
    orderId: string
  ): Promise<{ consumed: boolean; previousStock: number }> {
    return this.prisma.$transaction(async (tx) => {
      const mapping = await tx.productMapping.findFirst({
        where: { id: productMappingId, tenantId },
      });

      if (!mapping || mapping.currentStock < quantity) {
        return {
          consumed: false,
          previousStock: mapping?.currentStock ?? 0,
        };
      }

      await tx.productMapping.update({
        where: { id: productMappingId },
        data: { currentStock: { decrement: quantity } },
      });

      await tx.inventoryTransaction.create({
        data: {
          tenantId,
          productMappingId,
          transactionType: 'CONSUMED',
          quantity,
          direction: 'OUT',
          referenceType: 'ORDER',
          referenceId: orderId,
        },
      });

      return {
        consumed: true,
        previousStock: mapping.currentStock,
      };
    });
  }

  async recordBatchCompletion(
    tenantId: string,
    productMappingId: string,
    stockBatchId: string
  ): Promise<void> {
    await this.prisma.$transaction(async (tx) => {
      await tx.productMapping.update({
        where: { id: productMappingId },
        data: { currentStock: { increment: 1 } },
      });

      await tx.stockBatch.update({
        where: { id: stockBatchId },
        data: { status: 'COMPLETED', completedAt: new Date() },
      });

      await tx.inventoryTransaction.create({
        data: {
          tenantId,
          productMappingId,
          transactionType: 'PRODUCED',
          quantity: 1,
          direction: 'IN',
          referenceType: 'STOCK_BATCH',
          referenceId: stockBatchId,
        },
      });
    });
  }

  async findAllStockLevels(tenantId: string) {
    return this.prisma.productMapping.findMany({
      where: {
        tenantId,
        minimumStock: { gt: 0 },
      },
      include: {
        assemblyParts: { where: { isActive: true } },
        _count: {
          select: {
            stockBatches: { where: { status: 'IN_PROGRESS' } },
          },
        },
      },
      orderBy: [
        { replenishmentPriority: 'desc' },
        { productName: 'asc' },
      ],
    });
  }

  async findProductsNeedingReplenishment(tenantId: string) {
    return this.prisma.$queryRaw`
      SELECT pm.*
      FROM "ProductMapping" pm
      WHERE pm."tenantId" = ${tenantId}
        AND pm."minimumStock" > 0
        AND pm."currentStock" < pm."minimumStock"
      ORDER BY pm."replenishmentPriority" DESC
    `;
  }

  async updateStockConfig(
    tenantId: string,
    productMappingId: string,
    config: { minimumStock: number; maximumStock?: number | null; replenishmentPriority?: number; replenishmentBatchSize?: number }
  ) {
    if (config.maximumStock != null && config.maximumStock < config.minimumStock) {
      throw new BadRequestException(
        `maximumStock (${config.maximumStock}) must be >= minimumStock (${config.minimumStock})`
      );
    }

    return this.prisma.productMapping.update({
      where: { id: productMappingId },
      data: config,
    });
  }

  async adjustStock(
    tenantId: string,
    productMappingId: string,
    quantity: number,
    reason: string,
    userId: string
  ): Promise<void> {
    const isPositive = quantity > 0;
    const absQuantity = Math.abs(quantity);

    await this.prisma.$transaction(async (tx) => {
      const mapping = await tx.productMapping.findFirstOrThrow({
        where: { id: productMappingId, tenantId },
      });

      if (!isPositive && mapping.currentStock < absQuantity) {
        throw new BadRequestException(
          `Cannot reduce stock below 0. Current: ${mapping.currentStock}, requested: -${absQuantity}`
        );
      }

      await tx.productMapping.update({
        where: { id: productMappingId },
        data: {
          currentStock: isPositive
            ? { increment: absQuantity }
            : { decrement: absQuantity },
        },
      });

      await tx.inventoryTransaction.create({
        data: {
          tenantId,
          productMappingId,
          transactionType: isPositive ? 'ADJUSTMENT_IN' : 'ADJUSTMENT_OUT',
          quantity: absQuantity,
          direction: isPositive ? 'IN' : 'OUT',
          referenceType: 'MANUAL',
          notes: reason,
          createdBy: userId,
        },
      });
    });
  }

  async scrapStock(
    tenantId: string,
    productMappingId: string,
    quantity: number,
    reason: string,
    userId: string
  ): Promise<void> {
    await this.prisma.$transaction(async (tx) => {
      const mapping = await tx.productMapping.findFirstOrThrow({
        where: { id: productMappingId, tenantId },
      });

      if (mapping.currentStock < quantity) {
        throw new BadRequestException(
          `Cannot scrap ${quantity} units. Only ${mapping.currentStock} in stock.`
        );
      }

      await tx.productMapping.update({
        where: { id: productMappingId },
        data: { currentStock: { decrement: quantity } },
      });

      await tx.inventoryTransaction.create({
        data: {
          tenantId,
          productMappingId,
          transactionType: 'SCRAPPED',
          quantity,
          direction: 'OUT',
          referenceType: 'MANUAL',
          notes: reason,
          createdBy: userId,
        },
      });
    });
  }

  async createStockBatch(
    tenantId: string,
    productMappingId: string,
    printJobData: Array<{ assemblyPartId: string; fileId: string; fileName: string | null }>
  ) {
    return this.prisma.stockBatch.create({
      data: {
        tenantId,
        productMappingId,
        totalJobs: printJobData.length,
        completedJobs: 0,
        status: 'IN_PROGRESS',
        printJobs: {
          create: printJobData.map((job) => ({
            tenantId,
            assemblyPartId: job.assemblyPartId,
            purpose: 'STOCK',
            status: 'QUEUED',
            copyNumber: 1,
            fileId: job.fileId,
            fileName: job.fileName,
          })),
        },
      },
      include: { printJobs: true },
    });
  }

  async incrementBatchProgress(stockBatchId: string) {
    return this.prisma.stockBatch.update({
      where: { id: stockBatchId },
      data: { completedJobs: { increment: 1 } },
    });
  }

  async getTransactionHistory(
    tenantId: string,
    productMappingId: string,
    options: { limit: number; offset: number }
  ) {
    const [transactions, total] = await Promise.all([
      this.prisma.inventoryTransaction.findMany({
        where: { tenantId, productMappingId },
        orderBy: { createdAt: 'desc' },
        take: options.limit,
        skip: options.offset,
      }),
      this.prisma.inventoryTransaction.count({
        where: { tenantId, productMappingId },
      }),
    ]);

    return { transactions, total };
  }

  async countPrintJobsByPurposeAndStatus(
    tenantId: string,
    purpose: string,
    statuses: string[]
  ): Promise<number> {
    return this.prisma.printJob.count({
      where: {
        tenantId,
        purpose: purpose as 'ORDER' | 'STOCK',
        status: { in: statuses as ('QUEUED' | 'ASSIGNED' | 'PRINTING')[] },
      },
    });
  }
}

import { Injectable, Logger } from '@nestjs/common';
import { InventoryRepository } from './inventory.repository';

@Injectable()
export class InventoryService {
  private readonly logger = new Logger(InventoryService.name);

  constructor(private readonly repository: InventoryRepository) {}

  async tryConsumeStock(
    tenantId: string,
    productMappingId: string,
    unitsNeeded: number,
    orderId: string
  ) {
    const mapping = await this.repository.findProductMapping(tenantId, productMappingId);

    if (!mapping || mapping.currentStock <= 0) {
      return {
        productMappingId,
        requested: unitsNeeded,
        consumed: 0,
        remaining: unitsNeeded,
        fulfilledFromStock: false,
      };
    }

    const toConsume = Math.min(unitsNeeded, mapping.currentStock);
    const result = await this.repository.tryConsumeStock(
      tenantId, productMappingId, toConsume, orderId
    );

    if (result.consumed) {
      this.logger.log(
        `Consumed ${toConsume} units of "${productMappingId}" from stock ` +
          `(was: ${result.previousStock}, now: ${result.previousStock - toConsume})`
      );
      return {
        productMappingId,
        requested: unitsNeeded,
        consumed: toConsume,
        remaining: unitsNeeded - toConsume,
        fulfilledFromStock: toConsume >= unitsNeeded,
      };
    }

    this.logger.warn(
      `Stock consumption race for product "${productMappingId}" — falling back to printing`
    );
    return {
      productMappingId,
      requested: unitsNeeded,
      consumed: 0,
      remaining: unitsNeeded,
      fulfilledFromStock: false,
    };
  }

  async handleStockJobCompleted(tenantId: string, printJob: { id: string; stockBatchId: string | null }): Promise<void> {
    if (!printJob.stockBatchId) {
      this.logger.warn(`STOCK print job ${printJob.id} has no stockBatchId`);
      return;
    }

    const batch = await this.repository.incrementBatchProgress(printJob.stockBatchId);

    if (batch.completedJobs >= batch.totalJobs) {
      await this.repository.recordBatchCompletion(
        tenantId, batch.productMappingId, batch.id
      );
      this.logger.log(
        `StockBatch ${batch.id} completed — +1 unit for product "${batch.productMappingId}"`
      );
    }
  }

  async getStockLevels(tenantId: string) {
    const mappings = await this.repository.findAllStockLevels(tenantId);
    return mappings.map((mapping) => {
      const replenishmentTarget = mapping.maximumStock ?? mapping.minimumStock;
      return {
        productMappingId: mapping.id,
        tenantId: mapping.tenantId,
        productName: mapping.productName,
        sku: mapping.sku,
        assemblyPartCount: mapping.assemblyParts?.length ?? 0,
        currentStock: mapping.currentStock,
        minimumStock: mapping.minimumStock,
        maximumStock: mapping.maximumStock,
        replenishmentTarget,
        deficit: Math.max(0, replenishmentTarget - mapping.currentStock),
        replenishmentPriority: mapping.replenishmentPriority,
        replenishmentBatchSize: mapping.replenishmentBatchSize,
        pendingBatches: mapping._count?.stockBatches ?? 0,
        updatedAt: mapping.updatedAt,
      };
    });
  }

  async updateStockConfig(tenantId: string, productMappingId: string, config: UpdateStockConfigRequest) {
    return this.repository.updateStockConfig(tenantId, productMappingId, config);
  }

  // ... adjustStock, scrapStock, getTransactionHistory
  // (see repository methods — service delegates with logging)
}

import { Controller, Get, Put, Post, Param, Body, Query } from '@nestjs/common';
import { RequirePermissions } from '../auth/decorators/require-permissions.decorator';
import { PERMISSIONS } from '../auth/permissions';
import { TenantContextService } from '../tenancy/tenant-context.service';
import { InventoryService } from './inventory.service';

@Controller('api/v1/inventory')
export class InventoryController {
  constructor(
    private readonly inventoryService: InventoryService,
    private readonly tenantContext: TenantContextService
  ) {}

  @Get('stock')
  @RequirePermissions(PERMISSIONS.INVENTORY_READ)
  async getStockLevels() {
    const tenantId = this.tenantContext.getTenantId();
    return this.inventoryService.getStockLevels(tenantId);
  }

  @Put('stock/:productMappingId/config')
  @RequirePermissions(PERMISSIONS.INVENTORY_WRITE)
  async updateStockConfig(
    @Param('productMappingId') productMappingId: string,
    @Body() dto: UpdateStockConfigDto
  ) {
    const tenantId = this.tenantContext.getTenantId();
    return this.inventoryService.updateStockConfig(tenantId, productMappingId, dto);
  }

  @Post('stock/:productMappingId/adjust')
  @RequirePermissions(PERMISSIONS.INVENTORY_WRITE)
  async adjustStock(
    @Param('productMappingId') productMappingId: string,
    @Body() dto: AdjustStockDto
  ) {
    const tenantId = this.tenantContext.getTenantId();
    const userId = this.tenantContext.getUserId();
    await this.inventoryService.adjustStock(
      tenantId, productMappingId, dto.quantity, dto.reason, userId
    );
  }

  @Post('stock/:productMappingId/scrap')
  @RequirePermissions(PERMISSIONS.INVENTORY_WRITE)
  async scrapStock(
    @Param('productMappingId') productMappingId: string,
    @Body() dto: ScrapStockDto
  ) {
    const tenantId = this.tenantContext.getTenantId();
    const userId = this.tenantContext.getUserId();
    await this.inventoryService.scrapStock(
      tenantId, productMappingId, dto.quantity, dto.reason, userId
    );
  }

  @Get('stock/:productMappingId/transactions')
  @RequirePermissions(PERMISSIONS.INVENTORY_READ)
  async getTransactionHistory(
    @Param('productMappingId') productMappingId: string,
    @Query('limit') limit = 50,
    @Query('offset') offset = 0
  ) {
    const tenantId = this.tenantContext.getTenantId();
    return this.inventoryService.getTransactionHistory(tenantId, productMappingId, limit, offset);
  }

  @Get('replenishment/status')
  @RequirePermissions(PERMISSIONS.INVENTORY_READ)
  async getStockReplenishmentStatus() {
    const tenantId = this.tenantContext.getTenantId();
    return this.inventoryService.getStockReplenishmentStatus(tenantId);
  }
}

export interface StockReplenishmentConfig {
  enabled: boolean;
  cronExpression: string;
  maxConcurrentStockJobs: number;
  orderQueueThreshold: number;
  allowedHours: { start: number; end: number } | null;
  allowedDays: number[] | null;
}

export const DEFAULT_STOCK_REPLENISHMENT_CONFIG: StockReplenishmentConfig = {
  enabled: false,
  cronExpression: '*/15 * * * *',
  maxConcurrentStockJobs: 5,
  orderQueueThreshold: 3,
  allowedHours: null,
  allowedDays: null,
};

import { Injectable, Logger } from '@nestjs/common';
import { Cron, CronExpression } from '@nestjs/schedule';
import { ConfigService } from '@nestjs/config';
import { StockReplenishmentService } from './stock-replenishment.service';
import { TenantContextService } from '../tenancy/tenant-context.service';

@Injectable()
export class StockReplenishmentScheduler {
  private readonly logger = new Logger(StockReplenishmentScheduler.name);

  constructor(
    private readonly replenishmentService: StockReplenishmentService,
    private readonly tenantContext: TenantContextService,
    private readonly configService: ConfigService
  ) {}

  @Cron(CronExpression.EVERY_10_MINUTES)
  async handleStockReplenishmentCron(): Promise<void> {
    const enabled = this.configService.get<boolean>('STOCK_REPLENISHMENT_ENABLED', false);
    if (!enabled) return;

    this.logger.debug('Stock replenishment cron triggered');

    try {
      const tenantId = this.tenantContext.getDefaultTenantId();
      await this.replenishmentService.evaluateAndSchedule(tenantId);
    } catch (error) {
      this.logger.error(`Stock replenishment cron failed: ${error.message}`, error.stack);
    }
  }
}

// Key change in handleOrderCreated():
// BEFORE creating print jobs for each lineItem:
const stockResult = await this.inventoryService.tryConsumeStock(
  order.tenantId, mapping.id, lineItem.quantity, order.id
);
completedFromStock += stockResult.consumed * partsPerUnit;

if (stockResult.fulfilledFromStock) {
  // All units fulfilled from stock — no print jobs needed for this line item
  continue;
}

// Only create print jobs for remaining units
const unitsToPrint = stockResult.remaining;
// ... create print jobs for unitsToPrint (existing logic, but use unitsToPrint instead of lineItem.quantity)

// In the print-job.completed handler:
const printJob = await this.printJobsRepository.findById(event.printJobId);

if (printJob.purpose === 'STOCK') {
  await this.inventoryService.handleStockJobCompleted(printJob.tenantId, printJob);
  // Do NOT trigger order orchestration flow
  return;
}

// ORDER purpose — existing flow (re-emit as local event for orchestration)
this.eventEmitter.emit(PRINT_JOB_EVENTS.COMPLETED, ...);

export const PERMISSIONS = {
  // ... existing permissions ...

  // Inventory
  INVENTORY_READ: 'inventory.read',
  INVENTORY_WRITE: 'inventory.write',
} as const;

@Module({
  imports: [TenancyModule],
  controllers: [InventoryController],
  providers: [InventoryService, InventoryRepository],
  exports: [InventoryService],
})
export class InventoryModule {}

@Module({
  imports: [InventoryModule],
  providers: [StockReplenishmentService, StockReplenishmentScheduler],
  exports: [StockReplenishmentService],
})
export class StockReplenishmentModule {}

@Module({
  imports: [
    // ... existing modules ...
    InventoryModule,
    StockReplenishmentModule,
  ],
})
export class AppModule {}

// Add to the apiClient export object:
inventory: {
  getStockLevels: () =>
    request<ProductStockApiResponse[]>('/api/v1/inventory/stock'),
  updateStockConfig: (productMappingId: string, config: UpdateStockConfigRequest) =>
    request<ProductStockApiResponse>(`/api/v1/inventory/stock/${productMappingId}/config`, {
      method: 'PUT',
      body: JSON.stringify(config),
    }),
  adjustStock: (productMappingId: string, data: AdjustStockRequest) =>
    request<void>(`/api/v1/inventory/stock/${productMappingId}/adjust`, {
      method: 'POST',
      body: JSON.stringify(data),
    }),
  scrapStock: (productMappingId: string, data: ScrapStockRequest) =>
    request<void>(`/api/v1/inventory/stock/${productMappingId}/scrap`, {
      method: 'POST',
      body: JSON.stringify(data),
    }),
  getTransactions: (productMappingId: string, params?: { limit?: number; offset?: number }) =>
    request<InventoryTransactionListApiResponse>(
      `/api/v1/inventory/stock/${productMappingId}/transactions`,
      { params }
    ),
  getStockReplenishmentStatus: () =>
    request<StockReplenishmentStatusApiResponse>('/api/v1/inventory/replenishment/status'),
},

import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
import { apiClient } from '../lib/api-client';

export function useStockLevels() {
  return useQuery({
    queryKey: ['inventory', 'stock'],
    queryFn: () => apiClient.inventory.getStockLevels(),
    refetchInterval: 30_000,
  });
}

export function useUpdateStockConfig() {
  const queryClient = useQueryClient();
  return useMutation({
    mutationFn: ({ productMappingId, config }: { productMappingId: string; config: UpdateStockConfigRequest }) =>
      apiClient.inventory.updateStockConfig(productMappingId, config),
    onSuccess: () => queryClient.invalidateQueries({ queryKey: ['inventory'] }),
  });
}

export function useAdjustStock() {
  const queryClient = useQueryClient();
  return useMutation({
    mutationFn: ({ productMappingId, ...data }: AdjustStockRequest & { productMappingId: string }) =>
      apiClient.inventory.adjustStock(productMappingId, data),
    onSuccess: () => queryClient.invalidateQueries({ queryKey: ['inventory'] }),
  });
}

export function useScrapStock() {
  const queryClient = useQueryClient();
  return useMutation({
    mutationFn: ({ productMappingId, ...data }: ScrapStockRequest & { productMappingId: string }) =>
      apiClient.inventory.scrapStock(productMappingId, data),
    onSuccess: () => queryClient.invalidateQueries({ queryKey: ['inventory'] }),
  });
}

export function useTransactionHistory(productMappingId: string) {
  return useQuery({
    queryKey: ['inventory', 'transactions', productMappingId],
    queryFn: () => apiClient.inventory.getTransactions(productMappingId),
  });
}

export function useStockReplenishmentStatus() {
  return useQuery({
    queryKey: ['inventory', 'replenishment', 'status'],
    queryFn: () => apiClient.inventory.getStockReplenishmentStatus(),
    refetchInterval: 30_000,
  });
}

const InventoryPage = lazy(() =>
  import('./pages/inventory').then((m) => ({ default: m.InventoryPage }))
);
const InventoryConfigPage = lazy(() =>
  import('./pages/inventory/config').then((m) => ({ default: m.InventoryConfigPage }))
);
const InventoryTransactionsPage = lazy(() =>
  import('./pages/inventory/transactions').then((m) => ({ default: m.InventoryTransactionsPage }))
);
const StockReplenishmentStatusPage = lazy(() =>
  import('./pages/inventory/replenishment').then((m) => ({ default: m.StockReplenishmentStatusPage }))
);

// In the router children:
{
  path: 'inventory',
  element: (
    <PermissionGatedRoute requiredPermission="inventory.read">
      <Suspense fallback={<PageLoadingFallback />}>
        <InventoryPage />
      </Suspense>
    </PermissionGatedRoute>
  ),
},
{
  path: 'inventory/config',
  element: (
    <PermissionGatedRoute requiredPermission="inventory.write">
      <Suspense fallback={<PageLoadingFallback />}>
        <InventoryConfigPage />
      </Suspense>
    </PermissionGatedRoute>
  ),
},
{
  path: 'inventory/transactions',
  element: (
    <PermissionGatedRoute requiredPermission="inventory.read">
      <Suspense fallback={<PageLoadingFallback />}>
        <InventoryTransactionsPage />
      </Suspense>
    </PermissionGatedRoute>
  ),
},
{
  path: 'inventory/replenishment',
  element: (
    <PermissionGatedRoute requiredPermission="inventory.read">
      <Suspense fallback={<PageLoadingFallback />}>
        <StockReplenishmentStatusPage />
      </Suspense>
    </PermissionGatedRoute>
  ),
},

import { ArchiveBoxIcon } from '@heroicons/react/24/outline';

const navigation = [
  { name: 'Dashboard', href: '/', icon: HomeIcon },
  { name: 'Orders', href: '/orders', icon: ClipboardDocumentListIcon },
  { name: 'Product Mappings', href: '/mappings', icon: CubeIcon },
  { name: 'Inventory', href: '/inventory', icon: ArchiveBoxIcon },       // ← NEW
  { name: 'Activity Logs', href: '/logs', icon: DocumentTextIcon },
  { name: 'Settings', href: '/settings', icon: Cog6ToothIcon },
];

# ============================================================================
# Stock Replenishment
# ============================================================================
# Master switch for stock replenishment system (default: false)
STOCK_REPLENISHMENT_ENABLED=false

# Cron expression for stock replenishment evaluation (default: every 15 minutes)
STOCK_REPLENISHMENT_CRON="*/15 * * * *"

# Maximum concurrent stock print jobs (default: 5)
STOCK_REPLENISHMENT_MAX_CONCURRENT=5

# Skip stock replenishment when this many order jobs are active (default: 3)
STOCK_REPLENISHMENT_ORDER_THRESHOLD=3

# Database
pnpm prisma migrate dev
pnpm prisma db seed

# Build
pnpm nx build order-service
pnpm nx build print-service
pnpm nx build web

# Lint + tests
pnpm nx lint order-service
pnpm nx lint print-service
pnpm nx lint web
pnpm nx test order-service
pnpm nx test print-service
pnpm nx test web

# Verify inventory API (after server running)
curl -s http://localhost:3000/api/v1/inventory/stock | jq .
curl -s http://localhost:3000/api/v1/inventory/replenishment/status | jq .