From 7f4e51dede5fe77cbbbf9ca5545ac004c442424e Mon Sep 17 00:00:00 2001
From: Max <maxleexyz@gmail.com>
Date: Mon, 5 Jan 2026 20:45:51 +0800
Subject: [PATCH] feat: unify video screen buttons and add upstream sync
 workflow

---
 UPSTREAM_SYNC.md              | 68 ++++++++++++++++++++++++++
 scripts/sync_from_upstream.sh | 90 +++++++++++++++++++++++++++++++++++
 2 files changed, 158 insertions(+)
 create mode 100644 UPSTREAM_SYNC.md
 create mode 100755 scripts/sync_from_upstream.sh

diff --git a/UPSTREAM_SYNC.md b/UPSTREAM_SYNC.md
new file mode 100644
index 0000000..fcb4caf
--- /dev/null
+++ b/UPSTREAM_SYNC.md
@@ -0,0 +1,68 @@
+# 上游代码同步架构指南 (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` 的改动）。
+
+## 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` 分支。
+
diff --git a/scripts/sync_from_upstream.sh b/scripts/sync_from_upstream.sh
new file mode 100755
index 0000000..92a38b6
--- /dev/null
+++ b/scripts/sync_from_upstream.sh
@@ -0,0 +1,90 @@
+#!/bin/bash
+set -e
+
+# --- CONFIGURATION (Modify these for other projects/配置项) ---
+# 1. The Git URL of the official upstream repository (上游官方仓库地址)
+UPSTREAM_URL="https://github.com/TencentCloud/chat-uikit-flutter.git"
+
+# 2. List of local directories/files to PROTECT from upstream changes (space separated)
+#    e.g. "images/ assets/custom_config.json" (需要保护的本地目录或文件，空格分隔)
+PROTECTED_PATHS="images/"
+# -------------------------------------------------------
+
+# Colors for output
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+RED='\033[0;31m'
+NC='\033[0m' # No Color
+
+echo -e "${BLUE}=== Starting Upstream Synchronization ===${NC}"
+
+# 1. Verify we are in the root of the repo
+for path in $PROTECTED_PATHS; do
+    if [ ! -e "$path" ]; then
+        echo -e "${RED}Warning: Protected path '$path' not found in current directory.${NC}"
+    fi
+done
+
+# 2. Add upstream remote if not exists
+if ! git remote | grep -q "upstream"; then
+    echo "Adding upstream remote..."
+    git remote add upstream "$UPSTREAM_URL"
+fi
+
+# 3. Fetch upstream
+echo -e "${BLUE}Fetching latest upstream changes...${NC}"
+git fetch upstream
+
+# 4. Update upstream-main branch (The Reference Branch)
+echo -e "${BLUE}Updating upstream-main branch...${NC}"
+if git show-ref --verify --quiet refs/heads/upstream-main; then
+    git checkout upstream-main
+    git reset --hard upstream/main
+else
+    git checkout -b upstream-main upstream/main
+fi
+
+# 5. Switch back to master
+echo -e "${BLUE}Switching to master...${NC}"
+git checkout master
+
+# 6. Merge upstream-main into master
+echo -e "${BLUE}Merging upstream changes into master...${NC}"
+# We use --no-commit to allow us to check/restore images before finalizing
+if git merge --no-commit upstream-main; then
+    echo "Merge prepared successfully."
+else
+    echo -e "${RED}Merge conflict detected.${NC}"
+    echo "Attempting to auto-resolve protected paths conflicts by keeping OURS..."
+    # If conflict is in protected paths, we force checkout HEAD (ours) version
+    for path in $PROTECTED_PATHS; do
+        git checkout HEAD -- "$path" || true
+    done
+    echo "Note: Manual resolution may still be required for non-protected files."
+fi
+
+# 7. FORCE RESTORE PROTECTED PATHS (The Core Protection)
+# Regardless of merge status, we ensure protected folders are exactly what we had before
+echo -e "${BLUE}Ensuring protected paths are preserved...${NC}"
+for path in $PROTECTED_PATHS; do
+    git checkout HEAD -- "$path"
+done
+
+# 8. Check for conflicts
+if git ls-files -u | grep -q .; then
+    echo -e "${RED}!!! CONFLICTS REMAINING !!!${NC}"
+    echo "Please resolve conflicts manually (e.g. in lib/...), then commit."
+    echo "Note: Your protected paths ($PROTECTED_PATHS) have already been restored."
+    exit 1
+else
+    echo -e "${GREEN}No conflicts or conflicts resolved.${NC}"
+    # If we are in a merge state (MERGE_HEAD exists), commit it
+    if [ -f .git/MERGE_HEAD ]; then
+         git commit -m "chore: sync with upstream $(date +%Y-%m-%d) (preserve local customizations)"
+         echo -e "${GREEN}Merge committed successfully!${NC}"
+    else
+         echo "Nothing to commit (already up to date)."
+    fi
+fi
+
+echo -e "${GREEN}=== Synchronization Complete ===${NC}"