diff --git a/.agents/skills/mall4j/SKILL.md b/.agents/skills/mall4j/SKILL.md new file mode 100644 index 00000000..8844b15a --- /dev/null +++ b/.agents/skills/mall4j/SKILL.md @@ -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//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/` 全文贴进回答。 +--- diff --git a/.agents/skills/mall4j/references/feature-map.md b/.agents/skills/mall4j/references/feature-map.md new file mode 100644 index 00000000..19f7d092 --- /dev/null +++ b/.agents/skills/mall4j/references/feature-map.md @@ -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`。 +--- diff --git a/.claude/skills/mall4j/SKILL.md b/.claude/skills/mall4j/SKILL.md new file mode 100644 index 00000000..8844b15a --- /dev/null +++ b/.claude/skills/mall4j/SKILL.md @@ -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//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/` 全文贴进回答。 +--- diff --git a/.claude/skills/mall4j/references/feature-map.md b/.claude/skills/mall4j/references/feature-map.md new file mode 100644 index 00000000..19f7d092 --- /dev/null +++ b/.claude/skills/mall4j/references/feature-map.md @@ -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`。 +--- diff --git a/README.md b/README.md index 8c669e80..02b0d284 100644 --- a/README.md +++ b/README.md @@ -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/`（同一份内容）。按现有功能点辅助启动、使用和二次开发 建议先阅读文档，再结合视频搭建本地开发环境。 diff --git a/doc/README.md b/doc/README.md index 4e5c345c..c8cd2891 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1,5 +1,7 @@ # Mall4j 技术文档 +用 Cursor、Codex 或 Claude Code 打开本仓库时，可使用内置 Skill：`.agents/skills/mall4j/`（Claude Code 为 `.claude/skills/mall4j/`，内容相同）。它按开源版**现有功能点**辅助启动、使用和二次开发，详细说明仍以本 `doc/` 目录为准。 + 本文档面向项目维护者和二次开发者，目标是让新接手的人： - 30 分钟跑起后端接口、管理后台、MySQL、Redis。