> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Financial Close Setup Wizard - Admin Guide

> This guide covers administration and configuration of the Financial Close Setup Wizard. The wizard uses the configurable wizard infrastructure.

## Overview

This guide covers administration and configuration of the Financial Close Setup Wizard (FA-UX-01). The wizard uses the PF-41 configurable wizard infrastructure.

## Architecture

### Components

| Component         | Location                                                                       | Purpose                                                       |
| ----------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------- |
| Wizard Page       | `src/cores/fa/wizards/financial-close-setup/FinancialCloseSetupWizardPage.tsx` | Main wizard orchestration                                     |
| Step Registration | `src/cores/fa/wizards/registerFAWizardSteps.ts`                                | Custom step component registration                            |
| Wizard Template   | `pf_wizard_templates` (database)                                               | Step configuration and form fields                            |
| Custom Steps      | `src/cores/fa/wizards/financial-close-setup/steps/`                            | ReviewTasks, AssignTasks, ConfigureDependencies, ConfirmStart |

### Database Template

The wizard template is seeded in `pf_wizard_templates` with:

* Module: `fa`
* Wizard Type: `setup`
* 6 steps (2 form-based, 4 custom components)

## Permission Requirements

| Permission           | Description              | Required For               |
| -------------------- | ------------------------ | -------------------------- |
| `fa.close.create`    | Create close periods     | Accessing the wizard       |
| `fa.close.view`      | View close periods       | Viewing created periods    |
| `fa.close.approve`   | Approve close periods    | Approving completed closes |
| `fa.checklists.view` | View checklist templates | Seeing template options    |

## Configuration

### Wizard Settings

The wizard uses these `fa_module_settings` fields (if configured):

| Setting                         | Default | Description                   |
| ------------------------------- | ------- | ----------------------------- |
| `close_default_period_type`     | `month` | Default period type selection |
| `close_auto_assign_enabled`     | `false` | Auto-assign based on role     |
| `close_require_all_assignments` | `true`  | Require all tasks assigned    |

### Checklist Templates

For the wizard to function, at least one checklist template must exist:

1. Navigate to **FA → Close Management → Checklist Templates**
2. Create a template with `is_template = true`
3. Add tasks to the template with categories:
   * `reconciliation`
   * `reporting`
   * `review`
   * `approval`

## Draft Persistence

The wizard uses PF-41 draft persistence:

* **Storage**: Local storage with `localforage`
* **Key**: `fa-setup-wizard-draft-{organizationId}`
* **Auto-save**: Every 30 seconds
* **Expiration**: 30 days

### Clearing Drafts

Users can clear their draft by:

1. Completing the wizard
2. Starting a new wizard session and not saving

Admins can view draft statistics in PF-41 admin (if deployed).

## Event Publishing

The wizard publishes the following event on completion:

```typescript theme={null}
{
  event_type: 'close_period_started',
  organization_id: string,
  user_id: string,
  close_period_id: string,
  tasks_count: number,
  assignments_count: number,
  timestamp: string (ISO 8601),
}
```

This event is broadcast on the `fa_events` Supabase channel for real-time notifications.

## Customization (Future)

When PF-41 wizard builder is deployed, organizations will be able to customize:

* Step order and visibility
* Required vs optional fields
* Custom validation rules
* Additional form fields
* Step skip conditions

## Monitoring

### Wizard Usage

Query wizard completion events:

```sql theme={null}
-- Recent wizard completions
SELECT 
  organization_id,
  user_id,
  created_at,
  custom_fields->>'tasks_count' as tasks_count
FROM pf_audit_logs
WHERE module = 'fa' 
  AND action = 'close_period_setup'
ORDER BY created_at DESC
LIMIT 100;
```

### Draft Statistics

Query draft statistics (requires PF-41 admin tables):

```sql theme={null}
-- Active drafts by organization
SELECT 
  organization_id,
  COUNT(*) as draft_count,
  MAX(updated_at) as last_activity
FROM pf_wizard_drafts
WHERE module = 'fa' AND wizard_type = 'setup'
GROUP BY organization_id;
```

## Troubleshooting

### Wizard Template Not Loading

1. Verify the template exists:

```sql theme={null}
SELECT * FROM pf_wizard_templates 
WHERE module = 'fa' AND wizard_type = 'setup' AND is_active = true;
```

2. Check the migration ran successfully
3. Verify `is_active = true`

### Custom Steps Not Rendering

1. Verify step registration in `registerFAWizardSteps.ts`
2. Check browser console for import errors
3. Verify component IDs match template configuration

### Event Publishing Failures

Event publishing is non-blocking. Failures are logged but don't prevent wizard completion.

Check Supabase logs for channel errors.

## Performance Considerations

* **Task Batch Size**: For templates with 50+ tasks, consider pagination in review step
* **User Fetching**: Uses `staleTime: 5min` to reduce API calls
* **Draft Auto-save**: 30-second interval prevents excessive storage writes

## Security

* All database operations include `organization_id` filter (defense-in-depth)
* RLS policies enforce tenant isolation
* User assignments validated against organization membership
* No PHI/PII exposed in wizard data

## Related Documentation

* [Financial Close Setup Wizard User Guide](/fa/financial-close-setup-wizard-user-guide)
* [Financial Close Management Guide](/fa/financial-close-management-guide)
* [PF-41 Configurable Module Wizards](https://github.com/Encore-OS/encoreos/blob/development/specs/pf/specs/PF-41-configurable-module-wizards.md)