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.
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:
- Navigate to FA → Close Management → Checklist Templates
- Create a template with
is_template = true
- Add tasks to the template with categories:
reconciliationreportingreviewapproval
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:
- Completing the wizard
- 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:
{
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),
}
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:
-- 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):
-- 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
- Verify the template exists:
SELECT * FROM pf_wizard_templates
WHERE module = 'fa' AND wizard_type = 'setup' AND is_active = true;
- Check the migration ran successfully
- Verify
is_active = true
Custom Steps Not Rendering
- Verify step registration in
registerFAWizardSteps.ts
- Check browser console for import errors
- 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.
- 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
