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
    └── 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

⚠️ 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)

Production

• Serwer: NORDABIZ-01 (VM 249, IP 10.22.68.249)
• Baza: PostgreSQL na 10.22.68.249:5432
• Reverse Proxy: NPM na R11-REVPROXY-01 (VM 119, IP 10.22.68.250)
• Domena: nordabiznes.pl (DNS w OVH)
• SSL: Let's Encrypt (auto-renewal)

NPM Proxy Configuration (KRYTYCZNE!)

Proxy Host ID: 27 Forward Port: 5000 (NIE 80!)

PRAWIDŁOWA KONFIGURACJA:
NPM (10.22.68.250) → Backend (10.22.68.249:5000) ✓

BŁĘDNA KONFIGURACJA (powoduje pętlę przekierowań):
NPM (10.22.68.250) → Backend (10.22.68.249:80) ✗

UWAGA: Na serwerze 10.22.68.249 działa nginx na porcie 80 który przekierowuje na HTTPS. Flask/Gunicorn działa na porcie 5000. Przy edycji proxy hosta ZAWSZE sprawdź czy port = 5000!

Weryfikacja po zmianach NPM:

curl -I https://nordabiznes.pl/health
# Oczekiwany: HTTP 200

Raport incydentu: docs/INCIDENT_REPORT_20260102.md

Git & Deployment

Repozytoria Git

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

Konta: GitHub: pienczyn, Gitea: maciejpi

Workflow Deployment

┌─────────┐   git push    ┌─────────┐   git pull    ┌─────────┐
│   DEV   │ ────────────► │  Gitea  │ ◄──────────── │  PROD   │
│  (Mac)  │               │ (INPI)  │               │         │
└─────────┘               └─────────┘               └─────────┘
     │
     └──── git push ────► GitHub (backup)

Procedura wdrażania (WAŻNE!)

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

# 2. PROD: Pull zmiany
ssh maciejpi@10.22.68.249 "cd /var/www/nordabiznes && sudo -u www-data git pull"

# 3. PROD: Uruchom migracje SQL (jeśli są)
ssh maciejpi@10.22.68.249 "cd /var/www/nordabiznes && /var/www/nordabiznes/venv/bin/python3 scripts/run_migration.py database/migrations/XXX_nazwa.sql"

# 4. PROD: Restart serwisu
ssh maciejpi@10.22.68.249 "sudo systemctl restart nordabiznes"

# 5. Weryfikacja
curl -sI https://nordabiznes.pl/health | head -3

⚠️ UWAGI KRYTYCZNE:

1. Migracje SQL - NIE używaj psql bezpośrednio. Użyj scripts/run_migration.py

2. Uprawnienia logów - Jeśli błąd Permission denied: /var/log/nordabiznes/*:

   ssh maciejpi@10.22.68.249 "sudo chown -R maciejpi:maciejpi /var/log/nordabiznes/"
   

3. 502 po restarcie - Poczekaj 3-5 sekund i sprawdź ponownie

4. Git pull - Używaj sudo -u www-data git pull (www-data ma klucze SSH)

Uruchamianie skryptów na produkcji (KRYTYCZNE!):

• SSH timeout NIE oznacza że komenda nie została wykonana!
• ZAWSZE sprawdź czy poprzedni proces nie działa: ps aux | grep <skrypt>
• Dla długich operacji używaj nohup lub screen
• Incydent: docs/INCIDENT_REPORT_20260115.md

Uruchamianie skryptów Python z dostępem do bazy (WAŻNE!):

Skrypty Python wymagające dostępu do bazy danych MUSZĄ mieć ustawiony DATABASE_URL. Plik .env NIE jest automatycznie wczytywany przez source .env - to nie działa w kontekście SSH!

# ✅ PRAWIDŁOWO - ustaw DATABASE_URL bezpośrednio:
ssh maciejpi@10.22.68.249 "cd /var/www/nordabiznes && \
  DATABASE_URL='postgresql://nordabiz_app:HASŁO@127.0.0.1:5432/nordabiz' \
  /var/www/nordabiznes/venv/bin/python3 skrypt.py"

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

# ❌ BŁĘDNIE - source .env nie działa przez SSH:
ssh maciejpi@10.22.68.249 "source .env && python3 skrypt.py"

Hasło do bazy (produkcja): W pliku /var/www/nordabiznes/.env (DATABASE_URL)

Auto Claude - Rozwiązywanie problemów

Pliki stanu (NIE COMMITOWAĆ!)

• .auto-claude-security.json, .auto-claude-status, .auto-claude/
• Są w .gitignore + pre-commit hook automatycznie je usuwa ze staging

Konflikty merge z Auto Claude

# 1. Sprawdź konflikt
git status

# 2. Usuń pliki Auto Claude z merge
git rm .auto-claude-security.json .auto-claude-status

# 3. Dokończ merge
git commit -m "Merge branch 'feature' - resolve Auto Claude file conflicts"

Worktrees

git worktree list                                              # Lista aktywnych
git worktree remove .auto-claude/worktrees/tasks/<task-id>     # Usuń nieaktualny
git branch -d auto-claude/<task-id>                            # Usuń branch

Konwencje danych

Identyfikatory firm

• 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 firm

IT, Construction, Services, Production, Trade, Other

Poziomy jakości danych

basic, enhanced, complete

Ważne zasady

Bezpieczeństwo

• 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)
• Rate limiting: 200 req/dzień, 50 req/godzinę

Panel bezpieczeństwa: /admin/security

• 2FA, CSRF, HTTPS, GeoIP Blocking, Rate Limiting, Account Lockout, Audit Log

Zarządzanie credentials (KRYTYCZNE!)

NIGDY nie umieszczaj haseł w kodzie źródłowym!

# ✅ PRAWIDŁOWO:
DATABASE_URL = os.getenv('DATABASE_URL')

# ❌ BŁĘDNIE:
DATABASE_URL = 'postgresql://user:password123@localhost/db'

• Wszystkie sekrety w .env (nigdy w .py, .sh, .js)
• Fallback jako placeholder: CHANGE_ME (nie prawdziwe hasło!)

Pełne zasady: docs/CREDENTIALS.md

Deployment

• Przed wdrożeniem: python -m py_compile app.py
• SSH do NORDABIZ-01: ssh maciejpi@10.22.68.249 (ZAWSZE jako maciejpi!)
• Ścieżka aplikacji: /var/www/nordabiznes
• Restart: sudo systemctl restart nordabiznes
• ZAWSZE aktualizuj historię zmian (release_notes w app.py)

Szablony Jinja2 - WAŻNE!

• Blok {% block extra_js %} w base.html jest już wewnątrz <script>
• NIE DODAWAJ własnych tagów <script> w extra_js!
• Prawidłowo: {% block extra_js %}function foo() {...}{% endblock %}

Uprawnienia PostgreSQL

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

Testowanie na produkcji

Konta testowe (PROD):

Konto	Email	Hasło	Rola
Test User	test@nordabiznes.pl	&Rc2LdbSw&jiGR0ek@Bz	Użytkownik
Test Admin	testadmin@nordabiznes.pl	cSfQbbwegwv1v3Q2Dm0Q	Admin

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

SearchService

Unified search dla chatbota i /search. Szczegóły: docs/DEVELOPMENT.md#searchservice

Chatbot AI

• Limit firm: 8
• Historia: 10 wiadomości

Szczegóły: docs/DEVELOPMENT.md#chatbot-ai

Powiązane zasoby

• Źródło danych: https://norda-biznes.info/czlonkowie
• Backup: Proxmox Backup Server (VM snapshots)
• DNS wewnętrzny: nordabiznes.inpi.local

Szablon profilu firmy

Docelowa struktura (po optymalizacji)

1. Header (nazwa, kategoria, badge, krótki opis)
2. Pasek kontaktowy (www, email, telefon, lokalizacja)
3. O firmie (połączone opisy)
4. Usługi i kompetencje (połączone tagi)
5. Wyróżniki (połączone z wartościami)
6. Dane kontaktowe (pełne karty)
7. Informacje prawne i biznesowe
8. Social Media (wszystkie 6 platform)
9. Strona WWW (analiza techniczna)

Szablon: templates/company_detail.html

News Monitoring

System monitoringu wzmianek o firmach w mediach. Panel: /admin/news

Statusy: pending, approved, rejected

Szczegóły: docs/DEVELOPMENT.md#news-monitoring

ZOP Kaszubia News (ZOPK)

System monitoringu newsów projektu Zielony Okręg Przemysłowy Kaszubia. Panel: /admin/zopk/news

Tematy istotne

• Zielony Okręg Przemysłowy Kaszubia
• Elektrownia jądrowa (Lubiatowo-Kopalino)
• Offshore wind Bałtyk (Baltic Power, Baltica)
• Via Pomerania, Droga Czerwona
• Kongsberg (inwestycje w Rumi)
• Izba Przedsiębiorców NORDA

Tematy do odrzucenia

• Turystyka na Kaszubach
• Polityka ogólnopolska
• Inne regiony Polski
• Wypadki, clickbait

Reguły auto-approve (WAŻNE!)

Próg: score >= 3

Score	Status
1-2	pending
3-5	auto_approved

Plik: zopk_news_service.py (linie 890, 1124, 1145)

Social Media

Panel audytu: /admin/social-media Platformy: Facebook, Instagram, LinkedIn, YouTube, TikTok, Twitter

Szczegóły: docs/DEVELOPMENT.md#social-media

Audyt SEO

Panel: /admin/seo API: Google PageSpeed Insights

Szczegóły: docs/DEVELOPMENT.md#audyt-seo

Dodatkowe rejestry (TODO - przyszłe integracje)

Rejestr	Opis	API
CRBR	Centralny Rejestr Beneficjentów Rzeczywistych	https://crbr.podatki.gov.pl
SUDOP	System Udostępniania Danych o Pomocy Publicznej	https://sudop.uokik.gov.pl

Rejestry te mogą dostarczyć dodatkowe dane o firmach (beneficjenci rzeczywiści, otrzymana pomoc publiczna).

Plan rozwoju

Roadmap, priorytety i strategia monetyzacji: docs/ROADMAP.md

NordaGPT - Konfiguracja AI

Aktualny model (stan: 2026-01-29)

• Model: gemini-3-flash-preview (Gemini 3 Flash Preview)
• SDK: google-genai>=1.0.0 (nowy SDK z thinking mode)
• Inicjalizacja: app.py:286 - gemini_service.init_gemini_service(model='3-flash')
• Silnik chatu: nordabiz_chat.py używa globalnego gemini_service

Thinking Mode (NOWE!)

Użytkownicy mogą wybierać poziom rozumowania AI w UI chatu (dropdown obok badge "Gemini 3").

Poziom	Opis	Zastosowanie
Błyskawiczny (minimal)	Najszybsze odpowiedzi	Proste pytania: "kto?", "gdzie?"
Szybki (low)	Zrównoważony	Większość pytań o firmy i usługi
Głęboki (high)	Maksymalna analiza	Złożone pytania, rekomendacje, strategia

Zmiana poziomu:

• UI: Dropdown w headerze chatu
• API: POST /api/chat/settings z {"thinking_level": "high"}
• Zapisywane w sesji użytkownika

Dostępne modele w gemini_service.py

Alias	Model ID	Opis
flash	gemini-2.5-flash	Ogólnego przeznaczenia
flash-lite	gemini-2.5-flash-lite	Ultra tani ($0.10/$0.40 per 1M)
pro	gemini-2.5-pro	Najlepszy reasoning
flash-2.0	gemini-2.0-flash	Poprzednia generacja (wycofywany 31.03.2026)
3-flash	gemini-3-flash-preview	AKTUALNY - 7x lepszy reasoning, thinking mode
3-pro	gemini-3-pro-preview	Premium - 2M context

Zmiana modelu

# W app.py linia ~286:
gemini_service.init_gemini_service(model='3-flash')  # Zmień alias tutaj

UI Badge

W templates/chat.html badge w headerze: <span class="chat-header-badge">Gemini 3</span>

Prezentacja dla członków Izby (AKTYWNY PROJEKT)

Cel projektu

Stworzenie materiałów wideo prezentujących portal NordaBiz dla członków Izby NORDA.

Produkty końcowe

1. Podcast NotebookLM (2-3 min) - rozmowa AI o portalu
2. Zajawka Remotion (30s) - scenariusz "Problem → Rozwiązanie"
3. Tutorial wideo (2-3 min) - nagrania portalu + dialogi Zofia/Marek
4. Integracja z portalem - Akademia + widget na dashboardzie

Dokument źródłowy dla NotebookLM

docs/notebooklm-source.md - markdown do wgrania do notebooklm.google.com

Scenariusz zajawki 30s (Remotion)

[0-8s]  "Szukasz partnera do projektu?"
[8-16s] "Nie wiesz, kto w Izbie ma potrzebne kompetencje?"
[16-24s] "NordaGPT zna 150 firm i pomoże Ci znaleźć"
[24-30s] "nordabiznes.pl - Twoja sieć kontaktów"

Głosy edge-tts

• Marek: pl-PL-MarekNeural (męski)
• Zofia: pl-PL-ZofiaNeural (żeński)

GIFy do nagrania (Chrome MCP)

1. Strona główna zalogowanego
2. Katalog firm + filtrowanie
3. Profil firmy
4. Chat NordaGPT - pytanie
5. Chat NordaGPT - odpowiedź
6. Forum
7. Kalendarz
8. Tablica B2B

Pliki Remotion

• Lokalizacja: /Users/maciejpi/claude/projects/active/remotion/my-video/
• Komponenty: NordaBizZajawka.tsx, NordaBizTutorial.tsx
• Audio: public/audio/, public/voice/tutorial/
• Nagrania: public/recordings/*.gif

Konto testowe (PROD)

• Email: test@nordabiznes.pl
• Hasło: &Rc2LdbSw&jiGR0ek@Bz

Data projektu: 2026-01-29