nordabiz/scripts/README.md

# Norda Biznes - Scripts

Automatyczne skrypty do zbierania i przetwarzania danych o firmach członkowskich.

---

## 📁 Pliki

### `company-data-collector.js`

**Główny agent** zbierający dane o firmach z różnych źródeł.

**Funkcje:**
- 🔍 Wyszukiwanie firm w ALEO.com (NIP, REGON, KRS)
- 🌐 Znajdowanie stron WWW przez Google
- 📊 Ekstrakcja danych ze stron firmowych
- 💾 Automatyczny zapis do `data/companies-full.json`
- 📝 Generowanie logów i raportów

---

## 🚀 Użycie

### Podstawowe uruchomienie

```bash
node scripts/company-data-collector.js
```

Przetworzy wszystkie 80 firm z `data/companies-basic.json`.

### Z limitowaniem

```bash
# Przetw

órz tylko 5 pierwszych firm (test)
node scripts/company-data-collector.js --limit 5

# Przetwórz 10 firm
node scripts/company-data-collector.js --limit 10
```

### Pomijanie już przetworzonych

```bash
# Przetwórz tylko firmy, których nie ma w companies-full.json
node scripts/company-data-collector.js --skip-processed

# Kombinacja: pomiń przetworzone, limit 20
node scripts/company-data-collector.js --skip-processed --limit 20
```

### Pomoc

```bash
node scripts/company-data-collector.js --help
```

---

## 📊 Output

### Pliki wyjściowe:

1. **`data/companies-full.json`**
   - Pełne dane wszystkich przetworzonych firm
   - Aktualizowany po każdej firmie
   - Format JSON z metadanymi

2. **`data/collection-log.md`**
   - Szczegółowy log przetwarzania
   - Dla każdej firmy: timestamp, kroki, błędy
   - Markdown format

3. **Konsola**
   - Real-time progress
   - Raport końcowy ze statystykami

### Przykładowy output konsoli:

```
🤖 Norda Biznes - Company Data Collector Agent
================================================

📊 Załadowano 80 firm do zbadania

[1/80] Przetwarzanie: PIXLAB
────────────────────────────────────────────────────────────
📡 KROK 1: Wyszukiwanie w ALEO.com...
   ✅ Znaleziono dane urzędowe
🔍 KROK 2: Szukanie strony WWW...
   ✅ Znaleziono stronę: https://pixlab.pl
🌐 KROK 3: Pobieranie danych ze strony...
   ✅ Pobrano dane ze strony
✅ Pełne dane zebrane

[2/80] Przetwarzanie: KORNIX
...

============================================================
📊 RAPORT KOŃCOWY
============================================================

Przetworzono:    80/80 firm
Pełne dane:      56 (70%)
Częściowe dane:  20 (25%)
Niepowodzenia:   4 (5%)

Czas działania:  16.5 minut
Średnio na firmę: 0.21 min

============================================================
```

---

## ⚙️ Konfiguracja

### W pliku `company-data-collector.js`:

```javascript
const CONFIG = {
  delayBetweenRequests: 2000,  // 2 sekundy między firmami
  maxRetries: 3,               // Maksymalna liczba ponownych prób
  timeout: 30000              // Timeout 30 sekund
};
```

### Źródła danych:

Agent próbuje pobrać dane z:
1. **ALEO.com** - dane urzędowe (NIP, REGON, KRS)
2. **Google Search** - URL strony WWW
3. **Strony firmowe** - kontakt, usługi, kompetencje

---

## 🔧 Wymagania

### Node.js packages:

```bash
# Podstawowe (built-in):
- fs
- path

# Opcjonalne (dla pełnej funkcjonalności):
npm install puppeteer  # Web scraping
# lub
npm install playwright # Web scraping (zalecane)
# lub
npm install cheerio axios # Prosty scraping HTML
```

### API Keys (opcjonalne):

- **Google Custom Search API** - dla automatycznego znajdowania stron WWW
  - Instrukcje: https://developers.google.com/custom-search/v1/overview

---

## 📝 Status Implementacji

### ✅ Zaimplementowane:

- [x] Struktura agenta
- [x] CLI interface (argumenty, pomoc)
- [x] Wczytywanie danych z companies-basic.json
- [x] Zapis do companies-full.json
- [x] Generowanie logów
- [x] Raportowanie postępu
- [x] Ocena jakości danych
- [x] Statystyki i raporty

### 🔄 Do zaimplementowania:

- [ ] **Rzeczywiste wyszukiwanie w ALEO.com**
  - Wymaga: puppeteer/playwright
  - Metoda: `searchAleo(companyName)`

- [ ] **Rzeczywiste wyszukiwanie w Google**
  - Wymaga: Google Custom Search API
  - Metoda: `findWebsite(companyName)`

- [ ] **Rzeczywisty web scraping**
  - Wymaga: puppeteer/cheerio
  - Metoda: `scrapeWebsite(url)`

- [ ] **Automatyczna aktualizacja data-sources.md**
  - Metoda: `updateDataSources()`

---

## 🎯 Roadmap

### Faza 1: Ręczne zbieranie danych (OBECNA)
- ✅ Struktura agenta gotowa
- ✅ Pliki JSON i MD przygotowane
- 🔄 Ręczne wypełnianie danych (copy-paste z researchu)

### Faza 2: Semi-automatyczne zbieranie
- Implementacja scrapingu ALEO.com
- Znajdowanie stron WWW przez Google API
- Podstawowy scraping stron (kontakt)

### Faza 3: Pełna automatyzacja
- AI-assisted data extraction
- Automatyczna walidacja danych
- Scheduled updates (cron)
- Email notifications

---

## 🐛 Troubleshooting

### Agent się nie uruchamia

```bash
# Sprawdź czy Node.js jest zainstalowany:
node --version  # Powinno pokazać v14+ lub nowsze

# Sprawdź uprawnienia:
chmod +x scripts/company-data-collector.js

# Uruchom z verbose:
node scripts/company-data-collector.js --limit 1
```

### Brak danych w companies-full.json

```bash
# Sprawdź czy plik companies-basic.json istnieje:
ls -la data/companies-basic.json

# Sprawdź format JSON:
cat data/companies-basic.json | python -m json.tool
```

### "Cannot find module"

```bash
# Zainstaluj zależności:
npm install

# Lub jeśli używasz yarn:
yarn install
```

---

## 📚 Dokumentacja

### Struktura danych firmy:

Patrz: `data/companies-full.json` - przykłady z pełnymi danymi

### Log format:

Patrz: `data/collection-log.md` - przykład po uruchomieniu agenta

### Źródła danych:

Patrz: `data/data-sources.md` - lista wszystkich źródeł

---

## 👨‍💻 Development

### Testowanie:

```bash
# Test na 1 firmie:
node scripts/company-data-collector.js --limit 1

# Test na 5 firmach:
node scripts/company-data-collector.js --limit 5

# Dry run (bez zapisu):
# TODO: Dodać flagę --dry-run
```

### Debugowanie:

Odkomentuj linie z `console.log` w metodach:
- `searchAleo()`
- `findWebsite()`
- `scrapeWebsite()`

---

## 📞 Support

Pytania lub problemy? Kontakt:
- Email: biuro@norda-biznes.info
- Issue: Utwórz issue w repo

---

**Wersja:** 1.0
**Ostatnia aktualizacja:** 2025-11-23
**Autor:** Norda Biznes Partner Development Team