Financial Close Management - Admin Guide

import { useHasPermission, PermissionGate } from '@/platform/permissions';

// Hook usage
const canApprove = useHasPermission('fa.close.approve');

// Component usage
<PermissionGate permission="fa.close.approve">
  <Button onClick={handleApprove}>Approve Period</Button>
</PermissionGate>

1. Pre-Close Tasks
   1.1 Review open transactions (Manual, Medium)
   1.2 Process pending journal entries (Manual, High)
   1.3 Complete bank reconciliations (Manual, High)
       └─ Depends on: 1.2

2. Accruals & Adjustments
   2.1 Record accrued expenses (Manual, High)
   2.2 Post prepaid amortization (Manual, Medium)
   2.3 Record depreciation (Automated, Medium)
   2.4 Review accrual entries (Review, High)
       └─ Depends on: 2.1, 2.2, 2.3

3. Reconciliation & Review
   3.1 Reconcile subledgers to GL (Manual, High)
   3.2 Verify intercompany balances (Manual, Medium)
   3.3 Review account reconciliations (Review, High)
       └─ Depends on: 3.1, 3.2

4. Reporting & Finalization
   4.1 Generate trial balance (Manual, Medium)
   4.2 Review financial statements (Review, High)
   4.3 Prepare variance analysis (Manual, Medium)
   4.4 Manager approval (Approval, Critical)
       └─ Depends on: 4.1, 4.2, 4.3

5. Quarter-End Specific
   5.1 Review quarterly accruals (Review, High)
   5.2 Prepare quarterly reports (Manual, High)
   5.3 Review budget vs actual (Review, Medium)
   5.4 Update cash flow forecast (Manual, Medium)
   5.5 Quarter-end approval (Approval, Critical)

6. Year-End Specific
   6.1 Physical inventory count (Manual, Critical)
   6.2 Review fixed asset depreciation (Review, High)
   6.3 Prepare audit schedules (Manual, Critical)
   6.4 Tax provision calculation (Manual, Critical)
   6.5 Year-end adjustments review (Review, Critical)
   6.6 Final audit preparation (Manual, High)
   6.7 CFO year-end approval (Approval, Critical)

// Example: Check if period is closed before final report
const { data: closeStatus } = await supabase
  .from('fa_close_periods')
  .select('status')
  .eq('fiscal_period_id', periodId)
  .single();

if (closeStatus?.status !== 'completed') {
  throw new Error('Period must be closed before generating final reports');
}

{
  event_type: 'close_period_started';
  close_period_id: uuid;
  period_name: string;
  period_type: 'month' | 'quarter' | 'year';
  started_by: uuid;
  organization_id: uuid;
  timestamp: timestamptz;
}

{
  event_type: 'close_period_completed';
  close_period_id: uuid;
  period_name: string;
  fiscal_period_id: uuid | null;
  completed_by: uuid;
  organization_id: uuid;
  timestamp: timestamptz;
}

{
  event_type: 'close_period_approved';
  close_period_id: uuid;
  period_name: string;
  approved_by: uuid;
  organization_id: uuid;
  timestamp: timestamptz;
}

{
  event_type: 'close_task_assigned';
  task_id: uuid;
  task_name: string;
  close_period_id: uuid;
  assigned_to: uuid;
  assigned_by: uuid;
  organization_id: uuid;
  timestamp: timestamptz;
}

{
  event_type: 'close_task_completed';
  task_id: uuid;
  task_name: string;
  close_period_id: uuid;
  completed_by: uuid;
  organization_id: uuid;
  timestamp: timestamptz;
}

// Subscribe to close events
const channel = supabase.channel('fa_events');

channel.on('broadcast', { event: 'close_period_approved' }, (payload) => {
  // TODO: Replace with your app's structured logging
  // logger.info('Period approved:', payload);
  // Update UI or trigger downstream actions
});

channel.subscribe();

{
  approved: boolean;
  comments?: string;
}

{
  close_period_id: uuid;
  status: 'approved' | 'rejected';
  approved_at: timestamp;
  approved_by: uuid;
}

{
  close_period_id: uuid;
  period_name: string;
  status: CloseStatus;
  task_summary: {
    total: number;
    completed: number;
    skipped: number;
    in_progress: number;
    blocked: number;
    not_started: number;
  };
  completion_percentage: number;
  // ... additional fields
}

-- Example: fa_close_periods policy
CREATE POLICY "fa_close_periods_org_read" ON fa_close_periods
FOR SELECT USING (
  fa_has_org_access(organization_id, auth.uid())
);

CREATE POLICY "fa_close_periods_org_write" ON fa_close_periods
FOR ALL USING (
  fa_has_org_access(organization_id, auth.uid())
)
WITH CHECK (
  fa_has_org_access(organization_id, auth.uid())
);

// Correct pattern
await supabase
  .from('fa_close_periods')
  .update({ status: 'in_progress' })
  .eq('id', periodId)
  .eq('organization_id', currentOrganization.id);  // Always include

-- Trigger prevents updates to locked periods
CREATE TRIGGER fa_close_periods_lock_check
BEFORE UPDATE ON fa_close_periods
FOR EACH ROW
WHEN (OLD.status IN ('completed', 'locked'))
EXECUTE FUNCTION fa_prevent_locked_period_update();

-- Trigger validates task dependencies
CREATE TRIGGER fa_validate_task_dependency
BEFORE INSERT OR UPDATE ON fa_close_tasks
FOR EACH ROW
EXECUTE FUNCTION fa_validate_no_circular_dependency();

SELECT 
  cp.id,
  cp.period_name,
  cp.status,
  cp.organization_id,
  COUNT(ct.id) as total_tasks,
  COUNT(CASE WHEN ct.status = 'completed' THEN 1 END) as completed_tasks
FROM fa_close_periods cp
LEFT JOIN fa_close_checklists cc ON cc.close_period_id = cp.id
LEFT JOIN fa_close_tasks ct ON ct.checklist_id = cc.id
WHERE cp.id = '<period_id>'
GROUP BY cp.id;

SELECT 
  ct.id,
  ct.task_name,
  ct.status,
  ct.assigned_to,
  ct.depends_on_task_id
FROM fa_close_tasks ct
JOIN fa_close_checklists cc ON ct.checklist_id = cc.id
WHERE cc.close_period_id = '<period_id>'
  AND ct.status NOT IN ('completed', 'skipped')
ORDER BY ct.display_order;

-- View recent close events (if logging enabled)
SELECT * FROM pg_stat_activity 
WHERE query LIKE '%pg_notify%fa_events%'
ORDER BY query_start DESC
LIMIT 10;