# New API 升级摘要

本文档记录当前分支从自定义 `v0.12.1` 基线升级到上游 `v0.12.12` 的合并结果、保留的定制内容、关键变化与验证结论。

## 版本信息

- 上游最新正式版本：`v0.12.12`
- 上游 tag 提交：`28347402`
- 合并提交：`06f9bde3` `Merge tag 'v0.12.12' into codex/redeem-subscription`
- 兼容性修复提交：`198e723b` `fix: restore Claude file conversion and preserve stream status`
- 远端分支：`lich/codex/redeem-subscription`

## 升级背景

当前代码最初基于上游 `v0.12.1` 开发，并在此基础上加入了订阅兑换码、订阅展示与部署脚本等自定义修改。

本次升级的目标是：

- 合入上游 `v0.12.12` 全量改动
- 保留现有的订阅兑换码与订阅相关定制功能
- 吸收上游在 `v0.12.10` 引入的 Stripe webhook 安全修复
- 让后端测试、前端构建恢复到可用状态

## 保留的定制功能

本次升级中保留了当前分支已有的自定义能力：

- 订阅型兑换码
- 兑换码开通订阅后的用户分组升级逻辑
- 订阅相关前端展示与文案优化
- 已购买订阅额度重置行为修复
- 自定义部署文件和远端部署脚本

## 上游关键变化

从 `v0.12.1` 升级到 `v0.12.12`，上游中比较重要的变化包括：

### 支付与安全

- `v0.12.10` 引入 Stripe webhook 异步支付处理，避免未真正支付成功就提前入账
- `TopUp` 增加 `PaymentMethod` 字段，并增强支付方式校验
- 登录与 Token 鉴权错误处理增强，减少信息泄露风险

### 订阅与钱包

- 订阅卡片支持显示下次额度重置时间
- 多处额度输入改为金额优先的交互
- 用户与管理员额度调整体验增强

### 模型与 Relay

- Claude 增加 `cache_control`、`speed` 透传控制
- Claude 空字符串消息处理修复
- Gemini、Azure 等渠道兼容性修复
- 新增 `claude-opus-4-7` 支持
- 新增 Minimax 图片生成 relay

### 前端控制台

- Dashboard 图表增强
- 分组倍率和分组规则设置页重构
- ErrorBoundary 加入，提高页面级崩溃容错能力
- 多密钥管理弹窗索引显示修复

## 本次额外补充修复

为了恢复测试通过并兼容当前仓库行为，本次额外补充了两处修复：

### 1. Claude 文件内容转换修复

位置：`relay/channel/claude/relay-claude.go`

修复内容：

- `file` 类型内容会结合文件名推断 MIME
- 文本文件会解码为 Claude `text`
- PDF 文件会转换为 Claude `document`
- 未知二进制文件会忽略，不再误判为图片

### 2. StreamStatus 保留修复

位置：`relay/helper/stream_scanner.go`

修复内容：

- `StreamScannerHandler` 不再无条件覆盖调用方预置的 `StreamStatus`
- 预初始化的错误计数与状态可以被正确保留

## 冲突处理说明

本次合并过程中，主要人工处理了以下冲突：

- `model/redemption.go`
  - 保留订阅兑换码逻辑
  - 对齐上游错误定义拆分
- `web/src/components/table/redemptions/modals/EditRedemptionModal.jsx`
  - 保留订阅兑换码创建能力
  - 合入上游金额优先输入 UI
- `web/package.json`
  - 保留现有 `antd`
  - 采用上游升级后的 `axios 1.15.0`

## 验证结果

本次升级后已完成如下验证：

### 后端

- `go build ./...` 通过
- `go test ./...` 通过

### 前端

- `bun install` 通过
- `bun run build` 通过

### 已确认吸收的安全修复

- Stripe webhook 安全修复已经随着上游 `v0.12.10+` 合入

## 当前状态

当前分支已经完成：

- 合并上游 `v0.12.12`
- 修复合并后失败测试
- 后端测试全绿
- 前端构建通过
- 已推送到远端分支 `lich/codex/redeem-subscription`

## 建议后续动作

- 在实际部署环境做一轮支付、订阅、兑换码的业务回归
- 对 Stripe webhook、订阅购买、订阅型兑换码做线上前的重点验证
- 如需发版，可基于当前分支继续打 tag 或创建发布说明