# 商城管理系统功能设计

> **模块**：business-mall  
> **表前缀**：mall_  
> **依赖**：business-member（会员、积分、优惠券）

---

## 目录

- [一、设计目标与定位](#一设计目标与定位)
  - [1.1 系统定位](#11-系统定位)
  - [1.2 设计约束](#12-设计约束)
- [二、功能模块总览](#二功能模块总览)
- [三、功能模块详细设计](#三功能模块详细设计)
  - [3.1 商品中心](#31-商品中心)
  - [3.2 交易中心](#32-交易中心)
  - [3.3 营销中心](#33-营销中心)
  - [3.4 数据统计](#34-数据统计)
  - [3.5 基础设置与体验](#35-基础设置与体验)
- [四、核心表结构概览](#四核心表结构概览)
- [五、与 business-member 的集成关系](#五与-business-member-的集成关系)
- [六、数据库表结构设计](#六数据库表结构设计)
- [七、接口设计要点](#七接口设计要点)
- [八、实施阶段建议](#八实施阶段建议)
- [九、风险与注意点](#九风险与注意点)
- [十、核心业务流程说明](#十核心业务流程说明)
  - [10.1 下单流程（含积分、金币、账户余额、优惠券等判断）](#101-下单流程含积分金币账户余额优惠券等判断)
  - [10.2 商品审核流程（商户提交→平台审核）](#102-商品审核流程商户提交平台审核)
  - [10.3 支付成功后的奖励发放流程](#103-支付成功后的奖励发放流程)
- [十一、版本记录](#十一版本记录)
- [十二、商城通用可补充功能](#十二商城通用可补充功能)

---

## 一、设计目标与定位

### 1.1 系统定位

商城管理系统为企业级 B2C/B2B2C 电商平台的核心业务模块，提供商品管理、订单交易、营销活动等完整电商能力，与会员模块（business-member）深度集成，实现会员积分、优惠券、等级折扣在购物流程中的闭环。

### 1.2 设计约束

| 约束项 | 说明 |
|--------|------|
| 表前缀 | 所有业务表统一使用 `mall_` 前缀 |
| **实体类命名** | **所有实体类（Entity/Bean）必须加 `Mall` 前缀**，避免与其他模块业务单元命名冲突。例如：`mall_category` 表对应实体类 `MallCategory`（而非 `Category`），`mall_order` 对应 `MallOrder`（而非 `Order`） |
| 分层架构 | Bean → Service → Application → Controller |
| 后台路径 | `/admin/mall/**` |
| 移动端路径 | `/mobile/mall/**`（经 business-mobile-gateway） |
| 会员集成 | 订单关联 member_id，支持积分抵扣、优惠券核销、等级折扣 |

---

## 二、功能模块总览

```
┌─────────────────────────────────────────────────────────────────────────────────┐
│                           商城管理系统功能架构                                     │
└─────────────────────────────────────────────────────────────────────────────────┘

┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐
│   商品中心        │  │   交易中心        │  │   营销中心        │  │   数据统计        │
│                  │  │                  │  │                  │  │                  │
│ • 商品分类       │  │ • 购物车         │  │ • 秒杀/限时抢购   │  │ • 销售报表       │
│ • 品牌管理       │  │ • 订单管理       │  │ • 拼团活动       │  │ • 商品分析       │
│ • 商品SPU/SKU    │  │ • 支付对接       │  │ • 满减/满赠      │  │ • 订单分析       │
│ • 库存管理       │  │ • 售后管理       │  │ • 满减/满赠      │  │ • 订单分析       │
│ • 商品评价       │  │ • 收货地址       │  │ • 优惠券（复用   │  │ • 营销效果分析   │
│                  │  │                  │  │   member模块）   │  │ • 三级分销       │
└────────┬─────────┘  └────────┬─────────┘  └────────┬─────────┘  └──────────────────┘
         │                    │                    │
         └────────────────────┼────────────────────┘
                              │
                    ┌─────────▼─────────┐
                    │   business-member  │
                    │ 会员 | 积分 | 优惠券 │
                    └───────────────────┘
```

---

## 三、功能模块详细设计

### 3.1 商品中心

#### 3.1.1 商品分类

| 功能点 | 说明 | 优先级 |
|--------|------|--------|
| 多级分类 | 支持树形结构（如：家电→大家电→冰箱） | P0 |
| 分类排序 | 支持拖拽排序、排序号 | P0 |
| 分类图标/图片 | 用于前台展示 | P1 |
| 分类状态 | 启用/禁用，禁用后前台不展示 | P0 |

**核心实体**：`mall_category`（分类表）

#### 3.1.2 品牌管理

| 功能点 | 说明 | 优先级 |
|--------|------|--------|
| 品牌CRUD | 品牌名称、Logo、简介 | P0 |
| 品牌与分类关联 | 品牌可关联多个分类 | P1 |
| 品牌首字母 | 用于前台按字母筛选 | P2 |

**核心实体**：`mall_brand`

#### 3.1.3 商品SPU/SKU

| 功能点 | 说明 | 优先级 |
|--------|------|--------|
| SPU管理 | 标准产品单元（如：iPhone 15），含名称、主图、详情、分类、品牌 | P0 |
| SKU管理 | 库存单元（如：128G 黑色），含规格、价格、库存、条形码 | P0 |
| 规格属性 | 规格名（颜色/尺码）与规格值（红/蓝、S/M/L） | P0 |
| 商品上下架 | 上架/下架/定时上下架 | P0 |
| **商户修改/上架审核** | 商户新增、修改或申请上架商品需**平台审核**，审核通过后才会生效或上架 | P1 |
| 商品搜索 | 支持名称、分类、品牌、规格筛选 | P0 |
| 多图管理 | 主图、轮播图、详情图 | P0 |
| 虚拟销量 | 支持设置基础销量（真实销量+虚拟） | P2 |

**核心实体**：`mall_spu`（含审核状态、审核人、审核时间、驳回原因）、`mall_sku`、`mall_spec`、`mall_spec_value`、`mall_spu_spec`（SPU与规格关联）；可选 `mall_product_audit_log`（审核流水）

#### 3.1.3.1 商品审核（商户修改/上架需平台审核）

| 功能点 | 说明 | 优先级 |
|--------|------|--------|
| 提交审核 | 商户新增商品、修改商品信息或申请上架时，提交后进入**待审核**状态，前台不展示或仍为下架 | P1 |
| 平台审核 | 平台管理员在后台「待审核商品」列表中审核，可**通过**或**驳回**；驳回时须填写驳回原因 | P1 |
| 审核通过 | 通过后：新增/修改内容生效；若为「申请上架」则商品状态变为上架，前台可售 | P1 |
| 审核驳回 | 驳回后商品保持待审核或恢复为驳回前状态，商户可查看驳回原因并修改后重新提交 | P1 |
| 审核流水 | 可选：记录每次提交与审核的流水（提交时间、审核时间、审核结果、审核人），便于追溯 | P2 |

**流程说明**：

- **商户侧**：保存商品（新增/编辑）或点击「上架」时，若开启「商品需平台审核」，则 SPU 的 `audit_status` 置为待审核（PENDING），商品暂不对外展示或保持下架；商户可在「我的商品」中查看待审核、已通过、已驳回列表。
- **平台侧**：在后台「商品审核」列表中按待审核筛选，对每条进行通过或驳回操作；驳回时必填 `audit_remark`，审核通过时可将 `audit_status` 置为已通过（APPROVED），并将「申请上架」的 SPU 的 `status` 置为上架；驳回则置为已驳回（REJECTED）。
- **开关**：可在商城全局设置中配置「商户商品是否需平台审核」，关闭则商户保存/上架即生效，不经过审核。

**核心实体**：`mall_spu` 增加 `audit_status`（PENDING/APPROVED/REJECTED）、`audit_remark`、`audit_time`、`audit_by`；多商户场景下 SPU 增加 `merchant_id`。可选表 `mall_product_audit_log`（SPU ID、提交时间、审核时间、审核结果、驳回原因、审核人）。

#### 3.1.4 库存管理

| 功能点 | 说明 | 优先级 |
|--------|------|--------|
| 库存扣减 | 下单扣减、取消/退款回滚 | P0 |
| 库存预警 | 低于阈值提醒补货 | P1 |
| 库存流水 | 入库、出库、调整记录 | P1 |
| 多仓库 | 可选扩展，支持多仓库存 | P2 |

**核心实体**：`mall_sku_stock`、`mall_stock_log`（可选）

#### 3.1.5 商品评价

| 功能点 | 说明 | 优先级 |
|--------|------|--------|
| **评分项配置** | 后台可配置评价维度（评分项），如：商品质量、物流速度、服务态度等，每项可设置名称、满分值、排序 | P1 |
| 评价发布 | 订单完成后可评价，按配置的评分项逐项打分，含文字、图片 | P1 |
| 评价列表 | 商品详情页展示，支持分页、按好评/中评/差评筛选 | P1 |
| 商家回复 | 后台可回复评价 | P1 |
| 评价晒单 | 精选评价置顶 | P2 |

**评分项可配置说明**：

- 评分项由运营在后台维护，支持多维度（如：商品描述相符、物流速度、服务态度）。
- 每项可配置：名称、满分值（如 5 分）、是否必填、排序号。
- 用户评价时按当前启用的评分项逐项打分，系统可计算综合分或各维度均分。

**核心实体**：`mall_rating_item`（评分项配置）、`mall_product_review`（评价主表）、`mall_product_review_score`（评价各评分项得分明细，可选）

#### 3.1.6 商品收藏

| 功能点 | 说明 | 优先级 |
|--------|------|--------|
| 收藏/取消收藏 | 用户对 SPU 收藏、取消收藏 | P1 |
| 我的收藏列表 | 个人中心「我的收藏」列表，支持分页、删除 | P1 |
| 收藏数展示 | 商品详情页展示收藏数（可选） | P2 |

**核心实体**：`app_member_favorite`（`biz_type=product`，见 business-member 模块；原 `mall_favorite` 已废弃）

#### 3.1.7 商品咨询/问答

| 功能点 | 说明 | 优先级 |
|--------|------|--------|
| 用户提问 | 用户对商品（SPU）提问，可匿名 | P2 |
| 商家回复 | 后台对提问回复，支持多轮 | P2 |
| 问答列表 | 商品详情页展示该商品问答列表，支持分页 | P2 |

**核心实体**：`mall_product_qa`（订单ID可选、会员ID、SPU ID、问题内容、回复内容、是否匿名、状态）

#### 3.1.8 商品标签/卖点

| 功能点 | 说明 | 优先级 |
|--------|------|--------|
| 标签配置 | 后台维护标签库（热销、新品、推荐、包邮等），SPU 可关联多个标签 | P1 |
| 前台展示 | 商品列表、详情页展示标签 | P1 |

**核心实体**：`mall_tag`（标签名、标签编码、排序）、`mall_spu_tag`（SPU 与标签关联）

#### 3.1.9 单商品限购

| 功能点 | 说明 | 优先级 |
|--------|------|--------|
| 限购配置 | 后台为 SKU 配置每人限购数量（0 表示不限），可与秒杀限购并存 | P2 |
| 下单校验 | 下单时校验该用户该 SKU 在有效期内已购数量 + 本次数量 ≤ 限购数 | P2 |

**核心实体**：`mall_sku` 增加 `limit_per_user`（每人限购数量，0 不限）；以订单+SKU 统计已购数量。

#### 3.1.10 预售

| 功能点 | 说明 | 优先级 |
|--------|------|--------|
| 预售配置 | SPU/SKU 设为预售，配置定金、尾款支付时间、发货时间 | P2 |
| 定金+尾款 | 下单付定金，尾款期内付尾款，支持定金不退规则配置 | P2 |
| 定时开售 | 预售开始时间、结束时间 | P2 |

**核心实体**：`mall_presale`（关联 SPU/SKU、定金、尾款开始/结束时间、发货时间）、订单标记预售类型；支付分定金与尾款两笔。

---

### 3.2 交易中心

#### 3.2.1 购物车

| 功能点 | 说明 | 优先级 |
|--------|------|--------|
| 加入购物车 | 选择SKU、数量加入 | P0 |
| 修改数量/删除 | 修改数量、删除商品 | P0 |
| 选中结算 | 勾选商品计算总价、优惠 | P0 |
| 失效商品 | 下架/库存不足时标记失效 | P0 |
| 购物车合并 | 登录后合并未登录时加入的商品 | P1 |

**核心实体**：`mall_cart_item`

#### 3.2.2 收货地址

| 功能点 | 说明 | 优先级 |
|--------|------|--------|
| 地址CRUD | 收货人、手机、省市区、详细地址 | P0 |
| 默认地址 | 设置默认收货地址 | P0 |
| 地址数量限制 | 如最多 20 个 | P1 |

**核心实体**：`mall_member_address`（可复用 member 模块或独立）

#### 3.2.3 订单管理

| 功能点 | 说明 | 优先级 |
|--------|------|--------|
| 下单 | 选择商品、地址、优惠券、积分、金币抵扣、**账户余额**，计算实付金额；支付时可使用微信/支付宝/**账户余额**/金币等组合支付 | P0 |
| 订单状态 | 待支付→待发货→待收货→已完成；取消、退款 | P0 |
| 订单详情 | 商品、金额、优惠、物流信息 | P0 |
| 订单列表 | 分页、按状态筛选、搜索 | P0 |
| 订单超时取消 | 待支付订单超时自动取消 | P0 |
| 自动收货 | 发货后 N 天自动确认收货 | P1 |
| 订单导出 | 后台导出订单Excel | P1 |
| **订单备注** | 买家下单留言（如「不要放辣」）、商家后台备注，订单详情展示 | P0 |
| **订单改价** | 后台对待支付订单改价（如协商减零头），记录改价前后金额 | P1 |
| **发票管理** | 用户选择是否开票、填写抬头与税号，订单记录发票信息；可对接电子发票 | P1 |

**订单与会员集成**：

- 使用优惠券：核销 member 模块 `app_member_coupon`
- 使用积分：扣减 `app_member.available_points`，记录 `app_member_points_log`
- **使用账户余额**：下单/支付时可使用会员账户余额（`app_member.balance`）支付全部或部分订单金额，可与微信/支付宝/金币组合；支付成功后扣减余额并记录余额流水，退款时退回余额
- **金币抵扣**：扣减会员金币（如 `app_member.coins` 或独立金币表），按比例抵扣订单金额
- 等级折扣：按 `app_member_level.discount_rate` 计算
- 订单完成：增加成长值、积分（消费获取）
- **现金支付赠送**：用钱支付（微信/支付宝/余额等实付金额）可赠送积分、金币，赠送比例可配置（如 1 元送 10 积分、1 元送 1 金币）
- **三级分销**：订单完成后，按实付金额比例给二级、三级发放积分、金币；推荐人身份（会员等级）不同时，积分比例与金币比例可分别配置

**核心实体**：`mall_order`（含 buyer_remark、admin_remark、发票相关字段、改价记录）、`mall_order_item`、`mall_order_log`（状态变更日志）

#### 3.2.3.1 运费/运费模板

| 功能点 | 说明 | 优先级 |
|--------|------|--------|
| 运费模板 | 按地区、重量或件数计费；支持多模板（如包邮、按重量、按件数） | P0 |
| 包邮规则 | 满 X 元包邮、指定地区包邮、指定商品包邮 | P0 |
| 下单计算 | 下单时根据收货地址、商品重量/件数、包邮规则计算运费 | P0 |

**核心实体**：`mall_freight_template`（模板名、计费类型：WEIGHT/ITEM/FREE、首重/首件、续重/续件、包邮条件）、`mall_freight_template_region`（模板+地区+首费/续费）、商品/SKU 关联模板；订单记录 `freight_amount`。

#### 3.2.3.2 到店自提

| 功能点 | 说明 | 优先级 |
|--------|------|--------|
| 自提点维护 | 后台维护自提点（名称、地址、联系方式、营业时间） | P2 |
| 下单选自提 | 用户下单可选择「到店自提」、选择自提点与期望自提时间 | P2 |
| 到店核销 | 用户到店后核销（扫码或核销码），订单完成自提 | P2 |

**核心实体**：`mall_pickup_point`（自提点）、`mall_order` 增加 delivery_type（DELIVERY/PICKUP）、pickup_point_id、pickup_time、pickup_verify_code、pickup_verify_time。

#### 3.2.4 支付对接

| 功能点 | 说明 | 优先级 |
|--------|------|--------|
| 支付方式 | 微信支付、支付宝、**账户余额**（会员余额）、**金币抵扣现金**；支持组合支付 | P0 |
| **账户余额** | 下单/支付时可使用会员账户余额（`app_member.balance`）支付全部或部分金额，可与微信/支付宝/金币组合 | P0 |
| 金币抵扣 | 会员金币按比例抵扣订单金额（如 1 金币=0.01 元），与现金/余额组合支付 | P0 |
| 支付回调 | 异步回调更新订单状态、库存回滚 | P0 |
| 退款 | 支持原路退款；账户余额支付部分退回余额，金币支付部分退回金币 | P0 |
| 支付流水 | 记录支付单、退款单 | P1 |

**支付方式说明**：

| 支付方式 | 说明 |
|----------|------|
| 微信支付 | 对接微信支付 SDK |
| 支付宝 | 对接支付宝 SDK |
| **账户余额** | 使用会员账户余额（`app_member.balance`）支付全部或部分订单金额；下单时可选择使用余额，支付成功后扣减余额并记录流水，退款时原路退回余额；可与微信/支付宝/金币组合使用 |
| **金币抵扣现金** | 使用会员金币（`app_member.coins` 或独立金币表），按配置比例（如 100 金币=1 元）抵扣订单金额，可与微信/支付宝/余额组合使用 |

**说明**：支付可复用框架支付模块或对接第三方支付 SDK。账户余额、金币需在 member 模块或 mall 模块中定义存储与流水。

**核心实体**：`mall_pay_order`、`mall_refund_order`（或复用通用支付表）

#### 3.2.4.1 现金支付赠送（积分/金币）

| 功能点 | 说明 | 优先级 |
|--------|------|--------|
| 赠送规则 | 用钱支付（微信/支付宝/余额等实付金额）可赠送积分、金币 | P0 |
| **积分/金币开关** | 积分赠送、金币赠送可独立配置开启/关闭 | P0 |
| 比例配置 | 消费 1 元赠送的积分数量、金币数量可配置（如 1 元=10 积分、1 元=1 金币） | P0 |
| **消费人身份差异化** | 消费人（下单买家）的会员等级不同时，赠送的**积分**与**金币**可分别配置、互不相同 | P1 |
| 赠送时机 | 订单支付成功后，按实付金额 × 比例计算并发放（仅对已开启的项发放） | P0 |
| 退款扣回 | 退款时按比例扣回已赠送的积分、金币 | P0 |

**消费人身份差异化说明**：

- 消费赠送规则**仅使用一张表** `mall_reward_level_config`（与原 mall_reward_config 合并，以本表为主）。消费人身份以会员等级（`app_member.level_code`）为主，如 NORMAL、SILVER、GOLD、PLATINUM、DIAMOND。
- **积分与金币分别按消费人等级配置**：不同等级的消费人可配置不同的「每消费 1 元赠送积分数」和「每消费 1 元赠送金币数」，以及该等级是否启用积分、金币。例如：普通会员 1 元送 10 积分、1 金币；黄金会员 1 元送 15 积分、2 金币。
- 约定 **member_level_code = 'DEFAULT'** 表示默认配置：当消费人的等级在本表中无对应行时，使用 DEFAULT 行的比例与启用开关。可为某等级只配积分、只配金币或两者都配。

**配置示例**：

| 配置项 | 说明 | 示例 |
|--------|------|------|
| member_level_code | 等级编码；'DEFAULT' 表示默认（未匹配到具体等级时使用） | DEFAULT、NORMAL、GOLD |
| points_enabled / coins_enabled | 该等级是否启用积分、金币赠送 | 1、1 |
| points_per_yuan / coins_per_yuan | 该等级每消费 1 元赠送积分、金币数 | 10、1；GOLD 可配 15、2 |

**发放逻辑**：订单支付成功后，根据订单的消费人 `member_id` 查其 `level_code`，再查 `mall_reward_level_config`：先按该 level_code 匹配一行，有则用该行；无则用 member_level_code='DEFAULT' 的行。按该行的 points_enabled、coins_enabled 与 points_per_yuan、coins_per_yuan 计算并发放。

**核心实体**：`mall_reward_level_config`（消费赠送唯一配置表，含 DEFAULT 与各会员等级的 1 元送积分/金币及启用开关）

#### 3.2.5 物流管理

| 功能点 | 说明 | 优先级 |
|--------|------|--------|
| 发货 | 填写物流公司、运单号 | P0 |
| 物流查询 | 对接物流接口查询轨迹 | P1 |
| 物流公司维护 | 维护常用物流公司列表 | P1 |

**核心实体**：`mall_order`（物流字段）、`mall_logistics_company`（物流公司表）

#### 3.2.6 售后管理

| 功能点 | 说明 | 优先级 |
|--------|------|--------|
| 仅退款 | 未发货可申请仅退款 | P0 |
| 退货退款 | 已收货可申请退货退款 | P0 |
| 换货 | 申请换货 | P1 |
| 售后单状态 | 待审核→待退货→待收货→已完成/已拒绝 | P0 |
| **退款/退货原因** | 用户申请时选择原因（如不想要、质量问题、发错货），便于售后原因分析 | P2 |
| 退款处理 | 同意后退款、退回优惠券/积分/金币/余额，并扣回已赠送的积分、金币 | P0 |

**核心实体**：`mall_after_sale`（含 refund_reason、refund_reason_desc）、`mall_after_sale_item`

---

### 3.3 营销中心

#### 3.3.1 优惠券（复用 business-member）

| 功能点 | 说明 |
|--------|------|
| 优惠券模板 | 使用 `app_coupon_template` |
| 会员领券 | 使用 `app_member_coupon` |
| 订单核销 | 下单时选择可用优惠券，支付成功后核销 |

**扩展**：优惠券使用范围可配置「指定商品/分类/品牌」，需在 member 模块 `app_coupon_template` 中支持。

#### 3.3.2 秒杀/限时抢购

| 功能点 | 说明 | 优先级 |
|--------|------|--------|
| 秒杀场次 | 配置开始/结束时间 | P1 |
| 秒杀商品 | 场次关联商品、秒杀价、库存 | P1 |
| 限购 | 每人限购数量 | P1 |
| 秒杀下单 | 独立下单流程，扣减秒杀库存 | P1 |

**核心实体**：`mall_seckill_session`、`mall_seckill_sku`

#### 3.3.3 拼团活动

| 功能点 | 说明 | 优先级 |
|--------|------|--------|
| 拼团活动 | 配置拼团价、成团人数、有效期 | P2 |
| 开团/参团 | 用户开团或参团 | P2 |
| 成团 | 人数满足自动成团，生成订单 | P2 |

**核心实体**：`mall_group_activity`、`mall_group_order`、`mall_group_join`

#### 3.3.4 满减/满赠

| 功能点 | 说明 | 优先级 |
|--------|------|--------|
| 满减规则 | 满 X 减 Y、满 X 打 N 折 | P1 |
| 满赠 | 满 X 赠商品 | P2 |
| 活动时间 | 支持时间段配置 | P1 |

**核心实体**：`mall_promotion_rule`

#### 3.3.5 三级分销

| 功能点 | 说明 | 优先级 |
|--------|------|--------|
| 分销层级 | 一级（消费人）、二级（消费人的直接推荐人）、三级（二级的推荐人） | P1 |
| 奖励发放 | 订单完成后，按订单实际支付金额比例给二级、三级发放积分、金币或两者兼有 | P1 |
| 比例配置 | 二级、三级比例可配置（如二级 10%、三级 5%），按实付金额计算 | P1 |
| **推荐人身份差异化** | 推荐人（二级/三级）的会员等级不同时，其获得的**积分比例**与**金币比例**可分别配置、互不相同 | P1 |
| **积分/金币启用** | 每条按身份配置（mall_distribution_level_rate）可独立配置该身份是否启用积分、是否启用金币 | P1 |
| 奖励类型 | 支持仅积分、仅金币，或积分+金币同时发放；默认与按等级配置均可 | P1 |
| 邀请关系 | 复用 member 模块 `app_member.inviter_id` 建立推荐关系链 | P1 |
| 退款扣回 | 订单退款时，扣回已发放给二级、三级的积分与金币 | P1 |

**推荐人身份差异化说明**：

- 推荐人身份以会员等级（`app_member.level_code`）为主，如 NORMAL、SILVER、GOLD、PLATINUM、DIAMOND。
- **积分与金币分别按身份配置**：同一分销层级下，不同等级的推荐人可配置不同的**积分比例**和不同的**金币比例**。例如：
  - 二级推荐人：普通会员 积分 8% + 金币 2%，黄金会员 积分 10% + 金币 2%。
  - 三级推荐人：普通会员 积分 4% + 金币 1%，黄金会员 积分 5% + 金币 1%。
- 可为某等级只配置积分比例（不配金币则不发金币）、只配置金币比例，或两者都配；未配置某等级时，回退到该层级的默认配置。
- **积分、金币均可配置是否启用**：`mall_distribution_level_rate` 每条记录有 **points_enabled**、**coins_enabled**，该身份下仅当启用时才按对应比例发放，便于按身份精细控制「只发积分」「只发金币」或「同时发」。
- **仅使用一张表**：分销规则以 `mall_distribution_level_rate` 为主（与原 mall_distribution_config 合并）。约定 **member_level_code = 'DEFAULT'** 表示该分销层级的默认配置：当推荐人会员等级在本表中无对应行时，使用「该层级 + DEFAULT」行的比例与启用开关。例如：distribution_level=2 且 member_level_code='DEFAULT' 为二级默认；distribution_level=3 且 member_level_code='DEFAULT' 为三级默认。

**分销层级说明**（消费人为一级）：

| 层级 | 角色 | 说明 | 是否获奖励 |
|------|------|------|------------|
| 一级 | 消费人 | 下单购买的买家本人 | 否（层级起点） |
| 二级 | 消费人的直接推荐人 | 买家的 `inviter_id`，直接邀请买家的人 | 是 |
| 三级 | 二级的推荐人 | 二级的 `inviter_id`，间接推荐人 | 是 |

**示例**：A 邀请 B，C 邀请 A。B 下单消费 100 元 → B 是一级（消费人），A 是二级获奖励（按 A 的会员等级取对应的积分比例、金币比例），C 是三级获奖励（按 C 的会员等级取对应的积分比例、金币比例）。

**比例配置示例**：

| 配置项 | 说明 | 示例 |
|--------|------|------|
| 默认 | 该层级未按身份配置时使用：distribution_level=2/3 且 member_level_code='DEFAULT' 的两行 | 二级 DEFAULT：积分 8%、金币 2%；三级 DEFAULT：积分 4%、金币 1% |
| 按推荐人等级 | 推荐人会员等级（level_code）不同，**积分比例与金币比例分别配置** | 二级 GOLD：积分 10%、金币 2%；三级 GOLD：积分 5%、金币 1% |
| 仅积分/仅金币 | 某等级可只配积分或只配金币，未配置项不发放 | 某等级只填 points_rate，不填 coins_rate → 该等级只发积分 |
| **积分/金币启用** | 每条按身份配置的记录可独立配置是否启用积分、是否启用金币 | points_enabled=1、coins_enabled=0 → 该身份只发积分不发金币 |

**发放逻辑**：先按「分销层级 + 推荐人当前会员等级」查 `mall_distribution_level_rate`，取到则用该条记录的积分比例、金币比例，且仅当 **points_enabled=1** 时发放积分、**coins_enabled=1** 时发放金币；未取到则用该层级 **member_level_code='DEFAULT'** 的行（如 distribution_level=2 且 member_level_code='DEFAULT'）。再无则视为不发放。

**核心实体**：`mall_distribution_level_rate`（分销唯一配置表，含各层级 DEFAULT 与各推荐人等级：积分/金币比例及启用开关）、`mall_distribution_log`（分销奖励流水）

#### 3.3.6 新人专享/首单优惠

| 功能点 | 说明 | 优先级 |
|--------|------|--------|
| 首单标识 | 与 member 联动：新注册用户或未下过单用户视为「首单」 | P1 |
| 首单立减/赠券 | 后台配置首单立减金额或赠送优惠券，下单时自动享受 | P1 |

**核心实体**：`mall_first_order_config`（首单立减金额、赠券模板ID等）；与 member 首单标识联动。

#### 3.3.7 会员价/专享价

| 功能点 | 说明 | 优先级 |
|--------|------|--------|
| 按等级定价 | 后台为 SKU 配置各会员等级专享价（与等级折扣可并存：折扣针对原价，会员价可为独立价） | P1 |
| 前台展示 | 根据当前用户等级展示对应价格，未登录展示原价或最低档 | P1 |

**核心实体**：`mall_sku_level_price`（SKU ID、member_level_code、price）；无配置时回退 SKU 原价+等级折扣。

#### 3.3.8 赠品规则

| 功能点 | 说明 | 优先级 |
|--------|------|--------|
| 买 A 赠 B / 满件赠 | 后台配置：买指定商品或满 N 件赠指定商品，赠品走库存与订单明细 | P2 |
| 下单赠送 | 下单满足条件时自动加入赠品 SKU，订单明细标记赠品 | P2 |

**核心实体**：`mall_gift_rule`（规则类型：BUY_A_GIVE_B/FULL_ITEM、主商品条件、赠品 SKU、数量）、订单明细 `is_gift`。

#### 3.3.9 加价购

| 功能点 | 说明 | 优先级 |
|--------|------|--------|
| 加价换购配置 | 指定商品加 X 元换购另一 SKU，后台配置换购价与换购商品 | P2 |
| 下单选择 | 下单时展示可换购项，用户选择是否加价换购，订单含换购明细 | P2 |

**核心实体**：`mall_add_purchase`（主 SKU、换购 SKU、加价金额）、订单明细区分普通与换购。

#### 3.3.10 积分兑换/积分商城

| 功能点 | 说明 | 优先级 |
|--------|------|--------|
| 积分商品 | 后台配置可用积分兑换的商品及所需积分数 | P2 |
| 兑换下单 | 用户选择积分兑换，扣减 member 积分，生成订单（0 元单或积分+现金） | P2 |

**核心实体**：`mall_points_product`（SPU/SKU、所需积分、限兑数量等）；与 member 积分扣减、订单关联。

#### 3.3.11 砍价/助力

| 功能点 | 说明 | 优先级 |
|--------|------|--------|
| 砍价活动 | 后台配置砍价商品、底价、砍价次数、有效期 | P3 |
| 发起砍价 | 用户发起砍价，分享给好友助力，每次助力随机砍掉一定金额 | P3 |
| 达底价下单 | 砍至底价后可按底价购买，生成订单 | P3 |

**核心实体**：`mall_bargain_activity`、`mall_bargain_record`（用户发起记录）、`mall_bargain_help`（助力记录）；与订单关联。

---

### 3.4 数据统计

| 功能点 | 说明 | 优先级 |
|--------|------|--------|
| 销售概览 | 今日/本周/本月销售额、订单量 | P1 |
| 商品销售排行 | 销量、销售额排行 | P1 |
| 订单分析 | 订单状态分布、趋势图 | P1 |
| 营销效果 | 优惠券核销率、活动转化率 | P2 |
| **会员消费与复购** | 按会员统计消费金额、订单数、复购率，与 member 联动 | P1 |
| **库存预警报表** | 低于阈值的 SKU 汇总展示，便于补货 | P1 |
| **售后原因分析** | 售后单选择退款/退货原因，统计原因分布 | P2 |

---

### 3.5 基础设置与体验

#### 3.5.1 商城全局设置

| 功能点 | 说明 | 优先级 |
|--------|------|--------|
| 订单超时 | 待支付订单超时自动取消时间（分钟） | P0 |
| 自动收货 | 发货后 N 天自动确认收货 | P0 |
| 功能开关 | 是否开启评价、是否开启发票、是否开启自提、**是否开启商户商品平台审核**等 | P0 |

**核心实体**：`mall_setting`（配置键值对或独立配置表，如 order_timeout_minutes、auto_confirm_days）。

#### 3.5.2 订单/物流消息通知

| 功能点 | 说明 | 优先级 |
|--------|------|--------|
| 订单状态通知 | 下单成功、支付成功、发货、签收等站内信或短信/模板消息 | P1 |
| 物流提醒 | 发货后推送物流信息，签收提醒 | P1 |

**说明**：可与框架消息模块或第三方推送对接；记录通知模板与发送日志。

#### 3.5.3 搜索历史与热门搜索

| 功能点 | 说明 | 优先级 |
|--------|------|--------|
| 搜索历史 | 用户搜索词记录（按用户、时间），个人中心或搜索框下拉展示 | P2 |
| 热门搜索 | 统计搜索词频次，前台展示热门搜索词 | P2 |

**核心实体**：`mall_search_log`（会员ID、关键词、时间）、热门词可从日志统计或后台配置。

#### 3.5.4 浏览足迹

| 功能点 | 说明 | 优先级 |
|--------|------|--------|
| 浏览记录 | 用户浏览商品（SPU）时记录，按时间倒序 | P2 |
| 浏览足迹列表 | 个人中心「浏览足迹」列表，支持分页、删除 | P2 |

**核心实体**：`mall_browse_footprint`（会员ID、SPU ID、浏览时间）；可限制每人条数（如最近 200 条）。

---

## 四、核心表结构概览

| 序号 | 表名 | 说明 | 优先级 |
|------|------|------|--------|
| 1 | mall_category | 商品分类 | P0 |
| 2 | mall_brand | 品牌 | P0 |
| 3 | mall_spec | 规格名（颜色/尺码） | P0 |
| 4 | mall_spec_value | 规格值 | P0 |
| 5 | mall_spu | 商品SPU（含商户、审核状态、审核人、驳回原因等） | P0 |
| 5.1 | mall_product_audit_log | 商品审核流水（可选，记录每次提交与审核） | P2 |
| 6 | mall_sku | 商品SKU | P0 |
| 7 | mall_spu_spec | SPU与规格关联 | P0 |
| 8 | mall_cart_item | 购物车 | P0 |
| 9 | mall_member_address | 收货地址 | P0 |
| 10 | mall_order | 订单主表 | P0 |
| 11 | mall_order_item | 订单明细 | P0 |
| 12 | mall_order_log | 订单状态日志 | P0 |
| 13 | mall_rating_item | 评分项配置（评价维度可配置） | P1 |
| 14 | mall_product_review | 商品评价 | P1 |
| 15 | mall_product_review_score | 评价得分明细（各评分项得分，可选） | P1 |
| 16 | mall_seckill_session | 秒杀场次 | P1 |
| 17 | mall_seckill_sku | 秒杀商品 | P1 |
| 18 | mall_promotion_rule | 满减/满赠规则 | P1 |
| 19 | mall_after_sale | 售后单 | P0 |
| 20 | mall_logistics_company | 物流公司 | P1 |
| 21 | mall_reward_level_config | 消费赠送唯一配置表（含 DEFAULT 与各等级：1 元送积分/金币及启用开关） | P0 |
| 22 | mall_distribution_level_rate | 分销唯一配置表（含各层级 DEFAULT 与各推荐人等级：积分/金币比例及启用开关） | P1 |
| 23 | mall_distribution_log | 分销奖励流水（订单、层级、获奖励人、奖励金额/积分/金币） | P1 |
| 24 | mall_favorite | 商品收藏（会员、SPU） | P1 |
| 25 | mall_product_qa | 商品咨询/问答 | P2 |
| 26 | mall_tag | 商品标签（热销、新品、推荐等） | P1 |
| 27 | mall_spu_tag | SPU 与标签关联 | P1 |
| 28 | mall_presale | 预售配置（定金、尾款时间、发货时间） | P2 |
| 29 | mall_freight_template | 运费模板 | P0 |
| 30 | mall_freight_template_region | 运费模板地区及费用 | P0 |
| 31 | mall_pickup_point | 到店自提点 | P2 |
| 32 | mall_first_order_config | 新人/首单优惠配置 | P1 |
| 33 | mall_sku_level_price | SKU 会员等级专享价 | P1 |
| 34 | mall_gift_rule | 赠品规则（买 A 赠 B、满件赠） | P2 |
| 35 | mall_add_purchase | 加价购配置 | P2 |
| 36 | mall_points_product | 积分兑换商品配置 | P2 |
| 37 | mall_bargain_activity | 砍价活动 | P3 |
| 38 | mall_bargain_record | 砍价发起记录 | P3 |
| 39 | mall_bargain_help | 砍价助力记录 | P3 |
| 40 | mall_setting | 商城全局设置（订单超时、自动收货、功能开关） | P0 |
| 41 | mall_search_log | 搜索历史（可选，热门词可由此统计） | P2 |
| 42 | mall_browse_footprint | 浏览足迹 | P2 |

**说明**：`mall_sku` 增加 `limit_per_user`（单商品限购）；`mall_order` 增加买家备注、商家备注、发票信息、运费、改价、自提相关字段；`mall_order_item` 增加 `is_gift`；`mall_after_sale` 增加退款/退货原因字段。

---

## 六、数据库表结构设计

> 基础字段规范：所有表均包含 `id`、`create_by`、`create_date`、`update_by`、`update_date`、`del_flag`、`remarks`、`tenant_code`、`tenant_id`。

### 6.1 商品相关表

#### mall_category（商品分类）

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | VARCHAR(64) | 是 | 主键 |
| parent_id | VARCHAR(64) | 否 | 父分类ID，0 表示顶级 |
| category_name | VARCHAR(64) | 是 | 分类名称 |
| category_code | VARCHAR(32) | 否 | 分类编码 |
| category_icon | VARCHAR(500) | 否 | 分类图标 |
| category_image | VARCHAR(500) | 否 | 分类图片 |
| sort_order | INT | 否 | 排序号 |
| status | TINYINT | 是 | 状态：0-禁用 1-启用 |

#### mall_brand（品牌）

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | VARCHAR(64) | 是 | 主键 |
| brand_name | VARCHAR(64) | 是 | 品牌名称 |
| brand_code | VARCHAR(32) | 否 | 品牌编码 |
| brand_logo | VARCHAR(500) | 否 | 品牌Logo |
| brand_desc | VARCHAR(500) | 否 | 品牌简介 |
| first_letter | VARCHAR(2) | 否 | 首字母 |
| sort_order | INT | 否 | 排序号 |
| status | TINYINT | 是 | 状态：0-禁用 1-启用 |

#### mall_spu（商品SPU）

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | VARCHAR(64) | 是 | 主键 |
| spu_name | VARCHAR(128) | 是 | 商品名称 |
| spu_code | VARCHAR(32) | 否 | 商品编码 |
| category_id | VARCHAR(64) | 是 | 分类ID |
| brand_id | VARCHAR(64) | 否 | 品牌ID |
| main_image | VARCHAR(500) | 否 | 主图 |
| images | TEXT | 否 | 轮播图（JSON数组） |
| detail | TEXT | 否 | 商品详情（富文本） |
| virtual_sales | INT | 否 | 虚拟销量 |
| sort_order | INT | 否 | 排序号 |
| status | TINYINT | 是 | 状态：0-下架 1-上架 |
| merchant_id | VARCHAR(64) | 否 | 商户ID（多商户场景下关联商户，单商户可空） |
| audit_status | TINYINT | 否 | 审核状态：0-待审核 1-已通过 2-已驳回（未开启审核时可为空） |
| audit_remark | VARCHAR(500) | 否 | 驳回原因（驳回时必填） |
| audit_time | DATETIME | 否 | 审核时间 |
| audit_by | VARCHAR(64) | 否 | 审核人ID |

#### mall_product_audit_log（商品审核流水，可选）

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | VARCHAR(64) | 是 | 主键 |
| spu_id | VARCHAR(64) | 是 | SPU ID |
| submit_time | DATETIME | 是 | 提交审核时间 |
| audit_time | DATETIME | 否 | 审核时间 |
| audit_result | TINYINT | 否 | 审核结果：1-通过 2-驳回 |
| audit_remark | VARCHAR(500) | 否 | 驳回原因 |
| audit_by | VARCHAR(64) | 否 | 审核人ID |

> 用于记录每次商户提交与平台审核的流水，便于追溯；若仅需当前审核状态可在 mall_spu 上维护，不建本表。

#### mall_sku（商品SKU）

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | VARCHAR(64) | 是 | 主键 |
| spu_id | VARCHAR(64) | 是 | SPU ID |
| sku_name | VARCHAR(128) | 否 | SKU名称 |
| sku_code | VARCHAR(32) | 否 | SKU编码 |
| spec_info | VARCHAR(255) | 否 | 规格信息（如：颜色:红;尺码:M） |
| price | DECIMAL(12,2) | 是 | 销售价格 |
| original_price | DECIMAL(12,2) | 否 | 原价 |
| stock | INT | 是 | 库存 |
| stock_warn | INT | 否 | 库存预警阈值 |
| bar_code | VARCHAR(64) | 否 | 条形码 |
| image | VARCHAR(500) | 否 | SKU图片 |
| limit_per_user | INT | 否 | 每人限购数量，0 表示不限 |
| status | TINYINT | 是 | 状态：0-禁用 1-启用 |

### 6.2 订单相关表

#### mall_order（订单主表）

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | VARCHAR(64) | 是 | 主键 |
| order_no | VARCHAR(32) | 是 | 订单编号 |
| member_id | VARCHAR(64) | 是 | 会员ID |
| total_amount | DECIMAL(12,2) | 是 | 订单总金额 |
| discount_amount | DECIMAL(12,2) | 否 | 优惠金额 |
| coupon_amount | DECIMAL(12,2) | 否 | 优惠券抵扣 |
| points_amount | DECIMAL(12,2) | 否 | 积分抵扣金额 |
| coins_amount | DECIMAL(12,2) | 否 | 金币抵扣金额 |
| balance_amount | DECIMAL(12,2) | 否 | 账户余额支付金额 |
| freight_amount | DECIMAL(12,2) | 否 | 运费金额 |
| pay_amount | DECIMAL(12,2) | 是 | 实付金额 |
| points_used | INT | 否 | 使用积分数 |
| coins_used | INT | 否 | 使用金币数 |
| buyer_remark | VARCHAR(500) | 否 | 买家留言 |
| admin_remark | VARCHAR(500) | 否 | 商家备注 |
| invoice_type | TINYINT | 否 | 发票类型：0-不开票 1-个人 2-企业 |
| invoice_title | VARCHAR(128) | 否 | 发票抬头 |
| invoice_tax_no | VARCHAR(32) | 否 | 税号 |
| price_before_change | DECIMAL(12,2) | 否 | 改价前金额（改价时记录） |
| delivery_type | VARCHAR(16) | 否 | 配送方式：DELIVERY-配送 PICKUP-到店自提 |
| pickup_point_id | VARCHAR(64) | 否 | 自提点ID（到店自提时） |
| pickup_time | DATETIME | 否 | 期望自提时间 |
| pickup_verify_code | VARCHAR(32) | 否 | 自提核销码 |
| pickup_verify_time | DATETIME | 否 | 自提核销时间 |
| status | TINYINT | 是 | 状态：0-待支付 1-待发货 2-待收货 3-已完成 4-已取消 5-退款中 |
| pay_type | VARCHAR(32) | 否 | 支付方式：WECHAT/ALIPAY/BALANCE/COINS（组合支付时可存主支付方式或逗号分隔） |
| pay_time | DATETIME | 否 | 支付时间 |
| receiver_name | VARCHAR(64) | 是 | 收货人 |
| receiver_mobile | VARCHAR(20) | 是 | 收货手机 |
| receiver_province | VARCHAR(64) | 否 | 省 |
| receiver_city | VARCHAR(64) | 否 | 市 |
| receiver_district | VARCHAR(64) | 否 | 区 |
| receiver_address | VARCHAR(255) | 是 | 详细地址 |
| logistics_company | VARCHAR(64) | 否 | 物流公司 |
| logistics_no | VARCHAR(64) | 否 | 运单号 |
| ship_time | DATETIME | 否 | 发货时间 |
| confirm_time | DATETIME | 否 | 确认收货时间 |

#### mall_order_item（订单明细）

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | VARCHAR(64) | 是 | 主键 |
| order_id | VARCHAR(64) | 是 | 订单ID |
| sku_id | VARCHAR(64) | 是 | SKU ID |
| spu_id | VARCHAR(64) | 是 | SPU ID |
| sku_name | VARCHAR(128) | 否 | 商品名称 |
| spec_info | VARCHAR(255) | 否 | 规格信息 |
| price | DECIMAL(12,2) | 是 | 单价 |
| quantity | INT | 是 | 数量 |
| total_amount | DECIMAL(12,2) | 是 | 小计金额 |
| image | VARCHAR(500) | 否 | 商品图片 |
| is_gift | TINYINT | 否 | 是否赠品：0-否 1-是 |

### 6.2.1 评价与评分项表

#### mall_rating_item（评分项配置）

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | VARCHAR(64) | 是 | 主键 |
| item_name | VARCHAR(64) | 是 | 评分项名称（如：商品质量、物流速度、服务态度） |
| item_code | VARCHAR(32) | 否 | 评分项编码 |
| max_score | INT | 是 | 满分值，如 5 表示 1～5 分 |
| is_required | TINYINT | 是 | 是否必填：0-否 1-是 |
| sort_order | INT | 否 | 排序号 |
| status | TINYINT | 是 | 状态：0-禁用 1-启用 |

#### mall_product_review（商品评价）

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | VARCHAR(64) | 是 | 主键 |
| order_id | VARCHAR(64) | 是 | 订单ID |
| order_item_id | VARCHAR(64) | 否 | 订单明细ID |
| member_id | VARCHAR(64) | 是 | 会员ID |
| spu_id | VARCHAR(64) | 是 | 商品SPU ID |
| sku_id | VARCHAR(64) | 否 | 商品SKU ID |
| total_score | DECIMAL(3,2) | 否 | 综合得分（各评分项均分或加权） |
| score_detail | TEXT | 否 | 各评分项得分（JSON，如 {"item_id1":5,"item_id2":4}） |
| content | TEXT | 否 | 评价文字 |
| images | TEXT | 否 | 评价图片（JSON数组） |
| is_anonymous | TINYINT | 否 | 是否匿名：0-否 1-是 |
| reply_content | TEXT | 否 | 商家回复 |
| reply_time | DATETIME | 否 | 回复时间 |
| is_top | TINYINT | 否 | 是否置顶：0-否 1-是 |

#### mall_product_review_score（评价得分明细，可选）

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | VARCHAR(64) | 是 | 主键 |
| review_id | VARCHAR(64) | 是 | 评价ID |
| rating_item_id | VARCHAR(64) | 是 | 评分项ID |
| score | INT | 是 | 得分 |

> 若采用 `mall_product_review.score_detail` 存 JSON，可省略本表；需按评分项统计时建议使用本表。

### 6.3 营销配置表

#### mall_reward_level_config（消费赠送唯一配置表，以本表为主）

> 消费赠送规则仅使用本表（与原 mall_reward_config 合并）。每条记录对应一个「消费人身份」：**member_level_code = 'DEFAULT'** 表示默认配置（消费人等级在本表中无对应行时使用）；其他值为具体会员等级（如 NORMAL、GOLD），来自 app_member_level.level_code。

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | VARCHAR(64) | 是 | 主键 |
| member_level_code | VARCHAR(32) | 是 | 消费人会员等级编码；'DEFAULT' 表示默认（未匹配到具体等级时使用） |
| points_enabled | TINYINT | 是 | 该身份是否启用积分赠送：0-不发放 1-启用 |
| coins_enabled | TINYINT | 是 | 该身份是否启用金币赠送：0-不发放 1-启用 |
| points_per_yuan | DECIMAL(10,2) | 否 | 该身份下每消费1元赠送积分数；仅当 points_enabled=1 时生效 |
| coins_per_yuan | DECIMAL(10,2) | 否 | 该身份下每消费1元赠送金币数；仅当 coins_enabled=1 时生效 |
| sort_order | INT | 否 | 排序号 |
| status | TINYINT | 是 | 状态：0-禁用 1-启用 |

> 发放时按订单消费人的 level_code 查本表；先匹配该 level_code 的行，有则用该行；无则用 member_level_code='DEFAULT' 的行；按该行的 points_enabled、coins_enabled 与 points_per_yuan、coins_per_yuan 计算并发放。

#### mall_distribution_level_rate（分销唯一配置表，以本表为主）

> 分销规则仅使用本表（与原 mall_distribution_config 合并）。每条记录对应「分销层级 + 推荐人会员等级」：**member_level_code = 'DEFAULT'** 表示该层级的默认配置（推荐人等级在本表中无对应行时使用）；其他值为具体会员等级（如 NORMAL、GOLD），来自 app_member_level.level_code。例如：distribution_level=2 且 member_level_code='DEFAULT' 为二级默认；distribution_level=3 且 member_level_code='DEFAULT' 为三级默认。

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | VARCHAR(64) | 是 | 主键 |
| distribution_level | TINYINT | 是 | 分销层级：2-二级 3-三级 |
| member_level_code | VARCHAR(32) | 是 | 推荐人会员等级编码；'DEFAULT' 表示该层级默认（未匹配到具体等级时使用） |
| points_enabled | TINYINT | 是 | 该身份是否启用积分奖励：0-不发放 1-启用 |
| coins_enabled | TINYINT | 是 | 该身份是否启用金币奖励：0-不发放 1-启用 |
| points_rate | DECIMAL(5,4) | 否 | 该身份下积分奖励比例，如 0.1000 表示 10%；仅当 points_enabled=1 时生效 |
| coins_rate | DECIMAL(5,4) | 否 | 该身份下金币奖励比例，如 0.0200 表示 2%；仅当 coins_enabled=1 时生效 |
| sort_order | INT | 否 | 排序号 |
| status | TINYINT | 是 | 状态：0-禁用 1-启用 |

> 发放时先按「分销层级 + 推荐人当前会员等级」查本表，有则用该行；无则用该层级 **member_level_code='DEFAULT'** 的行。按该行的 points_enabled、coins_enabled 与 points_rate、coins_rate 计算并发放。

#### mall_distribution_log（分销奖励流水）

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | VARCHAR(64) | 是 | 主键 |
| order_id | VARCHAR(64) | 是 | 订单ID |
| order_no | VARCHAR(32) | 否 | 订单编号 |
| member_id | VARCHAR(64) | 是 | 消费人（一级）会员ID |
| reward_member_id | VARCHAR(64) | 是 | 获奖励人会员ID |
| level | TINYINT | 是 | 层级：2-二级 3-三级 |
| order_amount | DECIMAL(12,2) | 是 | 订单实付金额 |
| reward_rate | DECIMAL(5,4) | 是 | 奖励比例 |
| reward_points | INT | 否 | 奖励积分数 |
| reward_coins | INT | 否 | 奖励金币数 |
| reward_type | VARCHAR(16) | 是 | 奖励类型：POINTS/COINS |

### 6.3.1 商品中心与交易扩展表

#### mall_favorite（商品收藏）

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | VARCHAR(64) | 是 | 主键 |
| member_id | VARCHAR(64) | 是 | 会员ID |
| spu_id | VARCHAR(64) | 是 | SPU ID |

#### mall_product_qa（商品咨询/问答）

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | VARCHAR(64) | 是 | 主键 |
| member_id | VARCHAR(64) | 是 | 会员ID |
| spu_id | VARCHAR(64) | 是 | SPU ID |
| question | TEXT | 是 | 问题内容 |
| answer | TEXT | 否 | 回复内容 |
| is_anonymous | TINYINT | 否 | 是否匿名：0-否 1-是 |
| status | TINYINT | 是 | 状态：0-待回复 1-已回复 |

#### mall_tag（商品标签）

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | VARCHAR(64) | 是 | 主键 |
| tag_name | VARCHAR(32) | 是 | 标签名称（热销、新品、推荐、包邮等） |
| tag_code | VARCHAR(32) | 否 | 标签编码 |
| sort_order | INT | 否 | 排序号 |
| status | TINYINT | 是 | 状态：0-禁用 1-启用 |

#### mall_spu_tag（SPU与标签关联）

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | VARCHAR(64) | 是 | 主键 |
| spu_id | VARCHAR(64) | 是 | SPU ID |
| tag_id | VARCHAR(64) | 是 | 标签ID |

#### mall_presale（预售配置）

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | VARCHAR(64) | 是 | 主键 |
| spu_id | VARCHAR(64) | 是 | SPU ID |
| deposit_amount | DECIMAL(12,2) | 是 | 定金金额 |
| tail_start_time | DATETIME | 是 | 尾款开始时间 |
| tail_end_time | DATETIME | 是 | 尾款结束时间 |
| ship_time | DATETIME | 否 | 预计发货时间 |
| status | TINYINT | 是 | 状态：0-禁用 1-启用 |

#### mall_freight_template（运费模板）

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | VARCHAR(64) | 是 | 主键 |
| template_name | VARCHAR(64) | 是 | 模板名称 |
| charge_type | VARCHAR(16) | 是 | 计费类型：WEIGHT-按重量 ITEM-按件数 FREE-包邮 |
| first_weight | DECIMAL(10,2) | 否 | 首重(kg)（按重量时） |
| first_fee | DECIMAL(10,2) | 否 | 首费(元) |
| continue_weight | DECIMAL(10,2) | 否 | 续重(kg) |
| continue_fee | DECIMAL(10,2) | 否 | 续费(元) |
| free_amount | DECIMAL(12,2) | 否 | 满X元包邮（可选） |
| status | TINYINT | 是 | 状态：0-禁用 1-启用 |

#### mall_freight_template_region（运费模板地区）

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | VARCHAR(64) | 是 | 主键 |
| template_id | VARCHAR(64) | 是 | 运费模板ID |
| region_codes | VARCHAR(500) | 否 | 地区编码（省/市，逗号分隔） |
| first_fee | DECIMAL(10,2) | 是 | 首费 |
| continue_fee | DECIMAL(10,2) | 是 | 续费 |

#### mall_pickup_point（到店自提点）

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | VARCHAR(64) | 是 | 主键 |
| point_name | VARCHAR(64) | 是 | 自提点名称 |
| contact_mobile | VARCHAR(20) | 否 | 联系电话 |
| province | VARCHAR(64) | 否 | 省 |
| city | VARCHAR(64) | 否 | 市 |
| district | VARCHAR(64) | 否 | 区 |
| address | VARCHAR(255) | 是 | 详细地址 |
| business_hours | VARCHAR(128) | 否 | 营业时间 |
| sort_order | INT | 否 | 排序号 |
| status | TINYINT | 是 | 状态：0-禁用 1-启用 |

### 6.3.2 营销扩展表

#### mall_first_order_config（新人/首单优惠）

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | VARCHAR(64) | 是 | 主键 |
| discount_amount | DECIMAL(12,2) | 否 | 首单立减金额 |
| coupon_template_ids | VARCHAR(500) | 否 | 赠券模板ID（逗号分隔） |
| status | TINYINT | 是 | 状态：0-禁用 1-启用 |

#### mall_sku_level_price（SKU会员等级专享价）

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | VARCHAR(64) | 是 | 主键 |
| sku_id | VARCHAR(64) | 是 | SKU ID |
| member_level_code | VARCHAR(32) | 是 | 会员等级编码 |
| price | DECIMAL(12,2) | 是 | 专享价 |

#### mall_gift_rule（赠品规则）

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | VARCHAR(64) | 是 | 主键 |
| rule_type | VARCHAR(16) | 是 | 类型：BUY_A_GIVE_B-买A赠B FULL_ITEM-满件赠 |
| condition_sku_ids | VARCHAR(500) | 否 | 条件商品SKU ID（逗号分隔） |
| condition_quantity | INT | 否 | 满足数量（满件时） |
| gift_sku_id | VARCHAR(64) | 是 | 赠品SKU ID |
| gift_quantity | INT | 是 | 赠品数量 |
| start_time | DATETIME | 否 | 开始时间 |
| end_time | DATETIME | 否 | 结束时间 |
| status | TINYINT | 是 | 状态：0-禁用 1-启用 |

#### mall_add_purchase（加价购）

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | VARCHAR(64) | 是 | 主键 |
| main_sku_id | VARCHAR(64) | 是 | 主商品SKU ID |
| add_sku_id | VARCHAR(64) | 是 | 换购商品SKU ID |
| add_price | DECIMAL(12,2) | 是 | 加价金额(元) |
| status | TINYINT | 是 | 状态：0-禁用 1-启用 |

#### mall_points_product（积分兑换商品）

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | VARCHAR(64) | 是 | 主键 |
| sku_id | VARCHAR(64) | 是 | SKU ID |
| points_required | INT | 是 | 所需积分 |
| limit_per_user | INT | 否 | 每人限兑数量，0 不限 |
| stock | INT | 否 | 兑换库存 |
| start_time | DATETIME | 否 | 开始时间 |
| end_time | DATETIME | 否 | 结束时间 |
| status | TINYINT | 是 | 状态：0-禁用 1-启用 |

#### mall_bargain_activity（砍价活动）

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | VARCHAR(64) | 是 | 主键 |
| sku_id | VARCHAR(64) | 是 | SKU ID |
| initial_price | DECIMAL(12,2) | 是 | 初始价 |
| bottom_price | DECIMAL(12,2) | 是 | 底价 |
| help_count | INT | 是 | 需助力次数 |
| start_time | DATETIME | 是 | 开始时间 |
| end_time | DATETIME | 是 | 结束时间 |
| status | TINYINT | 是 | 状态：0-禁用 1-启用 |

#### mall_bargain_record（砍价发起记录）

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | VARCHAR(64) | 是 | 主键 |
| activity_id | VARCHAR(64) | 是 | 活动ID |
| member_id | VARCHAR(64) | 是 | 发起人会员ID |
| current_price | DECIMAL(12,2) | 是 | 当前已砍至价格 |
| help_count | INT | 否 | 已助力次数 |
| order_id | VARCHAR(64) | 否 | 成单后订单ID |
| status | TINYINT | 是 | 状态：0-进行中 1-已达底价 2-已下单 |

#### mall_bargain_help（砍价助力记录）

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | VARCHAR(64) | 是 | 主键 |
| record_id | VARCHAR(64) | 是 | 砍价记录ID |
| member_id | VARCHAR(64) | 是 | 助力人会员ID |
| cut_amount | DECIMAL(12,2) | 是 | 本次砍掉金额 |

### 6.3.3 基础与体验表

#### mall_setting（商城全局设置）

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | VARCHAR(64) | 是 | 主键 |
| config_key | VARCHAR(64) | 是 | 配置键（如 order_timeout_minutes、auto_confirm_days、review_enabled、invoice_enabled、pickup_enabled、**product_audit_enabled** 商户商品是否需平台审核） |
| config_value | VARCHAR(500) | 否 | 配置值 |

#### mall_search_log（搜索历史）

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | VARCHAR(64) | 是 | 主键 |
| member_id | VARCHAR(64) | 是 | 会员ID |
| keyword | VARCHAR(128) | 是 | 搜索关键词 |
| search_time | DATETIME | 是 | 搜索时间 |

#### mall_browse_footprint（浏览足迹）

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | VARCHAR(64) | 是 | 主键 |
| member_id | VARCHAR(64) | 是 | 会员ID |
| spu_id | VARCHAR(64) | 是 | SPU ID |
| browse_time | DATETIME | 是 | 浏览时间 |

#### mall_after_sale（售后单，补充字段）

售后单表需包含：refund_reason（退款/退货原因编码）、refund_reason_desc（原因描述或自定义文字），便于售后原因分析统计。

### 6.4 ER 关系示意

```
mall_category ──┬── mall_spu ── mall_sku
mall_brand ─────┘         │
                          ├── mall_order ── mall_order_item
mall_rating_item ─────────┴── mall_product_review ── mall_product_review_score
mall_member_address ──────┤         │
app_member (inviter_id) ───┴─────────┴── mall_distribution_log
                                    │
                          mall_reward_level_config（消费赠送唯一配置，含 DEFAULT 与各等级）
                          mall_distribution_level_rate（分销唯一配置，含各层级 DEFAULT 与各推荐人等级）
```

---

## 五、与 business-member 的集成关系

| 场景 | 集成点 |
|------|--------|
| 下单使用积分 | 调用 MemberService 扣减积分，记录积分流水 |
| 下单使用优惠券 | 校验 member 模块 `app_member_coupon` 可用性，核销更新状态 |
| **下单使用账户余额** | 下单/支付时可选择使用会员账户余额（`app_member.balance`）；支付成功后扣减余额、记录余额流水；退款时退回余额 |
| **下单使用金币** | 扣减会员金币，按配置比例（如 100 金币=1 元）抵扣订单金额 |
| 等级折扣 | 根据 `app_member.level_code` 查询 `app_member_level.discount_rate` 计算折扣 |
| 订单完成 | 增加会员成长值、消费积分（调用 MemberApplicationService） |
| **现金支付赠送** | 按实付金额 × 配置比例赠送积分、金币；消费人会员等级不同可配置不同的 1 元送积分/金币数 |
| **三级分销** | 订单完成后，按实付金额比例给二级、三级发放积分、金币；推荐人会员等级不同可配置不同的积分比例与金币比例 |
| 退款 | 退回积分、退回优惠券、**退回账户余额**、**退回金币**，并扣回已赠送的积分、金币、**分销奖励** |
| 收货地址 | 可与 member 模块共用或独立，建议独立 `mall_member_address` 便于扩展 |
| **首单优惠** | 与 member 首单标识联动，新用户或未下过单用户享受首单立减/赠券 |
| **会员价** | 根据 `app_member.level_code` 查 `mall_sku_level_price` 展示专享价 |
| **积分兑换** | 积分商城兑换商品时扣减 member 积分，生成订单 |

---

## 七、接口设计要点

### 7.1 后台管理接口（/admin/mall/**）

| 模块 | 典型接口 |
|------|----------|
| 分类 | POST /admin/mall/category/list、save、delete、tree |
| 评分项 | POST /admin/mall/ratingItem/list、save、delete；GET /admin/mall/ratingItem/options（评价用下拉） |
| 品牌 | POST /admin/mall/brand/list、save、delete |
| 商品 | POST /admin/mall/spu/list、save、delete；GET /admin/mall/spu/info |
| **商品审核** | POST /admin/mall/spu/auditList（待审核商品列表）；POST /admin/mall/spu/audit（通过/驳回，驳回时传 audit_remark） |
| SKU | POST /admin/mall/sku/list、save；GET /admin/mall/sku/stock |
| 订单 | POST /admin/mall/order/list；GET /admin/mall/order/info；POST /admin/mall/order/ship |
| 售后 | POST /admin/mall/afterSale/list；POST /admin/mall/afterSale/audit |
| 秒杀 | POST /admin/mall/seckill/session/list、save；POST /admin/mall/seckill/sku/list、save |
| 营销 | POST /admin/mall/promotion/list、save、delete |
| 消费赠送 | GET /admin/mall/rewardLevelConfig/info（含 DEFAULT）；POST /admin/mall/rewardLevelConfig/list、save、delete（唯一配置表，含 DEFAULT 与各等级：1 元送积分/金币及启用开关） |
| 三级分销 | GET /admin/mall/distribution/levelRate/info（含 DEFAULT）；POST /admin/mall/distribution/levelRate/list、save、delete（唯一配置表，含各层级 DEFAULT 与各推荐人等级）；POST /admin/mall/distribution/log/list |
| 运费模板 | POST /admin/mall/freightTemplate/list、save、delete；GET /admin/mall/freightTemplate/regions |
| 自提点 | POST /admin/mall/pickupPoint/list、save、delete |
| 商品标签 | POST /admin/mall/tag/list、save、delete；POST /admin/mall/spuTag/bind（SPU 关联标签） |
| 首单优惠 | GET /admin/mall/firstOrderConfig/info；POST /admin/mall/firstOrderConfig/save |
| 会员价 | POST /admin/mall/skuLevelPrice/list、save、delete |
| 赠品规则 | POST /admin/mall/giftRule/list、save、delete |
| 加价购 | POST /admin/mall/addPurchase/list、save、delete |
| 积分商城 | POST /admin/mall/pointsProduct/list、save、delete |
| 砍价活动 | POST /admin/mall/bargain/activity/list、save；POST /admin/mall/bargain/record/list |
| 预售 | POST /admin/mall/presale/list、save、delete |
| 商城设置 | GET /admin/mall/setting/info；POST /admin/mall/setting/save |

### 7.2 移动端接口（/mobile/mall/**）

| 模块 | 典型接口 |
|------|----------|
| 商品 | GET /mobile/mall/product/list、detail；GET /mobile/mall/category/tree |
| 购物车 | POST /mobile/mall/cart/add、update、delete、list |
| 订单 | POST /mobile/mall/order/create、list；GET /mobile/mall/order/detail；POST /mobile/mall/order/cancel、confirm |
| 地址 | POST /mobile/mall/address/list、save、delete、setDefault |
| 评价 | POST /mobile/mall/review/add、list |
| 秒杀 | GET /mobile/mall/seckill/sessions；POST /mobile/mall/seckill/order |
| 收藏 | POST /mobile/member/favorite/toggle、remove、list（统一收藏，见 business-member） |
| 商品问答 | GET /mobile/mall/product/qa/list；POST /mobile/mall/product/qa/add |
| 运费试算 | GET /mobile/mall/freight/calc（传地址、商品列表） |
| 自提点 | GET /mobile/mall/pickupPoint/list；GET /mobile/mall/order/pickupVerify（到店核销） |
| 首单优惠 | GET /mobile/mall/firstOrder/check（是否首单、可用优惠） |
| 加价购 | GET /mobile/mall/addPurchase/options（当前订单可换购项） |
| 积分商城 | GET /mobile/mall/pointsProduct/list；POST /mobile/mall/pointsProduct/exchange |
| 砍价 | GET /mobile/mall/bargain/activity/list、detail；POST /mobile/mall/bargain/start、help |
| 预售 | GET /mobile/mall/presale/list、detail；POST /mobile/mall/presale/order（定金/尾款） |
| 搜索历史/热门 | GET /mobile/mall/search/history、hot；POST /mobile/mall/search/log（记录搜索） |
| 浏览足迹 | GET /mobile/mall/footprint/list；POST /mobile/mall/footprint/record、delete |

---

## 八、实施阶段建议

| 阶段 | 内容 | 预估 |
|------|------|------|
| 第一阶段 | 商品中心（分类、品牌、SPU/SKU、库存、标签）、购物车、收货地址、订单主流程、**订单备注/运费模板/商城全局设置**、支付对接、物流、售后、商品评价 | 核心交易闭环与基础体验 |
| 第二阶段 | 商品收藏、商品问答、首单优惠、会员价、**订单改价/发票/消息通知**、数据统计（含会员消费与复购、库存预警报表）、积分商城 | 营销与运营增强 |
| 第三阶段 | 秒杀、满减、赠品、加价购、预售、到店自提、售后原因分析、搜索历史与热门搜索、浏览足迹 | 体验与运营完善 |
| 第四阶段 | 拼团、砍价/助力、多仓库等扩展 | 按需迭代 |

---

## 九、风险与注意点

1. **库存一致性**：高并发下单需考虑库存超卖，可采用乐观锁或 Redis 预扣减。
2. **订单状态机**：订单状态流转需严格校验，避免非法状态变更。
3. **优惠叠加**：多种优惠（满减、优惠券、积分、金币抵扣）需明确叠加规则与优先级。
4. **支付幂等**：支付回调需做幂等处理，防止重复回调导致重复发货/加积分。
5. **数据一致性**：订单完成涉及订单、库存、会员积分、优惠券等多表，需事务或分布式事务保障。

---

## 十、核心业务流程说明

本章详细描述商城核心业务流程，包括下单流程中的积分、金币、账户余额、优惠券等判断与使用，以及商品审核流程等，便于开发实施时参考。

### 10.1 下单流程（含积分、金币、账户余额、优惠券等判断）

#### 10.1.1 流程概述

用户从购物车或商品详情页发起下单，系统需依次处理：商品校验、价格计算、优惠叠加、支付方式选择、库存扣减、订单生成等环节。

#### 10.1.2 详细流程步骤

**步骤 1：商品与库存校验**

1. 校验商品状态：SPU 与 SKU 是否为上架（`mall_spu.status=1`、`mall_sku.status=1`）；若开启审核，还需校验 `audit_status=1`（已通过）。
2. 校验库存：SKU 库存是否充足（`mall_sku.stock >= 购买数量`）。
3. 校验限购：若 SKU 配置了 `limit_per_user > 0`，查询该用户该 SKU 在有效期内已购数量，校验「已购数量 + 本次数量 ≤ limit_per_user」。
4. 校验秒杀/限时抢购：若为秒杀商品，校验场次、秒杀库存、限购。

**步骤 2：价格计算（商品原价）**

1. 计算商品总价：`商品总价 = Σ(SKU单价 × 数量)`。
2. 应用会员等级折扣：
   - 查询 `app_member.level_code` → `app_member_level.discount_rate`（如 0.95 表示 95 折）。
   - 或查询 `mall_sku_level_price` 是否有该等级的专享价，有则用专享价，无则用 SKU 原价 × 折扣率。
   - `折扣后总价 = 商品总价 × discount_rate`（或按 SKU 专享价累加）。

**步骤 3：优惠叠加计算（优先级：满减 > 优惠券 > 积分抵扣 > 金币抵扣）**

1. **满减/满赠**：
   - 查询 `mall_promotion_rule`，按订单金额匹配满减规则（如满 100 减 10）。
   - 计算满减金额：`满减金额 = 匹配的满减金额`。
   - 更新订单总价：`订单总价 = 折扣后总价 - 满减金额`。

2. **优惠券**：
   - 用户选择优惠券，校验 `app_member_coupon` 是否可用（状态、有效期、使用范围）。
   - 计算优惠券抵扣：`优惠券抵扣 = min(优惠券面额, 订单总价 - 满减金额)`。
   - 更新订单总价：`订单总价 = 订单总价 - 优惠券抵扣`。

3. **积分抵扣**：
   - 用户选择使用积分，查询 `app_member.available_points`。
   - 校验积分是否充足：`可用积分 >= 用户输入的积分数`。
   - 计算积分抵扣金额：按配置比例（如 100 积分 = 1 元）计算 `积分抵扣金额 = 积分数 / 100`。
   - 校验积分抵扣上限：`积分抵扣金额 <= 订单总价 - 满减金额 - 优惠券抵扣`（通常积分最多抵扣订单金额的 50% 或配置上限）。
   - 更新订单总价：`订单总价 = 订单总价 - 积分抵扣金额`。

4. **金币抵扣**：
   - 用户选择使用金币，查询会员金币（`app_member.coins` 或独立金币表）。
   - 校验金币是否充足：`可用金币 >= 用户输入的金币数`。
   - 计算金币抵扣金额：按配置比例（如 100 金币 = 1 元）计算 `金币抵扣金额 = 金币数 / 100`。
   - 校验金币抵扣上限：`金币抵扣金额 <= 订单总价 - 满减金额 - 优惠券抵扣 - 积分抵扣金额`。
   - 更新订单总价：`订单总价 = 订单总价 - 金币抵扣金额`。

**步骤 4：运费计算**

1. 查询运费模板：根据收货地址（省市区）与商品 SKU 关联的运费模板（`mall_freight_template`）。
2. 计算运费：
   - 按重量：`运费 = 首费 + ceil((总重量 - 首重) / 续重) × 续费`。
   - 按件数：`运费 = 首费 + (件数 - 首件) × 续费`。
   - 包邮：若订单金额 ≥ 包邮金额或地址在包邮地区，则 `运费 = 0`。
3. 更新订单总价：`订单总价 = 订单总价 + 运费`。

**步骤 5：账户余额抵扣（可选）**

1. 用户选择使用账户余额，查询 `app_member.balance`。
2. 校验余额是否充足：`可用余额 >= 用户输入的余额金额`。
3. 校验余额抵扣上限：`余额抵扣金额 <= 订单总价`（余额可抵扣全部或部分）。
4. 更新订单总价：`订单总价 = 订单总价 - 余额抵扣金额`。

**步骤 6：实付金额计算**

```
实付金额 = 商品总价（含会员折扣）
         - 满减金额
         - 优惠券抵扣
         - 积分抵扣金额
         - 金币抵扣金额
         + 运费
         - 账户余额抵扣
```

**步骤 7：库存预扣减与订单生成（事务）**

1. **开启事务**。
2. **库存预扣减**：`mall_sku.stock = stock - 购买数量`（使用乐观锁或 Redis 预扣减）。
3. **生成订单**：
   - 插入 `mall_order`：记录总价、优惠、实付金额、积分/金币/余额使用量、运费、备注、发票信息等。
   - 插入 `mall_order_item`：记录商品明细、数量、单价、小计。
   - 插入 `mall_order_log`：记录订单创建日志。
4. **优惠券预占**：若使用优惠券，更新 `app_member_coupon.status = 1`（已使用，待支付成功后核销）。
5. **提交事务**。

**步骤 8：支付（异步）**

1. 用户选择支付方式（微信/支付宝/账户余额/组合支付）。
2. 调用支付接口，生成支付单。
3. 订单状态：`mall_order.status = 0`（待支付）。
4. 支付成功后回调：更新订单状态、核销优惠券、扣减积分/金币/余额、发放奖励（见 10.3）。

#### 10.1.3 关键判断点总结

| 判断项 | 校验逻辑 | 失败处理 |
|--------|----------|----------|
| 商品上架 | `status=1` 且（若开启审核）`audit_status=1` | 提示「商品已下架」或「商品审核中」 |
| 库存充足 | `stock >= 购买数量` | 提示「库存不足」 |
| 限购 | `已购数量 + 本次数量 ≤ limit_per_user` | 提示「超过限购数量」 |
| 积分充足 | `available_points >= 使用积分` | 提示「积分不足」 |
| 积分抵扣上限 | `积分抵扣金额 <= 订单总价 × 上限比例` | 提示「积分抵扣已达上限」 |
| 金币充足 | `coins >= 使用金币` | 提示「金币不足」 |
| 余额充足 | `balance >= 使用余额` | 提示「余额不足」 |
| 优惠券可用 | 状态、有效期、使用范围 | 提示「优惠券不可用」 |

---

### 10.2 商品审核流程（商户提交→平台审核）

#### 10.2.1 流程概述

商户新增、修改商品或申请上架时，若开启「商品需平台审核」，需提交审核；平台管理员审核通过后商品才生效或上架。

#### 10.2.2 详细流程步骤

**步骤 1：商户提交审核**

1. **判断是否开启审核**：查询 `mall_setting` 中 `config_key='product_audit_enabled'` 的值。
   - 若 `config_value='0'`（未开启），则商户保存/上架即生效，跳过审核。
   - 若 `config_value='1'`（已开启），进入审核流程。

2. **商户操作**：
   - **新增商品**：商户填写 SPU/SKU 信息后点击「保存并提交审核」。
   - **修改商品**：商户修改商品信息后点击「保存并提交审核」。
   - **申请上架**：商户对下架商品点击「申请上架」。

3. **更新 SPU 状态**：
   - `mall_spu.audit_status = 0`（待审核）。
   - 若为「申请上架」，`mall_spu.status` 仍保持 `0`（下架），待审核通过后改为 `1`（上架）。
   - 若为「新增/修改」，商品信息保存，但前台不展示（或保持下架）。

4. **可选：记录审核流水**：
   - 插入 `mall_product_audit_log`：`submit_time = 当前时间`，`audit_result = NULL`（待审核）。

**步骤 2：平台审核列表**

1. 平台管理员在后台「商品审核」列表中查看 `audit_status=0`（待审核）的商品。
2. 列表展示：SPU 名称、商户名称、提交时间、审核类型（新增/修改/申请上架）、商品信息预览。

**步骤 3：平台审核操作**

1. **审核通过**：
   - 平台管理员点击「通过」，可选填写备注。
   - 更新 `mall_spu`：
     - `audit_status = 1`（已通过）。
     - `audit_time = 当前时间`。
     - `audit_by = 当前管理员ID`。
     - 若为「申请上架」，`status = 1`（上架）。
   - 可选：更新 `mall_product_audit_log`：`audit_result = 1`（通过），`audit_time = 当前时间`。
   - 商品生效：新增/修改内容生效；申请上架的商品前台可售。

2. **审核驳回**：
   - 平台管理员点击「驳回」，**必填驳回原因**（`audit_remark`）。
   - 更新 `mall_spu`：
     - `audit_status = 2`（已驳回）。
     - `audit_remark = 驳回原因`。
     - `audit_time = 当前时间`。
     - `audit_by = 当前管理员ID`。
     - `status` 保持原状（若为申请上架，仍为下架）。
   - 可选：更新 `mall_product_audit_log`：`audit_result = 2`（驳回），`audit_remark = 驳回原因`。
   - 商品不生效：商户可查看驳回原因，修改后重新提交审核。

**步骤 4：商户查看审核结果**

1. 商户在「我的商品」中查看：
   - 待审核：`audit_status=0`。
   - 已通过：`audit_status=1`。
   - 已驳回：`audit_status=2`，显示驳回原因。

2. **重新提交**：若为已驳回，商户修改商品信息后重新提交，`audit_status` 重置为 `0`（待审核）。

#### 10.2.3 关键判断点总结

| 判断项 | 校验逻辑 | 处理 |
|--------|----------|------|
| 是否开启审核 | `mall_setting.product_audit_enabled = '1'` | 开启则走审核流程，否则直接生效 |
| 审核状态 | `audit_status`：0-待审核 1-已通过 2-已驳回 | 待审核商品前台不展示或保持下架 |
| 驳回必填原因 | `audit_remark` 不能为空 | 驳回时强制填写 |
| 申请上架 | `status=0` 且 `audit_status=1` 后改为 `status=1` | 审核通过后商品才上架 |

---

### 10.3 支付成功后的奖励发放流程

#### 10.3.1 流程概述

订单支付成功后，系统需发放：现金支付赠送（积分/金币）、三级分销奖励（积分/金币），并扣减已使用的积分/金币/余额、核销优惠券、增加会员成长值等。

#### 10.3.2 详细流程步骤

**步骤 1：支付回调处理（事务）**

1. **支付回调**：第三方支付（微信/支付宝）回调或账户余额/金币支付成功。
2. **幂等校验**：根据订单号查询订单状态，若已支付则直接返回，防止重复处理。
3. **开启事务**。

**步骤 2：订单状态更新**

1. 更新 `mall_order`：
   - `status = 1`（待发货）。
   - `pay_type = 支付方式`。
   - `pay_time = 当前时间`。

**步骤 3：扣减已使用的积分/金币/余额**

1. **扣减积分**：若 `points_used > 0`，调用 MemberService 扣减积分，记录 `app_member_points_log`（类型：订单使用）。
2. **扣减金币**：若 `coins_used > 0`，扣减会员金币，记录金币流水。
3. **扣减账户余额**：若 `balance_amount > 0`，扣减 `app_member.balance`，记录余额流水。

**步骤 4：核销优惠券**

1. 若订单使用了优惠券，更新 `app_member_coupon.status = 2`（已核销），记录核销时间。

**步骤 5：现金支付赠送（积分/金币）**

1. **查询消费人等级**：根据 `mall_order.member_id` 查询 `app_member.level_code`。
2. **查询赠送配置**：
   - 查询 `mall_reward_level_config`：先按 `level_code` 匹配，无则用 `member_level_code='DEFAULT'`。
   - 获取 `points_enabled`、`coins_enabled`、`points_per_yuan`、`coins_per_yuan`。
3. **计算赠送金额**：
   - 实付金额 = `pay_amount`（已扣除积分/金币/余额后的实付金额）。
   - 若 `points_enabled=1`：`赠送积分 = 实付金额 × points_per_yuan`。
   - 若 `coins_enabled=1`：`赠送金币 = 实付金额 × coins_per_yuan`。
4. **发放奖励**：
   - 调用 MemberService 增加积分，记录积分流水（类型：消费赠送）。
   - 增加会员金币，记录金币流水。

**步骤 6：三级分销奖励发放**

1. **查询推荐关系链**：
   - 消费人（一级）：`mall_order.member_id`。
   - 二级推荐人：查询 `app_member.inviter_id`（消费人的直接推荐人）。
   - 三级推荐人：查询二级推荐人的 `inviter_id`。

2. **发放二级奖励**（若存在二级推荐人）：
   - 查询二级推荐人的 `level_code`。
   - 查询 `mall_distribution_level_rate`：`distribution_level=2` 且 `member_level_code=二级推荐人等级`，无则用 `member_level_code='DEFAULT'`。
   - 获取 `points_enabled`、`coins_enabled`、`points_rate`、`coins_rate`。
   - 计算奖励：
     - 若 `points_enabled=1`：`奖励积分 = 实付金额 × points_rate`。
     - 若 `coins_enabled=1`：`奖励金币 = 实付金额 × coins_rate`。
   - 发放奖励并记录 `mall_distribution_log`。

3. **发放三级奖励**（若存在三级推荐人）：
   - 查询三级推荐人的 `level_code`。
   - 查询 `mall_distribution_level_rate`：`distribution_level=3` 且 `member_level_code=三级推荐人等级`，无则用 `member_level_code='DEFAULT'`。
   - 获取 `points_enabled`、`coins_enabled`、`points_rate`、`coins_rate`。
   - 计算并发放奖励，记录 `mall_distribution_log`。

**步骤 7：增加会员成长值与消费积分**

1. 调用 MemberApplicationService 增加会员成长值（按实付金额）。
2. 增加消费积分（若配置了消费获取积分）。

**步骤 8：提交事务**

1. 提交事务，完成支付成功后的所有处理。

#### 10.3.3 关键判断点总结

| 判断项 | 校验逻辑 | 处理 |
|--------|----------|------|
| 幂等性 | 订单状态已为「待发货」或「已完成」 | 直接返回，不重复处理 |
| 现金支付赠送开关 | `points_enabled`、`coins_enabled` | 仅当开启时发放对应奖励 |
| 消费人等级 | 查询 `level_code` → `mall_reward_level_config` | 按等级取对应赠送比例 |
| 推荐人存在 | `inviter_id` 不为空 | 存在才发放分销奖励 |
| 推荐人等级 | 查询推荐人 `level_code` → `mall_distribution_level_rate` | 按等级取对应分销比例 |
| 分销奖励开关 | `points_enabled`、`coins_enabled` | 仅当开启时发放对应奖励 |

---

## 十一、版本记录

本章所列**可补充功能已全部纳入上文各模块**，对应关系如下，便于对照与实施排期。

| 原补充项 | 已纳入章节 |
|----------|------------|
| **商户修改/上架商品需平台审核** | 3.1.3、3.1.3.1 |
| 商品收藏、商品咨询/问答、商品标签/卖点、单商品限购、预售 | 3.1.6～3.1.10 |
| 订单备注、运费/运费模板、发票管理、订单改价、到店自提 | 3.2.3、3.2.3.1、3.2.3.2 |
| 新人专享/首单优惠、会员价/专享价、赠品规则、加价购、积分兑换/积分商城、砍价/助力 | 3.3.6～3.3.11 |
| 会员消费与复购、库存预警报表、售后原因分析 | 3.4 数据统计；3.2.6 售后管理（退款原因） |
| 商城全局设置、订单/物流消息通知、搜索历史与热门搜索、浏览足迹 | 3.5.1～3.5.4 |

表结构见**四、核心表结构概览**（表 24～42）及**六、数据库表结构设计**（6.3.1～6.3.3）；接口见**七、接口设计要点**；实施阶段见**八、实施阶段建议**。后续新增通用能力时，可继续在本章补充清单并同步更新上文。

---

## 十、版本记录

| 版本 | 日期 | 说明 |
|------|------|------|
| 1.0.0 | 2026-01-24 | 初始功能设计，待评审后进入开发 |
| 1.0.1 | 2026-01-24 | 表前缀改为 mall_；新增支付方式：金币抵扣现金 |
| 1.0.2 | 2026-01-24 | 新增现金支付赠送积分、金币，支持配置消费 1 元赠送比例 |
| 1.0.3 | 2026-01-24 | 新增三级分销，订单完成按实付金额比例给推荐人发放积分或金币 |
| 1.0.4 | 2026-01-24 | 优化三级分销：一级=消费人，二级=直接推荐人，三级=间接推荐人 |
| 1.0.5 | 2026-01-24 | 新增目录、数据库表结构设计章节 |
| 1.0.6 | 2026-01-24 | 评分项可配置：新增 mall_rating_item、评价按配置维度打分 |
| 1.0.7 | 2026-01-24 | mall_reward_config 增加积分/金币独立开关：points_enabled、coins_enabled |
| 1.0.8 | 2026-01-24 | 三级分销按推荐人身份差异化：新增 mall_distribution_level_rate，推荐人等级不同则赠送积分/金币比例可配置不同 |
| 1.0.9 | 2026-01-24 | 三级分销优化：推荐人身份不同时积分与金币分别配置；config 表改为 level2/3_points_rate、level2/3_coins_rate；level_rate 表改为 points_rate、coins_rate，支持同一推荐人同时获得积分+金币且按等级差异化 |
| 1.0.10 | 2026-01-24 | 现金支付赠送按消费人身份差异化：新增 mall_reward_level_config，消费人会员等级不同可配置不同的 1 元送积分/金币数 |
| 1.0.11 | 2026-01-24 | mall_distribution_level_rate 增加 points_enabled、coins_enabled，每条按身份配置可独立控制该身份是否发放积分、是否发放金币 |
| 1.0.12 | 2026-01-24 | mall_reward_config 与 mall_reward_level_config 合并为一表，以 mall_reward_level_config 为主；约定 member_level_code='DEFAULT' 为默认配置，表内增加 points_enabled、coins_enabled |
| 1.0.13 | 2026-01-24 | mall_distribution_config 与 mall_distribution_level_rate 合并为一表，以 mall_distribution_level_rate 为主；约定 member_level_code='DEFAULT' 为该层级默认配置（如 2+DEFAULT、3+DEFAULT） |
| 1.0.14 | 2026-01-24 | 下单可使用账户余额：下单/支付支持使用会员账户余额（app_member.balance），可与微信/支付宝/金币组合；订单与会员集成增加「使用账户余额」与退款退回余额；mall_order 增加 balance_amount |
| 1.0.15 | 2026-01-24 | 新增「十一、商城通用可补充功能」：整理已有能力归纳，及商品/交易/营销/数据/基础等可补充功能清单（含优先级建议），便于评审与按需迭代 |
| 1.0.16 | 2026-01-24 | 将十一章可补充功能全部纳入正文：商品中心（收藏、问答、标签、限购、预售）、交易中心（订单备注/改价/发票、运费模板、到店自提）、营销中心（首单优惠、会员价、赠品、加价购、积分商城、砍价）、数据统计（会员消费与复购、库存预警、售后原因）、基础与体验（商城设置、消息通知、搜索历史、浏览足迹）；补充表结构、接口、实施阶段与集成关系；十一章改为「已纳入上文」对照表 |
| 1.0.17 | 2026-01-24 | 新增商户修改/上架商品需平台审核：3.1.3.1 商品审核（提交审核、平台通过/驳回、驳回原因）；mall_spu 增加 merchant_id、audit_status、audit_remark、audit_time、audit_by；可选 mall_product_audit_log；商城设置增加 product_audit_enabled；后台接口增加商品审核列表与审核操作 |
| 1.0.18 | 2026-01-24 | 新增「十、核心业务流程说明」：详细描述下单流程（商品校验、价格计算、优惠叠加、积分/金币/余额判断、库存扣减、订单生成）、商品审核流程（商户提交→平台审核→通过/驳回）、支付成功后奖励发放流程（现金支付赠送、三级分销）；包含关键判断点总结表 |
| 1.0.19 | 2026-01-24 | 设计约束增加实体类命名规范：所有实体类（Entity/Bean）必须加 `Mall` 前缀，避免与其他模块业务单元命名冲突（如 `MallCategory`、`MallOrder`），代码生成时需遵循此规则 |