Re_Backend/docs/NEW_TABLES_SUMMARY.md

New Tables Created for Dealer Claim Management

Overview

This document lists all the new database tables created specifically for the Dealer Claim Management system.

Tables Created

1. dealer_claim_details

Migration: 20251210-create-dealer-claim-tables.ts

Purpose: Main table storing claim-specific information

Key Fields:

• claim_id (PK)
• request_id (FK to workflow_requests, unique)
• activity_name, activity_type
• dealer_code, dealer_name, dealer_email, dealer_phone, dealer_address
• activity_date, location
• period_start_date, period_end_date
• estimated_budget, closed_expenses
• io_number, io_available_balance, io_blocked_amount, io_remaining_balance (legacy - now in internal_orders)
• sap_document_number, dms_number
• e_invoice_number, e_invoice_date
• credit_note_number, credit_note_date, credit_note_amount

Created: December 10, 2025

---

2. dealer_proposal_details

Migration: 20251210-create-dealer-claim-tables.ts

Purpose: Stores dealer proposal submission data (Step 1 of workflow)

Key Fields:

• proposal_id (PK)
• request_id (FK to workflow_requests, unique)
• proposal_document_path, proposal_document_url
• cost_breakup (JSONB - legacy, now use dealer_proposal_cost_items)
• total_estimated_budget
• timeline_mode ('date' | 'days')
• expected_completion_date, expected_completion_days
• dealer_comments
• submitted_at

Created: December 10, 2025

---

3. dealer_completion_details

Migration: 20251210-create-dealer-claim-tables.ts

Purpose: Stores dealer completion documents and expenses (Step 5 of workflow)

Key Fields:

• completion_id (PK)
• request_id (FK to workflow_requests, unique)
• activity_completion_date
• number_of_participants
• closed_expenses (JSONB array)
• total_closed_expenses
• completion_documents (JSONB array)
• activity_photos (JSONB array)
• submitted_at

Created: December 10, 2025

---

4. dealer_proposal_cost_items

Migration: 20251210-create-proposal-cost-items-table.ts

Purpose: Separate table for cost breakdown items (replaces JSONB in dealer_proposal_details)

Key Fields:

• cost_item_id (PK)
• proposal_id (FK to dealer_proposal_details)
• request_id (FK to workflow_requests - denormalized for easier querying)
• item_description
• amount (DECIMAL 15,2)
• item_order (for maintaining order in cost breakdown)

Benefits:

• Better querying and filtering
• Easier to update individual cost items
• Better for analytics and reporting
• Maintains referential integrity

Created: December 10, 2025

---

5. internal_orders ⭐ NEW

Migration: 20251211-create-internal-orders-table.ts

Purpose: Dedicated table for IO (Internal Order) details with proper structure

Key Fields:

• io_id (PK)
• request_id (FK to workflow_requests, unique - one IO per request)
• io_number (STRING 50)
• io_remark (TEXT) ⭐ - Dedicated field for IO remarks (not in comments)
• io_available_balance (DECIMAL 15,2)
• io_blocked_amount (DECIMAL 15,2)
• io_remaining_balance (DECIMAL 15,2)
• organized_by (FK to users) ⭐ - Tracks who organized the IO
• organized_at (DATE) ⭐ - When IO was organized
• sap_document_number (STRING 100)
• status (ENUM: 'PENDING', 'BLOCKED', 'RELEASED', 'CANCELLED')

Why This Table:

• Previously IO details were stored in dealer_claim_details table
• IO remark was being parsed from comments
• Now dedicated table with proper fields and relationships
• Better data integrity and querying

Created: December 11, 2025

---

6. claim_budget_tracking ⭐ NEW

Migration: 20251211-create-claim-budget-tracking-table.ts

Purpose: Comprehensive budget tracking throughout the claim lifecycle

Key Fields:

• budget_id (PK)
• request_id (FK to workflow_requests, unique - one budget record per request)

Budget Values:

• initial_estimated_budget - From claim creation
• proposal_estimated_budget - From Step 1 (Dealer Proposal)
• approved_budget - From Step 2 (Requestor Evaluation)
• io_blocked_amount - From Step 3 (Department Lead - IO blocking)
• closed_expenses - From Step 5 (Dealer Completion)
• final_claim_amount - From Step 6 (Requestor Claim Approval)
• credit_note_amount - From Step 8 (Finance)

Tracking Fields:

• proposal_submitted_at
• approved_at, approved_by (FK to users)
• io_blocked_at
• closed_expenses_submitted_at
• final_claim_amount_approved_at, final_claim_amount_approved_by (FK to users)
• credit_note_issued_at

Status & Analysis:

• budget_status (ENUM: 'DRAFT', 'PROPOSED', 'APPROVED', 'BLOCKED', 'CLOSED', 'SETTLED')
• currency (STRING 3, default: 'INR')
• variance_amount - Difference between approved and closed expenses
• variance_percentage - Variance as percentage

Audit Fields:

• last_modified_by (FK to users)
• last_modified_at
• modification_reason (TEXT)

Why This Table:

• Previously budget data was scattered across multiple tables
• No single source of truth for budget lifecycle
• No audit trail for budget modifications
• Now comprehensive tracking with status and variance calculation

Created: December 11, 2025

---

Summary

Total New Tables: 6

1. ✅ dealer_claim_details - Main claim information
2. ✅ dealer_proposal_details - Step 1: Dealer proposal
3. ✅ dealer_completion_details - Step 5: Completion documents
4. ✅ dealer_proposal_cost_items - Cost breakdown items
5. ✅ internal_orders ⭐ - IO details with dedicated fields
6. ✅ claim_budget_tracking ⭐ - Comprehensive budget tracking

Most Recent Additions (December 11, 2025):

• internal_orders - Proper IO data structure with ioRemark field
• claim_budget_tracking - Complete budget lifecycle tracking

Migration Order

Run migrations in this order:

npm run migrate

The migrations will run in chronological order:

1. 20251210-create-dealer-claim-tables.ts (creates tables 1-3)
2. 20251210-create-proposal-cost-items-table.ts (creates table 4)
3. 20251211-create-internal-orders-table.ts (creates table 5)
4. 20251211-create-claim-budget-tracking-table.ts (creates table 6)

Relationships

workflow_requests (1)
  ├── dealer_claim_details (1:1)
  ├── dealer_proposal_details (1:1)
  │   └── dealer_proposal_cost_items (1:many)
  ├── dealer_completion_details (1:1)
  ├── internal_orders (1:1) ⭐ NEW
  └── claim_budget_tracking (1:1) ⭐ NEW

Notes

• All tables have request_id foreign key to workflow_requests
• Most tables have unique constraint on request_id (one record per request)
• dealer_proposal_cost_items can have multiple items per proposal
• All tables use UUID primary keys
• All tables have created_at and updated_at timestamps