┌─────────┐
│  DRAFT  │ (Rascunho incompleto)
└────┬────┘
     │ preencher campos
     ↓
┌─────────┐
│ PENDING │ (Completo, pronto para publicar)
└────┬────┘
     │ publicar
     ↓
┌───────────┐
│ PUBLISHED │ (Recebendo propostas)
└─────┬─────┘
      │
      ├─→ 0 propostas → CANCELLED (pode reabrir)
      │                     ↓
      │                 PENDING (editar)
      │                     ↓
      │                 PUBLISHED (publicar novamente)
      │
      ├─→ ≥1 proposta → REVOKED (NÃO pode reabrir)
      │
      └─→ escolher vencedor
          ↓
      ┌─────────┐
      │ AWARDED │ (Vencedor escolhido)
      └────┬────┘
           │ finalizar
           ↓
      ┌──────────┐
      │ FINISHED │ (Processo completo)
      └──────────┘

QUALQUER status (exceto REVOKED, AWARDED, FINISHED) → DELETED (soft delete)

// Exemplo de validação
if ($from === OrderStatus::PUBLISHED && $to === OrderStatus::CANCELLED) {
    if ($order->proposals_count > 0) {
        throw new BusinessRuleException(
            'Não pode cancelar licitação com propostas. Use REVOGAR.'
        );
    }
}

if ($from === OrderStatus::PUBLISHED && $to === OrderStatus::REVOKED) {
    if ($order->proposals_count === 0) {
        throw new BusinessRuleException(
            'Não pode revogar licitação sem propostas. Use CANCELAR.'
        );
    }
    if (empty($reason)) {
        throw new ValidationException(
            'Motivo obrigatório para revogar licitação.'
        );
    }
}

CREATE TABLE order_status_history (
    id BIGSERIAL PRIMARY KEY,
    order_id BIGINT NOT NULL,
    from_status VARCHAR(50),
    to_status VARCHAR(50) NOT NULL,
    changed_by BIGINT NOT NULL, -- user_id
    changed_at TIMESTAMP NOT NULL DEFAULT NOW(),
    reason_type VARCHAR(100), -- enum CancellationReason
    reason_notes TEXT, -- texto livre adicional
    ip_address VARCHAR(45),
    user_agent TEXT,

    FOREIGN KEY (order_id) REFERENCES orders(id) ON DELETE CASCADE,
    FOREIGN KEY (changed_by) REFERENCES users(id)
);

CREATE INDEX idx_osh_order_id ON order_status_history(order_id);
CREATE INDEX idx_osh_changed_at ON order_status_history(changed_at);

// Migration para adicionar timestamps
Schema::table('orders', function (Blueprint $table) {
    $table->timestamp('published_at')->nullable();
    $table->timestamp('cancelled_at')->nullable();
    $table->timestamp('revoked_at')->nullable();
    $table->timestamp('awarded_at')->nullable();
    $table->timestamp('finished_at')->nullable();

    // Soft delete com metadados
    $table->softDeletes(); // deleted_at
    $table->unsignedBigInteger('deleted_by')->nullable();
    $table->string('deletion_reason', 500)->nullable();

    $table->foreign('deleted_by')->references('id')->on('users');
});

enum CancellationReason: string
{
    case SPECIFICATION_ERROR = 'erro_especificacao';
    case NEED_CHANGE = 'mudanca_necessidade';
    case INSUFFICIENT_BUDGET = 'orcamento_insuficiente';
    case SUPERIOR_DECISION = 'decisao_superior';
    case INADEQUATE_PROPOSALS = 'propostas_inadequadas';
    case DEADLINE_ISSUE = 'problema_prazo';
    case SUPPLIER_ISSUE = 'problema_fornecedor';
    case OTHER = 'outro';

    public function label(): string
    {
        return match($this) {
            self::SPECIFICATION_ERROR => 'Erro na especificação do produto',
            self::NEED_CHANGE => 'Mudança de necessidade',
            self::INSUFFICIENT_BUDGET => 'Orçamento insuficiente',
            self::SUPERIOR_DECISION => 'Decisão superior',
            self::INADEQUATE_PROPOSALS => 'Todas propostas inadequadas',
            self::DEADLINE_ISSUE => 'Problema com prazo de entrega',
            self::SUPPLIER_ISSUE => 'Problema com fornecedores',
            self::OTHER => 'Outro motivo',
        };
    }
}

🔔 Nova Licitação Disponível!

Licitação: #2025-001
Descrição: Compra de fertilizantes para plantação
Prazo para Propostas: 25/12/2025 às 18:00

Acesse o portal para enviar sua proposta:
[Link para Portal Fornecedor]

❌ Licitação Cancelada

A licitação #2025-001 foi cancelada pelo produtor.

Você não precisa enviar proposta para esta licitação.

⚠️ Licitação Revogada

A licitação #2025-001 foi REVOGADA.

Motivo: Mudança de necessidade

Suas propostas foram invalidadas e não serão consideradas.

Pedimos desculpas pelo transtorno.

🎉 Parabéns! Sua proposta foi a vencedora!

Licitação: #2025-001
Valor Total: R$ 15.000,00

Próximos passos:
1. Acesse o portal para assinar o contrato digital
2. Aguarde confirmação do produtor
3. Proceda com a entrega conforme combinado

[Link para Contrato]

📋 Resultado da Licitação #2025-001

Informamos que sua proposta não foi selecionada nesta licitação.

Agradecemos sua participação e esperamos contar com você em futuras oportunidades.

<?php

namespace App\Enums;

enum OrderStatus: string
{
    case DRAFT = 'draft';
    case PENDING = 'pending';
    case PUBLISHED = 'published';
    case CANCELLED = 'cancelled';
    case REVOKED = 'revoked';
    case AWARDED = 'awarded';
    case FINISHED = 'finished';

    public function label(): string
    {
        return match($this) {
            self::DRAFT => 'Rascunho',
            self::PENDING => 'Pendente',
            self::PUBLISHED => 'Publicada',
            self::CANCELLED => 'Cancelada',
            self::REVOKED => 'Revogada',
            self::AWARDED => 'Adjudicada',
            self::FINISHED => 'Finalizada',
        };
    }

    public function color(): string
    {
        return match($this) {
            self::DRAFT => '#6B7280',
            self::PENDING => '#3B82F6',
            self::PUBLISHED => '#10B981',
            self::CANCELLED => '#F59E0B',
            self::REVOKED => '#DC2626',
            self::AWARDED => '#8B5CF6',
            self::FINISHED => '#059669',
        };
    }

    public function canTransitionTo(OrderStatus $target): bool
    {
        return match($this) {
            self::DRAFT => in_array($target, [self::PENDING]),
            self::PENDING => in_array($target, [self::DRAFT, self::PUBLISHED]),
            self::PUBLISHED => in_array($target, [self::CANCELLED, self::REVOKED, self::AWARDED]),
            self::CANCELLED => in_array($target, [self::PENDING, self::PUBLISHED]),
            self::REVOKED => false, // nunca muda
            self::AWARDED => in_array($target, [self::FINISHED]),
            self::FINISHED => false, // nunca muda
        };
    }

    public function canDelete(): bool
    {
        return in_array($this, [self::DRAFT, self::PENDING]);
    }

    public function canEdit(): bool
    {
        return in_array($this, [self::DRAFT, self::PENDING, self::CANCELLED]);
    }

    public function canPublish(): bool
    {
        return in_array($this, [self::PENDING, self::CANCELLED]);
    }

    public function canCancel(): bool
    {
        return $this === self::PUBLISHED;
    }

    public function canRevoke(): bool
    {
        return $this === self::PUBLISHED;
    }
}

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;
use App\Enums\OrderStatus;
use App\Enums\CancellationReason;

class OrderStatusHistory extends Model
{
    const UPDATED_AT = null; // Tabela só tem created_at

    protected $table = 'order_status_history';

    protected $fillable = [
        'order_id',
        'from_status',
        'to_status',
        'changed_by',
        'changed_at',
        'reason_type',
        'reason_notes',
        'ip_address',
        'user_agent',
    ];

    protected $casts = [
        'from_status' => OrderStatus::class,
        'to_status' => OrderStatus::class,
        'reason_type' => CancellationReason::class,
        'changed_at' => 'datetime',
    ];

    // RELACIONAMENTOS
    public function order(): BelongsTo
    {
        return $this->belongsTo(Order::class);
    }

    public function changedBy(): BelongsTo
    {
        return $this->belongsTo(User::class, 'changed_by');
    }
}

<?php

namespace App\Services;

use App\Models\Order;
use App\Models\OrderStatusHistory;
use App\Enums\OrderStatus;
use App\Enums\CancellationReason;
use App\Exceptions\InvalidStatusTransitionException;
use App\Exceptions\BusinessRuleException;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\Facades\DB;

class OrderStatusService
{
    /**
     * Muda status da licitação com validações e rastreabilidade
     */
    public function changeStatus(
        Order $order,
        OrderStatus $newStatus,
        ?CancellationReason $reason = null,
        ?string $notes = null
    ): Order {
        DB::beginTransaction();

        try {
            $oldStatus = $order->status;

            // 1. Validar se transição é permitida
            if (!$oldStatus->canTransitionTo($newStatus)) {
                throw new InvalidStatusTransitionException(
                    "Não é possível mudar de {$oldStatus->label()} para {$newStatus->label()}"
                );
            }

            // 2. Validar regras de negócio específicas
            $this->validateBusinessRules($order, $oldStatus, $newStatus, $reason);

            // 3. Salvar no histórico ANTES de mudar
            $this->saveHistory($order, $oldStatus, $newStatus, $reason, $notes);

            // 4. Atualizar status e timestamp
            $updates = ['status' => $newStatus];
            $updates[$this->getTimestampField($newStatus)] = now();

            $order->update($updates);

            // 5. Disparar notificações
            $this->notifyStakeholders($order, $newStatus, $reason, $notes);

            // 6. Log de auditoria
            Log::info("Order status changed", [
                'order_id' => $order->id,
                'order_number' => $order->number,
                'from' => $oldStatus->value,
                'to' => $newStatus->value,
                'by' => auth()->id(),
                'reason' => $reason?->value,
            ]);

            DB::commit();

            return $order->fresh();

        } catch (\Exception $e) {
            DB::rollBack();
            throw $e;
        }
    }

    /**
     * Validações de regras de negócio
     */
    protected function validateBusinessRules(
        Order $order,
        OrderStatus $from,
        OrderStatus $to,
        ?CancellationReason $reason
    ): void {
        // Regra: Cancelar só se não tiver propostas
        if ($from === OrderStatus::PUBLISHED && $to === OrderStatus::CANCELLED) {
            if ($order->proposals_count > 0) {
                throw new BusinessRuleException(
                    'Não pode cancelar licitação com propostas. Use REVOGAR.'
                );
            }
        }

        // Regra: Revogar só se tiver propostas
        if ($from === OrderStatus::PUBLISHED && $to === OrderStatus::REVOKED) {
            if ($order->proposals_count === 0) {
                throw new BusinessRuleException(
                    'Não pode revogar licitação sem propostas. Use CANCELAR.'
                );
            }

            if (empty($reason)) {
                throw new BusinessRuleException(
                    'Motivo obrigatório para revogar licitação.'
                );
            }
        }

        // Regra: Publicar só se completo
        if ($to === OrderStatus::PUBLISHED) {
            if (!$this->isOrderComplete($order)) {
                throw new BusinessRuleException(
                    'Licitação incompleta. Preencha todos os campos obrigatórios.'
                );
            }
        }
    }

    /**
     * Verifica se licitação está completa
     */
    protected function isOrderComplete(Order $order): bool
    {
        return !empty($order->description)
            && !empty($order->deadline_date)
            && !empty($order->supply_radius)
            && $order->orderItems()->count() > 0;
    }

    /**
     * Salva histórico de mudança de status
     */
    protected function saveHistory(
        Order $order,
        OrderStatus $from,
        OrderStatus $to,
        ?CancellationReason $reason,
        ?string $notes
    ): void {
        OrderStatusHistory::create([
            'order_id' => $order->id,
            'from_status' => $from,
            'to_status' => $to,
            'changed_by' => auth()->id(),
            'changed_at' => now(),
            'reason_type' => $reason,
            'reason_notes' => $notes,
            'ip_address' => request()->ip(),
            'user_agent' => request()->userAgent(),
        ]);
    }

    /**
     * Retorna campo de timestamp apropriado para o status
     */
    protected function getTimestampField(OrderStatus $status): ?string
    {
        return match($status) {
            OrderStatus::PUBLISHED => 'published_at',
            OrderStatus::CANCELLED => 'cancelled_at',
            OrderStatus::REVOKED => 'revoked_at',
            OrderStatus::AWARDED => 'awarded_at',
            OrderStatus::FINISHED => 'finished_at',
            default => null,
        };
    }

    /**
     * Notifica stakeholders sobre mudança de status
     */
    protected function notifyStakeholders(
        Order $order,
        OrderStatus $newStatus,
        ?CancellationReason $reason,
        ?string $notes
    ): void {
        // TODO: Implementar notificações (Email/WhatsApp)
        // Ver seção "Notificações" deste documento
    }
}

// OrderController.php

/**
 * Excluir licitação (soft delete com metadados)
 */
public function destroy(Order $order, Request $request): JsonResponse
{
    $request->validate([
        'reason' => 'required|string|max:500',
    ]);

    try {
        // Verificar se pode excluir
        if (!$order->status->canDelete()) {
            return response()->json([
                'message' => "Não é possível excluir licitação com status {$order->status->label()}"
            ], 422);
        }

        // Salvar histórico
        OrderStatusHistory::create([
            'order_id' => $order->id,
            'from_status' => $order->status,
            'to_status' => null,
            'changed_by' => auth()->id(),
            'changed_at' => now(),
            'reason_type' => null,
            'reason_notes' => 'DELETED: ' . $request->reason,
            'ip_address' => $request->ip(),
            'user_agent' => $request->userAgent(),
        ]);

        // Soft delete com metadados
        $order->update([
            'deleted_by' => auth()->id(),
            'deletion_reason' => $request->reason,
        ]);
        $order->delete();

        return response()->json([
            'message' => 'Licitação excluída com sucesso'
        ]);

    } catch (\Exception $e) {
        return response()->json([
            'message' => 'Erro ao excluir licitação',
            'error' => $e->getMessage()
        ], 500);
    }
}

/**
 * Cancelar licitação (PUBLISHED → CANCELLED, sem propostas)
 */
public function cancel(Order $order, Request $request): JsonResponse
{
    $request->validate([
        'reason_type' => 'required|string',
        'reason_notes' => 'nullable|string|max:1000',
    ]);

    try {
        $statusService = new OrderStatusService();

        $order = $statusService->changeStatus(
            $order,
            OrderStatus::CANCELLED,
            CancellationReason::from($request->reason_type),
            $request->reason_notes
        );

        return response()->json([
            'message' => 'Licitação cancelada com sucesso',
            'data' => new OrderResource($order)
        ]);

    } catch (\Exception $e) {
        return response()->json([
            'message' => $e->getMessage()
        ], 422);
    }
}

/**
 * Revogar licitação (PUBLISHED → REVOKED, com propostas)
 */
public function revoke(Order $order, Request $request): JsonResponse
{
    $request->validate([
        'reason_type' => 'required|string',
        'reason_notes' => 'nullable|string|max:1000',
    ]);

    try {
        $statusService = new OrderStatusService();

        $order = $statusService->changeStatus(
            $order,
            OrderStatus::REVOKED,
            CancellationReason::from($request->reason_type),
            $request->reason_notes
        );

        return response()->json([
            'message' => 'Licitação revogada com sucesso',
            'data' => new OrderResource($order)
        ]);

    } catch (\Exception $e) {
        return response()->json([
            'message' => $e->getMessage()
        ], 422);
    }
}

// types/order.ts

export enum OrderStatus {
  DRAFT = 'draft',
  PENDING = 'pending',
  PUBLISHED = 'published',
  CANCELLED = 'cancelled',
  REVOKED = 'revoked',
  AWARDED = 'awarded',
  FINISHED = 'finished',
}

export enum CancellationReason {
  SPECIFICATION_ERROR = 'erro_especificacao',
  NEED_CHANGE = 'mudanca_necessidade',
  INSUFFICIENT_BUDGET = 'orcamento_insuficiente',
  SUPERIOR_DECISION = 'decisao_superior',
  INADEQUATE_PROPOSALS = 'propostas_inadequadas',
  DEADLINE_ISSUE = 'problema_prazo',
  SUPPLIER_ISSUE = 'problema_fornecedor',
  OTHER = 'outro',
}

export interface Order {
  id: number
  uuid: string
  number: string
  status: OrderStatus
  proposals_count: number
  published_at?: string
  cancelled_at?: string
  revoked_at?: string
  awarded_at?: string
  finished_at?: string
  // ... outros campos
}

export interface OrderStatusHistoryItem {
  id: number
  from_status: OrderStatus | null
  to_status: OrderStatus
  changed_by_name: string
  changed_at: string
  reason_type?: CancellationReason
  reason_notes?: string
}

<!-- Modal de Exclusão -->
<div v-if="showDeleteModal" class="modal">
  <div class="modal-content">
    <h3>Excluir Licitação?</h3>
    <p>Esta ação não pode ser desfeita.</p>

    <div class="form-group">
      <label>Motivo da exclusão:</label>
      <textarea
        v-model="deletionReason"
        required
        placeholder="Explique por que está excluindo esta licitação..."
      ></textarea>
    </div>

    <div class="actions">
      <button @click="cancelarExclusao">Cancelar</button>
      <button @click="confirmarExclusao" :disabled="!deletionReason">
        Confirmar Exclusão
      </button>
    </div>
  </div>
</div>

<!-- Modal de Cancelamento -->
<div v-if="showCancelModal" class="modal">
  <div class="modal-content">
    <h3>Cancelar Licitação?</h3>
    <p>Esta licitação ainda não recebeu propostas.</p>

    <div class="form-group">
      <label>Motivo do cancelamento:</label>
      <select v-model="cancellationReasonType" required>
        <option value="">Selecione um motivo</option>
        <option value="erro_especificacao">Erro na especificação</option>
        <option value="mudanca_necessidade">Mudança de necessidade</option>
        <option value="orcamento_insuficiente">Orçamento insuficiente</option>
        <option value="decisao_superior">Decisão superior</option>
        <option value="outro">Outro</option>
      </select>
    </div>

    <div v-if="cancellationReasonType" class="form-group">
      <label>Observações adicionais (opcional):</label>
      <textarea v-model="cancellationNotes" placeholder="Detalhes..."></textarea>
    </div>

    <div class="actions">
      <button @click="cancelarCancelamento">Voltar</button>
      <button @click="confirmarCancelamento" :disabled="!cancellationReasonType">
        Confirmar Cancelamento
      </button>
    </div>
  </div>
</div>

<!-- Modal de Revogação -->
<div v-if="showRevokeModal" class="modal">
  <div class="modal-content warning">
    <h3>⚠️ Revogar Licitação?</h3>

    <div class="alert alert-danger">
      <strong>ATENÇÃO:</strong> Esta licitação já recebeu
      <strong>{{ selectedOrder.proposals_count }} proposta(s)</strong>.

      Ao revogar:
      - Todos os fornecedores serão notificados
      - As propostas serão invalidadas
      - Não será possível reabrir esta licitação
    </div>

    <div class="form-group">
      <label>Motivo da revogação (obrigatório):</label>
      <select v-model="revocationReasonType" required>
        <option value="">Selecione um motivo</option>
        <option value="erro_especificacao">Erro na especificação</option>
        <option value="mudanca_necessidade">Mudança de necessidade</option>
        <option value="propostas_inadequadas">Propostas inadequadas</option>
        <option value="decisao_superior">Decisão superior</option>
        <option value="outro">Outro</option>
      </select>
    </div>

    <div class="form-group">
      <label>Explicação detalhada (obrigatório):</label>
      <textarea
        v-model="revocationNotes"
        required
        placeholder="Explique detalhadamente o motivo da revogação. Esta mensagem será enviada aos fornecedores."
      ></textarea>
    </div>

    <div class="actions">
      <button @click="cancelarRevogacao">Cancelar</button>
      <button
        @click="confirmarRevogacao"
        :disabled="!revocationReasonType || !revocationNotes"
        class="btn-danger"
      >
        Confirmar Revogação
      </button>
    </div>
  </div>
</div>

Log::channel('audit')->info('Order status changed', [
    'order_id' => $order->id,
    'order_number' => $order->number,
    'from_status' => $oldStatus->value,
    'to_status' => $newStatus->value,
    'changed_by' => auth()->id(),
    'changed_by_name' => auth()->user()->name,
    'ip_address' => request()->ip(),
    'user_agent' => request()->userAgent(),
    'reason_type' => $reason?->value,
    'reason_notes' => $notes,
    'timestamp' => now()->toIso8601String(),
]);