From 50a549c3fff0733eb6a56f5c17592d475c1b7555 Mon Sep 17 00:00:00 2001 From: Maciej Pienczyn Date: Sat, 31 Jan 2026 06:40:49 +0100 Subject: [PATCH] docs: Plan refaktoryzacji - Modularny Monolit (10 faz) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Szczegółowy plan wydzielenia 235 routes do ~25 blueprintów - Kategoryzacja routes według modułów - Harmonogram 10 faz (~33h pracy) - Docelowa struktura katalogów - Zasady refaktoryzacji i procedury wdrożenia Cel: Redukcja app.py z 15,570 → ~500 linii Co-Authored-By: Claude Opus 4.5 --- docs/MODULAR_MONOLITH_PLAN.md | 462 ++++++++++++++++++++++++++++++++++ docs/REFACTORING_STATUS.md | 23 +- 2 files changed, 479 insertions(+), 6 deletions(-) create mode 100644 docs/MODULAR_MONOLITH_PLAN.md diff --git a/docs/MODULAR_MONOLITH_PLAN.md b/docs/MODULAR_MONOLITH_PLAN.md new file mode 100644 index 0000000..007ae63 --- /dev/null +++ b/docs/MODULAR_MONOLITH_PLAN.md @@ -0,0 +1,462 @@ +# Plan Refaktoryzacji: Modularny Monolit + +> **Data utworzenia:** 2026-01-31 +> **Status:** W PLANOWANIU +> **Cel:** Redukcja app.py z 15,570 → ~500 linii + +--- + +## Stan obecny + +### Metryki app.py + +| Metryka | Wartość | +|---------|---------| +| Linie kodu | 15,570 | +| Routes (@app.route) | 235 | +| Funkcje (def) | 258 | +| Funkcje pomocnicze | ~30 | + +### Rozkład routes według kategorii + +| Kategoria | Ilość routes | Linie (szac.) | Priorytet | +|-----------|--------------|---------------|-----------| +| admin/* | 85 | ~4,000 | Średni | +| api/* | 85 | ~3,500 | Średni | +| zopk/* | 32 | ~2,500 | Niski | +| public (/, /company, /search) | ~20 | ~800 | Wysoki | +| forum/* | ~15 | ~600 | Średni | +| auth (login, register) | 8 | ~500 | Wysoki | +| account (konto, settings) | 13 | ~500 | Średni | +| messages (wiadomości) | ~10 | ~400 | Średni | +| chat/* | 8 | ~400 | Niski | +| audits (seo, gbp, it, krs) | ~25 | ~2,000 | Niski | +| honeypot | 10 | ~20 | Niski | + +### Blueprinty - aktualny stan + +| Blueprint | Status | Linie | Routes | +|-----------|--------|-------|--------| +| reports | ✅ Wdrożony | 198 | 4 | +| community/contacts | ✅ Wdrożony | ~200 | 6 | +| community/classifieds | ✅ Wdrożony | ~250 | 4 | +| community/calendar | ✅ Wdrożony | ~200 | 3 | +| education | ✅ Wdrożony | 59 | 2 | +| **Razem wdrożone** | | **~900** | **19** | +| **Pozostało w app.py** | | **~14,700** | **216** | + +### Funkcje pomocnicze do wydzielenia + +```python +# utils/validators.py +validate_email(email) +validate_password(password) +sanitize_input(text, max_length) + +# utils/notifications.py +create_notification(user_id, title, message, ...) +create_news_notification(company_id, news_id, news_title) + +# utils/analytics.py +get_or_create_analytics_session() +track_conversion(event_type, company_id, ...) +track_page_view() +log_brave_api_call(user_id, feature, company_name) + +# utils/security.py +check_geoip() +set_security_headers(response) +is_admin_exempt() + +# utils/api_usage.py +get_free_tier_usage() +get_brave_api_usage() + +# utils/filters.py +ensure_url_filter(url) +``` + +--- + +## Plan fazowy + +### Faza 2: Auth + Account (NASTĘPNA) + +**Szacowany czas:** 2-3 godziny +**Redukcja app.py:** ~1,000 linii + +#### 2.1 Blueprint: auth + +| Route | Endpoint | Metody | +|-------|----------|--------| +| /register | register | GET, POST | +| /login | login | GET, POST | +| /logout | logout | GET | +| /verify-2fa | verify_2fa | GET, POST | +| /forgot-password | forgot_password | GET, POST | +| /reset-password/ | reset_password | GET, POST | +| /verify-email/ | verify_email | GET | +| /resend-verification | resend_verification | GET, POST | + +**Zależności:** +- `validate_email()`, `validate_password()` +- `send_registration_notification()` +- Flask-Login + +#### 2.2 Blueprint: account + +| Route | Endpoint | Metody | +|-------|----------|--------| +| /konto | account_index | GET, POST | +| /konto/prywatnosc | account_privacy | GET, POST | +| /konto/bezpieczenstwo | account_security | GET | +| /konto/blokady | account_blocks | GET | +| /konto/blokady/dodaj | account_blocks_add | POST | +| /konto/blokady/usun/ | account_blocks_remove | POST | +| /settings/2fa | settings_2fa | GET, POST | +| /settings/privacy | settings_privacy | GET, POST | +| /settings/blocks | settings_blocks | GET | +| /settings/blocks/add | settings_blocks_add | POST | +| /settings/blocks/remove/ | settings_blocks_remove | POST | +| /dashboard | dashboard | GET | + +--- + +### Faza 3: Public + Forum + +**Szacowany czas:** 3-4 godziny +**Redukcja app.py:** ~1,400 linii + +#### 3.1 Blueprint: public + +| Route | Endpoint | +|-------|----------| +| / | index | +| /company/ | company_detail | +| /company/ | company_detail_by_slug | +| /company//recommend | company_recommend | +| /osoba/ | person_detail | +| /search | search | +| /aktualnosci | events | +| /nowi-czlonkowie | new_members | +| /mapa-polaczen | connections_map | +| /release-notes | release_notes | + +#### 3.2 Blueprint: forum + +| Route | Endpoint | +|-------|----------| +| /forum | forum_index | +| /forum/nowy | forum_new_topic | +| /forum/ | forum_topic | +| /forum//odpowiedz | forum_reply | +| /admin/forum | admin_forum | +| /admin/forum/topic//pin | admin_forum_pin | +| /admin/forum/topic//lock | admin_forum_lock | +| /admin/forum/topic//delete | admin_forum_delete_topic | +| /admin/forum/reply//delete | admin_forum_delete_reply | +| /admin/forum/topic//status | admin_forum_change_status | + +--- + +### Faza 4: Messages + Notifications + +**Szacowany czas:** 2 godziny +**Redukcja app.py:** ~600 linii + +#### 4.1 Blueprint: messages + +| Route | Endpoint | +|-------|----------| +| /wiadomosci | messages_inbox | +| /wiadomosci/wyslane | messages_sent | +| /wiadomosci/nowa | messages_new | +| /wiadomosci/wyslij | messages_send | +| /wiadomosci/ | messages_view | +| /wiadomosci//odpowiedz | messages_reply | +| /api/messages/unread-count | api_messages_unread | + +#### 4.2 Blueprint: notifications (API) + +| Route | Endpoint | +|-------|----------| +| /api/notifications | api_notifications_list | +| /api/notifications//read | api_notifications_read | +| /api/notifications/read-all | api_notifications_read_all | +| /api/notifications/unread-count | api_notifications_unread | + +--- + +### Faza 5: Chat (NordaGPT) + +**Szacowany czas:** 2 godziny +**Redukcja app.py:** ~400 linii + +| Route | Endpoint | +|-------|----------| +| /chat | chat_index | +| /api/chat/settings | api_chat_settings | +| /api/chat/start | api_chat_start | +| /api/chat//message | api_chat_message | +| /api/chat//history | api_chat_history | +| /api/chat/conversations | api_chat_conversations | +| /api/chat//delete | api_chat_delete | +| /api/chat/feedback | api_chat_feedback | + +--- + +### Faza 6: Admin panels + +**Szacowany czas:** 6-8 godzin +**Redukcja app.py:** ~4,000 linii + +#### 6.1 admin/users (~10 routes) +#### 6.2 admin/fees (~5 routes) +#### 6.3 admin/analytics (~10 routes) +#### 6.4 admin/ai (~5 routes) +#### 6.5 admin/status (~10 routes) +#### 6.6 admin/security (~5 routes) +#### 6.7 admin/announcements (~10 routes) +#### 6.8 admin/recommendations (~5 routes) + +--- + +### Faza 7: Audits + +**Szacowany czas:** 4-5 godzin +**Redukcja app.py:** ~2,000 linii + +#### 7.1 audits/seo (~10 routes) +#### 7.2 audits/gbp (~5 routes) +#### 7.3 audits/social (~5 routes) +#### 7.4 audits/it (~10 routes) +#### 7.5 audits/krs (~5 routes) +#### 7.6 audits/digital (~2 routes) + +--- + +### Faza 8: ZOPK + +**Szacowany czas:** 4-5 godzin +**Redukcja app.py:** ~2,500 linii + +| Moduł | Routes | +|-------|--------| +| zopk/public | 4 | +| zopk/admin | 5 | +| zopk/news | 15 | +| zopk/knowledge | 20 | +| zopk/timeline | 8 | + +--- + +### Faza 9: API misc + Honeypot + +**Szacowany czas:** 2 godziny +**Redukcja app.py:** ~500 linii + +- api/validation (check-email, verify-nip, verify-krs) +- api/analytics (track, heartbeat, scroll, error, performance) +- api/recommendations +- api/companies +- api/connections +- honeypot (wp-admin, .env, etc.) + +--- + +### Faza 10: Utils extraction + +**Szacowany czas:** 2 godziny + +Wydzielenie funkcji pomocniczych: +- utils/validators.py +- utils/notifications.py +- utils/analytics.py +- utils/security.py +- utils/api_usage.py +- utils/filters.py + +--- + +## Docelowa struktura + +``` +nordabiz/ +├── app.py # ~500 linii (tylko init + config) +├── config.py # Konfiguracja środowisk +├── extensions.py # Flask extensions (csrf, limiter, login) +│ +├── blueprints/ +│ ├── __init__.py # register_blueprints() +│ │ +│ ├── auth/ # Faza 2 +│ │ ├── __init__.py +│ │ └── routes.py +│ │ +│ ├── account/ # Faza 2 +│ │ ├── __init__.py +│ │ └── routes.py +│ │ +│ ├── public/ # Faza 3 +│ │ ├── __init__.py +│ │ └── routes.py +│ │ +│ ├── forum/ # Faza 3 +│ │ ├── __init__.py +│ │ └── routes.py +│ │ +│ ├── messages/ # Faza 4 +│ │ ├── __init__.py +│ │ └── routes.py +│ │ +│ ├── chat/ # Faza 5 +│ │ ├── __init__.py +│ │ └── routes.py +│ │ +│ ├── admin/ # Faza 6 +│ │ ├── __init__.py +│ │ ├── users.py +│ │ ├── fees.py +│ │ ├── analytics.py +│ │ ├── ai.py +│ │ ├── status.py +│ │ ├── security.py +│ │ ├── announcements.py +│ │ └── recommendations.py +│ │ +│ ├── audits/ # Faza 7 +│ │ ├── __init__.py +│ │ ├── seo.py +│ │ ├── gbp.py +│ │ ├── social.py +│ │ ├── it.py +│ │ ├── krs.py +│ │ └── digital.py +│ │ +│ ├── zopk/ # Faza 8 +│ │ ├── __init__.py +│ │ ├── public.py +│ │ ├── admin.py +│ │ ├── news.py +│ │ ├── knowledge.py +│ │ └── timeline.py +│ │ +│ ├── api/ # Faza 9 +│ │ ├── __init__.py +│ │ ├── validation.py +│ │ ├── analytics.py +│ │ ├── recommendations.py +│ │ ├── companies.py +│ │ └── connections.py +│ │ +│ ├── community/ # ✅ Faza 1 (DONE) +│ │ ├── contacts/ +│ │ ├── classifieds/ +│ │ └── calendar/ +│ │ +│ ├── reports/ # ✅ Faza 1 (DONE) +│ │ +│ └── education/ # ✅ Faza 1 (DONE) +│ +├── utils/ # Faza 10 +│ ├── __init__.py +│ ├── validators.py +│ ├── notifications.py +│ ├── analytics.py +│ ├── security.py +│ ├── api_usage.py +│ ├── filters.py +│ ├── decorators.py # ✅ Istnieje +│ └── helpers.py # ✅ Istnieje +│ +└── services/ # ✅ Istnieje (14 plików) + ├── gemini_service.py + ├── search_service.py + ├── email_service.py + └── ... +``` + +--- + +## Harmonogram szacunkowy + +| Faza | Zakres | Czas | Status | +|------|--------|------|--------| +| 1 | reports, community, education | 4h | ✅ DONE | +| 2 | auth, account | 3h | 🔜 Następna | +| 3 | public, forum | 4h | ⏳ | +| 4 | messages, notifications | 2h | ⏳ | +| 5 | chat | 2h | ⏳ | +| 6 | admin (8 modułów) | 8h | ⏳ | +| 7 | audits (6 modułów) | 5h | ⏳ | +| 8 | zopk (5 modułów) | 5h | ⏳ | +| 9 | api misc, honeypot | 2h | ⏳ | +| 10 | utils extraction | 2h | ⏳ | +| **RAZEM** | | **~37h** | | + +--- + +## Zasady refaktoryzacji + +### 1. url_for w blueprintach + +```python +# Wewnątrz blueprintu - z kropką +url_for('.endpoint') + +# W szablonach - pełna nazwa +url_for('blueprint.endpoint') +``` + +### 2. Testowanie po każdej fazie + +```bash +# Lokalnie +python3 app.py +curl http://localhost:5000/health + +# Testy manualne każdego route +``` + +### 3. Procedura wdrożenia + +```bash +# 1. Commit lokalny +git add . && git commit -m "refactor(phase-X): ..." + +# 2. Test lokalny + +# 3. Push +git push origin master && git push inpi master + +# 4. Deploy +ssh maciejpi@10.22.68.249 "cd /var/www/nordabiznes && sudo -u www-data git pull && sudo systemctl restart nordabiznes" + +# 5. Weryfikacja produkcji +curl https://nordabiznes.pl/health +``` + +### 4. Rollback + +```bash +git revert HEAD +git push origin master && git push inpi master +ssh maciejpi@10.22.68.249 "cd /var/www/nordabiznes && sudo -u www-data git pull && sudo systemctl restart nordabiznes" +``` + +--- + +## Metryki sukcesu + +| Metryka | Przed | Po | Cel | +|---------|-------|-----|-----| +| Linie app.py | 15,570 | ~500 | -97% | +| Routes w app.py | 235 | ~5 | -98% | +| Funkcje w app.py | 258 | ~10 | -96% | +| Blueprinty | 5 | ~25 | +400% | +| Czas uruchomienia | ? | bez zmian | = | +| Funkcjonalność | 100% | 100% | = | + +--- + +**Ostatnia aktualizacja:** 2026-01-31 diff --git a/docs/REFACTORING_STATUS.md b/docs/REFACTORING_STATUS.md index 569eb3e..102f113 100644 --- a/docs/REFACTORING_STATUS.md +++ b/docs/REFACTORING_STATUS.md @@ -48,13 +48,24 @@ nordabiz/ ## Harmonogram -### Plan dalszych prac +**Szczegółowy plan:** [`docs/MODULAR_MONOLITH_PLAN.md`](MODULAR_MONOLITH_PLAN.md) -| Faza | Zakres | Status | -|------|--------|--------| -| **Faza 1** | reports, contacts, classifieds, calendar | ✅ WDROŻONA | -| **Faza 2** | public + auth (~25 routes) | 🔜 Do zrobienia | -| **Fazy 3-7** | API, chat, admin, audits, ZOPK | 🔜 Do zrobienia | +### Podsumowanie faz + +| Faza | Zakres | Routes | Status | +|------|--------|--------|--------| +| **1** | reports, community, education | 19 | ✅ WDROŻONA | +| **2** | auth, account | ~20 | 🔜 Następna | +| **3** | public, forum | ~25 | ⏳ | +| **4** | messages, notifications | ~10 | ⏳ | +| **5** | chat | ~8 | ⏳ | +| **6** | admin (8 modułów) | ~60 | ⏳ | +| **7** | audits (6 modułów) | ~35 | ⏳ | +| **8** | zopk (5 modułów) | ~32 | ⏳ | +| **9** | api misc, honeypot | ~25 | ⏳ | +| **10** | utils extraction | - | ⏳ | + +**Cel:** Redukcja app.py z 15,570 → ~500 linii ---