284313f908
Some checks are pending
Bidi Control Character Guard / bidi-control-guard (push) Waiting to run
Circular Dependency Check / Check for new circular dependencies (push) Waiting to run
Citus Migration Smoke / Combined migrations on single-node Citus (push) Waiting to run
E2E Fresh Install Tests / fresh-install-e2e (push) Waiting to run
ext-v2 guardrails / Run ext-v2 guard and ESLint (push) Waiting to run
Integration Tests / Check for relevant changes (push) Waiting to run
Integration Tests / ${{ (github.event_name == 'schedule' || github.event.inputs.suite == 'full') && 'Full integration suite' || 'Tier-1 integration subset' }} (push) Blocked by required conditions
Mobile checks / Mobile lint + typecheck (push) Waiting to run
Mobile checks / Mobile unit tests (push) Waiting to run
Mobile checks / Mobile dependency audit (report) (push) Waiting to run
Mobile checks / Mobile reproducibility checks (push) Waiting to run
Secrets guard (env backups) / Ensure no tracked env backup files (push) Waiting to run
Temporal Readiness / fast-readiness (push) Waiting to run
Temporal Readiness / docker-parity (push) Waiting to run
TypeScript Type Check / Nx affected typecheck (push) Waiting to run
Unit Tests / Skipped-test budget (push) Waiting to run
Unit Tests / Nx affected unit tests (push) Waiting to run
Unit Tests / Server unit coverage (informational) (push) Waiting to run
Validate Tenant Management Schema / Check for relevant changes (push) Waiting to run
Validate Tenant Management Schema / Validate Tenant Management Schema (push) Blocked by required conditions
EE Workflows Build Guard / ee-workflows-build-guard (push) Waiting to run
Excluded: .git, node_modules, secrets/, compose.env, assemblyscript tgz Source: /opt/alga-psa on psa.joliet.tech
169 lines
6.3 KiB
Markdown
169 lines
6.3 KiB
Markdown
# 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
|
|
|
|
- [x] Created feature branch `feature/quickbooks-csv-export` from `release/0.15.0`
|
|
- [x] Set up development environment (port 3002)
|
|
- [x] 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`)
|
|
- [x] Created implementation plan
|
|
- [x] 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
|
|
|
|
- [x] Created `csvFieldNormalizer.ts` utility
|
|
- Column alias mappings for QuickBooks CSV variations
|
|
- Header normalization function
|
|
- Levenshtein distance for column suggestions
|
|
- Validation utilities for required columns
|
|
- [x] 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
|
|
- [x] 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
|
|
|
|
- [x] 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
|
|
- [x] Registered adapter in `registry.ts`
|
|
|
|
### 2024-12-16 - API Routes
|
|
|
|
- [x] Created CSV export API route (`POST /api/accounting/csv/export`)
|
|
- [x] Created tax import API route (`POST /api/accounting/csv/import/tax`)
|
|
- [x] Created template download route (`GET /api/accounting/csv/import/tax/template`)
|
|
- [x] Created import history route (`GET /api/accounting/csv/import/tax/history`)
|
|
- [x] Created rollback route (`POST /api/accounting/csv/import/tax/rollback/[importId]`)
|
|
|
|
### 2024-12-16 - UI Components
|
|
|
|
- [x] Created `CSVExportPanel` component
|
|
- Date range picker
|
|
- Invoice status filters
|
|
- Tax delegation mode toggle
|
|
- Download button with loading state
|
|
- [x] Created `CSVTaxImportPanel` component
|
|
- File upload (drag & drop)
|
|
- Required date range
|
|
- Inline help with QuickBooks export instructions
|
|
- Validate and Import buttons
|
|
- [x] Created `CSVImportPreview` component
|
|
- Stats summary (rows, valid, matched)
|
|
- Validation status badges
|
|
- Error and warning lists
|
|
- Import summary with tax totals
|
|
- [x] Created `CSVIntegrationSettings` wrapper component
|
|
- [x] 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
|