fix: pass explicit local build version

Dockerfile.app.local

@@ -1,11 +1,14 @@
 # syntax=docker/dockerfile:1
 # Aether 运行镜像：Rust gateway 直接服务 API + 前端静态文件（国内镜像源版本）
-# 构建命令: docker build -f Dockerfile.app.local -t aether-app:latest .
+# 构建命令: docker build --build-arg AETHER_BUILD_VERSION=v0.7.2 -f Dockerfile.app.local -t aether-app:latest .
 
 ARG RUST_VERSION=1.95.0
 
 # ==================== 前端构建 ====================
 FROM node:22-slim AS frontend-builder
+ARG AETHER_BUILD_VERSION
+ENV AETHER_BUILD_VERSION=${AETHER_BUILD_VERSION} \
+    AETHER_VERSION=${AETHER_BUILD_VERSION}
 WORKDIR /app/frontend
 COPY frontend/package*.json ./
 RUN --mount=type=cache,id=aether-npm-cache,target=/root/.npm,sharing=locked \
@@ -44,6 +47,9 @@ COPY crates/ ./crates/
 RUN cargo chef prepare --recipe-path recipe.json
 
 FROM gateway-base AS gateway-builder
+ARG AETHER_BUILD_VERSION
+ENV AETHER_BUILD_VERSION=${AETHER_BUILD_VERSION} \
+    AETHER_VERSION=${AETHER_BUILD_VERSION}
 COPY --from=gateway-planner /build/recipe.json ./recipe.json
 RUN --mount=type=cache,id=aether-cargo-registry,target=/usr/local/cargo/registry,sharing=locked \
     --mount=type=cache,id=aether-cargo-git,target=/usr/local/cargo/git,sharing=locked \

apps/aether-gateway/build.rs

@@ -2,14 +2,20 @@ use std::env;
 use std::process::Command;
 
 fn main() {
+    println!("cargo:rerun-if-env-changed=AETHER_BUILD_VERSION");
     println!("cargo:rerun-if-env-changed=AETHER_VERSION");
     println!("cargo:rerun-if-env-changed=GITHUB_REF_NAME");
     println!("cargo:rerun-if-changed=../../.git/HEAD");
 
     let package_version = env::var("CARGO_PKG_VERSION").unwrap_or_else(|_| "unknown".to_string());
-    let version = env::var("AETHER_VERSION")
+    let version = env::var("AETHER_BUILD_VERSION")
         .ok()
         .filter(|value| !value.trim().is_empty())
+        .or_else(|| {
+            env::var("AETHER_VERSION")
+                .ok()
+                .filter(|value| !value.trim().is_empty())
+        })
         .or_else(|| {
             env::var("GITHUB_REF_NAME")
                 .ok()

apps/aether-gateway/src/tests/architecture/admin_system.rs

@@ -1,5 +1,31 @@
 use super::*;
 
+#[test]
+fn admin_system_build_version_contract_uses_explicit_local_build_arg() {
+    let build_rs = read_workspace_file("apps/aether-gateway/build.rs");
+    for pattern in [
+        "cargo:rerun-if-env-changed=AETHER_BUILD_VERSION",
+        "env::var(\"AETHER_BUILD_VERSION\")",
+    ] {
+        assert!(
+            build_rs.contains(pattern),
+            "apps/aether-gateway/build.rs should consume explicit build version pattern {pattern}"
+        );
+    }
+
+    let dockerfile = read_workspace_file("Dockerfile.app.local");
+    for pattern in [
+        "ARG AETHER_BUILD_VERSION",
+        "ENV AETHER_BUILD_VERSION=${AETHER_BUILD_VERSION}",
+        "AETHER_VERSION=${AETHER_BUILD_VERSION}",
+    ] {
+        assert!(
+            dockerfile.contains(pattern),
+            "Dockerfile.app.local should pass explicit build version pattern {pattern}"
+        );
+    }
+}
+
 #[test]
 fn admin_system_and_endpoint_roots_stay_thin() {
     let system_mod = read_workspace_file("apps/aether-gateway/src/handlers/admin/system/mod.rs");