前端接口、事件与前后端业务链路

本章把两个前端项目中的 API 服务、后端微服务、异步任务和实时事件放到同一套契约下说明。具体业务接口仍以 muotai-backend 当前 Controller/DTO/VO 为准；本章记录前端如何组织、调用和展示这些接口。

1. 统一请求约定

1.1 请求地址

前端源码中的 API 通常省略 /api，例如 '/ai/v1/chatbot'。开发时由 Vite 将浏览器的 /api 前缀代理到 Gateway，生产时由 Nginx/CDN/Gateway 提供同源路径。

源码路径：/ai/v1/...
浏览器路径：/api/ai/v1/...
Gateway 路径：/ai/v1/...
业务服务：muotai-ai

不要把 http://localhost:6062、内网 IP 或服务容器名写进页面组件。服务地址只能出现在环境变量、Vite proxy、部署配置或专用 API 客户端中。

1.2 方法、参数和分页

操作	默认方法	参数位置
查询单条/列表	GET	path/query
创建/启动任务	POST	body/form-data
更新配置/状态	PUT	body/path
删除/撤销	DELETE	path/body
导出/下载	GET/POST	path/query 或文件流

分页请求需要统一传递 current、size 或后端约定的页码字段，页面不得把不同服务的分页字段混在同一 API 类型中。分页响应至少要能表达记录、当前页、页大小和总数；长任务列表还要表达任务状态和更新时间。

1.3 统一响应和错误

管理端 Axios 拦截器和用户端 lib/interceptor.ts会处理统一响应。业务失败不能仅依赖 HTTP 状态判断，必须同时检查响应中的 code/msg/data。前端错误处理建议按以下分类：

分类	典型错误	前端动作
参数错误	字段缺失、格式不符	定位表单字段并保留输入
身份过期	401、424	刷新 Token；失败则登录恢复
无权限	403 或业务授权码	关闭危险操作并提示联系管理员
资源不存在	文件、房间、Agent 已删除	刷新列表或返回上级
状态冲突	重复提交、版本冲突、订单已终态	展示当前状态并阻止重复操作
依赖失败	AI、解析、向量库、支付服务异常	保留任务 ID，提供重试/查询
网络问题	超时、503、断网、SSE 断开	显示网络状态，允许重试或恢复

2. 认证、租户和用户接口

2.1 登录和 Token

主要入口：

POST /auth/oauth2/token
DELETE /auth/token/logout
GET/POST /login/captcha 或项目配置的验证码接口
POST /admin/login/social
POST /admin/login/phone
GET /admin/front/user/info
GET /admin/front/menu

登录响应中的 accessToken、refreshToken、过期信息和用户/租户信息由 user store 保存。刷新请求使用 refresh_token grant，不能复用会触发刷新逻辑的普通 Axios 实例，否则会形成递归重试。

2.2 UPMS 管理接口

管理平台 systemApi.ts、tenant.ts和 menuApi.ts对应：

• 用户分页、用户详情、创建、更新、删除。
• 部门树、岗位、角色和角色成员。
• 菜单树、角色菜单授权、数据权限。
• 租户分页、详情、菜单树和租户校验。
• 前端主题和系统配置。

页面显示的菜单和按钮只是授权结果的投影；角色/租户变化后应清理旧菜单并重新注册路由。

3. AI Agent、聊天和事件流

3.1 Agent 管理

管理端 aiAgentApi.ts和用户端 aiAgent.ts负责 Agent 列表、详情、创建、更新、发布、模板和绑定关系。Agent 相关绑定通常包括模型、数据集、Skill、Tool、MCP、Channel、DocSpace 文件和 SubAgent。API 文档应为每一个绑定说明：

• 资源 ID 的租户归属和可见范围。
• 未发布/已发布版本的可修改字段。
• 删除或解绑是否影响已运行 Session。
• 列表接口是否返回分页、版本和发布状态。

3.2 聊天请求

聊天请求至少关联 agentId、sessionId和用户输入，可能附带 projectId、roomId、引用文件、链接、模型参数和工具选项。一个推荐的前端调用时序是：

WorkBench/AI Studio 选择上下文
  -> 创建或恢复 session
  -> 建立 SSE（带 agentId/sessionId）
  -> POST 发送消息和附件引用
  -> 接收 token、节点、工具、RAG、产物和终态事件
  -> 保存消息/刷新历史和产物
  -> 关闭连接或保留会话连接

后端同一 session 必须顺序执行；前端不能在同一 session 未结束时无控制地并发发送下一轮。跨 session 才能安全并行。

3.3 结构化事件

前端事件模型至少覆盖：

事件类别	页面表现	失败/终态
token/text	增量文本	文本完成或错误
thinking/planning	思考、规划、步骤折叠面板	暂停、失败、完成
tool/skill/MCP	工具调用、参数、结果和耗时	工具失败、权限拒绝
RAG/reference	引用文档、定位和来源	引用不可用
artifact/file	生成文件、下载或预览入口	产物生成失败
task/status	排队、运行、暂停、恢复、取消	终态时间和错误原因
error/done	用户提示和连接收口	error、completed、cancelled

事件渲染应具备版本兼容：未知事件保留可诊断信息并跳过渲染，不得因一个新事件让整个消息列表崩溃。

3.4 取消、重连和恢复

• 停止生成：先调用前端 abort，再调用后端取消/停止接口，最后刷新运行状态。
• 网络断开：保留 sessionId 和最后事件 ID；能否重连要以服务端重放能力为准。
• 页面离开：区分“离开页面但任务继续”和“用户明确取消”，不能把路由销毁自动当成业务取消。
• 重复事件：以 event id、sequence 或业务键去重；文本不能重复拼接。
• 服务端终态：收到 completed/error/cancelled 后停止轮询和心跳，清理 abort handle。

4. 文档空间、上传和预览接口

4.1 房间和文件

管理端 roomApi.ts/docSpace.ts和用户端 roomApi.ts/docSpace.ts覆盖：

房间：列表、创建、编辑、删除、归档、恢复、置顶、成员和权限
目录：创建、重命名、移动、删除、下载
文件：上传、详情、预览、下载、重命名、版本和 AI 分析
分享：分享房间/文件、密码校验、邀请、加入申请和成员审核
回收站：分页、恢复、批量删除、清空

文件、目录和房间均需在服务端进行租户、所有者或成员权限校验。前端传递的 roomId、parentId、fileId和 versionId不能视为授权证明。

4.2 分片上传

用户端的上传 API 采用批次和 uploadId 管理分片，典型接口语义如下：

POST .../init       初始化文件/批次
POST .../upload     上传一个分片或文件
POST .../complete   合并并提交
GET  .../status/:id 查询上传状态
GET  .../result/:id 获取处理结果

完成接口必须幂等；前端重试不能产生重复文件。上传完成后还可能进入解析、OCR、分段、向量化或 AI 分析，页面要继续展示处理状态。

4.3 文件预览和 WebOffice

预览 API 返回文件流、临时 URL、文件元数据或版本信息。前端必须处理 URL 过期、Content-Type 不匹配、下载权限失效和文件损坏。WebOffice 的凭证获取、打开和保存由专用 deps/API 适配，凭证不能长期持久化到 localStorage。

5. 文档起草、模板和知识库

5.1 文档起草

AI 起草前端会组合元数据、模板、文档 ID、章节任务和编辑器内容。后端 HMC/AI 服务可能异步创建任务，前端需要保存 taskId，并用流式回调或状态接口跟踪：pending → running → success/error。页面刷新后能否恢复取决于是否可按 documentId/taskId 查询，不能只依赖内存 Store。

5.2 模板

模板接口包括列表、详情、文件 URL、分类、缩略图上传、导入、发布和版本。模板文件可能通过 Doc Space 或 /admin/sys-file存储，前端展示的缩略图地址不等于原文件下载地址。

5.3 知识库和 RAG

知识库链路包含 Dataset、Document、Chunk、向量化和 Graph Schema。前端应把“文档已上传”“解析完成”“分段完成”“向量化完成”“可被 RAG 使用”作为不同状态。RAG 引用渲染需要保留文档 ID、片段 ID、页码/定位和来源链接。

6. 审计、工作流、专家和商业化接口

6.1 审计与合规

审计页面对应的接口通常有项目、业务域、资料、标准、控点、检测任务、风险、整改、报告和同步任务。长任务接口必须返回业务任务 ID，前端通过轮询/SSE 获取进度，不能在请求超时后直接认为失败。

6.2 工作流

工作流接口按表单、模型、实例、任务、组织、通知、请求和启动分组。前端设计器保存的是模型定义，运行页面处理的是实例/任务数据，两者不能混用。审批操作必须提交操作人上下文、意见、表单数据和版本/任务 ID，服务端验证任务当前可操作状态。

6.3 专家工单

工单接口覆盖创建、分页、详情、派单、转派、接单、拒单、风险项维护、处理进度、结论和完成。结算接口覆盖申请、审批、支付和导出。前端按钮应根据状态和角色显示，重复点击由后端幂等和前端 loading 双重保护。

6.4 Billing、Pay、Growth

支付二维码只是支付发起凭证；订单成功必须以 Pay 回调和 Billing 状态为准。积分、会员、存储和邀请奖励都可能异步到账，前端需要显示“处理中/已完成/失败”而不是只依赖一次提交响应。

7. API 到微服务索引

API 前缀	服务	代表功能
/auth	muotai-auth	OAuth2 token、刷新和登出
/admin	muotai-upms及公共文件服务	用户、角色、菜单、租户、文件上传
/ai/v1	muotai-ai	Agent、聊天、RAG、Skill、Tool、MCP、市场、文件房间
/doc/v1	muotai-doc-space	房间、文件、版本、解析、文档起草
/audit	muotai-audit	审计项目、任务、风险和报告
/expert	muotai-expert	专家、工单和结算
/workflow	muotai-wflow	Flowable 模型、实例和任务
/billing	muotai-billing	套餐、权益、用量、账户
/pay	muotai-pay	支付渠道、订单和退款
/growth	muotai-growth	邀请、活动和奖励

Gateway 的实际路由可能去掉服务前缀或重写路径，联调时以 Gateway 路由和服务注册状态为准。

8. 前端新增接口检查表

新增接口
├── 确认后端 Controller、HTTP 方法和完整路径
├── 确认服务、租户/角色/资源权限和数据范围
├── 定义请求 DTO、响应 DTO、分页和错误码类型
├── 在 API 层统一处理 baseURL、Header、解包和取消
├── 页面实现 loading、empty、error、retry 和重复提交保护
├── 异步接口保存业务 ID 并定义轮询/流式终态
├── 文件接口处理 Content-Type、文件名、临时 URL 和过期
├── 增加最小联调用例和失败用例
└── 更新接口路径索引、页面文档和后端关联链接