From c60fd7074a0845e6415fc23992084320721d2391 Mon Sep 17 00:00:00 2001
From: Lich-Mac-Mini <lich@Lich-Mac-MinideMac-mini.local>
Date: Fri, 17 Apr 2026 20:34:55 +0800
Subject: [PATCH] docs: add upgrade summary for v0.12.12 merge

---
 docs/upgrade-v0.12.12.md | 135 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 135 insertions(+)
 create mode 100644 docs/upgrade-v0.12.12.md

diff --git a/docs/upgrade-v0.12.12.md b/docs/upgrade-v0.12.12.md
new file mode 100644
index 00000000..bf14caf1
--- /dev/null
+++ b/docs/upgrade-v0.12.12.md
@@ -0,0 +1,135 @@
+# 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 或创建发布说明