# Traffic Toolkit PRO - Moduły

Kod rozszerzenia podzielony na 18 modułów dla lepszej czytelności i utrzymania (v8.5.0 - Phase 1+2 Complete).

---

## 📁 Struktura modułów

```
extension/modules/
├── config.js              # Konfiguracja (CONFIG, CAMPAIGN_FORMATS)
├── fp-utils.js            # v8.4.1: FP utilities (curry), zero deps - Issue #1
├── logger.js              # v8.4.1: Logger Registry + toast - Issue #1, #4
├── dom-helpers.js         # v8.4.1: DOM + CodeMirror helpers - Issue #1
├── schema-api.js          # v8.4.1: Schema fetching from CRM API - Issue #1
├── schema-serializer.js   # v8.4.1: Schema serialization - Issue #1
├── utils.js               # v8.4.1: DEPRECATED wrapper (backward compat) - Issue #1
├── state.js               # v8.4.1: Reactive state + immutability - Issue #3
├── image-helpers.js       # Funkcje dopasowania obrazków do formatów
├── templates.js           # Szablony CRM (CRM_TEMPLATES)
├── api.js                 # DEPRECATED w v8.0
├── transformers.js        # TRANSFORMER_STRATEGIES + CODE_TEMPLATES
├── schemas.js             # DEPRECATED w v8.0
├── diff.js                # v8.1: calculateDiff() - JSON Diff feature
├── effects.js             # Effects & subscriptions
├── ui.js                  # UI rendering + renderDiff() + dynamic fields
├── automation.js          # runAuto + schema application logic
└── main.js                # v8.4.1: Inicjalizacja + deprecations - Issue #8
```

---

## 🔧 Build Process

Moduły są łączone w jeden plik `extension/content.js` za pomocą build script:

```bash
node build.js
```

**Build script:**
1. Czyta wszystkie moduły w określonej kolejności (ważne dla zależności)
2. Łączy je w jeden plik
3. Opakowuje w IIFE `(function() { 'use strict'; ... })()`
4. Zapisuje jako `extension/content.js`

---

## 📦 Zależności między modułami

Kolejność modułów w build process:

```
config.js              → CONFIG, CAMPAIGN_FORMATS
  ↓
fp-utils.js            → curry (FP utilities) - zero deps! (v8.4.1)
  ↓
logger.js              → getLogger(namespace), Logger Registry (v8.4.1)
  ↓
dom-helpers.js         → DOM helpers, CodeMirror wrappers (v8.4.1)
  ↓
schema-api.js          → fetchFormCreationSchema (v8.4.1)
  ↓
schema-serializer.js   → Schema serialization (v8.4.1)
  ↓
utils.js               → DEPRECATED wrapper (re-exports) (v8.4.1)
  ↓
state.js               → toolkitState (reactive + immutable) (v8.4.1)
  ↓
image-helpers.js       → getMappedFormat, matchImageToFormat
  ↓
templates.js           → CRM_TEMPLATES
  ↓
api.js                 → DEPRECATED (puste)
  ↓
transformers.js        → TRANSFORMER_STRATEGIES + CODE_TEMPLATES
  ↓
schemas.js             → DEPRECATED (puste)
  ↓
diff.js                → calculateDiff() (v8.1)
  ↓
effects.js             → toolkitState subscriptions
  ↓
ui.js                  → renderFields, collectInput
  ↓
automation.js          → runAuto, applySchemaToCreation
  ↓
main.js                → initToolkit + eksporty + deprecations (v8.4.1)
```

---

## 📝 Opis modułów (v8.4.1)

### config.js
Stałe konfiguracyjne:
- `CONFIG.TIMEOUTS` - Timeouty (CREATION_ADD, TEMPLATE_SELECT, etc.)
- `CONFIG.SELECTORS` - Selektory CSS dla elementów CRM
- `CONFIG.LOGGING` - Konfiguracja logowania (namespaces, levels) ⭐ v8.4.1
- `CAMPAIGN_FORMATS` - Mapowanie formatów (wymiary, aliasy)

### fp-utils.js ⭐ v8.4.1 (Issue #1 - God Module split)
Functional programming utilities:
- **`curry(fn)`** - Function currying
- **Zero dependencies** - pierwszy moduł w dependency chain
- Pure functions only

### logger.js ⭐ v8.4.1 (Issue #1, #4 - God Module split + Logger Registry)
Logging system z namespace isolation:
- **`getLogger(namespace)`** - Logger Registry pattern (Issue #4)
  - One logger per module
  - Map-based caching - eliminuje duplikację
  - Namespace w każdym logu
- **`showToast(message, type, duration)`** - Toast notifications
- **`logError(error, context)`** - Centralized error handling
- **`withErrorHandling(fn, options)`** - Async error wrapper HOF
- **`withCallbackErrorHandling(fn, context)`** - Sync error wrapper HOF
- **350 lines** (was part of utils.js)

### dom-helpers.js ⭐ v8.4.1 (Issue #1 - God Module split)
DOM manipulation + CodeMirror helpers:
- **Event dispatching:** `dispatchEvent`, `dispatchEvents`
- **CodeMirror helpers:** `getCodeMirror`, `setCodeMirrorValue`, `waitForCodeMirror`, `getCodeMirrorFromTextarea`
- **Input helpers:** `setInputValue`, `setInputValueByParam`
- **Creation helpers:** `getLastCreation`
- **200 lines** (was part of utils.js)

### schema-api.js ⭐ v8.4.1 (Issue #1 - God Module split)
Schema fetching from CRM API:
- **`fetchFormCreationSchema(templateId)`** - pobiera pełną schema z API ⭐
  - Returns: `{templateId, form_creation_templates, form_creation_params, form_creation_iframe, form_creation_element}`
  - **In-memory caching** per templateId
  - Error handling + retry logic
- **`fetchCreationSchema(creationId)`** - schema + aktualne wartości z istniejącej kreacji
- **Schema transformation:** `mapParamToField`, `cloneSchema`, `validateSchema`
- **400 lines** (was part of utils.js)

### schema-serializer.js ⭐ v8.4.1 (Issue #1 - God Module split)
Schema serialization:
- **`applyTransformations(data)`** - Aplikuje transformacje
- **`serializeField(fieldDef, scope)`** - Single field → JSON
- **`prune(obj)`** - Immutable object pruner (remove null/undefined/empty)
- **250 lines** (was part of utils.js)

### utils.js ⚠️ DEPRECATED v8.4.1 (Issue #1 - God Module split)
**Wrapper module dla backward compatibility:**
- **Re-exports** wszystkich funkcji z 5 modułów:
  - fp-utils.js → curry
  - logger.js → getLogger, showToast, logError, error handlers
  - dom-helpers.js → DOM + CodeMirror helpers
  - schema-api.js → fetchFormCreationSchema, fetchCreationSchema
  - schema-serializer.js → serialization helpers
- **Zachowane dla backward compatibility** - stary kod nadal działa
- **⚠️ Nie dodawaj tu nowego kodu!** - użyj bezpośrednio specjalistycznych modułów

**Migration example:**
```javascript
// ❌ OLD (przez utils.js)
import { fetchFormCreationSchema } from './utils.js';

// ✅ NEW (bezpośrednio)
import { fetchFormCreationSchema } from './schema-api.js';
```

### state.js ⭐ v8.4.1 (Issue #3 - Immutability)
Reactive state management z immutability:
- **`createCoreStore(initialState, options)`** - Factory reactive store
  - **Immutability:** Wszystkie settery używają spread operator: `{...state, key: value}`
  - **History stack:** Zapis poprzednich stanów
  - **`undo()`** - Cofa ostatnią zmianę (time-travel debugging) ⭐
  - **`getHistory()`** - Zwraca historię stanów ⭐
- **`toolkitState`** - Globalny store dla UI
- Computed values: `placeholder`, `matchedImages`, `isImageTransformer`, etc.
- Reactive updates → auto-render UI

### image-helpers.js
Dopasowanie obrazków do formatów:
- `getMappedFormat(alias)` - Mapuje alias formatu na klucz
- `matchImageToFormat(image, format)` - Sprawdza czy obrazek pasuje
- `getSelectedImageUrl()` - Pobiera URL wybranego obrazka
- `getFormData()` - Pobiera dane z formularza dla transformerów obrazkowych

### templates.js
Szablony CRM:
- `CRM_TEMPLATES` - Mapowanie ID szablonu → config (displayName, defaultIframe)

### api.js
**DEPRECATED w v8.0** - wyczyszczony moduł:
- Wszystkie funkcje przeniesione do `utils.js`
- `fetchTemplateParams()` USUNIĘTE → zastąpione przez `fetchFormCreationSchema()`

### transformers.js
Transformery kodu (Strategy Pattern):
- `TRANSFORMER_STRATEGIES` - Mapa strategii transformacji
- `CODE_TEMPLATES` - UI templates z dynamic fields
- **`createStrategyTransformer()`** - zwraca object (nie JSON!) ⭐
- **`transformers`** - Async transformers (adform_tag, dcm_click_tracker_tag, etc.)
- **Schema helpers:**
  - `findFieldNameByParamName(schema, paramName)` - znajdź field.name dla param
  - `findFieldsByPattern(schema, pattern)` - znajdź pola regex

**Sygnatura `_default` w v8.0:**
```javascript
'_default': (code, schema, data) => { ... }  // schema zamiast apiParams!
```

### schemas.js
**DEPRECATED w v8.0** - wyczyszczony moduł:
- Wszystkie schemas przeniesione do `applySchemaToCreation()` w `automation.js`
- Brak potrzeby dla custom handlers - schema z API ma wszystko!

### effects.js
Reactive effects & subscriptions:
- Auto-update placeholder przy zmianie transformera
- Auto-populate image select przy zmianie formatu

### ui.js
Interfejs użytkownika:
- `renderFields(transformerName)` - Renderuje dynamic fields
- `collectInput(transformerName)` - Zbiera dane z UI
- `populateTransformerSelect()`, `populateImageSelect()`
- `injectUI()` - Inicjalizacja UI panelu

### automation.js
**Główny moduł v8.0 - Schema-Based Automation:**

- **`mergeSchemaWithOverrides(schema, code, overrides, options)`**
  - Merge pełnej schemy z overrides
  - Obsługuje: extraCode, creationFiles

- **`applySchemaToCreation(element, schema)`** ⭐
  - Aplikuje schema do formularza
  - Wywołuje `applySectionToForm()` dla każdej sekcji

- **`applySectionToForm(formElement, sections)`** ⭐
  - Sortuje pola według typu (selecty PIERWSZE, CodeMirror NA KOŃCU)
  - 200ms delay między polami (fix race condition)

- **`applyFieldValue(formElement, field)`** ⭐
  - Auto-detection typu pola
  - Skip jeśli wartość już OK (`[skip]` w logach)
  - Obsługuje: select, Select2, CodeMirror, checkbox, input

- **`getFieldPriority(field)`**
  - Priorytet sortowania (1-10)
  - select=1, radio=2, checkbox=3, input=4, textarea=5, CodeMirror=6

- **`normalizeForComparison(value)`**
  - Normalizacja dla porównań (null/undefined/Array)

- **`runAuto()`**
  - Pipeline: parse JSON → create creation → apply schema

- **Helper functions:** `createNewCreation()`, `selectCrmTemplate()`

### main.js ⭐ v8.4.1 (Issue #8 - Deprecation Warnings)
Inicjalizacja i eksporty:
- `initToolkit()` - Inicjalizacja extension
- **`window.trafficToolkit`** - Public API v8.4.1 (structured namespaces: logger, fp, dom)
- **Deprecation warnings** - 11 window globals z Object.defineProperty wrappers ⭐
  - One-time styled warnings w konsoli
  - Backward compatible - stare API nadal działa
  - Clear migration path: `window.trafficToolkit.*`
- Event listeners (Ctrl+Shift+D dla debug panel)
- Cleanup handlers - memory leak fix

---

## ✅ QA Checklist
- Po każdej zmianie modułów odpal `node build.js`, upewnij się że `extension/content.js` ma świeży timestamp.
- Przeładuj rozszerzenie w Chrome oraz stronę CRM przed testami.
- Włącz AUTO na przykładowym formularzu i sprawdź logi (`instrument.js`) — wpisy `[skip]` oznaczają pominięcie pól o identycznej wartości.
- Zweryfikuj, że selecty wymuszające dodatkowe pola nadal reagują (nawet gdy wartości zostały rozpoznane jako identyczne).
- Przy zmianach w transformerach/schema wykonaj pełen flow tworzenia kreacji i obserwuj konsolę przeglądarki pod kątem błędów.

---

## 🚀 Development

### Edycja kodu
1. Edytuj pliki w `extension/modules/`
2. Uruchom build: `node build.js`
3. Przeładuj extension w Chrome (`chrome://extensions` → reload)
4. Przeładuj stronę CRM

### Dodawanie nowego modułu
1. Utwórz plik w `extension/modules/`
2. Dodaj go do tablicy `MODULES` w `build.js` (w odpowiedniej kolejności!)
3. Uruchom build

### Debugowanie
- Build script wyświetla statystyki (linie, rozmiar)
- Syntax check: `node -c extension/content.js`
- Debug panel w extension: Ctrl+Shift+D
- Console logs: `⚡ Traffic Toolkit PRO v8.4.1 - Inicjalizacja...`
- Deprecation warnings: `⚠️ TTK Deprecation Warning` (v8.4.1)

---

## ✅ Korzyści z modularyzacji

1. **Czytelność** - Łatwiej znaleźć konkretny kod
2. **Możliwość utrzymania** - Łatwiejsze bugfixy i nowe funkcje
3. **Separacja logiki** - Każdy moduł ma jasno określoną odpowiedzialność
4. **DRY** - Brak duplikacji kodu
5. **Testowanie** - Łatwiejsze testowanie poszczególnych modułów
6. **Onboarding** - Nowi developerzy szybciej zrozumieją strukturę

---

## 📊 Statystyki v8.5.0

- **Build:** ~5291 linii, 212.26 KB (was 5189 lines, 208.17 KB in v8.4.1)
- **Moduły:** 18 sztuk
- **Deprecated:** 3 moduły (api.js, schemas.js, utils.js - wrapper only)

**Key changes v8.5.0 (Phase 1+2 Complete):**

**Phase 1 - Quick Wins & Strategy Pattern:**
- **Task #1:** Merge obrazek.js + klikalny-obrazek.js (factory pattern, -68 lines)
- **Task #2:** Add pipe & compose to fp-utils.js (+25 lines)
- **Task #3:** CONFIG.API centralization (BASE_URL + ENDPOINTS)
- **Task #4:** Build validation (syntax check + backup/restore)
- **Task #5:** FIELD_APPLIERS strategy map (declarative field handling)
- **Task #6:** Split createUI (283 → 12 lines, -96%)

**Phase 2 - Production Hardening:**
- **Task #10:** Template ID constants (CONFIG.TEMPLATE_IDS - eliminacja magic strings)
- **Task #13:** Error boundaries (try/catch w main.js + automation.js)
- **Task #11/12:** Already done (Cache TTL v8.1.3, Immutable prune() v8.3.9)
- **PR review:** .gitignore + cleanup unused CONFIG.API endpoints

**Build stats:**
- Phase 1: +80 lines (new features - duplication elimination)
- Phase 2: +22 lines (error boundaries + template constants)
- Net: +102 lines (+2% from v8.4.1)

**Key features from v8.4.1 (carried forward):**
- **Issue #1:** Split God Module utils.js (812 lines) → 5 specialized modules
- **Issue #3:** State immutability + time-travel debugging
- **Issue #4:** Logger Registry pattern
- **Issue #8:** Deprecation warnings for 11 window globals
- JSON Diff view (partial deep grouping)
- Dev JSON button (clipboard + console.log)
- Collapsible Full JSON section
- State management jako PRIMARY source dla runAuto()

---

**Ostatnia aktualizacja:** v8.5.0 (Styczeń 2025, Phase 1+2 Complete: Quick Wins + Production Hardening)