3df.pl — Private AI Business Database

Prywatna platforma biznesowa do zarządzania klientami, zleceniami, umowami i numerami seryjnymi wydruków 3D z integracją AI i Google Workspace.

---

Funkcjonalności

📊 Core Business

• Zarządzanie klientami — pełna baza z NIP, adresem, historią
• Zlecenia — tracking statusu, deadlines, ceny
• Numery seryjne — format DATA-KLIENT-NR + metadane (materiał, kolor, czas druku)
• Umowy — monitoring wygasających kontraktów, alerty
• Przychody — analiza, wykresy, raporty

🤖 AI Integration

• OpenAI GPT-4 — analiza biznesowa
• Anthropic Claude — przetwarzanie dokumentów
• Google Gemini — szybkie zapytania (darmowy)
• Automatyczny routing modeli, kontekst z bazy danych

📅 Google Workspace

• Calendar — synchronizacja 3 kont Google, timeline
• Drive — upload plików, automatyczna struktura folderów
• Google Docs — notatki z auto-sync

🔐 Auth & Security

• Google OAuth — whitelist 3 emaili
• JWT tokens — sesje użytkowników
• API Keys — dostęp dla Codex (v1 endpoints)
• Security headers, rate limiting

📈 Analytics & Monitoring

• Dashboard — wykresy Recharts (przychody, zlecenia, top klienci)
• Notifications — real-time WebSocket + toast alerts
• Audit logs — tracking wszystkich operacji

🎨 UI/UX

• Dark mode — 3 palety (3df neon blue, Gruvbox, Tokyo Night)
• Responsive — Tailwind CSS
• Komponenty — DataTable, Modal, Toast, Badge, Card
• Calendar view — FullCalendar.js

---

Tech Stack

Backend

• FastAPI 0.111.0 — Python async framework
• SQLAlchemy 2.0 + Alembic — ORM + migrations
• PostgreSQL — relacyjna baza danych
• Uvicorn — ASGI server

Frontend

• React 18.3 + Vite 5.2
• React Router 6.23 — routing
• Recharts 2.12 — wykresy
• FullCalendar 6.1 — kalendarz
• Tailwind CSS 3.4 — styling

Infrastructure

• Docker + Docker Compose — konteneryzacja
• Nginx — reverse proxy, SSL
• Let's Encrypt — darmowy SSL

---

Szybki start

🚀 Opcja 1: Native (bez Docker) — ZALECANE

Najszybszy sposób na uruchomienie aplikacji lokalnie:

# 1. Zainstaluj wymagania (jeśli nie masz)
# Arch Linux:
sudo pacman -S python python-pip nodejs npm postgresql

# Debian/Ubuntu:
sudo apt install python3 python3-pip python3-venv nodejs npm postgresql

# 2. Konfiguracja
cp .env.example .env
nano .env  # Wypełnij DATABASE_URL (postgresql://...) i inne opcjonalnie

# 3. Przygotuj bazę danych
sudo systemctl start postgresql
sudo -u postgres psql -c "CREATE USER 3dfuser WITH PASSWORD 'dev123';"
sudo -u postgres psql -c "CREATE DATABASE 3dfdb OWNER 3dfuser;"

# 4. Uruchom (auto-instaluje dependencies i migracje)
./scripts/start.sh

# 5. Otwórz w przeglądarce
# Frontend: http://localhost:5173
# API Docs: http://localhost:8000/docs

# 6. Stop
./scripts/stop.sh

Produkcja (instalacja system-wide + systemd):

./scripts/install.sh  # Instaluje do /opt/3df + nginx + systemd

📖 Pełna dokumentacja: docs/NATIVE_SETUP.md

---

🐳 Opcja 2: Docker (opcjonalnie)

Jeśli preferujesz Docker:

# 1. Konfiguracja
cp .env.example .env
nano .env

# 2. Uruchom
make dev
# LUB (jeśli masz docker-compose v1)
docker-compose -f docker-compose.dev.yml up --build

# 3. Migracje
make migrate

# 4. Frontend (osobny terminal)
cd frontend && npm install && npm run dev

# 5. Otwórz
# API: http://localhost:8000/docs
# Frontend: http://localhost:5173

📖 Pełna dokumentacja: docs/DOCKER.md

---

📚 Szczegółowe instrukcje

• docs/NATIVE_SETUP.md — Uruchamianie bez Docker (2 opcje: local dev + system-wide)
• docs/DOCKER.md — Docker development + production
• docs/INSTALL_DEBIAN.md — Instalacja na Debian/Ubuntu (manual)
• docs/INSTALL_ARCHLINUX.md — Instalacja na Arch Linux (manual)
• docs/QUICKSTART.md — 5-minute quick start

---

Dokumentacja

Dokumentacja

Plik	Opis
NATIVE_SETUP.md	Uruchamianie bez Docker (zalecane)
CONTROL_PANEL.md	Control Panel & Testing
INSTALL_DEBIAN.md	Instalacja na Debian/Ubuntu
INSTALL_ARCHLINUX.md	Instalacja na Arch Linux
DOCKER.md	Docker dev + production
GOOGLE_SETUP.md	Google OAuth, Calendar, Drive
AI_SETUP.md	OpenAI, Claude, Gemini API keys
API.md	REST API + WebSocket docs
QUICKSTART.md	5-minute quick start
DEPLOYMENT_CHECKLIST.md	Production checklist

---

Struktura projektu

3df_db/
├── backend/
│   ├── app/
│   │   ├── models/          # SQLAlchemy models (11)
│   │   ├── routers/         # FastAPI endpoints
│   │   ├── services/        # Business logic (AI, Google, scheduler)
│   │   ├── middleware/      # Security, API key auth
│   │   └── utils/           # Helpers (serial generator, security)
│   ├── alembic/             # Database migrations
│   └── requirements.txt
├── frontend/
│   ├── src/
│   │   ├── components/      # UI components
│   │   ├── pages/           # Strony aplikacji
│   │   ├── context/         # React contexts (Auth, Theme, Notification)
│   │   ├── api/             # Axios client
│   │   └── styles/          # CSS (themes, Tailwind)
│   └── package.json
├── docker/                  # Dockerfiles
├── nginx/                   # Nginx configs
├── docs/                    # Dokumentacja
├── scripts/                 # Backup, deploy
├── docker-compose.yml       # Dev setup
├── docker-compose.prod.yml  # Production
└── Makefile                 # Shortcuts

---

Konfiguracja .env

# App
APP_ENV=production
SECRET_KEY=<wygeneruj-losowy>
DATABASE_URL=postgresql://user:pass@localhost:5432/3dfdb

# JWT
JWT_SECRET_KEY=<inny-losowy-klucz>
JWT_ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=43200

# Auth
ALLOWED_EMAILS=admin@3df.pl,user2@gmail.com,user3@gmail.com
FRONTEND_URL=https://3df.pl

# Google
GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...
GOOGLE_SERVICE_ACCOUNT_FILE=/opt/3df/backend/service-account.json

# AI
OPENAI_API_KEY=sk-proj-...
ANTHROPIC_API_KEY=sk-ant-...
GEMINI_API_KEY=AIzaSy...

Pełny .env.example w repozytorium.

---

API Endpoints

Główne

• POST /auth/google — OAuth login
• GET /auth/me — Current user
• GET /clients, POST /clients — Klienci
• GET /orders, POST /orders — Zlecenia
• POST /serial-numbers — Generuj numer
• GET /analytics/dashboard — Dashboard data
• POST /ai/chat — AI chat
• WS /ws/{user_id} — WebSocket notifications

API Keys (v1 — Codex)

• GET /v1/clients
• GET /v1/orders
• POST /v1/serial-numbers

Interaktywna dokumentacja: https://3df.pl/api/docs

---

Development

# Backend
cd backend
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
alembic upgrade head
uvicorn app.main:app --reload

# Frontend
cd frontend
npm install
npm run dev

# Linting
cd frontend && npm run lint
cd backend && black . && flake8

---

Deployment

Production z Docker

# 1. Clone + config
cd /opt/3df
cp .env.example .env
nano .env

# 2. Build + Run
docker compose -f docker-compose.prod.yml up -d --build

# 3. SSL (Certbot)
sudo certbot --nginx -d 3df.pl

# 4. Systemd (opcjonalnie zamiast Docker)
# Zobacz INSTALL_DEBIAN.md sekcja 9

Backup

# Automatyczny cron (2:00 AM codziennie)
sudo crontab -e
# 0 2 * * * /opt/3df/scripts/backup.sh

# Ręczny backup
./scripts/backup.sh

---

Makefile Commands

make dev           # Docker dev environment
make prod          # Docker production
make migrate       # Run migrations
make migrate-create msg="opis"  # Create migration
make logs          # View all logs
make logs-api      # API logs
make shell-api     # Bash in API container
make shell-db      # psql in database
make backup        # Database backup
make clean         # Stop + remove containers

---

Roadmap

• Task 1: ✅ Scaffolding + Docker + dokumentacja (DONE)
• Task 2: Migracje Alembic (wygeneruj alembic revision --autogenerate)
• Task 3: Auth — test Google OAuth
• Task 4: Clients & Orders — test CRUD
• Task 5: Serial Numbers — test generator
• Task 6: Contracts & Revenue — wykresy
• Task 7: Google integration — Calendar/Drive/Notes sync
• Task 8: AI — test chat z 3 modelami
• Task 9: API Keys — test v1 endpoints
• Task 10: Notifications — WebSocket push
• Task 11: Deployment hardening — prod SSL, backups
• Task 12: E2E testing

---

License

Proprietary — 3df.pl Private Use Only

---

Support

• Issues: kontakt@3df.pl
• Docs: /docs/ folder
• API Docs: https://3df.pl/api/docs

---

Made with ❤️ for 3df.pl — 3D Printing Business

---

Troubleshooting

PostgreSQL: "data directory is missing or empty"

Problem: Na Arch Linux PostgreSQL nie jest zainicjalizowany po instalacji.

Fix:

make init-db
# LUB
sudo -u postgres initdb --locale=C.UTF-8 --encoding=UTF8 -D '/var/lib/postgres/data'
sudo systemctl start postgresql

Port 8000 zajęty

Problem: Backend nie może wystartować - port zajęty.

Fix:

# Sprawdź co używa portu
sudo lsof -i :8000

# Zatrzymaj poprzedni proces
./scripts/stop.sh
# LUB
kill <PID>

"cannot import fastapi"

Problem: Python dependencies nie zainstalowane.

Fix:

cd backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Frontend nie buduje się

Problem: node_modules nie zainstalowane lub uszkodzone.

Fix:

cd frontend
rm -rf node_modules package-lock.json
npm install
npm run build

Sprawdź pełny status i uruchom testy

make status  # Diagnostyka wszystkich komponentów
make test    # Testy integracyjne

📖 Więcej: docs/CONTROL_PANEL.md

---

Control Panel & Testing

Nowe narzędzia diagnostyczne:

make status       # Pełny status (PostgreSQL, Backend, Frontend, Config, Ports)
make init-db      # Inicjalizuj PostgreSQL
make start-db     # Start PostgreSQL (auto-tworzy bazę + użytkownika)
make stop-db      # Stop PostgreSQL
make restart-db   # Restart PostgreSQL
make test         # Uruchom wszystkie testy (25+ testów integracyjnych)

Zobacz: docs/CONTROL_PANEL.md dla szczegółów.