Change Orders & Claims Logic

class ChangeClaimService {

  /** Raise a new variation request from site */
  async createVariationRequest(projectId, description, estimatedImpact) {
    const vr = await VariationRequest.create({
      project_id: projectId,
      vr_number: await this.generateVRNumber(projectId),
      description,
      estimated_cost: estimatedImpact.cost,
      estimated_time_impact: estimatedImpact.days,
      status: 'draft'
    });
    await NotificationService.notify('PM', 'COMMERCIAL', {
      type: 'variation_request_raised', vr_id: vr.vr_id
    });
    return vr;
  }

  /** Evaluate a variation request for cost/time/scope impact */
  async evaluateChangeOrder(vrId) {
    const vr = await VariationRequest.findById(vrId);
    const costAnalysis = await BOQService.priceVariation(vr);
    const scheduleImpact = await ScheduleService.assessTimeImpact(vr);
    const scopeDefinition = await ScopeService.defineChangedScope(vr);
    await vr.update({
      estimated_cost: costAnalysis.totalCost,
      estimated_time_impact: scheduleImpact.criticalPathDays,
      status: 'evaluated'
    });
    return { costAnalysis, scheduleImpact, scopeDefinition };
  }

  /** Create formal change order from evaluated variation request */
  async createChangeOrder(vrId, approvedScope) {
    const vr = await VariationRequest.findById(vrId);
    if (vr.status !== 'evaluated') throw new Error('VR must be evaluated first');
    const co = await ChangeOrder.create({
      project_id: vr.project_id,
      contract_id: approvedScope.contractId,
      co_number: await this.generateCONumber(vr.project_id),
      co_type: approvedScope.type,
      cost_impact: approvedScope.costImpact,
      time_impact_days: approvedScope.timeImpactDays,
      status: 'pending_approval'
    });
    await ApprovalService.initiate('change_order', co.co_id, co.cost_impact);
    return co;
  }

  /** Record a delay event with contemporaneous evidence */
  async recordDelayEvent(projectId, eventDetails) {
    const event = await DelayEvent.create({
      project_id: projectId,
      event_type: eventDetails.type,
      cause_category: eventDetails.causeCategory,
      delay_days: eventDetails.delayDays,
      is_excusable: eventDetails.isExcusable,
      is_compensable: eventDetails.isCompensable,
      description: eventDetails.description,
      evidence_refs: eventDetails.evidenceDocIds
    });
    // Check if notice is required under the contract
    const contract = await ContractService.getNoticeRequirements(projectId);
    if (contract.requiresNotice) {
      await this.promptNoticeServing(projectId, event.event_id, contract.noticePeriodDays);
    }
    return event;
  }

  /** Serve contractual notice referencing specific clause */
  async serveNotice(projectId, noticeType, clauseRef) {
    const contract = await ContractService.getByProject(projectId);
    const responseDue = new Date();
    responseDue.setDate(responseDue.getDate() + contract.response_period_days);
    const notice = await Notice.create({
      project_id: projectId,
      notice_type: noticeType,
      clause_reference: clauseRef,
      response_due_date: responseDue,
      status: 'served'
    });
    await DocumentService.generateNoticeLetter(notice);
    return notice;
  }

  /** Prepare an EOT claim linking delay events with analysis method */
  async prepareEOTClaim(projectId, delayEventIds, analysisMethod) {
    const events = await DelayEvent.findByIds(delayEventIds);
    const totalDelay = events.reduce(function(sum, e) { return sum + e.delay_days; }, 0);
    const analysis = await DelayAnalysisService.run(analysisMethod, events);
    const claim = await EOTClaim.create({
      project_id: projectId,
      total_delay_days: totalDelay,
      requested_eot_days: analysis.entitledDays,
      cost_impact: analysis.prolongationCost,
      method_of_analysis: analysisMethod,
      status: 'draft'
    });
    return claim;
  }

  /** Submit a prepared claim for review */
  async submitClaim(claimId) {
    const claim = await EOTClaim.findById(claimId);
    const costs = await ClaimCost.findByClaimId(claimId);
    if (!costs.length) throw new Error('Claim must have cost breakdown before submission');
    await claim.update({ status: 'submitted', submitted_at: new Date() });
    await ApprovalService.initiate('eot_claim', claimId, claim.cost_impact);
    return claim;
  }

  /** Track negotiation rounds between contractor and client */
  async trackNegotiation(claimId, rounds) {
    for (const round of rounds) {
      await NegotiationRound.create({
        claim_id: claimId, round_number: round.number,
        contractor_position: round.contractorAmount,
        client_position: round.clientAmount,
        agreed_items: round.agreedItems, notes: round.notes
      });
    }
    const latestRound = rounds[rounds.length - 1];
    if (latestRound.settled) {
      await EOTClaim.update(claimId, { status: 'settled' });
      await FinanceService.updateRevisedBudget(claimId, latestRound.agreedAmount);
    }
  }

  /** Initiate arbitration when negotiation fails */
  async initiateArbitration(projectId, disputeDetails) {
    const arb = await Arbitration.create({
      project_id: projectId,
      claim_amount: disputeDetails.claimAmount,
      arbitrator: disputeDetails.proposedArbitrator,
      award_amount: null,
      status: 'initiated'
    });
    await NotificationService.notify('LEGAL_TEAM', {
      type: 'arbitration_initiated', arb_id: arb.arb_id
    });
    await DocumentService.packageClaimDocuments(projectId, arb.arb_id);
    return arb;
  }
}