Merge pull request 'feat(recycle-bin): 实现回收站功能并添加软删除支持' (#6) from huangruihao/magic:feat-回收站v1重建-0319 into master

Reviewed-on: https://git.dtyq.com/magic/magic/pulls/6

Author: lihq1403

backend/super-magic-module/config/routes-v1/recycle-bin.php

@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * Copyright (c) The Magic , Distributed under the software license
+ */
+use App\Interfaces\Middleware\Auth\UserAuthMiddleware;
+use Dtyq\SuperMagic\Interfaces\RecycleBin\RecycleBinApi;
+use Hyperf\HttpServer\Router\Router;
+
+Router::addGroup(
+    '/api/v1/recycle-bin',
+    static function () {
+        // 获取回收站列表
+        Router::get('/list', [RecycleBinApi::class, 'getRecycleBinList']);
+
+        // 检查父级是否存在
+        Router::post('/check', [RecycleBinApi::class, 'checkParent']);
+
+        // 恢复资源
+        Router::post('/restore', [RecycleBinApi::class, 'restore']);
+
+        // 彻底删除（永久删除）
+        Router::post('/permanent-delete', [RecycleBinApi::class, 'permanentDelete']);
+
+        // 移动回收站中的项目（移动+恢复）
+        Router::post('/move-project', [RecycleBinApi::class, 'moveProject']);
+
+        // 批量移动回收站中的项目（批量移动+恢复）
+        Router::post('/batch-move-project', [RecycleBinApi::class, 'batchMoveProject']);
+
+        // 移动回收站中的话题（移动+恢复）
+        Router::post('/move-topic', [RecycleBinApi::class, 'moveTopic']);
+
+        // 批量移动回收站中的话题（批量移动+恢复）
+        Router::post('/batch-move-topic', [RecycleBinApi::class, 'batchMoveTopic']);
+    },
+    ['middleware' => [UserAuthMiddleware::class]]
+);

backend/super-magic-module/migrations/2026_03_03_100001_create_magic_recycle_bin_table.php

@@ -0,0 +1,63 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * Copyright (c) The Magic , Distributed under the software license
+ */
+use Hyperf\Database\Migrations\Migration;
+use Hyperf\Database\Schema\Blueprint;
+use Hyperf\Database\Schema\Schema;
+use Hyperf\DbConnection\Db;
+
+return new class extends Migration {
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        if (Schema::hasTable('magic_recycle_bin')) {
+            return;
+        }
+
+        Schema::create('magic_recycle_bin', function (Blueprint $table) {
+            // 主键
+            $table->bigIncrements('id');
+
+            // 资源标识
+            $table->tinyInteger('resource_type')->unsigned()->comment('资源类型：1=workspace,2=project,3=topic,4=file');
+            $table->unsignedBigInteger('resource_id')->comment('资源ID，对应各业务表主键');
+            $table->string('resource_name', 255)->default('')->comment('资源名称，删除时快照');
+
+            // 所有权与操作人(与工作区/项目/话题/文件表 user_id 一致，用 string)
+            $table->string('owner_id', 128)->comment('资源创建者ID');
+            $table->string('deleted_by', 128)->comment('删除人ID');
+
+            // 删除时间与有效期（deleted_at 由业务写入）
+            $table->timestamp('deleted_at')->comment('删除时间');
+            $table->unsignedInteger('retain_days')->default(30)->comment('有效期(天)');
+
+            // 父级关联(用于恢复时排除用户曾删的子资源)
+            $table->unsignedBigInteger('parent_id')->nullable()->comment('父级资源ID：file/topic=project_id，project=workspace_id，workspace=NULL');
+
+            // 扩展信息(可选，列表也可从原表JOIN)
+            $table->json('extra_data')->nullable()->comment('扩展信息：父级名称等');
+
+            // 审计字段（与项目内 2025_06_23 project、2025_08_27 operation_logs 等保持一致）
+            $table->timestamp('created_at')->nullable()->comment('创建时间');
+            $table->timestamp('updated_at')->nullable()->comment('更新时间');
+
+            // 第一阶段仅主键，不建业务索引；后续若有性能需求再补 idx_owner_deleted、idx_deleted_at
+        });
+
+        // 添加表注释
+        Db::statement("ALTER TABLE magic_recycle_bin COMMENT '回收站统一表'");
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('magic_recycle_bin');
+    }
+};

backend/super-magic-module/migrations/2026_03_03_131220_add_soft_delete_to_project_members_table.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * Copyright (c) The Magic , Distributed under the software license
+ */
+use Hyperf\Database\Migrations\Migration;
+use Hyperf\Database\Schema\Blueprint;
+use Hyperf\Database\Schema\Schema;
+
+return new class extends Migration {
+    public function up(): void
+    {
+        Schema::table('magic_super_agent_project_members', function (Blueprint $table) {
+            $table->softDeletes()->comment('软删除时间');
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::table('magic_super_agent_project_members', function (Blueprint $table) {
+            $table->dropSoftDeletes();
+        });
+    }
+};

backend/super-magic-module/src/Application/RecycleBin/Command/RecycleBinCleanupCommand.php

@@ -0,0 +1,65 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * Copyright (c) The Magic , Distributed under the software license
+ */
+
+namespace Dtyq\SuperMagic\Application\RecycleBin\Command;
+
+use App\Infrastructure\Core\Traits\HasLogger;
+use Dtyq\SuperMagic\Application\RecycleBin\Crontab\RecycleBinCleanupCrontab;
+use Hyperf\Command\Annotation\Command;
+use Hyperf\Command\Command as HyperfCommand;
+use Throwable;
+
+/**
+ * 回收站清理命令（手动触发定时任务）.
+ */
+#[Command]
+class RecycleBinCleanupCommand extends HyperfCommand
+{
+    use HasLogger;
+
+    public function __construct(
+        protected RecycleBinCleanupCrontab $recycleBinCleanupCrontab,
+    ) {
+        parent::__construct('recycle-bin:cleanup');
+    }
+
+    public function configure(): void
+    {
+        parent::configure();
+        $this->setDescription('手动执行回收站过期记录清理任务（测试用）');
+    }
+
+    public function handle(): void
+    {
+        $this->info('');
+        $this->info('🗑️  回收站过期记录清理任务');
+        $this->info('==========================================');
+        $this->info('');
+
+        $this->info('🚀 开始执行清理任务...');
+        $this->info('');
+
+        $startTime = microtime(true);
+
+        try {
+            $this->recycleBinCleanupCrontab->execute();
+
+            $elapsedTime = round((microtime(true) - $startTime) * 1000, 2);
+
+            $this->info('');
+            $this->info("✅ 清理任务执行完成！耗时：{$elapsedTime}ms");
+            $this->info('');
+            $this->info('💡 提示：请查看日志文件获取详细执行结果');
+        } catch (Throwable $e) {
+            $this->error('');
+            $this->error('❌ 清理任务执行失败！');
+            $this->error('错误信息：' . $e->getMessage());
+            $this->error('文件：' . $e->getFile() . ':' . $e->getLine());
+            $this->error('');
+        }
+    }
+}

backend/super-magic-module/src/Application/RecycleBin/Crontab/RecycleBinCleanupCrontab.php

@@ -0,0 +1,88 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * Copyright (c) The Magic , Distributed under the software license
+ */
+
+namespace Dtyq\SuperMagic\Application\RecycleBin\Crontab;
+
+use App\Infrastructure\Core\Traits\HasLogger;
+use Dtyq\SuperMagic\Domain\RecycleBin\Service\RecycleBinDomainService;
+use Hyperf\Crontab\Annotation\Crontab;
+use Throwable;
+
+/**
+ * 回收站过期记录清理定时任务.
+ * 每天凌晨3点执行，自动清理超过保留期的回收站记录.
+ */
+#[Crontab(
+    rule: '0 3 * * *',
+    name: 'RecycleBinCleanupCrontab',
+    singleton: true,
+    mutexExpires: 3600,
+    onOneServer: true,
+    callback: 'execute',
+    memo: '回收站过期记录清理定时任务'
+)]
+readonly class RecycleBinCleanupCrontab
+{
+    use HasLogger;
+
+    /**
+     * 单批次处理的记录数量上限.
+     */
+    private const BATCH_SIZE = 1000;
+
+    public function __construct(
+        private RecycleBinDomainService $recycleBinDomainService
+    ) {
+    }
+
+    /**
+     * 执行清理任务.
+     */
+    public function execute(): void
+    {
+        $startTime = microtime(true);
+        $this->logger->info('回收站过期记录清理任务开始');
+
+        try {
+            // 查询过期记录 ID
+            $expiredIds = $this->recycleBinDomainService->findExpiredRecordIds(self::BATCH_SIZE);
+
+            if (empty($expiredIds)) {
+                $this->logger->info('回收站过期记录清理任务完成：无过期记录');
+                return;
+            }
+
+            // 调用系统彻底删除（不校验用户权限）
+            $result = $this->recycleBinDomainService->permanentDeleteBySystem($expiredIds);
+
+            $successCount = count($expiredIds) - count($result['failed']);
+            $failedCount = count($result['failed']);
+            $elapsedTime = round((microtime(true) - $startTime) * 1000, 2);
+
+            $this->logger->info('回收站过期记录清理任务完成', [
+                'total' => count($expiredIds),
+                'success' => $successCount,
+                'failed' => $failedCount,
+                'elapsed_ms' => $elapsedTime,
+            ]);
+
+            // 如果有失败记录，记录详细信息
+            if ($failedCount > 0) {
+                $this->logger->warning('回收站过期记录清理部分失败', [
+                    'failed_items' => $result['failed'],
+                ]);
+            }
+        } catch (Throwable $e) {
+            $this->logger->error('回收站过期记录清理任务失败', [
+                'error' => $e->getMessage(),
+                'file' => $e->getFile(),
+                'line' => $e->getLine(),
+                'trace' => $e->getTraceAsString(),
+            ]);
+        }
+    }
+}

backend/super-magic-module/src/Application/RecycleBin/DTO/BatchMoveProjectInRecycleBinRequestDTO.php

@@ -0,0 +1,97 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * Copyright (c) The Magic , Distributed under the software license
+ */
+
+namespace Dtyq\SuperMagic\Application\RecycleBin\DTO;
+
+use App\Infrastructure\Core\AbstractRequestDTO;
+
+/**
+ * 批量移动回收站项目请求 DTO.
+ *
+ * 参考现有 BatchMoveProjectsRequestDTO 设计.
+ */
+class BatchMoveProjectInRecycleBinRequestDTO extends AbstractRequestDTO
+{
+    /**
+     * 项目ID数组（字段名与现有批量接口保持一致）.
+     */
+    public array $projectIds = [];
+
+    /**
+     * 目标工作区ID（空字符串表示"无工作区"）.
+     */
+    public string $targetWorkspaceId = '';
+
+    /**
+     * 获取项目ID数组.
+     *
+     * @return array<string> 返回字符串数组（雪花ID保持字符串）
+     */
+    public function getProjectIds(): array
+    {
+        return $this->projectIds;
+    }
+
+    /**
+     * 获取整型项目ID数组（供内部使用）.
+     *
+     * @return array<int>
+     */
+    public function getProjectIdsAsInt(): array
+    {
+        return array_map('intval', $this->projectIds);
+    }
+
+    /**
+     * 获取目标工作区ID.
+     */
+    public function getTargetWorkspaceId(): ?int
+    {
+        if ($this->targetWorkspaceId === '') {
+            return null;
+        }
+        return (int) $this->targetWorkspaceId;
+    }
+
+    /**
+     * 检查是否移动到"无工作区".
+     */
+    public function isMovingToNoWorkspace(): bool
+    {
+        return $this->targetWorkspaceId === '';
+    }
+
+    /**
+     * 获取验证规则.
+     */
+    protected static function getHyperfValidationRules(): array
+    {
+        return [
+            'project_ids' => 'required|array|min:1|max:20',
+            'project_ids.*' => 'required|string',
+            'target_workspace_id' => 'present|string|max:64',
+        ];
+    }
+
+    /**
+     * 获取自定义错误消息.
+     */
+    protected static function getHyperfValidationMessage(): array
+    {
+        return [
+            'project_ids.required' => '项目ID列表不能为空',
+            'project_ids.array' => '项目ID必须是数组',
+            'project_ids.min' => '至少需要选择一个项目',
+            'project_ids.max' => '最多只能同时移动20个项目',
+            'project_ids.*.required' => '每个项目ID不能为空',
+            'project_ids.*.string' => '每个项目ID必须是字符串',
+            'target_workspace_id.present' => '目标工作区ID字段必填',
+            'target_workspace_id.string' => '目标工作区ID必须是字符串',
+            'target_workspace_id.max' => '目标工作区ID不能超过64个字符',
+        ];
+    }
+}