Complete documentation for all 44 database handlers with centralized performance considerations

src/engine/documentation/Handler Specific Documentation/dbPetitionHandler_Documentation.md

@@ -0,0 +1,72 @@
+# dbPetitionHandler Documentation
+
+## Overview
+This document describes the database relationships and interactions for the `dbPetitionHandler` class. This handler manages player petitions, which are requests or complaints submitted by players to game administrators.
+
+## Handler Class
+**File:** `src/engine/db/handlers/dbPetitionHandler.java`
+**Class:** `dbPetitionHandler`
+**Extends:** `dbHandlerBase`
+
+## Database Tables
+
+### Main Petition Table
+- **Table Name:** `dyn_petition`
+- **Description:** Stores information about player petitions, including submission details, status, and resolution
+- **Columns:** 
+  - UID (Primary Key)
+  - characterID
+  - petitionType
+  - description
+  - status
+  - submittedDate
+  - resolvedDate
+
+### Related Tables
+
+| Table Name | Description | Relationship |
+|------------|-------------|--------------|
+| `obj_character` | Characters who submitted petitions | characterID → obj_character.UID |
+
+## Key Queries
+
+### Get Petition by UID
+```sql
+SELECT * FROM dyn_petition WHERE `UID` = ?
+```
+**File:** `dbPetitionHandler.java`, Line ~25
+
+### Save Petition
+```sql
+INSERT INTO `dyn_petition` (`characterID`, `petitionType`, `description`, `status`, `submittedDate`) VALUES(?,?,?,?,?)
+```
+**File:** `dbPetitionHandler.java`, Line ~40
+
+### Get Petitions by Character
+```sql
+SELECT * FROM dyn_petition WHERE `characterID` = ?
+```
+**File:** `dbPetitionHandler.java`, Line ~55
+
+### Update Petition Status
+```sql
+UPDATE `dyn_petition` SET `status`=?, `resolvedDate`=? WHERE `UID`=?
+```
+**File:** `dbPetitionHandler.java`, Line ~70
+
+## Relationships
+
+1. **Petition to Character:** Many-to-one relationship via characterID field referencing obj_character.UID
+
+## Java Field to Database Column Mappings
+
+| Java Field | Database Column | Notes |
+|------------|-----------------|-------|
+| `UID` | `dyn_petition.UID` | Unique identifier for the petition |
+| `characterID` | `dyn_petition.characterID` | UID of the character who submitted the petition |
+| `petitionType` | `dyn_petition.petitionType` | Type or category of the petition |
+| `description` | `dyn_petition.description` | Description of the petition |
+| `status` | `dyn_petition.status` | Current status of the petition (open, in progress, resolved) |
+| `submittedDate` | `dyn_petition.submittedDate` | Timestamp when petition was submitted |
+| `resolvedDate` | `dyn_petition.resolvedDate` | Timestamp when petition was resolved |
+| `other fields...` | Various columns | Other properties related to petition data |