@tailor-platform/erp-kit 0.4.1 → 0.5.0

package/src/modules/inventory/db/itemValuation.ts

@@ -0,0 +1,50 @@
+import {
+  db,
+  type TailorAnyDBField,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { item as itemStub } from "../lib/_db_deps";
+import { valuationPolicy } from "./valuationPolicy";
+
+export interface CreateItemValuationTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+}
+
+export function createItemValuationType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreateItemValuationTypeParams<F>,
+) {
+  return db
+    .type("ItemValuation", {
+      itemId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: itemStub },
+          backward: "itemValuations",
+        })
+        .description("Foreign key to Item"),
+      valuationPolicyId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: valuationPolicy },
+          backward: "itemValuations",
+        })
+        .description("Foreign key to ValuationPolicy"),
+      totalQuantity: db.float().description("Total quantity in inventory"),
+      totalValue: db.float().description("Total inventory value"),
+      costPerUnit: db.float().description("Computed cost per unit (totalValue / totalQuantity)"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .indexes({
+      fields: ["itemId", "valuationPolicyId"],
+      unique: true,
+      name: "item_valuation_item_policy_idx",
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const itemValuation = createItemValuationType({});

package/src/modules/inventory/db/lot.ts

@@ -0,0 +1,51 @@
+import {
+  db,
+  type TailorAnyDBField,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { item as itemStub } from "../lib/_db_deps";
+
+export const LOT_STATUSES = ["ACTIVE", "FULLY_CONSUMED"] as const;
+
+export interface CreateLotTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+}
+
+export function createLotType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreateLotTypeParams<F>,
+) {
+  return db
+    .type("Lot", {
+      lotNumber: db.string().description("Lot/batch number, unique per item"),
+      itemId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: itemStub },
+          backward: "lots",
+        })
+        .description("Foreign key to Item"),
+      manufactureDate: db.datetime({ optional: true }).description("Date of manufacture"),
+      expirationDate: db
+        .datetime({ optional: true })
+        .description("Expiration date for shelf-life tracking"),
+      supplierLotReference: db
+        .string({ optional: true })
+        .description("Supplier's lot reference for traceability"),
+      status: db
+        .enum([...LOT_STATUSES] as [string, ...string[]])
+        .description("Consumption status: ACTIVE or FULLY_CONSUMED"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .indexes({
+      fields: ["lotNumber", "itemId"],
+      unique: true,
+      name: "lot_number_item_idx",
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const lot = createLotType({});

package/src/modules/inventory/db/lotStockLevel.ts

@@ -0,0 +1,48 @@
+import {
+  db,
+  type TailorAnyDBField,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { lot } from "./lot";
+import { storageLocation } from "./storageLocation";
+
+export interface CreateLotStockLevelTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+}
+
+export function createLotStockLevelType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreateLotStockLevelTypeParams<F>,
+) {
+  return db
+    .type("LotStockLevel", {
+      lotId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: lot },
+          backward: "lotStockLevels",
+        })
+        .description("Foreign key to Lot"),
+      storageLocationId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: storageLocation },
+          backward: "lotStockLevels",
+        })
+        .description("Foreign key to StorageLocation"),
+      onHand: db.float().description("Quantity of this lot on hand at this location"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .indexes({
+      fields: ["lotId", "storageLocationId"],
+      unique: true,
+      name: "lot_stock_level_lot_location_idx",
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const lotStockLevel = createLotStockLevelType({});

package/src/modules/inventory/db/serialNumber.ts

@@ -0,0 +1,53 @@
+import {
+  db,
+  type TailorAnyDBField,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { item as itemStub } from "../lib/_db_deps";
+import { storageLocation } from "./storageLocation";
+
+export const SERIAL_NUMBER_STATUSES = ["AVAILABLE", "ISSUED", "RETURNED", "SCRAPPED"] as const;
+
+export interface CreateSerialNumberTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+}
+
+export function createSerialNumberType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreateSerialNumberTypeParams<F>,
+) {
+  return db
+    .type("SerialNumber", {
+      serialNumber: db.string().description("Serial number value, unique per item"),
+      itemId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: itemStub },
+          backward: "serialNumbers",
+        })
+        .description("Foreign key to Item"),
+      storageLocationId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: storageLocation },
+          backward: "serialNumbers",
+        })
+        .description("Current storage location of the serial-tracked unit"),
+      status: db
+        .enum([...SERIAL_NUMBER_STATUSES] as [string, ...string[]])
+        .description("Lifecycle status: AVAILABLE, ISSUED, RETURNED, SCRAPPED"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .indexes({
+      fields: ["serialNumber", "itemId"],
+      unique: true,
+      name: "serial_number_item_idx",
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const serialNumber = createSerialNumberType({});

package/src/modules/inventory/db/stockLevel.ts

@@ -0,0 +1,51 @@
+import {
+  db,
+  type TailorAnyDBField,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { item as itemStub } from "../lib/_db_deps";
+import { storageLocation } from "./storageLocation";
+
+export interface CreateStockLevelTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+}
+
+export function createStockLevelType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreateStockLevelTypeParams<F>,
+) {
+  return db
+    .type("StockLevel", {
+      itemId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: itemStub },
+          backward: "stockLevels",
+        })
+        .description("Foreign key to Item"),
+      storageLocationId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: storageLocation },
+          backward: "stockLevels",
+        })
+        .description("Foreign key to StorageLocation"),
+      onHand: db.float().description("Quantity physically present"),
+      reserved: db.float().description("Quantity reserved for outbound orders"),
+      incoming: db.float().description("Quantity expected from inbound orders"),
+      blocked: db.float().description("Quantity blocked from use"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .indexes({
+      fields: ["itemId", "storageLocationId"],
+      unique: true,
+      name: "stock_level_item_location_idx",
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const stockLevel = createStockLevelType({});

package/src/modules/inventory/db/stockMoveLine.ts

@@ -0,0 +1,78 @@
+import {
+  db,
+  type TailorAnyDBField,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { item as itemStub } from "../lib/_db_deps";
+import { stockMovement } from "./stockMovement";
+import { storageLocation } from "./storageLocation";
+import { lot } from "./lot";
+import { serialNumber } from "./serialNumber";
+
+export interface CreateStockMoveLineTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+}
+
+export function createStockMoveLineType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreateStockMoveLineTypeParams<F>,
+) {
+  return db
+    .type("StockMoveLine", {
+      stockMovementId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: stockMovement },
+          backward: "stockMoveLines",
+        })
+        .description("Foreign key to StockMovement"),
+      itemId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: itemStub },
+          backward: "stockMoveLines",
+        })
+        .description("Foreign key to Item"),
+      quantity: db.float().description("Quantity to move, must be greater than 0"),
+      sourceLocationId: db
+        .uuid({ optional: true })
+        .relation({
+          type: "n-1",
+          toward: { type: storageLocation },
+          backward: "outboundMoveLines",
+        })
+        .description("Source storage location"),
+      destinationLocationId: db
+        .uuid({ optional: true })
+        .relation({
+          type: "n-1",
+          toward: { type: storageLocation },
+          backward: "inboundMoveLines",
+        })
+        .description("Destination storage location"),
+      lotId: db
+        .uuid({ optional: true })
+        .relation({
+          type: "n-1",
+          toward: { type: lot },
+          backward: "stockMoveLines",
+        })
+        .description("Optional foreign key to Lot for lot-tracked items"),
+      serialNumberId: db
+        .uuid({ optional: true })
+        .relation({
+          type: "n-1",
+          toward: { type: serialNumber },
+          backward: "stockMoveLines",
+        })
+        .description("Optional foreign key to SerialNumber for serial-tracked items"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const stockMoveLine = createStockMoveLineType({});

package/src/modules/inventory/db/stockMovement.ts

@@ -0,0 +1,48 @@
+import {
+  db,
+  type TailorAnyDBField,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+
+export const MOVEMENT_TYPES = [
+  "GOODS_RECEIPT",
+  "GOODS_ISSUE",
+  "INTERNAL_TRANSFER",
+  "BLOCK",
+  "UNBLOCK",
+] as const;
+
+export const BASE_STOCK_MOVEMENT_STATUSES = ["DRAFT", "CONFIRMED", "DONE", "CANCELLED"] as const;
+
+export interface CreateStockMovementTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+}
+
+export function createStockMovementType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreateStockMovementTypeParams<F>,
+) {
+  return db
+    .type("StockMovement", {
+      movementType: db
+        .enum([...MOVEMENT_TYPES] as [string, ...string[]])
+        .description(
+          "Movement type: GOODS_RECEIPT, GOODS_ISSUE, INTERNAL_TRANSFER, BLOCK, UNBLOCK",
+        ),
+      reasonCode: db
+        .string({ optional: true })
+        .description("Reason code, required for BLOCK and UNBLOCK"),
+      status: db
+        .enum([...BASE_STOCK_MOVEMENT_STATUSES] as [string, ...string[]])
+        .description("Lifecycle status: DRAFT, CONFIRMED, DONE, CANCELLED"),
+      executedAt: db
+        .datetime({ optional: true })
+        .description("Timestamp when the movement was executed"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const stockMovement = createStockMovementType({});

package/src/modules/inventory/db/storageLocation.ts

@@ -0,0 +1,56 @@
+import {
+  db,
+  type TailorAnyDBField,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { warehouse } from "./warehouse";
+
+export const BASE_STORAGE_LOCATION_STATUSES = ["ACTIVE", "INACTIVE"] as const;
+export const LOCATION_TYPES = ["zone", "bin"] as const;
+
+export interface CreateStorageLocationTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+}
+
+export function createStorageLocationType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreateStorageLocationTypeParams<F>,
+) {
+  return db
+    .type("StorageLocation", {
+      name: db.string().description("Location display name, unique within warehouse"),
+      code: db.string({ optional: true }).description("Location code, unique within warehouse"),
+      warehouseId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: warehouse },
+          backward: "storageLocations",
+        })
+        .description("Foreign key to Warehouse"),
+      parentId: db
+        .uuid({ optional: true })
+        .relation({
+          type: "n-1",
+          toward: { type: "self" },
+          backward: "children",
+        })
+        .description("Parent storage location (null for zones, zone id for bins)"),
+      locationType: db
+        .enum([...LOCATION_TYPES] as [string, ...string[]])
+        .description("Location type: zone or bin"),
+      storageCondition: db
+        .string({ optional: true })
+        .description("Storage condition: ambient, cold, hazardous"),
+      capacity: db.float({ optional: true }).description("Optional storage capacity"),
+      status: db
+        .enum([...BASE_STORAGE_LOCATION_STATUSES] as [string, ...string[]])
+        .description("Lifecycle status: ACTIVE, INACTIVE"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const storageLocation = createStorageLocationType({});

package/src/modules/inventory/db/valuationPolicy.ts

@@ -0,0 +1,33 @@
+import {
+  db,
+  type TailorAnyDBField,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+
+export const COSTING_METHODS = ["FIFO", "AVCO", "STANDARD_COST"] as const;
+
+export interface CreateValuationPolicyTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+}
+
+export function createValuationPolicyType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreateValuationPolicyTypeParams<F>,
+) {
+  return db
+    .type("ValuationPolicy", {
+      name: db.string().description("Policy display name"),
+      costingMethod: db
+        .enum([...COSTING_METHODS] as [string, ...string[]])
+        .description("Costing method: FIFO, AVCO, or STANDARD_COST"),
+      standardCostRate: db
+        .float({ optional: true })
+        .description("Fixed cost rate, required when costingMethod is STANDARD_COST"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const valuationPolicy = createValuationPolicyType({});

package/src/modules/inventory/db/warehouse.ts

@@ -0,0 +1,45 @@
+import {
+  db,
+  type TailorAnyDBField,
+  type TailorAnyDBType,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { site as siteStub } from "../lib/_db_deps";
+
+export const BASE_WAREHOUSE_STATUSES = ["ACTIVE", "INACTIVE"] as const;
+
+export interface CreateWarehouseTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+  siteType: TailorAnyDBType;
+}
+
+export function createWarehouseType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreateWarehouseTypeParams<F>,
+) {
+  return db
+    .type("Warehouse", {
+      name: db.string().description("Warehouse display name, unique within site"),
+      siteId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.siteType },
+          backward: "warehouses",
+        })
+        .description("Foreign key to Site"),
+      storageCondition: db
+        .string({ optional: true })
+        .description("Storage condition: ambient, cold, hazardous"),
+      capacity: db.float({ optional: true }).description("Optional storage capacity"),
+      status: db
+        .enum([...BASE_WAREHOUSE_STATUSES] as [string, ...string[]])
+        .description("Lifecycle status: ACTIVE, INACTIVE"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const warehouse = createWarehouseType({ siteType: siteStub });

package/src/modules/inventory/docs/commands/ApproveCountLine.md

@@ -0,0 +1,44 @@
+# ApproveCountLine
+
+## Overview
+
+approveCountLine approves a count line variance, transitioning it from PENDING to APPROVED status. When the variance is non-zero, an inventory adjustment is automatically generated with the reason "inventory-count" to reconcile the difference. Zero-variance lines are approved without generating an adjustment.
+
+## Business Rules
+
+- Count line must be in PENDING status
+- Approving a line with non-zero variance generates an inventory adjustment with reason "inventory-count"
+- Zero-variance lines are approved without generating an adjustment
+- Can also auto-approve lines within a configured tolerance
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive approve request] --> B{Count line exists?}
+    B -->|No| C[Return error: COUNT_LINE_NOT_FOUND]
+    B -->|Yes| D{Line status PENDING?}
+    D -->|No| E[Return error: COUNT_LINE_NOT_PENDING]
+    D -->|Yes| F[Approve count line]
+    F --> G{Variance ≠ 0?}
+    G -->|Yes| H[Generate inventory adjustment]
+    H --> I[Return approved line]
+    G -->|No| I
+```
+
+## External Dependencies
+
+- None (generates [InventoryAdjustment](../models/InventoryAdjustment.md) internally)
+
+## Error Scenarios
+
+- **COUNT_LINE_NOT_FOUND**: Referenced count line does not exist
+- **COUNT_LINE_NOT_PENDING**: Count line is not in PENDING status
+
+## Test Cases
+
+- returns error when not found
+- returns error when not pending
+- approves line
+- generates adjustment for non-zero variance
+- zero variance approved without adjustment

package/src/modules/inventory/docs/commands/ApproveInventoryAdjustment.md

@@ -0,0 +1,37 @@
+# ApproveInventoryAdjustment
+
+## Overview
+
+approveInventoryAdjustment approves a pending inventory adjustment, transitioning it from PENDING_APPROVAL to APPROVED status. An approved adjustment can then be confirmed to apply the stock level changes.
+
+## Business Rules
+
+- Adjustment must exist
+- Adjustment must be in PENDING_APPROVAL status
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive approve request] --> B{Adjustment exists?}
+    B -->|No| C[Return error: ADJUSTMENT_NOT_FOUND]
+    B -->|Yes| D{Status is PENDING_APPROVAL?}
+    D -->|No| E[Return error: ADJUSTMENT_NOT_PENDING_APPROVAL]
+    D -->|Yes| F[Update status to APPROVED]
+    F --> G[Return updated adjustment]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **ADJUSTMENT_NOT_FOUND**: Referenced adjustment does not exist
+- **ADJUSTMENT_NOT_PENDING_APPROVAL**: Adjustment is not in PENDING_APPROVAL status
+
+## Test Cases
+
+- returns error when not found
+- returns error when not pending
+- approves adjustment

package/src/modules/inventory/docs/commands/AssignSerialNumber.md

@@ -0,0 +1,46 @@
+# AssignSerialNumber
+
+## Overview
+
+assignSerialNumber assigns a unique serial number to an individual unit at goods receipt or production completion. The serial number is created in AVAILABLE state and is associated with a specific item and storage location. Serial numbers enable tracking of individual units throughout their lifecycle.
+
+## Business Rules
+
+- serialNumber is required and must be unique per item
+- itemId is required and must reference an existing item
+- storageLocationId is required and must reference an existing storage location (where the unit is received)
+- Quantity is always 1 (serial numbers track individual units)
+- Serial number is created in AVAILABLE state
+- The same serial number value can be used for different items
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive assign request] --> B{Item exists?}
+    B -->|No| C[Return error: ITEM_NOT_FOUND]
+    B -->|Yes| D{Location exists?}
+    D -->|No| E[Return error: STORAGE_LOCATION_NOT_FOUND]
+    D -->|Yes| F{Serial unique for item?}
+    F -->|No| G[Return error: DUPLICATE_SERIAL_NUMBER]
+    F -->|Yes| H[Create serial number in AVAILABLE state]
+    H --> I[Return created serial number]
+```
+
+## External Dependencies
+
+- [item-management::Item](../../../item-management/docs/models/Item.md) - Validates that the referenced item exists
+
+## Error Scenarios
+
+- **ITEM_NOT_FOUND**: Referenced item does not exist
+- **STORAGE_LOCATION_NOT_FOUND**: Referenced storage location does not exist
+- **DUPLICATE_SERIAL_NUMBER**: A serial number with the same value already exists for this item
+
+## Test Cases
+
+- returns error when item not found
+- returns error when location not found
+- returns error when serial already exists for item
+- assigns serial in AVAILABLE state
+- allows same serial number for different items