用户使用平台前端技术文档

用户平台源码位于 /Users/xing/workspace/muotai/muotai-frontend-neo。它面向普通用户、团队成员和企业成员，围绕工作台、文档空间、AI 对话、文件产物、写作工具、合同审查、市场和商业化账户组织页面。该仓库同时把聊天、上传、文件预览和 WebOffice 抽取为可注入依赖的 muotai-components 组件库。

1. 工程结构

text

src/
├── api/                  # AI、用户、房间、文档、市场、计费、增长 API
├── components/
│   ├── npm/              # 可复用组件库：chat、upload、preview、WebOffice
│   ├── marketplace/      # 市场卡片、筛选、资源详情
│   ├── sidePanel/        # 任务、文件、终端、浏览器、审查和聊天侧栏
│   ├── login/            # 登录弹窗、初始化和手机号绑定
│   └── help-feedback/    # 帮助、反馈和诊断
├── composables/          # Agent、Light App、资源和 WebOffice 组合式逻辑
├── depts/                # 组件依赖适配接口
├── lib/                  # interceptor、SSE、Markdown、存储、校验和事件总线
├── pages/                # Layout、Workbench、DocSpace、工具和账户页
├── router.ts             # 路由表和导航迁移
├── store/modules/        # user、navigation、currentRoute、project、transfer
├── types/                # API、页面、组件和业务类型
├── content/agreements/   # 服务、隐私和付费协议
└── data/constants/       # 模板、工具、市场、主题和文件常量

应用入口在 src/main.ts：安装 Router、Element Plus、Pinia persisted state，配置请求认证桥接层，注册全局指令和反馈诊断。src/App.vue只承担 Element Plus locale、用户初始化和顶层 RouterView；业务布局在 pages/layout/Layout.vue。

2. 路由和布局

2.1 Layout 子路由

路径	页面	作用
`/`	`Workbench`	工作台、最近会话、知识助手和快捷操作
`/room-document`	`docSpace`	文档空间、房间、文件和收藏
`/light-app`	`lightApp`	轻应用列表与启动
`/automations`	`Automations`	自动化任务
`/marketplace`	`Marketplace`	资源市场
`/toolbox`	`Toolbox`	工具箱
`/discovery`	`Discovery`	发现页
`/team`	`Team`	团队和成员
`/assistant`	`Assistant`	当前 Agent/session 的对话
`/billing`	`Billing`	会员、积分、存储和订单
`/system-setting`	`SystemSetting`	偏好、连接器、模型和通知

这些页面共享 Sidebar、Topbar、用户面板、房间切换、搜索、文档筛选和传输浮层。页面不应自行创建重复的全局导航、上传任务或登录弹窗。

2.2 独立页面和公开入口

编辑器、招标撰写、文案、合同审查、数据抽取、总结和改写等页面使用独立路由，适合全屏或步骤式任务。/invite/:code、/file-room/invite/:token和/agreements/:type可能在登录前打开，需要根据邀请码/分享 token/协议类型请求后端资源，再决定是否要求登录。

3. 用户身份和导航状态

3.1 登录恢复

components/login/ensureLogin.ts和 useUserInit提供页面操作前的登录保障。src/lib/requestAuth.ts由 main.ts注入 user store 的 accessToken、refreshToken、tenantId、Token 更新函数和认证失败回调，避免底层 interceptor直接依赖页面或 Store。

并发认证失败时，应用只唤起一个 LoginModal；登录成功后恢复原操作，取消或失败则将原请求置为失败并保留用户可见提示。

3.2 会话导航

navigation store 是 Assistant 页面业务上下文的唯一数据源：

interface SessionParams {
  projectId: string
  roomId: string
  agentId: string
  sessionId: string
  sessionTitle?: string
  content?: string
  folderPath?: string
  referencedFiles?: any[]
  linkIdList?: any[]
}

当前值保存到 sessionStorage。路由守卫兼容两种旧地址：

?agentId=&sessionId=&roomId=等旧 query 参数迁移到 currentSession，然后替换成干净 URL。
旧 ?id=<uuid>从历史 session 参数 Map 查找并迁移。

没有当前 session 时访问 Assistant 会回到 Workbench。新增入口应调用 setCurrentSession或 patchCurrentSession，不要把业务数据重新散落到多个 query 参数。

3.3 当前路由状态

currentRoute保存 query、params、history.state、fullPath、routeName 和 path。router.push/replace/go/back/forward被包装以同步这些信息，适合跨页面恢复弹窗、来源页面或编辑上下文。history.state 中不得存放 Token、完整文件内容和敏感业务数据。

4. 工作台、AI 助手和聊天

4.1 工作台

pages/Workbench由 WorkDashboard、KnowledgeAssistant、KnowledgeInput、历史面板、模板配置、专家卡片和会话归档等组件组成。工作台负责让用户选择 Agent、房间、项目和引用文件，再进入 Assistant；它不应在本地复制一份会话状态。

4.2 Assistant 和聊天组件

聊天组件位于 components/npm/chat：

text

Chat
├── chat.vue / chatInput.vue / messageList.vue
├── historySessions
├── smartStreamChat / markstreamVue
├── chatSection
│   ├── thinking / thinkingGroupPanel
│   ├── planning / agentStep / agentStepPanel
│   ├── intentRecognition / loadConfig / resourceAllocation
│   ├── skillCall / toolCall / taskDetail / taskEnd
│   ├── uploadFiles / referenceFiles / templateDoc
│   └── codeMsg / jsonMsg / mermaidMsg / quoteText / todoList
└── GeneratedFileCard / ChatReferenceList / DeepThinkingSimulator

一条 AI 响应可能包含纯文本、思考、规划、工具调用、RAG 引用、文件产物和终态，前端必须按结构化事件渲染，不能简单把所有 data 拼成字符串。具体运行时链路见请求链路与核心时序。

4.3 SSE 生命周期

lib/sse/sseManager.ts、runStatusSse.ts和 sseEvent.ts管理连接和事件解析。每个连接应具备：

连接认证和 session 绑定。
首包/连接超时保护。
心跳或空事件处理。
重复事件或重连后的去重策略。
用户点击停止后的 AbortController 和业务取消。
completed/error/cancelled/paused终态收口。

连接关闭只代表传输结束；后端任务仍可能运行。需要主动停止时必须调用后端取消接口，并刷新任务状态和产物列表。

5. 文档空间、房间和文件

5.1 DocSpace 页面

pages/docSpace把文档空间拆成导航栏、侧栏、房间列表、文件表格、筛选条、收藏、回收站、历史文件、权限、分享和智能文档抽屉。useFileBrowser.ts和 useRooms.ts封装文件浏览和房间加载逻辑，页面应通过 composable 统一维护分页、当前目录、面包屑和刷新。

5.2 房间协作

房间能力包括创建/编辑/归档、成员列表、成员权限、邀请、加入申请、房间项目和房间级轻应用。fileRoomSharing.ts提供邀请、申请、审批、成员权限更新和撤销接口；任何成员变更后都要刷新权限和可操作菜单。

5.3 文件传输和预览

用户端 upload.ts支持普通文件、批量文件、文件夹和分片上传，transfer store向全局 TransferBall提供进度和状态。预览组件位于 components/npm/FilePreview，支持 Office、PDF、Excel、文本、图片、媒体、压缩包、XMind 和 Markdown。文件预览依赖通过 FilePreviewDeps注入，组件本身不应假设宿主使用哪一个 API 客户端。

5.4 WebOffice

components/npm/WebOffice和 pages/webOffice负责打开在线文档、显示 AI Chat Panel、保存和切换文档。WebOfficeDeps提供凭证/打开文档能力，chatDeps和 filePreviewDeps提供 AI 侧栏和引用文件能力。文档应说明凭证过期、只读权限、保存失败、版本冲突和离开页面前保存策略。

6. 写作、审查和工具页

6.1 写作工具

路由	能力	关键状态
`/write-documents`	文档工作区	当前模板、项目、草稿和编辑状态
`/tender-writer`	招标文件撰写	项目发起、需求分析、大纲、章节和导出
`/copywriter`	文案生成	输入、生成中、结果和历史
`/summarizer`	总结	文件/文本输入、流式结果、导出
`/rewrite`	改写	原文、风格/指令、结果和替换
`/data-extractor`	数据抽取	文件、字段配置、抽取结果
`/editor`	通用编辑器	文档内容、自动保存、预览和导出

招标撰写同时存在 pages/tender-writer和历史 tender-writer copy，后续文档必须标明当前生产入口与旧实现差异，不要把复制目录误当成两个产品功能。

6.2 合同审查和合规检查

合同审查由上传、审查配置、分析进度、结果、风险报告、历史和导出步骤组成；合同检查页还提供记录列表、PDF 查看和风险卡。文档必须区分：

上传文件状态与后端分析任务状态。
风险项定位、等级、证据和整改状态。
报告生成是否异步，导出是否需要等待报告完成。
用户端页面与管理端规则/审计配置的边界。

7. 市场、轻应用、自动化和商业化

7.1 市场与轻应用

marketplace页面使用筛选组、市场侧栏、卡片网格、搜索头和资源详情弹窗展示模板、专家、轻应用和其他资源。加入、安装、预览和发布动作应通过 useResourceActions等 composable 调用 API，并根据资源类型处理权限和计费。

轻应用页面从模板、版本和资源包加载内容，lightAppLaunchDialog负责启动参数、房间上下文和运行错误。light-apps目录是独立的轻应用源码/打包工程，发布时需要单独记录版本和静态资源。

7.2 自动化

Automations.vue和 components/automation提供自动化列表、通知铃铛、内联文件夹选择和任务状态。自动化触发是异步行为，页面应展示启用/暂停、最近运行、失败原因和重试入口。

7.3 计费、积分和存储

pages/billing包含 AI 会员、积分充值、存储、支付记录、积分记录和存储记录。二维码支付组件只展示支付状态，不能在前端自行把订单标记为成功；应以 Pay/Billing 服务回调后的订单状态为准。

8. 组件库和依赖注入

用户端将 src/components打包为 muotai-components。纯展示组件可以直接使用；涉及请求、用户态、房间、上传或文件预览的组件必须由宿主通过 deps 注入：

deps	典型能力
`ChatDeps`	历史、开始/停止/恢复/取消运行、SSE 认证、产物和房间资源
`FilePreviewDeps`	下载、预览、编辑和文件类型判断
`UploadDeps`	文件/文件夹上传、进度、取消和目录浏览
`WebOfficeDeps`	Office 凭证、文档打开和保存
`LoadingDeps`	分析/任务状态查询

组件库宿主必须：

安装 Vue、Vue Router、Element Plus、Icons 和 Lucide peer dependencies。
引入 muotai-components/dist/style.css。
在使用 Header等路由组件时提供 router 上下文。
为有副作用的组件注入完整 deps，不在组件内偷偷读取宿主 API 或 Pinia。
升级包时同步检查 COMPONENTS_USAGE.md、deps 类型和异步 chunk。

9. 用户端 API 分组

分组	文件	主要路径/服务
认证与用户	`usersApi`、`messages`、`support`、`feedback`	`/auth`、`/admin`、AI support
Agent/聊天	`aiAgent`、`aiChatbot`、`aiChatbotNpm`、`skillApi`、`userMllModel`	`/ai/v1` → muotai-ai
文档空间	`docSpace`、`roomApi`、`fileRoomSharing`、`spaceProject`	`/doc/v1`、`/ai/v1/files`
上传与模板	`upload`、`doc-template`	Doc Space、AI 模板服务
审查	`contractCheck`、`documentCompliance`	Audit/AI/Expert
市场与自动化	`marketplace`、`myResource`、`lightApp`、`automation`	AI marketplace/light-app
商业化	`billing`、`growth`	Billing、Pay、Growth

API 返回值应在服务层完成类型化和解包；页面只处理业务数据、加载态和用户提示，不重复拼接 /api 或自行处理 Token。

10. 构建和发布形态

用户端 package.json的核心脚本包括：

text

npm run dev          # Web 开发
npm run build        # 应用构建
npm run build:lib    # 组件库构建
npm run pack         # 组件库打包并生成使用说明
npm run preview      # 预览产物
npm run lint         # vue-tsc 类型检查
npm run light-app:pack

vite.config.ts按 monaco-editor、mermaid、katex、xlsx、umo-editor、文件预览和 UI 依赖拆包。新增重型依赖时应评估首屏、路由切换和缓存，不要把所有依赖打入单一 vendor chunk。生产发布必须同时核对 VITE_API_BASE_URL、VITE_API_SERVER_URL、VITE_PORT、VITE_LOGIN_SOURCE、VITE_SHOW_ACCOUNT和 source map 配置。

用户使用平台前端技术文档 ​

1. 工程结构 ​

2. 路由和布局 ​

2.1 Layout 子路由 ​

2.2 独立页面和公开入口 ​

3. 用户身份和导航状态 ​

3.1 登录恢复 ​

3.2 会话导航 ​

3.3 当前路由状态 ​

4. 工作台、AI 助手和聊天 ​

4.1 工作台 ​

4.2 Assistant 和聊天组件 ​

4.3 SSE 生命周期 ​

5. 文档空间、房间和文件 ​

5.1 DocSpace 页面 ​

5.2 房间协作 ​

5.3 文件传输和预览 ​

5.4 WebOffice ​

6. 写作、审查和工具页 ​

6.1 写作工具 ​

6.2 合同审查和合规检查 ​

7. 市场、轻应用、自动化和商业化 ​

7.1 市场与轻应用 ​

7.2 自动化 ​

7.3 计费、积分和存储 ​

8. 组件库和依赖注入 ​

9. 用户端 API 分组 ​

10. 构建和发布形态 ​

用户使用平台前端技术文档

1. 工程结构

2. 路由和布局

2.1 Layout 子路由

2.2 独立页面和公开入口

3. 用户身份和导航状态

3.1 登录恢复

3.2 会话导航

3.3 当前路由状态

4. 工作台、AI 助手和聊天

4.1 工作台

4.2 Assistant 和聊天组件

4.3 SSE 生命周期

5. 文档空间、房间和文件

5.1 DocSpace 页面

5.2 房间协作

5.3 文件传输和预览

5.4 WebOffice

6. 写作、审查和工具页

6.1 写作工具

6.2 合同审查和合规检查

7. 市场、轻应用、自动化和商业化

7.1 市场与轻应用

7.2 自动化

7.3 计费、积分和存储

8. 组件库和依赖注入

9. 用户端 API 分组

10. 构建和发布形态