Appearance
前端开发、测试、构建与发布
本章给出两个前端项目的日常开发和发布约束。它不替代具体页面专题，而是定义新增页面、API、组件和异步任务时必须执行的工程流程。
1. 本地开发环境
1.1 启动顺序
前端联调前应先确认 MySQL、Redis、Nacos、对象存储/向量库、Auth、UPMS、Doc Space、AI 和 Gateway 已按后端文档启动。最小可用验证顺序是：
text
后端依赖
-> Auth/UPMS
-> Doc Space/AI
-> 其他业务服务
-> Gateway
-> 前端 dev server
-> 登录
-> 房间文件列表
-> 最小 Agent 聊天Gateway 尚未加载路由时，浏览器的 404/503 不能直接判定为页面错误；应同时检查 Vite proxy、Gateway 路由、Nacos 注册和服务端口。
1.2 管理端脚本
muotai-frontend/package.json当前主要脚本：
| 命令 | 用途 |
|---|---|
npm run dev | 默认 Vite 开发 |
npm run dev:muotai | 墨台环境，端口 3010 |
npm run dev:ljf 等 dev:* | 指定内网 Gateway 环境 |
npm run build / fast-build | 生产 Web 构建 |
npm run test-build | 构建回归 |
npm run tauri:dev / tauri:build | Tauri 桌面端 |
npm run pack:chat | 聊天库构建与 npm pack |
npm run lint | ESLint |
npm run lint:prettier | Prettier |
npm run lint:stylelint | Stylelint |
管理端构建设置了较大的 Node heap，因为编辑器、BPMN、PDF、图表和 AI 页面依赖较重；CI 需要显式传递相同的 NODE_OPTIONS。
1.3 用户端脚本
muotai-frontend-neo的脚本区分应用和组件库：
| 命令 | 用途 |
|---|---|
npm run dev | 应用开发 |
npm run build | 用户端 Web 应用 |
npm run build:lib | muotai-components库构建 |
npm run pack | 库构建、类型/使用说明生成和 tarball 打包 |
npm run lint | vue-tsc --noEmit |
npm run light-app:pack | 轻应用源码包 |
npm run preview | 预览构建产物 |
用户端使用 pnpm workspace 相关文件和本地 Umo Editor tarball；CI 必须使用锁文件安装，不能自动替换本地 tarball 版本。
2. 环境变量与代理
2.1 管理端
重点变量包括 VITE_API_BASE_URL、VITE_API_SERVER_URL、VITE_HMR、Tauri 构建使用的 API 地址以及各开发环境脚本注入的 Gateway 地址。生产环境应通过部署系统注入，不要把内网 IP 或密钥提交到 .env.production。
2.2 用户端
重点变量包括：
| 变量 | 作用 |
|---|---|
VITE_API_BASE_URL | 浏览器请求前缀，通常为 /api |
VITE_API_SERVER_URL | Vite proxy 的后端目标 |
VITE_PORT | 开发服务器端口 |
VITE_LOGIN_SOURCE | 登录来源标识，例如 neo |
VITE_SHOW_ACCOUNT | 是否显示账户相关 UI |
VITE_APP_ID | 应用/登录配置标识 |
VITE_PWD_ENC_KEY | 前端密码流程使用的配置项，禁止误当作服务端密钥 |
VITE_SOURCE_MAP | 是否生成 source map |
vite.config.ts还配置 /api/gpt外部模型代理和基于依赖类型的 manualChunks。新增代理必须明确目标、重写规则、WebSocket/CORS 和生产对应关系。
3. 新增页面流程
text
确认产品/角色/权限
-> 确认后端 API 和数据模型
-> 注册路由（懒加载、meta、公开/登录要求）
-> 建立页面 Store/composable 边界
-> 编写 API 类型和服务层
-> 实现 loading/empty/error/retry
-> 接入文件/流式/编辑器等异步能力
-> 增加联调和冒烟用例
-> 更新 frontend 文档和路由/API 索引页面组件不应直接写完整请求 URL、读取 Token 或修改其他页面的局部状态。跨页面共享状态应进入既有 Store；只有单页面流程状态才保留在组件。
4. 新增 API 和组件流程
4.1 API
新增接口必须明确：HTTP 方法、路径、请求参数位置、响应 DTO、分页结构、错误码、Token/tenant 头、取消方式、幂等键和后端 Controller/Service。异步接口还必须记录业务 ID、状态机、轮询间隔、终态和页面刷新后的恢复能力。
4.2 组件
组件分为纯展示组件和有副作用组件。用户端 npm 组件涉及聊天、上传、预览、WebOffice、任务状态时，必须通过 src/depts/*.ts定义的 deps 注入，不能直接依赖宿主 API 或 Pinia。管理端领域组件可使用项目 Store/API，但应保持页面与通用组件的边界。
5. 测试矩阵
5.1 功能回归
| 场景 | 最小用例 |
|---|---|
| 登录 | 密码/验证码、刷新 Token、登出、并发 401、租户切换 |
| 权限 | 无菜单、无按钮权限、越权资源 ID、公开邀请入口 |
| 房间/文件 | 创建房间、成员权限、上传、分片失败、预览、下载、恢复回收站 |
| AI | 新会话、历史会话、普通文本、RAG 引用、工具调用、暂停/恢复/取消 |
| 起草 | 模板、元数据、大纲、章节并发、保存、刷新恢复、导出 |
| 审查 | 上传、进度、风险定位、整改、报告和导出 |
| 工作流 | 模型、表单、发布、发起、待办、审批、抄送和通知 |
| 商业化 | 会员、积分、存储、支付处理中/成功/失败、邀请奖励 |
| 组件库 | 宿主注入 deps、CSS、router 上下文、文件预览和流式消息 |
5.2 网络和兼容性
至少测试 Chrome/Edge 当前版本、窄屏和常见桌面分辨率；对大文件、长文本、超长 AI 流、弱网、断网恢复、慢接口、临时 URL 过期和浏览器刷新进行专项验证。PDF、Office、Monaco、Mermaid、XMind 和 Excel 属于重型/异步资源，需要验证懒加载失败时的错误页面。
5.3 性能指标
AI 页面关注首 token、消息渲染耗时、SSE 连接数、结构化块数量和长会话内存；文件页面关注首屏、上传吞吐、分片失败率、预览耗时和大文件内存；管理端还要关注菜单路由注册、BPMN/表单设计器和图表渲染。
6. 构建产物与发布
6.1 Web 发布
发布服务器需要：
- 将
/api代理到正式 Gateway，并保持 WebSocket/SSE 的长连接和超时配置。 - 配置 history fallback，使深链接路由返回
index.html。 - 静态资源使用 hash 文件名和长期缓存，HTML 短缓存或发布后刷新。
- 发布前检查环境变量、Source Map 策略、CSP/CORS、下载响应头和大文件超时。
- 保留构建版本、Git SHA、前端环境和后端 Gateway 版本用于回滚。
6.2 组件库发布
用户端 build:lib以 src/components/npm/index.ts为入口，外部化 Vue、Vue Router、Pinia、Element Plus、Icons 和 Lucide。pack会生成 CSS、类型、组件索引和使用说明。发布前需验证：
- tarball 能在干净宿主项目安装。
- peer dependencies 版本满足要求。
dist/style.css能正确加载。- Chat/Upload/FilePreview/WebOffice 的 deps 类型和运行时行为一致。
- 未使用的重型组件可被异步 chunk/tree-shaking 处理。
6.3 Tauri 和轻应用
管理端 Tauri 发布需要核对 Rust 构建、文件/对话框权限、应用 API 地址和签名；用户端轻应用发布需要核对源码包、静态资源、版本号和运行时 API 地址。桌面端/轻应用不能直接复用 Web 环境中的相对路径假设。
7. 故障排查
| 现象 | 首先检查 |
|---|---|
| 深链接空白/404 | history fallback、路由路径、懒加载 chunk 和缓存 |
| 所有请求 401/424 | Authorization、refreshToken、tenant-id、Auth 服务和时间偏差 |
| 请求 404/503 | Vite proxy、Gateway route、Nacos 注册、服务端口 |
| SSE 无首包 | URL/headers、CORS、Gateway 超时、session/agent 参数和服务端连接数 |
| 消息重复 | 事件 ID 去重、重连逻辑、Store 是否重复添加连接 |
| 上传卡住 | uploadId/batchId、分片序号、complete 幂等、轮询定时器和对象存储 |
| 文件无法预览 | Content-Type、临时 URL、文件版本、渲染器 chunk 和权限 |
| 组件库宿主报错 | peer dependencies、CSS、router 上下文和 deps 是否完整 |
| 构建内存不足 | NODE_OPTIONS、manualChunks、编辑器/PDF/Office 重型依赖 |
| 页面状态丢失 | Store 持久化 key、sessionStorage、路由 state 和刷新恢复接口 |
8. 发布检查清单
text
发布前
├── lockfile 安装和 Node/pnpm 版本一致
├── lint、类型检查和 build 通过
├── API_BASE_URL、Gateway、Auth、租户和 CORS 已核验
├── 登录、房间、文件上传/预览、最小 AI 聊天冒烟通过
├── SSE/上传/异步任务的取消和失败场景通过
├── 深链接、刷新、回退和静态资源缓存通过
├── source map、日志和 Trace 采集策略已确认
├── 组件库 tarball 在干净宿主项目验证
├── Tauri/轻应用产物（如发布）单独验收
└── 记录前端版本、后端版本、配置版本和回滚包