Wujies 无界平台
应用

商城管理(mall)

装商城前要备齐哪三个应用、订单时限到底由谁决定,以及前台页打不开时查哪。

应用编码 mall,本页对应应用版本 1.0.6(引擎要求 >=5.6.2 <6.0.0),商业授权,仓库 wujies-mall-plugin。

商城管的是「一件东西怎么卖出去、卖完之后怎么办」:商品与 SKU、下单到售后、营销活动与优惠券、商家与统计。它不管四件事,那四件各有归属:支付渠道与支付单归 pay,买家账号与会员中心页面归 member,客服会话归 im,前台那一屏屏 HTML 由 cms 的主题渲染。

装它

清单里声明了三个依赖,要先装齐:member、pay、im。安装顺序与依赖不满足时的提示见 安装、升级、卸载与启停。

运行期取兄弟应用的能力走插件 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 的网站配置,见 内容与前台页。

用它

管理员在「商品管理」里建商品与 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 分钟,链接上没有真正的版本号,长缓存会把旧样式钉在访客浏览器里。

POST /site/store/{merchantId}/contact 单独说一段。它挂在 /site/** 匿名族上,C 端那条 /portal/mall/merchant/{id}/contact 走不了:宿主的登录校验除了看有没有登录还要比 clientid,那是管理端构建期注入的常量,服务端直出的公开页读不到也不该读。认人这一步由方法自己做,先 LoginHelper.isLogin() 再取 getUserId(),顺序不能反,后者只解 JWT 载荷,已注销的旧 token 照样读得出 id。它往 im_friend、im_conversation 各写行,所以是 POST:做成 GET,别的站点上一张 <img> 就能替访客联系商家。这条路径不校验 clientid,任何一枚有效 token 都能按这颗按钮,代价是会话列表里各多一行,读不到东西也不碰钱,比 /portal 少一道闸是已知代价。

活动卡的价格口径直接复用普通商品卡,契约里的 product.price 已经是活动价。进行中的卡详情链接出站:站内 /site/product/{id} 读目录契约,不认识活动,会把活动商品按原价印出来。「去下单」必须带上 activityId 与 activitySkuId 这两个 query,结算页按它们找活动价提交,不带就按原价结算。历史档只印商品名、活动名和结束时间,那条活动价已经拍不到了。库存那句是 activityStock - lockedStock,锁定的是下单未付款占住的量,随时可能回来但此刻确实拍不到。

券卡的「未开始」由 status = 1 且开始时间真的还没到两个条件一起判。商城的状态位靠定时任务翻,任务之间的空窗里 status 还写着未开始而 startTime 已经过了。C 端看不到这个空窗,它的列表接口在查询前先调一次刷新,那是一条 UPDATE。匿名公开页不能跟着学,所以这里复现刷新之后的结果,空窗期内直接算可领。券卡也没有「已领完」这一档:剩余几张只是一行字,C 端那颗按钮在剩 0 张时照样能点,由提交那一刻的服务端拒绝。把它做成禁用的状态会出现主题说领完、SPA 说还能领的分歧,谁对取决于那一瞬间有没有人正在领。剩余张数两个数任缺其一就不印,couponStock 为空时算出来是剩余 0 张,那是把没填读成领光了。

店铺页只印库里真有的字段:评分 ratingScore 与平台推荐那枚徽章。C 端那四个「综合体验 / 商品质量 / 物流速度 / 售后服务」是客户端拿固定系数现算的,库里没有这四列,粉丝数同样算出来。页面标题恒取 merchantName,不取店主的真实姓名,那是隐私问题。站内地址由模板调 asset.xxxUrl() 拼,数据包装类只出字。

出问题查什么

现象先看
前台 /site/shop 打不开、后台一切正常是否装了 cms,这六屏是它渲染的
商品卡点进去 404商品地址在两处各拼一份(见下方实现索引),两边路径不一致
下单报支付相关错误pay 是否启用、收银台要的支付应用与渠道是否配了
店铺页「联系客服」按了没反应im 是否启用;cms.consoleUrl 没配时模板直接不渲染这一块
过期订单一直不自动取消SnailJob 里那两个执行器有没有登记、有没有启用
改了业务配置里的数字没变化那四条目前没有读取方,见「配它」
装完侧栏没有「商城管理」菜单树在登录时生成,重建入口见 在部署里使用应用

实现索引

项值
数据表(24 张,卸载时的删除依据)mall_product、mall_sku、mall_category、mall_tag、mall_brand、mall_virtual_asset、mall_virtual_asset_delivery、mall_order、mall_order_item、mall_order_coupon、mall_after_sale、mall_merchant、mall_merchant_stats、mall_merchant_stats_daily、mall_platform_stats_realtime、mall_platform_stats_realtime_log、mall_platform_stats_daily、mall_promotion_activity、mall_promotion_activity_sku、mall_promotion_order_record、mall_coupon、mall_coupon_scope、mall_coupon_user、mall_coupon_order
后台接口/mall/product、/mall/category、/mall/tag、/mall/brand、/product/sku、/product/virtualAsset*、/mall/order*、/mall/afterSale、/mall/trade/orderCoupon、/mall/merchant、/mall/promotion/*、/mall/coupon/*、/mall/statistics/*
会员端/portal/mall/**(19 条,@SaCheckLogin)
公开端/open/mall/**、/open/mall/activity/**(@SaIgnore,只读)
前台页MallSiteController 挂在 /site,六屏见「用它」;MallSiteContactController 出 POST /site/store/{merchantId}/contact
自带静态资源/site/apps/mall/**,由 MallSiteAssetController 发出
定时任务src/main/java/cn/wujies/mall/task/ 下 13 个 @JobExecutor
消息消费ProductViewCountSyncConsumer(商品浏览量异步汇总)
迁移脚本01-create-mall-tables.sql(24 表)、02-create-mall-dictionaries.sql(11 个字典类型)、03-create-mall-website-config.sql(12 条配置)、04-create-mall-seed-data.sql(示例品牌/分类/商家/商品/SKU/标签/虚拟资产,全部 INSERT IGNORE)
前台地址契约本插件 cn.wujies.mall.site.MallSiteLinks 与 CMS 的 CmsThemeProperties 各拼一份同样的 URL。这是刻意重复:CMS 不该为了拼一条链就依赖本插件的类。改路径必须两边一起改,漏一边不会编译失败,只会安静地链到 404
源码cn/wujies/mall

相关

目录