后端函数注释生成专家

calculateAmount

/**
 * 计算订单汇总金额。
 *
 * 基于商品金额与运费，按优惠券、最小消费与有效期规则计算商品与运费的折扣，
 * 在折扣后金额上按给定税率计算税额，并返回包含各项明细与应付总额的汇总结果。
 *
 * 规则概述：
 * - 负数的商品金额、运费会按0处理；税率被限制在[0, 1]区间。
 * - 优惠券仅在未过期且订单金额（商品+运费）达到最小消费时生效。
 * - 百分比券仅作用于商品金额：折扣=itemsTotal*pct，结果四舍五入到分（HALF_UP）。
 * - 固定额券先抵扣商品的剩余应付，剩余额度再抵扣运费，均不超过各自金额。
 * - 税额=（折扣后商品+折扣后运费）*税率；税额到分，按roundUp选择进位（CEILING）或四舍五入（HALF_UP）。
 * - 最终总额=应税额+税额，到分四舍五入（HALF_UP）。
 *
 * @param itemsTotal 订单商品总金额，非空；若为负数按0处理。
 * @param shippingFee 运费金额，非空；若为负数按0处理。
 * @param coupons 可选的优惠券列表；允许为null或包含null元素。过期券或不满足最小消费的券将被忽略。
 * @param taxRate 税率，非空；小于0按0处理，大于1按1处理。
 * @param roundUp 是否对税额按分位向上取整（true使用CEILING；false使用HALF_UP）。
 * @return 包含各项原始金额、折扣、税率/税额与应付总额的订单汇总对象，非空。
 * @throws NullPointerException 当itemsTotal、shippingFee或taxRate为null时抛出。
 */

功能说明

根据输入的商品金额与运费，按优惠券类型、最小消费门槛和有效期计算折扣；在折扣后金额上应用税率计算税额（支持税额进位或四舍五入），并返回包含原始金额、折扣、税率、税额及最终应付总额的汇总结果。百分比优惠仅作用于商品金额；固定额优惠优先抵扣商品，剩余再抵扣运费。负数输入被视为0，税率被限制在[0,1]区间。

参数说明表格

返回值说明

• 类型：PricingService.OrderSummary
• 含义：
  • itemsTotal：输入的商品金额，保留两位小数（HALF_UP）。
  • shippingFee：输入的运费金额，保留两位小数（HALF_UP）。
  • discountOnItems：对商品金额的总折扣，包含百分比和固定额对商品部分的抵扣，保留两位小数（HALF_UP）。
  • discountOnShipping：对运费的总折扣（仅来源于固定额券剩余额度），保留两位小数（HALF_UP）。
  • taxRate：实际用于计算的税率（已限制在[0,1]区间）。
  • tax：按折扣后金额计算的税额，保留两位小数；取整方式由roundUp决定。
  • grandTotal：应付总额=折扣后金额+税额，保留两位小数（HALF_UP）。

注意事项

• itemsTotal、shippingFee、taxRate为必填且非空，否则抛出NullPointerException。
• 优惠券生效依赖当前时间判断有效期（Instant.now）；已过期的优惠券被忽略。
• 折扣不会使商品或运费为负；对商品与运费的折扣分别不超过各自原始金额。

RefreshToken

// RefreshToken 获取或刷新指定用户的活动令牌。
// 若存在距过期时间超过 10 分钟的活动令牌，则直接返回其 ID；
// 否则撤销旧令牌（若存在）并创建新令牌：
//   - ID: 16 字节随机数据的十六进制编码（32 个字符）
//   - Secret: 32 字节随机数据的十六进制编码（64 个字符）
//   - ExpiresAt: now + 2 小时
//   - CreatedAt: now
// 返回新建或现有令牌的 ID。
// 当 repo 为空、userID 为空、随机数生成失败或保存失败时返回错误。

功能说明： 为指定用户返回可用的令牌 ID。已有令牌若在 10 分钟内即将过期则被替换，新令牌会持久化保存，过期时间基于传入的 now 设置为 2 小时后。

参数说明： | 参数名 | 类型 | 说明 | |---|---|---| | ctx | context.Context | 上下文，用于仓库调用的取消和超时控制 | | repo | TokenRepo | 令牌存储接口，用于查询、保存与撤销 | | userID | string | 目标用户标识，不能为空 | | now | time.Time | 时间基准，用于计算剩余有效期和设置过期时间 |

返回值说明：

• string：令牌 ID（可能是现有令牌或新签发的令牌）
• error：当参数非法、随机数生成失败或保存失败时返回错误

注意事项：

• GetActiveToken 与 RevokeToken 的调用错误被忽略，不影响主流程返回。
• 返回值仅包含令牌 ID，不包含 Secret。
• 过期阈值为 10 分钟，新令牌有效期为 2 小时，均基于传入的 now 计算。

randomHex

// randomHex 生成包含 2n 个十六进制字符的随机字符串。
// 使用加密安全的随机源生成 n 字节数据并进行十六进制编码。
// 当 n 为 0 时返回空字符串；当随机源读取失败时返回错误。

功能说明： 生成以十六进制表示的随机字符串，适用于令牌 ID、密钥等需要高熵值的场景。

参数说明： | 参数名 | 类型 | 说明 | |---|---|---| | n | int | 生成的随机字节数，结果字符串长度为 2n |

返回值说明：

• string：由 n 字节随机数据编码而成的十六进制字符串（长度 2n）
• error：随机数读取失败时返回

注意事项：

• 使用 crypto/rand 作为随机源，具备加密安全性。
• n 应为非负数；若为负值将导致运行时错误。