Een beoordelingsstatus ontwerpen voor onzekere gegevens in een PHP-applicatie

Wanneer een applicatie een ambigu gegeven ontvangt, verbergt het afdwingen van een antwoord als ‘geldig’ of ‘ongeldig’ het probleem meestal in plaats van het op te lossen. Dit kan gebeuren met formulieren, integraties of resultaten die door een geautomatiseerd systeem worden voorgesteld: er ontbreekt context om het record veilig te accepteren of af te wijzen. In zulke gevallen moet menselijke beoordeling van onzekere gegevens in PHP een domeinstatus zijn, met expliciete regels, en geen informeel label of geïmproviseerde wachtrij.

Het ontwerp moet vier vragen beantwoorden: wat is ontvangen, wat wordt voorgesteld, wie moet beslissen en wat gebeurt er daarna? Door deze verantwoordelijkheden te scheiden, wordt de workflow eenvoudiger te beheren, fouten te corrigeren en uit te leggen waarom een gegeven op een bepaalde manier is verwerkt.

Classificeer het probleem voordat je statussen aanmaakt

Niet alle gegevens die niet verder kunnen, vereisen menselijke beoordeling. Maak op zijn minst onderscheid tussen de volgende situaties:

• Ongeldig: voldoet niet aan een verifieerbare regel, bijvoorbeeld een formaat dat niet kan worden geïnterpreteerd. Afwijzen of om correctie vragen is dan passend, afhankelijk van de herkomst en het product.
• Onvolledig: een noodzakelijk veld ontbreekt. De actie kan zijn het ontbrekende gegeven op te vragen, het concept te bewaren of op een aanvullende bron te wachten.
• Onzeker: er zijn meerdere plausibele interpretaties of het bewijs volstaat niet om automatisch te beslissen. Beoordeling door een persoon kan nodig zijn.

Beoordeling mag niet de algemene bestemming worden voor elke fout. Als een waarde een ondubbelzinnige beperking schendt, voegt het alleen maar werk toe om deze naar een beoordelingswachtrij te sturen. Wanneer de beslissing daarentegen afhangt van context of beoordelingsvermogen, maakt een status voor menselijke beoordeling het mogelijk de verwerking te stoppen zonder het gegeven voortijdig correct of onjuist te verklaren.

Het is ook verstandig deze workflow te onderscheiden van een importquarantaine. Een quarantaine is doorgaans bedoeld om invoer te isoleren die niet in het systeem mag worden opgenomen, bijvoorbeeld omdat technische of beveiligingscontroles zijn mislukt. Bij beoordeling wordt een zakelijke ambiguïteit opgelost. Een en hetzelfde record kan beide mechanismen doorlopen, maar de doelen, rechten en criteria voor het verlaten ervan zijn niet onderling uitwisselbaar.

Definieer een kleine, expliciete levenscyclus

Begin met de statussen die nodig zijn om het proces te beschrijven, niet met een lijst van alle toekomstige mogelijkheden. Een basislevenscyclus kan er zo uitzien:

• pending_review: wacht op een beslissing.
• confirmed: een persoon bevestigt een bruikbare waarde.
• rejected: de persoon bepaalt dat het gegeven niet mag worden verwerkt.
• reopened of een nieuwe vermelding in de beoordelingsstroom: een eerdere beslissing wordt opnieuw ter discussie gesteld.

Definieer welke transities zijn toegestaan. Een dossier dat op beoordeling wacht, kan bijvoorbeeld worden bevestigd of afgewezen; een afgehandeld dossier mag alleen onder toegestane voorwaarden worden heropend. Sta niet toe dat een willekeurig verzoek de status rechtstreeks in een willekeurige waarde verandert. Een transitie moet een beginstatus, eindstatus, toegestane actor en bijbehorende effecten specificeren.

Leg de reden voor de beslissing en de identiteit van de verantwoordelijke vast. Registreer bij afwijzing van een gegeven een bruikbare reden, niet alleen een boolean. Bewaar bij bevestiging van een interpretatie welke waarde is goedgekeurd en, indien van toepassing, welk bewijs de beslissing heeft onderbouwd. Bepaal per actie of een reden verplicht is en voorkom dat vrije notities onnodige persoonsgegevens bevatten.

Scheid invoer, voorstel en bevestigde waarde

Een robuust ontwerp overschrijft het ontvangen gegeven niet met de interpretatie van een automatisch proces of met de correctie van een persoon. Houd deze concepten van elkaar gescheiden:

• Ontvangen gegeven: de oorspronkelijke invoer en de herkomst ervan, met passende toegangs- en bewaarbeperkingen.
• Voorgestelde interpretatie: een suggestie van regels, een integratie of een assisterend systeem, met de informatie die nodig is om deze te beoordelen.
• Bevestigde waarde: de waarde die de applicatie gebruikt na de geautoriseerde beslissing.

Deze scheiding voorkomt dat een voorstel per ongeluk als waarheid wordt behandeld en maakt het mogelijk te reconstrueren hoe de huidige waarde tot stand is gekomen. Het is niet nodig om elk veld zonder onderscheid te dupliceren: bewaar de gegevens die nodig zijn voor audit en ondersteuning en pas daarbij het beleid voor gegevensbewaring en -bescherming toe. Behandel een score of geautomatiseerde toelichting in een voorstel als context, niet als beslissing.

Leg wijzigingen voor de gewone applicatie vast als gebeurtenissen of onveranderlijke geschiedenisitems: dossier-ID, actie, vorige en nieuwe status, actor, datum en reden. Het model kan daarnaast de huidige status bijhouden om de beoordelingswachtrij eenvoudig te kunnen raadplegen. Een correctie wordt weergegeven door een nieuwe beslissing of heropening die aan de geschiedenis is gekoppeld; het verwijderen van de eerdere beslissing vernietigt de traceerbaarheid.

Implementeer beslissingen in de domeinlaag

Kapsel transities in PHP in een applicatieservice of domeinentiteit in, in plaats van erop te vertrouwen dat elke controller dezelfde regels toepast. Een schematisch voorbeeld:

final class ReviewDecisionService
{
    public function confirm(ReviewCase $case, User $actor, string $value, string $reason): void
    {
        if (!$actor->canReview($case)) {
            throw new DomainException('Geen toegang');
        }

        if (!$case->isPending()) {
            throw new DomainException('Het dossier heeft geen status ‘pending’');
        }

        $case->confirm($value, $actor->id(), $reason);
    }
}

Het fragment laat zien waar regels thuishoren; het is geen volledige implementatie. Valideer ook het formaat en de grenzen van de waarde, controleer of de actor bevoegd is voor dat dossier en registreer de beslissing. Verwar authenticatie — wie de gebruiker is — niet met autorisatie — wat de gebruiker met dat record mag doen. Als er rollen of functiescheiding bestaan, leg die beperkingen dan vast als productregels.

Wanneer de update van het dossier en het schrijven van de geschiedenis consistent moeten zijn, sla ze dan op in een databasetransactie. Als de beslissing externe effecten activeert, zoals een aanroep naar een andere API, ga er dan niet van uit dat de lokale transactie ook dat systeem omvat. Gebruik een betrouwbaar leveringsmechanisme, zoals een transactionele outbox wanneer de architectuur dat vereist, en ontwerp verwerkers zo dat ze herhaalde leveringspogingen aankunnen.

Ontwerp een wachtrij die helpt bij het beslissen

Met een bruikbare wachtrij kunnen dossiers worden geprioriteerd en gevonden zonder hun context te verbergen. Neem relevante filters op — status, datum, type of toewijzing — en toon alleen de informatie die nodig is om het dossier te begrijpen. Maak duidelijk dat een voorstel slechts een voorstel is. Toon de herkomst, de reden voor beoordeling en de beschikbare acties, en presenteer geen bedieningselementen die de gebruiker niet mag uitvoeren.

Toewijzing kan dubbel werk verminderen, maar vervangt autorisatie of bescherming tegen gelijktijdige beslissingen niet. Iemand kan een dossier openen terwijl een ander dit afhandelt voordat de eerste het antwoord indient. Voorkom dat een verouderde pagina een recente wijziging overschrijft met optimistische gelijktijdigheidscontrole: vergelijk bij het opslaan een versienummer of tijdstempel en wijs de verouderde bewerking af, zodat de gebruiker het dossier opnieuw laadt.

Als het proces tijdelijke reserveringen vereist, definieer dan wanneer die verlopen en wat er gebeurt als ze verlopen. Gebruik geen permanente toewijzing als onbedoelde blokkering. Registreer relevante acties om te kunnen uitleggen wie het dossier heeft beoordeeld en dossiers te detecteren die langer dan operationeel aanvaardbaar op beoordeling wachten.

Corrigeer en heropen zonder het verleden te wissen

Een beslissing kan onjuist zijn of veranderen doordat er nieuw bewijs beschikbaar komt. Bepaal wie de beslissing mag heropenen, welke reden die persoon moet opgeven en of de bevestigde waarde niet langer beschikbaar is terwijl deze opnieuw wordt beoordeeld. Het antwoord hangt af van de invloed van de waarde op latere processen; het kan bijvoorbeeld nodig zijn nieuwe acties stop te zetten, maar reeds uitgevoerde effecten niet automatisch te verwijderen.

Bewaar de eerdere beslissing in de geschiedenis en maak een nieuwe versie of een nieuwe beoordelingsgebeurtenis aan. Als correctie van het gegeven vereist dat afhankelijke informatie opnieuw wordt berekend, identificeer die effecten dan expliciet en stel een idempotente procedure in om duplicaten te voorkomen. Een statuscorrectie mag niet doen alsof een externe bewerking al ongedaan is gemaakt.

Test regels, rechten en vervolgeffecten

Tests moeten de volledige workflow en de grenzen ervan afdekken, niet alleen controleren of het formulier wordt opgeslagen. Controleer minimaal het volgende:

• Een dossier met de status ‘pending’ accepteert de bedoelde transities en weigert de overige.
• Actoren zonder de juiste rechten kunnen geen beslissingen nemen, dossiers heropenen of beperkte gegevens raadplegen.
• Elke beslissing bewaart de actor, de reden en de eerdere en nieuwe waarden die bij de beslissing horen, overeenkomstig het vastgestelde beleid.
• Twee gelijktijdige wijzigingen kunnen niet leiden tot het overschrijven van de ene beslissing door een verouderde beslissing.
• Een fout bij het registreren van de geschiedenis laat de status niet bijgewerkt achter zonder traceerbaarheid.
• Een vervolgeffect opnieuw proberen leidt niet tot dubbele bewerkingen of meldingen.

Controleer als ontwerpchecklist of de onzekerheid een herkenbare oorzaak heeft; of het oorspronkelijke gegeven, het voorstel en de bevestigde waarde van elkaar zijn onderscheiden; of elke transitie een recht en reden heeft; of de wachtrij voldoende context biedt; en of heropenen de geschiedenis bewaart en de operationele impact definieert. Als een van deze punten afhankelijk is van informele afspraken, ontbreekt er nog een systeemregel.