Quick Start Guide
=================

For Users: Running the Service
------------------------------

Step 1: Implement Your TTS Service
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Create a file ``my_tts_service.py``:

.. code-block:: python

   from datetime import datetime
   from dashboard.notifications.tts_api_notifier.tts_interface import TTSService, TTSTicket
   import requests

   class MyTTSService(TTSService):
       def __init__(self, client_config: dict, include_sids: bool) -> None:
           self.api_url = client_config["tts"]["api_url"]
           self.api_key = client_config["tts"]["api_key"]
           self.include_sids = include_sids

       def find_overlapping_ticket(self, alarm_time: datetime, services: set[str]) -> TTSTicket | None:
           # Query your TTS API for overlapping maintenance tickets
           return None

       def update_maintenance_ticket(self, ticket_id: str, message: dict) -> None:
           # Update ticket via your TTS API using the ticket_id
           pass

       def create_ticket(self, message: dict) -> TTSTicket:
           # Create ticket via your TTS API
           return TTSTicket("internal-id", "NEW-TICKET-ID", "Ticket created", None)

Step 2: Create Configuration File
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

See :doc:`configuration` for full details on the configuration files.

Step 3: Run the Service
^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: bash

   tts_api_notifier --client-config /etc/dashboard/client-config.json

Or with optional parameters:

.. code-block:: bash

   tts_api_notifier --client-config /etc/dashboard/client-config.json --no-include-sids

The service will:

- Initialize database connection
- Connect to RabbitMQ
- Start processing messages
- Run until SIGTERM/SIGINT

Step 4: Monitor Logs
^^^^^^^^^^^^^^^^^^^^^

.. code-block:: text

   2026-04-02 10:15:30 - tts_api_notifier - INFO - Starting TTS API notifier service
   2026-04-02 10:15:31 - tts_api_notifier - INFO - Processing thread started
   2026-04-02 10:15:32 - tts_api_notifier - INFO - Created ticket TTS-12345 for alarm 67890


For Developers: Testing
-----------------------

Run Unit Tests
^^^^^^^^^^^^^^

.. code-block:: bash

   cd /path/to/dashboard-v3-python
   python -m pytest test/notifications/test_tts_api_notifier.py -v

Test with Mock TTS Service
^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

   from dashboard.notifications.tts_api_notifier import start_service
   from dashboard.notifications.tts_api_notifier.example_mock import MockTTSService
   import json

   # Load client config
   with open("test-client-config.json") as f:
       client_config = json.load(f)

   # Use mock service for testing
   tts_service = MockTTSService(client_config, include_sids=True)

   start_service(
       client_config_path="test-client-config.json",
       defaults_config_path="test-defaults-config.json",
       tts_service=tts_service
   )

Integration Test Demo
^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: bash

   python -m dashboard.notifications.tts_api_notifier.integration_test_example


Programmatic Usage (Advanced)
-----------------------------

For testing or advanced use cases, you can also start the service programmatically:

.. code-block:: python

   from dashboard.notifications.tts_api_notifier import start_service
   from my_tts_impl import MyTTSService

   tts_service = MyTTSService(client_config, include_sids=True)
   start_service(client_config, tts_service)


Implementing a TTSService
--------------------------

.. code-block:: python

   from datetime import datetime
   from dashboard.notifications.tts_api_notifier.tts_interface import TTSService, TTSTicket

   class MyTTSService(TTSService):
       def __init__(self, client_config: dict, include_sids: bool) -> None:
           self.api_url = client_config["tts"]["api_url"]
           self.api_key = client_config["tts"]["api_key"]
           self.include_sids = include_sids

       def find_overlapping_ticket(self, alarm_time: datetime, services: set[str]) -> TTSTicket | None:
           # Query TTS API for overlapping tickets affecting these services
           return None

       def update_maintenance_ticket(self, ticket_id: str, message: dict) -> None:
           # Update via TTS API using ticket_id
           pass

       def create_ticket(self, message: dict) -> TTSTicket:
           # Create via TTS API
           return TTSTicket("internal-id", "NEW-TICKET-123", "Ticket created", None)


Implementation Checklist
^^^^^^^^^^^^^^^^^^^^^^^^

To implement a concrete TTS service:

1. Subclass ``TTSService`` from ``tts_interface.py``
2. Implement ``__init__(self, client_config: dict, include_sids: bool) -> None``
3. Implement ``find_overlapping_ticket(alarm_time: datetime, services: set[str]) -> TTSTicket | None``
4. Implement ``update_maintenance_ticket(ticket_id: str, message: dict) -> None``
5. Implement ``create_ticket(message: dict) -> TTSTicket``
6. Handle TTS-specific credentials from client config
7. Call ``start_service()`` with your TTS instance


Troubleshooting
---------------

Issue: "Failed to initialize database"
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

**Solution:** Check database credentials in ``client-config.json``

.. code-block:: bash

   # Test DB connection
   mysql -u your_db_user -p -h db.example.com your_db_name

Issue: "Failed to connect to RabbitMQ"
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

**Solution:** Check RabbitMQ credentials and connection

.. code-block:: bash

   # Test RabbitMQ connection
   rabbitmqctl status

Issue: Messages not being processed
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Check logs for:

- ``should_create_ticket`` returning False (messages skipped)
- Exception messages (transient errors being retried)
- ``TicketError`` (alarm records not found)

Issue: Service not stopping gracefully
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

**Solution:** Ensure SIGTERM/SIGINT is sent

.. code-block:: bash

   # Send SIGTERM
   kill -TERM <pid>

   # Or use Ctrl+C (SIGINT)