adserver-dashboard 1.0.0

package/PCM/src/services/LineItemStatusService.js

@@ -0,0 +1,380 @@
+import { normalizeSource, SOURCE_TYPES as NORMALIZED_SOURCE_TYPES } from '../utils/sourceNormalizer.js';
+import { CAMPAIGN_STATUSES, WORKFLOW_TYPES, SOURCE_TYPES, TRANSITION_OWNERS } from './CampaignStatusService.js';
+
+export const LINE_ITEM_STATUSES = {
+  DRAFT: 'DRAFT',
+  GENERATED: 'GENERATED',
+  REQUESTED: 'REQUESTED',
+  PENDING: 'PENDING',
+  APPROVED: 'APPROVED',
+  LIVE: 'LIVE',
+  COMPLETED: 'COMPLETED',
+  EXPIRED: 'EXPIRED',
+  REJECTED: 'REJECTED',
+  ARCHIVED: 'ARCHIVED',
+  REOPENED: 'REOPENED'
+};
+
+const VALID_TRANSITIONS = {
+  [LINE_ITEM_STATUSES.DRAFT]: [
+    LINE_ITEM_STATUSES.GENERATED,
+    LINE_ITEM_STATUSES.ARCHIVED
+  ],
+  [LINE_ITEM_STATUSES.GENERATED]: [
+    LINE_ITEM_STATUSES.REQUESTED,
+    LINE_ITEM_STATUSES.PENDING,
+    LINE_ITEM_STATUSES.APPROVED,
+    LINE_ITEM_STATUSES.REJECTED,
+    LINE_ITEM_STATUSES.ARCHIVED
+  ],
+  [LINE_ITEM_STATUSES.REQUESTED]: [
+    LINE_ITEM_STATUSES.PENDING,
+    LINE_ITEM_STATUSES.APPROVED,
+    LINE_ITEM_STATUSES.REJECTED,
+    LINE_ITEM_STATUSES.ARCHIVED
+  ],
+  [LINE_ITEM_STATUSES.PENDING]: [
+    LINE_ITEM_STATUSES.APPROVED,
+    LINE_ITEM_STATUSES.REJECTED,
+    LINE_ITEM_STATUSES.ARCHIVED
+  ],
+  [LINE_ITEM_STATUSES.APPROVED]: [
+    LINE_ITEM_STATUSES.LIVE,
+    LINE_ITEM_STATUSES.EXPIRED,
+    LINE_ITEM_STATUSES.REJECTED,
+    LINE_ITEM_STATUSES.ARCHIVED,
+    LINE_ITEM_STATUSES.REOPENED
+  ],
+  [LINE_ITEM_STATUSES.LIVE]: [
+    LINE_ITEM_STATUSES.COMPLETED,
+    LINE_ITEM_STATUSES.ARCHIVED,
+    LINE_ITEM_STATUSES.REOPENED
+  ],
+  [LINE_ITEM_STATUSES.COMPLETED]: [
+    LINE_ITEM_STATUSES.ARCHIVED,
+    LINE_ITEM_STATUSES.REOPENED
+  ],
+  [LINE_ITEM_STATUSES.EXPIRED]: [
+    LINE_ITEM_STATUSES.ARCHIVED,
+    LINE_ITEM_STATUSES.REOPENED
+  ],
+  [LINE_ITEM_STATUSES.REJECTED]: [
+    LINE_ITEM_STATUSES.ARCHIVED,
+    LINE_ITEM_STATUSES.REOPENED
+  ],
+  [LINE_ITEM_STATUSES.ARCHIVED]: [
+    LINE_ITEM_STATUSES.REOPENED
+  ],
+  [LINE_ITEM_STATUSES.REOPENED]: [
+    LINE_ITEM_STATUSES.PENDING,
+    LINE_ITEM_STATUSES.APPROVED,
+    LINE_ITEM_STATUSES.LIVE,
+    LINE_ITEM_STATUSES.ARCHIVED
+  ]
+};
+
+const STATUSES_ALLOWING_REOPEN = [
+  LINE_ITEM_STATUSES.APPROVED,
+  LINE_ITEM_STATUSES.LIVE,
+  LINE_ITEM_STATUSES.COMPLETED,
+  LINE_ITEM_STATUSES.EXPIRED,
+  LINE_ITEM_STATUSES.REJECTED,
+  LINE_ITEM_STATUSES.ARCHIVED
+];
+
+const EDITABLE_STATUSES = [
+  LINE_ITEM_STATUSES.GENERATED,
+  LINE_ITEM_STATUSES.REQUESTED,
+  LINE_ITEM_STATUSES.REOPENED
+];
+
+const PACING_EDITABLE_STATUSES = [
+  LINE_ITEM_STATUSES.GENERATED,
+  LINE_ITEM_STATUSES.REQUESTED,
+  LINE_ITEM_STATUSES.REOPENED,
+  LINE_ITEM_STATUSES.APPROVED,
+  LINE_ITEM_STATUSES.LIVE
+];
+
+const SCHEDULE_EDITABLE_STATUSES = [
+  LINE_ITEM_STATUSES.GENERATED,
+  LINE_ITEM_STATUSES.REQUESTED,
+  LINE_ITEM_STATUSES.REOPENED
+];
+
+const INVENTORY_EDITABLE_STATUSES = [
+  LINE_ITEM_STATUSES.GENERATED,
+  LINE_ITEM_STATUSES.REQUESTED,
+  LINE_ITEM_STATUSES.REOPENED
+];
+
+const CAMPAIGN_TO_LINE_ITEM_CASCADE = {
+  [CAMPAIGN_STATUSES.PENDING]: LINE_ITEM_STATUSES.PENDING,
+  [CAMPAIGN_STATUSES.APPROVED]: LINE_ITEM_STATUSES.APPROVED,
+  [CAMPAIGN_STATUSES.LIVE]: LINE_ITEM_STATUSES.LIVE,
+  [CAMPAIGN_STATUSES.COMPLETED]: LINE_ITEM_STATUSES.COMPLETED,
+  [CAMPAIGN_STATUSES.EXPIRED]: LINE_ITEM_STATUSES.EXPIRED,
+  [CAMPAIGN_STATUSES.REJECTED]: LINE_ITEM_STATUSES.REJECTED,
+  [CAMPAIGN_STATUSES.ARCHIVED]: LINE_ITEM_STATUSES.ARCHIVED,
+  [CAMPAIGN_STATUSES.REOPENED]: LINE_ITEM_STATUSES.REOPENED
+};
+
+class LineItemStatusService {
+  isValidTransition(fromStatus, toStatus) {
+    const validNextStatuses = VALID_TRANSITIONS[fromStatus];
+    if (!validNextStatuses) {
+      return false;
+    }
+    return validNextStatuses.includes(toStatus);
+  }
+
+  getValidTransitions(currentStatus) {
+    return VALID_TRANSITIONS[currentStatus] || [];
+  }
+
+  canReopen(currentStatus) {
+    return STATUSES_ALLOWING_REOPEN.includes(currentStatus);
+  }
+
+  canEditPacing(status, source = SOURCE_TYPES.INTERNAL) {
+    if (source === SOURCE_TYPES.EXTERNAL) {
+      return [LINE_ITEM_STATUSES.APPROVED, LINE_ITEM_STATUSES.LIVE].includes(status);
+    }
+    return PACING_EDITABLE_STATUSES.includes(status);
+  }
+
+  canEditSchedule(status, source = SOURCE_TYPES.INTERNAL) {
+    if (source === SOURCE_TYPES.EXTERNAL) {
+      return false;
+    }
+    return SCHEDULE_EDITABLE_STATUSES.includes(status);
+  }
+
+  canEditInventory(status, source = SOURCE_TYPES.INTERNAL) {
+    if (source === SOURCE_TYPES.EXTERNAL) {
+      return false;
+    }
+    return INVENTORY_EDITABLE_STATUSES.includes(status);
+  }
+
+  canEditCreatives(status, source = SOURCE_TYPES.INTERNAL) {
+    if (source === SOURCE_TYPES.EXTERNAL) {
+      return false;
+    }
+    return INVENTORY_EDITABLE_STATUSES.includes(status);
+  }
+
+  getEditableFields(status, source = SOURCE_TYPES.INTERNAL) {
+    const fields = {
+      pacing: this.canEditPacing(status, source),
+      schedule: this.canEditSchedule(status, source),
+      inventory: this.canEditInventory(status, source),
+      creatives: this.canEditCreatives(status, source),
+      targeting: this.canEditSchedule(status, source),
+      deliveryTargeting: this.canEditSchedule(status, source)
+    };
+
+    return fields;
+  }
+
+  validateTransition(lineItem, toStatus, context = {}) {
+    const { owner = TRANSITION_OWNERS.USER, source, campaignStatus } = context;
+    const currentStatus = lineItem.status;
+    const rawSource = source || lineItem.source;
+    const lineItemSource = (rawSource === SOURCE_TYPES.INTERNAL || rawSource === SOURCE_TYPES.EXTERNAL) 
+      ? rawSource 
+      : normalizeSource(rawSource);
+
+    const errors = [];
+
+    if (!this.isValidTransition(currentStatus, toStatus)) {
+      errors.push({
+        code: 'INVALID_TRANSITION',
+        message: `Cannot transition line item from ${currentStatus} to ${toStatus}`,
+        allowedTransitions: this.getValidTransitions(currentStatus)
+      });
+    }
+
+    if (toStatus === LINE_ITEM_STATUSES.REOPENED && !this.canReopen(currentStatus)) {
+      errors.push({
+        code: 'REOPEN_NOT_ALLOWED',
+        message: `Cannot reopen line item from status ${currentStatus}. Allowed from: ${STATUSES_ALLOWING_REOPEN.join(', ')}`
+      });
+    }
+
+    if (toStatus === LINE_ITEM_STATUSES.LIVE) {
+      if (owner !== TRANSITION_OWNERS.MQ_WORKER && owner !== TRANSITION_OWNERS.SYSTEM) {
+        errors.push({
+          code: 'LIVE_REQUIRES_DELIVERY',
+          message: 'LIVE status can only be set by MQ_WORKER when delivery is confirmed.',
+          allowedOwner: TRANSITION_OWNERS.MQ_WORKER
+        });
+      }
+    }
+
+    if (toStatus === LINE_ITEM_STATUSES.COMPLETED || toStatus === LINE_ITEM_STATUSES.EXPIRED) {
+      if (owner !== TRANSITION_OWNERS.SCHEDULER && owner !== TRANSITION_OWNERS.SYSTEM) {
+        errors.push({
+          code: 'SCHEDULER_ONLY',
+          message: `${toStatus} status can only be set by SCHEDULER based on end date or delivery events.`,
+          allowedOwner: TRANSITION_OWNERS.SCHEDULER
+        });
+      }
+    }
+
+    if (campaignStatus) {
+      const statusHierarchy = this.getStatusHierarchy();
+      const campaignRank = statusHierarchy[campaignStatus] || 0;
+      const lineItemRank = statusHierarchy[toStatus] || 0;
+      
+      if (lineItemRank > campaignRank && !['ARCHIVED', 'REJECTED'].includes(toStatus)) {
+        errors.push({
+          code: 'EXCEEDS_CAMPAIGN_STATUS',
+          message: `Line item status ${toStatus} cannot exceed campaign status ${campaignStatus}`,
+          campaignStatus
+        });
+      }
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors,
+      fromStatus: currentStatus,
+      toStatus,
+      source: lineItemSource
+    };
+  }
+
+  getStatusHierarchy() {
+    return {
+      [LINE_ITEM_STATUSES.DRAFT]: 0,
+      [LINE_ITEM_STATUSES.GENERATED]: 1,
+      [LINE_ITEM_STATUSES.REQUESTED]: 2,
+      [LINE_ITEM_STATUSES.PENDING]: 3,
+      [LINE_ITEM_STATUSES.APPROVED]: 4,
+      [LINE_ITEM_STATUSES.LIVE]: 5,
+      [LINE_ITEM_STATUSES.COMPLETED]: 6,
+      [LINE_ITEM_STATUSES.EXPIRED]: 6,
+      [LINE_ITEM_STATUSES.REJECTED]: -1,
+      [LINE_ITEM_STATUSES.ARCHIVED]: -2,
+      [LINE_ITEM_STATUSES.REOPENED]: 3
+    };
+  }
+
+  getCascadeStatus(campaignStatus) {
+    return CAMPAIGN_TO_LINE_ITEM_CASCADE[campaignStatus] || null;
+  }
+
+  shouldCascadeStatus(campaignStatus) {
+    return campaignStatus in CAMPAIGN_TO_LINE_ITEM_CASCADE;
+  }
+
+  getLineItemsToUpdate(lineItems, targetStatus) {
+    return lineItems.filter(li => {
+      if (li.status === targetStatus) return false;
+      if (li.status === LINE_ITEM_STATUSES.ARCHIVED) return false;
+      return this.isValidTransition(li.status, targetStatus);
+    });
+  }
+
+  getStatusDefinition(status) {
+    const definitions = {
+      [LINE_ITEM_STATUSES.DRAFT]: {
+        description: 'Line item is being created or edited',
+        isEditable: true,
+        canAddInventory: true,
+        canAddCreatives: true
+      },
+      [LINE_ITEM_STATUSES.GENERATED]: {
+        description: 'Line item has been generated from import or sync',
+        isEditable: true,
+        canAddInventory: true,
+        canAddCreatives: true
+      },
+      [LINE_ITEM_STATUSES.REQUESTED]: {
+        description: 'Line item has been submitted for review',
+        isEditable: true,
+        canAddInventory: true,
+        canAddCreatives: true
+      },
+      [LINE_ITEM_STATUSES.PENDING]: {
+        description: 'Line item is awaiting approval',
+        isEditable: false,
+        canAddInventory: false,
+        canAddCreatives: false
+      },
+      [LINE_ITEM_STATUSES.APPROVED]: {
+        description: 'Line item has been approved and is ready to go live',
+        isEditable: false,
+        canAddInventory: false,
+        canAddCreatives: false,
+        canEditPacing: true
+      },
+      [LINE_ITEM_STATUSES.LIVE]: {
+        description: 'Line item is actively serving ads',
+        isEditable: false,
+        canAddInventory: false,
+        canAddCreatives: false,
+        canEditPacing: true
+      },
+      [LINE_ITEM_STATUSES.COMPLETED]: {
+        description: 'Line item has completed its delivery',
+        isEditable: false,
+        canAddInventory: false,
+        canAddCreatives: false
+      },
+      [LINE_ITEM_STATUSES.EXPIRED]: {
+        description: 'Line item has passed its end date without completing',
+        isEditable: false,
+        canAddInventory: false,
+        canAddCreatives: false
+      },
+      [LINE_ITEM_STATUSES.REJECTED]: {
+        description: 'Line item was rejected during approval',
+        isEditable: false,
+        canAddInventory: false,
+        canAddCreatives: false
+      },
+      [LINE_ITEM_STATUSES.ARCHIVED]: {
+        description: 'Line item has been archived (soft deleted)',
+        isEditable: false,
+        canAddInventory: false,
+        canAddCreatives: false
+      },
+      [LINE_ITEM_STATUSES.REOPENED]: {
+        description: 'Line item has been reopened for editing',
+        isEditable: true,
+        canAddInventory: true,
+        canAddCreatives: true
+      }
+    };
+
+    return definitions[status] || null;
+  }
+
+  getTransitionOwnership() {
+    return {
+      [TRANSITION_OWNERS.USER]: [
+        LINE_ITEM_STATUSES.DRAFT,
+        LINE_ITEM_STATUSES.GENERATED,
+        LINE_ITEM_STATUSES.REQUESTED,
+        LINE_ITEM_STATUSES.PENDING,
+        LINE_ITEM_STATUSES.APPROVED,
+        LINE_ITEM_STATUSES.ARCHIVED,
+        LINE_ITEM_STATUSES.REOPENED
+      ],
+      [TRANSITION_OWNERS.MQ_WORKER]: [
+        LINE_ITEM_STATUSES.LIVE,
+        LINE_ITEM_STATUSES.APPROVED
+      ],
+      [TRANSITION_OWNERS.SCHEDULER]: [
+        LINE_ITEM_STATUSES.COMPLETED,
+        LINE_ITEM_STATUSES.EXPIRED
+      ],
+      [TRANSITION_OWNERS.ADMIN]: Object.values(LINE_ITEM_STATUSES)
+    };
+  }
+}
+
+export default new LineItemStatusService();
+export { LineItemStatusService, CAMPAIGN_TO_LINE_ITEM_CASCADE };