统一退款不一致(refund_inconsistent)口径：引入 amounts.tolerance 并对齐模型与筛选

app/Http/Controllers/Admin/PlatformOrderController.php

@@ -1837,40 +1837,45 @@ class PlatformOrderController extends Controller
             })
             ->when(($filters['refund_inconsistent'] ?? '') !== '', function (Builder $builder) {
                 // 退款数据不一致（可治理）：
-                // - 状态=refunded 但 退款总额 < 已付金额（允许 0.01 容差）
+                // - 状态=refunded 但 退款总额 + 容差 < 已付金额
-                // - 状态!=refunded 且 已付金额>0 且 退款总额 >= 已付金额
+                // - 状态!=refunded 且 已付金额>0 且 退款总额 >= 已付金额 + 容差
                 // 退款总额口径：优先 refund_summary.total_amount；缺省回退汇总 refund_receipts[].amount
+                // 容差口径与模型 PlatformOrder::isRefundInconsistent() 对齐（config('saasshop.amounts.tolerance')）
+                $tol = (float) config('saasshop.amounts.tolerance', 0.01);
+                $tolCents = (int) round($tol * 100);
+                $tolCents = max(1, $tolCents);
+
                 $driver = $builder->getQuery()->getConnection()->getDriverName();
 
                 if ($driver === 'sqlite') {
                     $refundTotalExpr = "(CASE WHEN JSON_EXTRACT(meta, '$.refund_summary.total_amount') IS NOT NULL THEN CAST(JSON_EXTRACT(meta, '$.refund_summary.total_amount') AS REAL) ELSE (SELECT IFNULL(SUM(CAST(JSON_EXTRACT(value, '$.amount') AS REAL)), 0) FROM json_each(COALESCE(JSON_EXTRACT(meta, '$.refund_receipts'), '[]'))) END)";
 
-                    $builder->where(function (Builder $q) use ($refundTotalExpr) {
+                    $builder->where(function (Builder $q) use ($refundTotalExpr, $tolCents) {
-                        // refunded 但退款不够
+                        // refunded 但退款不够：refund_total + tol < paid
-                        $q->where(function (Builder $q2) use ($refundTotalExpr) {
+                        $q->where(function (Builder $q2) use ($refundTotalExpr, $tolCents) {
                             $q2->where('payment_status', 'refunded')
                                 ->whereRaw("paid_amount > 0")
-                                ->whereRaw("(ROUND($refundTotalExpr * 100) + 1) < ROUND(paid_amount * 100)");
+                                ->whereRaw("(ROUND($refundTotalExpr * 100) + {$tolCents}) < ROUND(paid_amount * 100)");
                         })
-                        // 非 refunded 但退款已达到/超过已付
+                        // 非 refunded 但退款已达到/超过已付 + tol：refund_total >= paid + tol
-                        ->orWhere(function (Builder $q2) use ($refundTotalExpr) {
+                        ->orWhere(function (Builder $q2) use ($refundTotalExpr, $tolCents) {
                             $q2->where('payment_status', '!=', 'refunded')
                                 ->whereRaw("paid_amount > 0")
-                                ->whereRaw("ROUND($refundTotalExpr * 100) >= ROUND(paid_amount * 100)");
+                                ->whereRaw("ROUND($refundTotalExpr * 100) >= (ROUND(paid_amount * 100) + {$tolCents})");
                         });
                     });
                 } else {
                     $refundTotalExpr = "(CASE WHEN JSON_EXTRACT(meta, '$.refund_summary.total_amount') IS NOT NULL THEN CAST(JSON_UNQUOTE(JSON_EXTRACT(meta, '$.refund_summary.total_amount')) AS DECIMAL(12,2)) ELSE (SELECT IFNULL(SUM(j.amount), 0) FROM JSON_TABLE(meta, '$.refund_receipts[*]' COLUMNS(amount DECIMAL(12,2) PATH '$.amount')) j) END)";
 
-                    $builder->where(function (Builder $q) use ($refundTotalExpr) {
+                    $builder->where(function (Builder $q) use ($refundTotalExpr, $tolCents) {
-                        $q->where(function (Builder $q2) use ($refundTotalExpr) {
+                        $q->where(function (Builder $q2) use ($refundTotalExpr, $tolCents) {
                             $q2->where('payment_status', 'refunded')
                                 ->whereRaw("paid_amount > 0")
-                                ->whereRaw("(ROUND($refundTotalExpr * 100) + 1) < ROUND(paid_amount * 100)");
+                                ->whereRaw("(ROUND($refundTotalExpr * 100) + {$tolCents}) < ROUND(paid_amount * 100)");
-                        })->orWhere(function (Builder $q2) use ($refundTotalExpr) {
+                        })->orWhere(function (Builder $q2) use ($refundTotalExpr, $tolCents) {
                             $q2->where('payment_status', '!=', 'refunded')
                                 ->whereRaw("paid_amount > 0")
-                                ->whereRaw("ROUND($refundTotalExpr * 100) >= ROUND(paid_amount * 100)");
+                                ->whereRaw("ROUND($refundTotalExpr * 100) >= (ROUND(paid_amount * 100) + {$tolCents})");
                         });
                     });
                 }

app/Models/PlatformOrder.php

@@ -48,19 +48,24 @@ class PlatformOrder extends Model
 
     public function isRefundInconsistent(): bool
     {
-        // 口径与平台订单列表 refund_inconsistent 保持一致：按分取整 + 0.01 容差
+        // 口径与平台订单列表 refund_inconsistent 保持一致：按分取整 + 容差（config('saasshop.amounts.tolerance')）
         $refundTotal = (float) $this->refundTotal();
         $paidAmount = (float) ($this->paid_amount ?? 0);
 
         $refundCents = (int) round($refundTotal * 100);
         $paidCents = (int) round($paidAmount * 100);
 
+        $tol = (float) config('saasshop.amounts.tolerance', 0.01);
+        $tolCents = (int) round($tol * 100);
+        $tolCents = max(1, $tolCents);
+
         if ((string) $this->payment_status === 'refunded') {
-            // 允许 0.01 容差：refund_total + 0.01 < paid
+            // 已退款但退款总额不足：refund_total + tol < paid
-            return ($refundCents + 1) < $paidCents;
+            return ($refundCents + $tolCents) < $paidCents;
         }
 
-        return $paidCents > 0 && $refundCents >= $paidCents;
+        // 非已退款但退款总额已达到/超过已付：refund_total >= paid + tol
+        return $paidCents > 0 && $refundCents >= ($paidCents + $tolCents);
     }
 
     public function isReconcileMismatch(): bool

tests/Feature/AdminPlatformOrderBatchActivateSubscriptionsRefundInconsistentFilterFieldsTest.php

@@ -58,7 +58,7 @@ class AdminPlatformOrderBatchActivateSubscriptionsRefundInconsistentFilterFields
             'meta' => [
                 'refund_summary' => [
                     'count' => 1,
-                    'total_amount' => 10.00,
+                    'total_amount' => 10.01,
                 ],
             ],
         ]);

tests/Feature/AdminPlatformOrderBatchMarkActivatedRefundInconsistentFilterFieldsTest.php

@@ -57,7 +57,7 @@ class AdminPlatformOrderBatchMarkActivatedRefundInconsistentFilterFieldsTest ext
             'meta' => [
                 'refund_summary' => [
                     'count' => 1,
-                    'total_amount' => 10.00,
+                    'total_amount' => 10.01,
                 ],
             ],
         ]);

tests/Feature/AdminPlatformOrderClearSyncErrorsRefundInconsistentFilterFieldsTest.php

@@ -58,7 +58,7 @@ class AdminPlatformOrderClearSyncErrorsRefundInconsistentFilterFieldsTest extend
             'meta' => [
                 'refund_summary' => [
                     'count' => 1,
-                    'total_amount' => 10.00,
+                    'total_amount' => 10.01,
                 ],
                 'subscription_activation_error' => [
                     'message' => '测试错误A',

tests/Feature/AdminPlatformOrderExportRefundInconsistentFilterTest.php

@@ -84,7 +84,7 @@ class AdminPlatformOrderExportRefundInconsistentFilterTest extends TestCase
             'meta' => [
                 'refund_summary' => [
                     'count' => 1,
-                    'total_amount' => 10.00,
+                    'total_amount' => 10.01,
                 ],
             ],
         ]);
@@ -110,7 +110,7 @@ class AdminPlatformOrderExportRefundInconsistentFilterTest extends TestCase
             'meta' => [
                 'refund_summary' => [
                     'count' => 1,
-                    'total_amount' => 10.00,
+                    'total_amount' => 10.01,
                 ],
             ],
         ]);

tests/Feature/AdminPlatformOrderRefundInconsistentFilterTest.php

@@ -87,9 +87,9 @@ class AdminPlatformOrderRefundInconsistentFilterTest extends TestCase
             'meta' => [
                 'refund_summary' => [
                     'count' => 1,
-                    'total_amount' => 10.00,
+                    'total_amount' => 10.01,
                     'last_at' => now()->toDateTimeString(),
-                    'last_amount' => 10.00,
+                    'last_amount' => 10.01,
                     'last_channel' => 'bank',
                 ],
             ],
@@ -116,9 +116,9 @@ class AdminPlatformOrderRefundInconsistentFilterTest extends TestCase
             'meta' => [
                 'refund_summary' => [
                     'count' => 1,
-                    'total_amount' => 10.00,
+                    'total_amount' => 10.01,
                     'last_at' => now()->toDateTimeString(),
-                    'last_amount' => 10.00,
+                    'last_amount' => 10.01,
                     'last_channel' => 'bank',
                 ],
             ],

tests/Feature/AdminPlatformOrderRefundInconsistentRowHintTest.php

@@ -57,7 +57,7 @@ class AdminPlatformOrderRefundInconsistentRowHintTest extends TestCase
             'meta' => [
                 'refund_summary' => [
                     'count' => 1,
-                    'total_amount' => 10.00,
+                    'total_amount' => 10.01,
                 ],
             ],
         ]);

tests/Unit/PlatformOrderRefundInconsistentTest.php

@@ -96,10 +96,12 @@ class PlatformOrderRefundInconsistentTest extends TestCase
             ],
         ]);
 
+        // refunded 状态下：只有当退款总额 + 容差 < 已付金额 才算不一致。
+        // 这里 refund_total=9.98、paid=10.00，差额 0.02 > 默认容差 0.01，因此应判定为不一致。
         $this->assertTrue($order->isRefundInconsistent());
     }
 
-    public function test_is_refund_inconsistent_when_status_not_refunded_but_refund_total_reaches_paid_amount(): void
+    public function test_is_refund_inconsistent_when_status_not_refunded_but_refund_total_reaches_paid_amount_plus_tolerance(): void
     {
         $merchant = Merchant::query()->create([
             'name' => '单测站点3',
@@ -139,6 +141,8 @@ class PlatformOrderRefundInconsistentTest extends TestCase
             ],
         ]);
 
-        $this->assertTrue($order->isRefundInconsistent());
+        // paid（非 refunded）状态下：只有当退款总额 >= 已付金额 + 容差 才算不一致。
+        // 这里 refund_total=10.00 与 paid=10.00 相等，未达到 paid + 0.01，因此不应判定不一致。
+        $this->assertFalse($order->isRefundInconsistent());
     }
 }

tests/Unit/PlatformOrderRefundInconsistentToleranceConfigTest.php

@@ -0,0 +1,84 @@
+<?php
+
+namespace Tests\Unit;
+
+use App\Models\Merchant;
+use App\Models\Plan;
+use App\Models\PlatformOrder;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Tests\TestCase;
+
+class PlatformOrderRefundInconsistentToleranceConfigTest extends TestCase
+{
+    use RefreshDatabase;
+
+    public function test_is_refund_inconsistent_respects_configured_tolerance(): void
+    {
+        config(['saasshop.amounts.tolerance' => 0.05]);
+
+        $merchant = Merchant::query()->create([
+            'name' => '容差单测站点',
+            'slug' => 'unit-test-merchant-refund-tol',
+            'status' => 'active',
+        ]);
+
+        $plan = Plan::query()->create([
+            'code' => 'unit_test_plan_refund_tol_1',
+            'name' => '容差单测套餐',
+            'billing_cycle' => 'monthly',
+            'price' => 10,
+            'list_price' => 10,
+            'status' => 'active',
+            'sort' => 10,
+            'published_at' => now(),
+        ]);
+
+        // 场景1：状态=refunded，但退款总额只差 0.02（在容差 0.05 内）=> 不应判定不一致
+        $order1 = PlatformOrder::query()->create([
+            'merchant_id' => $merchant->id,
+            'plan_id' => $plan->id,
+            'order_no' => 'PO_UNIT_REFUND_TOL_0001',
+            'order_type' => 'subscription',
+            'status' => 'activated',
+            'payment_status' => 'refunded',
+            'plan_name' => 'Unit Test Plan',
+            'billing_cycle' => 'monthly',
+            'period_months' => 1,
+            'quantity' => 1,
+            'payable_amount' => 10,
+            'paid_amount' => 10,
+            'placed_at' => now(),
+            'meta' => [
+                'refund_summary' => [
+                    'total_amount' => 9.98,
+                ],
+            ],
+        ]);
+
+        $this->assertFalse($order1->isRefundInconsistent());
+
+        // 场景2：状态!=refunded，但退款总额只比已付多 0.02（在容差 0.05 内）=> 不应判定不一致
+        $order2 = PlatformOrder::query()->create([
+            'merchant_id' => $merchant->id,
+            'plan_id' => $plan->id,
+            'order_no' => 'PO_UNIT_REFUND_TOL_0002',
+            'order_type' => 'subscription',
+            'status' => 'activated',
+            'payment_status' => 'paid',
+            'plan_name' => 'Unit Test Plan',
+            'billing_cycle' => 'monthly',
+            'period_months' => 1,
+            'quantity' => 1,
+            'payable_amount' => 10,
+            'paid_amount' => 10,
+            'placed_at' => now(),
+            'meta' => [
+                'refund_summary' => [
+                    'total_amount' => 10.02,
+                ],
+            ],
+        ]);
+
+        $this->assertFalse($order2->isRefundInconsistent());
+    }
+}