From d5cf9c14a9496b4361866365724c7b62e969ee21 Mon Sep 17 00:00:00 2001
From: Justin Gu <97915@qq.com>
Date: Sun, 6 Sep 2026 14:34:59 +0800
Subject: [PATCH] =?UTF-8?q?feat(web):=20=E5=93=81=E7=89=8C=E5=8C=BA?=
 =?UTF-8?q?=E6=98=BE=E7=A4=BA=E5=BA=94=E7=94=A8=E7=89=88=E6=9C=AC=E5=8F=B7?=
 =?UTF-8?q?=20=E2=80=94=20=E6=96=B0=E5=A2=9E=20GET=20/api/v1/meta=EF=BC=8C?=
 =?UTF-8?q?=E5=89=8D=E7=AB=AF=E5=90=AF=E5=8A=A8=E6=8B=89=E5=8F=96=E5=B1=95?=
 =?UTF-8?q?=E7=A4=BA?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/easy_tdx/web/routers/server.py | 21 +++++++++++++++++++++
 tests/unit/test_web_api.py         | 22 ++++++++++++++++++++++
 web-ui/src/App.vue                 | 22 +++++++++++++++++++---
 web-ui/src/api.ts                  | 12 ++++++++++++
 web-ui/src/types.ts                |  6 ++++++
 5 files changed, 80 insertions(+), 3 deletions(-)

diff --git a/src/easy_tdx/web/routers/server.py b/src/easy_tdx/web/routers/server.py
index aadda1f..e58d834 100644
--- a/src/easy_tdx/web/routers/server.py
+++ b/src/easy_tdx/web/routers/server.py
@@ -61,11 +61,32 @@ class SwitchResponse(BaseModel):
     message: str
 
 
+class MetaResponse(BaseModel):
+    """GET /meta 的响应。"""
+
+    version: str
+
+
 # --------------------------------------------------------------------------- #
 # Routes
 # --------------------------------------------------------------------------- #
 
 
+@router.get("/meta", response_model=MetaResponse)
+async def get_meta() -> MetaResponse:
+    """应用元信息：版本号（WebUI 左上角展示）。
+
+    源码运行未装包元数据（importlib.metadata 不可用）时留空，前端不显示。
+    """
+    try:
+        from importlib.metadata import version
+
+        v: str = version("easy-tdx")
+    except Exception:  # noqa: BLE001 — 元数据缺失属正常场景，留空即可
+        v = ""
+    return MetaResponse(version=v)
+
+
 @router.get("/server/hosts", response_model=HostListResponse)
 async def list_hosts(request: Request) -> HostListResponse:
     """列出所有候选 host + 当前正在使用的 host。
diff --git a/tests/unit/test_web_api.py b/tests/unit/test_web_api.py
index 4a58d5b..7516fe0 100644
--- a/tests/unit/test_web_api.py
+++ b/tests/unit/test_web_api.py
@@ -197,6 +197,28 @@ def test_realtime_router_endpoints():
     assert any("realtime" in p for p in paths)
 
 
+# ---------------------------------------------------------------------------
+# Meta endpoint（WebUI 品牌区版本号展示）
+# ---------------------------------------------------------------------------
+
+
+def test_meta_endpoint_returns_version():
+    """GET /api/v1/meta 应返回 version 字段（已安装时为语义化版本）。"""
+    pytest.importorskip("fastapi")
+    from fastapi.testclient import TestClient
+
+    from easy_tdx.web import create_app
+
+    client = TestClient(create_app())
+    resp = client.get("/api/v1/meta")
+    assert resp.status_code == 200
+    body = resp.json()
+    assert set(body.keys()) == {"version"}
+    assert isinstance(body["version"], str)
+    # 本测试环境下包已安装（pip install -e .），应能取到版本号
+    assert body["version"] != ""
+
+
 # ---------------------------------------------------------------------------
 # Task 10: CLI serve command
 # ---------------------------------------------------------------------------
diff --git a/web-ui/src/App.vue b/web-ui/src/App.vue
index 5a87b62..6fbd360 100644
--- a/web-ui/src/App.vue
+++ b/web-ui/src/App.vue
@@ -1,12 +1,19 @@
 <script setup lang="ts">
 // 根组件：侧边栏终端外壳 + 路由出口。
 // 布局借鉴专业看盘终端（侧边栏分组导航 + 底部实时连接状态徽标）。
-import { onMounted } from 'vue'
+import { onMounted, ref } from 'vue'
 
+import { fetchMeta } from './api'
 import { useQuoteStore } from './stores/quotes'
 
 const quoteStore = useQuoteStore()
-onMounted(() => quoteStore.connect())
+
+// 应用版本号（GET /meta），品牌区展示；取不到（旧后端/源码未装包）则不显示
+const appVersion = ref('')
+onMounted(async () => {
+  quoteStore.connect()
+  appVersion.value = (await fetchMeta()).version
+})
 
 const sseLabel: Record<string, string> = {
   connecting: '连接中',
@@ -21,7 +28,10 @@ const sseLabel: Record<string, string> = {
       <aside class="sidebar">
         <div class="brand">
           <span class="brand-name">easy-tdx</span>
-          <span class="brand-sub">行情终端</span>
+          <span class="brand-sub">
+            行情终端
+            <span v-if="appVersion" class="brand-ver">v{{ appVersion }}</span>
+          </span>
         </div>
         <nav class="side-nav">
           <div class="nav-group">行情</div>
@@ -109,6 +119,12 @@ const sseLabel: Record<string, string> = {
   font-size: 11px;
   color: var(--text-dim);
 }
+.brand-ver {
+  margin-left: 4px;
+  font-size: 10px;
+  opacity: 0.75;
+  font-variant-numeric: tabular-nums;
+}
 .side-nav {
   flex: 1;
   overflow-y: auto;
diff --git a/web-ui/src/api.ts b/web-ui/src/api.ts
index 25063a4..b87903e 100644
--- a/web-ui/src/api.ts
+++ b/web-ui/src/api.ts
@@ -3,6 +3,7 @@
 
 import type {
   ApiError,
+  AppMeta,
   BacktestRequest,
   BacktestResult,
   Bar,
@@ -455,6 +456,17 @@ export async function switchServerHost(host: string): Promise<ServerSwitchResult
   return (await resp.json()) as ServerSwitchResult
 }
 
+/** 应用元信息（版本号，品牌区展示）。失败返回空串，由调用方决定是否显示。 */
+export async function fetchMeta(): Promise<AppMeta> {
+  try {
+    const resp = await fetch(`${BASE}/meta`)
+    if (!resp.ok) return { version: '' }
+    return (await resp.json()) as AppMeta
+  } catch {
+    return { version: '' }
+  }
+}
+
 // ── 行情终端 ────────────────────────────────────────────────────────────────
 
 /** 批量拉实时五档（REST 一次性；持续刷新走 SSE，见 stores/quotes.ts）。
diff --git a/web-ui/src/types.ts b/web-ui/src/types.ts
index 7455f0f..6daede0 100644
--- a/web-ui/src/types.ts
+++ b/web-ui/src/types.ts
@@ -455,6 +455,12 @@ export interface ServerSwitchResult {
   message: string
 }
 
+/** GET /meta 的响应：应用元信息（版本号，WebUI 品牌区展示）。 */
+export interface AppMeta {
+  /** 语义化版本（如 "1.32.5"）；源码运行元数据缺失时为空串 */
+  version: string
+}
+
 // ── 行情终端：实时五档（SSE / POST /api/v1/security/quotes） ─────────────────
 
 /** 单只标的实时五档行情（后端 SecurityQuote 白名单投影，SSE 与 REST 同构）。 */