Re_Backend/docs/DEALER_CLAIM_FRESH_START.md

Dealer Claim Management - Fresh Start Guide

Overview

This guide helps you start fresh with the dealer claim management system by cleaning up all existing data and ensuring the database structure is ready for new requests.

Prerequisites

1. Database Migrations: Ensure all migrations are up to date, including the new tables:

   • internal_orders (for IO details)
   • claim_budget_tracking (for comprehensive budget tracking)

2. Backup (Optional but Recommended):

   • If you have important data, backup your database before running cleanup

Fresh Start Steps

Step 1: Run Database Migrations

Ensure all new tables are created:

cd Re_Backend
npm run migrate

This will create:

• ✅ internal_orders table (for IO details with ioRemark)
• ✅ claim_budget_tracking table (for comprehensive budget tracking)
• ✅ All other dealer claim related tables

Step 2: Clean Up All Existing Dealer Claims

Run the cleanup script to remove all existing CLAIM_MANAGEMENT requests:

npm run cleanup:dealer-claims

What this script does:

• Finds all workflow requests with workflow_type = 'CLAIM_MANAGEMENT'
• Deletes all related data from:
  • claim_budget_tracking
  • internal_orders
  • dealer_proposal_cost_items
  • dealer_completion_details
  • dealer_proposal_details
  • dealer_claim_details
  • activities
  • work_notes
  • documents
  • participants
  • approval_levels
  • subscriptions
  • notifications
  • request_summaries
  • shared_summaries
  • conclusion_remarks
  • tat_alerts
  • workflow_requests (finally)

Note: This script uses a database transaction, so if any step fails, all changes will be rolled back.

Step 3: Verify Cleanup

After running the cleanup script, verify that no CLAIM_MANAGEMENT requests remain:

SELECT COUNT(*) FROM workflow_requests WHERE workflow_type = 'CLAIM_MANAGEMENT';
-- Should return 0

Step 4: Seed Dealers (If Needed)

If you need to seed dealer users:

npm run seed:dealers

Database Structure Summary

New Tables Created

1. internal_orders - Dedicated table for IO (Internal Order) details

   • io_id (PK)
   • request_id (FK, unique)
   • io_number
   • io_remark ✅ (dedicated field, not in comments)
   • io_available_balance
   • io_blocked_amount
   • io_remaining_balance
   • organized_by (FK to users)
   • organized_at
   • status (PENDING, BLOCKED, RELEASED, CANCELLED)

2. claim_budget_tracking - Comprehensive budget tracking

   • budget_id (PK)
   • request_id (FK, unique)
   • initial_estimated_budget
   • proposal_estimated_budget
   • approved_budget
   • io_blocked_amount
   • closed_expenses
   • final_claim_amount
   • credit_note_amount
   • budget_status (DRAFT, PROPOSED, APPROVED, BLOCKED, CLOSED, SETTLED)
   • variance_amount & variance_percentage
   • Audit fields (last_modified_by, last_modified_at, modification_reason)

Existing Tables (Enhanced)

• dealer_claim_details - Main claim information
• dealer_proposal_details - Step 1: Dealer proposal
• dealer_proposal_cost_items - Cost breakdown items
• dealer_completion_details - Step 5: Completion documents

What's New

1. IO Details in Separate Table

• ✅ IO remark is now stored in internal_orders.io_remark (not parsed from comments)
• ✅ Tracks who organized the IO (organized_by, organized_at)
• ✅ Better data integrity and querying

2. Comprehensive Budget Tracking

• ✅ All budget-related values in one place
• ✅ Tracks budget lifecycle (DRAFT → PROPOSED → APPROVED → BLOCKED → CLOSED → SETTLED)
• ✅ Calculates variance automatically
• ✅ Audit trail for budget modifications

3. Proper Data Structure

• ✅ Estimated budget: claimDetails.estimatedBudget or proposalDetails.totalEstimatedBudget
• ✅ Claim amount: completionDetails.totalClosedExpenses or budgetTracking.finalClaimAmount
• ✅ IO details: internalOrder table (separate, dedicated)
• ✅ E-Invoice: claimDetails.eInvoiceNumber, claimDetails.eInvoiceDate
• ✅ Credit Note: claimDetails.creditNoteNumber, claimDetails.creditNoteAmount

Next Steps After Cleanup

1. Create New Claim Requests: Use the API or frontend to create fresh dealer claim requests
2. Test Workflow: Go through the 8-step workflow to ensure everything works correctly
3. Verify Data Storage: Check that IO details and budget tracking are properly stored

Troubleshooting

If Cleanup Fails

1. Check database connection
2. Verify foreign key constraints are not blocking deletion
3. Check logs for specific error messages
4. The script uses transactions, so partial deletions won't occur

If Tables Don't Exist

Run migrations again:

npm run migrate

If You Need to Restore Data

If you backed up before cleanup, restore from your backup. The cleanup script does not create backups automatically.

API Endpoints Ready

After cleanup, you can use these endpoints:

• POST /api/v1/dealer-claims - Create new claim request
• POST /api/v1/dealer-claims/:requestId/proposal - Submit proposal (Step 1)
• PUT /api/v1/dealer-claims/:requestId/io - Update IO details (Step 3)
• POST /api/v1/dealer-claims/:requestId/completion - Submit completion (Step 5)
• PUT /api/v1/dealer-claims/:requestId/e-invoice - Update e-invoice (Step 7)
• PUT /api/v1/dealer-claims/:requestId/credit-note - Update credit note (Step 8)

Summary

✅ Cleanup Script: npm run cleanup:dealer-claims
✅ Migrations: npm run migrate
✅ Fresh Start: Database is ready for new dealer claim requests
✅ Proper Structure: IO details and budget tracking in dedicated tables