update

2026-04-09 11:44:45 +02:00
parent 7ff7ff3a92
commit 61c66bfd55
79 changed files with 13667 additions and 144 deletions
--- a/.paul/phases/01-statlink-autolinking/01-01-PLAN.md
+++ b/.paul/phases/01-statlink-autolinking/01-01-PLAN.md
@@ -0,0 +1,249 @@
+---
+phase: 01-statlink-autolinking
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - migrations/013_statlink_tracking.sql
+  - src/Services/StatLinkService.php
+  - src/Controllers/SettingsController.php
+  - templates/settings/index.php
+  - .env
+autonomous: true
+delegation: off
+---
+
+<objective>
+## Goal
+Zbudować mechanizm automatycznego dodawania opublikowanych artykułów do StatLink.pl oraz ich automatycznego usuwania po 60 dniach.
+
+## Purpose
+Każdy opublikowany artykuł na stronach zapleczowych powinien automatycznie otrzymywać linkowanie w systemie StatLink.pl na okres 60 dni, co zwiększy efektywność pozycjonowania. Po 60 dniach link jest automatycznie usuwany, aby nie marnować punktów.
+
+## Output
+- `StatLinkService.php` — serwis PHP z logowaniem do StatLink via Guzzle (cookies), dodawaniem i usuwaniem linków
+- Migracja SQL do śledzenia linków w StatLink (statlink_id, article_id, added_at, expires_at)
+- Endpoint cron do automatycznego uruchamiania (dodaj nowe / usuń wygasłe)
+</objective>
+
+<context>
+## Project Context
+@.paul/PROJECT.md
+@.paul/ROADMAP.md
+@.paul/STATE.md
+
+## Source Files
+@src/Services/PublisherService.php
+@src/Models/Article.php
+@src/Controllers/SettingsController.php
+@.env
+
+## StatLink.pl Research (from browser exploration)
+- Login: POST to https://statlink.pl/ with fields: email (textbox), haslo (textbox), submit ZALOGUJ
+- Session: cookie-based (PHP session)
+- Add link: POST to /148,twoje-linki#lista with fields:
+  - niepozwol: CSRF token (must be scraped from page)
+  - https: 1 (radio, 0=http, 1=https)
+  - link: URL without protocol (e.g. "example.com/article-slug")
+  - anchor: anchor text (article title or topic keyword)
+  - fraza_kluczowa1, fraza_kluczowa2, fraza_kluczowa3: (empty)
+  - wylacznosc: unchecked
+  - frazowy: unchecked
+  - tylko_https: unchecked
+  - min_ilosc_znakow: 0
+  - statrank_min: 0, statrank_max: 10
+  - semstorm_keywords_top_min: 0
+  - ilosc_dziennie: 0.14 (= 1 link co 2 dni)
+  - ilosc_max: 10
+  - ilosc_nofollow: 0
+  - max_ilosc_domena: (default 5)
+  - id_kategorie_multiple[]: all category values selected
+  - zapisz: DODAJ
+- Delete link: POST to /148,twoje-linki#lista0 with fields:
+  - statlink_id: ID of the link
+  - usun: Usuń
+- Category checkboxes: multiple id_kategorie_multiple[] values (all selected)
+- NOWY LINK form is inside div#nowy_link2vis
+- Each link row has Edytuj and Usuń buttons with statlink_id hidden field
+</context>
+
+<acceptance_criteria>
+
+## AC-1: Login do StatLink
+```gherkin
+Given dane logowania w .env (statlink_url, statlink_login, statlink_password)
+When StatLinkService wykonuje login via Guzzle z CookieJar
+Then sesja jest utrzymana i kolejne requesty zwracają stronę zalogowanego użytkownika
+```
+
+## AC-2: Dodawanie linku do StatLink
+```gherkin
+Given opublikowany artykuł z wp_post_url i tytułem
+When StatLinkService::addLink() jest wywołane
+Then link zostaje dodany w StatLink.pl z prawidłowymi parametrami (anchor=tytuł/keyword, ilosc_dziennie=0.14, ilosc_max=10, wszystkie kategorie)
+And statlink_id zostaje zapisany w tabeli statlink_links
+```
+
+## AC-3: Usuwanie wygasłych linków
+```gherkin
+Given link w tabeli statlink_links z expires_at < NOW()
+When StatLinkService::removeExpiredLinks() jest wywołane
+Then link zostaje usunięty ze StatLink.pl via POST z usun
+And rekord w tabeli statlink_links zostaje oznaczony jako removed
+```
+
+## AC-4: Cron endpoint
+```gherkin
+Given endpoint /cron/statlink z tokenem autoryzacyjnym
+When endpoint jest wywołany
+Then nowe opublikowane artykuły (bez wpisu w statlink_links) dostają linki w StatLink
+And wygasłe linki (expires_at < NOW()) są usuwane ze StatLink
+```
+
+## AC-5: Tracking w bazie danych
+```gherkin
+Given tabela statlink_links
+When artykuł dostaje link w StatLink
+Then zapisywany jest: article_id, site_id, statlink_id, anchor, added_at, expires_at (added_at + 60 dni), status
+```
+
+</acceptance_criteria>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Migracja SQL + Model śledzenia StatLink</name>
+  <files>migrations/013_statlink_tracking.sql</files>
+  <action>
+    Utworzyć migrację tworzącą tabelę statlink_links:
+    - id INT AUTO_INCREMENT PRIMARY KEY
+    - article_id INT NOT NULL (FK do articles)
+    - site_id INT NOT NULL (FK do sites)
+    - statlink_id INT NULL (ID linku w systemie StatLink — parsowany z odpowiedzi)
+    - anchor VARCHAR(500) NOT NULL
+    - link_url VARCHAR(500) NOT NULL
+    - added_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
+    - expires_at DATETIME NOT NULL (added_at + 60 dni)
+    - removed_at DATETIME NULL
+    - status ENUM('active', 'expired', 'removed', 'failed') DEFAULT 'active'
+    - error_message TEXT NULL
+    - created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+
+    Indeksy: (article_id), (status, expires_at), (site_id)
+  </action>
+  <verify>SQL jest poprawny składniowo, tabela zawiera wszystkie kolumny</verify>
+  <done>AC-5 satisfied: tabela statlink_links gotowa do śledzenia linków</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: StatLinkService — login, dodawanie, usuwanie linków</name>
+  <files>src/Services/StatLinkService.php</files>
+  <action>
+    Utworzyć StatLinkService z metodami:
+
+    1. **login()** — POST do statlink.pl z email+haslo, utrzymuj CookieJar w Guzzle
+       - Sprawdź odpowiedź czy zawiera "Zalogowano"
+       - Rzuć wyjątek jeśli login się nie powiedzie
+
+    2. **addLink(array $article, string $anchor)** — dodaje link do StatLink:
+       - Najpierw GET /148,twoje-linki aby pobrać token CSRF (pole "niepozwol" — regex z HTML)
+       - POST do /148,twoje-linki#lista z parametrami:
+         - niepozwol: token z GET
+         - https: 1 (jeśli URL artykułu jest HTTPS) lub 0
+         - link: URL artykułu bez protokołu (np. "domena.pl/slug")
+         - anchor: tytuł artykułu lub keyword tematu (naprzemiennie)
+         - fraza_kluczowa1/2/3: puste
+         - ilosc_dziennie: 0.14
+         - ilosc_max: 10
+         - ilosc_nofollow: 0
+         - statrank_min: 0, statrank_max: 10
+         - id_kategorie_multiple[]: wszystkie kategorie (pobrać listę z HTML)
+         - zapisz: DODAJ
+       - Parsuj statlink_id z odpowiedzi (szukaj nowego ID w tabeli linków)
+       - Return statlink_id lub null
+
+    3. **removeLink(int $statlinkId)** — usuwa link ze StatLink:
+       - POST do /148,twoje-linki#lista0 z statlink_id + usun=Usuń
+       - Sprawdź czy usunięcie się powiodło
+
+    4. **getExistingLinkIds()** — parsuje listę linków z /148,twoje-linki
+       - Zwraca tablicę statlink_id dla weryfikacji
+
+    5. **scrapeCategories()** — parsuje checkboxy kategorii z formularza
+       - Zwraca tablicę wartości id_kategorie_multiple[] do zaznaczenia
+
+    6. **processNewArticles()** — główna metoda:
+       - Pobierz opublikowane artykuły bez wpisu w statlink_links
+       - Zaloguj się do StatLink
+       - Dla każdego artykułu: addLink() + zapisz do statlink_links z expires_at = NOW + 60 dni
+       - Anchor naprzemiennie: tytuł artykułu / keyword tematu
+
+    7. **removeExpiredLinks()** — główna metoda usuwania:
+       - Pobierz linki z status='active' AND expires_at < NOW()
+       - Zaloguj się do StatLink
+       - Dla każdego: removeLink() + ustaw status='removed', removed_at=NOW()
+
+    Użyj GuzzleHttp\Client z CookieJar.
+    Loguj operacje przez Logger (kanał 'statlink').
+    Odporność: try-catch per link, nie przerywaj całego batch przy błędzie jednego.
+    Avoid: nie wysyłaj więcej niż 5 linków w jednym uruchomieniu crona (rate limiting).
+  </action>
+  <verify>Klasa kompiluje się bez błędów, metody mają prawidłowe sygnatury</verify>
+  <done>AC-1, AC-2, AC-3 satisfied: serwis loguje się, dodaje i usuwa linki</done>
+</task>
+
+<task type="auto">
+  <name>Task 3: Cron endpoint + integracja z routerem</name>
+  <files>src/Controllers/SettingsController.php, src/Core/Router.php</files>
+  <action>
+    Dodać endpoint /cron/statlink w routerze (wzorowany na istniejących cron endpointach):
+    - Walidacja tokenu (SEO_TRIGGER_TOKEN lub nowy STATLINK_TRIGGER_TOKEN)
+    - Wywołanie StatLinkService::processNewArticles() — dodaj nowe
+    - Wywołanie StatLinkService::removeExpiredLinks() — usuń wygasłe
+    - Zwróć JSON z podsumowaniem (added: N, removed: N, errors: N)
+
+    Sprawdź jak działają istniejące cron endpointy w projekcie i zastosuj ten sam wzorzec.
+  </action>
+  <verify>Endpoint /cron/statlink odpowiada JSON-em z podsumowaniem</verify>
+  <done>AC-4 satisfied: cron endpoint do automatycznego zarządzania linkami StatLink</done>
+</task>
+
+</tasks>
+
+<boundaries>
+
+## DO NOT CHANGE
+- src/Services/PublisherService.php (nie modyfikuj flow publikacji)
+- src/Models/Article.php (nie zmieniaj istniejących metod)
+- migrations/001-012 (istniejące migracje niemodyfikowalne)
+- src/Services/InternalLinkService.php (osobny mechanizm linkowania)
+
+## SCOPE LIMITS
+- Ten plan NIE integruje StatLink z procesem publikacji (to osobny cron)
+- Nie dodajemy UI do zarządzania StatLink w panelu backPRO (może w przyszłości)
+- Nie modyfikujemy istniejących endpointów cron
+
+</boundaries>
+
+<verification>
+Before declaring plan complete:
+- [ ] Migracja 013 tworzy tabelę statlink_links
+- [ ] StatLinkService loguje się do statlink.pl (test ręczny)
+- [ ] StatLinkService dodaje link (test ręczny z jednym artykułem)
+- [ ] StatLinkService usuwa link (test ręczny)
+- [ ] Endpoint /cron/statlink zwraca JSON
+- [ ] Logger zapisuje operacje na kanale 'statlink'
+- [ ] Nie więcej niż 5 linków dodanych per uruchomienie crona
+</verification>
+
+<success_criteria>
+- Wszystkie taski wykonane
+- StatLinkService działa end-to-end (login → add → track → remove po 60 dniach)
+- Endpoint cron działa z tokenem
+- Brak błędów w istniejącej funkcjonalności
+</success_criteria>
+
+<output>
+After completion, create `.paul/phases/01-statlink-autolinking/01-01-SUMMARY.md`
+</output>
--- a/.paul/phases/01-statlink-autolinking/01-01-SUMMARY.md
+++ b/.paul/phases/01-statlink-autolinking/01-01-SUMMARY.md
@@ -0,0 +1,164 @@
+---
+phase: 01-statlink-autolinking
+plan: 01
+subsystem: seo
+tags: [statlink, guzzle, scraping, cron, seo-linkbuilding]
+
+requires:
+  - phase: none
+    provides: published articles with wp_post_url
+
+provides:
+  - StatLink.pl auto-linking service
+  - Cron endpoint for link management
+  - Link lifecycle tracking (add → expire → remove)
+
+affects: [admin-panel, monitoring]
+
+tech-stack:
+  added: [guzzle-cookiejar, html-scraping]
+  patterns: [service-class-per-integration, cron-token-auth, diagnostic-logging]
+
+key-files:
+  created:
+    - src/Services/StatLinkService.php
+    - src/Controllers/StatLinkController.php
+    - cron/statlink.php
+    - migrations/013_statlink_tracking.sql
+  modified:
+    - config/routes.php
+    - src/Core/Controller.php
+
+key-decisions:
+  - "Cookie-based Guzzle session for StatLink (no API available)"
+  - "Anchor sanitization: Polish diacritics → ASCII (StatLink restriction)"
+  - "MAX_LINKS_PER_RUN=1 to avoid rate limiting"
+  - "ilosc_dziennie=0.02, link lifetime 60 days"
+  - "json_encode with JSON_INVALID_UTF8_SUBSTITUTE for scraped HTML safety"
+
+patterns-established:
+  - "Diagnostic array pattern for debugging external service integrations"
+  - "FTP deploy requires OPcache reset for changes to take effect"
+
+duration: ~4h (initial build) + 2h (bugfix session 2026-04-09)
+started: 2026-04-08
+completed: 2026-04-09T11:15:00Z
+---
+
+# Phase 1 Plan 01: StatLink Auto-Linking Summary
+
+**Automated StatLink.pl link management: login, add links for published articles, track lifecycle, remove after 60 days**
+
+## Performance
+
+| Metric | Value |
+|--------|-------|
+| Duration | ~6h total (build + bugfix) |
+| Started | 2026-04-08 |
+| Completed | 2026-04-09 |
+| Tasks | 3 completed |
+| Files created | 4 |
+| Files modified | 2 |
+
+## Acceptance Criteria Results
+
+| Criterion | Status | Notes |
+|-----------|--------|-------|
+| AC-1: Login do StatLink | Pass | Guzzle CookieJar, GET homepage + POST login, verified on production |
+| AC-2: Dodawanie linku | Pass | Form POST with CSRF, anchor sanitization, ID extraction from response |
+| AC-3: Usuwanie wygasłych | Pass | POST with statlink_id + usun, status tracking |
+| AC-4: Cron endpoint | Pass | /statlink/token-run with SEO_TRIGGER_TOKEN, also cron/statlink.php |
+| AC-5: Tracking w bazie | Pass | statlink_links table with full lifecycle tracking |
+
+## Accomplishments
+
+- StatLink service logs in, adds links, removes expired links end-to-end
+- Robust diagnostic logging — every step tracked, errors surfaced in JSON response
+- Retry mechanism for failed links with error tracking in database
+- Token-secured HTTP endpoint + standalone cron script
+
+## Files Created/Modified
+
+| File | Change | Purpose |
+|------|--------|---------|
+| `src/Services/StatLinkService.php` | Created | Core service: login, addLink, removeLink, processNewArticles, retryFailedLinks, removeExpiredLinks |
+| `src/Controllers/StatLinkController.php` | Created | HTTP endpoints: index (admin view), runByToken (cron trigger) |
+| `cron/statlink.php` | Created | Standalone cron script with lock file |
+| `migrations/013_statlink_tracking.sql` | Created | statlink_links table schema |
+| `config/routes.php` | Modified | Added /statlink routes |
+| `src/Core/Controller.php` | Modified | json_encode with JSON_INVALID_UTF8_SUBSTITUTE |
+
+## Decisions Made
+
+| Decision | Rationale | Impact |
+|----------|-----------|--------|
+| ASCII-only anchors (transliteration) | StatLink rejects Polish diacritics in anchor field | All anchors auto-sanitized ą→a, ś→s etc. |
+| MAX_LINKS_PER_RUN=1 | Avoid StatLink rate limiting | 1 link per cron run, predictable load |
+| Timeout 120s per request | StatLink is slow | connect_timeout=60s, timeout=120s |
+| set_time_limit(300) | PHP default 30s insufficient | Both controller and cron script |
+| JSON_INVALID_UTF8_SUBSTITUTE | Scraped StatLink HTML contains broken UTF-8 | Prevents empty JSON responses |
+| findLinkIdInHtml before search | Response HTML already contains new link | Reduces requests, more reliable ID detection |
+
+## Deviations from Plan
+
+### Summary
+
+| Type | Count | Impact |
+|------|-------|--------|
+| Auto-fixed | 3 | Critical — without these fixes, no links were being added |
+| Scope additions | 1 | Retry mechanism (not in original plan) |
+| Deferred | 1 | No max retry limit |
+
+### Auto-fixed Issues
+
+**1. Anchor encoding — StatLink rejects Polish characters**
+- **Found during:** Production testing
+- **Issue:** StatLink form validation requires ASCII-only anchors (alphanumeric + `.,+-_?!&\:=` + space)
+- **Fix:** Added `sanitizeAnchor()` with Polish→ASCII transliteration map
+- **Files:** `src/Services/StatLinkService.php`
+- **Verification:** Links now added successfully with sanitized anchors
+
+**2. Empty JSON responses from scraped HTML**
+- **Found during:** Production debugging
+- **Issue:** `json_encode()` returns `false` (output: nothing) when data contains invalid UTF-8 from StatLink HTML
+- **Fix:** Added `JSON_INVALID_UTF8_SUBSTITUTE | JSON_UNESCAPED_UNICODE` flags
+- **Files:** `src/Core/Controller.php`
+- **Verification:** All endpoints return valid JSON
+
+**3. StatLink ID not detected after successful add**
+- **Found during:** Production testing
+- **Issue:** `findLinkIdBySearch` made separate request, URL matching was too narrow (no protocol variants, small region)
+- **Fix:** New `findLinkIdInHtml()` extracts ID directly from form response HTML with wider region and URL variants
+- **Files:** `src/Services/StatLinkService.php`
+- **Verification:** `statlink_id=2673465` correctly detected
+
+### Deferred Items
+
+- No max retry count for permanently failing links (could block queue)
+- StatLink cron not integrated into main publish cron — needs separate cron job setup on server
+
+## Issues Encountered
+
+| Issue | Resolution |
+|-------|------------|
+| OPcache serving stale files after FTP upload | Manual opcache_reset() via test script; documented in patterns |
+| PHP max_execution_time killing script | Added set_time_limit(300) in controller and cron |
+| Login diagnostics missing on failure | Added loginDiagnostic in all error paths (empty credentials, exceptions) |
+
+## Next Phase Readiness
+
+**Ready:**
+- StatLink service fully operational, links being added and tracked
+- 37 failed links queued for retry (will auto-process via cron)
+- Admin panel view exists at /statlink
+
+**Concerns:**
+- No max retry limit — a permanently failing link blocks the queue
+- Cron not yet configured on server (only manual token URL trigger)
+
+**Blockers:**
+- None
+
+---
+*Phase: 01-statlink-autolinking, Plan: 01*
+*Completed: 2026-04-09*