# 素屿 SUYU · 美妆香氛 B2C 商城 > **CNB 仓库 `meizhuangshangcheng`(RDPL-44)**:平台测试域的 `.multica/deploy.json` 仍为引导态;**正式交付请使用 `deploy/docker-compose`**(MySQL + API + Nginx:H5 `/`、管理端 `/admin/`)。微信小程序由业务方单独发布。 自营美妆 / 香氛品牌商城的完整实现:**Java 后端 + MySQL + C 端(H5 与微信小程序同一套代码)+ PC 管理后台**。 品牌名、商品与图片均为原创演示数据,可在后台整体替换。 | 目录 | 说明 | 技术 | | --- | --- | --- | | `mall-server/` | 服务端(C 端接口 `/api/app/**` + 后台接口 `/api/admin/**` + 支付回调) | Java 17 · Spring Boot 3.3 · MyBatis-Plus · MySQL 8 · 微信支付 APIv3 官方 SDK | | `mall-app/` | C 端商城,一套代码编译为 **H5** 与 **微信小程序** | uni-app (Vue 3 + Vite) · Pinia | | `mall-admin/` | PC 管理后台 | Vue 3 · Vite · Element Plus · ECharts · wangEditor | | `deploy/` | Docker Compose 一键部署(MySQL + 后端 + Nginx) | | | `tools/` | 实体生成脚本、演示图片生成脚本、接口端到端测试 | | 数据库结构见 `mall-server/src/main/resources/db/schema.sql`(28 张表,含完整字段注释)。后端启动时自动建表并初始化基础数据,无需手工导入。 --- ## 一、功能清单 ### C 端(H5 + 小程序) - **首页**:全屏主视觉轮播、公告、活动轮播、分类入口、新品 / 热销 / 推荐(全部由后台配置) - **全部商品 / 分类 / 搜索**:综合、销量、价格、新品排序;左侧分类 + 右侧分类横幅与商品;热搜词与搜索历史 - **商品详情**:轮播图、价格区间、促销标签与优惠弹层(满减 / 满赠 / 可领优惠券)、服务说明、多规格 SKU 选择(规格图)、**定制刻字**、**商品留言(如祝福语)**、限购提示、图文详情、评价、收藏、分享、客服 - **购物车**:勾选、改数量、换规格、失效商品、满减 / 满赠凑单提示、赠品展示、优惠明细、推荐商品 - **下单结算**:收货地址、自动选择最优优惠券(可手动切换 / 不使用)、积分抵扣、会员折扣、运费(满额包邮 / 偏远地区 / 不配送区域)、买家留言 - **支付**:微信支付(小程序 JSAPI、微信内 H5 JSAPI、手机浏览器 H5 支付、PC 扫码 Native)、余额支付、支付结果轮询;提供**模拟支付**模式用于联调 - **订单**:列表(搜索 + 状态页签)、详情、取消、去支付、物流单号、确认收货、评价(晒图 / 匿名)、删除、再次购买 - **售后**:按商品申请仅退款 / 退货退款、凭证上传、撤销、填写退货物流、进度查看,退款原路返回 - **会员**:小程序静默登录 + 头像昵称 + 手机号绑定;H5 短信验证码 / 密码登录;会员等级与成长值、积分与流水、余额充值与流水、领券中心与我的优惠券、收藏、收货地址(微信地址导入、省市区选择、智能识别)、账号与安全、协议 ### 管理后台 - **数据看板**:今日 / 昨日经营指标、待办事项、7 / 30 天趋势、热销商品 - **商品**:商品(多规格 SKU 矩阵、图片、富文本详情、定制 / 留言 / 限购 / 运费模板 / 赠品)、分类、评价回复与显隐、库存快速修改与库存预警 - **交易**:订单列表与详情、发货 / 改物流、改价、取消、改收货信息、备注、导出 CSV;售后审核、确认收货并退款 - **会员**:会员列表与详情、禁用、调整积分 / 余额、定向发券、会员等级与折扣 - **营销**:优惠券(满减 / 折扣、全场 / 分类 / 商品、固定期 / 领取后 N 天、新人券)、满减、满赠 - **内容**:首页主视觉 / 轮播 / 广告位、公告、协议、帮助 - **设置**:店铺信息、交易参数(自动取消 / 自动收货 / 售后期)、积分规则、充值档位、运费模板、快递公司 - **系统**:管理员、角色权限、操作日志 --- ## 二、快速开始 ### 方式 A:Docker Compose ```bash cd deploy cp .env.example .env # 至少修改数据库密码与 MALL_JWT_SECRET docker compose up -d --build ``` - H5 商城:`http://服务器IP/` - 管理后台:`http://服务器IP/admin/`,默认账号 **admin / admin123**(登录后请立即修改密码) - 默认是联调模式:`PAY_MOCK=true`(模拟支付)、`WX_MOCK_LOGIN=true`、短信验证码随接口返回,不需要任何微信资质即可走完下单 → 支付 → 发货 → 收货 → 评价 → 售后全流程。 ### 方式 B:本地开发 ```bash # 1) 数据库(MySQL 8 / MariaDB 10.6+) mysql -uroot -p -e "CREATE DATABASE mall DEFAULT CHARSET utf8mb4; CREATE USER 'mall'@'%' IDENTIFIED BY 'mall123456'; GRANT ALL ON mall.* TO 'mall'@'%';" # 2) 后端(JDK 17 + Maven),默认 8080 端口 cd mall-server && mvn -DskipTests package && java -jar target/mall-server.jar # 3) 管理后台 http://localhost:5173/admin/ cd mall-admin && npm i && npm run dev # 4) H5 商城 http://localhost:5174/ cd mall-app && npm i && npm run dev:h5 # 5) 微信小程序:构建后用微信开发者工具导入 mall-app/dist/dev/mp-weixin cd mall-app && npm run dev:mp-weixin ``` 接口冒烟测试(需全新演示库 + 模拟支付模式):`python3 tools/e2e_test.py http://127.0.0.1:8080` --- ## 三、上线配置清单 联调模式下所有外部依赖都是模拟的。正式上线前按下表逐项配置(环境变量见 `deploy/.env.example`,对应 `application.yml` 的 `mall.*`): | 事项 | 需要准备 | 配置 | | --- | --- | --- | | HTTPS 域名 | 已备案域名 + 证书(小程序、微信支付回调强制 HTTPS) | 在 Nginx 或云负载均衡上配置证书 | | 小程序登录 | 小程序 AppID / AppSecret | `WX_MOCK_LOGIN=false`、`WX_MP_APP_ID`、`WX_MP_SECRET`;`mall-app/src/manifest.json` 的 `mp-weixin.appid`;`mall-app/.env.production` 的 `VITE_API_BASE`;小程序后台添加 request / uploadFile / downloadFile 合法域名 | | 微信支付 | 商户号、API 证书(`apiclient_key.pem` + 证书序列号)、APIv3 密钥;商户号需与小程序(及服务号)AppID 绑定 | `PAY_MOCK=false`、`WX_MCH_ID`、`WX_MCH_SERIAL_NO`、`WX_API_V3_KEY`,私钥放 `deploy/cert/`;`PAY_NOTIFY_BASE_URL=https://你的域名`。新商户若为「微信支付公钥」模式,再填 `WX_PAY_PUBLIC_KEY_ID` 并放入 `pub_key.pem` | | H5 内微信支付 | 服务号 AppID / Secret(微信内打开 H5 用 JSAPI)、商户平台开通 H5 支付并配置 H5 域名(手机浏览器)、开通 Native(PC 扫码) | `WX_OA_APP_ID`、`WX_OA_SECRET`、`PAY_H5_RETURN_URL`;服务号后台配置网页授权域名与 JSAPI 支付目录 | | 短信验证码 | 阿里云 / 腾讯云短信签名与模板 | 目前只内置 `log` 通道(验证码打印在日志)。在 `SmsService.send()` 中接入所选厂商 SDK,并设置 `SMS_PROVIDER`、`SMS_EXPOSE_CODE=false` | | 安全项 | — | 修改 `MALL_JWT_SECRET`、数据库密码、后台 admin 密码;`SMS_EXPOSE_CODE=false` | | 内容替换 | 品牌素材 | 后台替换店铺名称 / LOGO、轮播图、商品、协议文本;正式开店可设 `MALL_INIT_DEMO_DATA=false` 不导入演示商品 | --- ## 四、关键设计 - **金额计算一处实现**(`TradeCalcService`):购物车预览、结算页、下单共用同一套规则 —— 商品总额 → 会员折扣 → 满减 / 满赠 → 优惠券 → 积分抵扣 → 运费 → 应付;并把实付分摊到每个商品行,作为售后可退上限。 - **库存与并发**:下单时用带库存条件的 `UPDATE`(库存足够才扣减)原子扣库存,不会超卖;取消 / 退款回补。优惠券领取、订单状态流转、支付回调、退款回调都用「带状态条件的更新」保证幂等。 - **支付可靠性**:支付单(`trade_pay`)与业务单分离,支持订单支付与余额充值;回调验签解密;前端轮询与定时任务主动查单兜底回调丢失;取消订单前先向微信查单并关单;订单已取消后才到账的支付自动原路退款。 - **定时任务**(`TradeTask`):超时未支付自动取消、发货后 N 天自动收货、支付 / 退款对账、优惠券过期。 - **权限**:后台 JWT + 角色权限标识(`@Perm`),写操作记录操作日志;C 端 JWT,`@MemberLogin` 标注需登录接口。 - **性能定位**:单体应用 + MySQL,Tomcat 200 线程、连接池 20,列表查询不取详情大字段、常用查询均有索引;面向日均万级访问的小型站点,单台 2C4G 即可运行。当前未引入 Redis,短信验证码、配置缓存放在本地内存,定时任务未加分布式锁 —— **按单实例部署设计**,如需多实例横向扩展需把这三处改为 Redis / 分布式锁。 - **文件存储**:上传图片存本地磁盘(Docker 卷),由后端 `/uploads/**` 提供访问;需要对象存储 / CDN 时替换 `FileService` 并设置 `MALL_UPLOAD_URL_PREFIX`。 - **表结构变更**:改 `schema.sql` 后执行 `python3 tools/gen_entity.py` 重新生成实体与 Mapper。启动时只执行 `CREATE TABLE IF NOT EXISTS`,已有库的加字段需自行执行 `ALTER TABLE`。 --- ## 五、验证情况 已在本地完成的验证(后端为模拟支付 / 模拟微信登录模式): - 后端接口端到端测试 `tools/e2e_test.py`:**62 项全部通过**,覆盖登录、浏览、购物车、满减 / 满赠、优惠券、运费、下单扣库存、支付幂等、发货、收货赠积分与升级、评价、退货退款、未发货整单退款(余额 / 积分 / 库存回滚)、取消订单、限购、改价、充值赠送、后台商品 CRUD、角色权限。 - H5 商城:生产构建经 Nginx 部署后,用无头浏览器跑通 27 步购物旅程(登录 → 选规格刻字 → 加购 → 新增地址 → 用券结算 → 模拟支付 → 订单 → 售后 → 充值 → 余额支付 → 收货 → 评价 → 退货退款等),截图见 `mall-app/screenshots/`。 - 管理后台:生产构建下全部菜单页面巡检无报错;商品、分类、优惠券、活动、轮播、文章、运费模板、角色、管理员、订单发货 / 改价 / 取消、售后审核等写流程均通过浏览器实测,截图见 `mall-admin/screenshots/`。 - 微信小程序:`npm run build:mp-weixin` 构建通过(包体约 1 MB)。 **尚未验证、需要在真实环境完成的部分:** - 小程序在微信开发者工具 / 真机上的运行(开发环境没有微信开发者工具,只验证了编译通过):`wx.login`、头像昵称、手机号、微信地址、`requestPayment`、客服、分享等原生能力的代码已按官方接口实现,但未实际执行过。 - 真实微信支付链路(JSAPI / H5 / Native 下单、支付回调、退款与退款回调):代码基于官方 `wechatpay-java` SDK 编写并编译通过,但没有商户资质,未与微信服务器实际联调。 - Docker Compose 一键部署:开发环境没有 Docker,`Dockerfile` / `docker-compose.yml` 未实际构建运行过;其中的 Nginx 配置已单独用本机 Nginx 验证可用。数据库实测使用的是 MariaDB 10.11(与 MySQL 8 语法兼容的部分),未在 MySQL 8 上实跑。 - H5 上的图片上传(头像、评价晒图、售后凭证)、密码登录 / 设置密码 / 换绑手机、积分抵扣开关等页面未做浏览器自动化操作;对应后端接口中积分抵扣已由接口测试覆盖。 ## 六、已知限制 - 短信只有日志通道,需自行接入短信厂商。 - 物流只记录快递公司与单号(可复制),未接入物流轨迹查询接口。 - 分类为一级分类;满减 / 满赠为全场活动(不支持指定商品范围),可与优惠券叠加。 - H5 省市区数据来自 `@vant/area-data`,个别区划可能缺失,可在 `mall-app/src/utils/area.js` 中补充(已补重庆江北区、渝北区)。 - 首页版式固定(主视觉 / 公告 / 轮播 / 分类 / 商品分组),内容可配但不支持拖拽式装修。 - uni-app 依赖使用的是当前 `vue3` 发布通道的版本(alpha 通道),如需更稳妥可在 `mall-app/package.json` 中统一换成 DCloud 的正式版号后重新构建验证。