Approval Workflows Logic

class WorkflowEngine {

  /** Initiate a new approval workflow for a submitted document */
  async initiateWorkflow(documentType, documentId, submittedBy) {
    const wfDef = await WorkflowDefinition.findOne({
      document_type: documentType, trigger_event: 'submitted'
    });
    const matrix = await this.findApprovalMatrix(wfDef.module, documentType, documentId);
    const instance = await WorkflowInstance.create({
      wf_id: wfDef.wf_id, document_type: documentType,
      document_id: documentId, current_node_id: wfDef.start_node_id,
      status: 'pending'
    });
    // Route to first approval level
    await this.routeToApprover(instance.instance_id, 1);
    return instance;
  }

  /** Find the matching approval matrix based on module, type, and conditions */
  async findApprovalMatrix(module, documentType, documentId) {
    const doc = await DocumentRegistry.findById(documentId);
    const matrices = await ApprovalMatrix.findAll({
      module, document_type: documentType
    });
    // Evaluate condition_field / condition_operator / condition_value
    for (const m of matrices) {
      if (this.evaluateCondition(doc[m.condition_field], m.condition_operator, m.condition_value)) {
        return m;
      }
    }
    throw new NoApprovalMatrixError(module, documentType);
  }

  /** Route the workflow instance to the approver at the given level */
  async routeToApprover(instanceId, levelNumber) {
    const instance = await WorkflowInstance.findById(instanceId);
    const level = await ApprovalLevel.findOne({
      matrix_id: instance.matrix_id, level_number: levelNumber
    });
    const approver = await this.resolveApprover(level);
    // Check delegation — substitute if delegator is on leave
    const delegate = await Delegation.findActive(approver.id);
    const actualApprover = delegate ? delegate.delegate_id : approver.id;
    const request = await ApprovalRequest.create({
      instance_id: instanceId, approver_id: actualApprover,
      document_summary: await this.buildSummary(instance),
      due_at: new Date(Date.now() + level.timeout_hours * 3600000),
      status: 'pending'
    });
    await NotificationService.send(actualApprover, 'approval_request', request);
    return request;
  }

  /** Process an approver's action on a pending request */
  async processAction(requestId, actorId, action, comments) {
    const request = await ApprovalRequest.findById(requestId);
    // Validate: cannot approve own submission
    const instance = await WorkflowInstance.findById(request.instance_id);
    if (instance.submitted_by === actorId) throw new SelfApprovalError();
    const slaMet = new Date() <= request.due_at;
    await WorkflowAction.create({
      instance_id: request.instance_id, node_id: instance.current_node_id,
      actor_id: actorId, action, comments, sla_met: slaMet
    });
    if (action === 'approve') {
      const nextNode = await WorkflowNode.findById(instance.current_node_id);
      if (nextNode.on_approve_node_id) {
        await instance.update({ current_node_id: nextNode.on_approve_node_id });
        await this.routeToApprover(instance.instance_id, instance.current_level + 1);
      } else {
        await instance.update({ status: 'approved' });
        await DocumentService.updateStatus(instance.document_type, instance.document_id, 'approved');
      }
    } else if (action === 'reject') {
      await instance.update({ status: 'rejected' });
      await DocumentService.updateStatus(instance.document_type, instance.document_id, 'rejected');
    } else if (action === 'return') {
      await instance.update({ status: 'returned' });
      await DocumentService.updateStatus(instance.document_type, instance.document_id, 'draft');
    }
    await request.update({ status: action });
  }

  /** Scheduled job: check for overdue requests and escalate */
  async checkEscalation() {
    const overdue = await ApprovalRequest.findAll({
      status: 'pending', due_at: { lt: new Date() }
    });
    for (const req of overdue) {
      const rule = await EscalationRule.findByWfId(req.wf_id);
      if (req.escalation_count >= rule.max_escalations) continue;
      const escalateTo = await this.resolveEscalationTarget(rule);
      await NotificationService.send(escalateTo, 'escalation', req);
      await req.update({ escalation_count: req.escalation_count + 1 });
    }
  }

  /** Delegate a pending approval to another user */
  async delegateApproval(requestId, delegateToUserId) {
    const req = await ApprovalRequest.findById(requestId);
    await req.update({ approver_id: delegateToUserId, status: 'pending' });
    await NotificationService.send(delegateToUserId, 'delegation', req);
  }
}