feat(upload): pending lifecycle for upload-on-select images

Mark front-end uploads (comment/ticket/report) as pending, return the
attachment id, discard own pending uploads on remove via
DELETE /upload/pending/{id}, claim referenced URLs on successful submit,
and purge unclaimed uploads older than 24h with an hourly cron.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

src/Admin/UserController.php

@@ -612,9 +612,12 @@ class UserController extends ControllerBase {
             wp_delete_attachment((int) $attachment_id, true);
             return $this->error(__('上传失败', 'aksrt'), 500);
         }
+        // 选图即上传：提交成功前处于待认领状态，× 移除或超时未提交会被清理。
+        \AKSRT\Attachment\PendingUploads::mark((int) $attachment_id);
         return $this->success([
             'message' => __('图片上传成功', 'aksrt'),
             'data'    => [
+                'id'  => (int) $attachment_id,
                 'url' => $url,
             ],
         ]);

src/Admin/UserControllerReportOperations.php

@@ -450,6 +450,8 @@ trait UserControllerReportOperations {
         );
 
         if ($report_id > 0) {
+            // 举证图片以 URL 拼入举报内容，提交成功即认领。
+            \AKSRT\Attachment\PendingUploads::claim_text($reason, $reporter_id);
             return $this->success([
                 'message' => __('举报已提交，我们会尽快处理', 'aksrt'),
                 'data'    => ['report_id' => $report_id],

src/Attachment/PendingUploads.php

@@ -0,0 +1,167 @@
+<?php
+/**
+ * 前台「选图即上传」的附件生命周期（对齐大厂：先传后认领，未认领兜底清理）。
+ *
+ * - 上传成功即打「待认领」标记（时间戳），返回 id + url；
+ * - 用户点 × 移除：DELETE /upload/pending/{id}，仅能删自己的、仍待认领的附件；
+ * - 表单提交成功（评论 / 工单 / 举报）后按引用的 URL 认领，去掉标记；
+ * - 定时任务删除超过 TTL 仍未认领的附件。
+ *
+ * @package AKSRT
+ */
+
+namespace AKSRT\Attachment;
+
+defined('ABSPATH') || exit;
+
+final class PendingUploads {
+
+    public const META      = '_aksrt_pending_upload';
+    public const CRON_HOOK = 'aksrt_pending_upload_cleanup';
+    private const TTL        = DAY_IN_SECONDS;
+    private const BATCH_SIZE = 100;
+    /** 单次认领最多解析的 URL 数，防止超长文本拖慢请求。 */
+    private const CLAIM_MAX = 20;
+
+    private static $instance = null;
+
+    public static function get_instance(): self {
+        if (null === self::$instance) {
+            self::$instance = new self();
+        }
+        return self::$instance;
+    }
+
+    public function init(): void {
+        add_action('rest_api_init', [$this, 'register_routes']);
+        add_action(self::CRON_HOOK, [$this, 'cleanup']);
+        add_action('init', [$this, 'maybe_schedule'], 20);
+        // 评论走 WP 原生管线（REST 提交 / 编辑均触发），在钩子上认领，避免侵入评论控制器。
+        add_action('comment_post', [$this, 'claim_comment'], 10, 3);
+        add_action('edit_comment', [$this, 'claim_edited_comment'], 10, 2);
+    }
+
+    public function maybe_schedule(): void {
+        if (!wp_next_scheduled(self::CRON_HOOK)) {
+            wp_schedule_event(time() + HOUR_IN_SECONDS, 'hourly', self::CRON_HOOK);
+        }
+    }
+
+    public function register_routes(): void {
+        register_rest_route('aksrt/v1', '/upload/pending/(?P<id>\d+)', [
+            'methods'             => 'DELETE',
+            'callback'            => [$this, 'rest_discard'],
+            'permission_callback' => static function (): bool {
+                return is_user_logged_in();
+            },
+            'args'                => [
+                'id' => ['sanitize_callback' => 'absint'],
+            ],
+        ]);
+    }
+
+    /** 上传成功后调用：标记为待认领。 */
+    public static function mark(int $attachment_id): void {
+        if ($attachment_id > 0) {
+            update_post_meta($attachment_id, self::META, time());
+        }
+    }
+
+    public function rest_discard(\WP_REST_Request $request): \WP_REST_Response {
+        $id = absint($request->get_param('id'));
+        if (!self::discard($id, get_current_user_id())) {
+            return new \WP_REST_Response([
+                'success' => false,
+                'message' => __('图片不存在或已被使用', 'aksrt'),
+            ], 404);
+        }
+        return new \WP_REST_Response(['success' => true]);
+    }
+
+    /** 删除用户自己仍待认领的附件；已被引用的附件绝不删除。 */
+    public static function discard(int $attachment_id, int $user_id): bool {
+        if (!self::is_owned_pending($attachment_id, $user_id)) {
+            return false;
+        }
+        return (bool) wp_delete_attachment($attachment_id, true);
+    }
+
+    /**
+     * 按 URL 列表认领（工单附件）。
+     *
+     * @param list<string> $urls
+     */
+    public static function claim_urls(array $urls, int $user_id): void {
+        if ($user_id <= 0) {
+            return;
+        }
+        foreach (array_slice(array_unique($urls), 0, self::CLAIM_MAX) as $url) {
+            if (!is_string($url) || $url === '') {
+                continue;
+            }
+            $id = (int) attachment_url_to_postid($url);
+            if (self::is_owned_pending($id, $user_id)) {
+                delete_post_meta($id, self::META);
+            }
+        }
+    }
+
+    /** 从正文中提取本站上传目录下的 URL 并认领（评论 [img=…]、举报举证）。 */
+    public static function claim_text(string $text, int $user_id): void {
+        if ($user_id <= 0 || $text === '') {
+            return;
+        }
+        $base = (string) (wp_get_upload_dir()['baseurl'] ?? '');
+        if ($base === '' || strpos($text, wp_parse_url($base, PHP_URL_PATH) ?: $base) === false) {
+            return;
+        }
+        if (!preg_match_all('#https?://[^\s\[\]"\'<>]+#i', $text, $matches)) {
+            return;
+        }
+        $urls = array_filter($matches[0], static function (string $url) use ($base): bool {
+            return strpos(set_url_scheme($url), set_url_scheme($base)) === 0;
+        });
+        self::claim_urls(array_values($urls), $user_id);
+    }
+
+    /** @param int|string $approved */
+    public function claim_comment($comment_id, $approved, $commentdata): void {
+        $data = is_array($commentdata) ? $commentdata : [];
+        self::claim_text((string) ($data['comment_content'] ?? ''), (int) ($data['user_id'] ?? 0));
+    }
+
+    public function claim_edited_comment($comment_id, $data = []): void {
+        $comment = get_comment((int) $comment_id);
+        if ($comment) {
+            self::claim_text((string) $comment->comment_content, (int) $comment->user_id);
+        }
+    }
+
+    /** 定时清理：超过 TTL 仍未认领的附件连同文件一起删除。 */
+    public function cleanup(): void {
+        global $wpdb;
+        $ids = $wpdb->get_col($wpdb->prepare(
+            "SELECT p.ID FROM {$wpdb->posts} p
+             INNER JOIN {$wpdb->postmeta} m ON m.post_id = p.ID AND m.meta_key = %s
+             WHERE p.post_type = 'attachment' AND CAST(m.meta_value AS UNSIGNED) < %d
+             ORDER BY p.ID ASC LIMIT %d",
+            self::META,
+            time() - self::TTL,
+            self::BATCH_SIZE
+        ));
+        foreach ((array) $ids as $id) {
+            wp_delete_attachment((int) $id, true);
+        }
+    }
+
+    private static function is_owned_pending(int $attachment_id, int $user_id): bool {
+        if ($attachment_id <= 0 || $user_id <= 0) {
+            return false;
+        }
+        $post = get_post($attachment_id);
+        return $post
+            && $post->post_type === 'attachment'
+            && (int) $post->post_author === $user_id
+            && get_post_meta($attachment_id, self::META, true) !== '';
+    }
+}

src/Ticket/TicketRest.php

@@ -279,6 +279,7 @@ final class TicketRest {
         if ($id <= 0) {
             return new \WP_Error('aksrt_ticket_db', __('工单提交失败', 'aksrt'), ['status' => 500]);
         }
+        \AKSRT\Attachment\PendingUploads::claim_urls($attachment, get_current_user_id());
 
         $ticket = TicketRepository::get_instance()->find($id);
         if (is_array($ticket)) {
@@ -323,6 +324,7 @@ final class TicketRest {
         if ($reply_id <= 0) {
             return new \WP_Error('aksrt_ticket_db', __('回复提交失败', 'aksrt'), ['status' => 500]);
         }
+        \AKSRT\Attachment\PendingUploads::claim_urls($attachment, get_current_user_id());
 
         $repo->touch_reply($id, 'user', get_current_user_id());
         $repo->apply_reply_status($id, $ticket, 'user');

src/Ticket/TicketRestAdmin.php

@@ -337,6 +337,7 @@ final class TicketRestAdmin {
         if ($id <= 0) {
             return new \WP_Error('aksrt_ticket_db', __('工单创建失败', 'aksrt'), ['status' => 500]);
         }
+        \AKSRT\Attachment\PendingUploads::claim_urls($attachment, get_current_user_id());
         $ticket = TicketRepository::get_instance()->find($id);
         if (is_array($ticket)) {
             TicketNotifier::user_replied($ticket);
@@ -371,6 +372,7 @@ final class TicketRestAdmin {
         if ($reply_id <= 0) {
             return new \WP_Error('aksrt_ticket_db', __('回复提交失败', 'aksrt'), ['status' => 500]);
         }
+        \AKSRT\Attachment\PendingUploads::claim_urls($attachment, get_current_user_id());
         $repo->touch_reply($id, 'admin', get_current_user_id());
         $repo->apply_reply_status($id, $ticket, 'admin');
         TicketNotifier::user_replied($repo->find($id) ?? $ticket);