maciejpi/nordabiz
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
7c8fd90a21
nordabiz/CLAUDE.md
Maciej Pienczyn b2f24f02bc
Some checks are pending
NordaBiz Tests / Unit & Integration Tests (push) Waiting to run
Details
NordaBiz Tests / E2E Tests (Playwright) (push) Blocked by required conditions
Details
NordaBiz Tests / Smoke Tests (Production) (push) Blocked by required conditions
Details
NordaBiz Tests / Send Failure Notification (push) Blocked by required conditions
Details
feat(messages): optimistic UI — message appears instantly on Enter 
Instead of waiting for API response before showing the message,
the editor clears and message appears in DOM immediately. The API
call happens in the background. Real message ID replaces temp ID
in state for polling dedup.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-28 17:14:07 +01:00

9.5 KiB
Raw Blame History

Norda Biznes Partner - Instrukcje dla Claude

Opis projektu

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

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ą!

# 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 reload 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 reload 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!

# ✅ 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 reload 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

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