上游代码同步架构指南 (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）：

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

4. 自动化脚本 (Automation)

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

脚本逻辑

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

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

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

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

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

复制脚本: 将 scripts/sync_from_upstream.sh 复制到新项目的 scripts/ 目录。

配置参数: 打开复制后的脚本，编辑顶部的配置项：

# 配置您的上游仓库地址
UPSTREAM_URL="https://github.com/Your/Upstream-Repo.git"

# 配置您需要保护的目录（如 config, assets 等），以空格分隔
PROTECTED_PATHS="config/ assets/ images/"

赋予权限: 运行 chmod +x scripts/sync_from_upstream.sh。
初始化: 第一次运行脚本时，它会自动为您创建 upstream-main 分支。

3.1 KiB Raw Blame History Unescape Escape