@stackonward/cli 0.0.1 → 1.0.1

package/dist/resources/templates/go-backend/internal/common/money/format_test.go

@@ -0,0 +1,204 @@
+package money
+
+import (
+	"errors"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"{{module}}/internal/common/types"
+)
+
+// ─── FormatMajorOrZero (兜底版) — banker's rounding 边界全覆盖 ───
+
+func TestFormatMajorOrZero(t *testing.T) {
+	tests := []struct {
+		name     string
+		amount   string
+		currency string
+		want     string
+	}{
+		// USD - 2 位精度
+		{"USD 截断尾零", "9.9900", "USD", "9.99"},
+		{"USD 整数", "10", "USD", "10.00"},
+		{"USD 零", "0", "USD", "0.00"},
+
+		// USD banker's rounding (HALF_EVEN)
+		{"USD HalfEven 0.005 → 0.00", "0.005", "USD", "0.00"},
+		{"USD HalfEven 0.015 → 0.02", "0.015", "USD", "0.02"},
+		{"USD HalfEven 0.025 → 0.02", "0.025", "USD", "0.02"},
+		{"USD HalfEven 0.035 → 0.04", "0.035", "USD", "0.04"},
+		{"USD HalfEven 1.005 → 1.00", "1.005", "USD", "1.00"},
+		{"USD HalfEven 1.015 → 1.02", "1.015", "USD", "1.02"},
+		{"USD HalfEven 大于半数仍向上", "1.006", "USD", "1.01"},
+		{"USD HalfEven 小于半数仍向下", "1.004", "USD", "1.00"},
+
+		// USD 负数 banker's rounding
+		{"USD 负数尾零", "-9.9900", "USD", "-9.99"},
+		{"USD 负数 -0.005 → 0.00", "-0.005", "USD", "0.00"},
+		{"USD 负数 -0.015 → -0.02", "-0.015", "USD", "-0.02"},
+		{"USD 负数 -0.025 → -0.02", "-0.025", "USD", "-0.02"},
+
+		// USD 大额
+		{"USD 大额", "1234567890.1234", "USD", "1234567890.12"},
+
+		// JPY - 0 位精度
+		{"JPY 整数", "1999", "JPY", "1999"},
+		{"JPY HalfEven 1999.5 → 2000", "1999.5", "JPY", "2000"},
+		{"JPY HalfEven 2000.5 → 2000", "2000.5", "JPY", "2000"},
+		{"JPY HalfEven 2001.5 → 2002", "2001.5", "JPY", "2002"},
+		{"JPY 零", "0", "JPY", "0"},
+		{"JPY 整数尾零", "1999.0000", "JPY", "1999"},
+		{"JPY 截断小数大于半数", "1999.7", "JPY", "2000"},
+
+		// BHD - 3 位精度
+		{"BHD 截断到 3 位", "19.9999", "BHD", "20.000"},
+		{"BHD 保留 3 位", "19.123", "BHD", "19.123"},
+		{"BHD HalfEven 0.0005 → 0.000", "0.0005", "BHD", "0.000"},
+		{"BHD HalfEven 0.0015 → 0.002", "0.0015", "BHD", "0.002"},
+
+		// 边界
+		{"空字符串 USD", "", "USD", "0.00"},
+		{"空字符串 JPY", "", "JPY", "0"},
+		{"空字符串 BHD", "", "BHD", "0.000"},
+		{"空字符串未知货币", "", "XYZ", "0.00"},
+
+		// 未知货币 fallback 2 位
+		{"未知货币", "9.9900", "XYZ", "9.99"},
+		{"小写货币代码", "9.9900", "usd", "9.99"},
+
+		// 解析失败 fail-closed → 零
+		{"非法 decimal USD", "abc", "USD", "0.00"},
+		{"非法 decimal JPY", "1.2.3", "JPY", "0"},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			got := FormatMajorOrZero(tc.amount, tc.currency)
+			assert.Equal(t, tc.want, got)
+		})
+	}
+}
+
+func TestFormatMajorWithCurrencySymbolOrZero(t *testing.T) {
+	bhdMeta, ok := types.LookupCurrencyMeta("BHD")
+	require.True(t, ok)
+
+	tests := []struct {
+		name     string
+		amount   string
+		currency string
+		want     string
+	}{
+		{"USD trims storage scale", "29.9900", "USD", "$29.99"},
+		{"JPY uses zero decimals", "1999.0000", "JPY", "¥1999"},
+		{"BHD uses three decimals", "1.2345", "BHD", bhdMeta.Symbol + "1.234"},
+		{"unknown currency keeps code", "9.9900", "xyz", "XYZ9.99"},
+		{"empty currency omits symbol", "9.9900", "", "9.99"},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			got := FormatMajorWithCurrencySymbolOrZero(tc.amount, tc.currency)
+			assert.Equal(t, tc.want, got)
+		})
+	}
+}
+
+// ─── FormatMajor (严格版) — 错误传递 ─────────────────────────────
+
+func TestFormatMajor(t *testing.T) {
+	t.Run("正常路径", func(t *testing.T) {
+		got, err := FormatMajor("9.9900", "USD")
+		require.NoError(t, err)
+		assert.Equal(t, "9.99", got)
+	})
+
+	t.Run("空字符串返回 ErrEmptyAmount", func(t *testing.T) {
+		_, err := FormatMajor("", "USD")
+		require.Error(t, err)
+		assert.True(t, errors.Is(err, ErrEmptyAmount))
+	})
+
+	t.Run("非法 decimal 返回 ErrInvalidAmount", func(t *testing.T) {
+		_, err := FormatMajor("abc", "USD")
+		require.Error(t, err)
+		assert.True(t, errors.Is(err, ErrInvalidAmount))
+	})
+
+	t.Run("多个小数点返回 ErrInvalidAmount", func(t *testing.T) {
+		_, err := FormatMajor("1.2.3", "USD")
+		require.Error(t, err)
+		assert.True(t, errors.Is(err, ErrInvalidAmount))
+	})
+
+	t.Run("JPY 0 位精度", func(t *testing.T) {
+		got, err := FormatMajor("1999.5", "JPY")
+		require.NoError(t, err)
+		assert.Equal(t, "2000", got)
+	})
+
+	t.Run("BHD 3 位精度", func(t *testing.T) {
+		got, err := FormatMajor("19.9999", "BHD")
+		require.NoError(t, err)
+		assert.Equal(t, "20.000", got)
+	})
+
+	t.Run("未知货币兜底 2 位精度（不报错）", func(t *testing.T) {
+		got, err := FormatMajor("9.9900", "XYZ")
+		require.NoError(t, err)
+		assert.Equal(t, "9.99", got)
+	})
+}
+
+// ─── FormatMajorPtrOrZero / FormatMajorPtrsOrZero (兜底版) ──────
+
+func TestFormatMajorPtrOrZero(t *testing.T) {
+	t.Run("nil 透传 nil", func(t *testing.T) {
+		assert.Nil(t, FormatMajorPtrOrZero(nil, "USD"))
+	})
+	t.Run("非 nil 正常格式化", func(t *testing.T) {
+		amount := "9.9900"
+		got := FormatMajorPtrOrZero(&amount, "USD")
+		require.NotNil(t, got)
+		assert.Equal(t, "9.99", *got)
+	})
+	t.Run("非 nil JPY", func(t *testing.T) {
+		amount := "1999.50"
+		got := FormatMajorPtrOrZero(&amount, "JPY")
+		require.NotNil(t, got)
+		assert.Equal(t, "2000", *got)
+	})
+	t.Run("非 nil 解析失败兜底零值", func(t *testing.T) {
+		amount := "abc"
+		got := FormatMajorPtrOrZero(&amount, "USD")
+		require.NotNil(t, got)
+		assert.Equal(t, "0.00", *got)
+	})
+}
+
+func TestFormatMajorPtrsOrZero(t *testing.T) {
+	usd := "USD"
+	amount := "9.9900"
+	t.Run("amount nil 透传", func(t *testing.T) {
+		assert.Nil(t, FormatMajorPtrsOrZero(nil, &usd))
+	})
+	t.Run("currency nil 透传", func(t *testing.T) {
+		assert.Nil(t, FormatMajorPtrsOrZero(&amount, nil))
+	})
+	t.Run("两者 nil 透传", func(t *testing.T) {
+		assert.Nil(t, FormatMajorPtrsOrZero(nil, nil))
+	})
+	t.Run("两者非 nil 格式化", func(t *testing.T) {
+		got := FormatMajorPtrsOrZero(&amount, &usd)
+		require.NotNil(t, got)
+		assert.Equal(t, "9.99", *got)
+	})
+	t.Run("解析失败兜底零值", func(t *testing.T) {
+		bad := "abc"
+		got := FormatMajorPtrsOrZero(&bad, &usd)
+		require.NotNil(t, got)
+		assert.Equal(t, "0.00", *got)
+	})
+}

package/dist/resources/templates/go-backend/internal/common/money/gateway.go

@@ -0,0 +1,144 @@
+package money
+
+import (
+	"fmt"
+	"math"
+	"math/big"
+	"strings"
+)
+
+// MinorToMajor 将最小货币单位转换为主要单位字符串。
+//
+// 根据货币的 DecimalPlaces 自动选择除数：
+//   - USD (2位): 1999  → "19.99"
+//   - JPY (0位): 1999  → "1999"
+//   - BHD (3位): 19990 → "19.990"
+//
+// 用于支付网关响应解码（Stripe / Airwallex 把金额以最小单位整数返回）。
+//
+// 命名与 Stripe / moneyphp 行业术语对齐；不返回 error，未知货币按 2 位精度
+// 兜底，调用方需保证 currency 合法。
+func MinorToMajor(minorUnit int64, currencyCode string) string {
+	dp := DecimalPlaces(currencyCode)
+	if dp == 0 {
+		return fmt.Sprintf("%d", minorUnit)
+	}
+	divisor := int64(math.Pow10(dp))
+	whole := minorUnit / divisor
+	frac := minorUnit % divisor
+	if frac < 0 {
+		frac = -frac
+	}
+	return fmt.Sprintf("%d.%0*d", whole, dp, frac)
+}
+
+// MajorToMinor 将主要货币单位字符串转换为最小货币单位。
+//
+// 根据货币的 DecimalPlaces 自动选择乘数：
+//   - USD (2位): "19.99"  → 1999
+//   - JPY (0位): "1999"   → 1999（不乘）
+//   - BHD (3位): "19.990" → 19990
+//
+// 用于支付网关请求编码（金额必须以最小单位整数发送给 Stripe / Airwallex）。
+//
+// 错误条件：
+//   - amount 为空 / 不匹配严格十进制正则 → ErrInvalidAmount（拒绝 "5e9999" /
+//     "0x10" / "+5" 等非财务格式，与 Stripe API、Java BigDecimal(String) 一致）
+//   - amount 整数部分非法 → ErrInvalidAmount
+//   - amount 小数部分非法 → ErrInvalidAmount
+//   - amount 小数位数超出货币精度 → ErrInvalidAmount（与 Stripe API 一致，
+//     拒绝 fractional minor unit；如 USD "9.999" 不能编码为 999.9 美分）
+//
+// 注：`MajorToMinor` 是网关编码入口（fail-loud），与 `FromMajor` 的展示路径
+// 截断行为不同 —— 后者用于内部 Money 构造，超出精度按截断处理是合理的展示
+// 兜底；前者要发送给真实支付网关，必须严格拒绝精度溢出，否则会丢失用户金额。
+func MajorToMinor(amount, currencyCode string) (int64, error) {
+	return majorToMinor(amount, DecimalPlaces(currencyCode), currencyCode)
+}
+
+// MajorToMinorWithExponent 使用已锁定的货币指数将主要单位转换为最小单位。
+// 调用方必须从成交或价格快照读取指数，不能在消费边界按币种再次推断。
+func MajorToMinorWithExponent(amount string, exponent int) (int64, error) {
+	if exponent < 0 || exponent > 18 {
+		return 0, fmt.Errorf("%w: currency exponent %d is outside [0,18]", ErrInvalidAmount, exponent)
+	}
+	return majorToMinor(amount, exponent, fmt.Sprintf("exponent:%d", exponent))
+}
+
+func majorToMinor(amount string, dp int, precisionOwner string) (int64, error) {
+	multiplier := int64(math.Pow10(dp))
+
+	// 严格十进制前置校验：复用 format.go 的 strictDecimalRe，避免 big.Int.SetString
+	// 接受 "+5" / 空字符串等非财务格式（与下方 SplitN("", ".", 2) 配合时，
+	// "" 会被解析为单元素切片导致后续逻辑出错；负号检查也会越界）。
+	if !strictDecimalRe.MatchString(amount) {
+		return 0, fmt.Errorf("%w: %q", ErrInvalidAmount, amount)
+	}
+
+	parts := strings.SplitN(amount, ".", 2)
+	negative := strings.HasPrefix(amount, "-")
+
+	intStr := parts[0]
+	if negative {
+		intStr = intStr[1:]
+	}
+
+	integerPart := new(big.Int)
+	if _, ok := integerPart.SetString(intStr, 10); !ok {
+		return 0, fmt.Errorf("%w: %s", ErrInvalidAmount, amount)
+	}
+
+	result := new(big.Int).Mul(integerPart, big.NewInt(multiplier))
+
+	if len(parts) == 2 {
+		fracStr := parts[1]
+		// 拒绝精度溢出：USD 只支持 2 位小数，"9.999" 无法表达为整数美分。
+		// 例外：超出精度的部分如果全是零，可以容忍（"1999.0" 当 JPY 处理）。
+		if len(fracStr) > dp {
+			overflow := fracStr[dp:]
+			fp := new(big.Int)
+			if _, ok := fp.SetString(overflow, 10); !ok {
+				return 0, fmt.Errorf("%w: invalid fractional part %q", ErrInvalidAmount, overflow)
+			}
+			if fp.Sign() != 0 {
+				return 0, fmt.Errorf("%w: amount %q exceeds %s precision (%d decimal places)",
+					ErrInvalidAmount, amount, precisionOwner, dp)
+			}
+			fracStr = fracStr[:dp]
+		}
+		if dp > 0 {
+			for len(fracStr) < dp {
+				fracStr += "0"
+			}
+			fp := new(big.Int)
+			if _, ok := fp.SetString(fracStr, 10); !ok {
+				return 0, fmt.Errorf("%w: invalid fractional part %q", ErrInvalidAmount, fracStr)
+			}
+			result.Add(result, fp)
+		}
+	}
+
+	if negative {
+		result.Neg(result)
+	}
+
+	if !result.IsInt64() {
+		return 0, fmt.Errorf("%w: amount %q exceeds int64 minor-unit range", ErrInvalidAmount, amount)
+	}
+
+	return result.Int64(), nil
+}
+
+// FormatMajorFromFloat 将 float64 金额按货币精度格式化为字符串。
+//
+// 根据货币的 DecimalPlaces 自动决定小数位数：
+//   - USD (2位): 19.99   → "19.99"
+//   - JPY (0位): 1999.0  → "1999"
+//   - BHD (3位): 19.99   → "19.990"
+//
+// 用于网关返回 float 金额的展示路径（Airwallex / Apple IAP）。
+// 不返回 error；未知货币按 2 位精度兜底。
+func FormatMajorFromFloat(amount float64, currencyCode string) string {
+	dp := DecimalPlaces(currencyCode)
+	return fmt.Sprintf("%.*f", dp, amount)
+}

package/dist/resources/templates/go-backend/internal/common/money/gateway_test.go

@@ -0,0 +1,165 @@
+package money
+
+import (
+	"errors"
+	"math"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// ─── MinorToMajor ────────────────────────────────────────────────
+
+func TestMinorToMajor(t *testing.T) {
+	tests := []struct {
+		name         string
+		minorUnit    int64
+		currencyCode string
+		want         string
+	}{
+		{"USD 美元", 1999, "USD", "19.99"},
+		{"USD 整数美元", 100, "USD", "1.00"},
+		{"USD 不足 1 美元", 1, "USD", "0.01"},
+		{"USD 零", 0, "USD", "0.00"},
+		{"USD 大额", 123456789, "USD", "1234567.89"},
+
+		{"JPY 无小数", 1999, "JPY", "1999"},
+		{"JPY 零", 0, "JPY", "0"},
+
+		{"BHD 三位小数", 19990, "BHD", "19.990"},
+		{"BHD 不足 1 BHD", 1, "BHD", "0.001"},
+
+		{"未知货币兜底 2 位", 1999, "XYZ", "19.99"},
+
+		{"负数 USD", -1999, "USD", "-19.99"},
+		{"负数 JPY", -1999, "JPY", "-1999"},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			got := MinorToMajor(tc.minorUnit, tc.currencyCode)
+			assert.Equal(t, tc.want, got)
+		})
+	}
+}
+
+// ─── MajorToMinor ────────────────────────────────────────────────
+
+func TestMajorToMinor(t *testing.T) {
+	tests := []struct {
+		name         string
+		amount       string
+		currencyCode string
+		want         int64
+		wantErr      bool
+	}{
+		{"USD 19.99 → 1999", "19.99", "USD", 1999, false},
+		{"USD 整数", "100", "USD", 10000, false},
+		{"USD 零", "0", "USD", 0, false},
+		{"USD 负数", "-5.50", "USD", -550, false},
+		{"USD int64 最大值", "92233720368547758.07", "USD", math.MaxInt64, false},
+		{"USD int64 最小值", "-92233720368547758.08", "USD", math.MinInt64, false},
+		{"USD 拒绝正向溢出", "92233720368547758.08", "USD", 0, true},
+		{"USD 拒绝负向溢出", "-92233720368547758.09", "USD", 0, true},
+		// 网关编码入口（fail-loud）：精度超出必须拒绝，与 Stripe API 一致
+		{"USD 拒绝精度溢出", "10.999", "USD", 0, true},
+		{"USD 拒绝多位精度溢出", "10.12345", "USD", 0, true},
+
+		{"JPY 整数", "1999", "JPY", 1999, false},
+		{"JPY 整数带 .0 容忍", "1999.0", "JPY", 1999, false},
+		{"JPY 拒绝小数", "1999.9", "JPY", 0, true},
+		{"JPY int64 最大值", "9223372036854775807", "JPY", math.MaxInt64, false},
+		{"JPY int64 最小值", "-9223372036854775808", "JPY", math.MinInt64, false},
+		{"JPY 拒绝正向溢出", "9223372036854775808", "JPY", 0, true},
+		{"JPY 拒绝负向溢出", "-9223372036854775809", "JPY", 0, true},
+
+		{"BHD 三位小数", "19.990", "BHD", 19990, false},
+		{"BHD int64 最大值", "9223372036854775.807", "BHD", math.MaxInt64, false},
+		{"BHD int64 最小值", "-9223372036854775.808", "BHD", math.MinInt64, false},
+		{"BHD 拒绝正向溢出", "9223372036854775.808", "BHD", 0, true},
+		{"BHD 拒绝负向溢出", "-9223372036854775.809", "BHD", 0, true},
+		// 超出精度但全为零 → 容忍（"19.9990" 等价于 "19.999"）
+		{"BHD 多位尾零容忍", "19.9990", "BHD", 19999, false},
+		// 超出精度且有非零位 → 拒绝
+		{"BHD 拒绝四位精度溢出", "19.9999", "BHD", 0, true},
+
+		{"非法整数部分", "abc.00", "USD", 0, true},
+		{"完全非法", "abc", "USD", 0, true},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			got, err := MajorToMinor(tc.amount, tc.currencyCode)
+			if tc.wantErr {
+				require.Error(t, err)
+				assert.True(t, errors.Is(err, ErrInvalidAmount))
+			} else {
+				require.NoError(t, err)
+				assert.Equal(t, tc.want, got)
+			}
+		})
+	}
+}
+
+func TestMajorToMinorWithExponentUsesSnapshottedPrecision(t *testing.T) {
+	minor, err := MajorToMinorWithExponent("1.234", 3)
+	require.NoError(t, err)
+	assert.Equal(t, int64(1234), minor)
+
+	_, err = MajorToMinorWithExponent("1.234", 2)
+	require.Error(t, err)
+	assert.True(t, errors.Is(err, ErrInvalidAmount))
+
+	_, err = MajorToMinorWithExponent("1", 19)
+	require.Error(t, err)
+	assert.True(t, errors.Is(err, ErrInvalidAmount))
+}
+
+// ─── 双向往返一致性 ──────────────────────────────────────────────
+
+func TestMinorMajorRoundTrip(t *testing.T) {
+	cases := []struct {
+		minor    int64
+		currency string
+	}{
+		{1999, "USD"},
+		{100, "USD"},
+		{0, "USD"},
+		{1999, "JPY"},
+		{19990, "BHD"},
+	}
+	for _, c := range cases {
+		major := MinorToMajor(c.minor, c.currency)
+		back, err := MajorToMinor(major, c.currency)
+		require.NoError(t, err)
+		assert.Equal(t, c.minor, back, "round trip mismatch for %d %s", c.minor, c.currency)
+	}
+}
+
+// ─── FormatMajorFromFloat ────────────────────────────────────────
+
+func TestFormatMajorFromFloat(t *testing.T) {
+	tests := []struct {
+		name         string
+		amount       float64
+		currencyCode string
+		want         string
+	}{
+		{"USD 2 位精度", 19.99, "USD", "19.99"},
+		{"USD 截断展示", 19.999, "USD", "20.00"},
+		{"JPY 0 位精度", 1999.0, "JPY", "1999"},
+		{"JPY 浮点输入截断", 1999.7, "JPY", "2000"},
+		{"BHD 3 位精度", 19.99, "BHD", "19.990"},
+		{"未知货币兜底 2 位", 19.99, "XYZ", "19.99"},
+		{"零", 0.0, "USD", "0.00"},
+		{"负数", -19.99, "USD", "-19.99"},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			got := FormatMajorFromFloat(tc.amount, tc.currencyCode)
+			assert.Equal(t, tc.want, got)
+		})
+	}
+}

package/dist/resources/templates/go-backend/internal/common/money/rounding.go

@@ -0,0 +1,56 @@
+package money
+
+import (
+	"fmt"
+
+	"github.com/shopspring/decimal"
+)
+
+// DivideMinorUnitsHalfEven 使用纯整数运算将最小货币单位按 HALF_EVEN 舍入相除。
+// 支持正负金额；除数必须为正数。实现不对余数乘二，避免 int64 边界溢出。
+func DivideMinorUnitsHalfEven(amountMinor, divisor int64) (int64, error) {
+	if divisor <= 0 {
+		return 0, fmt.Errorf("%w: %d", ErrInvalidDivisor, divisor)
+	}
+	quotient := amountMinor / divisor
+	remainder := amountMinor % divisor
+	if remainder == 0 {
+		return quotient, nil
+	}
+
+	direction := int64(1)
+	if remainder < 0 {
+		remainder = -remainder
+		direction = -1
+	}
+	complement := divisor - remainder
+	if remainder > complement || (remainder == complement && quotient%2 != 0) {
+		quotient += direction
+	}
+	return quotient, nil
+}
+
+// formatDecimalBankerRounding 用 banker's rounding（HALF_EVEN）格式化金额。
+func formatDecimalBankerRounding(value decimal.Decimal, dp int) string {
+	if dp < 0 {
+		dp = 0
+	}
+	return value.RoundBank(int32(dp)).StringFixed(int32(dp))
+}
+
+// zeroWithDecimals 返回指定小数位的零值字符串，如 (2 → "0.00"、0 → "0"、3 → "0.000")。
+func zeroWithDecimals(dp int) string {
+	if dp <= 0 {
+		return "0"
+	}
+	return "0." + repeatZeros(dp)
+}
+
+// repeatZeros 生成 n 个 '0' 字符串，避免 strings.Repeat 在热点路径上的额外分配。
+func repeatZeros(n int) string {
+	buf := make([]byte, n)
+	for i := range buf {
+		buf[i] = '0'
+	}
+	return string(buf)
+}

package/dist/resources/templates/go-backend/internal/common/money/rounding_test.go

@@ -0,0 +1,51 @@
+package money
+
+import (
+	"errors"
+	"math"
+	"testing"
+)
+
+func TestDivideMinorUnitsHalfEven(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name        string
+		amountMinor int64
+		divisor     int64
+		want        int64
+	}{
+		{name: "exact", amountMinor: 1200, divisor: 12, want: 100},
+		{name: "positive below half", amountMinor: 1000, divisor: 12, want: 83},
+		{name: "positive odd tie", amountMinor: 1002, divisor: 12, want: 84},
+		{name: "positive even tie", amountMinor: 1014, divisor: 12, want: 84},
+		{name: "negative odd tie", amountMinor: -1002, divisor: 12, want: -84},
+		{name: "negative even tie", amountMinor: -1014, divisor: 12, want: -84},
+		{name: "maximum int64", amountMinor: math.MaxInt64, divisor: 2, want: 4611686018427387904},
+		{name: "minimum int64", amountMinor: math.MinInt64, divisor: 3, want: -3074457345618258603},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			t.Parallel()
+			got, err := DivideMinorUnitsHalfEven(test.amountMinor, test.divisor)
+			if err != nil {
+				t.Fatalf("DivideMinorUnitsHalfEven() error = %v", err)
+			}
+			if got != test.want {
+				t.Fatalf("DivideMinorUnitsHalfEven() = %d, want %d", got, test.want)
+			}
+		})
+	}
+}
+
+func TestDivideMinorUnitsHalfEvenRejectsNonPositiveDivisor(t *testing.T) {
+	t.Parallel()
+
+	for _, divisor := range []int64{0, -1} {
+		_, err := DivideMinorUnitsHalfEven(1000, divisor)
+		if !errors.Is(err, ErrInvalidDivisor) {
+			t.Fatalf("DivideMinorUnitsHalfEven() error = %v, want ErrInvalidDivisor", err)
+		}
+	}
+}

package/dist/resources/templates/go-backend/internal/common/principal/context.go

@@ -0,0 +1,56 @@
+package principal
+
+import (
+	"context"
+
+	"github.com/gin-gonic/gin"
+)
+
+// ctxKey 私有 context key 类型，避免与其他 package collision。
+type ctxKey struct{}
+
+// ginKey gin.Context 中的 key 名（使用与 ctx 解耦的字符串以方便跨 helper 读取）。
+const ginKey = "principal"
+
+// WithPrincipal 把 Principal 写入 context.Context（供 service 层读取）+ gin.Context（供 handler 读取）。
+func WithPrincipal(c *gin.Context, p *Principal) {
+	c.Set(ginKey, p)
+	ctx := context.WithValue(c.Request.Context(), ctxKey{}, p)
+	c.Request = c.Request.WithContext(ctx)
+}
+
+// Get 读取 Principal。未注入时返回 nil（公开路径 + 匿名访问场景）。
+//
+// 优先 gin.Context 路径（handler 用），fallback 到 context.Context（service 用）。
+func Get(c *gin.Context) *Principal {
+	if v, ok := c.Get(ginKey); ok {
+		if p, ok := v.(*Principal); ok {
+			return p
+		}
+	}
+	return FromContext(c.Request.Context())
+}
+
+// FromContext 仅从 context.Context 读取（service 层调用，无 gin.Context）。
+func FromContext(ctx context.Context) *Principal {
+	if ctx == nil {
+		return nil
+	}
+	v := ctx.Value(ctxKey{})
+	if p, ok := v.(*Principal); ok {
+		return p
+	}
+	return nil
+}
+
+// MustGet 读取 Principal，未注入时 panic。
+//
+// 仅在已挂载 PrincipalContext middleware 的 authenticated 路由 handler 中使用。
+// 公开路径请用 Get（nil-safe）。
+func MustGet(c *gin.Context) *Principal {
+	p := Get(c)
+	if p == nil {
+		panic("principal: middleware.PrincipalContext not registered for this route")
+	}
+	return p
+}