# 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 - **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) ### NPM Proxy Configuration (KRYTYCZNE!) **Proxy Host ID:** 27 | **Forward Port:** 5000 (NIE 80!) ``` NPM (10.22.68.250) → Backend (10.22.68.249:5000) ✓ NPM (10.22.68.250) → Backend (10.22.68.249:80) ✗ (pętla przekierowań!) ``` Na serwerze .249 nginx na porcie 80 przekierowuje na HTTPS. Flask/Gunicorn na porcie 5000. **ZAWSZE** sprawdź port po edycji NPM! **Weryfikacja:** `curl -I https://nordabiznes.pl/health` | **Incydent:** `docs/INCIDENT_REPORT_20260102.md` ## 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ą!** ```bash # 1. DEV: Push do obu repozytoriów git push origin master && git push inpi master # 2. STAGING: Wdrożenie i test ssh maciejpi@10.22.68.248 "cd /var/www/nordabiznes && sudo -u www-data git pull && sudo systemctl restart nordabiznes" # ⚠️ OBOWIĄZKOWO: Test manualny nowej funkcjonalności na staging! # 3. PROD: Pull zmiany (DOPIERO PO WERYFIKACJI STAGING!) ssh maciejpi@10.22.68.249 "cd /var/www/nordabiznes && sudo -u www-data git pull" # 4. PROD: 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" # 5. PROD: Restart + weryfikacja ssh maciejpi@10.22.68.249 "sudo systemctl restart nordabiznes" 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** - `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) 5. **SSH timeout** - NIE oznacza że komenda nie została wykonana! Sprawdź `ps aux | grep ` **Skrypty Python z dostępem do bazy (WAŻNE!):** `.env` NIE jest wczytywany przez `source .env` w kontekście SSH! ```bash # ✅ PRAWIDŁOWO: 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: ssh maciejpi@10.22.68.249 "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: `ssh maciejpi@10.22.68.249` (ZAWSZE jako maciejpi!) - Ścieżka: `/var/www/nordabiznes` | Restart: `sudo systemctl restart nordabiznes` - **ZAWSZE** aktualizuj `release_notes` w app.py ### Szablony Jinja2 - WAŻNE! - `{% block extra_js %}` w `base.html` jest **wewnątrz** `