常见问题

npm install 出现 Vue 与 Pinia 依赖冲突

优先使用项目锁定版本，不要直接 --force。确认 package.json 和 lock 文件一致，再删除由失败安装产生的临时依赖并重新安装。当前项目选择与 Vue 3.4 兼容的 Pinia 版本。

登录成功后又提示认证失败

登录后还会请求 mine 和 mineResources。如果其中任一接口返回 401，前端会清除 Token。检查服务端 Token 是否写入 Redis、用户是否启用以及认证接口路径是否正确。

没有角色时进入 404 循环

登录页、首页和个人中心不应依赖角色菜单权限。前端没有可访问菜单时回到个人中心，并始终允许退出登录。

按钮仍显示，但接口返回 403

按钮由 view: 资源控制，接口由 api: 资源控制。检查普通角色是否仍拥有按钮资源，前端是否刷新认证上下文，以及后端资源是否启用。

取消接口挂载后接口仍能访问

挂载关系本身不等于角色授权。如果角色的 sys_role_res 仍存在接口资源，鉴权仍可能通过。当前实现应在挂载删除时清理失效挂载授权；保存角色授权后重新查询确认。

同一接口在多个授权位置一起勾选

前端树节点不能只用接口 resId 作为 Key。同一接口多对多挂载时必须按 mountId 区分展示位置。

地区树接口很快但页面很慢

检查前端是否默认展开了全部区县、是否重复调用 tree、是否一次渲染大量节点。默认只展开省和市，街道村庄不进入首屏树。

上传头像成功但刷新后不显示

确认保存资料接口已经提交新 fileKey，存储记录已标记使用，头像 URL 使用公开预览或有权限的预览方式。null 表示不更新，空字符串表示清空。

删除存储提示正在使用

isUsed = true 时默认保护。确认没有业务引用后，在页面二次确认并使用强制删除。不要通过直接修改数据库绕过文件清理。

系统参数修改后不生效

检查参数键、类型和启用状态，点击“刷新缓存”。如果仍异常，通过日志确认 Redis 快照是否重建，并检查代码是否使用对应 SysConfigEnum。

接口返回 401 和 403 有什么区别

• 401：Token 不存在、无效或服务端已撤销，前端回登录页。
• 403：身份有效但缺少权限，前端保留会话。

如何排查一次接口调用

从响应取得 traceId，在服务端日志中搜索相同 reqId，依次查看鉴权结果、SQL、Service 日志和最终返回。文件响应没有 JSON traceId 时，根据请求时间和服务端请求日志定位。

文档为什么不能直接打开 Markdown

文档源码需要 VitePress 开发服务器或构建。开发执行 npm run dev；生产执行 npm run build 并托管 docs/.vitepress/dist。