mall4j/doc

Mall4j 技术文档

用 Cursor、Codex 或 Claude Code 打开本仓库时，可使用内置 Skill：.agents/skills/mall4j/（Claude Code 为 .claude/skills/mall4j/，内容相同）。它按开源版现有功能点辅助启动、使用和二次开发，详细说明仍以本 doc/ 目录为准。

本文档面向项目维护者和二次开发者，目标是让新接手的人：

• 30 分钟跑起后端接口、管理后台、MySQL、Redis。
• 2 小时读懂项目结构、技术框架和权限体系。
• 1 天完成一个简单后台管理功能的二次开发。

推荐阅读路径

首次接手项目，先按“跑起来”阅读：

1. 30 分钟启动路线
2. 环境要求
3. 数据库初始化
4. 后端本地启动
5. 管理后台本地启动
6. 启动检查题-含答案

跑起来以后，再读“看懂和二开”：

1. 项目介绍
2. 数据库表阅读路线
3. 核心表速查
4. 整体架构
5. 权限体系
6. 二开总览
7. 新增后台管理功能-帮助中心文章

准备上线时，读“部署运维”：

1. 部署路径选择
2. 部署总览
3. 生产配置
4. Nginx 配置
5. 上线检查题-含答案

目录说明

目录	说明
1-项目概览	项目定位、仓库结构、后端模块和前端项目说明。
2-环境搭建	本地开发环境、数据库初始化、后端和管理后台启动。
3-技术框架	整体架构、后端分层、前后端调用链路、配置文件。
4-技术实现	权限、异常、日志、分页、文件上传、分布式锁等通用机制。
5-二次开发	二开路径、后台功能示例、菜单权限、接口和前端页面。
6-核心业务	商品、SKU、购物车、订单、支付等主链路。
7-数据模型	核心表关系、字段含义、业务概念到数据表的映射。
8-部署运维	Docker、Nginx、生产配置和上线注意事项。
9-故障排查	启动、登录、验证码、401、接口地址等常见问题。

本地默认端口

服务	默认端口	入口
管理端后端 yami-shop-admin	8085	WebApplication
用户端后端 yami-shop-api	8086	ApiApplication
管理后台 front-end/mall4v	9527	pnpm run dev
MySQL	3306	数据库名 yami_shops
Redis	6379	默认库 0