# 前端-01：工程结构与核心依赖

- 版本：v6
- 更新日期：2026-05-24
- 目标读者：前端 / 架构 / 产品 / 后端
- 阅读时间：25-40 分钟
- 边界说明：本文件只定义阶段 7 的前端工程基线、管理后台与用户端拆分、路由组织、状态分层和接口边界。写作台交互看 `前端-02`，元引擎看 `前端-03`，精确 API 看 `后端-05`。

## 1. 前端工程基线

Muse 前端拆为两个项目，不能再用一套 Next.js 应用同时承载管理后台和用户端。

| 目标仓库 | 来源 / 形态 | 定位 | 技术栈 | 接口前缀 |
|---|---|---|---|---|
| `muse-admin/` | fork `yudao-ui-admin-vben`，主应用路径 `apps/web-antd` | 管理后台(Admin Console) | Vue 3 + Vite + Ant Design Vue + TypeScript | `/admin-api/**` |
| `muse-studio/` | 自研用户端 | 用户端创作产品(User Workspace / Agent Workspace / Knowledge Workspace / Marketplace / Personal Center) | React + Vite + TypeScript | `/app-api/**` |

核心原则：

1. 管理后台只服务管理员治理、配置、审核、观察和运营。
2. 用户端只服务普通用户创作、购买、安装、绑定、发布和个人中心。
3. 两个前端可以共享设计 token、类型生成和接口文档，但不能共享路由、权限模型或后台 layout。
4. 前端只做可见性、交互、状态恢复和用户反馈；权限、事实写入、幂等、审计和状态机必须由后端保证。

阶段 1~6 的硬约束在前端落点：

- 六个产品空间必须保持清楚：管理员控制台、用户工作区、智能体工作台、知识库工作台、市场、个人中心。
- 用户知识库是用户端一级空间，不能被写成作品工作台里的附属抽屉。
- 市场资产包括作品、智能体、知识库；购买、安装或绑定只改变授权和可用性，不自动写入作品事实。
- 作品资产当前 feature gate 默认关闭：用户端只展示阅读、收藏、授权记录或后续能力禁用态，不提供模板化新建、参考来源写入或进入 AI 上下文。
- 输入输出合规、拆分切块、RAG 入库、语义安全围栏、静态检查、权限、审计、Shadow -> Canonical 等保护节点不可被用户替换。
- 前端必须展示或传递来源 lineage、授权快照和来源状态，但不能在本地伪造这些可信结果。
- 前端隐藏菜单、按钮或字段不是安全边界。

## 2. 管理后台：Vben Admin

管理后台使用：

```text
muse-admin/  # fork yudao-ui-admin-vben
  apps/web-antd/
```

当前保留模块：

| 模块 | 当前定位 |
|---|---|
| `system` | 用户、角色、菜单、权限等平台后台 |
| `infra` | 配置、文件、字典、任务、日志等基础后台 |
| `dashboard` | 后台首页 |
| `ai` | 代码保留，默认隐藏 |
| `member` | 代码保留，默认隐藏 |
| `pay` | 代码保留，默认隐藏 |
| `bpm` | 代码保留，默认隐藏 |
| `report` | 代码保留，默认隐藏 |
| `mp` | 代码保留，默认隐藏 |

已裁剪后台旧业务域：

- `mall`
- `crm`
- `erp`
- `iot`
- `mes`
- 对应页面、API、静态路由、store、工作台快捷入口

注意：`mp` 保留，不删。

### 2.1 后续管理后台能力

| 后台能力 | 页面方向 | 后端 owner |
|---|---|---|
| 内容管理 | 作品治理列表、章节异常摘要、版本治理摘要、导入导出记录、脱敏元信息、异常内容处理 | content |
| 知识管理 | 全局知识库治理、用户知识库治理摘要、知识来源状态、知识草稿治理摘要、检索配置 | knowledge / infra |
| AI 管理 | 模型网关绑定引用、可用模型摘要、任务调用归属摘要、Prompt、Agent、生成任务、候选、评测、质量门控、工具授权摘要 | ai |
| 市场管理 | 资产审核、发布申请、授权记录、申诉、治理结果、上下架 | market / bpm |
| 账户管理 | 用户资料、权益、配额、用量、购买/授权/发布记录 | account/member/pay |
| 运营配置 | 字典、配置、文件、任务、日志、菜单权限 | system / infra |

管理后台不得承载普通用户写作台、候选接受、作品知识取舍或市场购买后的使用流程。

内容管理和知识管理默认只展示治理摘要、异常摘要、脱敏元信息、任务状态、配置和审计记录；不得暗示管理员默认可查看用户私有正文全文、私有版本全文或用户知识库全文。确需查看私有内容时，必须由后续合规访问接口承接，并包含访问理由、时效、分权审批、最小范围和审计记录。

AI 管理只消费 New-API 在 Muse 侧允许展示的网关绑定引用、可用模型摘要和任务调用归属摘要。Provider 配置、路由策略、成本权威口径和原始调用日志仍归 New-API，Muse 管理后台不能把这些写成自身 owner。

### 2.2 管理后台路由、状态和权限

Vben Admin 的页面入口由后台菜单和权限点驱动。Muse 后续新增管理页面可以挂在 Vben 管理后台的菜单体系下，但只调用 `/admin-api/**`。

| 边界 | 管理后台要求 |
|---|---|
| 路由 | 使用 Vben 路由、菜单、面包屑和权限守卫；不复用 `muse-studio` 的 React Router 路由 |
| 状态 | 使用 Vben 既有 API 请求、表格、表单、弹窗和菜单状态；不保存用户端作品编辑器状态 |
| 权限 | 使用 `system` 菜单、按钮、角色、数据范围和高危动作复核；后端仍必须校验业务 owner |
| API | 只访问 `/admin-api/**`；不从后台页面调用用户端 `/app-api/**` 完成用户创作决策 |
| 数据 | 默认展示治理摘要、异常摘要、脱敏元信息、配置、任务和审计；不默认读取用户私有正文全文、私有版本全文或用户知识库全文 |

## 3. 用户端：muse-studio

`muse-studio/` 是普通用户使用的创作产品，不走 Vben。

技术栈：

- React + Vite + TypeScript（SPA，不使用 Next.js；后续文档已全部按纯 React 栈编写）
- Tiptap / ProseMirror：正文编辑、Block 级操作和候选合并
- TanStack Query：服务器状态、轮询、失效刷新
- Zustand 或等价轻量 store：工作台 UI 状态
- React Hook Form + Zod：用户端表单和即时校验

用户端承载：

| 产品空间 | 默认入口 | 主要能力 |
|---|---|---|
| 用户工作区 | 我的作品 | 作品列表、单作品工作台、写作、规划、知识、一致性、导入、导出、记录与用量 |
| 智能体工作台 | 智能体列表 | 用户智能体、已安装智能体、作品槽位替换、试用、发布准备 |
| 知识库工作台 | 我的知识库 | 资料管理、处理任务状态、知识库版本、发布准备、已安装知识库、作品绑定、安装管理 |
| 市场 | 市场首页 | 作品、智能体、知识库资产发现、购买、安装、绑定、发布 |
| 个人中心 | 个人资料或用量页 | 资料、偏好、权益、配额、用量、购买/授权/发布记录 |

用户端不得暴露系统 Prompt、底层 Pipeline、管理员审计日志、原始密钥、完整模型请求响应或后台配置表。

用户知识库工作台的前端依赖必须闭合到 `/app-api/**` 的资料、处理任务、版本、发布准备、安装和绑定状态接口。页面至少区分资料上传/引用、解析切块/RAG 入库任务状态、知识库版本与回滚可见状态、发布预检状态、市场安装状态、作品绑定状态和授权快照；前端只展示后端返回的任务与来源状态，不自行推断资料是否已可检索或可发布。

用户端页面文案必须使用产品语言：跳转授权、使用检查、工具权限摘要、运行权限摘要、来源重验、授权记录等。底层会话、检查编号、工具授权和运行权限包等技术名只能出现在管理员审计、调试详情或接口说明中，不能作为普通用户界面的标题、按钮、错误提示或空态说明。

## 4. 用户端路由建议

```text
muse-studio/
  app/
    (auth)/
      login/
    (user)/
      works/
        page.tsx
        [workId]/
          writing/
          planning/
          knowledge/
          agents/
          import/
          export/
          records/
      agents/
      knowledge-bases/
      marketplace/
      profile/
  components/
    workspace/
    writing-desk/
    planning-desk/
    knowledge/
    agents/
    marketplace/
    personal-center/
    editor/
    common/
  lib/
    api/
    queries/
    mutations/
    store/
    auth/
    permissions/
    types/
```

约束：

- 登录恢复和应用入口初始化调用 `/app-api/muse/me`，用于获取当前用户、权益摘要、默认入口和可见产品空间。
- `/works` 只承载我的作品列表和入口。
- `/works/[workId]/*` 才承载单作品深层创作流程。
- 智能体、知识库、市场、个人中心是用户端顶级空间，不塞进某个作品工作台内部。
- 作品工作台只展示当前作品关联的智能体、知识库和市场资产使用状态，不承载完整后台配置。
- 作品资产在 feature gate 开启前只出现阅读、收藏、授权记录和不可用原因；模板化、参考来源写入和 AI 上下文绑定入口必须禁用或隐藏，并显示需要后续能力开启。

## 5. 状态分层

| 状态类型 | 管理后台 | 用户端 |
|---|---|---|
| 服务器事实 | Vben API store / table query | TanStack Query |
| 表单状态 | Ant Design Vue Form | React Hook Form / local form state |
| UI 临时态 | Vben route/menu/modal state | Zustand / component state |
| 权限可见性 | 后端菜单和权限点驱动 | `/app-api/muse/me` 权益摘要 + 业务接口结果 |
| 待确认内容 | 管理后台只查看、治理或异常处理 | 用户端决策：接受、修改后合并、丢弃、确认知识、规划候选确认 |

正式事实来自后端 Canonical，待确认内容来自 Shadow，历史来自 Archive。前端不能把本地缓存伪造成正式事实。

## 6. 实时通信策略

用户端使用 SSE（Server-Sent Events）作为实时通信方案，分为两类连接：

### 6.1 AI 生成 streaming 端点

- 路径：`POST /app-api/muse/ai/generate/stream`
- 生命周期：per-request，请求发起时建立 SSE 连接，生成完成后连接关闭。
- 用途：AI 正文生成、候选生成等需要流式输出的场景。
- 结束信号：服务端发送 `event: done`，payload 包含候选 ID。前端收到后用候选 ID 调用 REST 接口（`GET /app-api/muse/suggestions/{suggestionId}`）获取完整结构化结果（质量评分、来源标注等元数据）。
- 错误处理：服务端发送 `event: error` 时，前端展示错误原因并关闭连接。

### 6.2 统一事件 stream

- 路径：`GET /app-api/muse/events/stream`
- 生命周期：长连接，用户登录后建立，页面关闭时断开。
- 用途：接收服务端推送的异步事件通知，前端按 event type 分发到对应处理器。

事件类型枚举：

| event type | 含义 | 前端处理 |
|---|---|---|
| `candidate.arrived` | 新候选到达 | 刷新候选列表，展示新候选提示 |
| `task.completed` | 异步任务成功完成 | 停止轮询，刷新任务结果 |
| `task.failed` | 异步任务失败 | 停止轮询，展示失败原因 |
| `source.changed` | 来源状态变化 | 刷新来源状态，按需禁用操作 |
| `knowledge.auto_confirmed` | 知识自动确认 | 刷新知识草稿列表 |

### 6.3 断线重连策略

- 重连机制：使用 `lastEventId` 续传。每次收到事件时记录 `lastEventId`，断线重连时通过 `Last-Event-ID` header 告知服务端续传位置。
- 服务端保留策略：服务端保留最近 N 分钟事件。重连时如果 `lastEventId` 仍在保留窗口内，从该位置补发后续事件。
- resync 降级：如果 `lastEventId` 已过期（超出保留窗口），服务端返回 `event: resync`。前端收到 `resync` 后，放弃增量补发，改为 refetch 当前页面所有相关状态（通过 TanStack Query 的 `invalidateQueries` 批量刷新）。
- 退避策略：重连间隔使用指数退避（1s → 2s → 4s → 8s → 最大 30s），连接成功后重置。

## 7. 接口边界

- 管理后台只调用 `/admin-api/**`。
- 用户端只调用 `/app-api/**`。
- 用户端当前用户入口是 `GET /app-api/muse/me`，不使用 `/app-api/auth/me`。
- `system/infra` 的平台接口按 Yudao 约定保留。
- Muse 新业务接口由后端模块分别提供 admin/app controller。
- 前端类型可以由 OpenAPI 或等价接口契约生成，但接口 owner 是 `后端-05`。
- 前端禁止绕过接口直接访问数据库、对象存储私有地址、RAGFlow、New-API 或内部模型服务。
- 导出和下载前端必须承接服务端返回的导出清单(included/excluded manifest)：展示已包含内容、已排除内容、排除原因、下载凭证有效期和来源/授权重验状态。下载凭证过期、来源被召回或授权被撤销时，用户端必须重新检查或重新生成，不能继续显示单一“成功下载”态。

## 8. 权限与导航边界

- Vben 管理后台的菜单、按钮和页面权限来自 `system` 菜单权限体系。
- `muse-studio` 的导航可见性来自用户权益、授权、作品权限和业务状态。
- 隐藏菜单不是安全边界；后端必须在 `/admin-api/**` 和 `/app-api/**` 同时做认证与业务权限校验。
- 管理员后台可以查看治理摘要、异常摘要、脱敏元信息和审计，不默认读取用户私有正文全文、私有版本全文或用户知识库全文。
- 用户端不允许通过 URL 进入管理后台配置。
- 用户端市场购买、安装、绑定成功后，只刷新授权、安装状态、可用动作和来源授权快照；不会把市场资产内容自动写入作品正文、Local KB 或规划正式事实。

## 9. 跨空间跳转与 Handoff 前端消费

市场购买、安装或绑定资产后，用户需要从市场空间跳转到目标空间（知识库工作台、智能体工作台或作品工作台）完成绑定或使用。Handoff token 是跨空间跳转的前端传递机制。

### 9.1 Handoff token 前端生命周期

创建：

- 市场购买/安装成功后，前端调用 `POST /app-api/muse/marketplace/handoffs` 创建 handoff token。
- 服务端返回 `handoffToken`、过期时间和目标 owner 消费入口。

传递方式：

- Handoff token 通过 URL query parameter 传递到目标空间页面，例如 `/works/[workId]/knowledge?handoffToken=xxx`。
- 前端路由守卫在目标页面解析 `handoffToken` 参数。
- 传递后立即从 URL 中移除 `handoffToken`（使用 `replaceState`），避免刷新重复消费。

目标空间消费：

- 知识库绑定：目标页面解析 handoff token 后，调用 `POST /app-api/muse/works/{workId}/knowledge-bindings/prechecks` 传入 handoff 信息，获取 `kbBindPrecheckId`，再调用绑定接口完成绑定。
- 智能体槽位替换：目标页面调用 `POST /app-api/muse/works/{workId}/agent-slots/{slotKey}/prechecks` 传入 handoff 信息，获取 `agentSlotPrecheckId`，再调用绑定接口完成槽位替换。
- 前端不能自造 precheck，必须由目标 owner 基于 handoff token 生成。

过期/取消处理：

- Handoff token 有短期时效（服务端定义）。
- 过期时前端展示"跳转授权已过期，请返回市场重新操作"，引导用户回到市场空间。
- 用户可主动取消（`POST /app-api/muse/marketplace/handoffs/{handoffToken}/cancel`）。
- 已消费的 handoff 不可重复使用；重复消费返回 `MARKET_HANDOFF_INVALID`，前端提示并引导刷新。

### 9.2 Handoff 状态查询

- 前端可调用 `GET /app-api/muse/marketplace/handoffs/{handoffToken}` 查询 handoff 当前状态。
- 状态包括：有效、已消费、已过期、已取消。
- 目标页面在消费前应先查询状态，避免对已失效 handoff 发起无效请求。

## 10. 关联阅读

- 产品定位：`产品-01-产品定位与核心价值.md`
- 功能总纲：`产品-02-核心功能与交互边界.md`
- 管理后台规格：`产品-02B-管理员控制台功能规格.md`
- 用户端规格：`产品-02C` 至 `产品-02G`
- 后端工程结构：`后端-02-工程结构与模块职责.md`
- API 契约：`后端-05-统一API契约-v1.md`