mirror of
https://gitee.com/gz-yami/mall4j.git
synced 2026-10-06 06:12:57 +08:00
添加AI Skill
This commit is contained in:
lhd
@@ -0,0 +1,63 @@
|
||||
---
|
||||
name: mall4j
|
||||
description: "Mall4j 开源版现有功能副驾驶：本地启动、mall4v/mall4m/mall4uni、商品/SKU、购物车、下单支付、订单发货、会员、运费、权限、部署排查。适用于下载 mall4j / yami-shop 后按现有功能使用或二次开发；不要编造开源版没有的能力。"
|
||||
---
|
||||
|
||||
# Mall4j 开源版现有功能副驾驶
|
||||
|
||||
给已下载本仓库的人用：按**现有功能点**说明怎么用、改哪。细节以 `doc/` 和源码为准。路径相对仓库根目录（含 `pom.xml`、`yami-shop-admin`、`front-end`、`doc`）。这是 B2C 单商户开源版，不要套 mall4cloud / 跨境版。使用通用 `SKILL.md`（Agent Skills），Cursor、Codex、Claude Code 均可加载。
|
||||
|
||||
## 每轮怎么做
|
||||
|
||||
1. 判断场景：启动 / 排查 / 部署，或某一个现有功能点。
|
||||
2. 只读下方路由里该行的 1–3 篇 `doc/`。不要整目录读 `doc/`。
|
||||
3. **只有问到具体功能（商品、购物车、订单等）时**，再读 [references/feature-map.md](references/feature-map.md)。启动、401、端口问题不要读地图。
|
||||
4. 先说当前实现，再给基于现有文件的改法。
|
||||
|
||||
## 快速路由
|
||||
|
||||
| 场景 | 最少阅读 |
|
||||
| --- | --- |
|
||||
| 第一次启动、登录后台 | `doc/2-环境搭建/1-30分钟启动路线.md`、`doc/2-环境搭建/2-环境要求.md`、`doc/2-环境搭建/3-数据库初始化.md` |
|
||||
| 接口地址、401、验证码 | `doc/2-环境搭建/6-前端接口地址配置.md`、`doc/9-故障排查/1-常见问题.md` |
|
||||
| 启动失败 | `doc/9-故障排查/2-启动失败.md` |
|
||||
| 模块怎么分 | `doc/1-项目概览/1-项目介绍.md`、`doc/1-项目概览/3-后端模块说明.md`、`doc/1-项目概览/4-前端项目说明.md` |
|
||||
| 商品 / SKU / 分类 / 规格 | `doc/6-核心业务/2-商品与SKU.md` |
|
||||
| 购物车 | `doc/6-核心业务/3-购物车.md` |
|
||||
| 确认 / 提交订单 | `doc/6-核心业务/4-确认订单.md`、`doc/6-核心业务/5-提交订单.md` |
|
||||
| 支付 | `doc/6-核心业务/6-支付流程.md` |
|
||||
| 订单 / 发货 | `doc/6-核心业务/7-订单管理.md` |
|
||||
| 交易总览 | `doc/6-核心业务/1-核心交易链路.md` |
|
||||
| 权限 / 菜单 | `doc/4-技术实现/1-权限体系.md` |
|
||||
| 改现有后台页、菜单不显示 | `doc/5-二次开发/3-二开文件位置速查.md`、`doc/5-二次开发/9-二开常见卡点.md` |
|
||||
| 部署上线 | `doc/8-部署运维/1-部署路径选择.md`、`doc/8-部署运维/3-生产配置.md` |
|
||||
|
||||
表名、Controller、页面对应关系：问到该功能时再打开 `feature-map.md`。分层/配置按问题补 `doc/3-技术框架/` 或 `doc/4-技术实现/` 对应篇。
|
||||
|
||||
## 固定口径
|
||||
|
||||
| 端 | 位置 | 本地 |
|
||||
| --- | --- | --- |
|
||||
| 管理端 | `yami-shop-admin`（`WebApplication`） | `8085` |
|
||||
| 用户端 | `yami-shop-api`（`ApiApplication`） | `8086` |
|
||||
| 管理后台 | `front-end/mall4v` | `9527` → `8085` |
|
||||
| 小程序 | `front-end/mall4m` | `utils/config.js` → `8086` |
|
||||
| uni-app | `front-end/mall4uni` | `.env.*` → `8086` |
|
||||
| 库 | `db/yami_shop.sql` | `yami_shops` |
|
||||
|
||||
后台账号 `admin` / `123456`。第一次只跑 MySQL + Redis + admin + mall4v。mall4v 接口用 `VITE_APP_BASE_API`，资源用 `VITE_APP_RESOURCES_URL`。菜单 `url` = `front-end/mall4v/src/views/modules/<url>/index.vue`。
|
||||
|
||||
后台功能放 `yami-shop-admin`，浏览/购物车/下单/支付放 `yami-shop-api`。规则放 Service。改菜单时同时核 `tz_sys_menu`、`@PreAuthorize`、前端 `isAuth()`。
|
||||
|
||||
交易主线：`商品/SKU → 购物车 → 确认订单 → 提交订单 → 支付 → 后台发货`。金额看 `tz_order_settlement`，不接受前端传应付金额。开源支付会直接 `paySuccess()`，回调在 `PayNoticeController` 里是注释；不要把同步返回或支付结果页当成生产支付成功。
|
||||
|
||||
库存、订单/支付状态、`OrderTask` 自动取消/确认收货，改前先读对应 `doc/6` 并跑通链路。
|
||||
|
||||
## 不要编
|
||||
|
||||
开源版没有：多商户、SaaS、跨境、分销、营销中台、完整优惠券（`couponIds` 仅保留字段）、完整退款（有 `tz_order_refund` 无 Controller）、生产微信/支付宝。不要改成 mall4cloud 微服务。用户要这些时说明现状即可。
|
||||
|
||||
分不清 8085/8086 或三端、要把开源支付当三方上线、或能力不在现有功能点里：先停下来问一句，再改代码。
|
||||
|
||||
不重写订单状态机；不把密钥写入仓库或前端；不把 `doc/` 全文贴进回答。
|
||||
---
|
||||
@@ -0,0 +1,173 @@
|
||||
# Mall4j 开源版现有功能点地图
|
||||
|
||||
启动、401、端口问题不要读本文件。只在用户问到某个现有功能时打开。
|
||||
|
||||
只列仓库里已经有的入口。路径相对 Mall4j 仓库根目录。管理端 Controller 默认在：
|
||||
|
||||
```text
|
||||
yami-shop-admin/src/main/java/com/yami/shop/admin/controller/
|
||||
```
|
||||
|
||||
用户端 Controller 默认在：
|
||||
|
||||
```text
|
||||
yami-shop-api/src/main/java/com/yami/shop/api/controller/
|
||||
```
|
||||
|
||||
系统权限 Controller 在：
|
||||
|
||||
```text
|
||||
yami-shop-sys/src/main/java/com/yami/shop/sys/controller/
|
||||
```
|
||||
|
||||
后台页面在 `front-end/mall4v/src/views/modules/`，CRUD 配置在 `front-end/mall4v/src/crud/`。
|
||||
C 端：小程序 `front-end/mall4m/pages/`，uni-app `front-end/mall4uni/src/pages/`。
|
||||
|
||||
表结构以 `db/yami_shop.sql` 为准。
|
||||
|
||||
## 启动与使用
|
||||
|
||||
| 事项 | 位置 |
|
||||
| --- | --- |
|
||||
| 最小闭环 | MySQL `3306` → Redis `6379` → `yami-shop-admin` `8085` → `mall4v` `9527` |
|
||||
| 初始化 SQL | `db/yami_shop.sql`，库名 `yami_shops` |
|
||||
| 后台账号 | `admin` / `123456` |
|
||||
| 管理端配置 | `yami-shop-admin/src/main/resources/application-dev.yml` |
|
||||
| 用户端配置 | `yami-shop-api/src/main/resources/application-dev.yml` |
|
||||
| mall4v 接口 | `front-end/mall4v/.env.development` → `VITE_APP_BASE_API` |
|
||||
| mall4m 接口 | `front-end/mall4m/utils/config.js` |
|
||||
| mall4uni 接口 | `front-end/mall4uni/.env.development` |
|
||||
| 文档 | `doc/2-环境搭建/` |
|
||||
|
||||
用户端本地联调时再启动 `yami-shop-api`（`8086`）以及 mall4m 或 mall4uni。
|
||||
|
||||
## 商品
|
||||
|
||||
| 能力 | 管理端 | 用户端 | 后台页 | C 端页 | 表 |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| 商品 SPU / 发布 | `ProductController` | `ProdController` | `prod/prodList`、`prod/prodInfo` | `prod/prod` | `tz_prod` |
|
||||
| SKU / 价格库存 | 随商品保存 | `SkuController` | `prod/prodInfo` 内组件 | 商品详情 | `tz_sku` |
|
||||
| 分类 | `CategoryController` | `CategoryController` | `prod/category` | `category`、`prod-classify` | `tz_category` |
|
||||
| 规格 | `SpecController` | — | `prod/spec` | — | `tz_prod_prop`、`tz_prod_prop_value` |
|
||||
| 商品分组 | `ProdTagController`、`ProdTagReferenceController` | `ProdTagController` | `prod/prodTag` | 首页/分组展示 | `tz_prod_tag`、`tz_prod_tag_reference` |
|
||||
| 商品评论 | `ProdCommController` | `ProdCommController` | `prod/prodComm` | 商品详情评论 | 评论相关表 |
|
||||
| 搜索 | — | `SearchController` | — | `search-page`、`search-prod-show` | 商品表 |
|
||||
|
||||
品牌 `BrandController`、属性 `AttributeController` 有管理端接口，后台没有独立 `views/modules` 目录。改商品发布时跟 `prod/prodInfo` 和对应 Service，不要假设有单独菜单页。
|
||||
|
||||
文档：`doc/6-核心业务/2-商品与SKU.md`、`doc/7-数据模型/5-商品数据模型.md`。
|
||||
|
||||
## 购物车
|
||||
|
||||
| 项 | 位置 |
|
||||
| --- | --- |
|
||||
| 用户端 | `ShopCartController` |
|
||||
| 表 | `tz_basket`，唯一索引 `uk_user_shop_sku(sku_id, user_id, shop_id)` |
|
||||
| C 端 | mall4m / mall4uni 的 `basket` |
|
||||
| 文档 | `doc/6-核心业务/3-购物车.md` |
|
||||
|
||||
主要接口：`/p/shopCart/info`、`changeItem`、`deleteItem`、`deleteAll`、`prodCount`、`expiryProdList`、`totalPay`。`changeItem` 的 `count` 是增量。
|
||||
|
||||
## 确认订单与提交订单
|
||||
|
||||
| 项 | 位置 |
|
||||
| --- | --- |
|
||||
| 用户端 | `OrderController`（`confirm`、`submit`） |
|
||||
| 监听 | `ConfirmOrderListener`、`SubmitOrderListener` |
|
||||
| 服务 | `OrderServiceImpl`、购物项组装在 `BasketServiceImpl` |
|
||||
| C 端 | `submit-order` |
|
||||
| 表 | `tz_order`、`tz_order_item`、`tz_order_settlement`、`tz_user_addr_order` |
|
||||
| 文档 | `doc/6-核心业务/4-确认订单.md`、`doc/6-核心业务/5-提交订单.md` |
|
||||
|
||||
`OrderParam`：`basketIds` 购物车结算，`orderItem` 立即购买，`addrId` 必填。`couponIds` 为开源版保留参数，不要按已接通优惠券来实现。
|
||||
|
||||
库存扣减：`SkuMapper.xml`、`ProductMapper.xml` 条件更新。
|
||||
|
||||
## 支付
|
||||
|
||||
| 项 | 位置 |
|
||||
| --- | --- |
|
||||
| 下单支付 | `PayController`，`POST /p/order/pay`、`/p/order/normalPay` |
|
||||
| 实现 | `PayServiceImpl` |
|
||||
| 回调 | `PayNoticeController`（逻辑注释中） |
|
||||
| 参数 | `PayParam`：订单号集合 + 支付方式，不含前端金额 |
|
||||
| C 端 | `pay-result` |
|
||||
| 表 | `tz_order_settlement`（`payNo`、`pay_amount`） |
|
||||
| 文档 | `doc/6-核心业务/6-支付流程.md` |
|
||||
|
||||
当前实现会直接 `paySuccess()` 并发布 `PaySuccessOrderEvent`。这是本地跑通，不是生产三方支付。
|
||||
|
||||
## 订单与发货
|
||||
|
||||
| 能力 | 入口 | 页面 |
|
||||
| --- | --- | --- |
|
||||
| 我的订单 / 详情 / 用户侧操作 | `MyOrderController` | `orderList`、`order-detail` |
|
||||
| 后台订单查询 / 详情 / 发货 / 导出 | 管理端 `OrderController` | `order/order` |
|
||||
| 物流查询 | 管理端/用户端 `DeliveryController` | `express-delivery` |
|
||||
| 超时取消、自动确认收货 | `yami-shop-admin/.../task/OrderTask.java` | — |
|
||||
| 状态枚举 | `yami-shop-bean/.../enums/OrderStatus.java` | — |
|
||||
|
||||
文档：`doc/6-核心业务/7-订单管理.md`、`doc/7-数据模型/6-订单数据模型.md`。
|
||||
|
||||
`tz_order_refund`、`OrderRefund`、`OrderRefundMapper` 存在，没有退款 Controller，也没有完整退款页面。不要按已上线退款流程改。
|
||||
|
||||
## 会员与地址
|
||||
|
||||
| 能力 | 管理端 | 用户端 | 后台页 | C 端页 | 表 |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| 会员 | `UserController` | `UserController`、`UserRegisterController` | `user/user` | `user`、`register`、登录页 | `tz_user` |
|
||||
| 地址 | `UserAddrController` | `AddrController` | `user` 相关 | `delivery-address`、`editAddress` | `tz_user_addr` |
|
||||
| 收藏 | — | `UserCollectionController` | — | 用户相关 | `tz_user_collection` |
|
||||
| 短信 | — | `SmsController` | — | 绑定手机等 | — |
|
||||
| 地区 | `AreaController` | `AreaController` | `sys/area` | 地址选择 | 地区表 |
|
||||
|
||||
## 店铺运营
|
||||
|
||||
| 能力 | 管理端 | 用户端 | 后台页 | 表 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 运费模板 | `TransportController` | 确认订单时计算 | `shop/transport` | `tz_transport` |
|
||||
| 自提点 | `PickAddrController` | — | `shop/pickAddr` | `tz_pick_addr` |
|
||||
| 公告 | `NoticeController` | `NoticeController` | `shop/notice` | `tz_notice` |
|
||||
| 热搜 | `HotSearchController` | 搜索相关 | `shop/hotSearch` | `tz_hot_search` |
|
||||
| 轮播 | `IndexImgController` | `IndexImgController` | `admin/indexImg` | `tz_index_img` |
|
||||
| 店铺信息 | `ShopDetailController` | — | 跟店铺配置代码 | `tz_shop_detail` |
|
||||
| 文件上传 | `FileController` | — | 各表单上传 | `tz_attach_file` |
|
||||
| 后台留言 | `MessageController` | — | 仅有 `crud/admin/message.js`，无独立 views 目录 | 跟 `Message` 模型 |
|
||||
|
||||
C 端首页 `index`，公告 `recent-news`、`news-detail`。
|
||||
|
||||
品牌 `BrandController`、属性 `AttributeController` 见商品节；留言接口存在但后台页不完整。改这些能力时先跟现有代码，不要假设有完整菜单页。
|
||||
|
||||
## 权限与系统
|
||||
|
||||
| 能力 | Controller | 后台页 | 表 |
|
||||
| --- | --- | --- | --- |
|
||||
| 管理员 | `SysUserController` | `sys/user` | `tz_sys_user`、`tz_sys_user_role` |
|
||||
| 角色 | `SysRoleController` | `sys/role` | `tz_sys_role`、`tz_sys_role_menu` |
|
||||
| 菜单按钮 | `SysMenuController` | `sys/menu` | `tz_sys_menu` |
|
||||
| 系统日志 | `SysLogController` | `sys/log` | 日志表 |
|
||||
| 系统配置 | `SysConfigController` | `sys/config` | 配置表 |
|
||||
| 管理端登录 | `AdminLoginController` | 登录页 | — |
|
||||
|
||||
权限标识走 `@PreAuthorize("@pms.hasPermission('...')")`。登录后菜单来自 `GET /sys/menu/nav`。文档：`doc/4-技术实现/1-权限体系.md`。
|
||||
|
||||
关系：
|
||||
|
||||
```text
|
||||
tz_sys_user -> tz_sys_user_role -> tz_sys_role -> tz_sys_role_menu -> tz_sys_menu
|
||||
```
|
||||
|
||||
## 部署与排查
|
||||
|
||||
| 场景 | 文档 |
|
||||
| --- | --- |
|
||||
| 选 jar 还是 Docker | `doc/8-部署运维/1-部署路径选择.md` |
|
||||
| 生产配置 | `doc/8-部署运维/3-生产配置.md`（admin / api 两份 `application-prod.yml` 都要改） |
|
||||
| Nginx | `doc/8-部署运维/4-Nginx配置.md` |
|
||||
| 上线自查 | `doc/8-部署运维/6-上线检查题-含答案.md` |
|
||||
| 401 / 验证码 / 端口 | `doc/9-故障排查/1-常见问题.md`、`4-接口地址与401问题.md` |
|
||||
| 启动失败 | `doc/9-故障排查/2-启动失败.md` |
|
||||
| 登录验证码 | `doc/9-故障排查/3-登录与验证码问题.md` |
|
||||
|
||||
当前 `docker-compose.yml` 引用了 `db/Dockerfile`，而 `db/` 只有 SQL，不能直接无脑 `docker compose up`。
|
||||
---
|
||||
@@ -0,0 +1,63 @@
|
||||
---
|
||||
name: mall4j
|
||||
description: "Mall4j 开源版现有功能副驾驶：本地启动、mall4v/mall4m/mall4uni、商品/SKU、购物车、下单支付、订单发货、会员、运费、权限、部署排查。适用于下载 mall4j / yami-shop 后按现有功能使用或二次开发；不要编造开源版没有的能力。"
|
||||
---
|
||||
|
||||
# Mall4j 开源版现有功能副驾驶
|
||||
|
||||
给已下载本仓库的人用：按**现有功能点**说明怎么用、改哪。细节以 `doc/` 和源码为准。路径相对仓库根目录（含 `pom.xml`、`yami-shop-admin`、`front-end`、`doc`）。这是 B2C 单商户开源版，不要套 mall4cloud / 跨境版。使用通用 `SKILL.md`（Agent Skills），Cursor、Codex、Claude Code 均可加载。
|
||||
|
||||
## 每轮怎么做
|
||||
|
||||
1. 判断场景：启动 / 排查 / 部署，或某一个现有功能点。
|
||||
2. 只读下方路由里该行的 1–3 篇 `doc/`。不要整目录读 `doc/`。
|
||||
3. **只有问到具体功能（商品、购物车、订单等）时**，再读 [references/feature-map.md](references/feature-map.md)。启动、401、端口问题不要读地图。
|
||||
4. 先说当前实现，再给基于现有文件的改法。
|
||||
|
||||
## 快速路由
|
||||
|
||||
| 场景 | 最少阅读 |
|
||||
| --- | --- |
|
||||
| 第一次启动、登录后台 | `doc/2-环境搭建/1-30分钟启动路线.md`、`doc/2-环境搭建/2-环境要求.md`、`doc/2-环境搭建/3-数据库初始化.md` |
|
||||
| 接口地址、401、验证码 | `doc/2-环境搭建/6-前端接口地址配置.md`、`doc/9-故障排查/1-常见问题.md` |
|
||||
| 启动失败 | `doc/9-故障排查/2-启动失败.md` |
|
||||
| 模块怎么分 | `doc/1-项目概览/1-项目介绍.md`、`doc/1-项目概览/3-后端模块说明.md`、`doc/1-项目概览/4-前端项目说明.md` |
|
||||
| 商品 / SKU / 分类 / 规格 | `doc/6-核心业务/2-商品与SKU.md` |
|
||||
| 购物车 | `doc/6-核心业务/3-购物车.md` |
|
||||
| 确认 / 提交订单 | `doc/6-核心业务/4-确认订单.md`、`doc/6-核心业务/5-提交订单.md` |
|
||||
| 支付 | `doc/6-核心业务/6-支付流程.md` |
|
||||
| 订单 / 发货 | `doc/6-核心业务/7-订单管理.md` |
|
||||
| 交易总览 | `doc/6-核心业务/1-核心交易链路.md` |
|
||||
| 权限 / 菜单 | `doc/4-技术实现/1-权限体系.md` |
|
||||
| 改现有后台页、菜单不显示 | `doc/5-二次开发/3-二开文件位置速查.md`、`doc/5-二次开发/9-二开常见卡点.md` |
|
||||
| 部署上线 | `doc/8-部署运维/1-部署路径选择.md`、`doc/8-部署运维/3-生产配置.md` |
|
||||
|
||||
表名、Controller、页面对应关系：问到该功能时再打开 `feature-map.md`。分层/配置按问题补 `doc/3-技术框架/` 或 `doc/4-技术实现/` 对应篇。
|
||||
|
||||
## 固定口径
|
||||
|
||||
| 端 | 位置 | 本地 |
|
||||
| --- | --- | --- |
|
||||
| 管理端 | `yami-shop-admin`（`WebApplication`） | `8085` |
|
||||
| 用户端 | `yami-shop-api`（`ApiApplication`） | `8086` |
|
||||
| 管理后台 | `front-end/mall4v` | `9527` → `8085` |
|
||||
| 小程序 | `front-end/mall4m` | `utils/config.js` → `8086` |
|
||||
| uni-app | `front-end/mall4uni` | `.env.*` → `8086` |
|
||||
| 库 | `db/yami_shop.sql` | `yami_shops` |
|
||||
|
||||
后台账号 `admin` / `123456`。第一次只跑 MySQL + Redis + admin + mall4v。mall4v 接口用 `VITE_APP_BASE_API`，资源用 `VITE_APP_RESOURCES_URL`。菜单 `url` = `front-end/mall4v/src/views/modules/<url>/index.vue`。
|
||||
|
||||
后台功能放 `yami-shop-admin`，浏览/购物车/下单/支付放 `yami-shop-api`。规则放 Service。改菜单时同时核 `tz_sys_menu`、`@PreAuthorize`、前端 `isAuth()`。
|
||||
|
||||
交易主线：`商品/SKU → 购物车 → 确认订单 → 提交订单 → 支付 → 后台发货`。金额看 `tz_order_settlement`，不接受前端传应付金额。开源支付会直接 `paySuccess()`，回调在 `PayNoticeController` 里是注释；不要把同步返回或支付结果页当成生产支付成功。
|
||||
|
||||
库存、订单/支付状态、`OrderTask` 自动取消/确认收货，改前先读对应 `doc/6` 并跑通链路。
|
||||
|
||||
## 不要编
|
||||
|
||||
开源版没有：多商户、SaaS、跨境、分销、营销中台、完整优惠券（`couponIds` 仅保留字段）、完整退款（有 `tz_order_refund` 无 Controller）、生产微信/支付宝。不要改成 mall4cloud 微服务。用户要这些时说明现状即可。
|
||||
|
||||
分不清 8085/8086 或三端、要把开源支付当三方上线、或能力不在现有功能点里：先停下来问一句，再改代码。
|
||||
|
||||
不重写订单状态机；不把密钥写入仓库或前端；不把 `doc/` 全文贴进回答。
|
||||
---
|
||||
@@ -0,0 +1,173 @@
|
||||
# Mall4j 开源版现有功能点地图
|
||||
|
||||
启动、401、端口问题不要读本文件。只在用户问到某个现有功能时打开。
|
||||
|
||||
只列仓库里已经有的入口。路径相对 Mall4j 仓库根目录。管理端 Controller 默认在：
|
||||
|
||||
```text
|
||||
yami-shop-admin/src/main/java/com/yami/shop/admin/controller/
|
||||
```
|
||||
|
||||
用户端 Controller 默认在：
|
||||
|
||||
```text
|
||||
yami-shop-api/src/main/java/com/yami/shop/api/controller/
|
||||
```
|
||||
|
||||
系统权限 Controller 在：
|
||||
|
||||
```text
|
||||
yami-shop-sys/src/main/java/com/yami/shop/sys/controller/
|
||||
```
|
||||
|
||||
后台页面在 `front-end/mall4v/src/views/modules/`，CRUD 配置在 `front-end/mall4v/src/crud/`。
|
||||
C 端：小程序 `front-end/mall4m/pages/`，uni-app `front-end/mall4uni/src/pages/`。
|
||||
|
||||
表结构以 `db/yami_shop.sql` 为准。
|
||||
|
||||
## 启动与使用
|
||||
|
||||
| 事项 | 位置 |
|
||||
| --- | --- |
|
||||
| 最小闭环 | MySQL `3306` → Redis `6379` → `yami-shop-admin` `8085` → `mall4v` `9527` |
|
||||
| 初始化 SQL | `db/yami_shop.sql`，库名 `yami_shops` |
|
||||
| 后台账号 | `admin` / `123456` |
|
||||
| 管理端配置 | `yami-shop-admin/src/main/resources/application-dev.yml` |
|
||||
| 用户端配置 | `yami-shop-api/src/main/resources/application-dev.yml` |
|
||||
| mall4v 接口 | `front-end/mall4v/.env.development` → `VITE_APP_BASE_API` |
|
||||
| mall4m 接口 | `front-end/mall4m/utils/config.js` |
|
||||
| mall4uni 接口 | `front-end/mall4uni/.env.development` |
|
||||
| 文档 | `doc/2-环境搭建/` |
|
||||
|
||||
用户端本地联调时再启动 `yami-shop-api`（`8086`）以及 mall4m 或 mall4uni。
|
||||
|
||||
## 商品
|
||||
|
||||
| 能力 | 管理端 | 用户端 | 后台页 | C 端页 | 表 |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| 商品 SPU / 发布 | `ProductController` | `ProdController` | `prod/prodList`、`prod/prodInfo` | `prod/prod` | `tz_prod` |
|
||||
| SKU / 价格库存 | 随商品保存 | `SkuController` | `prod/prodInfo` 内组件 | 商品详情 | `tz_sku` |
|
||||
| 分类 | `CategoryController` | `CategoryController` | `prod/category` | `category`、`prod-classify` | `tz_category` |
|
||||
| 规格 | `SpecController` | — | `prod/spec` | — | `tz_prod_prop`、`tz_prod_prop_value` |
|
||||
| 商品分组 | `ProdTagController`、`ProdTagReferenceController` | `ProdTagController` | `prod/prodTag` | 首页/分组展示 | `tz_prod_tag`、`tz_prod_tag_reference` |
|
||||
| 商品评论 | `ProdCommController` | `ProdCommController` | `prod/prodComm` | 商品详情评论 | 评论相关表 |
|
||||
| 搜索 | — | `SearchController` | — | `search-page`、`search-prod-show` | 商品表 |
|
||||
|
||||
品牌 `BrandController`、属性 `AttributeController` 有管理端接口，后台没有独立 `views/modules` 目录。改商品发布时跟 `prod/prodInfo` 和对应 Service，不要假设有单独菜单页。
|
||||
|
||||
文档：`doc/6-核心业务/2-商品与SKU.md`、`doc/7-数据模型/5-商品数据模型.md`。
|
||||
|
||||
## 购物车
|
||||
|
||||
| 项 | 位置 |
|
||||
| --- | --- |
|
||||
| 用户端 | `ShopCartController` |
|
||||
| 表 | `tz_basket`，唯一索引 `uk_user_shop_sku(sku_id, user_id, shop_id)` |
|
||||
| C 端 | mall4m / mall4uni 的 `basket` |
|
||||
| 文档 | `doc/6-核心业务/3-购物车.md` |
|
||||
|
||||
主要接口：`/p/shopCart/info`、`changeItem`、`deleteItem`、`deleteAll`、`prodCount`、`expiryProdList`、`totalPay`。`changeItem` 的 `count` 是增量。
|
||||
|
||||
## 确认订单与提交订单
|
||||
|
||||
| 项 | 位置 |
|
||||
| --- | --- |
|
||||
| 用户端 | `OrderController`（`confirm`、`submit`） |
|
||||
| 监听 | `ConfirmOrderListener`、`SubmitOrderListener` |
|
||||
| 服务 | `OrderServiceImpl`、购物项组装在 `BasketServiceImpl` |
|
||||
| C 端 | `submit-order` |
|
||||
| 表 | `tz_order`、`tz_order_item`、`tz_order_settlement`、`tz_user_addr_order` |
|
||||
| 文档 | `doc/6-核心业务/4-确认订单.md`、`doc/6-核心业务/5-提交订单.md` |
|
||||
|
||||
`OrderParam`：`basketIds` 购物车结算，`orderItem` 立即购买，`addrId` 必填。`couponIds` 为开源版保留参数，不要按已接通优惠券来实现。
|
||||
|
||||
库存扣减：`SkuMapper.xml`、`ProductMapper.xml` 条件更新。
|
||||
|
||||
## 支付
|
||||
|
||||
| 项 | 位置 |
|
||||
| --- | --- |
|
||||
| 下单支付 | `PayController`，`POST /p/order/pay`、`/p/order/normalPay` |
|
||||
| 实现 | `PayServiceImpl` |
|
||||
| 回调 | `PayNoticeController`（逻辑注释中） |
|
||||
| 参数 | `PayParam`：订单号集合 + 支付方式，不含前端金额 |
|
||||
| C 端 | `pay-result` |
|
||||
| 表 | `tz_order_settlement`（`payNo`、`pay_amount`） |
|
||||
| 文档 | `doc/6-核心业务/6-支付流程.md` |
|
||||
|
||||
当前实现会直接 `paySuccess()` 并发布 `PaySuccessOrderEvent`。这是本地跑通，不是生产三方支付。
|
||||
|
||||
## 订单与发货
|
||||
|
||||
| 能力 | 入口 | 页面 |
|
||||
| --- | --- | --- |
|
||||
| 我的订单 / 详情 / 用户侧操作 | `MyOrderController` | `orderList`、`order-detail` |
|
||||
| 后台订单查询 / 详情 / 发货 / 导出 | 管理端 `OrderController` | `order/order` |
|
||||
| 物流查询 | 管理端/用户端 `DeliveryController` | `express-delivery` |
|
||||
| 超时取消、自动确认收货 | `yami-shop-admin/.../task/OrderTask.java` | — |
|
||||
| 状态枚举 | `yami-shop-bean/.../enums/OrderStatus.java` | — |
|
||||
|
||||
文档：`doc/6-核心业务/7-订单管理.md`、`doc/7-数据模型/6-订单数据模型.md`。
|
||||
|
||||
`tz_order_refund`、`OrderRefund`、`OrderRefundMapper` 存在，没有退款 Controller，也没有完整退款页面。不要按已上线退款流程改。
|
||||
|
||||
## 会员与地址
|
||||
|
||||
| 能力 | 管理端 | 用户端 | 后台页 | C 端页 | 表 |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| 会员 | `UserController` | `UserController`、`UserRegisterController` | `user/user` | `user`、`register`、登录页 | `tz_user` |
|
||||
| 地址 | `UserAddrController` | `AddrController` | `user` 相关 | `delivery-address`、`editAddress` | `tz_user_addr` |
|
||||
| 收藏 | — | `UserCollectionController` | — | 用户相关 | `tz_user_collection` |
|
||||
| 短信 | — | `SmsController` | — | 绑定手机等 | — |
|
||||
| 地区 | `AreaController` | `AreaController` | `sys/area` | 地址选择 | 地区表 |
|
||||
|
||||
## 店铺运营
|
||||
|
||||
| 能力 | 管理端 | 用户端 | 后台页 | 表 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 运费模板 | `TransportController` | 确认订单时计算 | `shop/transport` | `tz_transport` |
|
||||
| 自提点 | `PickAddrController` | — | `shop/pickAddr` | `tz_pick_addr` |
|
||||
| 公告 | `NoticeController` | `NoticeController` | `shop/notice` | `tz_notice` |
|
||||
| 热搜 | `HotSearchController` | 搜索相关 | `shop/hotSearch` | `tz_hot_search` |
|
||||
| 轮播 | `IndexImgController` | `IndexImgController` | `admin/indexImg` | `tz_index_img` |
|
||||
| 店铺信息 | `ShopDetailController` | — | 跟店铺配置代码 | `tz_shop_detail` |
|
||||
| 文件上传 | `FileController` | — | 各表单上传 | `tz_attach_file` |
|
||||
| 后台留言 | `MessageController` | — | 仅有 `crud/admin/message.js`，无独立 views 目录 | 跟 `Message` 模型 |
|
||||
|
||||
C 端首页 `index`，公告 `recent-news`、`news-detail`。
|
||||
|
||||
品牌 `BrandController`、属性 `AttributeController` 见商品节；留言接口存在但后台页不完整。改这些能力时先跟现有代码，不要假设有完整菜单页。
|
||||
|
||||
## 权限与系统
|
||||
|
||||
| 能力 | Controller | 后台页 | 表 |
|
||||
| --- | --- | --- | --- |
|
||||
| 管理员 | `SysUserController` | `sys/user` | `tz_sys_user`、`tz_sys_user_role` |
|
||||
| 角色 | `SysRoleController` | `sys/role` | `tz_sys_role`、`tz_sys_role_menu` |
|
||||
| 菜单按钮 | `SysMenuController` | `sys/menu` | `tz_sys_menu` |
|
||||
| 系统日志 | `SysLogController` | `sys/log` | 日志表 |
|
||||
| 系统配置 | `SysConfigController` | `sys/config` | 配置表 |
|
||||
| 管理端登录 | `AdminLoginController` | 登录页 | — |
|
||||
|
||||
权限标识走 `@PreAuthorize("@pms.hasPermission('...')")`。登录后菜单来自 `GET /sys/menu/nav`。文档：`doc/4-技术实现/1-权限体系.md`。
|
||||
|
||||
关系：
|
||||
|
||||
```text
|
||||
tz_sys_user -> tz_sys_user_role -> tz_sys_role -> tz_sys_role_menu -> tz_sys_menu
|
||||
```
|
||||
|
||||
## 部署与排查
|
||||
|
||||
| 场景 | 文档 |
|
||||
| --- | --- |
|
||||
| 选 jar 还是 Docker | `doc/8-部署运维/1-部署路径选择.md` |
|
||||
| 生产配置 | `doc/8-部署运维/3-生产配置.md`（admin / api 两份 `application-prod.yml` 都要改） |
|
||||
| Nginx | `doc/8-部署运维/4-Nginx配置.md` |
|
||||
| 上线自查 | `doc/8-部署运维/6-上线检查题-含答案.md` |
|
||||
| 401 / 验证码 / 端口 | `doc/9-故障排查/1-常见问题.md`、`4-接口地址与401问题.md` |
|
||||
| 启动失败 | `doc/9-故障排查/2-启动失败.md` |
|
||||
| 登录验证码 | `doc/9-故障排查/3-登录与验证码问题.md` |
|
||||
|
||||
当前 `docker-compose.yml` 引用了 `db/Dockerfile`，而 `db/` 只有 SQL，不能直接无脑 `docker compose up`。
|
||||
---
|
||||
@@ -40,6 +40,7 @@ Mall4j 主线已升级到 Spring Boot 4 和 Vue3，适合新项目评估和长
|
||||
- Gitee 文档：[https://gitee.com/gz-yami/mall4j/tree/master/doc](https://gitee.com/gz-yami/mall4j/tree/master/doc)
|
||||
- 看云文档：[https://www.kancloud.cn/yami/mall4j](https://www.kancloud.cn/yami/mall4j)
|
||||
- 开发环境搭建视频：[https://www.bilibili.com/video/BV1eW4y1V7c1](https://www.bilibili.com/video/BV1eW4y1V7c1)
|
||||
- Agent Skill：权威副本 `.agents/skills/mall4j/`（Cursor / Codex）；Claude Code 使用 `.claude/skills/mall4j/`（同一份内容）。按现有功能点辅助启动、使用和二次开发
|
||||
|
||||
建议先阅读文档，再结合视频搭建本地开发环境。
|
||||
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# Mall4j 技术文档
|
||||
|
||||
用 Cursor、Codex 或 Claude Code 打开本仓库时，可使用内置 Skill：`.agents/skills/mall4j/`（Claude Code 为 `.claude/skills/mall4j/`，内容相同）。它按开源版**现有功能点**辅助启动、使用和二次开发，详细说明仍以本 `doc/` 目录为准。
|
||||
|
||||
本文档面向项目维护者和二次开发者，目标是让新接手的人：
|
||||
|
||||
- 30 分钟跑起后端接口、管理后台、MySQL、Redis。
|
||||
|
||||
Reference in New Issue
Block a user