Add commit hash selection to build-and-deploy pipeline

jenkins/Jenkinsfile.build-and-deploy

@@ -10,6 +10,7 @@ pipeline {
     string(name: 'AGENT_LABEL', defaultValue: 'built-in', description: '构建节点标签')
     string(name: 'GENARRATIVE_WORKSPACE_ROOT', defaultValue: '', description: '源码根目录，留空则使用当前 Jenkins 工作区')
     string(name: 'BUILD_VERSION', defaultValue: '', description: '发布版本号，留空则使用 Jenkins BUILD_NUMBER')
+    string(name: 'COMMIT_HASH', defaultValue: '', description: '可选，指定要构建的 Git commit hash；留空则使用 SCM 当前检出的提交')
     string(name: 'DATABASE', defaultValue: 'genarrative-pipeline-local-test', description: '发布包默认 SpacetimeDB database')
     string(name: 'API_PORT', defaultValue: '8082', description: '发布包内 api-server 端口')
     string(name: 'WEB_PORT', defaultValue: '25001', description: '发布包内静态网站端口，默认 25001')
@@ -37,6 +38,11 @@ pipeline {
           env.EFFECTIVE_BUILD_VERSION = params.BUILD_VERSION?.trim() ? params.BUILD_VERSION.trim() : env.BUILD_NUMBER
           // 允许 Jenkins Job 直接指定固定源码目录，未指定时回退到当前工作区。
           env.WORKSPACE_ROOT = params.GENARRATIVE_WORKSPACE_ROOT?.trim() ? params.GENARRATIVE_WORKSPACE_ROOT.trim() : pwd()
+          def commitHash = params.COMMIT_HASH?.trim()
+          if (commitHash && !(commitHash ==~ /^[0-9a-fA-F]{7,40}$/)) {
+            error('COMMIT_HASH 只能填写 7 到 40 位十六进制 Git commit hash，当前值: ' + commitHash)
+          }
+          env.REQUESTED_COMMIT_HASH = commitHash ?: ''
           def database = params.DATABASE?.trim()
           if (!database) {
             error('DATABASE 不能为空。')
@@ -102,14 +108,34 @@ pipeline {
           sh '''
             bash -lc '
               set -euo pipefail
+              if [[ -n "${REQUESTED_COMMIT_HASH}" ]]; then
+                # Jenkins 先按 SCM 配置完成 checkout；如指定 commit，再拉取远端引用并切到该提交构建。
+                git fetch --tags --prune origin "+refs/heads/*:refs/remotes/origin/*" || git fetch --all --tags --prune
+                if [[ "$(git rev-parse --is-shallow-repository 2>/dev/null || echo false)" == "true" ]]; then
+                  git fetch --unshallow --tags || true
+                fi
+                git cat-file -e "${REQUESTED_COMMIT_HASH}^{commit}"
+                resolved_commit="$(git rev-parse "${REQUESTED_COMMIT_HASH}^{commit}")"
+                git checkout --detach "${resolved_commit}"
+                echo "[build-and-deploy] 使用指定 commit 构建: ${resolved_commit}"
+              else
+                resolved_commit="$(git rev-parse HEAD)"
+                echo "[build-and-deploy] 使用 SCM checkout commit 构建: ${resolved_commit}"
+              fi
               # 构建前清理工作区内的 Git 变更和未跟踪文件，避免复用固定源码目录时受到上次构建残留影响。
               # 这里不使用 -x，避免删除 node_modules 等忽略目录后与 RUN_NPM_CI=false 的配置冲突。
               git reset --hard HEAD
               git clean -fd
+              echo "${resolved_commit}" > "build-and-deploy-commit.txt"
               rm -rf "build/${EFFECTIVE_BUILD_VERSION}"
             '
           '''
 
+          script {
+            env.EFFECTIVE_COMMIT_HASH = readFile('build-and-deploy-commit.txt').trim()
+            echo "构建 commit: ${env.EFFECTIVE_COMMIT_HASH}"
+          }
+
           script {
             // 是否重装依赖交给流水线参数决定，避免每次构建都重复执行 npm ci。
             if (params.RUN_NPM_CI) {