<?php
/**
 * Caterpoint Order Template Model
 *
 * @category    PortalPeople
 * @package     Caterpoint
 * @author      Portal People Development Team
 * @copyright   Copyright (c) 2026 Portal People (https://portalpeople.co.uk)
 *
 * USAGE:
 * ------
 * This is a template model. To use this module, you should:
 * 
 * 1. Create your own Order model in your application that extends this
 * 2. Configure the module to use your model:
 *    
 *    'modules' => [
 *        'caterpoint' => [
 *            'class' => 'PortalPeople\caterpoint\Module',
 *            'apiEndpoint' => 'https://cp3-bayley-test.caterpoint.co.uk/api',
 *            'apiToken' => 'your-api-token',
 *        ],
 *    ],
 * 
 * 3. In your OrderImportService, set:
 *    $service->orderModelClass = 'app\models\CaterpointOrder';
 * 
 * 4. Implement the findOrCreateOrder() and mapOrderData() methods
 *    in OrderImportService based on your model structure
 */

namespace PortalPeople\caterpoint\models;

use yii\db\ActiveRecord;
use yii\behaviors\TimestampBehavior;

/**
 * CaterpointOrder Model Template
 * 
 * Database schema example:
 * 
 * CREATE TABLE caterpoint_orders (
 *     id INTEGER PRIMARY KEY AUTO_INCREMENT,
 *     external_order_id VARCHAR(255) NOT NULL UNIQUE,
 *     reference VARCHAR(255),
 *     customer_reference VARCHAR(255),
 *     status VARCHAR(50),
 *     external_status VARCHAR(50),
 *     order_date DATETIME,
 *     customer_data JSON,
 *     delivery_data JSON,
 *     totals_data JSON,
 *     external_data JSON,
 *     created_at DATETIME,
 *     updated_at DATETIME,
 *     INDEX idx_external_order_id (external_order_id),
 *     INDEX idx_reference (reference),
 *     INDEX idx_status (status)
 * );
 */
class CaterpointOrder extends ActiveRecord
{
    /**
     * @inheritdoc
     */
    public static function tableName()
    {
        return 'caterpoint_orders';
    }

    /**
     * @inheritdoc
     */
    public function behaviors()
    {
        return [
            TimestampBehavior::class,
        ];
    }

    /**
     * @inheritdoc
     */
    public function rules()
    {
        return [
            [['external_order_id'], 'required'],
            [['external_order_id'], 'unique'],
            [['reference', 'customer_reference', 'status', 'external_status'], 'string', 'max' => 255],
            [['order_date', 'created_at', 'updated_at'], 'safe'],
            [['customer_data', 'delivery_data', 'totals_data', 'external_data'], 'safe'],
        ];
    }

    /**
     * @inheritdoc
     */
    public function attributeLabels()
    {
        return [
            'id' => 'ID',
            'external_order_id' => 'Caterpoint Order ID',
            'reference' => 'Order Reference',
            'customer_reference' => 'Customer Reference',
            'status' => 'Status',
            'external_status' => 'External Status',
            'order_date' => 'Order Date',
            'customer_data' => 'Customer Data',
            'delivery_data' => 'Delivery Data',
            'totals_data' => 'Totals Data',
            'external_data' => 'External Data',
            'created_at' => 'Created At',
            'updated_at' => 'Updated At',
        ];
    }

    /**
     * Find order by external Caterpoint ID
     * 
     * @param string $externalOrderId
     * @return self|null
     */
    public static function findByExternalId(string $externalOrderId): ?self
    {
        return static::findOne(['external_order_id' => $externalOrderId]);
    }

    /**
     * Find or create order by external ID
     * 
     * @param string $externalOrderId
     * @return self
     */
    public static function findOrCreate(string $externalOrderId): self
    {
        $order = static::findByExternalId($externalOrderId);
        
        if ($order === null) {
            $order = new static();
            $order->external_order_id = $externalOrderId;
        }
        
        return $order;
    }
}
