常见问题

版本：v3.0 ｜ 最后更新：2026-07 ｜ 文档状态：已同步代码

项目开发和使用中经常遇到的问题，以及解决方法。

---

环境相关

Q: 启动后端时报数据库连接失败

原因：MySQL 服务未启动，或数据库配置不匹配。

解决：

1. 确认 MySQL 服务已启动
2. 检查 application.yml 中的数据库地址、用户名、密码
3. 确认 mall 数据库已创建并导入了 docs/sql/mall.sql

Q: Redis 连接超时

原因：Redis 服务未启动。

解决：运行 redis-server 启动 Redis，默认端口 6379。

Q: 前端页面显示"暂无数据"但数据库有数据

原因：后端服务未启动或端口不对。

解决：

1. 确认 mall-admin（8080）和 mall-portal（8085）都已启动
2. 打开浏览器控制台看是否有网络请求报错
3. 检查 Vite 代理配置是否正确

---

功能相关

Q: 后台登录后侧边栏菜单为空

原因：当前管理员账号没有分配角色，或角色没有分配菜单权限。

解决：用超级管理员（admin）登录 → 权限管理 → 给该管理员分配角色 → 给角色分配菜单。

Q: 商品分类"是否显示"开关切换后自动弹提示

原因：这是 el-switch 组件的已知行为，初始化时会触发 change 事件。

解决：已在代码中处理，通过标记位防止初始化时误触发。

Q: 前台商城页面打不开

原因：前台需要 mall-portal（8085）服务运行。

解决：确保同时启动了 mall-admin 和 mall-portal 两个后端服务。

Q: 退货申请审核按钮点了没反应

原因：可能是 keep-alive 缓存导致页面数据未刷新。

解决：离开页面后重新进入，或刷新页面后再操作。

---

开发相关

Q: 新增的 API 返回 401 未授权

原因：新接口没有加入安全白名单。

解决：在对应的 application.yml 中的 secure.ignored.urls 里添加新接口路径。

Q: 前端编译报 TypeScript 错误

解决：

1. 运行 cd mall-admin-web && npx tsc --noEmit 查看具体错误
2. 检查是否有新增的类型未定义
3. 确认 src/types/ 下的类型文件是否完整

Q: 修改了代码但页面没变化

原因：可能是浏览器缓存或 Vue keep-alive 缓存。

解决：

1. 浏览器硬刷新（Ctrl + Shift + R）
2. 如果是列表页，检查是否需要在 onActivated 中重新加载数据

Q: 后台商品图片 / 富文本传图失败（404）

原因：前端上传地址与后端端点不一致。上传地址取自 .env 的 VITE_MINIO_UPLOAD_URL，必须等于后端 MinioController 的 /api/minio/upload，否则请求既匹配不到 Vite 代理、后端也会 404。

解决：确认 mall-admin-web/.env 中 VITE_MINIO_UPLOAD_URL=/api/minio/upload（曾误配为 /minio/upload，已修复）。改完需重启 npm run dev 让 Vite 重新读取 .env。

Q: 订单超过超时时间没有自动关闭

原因：超时取消有两条路径，任一出问题都会导致订单挂住。

解决：

1. 主路径 —— RabbitMQ 死信延迟队列：下单时发送延迟消息，到期后由 CancelOrderReceiver 消费。请确认 RabbitMQ 已启动（未启动则延迟消息无法投递）。
2. 兜底路径 —— OrderTimeOutCancelTask 每 10 分钟扫描一次超时未支付订单（status = 0 且超过 oms_order_setting.normal_order_overtime），已启用。
3. 也可手动触发：POST /api/order/cancelTimeOutOrder。

Q: 前台搜索没有走 Elasticsearch

原因：mall-search 模块虽有完整的 ES 代码，但与 mall-portal / mall-admin / 前端均未接线，且没有 ES 服务实例。

解决：当前设计如此，前台搜索走 MySQL LIKE。ES 接入属于 Phase 3+ 规划。

Q: 支付宝/微信支付点了就直接成功

原因：支付整体是模拟实现——paySuccess 直接置订单状态为已支付并扣减库存，无支付网关调用、无签名校验。前台支付页的「微信支付」按钮是占位（后端 0 实现），支付宝后端 SDK 代码完整但凭据为 your appId 占位符、前端未接线。

解决：这是预期行为（演示环境）。真实支付接入见 docs/guide/roadmap.md 的 Phase 3+。

---

数据相关

Q: 数据库有多少张表、在哪里看

所有表结构定义在 docs/sql/mall.sql 文件中。业务实体及关联关系可参考 数据字典。

表数量只有一个权威来源 —— docs/dev/context.md 的「3.1 关键数字」小节。其他文档不再复述该数字，避免改一处漏十处。

Q: 可以新增数据库表吗

当前阶段不新增表，所有功能基于现有表实现（表数量见 docs/dev/context.md 第 3.1 节）。

Q: 测试数据在哪里

数据库脚本已包含基础数据（管理员、角色、菜单、部分商品等）。如需更多测试数据，可参考数据字典手动添加。