# PDF Editor - Database Schema & Data Flow

## Database Table: `annotations`

### Location
- **Migration File**: `database/migrations/2025_09_29_104240_create_annotations_table.php`
- **Updated Migration**: `database/migrations/2025_10_16_131634_update_annotations_shape_type_enum.php`

### Table Structure

```sql
CREATE TABLE annotations (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    pdf_file VARCHAR(255),
    page_number INT,
    shape_type ENUM('rect', 'circle', 'triangle', 'spool', 'weld', 'shop_weld', 'leader_line', 'text'),
    x_coordinate DECIMAL(10,2),
    y_coordinate DECIMAL(10,2),
    width DECIMAL(10,2),
    height DECIMAL(10,2),
    shape_id VARCHAR(100),
    spool_no VARCHAR(100),
    joint_type TEXT,
    classification VARCHAR(50),
    created_by BIGINT,
    created_at TIMESTAMP,
    updated_at TIMESTAMP
);
```

### Field Descriptions

| Field | Type | Description | Used For |
|-------|------|-------------|----------|
| `id` | BIGINT | Primary key | Unique identifier |
| `pdf_file` | VARCHAR(255) | PDF file path | Linking annotations to specific PDFs |
| `page_number` | INT | Page number | Multi-page PDF support |
| `shape_type` | ENUM | Type of annotation | rect, circle, triangle, spool, weld, shop_weld, leader_line, text |
| `x_coordinate` | DECIMAL(10,2) | X position | Canvas coordinate (for shapes: top-left, for lines: start point) |
| `y_coordinate` | DECIMAL(10,2) | Y position | Canvas coordinate |
| `width` | DECIMAL(10,2) | Width/Delta X | Shape width or line X distance |
| `height` | DECIMAL(10,2) | Height/Delta Y | Shape height or line Y distance |
| `shape_id` | VARCHAR(100) | Unique shape ID | Cross-referencing (leader lines to shapes, QR codes) |
| `spool_no` | VARCHAR(100) | Spool number | Business data for welding |
| `joint_type` | TEXT | Joint type or text content | Business data for welding OR free text content |
| `classification` | VARCHAR(50) | Annotation category | 'shape_text', 'free_text', etc. |
| `created_by` | BIGINT | User ID | Audit trail |
| `created_at` | TIMESTAMP | Creation time | Audit trail |
| `updated_at` | TIMESTAMP | Update time | Audit trail |

### Special Field Usage

#### Leader Lines
- `shape_type`: 'leader_line'
- `x_coordinate`, `y_coordinate`: Start point (click point)
- `width`: Delta X (x2 - x1)
- `height`: Delta Y (y2 - y1)
- Additional metadata stored in backend:
  - `connectedShapeId`: The shape this line connects to
  - `originalStartPoint`: Original click coordinates for reconnection

#### Text Annotations
- `shape_type`: 'text'
- `joint_type`: Contains the actual text content
- `classification`: 
  - 'shape_text': Text inside shapes (red, bold, 28px)
  - 'free_text': Standalone notes (black, normal, 16px)

#### Shapes (rect, circle, triangle, etc.)
- Standard coordinate and dimension fields
- `spool_no`: **Business identifier - populated from Spool Number dropdown**
  - Rectangle shapes: Display spool_no as text inside shape
  - Source: MTO (Material Take-Off) data or manually generated
  - Dropdown ID: `#spool-select`
- `joint_type`: **Joint/Weld classification - populated from Weld Number dropdown**
  - Triangle/Circle shapes: Display joint_type (weld number) as text inside shape
  - Source: MTO welders data or manually entered
  - Dropdown ID: `#weld-select`
- `shape_id`: Used for QR code generation and leader line connection

**Shape Type → Data Mapping:**
- **Rectangle** → Uses `spool_no` for text content
- **Triangle** → Uses `joint_type` (weld number) for text content
- **Circle** → Uses `joint_type` (weld number) for text content

---

## Data Population System

### Spool Number (`spool_no` field)

#### What is it?
Spool number is a unique identifier for a spool in piping/welding systems. In the PDF Editor, this value is used to label rectangle shapes.

#### How it's populated:
1. **From MTO Data** (Material Take-Off):
   ```javascript
   // Function: populateMtoForms()
   // Populates dropdown from mtoData.spools array
   spoolSelect.innerHTML = '<option value="">Select Spool</option>';
   mtoData.spools.forEach(spool => {
       option.value = spool.spool_number; // e.g., "SP001"
       option.textContent = spool.spool_number;
   });
   ```

2. **Auto-Generate**:
   - Button: "Generate" next to Spool Number dropdown
   - API Call: `GET /api/mto/spools/generate-number`
   - Returns: New unique spool number (e.g., "SP123")

3. **Manual Selection**:
   - User selects from dropdown: `<select id="spool-select">`
   - Value is stored when shape is created

#### When it's used:
- **Rectangle shapes**: Display spool_no inside the shape as red text
- **Shape creation**: Value is read from dropdown and assigned to `shape.spoolNo`
- **Database save**: Stored in `annotations.spool_no` column

#### Code Flow:
```javascript
// 1. User selects spool from dropdown
<select id="spool-select">
    <option value="SP001">SP001</option>
    <option value="SP002">SP002</option>
</select>

// 2. User draws rectangle with leader line
const spoolSelect = document.getElementById('spool-select');
const spoolNo = spoolSelect.value; // "SP001"

// 3. Shape is created with spool number
shape.set('spoolNo', spoolNo);

// 4. Text is added inside rectangle
textContent = (spoolNo && spoolNo.trim() !== '') ? spoolNo : 'N/A';
// Result: "SP001" displayed in red inside rectangle

// 5. Save to database
annotation = {
    spool_no: obj.spoolNo, // "SP001"
    shape_type: 'rect',
    ...
};
```

---

### Weld/Joint Number (`joint_type` field)

#### What is it?
Weld/Joint number is a unique identifier for a weld joint in piping systems. In the PDF Editor, this value is used to label triangle and circle shapes.

#### How it's populated:
1. **From MTO Welders Data**:
   ```javascript
   // Function: populateMtoForms()
   // Populates dropdown from mtoData.welders array
   weldSelect.innerHTML = '<option value="">Select Weld</option>';
   mtoData.welders.forEach(welder => {
       option.value = welder.welder_code; // e.g., "W001"
       option.textContent = welder.welder_code;
   });
   ```

2. **Auto-Generate**:
   - Button: "Generate" next to Weld Number dropdown
   - API Call: `GET /api/mto/joints/generate-number?spool_no={spoolNo}`
   - Returns: New joint number based on spool (e.g., "J-SP001-001")

3. **Manual Selection**:
   - User selects from dropdown: `<select id="weld-select">`
   - Value is stored when shape is created

#### When it's used:
- **Triangle shapes**: Display joint_type inside the shape as red text
- **Circle shapes**: Display joint_type inside the shape as red text
- **Shape creation**: Value is read from dropdown and assigned to `shape.weldNo`
- **Database save**: Stored in `annotations.joint_type` column

#### Code Flow:
```javascript
// 1. User selects weld from dropdown
<select id="weld-select">
    <option value="W001">W001</option>
    <option value="W002">W002</option>
</select>

// 2. User draws triangle with leader line
const weldSelect = document.getElementById('weld-select');
const weldNo = weldSelect.value; // "W001"

// 3. Shape is created with weld number
shape.set('weldNo', weldNo);

// 4. Text is added inside triangle
textContent = (weldNo && weldNo.trim() !== '') ? weldNo : 'N/A';
// Result: "W001" displayed in red inside triangle

// 5. Save to database
annotation = {
    joint_type: obj.weldNo, // "W001"
    shape_type: 'triangle',
    ...
};
```

---

### Current Status Issue

**Problem**: `spool_no` field is currently empty in database

**Possible Reasons**:
1. **MTO Data Not Loaded**: `mtoData.spools` array is empty or not fetched
2. **Dropdown Not Selected**: User is creating shapes without selecting spool/weld number
3. **Sample Data**: System falls back to sample data (SP001, SP002, SP003) if MTO data is missing
4. **API Integration**: MTO API endpoints might not be returning data

**How to Fix**:
1. Check MTO data loading in browser console
2. Ensure dropdown has options before creating shapes
3. Select spool/weld number from dropdown before drawing
4. Verify API endpoints are working:
   - `/api/mto/spools/generate-number`
   - `/api/mto/joints/generate-number`

**Testing**:
```javascript
// Open browser console on PDF Editor page
console.log('MTO Data:', mtoData);
console.log('Spools:', mtoData.spools);
console.log('Welders:', mtoData.welders);

// Check dropdown values
const spoolSelect = document.getElementById('spool-select');
console.log('Spool options:', Array.from(spoolSelect.options).map(o => o.value));
```

---

## API Endpoints

### 1. Save/Sync Annotations
**Endpoint**: `POST /api/pdf-editor/annotations/sync`

**Controller**: `app/Http/Controllers/Api/AnnotationController.php` → `syncAnnotations()`

**Request Body**:
```json
{
  "pdf_file": "path/to/file.pdf",
  "page_number": 1,
  "annotations": [
    {
      "shape_id": "shape-1729612345678",
      "spool_no": "SP-001",
      "joint_type": "Butt Weld",
      "classification": "",
      "page_number": 1,
      "x_coordinate": 100,
      "y_coordinate": 200,
      "width": 140,
      "height": 70,
      "shape_type": "rect",
      "pdf_file_path": "path/to/file.pdf",
      "created_by": 1
    },
    {
      "shape_id": "leader-1729612345680",
      "shape_type": "leader_line",
      "x_coordinate": 150,
      "y_coordinate": 180,
      "width": 0,
      "height": 50,
      "connectedShapeId": "shape-1729612345678",
      "originalStartPoint": {"x": 150, "y": 180}
    }
  ]
}
```

**Response**:
```json
{
  "success": true,
  "message": "Annotations synced successfully",
  "data": {
    "deleted": 2,
    "created": 5
  }
}
```

**Logic**:
1. Deletes all existing annotations for the specific PDF page
2. Inserts all new annotations from the request
3. Transaction-based for data integrity

---

### 2. Load Annotations
**Endpoint**: `GET /api/pdf-editor/annotations?pdf_file={path}&page_number={num}`

**Controller**: `app/Http/Controllers/Api/AnnotationController.php` → `index()`

**Response**:
```json
{
  "success": true,
  "data": [
    {
      "id": 123,
      "pdf_file": "path/to/file.pdf",
      "page_number": 1,
      "shape_type": "triangle",
      "x_coordinate": 300,
      "y_coordinate": 400,
      "width": 140,
      "height": 140,
      "shape_id": "shape-1729612345690",
      "spool_no": "SP-002",
      "joint_type": "Fillet",
      "classification": "",
      "created_by": 1,
      "created_at": "2025-10-22 10:30:00",
      "updated_at": "2025-10-22 10:30:00"
    }
  ]
}
```

---

### 3. Generate QR Code
**Endpoint**: `GET /api/pdf-editor/qr-code/{shapeId}`

**Controller**: `app/Http/Controllers/Api/AnnotationController.php` → `generateQRCode()`

**Response**: PNG image data (base64 or binary)

**Used For**: Generating QR codes for shape annotations

---

## Data Flow Diagram

```
┌─────────────────────────────────────────────────────────────┐
│                    PDF EDITOR FRONTEND                       │
│                 (pdf-editor.blade.php)                       │
└─────────────────────────────────────────────────────────────┘
                            │
                            │ User draws shapes, 
                            │ adds text, creates 
                            │ leader lines
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                    FABRIC.JS CANVAS                          │
│  - Shapes (rect, circle, triangle)                          │
│  - Leader Lines (connecting click point to shape edge)      │
│  - Text Objects (free text notes + shape text)              │
│  - QR Codes (linked to shapes)                              │
└─────────────────────────────────────────────────────────────┘
                            │
                            │ Save button clicked
                            ▼
┌─────────────────────────────────────────────────────────────┐
│            saveCurrentPageAnnotations()                      │
│  - Iterates through all canvas objects                      │
│  - Skips QR codes (not saved)                               │
│  - Converts shapes, lines, text to annotation format        │
│  - Prepares JSON payload                                    │
└─────────────────────────────────────────────────────────────┘
                            │
                            │ POST /api/pdf-editor/annotations/sync
                            ▼
┌─────────────────────────────────────────────────────────────┐
│          API: AnnotationController@syncAnnotations          │
│  1. Validates request data                                  │
│  2. Starts database transaction                             │
│  3. Deletes old annotations for this page                   │
│  4. Inserts new annotations                                 │
│  5. Commits transaction                                     │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                    DATABASE TABLE                            │
│                      `annotations`                           │
│  - All annotations stored with coordinates, types, metadata │
└─────────────────────────────────────────────────────────────┘
                            │
                            │ Page reload or PDF selection
                            │ GET /api/pdf-editor/annotations
                            ▼
┌─────────────────────────────────────────────────────────────┐
│          API: AnnotationController@index                    │
│  - Fetches annotations for specified PDF + page             │
│  - Returns JSON array                                       │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│            loadExistingAnnotations()                         │
│  - Receives annotation data from API                        │
│  - Calls loadAnnotationToCanvas() for each                  │
│  - Recreates shapes, lines, text on canvas                  │
│  - Calls reconnectLeaderLines() to re-establish connections │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                    FABRIC.JS CANVAS                          │
│  - All annotations restored                                 │
│  - Leader lines connected to shapes                         │
│  - QR codes regenerated via API                             │
└─────────────────────────────────────────────────────────────┘
```

---

## Key Implementation Details

### Triangle Leader Line Connection
- **Challenge**: Triangles have different geometry than rectangles/circles
- **Solution**: Custom `calculateEdgePoint()` function in `setupConnectedMovement()`
  - Calculates triangle vertices and edges
  - Determines closest edge/vertex based on original click position
  - Connects leader line to appropriate edge point
  - Handles rotation, scaling, and movement events

### Unique Shape IDs
- Generated using `Date.now()` to ensure uniqueness across page reloads
- Format: `shape-{timestamp}`, `leader-{timestamp}`, `text-{timestamp}`
- Prevents database conflicts when saving new annotations

### Text Handling
- **Shape Text**: Red, bold, 28px, positioned inside shapes, non-selectable
- **Free Text**: Black, normal, 16px, standalone notes, selectable
- Both saved to same table with different `classification` values

### Leader Line Storage
- Start point stored as `x_coordinate`, `y_coordinate`
- End point calculated using `width` and `height` deltas
- Metadata (`connectedShapeId`, `originalStartPoint`) preserved for reconnection

---

## Validation Rules

```php
// app/Http/Controllers/Api/AnnotationController.php

'annotations' => 'required|array',
'annotations.*.shape_type' => 'required|in:rect,circle,triangle,spool,weld,shop_weld,leader_line,text',
'annotations.*.x_coordinate' => 'required|numeric',
'annotations.*.y_coordinate' => 'required|numeric',
'annotations.*.width' => 'nullable|numeric',
'annotations.*.height' => 'nullable|numeric',
'annotations.*.shape_id' => 'required|string',
'annotations.*.page_number' => 'required|integer',
```

---

## Future Enhancements
- Add annotation history/versioning
- Implement collaborative editing with user tracking
- Add annotation comments/notes
- Support for more shape types
- Advanced leader line routing (avoid overlaps)