会员与点数

文本翻译（/api/translate）
  requiredPoints = max(1, ceil(字符数 / 1000))     // app.points.text-chars-per-point = 1000

文档翻译（/api/document）
  requiredPoints = 页数 × 1                        // 1 点 / 页，启动任务时一次性预扣

翻译缓存命中
  usedPoints = 0                                   // 命中 Redis 缓存不扣任何额度

Mock 降级结果
  usedPoints = 0（自动全额退还）                    // 退还备注「Mock降级占位结果退还扣点」

if (balance >= requiredPoints) {
    点数账户全额扣除                                          // ① 余额充足：只扣点数
} else if (balance > 0) {
    点数账户扣光 + 会员配额补足 (required - balance)           // ② 混合扣减
} else if (membershipRemain >= requiredPoints) {
    会员配额全额扣除                                          // ③ 无点数：纯会员额度
} else {
    throw new InsufficientPointsException(
        "点数余额与会员配额不足，无法完成本次翻译");          // → HTTP 402
}

💰 计费发生在调用真实引擎之前（deductOrThrow）； 若引擎降级为 Mock 占位结果，已扣点数自动全额退还（退还失败仅记日志，不影响响应）。

返回三档会员方案，价格与配额如下（方案在服务端硬编码组装，价格不随请求变化）：

[
  { "type": 0, "name": "包月会员", "price": 49,  "monthlyQuota": 5000 },
  { "type": 1, "name": "包季会员", "price": 139, "monthlyQuota": 5000 },
  { "type": 2, "name": "包年会员", "price": 299, "monthlyQuota": 5000 }
]

⚠️ type 字段是枚举下标（ordinal），不是枚举内部 value： 0=包月 / 1=包季 / 2=包年。而 MembershipTypeEnum 自身的 value 字段为 1/2/3， 二者不一致，集成时务必以本表 ordinal 为准，勿混用。

直接开通会员（内部开通通道，无支付环节；线上购买流程走第 09 章订单支付，支付成功后由系统调用同一订阅逻辑）。

months = {包月: 1, 包季: 3, 包年: 12}[type]
periodQuota = monthlyQuota × months          // 默认 5000 × months
startAt = now；endAt = now + months          // 精确到月（plusMonths）
status = ACTIVE(1)，periodUsed = 0
// 随后赠送点数（失败不影响开通）：
pointsService.add(userId, subscribeBonusPoints, "会员开通赠送点数",
                  "membership:{membershipId}")   // 默认 +5000 点

{
  "id": 3, "userId": 1,
  "type": "MONTHLY",              // 枚举名
  "status": "ACTIVE",             // ACTIVE(1) 正常 / EXPIRED(2) 过期 / CANCELLED(3) 取消
  "startAt": "2026-09-06T10:00:00",
  "endAt": "2026-10-06T10:00:00",
  "periodQuota": 5000,            // 本周期总配额
  "periodUsed": 0,                // 本周期已用
  "version": 0                     // 乐观锁版本号
}

💰 赠点步骤包在 try/catch 中：加点失败仅记 warn 日志，会员照常开通，响应不受影响。

查询当前登录用户的点数余额。用户 ID 由服务端从 UserContext（JWT 解析结果）取得，请求无需任何参数。

{ "balance": 4321 }

点数来源：注册赠送、会员开通赠点、退款补退等；消耗于文本翻译扣点。 会员剩余配额不在此接口返回——如需一并展示，可结合会员状态接口自行计算 剩余配额 = periodQuota - periodUsed。

取该用户 endAt 最新的一条会员记录，须同时满足：
  status == ACTIVE && endAt.isAfter(now)
不满足 → 视为无有效会员

1. 事务包裹 扣减在 TransactionTemplate 编程式事务中执行，保证「读余额 → 扣减 → 回写」原子性。
2. 乐观锁竞争 UserMembership 带 @Version 字段，MyBatis-Plus updateById 以 version 条件更新；并发扣减时后写方更新行数为 0。
3. 有限重试 更新失败自动重试，最多 3 次（MAX_RETRY=3）；重试期间重新读取最新配额再判定。
4. 超限失败 3 次重试仍失败 → 抛 IllegalStateException("操作繁忙，请稍后重试") → HTTP 409 ILLEGAL_STATE。