Maciej Pienczyn
edcba4b178
Some checks are pending
NordaBiz Tests / Unit & Integration Tests (push) Waiting to run
NordaBiz Tests / E2E Tests (Playwright) (push) Blocked by required conditions
NordaBiz Tests / Smoke Tests (Production) (push) Blocked by required conditions
NordaBiz Tests / Send Failure Notification (push) Blocked by required conditions
Mark all phases (0-4) as complete (~95% completeness). Add Phase 0b (GBP dashboard quick wins: review link, directions, open status badge, NAP comparison). Add DB migrations table. Update CLAUDE.md to reflect current status. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
228 lines
9.1 KiB
Markdown
228 lines
9.1 KiB
Markdown
# 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 <skrypt>`
|
|
|
|
**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** `<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
|
|
|
|
```bash
|
|
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`
|
|
|
|
## Audit Completeness Plan (2026-02-08)
|
|
|
|
- **Plan:** `docs/AUDIT_COMPLETENESS_PLAN.md` — pełny plan ulepszeń (5 faz, $0, 52%→95%)
|
|
- **Status:** Fazy 0-4 UKOŃCZONE. Kompletność: ~95%
|
|
- **Pozostaje:** OAuth credentials w .env (F3: GBP Business Profile, Facebook/Instagram, Search Console)
|
|
- **Migracje:** 058-062 (oauth_tokens, SEO columns, FID→INP, Places API, maps_links)
|
|
|
|
## 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`
|