docs(dump): add changelog

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>

src/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to AeonDumpManager will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- List, create, and delete SQL database dumps from a Settings admin page (nested under Settings, per
+  Shopware's [Add Menu Entry](https://developer.shopware.com/docs/v6.6/guides/plugins/plugins/administration/routing-navigation/add-menu-entry.html)
+  guide) and via `aeon:dump:list`/`aeon:dump:create`/`aeon:dump:remove` console commands.
+- Dumps are created with `mysqldump`/`mariadb-dump` (auto-detected, with an optional `dumpBinaryName`
+  override), gzip-compressed, and stored in the plugin's private Flysystem mount.
+- `maxDumps` auto-purges the oldest dump on creation; `retantionDays` purges dumps and stale job rows
+  on a recurring scheduled task.
+- Admin UI dump creation runs asynchronously via Symfony Messenger with a polling progress bar; console
+  creation runs synchronously.
+- ACL-gated (`aeon_dump_manager.viewer`/`.creator`/`.deleter`), enforced both client-side and
+  server-side.

src/Controller/DumpController.php

@@ -6,7 +6,8 @@ use AeonDumpManager\MessageQueue\Message\CreateDumpMessage;
 use AeonDumpManager\Service\DumpJobStatusService;
 use AeonDumpManager\Service\DumpLister;
 use AeonDumpManager\Service\DumpService;
-use Shopware\Core\Framework\Api\Route\ApiRouteScope;
+use AeonDumpManager\Service\Exception\DumpNotFoundException;
+use Shopware\Core\Framework\Routing\ApiRouteScope;
 use Shopware\Core\PlatformRequest;
 use Symfony\Component\HttpFoundation\JsonResponse;
 use Symfony\Component\HttpFoundation\Response;
@@ -67,7 +68,11 @@ class DumpController
     )]
     public function delete(string $filename): JsonResponse
     {
-        $this->dumpService->delete($filename);
+        try {
+            $this->dumpService->delete($filename);
+        } catch (DumpNotFoundException $exception) {
+            return new JsonResponse(['message' => $exception->getMessage()], Response::HTTP_NOT_FOUND);
+        }
 
         return new JsonResponse(null, Response::HTTP_NO_CONTENT);
     }

src/Resources/app/administration/src/global.d.ts

@@ -0,0 +1,20 @@
+// Shopware injects its Administration API as untyped globals at runtime; there's
+// no official @shopware-ag type package for plugin authors to install against
+// (per docs/research/admin-dump-manager-ui.md §4), so these are declared loosely
+// as `any` — good enough for editor support, and the build (swc, type-stripping
+// only, no tsc typecheck) doesn't need them at all.
+declare const Shopware: any;
+
+interface Window {
+    Shopware: typeof Shopware;
+}
+
+declare module '*.html.twig' {
+    const template: string;
+    export default template;
+}
+
+declare module '*.json' {
+    const value: Record<string, unknown>;
+    export default value;
+}

src/Resources/app/administration/src/main.ts

@@ -1,7 +1,7 @@
 import DumpApiService from './service/dump-api.service';
 import './module/aeon-dump-manager';
 
-Shopware.Application.addServiceProvider('aeonDumpManagerApiService', (container) => {
+Shopware.Application.addServiceProvider('aeonDumpManagerApiService', (container: { loginService: unknown }) => {
     const initContainer = Shopware.Application.getContainer('init');
 
     return new DumpApiService(initContainer.httpClient, container.loginService);

src/Resources/app/administration/src/module/aeon-dump-manager/index.js

@@ -1,39 +0,0 @@
-import './acl';
-import './page/aeon-dump-manager-list';
-import deDE from './snippet/de-DE.json';
-import enGB from './snippet/en-GB.json';
-
-Shopware.Module.register('aeon-dump-manager', {
-    type: 'plugin',
-    name: 'DumpManager',
-    title: 'aeon-dump-manager.general.mainMenuItemGeneral',
-    description: 'aeon-dump-manager.general.descriptionTextModule',
-    color: '#ff3d58',
-    icon: 'default-object-storage',
-
-    snippets: {
-        'de-DE': deDE,
-        'en-GB': enGB,
-    },
-
-    routes: {
-        list: {
-            component: 'aeon-dump-manager-list',
-            path: 'list',
-            meta: {
-                parentPath: 'sw.settings.index.system',
-                privilege: 'aeon_dump_manager.viewer',
-            },
-        },
-    },
-
-    // Shown as a card on the Settings page's "System" group, next to
-    // Plugins/Cache — matches the locked ACL/menu-naming decision. Plugins
-    // cannot register a first-level main-menu entry.
-    settingsItem: {
-        group: 'system',
-        to: 'aeon.dump.manager.list',
-        icon: 'default-object-storage',
-        privilege: 'aeon_dump_manager.viewer',
-    },
-});

src/Resources/app/administration/src/module/aeon-dump-manager/index.ts

@@ -0,0 +1,53 @@
+import './acl';
+import './page/aeon-dump-manager-list';
+import deDE from './snippet/de-DE.json';
+import enGB from './snippet/en-GB.json';
+
+Shopware.Module.register('aeon-dump-manager', {
+    type: 'plugin',
+    name: 'DumpManager',
+    title: 'aeon-dump-manager.general.mainMenuItemGeneral',
+    description: 'aeon-dump-manager.general.descriptionTextModule',
+    color: '#ff3d58',
+    icon: 'regular-database',
+
+    snippets: {
+        'de-DE': deDE,
+        'en-GB': enGB,
+    },
+
+    routes: {
+        list: {
+            component: 'aeon-dump-manager-list',
+            path: 'list',
+            meta: {
+                parentPath: 'sw.settings.index.system',
+                privilege: 'aeon_dump_manager.viewer',
+            },
+        },
+    },
+
+    // Per https://developer.shopware.com/docs/v6.6/guides/plugins/plugins/administration/routing-navigation/add-menu-entry.html —
+    // plugins can't register a first-level main-menu entry, so this nests
+    // under the core 'sw-settings' navigation node. Clicking Settings in the
+    // main sidebar shows this as a sub-item, landing at #/sw/settings/.
+    navigation: [{
+        id: 'aeon-dump-manager-list',
+        label: 'aeon-dump-manager.general.mainMenuItemGeneral',
+        color: '#ff3d58',
+        path: 'aeon.dump.manager.list',
+        icon: 'regular-database',
+        parent: 'sw-settings',
+        position: 100,
+        privilege: 'aeon_dump_manager.viewer',
+    }],
+
+    // Also shown as a card on the Settings overview page's "System" group,
+    // next to Plugins/Cache — complements the navigation entry above.
+    settingsItem: {
+        group: 'system',
+        to: 'aeon.dump.manager.list',
+        icon: 'regular-database',
+        privilege: 'aeon_dump_manager.viewer',
+    },
+});

src/Resources/app/administration/src/module/aeon-dump-manager/page/aeon-dump-manager-list/index.ts

@@ -1,13 +1,38 @@
 import template from './aeon-dump-manager-list.html.twig';
+import type DumpApiService, { DumpFile, DumpJob } from '../../../../service/dump-api.service';
 
 const { Component } = Shopware;
 
+interface PendingJob {
+    status: string;
+    percent: number | null;
+    errorMessage?: string | null;
+}
+
+interface ComponentData {
+    dumps: DumpFile[];
+    isLoading: boolean;
+    pendingJob: PendingJob | null;
+    deleteFilename: string | null;
+    pollTimer: number | null;
+}
+
+interface ComponentInstance extends ComponentData {
+    aeonDumpManagerApiService: DumpApiService;
+    $tc: (key: string, count?: number, values?: Record<string, unknown>) => string;
+    createNotificationError: (options: { message: string }) => void;
+    createNotificationSuccess: (options: { message: string }) => void;
+    loadList: () => Promise<void>;
+    stopPolling: () => void;
+    pollJobStatus: (jobId: string) => void;
+}
+
 Component.register('aeon-dump-manager-list', {
     template,
 
     inject: ['aeonDumpManagerApiService', 'acl'],
 
-    data() {
+    data(): ComponentData {
         return {
             dumps: [],
             isLoading: false,
@@ -40,16 +65,16 @@ Component.register('aeon-dump-manager-list', {
         },
     },
 
-    created() {
+    created(this: ComponentInstance) {
         this.loadList();
     },
 
-    beforeDestroy() {
+    beforeDestroy(this: ComponentInstance) {
         this.stopPolling();
     },
 
     methods: {
-        loadList() {
+        loadList(this: ComponentInstance): Promise<void> {
             this.isLoading = true;
 
             return this.aeonDumpManagerApiService.getList()
@@ -61,22 +86,22 @@ Component.register('aeon-dump-manager-list', {
                 });
         },
 
-        formatDatetime(value) {
+        formatDatetime(value: string): string {
             return new Date(value).toLocaleString();
         },
 
-        formatSize(bytes) {
+        formatSize(bytes: number): string {
             return Shopware.Utils.format.fileSize(bytes);
         },
 
-        onCreate() {
+        onCreate(this: ComponentInstance) {
             this.pendingJob = { percent: 0, status: 'pending' };
 
             this.aeonDumpManagerApiService.create()
                 .then((response) => {
                     this.pollJobStatus(response.jobId);
                 })
-                .catch((error) => {
+                .catch((error: Error) => {
                     this.pendingJob = null;
                     this.createNotificationError({
                         message: this.$tc('aeon-dump-manager.list.createFailed', 0, { error: error.message }),
@@ -84,11 +109,11 @@ Component.register('aeon-dump-manager-list', {
                 });
         },
 
-        pollJobStatus(jobId) {
+        pollJobStatus(this: ComponentInstance, jobId: string) {
             this.stopPolling();
 
             this.pollTimer = window.setInterval(() => {
-                this.aeonDumpManagerApiService.getJobStatus(jobId).then((job) => {
+                this.aeonDumpManagerApiService.getJobStatus(jobId).then((job: DumpJob) => {
                     if (job.status === 'done') {
                         this.stopPolling();
                         this.pendingJob = null;
@@ -101,7 +126,7 @@ Component.register('aeon-dump-manager-list', {
                         this.stopPolling();
                         this.pendingJob = null;
                         this.createNotificationError({
-                            message: this.$tc('aeon-dump-manager.list.createFailed', 0, { error: job.errorMessage }),
+                            message: this.$tc('aeon-dump-manager.list.createFailed', 0, { error: job.errorMessage ?? '' }),
                         });
                         return;
                     }
@@ -111,23 +136,23 @@ Component.register('aeon-dump-manager-list', {
             }, 2000);
         },
 
-        stopPolling() {
+        stopPolling(this: ComponentInstance) {
             if (this.pollTimer !== null) {
                 window.clearInterval(this.pollTimer);
                 this.pollTimer = null;
             }
         },
 
-        onRequestDelete(filename) {
+        onRequestDelete(this: ComponentInstance, filename: string) {
             this.deleteFilename = filename;
         },
 
-        onCancelDelete() {
+        onCancelDelete(this: ComponentInstance) {
             this.deleteFilename = null;
         },
 
-        onConfirmDelete() {
-            const filename = this.deleteFilename;
+        onConfirmDelete(this: ComponentInstance): Promise<void> {
+            const filename = this.deleteFilename as string;
             this.deleteFilename = null;
 
             return this.aeonDumpManagerApiService.remove(filename)

src/Resources/app/administration/src/service/dump-api.service.js

@@ -1,31 +0,0 @@
-const { ApiService } = Shopware.Classes;
-
-export default class DumpApiService extends ApiService {
-    constructor(httpClient, loginService, apiEndpoint = 'aeon-dump-manager') {
-        super(httpClient, loginService, apiEndpoint);
-    }
-
-    getList() {
-        return this.httpClient
-            .get('/_action/aeon-dump-manager/dumps', { headers: this.getBasicHeaders() })
-            .then((response) => ApiService.handleResponse(response));
-    }
-
-    create() {
-        return this.httpClient
-            .post('/_action/aeon-dump-manager/dumps', {}, { headers: this.getBasicHeaders() })
-            .then((response) => ApiService.handleResponse(response));
-    }
-
-    remove(filename) {
-        return this.httpClient
-            .delete(`/_action/aeon-dump-manager/dumps/${encodeURIComponent(filename)}`, { headers: this.getBasicHeaders() })
-            .then((response) => ApiService.handleResponse(response));
-    }
-
-    getJobStatus(jobId) {
-        return this.httpClient
-            .get(`/_action/aeon-dump-manager/dumps/jobs/${encodeURIComponent(jobId)}`, { headers: this.getBasicHeaders() })
-            .then((response) => ApiService.handleResponse(response));
-    }
-}

src/Resources/app/administration/src/service/dump-api.service.ts

@@ -0,0 +1,69 @@
+export interface DumpFile {
+    filename: string;
+    datetime: string;
+    sizeBytes: number;
+}
+
+export interface DumpList {
+    dumps: DumpFile[];
+}
+
+export interface CreateDumpResponse {
+    jobId: string;
+}
+
+export type DumpJobStatus = 'pending' | 'running' | 'done' | 'failed';
+
+export interface DumpJob {
+    id: string;
+    status: DumpJobStatus;
+    percent: number | null;
+    filename: string | null;
+    errorMessage: string | null;
+}
+
+// Shopware.Classes.ApiService has no official type package for plugin authors
+// (per docs/research/admin-dump-manager-ui.md §4) — redeclaring the inherited
+// member this class actually uses keeps everything below typed without one.
+// `declare` is required here: a normal field declaration compiles to a real
+// `this.httpClient = void 0` in the constructor, which runs *after* `super()`
+// and silently clobbers the value the base class just set.
+const { ApiService } = Shopware.Classes;
+
+export default class DumpApiService extends ApiService {
+    protected declare httpClient: {
+        get: (url: string, config?: unknown) => Promise<unknown>;
+        post: (url: string, data: unknown, config?: unknown) => Promise<unknown>;
+        delete: (url: string, config?: unknown) => Promise<unknown>;
+    };
+
+    protected declare getBasicHeaders: (additionalHeaders?: Record<string, string>) => Record<string, string>;
+
+    constructor(httpClient: unknown, loginService: unknown, apiEndpoint = 'aeon-dump-manager') {
+        super(httpClient, loginService, apiEndpoint);
+    }
+
+    getList(): Promise<DumpList> {
+        return this.httpClient
+            .get('/_action/aeon-dump-manager/dumps', { headers: this.getBasicHeaders() })
+            .then((response: unknown) => ApiService.handleResponse(response));
+    }
+
+    create(): Promise<CreateDumpResponse> {
+        return this.httpClient
+            .post('/_action/aeon-dump-manager/dumps', {}, { headers: this.getBasicHeaders() })
+            .then((response: unknown) => ApiService.handleResponse(response));
+    }
+
+    remove(filename: string): Promise<void> {
+        return this.httpClient
+            .delete(`/_action/aeon-dump-manager/dumps/${encodeURIComponent(filename)}`, { headers: this.getBasicHeaders() })
+            .then((response: unknown) => ApiService.handleResponse(response));
+    }
+
+    getJobStatus(jobId: string): Promise<DumpJob> {
+        return this.httpClient
+            .get(`/_action/aeon-dump-manager/dumps/jobs/${encodeURIComponent(jobId)}`, { headers: this.getBasicHeaders() })
+            .then((response: unknown) => ApiService.handleResponse(response));
+    }
+}

src/Resources/app/administration/src/tsconfig.json

@@ -0,0 +1,13 @@
+{
+    "compilerOptions": {
+        "target": "es2022",
+        "module": "esnext",
+        "moduleResolution": "bundler",
+        "strict": false,
+        "noEmit": true,
+        "skipLibCheck": true,
+        "allowJs": true,
+        "esModuleInterop": true
+    },
+    "include": ["**/*.ts", "global.d.ts"]
+}

src/Resources/config/config.xml

@@ -6,12 +6,12 @@
     <card>
         <title>Minimal configuration</title>
 
-        <input-field type="number">
+        <input-field type="int">
             <name>maxDumps</name>
             <label>Maximum allowed dumps to exist</label>
             <defaultValue>6</defaultValue>
         </input-field>
-        <input-field type="number">
+        <input-field type="int">
             <name>retantionDays</name>
             <label>How many Days the dumps kept in the Storage. 0 Means unlimited</label>
             <defaultValue>0</defaultValue>
@@ -19,7 +19,6 @@
         <input-field type="text">
             <name>dumpBinaryName</name>
             <label>Name of the mysqldump/mariadb-dump binary to look up on PATH (e.g. if your distro renamed it). Leave empty to auto-detect.</label>
-            <defaultValue>""</defaultValue>
         </input-field>
     </card>
 

src/Resources/config/services.xml

@@ -5,81 +5,82 @@
            xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
 
     <services>
-
         <!-- Services -->
 
         <service id="Symfony\Component\Process\ExecutableFinder"/>
 
-        <service id="AeonDumpManager\Service\DumpFilenameParser"/>
+        <service id="aeon_dump_manager.dump_filename_parser" class="AeonDumpManager\Service\DumpFilenameParser"/>
 
-        <service id="AeonDumpManager\Service\DumpBinaryLocator">
+        <service id="aeon_dump_manager.dump_binary_locator" class="AeonDumpManager\Service\DumpBinaryLocator">
             <argument type="service" id="Doctrine\DBAL\Connection"/>
             <argument type="service" id="Shopware\Core\System\SystemConfig\SystemConfigService"/>
             <argument type="service" id="Symfony\Component\Process\ExecutableFinder"/>
         </service>
 
-        <service id="AeonDumpManager\Service\DumpJobStatusService">
+        <service id="aeon_dump_manager.dump_job_status_service" class="AeonDumpManager\Service\DumpJobStatusService">
             <argument type="service" id="Doctrine\DBAL\Connection"/>
         </service>
 
-        <service id="AeonDumpManager\Service\DumpLister">
+        <service id="aeon_dump_manager.dump_lister" class="AeonDumpManager\Service\DumpLister">
             <argument type="service" id="aeon_dump_manager.filesystem.private"/>
-            <argument type="service" id="AeonDumpManager\Service\DumpFilenameParser"/>
+            <argument type="service" id="aeon_dump_manager.dump_filename_parser"/>
         </service>
 
-        <service id="AeonDumpManager\Service\DumpService">
-            <argument type="service" id="AeonDumpManager\Service\DumpLister"/>
+        <service id="aeon_dump_manager.dump_service" class="AeonDumpManager\Service\DumpService">
+            <argument type="service" id="aeon_dump_manager.dump_lister"/>
             <argument type="service" id="aeon_dump_manager.filesystem.private"/>
-            <argument type="service" id="AeonDumpManager\Service\DumpBinaryLocator"/>
+            <argument type="service" id="aeon_dump_manager.dump_binary_locator"/>
             <argument type="service" id="Doctrine\DBAL\Connection"/>
             <argument type="service" id="Shopware\Core\System\SystemConfig\SystemConfigService"/>
-            <argument type="service" id="AeonDumpManager\Service\DumpFilenameParser"/>
+            <argument type="service" id="aeon_dump_manager.dump_filename_parser"/>
         </service>
 
         <!-- Async create job -->
 
-        <service id="AeonDumpManager\MessageQueue\Handler\CreateDumpHandler">
-            <argument type="service" id="AeonDumpManager\Service\DumpService"/>
-            <argument type="service" id="AeonDumpManager\Service\DumpJobStatusService"/>
+        <service id="aeon_dump_manager.message_queue.create_dump_handler" class="AeonDumpManager\MessageQueue\Handler\CreateDumpHandler">
+            <argument type="service" id="aeon_dump_manager.dump_service"/>
+            <argument type="service" id="aeon_dump_manager.dump_job_status_service"/>
+            <tag name="messenger.message_handler"/>
         </service>
 
         <!-- Retention -->
 
-        <service id="AeonDumpManager\ScheduledTask\PurgeDumpsTask">
+        <service id="aeon_dump_manager.scheduled_task.purge_dumps_task" class="AeonDumpManager\ScheduledTask\PurgeDumpsTask">
             <tag name="shopware.scheduled.task"/>
         </service>
 
-        <service id="AeonDumpManager\ScheduledTask\PurgeDumpsTaskHandler">
+        <service id="aeon_dump_manager.scheduled_task.purge_dumps_task_handler" class="AeonDumpManager\ScheduledTask\PurgeDumpsTaskHandler">
             <argument type="service" id="scheduled_task.repository"/>
             <argument type="service" id="logger"/>
-            <argument type="service" id="AeonDumpManager\Service\DumpService"/>
-            <argument type="service" id="AeonDumpManager\Service\DumpJobStatusService"/>
+            <argument type="service" id="aeon_dump_manager.dump_service"/>
+            <argument type="service" id="aeon_dump_manager.dump_job_status_service"/>
             <argument type="service" id="Shopware\Core\System\SystemConfig\SystemConfigService"/>
+            <tag name="messenger.message_handler" handles="AeonDumpManager\ScheduledTask\PurgeDumpsTask"/>
         </service>
 
         <!-- Console commands -->
 
-        <service id="AeonDumpManager\Command\DumpListCommand">
-            <argument type="service" id="AeonDumpManager\Service\DumpLister"/>
+        <service id="aeon_dump_manager.command.dump_list" class="AeonDumpManager\Command\DumpListCommand">
+            <argument type="service" id="aeon_dump_manager.dump_lister"/>
             <tag name="console.command"/>
         </service>
 
-        <service id="AeonDumpManager\Command\DumpCreateCommand">
-            <argument type="service" id="AeonDumpManager\Service\DumpService"/>
+        <service id="aeon_dump_manager.command.dump_create" class="AeonDumpManager\Command\DumpCreateCommand">
+            <argument type="service" id="aeon_dump_manager.dump_service"/>
             <tag name="console.command"/>
         </service>
 
-        <service id="AeonDumpManager\Command\DumpRemoveCommand">
-            <argument type="service" id="AeonDumpManager\Service\DumpService"/>
+        <service id="aeon_dump_manager.command.dump_remove" class="AeonDumpManager\Command\DumpRemoveCommand">
+            <argument type="service" id="aeon_dump_manager.dump_service"/>
             <tag name="console.command"/>
         </service>
 
         <!-- Admin API controller -->
 
         <service id="AeonDumpManager\Controller\DumpController" public="true">
-            <argument type="service" id="AeonDumpManager\Service\DumpLister"/>
-            <argument type="service" id="AeonDumpManager\Service\DumpService"/>
-            <argument type="service" id="AeonDumpManager\Service\DumpJobStatusService"/>
+            <argument type="service" id="aeon_dump_manager.dump_lister"/>
+            <argument type="service" id="aeon_dump_manager.dump_service"/>
+            <argument type="service" id="aeon_dump_manager.dump_job_status_service"/>
             <argument type="service" id="messenger.default_bus"/>
         </service>
 

src/Service/DumpBinaryLocator.php

@@ -40,6 +40,9 @@ class DumpBinaryLocator
 
     private function isMariaDb(): bool
     {
-        return MySqlVariant::isMariaDb($this->connection->getServerVersion());
+        // Connection::getServerVersion() is private in the DBAL version this
+        // repo pins against — SELECT VERSION() is the stable public way to get
+        // the same string.
+        return MySqlVariant::isMariaDb((string) $this->connection->fetchOne('SELECT VERSION()'));
     }
 }