# Sync Upstream - 从上游仓库拉取合并

从 Calcium-Ion/new-api 上游仓库拉取最新代码并安全合并到当前分支。

## 执行步骤

### 1. 环境准备
- 检查当前工作区是否有未提交的更改，如有则先提示用户处理
- 检查是否已配置 `upstream` remote，如果没有则添加：
  ```
  git remote add upstream https://github.com/Calcium-Ion/new-api.git
  ```

### 2. 拉取上游代码
```
git fetch upstream
```

### 3. 分析差异
- 运行 `git log HEAD..upstream/main --oneline` 查看上游有哪些新提交
- 运行 `git diff HEAD...upstream/main --stat` 查看哪些文件被改动
- 将差异分析结果展示给用户

### 4. 冲突风险评估
重点关注以下我们自定义修改过的文件，标记为**高风险**：
- `CLAUDE.md` — 我们的项目规范，**必须保留我们的版本**
- `.claude/` — 我们的 Claude Code 配置和 skills，**必须保留**
- `common/sms.go`, `common/sms_unisms.go` — 短信功能（我们新增）
- `middleware/sms-verification-rate-limit.go` — 短信限流（我们新增）
- `common/constants.go` — 我们新增了 SMS 相关常量
- `model/user.go` — 我们新增了 Phone 字段和相关方法
- `model/option.go` — 我们新增了 SMS 相关配置
- `controller/misc.go` — 我们新增了 SMS 验证接口
- `controller/user.go` — 我们修改了注册逻辑
- `router/api-router.go` — 我们新增了 SMS 路由
- `i18n/` — 我们新增了 SMS 相关翻译
- `web/src/components/auth/RegisterForm.jsx` — 手机号注册 UI
- `web/src/components/settings/SystemSetting.jsx` — SMS 配置 UI
- `web/src/components/table/users/UsersColumnDefs.jsx` — 用户列表手机号列
- `web/src/i18n/locales/` — 前端翻译

将风险评估结果展示给用户，让用户确认是否继续。

### 5. 执行合并
- 使用 `git merge upstream/main` 进行合并
- **绝不**使用 `--force` 或 `--strategy-option theirs`

### 6. 处理冲突
如果出现合并冲突：
- 逐个冲突文件分析
- 对于我们**新增**的文件（如 `common/sms.go`）：保留我们的版本
- 对于 `CLAUDE.md` 和 `.claude/`：**始终保留我们的版本**
- 对于**双方都修改**的文件（如 `model/user.go`）：智能合并，保留双方的改动
  - 读取冲突内容，理解上游改了什么、我们改了什么
  - 将两者的改动合并到一起
  - 确保我们的自定义功能（如 Phone 字段、SMS 验证）不丢失
- 解决完所有冲突后，展示修改摘要给用户确认

### 7. 验证
- 运行 `go build ./common/... ./model/... ./controller/... ./middleware/... ./router/...` 确认 Go 编译通过
- 检查是否有遗漏的冲突标记 (`<<<<<<<`, `=======`, `>>>>>>>`)

### 8. 完成
- 提示用户合并结果
- 如果用户要求，创建合并提交

## 重要原则

1. **安全第一**：任何不确定的决策都要询问用户
2. **保护自定义代码**：我们的新增功能和修改绝不能在合并中丢失
3. **不自动推送**：合并完成后不会自动 push，需要用户确认后手动推送
4. **可逆操作**：如果合并出问题，提示用户可以用 `git merge --abort` 回退