[!NOTE]
当前 MAX API 分为正式版和 Preview 预览版。Preview 预览版用于提前开放新能力和修复，便于在真实环境中验证兼容性、稳定性和安全性；正式版将在对应 Preview 预览版稳定运行 1 周后正式发布，以保障系统安全性和可靠性。

Release Notes

GitHub地址：

https://github.com/MAX-API-Next/MAX-API/releases/tag/v1.0.3-preview.2

Highlights

• 加强支付、订阅、兑换码、邀请额度和任务计费链路的一致性，降低重复回调、重复兑换、重复退款和并发扣减造成的错账风险。
• 新增 OpenAI Chat / Responses 空补全重试能力，并将内部空补全错误码与通用 empty_response 区分，避免影响 Gemini 等其它渠道的正常重试策略。
• 优化用量日志加载体验：页面进入后不再自动查询大批量日志，搜索后加载列表，详情正文按需打开。
• 用户管理新增余额状态筛选和负余额提示，便于快速定位异常账户。
• 后台顶部导航支持配置自定义导航项，方便接入站内页面或外部链接。

New Features

• 系统设置新增“空补全重试”开关 EmptyCompletionRetryEnabled。
• 新增内部错误码 empty_completion，专用于 OpenAI Responses 空补全重试链路。
• 用量日志新增详情接口：
  • 管理员可查看完整日志详情。
  • 普通用户只能查看自己的日志详情。
• 用户管理新增余额状态筛选：
  • 负余额
  • 零余额
  • 正常余额
• 用户余额列新增负余额异常标记和说明提示。
• 顶部导航新增自定义导航项配置，支持名称、链接和启用状态。
• 兑换码批量复制改为只复制兑换码本身，方便直接分发。

Improvements

• 支付、订阅、兑换码等事务路径统一使用 GORM v2 clause.Locking 行锁封装。
• MySQL 下用户额度更新遇到 no-op RowsAffected=0 时，会在事务内确认用户是否存在，避免把有效订单误判为用户不存在。
• Stripe / Creem / Waffo / Waffo Pancake / 手动补单等充值路径统一加强额度写入校验。
• 兑换码创建和更新增加服务端额度正数校验，并补充后端 i18n 文案。
• 订阅订单完成、过期、余额支付、预扣退款、用量回写等路径加强事务状态判断和幂等处理。
• 订阅计费使用数据库事务时间，减少应用时间和数据库时间不一致导致的边界问题。
• 订阅负向用量调整返回实际生效 delta，日志和结算字段按实际可退额度记录。
• 用量日志列表默认隐藏请求/响应审计正文，详情弹窗按需加载完整内容。
• 用量日志列表和统计统一由 searchVersion 触发，避免首屏自动查询和重复刷新。
• 用量日志页默认分页调整为 100 条，降低大表查询压力。
• 用户搜索在关键字为空时不再拼接全字段 LIKE '%%'。
• OpenAI Responses 兼容层增强：
  • 支持 refusal 文本提取。
  • 空输出可触发重试。
  • EOF 且无可见输出时也可触发空补全检测。
  • 流式前置事件增加缓冲上限，避免无界占用内存。
  • 空补全不会触发自动禁用通道。
  • 记录空补全重试链路，便于排查。

Bug Fixes

• 修复 Gemini empty_response 在 EmptyCompletionRetryEnabled=false 时被误阻止重试的问题。
• 修复 OpenAI 空补全内部重试复用通用 empty_response 错误码导致跨渠道语义混淆的问题。
• 修复 Responses / Chat 流式空补全在缺少 response.completed、仅 EOF 结束时无法重试的问题。
• 修复 Responses 流式处理在首个可见内容前无界缓存 SSE 事件导致 TTFB 和内存风险的问题。
• 修复纯空白 delta 可能被误判为可见输出的问题。
• 修复兑换码重复兑换可能导致重复加余额的问题。
• 修复零额度或负额度兑换码可能进入后续兑换链路的问题。
• 修复 MySQL no-op 更新可能导致有效充值或兑换被 RowsAffected=0 误判失败的问题。
• 修复订阅订单重复完成时可能重复创建订阅或充值记录的问题。
• 修复订阅预扣退款重复执行时可能重复返还额度的问题。
• 修复订阅余额支付在余额不足时可能越界扣减的问题。
• 修复订阅用量负向调整可能低于 0 或日志记录超额退款的问题。
• 修复部分支付网关回调状态更新未严格限制 pending 状态的问题。
• 修复邀请额度转余额的并发扣减一致性问题。
• 修复用户管理余额筛选在空关键字下仍触发全字段模糊搜索的问题。

Compatibility Notes

• 新增 EmptyCompletionRetryEnabled 配置项，默认关闭；启用时仍需配置 RetryTimes > 0。
• OpenAI 空补全内部错误码从通用 empty_response 独立为 empty_completion。
• Gemini 等其它渠道返回的 empty_response 继续按普通状态码重试策略处理。
• 用量日志页行为变化：进入页面不会立即加载日志，需要点击“搜索”。
• 用量日志默认分页大小调整为 100。
• 顶部导航配置结构新增 custom 字段，旧配置按默认值兼容。
• 行锁封装在 SQLite 下不会启用 FOR UPDATE；MySQL / PostgreSQL 使用数据库行锁能力。
• 订阅用量调整函数返回值发生变化，内部调用已同步为实际应用 delta。

Verification

• go test ./...
• go test ./model
• go test ./controller
• go test ./relay/channel/openai
• go test ./service ./service/openaicompat
• bunx eslint 针对变更的前端文件
• bun run typecheck
• bun run i18n:sync
• git diff --check