feat: standardize main.py with health checks, structured logging, and API docs

- Add module-level docstring with endpoint documentation
- Add /health endpoint with database connectivity check
- Add root endpoint redirecting to API docs
- Add FastAPI metadata (title, description, version)
- Reorganize imports and code structure with section separators
- Add shutdown event handler
- Change failed DB connection log level to warning

main.py

@@ -1,20 +1,53 @@
+"""
+eamco_auto_api - FastAPI Automatic Delivery Microservice.
+
+This microservice provides endpoints for managing automatic oil delivery
+scheduling, fuel level estimation, and delivery confirmation.
+
+Endpoints:
+    GET  /health                    - Health check with database connectivity status
+    GET  /main/temp                 - Manually trigger temperature fetch
+    GET  /main/update/auto          - Update fuel levels for auto-delivery customers
+    GET  /main/update/normal        - Update fuel levels for normal customers
+    GET  /delivery/...              - Delivery management endpoints
+    POST /confirm/...               - Delivery confirmation endpoints
+    GET  /fixstuff/auto/...         - Auto-delivery fix/maintenance endpoints
+    GET  /fixstuff/customer/...     - Customer fix/maintenance endpoints
+
+Usage:
+    # Development
+    uvicorn main:app --reload --host 0.0.0.0 --port 8000
+
+    # Production (Docker)
+    docker run -p 8000:8000 eamco_auto_api
+"""
+
 import logging
 import sys
 import uuid
-from app.routers import fixstuff_auto
+import os
+
 from fastapi import FastAPI, Request
-from app.routers import main, delivery, confirm, fixstuff_customer
 from fastapi.middleware.cors import CORSMiddleware
 from starlette.middleware.base import BaseHTTPMiddleware
-import os
-from config import load_config
 from sqlalchemy import create_engine, text
 from sqlalchemy.orm import sessionmaker
 
+from config import load_config
+from app.routers import main, delivery, confirm, fixstuff_auto, fixstuff_customer
+
+
+# =============================================================================
+# CONFIGURATION
+# =============================================================================
 
 ApplicationConfig = load_config()
 
-# Configure logging
+# =============================================================================
+# LOGGING CONFIGURATION
+# =============================================================================
+
+
 def setup_logging():
     """Configure structured logging for the application."""
     log_level = logging.DEBUG if ApplicationConfig.CURRENT_SETTINGS != 'PRODUCTION' else logging.INFO
@@ -37,9 +70,13 @@ def setup_logging():
 
     return logging.getLogger('eamco_auto_api')
 
+
 logger = setup_logging()
 
-# Database setup with connection pooling
+# =============================================================================
+# DATABASE SETUP
+# =============================================================================
+
 engine = create_engine(
     ApplicationConfig.SQLALCHEMY_DATABASE_URI,
     pool_pre_ping=True,
@@ -49,6 +86,7 @@ engine = create_engine(
 )
 SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
 
+
 def check_db_connection():
     """
     Test database connectivity.
@@ -61,11 +99,27 @@ def check_db_connection():
     except Exception:
         return False
 
-app = FastAPI()
+
+# =============================================================================
+# FASTAPI APPLICATION
+# =============================================================================
+
+app = FastAPI(
+    title="eamco_auto_api",
+    description="Automatic oil delivery scheduling and fuel estimation microservice",
+    version="1.0.0",
+    docs_url="/docs",
+    redoc_url="/redoc",
+)
+
+# =============================================================================
+# MIDDLEWARE
+# =============================================================================
 
 
-# Request ID middleware for request tracking/correlation
 class RequestIDMiddleware(BaseHTTPMiddleware):
+    """Request ID middleware for request tracking/correlation."""
+
     async def dispatch(self, request: Request, call_next):
         request_id = request.headers.get("X-Request-ID") or str(uuid.uuid4())[:8]
         request.state.request_id = request_id
@@ -73,13 +127,8 @@ class RequestIDMiddleware(BaseHTTPMiddleware):
         response.headers["X-Request-ID"] = request_id
         return response
 
-app.add_middleware(RequestIDMiddleware)
 
-app.include_router(main.router)
-app.include_router(delivery.router)
-app.include_router(confirm.router)
-app.include_router(fixstuff_auto.router)
-app.include_router(fixstuff_customer.router)
+app.add_middleware(RequestIDMiddleware)
 
 app.add_middleware(
     CORSMiddleware,
@@ -89,12 +138,54 @@ app.add_middleware(
     allow_headers=["Authorization", "Content-Type", "Accept", "Origin", "X-Requested-With"],
 )
 
+# =============================================================================
+# ROUTERS
+# =============================================================================
+
+app.include_router(main.router)
+app.include_router(delivery.router)
+app.include_router(confirm.router)
+app.include_router(fixstuff_auto.router)
+app.include_router(fixstuff_customer.router)
+
+# =============================================================================
+# ENDPOINTS
+# =============================================================================
 
 
+@app.get("/", include_in_schema=False)
+async def root():
+    """Root endpoint - redirect to docs."""
+    return {
+        "service": "eamco_auto_api",
+        "version": "1.0.0",
+        "docs": "/docs",
+    }
+
+
+@app.get("/health", tags=["Health"])
+async def health_check():
+    """
+    Health check endpoint.
+
+    Returns service status and database connectivity.
+    Use this endpoint for container health checks and monitoring.
+
+    Returns:
+        JSON with status and db_connected flag
+    """
+    db_connected = check_db_connection()
+
+    return {
+        "status": "healthy" if db_connected else "degraded",
+        "db_connected": db_connected,
+    }
+
+
+# =============================================================================
+# STARTUP/SHUTDOWN EVENTS
+# =============================================================================
 
-@app.get("/")
-def read_root():
-    return {"Status": "Auto Service is online"}
 
 @app.on_event("startup")
 async def startup_event():
@@ -116,4 +207,10 @@ async def startup_event():
     if check_db_connection():
         logger.info("DB Connection: ✅ OK")
     else:
-        logger.info("DB Connection: ❌ FAILED")
+        logger.warning("DB Connection: ❌ FAILED")
+
+
+@app.on_event("shutdown")
+async def shutdown_event():
+    """Application shutdown - cleanup."""
+    logger.info("🛑 eamco_auto_api SHUTTING DOWN")