fix(review-feedback-965): address latest review comments

Author: ZhuLinsen

docs/DEPLOY.md

@@ -317,7 +317,7 @@ deploy:
 
 - **直接部署（pip + python）**：先构建前端，再启动服务：
   ```bash
-  # 安装 Node.js 20+（如尚未安装）
+  # 安装 Node.js 18+（推荐 20+，如尚未安装）
   # 构建前端
   cd apps/dsa-web
   npm ci

docs/deploy-webui-cloud.md

@@ -227,7 +227,7 @@ docker-compose -f ./docker/docker-compose.yml up -d
 
 重建完成后，用 `Ctrl+Shift+R` 强制刷新浏览器缓存，再访问页面。
 
-**直接部署用户**：先确保已安装 Node.js 20+，然后手动构建前端：
+**直接部署用户**：先确保已安装 Node.js 18+（推荐 20+），然后手动构建前端：
 
 ```bash
 cd apps/dsa-web

src/webui_frontend.py

@@ -122,7 +122,9 @@ 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'
+    lock_file = frontend_dir / "package-lock.json"
+    install_cmd = "npm ci" if lock_file.exists() else "npm install"
+    return f'cd "{frontend_dir}" && {install_cmd} && npm run build'
 
 
 def _has_static_assets(static_dir: Path) -> bool:
@@ -146,11 +148,13 @@ def _has_static_assets(static_dir: Path) -> bool:
 def _warn_if_assets_missing(artifact_index: Path, frontend_dir: Path) -> None:
     """当 index.html 存在但 assets/ 缺失时，发出页面显示异常警告。"""
     static_dir = artifact_index.parent
+    assets_dir = static_dir / "assets"
     if not _has_static_assets(static_dir):
         logger.warning(
-            "检测到 %s 但 static/assets/ 目录不存在或无 CSS/JS 文件，"
+            "检测到 %s 但 %s 目录不存在或无 CSS/JS 文件，"
             "WebUI 将因缺少样式与脚本而显示异常（元素过大、布局错乱）",
             artifact_index,
+            assets_dir,
         )
         logger.warning(
             "请重新构建前端以修复此问题: %s",

tests/test_webui_frontend.py

@@ -68,7 +68,7 @@ def test_prepare_webui_frontend_assets_warns_when_assets_missing(tmp_path, monke
         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 "目录不存在或无 CSS/JS 文件" in caplog.text
     assert "WebUI 将因缺少样式与脚本而显示异常" in caplog.text
 
 
@@ -87,7 +87,7 @@ def test_prepare_webui_frontend_assets_auto_build_disabled_warns_when_assets_mis
         result = webui_frontend.prepare_webui_frontend_assets()
 
     assert result is True  # index.html present, still returns True
-    assert "assets/ 目录不存在或无 CSS/JS 文件" in caplog.text
+    assert "目录不存在或无 CSS/JS 文件" in caplog.text
 
 
 def test_has_static_assets_returns_false_for_missing_dir(tmp_path):