dragndrop_hld/SPLICING_MAPPING.md

# Splicing Field Mapping Guide

This document maps shapefile fields to Verofy API fields for splicing.

## Data Analysis Summary

**Source:** Map Project ID 15685
**Total Splicing Records (from API):** 0 (no existing data in this map)
**Total Splicing Records (from shapefile):** 100
**Date Retrieved:** 2025-12-09

## Shapefile Structure

From `splicing.shp`:

| Field Name | Data Type | Sample Values |
|------------|-----------|---------------|
| AKA | String | "EUR_CBSP_005_600D", "EUR_Z05_MST_018", "EUR_Z05_SP_004_450D" |
| Type | String | "Splice", "MST" |
| Group 1 | String | "Zone 02", "Zone 03" |
| Group 2 | String | "EUR_Z05 225-228", null |
| Latitude | Float | 40.778622 |
| Longitude | Float | -124.144169 |
| UID | Integer | 0, 1, 2, ... |

### Unique Values Analysis

**Type values found:**
- "Splice" (majority)
- "MST" (Mechanical Splice Terminal)

**Group 1 values:**
- "Zone 02"
- "Zone 03"

**Group 2 values:**
- Various zone identifiers like "EUR_Z05 225-228"
- Many null values

## Verofy API Structure

Based on `/map-splice` API endpoint and pattern from similar models:

| Field Name | Data Type | Required | Sample Values |
|------------|-----------|----------|---------------|
| id | Integer | Auto | (auto-generated) |
| mapProjectId | Integer | **Yes** | 15685 |
| name | String | **Yes** | "EUR_CBSP_005_600D" |
| latitude | String | **Yes** | "40.778622" |
| longitude | String | **Yes** | "-124.144169" |
| typeId | Integer | **Yes** | 1 (Splice), 2 (FTP), 3 (MST) |
| statusId | Integer | **Yes** | 1 (Planned), 2 (Splicing Required), 3 (Splicing Completed) |
| group1 | String | No | "Zone 02" |
| group2 | String | No | "EUR_Z05 225-228" |
| locked | Integer | No | 0 (unlocked), 1 (locked) |
| custom | Integer | No | 0 |

## Field Mapping

### Direct Mappings

| Shapefile Field | API Field | Transformation |
|-----------------|-----------|----------------|
| AKA | name | Direct copy (string) - This is the primary identifier |
| Latitude | latitude | Convert float to string |
| Longitude | longitude | Convert float to string |
| Group 1 | group1 | Direct copy (string) |
| Group 2 | group2 | Direct copy (string) |

### Type Mapping (Lookup Required)

The shapefile `Type` field (string) must be mapped to API `typeId` (integer) using the MapSpliceType reference:

| Shapefile Type Value | API typeId | Type Name in Verofy |
|----------------------|------------|---------------------|
| "Splice" | 1 | Splice |
| "FTP" | 2 | FTP (Fiber Termination Panel) |
| "MST" | 3 | MST (Mechanical Splice Terminal) |

### Generated/Default Values

| API Field | Value | Notes |
|-----------|-------|-------|
| mapProjectId | User provided | Required parameter |
| name | {AKA} or "Splice-{UID}" | Use AKA field, fallback to generated name |
| statusId | 1 | Default to "Planned" |
| locked | 0 | Default to unlocked |
| custom | 0 | Default value |

### Unused Shapefile Fields

| Field | Usage |
|-------|--------|
| UID | Used only as fallback if AKA is empty |

## API Endpoint

**Endpoint:** `POST /v1/map-splice/create`
**Authentication:** Bearer token required
**Success Response:** 201 Created

## Example API Request

### Example 1: Splice Point
```json
{
  "mapProjectId": 15685,
  "name": "EUR_CBSP_005_600D",
  "latitude": "40.778622",
  "longitude": "-124.144169",
  "typeId": 1,
  "statusId": 1,
  "group1": "Zone 02",
  "group2": null,
  "locked": 0
}
```

### Example 2: MST Point
```json
{
  "mapProjectId": 15685,
  "name": "EUR_Z05_MST_018",
  "latitude": "40.783264",
  "longitude": "-124.142093",
  "typeId": 3,
  "statusId": 1,
  "group1": "Zone 02",
  "group2": "EUR_Z05 225-228",
  "locked": 0
}
```

## Implementation Notes

1. **Type Lookup:** The current `verofy_uploader.py` incorrectly maps `Type` to `type` (string field). It should map to `typeId` (integer) using the MapSpliceType reference lookup.

2. **Reference Data:** Load MapSpliceType references from `MapSpliceType_references.json`.

3. **AKA Field Importance:** The AKA field contains meaningful identifiers that should be preserved as the name. Examples:
   - "EUR_CBSP_005_600D" - Cabinet splice point
   - "EUR_Z05_MST_018" - Zone 5 MST #18
   - "EUR_Z05_SP_004_450D" - Zone 5 splice point #4

4. **Error Handling:** If a Type value from the shapefile is not found in the lookup table:
   - Log a warning with the unknown type
   - Default to typeId: 1 (Splice) as it's the most common type
   - Continue processing rather than failing

5. **Status Default:** Default to statusId: 1 (Planned) for new imports. This can be updated later based on actual splicing progress.

## Status Reference

| statusId | Status Name | Description |
|----------|-------------|-------------|
| 1 | Planned | Splice location is planned but not yet worked |
| 2 | Splicing Required | Location identified, splicing work needed |
| 3 | Splicing Completed | Splicing work has been completed |

Default to statusId: 1 (Planned) for new imports.

## Type Reference

| typeId | Type Name | Description |
|--------|-----------|-------------|
| 1 | Splice | Standard fiber splice point |
| 2 | FTP | Fiber Termination Panel |
| 3 | MST | Mechanical Splice Terminal |

## Key Differences from Current Implementation

**Current (Incorrect):**
```python
splicing_data = {
    "type": str(row['Type'])  # ❌ Wrong - sends string
}
```

**Corrected:**
```python
splicing_data = {
    "typeId": type_lookup.get(row['Type'], 1),  # ✅ Correct - sends integer ID
    "statusId": 1,  # ✅ Added required field
    "locked": 0     # ✅ Added default field
}
```