Finance Period Close Logic

class PeriodCloseService {

  /** Run pre-close checks for all modules in the period */
  async runPreCloseChecks(periodId) {
    const period = await FiscalPeriod.findById(periodId);
    const modules = ['procurement', 'inventory', 'payroll', 'subcontractor', 'finance'];
    const results = [];
    for (const mod of modules) {
      const pending = await PendingItems.count({ period_id: periodId, module: mod });
      const unapproved = await Approvals.count({ period_id: periodId, module: mod, status: 'pending' });
      results.push({ module: mod, pending, unapproved, ready: pending === 0 && unapproved === 0 });
    }
    return { periodId, allReady: results.every(r => r.ready), modules: results };
  }

  /** Auto-generate accruals for uninvoiced GRNs and unbilled DMBs */
  async generateAccruals(periodId) {
    const period = await FiscalPeriod.findById(periodId);
    // Uninvoiced GRNs
    const grns = await GRN.findAll({
      entity_id: period.entity_id, date_between: [period.start_date, period.end_date],
      invoice_status: 'uninvoiced'
    });
    for (const grn of grns) {
      await ProvisionalEntry.create({
        entity_id: period.entity_id, entry_type: 'grn_accrual',
        amount: grn.total_amount, is_reversed: false
      });
    }
    // Unbilled DMBs
    const dmbs = await DMB.findAll({
      entity_id: period.entity_id, date_between: [period.start_date, period.end_date],
      bill_status: 'unbilled'
    });
    for (const dmb of dmbs) {
      await ProvisionalEntry.create({
        entity_id: period.entity_id, entry_type: 'dmb_accrual',
        amount: dmb.certified_amount, is_reversed: false
      });
    }
    // Post accrual journal entries
    await JournalService.postPeriodAccruals(periodId);
    return { grn_accruals: grns.length, dmb_accruals: dmbs.length };
  }

  /** Run depreciation for all fixed assets in the period */
  async runDepreciation(periodId) {
    const period = await FiscalPeriod.findById(periodId);
    const assets = await FixedAsset.findAll({ entity_id: period.entity_id, status: 'active' });
    for (const asset of assets) {
      const depnAmount = asset.method === 'SLM'
        ? asset.depreciable_value / asset.useful_life_months
        : asset.wdv * asset.rate / 12;
      await JournalEntry.create({
        period_id: periodId, je_type: 'depreciation',
        source_module: 'fixed_assets', status: 'posted'
      });
      await asset.update({ accumulated_depn: literal('accumulated_depn + ' + depnAmount) });
    }
    return { assets_processed: assets.length };
  }

  /** Reconcile inter-company transactions for the period */
  async reconcileIntercompany(periodId) {
    const period = await FiscalPeriod.findById(periodId);
    const txns = await IntercompanyTxn.findAll({ period_id: periodId, status: 'pending' });
    const pairs = groupByEntityPair(txns);
    for (const [pairKey, pairTxns] of Object.entries(pairs)) {
      const netAmount = pairTxns.reduce((sum, t) => sum + t.amount, 0);
      if (Math.abs(netAmount) > 0.01) throw new ICImbalanceError(pairKey, netAmount);
      await IntercompanyTxn.updateAll(pairTxns.map(t => t.id), { status: 'reconciled' });
    }
    return { pairs_reconciled: Object.keys(pairs).length };
  }

  /** Soft close — warn on new transactions but allow pending completions */
  async softClose(periodId) {
    const checks = await this.runPreCloseChecks(periodId);
    if (!checks.allReady) {
      const pending = checks.modules.filter(m => !m.ready);
      return { status: 'soft_closed_with_warnings', warnings: pending };
    }
    await FiscalPeriod.update(periodId, { status: 'soft_closed' });
    return { status: 'soft_closed', warnings: [] };
  }

  /** Hard close — lock period completely, no further entries allowed */
  async hardClose(periodId) {
    const modules = ['procurement', 'inventory', 'payroll', 'subcontractor', 'finance'];
    for (const mod of modules) {
      await PeriodLock.upsert({ period_id: periodId, module: mod, is_locked: true, locked_by: currentUser() });
    }
    await FiscalPeriod.update(periodId, { is_open: false, closed_by: currentUser() });
    await AuditTrail.log('period_hard_close', { period_id: periodId });
    await this.generateFinancials(periodId);
    return { status: 'hard_closed', period_id: periodId };
  }

  /** Generate financial statements after hard close */
  async generateFinancials(periodId) {
    const reportTypes = ['trial_balance', 'profit_and_loss', 'balance_sheet', 'cash_flow'];
    for (const type of reportTypes) {
      await FinancialReport.create({
        report_type: type, parameters: { period_id: periodId },
        last_generated: new Date()
      });
    }
    // Year-end: generate closing entries (P&L → Retained Earnings)
    const period = await FiscalPeriod.findById(periodId);
    if (period.period_name.endsWith('M12')) {
      await JournalService.postClosingEntries(periodId);
    }
    return { reports_generated: reportTypes.length };
  }

  /** Reopen a previously closed period (requires authorization) */
  async reopenPeriod(periodId, reason) {
    if (!currentUser().hasRole('FINANCE_CONTROLLER')) {
      throw new UnauthorizedError('Only Finance Controller can reopen periods');
    }
    await FiscalPeriod.update(periodId, { is_open: true, closed_by: null });
    await PeriodLock.updateAll({ period_id: periodId }, { is_locked: false });
    await AuditTrail.log('period_reopened', { period_id: periodId, reason, reopened_by: currentUser() });
    return { status: 'reopened', period_id: periodId, reason };
  }
}