Assist_Design/docs/development/refactoring/code-quality-checklist.md

Code Quality Improvement Checklist

Use this checklist to track progress on the refactoring plan.

---

Phase 1: Quick Wins ✅ COMPLETE

1.1 Add Mapping Helper Methods ✅

• Add getWhmcsClientIdOrThrow() to MappingsService
• Add getMappingOrThrow() to MappingsService
• Add unit tests for new methods
• Update index.ts exports if needed (N/A - no index.ts)

1.2 Refactor WHMCS Mapping Lookups ✅

• apps/bff/src/modules/billing/billing.controller.ts (4 occurrences)
• apps/bff/src/modules/billing/services/invoice-retrieval.service.ts (1 occurrence)
  • Remove private getUserMapping() method
• apps/bff/src/modules/users/infra/user-profile.service.ts (2 occurrences)
• apps/bff/src/modules/subscriptions/subscriptions.service.ts (3 occurrences)
• apps/bff/src/modules/subscriptions/sim-management/services/esim-management.service.ts (1 occurrence)
• apps/bff/src/modules/subscriptions/sim-management/services/sim-cancellation.service.ts (2 occurrences)
• apps/bff/src/modules/subscriptions/sim-management/services/sim-topup.service.ts (1 occurrence)
• apps/bff/src/modules/subscriptions/sim-order-activation.service.ts (1 occurrence)
• apps/bff/src/modules/auth/application/auth.facade.ts (1 occurrence)
• Run tests after each file change

1.3 Rename getErrorMessage Functions ✅

Step 1: Add new function names as aliases

• In apps/bff/src/core/utils/error.util.ts: Add extractErrorMessage as alias
• In packages/domain/common/errors.ts: Add getMessageForErrorCode as alias
• Update exports in both locations

Step 2: Update all imports (gradual migration)

• Old names kept as deprecated aliases for backwards compatibility
• Update imports incrementally (can be done over time)

Step 3: Remove old function names

• Remove getErrorMessage from error.util.ts (after migration complete)
• Remove getErrorMessage from errors.ts (after migration complete)
• Run full test suite

1.4 Remove Unused Status Wrapper Methods ✅

Audit usage:

• invoice-retrieval.service.ts → getUnpaidInvoices() - UNUSED, REMOVED
• invoice-retrieval.service.ts → getOverdueInvoices() - UNUSED, REMOVED
• invoice-retrieval.service.ts → getPaidInvoices() - UNUSED, REMOVED
• invoice-retrieval.service.ts → getCancelledInvoices() - UNUSED, REMOVED
• invoice-retrieval.service.ts → getCollectionsInvoices() - UNUSED, REMOVED
• invoice-retrieval.service.ts → hasInvoices() - UNUSED, REMOVED
• invoice-retrieval.service.ts → getInvoiceCountByStatus() - UNUSED, REMOVED
• subscriptions.service.ts → getSuspendedSubscriptions() - UNUSED, REMOVED
• subscriptions.service.ts → getCancelledSubscriptions() - UNUSED, REMOVED
• subscriptions.service.ts → getPendingSubscriptions() - UNUSED, REMOVED

---

Phase 2: Medium-Term Improvements ✅ COMPLETE

2.1 Create Error Handling Utility ✅

• Create apps/bff/src/core/utils/error-handler.util.ts
• Add withErrorHandling() function
• Add withErrorSuppression() function
• Add withErrorLogging() function
• Add unit tests
• Export from apps/bff/src/core/utils/index.ts (optional)

2.2 Refactor Services to Use Error Handling Utility (Partial) ✅

High Priority:

• invoice-retrieval.service.ts - Refactored to use withErrorHandling

Medium Priority (not yet done):

• subscriptions.service.ts (12 blocks)
• user-profile.service.ts (6 blocks)
• signup-workflow.service.ts (8 blocks)
• password-workflow.service.ts (4 blocks)
• whmcs-link-workflow.service.ts (5 blocks)

2.3 Consolidate WHMCS Connection Methods ✅

• Update WhmcsRequestOptions interface with highPriority option
• Refactor makeRequest() to handle both cases
• Deprecate makeHighPriorityRequest() (don't remove yet)
• Update callers of makeHighPriorityRequest() (not required, deprecated method delegates)
• Run integration tests

---

Phase 3: Long-Term Improvements (Partial)

3.1 Split SignupWorkflowService ✅

Create new files:

• signup.types.ts
• signup-validation.service.ts
• signup-account-resolver.service.ts
• index.ts (exports)

Migration:

• Move validation logic to signup-validation.service.ts
• Move account resolution to signup-account-resolver.service.ts
• Refactor signup-workflow.service.ts to use new services
• Update auth.module.ts with new providers
• Update tests
• Keep signup-workflow.service.ts as orchestrator (delegating to new services)

3.2 Split UserProfileService (DEFERRED)

Create new files:

• dashboard.service.ts
• whmcs-custom-fields.util.ts

Migration:

• Extract getUserSummary() to DashboardService
• Extract custom field logic to utility
• Update module providers
• Update tests

3.3 Evaluate WhmcsService Facade (DEFERRED)

Analysis:

• List all direct usages of WhmcsService
• Determine if cross-cutting concerns are needed
• Make go/no-go decision

3.4 Dead Code Audit (DEFERRED)

Tools:

• Run ts-prune to find unused exports
• Review test coverage reports

3.5 Create LoggableService Base Class (DEFERRED - Optional)

• Team decision on using inheritance
• If yes: Create base class
• If yes: Migrate services incrementally

---

Final Verification

• All unit tests passing
• All integration tests passing
• Manual smoke testing complete
• No new linter errors (verified with TypeScript compiler)
• Documentation updated
• PR reviewed and approved

---

Notes

Date	Note
Dec 2025	Phase 1 and Phase 2 completed. Phase 3.1 (SignupWorkflowService split) completed. Remaining Phase 3 items deferred for future sprints.