# 观澜 · 前端（`app_frontEnd/`）

**职责**：v2 工作台单页与交互、图表库、经典页模板、门户与静态页装配、设计系统与界面文案（双语文案语言包 + 显示层术语）

**允许依赖**：app_common

**对外公开面**：`common/app_frontEnd_guanlan/api.py` —— 模块间调用**只许**走这里（`scripts/module_boundary_audit.py` 机器检查）。

**目录（P5 起，2026-09-28）**：

```
common/app_frontEnd_guanlan/
  api.py                 公开面（10 个公开名，其中 9 个在本模块内）
  assets/                app.js · app.css · charts.js · favicon.svg · classic_chart.js（经典页图表脚本）
  pages/                 shell.html（v2 外壳）· build.py（出页）· snapshot.py（单文件烘焙）
                         classic.py + classic_{fleet,problem,turbine}.html（从 serve.py 抽出的经典页模板）
  design.py              设计系统 CSS 单一来源（serve/静态页/台页共用）
  lang.py                双语文案语言包（一条文案一个 key）
  terms.py               显示层术语映射（内部说法 → 现场说法）
  builders/              portal_build.py（门户装配）· portal_fix_anchors.py（锚点修复）· portal_inject_claims.py（结论段注入）
```

**迁移状态**：**P5 已完成（2026-09-28）** —— 13 件实体迁入本模块；旧路径全部留兼容壳：
`src/windscada/ui/{build,snapshot}.py`、`src/windscada/{design,lang,terms}.py`（模块别名壳，`python -m` 也照旧）、
`scripts/{portal_build,guanlan_portal_fix_anchors,guanlan_portal_inject_claims}.py`（CLI 壳）。

**本轮实逮**：① 资源件（js/css/svg/html）**无壳可留**，按路径读它们的审计器必须同步改（`detail_deps`、`pages_audit`、
`guanlan_baseline_manifest`、`audit_chinese_terms`、`check_portability` 的 ALLOW 键、`configs/registry.yaml` 的 consumers）；
② 迁入 `builders/` 后 `__file__` 上跳层数变了 ⇒ 取根统一走公共层 `install_root()`；③ 服务类脚本的模板常量可以抽成
**真资源件 + 只读装载器**，但装载必须 `newline=''`（否则 CRLF 翻译会改掉模板字节）。

**验收**：`build.render` 四种组合与 `design` 两段 CSS 逐字节等于迁移前；`serve.py` 四个模板常量（CHART_JS/PAGE_*）
与三张经典页渲染逐字节一致；`scripts/portal_build.py --verify` 装配结果与 20.19 MB 门户逐字节一致；
服务重启后门户 / `/detail/v2` / `/ops` / `/cms/` 页面体 sha256 与迁移前一致；全门禁 rc=0。

**归口说明（2026-09-28 用户裁）**：语言包与显示层术语归**前端**（只有出页器与后端 `cli.py` 的"语言包闸"用它们）；
英文投影层 `ui_en / i18n_en / data_tpl_en / en_text` 仍在既有路径（后端 `serve.py` 的数据层英文投影在用），归口待裁。

> 依据：`docs/重构方案_模块化_v0.1.md`（用户令 2026-09-22：只重构目录与接口、零行为变化、逐版本可回滚）。

## 安装部署与运行

本系统是**单包离线交付**：解压到无空格无中文路径 → 安装 → 自检 → 启动（一套安装，七个模块共用一份 `.venv`）。
本模块目录里的脚本只是**入口包装**，内部调安装根的统一入口，保证"进模块目录也能装/跑/卸"：

| 动作 | Windows | Linux/macOS | 内部实际调用 |
|---|---|---|---|
| 安装 | `install.bat` | `sh install.sh` | 安装根 `install.bat` / `install.sh`（建 `.venv`、装依赖、自检、注册服务） |
| 运行 | `run.bat` | `sh run.sh` | 安装根 `start.bat`（Windows）／`python guanlan.py serve`（跨平台） |
| 卸载 | `uninstall.bat` | `sh uninstall.sh` | 安装根 `uninstall.bat` / `uninstall.sh` |

目录约定（P9，2026-09-28 用户令）：

```
app_frontEnd/
  common/               模块内通用插件/组件（旧导入前缀的兼容别名在此保留一个版本）
  configs/              本模块专属配置域（共用单件在安装根 configs/）
  data/                 模块相关数据件（运行期数据在安装根 data/、outputs/）
  app_frontEnd_guanlan/                观澜在本模块的实现包（模块间调用只许经其中的 api.py）
  README.MD             本文件（职责 / 公开面 / 安装部署与运行）
  install.bat|sh  uninstall.bat|sh  run.bat|sh
```

自检与打包：安装根 `check.bat`（=`python guanlan.py check`）、`pack.bat` / `sh pack.sh`
（打包 + 开箱验证：页面 5/5 + 卸载核验）。

## Web 前端（Vue 3 + Vite + TypeScript + Node，P11 起）

```bash
cd app_frontEnd/web
npm install            # 依赖源 https://registry.npmmirror.com（本机可达）
npm run build          # 产物 → release/web/（由静态组件伺服、经网关 /web 前缀暴露）
npm run dev            # 开发期：/api → 127.0.0.1:18033，/algorithm → 127.0.0.1:18050（见 vite.config.ts）
node tools/contract_smoke.mjs    # 用与浏览器同一条数据通道复核冻契约（42 条端点）
```

* 取数只走 `src/api/contract.ts`（相对路径，不带 host），路径与形状以
  `app_backEnd/app_backEnd_guanlan/contract/http_api_v1.json` 冻契约为准；
* 迁移纪律：v2 工作台逐页签迁移，**与重构前页面指纹对拍通过后**才删除对应的 Python 前端源码。