> 本文整理自平台文档 docs/wujies/5.x/plugins/mall.mdx,用于站点内容演示。
(https://console.wujies.cn/remote-apps/cms-assets/doc-228d0fbbad30-cover.svg)
应用编码 mall,本页对应应用版本 1.0.6(引擎要求 >=5.6.2 <6.0.0),商业授权,仓库 [wujies-mall-plugin](https://gitee.com/wujies/wujies-mall-plugin)。
商城管的是「一件东西怎么卖出去、卖完之后怎么办」:商品与 SKU、下单到售后、营销活动与优惠券、商家与统计。它不管四件事,那四件各有归属:支付渠道与支付单归 pay,买家账号与会员中心页面归 member,客服会话归 im,前台那一屏屏 HTML 由 cms 的主题渲染。
装它
清单里声明了三个依赖,要先装齐:member、pay、im。安装顺序与依赖不满足时的提示见 [安装、升级、卸载与启停](/docs/wujies/5.x/platform/app-market/install)。
运行期取兄弟应用的能力走插件 SDK 的定位器(PayServiceLocator、ImServiceLocator)按接口现取,兄弟插件的 bean 直接注不进来;取不到时落到 cn.wujies.mall.fallback 里的降级。这个包 pom.xml 还把那三个兄弟构件声明为 provided,所以自己编译这个仓库前要按 member → pay → im 的顺序各构建安装一次到本地仓库。
装完侧栏多一组「商城管理」,7 个分组、27 个页面、连按钮权限共 176 个菜单节点:
| 分组 | 页面 | 权限码前缀 |
|---|---|---|
| 商城管理(顶层两项) | 商城配置、商城统计总览 | mall:settings,统计总览无权限码 |
| 商品管理 | 商品列表、分类、标签、品牌、SKU、虚拟资产、虚拟资产发放、商品统计 | mall:(前四项)、product:(SKU 与虚拟资产)、statistics:(商品统计) |
| 订单管理 | 订单列表、订单明细、售后申请、订单优惠券 | mall:(前三项)、trade:(订单优惠券) |
| 商家管理 | 商家列表 | merchant: |
| 营销管理 | 营销活动、活动商品明细、活动订单记录 | promotion: |
| 优惠券管理 | 优惠券模板、领券记录、适用范围、使用记录 | coupon: |
| 数据统计 | 商家汇总、商家日统计、平台日统计、平台实时统计、平台分钟快照 | statistics: |
给角色授权时别只勾 mall:*:product:、trade:、merchant:、promotion:、coupon:、statistics: 这六个前缀各管一批页面,漏勾的表现是菜单在、点进去空表。
配它
「商城配置」两个页签写的是 sys_config 里 config_category = 'mall' 的 12 行(种子见迁移脚本 03)。页签本体由宿主的 ModuleWebsiteSettings.vue 与 ModuleBusinessSettings.vue 渲染,按这一类整读整写。
业务配置那一屏现在改了不起作用。mall.orderAutoCancelMinutes、mall.afterSaleDays、mall.minOrderAmount、mall.buyButtonText 这四条只有页面在读回来显示,Java 侧没有任何取值的地方(本插件 src/main/java 里搜不到配置服务)。真正决定行为的是 MallTradeConstants 里的三个常量:
| 时限 | 值 | 生效方式 |
|---|---|---|
| 普通订单支付时限 | 24 小时 | 下单时写进 mall_order.pay_expire_time |
| 活动订单支付时限 | 30 分钟 | 同上 |
| 发货后自动确认收货 | 7 天 | 发货时写进 receive_expire_time |
要改这三个数只能改常量重新打包。到期之后由两个定时任务收口:mallOrderAutoCancelTask 与 mallOrderAutoReceiveTask。它们是 SnailJob 的执行器,没有在 SnailJob 控制台登记并启用就永远不跑,过期订单会一直挂在待支付。本插件一共 13 个这样的任务类(券状态刷新、券到期、活动开始/结束、商家与平台统计等),清单见 src/main/java/cn/wujies/mall/task/。
网站配置那 8 条(mall.logo / mall.name / mall.backgroundImage …)同理没有前台读取方:主题侧的配置读取器只查 config_category = 'cms' 那一类。前台头部、Logo、备案号走的是 CMS 的网站配置,见 [内容与前台页](/docs/wujies/5.x/plugins/cms)。
用它
管理员在「商品管理」里建商品与 SKU、审核上架;「订单管理」里发货、审核退款、处理投诉;商品页与订单页各有一颗按钮权限(mall:goods:self、mall:order:self)决定这个角色是看全平台还是只看自己发的货。商家与统计那两组是给多商家部署用的。
会员在会员中心下单、进收银台、领券、申请售后与投诉,接口一律是 /portal/mall/**,只要登录、不要权限码,返回的都是自己的单。
游客能匿名读目录:/open/mall/** 提供分类、品牌、商家、商品列表/详情/搜索建议,/open/mall/activity 提供活动,都是 @SaIgnore。游客没有下单入口,下单要先登录成会员。
前台六屏是 /site/shop(目录)、/site/shop/home(商店首页)、/site/product/{id}、/site/store/{id}、/site/activity、/site/coupon,代码在本插件的 cn.wujies.mall.site,下面单列一节。这一屏自己的样式在 /site/apps/mall/mall.css,由本插件发出。
前台六屏
页面跟着数据走,主题只提供版式。商城经 SDK 的 SiteRenderApi 向内容中心借壳(头部、尾部、导航、SEO、备案号),主题可以用同名模板覆盖任意一屏。以前这六页写在 CMS 主题里,CMS 回头向商城取数,于是装了 CMS 就必须装商城。
借来的这份能力每次调用现反查。CMS 是兄弟插件,按类型注入拿到的一直是 null,装配期还会让本应用启不来;缓存成字段的话,CMS 换成一代之后这里还指向已经关闭的旧上下文。没装 CMS 时给 404 加一个空响应体:状态码必须是对的,200 会教搜索引擎收录空气,而"这个站点没装内容中心"是内部部署状态,不该讲给访客看。
写这一类页有三条硬要求。挂在 /site/** 下并标 @SaIgnore,宿主的匿名与租户口径都按这个前缀放行,租户不对时查出来永远是默认租户的商品。produces 写 text/html;charset=UTF-8 且方法返回 String,插件子上下文里没有 ViewResolver,少了 charset 中文页面会花成问号。状态码写进 response 再返回 HTML,不抛"不存在",抛出去会撞上宿主的全局异常处理器,访客和搜索引擎收到的是一段 JSON。
路径与查询参数一律收 String 再自己解析。签名写成 Long 或 BigDecimal,访客手滑改一个数字就先撞上 Spring 的类型转换,浏览器拿到的还是那段 JSON。
商品与店铺访问不到时出同一份 404。区分"存在但你看不见"本身就是信息,分享出去的链接会把未审核的内容公开出来。
目录页、活动页、领券页的筛选条件都走 query,不放进路径段,几个条件是正交的。带任一条件时 noindex,canonical 恒为本页地址。左栏每一条链接都原样带着其余几个条件,点了分类却把搜索词丢掉,用户会以为是筛选没生效。
取数用本插件自己的三个契约实现,按类型直接注入,它们注册在同一个子上下文里。口径与 /open/mall/** 同一套:在售、审核通过、状态正常、分类含子分类,不会出现列表里有而这一页没有。查询失败时按空数据出页并留一行 ERROR,访客不该看到堆栈,运维必须看到。
前台没有加购按钮,也没有购物车页。购物车是 C 端 SPA 存在 localStorage 里的本地状态,服务端渲染的公开页读不到也写不进。卡片上的两个动作是「看详情」与「去下单」,后者进单品结算页。
领券中心只列券。「立即领取」出站去后台会员中心的 /member/coupon,领取要写 mall_coupon_user,匿名请求没有可写的身份。店铺页的「联系客服」同理只在已登录时才显形,点了先 POST /site/store/{id}/contact 把会话建起来,再打开会员中心的即时通讯页。
这一屏自己的样式与图片由 MallSiteAssetController 从 /site/apps/mall/** 发出,内容中心代发不了:插件各有各的类加载器,主题那个资源端点只按它自己的加载器取文件,读不到本插件 jar 里的东西。谁的文件谁发。取数走 classpath 资源,三条约束都要留着:应用编码写死在常量里,拒绝 .. 与前导斜杠(ClassPathResource 会先做规范化,必须赶在它之前挡掉),扩展名走白名单。缓存只给 5 分钟,
本文导览
(https://console.wujies.cn/remote-apps/cms-assets/doc-228d0fbbad30-guide.svg)


评论区需要浏览器启用 JavaScript 才能加载。