本地启动

前端应用在 fago/fago-vben5/apps/web-antd。用外层仓库的脚本启动，这样会使用锁定的 Node 与 pnpm，并带上开发代理：

当前后台使用官方 vbenjs/vue-vben-admin 固定快照的完整布局。fago-vben5 是既有工程目录名；页面外壳由官方 BasicLayout 提供侧栏、顶栏、面包屑、多标签、全屏、主题与布局偏好，登录页使用官方 AuthPageLayout。现有业务页面与 Fago API 保留，脚本路径不变。

bash scripts/web.sh install --frozen-lockfile
bash scripts/web.sh dev --host 127.0.0.1 --port 5174

默认把浏览器的 /api 转到 127.0.0.1:8081。API 地址不同时设置 FAGO_API_PROXY_TARGET。后端的 APP_AUTH_ORIGINS 必须等于浏览器地址，开发示例是 http://127.0.0.1:5174。

打开 http://127.0.0.1:5174/workspace。尚未登录时会进入对应身份的登录页：

身份	登录路径
租户	/auth/login
平台	/platform/auth/login

首次登录或口令到期进入固定的改密页。改密页不加载菜单。改密成功后会话被撤销，需要重新登录。

登录后可点击右上角设置图标调整布局、亮暗主题和显示密度，点击侧栏折叠按钮收起导航；打开多个页面会显示原生标签栏。右上角账号菜单提供个人中心、修改本人密码和「退出登录」；OIDC 会话另有「统一退出」。菜单搜索只使用当前已授权页面。通知业务继续从「消息通知」进入，没有复制上游示例消息。

例如核对文件页面与标签导航，可按以下步骤操作；没有文件权限时不会出现该入口：

登录 → 基础设施 → 文件管理（/infra/files）
再打开个人中心 → 顶部出现两个页面标签 → 点击“文件管理”标签返回
右上角主题按钮 → 切换亮/暗主题，当前业务页面仍保持打开
右上角账号菜单 → 退出登录 → 确认

src/preferences.ts 维护应用显示默认值，src/layouts/basic.vue 桥接 Fago 权限与官方布局。业务 token、本人资料、菜单、标签和搜索历史仅驻留内存；主题等显示偏好可保存。切换账号或授权版本会清理旧标签与页面缓存。首次改密和 SSO 返回仍使用既有受控流程，登录表单不进入上游演示的 KeepAlive 缓存。

主内容区四周统一保留 20px。官方布局的单边值会覆盖总 contentPadding，因此应用同时配置四边；启动时只同步这组间距，已保存的主题与布局保持原选择。维护间距时修改 src/preferences.ts 的同一配置，固定页脚另在底部预留自身高度：

export const contentSpacingPreferences = {
  contentPadding: 20,
  contentPaddingBottom: 20,
  contentPaddingLeft: 20,
  contentPaddingRight: 20,
  contentPaddingTop: 20,
};

生产构建使用 bash scripts/web.sh build。生产包不包含 mock 后端。静态文件目录是 fago/fago-vben5/apps/web-antd/dist/，由 deploy/proxy/nginx.conf 这套模板反向代理。该模板尚未代替实际部署。

依赖安装、类型检查和合同检查也可以通过 scripts/web.sh 的 typecheck、contract 子命令运行。后端还没启动时，页面上的健康状态不会显示连接正常。