refactor(shop-statuses): migrate to DI, restructure docs into docs/ folder (0.268)

- Migrate ShopStatuses module to Domain + DI architecture
- Add ShopStatusRepository, ShopStatusesController with color picker
- Convert front\factory\ShopStatuses to facade
- Add FormFieldType::COLOR with HTML5 color picker
- Move documentation files to docs/ folder (PROJECT_STRUCTURE, REFACTORING_PLAN, CHANGELOG, FORM_EDIT_SYSTEM, TESTING, DATABASE_STRUCTURE)
- Tests: 254 tests, 736 assertions

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

autoload/admin/Controllers/ShopStatusesController.php

@@ -0,0 +1,260 @@
+<?php
+namespace admin\Controllers;
+
+use Domain\ShopStatus\ShopStatusRepository;
+use admin\ViewModels\Common\PaginatedTableViewModel;
+use admin\ViewModels\Forms\FormAction;
+use admin\ViewModels\Forms\FormEditViewModel;
+use admin\ViewModels\Forms\FormField;
+use admin\ViewModels\Forms\FormTab;
+
+class ShopStatusesController
+{
+    private ShopStatusRepository $repository;
+
+    public function __construct(ShopStatusRepository $repository)
+    {
+        $this->repository = $repository;
+    }
+
+    public function list(): string
+    {
+        $sortableColumns = ['id', 'status', 'color', 'o', 'apilo_status_id'];
+        $filterDefinitions = [
+            [
+                'key' => 'status',
+                'label' => 'Status',
+                'type' => 'text',
+            ],
+        ];
+
+        $listRequest = \admin\Support\TableListRequestFactory::fromRequest(
+            $filterDefinitions,
+            $sortableColumns,
+            'o'
+        );
+
+        $sortDir = $listRequest['sortDir'];
+        if (trim((string)\S::get('sort')) === '') {
+            $sortDir = 'ASC';
+        }
+
+        $result = $this->repository->listForAdmin(
+            $listRequest['filters'],
+            $listRequest['sortColumn'],
+            $sortDir,
+            $listRequest['page'],
+            $listRequest['perPage']
+        );
+
+        $apiloStatusList = $this->getApiloStatusList();
+
+        $rows = [];
+        $lp = ($listRequest['page'] - 1) * $listRequest['perPage'] + 1;
+        foreach ($result['items'] as $item) {
+            $id = (int)($item['id'] ?? 0);
+            $statusName = trim((string)($item['status'] ?? ''));
+            $color = trim((string)($item['color'] ?? ''));
+            $apiloStatusId = $item['apilo_status_id'] ?? null;
+
+            $apiloStatusLabel = '';
+            if ($apiloStatusId !== null && isset($apiloStatusList[$apiloStatusId])) {
+                $apiloStatusLabel = $apiloStatusList[$apiloStatusId];
+            }
+
+            $colorHtml = $color !== ''
+                ? '<span style="display:inline-block;width:20px;height:20px;background:' . htmlspecialchars($color, ENT_QUOTES, 'UTF-8') . ';border:1px solid #ccc;vertical-align:middle;margin-right:5px;"></span> ' . htmlspecialchars($color, ENT_QUOTES, 'UTF-8')
+                : '-';
+
+            $rows[] = [
+                'lp' => $lp++ . '.',
+                'status' => '<a href="/admin/shop_statuses/edit/id=' . $id . '">' . htmlspecialchars($statusName, ENT_QUOTES, 'UTF-8') . '</a>',
+                'color' => $colorHtml,
+                'apilo_status' => htmlspecialchars($apiloStatusLabel, ENT_QUOTES, 'UTF-8'),
+                '_actions' => [
+                    [
+                        'label' => 'Edytuj',
+                        'url' => '/admin/shop_statuses/edit/id=' . $id,
+                        'class' => 'btn btn-xs btn-primary',
+                    ],
+                ],
+            ];
+        }
+
+        $total = (int)$result['total'];
+        $totalPages = max(1, (int)ceil($total / $listRequest['perPage']));
+
+        $viewModel = new PaginatedTableViewModel(
+            [
+                ['key' => 'lp', 'label' => 'Lp.', 'class' => 'text-center', 'sortable' => false],
+                ['key' => 'status', 'sort_key' => 'status', 'label' => 'Status', 'sortable' => true, 'raw' => true],
+                ['key' => 'color', 'sort_key' => 'color', 'label' => 'Kolor', 'sortable' => true, 'raw' => true],
+                ['key' => 'apilo_status', 'sort_key' => 'apilo_status_id', 'label' => 'Status Apilo', 'sortable' => true],
+                ],
+            $rows,
+            $listRequest['viewFilters'],
+            [
+                'column' => $listRequest['sortColumn'],
+                'dir' => $sortDir,
+            ],
+            [
+                'page' => $listRequest['page'],
+                'per_page' => $listRequest['perPage'],
+                'total' => $total,
+                'total_pages' => $totalPages,
+            ],
+            array_merge($listRequest['queryFilters'], [
+                'sort' => $listRequest['sortColumn'],
+                'dir' => $sortDir,
+                'per_page' => $listRequest['perPage'],
+            ]),
+            $listRequest['perPageOptions'],
+            $sortableColumns,
+            '/admin/shop_statuses/list/',
+            'Brak danych w tabeli.'
+        );
+
+        return \Tpl::view('shop-statuses/view-list', [
+            'viewModel' => $viewModel,
+        ]);
+    }
+
+    public function edit(): string
+    {
+        $status = $this->repository->find((int)\S::get('id'));
+        if ($status === null) {
+            \S::alert('Status nie zostal znaleziony.');
+            header('Location: /admin/shop_statuses/list/');
+            exit;
+        }
+
+        $apiloStatusList = $this->getApiloStatusList();
+
+        return \Tpl::view('shop-statuses/status-edit', [
+            'form' => $this->buildFormViewModel($status, $apiloStatusList),
+        ]);
+    }
+
+    public function save(): void
+    {
+        $legacyValues = \S::get('values');
+
+        if ($legacyValues) {
+            $values = json_decode((string)$legacyValues, true);
+            $response = [
+                'status' => 'error',
+                'msg' => 'Podczas zapisywania statusu wystapil blad. Prosze sprobowac ponownie.',
+            ];
+
+            if (is_array($values)) {
+                $statusId = (int)($values['id'] ?? 0);
+                $id = $this->repository->save($statusId, $values);
+                if ($id !== null && $id >= 0) {
+                    $response = [
+                        'status' => 'ok',
+                        'msg' => 'Status zostal zapisany.',
+                        'id' => (int)$id,
+                    ];
+                }
+            }
+
+            echo json_encode($response);
+            exit;
+        }
+
+        $payload = $_POST;
+        $statusId = isset($payload['id']) && $payload['id'] !== '' ? (int)$payload['id'] : null;
+        if ($statusId === null) {
+            $statusId = (int)\S::get('id');
+        }
+
+        $id = $this->repository->save($statusId, $payload);
+        if ($id !== null && $id >= 0) {
+            echo json_encode([
+                'success' => true,
+                'id' => (int)$id,
+                'message' => 'Status zostal zapisany.',
+            ]);
+            exit;
+        }
+
+        echo json_encode([
+            'success' => false,
+            'errors' => ['general' => 'Podczas zapisywania statusu wystapil blad.'],
+        ]);
+        exit;
+    }
+
+    private function buildFormViewModel(array $status, array $apiloStatusList): FormEditViewModel
+    {
+        $id = (int)($status['id'] ?? 0);
+
+        $apiloOptions = ['' => '--- wybierz status apilo.com ---'];
+        foreach ($apiloStatusList as $apiloId => $apiloName) {
+            $apiloOptions[$apiloId] = $apiloName;
+        }
+
+        $data = [
+            'id' => $id,
+            'status' => (string)($status['status'] ?? ''),
+            'color' => (string)($status['color'] ?? ''),
+            'apilo_status_id' => $status['apilo_status_id'] ?? '',
+        ];
+
+        $fields = [
+            FormField::hidden('id', $id),
+            FormField::text('status', [
+                'label' => 'Status',
+                'tab' => 'settings',
+                'readonly' => true,
+            ]),
+            FormField::color('color', [
+                'label' => 'Kolor',
+                'tab' => 'settings',
+            ]),
+            FormField::select('apilo_status_id', [
+                'label' => 'Status z Apilo',
+                'tab' => 'settings',
+                'options' => $apiloOptions,
+            ]),
+        ];
+
+        $tabs = [
+            new FormTab('settings', 'Ustawienia', 'fa-wrench'),
+        ];
+
+        $actionUrl = '/admin/shop_statuses/save/id=' . $id;
+        $actions = [
+            FormAction::save($actionUrl, '/admin/shop_statuses/list/'),
+            FormAction::cancel('/admin/shop_statuses/list/'),
+        ];
+
+        return new FormEditViewModel(
+            'status-edit',
+            'Edycja statusu zamowienia',
+            $data,
+            $fields,
+            $tabs,
+            $actions,
+            'POST',
+            $actionUrl,
+            '/admin/shop_statuses/list/',
+            true,
+            ['id' => $id]
+        );
+    }
+
+    private function getApiloStatusList(): array
+    {
+        $list = [];
+        $raw = @unserialize(\admin\factory\Integrations::apilo_settings('status-types-list'));
+        if (is_array($raw)) {
+            foreach ($raw as $apiloStatus) {
+                if (isset($apiloStatus['id'], $apiloStatus['name'])) {
+                    $list[(int)$apiloStatus['id']] = (string)$apiloStatus['name'];
+                }
+            }
+        }
+        return $list;
+    }
+}

autoload/admin/Support/Forms/FormFieldRenderer.php

@@ -308,6 +308,36 @@ class FormFieldRenderer
                'value="' . htmlspecialchars($value ?? '') . '">';
     }
 
+    /**
+     * Renderuje pole koloru (color picker + text input)
+     */
+    public function renderColor(FormField $field): string
+    {
+        $value = $this->form->getFieldValue($field);
+        $error = $this->form->getError($field->name);
+        $colorValue = htmlspecialchars($value ?? '#000000', ENT_QUOTES, 'UTF-8');
+        $fieldName = htmlspecialchars($field->name, ENT_QUOTES, 'UTF-8');
+        $fieldId = htmlspecialchars($field->id, ENT_QUOTES, 'UTF-8');
+        $label = htmlspecialchars($field->label, ENT_QUOTES, 'UTF-8');
+
+        $html = '<div class="form-group row">';
+        $html .= '<label class="col-lg-4 control-label">' . $label . ':</label>';
+        $html .= '<div class="col-lg-8">';
+        $html .= '<div style="display:flex;align-items:center;gap:8px;">';
+        $html .= '<input type="color" id="' . $fieldId . '_picker" value="' . $colorValue . '" style="width:40px;height:34px;padding:2px;border:1px solid #ccc;cursor:pointer;" />';
+        $html .= '<input type="text" name="' . $fieldName . '" id="' . $fieldId . '" value="' . $colorValue . '" class="form-control" style="max-width:150px;" />';
+        $html .= '</div>';
+        $html .= '</div>';
+        $html .= '</div>';
+        $html .= '<script>$(function(){'
+            . 'var $p=$("#' . $fieldId . '_picker"),$t=$("#' . $fieldId . '");'
+            . '$p.on("input",function(){$t.val(this.value);});'
+            . '$t.on("input",function(){var v=this.value;if(/^#[0-9a-fA-F]{6}$/.test(v))$p.val(v);});'
+            . '});</script>';
+
+        return $this->wrapWithError($html, $error);
+    }
+
     public function renderCustom(FormField $field): string
     {
         return (string)($field->customHtml ?? '');

autoload/admin/ViewModels/Forms/FormField.php

@@ -268,6 +268,21 @@ class FormField
         );
     }
 
+    public static function color(string $name, array $config = []): self
+    {
+        return new self(
+            $name,
+            FormFieldType::COLOR,
+            $config['label'] ?? '',
+            $config['value'] ?? null,
+            $config['tab'] ?? 'default',
+            $config['required'] ?? false,
+            $config['attributes'] ?? [],
+            [],
+            $config['help'] ?? null
+        );
+    }
+
     public static function hidden(string $name, $value = null): self
     {
         return new self(

autoload/admin/ViewModels/Forms/FormFieldType.php

@@ -21,4 +21,5 @@ class FormFieldType
     public const HIDDEN = 'hidden';
     public const LANG_SECTION = 'lang_section';
     public const CUSTOM = 'custom';
+    public const COLOR = 'color';
 }

autoload/admin/class.Site.php

@@ -332,6 +332,13 @@ class Site
           new \Domain\Integrations\IntegrationsRepository( $mdb )
         );
       },
+      'ShopStatuses' => function() {
+        global $mdb;
+
+        return new \admin\Controllers\ShopStatusesController(
+          new \Domain\ShopStatus\ShopStatusRepository( $mdb )
+        );
+      },
     ];
 
     return self::$newControllers;

autoload/admin/controls/class.ShopStatuses.php

@@ -1,34 +0,0 @@
-<?
-namespace admin\controls;
-
-class ShopStatuses {
-
-  // status_save
-  public static function status_save()
-  {
-    $response = [ 'status' => 'error', 'msg' => 'Podczas zapisywania statusu wystąpił błąd. Proszę spróbować ponownie.' ];
-    $values = json_decode( \S::get( 'values' ), true );
-
-    if ( $id = \admin\factory\ShopStatuses::status_save( $values['id'], $values['color'], $values['apilo_status_id'] ) )
-      $response = [ 'status' => 'ok', 'msg' => 'Status został zapisany.', 'id' => $id ];
-
-    echo json_encode( $response );
-    exit;
-  }
-
-  // status_edit
-  public static function status_edit()
-  {
-    return \Tpl::view( 'shop-statuses/status-edit', [
-      'status' => \admin\factory\ShopStatuses::get_status( \S::get( 'id' ) ),
-      'apilo_order_status_list' => unserialize( \admin\factory\Integrations::apilo_settings( 'status-types-list' ) ),
-    ] );
-  }
-
-  static public function view_list()
-  {
-    return \Tpl::view( 'shop-statuses/view-list', [
-      'apilo_order_status_list' => unserialize( \admin\factory\Integrations::apilo_settings( 'status-types-list' ) ),
-    ] );
-  }
-}

autoload/admin/factory/class.Integrations.php

@@ -4,7 +4,7 @@ namespace admin\factory;
 /**
  * Fasada kompatybilnosci wstecznej.
  * Deleguje do Domain\Integrations\IntegrationsRepository.
- * Uzywane przez: cron.php, shop\Order, admin\controls\ShopStatuses, admin\controls\ShopTransport, admin\controls\ShopPaymentMethod, admin\controls\ShopProduct.
+ * Uzywane przez: cron.php, shop\Order, admin\Controllers\ShopStatusesController, admin\controls\ShopTransport, admin\controls\ShopPaymentMethod, admin\controls\ShopProduct.
  */
 class Integrations {
 

autoload/admin/factory/class.ShopStatuses.php

@@ -1,24 +0,0 @@
-<?
-namespace admin\factory;
-
-class ShopStatuses {
-  // get_status
-  public static function get_status( $id )
-  {
-    global $mdb;
-    return $mdb -> get( 'pp_shop_statuses', '*', [ 'id' => $id ] );
-  }
-
-  // status_save
-  public static function status_save( $status_id, $color, $apilo_status_id )
-  {
-    global $mdb;
-
-    $mdb -> update( 'pp_shop_statuses', [
-        'color' => $color,
-        'apilo_status_id' => $apilo_status_id ? $apilo_status_id : null,
-      ], [ 'id' => $status_id ] );
-
-    return $status_id;
-  }
-}