From 8e33f9ce4f28929fb033cf3ffefeec8636f78c6d Mon Sep 17 00:00:00 2001
From: Paulo Castellano <paulofcastellano@gmail.com>
Date: Wed, 1 Apr 2026 11:07:21 -0300
Subject: [PATCH] feat: add error_context column to post_platforms for
 structured error debugging

---
 app/Jobs/PublishToSocialPlatform.php          | 26 ++++++++++++++++---
 app/Models/PostPlatform.php                   |  5 +++-
 ..._error_context_to_post_platforms_table.php | 22 ++++++++++++++++
 3 files changed, 48 insertions(+), 5 deletions(-)
 create mode 100644 database/migrations/2026_04_01_140435_add_error_context_to_post_platforms_table.php

diff --git a/app/Jobs/PublishToSocialPlatform.php b/app/Jobs/PublishToSocialPlatform.php
index 46b11b76..f9a94d64 100644
--- a/app/Jobs/PublishToSocialPlatform.php
+++ b/app/Jobs/PublishToSocialPlatform.php
@@ -103,12 +103,22 @@ public function handle(): void
                     'platform_error_code' => $e->platformErrorCode,
                 ]);
 
-                $this->postPlatform->markAsFailed($e->getMessage());
+                $this->postPlatform->markAsFailed($e->getMessage(), [
+                    'category' => 'token_expired',
+                    'platform_error_code' => $e->platformErrorCode,
+                    'failed_at' => now()->toIso8601String(),
+                ]);
                 $this->postPlatform->socialAccount->markAsDisconnected($e->getMessage());
                 break;
             } catch (SocialPublishException $e) {
                 Log::error('Social publish failed: '.$e->userMessage);
-                $this->postPlatform->markAsFailed($e->userMessage);
+                $this->postPlatform->markAsFailed($e->userMessage, [
+                    'category' => $e->category->value,
+                    'platform_error_code' => $e->platformErrorCode,
+                    'failed_at' => now()->toIso8601String(),
+                    'content_length' => mb_strlen($this->postPlatform->content ?? ''),
+                    'media_count' => $this->postPlatform->media->count(),
+                ]);
                 break;
             } catch (\Throwable $e) {
                 Log::error('Failed to publish to social platform', [
@@ -116,7 +126,12 @@ public function handle(): void
                     'platform' => $this->postPlatform->platform->value,
                     'error' => $e->getMessage(),
                 ]);
-                $this->postPlatform->markAsFailed($e->getMessage());
+                $this->postPlatform->markAsFailed($e->getMessage(), [
+                    'category' => 'unknown',
+                    'failed_at' => now()->toIso8601String(),
+                    'content_length' => mb_strlen($this->postPlatform->content ?? ''),
+                    'media_count' => $this->postPlatform->media->count(),
+                ]);
                 break;
             }
         }
@@ -224,7 +239,10 @@ public function failed(?\Throwable $exception): void
         $this->postPlatform->refresh();
 
         if ($this->postPlatform->status !== PostPlatformStatus::Published) {
-            $this->postPlatform->markAsFailed($exception?->getMessage() ?? 'Unknown error');
+            $this->postPlatform->markAsFailed($exception?->getMessage() ?? 'Unknown error', [
+                'category' => 'job_failed',
+                'failed_at' => now()->toIso8601String(),
+            ]);
             $this->updatePostStatus();
             $this->broadcastStatus();
         }
diff --git a/app/Models/PostPlatform.php b/app/Models/PostPlatform.php
index eeb311fe..8c7a26ee 100644
--- a/app/Models/PostPlatform.php
+++ b/app/Models/PostPlatform.php
@@ -30,6 +30,7 @@ class PostPlatform extends Model
         'platform_post_id',
         'platform_url',
         'error_message',
+        'error_context',
         'published_at',
         'meta',
     ];
@@ -43,6 +44,7 @@ protected function casts(): array
             'status' => Status::class,
             'published_at' => 'datetime',
             'meta' => 'array',
+            'error_context' => 'array',
         ];
     }
 
@@ -71,11 +73,12 @@ public function markAsPublished(string $platformPostId, ?string $platformUrl = n
         ]);
     }
 
-    public function markAsFailed(string $errorMessage): void
+    public function markAsFailed(string $errorMessage, ?array $errorContext = null): void
     {
         $this->update([
             'status' => Status::Failed,
             'error_message' => $errorMessage,
+            'error_context' => $errorContext,
         ]);
     }
 }
diff --git a/database/migrations/2026_04_01_140435_add_error_context_to_post_platforms_table.php b/database/migrations/2026_04_01_140435_add_error_context_to_post_platforms_table.php
new file mode 100644
index 00000000..2bbd6e59
--- /dev/null
+++ b/database/migrations/2026_04_01_140435_add_error_context_to_post_platforms_table.php
@@ -0,0 +1,22 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::table('post_platforms', function (Blueprint $table) {
+            $table->json('error_context')->nullable()->after('error_message');
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::table('post_platforms', function (Blueprint $table) {
+            $table->dropColumn('error_context');
+        });
+    }
+};