核心内容概览
稀土掘金开发者社区最新发布的《WMS 仓储系统集成 AI Agent 实战》第 7 讲，系统总结了基于 Vue 3.5.13 + Vue Router 4.5 + Pinia 2.3 的前端工程化实践。项目核心技术栈还包括 Axios 1.7.9 + Element Plus 2.9.1 + markdown-it 14.1 + Vite 6.2.4，采用 pnpm 作为包管理器。
项目采用明确的目录结构划分：api 目录封装网络请求（request.js 为核心拦截器），stores 目录独立管理 user.js 与 chat.js 两个 Pinia store，components 目录包含 GlobalLayout.vue 与 PermissionBtn.vue 通用组件。
核心实现要点包括：
- Pinia 双 Store 职责分离：user.js 管理认证态（token/role/expiresAt 等）并双写 localStorage；chat.js 专门处理流式对话状态
- 并发刷新的单飞+排队模式：基于 Axios 拦截器实现 token 刷新锁，防止重复刷新请求
- Markdown 渲染安全方案：采用 markdown-it 的 ‘zero’ 预设 + 白名单语法机制
- RBAC 前端三层权限控制：路由守卫、菜单过滤与按钮级指令配合实现
Pinia 双 Store 设计与流式对话 Bug 修复
user.js store 维护五个响应式状态（token、refreshToken、role、userName、expiresAt），通过 computed 属性派生 isAdmin 角色判定。其最核心设计是刷新 token 使用独立 axios 实例，绕过主拦截器避免死循环。
localStorage 双写策略解决刷新页面后 Pinia 内存态丢失问题。作者特别说明：前端 role 可通过 F12 修改仅影响展示层，后端 RBAC 校验才是真正的安全闸门。
chat.js store 的 updateLastMessage → updateMessageAt 修复，对应一个关键 bug：
| 版本 | Vue 3.5.13 + Pinia 2.3 |
|---|---|
| 复现场景 | 工具调用的流式对话（tool_call 插入后文字 token 继续到达） |
| 真实现象 | AI 气泡停在半句话，后续 token 静默丢失 |
| 根因 | 工具卡片作为独立消息插入后，“最后一条"不再指向 AI 消息 |
该修复证明：流式场景必须用索引定位消息，不能依赖"最后一条"逻辑。这一经验同样适用于-appendToolCallToMessage 与 appendToolResultToMessage 等工具调用相关操作。
Axios 拦截器三层刷新与双路径 401 处理
项目在 request.js 中实现完整的三层刷新逻辑：
- 死循环防护：认证接口（login/register/refresh）直接放行
- 刷新失败熔断：refresh 接口返回 401 直接触发登出，不再重试
- 业务码与 HTTP 状态双路径：后端两种 401 均需处理
后端 401 分为两种形态：
- HTTP 200 + body.code === 401（业务层 Result.error）
- HTTP 401 状态码（Security 过滤器链直接拦截）
两者 body 格式不同（后者无统一 code 字段），前端必须分别处理。403 的处理逻辑与 401 严格区分：仅跳转提示页（router.push(’/403’)），不触发登出——因为 403 表示权限不足而非认证失效。
Markdown 渲染的安全边界界定
Markdown 渲染采用 markdown-it 14.1.0，但放弃默认 commonmark 预设，转而使用 ‘zero’ 预设 + 白名单启用：
| |
| 问题表现 | 流式渲染中正文随机出现巨大字号或加粗 |
|---|---|
| 根因层1 | Setext 语法：残缺 Markdown （如”###“后接换行）被误识别为标题 |
| 根因层2 | 业务数据中的 --- 与 ** 被解析为 hr 与 strong |
白名单方案比黑名单更安全：对话场景实际只需段落、链接、代码等基础语法，heading/strong/em/hr 等高级语法全部禁用，确保流式中间态与业务数据均能正确渲染。
RBAC 权限前端实现与知识库工程细节
前端实现三层 RBAC 控制：
- 路由 meta + 导航守卫：通过 to.meta.role 字段校验角色，未授权跳转 403 页面
- 菜单动态过滤：GlobalLayout.vue 按 meta.role 过滤侧边栏菜单（USER 角色不可见知识库管理等入口）
- PermissionBtn 按钮指令：组件级控制物料编辑/删除按钮的可见性
作者强调三层均为体验层，后端接口必须有 @PreAuthorize 或 Security 配置兜底。
知识库管理页的两个工程细节：
- 批量上传串行处理：每个文件需 Tika 解析+分片+bge-m3 向量化（20MB PDF 耗时数十秒），并发会打爆 Ollama embedding 队列
- Blob 手动下载：因下载接口需 Authorization 头，使用 fetch + createObjectURL 触发下载后记得调用 URL.revokeObjectURL 释放内存
RAG 问答支持追问能力需历史对话上下文，但原文未提供具体实现参数。
落地建议
- 适合开发者：正在构建含流式 AI 对话与权限系统的中后台项目；需处理 JWT token 刷新与 Markdown 渲染的场景
- 建议再观望者：若项目暂无工具调用流式对话场景，可暂缓实施索引定位式更新方案；若使用较新版本 markdown-it（14.1+后），建议实测 zero 预设兼容性
写在最后
前端工程化的核心挑战并非技术本身，而在于识别那些不抛异常却真实影响用户体验的"静默 bugs”。本讲揭示的两个关键经验——流式对话必须索引定位、Markdown 白名单优于黑名单——体现了对框架默认行为的深度反思与准确边界界定。随着 AI 模型能力增强，前端与大模型的交互契约将持续演进，而可靠的工程措施永远是体验的基石。