nordabiz/CLAUDE.md

Norda Biznes Partner - Instrukcje dla Claude

Opis projektu

Platforma katalogowa i networkingowa dla członków stowarzyszenia Norda Biznes z Wejherowa.

• Produkcja: https://nordabiznes.pl
• Status: LIVE (od 2025-11-23)
• Firmy: 150 podmiotów gospodarczych (cel)

Struktura projektu

nordabiz/
├── app.py                 # Główna aplikacja Flask (routes, auth, API)
├── database.py            # Modele SQLAlchemy (Company, User, Chat)
├── gemini_service.py      # Integracja Google Gemini AI
├── nordabiz_chat.py       # Silnik chatu AI z kontekstem firm
├── search_service.py      # Unified SearchService (synonimy, FTS, fuzzy)
├── templates/             # Szablony Jinja2
├── static/                # CSS, JS, obrazy
├── database/              # Schematy SQL, migracje
├── data/                  # Dane źródłowe JSON
├── tests/                 # Testy jakości AI
├── scripts/               # Narzędzia Python/Node.js
└── docs/                  # Dokumentacja
    ├── architecture/      # Architektura systemu (C4, flows)
    ├── DEVELOPMENT.md     # Szczegóły deweloperskie
    ├── ROADMAP.md         # Plan rozwoju, monetyzacja
    ├── CREDENTIALS.md     # Zasady zarządzania credentials
    ├── CLAUDE-REFERENCE.md # Szczegóły operacyjne (DR, ZOPK, Remotion, cron)
    └── INCIDENT_REPORT_*.md

Dokumentacja

Dokument	Zawartość
docs/architecture/	Architektura C4, schematy bazy, API, flows
docs/DEVELOPMENT.md	SearchService, Chatbot, Testy AI, SEO, News
docs/ROADMAP.md	Plan rozwoju, priorytety, monetyzacja
docs/CREDENTIALS.md	Zarządzanie hasłami i kluczami API
docs/CLAUDE-REFERENCE.md	Szczegóły operacyjne przeniesione z CLAUDE.md

⚠️ WAŻNE: Przed zmianami w NPM/proxy przeczytaj docs/architecture/08-critical-configurations.md

Technologie

Warstwa	Technologia
Backend	Flask 3.0, SQLAlchemy 2.0, Python 3.9+
Frontend	HTML5, CSS3, Vanilla JS, Jinja2
Baza danych	PostgreSQL (prod i dev via Docker)
AI	Google Gemini 3 Flash (free tier)
Security	Flask-Login, Flask-WTF (CSRF), Flask-Limiter

Środowiska

Development (lokalne)

• Baza: PostgreSQL via Docker (localhost:5433/nordabiz)
• Port: 5000 lub 5001
• Uruchomienie: python3 app.py
• Docker DB: docker compose up -d (jeśli nie działa)

Staging

• Serwer: NORDABIZ-STAGING-01 (VM 248, IP 10.22.68.248)
• Baza: PostgreSQL nordabiz_staging na 10.22.68.248:5432
• Domena: staging.nordabiznes.pl (NPM Proxy Host ID: 44)
• Weryfikacja: curl -I https://staging.nordabiznes.pl/health

Production (OVH VPS)

• Serwer: inpi-vps-waw01 (OVH VPS, IP 57.128.200.27)
• Baza: PostgreSQL na 57.128.200.27:5432
• SSL/Proxy: nginx na VPS (bezpośrednio, bez NPM)
• Domena: nordabiznes.pl (DNS w OVH, SSL Let's Encrypt)
• SSH: ssh maciejpi@57.128.200.27 (ZAWSZE jako maciejpi!)
• Ścieżka: /var/www/nordabiznes | Restart: sudo systemctl restart nordabiznes
• Weryfikacja: curl -I https://nordabiznes.pl/health

⚠️ Różnice OVH VPS vs stary on-prem:

• Brak .git repo na VPS — deploy przez rsync, NIE git pull
• .env jest root-owned — skrypty wymagają sudo do odczytu
• Migracje wymagają sudo -u postgres psql (app user nie ma ALTER TABLE)

NPM Proxy Configuration (tylko staging)

NPM dotyczy teraz tylko staging (Proxy Host ID: 44 dla staging.nordabiznes.pl). Produkcja nie korzysta z NPM — SSL obsługuje nginx bezpośrednio na OVH VPS.

Git & Deployment

Repozytoria Git

Remote	URL	Cel
origin (GitHub)	git@github.com:pienczyn/nordabiz.git	Cloud backup, CI/CD
inpi (Gitea)	git@10.22.68.180:maciejpi/nordabiz.git	Wewnętrzny, deploy source

Procedura wdrażania (WAŻNE!)

ZAWSZE testuj na staging przed produkcją!

# 1. DEV: Push do obu repozytoriów
git push origin master && git push inpi master

# 2. STAGING: Wdrożenie i test (on-prem, bez zmian)
ssh maciejpi@10.22.68.248 "cd /var/www/nordabiznes && sudo -u www-data git pull && sudo systemctl reload nordabiznes"
# ⚠️ OBOWIĄZKOWO: Test manualny nowej funkcjonalności na staging!

# 3. PROD (OVH VPS): Pull zmiany (DOPIERO PO WERYFIKACJI STAGING!)
ssh maciejpi@57.128.200.27 "cd /var/www/nordabiznes && sudo git pull"

# 4. PROD: Migracje SQL (jeśli są)
ssh maciejpi@57.128.200.27 "sudo -u postgres psql nordabiz -f /var/www/nordabiznes/database/migrations/XXX_nazwa.sql"

# 5. PROD: Restart + weryfikacja
ssh maciejpi@57.128.200.27 "sudo systemctl restart nordabiznes"
curl -sI https://nordabiznes.pl/health | head -3

⚠️ UWAGI KRYTYCZNE:

1. Git pull z sudo - sudo git pull (pliki owned by root, SSH key maciejpi, remote: GitHub)
2. Migracje SQL - Używaj sudo -u postgres psql (app user nie ma ALTER TABLE)
3. .env jest root-owned - Skrypty wymagają sudo do odczytu
4. 502 po restarcie - Poczekaj 3-5 sekund i sprawdź ponownie
5. SSH timeout - NIE oznacza że komenda nie została wykonana! Sprawdź ps aux | grep <skrypt>
6. Staging nadal on-prem - Git pull na .248 działa jak wcześniej (www-data ma klucze SSH)

Skrypty Python z dostępem do bazy (WAŻNE!):

.env na OVH VPS jest root-owned — wymaga sudo do odczytu!

# ✅ PRAWIDŁOWO:
ssh maciejpi@57.128.200.27 "cd /var/www/nordabiznes && \
  sudo DATABASE_URL=\$(sudo grep DATABASE_URL .env | cut -d'=' -f2) \
  /var/www/nordabiznes/venv/bin/python3 skrypt.py"

# ❌ BŁĘDNIE:
ssh maciejpi@57.128.200.27 "source .env && python3 skrypt.py"

Konwencje danych

• Slug: kebab-case, np. pixlab-sp-z-o-o
• NIP: 10 cyfr bez myślników | REGON: 9 lub 14 cyfr | KRS: 10 cyfr (tylko spółki)
• Kategorie: IT, Construction, Services, Production, Trade, Other
• Jakość danych: basic, enhanced, complete

Ważne zasady

Bezpieczeństwo & Credentials

• NIE edytuj bezpośrednio bazy produkcyjnej PostgreSQL
• Testuj zmiany na DEV (Docker: localhost:5433) przed wdrożeniem
• Klucze API i hasła tylko w .env (nigdy w kodzie!) — docs/CREDENTIALS.md
• Rate limiting: 200 req/dzień, 50 req/godzinę
• Panel bezpieczeństwa: /admin/security

Deployment

• Przed wdrożeniem: python -m py_compile app.py
• SSH prod: ssh maciejpi@57.128.200.27 (OVH VPS, ZAWSZE jako maciejpi!)
• SSH staging: ssh maciejpi@10.22.68.248 (on-prem VM 248)
• Ścieżka: /var/www/nordabiznes | Restart prod: sudo systemctl restart nordabiznes
• Deploy prod: rsync (brak .git na VPS) | Deploy staging: git pull
• ZAWSZE aktualizuj release_notes w app.py

Szablony Jinja2 - WAŻNE!

• {% block extra_js %} w base.html jest wewnątrz <script> — NIE DODAWAJ własnych tagów <script>!

Uprawnienia PostgreSQL

• Po utworzeniu tabel: GRANT ALL ON TABLE ... TO nordabiz_app
• Po utworzeniu sekwencji: GRANT USAGE, SELECT ON SEQUENCE ... TO nordabiz_app

Infrastruktura testowa

pytest tests/ -v                          # Wszystkie testy
pytest tests/unit/ -v                     # Unit testy (bez bazy)
pytest tests/integration/ -v              # Integration testy (z bazą)
pytest tests/ --cov=. --cov-report=html   # Testy z coverage

CI/CD: .github/workflows/test.yml (unit → e2e na staging → smoke na prod)

Konta testowe (PROD): Brak (usunięte 2026-02-04)

API Endpoints (podstawowe)

Endpoint	Opis
/	Katalog firm
/company/<slug>	Profil firmy
/search	Wyszukiwanie
/chat	Chat AI
/health	Health check
/admin/*	Panele admina

Pełna lista: docs/architecture/10-api-endpoints.md

Moduły (szczegóły w docs/)

• SearchService: Unified search dla chatbota i /search — docs/DEVELOPMENT.md#searchservice
• Chatbot AI: Limit 8 firm, 10 wiadomości historii — docs/DEVELOPMENT.md#chatbot-ai
• News Monitoring: Panel /admin/news, statusy: pending/approved/rejected
• ZOPK News: Panel /admin/zopk/news, auto-approve score >= 3 — szczegóły w docs/CLAUDE-REFERENCE.md
• Social Media: Panel /admin/social-media (FB, IG, LinkedIn, YT, TikTok, Twitter)
• Audyt SEO: Panel /admin/seo, API Google PageSpeed Insights
• Website Updater: Cron miesięczny, scripts/website_content_updater.py — szczegóły w docs/CLAUDE-REFERENCE.md

NordaGPT - Konfiguracja AI

• Model: gemini-3-flash-preview (alias 3-flash) — thinking mode, 7x lepszy reasoning
• SDK: google-genai>=1.0.0
• Inicjalizacja: app.py:286 — gemini_service.init_gemini_service(model='3-flash')
• Zmiana modelu: Edytuj alias w app.py:286. Katalog modeli: docs/CLAUDE-REFERENCE.md

Status projektu (2026-02-09)

Refaktoring app.py — ✅ UKOŃCZONY

• Wynik: 15,570 → 1,557 linii (-90%), 17 blueprintów, 49 plików z routami
• Plany: docs/REFACTORING_STATUS.md, docs/MODULAR_MONOLITH_PLAN.md

Audit Completeness — ✅ UKOŃCZONY (~95%)

• Plan: docs/AUDIT_COMPLETENESS_PLAN.md — 5 faz, $0, 52%→95%
• Google OAuth: ✅ Skonfigurowany i działa na produkcji (GBP + Search Console)
• Meta OAuth: Brakuje META_APP_ID/SECRET w .env (framework gotowy, wymaga Facebook App review)
• Migracje: 058-062 (oauth_tokens, SEO columns, FID→INP, Places API, maps_links)

ZOPK Knowledge Base — ✅ UKOŃCZONY (5/5 priorytetów)

• Panel admina (/admin/zopk/knowledge), timeline (/admin/zopk/timeline), deduplikacja encji, graf relacji, linki do źródeł w odpowiedziach
• Plan: docs/PLAN_ZOPK_KNOWLEDGE_BASE_IMPROVEMENTS.md

Powiązane zasoby

• Źródło danych: https://norda-biznes.info/czlonkowie
• Backup: Proxmox Backup Server — szczegóły DR: docs/DR-PLAYBOOK.md i docs/CLAUDE-REFERENCE.md
• DNS wewnętrzny: nordabiznes.inpi.local
• Prezentacja Izby: Remotion wideo — szczegóły w docs/CLAUDE-REFERENCE.md
• Plan rozwoju: docs/ROADMAP.md