crewli/api/app/Services/FormBuilder/FormFieldService.php

<?php

declare(strict_types=1);

namespace App\Services\FormBuilder;

use App\Enums\FormBuilder\FormFieldType;
use App\Exceptions\FormBuilder\BindingChangeBlockedException;
use App\Exceptions\FormBuilder\CyclicDependencyException;
use App\Exceptions\FormBuilder\DestructiveConfirmationRequiredException;
use App\Exceptions\FormBuilder\FrozenSchemaException;
use App\Jobs\FormBuilder\BackfillFormValueIndexedJob;
use App\Models\FormBuilder\FormField;
use App\Models\FormBuilder\FormFieldLibrary;
use App\Models\FormBuilder\FormSchema;
use App\Models\FormBuilder\FormSchemaSection;
use App\Models\FormBuilder\FormSubmission;
use App\Models\FormBuilder\FormValue;
use Illuminate\Support\Facades\DB;

/**
 * FormField CRUD + reorder + library insertion + binding safety
 * (ARCH §4.2, §6.5, §8, §4.8.1, §7.2).
 */
final class FormFieldService
{
    public function __construct(
        private readonly FormSchemaService $schemaService,
        private readonly FormFieldBindingService $bindingService,
        private readonly FormFieldValidationRuleService $validationRuleService,
        private readonly FormFieldConfigService $configService,
        private readonly FormFieldConditionalLogicService $conditionalLogicService,
        private readonly FormFieldOptionService $optionService,
    ) {}

    public function create(FormSchema $schema, array $data): FormField
    {
        $this->assertNotFrozen($schema);

        $data['form_schema_id'] = $schema->id;
        $data['sort_order'] ??= $this->nextSortOrder($schema);

        $bindingSpec = $this->extractBindingSpec($data);
        $validationRuleSpecs = $this->extractValidationRuleSpecs($data);
        $optionSpecs = $this->extractOptionSpecs($data);
        [$conditionalTree, $conditionalProvided] = $this->extractConditionalLogicTree($data);

        /** @var FormField $field */
        $field = FormField::create($data);

        if ($bindingSpec !== null) {
            $this->bindingService->replaceBindings($field, [$bindingSpec]);
        }

        if ($validationRuleSpecs !== null) {
            $this->validationRuleService->replaceRules($field, $validationRuleSpecs);
        }

        if ($optionSpecs !== null) {
            $this->optionService->replaceOptions($field, $optionSpecs);
        }

        if ($conditionalProvided) {
            // Cycle check runs inside the service — reads the schema's
            // relational adjacency and throws on a back-edge.
            if ($conditionalTree !== null) {
                $this->conditionalLogicService->assertNoCycles($field, $conditionalTree);
            }
            $this->conditionalLogicService->replaceLogic($field, $conditionalTree);
        }

        $this->schemaService->bumpVersion($schema);
        $field->logFieldChange('field.created');

        if ($field->is_filterable) {
            BackfillFormValueIndexedJob::dispatch($field->id)->onQueue('default');
        }

        return $field->refresh();
    }

    public function update(FormField $field, array $data, bool $forceBindingChange = false): FormField
    {
        $schema = $field->schema;
        $this->assertNotFrozenForStructural($schema, $data);

        $bindingProvided = array_key_exists('binding', $data);
        $rawBinding = $bindingProvided ? $data['binding'] : null;
        $bindingSpec = $bindingProvided ? $this->extractBindingSpec($data) : null;

        $validationRulesProvided = array_key_exists('validation_rules', $data);
        $validationRuleSpecs = $validationRulesProvided ? $this->extractValidationRuleSpecs($data) : null;

        $optionsProvided = array_key_exists('options', $data);
        $optionSpecs = $optionsProvided ? $this->extractOptionSpecs($data) : null;

        [$conditionalTree, $conditionalProvided] = $this->extractConditionalLogicTree($data);

        $currentBindingShape = $this->bindingService->toJsonShape($field->bindings()->first());
        $currentConditionalShape = $this->conditionalLogicService->toJsonShape($field->rootConditionalLogicGroup());
        $currentOptionsShape = $this->optionService->toJsonShape($field->options()->get());

        if ($bindingProvided && $this->bindingChanged($currentBindingShape, $rawBinding)) {
            $this->assertBindingChangeAllowed($field, $forceBindingChange);
        }

        if ($conditionalProvided && $conditionalTree !== null) {
            $this->conditionalLogicService->assertNoCycles($field, $conditionalTree);
        }

        $before = [
            'binding' => $currentBindingShape,
            'is_filterable' => $field->is_filterable,
            'is_pii' => $field->is_pii,
            'field_type' => $field->field_type,
        ];

        $field->fill($data);
        $field->save();

        if ($bindingProvided) {
            $this->bindingService->replaceBindings($field, $bindingSpec === null ? [] : [$bindingSpec]);
        }

        if ($validationRulesProvided) {
            $this->validationRuleService->replaceRules($field, $validationRuleSpecs ?? []);
        }

        if ($optionsProvided) {
            $this->optionService->replaceOptions($field, $optionSpecs ?? []);
        }

        if ($conditionalProvided) {
            $this->conditionalLogicService->replaceLogic($field, $conditionalTree);
        }

        $this->schemaService->bumpVersion($schema);

        $newConditionalShape = $this->conditionalLogicService->toJsonShape($field->fresh()?->rootConditionalLogicGroup());
        $new = [
            'binding' => $this->bindingService->toJsonShape($field->bindings()->first()),
            'is_filterable' => $field->is_filterable,
            'is_pii' => $field->is_pii,
            'field_type' => $field->field_type,
        ];

        // ARCH §8.6: include conditional_logic in the field.updated diff only
        // when the tree actually changed. Bare label/sort_order updates and
        // payloads that did not touch conditional_logic must not carry the
        // key — otherwise downstream activity-log consumers see noise.
        if ($currentConditionalShape !== $newConditionalShape) {
            $before['conditional_logic'] = $currentConditionalShape;
            $new['conditional_logic'] = $newConditionalShape;
        }

        // §17.6.3 dual emit pattern: include options in the field.updated diff
        // only when the option set actually changed (byte-equal JSON compare).
        // The semantic field.options_replaced event from
        // FormFieldOptionService::replaceOptions stays in addition to this.
        $newOptionsShape = $this->optionService->toJsonShape($field->fresh()?->options()->get() ?? collect());
        if (json_encode($currentOptionsShape) !== json_encode($newOptionsShape)) {
            $before['options'] = $currentOptionsShape;
            $new['options'] = $newOptionsShape;
        }

        $field->logFieldChange('field.updated', [
            'old' => $before,
            'new' => $new,
        ]);

        if ($before['is_filterable'] !== $field->is_filterable) {
            BackfillFormValueIndexedJob::dispatch($field->id)->onQueue('default');
        }

        return $field->refresh();
    }

    /**
     * Extract the `validation_rules` key from the request data array and
     * return it as the service-layer spec list. The JSON column is no
     * longer written (WS-5b commit 3) — writes go through
     * `FormFieldValidationRuleService::replaceRules` after the FormField
     * row is created/updated.
     *
     * Returns `null` when the key was absent (no change requested), or an
     * empty list when the caller explicitly cleared rules. Callers
     * distinguish via `array_key_exists('validation_rules', $data)`
     * BEFORE invoking this helper.
     *
     * @param  array<string, mixed>  $data
     * @return list<array<string, mixed>>|null
     */
    private function extractValidationRuleSpecs(array &$data): ?array
    {
        if (! array_key_exists('validation_rules', $data)) {
            return null;
        }
        $raw = $data['validation_rules'];
        unset($data['validation_rules']);
        if (! is_array($raw)) {
            return [];
        }

        /** @var list<array<string, mixed>> $raw */
        return array_values($raw);
    }

    /**
     * Extract the `options` key from the request data array and return
     * it as the service-layer spec list. The JSON column is gone post
     * WS-5d commit 3 — writes go through
     * `FormFieldOptionService::replaceOptions` after the FormField row
     * is created/updated.
     *
     * @param  array<string, mixed>  $data
     * @return list<array<string, mixed>>|null
     */
    private function extractOptionSpecs(array &$data): ?array
    {
        if (! array_key_exists('options', $data)) {
            return null;
        }
        $raw = $data['options'];
        unset($data['options']);
        if (! is_array($raw)) {
            return [];
        }

        /** @var list<array<string, mixed>> $raw */
        return array_values($raw);
    }

    /**
     * @param  array<string, mixed>  $data
     * @return array{target_entity:string,target_attribute:string,mode:string,sync_direction?:?string}|null
     */
    private function extractBindingSpec(array &$data): ?array
    {
        if (! array_key_exists('binding', $data)) {
            return null;
        }
        $raw = $data['binding'];
        unset($data['binding']);
        if (! is_array($raw) || $raw === []) {
            return null;
        }

        return [
            'target_entity' => (string) ($raw['entity'] ?? ''),
            'target_attribute' => (string) ($raw['column'] ?? ''),
            'mode' => (string) ($raw['mode'] ?? ''),
            'sync_direction' => isset($raw['sync_direction']) ? (string) $raw['sync_direction'] : null,
        ];
    }

    /**
     * @param  array<string, mixed>|null  $current  Pre-WS-5a ARCH §6.3 shape
     * @param  array<string, mixed>|null  $next
     */
    private function bindingChanged(?array $current, ?array $next): bool
    {
        $normalise = static function (?array $value): array {
            if ($value === null || $value === []) {
                return [];
            }

            return [
                'mode' => (string) ($value['mode'] ?? ''),
                'entity' => (string) ($value['entity'] ?? ''),
                'column' => (string) ($value['column'] ?? ''),
                'sync_direction' => (string) ($value['sync_direction'] ?? ''),
            ];
        };

        return $normalise($current) !== $normalise($next);
    }

    public function delete(FormField $field, ?string $confirmedName = null): void
    {
        $schema = $field->schema;
        $this->assertNotFrozen($schema);

        $hasValues = FormValue::query()->where('form_field_id', $field->id)->exists();
        if ($hasValues && $confirmedName !== $field->label) {
            throw DestructiveConfirmationRequiredException::forName($field->label);
        }

        DB::transaction(function () use ($field, $schema): void {
            $field->logFieldChange('field.deleted');
            $field->delete();
            $this->schemaService->bumpVersion($schema);
        });
    }

    /**
     * @param  array<int, string>  $orderedFieldIds
     */
    public function reorder(FormSchema $schema, array $orderedFieldIds): void
    {
        DB::transaction(function () use ($schema, $orderedFieldIds): void {
            foreach ($orderedFieldIds as $index => $fieldId) {
                FormField::query()
                    ->where('form_schema_id', $schema->id)
                    ->whereKey($fieldId)
                    ->update(['sort_order' => $index]);
            }
            $this->schemaService->bumpVersion($schema);
        });
    }

    public function insertFromLibrary(FormSchema $schema, FormFieldLibrary $library, array $overrides = []): FormField
    {
        $this->assertNotFrozen($schema);

        $data = array_merge([
            'form_schema_id' => $schema->id,
            'library_field_id' => $library->id,
            'field_type' => $library->field_type,
            'slug' => $this->ensureUniqueSlug($schema, $library->slug),
            'label' => $library->label,
            'help_text' => $library->help_text,
            'is_required' => (bool) $library->default_is_required,
            'is_filterable' => (bool) $library->default_is_filterable,
            'translations' => $library->translations,
            'sort_order' => $this->nextSortOrder($schema),
        ], $overrides);

        // Options: post-WS-5d row-clone via the service. The legacy JSON
        // column is no longer copied.
        unset($data['options']);

        if (! isset($data['slug']) || $data['slug'] === '') {
            $data['slug'] = $this->ensureUniqueSlug($schema, $library->slug);
        } else {
            $data['slug'] = $this->ensureUniqueSlug($schema, $data['slug']);
        }

        /** @var FormField $field */
        $field = FormField::create($data);

        $this->bindingService->copyBindings($library, $field);
        $this->validationRuleService->copyRules($library, $field);
        $this->configService->copyConfigs($library, $field);
        $this->optionService->copyOptions($library, $field);

        FormFieldLibrary::query()->whereKey($library->id)->increment('usage_count');

        $this->schemaService->bumpVersion($schema);
        $field->logFieldChange('field.inserted_from_library', ['library_field_id' => $library->id]);

        if ($field->is_filterable) {
            BackfillFormValueIndexedJob::dispatch($field->id)->onQueue('default');
        }

        return $field->refresh();
    }

    private function assertBindingChangeAllowed(FormField $field, bool $forceBindingChange): void
    {
        $submittedCount = FormSubmission::query()
            ->where('form_schema_id', $field->form_schema_id)
            ->where('status', 'submitted')
            ->count();

        if ($submittedCount > 0 && ! $forceBindingChange) {
            throw BindingChangeBlockedException::forField($field->id, $submittedCount);
        }
    }

    private function assertNotFrozen(FormSchema $schema): void
    {
        if ($schema->freeze_on_submit && $this->schemaService->hasSubmittedSubmissions($schema)) {
            throw FrozenSchemaException::forSchema($schema->id);
        }
    }

    private function assertNotFrozenForStructural(FormSchema $schema, array $data): void
    {
        $structuralKeys = ['field_type', 'binding', 'options', 'validation_rules', 'is_required', 'slug'];
        foreach ($structuralKeys as $key) {
            if (array_key_exists($key, $data)) {
                $this->assertNotFrozen($schema);

                return;
            }
        }
    }

    /**
     * Extract `conditional_logic` from incoming write-data. Returns a
     * tuple `[tree, wasProvided]`: `tree` is the root-group spec (or
     * null when the caller cleared logic); `wasProvided` is false when
     * the key was absent from the request — we must distinguish "no
     * change requested" from "cleared to null".
     *
     * Strips the `show_when` wrapper (controllers submit the outer JSON
     * shape as-is) and rewrites nested `{"all"|"any": [...]}` nodes into
     * the service's internal `{"operator", "children"}` form.
     *
     * @param  array<string, mixed>  $data
     * @return array{0: array<string, mixed>|null, 1: bool}
     */
    private function extractConditionalLogicTree(array &$data): array
    {
        if (! array_key_exists('conditional_logic', $data)) {
            return [null, false];
        }
        $raw = $data['conditional_logic'];
        unset($data['conditional_logic']);

        if ($raw === null || $raw === [] || ! is_array($raw)) {
            return [null, true];
        }

        if (isset($raw['show_when']) && is_array($raw['show_when'])) {
            /** @var array<string, mixed> $rootGroup */
            $rootGroup = $raw['show_when'];
        } else {
            /** @var array<string, mixed> $rootGroup */
            $rootGroup = $raw;
        }

        return [FormFieldConditionalLogicService::normaliseLegacyShape($rootGroup), true];
    }

    /**
     * @return array<int, string>
     */
    public function detectSectionCycle(FormSchema $schema, FormSchemaSection $section, ?string $dependsOnId): void
    {
        if ($dependsOnId === null) {
            return;
        }

        $chain = [];
        $current = $dependsOnId;
        $safety = 100;
        while ($current !== null && $safety-- > 0) {
            if ($current === $section->id) {
                throw CyclicDependencyException::forSection($section->id);
            }
            $chain[] = $current;
            $parent = FormSchemaSection::query()
                ->whereKey($current)
                ->value('depends_on_section_id');
            $current = $parent !== null ? (string) $parent : null;
        }
    }

    private function nextSortOrder(FormSchema $schema): int
    {
        $max = (int) FormField::query()
            ->where('form_schema_id', $schema->id)
            ->max('sort_order');

        return $max + 1;
    }

    private function ensureUniqueSlug(FormSchema $schema, string $slug): string
    {
        $base = \Illuminate\Support\Str::slug($slug) ?: 'veld';
        $candidate = $base;
        $i = 2;
        while (FormField::query()
            ->where('form_schema_id', $schema->id)
            ->where('slug', $candidate)
            ->exists()
        ) {
            $candidate = $base.'-'.$i;
            $i++;
        }

        return $candidate;
    }
}