Zählerstand-Agent

<?php

declare(strict_types=1);

use EnneoSDK\Api;
use EnneoSDK\ApiEnneo;
use EnneoSDK\Helpers;
use EnneoSDK\IntentInfo;
use EnneoSDK\IntentOption;
use EnneoSDK\Interaction;

require(getenv()['SDK'] ?? 'sdk.php');


/** @var stdClass $in */
######### Expected Input:
// contractId -> ID of the contract (required)
// readingDate -> date of the reading. Optional. If no date is provided, the ticket creation date will be used
// ticketDate -> date of ticket creation (required)
// value -> reading value (optional). If no value is provided, the function will check attachments and try OCR there
// ticketId -> ID of the ticket (required)
// channel -> ticket channel. Voice and chat can be handled synchronously.
// counter -> consumption-related counter. Value is empty while first execution.
// plausibilityReason -> reason to save invalid readings. Used only if value can't be saved without a reason


######### Possible Actions:
// For better readability, actions can be prefixed with "base_", if they are handled in main agent business logic
// save reading without reason
const BASE_SAVE_READING = 'base_save_reading';
// save invalid reading using plausibility reason
const BASE_SAVE_INVALID_READING = 'base_save_invalid_reading';
// reading date is not valid
const READING_DATE_INVALID = 'reading_date_invalid';
// no reading value provided
const READING_VALUE_NOT_PROVIDED = 'reading_value_not_provided';
// reading value is not valid
const READING_VALUE_INVALID = 'reading_value_invalid';
// success
const SAVE_READING_COMPLETED = 'save_reading_completed';


// Create an Interaction object for output and fetch contract data from ERP
$interaction = new Interaction($in);
$contract = ApiEnneo::getContract($in->contractId);


######### STEP: if "Save" or "Save unplausibel" action is already selected, try to save reading
if ($in->_action === BASE_SAVE_READING || $in->_action === BASE_SAVE_INVALID_READING) {
    try {
        $parameters = [
            'tenant' => 'tenant',
            'mockedStatus' => 'OK', // use PLAUSIBILITY_REASON_NEEDED to test unplausible reading
            'contractId' => $in->contractId,
            'readingDate' => $in->readingDate,
            'newConsumptions' => [
                [
                    'consumption' => $in->value,
                    'consumptionUnit' => 'KILOWATT_HOURS',
                    'consumptionRelatedCounter' => $in->counter
                ]
            ]
        ];
        if ($in->_acttion === BASE_SAVE_INVALID_READING) {
            if (!$in->_plausibilityReason) {
                $interaction->infos[] = new IntentInfo(
                    type: 'warning',
                    message: 'Bitte den Plausibilitätsgrund angeben'
                );
                $interaction->options[] = new IntentOption(
                    type: BASE_SAVE_INVALID_READING,
                    name: 'Erneut versuchen',
                    recommended: true
                );
                stopProcessing($interaction);
            }

            $parameters['params']['newConsumptions'][0]['plausibilityReason'] = $in->_plausibilityReason;
        }

        $response = Api::call(
            method: 'POST',
            url: 'https://echo.enneo.ai',
            params: $parameters
        );
    } catch (Throwable $exception) {
        $interaction->infos[] = new IntentInfo(
            type: 'danger',
            message: 'Zählerstand konnte nicht gespeichert werden'
        );
        $interaction->options[] = new IntentOption(
            type: BASE_SAVE_READING,
            name: 'Erneut versuchen',
            recommended: true
        );
        stopProcessing($interaction);
    }

    // On invalid readings: save using a plausibility reason or inform the customer
    if ($response->mockedStatus === 'PLAUSIBILITY_REASON_NEEDED') {
        $interaction->infos[] = new IntentInfo(
            type: 'warning',
            message: 'Zählerstand ist nicht plausibel. Bitte den Grund wür die Abweichung angeben.'
        );
        $interaction->options[] = new IntentOption(
            type: BASE_SAVE_INVALID_READING,
            name: 'Plausibilitätsgrund angeben und speichern',
            recommended: true
        );
        $interaction->options[] = new IntentOption(
            type: READING_VALUE_INVALID,
            name: 'Kunden über inplausiblen ZS informieren',
            recommended: false
        );
        stopProcessing($interaction);
    }

    // Success
    $interaction->infos[] = new IntentInfo(
        type: 'success',
        message: 'Zählerstand gespeichert'
    );
    $in->_action = SAVE_READING_COMPLETED;
    stopProcessing($interaction);
}

######### STEP: fetch existing readings
$meterReadingsDataResponse = Api::call(
    method: 'POST',
    url: 'https://echo.enneo.ai',
    params: [
        'contractId' => $in->contractId,
        'mockedResult' => getMockedMeterDataResponse()
    ]
);
$meterReadingsData = $meterReadingsDataResponse->mockedResult ?? getMockedMeterDataResponse();


// set consumption-related counter
$in->counter = $meterReadingsData->meters[0]->counterType;

######### STEP: get reading date and validate it
$in->readingDate = empty($in->readingDate) ? $in->ticketDate : $in->readingDate;
$isReadingDateValid = true;
// TODO:
// reading date can be validated here.
// On synchronous channel, user will be requested to change the date. On async channels, text template can be sent
$latestExistingReadingDate = max(array_map(fn($item) => $item->readingDate, $meterReadingsData->meters[0]->meterReadings));
if ($in->readingDate <= $latestExistingReadingDate) {
    $interaction->infos[] = new IntentInfo(
        type: 'warning',
        message: isSyncChannel($in)
            ? sprintf('Bitte geben Sie ein Datum nach dem %s ein', Helpers::formatDate($latestExistingReadingDate))
            : sprintf('Es liget bereits eine Ablseung vom %s vor', Helpers::formatDate($latestExistingReadingDate))
    );
    $interaction->options[] = new IntentOption(
        type: READING_DATE_INVALID,
        name: isSyncChannel($in) ? 'Datum korrigieren' : 'Kunden informieren',
        recommended: true
    );
    stopProcessing($interaction);
}

######### STEP: get reading value and validate it
if (!$in->value && !isSyncChannel($in)) {
    // on async channels (email), value could be provided as image in email attachment
    $in->value = getValueUsingOcrOnAttachments($in, $meterReadingsData);
}
if (!$in->value) {
    $interaction->infos[] = new IntentInfo(
        type: 'warning',
        message: 'Es wurde kein Zählerstand übermittelt'
    );
    $interaction->options[] = new IntentOption(
        type: READING_VALUE_NOT_PROVIDED,
        name: isSyncChannel($in) ? 'Zählerstand eingeben' : 'Kunden informieren',
        recommended: true
    );
    stopProcessing($interaction);
}
// TODO:
// reading value validation can be adjusted and improved here
$latestReadingValue = max(array_map(fn($item) => $item->consumption, $meterReadingsData->meters[0]->meterReadings));
if ($in->value <= $latestReadingValue) {
    $interaction->infos[] = new IntentInfo(
        type: 'warning',
        message: sprintf(
            'Zählerstand ist kleiner als zuletzt übermittelter Zählerstand (%s, %s)',
            Helpers::formatDate($latestExistingReadingDate),
            $latestReadingValue
        )
    );
    $interaction->options[] = new IntentOption(
        type: READING_VALUE_INVALID,
        name: isSyncChannel($in) ? 'Anderen Zählerstand eingeben' : 'Kunden informieren',
        recommended: true
    );
    stopProcessing($interaction);
}

######### STEP: data validation passed. Add "save" action
$interaction->options[] = new IntentOption(
    type: BASE_SAVE_READING,
    name: 'Zählerstand speichern',
    recommended: true
);
stopProcessing($interaction);


######### HELPER FUNCTIONS #########
function stopProcessing(Interaction $interaction): void
{
    echo json_encode($interaction);
    exit();
}

function isSyncChannel($in): bool
{
    return in_array($in->channel, ['chat', 'phone']);
}

function getValueUsingOcrOnAttachments(stdClass $in, stdClass $meterReadingsData): ?float
{
    // Last reading date & value can be provided to improve the OCR
    $latestReadingValue = max(array_map(fn($item) => $item->consumption, $meterReadingsData->meters[0]->meterReadings));
    $latestReadingDate = max(array_map(fn($item) => $item->readingDate, $meterReadingsData->meters[0]->meterReadings));

    $ticket = ApiEnneo::getTicket($in->ticketId);
    foreach ($ticket->attachments as $attachment) {
        if ($attachment->size < 10000) {
            // attachment to small (logo etc)
            continue;
        }
        if (!in_array($attachment->fileEnding, ['jpg', 'jpeg', 'png', 'gif'])) {
            // unsupported file extension
            continue;
        }
        $response = ApiEnneo::post(
            endpoint: '/api/cortex/ocrMeter',
            body: [
                'ticketId' => $in->ticketId,
                'fileUrl' => $_ENV['ENNEO_API_URL'] . $attachment->url,
                'readingDate' => $in->readingDate,
                'lastReading' => $latestReadingValue,
                'lastReadingDate' => $latestReadingDate,
            ]
        );
        if ($response->responses ?? $response->response) {
            $body = $response->responses ?? $response->response;
            // TODO: value2 can be used for HT/NT implementation
            $value2 = (float)($body->meter_reading_2 ?? $body->meterReading2);

            return (float)($body->meter_reading_1 ?? $body->meterReading1);
        }
    }

    return null;
}


/**
 * Generates a mocked response for meter data including meter details,
 * reading details, and associated properties.
 */
function getMockedMeterDataResponse(): array
{
    return [
        'meters' => [
            [
                'meterNumber' => '000000000000123456',
                'counterType' => 'ET',
                'numberOfPreDecimalDigitsForMeter' => 6,
                'numberOfPostDecimalDigitsForMeter' => 1,
                'addMeterReadingPossible' => true,
                'meterReadings' => [
                    [
                        'consumptionRelatedCounter' => 'ET',
                        'readingDate' => '2024-05-22',
                        'consumption' => 80048,
                        'consumptionUnit' => 'KILOWATT_HOURS',
                        'reason' => 'INITIAL_METER_COUNT'
                    ],
                    [
                        'consumptionRelatedCounter' => 'ET',
                        'readingDate' => '2024-12-21',
                        'consumption' => 81246,
                        'consumptionUnit' => 'KILOWATT_HOURS',
                        'reason' => 'INTERMEDIATE_READING'
                    ]
                ]
            ]
        ]
    ];
}