nordabiz/docs/REFACTORING_STATUS.md

# Status Refaktoringu app.py

> **Ostatnia aktualizacja:** 2026-02-09
> **Autor sesji:** Claude Opus 4.5 (fazy 1-6.1), Claude Opus 4.6 (weryfikacja końcowa)

## Stan obecny

### Faza 1 - ✅ WDROŻONA NA PRODUKCJĘ

**Commit:** `66856a6`
**Data wdrożenia:** 2026-01-28

| Blueprint | URL Prefix | Routes | Status |
|-----------|------------|--------|--------|
| reports | `/raporty` | 4 | ✅ Przetestowane |
| contacts | `/kontakty` | 6 | ✅ Przetestowane |
| classifieds | `/tablica` | 4 | ✅ Przetestowane |
| calendar | `/kalendarz` | 3 | ✅ Przetestowane |
| education | `/edukacja` | 2 | ✅ Przetestowane |

---

### Faza 2a - ✅ WDROŻONA NA PRODUKCJĘ

**Data wdrożenia:** 2026-01-31
**Strategia:** Alias Bridge (bezpieczna migracja)
**Commity:** `d5adf02` (blueprinty), `cdd050a` (cleanup), `0ccb109` (docs)

| Blueprint | Routes | Status |
|-----------|--------|--------|
| auth | 20 | ✅ Gotowy, aliasy aktywne |
| public | 11 | ✅ Gotowy, aliasy aktywne |

**Pliki utworzone:**
- `blueprints/auth/__init__.py`
- `blueprints/auth/routes.py` (1,040 linii)
- `blueprints/public/__init__.py`
- `blueprints/public/routes.py` (862 linii)

**Redukcja app.py:**
- Przed: 15,577 linii
- Po: 13,820 linii
- **Usunięto: 1,757 linii (11.3%)**

**Testy (DEV):**
- ✅ Wszystkie endpointy działają
- ✅ Aliasy: `url_for('login')` = `url_for('auth.login')`
- ✅ Istniejące blueprinty działają

---

## Metodologia Refaktoringu (Alias Bridge)

### Dlaczego ta metoda?

Problem: 125+ wywołań `url_for()` w szablonach i kodzie używa starych nazw (`url_for('login')`).
Rozwiązanie: Aliasy pozwalają na stopniową migrację bez "Big Bang".

### Procedura dla każdej fazy

#### Krok 1: Utworzenie blueprintu

```bash
mkdir -p blueprints/<nazwa>
touch blueprints/<nazwa>/__init__.py
touch blueprints/<nazwa>/routes.py
```

```python
# blueprints/<nazwa>/__init__.py
from flask import Blueprint
bp = Blueprint('<nazwa>', __name__)
from . import routes
```

#### Krok 2: Przeniesienie tras

1. Skopiuj funkcje z app.py do `blueprints/<nazwa>/routes.py`
2. Zmień `@app.route` na `@bp.route`
3. Zaktualizuj importy (używaj `from extensions import limiter`)
4. Wewnętrzne url_for: użyj `.endpoint` (z kropką)

#### Krok 3: Rejestracja + aliasy

```python
# blueprints/__init__.py
from blueprints.<nazwa> import bp as <nazwa>_bp
app.register_blueprint(<nazwa>_bp)

_create_endpoint_aliases(app, <nazwa>_bp, {
    'stara_nazwa': '<nazwa>.nowa_nazwa',
    # ...
})
```

#### Krok 4: Dezaktywacja duplikatów w app.py

```python
# PRZED:
@app.route('/endpoint')
def funkcja():

# PO:
# @app.route('/endpoint')  # MOVED TO <nazwa>.<endpoint>
def _old_funkcja():
```

#### Krok 5: Test

```bash
python3 -c "from app import app; print('OK')"
# Test wszystkich endpointów
```

#### Krok 6: Cleanup (po weryfikacji na PROD)

Usuń funkcje z prefiksem `_old_` z app.py.

---

## Harmonogram

**Szczegółowy plan:** [`docs/MODULAR_MONOLITH_PLAN.md`](MODULAR_MONOLITH_PLAN.md)

### Podsumowanie faz

| Faza | Zakres | Routes | Status |
|------|--------|--------|--------|
| **1** | reports, community, education | 19 | ✅ WDROŻONA |
| **2a** | auth + public + cleanup | 31 | ✅ WDROŻONA |
| **3** | forum (10 routes) | 10 | ✅ WDROŻONA |
| **4** | messages + notifications (11 routes) | 11 | ✅ WDROŻONA |
| **5** | chat (9 routes) | 9 | ✅ WDROŻONA |
| **6.1** | admin Part 1 (recommendations, users, fees, calendar) | 19 | ✅ WDROŻONA |
| **6.2** | admin Part 2 (seo, analytics, ai-usage, status, etc.) | ~41 | ✅ WDROŻONA |
| **7** | audits (6 modułów) | ~35 | ✅ WDROŻONA |
| **8** | zopk (5 modułów) | ~32 | ✅ WDROŻONA |
| **9** | api misc, honeypot | ~25 | ✅ WDROŻONA |
| **10** | final cleanup | - | ✅ WDROŻONA |

**Status końcowy (2026-02-09):** app.py zredukowane z 15,570 → 1,557 linii (-90%). 17 blueprintów, 49 plików z routami.

---

## Metryki optymalizacji

### Po Fazie 1 (2026-01-28)
- app.py: 15,570 → 13,699 linii (-12%)

### Po Fazie 2a (2026-01-31)
- app.py: 15,577 → 13,820 linii
- **Usunięto: 1,757 linii (11.3%)**
- Nowe pliki:
  - `blueprints/auth/routes.py` (1,040 linii)
  - `blueprints/public/routes.py` (862 linii)

### Po Fazie 3 - Forum (2026-01-31)
- app.py: 13,820 → 13,398 linii
- **Usunięto: 422 linie (3.1%)**
- Nowe pliki:
  - `blueprints/forum/__init__.py`
  - `blueprints/forum/routes.py` (450 linii)

### Po Fazie 6.1 - Admin Part 1 (2026-01-31)
- app.py: 12,600 → 11,774 linii (**-826 linii**)
- **Nowe pliki:**
  - `blueprints/admin/__init__.py` (12 linii)
  - `blueprints/admin/routes.py` (828 linii)
- **Trasy przeniesione:** 19 (recommendations: 3, users: 8, fees: 5, calendar: 3)
- **UWAGA:** Trasy AI-parse pozostają w app.py

### Łączna redukcja app.py
- Start: 15,570 linii
- Po Fazie 1: 13,699 linii (-12.0%)
- Po Fazie 2a: 13,820 linii (-11.2% od startu)
- Po Fazie 3: 13,398 linii (-13.9% od startu)
- Po Fazie 4: 13,058 linii (-16.1% od startu)
- Po Fazie 5: 12,600 linii (-19.1% od startu)
- Po Fazie 6.1: 11,774 linii (**-24.4% od startu**)
- **Stan końcowy (2026-02-09): 1,557 linii (-90.0% od startu)**
- 17 blueprintów, 49 plików z routami
- **Refaktoring UKOŃCZONY**

---

## Weryfikacja przed wdrożeniem

### Checklist DEV

```bash
# 1. Import aplikacji
python3 -c "from app import app; print('OK')"

# 2. Test endpointów
python3 -c "
from app import app
with app.test_client() as c:
    assert c.get('/').status_code == 200
    assert c.get('/login').status_code == 200
    assert c.get('/health').status_code == 200
print('All endpoints OK')
"

# 3. Test url_for (aliasy)
python3 -c "
from app import app
from flask import url_for
with app.test_request_context():
    assert url_for('login') == '/login'
    assert url_for('auth.login') == '/login'
    assert url_for('index') == '/'
    assert url_for('public.index') == '/'
print('Aliases OK')
"
```

### Checklist PROD

```bash
# Po wdrożeniu
curl -sI https://nordabiznes.pl/health | head -1
curl -sI https://nordabiznes.pl/ | head -1
curl -sI https://nordabiznes.pl/login | head -1
curl -sI https://nordabiznes.pl/release-notes | head -1
```

---

## Metodologia Bezpiecznego Wdrażania (OBOWIĄZKOWA)

> **INCYDENT 2026-01-31:** Awaria produkcji spowodowana niedziałającymi aliasami.
> Szablony używały `url_for('admin_seo')` ale alias nie został utworzony.

### Zasady PRZED przeniesieniem trasy do blueprintu

1. **NAJPIERW zaktualizuj szablony** - zmień `url_for('stara_nazwa')` na `url_for('blueprint.endpoint')`
2. **Wdróż zmianę szablonów** - przetestuj na produkcji
3. **DOPIERO POTEM** przenieś trasę do blueprintu

### Zasada: Pełne nazwy blueprintów (NIE aliasy)

```python
# ❌ BŁĘDNIE - aliasy są zawodne
url_for('admin_seo')

# ✅ PRAWIDŁOWO - pełna nazwa blueprintu
url_for('admin.admin_seo')
```

**Dlaczego:** Aliasy mogą nie działać dla tras w oddzielnych plikach. Pełne nazwy są jawne i niezawodne.

### Checklist PRZED każdym deploy

```bash
# 1. Test importu
python3 -c "from app import app; print('OK')"

# 2. Test renderowania strony głównej (NIE tylko status!)
curl -s https://localhost:5000/ | head -50

# 3. Test url_for dla przeniesionych endpointów
python3 -c "
from app import app
from flask import url_for
with app.test_request_context():
    print(url_for('admin.admin_seo'))  # Musi działać
"

# 4. Dopiero po pozytywnych testach - deploy na PROD
```

### Procedura przenoszenia trasy (NOWA)

1. **Audit szablonów** - znajdź wszystkie `url_for('nazwa_trasy')` w templates/
2. **Zaktualizuj szablony** - zmień na `url_for('blueprint.nazwa_trasy')`
3. **Wdróż szablony** - commit, push, deploy, test PROD
4. **Utwórz trasę w blueprincie** - skopiuj kod do blueprints/
5. **Skomentuj trasę w app.py** - prefix `_old_`
6. **Test lokalny** - import + renderowanie stron
7. **Deploy** - commit, push, deploy
8. **Test PROD** - sprawdź czy strony się renderują
9. **Cleanup** - usuń martwy kod z app.py

---

## Lekcje na przyszłość

1. **url_for w szablonach:**
   - **ZAWSZE używaj pełnych nazw:** `url_for('blueprint.endpoint')`
   - **NIE polegaj na aliasach** - są zawodne
   - Wewnątrz blueprintu: `url_for('.endpoint')` (z kropką)

2. **Kolejność operacji:**
   - **NAJPIERW szablony** - zaktualizuj url_for
   - Potem blueprinty
   - Cleanup dopiero po teście PROD

3. **Bezpieczeństwo:**
   - Zawsze testuj renderowanie stron, nie tylko status HTTP
   - Prefix `_old_` dla zdezaktywowanych funkcji
   - Rollback: odkomentuj `@app.route`

---

## Kontakt

W razie problemów z wdrożeniem sprawdź:
- Logi: `/var/log/nordabiznes/`
- Health check: `curl https://nordabiznes.pl/health`
- Rollback: `git revert HEAD && git push`