PSA/docs/archive/controller-migration-analysis.md

Controller Migration Analysis

Summary

This analysis identifies all controllers that extend from BaseController (not ApiBaseController) and checks if they have V2 replacements.

V2 Controllers (Already Migrated)

These controllers have been migrated to V2 and extend ApiBaseControllerV2:

1. ApiCompanyControllerV2 - Companies management
2. ApiContactControllerV2 - Contacts management ✅ (routes using V2)
3. ApiPermissionControllerV2 - Permissions management
4. ApiProjectControllerV2 - Projects management ✅ (routes using V2)
5. ApiRoleControllerV2 - Roles management
6. ApiTeamControllerV2 - Teams management ✅ (routes using V2)
7. ApiTicketControllerV2 - Tickets management
8. ApiTimeEntryControllerV2 - Time entries management
9. ApiUserControllerV2 - Users management ✅ (routes using V2)

Non-V2 Controllers (Need Migration)

These controllers still extend BaseController and do NOT have V2 versions:

1. AssetController - Asset management

   • Routes: /api/v1/assets/*
   • Status: Still using old controller

2. AutomationController - Automation rules and executions

   • Routes: /api/v1/automation/*
   • Status: Still using old controller

3. ContractLineController - Contract Lines management

   • Routes: /api/v1/contract-lines/*
   • Status: Still using old controller

4. CategoryController - Category management (tickets/services)

   • Routes: /api/v1/categories/*
   • Status: Still using old controller

5. FinancialController - Financial operations (credits, transactions, reports)

   • Routes: /api/v1/financial/*
   • Status: Still using old controller

6. InvoiceController - Invoice management

   • Routes: /api/v1/invoices/*
   • Status: Still using old controller

7. MetadataController - API metadata and documentation

   • Routes: /api/v1/meta/*
   • Status: Still using old controller

8. PermissionRoleController - Permission role management

   • Routes: /api/v1/roles/*, /api/v1/permissions/*
   • Status: Still using old controller

9. QuickBooksController - QuickBooks integration

   • Routes: /api/v1/integrations/quickbooks/*
   • Status: Still using old controller

10. TagController - Tag management

    • Routes: /api/v1/tags/*
    • Status: Still using old controller

11. TimeSheetController - Time sheet management

    • Routes: /api/v1/time-sheets/*
    • Status: Still using old controller

12. WebhookController - Webhook management

    • Routes: /api/v1/webhooks/*
    • Status: Still using old controller

13. WorkflowController - Workflow management

    • Routes: /api/v1/workflows/*
    • Status: Still using old controller

Migration Priority

Based on usage patterns and complexity:

High Priority

1. TagController - Widely used across the system
2. AssetController - Core business entity
3. InvoiceController - Critical for billing
4. TimeSheetController - Related to time tracking

Medium Priority

5. CategoryController - Used for organization
6. FinancialController - Complex but isolated
7. WebhookController - Integration point
8. WorkflowController - Advanced feature

Low Priority

9. AutomationController - Advanced feature
10. ContractLineController - Configuration-focused
11. MetadataController - API documentation
12. PermissionRoleController - Admin feature
13. QuickBooksController - External integration

Key Differences: BaseController vs ApiBaseControllerV2

• BaseController: Uses basic CRUD patterns with simple middleware composition
• ApiBaseControllerV2: Provides enhanced features including:
  • Built-in pagination with metadata
  • Standardized error handling
  • Request/response validation
  • Automatic HATEOAS link generation
  • Better TypeScript support
  • Consistent API response format

Recommendation

Start migrating controllers in the priority order listed above. Each migration should:

1. Create a new V2 controller extending ApiBaseControllerV2
2. Update the corresponding service if needed
3. Update all routes to use the new V2 controller
4. Add proper TypeScript types and validation schemas
5. Update tests to match the new API format