From 9d3d086adc4f03560b2bd69081b1807406afb0bd Mon Sep 17 00:00:00 2001
From: kang <kangdeng28@gmail.com>
Date: Wed, 13 May 2026 17:54:05 +0800
Subject: [PATCH] =?UTF-8?q?feat:=20=E6=B7=BB=E5=8A=A0=E8=B4=A7=E5=B8=81?=
 =?UTF-8?q?=E6=A0=BC=E5=BC=8F=E5=8C=96=E9=85=8D=E7=BD=AE=EF=BC=8C=E6=94=AF?=
 =?UTF-8?q?=E6=8C=81=E8=87=AA=E5=AE=9A=E4=B9=89=E5=B0=8F=E6=95=B0=E4=BD=8D?=
 =?UTF-8?q?=E5=92=8C=E5=88=86=E9=9A=94=E7=AC=A6=EF=BC=8C=E5=A2=9E=E5=BC=BA?=
 =?UTF-8?q?=20API=20=E5=93=8D=E5=BA=94=E7=9A=84=E5=8F=AF=E8=AF=BB=E6=80=A7?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 app/Support/CurrencyFormatter.php | 45 +++++++++++++++++++++++++++++++
 config/lottery.php                | 13 +++++++++
 2 files changed, 58 insertions(+)
 create mode 100644 app/Support/CurrencyFormatter.php

diff --git a/app/Support/CurrencyFormatter.php b/app/Support/CurrencyFormatter.php
new file mode 100644
index 0000000..7f1313d
--- /dev/null
+++ b/app/Support/CurrencyFormatter.php
@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Support;
+
+/**
+ * 将「最小货币单位」整数格式化为展示用字符串（不改变业务数字，仅格式化）。
+ *
+ * 拆分位数由 {@see config('lottery.ui.format.currency.decimals')} 决定，默认 2（即 ÷100）。
+ */
+final class CurrencyFormatter
+{
+    public static function fromMinor(int|string|null $minor): string
+    {
+        if ($minor === null || $minor === '') {
+            return self::formatMinorInt(0);
+        }
+
+        return self::formatMinorInt((int) $minor);
+    }
+
+    private static function formatMinorInt(int $minorUnits): string
+    {
+        $decimals = max(0, min(12, (int) config('lottery.ui.format.currency.decimals', 2)));
+        $decSep = (string) config('lottery.ui.format.currency.decimal_separator', '.');
+        $thousandsSep = (string) config('lottery.ui.format.currency.thousands_separator', ',');
+
+        $divisor = (int) max(1, 10 ** $decimals);
+        $negative = $minorUnits < 0;
+        $abs = abs($minorUnits);
+
+        $integerPart = intdiv($abs, $divisor);
+        $fractionRaw = $abs % $divisor;
+        $fractionPadded = str_pad((string) $fractionRaw, $decimals, '0', STR_PAD_LEFT);
+
+        $integerPartFormatted = number_format((float) $integerPart, 0, $decSep, $thousandsSep);
+
+        if ($decimals === 0) {
+            return ($negative ? '-' : '').$integerPartFormatted;
+        }
+
+        return ($negative ? '-' : '').$integerPartFormatted.$decSep.$fractionPadded;
+    }
+}
diff --git a/config/lottery.php b/config/lottery.php
index c61258c..0c2c283 100644
--- a/config/lottery.php
+++ b/config/lottery.php
@@ -79,4 +79,17 @@ return [
         /** 结果发布后的冷静期（分钟），{@see draws.cooling_end_time} */
         'cooldown_minutes' => max(0, (int) env('LOTTERY_DRAW_COOLDOWN_MINUTES', 15)),
     ],
+
+    /*
+    | ui.format：API 中 *_formatted 展示用（由 {@see \App\Support\CurrencyFormatter} 读取）
+    */
+    'ui' => [
+        'format' => [
+            'currency' => [
+                'decimals' => max(0, min(12, (int) env('LOTTERY_CURRENCY_DISPLAY_DECIMALS', 2))),
+                'decimal_separator' => env('LOTTERY_CURRENCY_DECIMAL_SEP', '.'),
+                'thousands_separator' => env('LOTTERY_CURRENCY_THOUSANDS_SEP', ','),
+            ],
+        ],
+    ],
 ];