PSA/ee/docs/plans/progress-quickbooks-csv-export.md

QuickBooks CSV Export/Import - Progress Tracker

Overview

This document tracks the implementation progress of the QuickBooks CSV Export/Import feature, which provides an alternative to OAuth integration for QuickBooks.

Branch: feature/quickbooks-csv-export Started: 2024-12-16 Status: Core Implementation Complete

---

Progress Log

2024-12-16 - Initial Setup

• Created feature branch feature/quickbooks-csv-export from release/0.15.0
• Set up development environment (port 3002)
• Completed comprehensive exploration of existing codebase:
  • QuickBooks integration (quickBooksOnlineAdapter.ts, qboClientService.ts)
  • External tax calculation system (externalTaxImportService.ts)
  • Accounting export batch system (accountingExportService.ts)
  • Mapping resolver (accountingMappingResolver.ts)
• Created implementation plan
• Created feature tracking files:
  • features-quickbooks-csv-export.json - Task list with completion status
  • progress-quickbooks-csv-export.md - This progress file

2024-12-16 - Core Infrastructure

• Created csvFieldNormalizer.ts utility
  • Column alias mappings for QuickBooks CSV variations
  • Header normalization function
  • Levenshtein distance for column suggestions
  • Validation utilities for required columns
• Created csvTaxImportValidator.ts service
  • Structure validation (required columns with alias support)
  • Row-level parsing (dates, amounts, tax rates)
  • Database cross-referencing (invoice existence, tax_source check)
  • Duplicate detection and tax aggregation
• Created csvTaxImportService.ts service
  • Main importTaxFromCSV method with validation and dry-run support
  • Proportional tax distribution using floor + remainder algorithm
  • Transaction-based updates for atomicity
  • Import history tracking in external_tax_imports table
  • Rollback capability to revert imports

2024-12-16 - Export Adapter

• Created QuickBooksCSVAdapter
  • Implements AccountingExportAdapter interface
  • File-based delivery mode (generates downloadable CSV)
  • Resolves service, tax code, and payment term mappings
  • Supports tax delegation mode for external tax calculation
• Registered adapter in registry.ts

2024-12-16 - API Routes

• Created CSV export API route (POST /api/accounting/csv/export)
• Created tax import API route (POST /api/accounting/csv/import/tax)
• Created template download route (GET /api/accounting/csv/import/tax/template)
• Created import history route (GET /api/accounting/csv/import/tax/history)
• Created rollback route (POST /api/accounting/csv/import/tax/rollback/[importId])

2024-12-16 - UI Components

• Created CSVExportPanel component
  • Date range picker
  • Invoice status filters
  • Tax delegation mode toggle
  • Download button with loading state
• Created CSVTaxImportPanel component
  • File upload (drag & drop)
  • Required date range
  • Inline help with QuickBooks export instructions
  • Validate and Import buttons
• Created CSVImportPreview component
  • Stats summary (rows, valid, matched)
  • Validation status badges
  • Error and warning lists
  • Import summary with tax totals
• Created CSVIntegrationSettings wrapper component
• Integrated into IntegrationsSettingsPage under Accounting category

---

Phase Status

Phase	Status	Progress
1. Core Infrastructure	Mostly Complete	3/5 tasks
2. Export Adapter	Mostly Complete	3/4 tasks
3. Import API	Mostly Complete	2/4 tasks
4. UI Components	Complete	4/4 tasks
5. Testing & Polish	Not Started	0/3 tasks

Overall Progress: 12/20 tasks (60%)

---

Remaining Work

Phase 1: Core Infrastructure

• Write unit tests for CSV field normalizer
• Write unit tests for CSV tax import validator

Phase 2: Export Adapter

• Write unit tests for QuickBooksCSVAdapter

Phase 3: Import API

• Write integration tests for CSV export flow
• Write integration tests for CSV tax import flow

Phase 5: Testing & Polish

• Write Playwright E2E tests for CSV export UI
• Write Playwright E2E tests for CSV import UI
• Add optional database index for CSV import queries

---

Commits

Date	Commit	Description
2024-12-16	18b82a1b2	feat(csv-import): add CSV field normalizer utility
2024-12-16	fc0652c8a	feat(csv-import): add CSV tax import validator service
2024-12-16	c6fb100a3	feat(csv-import): add CSV tax import service
2024-12-16	26f55cf6e	feat(csv-export): add QuickBooks CSV export adapter
2024-12-16	f586bcfa6	feat(csv): add CSV accounting API routes
2024-12-16	7e008f1ff	feat(csv-ui): add CSV export and import UI components
2024-12-16	950ab8671	feat(csv-ui): integrate CSV panels into integrations settings

---

Reference Files

Key files created during implementation:

Core Services:

• server/src/lib/utils/csvFieldNormalizer.ts - Column name normalization
• server/src/lib/services/csvTaxImportValidator.ts - Validation rules
• server/src/lib/services/csvTaxImportService.ts - Import logic

Adapter:

• server/src/lib/adapters/accounting/quickBooksCSVAdapter.ts - CSV export adapter
• server/src/lib/adapters/accounting/registry.ts - Adapter registration

API Routes:

• server/src/app/api/accounting/csv/export/route.ts
• server/src/app/api/accounting/csv/import/tax/route.ts
• server/src/app/api/accounting/csv/import/tax/template/route.ts
• server/src/app/api/accounting/csv/import/tax/history/route.ts
• server/src/app/api/accounting/csv/import/tax/rollback/[importId]/route.ts

UI Components:

• server/src/components/integrations/csv/CSVExportPanel.tsx
• server/src/components/integrations/csv/CSVTaxImportPanel.tsx
• server/src/components/integrations/csv/CSVImportPreview.tsx
• server/src/components/settings/integrations/CSVIntegrationSettings.tsx

---

Notes

• The CSV integration is accessible from Settings > Integrations > Accounting tab
• Service mappings must be configured in the QuickBooks Online section before exporting
• Unmapped services will cause the entire export to fail (consistent with existing adapters)
• Inline help is provided in the tax import panel with QuickBooks export instructions