Spec: 分阶段评估并吸收 upstream/main 更新

[xunyoyo]

背景

本 fork 已经长期偏离 upstream/main，不能直接把上游整段 merge 进来。目标是把 upstream/main 里值得吸收的安全修复、网关兼容、模型/账号/运维改进分阶段更新到本仓 main，同时保留本 fork 已上线的订阅计费、支付、积分、公益 key、运维口径和部署语义。

本 issue 作为这轮 upstream 同步工作的 spec；后续实现和 PR 拆分都以这里为准。

当前证据快照

取证时间：2026-07-08

• 本仓基线：origin/main = becb0f350
• 上游目标：upstream/main = 6f43986c3
• merge-base：945b9b208b32dac443cf25e1e96f4ac587c93223
• git rev-list --left-right --count origin/main...upstream/main：本 fork 独有 146 个提交，上游独有 433 个提交
• patch-id 去重后：upstream/main 仍有 277 个 patch 不在本 fork；本 fork 仍有 123 个 patch 不在 upstream
• git diff --shortstat origin/main...upstream/main：835 files changed, 154470 insertions(+), 60248 deletions(-)
• 差异最集中的路径：
  • backend/internal/service：约 319 个差异文件片段
  • frontend/src/components：约 89 个
  • backend/internal/handler：约 78 个
  • frontend/src/views：约 48 个
  • backend/internal/repository：约 47 个
  • frontend/src/i18n：约 29 个
  • backend/internal/pkg：约 29 个
  • frontend/src/api：约 20 个
• 上游新增/变更迁移集中在 154..169，包括 account spark shadow、ops system logs api_key_id、Grok platform quota、batch image foundation 等；本 fork 已经有自己的 142..173 订阅/计费/积分迁移。

结论：这不是一次普通 rebase/merge，而是一次“按主题筛选 + 小 PR 吸收 + 真实库验证”的同步项目。

目标

1. 逐项评估 upstream/main 相对 origin/main 的变化，明确每个主题是 吸收 / 改写后吸收 / 暂缓 / 跳过。
2. 优先吸收低耦合、高价值的安全修复、协议兼容、网关 bugfix、模型映射与运维可观测性改进。
3. 对会触碰本 fork 魔改语义的代码，只在理解冲突后改写吸收，禁止机械覆盖。
4. 保持本 fork 当前线上语义：订阅计费三窗口/自定义购买/积分/公益 key/错误归因/部署元数据等不能被上游默认语义回滚。
5. 每一批变更必须能独立 review、独立测试、独立回滚。

非目标

• 不做一次性大 merge。
• 不以 upstream/main 的 VERSION、release workflow、Docker/release 元数据直接替换本 fork 的生产部署语义。
• 不重命名、不修改任何已存在迁移文件；需要变化只能追加新迁移。
• 不因为上游实现存在就默认启用新产品功能，例如 batch image、赞助商资产、README/landing 品牌内容。
• 不把本 fork 的计费、支付、积分、公益 key 业务规则迁回 upstream 默认规则。

硬性约束

迁移约束

• 已存在迁移文件视为 immutable，包括注释也不改。
• 允许数字前缀重复，但必须按完整文件名审查执行顺序和 checksum 行为。
• 上游新增迁移若要吸收，必须检查与本 fork 已有 142..173 迁移的数据模型是否冲突。
• 涉及真实余额、支付、订阅、积分、usage billing 的迁移，必须做真实 PostgreSQL/Testcontainers dry run，不能只跑单测。

魔改保护约束

同步时必须保护以下本 fork 语义：

• 订阅计费：三窗口限额、自定义购买、量大优惠、订阅/分组解耦、倍率折算、钱包兜底、透支语义修正。
• 支付与积分：KeyingPay/EasyPay 二次确认、affiliate points、提现/冻结/ledger 规则、移动端购买路径修正。
• 网关与运维：上游错误归因、client/client_via_upstream SLA 口径、公益 key IP cap/白名单/标准 429、WHAM usage endpoint。
• 部署：本 fork 的生产路径是源码构建二进制，构建元数据不能让 admin 更新面板误以为是 upstream release。
• CI：patch coverage、backend/frontend/integration/security checks 不能因为同步而弱化。

初始分层取舍

A. 优先吸收

这些通常价值高、冲突相对可控，建议先做小 PR：

• 安全/依赖修复，例如 aws sdk eventstream vuln bump。
• OpenAI/Codex/Gateway 协议 bugfix：compact body signal routing、messages/chat fallback hardening、function call item id、Responses alias normalization、websearch/history block、parse error observability。
• 上游请求/错误处理增强，但必须对照本 fork issue ops/gateway: SLA 误把非服务故障计入(口径写死、复制 5+ 处)+ 上游错误改写散落多入口、默认丢真实状态 #16 的错误归因语义。
• 模型映射和最新模型适配，但必须保持本 fork 的 pricing、platform quota、group config 规则。
• 小型前端体验修复：sidebar scroll persist、usage 文案纠偏、支付金额显示 bugfix 等。

B. 改写后再吸收

这些触碰魔改核心，必须先审语义再做：

• payment/subscription 相关修复：退款 pending、订阅撤销恢复、CNY/USD opt-in rate、subscription amount/affiliate base 等。
• OpenAI/Grok/Antigravity 账号调度、quota、OAuth、shadow account、scheduler score 相关改动。
• usage log、ops realtime stats、system logs、IP geolocation、admin usage table 相关改动。
• settings/admin/account 大文件拆分和 i18n 拆分：可以吸收结构性收益，但要避免把本 fork UI/业务字段回滚。
• Docker/deploy 默认值：只能吸收开发体验和安全默认值，不能覆盖本 fork 生产部署路径。

C. 默认暂缓

这些体量大或产品方向不确定，除非单独立项，否则先不进本轮：

• Batch Image foundation 及其 worker/repository/UI/migrations 全套。
• sponsors/logos/README 多语言大改。
• 上游 release/version 自动同步逻辑。
• 会改变本 fork landing/品牌/价格页叙事的内容改动。

D. 默认跳过

• 纯上游品牌、赞助商、文档推广内容。
• 与本 fork 已实现方案等价但会造成大面积冲突的重构。
• 会弱化当前 CI/coverage/secret scan 策略的配置变化。

执行计划

阶段 0：生成评估清单

产出一张 upstream PR/commit 级清单，至少包含：

• upstream PR/commit
• touched paths
• 主题
• 初步分层：A/B/C/D
• 是否已被本 fork cherry-pick 或等价吸收
• 与本 fork 的冲突点
• 推荐处理方式：cherry-pick / 手写移植 / 暂缓 / 跳过
• 必跑测试

阶段 1：低风险修复 PR

先做 1-3 个小 PR，只吸收 A 类：安全、网关协议 bugfix、小型 UI bugfix。

验收：

• backend build / wire / vet / unit 通过
• frontend lint / typecheck / 相关 vitest 通过
• 对 gateway/openai 的变更有 targeted tests
• 不修改历史迁移

阶段 2：账号、网关、usage/ops 分组 PR

按领域拆 PR，不跨越支付/订阅大边界：

• OpenAI/Codex/Gateway 兼容组
• Grok/Antigravity/OAuth/account scheduler 组
• usage/ops/system logs 组
• settings/admin/i18n 结构组

每组 PR 都要在描述里列出：吸收了哪些 upstream commit、刻意跳过了哪些、为什么。

阶段 3：支付/订阅/计费专项审查

这个阶段不能直接 cherry-pick。需要单独读 upstream 变更和本 fork 现有语义，写子 spec 后再动手。

重点保护：

• 三窗口订阅限额
• 自定义购买/量大优惠/倍率折算
• affiliate points 和支付入账安全
• 已上线迁移 checksum
• 真实生产形态数据下的余额/usage billing 一致性

阶段 4：决定是否立项大功能

Batch Image、Grok media、IP geolocation 等大功能单独决策：

• 如果要吸收，拆独立 issue/PR。
• 如果只需要其中的 bugfix 或模型配置，摘出最小 patch。
• 不把大功能夹带进 upstream sync PR。

验证门槛

每个 PR 至少要求：

• git diff --check
• backend 编译与 wire 生成检查
• Go unit tests 覆盖 touched packages
• 前端 lint/typecheck/相关 vitest
• 涉及 DB/Redis/计费/支付/订阅/usage billing：必须跑真实 PostgreSQL/Redis 或 testcontainers 集成测试
• 涉及迁移：必须在干净 DB 和带本 fork 历史迁移 DB 两种路径验证
• 涉及 gateway/openai/streaming：必须有协议级 targeted tests 或 smoke tests
• 涉及部署配置：必须明确不改变本 fork 生产部署元数据和 BuildType=source 预期

Done 标准

本 issue 完成必须同时满足：

• upstream 差异清单已完成，并且每一项有明确 吸收/改写吸收/暂缓/跳过 结论。
• A 类修复已合入或明确记录为什么不合入。
• B 类高风险主题至少完成代码审查和子 spec，不能停留在“以后看”。
• 所有已合入 PR 均有对应测试证据。
• 没有修改历史迁移文件。
• 本 fork 的订阅/支付/积分/公益 key/错误归因/部署语义没有被回滚。

初始建议

先不要从 upstream/main 开 merge commit。建议从 origin/main 新开同步工作分支/工作树，先做阶段 0 的评估表，再按 A 类小 PR 开始吸收。当前差异已经大到足够让“一把 merge 后修冲突”变成不可 review 的风险源。