Туториали

Laravel CRM: Enrich Leads with Automated Website Technology Summaries

Laravel CRM: Збогатете ги потенцијалните клиенти со автоматизирани прегледи на технологиите што ги користат веб-страниците

Веб-страницата на потенцијален клиент може да ѝ покаже на агенцијата каде би можел да започне корисен разговор: надградба на CMS, интеграција за е-трговија или проблем со одржувањето на frontend-от. Тој контекст станува вреден кога е прикажан покрај потенцијалниот клиент, пред некој да отвори десетина јазичиња во прелистувачот.

Ќе изградиме мал Laravel CRM backend што складира потенцијални клиенти, ги збогатува податоците за нивните веб-страници преку Website Technology Detector API и зачувува читлив извештај за технологиите. Artisan овозможува создавање и прегледување, а закажана команда го обработува збогатувањето независно од интерактивно барање.

Добијте пристап и копирајте го токенот за услугата

  1. Регистрирајте сметка или најавете се.

  2. Отворете ја страницата на услугата Website Technology Detector, изберете еден од достапните планови Free, Plus или Pro и завршете ја активацијата.

  3. Отворете ја официјалната документација. Пронајдете го панелот Service token и копирајте го токенот наменет за таа услуга.

За оваа услуга е потребен токен. Неговото повторно генерирање го поништува претходниот активен токен, па затоа усогласете ја ротацијата со пуштањето во употреба. Автентикацијата поддржува Bearer токени, заглавие X-API-Token или токен како параметар во барањето. Користиме Bearer автентикација за пристапните податоци да не се појавуваат во URL-адресите.

Точната операција е POST https://ai.mihajlo.mk/api/website-technology-detector/v1/detect-technologies. Ова минимално барање го испраќа задолжителното JSON-својство:

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"}'

Заменете го местодржачот локално, без да зачувате вистински токен во историјата на школката или во споделен излез. Прегледајте го документираниот одговор пред да користите кое било конкретно поле како деловно правило.

Создајте го Laravel проектот

Користете PHP 8.3+, Composer и поддршка за SQLite. Оваа имплементација е наменета за Laravel 12 и ги користи неговиот HTTP клиент, заклучувањата преку кешот во базата на податоци, распоредувачот и алатките за тестирање.

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

Задржете ги SQLite базата на податоци и миграциите за кеш-табелите од почетната структура. Додајте ги овие вредности во .env на проектот, кој мора да остане надвор од контрола на верзии:

DB_CONNECTION=sqlite
CACHE_STORE=database
WEBSITE_TECHNOLOGY_TOKEN=YOUR_SERVICE_TOKEN

Додајте го овој запис во низата што ја враќа config/services.php:

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

Датотеките подолу ја сочинуваат целосната интеграција: модел и миграција за потенцијалните клиенти, слој за комуникација со API, тип за неуспех, Artisan команда и функционални тестови. Обработката на десет потенцијални клиенти што се на ред при секое извршување ја одржува архитектурата едноставна. Закажувањето во заднина спречува продавачот да чека на далечинска проверка на веб-страница; за овој обем на работа не е потребна посебна редица.

Зачувајте ги извештаите и јасните состојби на обработка

Заменете го методот up() на генерираната миграција со оваа имплементација. Задржете го генерираниот down(), кој ја брише табелата 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']);
    });
}

Користете го овој модел во 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',
        ];
    }
}

Примен извештај значи дека API вратил структуриран JSON. Тоа не значи дека секоја технологија е потврдена, дека е позната верзијата што недостасува или дека празен извештај докажува оти веб-страницата не користи технологии што можат да се откријат.

Изградете отпорен слој за комуникација со API

Доставената спецификација наведува информации за сигурноста, доказите, верзиите и пренасочувањата, без да ги прецизира нивните JSON-патеки. Погодувањето на патеките би создало нестабилна интеграција. Наместо тоа, нашиот доменски мапер го претвора вистинското стебло на одговорот во означени редови, зачувувајќи ги тие детали каде и да се појавуваат. Тој го задржува оригиналниот структуриран извештај за преглед и никогаш не ги претвора бројчаните вредности за сигурност во неподдржани проценти.

Создајте 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);
    }
}

Создајте 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.',
        ];
    }
}

Вратените клучеви report и summary ѝ припаѓаат на нашата апликација, а не на надворешното API. Ова конзервативно мапирање останува корисно и кога полињата во одговорот се менуваат. Поселективен преглед наменет за продажба треба да се заснова на проверена документација и снимени, санитизирани примероци од одговори според спецификацијата.

HTTP-пренасочувањата се оневозможени за самото API-барање. Информациите за пренасочувањата на проверуваната веб-страница остануваат дел од извештајот. Проверката на големината на одговорот ги ограничува зачуваните податоци по преземањето; таа не е ограничување на меморијата при стриминг.

Обработувајте потенцијални клиенти со ограничен број повторни обиди

Заменете го app/Console/Commands/EnrichLeads.php со следново. Ако недостасуваат пристапни податоци, обработката завршува со грешка пред да се потроши обид. За секој потенцијален клиент се дозволени најмногу пет обиди; неуспешната автентикација и валидација веднаш ги запираат обидите.

<?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;
    }
}

Неуспешните поврзувања и HTTP-грешките што исполнуваат услови доведуваат до зачувани одлуки за повторен обид, наместо процесите да чекаат. Нумеричките вредности и вредностите со HTTP-датум во Retry-After се почитуваат во рамки на период за повторен обид од еден ден. Подолгите чекања бараат проверка од оператор.

Ако процесот се прекине по далечинскиот повик, но пред зачувувањето, откривањето може да се повтори. Овој дизајн овозможува обработката да продолжи по прекин, но не гарантира дека барањата ќе се испратат точно еднаш. Проверете ја преостанатата квота пред повторно да ги обработите неуспешните потенцијални клиенти.

Тестирајте го однесувањето без повикување на услугата

Создајте tests/Feature/LeadTechnologyTest.php. Намерно произволното стебло на одговорот го тестира зачувувањето на структурата, без да се претставува како документација за имињата на надворешните полиња.

<?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);
    }
}

Закажете, обезбедете и проверете

Додајте го ова во routes/console.php:

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

Пуштете ја апликацијата во употреба со еден распоредувач, трајна SQLite меморија и споделен кеш во базата на податоци. Извршете ги овие проверки пред да го овозможите распоредувачот:

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

Поставете го вообичаениот запис за распоредувачот што се извршува еднаш во минута, заменувајќи ја патеката до проектот:

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

Поднесувајте само јавни веб-страници што сте овластени да ги проверувате. Валидацијата на URL ја проверува синтаксата; таа не утврдува дали DNS-одредиштата или пренасочувањата се јавни. Детекторот мора самиот да ги применува своите ограничувања за излезен мрежен сообраќај. Laravel комуницира само со фиксната API-крајна точка.

Контролирајте го пристапот до извештаите заедно со пристапот до податоците за потенцијалните клиенти. Ако подоцна прикажувате прегледи во Blade, користете интерполација со екранирање. Исклучете ги заглавијата за авторизација и телата на одговорите од HTTP-следењето. Следете колку долго потенцијалните клиенти чекаат на обработка, неуспешните состојби и настаните rate_limited; успешното завршување на распоредувачот не значи дека обработката на секој потенцијален клиент успеала.

Ако одговорите 401 или 403 продолжат да се појавуваат, проверете ги активацијата и ротацијата на токенот, а потоа повторно изградете ја кешираната конфигурација. При грешки поврзани со квотата, проверете го планот пред повторен обид. Невалиден JSON или неочекувана структура бараат проверка на санитизиран одговор според официјалната документација.

  • Потврдете дека вистински потенцијален клиент достигнува состојба received и дека неговиот извештај ги вклучува достапните докази, сигурноста, верзиите и пренасочувањата.
  • Проверете дали неуспешната автентикација ги запира повторните обиди и дали ограничувањата на бројот на барања ја одложуваат обработката.
  • Потврдете дека распоредувачот работи и дека времето на чекање за обработка се намалува.
  • Проверете дали пристапните податоци и необработените извештаи остануваат надвор од дневниците.

Корисниот резултат е подобар прв разговор. Зачувајте ги доказите заедно со извештајот, задржете ја неизвесноста и дозволете прегледот на технологиите да ѝ даде на агенцијата причина да постави попрецизно прашање.

Портрет на автор на блогот

Mihajlo

Јас сум Михајло - развивач поттикнат од љубопитност, дисциплина и постојаната желба да создадам нешто значајно. Споделувам увиди, упатства и бесплатни услуги за да им помогнам на другите да ја поедностават својата работа и да растат во постојано развивачкиот свет на софтверот и вештачката интелигенција.