如何在 Laravel 9 API 中基于支付记录与到期日动态更新交易状态-php教程-PHP中文网

如何在 Laravel 9 API 中基于支付记录与到期日动态更新交易状态

本文详解如何在 Laravel 9 API 项目中，根据关联支付记录总金额与交易 due_on 日期，自动计算并返回准确的交易状态（paid/overdue/outstanding），避免硬编码逻辑，兼顾性能与可维护性。

本文详解如何在 laravel 9 api 项目中，根据关联支付记录总金额与交易 `due_on` 日期，自动计算并返回准确的交易状态（paid/overdue/outstanding），避免硬编码逻辑，兼顾性能与可维护性。

在构建账单或交易类 API 时，交易状态不应仅依赖静态字段，而应由实时业务规则动态判定：是否已付清？是否逾期？是否尚在宽限期内？Laravel 提供了灵活的查询构建器能力，可将复杂状态逻辑安全、高效地集成到 Eloquent 流程中。

✅ 核心逻辑说明

状态判定需同时满足两个维度：

金额维度：已支付总额（SUM(p.amount)）与交易总金额（t.amount）的关系；
时间维度：当前时间（NOW()）与截止日期（t.due_on）的比较。

对应三种状态：

laravel-specialist

精通 Laravel 10+，遵循现代 PHP 实践的 Laravel 专家。擅长优雅语法、Eloquent ORM、队列系统及企业级特性...

下载

paid：已付清（SUM(p.amount) >= t.amount）→ 无论是否超期，均视为完成；
overdue：未付清且已过期（SUM(p.amount)
outstanding：未付清但尚未到期（SUM(p.amount) NOW()）。

⚠️ 注意：原始 SQL 中 ELSE 'paid' 隐含了“付清即 paid”，但需确保 SUM(p.amount) 在无支付记录时返回 NULL —— 此时 SUM(p.amount)

✅ 推荐实现（修复版 + 可复用）

use Illuminate\Support\Facades\DB;
use Illuminate\Http\Request;

public function show(Transaction $transaction)
{
    // 使用 COALESCE 防止无支付记录时 SUM 返回 NULL
    $status = DB::table('transactions as t')
        ->select(DB::raw("
            CASE
                WHEN COALESCE(SUM(p.amount), 0)  NOW() THEN 'outstanding'
                ELSE 'paid'
            END AS status
        "))
        ->leftJoin('payments as p', 't.id', '=', 'p.transaction_id') // LEFT JOIN 确保无支付记录时仍能查出交易
        ->where('t.id', $transaction->id)
        ->where('p.buyer_id', auth()->id()) // 或使用 Auth::id()
        ->groupBy('t.id')
        ->first();

    // 若未匹配到任何 payment（如 buyer_id 不匹配），$status 可能为 null → 返回默认状态
    $status = $status ? $status->status : 'outstanding';

    return response()->json(['status' => $status]);
}

✅ 进阶建议：封装为模型访问器（推荐用于列表页 & 复用场景）

若需在 TransactionResource 或列表接口中批量展示状态，建议将逻辑移至模型中，提升可测试性与复用性：

// app/Models/Transaction.php
protected $appends = ['calculated_status'];

public function getCalculatedStatusAttribute()
{
    $paidSum = $this->payments()
        ->where('buyer_id', auth()->id())
        ->sum('amount');

    if ($paidSum >= $this->amount) {
        return 'paid';
    }

    return $this->due_on <blockquote>
<p>✅ 优势：无需原生 SQL，兼容 Eloquent 关系，支持缓存与单元测试；<br>
❗ 注意：列表页大量调用时存在 N+1 风险，可通过 withSum() 预加载优化（Laravel 9.23+）：</p>
<pre class="brush:php;toolbar:false;">Transaction::withSum(['payments as paid_sum' => fn ($q) => $q->where('buyer_id', auth()->id())], 'amount')
    ->get()
    ->map(fn ($t) => [
        'id' => $t->id,
        'status' => $t->paid_sum >= $t->amount 
            ? 'paid' 
            : ($t->due_on