@things-factory/worksheet-base 4.3.693 → 4.3.694

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/worksheet-base",
-  "version": "4.3.693",
+  "version": "4.3.694",
   "main": "dist-server/index.js",
   "browser": "client/index.js",
   "things-factory": true,
@@ -27,24 +27,24 @@
     "@things-factory/biz-base": "^4.3.689",
     "@things-factory/document-template-base": "^4.3.689",
     "@things-factory/id-rule-base": "^4.3.689",
-    "@things-factory/integration-accounting": "^4.3.689",
+    "@things-factory/integration-accounting": "^4.3.694",
     "@things-factory/integration-base": "^4.3.689",
     "@things-factory/integration-lmd": "^4.3.689",
     "@things-factory/integration-marketplace": "^4.3.689",
     "@things-factory/integration-powrup": "^4.3.689",
     "@things-factory/integration-sellercraft": "^4.3.689",
     "@things-factory/integration-sftp": "^4.3.689",
-    "@things-factory/marketplace-base": "^4.3.689",
+    "@things-factory/marketplace-base": "^4.3.694",
     "@things-factory/notification": "^4.3.689",
-    "@things-factory/sales-base": "^4.3.693",
+    "@things-factory/sales-base": "^4.3.694",
     "@things-factory/setting-base": "^4.3.689",
     "@things-factory/shell": "^4.3.689",
     "@things-factory/transport-base": "^4.3.689",
-    "@things-factory/warehouse-base": "^4.3.691",
+    "@things-factory/warehouse-base": "^4.3.694",
     "@things-factory/worksheet-ui": "^4.3.689",
     "jspdf": "2.5.1",
     "puppeteer": "21.0.3",
     "uuid": "^9.0.0"
   },
-  "gitHead": "e8372d502e3b7e99b9918eae3ed57093a50660bf"
+  "gitHead": "a1bf668bd52a6b9f12b719ca1467beb423270400"
 }

package/server/controllers/inbound/putaway-worksheet-controller.ts

@@ -28,6 +28,7 @@ import { Worksheet, WorksheetDetail } from '../../entities'
 import { webhookHandler, WebhookEventsEnum } from '@things-factory/integration-base'
 import { switchLocationStatus } from '../../utils'
 import { VasWorksheetController } from '../vas/vas-worksheet-controller'
+import { isInventoryExpiring } from '../../utils/inventory-util'
 
 export class PutawayWorksheetController extends VasWorksheetController {
   async generatePutawayWorksheet(arrivalNoticeId: string, inventories: Inventory[]): Promise<Worksheet> {
@@ -122,6 +123,89 @@ export class PutawayWorksheetController extends VasWorksheetController {
     }
   }
 
+  private async validateLocationLevel3(inventory: Inventory, location: Location): Promise<void> {
+    // Only enforce for level 3
+    const levelSetting: Setting = await this.trxMgr.getRepository(Setting).findOne({
+      where: { domain: this.domain, name: 'location-recommendation-level' }
+    })
+    if (levelSetting?.value !== 'level 3') return
+
+    // Expiry enforcement: quarantine only
+    const expiring = await isInventoryExpiring(inventory)
+    if (expiring) {
+      if (location.type !== LOCATION_TYPE.QUARANTINE) {
+        throw new Error('Expiring inventory must be stored in QUARANTINE location')
+      }
+      return
+    }
+
+    // Allowed types (ranking is used for recommendation; validation enforces allowed set)
+    const allowedTypes = [LOCATION_TYPE.STORAGE, LOCATION_TYPE.SHELF, LOCATION_TYPE.FLOOR]
+    if (!allowedTypes.includes(location.type as any)) {
+      throw new Error('Scanned location type is not allowed for putaway (allowed: STORAGE, SHELF, FLOOR)')
+    }
+
+    // Stacking limits
+    const stackingSetting: Setting = await this.trxMgr.getRepository(Setting).findOne({
+      where: { domain: this.domain, name: 'stacking-option-limit' }
+    })
+    let minLimit = 1
+    let maxLimit = 1
+    if (stackingSetting?.value) {
+      try {
+        const parsed = JSON.parse(stackingSetting.value)
+        minLimit = Number(parsed.Min ?? parsed.min ?? minLimit) || minLimit
+        maxLimit = Number(parsed.Max ?? parsed.max ?? maxLimit) || maxLimit
+      } catch (e) {}
+    }
+
+    // Ensure product is loaded to check allowStackingOption
+    if (!inventory.product) {
+      inventory = await this.trxMgr.getRepository(Inventory).findOne({
+        where: { id: inventory.id },
+        relations: ['product']
+      })
+    }
+    const stackingLimit = inventory.product?.allowStackingOption ? maxLimit : minLimit
+
+    // Count inventories in the scanned location
+    const totalCount = await this.trxMgr
+      .getRepository(Inventory)
+      .createQueryBuilder('inv')
+      .leftJoin('inv.location', 'loc')
+      .where('loc.id = :locId', { locId: location.id })
+      .andWhere('inv.status = :status', { status: INVENTORY_STATUS.STORED })
+      .getCount()
+
+    if (totalCount >= stackingLimit) {
+      throw new Error('Scanned location reached stacking limit for this product')
+    }
+
+    if (totalCount > 0) {
+      // Homogeneity check: ensure all inventories match product, batch, expiration
+      const params: any = { pid: inventory.product.id }
+      const batchCond = inventory.batchId ? 'inv.batchId = :batchId' : 'inv.batchId IS NULL'
+      if (inventory.batchId) params.batchId = inventory.batchId
+      const expCond = inventory.expirationDate ? 'inv.expirationDate = :exp' : 'inv.expirationDate IS NULL'
+      if (inventory.expirationDate) params.exp = inventory.expirationDate
+
+      const matchCount = await this.trxMgr
+        .getRepository(Inventory)
+        .createQueryBuilder('inv')
+        .leftJoin('inv.product', 'product')
+        .leftJoin('inv.location', 'loc')
+        .where('loc.id = :locId', { locId: location.id })
+        .andWhere('inv.status = :status', { status: INVENTORY_STATUS.STORED })
+        .andWhere('product.id = :pid', params)
+        .andWhere(batchCond, params)
+        .andWhere(expCond, params)
+        .getCount()
+
+      if (matchCount !== totalCount) {
+        throw new Error('Scanned location contains different SKU/batch/expiry; not allowed for level 3')
+      }
+    }
+  }
   async activatePutaway(worksheetNo: string, putawayWorksheetDetails: Partial<WorksheetDetail>[]): Promise<Worksheet> {
     let worksheet: Worksheet = await this.findActivatableWorksheet(worksheetNo, WORKSHEET_TYPE.PUTAWAY, [
       'arrivalNotice',
@@ -274,6 +358,7 @@ export class PutawayWorksheetController extends VasWorksheetController {
         relations: ['warehouse']
       })
       if (!location) throw new Error(this.ERROR_MSG.FIND.NO_RESULT(locationName))
+      await this.validateLocationLevel3(inventory, location)
       const warehouse: Warehouse = location.warehouse
       const zone: string = location.zone
 
@@ -332,6 +417,7 @@ export class PutawayWorksheetController extends VasWorksheetController {
       })
 
       if (!location) throw new Error(this.ERROR_MSG.FIND.NO_RESULT(locationName))
+      await this.validateLocationLevel3(inventory, location)
       const warehouse: Warehouse = location.warehouse
       const zone: string = warehouse.zone
 
@@ -385,6 +471,7 @@ export class PutawayWorksheetController extends VasWorksheetController {
       relations: ['warehouse']
     })
     if (!location) throw new Error(this.ERROR_MSG.FIND.NO_RESULT(locationName))
+    await this.validateLocationLevel3(inventory, location)
     const warehouse: Warehouse = location.warehouse
     const zone: string = warehouse.zone
 

package/server/graphql/resolvers/worksheet/index.ts

@@ -41,7 +41,7 @@ import { putawayReplenishmentWorksheetResolver } from './putaway-replenishment-w
 import { Mutations as PutawayReturnMutations } from './putaway-return'
 import { putawayReturningWorksheetResolver } from './putaway-returning-worksheet'
 import { putawayWorksheetResolver } from './putaway-worksheet'
-import { recommendPutawayLocationResolver } from './recommend-putway-location'
+import { recommendPutawayLocationResolver } from './recommend-putaway-location'
 import { refreshActiveWorksheetPickingViews } from './refresh-active-worksheet-picking-views'
 import { rejectCancellationReleaseOrder } from './reject-cancellation-release-order'
 import { replacePickingPalletsResolver } from './replace-picking-pallets'

package/server/graphql/resolvers/worksheet/recommend-putaway-location.ts

@@ -0,0 +1,423 @@
+import { getRepository, In } from 'typeorm'
+
+import { ArrivalNotice, ReturnOrder } from '@things-factory/sales-base'
+import { Setting } from '@things-factory/setting-base'
+import { Domain } from '@things-factory/shell'
+import { Inventory, Location, LOCATION_STATUS, LOCATION_TYPE, Warehouse } from '@things-factory/warehouse-base'
+
+import { WORKSHEET_STATUS, WORKSHEET_TYPE } from '../../../constants'
+import { Worksheet, WorksheetDetail } from '../../../entities'
+import { isInventoryExpiring } from '../../../utils/inventory-util'
+
+export const recommendPutawayLocationResolver = {
+  async recommendPutawayLocation(
+    _: void,
+    { worksheetDetailName, optCnt = 1 }: { worksheetDetailName: string; optCnt: number },
+    context: any
+  ): Promise<Location[]> {
+    const domain: Domain = context.state.domain
+
+    const worksheetDetail: WorksheetDetail = await getRepository(WorksheetDetail).findOne(
+      { domain, name: worksheetDetailName },
+      {
+        relations: [
+          'worksheet',
+          'worksheet.arrivalNotice',
+          'worksheet.returnOrder',
+          'targetInventory',
+          'targetInventory.inventory',
+          'targetInventory.inventory.product'
+        ]
+      }
+    )
+
+    const inventory: Inventory = worksheetDetail.targetInventory.inventory
+    if (worksheetDetail.status !== WORKSHEET_STATUS.EXECUTING) throw new Error('Current target is not processing')
+
+    const arrivalNotice: ArrivalNotice = worksheetDetail.worksheet.arrivalNotice
+    const returnOrder: ReturnOrder = worksheetDetail.worksheet.returnOrder
+
+    let unloadingWS: Worksheet
+    if (arrivalNotice) {
+      unloadingWS = await getRepository(Worksheet).findOne({
+        where: { domain, arrivalNotice, type: WORKSHEET_TYPE.UNLOADING },
+        relations: ['bufferLocation', 'bufferLocation.warehouse']
+      })
+    } else if (returnOrder) {
+      unloadingWS = await getRepository(Worksheet).findOne({
+        where: { domain, returnOrder, type: WORKSHEET_TYPE.UNLOADING_RETURN },
+        relations: ['bufferLocation', 'bufferLocation.warehouse']
+      })
+    }
+
+    const targetWarehouse: Warehouse = unloadingWS.bufferLocation.warehouse
+    const sortingLevelSetting: Setting = await getRepository(Setting).findOne({
+      where: { domain, name: 'location-recommendation-level' }
+    })
+    const sortingLevel = sortingLevelSetting?.value
+
+    const isExpiring: boolean = await isInventoryExpiring(inventory)
+
+    let recommendedLocations: Location[] = []
+    if (isExpiring) {
+      switch (sortingLevel) {
+        case 'level 1':
+        case 'level 2':
+          recommendedLocations = await recommendQuarantineLocationLevel1(domain, targetWarehouse, optCnt)
+          break
+
+        default:
+          recommendedLocations = await recommendQuarantineLocationLevel1(domain, targetWarehouse, optCnt)
+          break
+      }
+    }
+
+    if (recommendedLocations.length > 0) return recommendedLocations
+
+    switch (sortingLevel) {
+      case 'level 1':
+        recommendedLocations = await recommendLocationLevel1(domain, targetWarehouse, optCnt)
+        break
+
+      case 'level 2':
+        recommendedLocations = await recommendLocationLevel2(domain, targetWarehouse, optCnt, inventory.product.id)
+        break
+
+      case 'level 3':
+        recommendedLocations = await recommendLocationLevel3(domain, targetWarehouse, optCnt, inventory)
+        break
+
+      default:
+        recommendedLocations = await recommendLocationLevel1(domain, targetWarehouse, optCnt)
+        break
+    }
+
+    return recommendedLocations
+  }
+}
+
+export async function recommendLocationLevel1(
+  domain: Domain,
+  warehouse: Warehouse,
+  optCnt: number
+): Promise<Location[]> {
+  return await getEmptyLocations(domain, warehouse, optCnt, [LOCATION_TYPE.SHELF, LOCATION_TYPE.FLOOR])
+}
+
+export async function recommendLocationLevel2(
+  domain: Domain,
+  warehouse: Warehouse,
+  optCnt: number,
+  productId: string
+): Promise<Location[]> {
+  return await getLevel2Location(
+    domain,
+    warehouse,
+    optCnt,
+    [LOCATION_TYPE.STORAGE, LOCATION_TYPE.SHELF, LOCATION_TYPE.FLOOR],
+    productId
+  )
+}
+
+export async function recommendQuarantineLocationLevel1(
+  domain: Domain,
+  warehouse: Warehouse,
+  optCnt: number
+): Promise<Location[]> {
+  return await getEmptyLocations(domain, warehouse, optCnt, [LOCATION_TYPE.QUARANTINE])
+}
+
+export async function getEmptyLocations(
+  domain: Domain,
+  warehouse: Warehouse,
+  optCnt: number,
+  allowedTypes: LOCATION_TYPE[]
+): Promise<Location[]> {
+  const orderSetting: Setting = await getRepository(Setting).findOne({
+    where: { domain, name: 'rule-for-storing-product' }
+  })
+  let order = {}
+  if (orderSetting?.value) order = JSON.parse(orderSetting.value)
+
+  return await getRepository(Location).find({
+    where: {
+      domain,
+      warehouse,
+      status: LOCATION_STATUS.EMPTY,
+      type: In(allowedTypes)
+    },
+    order,
+    take: optCnt
+  })
+}
+
+export async function getLevel2Location(
+  domain: Domain,
+  warehouse: Warehouse,
+  optCnt: number,
+  allowedTypes: LOCATION_TYPE[],
+  productId: string
+): Promise<Location[]> {
+  let sortLocation: Record<string, 'ASC' | 'DESC'> = {}
+  const recommended: Location[] = []
+
+  // -------- rule-for-storing-product (ordering) ----------
+  const orderSetting: Setting | undefined = await getRepository(Setting).findOne({
+    where: { domain, name: 'rule-for-storing-product' }
+  })
+
+  if (orderSetting?.value) {
+    try {
+      // e.g. {"zone":"ASC","row":"ASC","column":"ASC","shelf":"ASC"}
+      sortLocation = JSON.parse(orderSetting.value)
+    } catch {
+      // ignore malformed setting, fallback to no extra ordering
+    }
+  }
+
+  // -------- main logic per allowed type ----------
+  for (const type of allowedTypes) {
+    if (recommended.length >= optCnt) break
+
+    // 1) OCCUPIED locations that already store this product,
+    //    ordered by *product qty per location* ASC (minimal first).
+    //
+    // product_qty := SUM(inv.qty) WHERE inv.product = :productId AND inv.status='STORED'
+    const qbLoc = await getRepository(Location)
+      .createQueryBuilder('location')
+      .select('location.id', 'id')
+      .addSelect(
+        `COALESCE(SUM(CASE WHEN inv.product = :productId AND inv.status = :stored THEN inv.qty ELSE 0 END), 0)`,
+        'product_qty'
+      )
+      .leftJoin(Inventory, 'inv', 'inv.location = location.id AND inv.domain = :domain', { domain: domain.id })
+      .where('location.domain = :domain', { domain: domain.id })
+      .andWhere('location.warehouse = :warehouse', { warehouse: warehouse.id })
+      .andWhere('location.status = :status', { status: LOCATION_STATUS.OCCUPIED })
+      .andWhere('location.type = :type', { type })
+      .groupBy('location.id')
+      // keep only locations where this product exists
+      .having(
+        `COALESCE(SUM(CASE WHEN inv.product = :productId AND inv.status = :stored THEN inv.qty ELSE 0 END), 0) > 0`,
+        { productId, stored: 'STORED' }
+      )
+      .orderBy('product_qty', 'ASC') // minimal qty first
+
+    // secondary ordering: rule-for-storing-product
+    Object.entries(sortLocation).forEach(([key, value]) => {
+      qbLoc.addOrderBy(`location.${key}`, value as 'ASC' | 'DESC')
+    })
+
+    qbLoc.limit(optCnt - recommended.length)
+
+    const rows = await qbLoc.getRawMany<{ id: string; product_qty: string }>()
+    if (rows.length > 0) {
+      const ids = rows.map(r => r.id)
+
+      const locEntities = await getRepository(Location).find({
+        where: { id: In(ids) as any }
+      })
+
+      const byId: Map<string, Location> = new Map(locEntities.map((l: Location) => [l.id, l as Location]))
+      for (const id of ids) {
+        const loc = byId.get(id)
+        if (loc) {
+          recommended.push(loc)
+          if (recommended.length >= optCnt) break
+        }
+      }
+    }
+
+    // 2) If still not enough, suggest EMPTY locations for that type,
+    //    ordered purely by rule-for-storing-product.
+    if (recommended.length < optCnt) {
+      const empties = await getRepository(Location).find({
+        where: {
+          domain,
+          warehouse,
+          status: LOCATION_STATUS.EMPTY,
+          type
+        } as any,
+        order: sortLocation,
+        take: optCnt - recommended.length
+      })
+
+      recommended.push(...empties)
+    }
+  }
+
+  // de-duplicate in case of weird overlaps & hard-limit to optCnt
+  const seen = new Set<string>()
+  const unique = recommended.filter(loc => {
+    if (seen.has(loc.id)) return false
+    seen.add(loc.id)
+    return true
+  })
+
+  return unique.slice(0, optCnt)
+}
+
+export async function recommendLocationLevel3(
+  domain: Domain,
+  warehouse: Warehouse,
+  optCnt: number,
+  inventory: Inventory
+): Promise<Location[]> {
+  // -------- order (rule-for-storing-product) ----------
+  let sortLocation: Record<string, 'ASC' | 'DESC'> = {}
+  const orderSetting: Setting | undefined = await getRepository(Setting).findOne({
+    where: { domain, name: 'rule-for-storing-product' }
+  })
+
+  if (orderSetting?.value) {
+    try {
+      const parsed = JSON.parse(orderSetting.value)
+      // Expecting something like: {"zone":"ASC","row":"ASC","column":"ASC","shelf":"ASC"}
+      sortLocation = parsed
+    } catch {
+      // ignore malformed order setting
+    }
+  }
+
+  // -------- stacking limit (Min/Max depending on allowStackingOption) ----------
+  const stackingSetting: Setting | undefined = await getRepository(Setting).findOne({
+    where: { domain, name: 'stacking-option-limit' }
+  })
+
+  let minLimit = 1
+  let maxLimit = 1
+  if (stackingSetting?.value) {
+    const parsed = (() => {
+      try {
+        return JSON.parse(stackingSetting.value)
+      } catch (e) {
+        throw new Error('Invalid stacking-option-limit setting: must be valid JSON')
+      }
+    })()
+
+    const parsedMin = Number(parsed.Min ?? parsed.min)
+    const parsedMax = Number(parsed.Max ?? parsed.max)
+
+    if (Number.isNaN(parsedMin) || Number.isNaN(parsedMax)) {
+      throw new Error('Invalid stacking-option-limit setting: limits must be numeric')
+    }
+
+    if (parsedMin > parsedMax) {
+      throw new Error('Kindly ensure your min limit is lower than your max limit')
+    }
+
+    minLimit = parsedMin
+    maxLimit = parsedMax
+  }
+
+  const stackingLimit = inventory.product?.allowStackingOption ? maxLimit : minLimit
+
+  // -------- matching keys (product/batch/expiry) ----------
+  const productId = inventory.product?.id
+  if (!productId) return []
+
+  // Treat both NULL and literal '-' as "no batch" if that is how your data behaves
+  const normalizeBatch = (v: string | null | undefined) => (v === undefined || v === null || v === '' ? null : v)
+
+  const batchIdParam = normalizeBatch(inventory.batchId)
+  const expDateParam = inventory.expirationDate ?? null
+
+  const allowedTypesInOrder: LOCATION_TYPE[] = [LOCATION_TYPE.STORAGE, LOCATION_TYPE.SHELF, LOCATION_TYPE.FLOOR]
+
+  const recommended: Location[] = []
+
+  for (const type of allowedTypesInOrder) {
+    if (recommended.length >= optCnt) break
+
+    // ---------------- OCCUPIED, HOMOGENEOUS, UNDER CAPACITY ----------------
+    // Single join to inventories, then conditional aggregates:
+    //  total_cnt = SUM(inv.id is not null)
+    //  match_cnt = SUM(inv matches product/batch/expiry)
+    const matchPreds: string[] = [
+      'inv.status = :stored',
+      'inv.product = :productId',
+      batchIdParam == null ? 'inv.batchId IS NULL' : 'inv.batchId = :batchId',
+      expDateParam == null ? 'inv.expirationDate IS NULL' : 'inv.expirationDate = :expDate'
+    ]
+
+    const matchParams: any = {
+      stored: 'STORED',
+      productId
+    }
+    if (batchIdParam != null) matchParams.batchId = batchIdParam
+    if (expDateParam != null) matchParams.expDate = expDateParam
+
+    const qbLoc = await getRepository(Location)
+      .createQueryBuilder('location')
+      .select('location.id', 'id')
+      .leftJoin(Inventory, 'inv', 'inv.location = location.id AND inv.status = :stored', { stored: 'STORED' })
+      .where('location.domain = :domain', { domain: domain.id })
+      .andWhere('location.warehouse = :warehouse', { warehouse: warehouse.id })
+      .andWhere('location.status = :status', { status: LOCATION_STATUS.OCCUPIED })
+      .andWhere('location.type = :type', { type })
+
+      .groupBy('location.id')
+      // homogeneous: total_cnt == match_cnt
+      .having(
+        `
+        SUM(CASE WHEN inv.id IS NOT NULL THEN 1 ELSE 0 END)
+        =
+        SUM(CASE WHEN ${matchPreds.join(' AND ')} THEN 1 ELSE 0 END)
+        `,
+        matchParams
+      )
+      // under capacity
+      .andHaving(
+        `
+        SUM(CASE WHEN inv.id IS NOT NULL THEN 1 ELSE 0 END) < :stackLimit
+        `,
+        { stackLimit: stackingLimit }
+      )
+      // prefer topping up partially-filled first
+      .orderBy('SUM(CASE WHEN inv.id IS NOT NULL THEN 1 ELSE 0 END)', 'DESC')
+
+    // secondary sort per rule-for-storing-product
+    Object.entries(sortLocation).forEach(([key, value]) => {
+      qbLoc.addOrderBy(`location.${key}`, value as 'ASC' | 'DESC')
+    })
+
+    // Only fetch as many as we still need
+    qbLoc.limit(optCnt - recommended.length)
+
+    const locIdsRaw = await qbLoc.getRawMany()
+    const occupiedLocationIds: string[] = locIdsRaw.map(r => r.id)
+
+    if (occupiedLocationIds.length > 0) {
+      const occupiedLocations = await getRepository(Location).find({
+        where: { id: In(occupiedLocationIds) }
+      })
+      // keep the order from occupiedLocationIds
+      const byId = new Map(occupiedLocations.map((l: Location) => [l.id, l]))
+      for (const id of occupiedLocationIds) {
+        const loc = byId.get(id)
+        if (loc) {
+          recommended.push(loc)
+          if (recommended.length >= optCnt) break
+        }
+      }
+    }
+
+    // ---------------- EMPTY fallback (same type, ordered by rule) ----------------
+    if (recommended.length < optCnt) {
+      const emptyLocations = await getRepository(Location).find({
+        where: {
+          domain,
+          warehouse,
+          status: LOCATION_STATUS.EMPTY,
+          type
+        },
+        order: sortLocation,
+        take: optCnt - recommended.length
+      })
+
+      recommended.push(...emptyLocations)
+    }
+  }
+
+  return recommended.slice(0, optCnt)
+}