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

# 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:

docker-compose restart api

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

Live Deployment

# 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

docker-compose up -d        # Start systemet
docker-compose logs -f      # Se logs
docker-compose down         # Stop systemet

Production

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)

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

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

# 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