bmc_hub/README.md

# BMC Hub 🚀

Et centralt management system til BMC Networks - håndterer kunder, services, hardware og billing.

**Baseret på OmniSync arkitektur med Python + PostgreSQL**

## 🌟 Features

- **Customer Management**: Komplet kundedatabase med CRM integration
- **Time Tracking Module**: vTiger integration med tidsregistrering og fakturering
  - Automatisk sync fra vTiger (billable timelogs)
  - Step-by-step godkendelses-wizard
  - Auto-afrunding til 0.5 timer
  - Klippekort-funktionalitet
  - e-conomic export (draft orders)
- **Hardware Tracking**: Registrering og sporing af kundeudstyr
- **Service Management**: Håndtering af services og abonnementer
- **Billing Integration**: Automatisk fakturering via e-conomic
- **REST API**: FastAPI med OpenAPI dokumentation
- **Web UI**: Responsive Bootstrap 5 interface
- **PostgreSQL**: Production-ready database
- **Docker**: Container deployment med version control

## 📚 Quick Start

### Lokal Udvikling

```bash
# 1. Clone repository
git clone git@g.bmcnetworks.dk:ct/bmc_hub.git
cd bmc_hub

# 2. Kopier og rediger .env
cp .env.example .env
nano .env  # Tilføj dine credentials

# 3. Start med Docker Compose
docker-compose up -d

# 4. Åbn browser
open http://localhost:8001/api/docs  # API docs
open http://localhost:8001            # Web UI
```

**Standard ports** (for at undgå konflikter):
- API: `8001` (mapped til container port 8000)
- PostgreSQL: `5433` (mapped til container port 5432)

**Note**: Auto-reload er deaktiveret som standard for at undgå log spam. Når du ændrer kode, skal du genstarte containeren:
```bash
docker-compose restart api
```

Hvis du ønsker live reload (med potentiel log spam), sæt `ENABLE_RELOAD=true` i `.env`.

### Live Deployment

```bash
# På serveren
cd /opt
git clone git@g.bmcnetworks.dk:ct/bmc_hub.git
cd bmc_hub

# Setup environment
cp .env.prod.example .env
nano .env  # Udfyld credentials og version tag

# Deploy
docker-compose -f docker-compose.prod.yml up -d
```

## 🛠️ Deployment Commands

### Lokal Development
```bash
docker-compose up -d        # Start systemet
docker-compose logs -f      # Se logs
docker-compose down         # Stop systemet
```

### Production
```bash
docker-compose -f docker-compose.prod.yml up -d    # Start
docker-compose -f docker-compose.prod.yml pull     # Update til ny version
docker-compose -f docker-compose.prod.yml restart  # Restart
```

## 📋 Krav

### Development
- Docker Desktop eller Podman
- Git

### Production
- Docker eller Podman
- PostgreSQL (via container)
- Nginx reverse proxy
- SSL certifikat

## 🏗️ Projekt Struktur

```
bmc_hub/
├── app/
│   ├── core/
│   │   ├── config.py          # Konfiguration
│   │   └── database.py        # PostgreSQL helpers
│   ├── models/
│   │   └── schemas.py         # Pydantic models
│   ├── routers/
│   │   ├── customers.py       # Customer CRUD
│   │   ├── hardware.py        # Hardware management
│   │   └── billing.py         # Billing endpoints
│   ├── services/
│   │   └── economic.py        # e-conomic integration
│   └── jobs/
│       └── sync_job.py        # Scheduled jobs
├── static/
│   └── index.html             # Dashboard UI
├── migrations/                 # Database migrations
├── docker-compose.yml          # Local development
├── docker-compose.prod.yml     # Production deployment
├── Dockerfile                  # Docker image
├── requirements.txt            # Python dependencies
├── .env.example                # Environment template (local)
├── .env.prod.example           # Environment template (production)
└── main.py                     # FastAPI application
```

## 🔌 API Endpoints

### Main API
- `GET /api/v1/customers` - List customers
- `GET /api/v1/hardware` - List hardware
- `GET /api/v1/billing/invoices` - List invoices
- `GET /health` - Health check

### Time Tracking Module
- `POST /api/v1/timetracking/sync` - Sync from vTiger (read-only)
- `GET /api/v1/timetracking/wizard/next` - Get next pending timelog
- `POST /api/v1/timetracking/wizard/approve/{id}` - Approve timelog
- `POST /api/v1/timetracking/orders/generate` - Generate invoice order
- `POST /api/v1/timetracking/export` - Export to e-conomic (with safety flags)
- `GET /api/v1/timetracking/export/test-connection` - Test e-conomic connection

Se fuld dokumentation: http://localhost:8001/api/docs

## 🚨 e-conomic Write Mode

Time Tracking modulet kan eksportere ordrer til e-conomic med **safety-first approach**:

### Safety Flags (default: SAFE)
```bash
TIMETRACKING_ECONOMIC_READ_ONLY=true   # Block all writes
TIMETRACKING_ECONOMIC_DRY_RUN=true     # Simulate writes (log only)
```

### Enable Write Mode
Se detaljeret guide: [docs/ECONOMIC_WRITE_MODE.md](docs/ECONOMIC_WRITE_MODE.md)

**Quick steps:**
1. Test connection: `GET /api/v1/timetracking/export/test-connection`
2. Test dry-run: Set `READ_ONLY=false`, keep `DRY_RUN=true`
3. Export test order: `POST /api/v1/timetracking/export`
4. Enable production: Set **both** flags to `false`
5. Verify first order in e-conomic before bulk operations

**CRITICAL**: All customers must have `economic_customer_number` (synced from vTiger `cf_854` field).

## 🧪 Testing

```bash
# Install test dependencies
pip install pytest pytest-cov

# Run tests
pytest

# Run with coverage
pytest --cov=app
```

## 📄 License

MIT License

## 📞 Support

- **Issues**: Gitea Issues
- **Dokumentation**: `/api/docs`
- **Email**: support@bmcnetworks.dk

---

**Made with ❤️ by BMC Networks**