Vodiči

Laravel CRM: Enrich Leads with Automated Website Technology Summaries

Laravel CRM: Obogatite potencijalne klijente automatiziranim sažecima tehnologija web-stranica

Web-mjesto potencijalnog klijenta može agenciji pokazati gdje bi koristan razgovor mogao započeti: nadogradnjom CMS-a, integracijom sustava za e-trgovinu ili problemom s održavanjem frontenda. Taj kontekst postaje vrijedan kada je prikazan uz podatke o potencijalnom klijentu, prije nego što netko otvori desetak kartica u pregledniku.

Izradit ćemo mali CRM backend u Laravelu koji pohranjuje podatke o potencijalnim klijentima, obogaćuje ih podacima o njihovim web-mjestima putem API-ja Website Technology Detector i sprema čitljivo izvješće o tehnologijama. Artisan omogućuje stvaranje i pregled zapisa; zakazana naredba obavlja obogaćivanje neovisno o interaktivnom zahtjevu.

Pristupite usluzi i kopirajte token

  1. Registrirajte račun ili se prijavite.

  2. Otvorite stranicu usluge Website Technology Detector, odaberite jedan od dostupnih paketa Free, Plus ili Pro i dovršite aktivaciju.

  3. Otvorite službenu dokumentaciju. Pronađite ploču Service token i kopirajte token za tu uslugu.

Za ovu je uslugu potreban token. Njegovo ponovno generiranje opoziva prethodni aktivni token, stoga zamjenu uskladite s implementacijom. Autentifikacija podržava Bearer tokene, zaglavlje X-API-Token ili token kao parametar upita. Koristimo Bearer autentifikaciju kako pristupni podaci ne bi bili u URL-ovima.

Točna je operacija POST https://ai.mihajlo.mk/api/website-technology-detector/v1/detect-technologies. Ovaj minimalni zahtjev šalje obavezno JSON svojstvo:

curl --request POST \
  'https://ai.mihajlo.mk/api/website-technology-detector/v1/detect-technologies' \
  --header 'Authorization: Bearer YOUR_SERVICE_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{"url":"https://example.com"}'

Zamijenite rezervirano mjesto lokalno, bez spremanja stvarnog tokena u povijest ljuske ili dijeljeni izlaz. Proučite dokumentirani odgovor prije nego što neko polje upotrijebite kao temelj poslovnog pravila.

Stvorite projekt u Laravelu

Koristite PHP 8.3+, Composer i podršku za SQLite. Ova je implementacija namijenjena Laravelu 12 i koristi njegov HTTP klijent, zaključavanja predmemorije u bazi podataka, planer i mogućnosti testiranja.

composer create-project laravel/laravel agency-crm "^12.0"
cd agency-crm
php artisan make:model Lead -m
php artisan make:command EnrichLeads

Zadržite migracije za SQLite bazu podataka i tablicu predmemorije iz početnog predloška. Dodajte ove vrijednosti u projektnu datoteku .env, koja mora ostati izvan sustava za upravljanje verzijama:

DB_CONNECTION=sqlite
CACHE_STORE=database
WEBSITE_TECHNOLOGY_TOKEN=YOUR_SERVICE_TOKEN

Dodajte ovaj unos u polje koje vraća config/services.php:

'website_technology' => [
    'token' => env('WEBSITE_TECHNOLOGY_TOKEN'),
],

Datoteke u nastavku čine potpunu integraciju: model potencijalnog klijenta i migraciju, sloj za komunikaciju s API-jem, vrstu pogreške, Artisan naredbu i funkcionalne testove. Obrada deset potencijalnih klijenata koji su na redu po pokretanju održava arhitekturu jednostavnom. Pozadinsko zakazivanje uklanja potrebu da prodajni djelatnik čeka udaljenu provjeru web-mjesta; zaseban red čekanja nije potreban za ovaj opseg posla.

Trajno pohranite izvješća i izričita stanja obrade

Zamijenite metodu up() generirane migracije ovom implementacijom. Zadržite generiranu metodu down(), koja briše leads.

public function up(): void
{
    Schema::create('leads', function (Blueprint $table) {
        $table->id();
        $table->string('website_url', 2048);
        $table->string('technology_state')->default('pending');
        $table->unsignedInteger('technology_attempts')->default(0);
        $table->timestamp('technology_next_at')->nullable();
        $table->text('technology_summary')->nullable();
        $table->json('technology_report')->nullable();
        $table->string('technology_error')->nullable();
        $table->timestamps();
        $table->index(['technology_state', 'technology_next_at']);
    });
}

Upotrijebite ovaj model u app/Models/Lead.php:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Lead extends Model
{
    protected $fillable = ['website_url'];

    protected function casts(): array
    {
        return [
            'technology_report' => 'array',
            'technology_next_at' => 'datetime',
        ];
    }
}

Primljeno izvješće znači da je API vratio strukturirani JSON. To ne znači da je svaka tehnologija sa sigurnošću utvrđena, da je poznata verzija koja nedostaje ili da prazno izvješće dokazuje da web-mjesto ne koristi nijednu tehnologiju koju je moguće otkriti.

Izradite otporan sloj za komunikaciju s API-jem

Priloženi ugovor navodi pouzdanost, dokaze, verzije i informacije o preusmjeravanjima, ali ne određuje njihove JSON putanje. Nagađanje putanja dovelo bi do krhke integracije. Naš mehanizam za mapiranje u domenu umjesto toga prikazuje stvarno stablo odgovora kao označene retke, čuvajući te pojedinosti gdje god se pojavljuju. Zadržava izvorno strukturirano izvješće za pregled i nikada ne pretvara vrijednosti pouzdanosti u neutemeljene postotke.

Stvorite app/Services/DetectionFailure.php:

<?php

namespace App\Services;

final class DetectionFailure extends \RuntimeException
{
    public function __construct(
        string $reason,
        public readonly ?int $retryAfter = null,
    ) {
        parent::__construct($reason);
    }
}

Stvorite app/Services/TechnologyDetector.php:

<?php

namespace App\Services;

use Illuminate\Http\Client\ConnectionException;
use Illuminate\Support\Facades\Http;

final class TechnologyDetector
{
    public function detect(string $url): array
    {
        try {
            $response = Http::withToken(
                config('services.website_technology.token')
            )->acceptJson()->connectTimeout(5)->timeout(25)
                ->withOptions(['allow_redirects' => false])
                ->post(
                    'https://ai.mihajlo.mk/api/website-technology-detector/v1/detect-technologies',
                    ['url' => $url]
                );
        } catch (ConnectionException) {
            throw new DetectionFailure('connection_failure', 60);
        }

        $status = $response->status();

        if ($status === 429) {
            $header = $response->header('Retry-After');
            $seconds = ctype_digit($header)
                ? (float) $header
                : max(0, (strtotime($header) ?: time()) - time());

            if ($seconds > 86400) {
                throw new DetectionFailure('quota_wait_exceeds_one_day');
            }

            throw new DetectionFailure(
                'rate_limited',
                max(60, (int) $seconds)
            );
        }

        if ($status === 408 || $response->serverError()) {
            throw new DetectionFailure("http_{$status}", 60);
        }

        if (! $response->successful()) {
            throw new DetectionFailure("http_{$status}");
        }

        if (strlen($response->body()) > 262144) {
            throw new DetectionFailure('report_too_large');
        }

        try {
            $report = json_decode(
                $response->body(), true, 64, JSON_THROW_ON_ERROR
            );
        } catch (\JsonException) {
            throw new DetectionFailure('invalid_json');
        }

        if (! is_array($report)) {
            throw new DetectionFailure('unexpected_report_shape');
        }

        $lines = [];
        $walk = function (array $node, string $path = 'Report')
            use (&$walk, &$lines): void {
                foreach ($node as $key => $value) {
                    if (count($lines) >= 200) {
                        return;
                    }

                    $label = is_int($key)
                        ? 'Item '.($key + 1)
                        : ucwords(str_replace(['_', '-'], ' ', $key));
                    $label = preg_replace('/[\x00-\x1F\x7F]/', ' ', $label);
                    $name = "{$path} / {$label}";

                    if (is_array($value) && $value !== []) {
                        $walk($value, $name);
                    } else {
                        $lines[] = $name.': '.json_encode(
                            $value,
                            JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE
                        );
                    }
                }
            };

        $walk($report);

        if (count($lines) === 200) {
            $lines[] = 'Display limit reached; inspect the stored report.';
        }

        return [
            'report' => $report,
            'summary' => implode("\n", $lines)
                ?: 'No report details returned; technology presence is unknown.',
        ];
    }
}

Vraćeni ključevi report i summary pripadaju našoj aplikaciji, a ne vanjskom API-ju. Ovo konzervativno mapiranje ostaje korisno i kada se polja odgovora mijenjaju. Selektivniji sažetak usmjeren na prodaju trebao bi se temeljiti na provjerenoj dokumentaciji i zabilježenim, pročišćenim primjerima ugovora.

HTTP preusmjeravanja onemogućena su za sam API zahtjev. Informacije o preusmjeravanjima pregledanog web-mjesta ostaju dio izvješća. Provjera veličine odgovora ograničava količinu pohranjenih podataka nakon preuzimanja; ona ne ograničava upotrebu memorije tijekom prijenosa.

Obradite potencijalne klijente uz ograničen broj ponovnih pokušaja

Zamijenite app/Console/Commands/EnrichLeads.php sljedećim sadržajem. Ako pristupni podaci nedostaju, postupak se prekida prije nego što se potroši pokušaj. Za svakog potencijalnog klijenta dopušteno je najviše pet pokušaja; pogreške autentifikacije i provjere valjanosti odmah zaustavljaju postupak.

<?php

namespace App\Console\Commands;

use App\Models\Lead;
use App\Services\DetectionFailure;
use App\Services\TechnologyDetector;
use Illuminate\Console\Command;
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\Facades\Validator;

class EnrichLeads extends Command
{
    protected $signature = 'crm:tech {--add=} {--show=}';
    protected $description = 'Create, inspect, or enrich CRM leads';

    public function handle(TechnologyDetector $detector): int
    {
        if ($url = $this->option('add')) {
            Validator::make(['url' => $url], [
                'url' => ['required', 'url:http,https', 'max:2048'],
            ])->validate();

            $parts = parse_url($url);
            if (isset($parts['user']) || isset($parts['pass'])) {
                $this->error('URLs must not contain credentials.');
                return self::FAILURE;
            }

            $this->info((string) Lead::create(['website_url' => $url])->id);
            return self::SUCCESS;
        }

        if ($id = $this->option('show')) {
            $lead = Lead::findOrFail($id);
            $this->line($lead->technology_state);
            $this->line($lead->technology_summary
                ?? $lead->technology_error ?? 'Awaiting enrichment');
            return self::SUCCESS;
        }

        if (! config('services.website_technology.token')) {
            $this->error('Missing service token.');
            return self::FAILURE;
        }

        $ids = Lead::where('technology_state', 'pending')
            ->where(fn ($q) => $q->whereNull('technology_next_at')
                ->orWhere('technology_next_at', '<=', now()))
            ->orderBy('id')->limit(10)->pluck('id');

        foreach ($ids as $id) {
            Cache::lock("lead-technology:{$id}", 120)->get(
                function () use ($id, $detector): void {
                    $lead = Lead::findOrFail($id);
                    if ($lead->technology_state !== 'pending'
                        || $lead->technology_next_at?->isFuture()) {
                        return;
                    }

                    $attempt = $lead->technology_attempts + 1;
                    $lead->forceFill([
                        'technology_attempts' => $attempt,
                    ])->save();

                    try {
                        $result = $detector->detect($lead->website_url);
                        $changes = [
                            'technology_state' => 'received',
                            'technology_summary' => $result['summary'],
                            'technology_report' => $result['report'],
                            'technology_error' => null,
                            'technology_next_at' => null,
                        ];
                    } catch (DetectionFailure $e) {
                        $retry = $e->retryAfter !== null && $attempt < 5;
                        $delay = max(
                            $e->retryAfter ?? 0,
                            min(3600, 60 * 2 ** min($attempt - 1, 6))
                                + random_int(0, 30)
                        );
                        $changes = [
                            'technology_state' => $retry ? 'pending' : 'failed',
                            'technology_error' => $e->getMessage(),
                            'technology_next_at' => $retry
                                ? now()->addSeconds($delay) : null,
                        ];
                    }

                    $lead->forceFill($changes)->save();
                    Log::info('lead_technology.result', [
                        'lead_id' => $id,
                        'attempt' => $attempt,
                        'state' => $lead->technology_state,
                        'reason' => $lead->technology_error,
                    ]);
                }
            );
        }

        return self::SUCCESS;
    }
}

Pogreške povezivanja i odgovarajuće HTTP pogreške pretvaraju se u pohranjene odluke o ponovnom pokušaju, umjesto u procese koji čekaju. Brojčane vrijednosti i vrijednosti zaglavlja Retry-After u obliku HTTP datuma poštuju se unutar razdoblja za ponovni pokušaj od jednog dana. Dulja čekanja zahtijevaju pregled operatera.

Pad sustava nakon udaljenog poziva, ali prije spremanja, može dovesti do ponavljanja otkrivanja. Ovaj dizajn omogućuje oporavak obrade, ali ne jamči da će zahtjevi biti poslani točno jednom. Provjerite preostalu kvotu prije ponovnog pokretanja obrade neuspjelih zapisa o potencijalnim klijentima.

Testirajte ponašanje bez pozivanja usluge

Stvorite tests/Feature/LeadTechnologyTest.php. Namjerno proizvoljno stablo odgovora testira očuvanje strukture bez pretvaranja da dokumentira nazive polja vanjskog sustava.

<?php

namespace Tests\Feature;

use App\Models\Lead;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Illuminate\Support\Facades\Http;
use Tests\TestCase;

class LeadTechnologyTest extends TestCase
{
    use RefreshDatabase;

    public function test_report_is_saved_and_request_is_authenticated(): void
    {
        config(['services.website_technology.token' => 'test-placeholder']);
        Http::preventStrayRequests();
        Http::fake(['*' => Http::response([
            ['ExampleCMS', 0.8, ['HTML marker'], '1.2', 'https://example.com'],
        ])]);

        $lead = Lead::create(['website_url' => 'https://example.com']);
        $this->artisan('crm:tech')->assertSuccessful();

        $this->assertSame('received', $lead->fresh()->technology_state);
        $this->assertStringContainsString(
            'HTML marker', $lead->fresh()->technology_summary
        );

        Http::assertSent(fn ($request) =>
            $request->method() === 'POST'
            && $request->url() ===
                'https://ai.mihajlo.mk/api/website-technology-detector/v1/detect-technologies'
            && $request->hasHeader('Authorization', 'Bearer test-placeholder')
            && $request['url'] === 'https://example.com'
        );
    }

    public function test_rate_limit_defers_and_authentication_failure_stops(): void
    {
        config(['services.website_technology.token' => 'test-placeholder']);
        Http::fakeSequence()
            ->push([], 429, ['Retry-After' => '120'])
            ->push([], 401);

        $lead = Lead::create(['website_url' => 'https://example.com']);
        $this->artisan('crm:tech')->assertSuccessful();
        $this->assertTrue(
            $lead->fresh()->technology_next_at->gte(now()->addSeconds(120))
        );

        $this->artisan('crm:tech')->assertSuccessful();
        Http::assertSentCount(1);

        $this->travel(3)->minutes();
        $this->artisan('crm:tech')->assertSuccessful();
        $this->assertSame('failed', $lead->fresh()->technology_state);
        $this->assertSame('http_401', $lead->fresh()->technology_error);
    }
}

Zakažite, osigurajte i provjerite

Dodajte ovo u routes/console.php:

\Illuminate\Support\Facades\Schedule::command('crm:tech')
    ->everyMinute()
    ->withoutOverlapping(10);

Implementirajte rješenje s jednim planerom, trajnom pohranom za SQLite i dijeljenom predmemorijom u bazi podataka. Prije omogućavanja planera pokrenite ove provjere:

php artisan migrate --force
php artisan test
php artisan config:cache
php artisan crm:tech --add=https://example.com
php artisan crm:tech
php artisan crm:tech --show=1

Postavite uobičajeni unos za pokretanje planera jednom u minuti, uz zamjenu putanje projekta:

* * * * * cd /absolute/path/agency-crm && php artisan schedule:run

Šaljite samo javna web-mjesta za čiji pregled imate ovlaštenje. Provjera valjanosti URL-a provjerava sintaksu; ona ne utvrđuje jesu li DNS odredišta ili preusmjeravanja javni. Detektor mora provoditi vlastita ograničenja izlaznog mrežnog prometa. Laravel kontaktira samo fiksnu krajnju točku API-ja.

Pristup izvješćima ograničite jednako kao i pristup podacima o potencijalnim klijentima. Ako kasnije budete prikazivali sažetke u Bladeu, koristite interpolaciju s odgovarajućim kodiranjem znakova. Izuzmite autorizacijska zaglavlja i tijela odgovora iz praćenja HTTP prometa. Pratite koliko dugo zapisi o potencijalnim klijentima čekaju obradu, neuspjela stanja i događaje rate_limited; uspješan završetak planera ne znači da je obrada svakog potencijalnog klijenta uspjela.

Ako se odgovori 401 ili 403 stalno pojavljuju, provjerite aktivaciju i zamjenu tokena, a zatim ponovno izgradite predmemoriranu konfiguraciju. U slučaju pogrešaka zbog kvote provjerite paket prije ponovnog pokušaja. Nevaljani JSON ili neočekivane strukture zahtijevaju pregled pročišćenog odgovora u odnosu na službenu dokumentaciju.

  • Potvrdite da stvarni zapis o potencijalnom klijentu doseže stanje received i da njegovo izvješće uključuje dostupne dokaze, pouzdanost, verzije i preusmjeravanja.
  • Provjerite zaustavlja li neuspjela autentifikacija ponovne pokušaje i odgađaju li ograničenja broja zahtjeva obradu.
  • Potvrdite da se planer pokreće i da se smanjuje vrijeme čekanja na obradu.
  • Provjerite da pristupni podaci i sirova izvješća ne završavaju u zapisnicima.

Koristan je rezultat kvalitetniji prvi razgovor. Zadržite priložene dokaze, očuvajte informacije o nesigurnosti i dopustite da sažetak tehnologija agenciji pruži povod za preciznije pitanje.

Portret autora bloga

Mihajlo

Ja sam Mihajlo — programer vođen znatiželjom, disciplinom i stalnom željom da stvorim nešto smisleno. Dijelim uvide, tutorijale i besplatne usluge kako bih pomogao drugima da pojednostave svoj rad i rastu u svijetu softvera i umjetne inteligencije koji se neprestano razvija.