fix(issue-944): [feature]-部署完以后-webui-ui异常变大-布局异常

Author: ZhuLinsen

docs/CHANGELOG.md

@@ -13,6 +13,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 <!-- 每条独立一行追加到本段末尾，无需分类标题，合并时冲突最小 -->
 - [修复] **MiniMax-M2.7 模型连接测试支持** — 修复 LLM 通道连接测试在 MiniMax-M2.7 模型下返回 "Empty response" 的问题；增加了 `max_tokens` 上限（8→256）以容纳 MiniMax 思考过程，并添加 `content_blocks` 格式解析逻辑统一处理 MiniMax 响应格式差异。
 - [修复] 移除 `HistoryItem` 与 `ReportSummary` 响应 Schema 中 `sentiment_score` 的 `ge=0/le=100` 约束（fixes #942）——历史库中存储的超范围负值或大于 100 的情绪评分不再触发 Pydantic ValidationError，历史列表与详情接口恢复正常返回。
+- [修复] webui_frontend.py 在 static/index.html 存在但 static/assets/ 缺失时发出明确警告，避免用户因 CSS/JS 资源缺失导致页面元素异常变大却无从排查
+- [文档] DEPLOY.md 和 deploy-webui-cloud.md 新增"UI 元素异常变大/布局错乱"排查步骤（重建 Docker 镜像或手动执行 npm run build）
 
 - [新功能] 集成 Longbridge OpenAPI 作为美股/港股可选数据源；配置 `LONGBRIDGE_*` 后优先使用长桥获取日线与实时行情，YFinance / AkShare 兜底；未配置时行为与此前一致。长桥联调请使用 `tests/longbridge_live_smoke.py`（手动脚本，不参与 pytest 收集）。
 - [文档] 澄清 README（中/英/繁）中长桥「首选 / 兜底 / 未配置不调用」的边界；`docs/README_EN.md` / `docs/README_CHT.md` 顶部导航与完整指南链接改为 `./` 相对路径，避免在文档子目录下解析错误；`LONGBRIDGE_PRINT_QUOTE_PACKAGES` 与代码及 `.env.example` 对齐为未设置时默认关闭。

docs/DEPLOY.md

@@ -299,6 +299,36 @@ deploy:
       memory: 1G
 ```
 
+### 5. WebUI 打开后 UI 元素异常变大 / 布局错乱
+
+**症状**：能访问 8000 端口，但页面上的文字、按钮、卡片异常放大，没有正常布局。
+
+**根因**：`static/index.html` 存在，但 CSS/JS 资源文件缺失（`static/assets/` 为空或不存在），浏览器无法加载样式与脚本，导致裸 HTML 渲染。
+
+**解决方法**：
+
+- **Docker 部署**：执行以下命令重新构建镜像（确保前端已正确打包进镜像）：
+  ```bash
+  docker-compose -f ./docker/docker-compose.yml down
+  docker-compose -f ./docker/docker-compose.yml build --no-cache
+  docker-compose -f ./docker/docker-compose.yml up -d
+  ```
+  构建完成后刷新浏览器缓存（`Ctrl+Shift+R`）再访问。
+
+- **直接部署（pip + python）**：先构建前端，再启动服务：
+  ```bash
+  # 安装 Node.js 20+（如尚未安装）
+  # 构建前端
+  cd apps/dsa-web
+  npm ci
+  npm run build
+  cd ../..
+  # 启动服务
+  python main.py --webui-only
+  ```
+
+**验证**：用浏览器开发者工具（F12 → Network）检查是否有 `/assets/index-*.js` 和 `/assets/index-*.css` 的 404 错误；如有，说明资源缺失，按上述步骤重新构建即可。
+
 ---
 
 ## 🔄 快速迁移

docs/deploy-webui-cloud.md

@@ -209,6 +209,34 @@ sudo firewall-cmd --reload
 - 直接部署：默认 8000，可通过 `WEBUI_PORT=xxxx` 修改
 - Docker：默认 8000，可通过 `API_PORT=xxxx` 修改
 
+### 5. 页面能打开，但 UI 元素异常变大 / 布局错乱
+
+**症状**：浏览器能访问到 8000 端口，页面有内容，但文字、按钮、卡片尺寸异常大，没有正常布局与配色。
+
+**根因**：`static/index.html` 存在但 CSS/JS 资源缺失（`static/assets/` 为空或不存在），浏览器加载了 HTML 框架但无法拿到样式与脚本，退化为裸 HTML 渲染。
+
+可先用浏览器开发者工具（F12 → Network 标签页）检查是否有 `/assets/index-*.js`、`/assets/index-*.css` 的 **404** 错误。若有，按以下方式修复：
+
+**Docker 用户**：
+
+```bash
+docker-compose -f ./docker/docker-compose.yml down
+docker-compose -f ./docker/docker-compose.yml build --no-cache
+docker-compose -f ./docker/docker-compose.yml up -d
+```
+
+重建完成后，用 `Ctrl+Shift+R` 强制刷新浏览器缓存，再访问页面。
+
+**直接部署用户**：先确保已安装 Node.js 20+，然后手动构建前端：
+
+```bash
+cd apps/dsa-web
+npm ci
+npm run build
+cd ../..
+python main.py --webui-only
+```
+
 ---
 
 ## 可选：Nginx 反向代理（绑定域名 / 80 端口）

src/webui_frontend.py

@@ -124,6 +124,43 @@ def _run_frontend_commands(commands: Sequence[Sequence[str]], frontend_dir: Path
 def _manual_build_command(frontend_dir: Path) -> str:
     return f'cd "{frontend_dir}" && npm install && npm run build'
 
+
+def _has_static_assets(static_dir: Path) -> bool:
+    """检查 static/assets/ 是否存在且包含 CSS/JS 文件。
+
+    index.html 存在但 assets/ 为空或缺失时，浏览器无法加载样式与脚本，
+    会导致页面元素异常放大、布局错乱（纯裸 HTML 渲染）。
+    """
+    assets_dir = static_dir / "assets"
+    if not assets_dir.is_dir():
+        return False
+    try:
+        return any(
+            f.suffix in (".js", ".css") and f.is_file()
+            for f in assets_dir.iterdir()
+        )
+    except OSError:
+        return False
+
+
+def _warn_if_assets_missing(artifact_index: Path, frontend_dir: Path) -> None:
+    """当 index.html 存在但 assets/ 缺失时，发出页面显示异常警告。"""
+    static_dir = artifact_index.parent
+    if not _has_static_assets(static_dir):
+        logger.warning(
+            "检测到 %s 但 static/assets/ 目录不存在或无 CSS/JS 文件，"
+            "WebUI 将因缺少样式与脚本而显示异常（元素过大、布局错乱）",
+            artifact_index,
+        )
+        logger.warning(
+            "请重新构建前端以修复此问题: %s",
+            _manual_build_command(frontend_dir),
+        )
+        logger.warning(
+            "Docker 用户请执行: docker-compose -f ./docker/docker-compose.yml build --no-cache"
+        )
+
+
 def prepare_webui_frontend_assets() -> bool:
     """
     Prepare frontend assets for WebUI startup.
@@ -143,6 +180,7 @@ def prepare_webui_frontend_assets() -> bool:
     if not auto_build_enabled:
         if artifact_index.exists():
             logger.info("WEBUI_AUTO_BUILD=false，检测到前端静态产物: %s", artifact_index)
+            _warn_if_assets_missing(artifact_index, frontend_dir)
             return True
         logger.warning("未检测到 WebUI 前端静态产物: %s", artifact_index)
         logger.warning("当前配置 WEBUI_AUTO_BUILD=false，不会在后端启动时自动编译前端")
@@ -155,6 +193,7 @@ def prepare_webui_frontend_assets() -> bool:
 
     if not needs_build:
         logger.info("检测到可直接复用的前端静态产物，跳过运行时自动构建: %s", artifact_index)
+        _warn_if_assets_missing(artifact_index, frontend_dir)
         return True
 
     package_json = frontend_dir / "package.json"

tests/test_webui_frontend.py

@@ -12,11 +12,20 @@ def _prepare_fake_repo(tmp_path, monkeypatch):
     return repo_root
 
 
+def _create_full_static(repo_root):
+    """Create static/index.html + static/assets/*.js/.css (complete build)."""
+    static_dir = repo_root / "static"
+    assets_dir = static_dir / "assets"
+    assets_dir.mkdir(parents=True)
+    (static_dir / "index.html").write_text("<!doctype html>", encoding="utf-8")
+    (assets_dir / "index-abc123.js").write_text("/* js */", encoding="utf-8")
+    (assets_dir / "index-abc123.css").write_text("/* css */", encoding="utf-8")
+    return static_dir
+
+
 def test_prepare_webui_frontend_assets_reuses_prebuilt_static_without_source(tmp_path, monkeypatch, caplog):
     repo_root = _prepare_fake_repo(tmp_path, monkeypatch)
-    static_index = repo_root / "static" / "index.html"
-    static_index.parent.mkdir(parents=True)
-    static_index.write_text("<!doctype html>", encoding="utf-8")
+    _create_full_static(repo_root)
 
     monkeypatch.delenv("WEBUI_AUTO_BUILD", raising=False)
     monkeypatch.delenv("WEBUI_FORCE_BUILD", raising=False)
@@ -28,6 +37,7 @@ def test_prepare_webui_frontend_assets_reuses_prebuilt_static_without_source(tmp
     assert "检测到可直接复用的前端静态产物" in caplog.text
     assert "未找到前端项目，无法自动构建" not in caplog.text
     assert "未检测到 npm，无法自动构建前端" not in caplog.text
+    assert "assets/ 目录不存在或无 CSS/JS 文件" not in caplog.text
 
 
 def test_prepare_webui_frontend_assets_fails_without_static_or_source(tmp_path, monkeypatch, caplog):
@@ -40,3 +50,64 @@ def test_prepare_webui_frontend_assets_fails_without_static_or_source(tmp_path,
         assert webui_frontend.prepare_webui_frontend_assets() is False
 
     assert "未找到前端项目，无法自动构建" in caplog.text
+
+
+def test_prepare_webui_frontend_assets_warns_when_assets_missing(tmp_path, monkeypatch, caplog):
+    """index.html 存在但 static/assets/ 缺失时应发出 WebUI 显示异常警告（Issue #944）。"""
+    repo_root = _prepare_fake_repo(tmp_path, monkeypatch)
+    static_index = repo_root / "static" / "index.html"
+    static_index.parent.mkdir(parents=True)
+    static_index.write_text("<!doctype html>", encoding="utf-8")
+    # No assets directory created — simulates incomplete/broken build
+
+    monkeypatch.delenv("WEBUI_AUTO_BUILD", raising=False)
+    monkeypatch.delenv("WEBUI_FORCE_BUILD", raising=False)
+    monkeypatch.setattr(webui_frontend.shutil, "which", lambda _: None)
+
+    with caplog.at_level(logging.WARNING):
+        result = webui_frontend.prepare_webui_frontend_assets()
+
+    assert result is True  # function still returns True (index.html present)
+    assert "assets/ 目录不存在或无 CSS/JS 文件" in caplog.text
+    assert "WebUI 将因缺少样式与脚本而显示异常" in caplog.text
+
+
+def test_prepare_webui_frontend_assets_auto_build_disabled_warns_when_assets_missing(tmp_path, monkeypatch, caplog):
+    """WEBUI_AUTO_BUILD=false 且 assets 缺失时也应发出警告。"""
+    repo_root = _prepare_fake_repo(tmp_path, monkeypatch)
+    static_index = repo_root / "static" / "index.html"
+    static_index.parent.mkdir(parents=True)
+    static_index.write_text("<!doctype html>", encoding="utf-8")
+    # No assets directory — simulates state where only index.html exists
+
+    monkeypatch.setenv("WEBUI_AUTO_BUILD", "false")
+    monkeypatch.delenv("WEBUI_FORCE_BUILD", raising=False)
+
+    with caplog.at_level(logging.WARNING):
+        result = webui_frontend.prepare_webui_frontend_assets()
+
+    assert result is True  # index.html present, still returns True
+    assert "assets/ 目录不存在或无 CSS/JS 文件" in caplog.text
+
+
+def test_has_static_assets_returns_false_for_missing_dir(tmp_path):
+    assert webui_frontend._has_static_assets(tmp_path / "nonexistent") is False
+
+
+def test_has_static_assets_returns_false_for_empty_assets(tmp_path):
+    (tmp_path / "assets").mkdir()
+    assert webui_frontend._has_static_assets(tmp_path) is False
+
+
+def test_has_static_assets_returns_true_when_js_present(tmp_path):
+    assets = tmp_path / "assets"
+    assets.mkdir()
+    (assets / "main.js").write_text("", encoding="utf-8")
+    assert webui_frontend._has_static_assets(tmp_path) is True
+
+
+def test_has_static_assets_returns_true_when_css_present(tmp_path):
+    assets = tmp_path / "assets"
+    assets.mkdir()
+    (assets / "style.css").write_text("", encoding="utf-8")
+    assert webui_frontend._has_static_assets(tmp_path) is True