Rainytoken/docs/UPSTREAM-SYNC.md

上游同步指南（Rainytoken 二开合并流程）

目的：上游（CATMIAOZHI/Rainytoken）持续更新时，把二开工作区（本地分支）与上游 新基线对齐，冲突可控、可重复、可一键执行。 本仓库两条线：main = 上游基线跟踪（保持可随时 fetch/rebase）；dev = 二开改动。

---

1. 仓库当前状态

分支	内容	说明
main	上游基线（当前 eecf549，v1.6.3 后继续可追）	不加入二开改动，保持与 origin/main 一致
dev（建议名）	全部二开改动（3 家供应商 + API 管理页 + 用量页 + 充值 + Sub2API 明细升级 + 本指南）	二开唯一工作分支

因为当初二开没有分叉提交，全部二开改动都在工作区；首次授权后统一 commit 到 dev。 上游的 5 个提交（v1.6.4）尚未合入二开，按下面的流程合并后二开同时拥有两边功能。

---

2. 每轮上游更新的快捷流程（一键脚本）

在项目根目录执行（Git Bash）：

./scripts/sync-upstream.sh

脚本自动完成：fetch 上游 → 切到 dev → rebase 到 origin/main → assembleDebug 编译验证。

手动等价流程：

# 1. 拉上游（直连，绕过失效代理）
git -c http.proxy= -c https.proxy= fetch origin main

# 2. 在二开分支上 rebase 到新基线
git checkout dev
git rebase origin/main

# 3. 若冲突：手动解决相同文件后
git add <冲突文件>
git rebase --continue

# 4. 编译回归
CI=true ./gradlew.bat :app:assembleDebug

---

3. 已知冲突面（预计最多遇到的）

二开与上游都在改的文件，但改动区域通常不同，多为小冲突：

文件	上游改	二开改	冲突可能性
app/src/main/java/com/rainy/token/domain/service/ServiceType.kt	CCGO 显示名	追加 Trae/WorkBuddy/Sub2API 枚举	低（相邻区域，git 自动合）
app/src/main/res/values*/strings.xml ×3	CCGO 更名 + 时间选择器 key	sub2_* 系列 + 服务三语	低
app/src/main/java/com/rainy/token/ui/components/ServiceIcon.kt	CCGO 更名	新服务图标分支	低
app/src/main/java/com/rainy/token/di/NetworkModule.kt	CCGO 更名	3 个新 Repository @Provides	低
app/src/main/java/com/rainy/token/ui/servicedetail/ServiceDetailScreen.kt	CCGO 文案	Sub2API 明细卡分支 + 充值	低
app/src/main/java/com/rainy/token/ui/dashboard/Usage*Screen.kt	时间选择器大改	（二开基本没动）	无

尾部逗号/顺序类冲突：每次合并时统一以「二开语义」为准重新排布，不影响功能。 版本号（app/build.gradle.kts）：上游 taste.md 已声明版本号控制权归上游作者—— 二开合并上游后不要自作主张 bump 版本；由用户在发版时决策。

---

4. 变更落地检查清单（每次合并后）

1. assembleDebug 绿（脚本已做）；
2. 服务枚举/凭据指纹 when 无编译告警（新增枚举必有分支）；
3. 三语 strings 无缺 key（lint 可查）；
4. 若有 UI 改动 → taste.md 要求的独立 subagent 审计；
5. 需要推手机看效果：adb -s <serial> install -r app/build/outputs/apk/debug/app-debug.apk。

---

5. 建议节奏

• 上游「发版」（release commit）或你看到感兴趣的新功能时再合并，不必每次小提交都跟；
• 合完上游后建议打一个二开本地 tag（rain-<日期>）便于回溯；
• 禁止直接 push 到上游；二开仓库如需推送，仅推 dev 且需用户授权。