# 上游代码同步架构指南 (Upstream Synchronization Guide)

## 1. 核心理念 (Core Philosophy)

作为基于开源项目二次开发的商业项目，我们采用 **"双流分支策略" (Dual-Stream Branching Strategy)**。这一策略旨在解决以下核心冲突：
*   **Keep Updated**: 必须紧跟官方 bug 修复和新特性。
*   **Keep Customized**: 必须严格保留私有的 UI 定制和资源修改。

## 2. 分支架构 (Branch Architecture)

我们维护两个长期的核心分支：

### A. `upstream-main` (官方纯净流)
*   **定义**: 官方代码在本地的**只读镜像**。
*   **规则**: 
    1.  **严禁**直接修改此分支代码。
    2.  仅通过 `git pull upstream main` 更新。
*   **作用**: 作为 Merge 的基准（Base），确保我们清楚知道“官方改了什么”。

### B. `master` (私有定制流)
*   **定义**: 我们的生产环境主分支。
*   **组成**: `upstream-main` + `私有补丁 (Custom Patches)`。
*   **私有补丁内容**:
    *   `images/` 下的定制资源。
    *   `UI Widgets` 的样式调整（如 `video_screen.dart` 的改动）。

### C. `LOCAL_CHANGES.md` (变更白皮书)
*   **定义**: 项目的“差异账本”。
*   **规则**: 任何不跟随官方的修改，**必须**在此文件记录。这能让我们在合并冲突时快速回忆起“这是我们故意改的”还是“意外”。

## 3. 同步工作流 (Synchronization Workflow)


每当需要同步官方更新时，执行以下标准流程（Standard Operating Procedure）：

1.  **更新基准**: 切换到 `upstream-main` 并拉取最新官方代码。
2.  **执行合并**: 切换回 `master`，合并 `upstream-main`。
3.  **资源保护**: 如果发生冲突，始终以 `master` 的 `images/` 为准（"Ours" 策略）。

## 4. 自动化脚本 (Automation)

为了降低人为失误，我们提供了自动化脚本 `scripts/sync_from_upstream.sh`。

### 脚本逻辑
1.  自动 Fetch `upstream`。
2.  重置 `upstream-main` 到最新官方 commit。
3.  尝试合并到 `master`。
4.  **关键保护**:哪怕没有冲突，脚本也会强制检查并恢复 `images/` 目录到合并前的状态，确保私有资源不被官方资源覆盖。

```bash
# 执行方式
./scripts/sync_from_upstream.sh
```

---
**Architect Note**: 保持 `upstream-main` 的纯净是此架构的基石。一旦该分支被污染，差异对比将失去意义。

## 5. 如何在其他项目复用 (How to Reuse)

如果您有其他类似项目（既要跟上游，又有本地定制），请按以下步骤复用此方案：

1.  **复制脚本**: 将 `scripts/sync_from_upstream.sh` 复制到新项目的 `scripts/` 目录。
2.  **配置参数**: 打开复制后的脚本，编辑顶部的配置项：
    ```bash
    # 配置您的上游仓库地址
    UPSTREAM_URL="https://github.com/Your/Upstream-Repo.git"
    
    # 配置您需要保护的目录（如 config, assets 等），以空格分隔
    PROTECTED_PATHS="config/ assets/ images/"
    ```
3.  **赋予权限**: 运行 `chmod +x scripts/sync_from_upstream.sh`。
4.  **初始化**: 第一次运行脚本时，它会自动为您创建 `upstream-main` 分支。