mall 电商系统 - 开发上下文

版本：v3.0 ｜最后更新：2026-07 ｜文档状态：持续更新

本文档供 AI 开发者快速了解项目状态，每次迭代后需同步更新。新会话开始任务前请先阅读此文件。

1. 当前开发阶段

阶段	状态	说明
Phase 1-1 后台权限系统	✅ 已完成	登录/验证码/管理员/角色/菜单/资源/仪表盘
Phase 1-2 后台商品管理	✅ 已完成	分类/品牌/属性/单规格商品/运费模板
Phase 1-3 后台订单管理	✅ 已完成	订单列表/详情/发货/退货审核/操作日志
Phase 1-4 前台用户系统	✅ 已完成	注册/登录/个人信息/收货地址
Phase 1-5 前台购物	✅ 已完成	首页/搜索/详情/购物车/下单/支付/售后
前端重构	✅ 已完成	后台管理全站 shadcn/ui 风格重写
Phase 2-1 多规格商品	✅ 已完成	SPU/SKU 模型、规格选择器、SKU 价格/库存联动
Phase 2-2 促销活动	✅ 已完成	秒杀活动、优惠券、满减促销（后端+前端）
Phase 2-3 内容管理	✅ 已完成	专题管理、优选专区、话题管理（后端CRUD+前端页面）
Phase 2-4 会员体系	✅ 已完成	后台会员管理、会员等级、积分/成长值、自动升降级
Phase 2-5 前台增强	✅ 已完成	商品评论（后端+前端）、收藏/浏览历史、会员中心增强

2. 项目概况

项目名：mall 电商系统
定位：B2C 电商平台（单商户模式）
代码路径：D:\workspace\PM\Project\mall\

技术栈

层	技术
后端	Spring Boot 3.5.14 + JDK 17 + MyBatis + Spring Security (JWT)
前端（后台）	Vue 3 + TypeScript + Element Plus + Pinia + Vite 7 + TailwindCSS
数据库	MySQL 8.0 (root/123456, 库名 mall)
缓存	Redis (localhost:6379)
其他	PageHelper 分页, Druid 连接池, Hutool, SpringDoc OpenAPI

模块结构

mall (父 POM)
├── mall-common      → 工具类及通用代码
├── mall-mbg         → MyBatis Generator DAO 代码（全表映射，数量见第 3.1 节）
├── mall-security    → Spring Security 封装（JWT + 动态权限）
├── mall-admin       → 后台管理系统 API (端口 8080) ✅ 主要开发
├── mall-admin-web   → 后台管理前端 (端口 5173) ✅ shadcn/ui 风格
├── mall-portal      → 前台商城系统 API (端口 8085)
└── mall-search      → Elasticsearch 搜索（待配置 ES 服务）

依赖顺序

mall-common → mall-mbg → mall-security → mall-admin / mall-portal / mall-search

3. 需求文档索引

文档	路径	内容
PRD 索引	`docs/prd/index.md`	19 份模块 PRD 入口文档
API 接口规范	`docs/prd/mall_api_spec.md`	统一接口规范
数据字典	`docs/prd/mall_data_dictionary.md`	核心数据模型（业务实体与关联关系，不含字段级内容）

3.1 关键数字（单一来源）

本节是表数量、页面数、阶段状态的唯一权威来源。其他文档请引用本节，不要各自复述数字（历史上「73 张表」被复制到 11+ 处，改一次漏十处）。

指标	数值	校验方式
MySQL 表数量	75	`grep -c '^CREATE TABLE' docs/sql/mall.sql`（cms 12 / oms 8 / pms 18 / sms 13 / ums 24）
前台（Portal）页面路由	20（公开 8 + 需登录 12）	`mall-admin-web/src/router/index.ts` 的 `portalRouterMap`
后台管理页面路由	55（另有常量路由 4）	同上，`asyncRouterMap`
Vue 页面文件（`views/`）	98	`glob mall-admin-web/src/views/*/.vue`
后端 Controller	56（admin 39 / portal 16 / search 1）	`grep -rn 'class .*Controller'`
前端 API 文件	38	`glob mall-admin-web/src/apis/*.ts`
`el-table` 带 `border` 残留	0（原 21 处已全部清理）	约定：`el-table` 一律不加 `border`
未迁移 `el-card shadow="never"`	7 文件	待清理

4. 开发规范

通用规则

数据库：使用 docs/sql/mall.sql，不新增表
验收条件：每个模块末尾有 AC-xxx 格式验收标准
权限：新增 API 需注册到资源管理，新增页面需注册到菜单管理
日志：所有订单操作必须写 oms_order_operate_history

后端约定

Controller 路径：
- mall-admin 统一使用 /api/ 前缀，如 @RequestMapping("/api/order")
- mall-portal 会员接口使用 /member/（注册/登录/改密/地址/收藏/浏览历史/优惠券/关注/举报），地址为 /member/address/
分页：使用 PageHelper.startPage(pageNum, pageSize)，Example 类无 setLimit
参数格式：统一使用 @RequestBody JSON Body（不用 @RequestParam）
安全白名单：在 application.yml 的 secure.ignored.urls 中配置
操作日志：发货日志格式 "发货：{物流公司}，运单号：{运单号}"
获取当前用户：
- 后台管理员：SecurityContextHolder.getContext().getAuthentication().getName()
- 前台会员：memberService.getCurrentMember()

前端约定

页面风格：全站 shadcn/ui 风格，使用 PageCard 组件
列表页模式：筛选搜索 → 数据列表，分页在 PageCard 内部
表格：el-table 不加 border，操作按钮用 type="primary" link
通用组件：PageCard、PageHeader、ProductCard（前台商品卡片）、useTableList<T, Q> composable
API 文件：src/apis/*.ts，路径带 /api/ 前缀
类型定义：src/types/*.ts
Vite 代理：
- /api → http://localhost:8080（后台管理）
- /papi → http://localhost:8085（前台商城，rewrite 去掉 /papi 前缀）
- /member → http://localhost:8085（会员接口）
Element Plus：
- 对话框用 v-model（不是 v-model:visible）
- el-radio 使用 :value 而非 :label

5. 已完成模块关键改动

Phase 1-1 后台权限系统

JWT Token 认证（7天有效期）
图形验证码（Hutool LineCaptcha + Redis，5分钟过期）
账号锁定（连续5次失败锁定30分钟）
RBAC 权限模型 + 动态权限控制
所有 Controller 路径统一为 /api/ 前缀

Phase 1-2 后台商品管理

商品分类树（三级限制 level 0/1/2）
品牌管理（删除保护：有商品关联时拒绝）
属性/属性值管理
单规格商品 CRUD
运费模板 CRUD
分类删除保护：有子分类或有商品关联时拒绝

Phase 1-3 后台订单管理

订单列表：日期范围搜索（createTimeStart/createTimeEnd）
订单列表：商品信息列（图片+数量，SQL 子查询扩展字段）
发货操作：日志记录物流公司+运单号+当前管理员用户名
退货申请：审核流程（待处理→退货中→已完成/已拒绝）
Bug 修复：deliverySn 错误使用 orderSn、v-model:visible → v-model
物流公司：8家预置（顺丰速运/圆通速递/中通快递/韵达快递/申通快递/邮政EMS/京东快递/极兔速递）

Phase 1-4 前台用户系统

注册：POST /member/register，JSON Body，自动设置昵称=用户名、积分=0
登录：POST /member/login，支持用户名或手机号
用户信息：GET /member/info、POST /member/update（昵称/头像）
收货地址：/member/address/（list/create/update/delete）
地址上限：每用户最多 10 个
默认地址：设置时自动取消其他默认，删除时自动选取最近创建的为默认
字段映射：请求 phone → 模型 phoneNumber
安全白名单：/member/register、/member/login、/member/getAuthCode 无需登录

Phase 1-5 前台购物

后端 5 个 Controller 路径统一加 /api/ 前缀
新增端点：listByCategory（按分类获取商品）、check（购物车选中切换）、returnApply/list（售后列表）
OmsCartItem 增加 selected 字段（内存级选中状态，ConcurrentHashMap 存储）
安全白名单更新：/home/** → /api/home/**，/product/** → /api/product/**
地址 Controller 路径：/api/member/address → /member/address（与会员接口统一）
前端新增 Portal 模块：PortalLayout + 20 个页面路由（公开 8：首页/注册/分类/搜索/商品详情/品牌/专题/帮助；需登录 12：购物车/确认订单/支付/订单列表/订单详情/售后/个人中心/地址/改密/收藏/浏览历史/优惠券）
前台代理方案：/papi/ rewrite 到 portal 后端，解决 admin/portal 路径冲突
会员 token 独立存储：portalHttp.ts 使用 localStorage('portal_token')
模拟支付：直接调用 /api/order/paySuccess

Phase 2-1 多规格商品

SPU/SKU 模型：pms_product + pms_sku_stock 表关联
后台商品编辑：支持多规格属性配置、SKU 价格/库存/图片批量设置
前台商品详情：SKU 规格选择器（属性名匹配、可选值集合、库存联动）
价格区间展示：未完全选择时显示最低价~最高价
购物车多规格兼容：productSkuId 关联 SKU 记录

Phase 2-2 促销活动

秒杀：sms_flash_promotion + sms_flash_promotion_session + sms_flash_promotion_product_relation，后台场次/商品管理，前台秒杀专区
优惠券：sms_coupon + sms_coupon_history，后台 CRUD + 领取/使用流程，前台结算页优惠券选择
满减：pms_full_reduction，商品关联满减促销

Phase 2-3 内容管理

专题管理：cms_subject CRUD（后台+前端页面）
优选专区：cms_preference_area CRUD（后台+前端页面）
话题管理：cms_topic CRUD（后台+前端页面）

Phase 2-4 会员体系

后台会员管理：会员列表/搜索/状态管理、积分/成长值调整
会员等级：ums_member_level 等级配置、成长值阈值
自动升降级：下单赠送成长值 → updateGrowth → checkAndUpdateMemberLevel 自动匹配等级
积分变动记录：ums_integration_change_history

Phase 2-5 前台增强

商品评论：PmsProductCommentController（/api/product/comment/list、/replayList/{commentId}），支持 type 筛选（全部/有图/好评/中评/差评）
评论前端：商品详情页评论 Tab（统计区、筛选标签、评论列表、商家回复展开）
收藏功能：MemberProductCollectionController（MongoDB），前台收藏/取消收藏按钮
浏览历史：MemberReadHistoryController（MongoDB），商品详情页自动记录，按日期分组展示
会员中心增强：成长值展示、收藏/浏览历史入口

前端重构

布局重构：Layout.vue 重构为 shadcn 风格，侧边栏/导航栏/主内容区统一 CSS 变量
TagsView：新增多标签页导航组件，支持关闭/刷新/右键菜单
通用组件：
- PageCard — 替代旧式 el-card shadow="never"，支持标题和 header 插槽
- PageHeader — 页面标题组件
- useTableList<T, Q> — 列表页通用 composable（分页/加载/搜索/重置）
全站页面重写：
- 登录/仪表盘页面优化
- UMS 模块：管理员、角色、菜单、资源（含分类列表）、分配菜单、分配资源
- PMS 模块：商品列表、商品新增/编辑（含属性/规格/关联子组件）、分类、品牌、属性、运费模板
- OMS 模块：订单列表、订单详情、发货列表、退货申请、退货详情、订单设置
- SMS 模块：广告、品牌推荐、新品推荐、人气推荐、专题推荐、优惠券（含历史/详情）、秒杀（含场次/商品）
代码规范：
- 所有 el-card shadow="never" 替换为 PageCard
- 所有 el-table border 移除
- 所有 el-radio :label 改为 :value
- 统一分页样式 .pagination-container 右对齐
- TypeScript 编译和 Vite 构建均无错误

6. 关键文件索引

后端 - mall-admin

模块	Controller	Service	DAO/XML
订单	`OmsOrderController`	`OmsOrderServiceImpl`	`OmsOrderDao.xml`
退货	`OmsOrderReturnApplyController`	`OmsOrderReturnApplyServiceImpl`	-
商品	`PmsProductController`	`PmsProductServiceImpl`	-
分类	`PmsProductCategoryController`	-	-

后端 - mall-portal

模块	Controller	Service
会员	`UmsMemberController` (/member/)	`UmsMemberServiceImpl`
地址	`UmsMemberReceiveAddressController` (/member/address/)	`UmsMemberReceiveAddressServiceImpl`
首页	`HomeController` (/api/home/)	`HomeServiceImpl`
商品	`PmsPortalProductController` (/api/product/)	`PmsPortalProductServiceImpl`
购物车	`OmsCartItemController` (/api/cart/)	`OmsCartItemServiceImpl`
订单	`OmsPortalOrderController` (/api/order/)	`OmsPortalOrderServiceImpl`
售后	`OmsPortalOrderReturnApplyController` (/api/returnApply/)	`OmsPortalOrderReturnApplyServiceImpl`
评论	`PmsProductCommentController` (/api/product/comment/)	`PmsProductCommentServiceImpl`
收藏	`MemberProductCollectionController` (/member/productCollection/，无 /api 前缀)	MongoDB
浏览历史	`MemberReadHistoryController` (/member/readHistory/，无 /api 前缀)	MongoDB
支付宝（未接线）	`AlipayController` (/alipay/，凭据为占位符)	`AlipayServiceImpl`
品牌关注	`MemberAttentionController` (/member/attention/)	-
会员优惠券	`UmsMemberCouponController` (/member/coupon/)	-

前端 - mall-admin-web

模块	页面目录	API 文件
登录/仪表盘	`views/home/`	`apis/admin.ts`
管理员	`views/ums/admin/`	`apis/admin.ts`
角色	`views/ums/role/`	`apis/role.ts`
菜单	`views/ums/menu/`	`apis/menu.ts`
资源	`views/ums/resource/`	`apis/resource.ts`
商品管理	`views/pms/product/`	`apis/product.ts`
商品分类	`views/pms/productCate/`	`apis/productCate.ts`
品牌	`views/pms/brand/`	`apis/brand.ts`
属性	`views/pms/productAttr/`	`apis/productAttr.ts`
运费模板	`views/pms/feightTemplate/`	`apis/feightTemplate.ts`
订单	`views/oms/order/`	`apis/order.ts`
退货申请	`views/oms/apply/`	`apis/returnApply.ts`
营销（SMS）	`views/sms/*/`	`apis/*.ts`
专题管理	`views/cms/subject/`	`apis/cmsSubject.ts`
话题管理	`views/cms/topic/`	`apis/cmsTopic.ts`
优选专区	`views/cms/preferenceArea/`	`apis/cmsPreferenceArea.ts`
帮助管理	`views/cms/help/`	`apis/help.ts`
举报处理	`views/cms/memberReport/`	`apis/memberReport.ts`
会员管理	`views/ums/member/`	`apis/memberManage.ts`
前台商城	`views/portal/`	`apis/portal.ts`

配置

文件	用途
`mall-admin/src/main/resources/application.yml`	后台安全白名单
`mall-portal/src/main/resources/application.yml`	前台安全白名单
`mall-admin-web/vite.config.ts`	前端代理配置
`mall-admin-web/src/router/index.ts`	前端路由

7. 启动命令

bash

# 后端编译
mvn compile -q

# 后台前端编译
cd mall-admin-web && npm run build

# 启动顺序
# 1. MySQL (localhost:3306, root/123456, 库名 mall)
# 2. Redis (localhost:6379)
# 3. mall-admin (端口 8080)
# 4. mall-admin-web (端口 5173, 开发模式)

8. 已知注意事项

mall-portal 包名与目录不一致：文件在 com/mall/ 目录但 package 声明为 com.mall.portal.*，这是项目原有结构，编译正常通过，新建文件保持一致即可
MyBatis Example 无 setLimit：分页必须用 PageHelper.startPage()
Element Plus Dialog：使用 v-model 控制显隐，不要用 v-model:visible
Element Plus Radio：使用 :value 绑定值，不要用已废弃的 :label
mall-portal 的 DTO 放在 com.mall.dto 包：目录为 mall-portal/src/main/java/com/mall/dto/
数据库不新增表：使用现有 docs/sql/mall.sql（表数量见第 3.1 节）
前端页面风格：shadcn/ui 迁移已收尾——el-table 的 border 属性已全部移除（原 21 处 / 17 文件）。仍余 7 个文件使用旧写法 el-card shadow="never"（等于未迁移到 PageCard 的全部文件）属细节遗留。新写页面一律用 PageCard + 无 border
图片/富文本上传路径：前端上传地址取自 mall-admin-web/.env 的 VITE_MINIO_UPLOAD_URL，必须与后端 MinioController 的 /api/minio/upload 一致（经 vite.config.ts 的 /api 代理转发到 mall-admin:8080）。⚠️ 该值曾误配为 /minio/upload（不匹配任何代理、后端也不认）导致上传全链路 404，已修复；后续若改 .env 或代理规则请同步核对
订单超时取消有双保险：主路径是 RabbitMQ 死信延迟队列（QueueEnum / RabbitMqConfig / CancelOrderReceiver，延迟取自 oms_order_setting.normalOrderOvertime）；OrderTimeOutCancelTask 每 10 分钟兜底扫描一次，防止消息丢失。两者并发安全——getTimeOutOrders 只查 status = 0，任一路径置为 4 后另一路径不再命中
useTableList / PageHeader 是闲置代码：composables/useTableList.ts 与 components/PageHeader/ 均存在但被 0 个页面引用，不要当作既有实践照搬
mall-search 是孤儿模块：287 行真实 ES 逻辑，但 mall-portal / mall-admin 与前端均无任何调用，且无 ES 服务。前台搜索实际走 MySQL LIKE
支付宝已接入但未接线：AlipayController（/alipay/pay|webPay|notify|query）与 AlipayServiceImpl 代码完整，但 appId / 密钥均为 your appId 占位符，prod 也用沙箱网关，前端 0 次调用
微信支付是前端假按钮：pay/index.vue 提供「微信支付」选项，后端无任何微信实现，点击同样直接调 paySuccess 成功
支付整体是模拟的：OmsPortalOrderServiceImpl 的 paySuccess 直接置 status=1 并扣真实库存，无网关调用、无签名校验
docs/dev/progress.md「框架搭建」表历史上存在虚假打勾（JTA/HTTPS/Docker/RestTemplate 等从未实现），已于本次审计修正，后续新增打勾请务必核实

9. 更新日志

日期	阶段	变更摘要
2026-07-13	Phase 1-3	订单列表日期范围搜索、商品信息列、发货日志完善、物流公司扩展、Bug修复
2026-07-14	Phase 1-4	会员注册登录(JSON Body)、手机号登录、用户信息改、收货地址CRUD、地址上限/默认切换
2026-07-15	Phase 1-5	前台购物完整实现：后端路径调整+新端点、前端 Portal 模块(20页面)、购物车/订单/支付/售后、代理方案
2026-07-15	前端重构	后台管理全站 shadcn/ui 风格重写：布局重构、TagsView、PageCard 组件、useTableList composable、30+ 页面重写
2026-07-16	Phase 2-1	SPU/SKU 多规格商品全链路：后台规格编辑器、前台 SKU 选择器、价格库存联动
2026-07-16	Phase 2-2	促销活动：秒杀活动/优惠券/满减促销后端+前端
2026-07-16	Phase 2-3	内容管理：专题/优选专区/话题后端CRUD+前端页面
2026-07-16	Phase 2-4	会员体系：后台会员管理、会员等级、积分/成长值、自动升降级
2026-07-16	Phase 2-5	前台增强：商品评论（后端+前端）、收藏/浏览历史、会员中心成长值展示
2026-07-15	Bug修复	Hamburger折叠空白页修复(visibility:collapse)、TagsView初始路径修正(/home→/admin/home)
2026-07	文档审计	全量文档审计修正：恢复被损坏的 `docs/prd/index.md`；表数量 73→75；修正默认账号密码(admin/macro123)；分类级数两级→三级；setup.md 补 MongoDB；`progress.md` 框架搭建表移除 4 项虚假打勾；`mall_api_spec.md` 能力数 51→65；新增第 3.1 节「关键数字」单一来源
2026-07	技术债清理	修复上传链路 404（`.env` 指向 `/api/minio/upload`）；启用 `OrderTimeOutCancelTask` 兜底定时器（并改为 public）；清理 5 个文件 23 行重复 import + 5 处未使用 import；移除 21 处 `el-table` 的 `border` 属性

mall 电商系统 - 开发上下文 ​

1. 当前开发阶段 ​

2. 项目概况 ​

技术栈 ​

模块结构 ​

依赖顺序 ​

3. 需求文档索引 ​

3.1 关键数字（单一来源） ​

4. 开发规范 ​

通用规则 ​

后端约定 ​

前端约定 ​

5. 已完成模块关键改动 ​

Phase 1-1 后台权限系统 ​

Phase 1-2 后台商品管理 ​

Phase 1-3 后台订单管理 ​

Phase 1-4 前台用户系统 ​

Phase 1-5 前台购物 ​

Phase 2-1 多规格商品 ​

Phase 2-2 促销活动 ​

Phase 2-3 内容管理 ​

Phase 2-4 会员体系 ​

Phase 2-5 前台增强 ​

前端重构 ​

6. 关键文件索引 ​

后端 - mall-admin ​

后端 - mall-portal ​

前端 - mall-admin-web ​

配置 ​

7. 启动命令 ​

8. 已知注意事项 ​

9. 更新日志 ​

mall 电商系统 - 开发上下文

1. 当前开发阶段

2. 项目概况

技术栈

模块结构

依赖顺序

3. 需求文档索引

3.1 关键数字（单一来源）

4. 开发规范

通用规则

后端约定

前端约定

5. 已完成模块关键改动

Phase 1-1 后台权限系统

Phase 1-2 后台商品管理

Phase 1-3 后台订单管理

Phase 1-4 前台用户系统

Phase 1-5 前台购物

Phase 2-1 多规格商品

Phase 2-2 促销活动

Phase 2-3 内容管理

Phase 2-4 会员体系

Phase 2-5 前台增强

前端重构

6. 关键文件索引

后端 - mall-admin

后端 - mall-portal

前端 - mall-admin-web

配置

7. 启动命令

8. 已知注意事项

9. 更新日志