# 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ą!** ```bash # 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 ` 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! ```bash # ✅ 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** `