311 lines
9.1 KiB
Markdown
311 lines
9.1 KiB
Markdown
# Database Schema Documentation
|
|
|
|
## 1. Overview
|
|
This document provides a detailed reference for the backend database schema of the Royal Enfield Workflow Management System.
|
|
|
|
**Database System:** PostgreSQL 16.x
|
|
**Schema Conventions:**
|
|
* **Primary Keys:** UUID (v4) for all tables.
|
|
* **Naming:** Snake_case for tables and columns.
|
|
* **Audit Columns:** Most tables include `created_at`, `updated_at`, `created_by`, `updated_by`.
|
|
* **Soft Deletes:** `is_deleted` flag used on critical entities.
|
|
|
|
## 2. Architecture Diagrams (A4 Optimized)
|
|
|
|
### 2.1. Core Workflow Architecture
|
|
Focuses on the request lifecycle, approval chains, and direct interactions.
|
|
|
|
```mermaid
|
|
erDiagram
|
|
users ||--o{ workflow_requests : "initiates"
|
|
users ||--o{ approval_levels : "approves"
|
|
users ||--o{ participants : "collaborates"
|
|
workflow_requests ||--|{ approval_levels : "has_steps"
|
|
workflow_requests ||--o{ participants : "has_users"
|
|
workflow_requests ||--o{ documents : "contains"
|
|
workflow_requests ||--o{ work_notes : "discussions"
|
|
workflow_requests ||--o{ activities : "audit_trail"
|
|
workflow_templates ||--o{ workflow_requests : "spawns"
|
|
workflow_requests ||--|| conclusion_remarks : "finalizes"
|
|
|
|
workflow_requests {
|
|
uuid request_id PK
|
|
varchar request_number
|
|
enum status
|
|
integer current_level
|
|
}
|
|
approval_levels {
|
|
uuid level_id PK
|
|
integer level_number
|
|
enum status
|
|
uuid approver_id FK
|
|
}
|
|
```
|
|
|
|
### 2.2. Business Domain Data
|
|
Focuses on the specific data payloads (Dealers, Finance, Claims) attached to requests.
|
|
|
|
```mermaid
|
|
erDiagram
|
|
workflow_requests ||--o{ dealers : "context"
|
|
workflow_requests ||--|| dealer_claim_details : "claim_data"
|
|
workflow_requests ||--|| dealer_proposal_details : "proposal"
|
|
workflow_requests ||--|| dealer_completion_details : "evidence"
|
|
workflow_requests ||--o{ dealer_claim_history : "versions"
|
|
|
|
workflow_requests ||--|| claim_budget_tracking : "financials"
|
|
workflow_requests ||--|| internal_orders : "sap_ref"
|
|
workflow_requests ||--o{ claim_invoices : "billing"
|
|
claim_invoices ||--o{ claim_credit_notes : "adjustments"
|
|
|
|
dealer_claim_details {
|
|
uuid claim_id PK
|
|
varchar activity_type
|
|
}
|
|
claim_budget_tracking {
|
|
decimal approved_budget
|
|
decimal final_claim_amount
|
|
}
|
|
```
|
|
|
|
### 2.3. System Support Services
|
|
Focuses on cross-cutting concerns like logging, notifications, and monitoring.
|
|
|
|
```mermaid
|
|
erDiagram
|
|
users ||--o{ notifications : "receives"
|
|
users ||--o{ system_settings : "configures"
|
|
users ||--o{ audit_logs : "actions"
|
|
|
|
workflow_requests ||--o{ notifications : "triggers"
|
|
workflow_requests ||--o{ tat_tracking : "monitors_sla"
|
|
workflow_requests ||--o{ tat_alerts : "sla_breaches"
|
|
workflow_requests ||--o{ request_summaries : "ai_summary"
|
|
workflow_requests ||--o{ report_cache : "reporting"
|
|
|
|
notifications ||--o{ email_logs : "outbound"
|
|
notifications ||--o{ sms_logs : "outbound"
|
|
|
|
tat_tracking {
|
|
decimal total_tat_hours
|
|
boolean threshold_breached
|
|
}
|
|
```
|
|
|
|
## 3. Schema Modules
|
|
|
|
### 3.1. User & Authentication Module
|
|
Manages user identities, sessions, and system-wide configurations.
|
|
|
|
```mermaid
|
|
erDiagram
|
|
users ||--o{ user_sessions : "has"
|
|
users ||--o{ subscriptions : "has_device"
|
|
users ||--o{ system_settings : "modifies"
|
|
|
|
users {
|
|
uuid user_id PK
|
|
varchar employee_id
|
|
varchar email
|
|
varchar display_name
|
|
enum role
|
|
boolean is_active
|
|
}
|
|
user_sessions {
|
|
uuid session_id PK
|
|
uuid user_id FK
|
|
varchar session_token
|
|
timestamp expires_at
|
|
}
|
|
subscriptions {
|
|
uuid subscription_id PK
|
|
uuid user_id FK
|
|
varchar endpoint
|
|
}
|
|
```
|
|
|
|
#### Tables
|
|
|
|
**`users`**
|
|
Core user registry. synced with Okta/HRMS.
|
|
* `user_id` (PK): Unique UUID.
|
|
* `employee_id` (Unique): HR system ID.
|
|
* `email` (Unique): Official email address.
|
|
* `role`: RBAC role (USER, ADMIN, etc.).
|
|
* `is_active`: Soft delete/account link status.
|
|
|
|
**`user_sessions`**
|
|
Active JWT sessions for invalidation/tracking.
|
|
* `session_token`: The JWT access token.
|
|
* `refresh_token`: For renewing access tokens.
|
|
* `device_type`: Web/Mobile classification.
|
|
|
|
**`system_settings`**
|
|
Dynamic configuration (e.g., global TAT thresholds).
|
|
* `setting_key` (Unique): Config identifier name.
|
|
* `setting_value`: The value (text/json).
|
|
|
|
---
|
|
|
|
### 3.2. Workflow Engine Module
|
|
The core engine driving request lifecycles, approvals, and tracking.
|
|
|
|
```mermaid
|
|
erDiagram
|
|
workflow_requests ||--|{ approval_levels : "steps"
|
|
workflow_requests ||--o{ activities : "events"
|
|
workflow_requests ||--|{ participants : "access"
|
|
workflow_templates ||--o{ workflow_requests : "spawns"
|
|
|
|
workflow_requests {
|
|
uuid request_id PK
|
|
varchar request_number
|
|
enum status
|
|
uuid initiator_id FK
|
|
}
|
|
approval_levels {
|
|
uuid level_id PK
|
|
uuid request_id FK
|
|
integer level_number
|
|
enum status
|
|
uuid approver_id FK
|
|
}
|
|
```
|
|
|
|
#### Tables
|
|
|
|
**`workflow_requests`**
|
|
The central entity representing a business process instance.
|
|
* `request_number`: Human-readable ID (e.g., REQ-2024-001).
|
|
* `current_level`: Pointer to the active approval step.
|
|
* `status`: DRAFT, PENDING, APPROVED, REJECTED, CLOSED.
|
|
|
|
**`approval_levels`**
|
|
Defines the sequence of approvers for a request.
|
|
* `level_number`: Sequence index (1, 2, 3...).
|
|
* `approver_id`: User responsible for this step.
|
|
* `tat_hours`: SLA for this specific step.
|
|
* `status`: PENDING, APPROVED, REJECTED.
|
|
|
|
**`participants`**
|
|
Users with visibility/access to the request (spectators, contributors).
|
|
* `participant_type`: SPECTATOR, CONTRIBUTOR.
|
|
* `can_comment`, `can_view_documents`: Granular permissions.
|
|
|
|
**`activities`**
|
|
Audit trail of all actions performed on a request.
|
|
* `activity_type`: CREATED, APPROVED, COMMENTED, FILE_UPLOADED.
|
|
* `metadata`: JSON payload with specific details of the event.
|
|
|
|
**`workflow_templates`**
|
|
Blueprints for creating new requests.
|
|
* `approval_levels_config`: JSON defining the default approver chain structure.
|
|
|
|
---
|
|
|
|
### 3.3. Dealer Management Module
|
|
Stores specific data related to dealer claims, onboardings, and performance.
|
|
|
|
```mermaid
|
|
erDiagram
|
|
workflow_requests ||--|| dealer_claim_details : "details"
|
|
workflow_requests ||--|| dealer_proposal_details : "proposal"
|
|
workflow_requests ||--|| dealer_completion_details : "completion"
|
|
workflow_requests ||--o{ dealer_claim_history : "versions"
|
|
workflow_requests ||--o{ dealers : "related_to"
|
|
|
|
dealers {
|
|
uuid dealer_id PK
|
|
varchar dealer_name
|
|
varchar sales_code
|
|
}
|
|
```
|
|
|
|
#### Tables
|
|
|
|
**`dealers`**
|
|
Master data for dealerships.
|
|
* `sales_code`, `service_code`: Dealer unique identifiers.
|
|
* `dealer_name`, `region`, `city`: Location details.
|
|
|
|
**`dealer_claim_details`**
|
|
Specific attributes for a Dealer Claim request.
|
|
* `activity_name`, `activity_type`: Marketing/Sales activity details.
|
|
* `period_start_date`, `period_end_date`: Duration of the claim activity.
|
|
|
|
**`dealer_proposal_details`**
|
|
Stores the initial proposal data for a claim.
|
|
* `total_estimated_budget`: The proposed validation amount.
|
|
* `proposal_document_url`: Link to the uploaded proposal PDF/Doc.
|
|
|
|
**`dealer_claim_history`**
|
|
Snapshots of the claim data at various approval stages.
|
|
* `snapshot_data`: JSON dump of the claim state.
|
|
* `version`: Incremental version number.
|
|
|
|
---
|
|
|
|
### 3.4. Financial Module
|
|
Manages budgeting, internal orders, and invoicing.
|
|
|
|
```mermaid
|
|
erDiagram
|
|
workflow_requests ||--|| claim_budget_tracking : "budget"
|
|
workflow_requests ||--|| internal_orders : "io"
|
|
workflow_requests ||--o{ claim_invoices : "invoices"
|
|
claim_invoices ||--o{ claim_credit_notes : "credit_notes"
|
|
```
|
|
|
|
#### Tables
|
|
|
|
**`claim_budget_tracking`**
|
|
Central ledger for a request's financial lifecycle.
|
|
* `initial_estimated_budget`: Original requested amount.
|
|
* `approved_budget`: Validated amount after approvals.
|
|
* `io_blocked_amount`: Amount reserved in SAP.
|
|
* `final_claim_amount`: Actual payout amount.
|
|
|
|
**`internal_orders`**
|
|
SAP Internal Order references.
|
|
* `io_number`: The IO code from SAP.
|
|
* `io_available_balance`, `io_blocked_amount`: Balance tracking.
|
|
|
|
**`claim_invoices`**
|
|
Invoices submitted against the claim.
|
|
* `invoice_number`: Vendor invoice ID.
|
|
* `amount`: Invoice value.
|
|
* `dms_number`: Document Management System reference.
|
|
|
|
**`claim_credit_notes`**
|
|
Adjustments/Returns linked to invoices.
|
|
* `credit_note_amount`: Value to be deducted/adjusted.
|
|
|
|
---
|
|
|
|
### 3.5. Ancillary Modules
|
|
Support functions like notifications, tracking, and logs.
|
|
|
|
#### Tables
|
|
|
|
**`notifications`**
|
|
User alerts.
|
|
* `is_read`: Read status.
|
|
* `action_url`: Deep link to the relevant request.
|
|
|
|
**`tat_tracking`**
|
|
Turnaround Time monitoring.
|
|
* `tracking_type`: REQUEST (overall) or LEVEL (step-specific).
|
|
* `total_tat_hours`: The allowed time.
|
|
* `elapsed_hours`: Time consumed so far.
|
|
* `breached_flags`: `threshold_50_breached`, etc.
|
|
|
|
**`tat_alerts`**
|
|
Logs of TAT breach notifications sent.
|
|
* `alert_type`: TAT_50, TAT_75, TAT_100.
|
|
* `is_breached`: Confirmed breach status.
|
|
|
|
**`request_summaries`**
|
|
AI or manually generated summaries of complex requests.
|
|
* `is_ai_generated`: Origin flag.
|
|
* `description`, `closing_remarks`: Narrative text.
|