# cloudmall **Repository Path**: jasonma1210/cloudmall ## Basic Information - **Project Name**: cloudmall - **Description**: 云商城项目 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-11-24 - **Last Updated**: 2025-11-24 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # SaaS 电商平台需求规格说明书 ## 一、项目概述 ### 1. 项目名称 SaaS 多租户电商平台（简称：CloudMall） ### 2. 核心目标 - 支持 **多商家入驻**，实现租户级资源隔离（数据、配置、权限）。 - 承载 **5W 同时在线用户**，峰值并发 **5000 QPS**（尤其抢购场景），保证系统高可用。 - 覆盖电商全链路：商家运营（入驻 / 装修 / 商品）、用户购物（浏览 / 搜索 / 下单 / 支付 / 抢购）、平台管控（租户管理 / 营销 / 财务）。 - 技术栈：后端采用 Spring Boot 3.5 **单体架构**，通过 Nginx 集群和 Redis 分布式 Session 提升并发能力；前端采用 Vue3 响应式开发；使用 RocketMQ 处理异步事件和延迟任务。 ### 3. 用户画像 | 角色 | 核心诉求 | | -------------- | ------------------------------------------------------------ | | 消费者（C 端） | 流畅的购物体验（浏览 / 搜索 / 下单 / 支付）、参与限时抢购、优惠叠加、多商家订单合并支付、物流跟踪、便捷售后（7 天无理由等）。 | | 商家（B 端） | 快速入驻、零代码店铺装修、商品管理、订单处理、营销工具（优惠券 / 满减 / 抢购）、数据统计、自主配置支付（支付宝 / 微信 / 云闪付）与物流接口、处理售后申请。 | | 平台管理员 | 租户审核、资源管控、违规处理、平台营销活动策划、财务结算、数据监控、系统配置、维护抢购活动秩序、处理跨商家纠纷。 | ## 二、功能性需求 ### 1. 多租户基础能力（SaaS 核心） #### 1.1 租户隔离 - 数据隔离：采用 **共享数据库 + 独立 Schema** 模式（商家数据按租户 ID 分区，避免跨租户访问）。 - 配置隔离：商家独立配置（店铺名称、logo、支付方式、物流模板、营销规则）。 - 权限隔离：商家管理员仅能操作本租户资源，平台管理员可跨租户管理。 #### 1.2 租户生命周期管理 - 入驻申请：商家填写企业信息（营业执照、法人身份）、店铺信息（名称、类目、简介），提交平台审核。 - 审核流程：平台管理员审核资料真实性，支持驳回（附带原因）、通过（自动创建租户 Schema）。 - 租户状态：草稿→待审核→已通过→运营中→暂停（违规）→注销（主动退出）。 - 资源配置：为租户分配资源配额（商品上限、带宽、存储、API 调用次数），支持按套餐升级。 ### 2. 商家端功能（B 端管理后台） #### 2.1 店铺管理 - 基础设置：店铺名称、logo、简介、联系方式、营业时间、退货地址。 - 店铺装修：支持 **可视化拖拽编辑**（模板选择、组件配置：轮播图、分类导航、商品橱窗、活动 Banner）。 - **支付配置**：商家可自主录入并管理 **支付宝、微信支付、云闪付** 等第三方支付平台的 API Key、商户号等配置信息，用于对接支付接口。平台提供配置模板和测试工具。 - 物流配置 ： - 对接主流物流平台（如顺丰、圆通、中通、韵达等），商家可配置物流模板（运费计算规则：按重量 / 体积 / 件数、包邮条件）。 - 支持物流单号的录入与追踪，商家可在订单管理中查看物流流转状态。 #### 2.2 商品管理 - 商品分类：支持多级分类（最多 3 级），自定义分类名称、排序、图标。 - 商品发布： - 基础信息：名称、主图（多图上传）、详情描述（富文本 / Markdown）、价格（原价 / 售价）、库存。 - 规格管理：支持多规格（如颜色、尺寸），规格组合定价（如红色 + XL 码单独定价）。 - 上下架：支持手动 / 定时上下架，商品状态（草稿 / 待审核 / 已上架 / 已下架）。 - 库存管理： - 实时库存：下单减库存（悲观锁 / 乐观锁保证并发安全），支持库存预警（低于阈值提醒）。 - 库存操作：手动调整库存（入库 / 出库），记录操作日志（原因、操作员、时间）。 #### 2.3 订单管理 - 订单列表：筛选（时间、状态、订单号、买家昵称），支持导出 Excel。 - 订单处理与流转 ： - 订单状态：待支付 → 待发货 → 待收货 → 已完成。 - 异常流程：待支付 → 已取消（超时未支付 / 用户取消）；待发货 → 已取消（商家取消 / 用户申请取消并通过）；待收货 → 售后处理中 → 售后完成 / 售后取消。 - 发货操作：填写物流单号，系统自动对接物流平台获取物流信息。 - 售后管理 ： - 处理用户发起的退款 / 退货申请，查看申请原因和凭证。 - 支持同意或拒绝申请，填写处理意见。 - 跟踪退货物流，确认退货入库后进行退款操作。 - 订单详情：展示商品信息、买家信息、支付信息、物流信息、优惠明细、售后记录。 #### 2.4 营销工具 - 优惠券管理： - 创建优惠券：设置类型（满减券 / 折扣券 / 免运费券）、面额、使用条件（满 X 元可用、指定商品 / 分类）、有效期、发放数量。 - 发放方式：主动发放（商家手动发送给用户）、被动领取（用户在店铺页面领取）。 - 满减活动：设置满减规则（如满 100 减 20、满 200 减 50），支持叠加优惠券（需配置优先级）。 - 限时折扣：选择商品设置折扣率、活动时间，支持限购数量。 - 抢购活动（新增） ： - 创建抢购活动：设置活动商品、活动时间、抢购价、限购数量、参与用户范围。 - 活动管理：查看活动状态（未开始 / 进行中 / 已结束）、参与人数、抢购成功数量。 - 库存预热：活动开始前，系统自动将活动商品库存加载到 Redis 中。 - 防超卖保障：依赖 Redis 预减库存 + RocketMQ 异步下单 + 数据库最终校验的机制。 #### 2.5 数据统计 - 经营概览：今日 / 昨日 / 近 7 日 / 近 30 日的订单量、销售额、支付金额、访客数、转化率。 - 商品分析：商品销量排行、浏览量排行、加购率。 - 用户分析：新老用户占比、用户地域分布、消费频次。 - 财务分析：收入明细、退款明细、平台佣金扣除明细。 - 抢购分析（新增）：各抢购活动的参与人数、下单转化率、销售额贡献。 ### 3. 用户端功能（C 端小程序 / APP/H5） #### 3.1 用户中心 - 注册登录：支持手机号验证码、微信 / QQ 第三方登录，自动关联平台账号。Token 存储于 Redis，实现分布式 Session。 - 个人信息：头像、昵称、性别、生日、收货地址（支持多地址、默认地址）。 - 账户安全：密码修改、手机号绑定、第三方账号解绑。 - 我的资产：余额、积分、优惠券（按店铺分类展示，标注使用条件）。 #### 3.2 店铺与商品浏览 - 首页：展示推荐店铺、平台活动 Banner、分类导航、热门 / 抢购商品。 - 店铺搜索与详情：支持按店铺名称、关键词搜索，查看店铺信息、商品分类、推荐商品。 - 商品列表：按分类 / 店铺展示商品，支持筛选（价格区间、销量、评分、规格）、排序（默认 / 价格 / 销量 / 新品）。 - 商品搜索 ： - 支持关键词搜索，采用 PostgreSQL 的 **倒排索引** 技术，并集成 **中文分词插件**（如 pg_jieba），提升搜索准确性和效率。 - 支持搜索历史记录、热门搜索推荐。 - 商品详情：展示商品信息（主图 / 详情图、价格、规格、库存）、店铺信息、评价列表、加入购物车 / 立即购买按钮。 #### 3.3 购物车 - 加入购物车：支持选择商品规格、数量，自动计算价格（含店铺优惠）。 - 购物车管理：修改数量、删除商品、勾选 / 取消勾选，支持跨店铺商品合并展示。 - 优惠计算：自动匹配商品对应的优惠券、满减活动，展示最优优惠组合（支持手动切换）。 #### 3.4 抢购功能（新增） - 抢购列表：展示当前和即将开始的抢购活动，包含倒计时、抢购价、剩余库存等信息。 - 抢购详情：展示活动规则、商品信息、已抢购人数。 - 抢购流程： - 用户点击 “立即抢购”，前端生成唯一 `request_id`。 - 系统进行资格校验（是否登录、活动时间、是否已抢购）和 Redis 预减库存。 - 预减成功后，返回 “抢购成功，订单正在处理中”，并通过 RocketMQ 异步创建订单。 - 用户可在 “我的订单” 中查看最终创建结果。 #### 3.5 下单与支付 - 订单创建： - 选择收货地址、支付方式、配送方式。 - 支持 **多商家商品合并下单**：生成一个主订单，包含多个商家子订单（按商家拆分，分别计算优惠和运费）。 - **幂等性保证**：通过前端生成的唯一 `request_id` 防止重复提交订单。 - 支付流程： - 合并支付：一次支付主订单金额（包含所有子订单应付金额），支付成功后分别通知对应商家。 - 支付方式：微信支付、支付宝支付、云闪付、余额支付。 - 订单状态：待支付→待发货→待收货→已完成→已取消（支持超时自动取消）。 - 支付状态异步处理 ： - 下单成功后，系统向 RocketMQ 发送 **延迟消息**（如 15 分钟），用于处理订单超时未支付的自动取消。 - 支付平台回调接口通过 **幂等性校验**（`transaction_id`）确保支付结果只处理一次。 - 引入 **支付状态兜底检查机制**（如 1 小时延迟消息），主动查询长时间处于 “待支付” 状态的订单的真实支付情况，保证最终一致性。 - 订单管理：订单列表（筛选 / 搜索）、订单详情（物流跟踪、售后申请）。 #### 3.6 优惠叠加规则 - 优先级：平台优惠券 > 店铺满减 > 店铺优惠券 > 商品折扣。 - 叠加限制： - 同一类型优惠不可叠加（如同一店铺的两张满减券不可同时使用）。 - 优惠券可与满减叠加（如满 100 减 20 的满减活动，可再使用一张 10 元优惠券，实付 70 元）。 - 免运费券可与其他优惠叠加（优先抵扣运费）。 #### 3.7 物流跟踪与售后 - **物流跟踪**：在订单详情页，用户可以查看所购商品的 **完整物流流转信息**，包括揽收、中转、派送、签收等各个节点的时间和地点。 - 售后申请 ： - 支持在订单完成后或特定条件下（如发货后）发起退款 / 退货申请。 - 申请原因包括：7 天无理由退货、商品质量问题、商品与描述不符、物流破损、错发漏发等。 - 用户需上传相关凭证（照片），填写申请说明。 - 跟踪售后处理进度，查看商家处理意见、退款状态。 ### 4. 总控端功能（平台管理后台） #### 4.1 租户管理 - 租户列表：展示所有商家租户（按状态筛选），支持搜索（租户名称、法人姓名、手机号）。 - 租户审核：查看入驻申请资料，支持通过 / 驳回（填写驳回原因）。 - 租户运营：暂停 / 恢复租户运营（如违规处理）、调整资源配额（如升级商品上限）。 - 租户监控：查看租户实时运营数据（订单量、并发请求数、带宽占用）。 #### 4.2 商品与内容管理 - 商品审核：审核商家发布的商品（合规性检查：是否侵权、违规词），支持通过 / 驳回。 - 违规商品处理：下架违规商品、扣除商家积分、发送整改通知。 - 平台内容管理：编辑首页 Banner、推荐店铺 / 商品、平台活动内容。 #### 4.3 用户管理 - 用户列表：展示所有平台用户，支持搜索（手机号、昵称、注册时间）。 - 用户操作：冻结 / 解冻用户账号、重置密码、查看用户订单 / 优惠券记录。 - 用户画像：分析用户消费习惯、地域分布、热门店铺 / 商品。 #### 4.4 营销与活动 - 平台优惠券：创建平台级优惠券（全平台通用 / 指定类目通用），设置发放规则（总量 / 每人限领）。 - 平台满减：设置跨店铺满减活动（如全平台满 300 减 50），支持与店铺优惠叠加。 - 活动管理：创建平台活动（如 618 大促、新人专享），设置活动时间、参与商家、优惠规则。 - 抢购活动管理（新增）：审核商家创建的抢购活动，监控活动期间的系统负载和异常情况。 #### 4.5 财务管理 - 结算管理：按周期（T+7/T+15）与商家结算款项（扣除平台佣金、手续费）。 - 账单管理：生成商家结算账单（收入、支出、明细），支持商家在线查看 / 下载。 - 佣金设置：配置平台基础佣金率（按类目区分），支持针对优质商家调整佣金。 - 退款处理：处理用户退款申请，审核退款原因，协调商家与用户（部分退款需平台介入）。 #### 4.6 系统监控与运维 - 性能监控：实时查看系统 QPS、响应时间、CPU / 内存占用、数据库连接数、Redis 缓存命中率、RocketMQ 消息积压情况。 - 日志管理：查看接口访问日志、错误日志、用户操作日志、消息消费日志，支持按时间 / 模块筛选。 - 告警配置：设置告警阈值（如 QPS 超过 4000、响应时间超过 500ms、消息积压超过 1000），支持邮件 / 短信告警。 - 系统配置： - 配置第三方服务接口（如短信服务、对象存储服务）。 - 管理支付平台和物流平台的对接参数模板。 - 配置全局退单规则（如默认支持 7 天无理由退货的商品类目）。 - 配置 RocketMQ 相关参数（延迟级别等）。 ### 5. 订单流转、退单条件及抢购实现（核心逻辑） #### 5.1 完整订单流转状态 - **待支付 (PENDING_PAYMENT)**：用户创建订单后，未完成支付。 - **待发货 (TO_BE_SHIPPED)**：用户已支付，商家未发货。 - **待收货 (TO_BE_RECEIVED)**：商家已发货，物流在途。 - **已完成 (COMPLETED)**：用户确认收货，或物流签收后超时自动完成。 - **已取消 (CANCELLED)**：订单在待支付或待发货状态被取消。 - **售后处理中 (AFTER_SALE)**：用户发起售后申请，商家或平台正在处理。 - **售后完成 (AFTER_SALE_DONE)**：售后申请处理完毕。 - **售后取消 (AFTER_SALE_CANCELLED)**：售后申请被撤回或拒绝。 #### 5.2 基于 RocketMQ 的订单状态异步处理 - **超时取消**：订单创建为 “待支付” 后，系统向 RocketMQ `order_payment_timeout` 主题发送一条延迟消息（如 15 分钟）。消费者监听该主题，到期后检查订单状态，若仍为 “待支付” 则执行取消逻辑。 - **支付结果兜底**：同时，向 `order_payment_confirm_check` 主题发送一条延迟更长的消息（如 1 小时）。消费者到期后检查订单状态，若仍为 “待支付”，则主动调用支付平台接口查询真实支付状态，并进行相应处理（补支付成功或取消订单），确保最终一致性。 #### 5.3 幂等性保证 - **订单创建**：前端生成唯一 `request_id`，后端通过 Redis `SETNX` 命令确保同一请求只处理一次。 - **支付回调**：利用支付平台返回的唯一 `transaction_id`，在 `pay_log` 表中记录，确保回调逻辑只执行一次。 - **消息消费**：消费者处理消息时，首先根据业务主键（如订单号）检查业务状态，确保消息不会被重复处理（例如，取消一个已发货的订单）。 #### 5.4 抢购功能实现（防超买超卖） - **库存预热**：抢购活动开始前，将商品库存加载到 Redis。 - **限流与资格校验**：Nginx 和应用层限流，Redis 检查用户是否已抢购。 - **Redis 预减库存**：使用 Lua 脚本执行原子操作 `DECRBY`，确保库存检查和扣减的原子性。 - **异步下单**：预减成功后，向 RocketMQ `order_create_queue` 发送消息，由消费者异步在数据库中创建订单和扣减最终库存。 - **最终一致性**：消费者在创建订单时，会再次检查数据库库存，作为最后一道防线。 #### 5.5 退单条件与流程 - **7 天无理由退货**：订单完成后 7 天内，商品完好、不影响二次销售。流程：申请 → 商家审核 → 寄回商品 → 商家确认收货 → 退款。 - **质量问题 / 描述不符**：收到商品后发现问题，需提供凭证。流程同上，但商家承担运费。 - **物流问题**：物流丢失、破损或超时。流程：申请 → 平台核实 → 退款或补发。 - **错发 / 漏发**：收到商品与订单不符。流程：申请 → 商家审核 → 协商退款或补发。 ## 三、非功能性需求 ### 1. 性能需求 - 并发能力：支持 **5000 QPS** 峰值（订单创建 / 支付 / 抢购接口），**99.9% 响应时间 < 500ms**。 - 在线用户：支持 **5W 同时在线用户**，无明显卡顿（页面加载时间 < 2s）。 - 数据处理： - 单表数据量达 1000 万 + 时，查询响应时间 < 1s（依赖索引优化、分库分表或时序表）。 - 利用 PostgreSQL 的 **时序表** 特性优化大量历史数据（如订单流水、用户行为日志）的存储和查询性能。 - 缓存策略：热点数据（商品信息、用户购物车、优惠券、用户 Session、抢购库存）缓存命中率 > 90%（使用 Redis 集群）。 - 搜索性能：商品搜索关键词查询响应时间 < 300ms。 - 消息处理：RocketMQ 消息生产和消费的平均延迟 < 100ms，支持消息堆积和重试。 ### 2. 高可用需求 - 可用性：系统全年可用性 ≥ 99.95%（允许每月 downtime ≤ 4.38 小时）。 - 容灾能力： - 多实例部署：核心应用部署多个实例，通过 Nginx 负载均衡。 - 数据备份：PostgreSQL 主从复制，每日全量备份 + 实时增量备份，RTO < 1 小时。 - 服务降级：非核心服务（如数据统计）可降级，保证核心购物流程可用。 - 消息队列高可用：RocketMQ 部署主从架构，确保消息不丢失。 ### 3. 安全性需求 - 身份认证：基于 JWT + Redis 实现多端统一认证与会话共享，支持 Token 过期刷新。 - 权限控制：RBAC 模型（平台管理员 / 商家管理员 / 普通用户），细粒度权限管控。 - 数据安全：敏感数据加密存储（AES），传输加密（HTTPS）。 - 接口防护：限流、防刷、防注入（SQL/XSS）、接口签名。 ### 4. 可扩展性与可维护性需求 - 架构扩展：虽然当前为单体架构，但设计时应考虑未来可能的微服务拆分，模块间低耦合。 - 功能扩展：支持插件化开发（如新增支付方式、物流接口）。 - 租户扩展：支持租户数量无上限扩展。 - 代码规范：遵循清晰的代码规范和设计模式，完善的注释和文档。 - 日志与监控：全面的日志记录和完善的监控告警体系，便于问题排查。 ### 5. 易用性需求 - 前端体验：Vue3 响应式开发，支持多端适配，操作流程简洁直观。 - 商家后台：可视化操作，降低使用门槛。 - 平台后台：批量操作，提高运营效率。 ## 四、技术架构设计 ### 1. 后端架构（Spring Boot 3.5） #### 1.1 架构模式 - **核心架构**：采用 **单体 Spring Boot 3.5 应用** 作为核心，通过 **Nginx** 进行负载均衡，部署多个应用实例以提高并发处理能力和可用性。 - **分布式 Session**：用户认证成功后，生成 JWT Token，存储于 Redis 中，实现分布式环境下的 Session 共享。 - **异步通信**：引入 **RocketMQ** 处理异步事件（如下单、支付通知）和延迟任务（如订单超时取消）。 #### 1.2 核心技术选型 - 框架：Spring Boot 3.5 - 数据库 ：PostgreSQL 15+ - **索引优化**：为查询频繁的字段建立合适的索引。 - **时序表**：对订单历史、操作日志等大数据量表使用时序表优化。 - **全文搜索**：启用全文搜索功能，安装 **pg_jieba** 中文分词插件。 - 缓存：Redis 7.0（集群模式，用于缓存、分布式锁、分布式 Session） - 消息队列：**RocketMQ 5.x**（用于异步处理、延迟队列、解耦） - API 文档：Knife4j（基于 Swagger 3.0） - 监控：Prometheus + Grafana（性能监控）、ELK（日志分析） - 部署：Docker + Nginx ### 2. 前端架构（Vue3） #### 2.1 端拆分 | 端名称 | 技术栈 | | -------------- | ------------------------------------------ | | 用户端（C 端） | Vue3 + Vite + Pinia + Vant UI + Axios | | 商家端（B 端） | Vue3 + Vite + Pinia + Element Plus + Axios | | 总控端（平台） | Vue3 + Vite + Pinia + Element Plus + Axios | #### 2.2 核心特性 - 响应式：适配 PC / 移动端。 - 性能优化：路由懒加载、组件缓存、图片懒加载、接口请求防抖 / 节流。 - 状态管理：Pinia 替代 Vuex。 - 权限控制：基于角色的菜单显示 / 接口访问控制。 ## 五、开发计划与里程碑 | 阶段 | 时间周期 | 核心任务 | | ---------------- | -------- | ------------------------------------------------------------ | | 需求分析与设计 | 3 周 | 细化需求、架构设计、数据库设计（含索引、时序表）、接口定义、支付 / 物流 / RocketMQ 对接方案 | | 基础框架搭建 | 4 周 | Spring Boot 单体框架搭建、Nginx 配置、Redis 集成、RocketMQ 集成、前端基础模板开发 | | 核心功能开发 | 10 周 | 租户管理、商品管理（含搜索）、订单管理（含流转、幂等性）、购物车、支付集成、物流集成、优惠系统、售后系统、抢购功能 | | 高并发与性能优化 | 3 周 | 缓存策略优化、数据库查询优化、Nginx 性能调优、RocketMQ 调优、压力测试与问题修复 | | 测试与修复 | 4 周 | 功能测试、性能测试、安全测试、用户体验测试、Bug 修复 | | 上线部署 | 2 周 | 环境部署、数据迁移、灰度发布、监控告警配置 | ## 六、风险与应对 | 风险点 | 应对措施 | | --------------------------- | ------------------------------------------------------------ | | 高并发下订单创建冲突 / 超卖 | 采用分布式锁（Redis Redlock）、RocketMQ 异步下单、数据库最终校验 | | 数据一致性问题 | 基于本地消息表 + RocketMQ 实现最终一致性，支付状态兜底检查 | | 消息队列可靠性 | RocketMQ 主从部署、消息重试机制、死信队列处理 | | 第三方接口依赖 | 对支付 / 物流接口做降级处理和重试机制，做好接口监控 | | 搜索性能不足 | 优化 PostgreSQL 全文搜索配置、合理设计分词策略、对热门搜索结果进行缓存 | | 单体架构瓶颈 | 初期通过集群部署和优化缓解，长期规划微服务拆分方案 |