前端总体架构与运行边界

本章描述 muotai-frontend（管理平台）和 muotai-frontend-neo（用户使用平台）的共同运行模型。两个项目共享墨台后端的认证、网关、AI、文档空间和业务服务，但页面组织和状态边界不同：管理平台以菜单、角色、租户和业务管理为中心，用户平台以工作台、会话、文档空间和 AI 产物为中心。

1. 代码基线与事实等级

项目	源码根目录	应用形态	主要入口
管理平台	`/Users/xing/workspace/muotai/muotai-frontend`	Vite Web 应用；可选 Tauri 桌面端；可打包聊天库	`src/main.ts`、`src/App.vue`、`src/router/index.ts`
用户平台	`/Users/xing/workspace/muotai/muotai-frontend-neo`	Vite Web 应用；同时可构建 `muotai-components` npm 包	`src/main.ts`、`src/App.vue`、`src/router.ts`
后端	`/Users/xing/workspace/muotai/muotai-backend`	Spring Cloud 微服务	Gateway、Auth、UPMS、AI、Doc Space 等

文档事实按以下优先级解释：当前 .ts/.vue 源码高于 README，当前 package.json 和 vite.config.ts 高于历史构建脚本，当前后端 Controller/API 契约高于前端注释。若部署配置、镜像端口和源码不一致，应在端口与部署差异中登记为待确认项。

2. 产品边界

text

浏览器 / Tauri / 组件库宿主
              │
              ▼
      管理平台或用户使用平台
              │
              ├── /auth、/admin       Auth / UPMS
              ├── /ai/v1              muotai-ai
              ├── /doc/v1             muotai-doc-space / HMC
              ├── /audit、/standard   审计 / 标准化
              ├── /expert             专家与工单
              ├── /workflow            WFlow / Flowable
              ├── /billing、/pay       计费 / 支付
              └── /growth              增长与邀请

前端负责页面编排、输入校验、请求发起、流式事件展示、文件传输进度和用户可见错误。前端不负责最终租户隔离、角色授权、资源归属、订单状态和 AI 工具安全校验；这些校验必须由 Gateway/业务服务在服务端重新执行。

3. 应用启动链路

3.1 管理平台

text

index.html
  -> src/main.ts
     -> createApp(App)
     -> app.use(router)
     -> app.use(ElementPlus)
     -> initStore / Pinia
     -> 全局指令、样式、图标和插件
  -> src/App.vue
     -> RouterView
  -> src/router/index.ts
     -> staticRoutes
     -> 登录后加载 asyncRoutes
     -> Layout/页面组件

管理平台的布局、标签页、菜单、主题和用户状态在页面切换期间持续存在。静态路由用于登录、异常页、文件预览和少量固定入口；业务菜单可以来自 asyncRoutes.ts 或后端菜单，经 menuToRouter/registerRoutes 转换后注册。

3.2 用户使用平台

text

index.html
  -> src/main.ts
     -> createApp(App)
     -> router
     -> Element Plus
     -> initStore（持久化 Pinia）
     -> requestAuth、反馈诊断、全局指令
  -> src/App.vue
     -> 中文 locale
     -> RouterView
  -> src/router.ts
     -> routeLoaders 懒加载页面
     -> Layout 子路由或独立工具页

用户平台没有管理端那样的后端菜单注册过程。router.ts集中声明业务页面，routeLoaders统一提供动态导入，导航期间由 routeLoading 控制顶部进度条。Assistant 页面在进入时必须有 navigation.currentSession；旧版本 query 参数会在路由守卫中迁移到 sessionStorage 后清理 URL。

4. 路由和页面加载模型

4.1 管理平台路由

管理平台同时存在三类路由：

静态路由：登录、注册、找回密码、授权回调、异常页、房间文件页、文件预览和部分模块首页。
异步路由：房间、知识库、AI、文档、工作流、系统设置、专家和运营菜单。
模块路由：module/audit/router.ts、module/accounting/router.ts、module/specialProject/router.ts，通过 isStatic 和模块元信息加入静态或异步菜单。

路由 meta 中的 keepAlive、isHide、hidden、separatorBar、menuPath 和 module 会影响菜单、标签页和页面缓存。新增页面必须明确是否显示在菜单、是否可直接访问、是否需要登录以及是否保留组件状态。

4.2 用户平台路由

用户平台路由分为 Layout 子路由和独立页面：

类别	典型路径	说明
Layout 子路由	`/`、`/room-document`、`/assistant`、`/billing`	共享侧边栏、顶部栏、会话和传输浮层
独立编辑/工具页	`/editor`、`/tender-writer`、`/contract-reviewer`、`/rewrite`	适合全屏编辑或步骤式任务
公开入口	`/invite/:code`、`/file-room/invite/:token`、`/agreements/:type`	可能在登录前访问，必须单独处理身份和资源校验
回调入口	`/authredirect`	第三方登录或 OAuth 回跳

路由跳转的业务参数优先放入 navigation store 或 currentRoute store。不要重新把 Agent、Session、Room 等完整业务上下文拼到 URL；如需兼容旧地址，只保留一次性迁移逻辑。

5. 请求客户端和认证上下文

5.1 基础 URL 与代理

两个项目均以 VITE_API_BASE_URL 作为浏览器请求前缀，以 VITE_API_SERVER_URL 作为开发服务器代理目标。常见开发形态是：

text

浏览器请求 /api/ai/v1/...
  -> Vite proxy 去掉 /api
  -> Gateway :9999 或部署配置的网关地址
  -> /ai/v1/... 业务路由

用户平台 vite.config.ts额外配置 /api/gpt 到外部模型代理；管理平台还保留多个 dev:* 内网环境和 Tauri 合同编辑环境。生产环境应由 Nginx/CDN 或网关提供同源 /api，避免把内部服务地址暴露给浏览器。

5.2 Header 和上下文

Header/字段	来源	用途
`Authorization`	accessToken	OAuth2 Bearer 身份认证
`request-token`	sessionStorage 或登录上下文	特定前端/请求链路校验
`tenant-id`	user store 的 tenantId	租户上下文透传；服务端仍须从 Token 校验
Trace ID	服务端响应或诊断上下文	错误定位、反馈和日志关联

管理端统一请求主要在 src/api/interceptor.ts；用户端请求由 src/lib/interceptor.ts 和 src/lib/requestAuth.ts协作完成。请求拦截器注入认证信息，响应拦截器解包业务响应、显示错误并处理认证过期。

5.3 Token 刷新和认证恢复

认证恢复必须满足以下约束：

accessToken 过期时优先使用 refreshToken 请求 /auth/oauth2/token，成功后只重试原始请求一次。
refresh 请求本身失败时清空用户状态并回到登录流程，不能继续递归刷新。
多个请求同时收到 401/424 时，只允许一次登出和登录弹窗恢复；其他请求等待恢复结果。
登出需要清理 Token、用户信息、工作台签页、当前会话和必要的 sessionStorage，但租户默认值是否保留要遵循项目现有实现。
公开邀请、分享和协议页不能假设已经存在用户 Token；进入后再根据资源状态决定是否唤起登录。

6. 状态管理和持久化

6.1 管理端 Store

Store	主要职责	持久化/生命周期
`user`	登录、用户信息、租户、Token、锁屏和搜索历史	Pinia 持久化到 localStorage
`menu`	菜单列表和菜单宽度	页面/布局生命周期
`setting`、`config`	主题、布局和系统配置	持久化或配置接口
`worktab`	已打开页面和标签页	登录会话；登出时清理
`notice`	通知和未读状态	页面/接口刷新
`sse`	Agent 会话的连接、发送消息和回答状态	内存；连接关闭即清理
`aiDoc`	起草文档、生成任务和并发池	文档任务期间，部分数据持久化
`workflow`、`table`	工作流页面和表格通用状态	页面/模块生命周期

6.2 用户端 Store

Store	主要职责	持久化/生命周期
`user`	用户、租户、Token、登录恢复	Pinia persisted state/localStorage
`navigation`	当前 project/room/agent/session 和引用文件	sessionStorage；支持旧 URL 迁移
`currentRoute`	query、params、history.state 和完整路径	内存；由路由方法同步
`project`	当前项目 ID	页面/会话生命周期
`transfer`	上传/下载任务、进度、状态和失败	内存；页面刷新后不保证恢复

6.3 状态边界

组件的临时 UI 状态（弹窗、折叠、当前 tab）应留在组件或 composable；跨页面业务上下文放 Store；后端权威状态通过 API/SSE/轮询重新获取。不要把完整文件内容、Token、模型密钥或未经脱敏的 AI 轨迹写入持久化 Store。

7. 文件、编辑器和实时能力

7.1 文件传输

普通上传适合小文件，分片上传适合大文件或多文件场景。标准链路为：

text

选择文件
  -> 前端校验类型/大小
  -> init（得到 uploadId/batchId）
  -> upload（分片或单文件）
  -> complete（幂等合并）
  -> status/result 轮询
  -> 文件记录可用

用户端 src/api/upload.ts 将上传任务接入 transfer store；管理端以 src/api/upload.ts、FileUpload、UploadFile 和房间组件组合实现。取消上传必须终止 Fetch/XHR、清理定时器和更新 UI，不能只隐藏进度条。

7.2 预览和在线编辑

两个项目都包含 PDF、Office、Excel、文本、Markdown、图片和多媒体预览。用户端把这些能力聚合到 components/npm/FilePreview，管理端则分布在 components/FilePreview、views/rooms 和 views/webOffice。预览前应先确认文件类型、下载地址、权限和版本；无法预览时展示可重试或下载原文件的错误状态。

7.3 SSE 和流式响应

AI 请求通常经历“建立连接 → 发送消息 → 接收 token/结构化事件 → 终态 → 关闭连接”。前端必须区分连接状态、业务运行状态和最终消息状态：SSE 断开并不等于后端任务已经取消，业务取消应调用对应取消接口或发送取消指令。具体事件字段以AI 聊天与智能体执行和文件与流式事件为准。

8. 后端服务映射

前端领域	主要路径	后端服务	前端关注点
登录/用户/权限	`/auth`、`/admin`	`muotai-auth`、`muotai-upms`	Token、租户、菜单、角色、组织
Agent/LLM/RAG/Tool/Skill	`/ai/v1`	`muotai-ai`	Session 顺序、SSE、工具权限、引用文件
房间/文件/文档	`/doc/v1`、`/ai/v1/files`	`muotai-doc-space`、`muotai-ai`	文件 ACL、上传、预览、版本和回收
文档起草	`/doc/v1/ai-draft-record`、HMC API	`muotai-hmc`、`muotai-doc-space`、`muotai-ai`	任务状态、章节生成、编辑器内容
审计/合规/风险	`/audit`、`/expert`	`muotai-audit`、`muotai-expert`	长任务、风险状态、报告和工单
工作流	`/workflow` 或网关映射	`muotai-wflow`	Flowable 实例、任务和组织
计费/支付	`/billing`、`/pay`	`muotai-billing`、`muotai-pay`	订单终态、幂等、二维码和回调
邀请/增长	`/growth`	`muotai-growth`	邀请码、奖励、兑换和统计

后端服务端口、Gateway 路由和前端代理存在过历史差异时，优先检查当前 service-map.md、模块 application.yml 和实际部署配置。

9. 错误、日志和可观测性

前端错误处理分三层：

HTTP 层：网络不可达、超时、503、CORS、连接断开。
认证层：401/424、Token 刷新失败、租户上下文缺失。
业务层：统一响应 code/msg/data 中的失败码、资源不存在、状态冲突、限流和依赖失败。

错误提示应包含可行动信息（重试、重新登录、下载原文件、联系管理员），并在诊断/反馈中保留 Trace ID、页面路径、业务 ID 和脱敏请求信息。Token、密码、API Key、下载签名、文件内容和模型密钥不得写入控制台或反馈 payload。

10. 相关源码和文档

管理端启动：muotai-frontend/src/main.ts、src/App.vue、src/router/
用户端启动：muotai-frontend-neo/src/main.ts、src/App.vue、src/router.ts
后端架构：整体架构、请求链路与时序、安全与多租户
后端接口：接口基础约定、认证与统一响应、前端对接边界

前端总体架构与运行边界 ​

1. 代码基线与事实等级 ​

2. 产品边界 ​

3. 应用启动链路 ​

3.1 管理平台 ​

3.2 用户使用平台 ​

4. 路由和页面加载模型 ​

4.1 管理平台路由 ​

4.2 用户平台路由 ​

5. 请求客户端和认证上下文 ​

5.1 基础 URL 与代理 ​

5.2 Header 和上下文 ​

5.3 Token 刷新和认证恢复 ​

6. 状态管理和持久化 ​

6.1 管理端 Store ​

6.2 用户端 Store ​

6.3 状态边界 ​

7. 文件、编辑器和实时能力 ​

7.1 文件传输 ​

7.2 预览和在线编辑 ​

7.3 SSE 和流式响应 ​

8. 后端服务映射 ​

9. 错误、日志和可观测性 ​

10. 相关源码和文档 ​

前端总体架构与运行边界

1. 代码基线与事实等级

2. 产品边界

3. 应用启动链路

3.1 管理平台

3.2 用户使用平台

4. 路由和页面加载模型

4.1 管理平台路由

4.2 用户平台路由

5. 请求客户端和认证上下文

5.1 基础 URL 与代理

5.2 Header 和上下文

5.3 Token 刷新和认证恢复

6. 状态管理和持久化

6.1 管理端 Store

6.2 用户端 Store

6.3 状态边界

7. 文件、编辑器和实时能力

7.1 文件传输

7.2 预览和在线编辑

7.3 SSE 和流式响应

8. 后端服务映射

9. 错误、日志和可观测性

10. 相关源码和文档