# MARS-1049: ENCODING Implementation in FILE_MANAGER

## Change Description
Adding `ENCODING` column to the `A_SOURCE_FILE_CONFIG` table and modifying the `FILE_MANAGER` package to support different character encodings for CSV files.

## Objective
Enable configuration of character encoding for individual source files without code modifications. The value from the `ENCODING` column will be passed as a `characterset` parameter in the formatting options of the `CREATE_EXTERNAL_TABLE` procedure.

---

## 1. DATABASE STRUCTURE MODIFICATIONS

### Adding ENCODING column
```sql
-- Add column to A_SOURCE_FILE_CONFIG table
ALTER TABLE CT_MRDS.A_SOURCE_FILE_CONFIG 
ADD (ENCODING VARCHAR2(50));

-- Add column comment
COMMENT ON COLUMN CT_MRDS.A_SOURCE_FILE_CONFIG.ENCODING 
IS 'Character encoding for CSV files (e.g. UTF8, WE8MSWIN1252, etc.)';
```

**Data type**: `VARCHAR2(50)` - sufficient for Oracle encoding names
**Nullable**: `YES` - defaults to NULL, database default encoding is used
**Default**: `NULL`

---

## 2. FILE_MANAGER PACKAGE MODIFICATIONS

### A. CREATE_EXTERNAL_TABLE procedure signature (main)
**BEFORE:**
```sql
PROCEDURE CREATE_EXTERNAL_TABLE (
   pTableName          IN VARCHAR2,
   pTemplateTableName  IN VARCHAR2,
   pPrefix             IN VARCHAR2,
   pBucketUri          IN VARCHAR2 DEFAULT ENV_MANAGER.gvInboxBucketUri,
   pFileName           IN VARCHAR2 DEFAULT NULL,
   pDelimiter          IN VARCHAR2 DEFAULT ','
)
```

**PO:**
```sql
PROCEDURE CREATE_EXTERNAL_TABLE (
   pTableName          IN VARCHAR2,
   pTemplateTableName  IN VARCHAR2,
   pPrefix             IN VARCHAR2,
   pBucketUri          IN VARCHAR2 DEFAULT ENV_MANAGER.gvInboxBucketUri,
   pFileName           IN VARCHAR2 DEFAULT NULL,
   pDelimiter          IN VARCHAR2 DEFAULT ',',
   pEncoding           IN VARCHAR2 DEFAULT NULL  -- NOWY PARAMETR
)
```

### B. Wywołanie procedury CREATE_EXTERNAL_TABLE (overload)
**Lokalizacja**: Linie 499-506
**PRZED:**
```sql
CREATE_EXTERNAL_TABLE(
   pTableName => vSourceFileReceived.EXTERNAL_TABLE_NAME,
   pTemplateTableName => vSourceFileConfig.TEMPLATE_TABLE_NAME,
   pPrefix => vSourceFileReceived.SOURCE_FILE_PREFIX_INBOX,
   pBucketUri => ENV_MANAGER.gvInboxBucketUri,
   pFileName => vFileName,
   pDelimiter => ','
);
```

**PO:**
```sql
CREATE_EXTERNAL_TABLE(
   pTableName => vSourceFileReceived.EXTERNAL_TABLE_NAME,
   pTemplateTableName => vSourceFileConfig.TEMPLATE_TABLE_NAME,
   pPrefix => vSourceFileReceived.SOURCE_FILE_PREFIX_INBOX,
   pBucketUri => ENV_MANAGER.gvInboxBucketUri,
   pFileName => vFileName,
   pDelimiter => ',',
   pEncoding => vSourceFileConfig.ENCODING  -- NOWY PARAMETR
);
```

### C. Logika kodowania w opcjach formatowania
**Lokalizacja**: Około linii 455 w sekcji vFormat
**PRZED:**
```sql
IF pDelimiter = '|' THEN
   vFormat := json_object('delimiter' VALUE '|', 'skipheaders' VALUE '1');
ELSE
   vFormat := json_object('type' VALUE 'CSV', 'skipheaders' VALUE '1', 'ignoremissingcolumns' value 'true');
END IF;
```

**PO:**
```sql
-- Tworzenie podstawowego formatu
IF pDelimiter = '|' THEN
   vFormat := json_object('delimiter' VALUE '|', 'skipheaders' VALUE '1');
ELSE
   vFormat := json_object('type' VALUE 'CSV', 'skipheaders' VALUE '1', 'ignoremissingcolumns' value 'true');
END IF;

-- Dodanie kodowania jeśli zostało określone
IF pEncoding IS NOT NULL AND LENGTH(TRIM(pEncoding)) > 0 THEN
   vFormat := JSON_MERGEPATCH(vFormat, json_object('characterset' VALUE pEncoding));
END IF;
```

---

## 3. PRZYKŁADY UŻYCIA

### Test z kodowaniem UTF-8
```sql
-- Konfiguracja dla plików z UTF-8 encoding
UPDATE CT_MRDS.A_SOURCE_FILE_CONFIG 
SET ENCODING = 'UTF8'
WHERE A_SOURCE_FILE_CONFIG_KEY = 1;
```

### Test z kodowaniem Windows-1252
```sql
-- Konfiguracja dla plików z Windows-1252 encoding
UPDATE CT_MRDS.A_SOURCE_FILE_CONFIG 
SET ENCODING = 'WE8MSWIN1252'
WHERE A_SOURCE_FILE_CONFIG_KEY = 2;
```

### Resetowanie do wartości domyślnych
```sql
-- Usunięcie kodowania (powrót do domyślnego kodowania bazy)
UPDATE CT_MRDS.A_SOURCE_FILE_CONFIG 
SET ENCODING = NULL
WHERE A_SOURCE_FILE_CONFIG_KEY = 1;
```

---

## 4. MODYFIKACJA ISTNIEJĄCEJ PROCEDURY ADD_SOURCE_FILE_CONFIG

### Rozszerzenie procedury ADD_SOURCE_FILE_CONFIG
**PRZED:**
```sql
PROCEDURE ADD_SOURCE_FILE_CONFIG(
   pSourceKey IN VARCHAR2,
   pSourceFileType IN VARCHAR2,
   pSourceFileId IN VARCHAR2,
   pSourceFileDesc IN VARCHAR2,
   pSourceFileNamePattern IN VARCHAR2,
   pTableId IN VARCHAR2,
   pTemplateTableName IN VARCHAR2
)
```

**PO:**
```sql
PROCEDURE ADD_SOURCE_FILE_CONFIG(
   pSourceKey IN VARCHAR2,
   pSourceFileType IN VARCHAR2,
   pSourceFileId IN VARCHAR2,
   pSourceFileDesc IN VARCHAR2,
   pSourceFileNamePattern IN VARCHAR2,
   pTableId IN VARCHAR2,
   pTemplateTableName IN VARCHAR2,
   pEncoding IN VARCHAR2 DEFAULT NULL  -- NOWY PARAMETR
)
```

### Modyfikacja INSERT statement w ADD_SOURCE_FILE_CONFIG
**PRZED:**
```sql
INSERT INTO CT_MRDS.A_SOURCE_FILE_CONFIG (
   A_SOURCE_KEY, SOURCE_FILE_TYPE, SOURCE_FILE_ID, SOURCE_FILE_DESC,
   SOURCE_FILE_NAME_PATTERN, TABLE_ID, TEMPLATE_TABLE_NAME
) VALUES (
   pSourceKey, pSourceFileType, pSourceFileId, pSourceFileDesc,
   pSourceFileNamePattern, pTableId, pTemplateTableName
);
```

**PO:**
```sql
INSERT INTO CT_MRDS.A_SOURCE_FILE_CONFIG (
   A_SOURCE_KEY, SOURCE_FILE_TYPE, SOURCE_FILE_ID, SOURCE_FILE_DESC,
   SOURCE_FILE_NAME_PATTERN, TABLE_ID, TEMPLATE_TABLE_NAME, ENCODING
) VALUES (
   pSourceKey, pSourceFileType, pSourceFileId, pSourceFileDesc,
   pSourceFileNamePattern, pTableId, pTemplateTableName, pEncoding
);
```

### Przykład użycia zmodyfikowanej procedury
```sql
-- Dodanie konfiguracji z kodowaniem UTF-8
CALL FILE_MANAGER.ADD_SOURCE_FILE_CONFIG(
   pSourceKey => 'C2D',
   pSourceFileType => 'INPUT',
   pSourceFileId => 'UC_DISSEM',
   pSourceFileDesc => 'UC DISSEM Metadata with UTF-8 encoding',
   pSourceFileNamePattern => 'UC_NMA_DISSEM-*.csv',
   pTableId => 'A_UC_DISSEM_METADATA_LOADS',
   pTemplateTableName => 'CT_ET_TEMPLATES.C2D_A_UC_DISSEM_METADATA_LOADS',
   pEncoding => 'UTF8'
);

-- Dodanie konfiguracji bez kodowania (jak dotychczas)
CALL FILE_MANAGER.ADD_SOURCE_FILE_CONFIG(
   pSourceKey => 'LM',
   pSourceFileType => 'INPUT', 
   pSourceFileId => 'STANDING_FACILITIES',
   pSourceFileDesc => 'Standing Facilities Data',
   pSourceFileNamePattern => 'SF_*.csv',
   pTableId => 'STANDING_FACILITIES',
   pTemplateTableName => 'CT_ET_TEMPLATES.LM_STANDING_FACILITIES'
   -- pEncoding pomijamy - będzie NULL (domyślne kodowanie)
);
```

---

## 5. TESTY WALIDACYJNE

### Test 1: Podstawowa funkcjonalność
```sql
-- 1. Ustawienie kodowania UTF-8
UPDATE CT_MRDS.A_SOURCE_FILE_CONFIG 
SET ENCODING = 'UTF8'
WHERE A_SOURCE_FILE_CONFIG_KEY = 1;

-- 2. Test przetwarzania pliku
CALL FILE_MANAGER.PROCESS_SOURCE_FILE('INBOX/TEST/FILE_ID/TABLE_NAME/test_file.csv');

-- 3. Sprawdzenie logów
SELECT * FROM CT_MRDS.A_PROCESS_LOG 
WHERE PROCEDURE_NAME = 'CREATE_EXTERNAL_TABLE' 
ORDER BY LOG_DATE DESC;
```

### Test 2: Fallback do wartości domyślnych
```sql
-- 1. Ustawienie NULL
UPDATE CT_MRDS.A_SOURCE_FILE_CONFIG 
SET ENCODING = NULL
WHERE A_SOURCE_FILE_CONFIG_KEY = 1;

-- 2. Test przetwarzania - powinno być używane domyślne kodowanie
CALL FILE_MANAGER.PROCESS_SOURCE_FILE('INBOX/TEST/FILE_ID/TABLE_NAME/test_file.csv');
```

### Test 3: Różne kodowania
```sql
-- 1. Test z Windows-1252
UPDATE CT_MRDS.A_SOURCE_FILE_CONFIG 
SET ENCODING = 'WE8MSWIN1252'
WHERE A_SOURCE_FILE_CONFIG_KEY = 1;

-- 2. Test z UTF-8
UPDATE CT_MRDS.A_SOURCE_FILE_CONFIG 
SET ENCODING = 'UTF8'
WHERE A_SOURCE_FILE_CONFIG_KEY = 2;

-- 3. Test przetwarzania obu plików
CALL FILE_MANAGER.PROCESS_SOURCE_FILE('INBOX/TEST1/FILE_ID/TABLE_NAME/test_file1.csv');
CALL FILE_MANAGER.PROCESS_SOURCE_FILE('INBOX/TEST2/FILE_ID/TABLE_NAME/test_file2.csv');
```

---

## 6. HARMONOGRAM WDROŻENIA

### Faza 1: Przygotowanie struktury (KRYTYCZNA)
1. ✅ Dodanie kolumny `ENCODING` do tabeli
2. ✅ Zaktualizowanie definicji tabeli w plikach DDL

### Faza 2: Modyfikacja pakietu (WYSOKA)
1. ⏳ Dodanie parametru do sygnatury `CREATE_EXTERNAL_TABLE`
2. ⏳ Implementacja logiki kodowania w formatowaniu JSON
3. ⏳ Aktualizacja wywołania w procedurze overload
4. ⏳ Aktualizacja parametrów logowania

### Faza 3: Testy i walidacja (ŚREDNIA)
1. ⏳ Testy jednostkowe z różnymi kodowaniami
2. ⏳ Testy integracyjne z różnymi typami plików
3. ⏳ Walidacja fallback do domyślnego kodowania

### Faza 4: Modyfikacja procedur konfiguracyjnych (NISKA)
1. ⏳ Modyfikacja `ADD_SOURCE_FILE_CONFIG` - dodanie parametru `pEncoding`
2. ⏳ Aktualizacja dokumentacji
3. ⏳ Przykłady użycia w confluence

---

## 7. ROLLBACK

W przypadku problemów można wykonać rollback:

```sql
-- Usunięcie kolumny (OSTROŻNIE - spowoduje utratę danych)
ALTER TABLE CT_MRDS.A_SOURCE_FILE_CONFIG DROP COLUMN ENCODING;

-- Przywrrócenie oryginalnej wersji pakietu FILE_MANAGER
-- (wymagane przywrrócenie z backupu)
```

---

## 8. UWAGI TECHNICZNE

### Ograniczenia
- Maksymalna długość nazwy kodowania: 50 znaków
- Obsługiwane kodowania: wszystkie wspierane przez Oracle Database
- Przykłady poprawnych nazw: `UTF8`, `WE8MSWIN1252`, `AL32UTF8`, `WE8ISO8859P1`

### Bezpieczeństwo
- Brak walidacji nazwy kodowania na poziomie aplikacji
- Oracle Database zwaliduje kodowanie podczas tworzenia external table
- Fallback do domyślnego kodowania bazy w przypadku NULL

### Wydajność
- Minimalne obciążenie - kodowanie dodawane tylko jeśli nie jest NULL
- Brak wpływu na istniejące procesy gdy kolumna jest NULL
- Używa natywnej funkcji JSON_MERGEPATCH Oracle Database

---

## 9. PRZYGOTOWANIE PACZKI INSTALACYJNEJ

### Struktura paczki MARS-1049
```
MARS_Packages/REL02/MARS-1049/
├── 01_MARS_1049_install_CT_MRDS_ADD_ENCODING_COLUMN.sql
├── 02_MARS_1049_install_CT_MRDS_FILE_MANAGER_SPEC.sql
├── 03_MARS_1049_install_CT_MRDS_FILE_MANAGER_BODY.sql
├── 04_MARS_1049_verify_ENCODING_FUNCTIONALITY.sql
├── 05_MARS_1049_track_version.sql
├── 91_MARS_1049_rollback_FILE_MANAGER_BODY.sql
├── 92_MARS_1049_rollback_FILE_MANAGER_SPEC.sql
├── 93_MARS_1049_rollback_ENCODING_COLUMN.sql
├── 94_MARS_1049_track_rollback_version.sql
├── install_mars1049.sql
├── rollback_mars1049.sql
└── README_ENCODING.md
```

### Zawartość skryptów instalacyjnych

#### 01_MARS_1049_install_CT_MRDS_ADD_ENCODING_COLUMN.sql
```sql
-- MARS-1049: Dodanie kolumny ENCODING do A_SOURCE_FILE_CONFIG
-- Autor: System Enhancement
-- Data: 2025-11-24

PROMPT Adding ENCODING column to CT_MRDS.A_SOURCE_FILE_CONFIG

ALTER TABLE CT_MRDS.A_SOURCE_FILE_CONFIG 
ADD (ENCODING VARCHAR2(50));

COMMENT ON COLUMN CT_MRDS.A_SOURCE_FILE_CONFIG.ENCODING 
IS 'Character encoding for CSV files (e.g. UTF8, WE8MSWIN1252, etc.)';

PROMPT ENCODING column added successfully
```

#### 02_MARS_1049_install_CT_MRDS_FILE_MANAGER_SPEC.sql
```sql
-- MARS-1049: Aktualizacja specyfikacji FILE_MANAGER - dodanie parametru pEncoding
-- Zawiera: Modyfikację sygnatury CREATE_EXTERNAL_TABLE i ADD_SOURCE_FILE_CONFIG
```

#### 04_MARS_1049_verify_ENCODING_FUNCTIONALITY.sql
```sql
-- MARS-1049: Weryfikacja funkcjonalności ENCODING
PROMPT Testing ENCODING functionality...

-- Test 1: Sprawdzenie struktury tabeli
SELECT COLUMN_NAME, DATA_TYPE, DATA_LENGTH, NULLABLE 
FROM USER_TAB_COLUMNS 
WHERE TABLE_NAME = 'A_SOURCE_FILE_CONFIG' 
AND COLUMN_NAME = 'ENCODING';

-- Test 2: Test podstawowej funkcjonalności
INSERT INTO CT_MRDS.A_SOURCE_FILE_CONFIG (
    A_SOURCE_KEY, SOURCE_FILE_TYPE, SOURCE_FILE_ID, 
    SOURCE_FILE_DESC, SOURCE_FILE_NAME_PATTERN, 
    TABLE_ID, TEMPLATE_TABLE_NAME, ENCODING
) VALUES (
    'TEST', 'INPUT', 'ENCODING_TEST', 
    'Test ENCODING functionality', 'test_*.csv',
    'TEST_TABLE', 'CT_ET_TEMPLATES.TEST_TABLE', 'UTF8'
);

-- Sprawdzenie czy rekord został dodany
SELECT A_SOURCE_FILE_CONFIG_KEY, ENCODING 
FROM CT_MRDS.A_SOURCE_FILE_CONFIG 
WHERE A_SOURCE_KEY = 'TEST' AND SOURCE_FILE_ID = 'ENCODING_TEST';

-- Cleanup
DELETE FROM CT_MRDS.A_SOURCE_FILE_CONFIG 
WHERE A_SOURCE_KEY = 'TEST' AND SOURCE_FILE_ID = 'ENCODING_TEST';

PROMPT ENCODING functionality verification completed successfully
```

#### install_mars1049.sql (Master Install Script)
```sql
-- MARS-1049: Master Installation Script
-- CSV Encoding Support Implementation

PROMPT ================================================
PROMPT MARS-1049: Installing CSV Encoding Support
PROMPT ================================================

SPOOL install_mars1049.log

-- Faza 1: Struktura bazy danych
PROMPT Phase 1: Database Structure Changes
@@01_MARS_1049_install_CT_MRDS_ADD_ENCODING_COLUMN.sql

-- Faza 2: Pakiet FILE_MANAGER (Specyfikacja)
PROMPT Phase 2: FILE_MANAGER Package Specification
@@02_MARS_1049_install_CT_MRDS_FILE_MANAGER_SPEC.sql

-- Faza 3: Pakiet FILE_MANAGER (Ciało)
PROMPT Phase 3: FILE_MANAGER Package Body
@@03_MARS_1049_install_CT_MRDS_FILE_MANAGER_BODY.sql

-- Faza 4: Weryfikacja
PROMPT Phase 4: Functionality Verification
@@04_MARS_1049_verify_ENCODING_FUNCTIONALITY.sql

-- Faza 5: Tracking wersji
PROMPT Phase 5: Version Tracking
@@05_MARS_1049_track_version.sql

PROMPT ================================================
PROMPT MARS-1049: Installation completed successfully
PROMPT ================================================

SPOOL OFF
```

#### rollback_mars1049.sql (Master Rollback Script)
```sql
-- MARS-1049: Master Rollback Script
-- WARNING: This will remove ENCODING functionality

PROMPT ================================================
PROMPT MARS-1049: Rolling back CSV Encoding Support
PROMPT WARNING: This will remove ENCODING column and data!
PROMPT ================================================

SPOOL rollback_mars1049.log

-- Rollback w odwrotnej kolejności
@@94_MARS_1049_track_rollback_version.sql
@@93_MARS_1049_rollback_ENCODING_COLUMN.sql
@@92_MARS_1049_rollback_FILE_MANAGER_SPEC.sql
@@91_MARS_1049_rollback_FILE_MANAGER_BODY.sql

PROMPT ================================================
PROMPT MARS-1049: Rollback completed
PROMPT ================================================

SPOOL OFF
```

### Deployment Commands
```powershell
# Instalacja paczki MARS-1049
Get-Content "MARS_Packages\REL02\MARS-1049\install_mars1049.sql" | sql "CT_MRDS/Cloudpass#34@ggmichalski_high"

# W przypadku problemów - rollback
Get-Content "MARS_Packages\REL02\MARS-1049\rollback_mars1049.sql" | sql "CT_MRDS/Cloudpass#34@ggmichalski_high"

# Archiwizacja po instalacji
7z a -pMojeSuperHaslo -mhe=on MARS_1049_arch.7z MARS_Packages\REL02\MARS-1049\*.sql
```

---

## Status: GOTOWE DO IMPLEMENTACJI
**Utworzone**: 2025-11-24
**Autor**: System FILE_MANAGER Enhancement
**MARS Issue**: MARS-1049
**Priorytet**: WYSOKI