Mall

受众：开发者摘要：spring-open-module-mall 商城：B2B2C 商户 / 店铺、商品 / SKU / 购物车 / 地址 / 订单 / 支付 / 评价 / 售后。

Mall 模块用于承载商城场景。当前提供 B2B2C 商户入驻、店铺、店铺角色、店铺员工、物流承运商、商品 / SKU 商户归属、店铺商品审核、商家自助控制台、资质和审核状态机，以及商品分类、商品、SKU、实物 / 虚拟 / 混合商品类型、商品搜索筛选、商品收藏、购物车、收货地址、下单、订单支付、支付状态同步、虚拟交付项、交易时间线、发货、确认收货、发票、商品评价、售后申请、秒杀活动、商品 / SKU 积分价规则、积分兑换 / 抵扣、订单奖励积分、退款奖励冲正、后台售后处理和退款 / 退货登记，满足 Admin / App / PC 三端商城基础交易闭环联调。

模块是可选依赖，应用不需要电商能力时可以移除 spring-open-module-mall 引用，不影响 CMS、Blog、Forum 或其他模块。

配置

yaml

spring:
  open:
    mall:
      enabled: true
      notifications:
        enabled: true
        channels:
          - database
        template: mall.order.status-changed
        after-sale-template: mall.after-sale.status-changed
      payment:
        default-method: balance
        method-order:
          - balance
          - wechat
          - alipay
          - web3
          - yungouos
          - union-pay
          - jd-pay
          - qq-pay
          - paypal
        balance-enabled: true
      trade:
        shipping-amount: 0
        free-shipping-threshold:
        payment-timeout-minutes: 30
        auto-complete-pure-virtual-orders: false
        virtual-delivery:
          inventory-warning:
            enabled: true
            threshold: 10
          encryption:
            enabled: true
            provider: config
            current-key-id: default
            keys:
              default: ${SPRING_OPEN_MALL_VIRTUAL_DELIVERY_ENCRYPTION_SECRET:}
            secret: ${SPRING_OPEN_MALL_VIRTUAL_DELIVERY_ENCRYPTION_SECRET:}
        timeout-release:
          enabled: true
          auto-startup: true
          fixed-delay: 5m
          task-name: mall.order.timeout-release
          instance-id: default
          limit: 100
      after-sales:
        auto:
          enabled: true
          auto-startup: true
          timeout: 24h
          action: closed
          fixed-delay: 10m
          task-name: mall.after-sale.auto-handle
          instance-id: default
          limit: 100
        refund-reconcile:
          enabled: true
          auto-startup: true
          fixed-delay: 10m
          task-name: mall.after-sale.refund-reconcile
          instance-id: default
          limit: 100
      merchant-settlement:
        settlement-delay: 7d
        auto-approval:
          enabled: true
          auto-startup: true
          timeout: 24h
          fixed-delay: 10m
          task-name: mall.merchant-settlement.auto-approval
          instance-id: default
          limit: 100

spring.open.mall.enabled=false 时，Mall Controller、Service 和 Mapper 扫描都会关闭。

spring.open.mall.notifications.enabled=false 时，不发送订单和售后状态通知。channels 默认只写入站内信，可以增加 websocket、mail、sms 等 Notification 通道。template 是订单状态通知模板编码，after-sale-template 是售后状态通知模板编码，模板不存在时使用 Mall 内置标题和正文。

spring.open.mall.payment.default-method 控制 Mall 直连支付 contract 的默认支付倾向，默认是 balance。用户侧 App / PC 不再用 Mall 支付方式元数据自行构建支付选择，而是把订单号交给统一收银台；法币、余额、Web3 代币等实际可用方式由收银台呈现。该配置为空时，GET /payment-methods 不会标记默认选中项；仍使用 Mall 直连支付 contract 的调用方应保持未选择状态，让用户自行选择支付方式。

spring.open.mall.payment.method-order 控制运营侧支付方式展示顺序，列表越靠前越优先显示；未列出的支付方式会按内置顺序追加。配置了 method-order 时，展示顺序以 method-order 为准；未配置时才使用 default-method 把可用默认方式前置。

spring.open.mall.payment.balance-enabled=false 时，余额支付会以 enabled=false 和 unavailableReason 返回，不会作为可用默认方式；即使前端仍提交 balance，后端也会拒绝扣款。需要关闭平台账户余额的系统只改这一个开关即可。

支付方式的 name、description 和 unavailableReason 会按当前 locale 解析多语言文案，同时返回 displayName、displayDescription 和 displayUnavailableReason 作为明确展示字段。框架内置支付方式使用 messages.mall.payment-method.<code>.name、messages.mall.payment-method.<code>.description 和 messages.mall.payment-method.<code>.unavailable 这类 key；数据库配置中的 i18n 文案优先，资源文件兜底，未命中时返回 Mall 内置原文。接口不返回 nameKey 或 descriptionKey，前端只消费已经解析后的用户可见文案。

商品分类同样返回展示文案：MallCategoryVO.displayName 和商品 displayCategoryName 会按 messages.mall.category.<code>.name 解析，未配置翻译时回退分类原始名称。前端展示分类名称时优先使用 display 字段，不维护独立硬编码翻译表。分类支持多级父子结构；公开商品列表和后台商品列表按父级分类筛选时会自动包含全部子级分类商品，避免运营选择一级类目后看不到下级商品。

spring.open.mall.trade.shipping-amount 控制第一阶段统一运费，默认 0。spring.open.mall.trade.free-shipping-threshold 为空时不启用满额包邮；配置金额后，订单商品金额大于等于该阈值时运费自动归零。spring.open.mall.trade.payment-timeout-minutes 控制待支付订单超时释放默认窗口，后台释放接口未传截止时间时使用该值计算超时订单。auto-complete-pure-virtual-orders=true 时，纯虚拟订单在全部虚拟交付项进入已交付或已查看后自动转为已完成；默认关闭，避免人工交付、售后观察或运营复核场景被提前完成。virtual-delivery.inventory-warning.enabled=true 时，后台会按商品和 SKU 的真实库存字段检查虚拟 / 混合商品库存池；threshold 默认 10，库存小于等于阈值进入低库存预警，库存为 0 或空值进入缺货预警。virtual-delivery.encryption.enabled=true 时，卡密、授权码和账号类敏感交付内容会使用 AES-GCM 写入 contentValue 密文载荷；默认 provider=config，从本地配置或数据库配置读取 current-key-id + keys 多版本密钥，密文会保存 key id，历史 key 保留在 keys 中即可继续解密旧内容。secret 是旧版单密钥兜底，未配置 keys 时继续用于写入和解密；旧格式密文没有 key id，因此切换到 keys 后仍应保留原 secret，直到旧密文全部完成轮换。需要接入 Vault、云 KMS 或自研密钥服务时，实现 MallVirtualDeliveryKeyProvider Spring Bean，并让 name() 与 provider 配置一致即可，不需要把云厂商 SDK 暴露给 Mall 业务代码。默认开启加密，缺少密钥时拒绝写入强敏感内容，避免悄悄明文落库。timeout-release 会在 Scheduler 可用时自动注册周期任务，默认每 5 分钟释放一次超时待支付订单。后续接入运费模板、地区规则和活动规则时，仍以这些配置作为轻量兜底。

spring.open.mall.after-sales.auto.* 控制待处理售后申请的超时自动处理。默认开启，超过 timeout 仍未人工处理时执行 action，支持 closed、rejected、approved。默认 closed 表示关闭售后申请，不自动批准退款 / 退货，避免资金安全场景因为无人审核而自动出款；确有自动通过需求时可以显式配置 approved。任务名称默认 mall.after-sale.auto-handle，会复用已有售后审核路径，因此状态事件、站内信通知和幂等字段保持一致。售后后台处理已接入审批工作流，流程编码为 mall.after-sale.review。

spring.open.mall.after-sales.refund-reconcile.* 控制售后退款 pending 状态自动回查。默认开启，任务名称为 mall.after-sale.refund-reconcile，会周期扫描已通过且退款仍为 pending 的售后单，使用原售后退款幂等号重放支付通道退款请求；支付通道返回 success / refunded 时，Mall 会统一完成余额、积分和全额退款优惠券返还，并发布售后状态事件。支付通道仍返回 pending / processing 时只记录可识别的退款流水号并继续等待，不会提前执行退款完成后的账务动作；退货退款在用户退货未签收前会跳过回查。

spring.open.mall.merchant-settlement.settlement-delay 控制订单商品签收后等待多久才允许进入商户结算，应用默认 7d，用于覆盖售后保护期并降低退款后商家余额追偿风险。生成结算单时，后端会把实际结算截止时间限制为 now - settlement-delay；如果请求周期还没到可结算日，则不会纳入刚签收的订单商品。

spring.open.mall.merchant-settlement.auto-approval.* 控制商户结算超时自动审核和入账。默认开启，结算单超过 timeout 仍为待审核、未冻结、未入账且商户已绑定主账号（owner_user_id 仍是当前店铺启用员工）时，Queue 延迟任务会投递到 mall-merchant-settlement 专用队列并自动审核、把结算净额入账商户主账号 Money 余额；Scheduler 只兜底队列不可用、消息漏投或异常断链。主账号缺失、币种不匹配、风控冻结或余额账本不可用时不会自动入账，仍保留给平台人工复审。商家到账后再通过 Money 提现流程提现。

上述 Mall 交易、支付、通知、虚拟交付、售后和商户结算自动化配置已由 MallServiceProvider 声明到 lifecycle 配置 schema。后台配置中心可以发现这些主干配置；虚拟交付多版本密钥和旧版单密钥会标记为敏感配置，生产环境建议改接 Vault、云 KMS 或自研密钥 Provider。

数据模型

当前核心交易表包括：

表	说明
`mall_merchant`	B2B2C 商户，保存商户编码、名称、联系人、资质 JSON、主账号用户 ID（`owner_user_id`，结算净应付入账其 Money 余额）、启停状态、审核状态和审核时间点
`mall_shop`	B2B2C 店铺，保存店铺类型（`merchant` / `self_operated`）、所属商户、店铺编码、名称、Logo、描述、开闭状态、审核状态和开闭时间点；自营店铺允许不绑定商户
`mall_shop_role`	B2B2C 店铺角色，保存店铺内角色编码、名称、权限码集合、启停状态和排序
`mall_shop_staff`	B2B2C 店铺员工，保存店铺与平台用户绑定、联系方式、启停状态、权限快照和加入 / 停用时间
`mall_shop_staff_role`	B2B2C 店铺员工角色关系，保存员工与角色的关联
`mall_logistics_carrier`	物流承运商基础资料，保存承运商编码、名称、联系电话、物流查询链接模板、启停状态和排序；迁移会预置顺丰、京东物流、中通、申通、圆通、韵达、EMS 和其他物流
`mall_category`	商品分类，包含父级、编码、名称、图标、排序和状态
`mall_product`	商品，包含商户 / 店铺归属、编码、名称、摘要、详情、图片、商品类型、虚拟交付提示、分类快照、价格、会员价、库存、销量、上下架状态、审核状态、发布时间和 SEO 信息
`mall_product_sku`	商品 SKU，包含商品、商户 / 店铺快照、编码、名称、规格 JSON、价格、会员价、库存、状态和排序
`mall_product_favorite`	商品收藏，使用 `user_id + product_id` 记录当前用户收藏关系
`mall_cart_item`	购物车条目，保存当前用户商品 / SKU 快照、商品类型、虚拟交付提示、数量、选中状态和价格锁定时间
`mall_address`	收货地址，保存当前用户地址簿和默认地址
`mall_order`	订单主表，保存订单号、用户、状态、商品金额、优惠金额、运费、应付金额、优惠 / 运费 / 积分抵扣承担方、支付摘要、发货、发票和收货地址快照
`mall_order_item`	订单商品表，保存商户 / 店铺、商品 / SKU、商品类型、虚拟交付提示、数量、金额、原价 / 会员价 / 活动快照、费用承担方、价格锁定和子订单履约快照
`mall_virtual_delivery_item`	虚拟交付项，保存订单商品、用户、交付类型、交付状态、受控查看内容、资源链接、幂等操作键和查看时间
`mall_virtual_delivery_log`	虚拟交付审计日志，记录自动生成、交付、后台补发和受控查看动作
`mall_seckill_activity`	秒杀活动，保存活动编码、商品 / SKU、秒杀价、库存、已售、限购、活动时间和上下线状态
`mall_seckill_order`	秒杀订单关联表，保存活动、用户、订单、数量、锁定 / 已支付 / 已释放状态和幂等键
`mall_review`	商品评价，记录用户、订单、订单商品、商户 / 店铺 / 商品快照、评分、内容、图片、审核状态和商户回复
`mall_after_sale`	售后申请，记录售后单号、用户、订单商品、类型、状态、申请金额、原因、凭证、证明文件状态、退款 / 退货处理信息、商户责任和平台仲裁快照
`mall_merchant_settlement`	B2B2C 商户结算单，记录商户、店铺、结算周期、币种、商品结算基数、平台佣金、应结金额、审核状态、余额入账状态、对账状态和风控状态
`mall_merchant_settlement_item`	B2B2C 商户结算明细账本，按订单商品快照商品 / SKU、金额、佣金、应结金额和确认收货时间，并用 `order_item_id` 唯一约束防重复结算
`mall_coupon_template`	优惠券模板，保存券类型、面额 / 折扣、门槛、适用范围、领取方式、总量、每人限制和有效期
`mall_user_coupon`	用户券，保存用户、模板快照、券码、状态、领取时间、有效期、锁定订单和使用订单
`mall_coupon_usage_log`	优惠券生命周期日志，记录领取、锁定、核销、释放、过期和返还等动作

内置演示数据

新环境会随 Mall 模块插入少量演示数据，包含 3 个商品分类、3 个商品、3 个 SKU 和 1 张满减券。它们用于让商品列表、商品详情、SKU、领券和结算入口在安装后立即可体验，数量刻意保持很少，方便管理员清理和替换。

这些数据使用稳定商品编码、SKU 编码和券模板编码。后台提供受控清理入口，只会按这批稳定编码定位数据，并在执行前展示待清理清单；如果这些数据已经出现在购物车、订单、收藏、评价或用户已领取优惠券中，后端会拒绝自动清理，避免误删真实业务痕迹。

演示数据清理是多业务模块治理能力，不是 Mall 专属能力。每个模块接入时都应返回自己的 moduleCode、cleanupType 和确认短语，执行请求必须把这些防护字段原样提交，防止管理员在错误模块或错误数据类型上误触发清理。

后台清理接口由 Install 统一聚合，Mall 作为其中一个业务模块贡献方：

http

GET  /api/v1/admin/install/quickstart-cleanups
POST /api/v1/admin/install/quickstart-cleanups
GET  /api/v1/admin/install/quickstart-cleanups/mall
POST /api/v1/admin/install/quickstart-cleanups/mall

GET /api/v1/admin/install/quickstart-cleanups/mall 返回待清理的分类、商品、SKU、优惠券模板编码，以及购物车、订单、收藏、评价和用户券阻塞数量；同时返回执行时必须提交的 moduleCode=mall、cleanupType=quickstart-data 和确认短语。
POST /api/v1/admin/install/quickstart-cleanups/mall 需要提交 moduleCode=mall、cleanupType=quickstart-data 和确认短语 清理商城快速体验数据。执行权限使用 install:quickstart-cleanup:execute，默认仅 super-admin 预置；存在任一用户交互阻塞时返回业务错误，不做部分删除。

状态字段统一使用：

值	说明
`0`	草稿
`1`	已发布
`2`	已下线

公开接口只返回已发布、未删除、发布时间不晚于当前时间，且公开可售范围仍有效的商品：历史无店铺归属商品按平台自营处理；自营店铺商品要求店铺已审核通过且开启；第三方商户店铺商品还要求所属商户已审核通过且启用。分类公开接口只返回已发布分类；商品分页的 categoryId / categoryCode 支持父级分类语义，会把该分类及其所有子级分类商品一起纳入结果。

公共只读接口

所有接口的 JSON 响应体使用 Result<T>。

http

GET /api/v1/mall/categories
GET /api/v1/mall/products
GET /api/v1/mall/products/{id}
GET /api/v1/mall/products/{id}/reviews
POST /api/v1/mall/products/{id}/favorites
DELETE /api/v1/mall/products/{id}/favorites
GET /api/v1/mall/me/favorites
GET /api/v1/mall/seckill-activities
GET /api/v1/mall/seckill-activities/{id}

商品列表支持：

http

page=1
size=10
keyword=phone
categoryId=100
categoryCode=digital
productType=virtual
minPrice=1
maxPrice=999
sort=price-asc

当前排序值：

值	说明
`price-asc`	价格升序
`price-desc`	价格降序
`sales-desc`	销量降序

未传排序时，按 sortOrder 升序、id 倒序返回。

商品响应会把 coverUrl 和 imageUrls 同步投影为 mediaAssets。前端可以直接读取其中的素材类型、预览 URL、缩略图 URL、内容安全 scene 和排序，不需要自行解析 URL 后缀或拼接内容安全场景；保存商品时仍沿用原有 coverUrl / imageUrls contract。

购物车条目、订单商品和售后可选商品会把商品快照 coverUrl 同步投影为 mediaAssets。对应内容安全 scene 分别为 mall.cart-item.coverUrl、mall.order-item.coverUrl 和 mall.after-sale-item.coverUrl，前端交易卡片可以直接消费统一媒体资产字段展示封面、缩略图和素材类型。

秒杀活动只返回已开启、未删除且处于活动时间窗口内的商品活动。公开列表支持按商品筛选，响应包含活动编码、商品 / SKU 快照、秒杀价、币种、活动库存、已售数量、每人限购、开始 / 结束时间和剩余库存；前端应直接使用这些字段展示活动卡片，不自行推导库存或活动状态。

商品类型

商品类型由后端统一保存和快照，前端只按接口返回字段展示，不自行推导：

值	说明
`physical`	实物商品，默认值
`virtual`	虚拟商品，例如课程、资源、卡密、授权码
`mixed`	混合商品，同时包含实物和虚拟权益

虚拟交付类型：

值	说明
`resource-link`	资源链接、网盘链接或后续 Storage 私有签名链接
`card-key`	卡密、兑换码、激活码
`license-code`	授权码、会员兑换码
`account`	账号类交付，敏感内容默认加密存储并通过受控 reveal 审计查看
`manual-virtual`	人工审核或人工补发，虚拟 / 混合商品未传交付类型时默认使用

当前已完成虚拟商品第一阶段交付闭环：

商品保存、商品详情、购物车快照、订单商品快照都会返回 productType、virtualDeliveryType 和 virtualDeliveryNote。
订单详情中的快照字段只用于前端展示交付预期，不承载真实卡密、账号密码或下载密钥。
支付成功后，虚拟 / 混合订单商品会按订单项幂等生成 mall_virtual_delivery_item。
virtualDeliveryNote 为资源链接或交付提示时，可作为第一阶段自动交付内容写入交付项；manual-virtual 默认生成待人工交付项。
用户只能查看自己已支付订单的交付项，默认列表返回脱敏内容；点击查看时走受控 reveal 接口。卡密、授权码和账号类交付会返回 sensitive=true，未 reveal 时 contentValue 始终为空，前端只展示 contentMask。
后台可以查看订单交付项，并通过 operationKey 幂等补发 / 人工交付；对已交付、已查看或失败的交付项，可使用重发接口更新内容并追加 resent 审计。
后台可以通过 GET /api/v1/admin/mall/orders/deliveries/pending 查询待人工交付或待内容补齐的虚拟交付项，并通过 GET /api/v1/admin/mall/orders/deliveries/pending/summary 查看待处理、敏感待处理和人工待处理统计，用于运营预警。
后台可以通过 GET /api/v1/admin/mall/orders/deliveries/inventory-warnings 查询虚拟 / 混合商品真实库存池预警。该接口返回商品级和 SKU 级库存、阈值、warningLevel 和本地化展示文案，适合运营提前补充卡密、授权码、账号或资源库存。订单扣减虚拟 / 混合商品或 SKU 库存后，如果库存小于等于阈值，会发布通知规则事件 mall.virtual-delivery.inventory-low-stock；扣到 0 或以下时发布 mall.virtual-delivery.inventory-out-of-stock，运营可在Notification 通知规则中配置接收人、通道、去重和静默窗口。
后台可以通过 POST /api/v1/admin/mall/orders/{id}/deliveries/batch 批量导入卡密、授权码、账号或资源链接，按订单商品待处理交付项顺序填充；请求级 operationKey 会自动扩展为逐条幂等键。
后台可以作废误发、补发后废弃或售后需要冻结的交付项；作废后清空明文内容和访问地址，用户不可再 reveal。
后台可以查看交付项审计日志，覆盖平台自动生成、自动交付、后台人工交付、后台重发、后台作废、用户受控查看和管理员受控查看。
用户发起虚拟 / 混合商品售后时，售后单会快照 virtualDeliveryStatus、virtualDeliveryViewed 和 reviewStrategy。未查看 / 未领取记录为 virtual-unviewed，已查看 / 已领取记录为 virtual-viewed，方便后续自动退款或人工审核策略基于售后申请时的交付状态判断。

第一阶段先提供受控查看、敏感类型标识、非 reveal 明文护栏、后台补发、批量导入、后台待处理预警、真实库存池预警、后台重发、后台作废、售后查看状态快照和操作审计。卡密、账号密码、授权码等强敏感内容已经按配置写入 AES-GCM 密文载荷，并支持多版本密钥轮换；生产如需 Vault / KMS，只需按 MallVirtualDeliveryKeyProvider 扩展密钥来源。

收藏接口需要登录态：

POST /products/{id}/favorites 为幂等收藏，重复收藏仍返回成功。
DELETE /products/{id}/favorites 为幂等取消收藏，未收藏时仍返回成功。
GET /me/favorites 返回当前用户收藏商品分页，只返回仍处于发布状态的商品。

用户交易接口

购物车、地址和订单接口都需要登录态。

http

GET    /api/v1/mall/cart/items
POST   /api/v1/mall/cart/items
PUT    /api/v1/mall/cart/items/{id}
DELETE /api/v1/mall/cart/items/{id}
PUT    /api/v1/mall/cart/items/batch
DELETE /api/v1/mall/cart/items

GET    /api/v1/mall/addresses
POST   /api/v1/mall/addresses
PUT    /api/v1/mall/addresses/{id}
PUT    /api/v1/mall/addresses/{id}/default
DELETE /api/v1/mall/addresses/{id}

POST   /api/v1/mall/orders
POST   /api/v1/mall/orders/preview
POST   /api/v1/mall/orders/coupons
POST   /api/v1/mall/seckill-activities/{id}/orders
GET    /api/v1/mall/orders
GET    /api/v1/mall/orders/{id}
GET    /api/v1/mall/orders/{id}/timeline
GET    /api/v1/mall/orders/{id}/deliveries
POST   /api/v1/mall/orders/deliveries/{deliveryId}/reveal
GET    /api/v1/mall/orders/{id}/payment/status
GET    /api/v1/mall/payment-methods
POST   /api/v1/mall/orders/{id}/pay
POST   /api/v1/mall/orders/{id}/payment/sync
POST   /api/v1/mall/orders/{id}/cancel
POST   /api/v1/mall/orders/{id}/receipt/confirm
POST   /api/v1/mall/orders/{id}/invoice
GET    /api/v1/mall/orders/{id}/after-sale-items

GET    /api/v1/mall/me/reviews
POST   /api/v1/mall/reviews

GET    /api/v1/mall/me/after-sales
GET    /api/v1/mall/after-sales/{id}
POST   /api/v1/mall/orders/{id}/after-sales
POST   /api/v1/mall/after-sales/{id}/return-logistics

GET    /api/v1/mall/coupons/claimable
POST   /api/v1/mall/coupons/{templateId}/claim
GET    /api/v1/mall/coupons/mine
GET    /api/v1/mall/coupons/mine/{id}

购物车添加同一商品 / SKU 会自动合并数量。加入购物车时会保存商品 / SKU 快照和 priceLockedAt，创建订单时会重新读取商品和 SKU 当前发布状态、价格与库存，并要求 SKU 的商户 / 店铺归属与商品一致，写入商户 / 店铺、商品 / SKU 和金额快照，并扣减商品库存和 SKU 库存；创建成功后删除对应购物车条目。取消待支付订单时会恢复商品库存和 SKU 库存。

批量购物车语义：

PUT /cart/items/batch 支持批量更新数量和选中状态。
DELETE /cart/items 使用请求体传 ID 列表，避免 URL 过长。
创建订单只接受当前用户已选中的购物车条目，避免前端误把未选中商品带入订单。

订单预览：

POST /orders/preview 和 POST /orders 使用同一个下单请求体。
预览会校验地址、购物车条目、商品 / SKU 发布状态、库存、数量和金额。
预览在 Pipeline starter 可用时会先执行 mall.order.preview，内置步骤覆盖请求 / 地址 / 购物车快照、商品项数量和币种一致性；Pipeline 中断会转为 Mall 业务错误，不向前端暴露内部执行细节。
预览会返回商品金额、优惠金额、运费、积分应付、积分抵扣、最终现金应付、币种、优惠码、地址快照、订单商品快照和店铺子订单快照。
subOrders 按 merchantId + shopId 拆分店铺子订单，返回子订单商品、商品金额、优惠 / 运费 / 积分抵扣、现金应付分摊、shippingStatus、物流公司、物流单号、发货时间和签收时间；存在多个子订单时 parentOrder=true 且 subOrderCount 返回子订单数量，父订单负责统一支付。
预览不会创建订单、不会扣减库存、不会锁定优惠券、不会删除购物车条目，适合结算页在提交订单前展示价格锁定结果。
预览和真实下单共用同一套金额计算逻辑，避免前端展示金额和最终订单金额不一致。
POST /orders/coupons 使用同一个结算请求体，返回当前购物车下的可用券 / 不可用券列表、可抵扣金额、使用后应付金额和不可用原因，适合 App / PC 在结算页让用户选券。

订单金额语义：

productAmount 是订单商品金额合计。
discountAmount 是优惠金额；优惠券、会员价和秒杀活动价都会进入同一订单优惠口径。
shippingAmount 是运费；第一阶段默认 0，后续接运费模板。
pointsAmount 是本次预览需要消耗的积分总额。
pointsDiscountAmount 是积分抵扣掉的现金金额。
cashPayableAmount 是最终现金应付金额。
payableAmount 是实际现金应付金额，当前等同 cashPayableAmount。
totalAmount 当前等同 payableAmount，保留给兼容支付模块和报表读取。
discountBearerType、shippingFeeBearerType 和 pointsDiscountBearerType 分别记录优惠、运费和积分抵扣承担方；当前会员价 / 秒杀差额由商户承担，优惠券、满额包邮和积分抵扣由平台承担。
创建订单支持 couponCode、voucherId 和 idempotencyKey。同一用户同一个 idempotencyKey 重复下单会返回已有订单，避免前端重复提交；couponCode 与 voucherId 互斥。
创建订单在 Pipeline starter 可用时会先执行 mall.order.create.prepare，内置步骤覆盖下单命令、地址、购物车条目、只读库存和币种一致性；Pipeline 中断会在扣库存、锁券、建单和删除购物车前转为 Mall 业务错误。
运费第一阶段来自 spring.open.mall.trade.shipping-amount，满额包邮来自 spring.open.mall.trade.free-shipping-threshold。
商品和 SKU 可保存 memberPrice。订单预览和下单会优先使用 SKU 会员价，未配置时回退商品会员价；只有会员价低于当前现金价时才作为成交价，并在订单商品返回 originalUnitPrice、memberUnitPrice、promotionType=member_price、promotionName 和费用承担方快照。

优惠券：

GET /coupons/claimable 返回当前可手动领取的优惠券模板，只返回已发布、未删除、处于有效期内且仍有剩余数量的模板。
POST /coupons/{templateId}/claim 为当前用户领取优惠券，会校验领取方式、有效期、总量和每人领取上限。
GET /coupons/mine 返回当前用户优惠券分页，可按状态、券类型和关键词筛选。
GET /coupons/mine/{id} 返回当前用户某张券详情，只能读取自己的券。
券类型包括 amount（满减）、discount（折扣，支持最高优惠）和 shipping（运费券）。
后台可维护优惠券模板，并查看用户券发放情况；用户领取会写入 mall_coupon_usage_log 生命周期日志。
订单预览和下单都可以传 couponCode。后端会重新校验用户券归属、状态、有效期、门槛、适用范围和金额，不信任前端计算结果。
订单预览和下单也可以传 voucherId 使用 Core Voucher 通用卡券。Mall 只读取 Voucher 实例和模板并按自身结算规则计算优惠，下单锁定 Voucher，支付成功确认核销，取消订单释放锁定；订单只保存 voucherId、voucherLockId、voucherUsageId 快照。
POST /orders/coupons 会按当前购物车金额、运费和商品范围拆分可用 / 不可用券，并返回状态不可用、未开始、已过期、未达门槛、适用范围不匹配等原因。
预览只计算 discountAmount，不锁券、不扣库存、不删除购物车。
下单成功后会锁定用户券，支付成功后核销为 used，待支付订单取消时释放回 available。
折扣券的 discountRate 按应付倍率理解，例如 0.8 表示八折；maxDiscountAmount 用于限制最高优惠。
后台可通过 POST /api/v1/admin/mall/orders/expired/release 批量释放超时待支付订单，释放逻辑复用取消订单链路，会恢复库存并把锁定用户券释放回 available。Scheduler 可用时会按 spring.open.mall.trade.timeout-release.fixed-delay 自动周期触发同一 Service 能力。售后全额退款后会返还订单已使用优惠券；部分退款不返还，避免优惠券在部分售后中被误放回。待处理售后会按 spring.open.mall.after-sales.auto.* 自动处理超时申请，默认关闭申请，不自动退款。

秒杀订单：

POST /seckill-activities/{id}/orders 用于当前登录用户直接从秒杀活动创建待支付订单。请求字段为 addressId、quantity、remark 和 idempotencyKey。
后端会校验活动已开启、时间窗口有效、活动商品和 SKU 仍发布、活动库存足够、用户累计购买量未超过 perUserLimit，再锁定活动库存并扣减商品 / SKU 库存。
秒杀下单不经过购物车，不接受优惠券叠加；App / PC 结算页在 seckillActivityId 模式下应隐藏或禁用优惠券入口。
秒杀订单支付成功时，Mall 会把对应秒杀锁定记录转为已支付并累加活动已售数量；待支付订单取消或超时释放时，会释放活动库存并恢复商品 / SKU 库存。
秒杀订单商品会写入 promotionType=seckill、活动 ID、活动名称、原价快照和商户承担方快照，订单详情无需再反查活动表才能解释活动价来源。

支付入口说明：

GET /payment-methods 返回用户侧可展示的支付方式元数据，包括 code、name、displayName、icon、logoUrl、description、displayDescription、supportedEnvironments、recommended、enabled、unavailableReason、displayUnavailableReason 和 defaultSelected。
返回列表顺序已经按 spring.open.mall.payment.method-order 或 default-method 调整；前端不需要也不应该依赖额外全局 defaultMethod 字段。
只有 defaultSelected=true 且当前支付环境可用时，使用 Mall 直连支付 contract 的前端才可以自动选中该支付方式；没有默认值时必须保持未选择状态，让用户自行选择，避免默认选中造成困扰。
用户侧 App / PC 的订单付款入口应优先打开统一收银台，不在 Mall 页面内单独维护支付方式选择；如需要展示支付摘要，应优先使用 displayName、icon、logoUrl、displayDescription 和 supportedEnvironments，不要把 gateway、provider 或生态库名称作为普通用户可见支付名称。
displayName、displayDescription 和 displayUnavailableReason 已按当前语言解析，前端不需要也不应该自行拼接多语言 key。
POST /orders/{id}/pay 只允许待支付订单调用。
请求可以传 gateway、provider、scene、clientIp、notifyUrl、returnUrl 和 attributes。
Pipeline 可用时，POST /orders/{id}/pay 会先执行 mall.order.pay.prepare，校验订单可支付状态、支付金额 / 币种、支付场景和余额支付可用性。Pipeline 中断发生在 Payment Provider 调用、收银台订单写入、订单状态更新、优惠券 / 积分 / 秒杀确认和虚拟交付之前。
App / PC 可按页面需要展示支付方式元数据的一部分：订单详情 / 支付结果只展示简洁支付名称，完整支付选择交给统一收银台。
App、H5、PC、注入钱包浏览环境等不同运行环境由统一收银台识别并选择合适的支付交互；Mall 直连支付 contract 仍可接收 scene 和 attributes.paymentEnvironment，再由 Payment Facade 和具体 Provider 决定跳转、钱包签名或兜底提示。
balance 表示平台账户余额支付。Mall 只调用 Payment Facade，Money 用户余额模块通过 balance Payment provider 提供扣款和退款实现，按 mall-order:<订单号>:consume 幂等扣减可用余额，并把余额流水 ID 写入支付结果 payload。
余额支付订单发生售后退款并标记退款成功后，Mall 会按 mall-order:<订单号>:after-sale:<售后单ID>:refund 幂等写入用户余额 refund 流水，避免订单售后状态和余额账本脱节。
web3 表示外部 Web3 钱包支付。用户侧页面不单开 Web3 支付入口；Mall 把可支付订单交给统一收银台后，由收银台在检测到钱包签名能力时展示 Web3 代币支付并处理链上交易参数，tx hash 仍通过支付同步链路回传。钱包交易由用户自行签名，Mall / Payment / Web3 starter 不托管私钥、不替用户广播。
不具备钱包签名能力的运行环境不能直接完成 Web3 代币付款；前端应使用中性提示说明“当前环境未检测到可用的钱包签名能力”，并允许用户稍后在支持注入钱包的浏览环境中重试或手动同步交易状态。
后续如增加 web3-balance，它应表示平台内 Web3 资产余额，不等同于外部钱包支付；多币种和汇率需要在余额账本中保存币种、汇率快照和折算金额，Mall 订单只保存订单金额、币种和支付摘要。
积分购买不等同于余额支付：积分账户、积分冻结、积分扣减、积分退回、订单奖励和退款奖励冲正由 Member Points + Money 账本承接；Mall 订单只保存积分价格、积分抵扣、现金支付和奖励关联快照，不直接写积分余额表。
未传 gateway 和 provider 时，如果 default-method=balance，Mall 会优先按余额支付处理；显式传其他 gateway / provider 时才进入 Payment 模块默认链路，本地开发默认 mock。
Mall 对第三方收银台只调用 Payment Facade，不直接依赖 Cashier 支付运维表，也不暴露支付宝、微信或 IJPay API；余额支付统一走 Payment provider balance，由 Money 用户余额模块提供实现。订单 / 售后状态可靠投递则通过条件装配的 Outbox contract 写入，不复用支付运维表。
Payment 返回 success 状态时，订单会更新为已支付并写入支付时间。
clientIp、notifyUrl、returnUrl 会写入订单支付摘要，订单详情会返回 paymentClientIp、paymentNotifyUrl、paymentReturnUrl，方便 PC / App 在支付回跳页做状态同步和展示。
POST /orders/{id}/payment/sync 默认重新读取订单本地支付快照并补齐已支付订单的虚拟交付；当订单支付摘要或请求字段明确为 web3 且带有 transactionId / attributes.web3TransactionHash 时，会通过 Payment/Web3 query 查询链上确认结果，确认成功后执行 Mall 支付成功副作用、状态事件和虚拟交付。
GET /orders/{id}/payment/status 只读取本地订单支付快照，不触发第三方支付查询，适合支付回跳页高频轮询。
后台也提供 GET /api/v1/admin/mall/orders/{id}/payment/status，用于 Admin 查看本地支付摘要。

订单状态事件：

订单支付成功和取消订单时，Mall 会发布 MallOrderStatusChangedEvent；普通支付状态同步入口只刷新本地快照，Web3 带 tx hash 同步确认成功时会发布支付成功状态变更。
事件包含订单 ID、订单号、用户 ID、变更前后状态、变更原因和支付摘要字段。
在装配 Outbox contract 时，订单状态变更会先同事务写入 mall-order-status / mall.order.status-changed Outbox 事件，幂等键为 mall-order:status:<orderId>:<previousStatus>:<currentStatus>:<reason>。
Mall 内置一个事务提交后的订单状态通知监听器，通过 Notification Facade 向订单用户发送通知；默认通道是站内信。
订单进入已支付状态时还会发布 mall.order.fulfillment-pending 通知规则事件源，默认未配置接收人时静默跳过；运营可在 Notification 通知规则中配置后台履约提醒的通道、接收人、去重和静默窗口。
订单状态通知失败只记录日志，不回滚订单支付、取消或状态同步结果。
后续仍可在应用装配层继续监听该事件，扩展 Queue 任务、支付回调桥接、售后联动或更多业务通知。

Mall 也提供统一补偿命令 handler：

consumer=mall、commandType=mall.order.release-expired-pending：payload 支持 expiredBefore 和 limit，用于通过 Outbox 运维页手动入队 / 重放超时待支付订单释放动作；字段为空时沿用 Mall 订单服务默认超时窗口和数量口径。
consumer=mall、commandType=mall.after-sale.refund-balance：payload 必须包含 orderId、afterSaleId 和 amount，reason 可选；执行时复用 Mall 订单余额退款能力，适合售后退款链路失败后的人工入队 / 重放。
consumer=mall、commandType=mall.order.refund-coupon：payload 必须包含 orderId，reason 可选；执行时复用 Mall 订单优惠券退回能力，适合售后退款链路中优惠券释放失败后的人工入队 / 重放。
consumer=mall、commandType=mall.after-sale.reconcile-refund：payload 可传 afterSaleId 定向回查单个售后退款，或传 limit 批量回查 pending 退款；执行时重放原支付通道退款请求，Provider 仍返回 pending / processing 时命令保持失败重试节奏，返回 success / refunded 后统一完成余额、积分和优惠券返还。

交易时间线：

GET /orders/{id}/timeline 返回当前用户订单的交易时间线。
时间线节点包含订单创建、发起支付、支付成功、发货、确认收货、申请开票、发票开具、订单取消和售后相关节点。
每个节点包含 code、title、description、completed、occurredAt 和 attributes。
App / PC 可以直接使用该接口展示订单进度、履约进度、发票进度和售后进度，不需要在前端自行拼接多个状态字段。
attributes 只用于展示摘要，例如订单号、支付状态、交易号、物流公司、物流单号、发票号、售后单号、退款流水等。

订单状态：

值	说明
`10`	待支付
`20`	已支付
`30`	已发货
`40`	已完成
`90`	已取消

当前取消订单只允许待支付订单执行；支付后可由后台整单发货，也可通过店铺子订单发货接口只发某个 shopId。发货请求可以传 carrierCode 引用后台维护的启用物流承运商，此时后端会用承运商名称写入物流公司快照；也可以继续只传 logisticsCompany 手工填写物流公司。部分店铺发货时父订单保持已支付并返回 shippingStatus=partial_shipped；全部店铺子订单都发货后父订单进入已发货，用户确认收货后订单商品和店铺子订单履约快照进入已签收。后台售后发起退款时，退款流水号可选：留空会按订单支付摘要通过 Payment Facade 尝试原支付通道退款；人工或外部流程已退款时再填写退款流水号作为结果登记。

发票接口：

用户可对已支付、已发货或已完成订单发起开票申请。
后台可登记发票号、发票链接和开票结果。
后台开票接口支持 operationKey 幂等键，避免重复操作。

商品评价说明：

GET /products/{id}/reviews 只返回已发布评价，并会校验商品本身仍可公开读取。
GET /me/reviews 返回当前用户评价分页。
POST /reviews 需要登录态，只允许基于当前用户已发货或已完成的订单商品创建评价，待支付 / 已支付未发货订单不可提前评价。
同一用户同一个订单商品只能评价一次。
评价创建时会从商品快照派生 merchantId、shopId、productCode 和 productName，避免后续商品改名或迁店影响历史评价归属。
评价响应不暴露订单和订单商品内部 ID；评价保存评分、内容和图片 URL 字符串，并把 imageUrls 同步投影为 mediaAssets，供前端统一展示评价图片和内容安全 scene。
后台和商家控制台均可按店铺分页查看已发布评价，筛选评分和是否已回复；店铺信誉摘要实时统计已发布评价数量、平均评分、好评数、差评数、已回复数和最近评价时间。
平台运营回复评价使用 POST /api/v1/admin/mall/reviews/{id}/reply；商家在自助控制台使用 POST /api/v1/mall/merchant-console/reviews/{id}/reply，后端会按评价 shopId 复核当前商家员工店铺权限，写入 merchantReply 与 merchantRepliedAt；查看和回复权限分别为 mall:review:view、mall:review:reply。追评和更细审核流后续扩展。
App / PC 商品详情评价列表和我的评价页会展示 merchantReply；前端仍兼容历史 replyContent 字段，避免旧接口响应下商家回复空白。
Admin 评价信誉页按店铺维度消费上述接口：先选择已审核店铺，再查看信誉指标、评分 / 回复状态筛选后的评价列表，并在回复弹窗中提交真实商户 / 运营回复；接口失败时只展示真实错误和空态。
PC 商家工作台 /account/mall-merchant 已接入评价 tab，商家可查看当前店铺评价、信誉摘要并回复自己店铺的评价；店主入驻默认权限和店铺角色可分配权限均包含 mall:review:view / mall:review:reply。

Mall 模块还通过 core UserActivitySource 向 Runtime 用户动态聚合出口贡献当前用户的已发布商品评价。动态类型为 mall.review，打开入口使用 PC 产品路由 /mall/{productId}；用户动态出口仍走 core contract，不直接读取其他模块用户动态表。

售后申请说明：

GET /me/after-sales 返回当前用户售后申请分页，可按 status 过滤。
GET /after-sales/{id} 只返回当前用户自己的售后申请。
GET /orders/{id}/after-sale-items 返回订单商品快照、是否可申请售后、是否已有处理中售后和对应售后状态。用户界面应展示商品名称、SKU、数量、金额和“可申请 / 处理中”状态，orderItemId 只作为发起售后时的内部提交字段，不应当作为让用户手动填写的表单项。
POST /orders/{id}/after-sales 需要登录态，只允许基于当前用户的已支付订单商品创建售后申请。
POST /after-sales/{id}/return-logistics 用于用户提交退货物流，只允许已通过且待退货的售后申请；接口支持 operationKey 幂等，字段包括物流公司、物流单号和备注。
售后类型当前支持 refund、return-refund 和 exchange，未传时默认 refund。
未传 applyAmount 时默认使用订单商品金额；传入金额不能大于订单商品金额。
同一用户同一个订单商品同一时间只允许存在一个未关闭售后申请。
售后申请可以继续传 proofUrls，也可以传 proofFileIds 关联当前用户上传的文件元数据 ID。Mall 只保存标量文件 ID，不直接依赖 File 模块实现。proofFileIds 是前后端内部传输字段，用户侧页面只能提供证明文件上传、预览和移除交互，不应让普通用户手动输入或直接查看文件 ID。
proofStatus 表达证明文件生命周期，当前值为 submitted、accepted、rejected、archived。
refundStatus 表达退款状态，当前值为 none、pending、success、failed。
returnStatus 表达退货状态，当前值为 none、pending、received、rejected。
B2B2C 售后会返回商户责任和平台仲裁快照：merchantResponsibility / platformArbitrationResult 当前值为 none、merchant、buyer、platform、shared，platformArbitrationStatus 当前值为 none、pending、accepted、rejected、closed。后台审批、驳回、关闭、退货收货和退款处理请求均可传入这些字段，平台会随售后处理动作固化责任归因和仲裁时间。
虚拟 / 混合商品售后会返回 virtualDeliveryStatus、virtualDeliveryViewed 和 reviewStrategy，用于前端展示售后审核提示或后台判断后续处理策略。普通用户界面不需要展示这些技术字段，可转换为“未查看，通常更适合自动退款”或“已查看，需要人工审核”这类产品文案。
创建售后申请会发布售后状态事件，并通过 Notification Facade 通知用户；在装配 Outbox contract 时，售后状态变更会先同事务写入 mall-after-sale-status / mall.after-sale.status-changed Outbox 事件，幂等键包含售后 ID、变更前后状态、退款状态、退货状态和原因。售后进入待审核状态时还会发布 mall.after-sale.pending-review 通知规则事件源，默认未配置接收人时静默跳过，运营可在 Notification 通知规则中配置后台审核提醒的通道、接收人和静默窗口。
后台可审批、拒绝、关闭售后；这些动作会先执行审批工作流 mall.after-sale.review，校验状态动作和权限快照。人工拒绝必须填写拒绝原因或处理备注。
退货退款场景必须先登记退货收货，再发起退款；退货收货和发起退款也会先经过审批工作流校验。退款流水号留空时，后端会尝试原支付通道退款；填写退款流水号时视为人工或外部流程已完成退款记录。余额 / 积分退款、退款流水和优惠券返还仍由 Mall 售后 Service 负责。
后台处理接口支持 operationKey 幂等键，避免重复审批、重复登记收货或重复发起退款。

后台管理接口

后台提供 B2B2C 商户、店铺、物流承运商、商品分类、商品、SKU、评价信誉、秒杀活动、订单、售后和优惠券的基础管理入口。商品分类管理和商品编辑表单支持多级分类选择；商品列表按父级分类筛选时会包含下级分类商品。

B2B2C 商户 / 店铺首段先收口平台 Admin contract 与状态机：

商户创建后默认 status=0（停用）、reviewStatus=0（草稿）；提交审核后进入 reviewStatus=10（待审核）；审核通过会写入 reviewStatus=20 并自动启用；驳回会写入 reviewStatus=30 并保持停用。
商户提交、审核通过和驳回已接入 Approval 工作流 mall.merchant.review；驳回必须填写审核说明，后台请求可传 operationKey 作为审批 traceId。Admin /mall/merchants 商户入驻页已真实接入商户列表、创建 / 编辑、提交审核、审核通过、驳回、启用 / 停用和删除。
商户结算净应付金额直接入账 商户主账号（ownerUserId）拥有的 Money 用户余额账户：自助入驻时主账号自动绑定为申请人本人，Admin /mall/merchants 商户页也可在创建 / 编辑时指定或调整主账号用户 ID。结算入账为平台内部闭环、无需外部代付账户，也不再有单独维护 / 审核「结算账户」的环节；入账前只校验商户已绑定主账号且该主账号仍是当前店铺启用员工。银行卡 / Web3 钱包等提现目的地由 Money 提现流程维护，不作为 Mall 结算或结算单外部出款目标。
店铺创建后默认 status=0（关闭）、reviewStatus=0（草稿）；shopType=merchant 店铺提交、审核通过和开启前都要求所属商户已审核通过并启用；shopType=self_operated 表示平台自营店铺，不要求绑定商户；审核通过会自动开启店铺。
店铺角色和员工只允许绑定已审核通过且开启的店铺；角色保存权限码集合，员工分配角色后会落一份聚合后的 permissionSnapshot，用于后续商户后台数据范围和按钮权限快速判断；角色权限修改、启用、停用或删除后会同步刷新已分配员工的权限快照，删除角色时会清理员工角色关系，避免旧授权继续生效。
员工角色关系采用全量替换语义，替换时先按员工物理清理旧关系再写入新关系，避免逻辑删除行继续占用 staff_id + role_id 组合唯一键。
商品保存可传 shopId 绑定已审核通过且开启的店铺，并自动派生 merchantId；商品的自营标识继承店铺类型，MallProductVO 会返回 shopType 和 selfOperated 供 Admin / App / PC 展示“自营”徽标；历史无店铺归属商品按平台自营处理。店铺商品默认进入 reviewStatus=10（待审核），后台审核通过后进入 reviewStatus=20，驳回进入 reviewStatus=30。公开商品列表、详情、购物车加购和下单复验只返回已发布、审核通过且公开可售范围有效的商品；店铺关闭、店铺审核失效或第三方商户停用后，商品会从公开侧隐藏并不能继续加购 / 下单。
商品 SKU 会继承商品的 merchantId / shopId 快照，用于后续库存、拆单、履约、结算和商户数据范围过滤；订单预览和下单会重新校验 SKU 归属，异常 SKU 快照会按不存在处理。
资质首段通过 qualificationJson 保存，后续结算入账和商户后台会继续复用商户 / 店铺 ID，不重复建模型。
物流承运商由平台后台维护，支持编码、名称、联系人手机号、物流查询链接模板、启停和排序；发货接口传 carrierCode 时会校验承运商存在且启用，并把承运商名称写入订单 / 子订单物流公司快照。
Admin /mall/orders 订单页已接入真实发货入口：列表和详情页可整单发货，详情页可按店铺子订单发货；弹窗默认读取启用物流承运商，也允许未选择承运商时手填物流公司，并在提交前进行二次确认。
商户结算生成必须指定 merchantId 和 shopId，只纳入已完成、订单商品已签收且已超过 settlement-delay 售后保护期的明细；已成功退款的售后金额会先从订单商品结算基数中扣减，成功全额退款的订单商品不进入结算单，部分退款只按剩余净额计佣和入账。mall_merchant_settlement_item.order_item_id 使用唯一约束防止同一订单商品重复结算。平台佣金和应结金额按金额精度 RoundingMode.DOWN 截断，避免派生金额四舍五入造成平台超付。结算单审核状态为 pending / approved / rejected。
审核通过后的结算入账由 Mall 同事务写入 Money 用户余额账本，结算净额会以 ADJUST_IN 入账商户主账号（ownerUserId）的 Money 余额账户，凭证号格式为 money-ledger:{ledgerId}；商家到账后通过 Money 提现流程提现。spring.open.mall.merchant-settlement.auto-approval.enabled=true 时，超时待审核且主账号 / 风控合规的结算单会通过 mall-merchant-settlement 专用队列自动审核并入账商户余额，Scheduler 仅兜底异常断链。payoutStatus 支持 pending、processing、paid、failed、frozen；入账前会校验商户已绑定主账号且该主账号是当前店铺启用员工，余额入账幂等键为 mall:merchant:settlement-credit:money-balance:{settlementId}，失败必须登记 payoutFailureReason。风控 riskStatus 支持 normal、frozen、released，未入账前可冻结，解除后恢复待入账。已入账后可登记对账结果，reconciliationStatus 支持 pending、matched、mismatched。

Mall 基线迁移会为内置 merchant 角色绑定商城后台只读菜单和权限，覆盖商品分类、商品、SKU、订单、售后、优惠券模板、用户优惠券、支付记录、交易事件、履约凭证和库存流水。该模板只开放 *:view 权限，不授予平台后台内的商品维护、发货、退款、作废、删除等写操作；面向第三方商家的受控写动作走商家自助控制台 API，并由店铺员工权限快照和店铺归属强制收窄数据范围。

商家自助控制台接口

商家自助控制台使用当前登录用户的 mall_shop_staff 关系解析可管理店铺。第三方用户可先提交入驻申请，系统会创建待审核商户、待审核店铺，并把当前用户绑定为店铺 owner；在商户未审核通过 / 未启用或店铺未审核通过 / 未开启前，owner 关系不会进入 profile 的可管理店铺范围，也不能调用商品、发货、售后、结算或团队管理接口。只有员工启用、所属商户已审核通过且启用、店铺已审核通过且开启的店铺会进入可访问范围；存在多个可管理店铺时，写入和查询接口必须显式传 shopId。后端会忽略前端传入的 merchantId / shopId 越权筛选，把查询和写入强制收窄到当前员工可管理店铺，并按 permissionSnapshot 校验具体动作权限。商家自助创建 / 修改 / 启用 / 停用 / 删除店铺角色，以及创建 / 修改 / 分配员工角色时，权限集合都会复核商家控制台白名单，不允许把结算生成、审核、入账、风控、对账、退款出款等平台权限下放给店铺员工；历史或平台侧遗留的非白名单权限角色只能由 Admin 后台处理。

http

GET    /api/v1/mall/merchant-console/profile
POST   /api/v1/mall/merchant-console/onboarding

GET    /api/v1/mall/merchant-console/shop-roles
POST   /api/v1/mall/merchant-console/shop-roles
PUT    /api/v1/mall/merchant-console/shop-roles/{id}
POST   /api/v1/mall/merchant-console/shop-roles/{id}/enable
POST   /api/v1/mall/merchant-console/shop-roles/{id}/disable
DELETE /api/v1/mall/merchant-console/shop-roles/{id}

GET    /api/v1/mall/merchant-console/shop-staff
POST   /api/v1/mall/merchant-console/shop-staff
PUT    /api/v1/mall/merchant-console/shop-staff/{id}
POST   /api/v1/mall/merchant-console/shop-staff/{id}/roles
POST   /api/v1/mall/merchant-console/shop-staff/{id}/enable
POST   /api/v1/mall/merchant-console/shop-staff/{id}/disable
DELETE /api/v1/mall/merchant-console/shop-staff/{id}

GET    /api/v1/mall/merchant-console/products
GET    /api/v1/mall/merchant-console/products/{id}
POST   /api/v1/mall/merchant-console/products
PUT    /api/v1/mall/merchant-console/products/{id}
POST   /api/v1/mall/merchant-console/products/{id}/submit
DELETE /api/v1/mall/merchant-console/products/{id}

GET    /api/v1/mall/merchant-console/products/{productId}/skus
GET    /api/v1/mall/merchant-console/products/{productId}/skus/{id}
POST   /api/v1/mall/merchant-console/products/{productId}/skus
PUT    /api/v1/mall/merchant-console/products/{productId}/skus/{id}
DELETE /api/v1/mall/merchant-console/products/{productId}/skus/{id}
DELETE /api/v1/mall/merchant-console/products/{productId}/skus

GET    /api/v1/mall/merchant-console/orders
GET    /api/v1/mall/merchant-console/orders/{id}
GET    /api/v1/mall/merchant-console/logistics-carriers
POST   /api/v1/mall/merchant-console/orders/{id}/sub-orders/{shopId}/ship
GET    /api/v1/mall/merchant-console/orders/{id}/deliveries
POST   /api/v1/mall/merchant-console/orders/{id}/deliveries
POST   /api/v1/mall/merchant-console/orders/{id}/deliveries/batch
POST   /api/v1/mall/merchant-console/orders/deliveries/{deliveryId}/reveal
POST   /api/v1/mall/merchant-console/orders/deliveries/{deliveryId}/resend
POST   /api/v1/mall/merchant-console/orders/deliveries/{deliveryId}/revoke
GET    /api/v1/mall/merchant-console/orders/deliveries/{deliveryId}/logs

GET    /api/v1/mall/merchant-console/after-sales
GET    /api/v1/mall/merchant-console/after-sales/{id}
POST   /api/v1/mall/merchant-console/after-sales/{id}/approve
POST   /api/v1/mall/merchant-console/after-sales/{id}/reject
POST   /api/v1/mall/merchant-console/after-sales/{id}/return-receipt

GET    /api/v1/mall/merchant-console/reviews
GET    /api/v1/mall/merchant-console/reviews/reputation
POST   /api/v1/mall/merchant-console/reviews/{id}/reply

GET    /api/v1/mall/merchant-console/settlements
GET    /api/v1/mall/merchant-console/settlements/{id}
GET    /api/v1/mall/merchant-console/settlements/{id}/items

profile 返回当前用户可管理店铺、员工 ID、商户 ID、店铺编码、店铺名称和权限码快照；如果当前用户已有入驻生成的 owner 员工关系但商户 / 店铺尚未审核通过、未开启或已驳回，也会在 onboardingApplications 返回申请状态和审核说明，供前端展示进度但不开放经营动作。
onboarding 接受商户编码 / 名称 / 联系方式 / 资质 JSON 与店铺编码 / 名称 / Logo / 描述，创建 reviewStatus=10 的商户和店铺，把当前用户绑定为商户主账号（owner_user_id，后续结算净应付入账其 Money 余额）并写入 owner 员工快照；owner 默认拥有商品 / SKU 维护、订单查看 / 发货、售后处理、评价查看 / 回复、结算单查看和店铺团队管理权限，但没有退款出款、结算生成 / 审核 / 入账 / 风控 / 对账等平台财务权限。结算收款用户即商户主账号，无需商家单独维护结算账户。
shop-roles 和 shop-staff 只允许维护当前员工可管理店铺内的角色和员工；店铺角色创建 / 修改 / 启用 / 停用 / 删除、员工创建 / 修改和员工角色分配都会复核商家控制台权限白名单，历史或平台侧遗留的非白名单权限角色只能由 Admin 后台处理；员工角色分配仍复用 mall_shop_staff_role 全量替换语义，角色权限变更、启停或删除会立即重算已分配员工的 permissionSnapshot，删除角色时同步清理员工角色关系。商家控制台禁止改派身份、变更自身角色、停用或删除当前登录员工关系；当前员工保存资料时后端会保留原 userId、roleIds 和启用状态，避免误操作把自己锁出店铺。如需平台兜底修复，可由 Admin 后台处理。
商品和 SKU 读写动作必须归属当前员工可管理店铺；商品详情、提交审核和删除会同时复核商品 merchantId / shopId 与当前店铺访问快照一致；商家侧 SKU 列表和商品详情内 SKU 会过滤 merchantId / shopId 与商品归属不一致的异常 SKU，SKU 详情、更新、单删和批删遇到异常快照会按不存在处理；商家修改商品时只允许保留当前店铺或迁移到同一商户下且当前员工可管理的店铺，不能把商品转移到其他商户；商家修改商品后会自动回到待审核状态，商品提交审核后仍走平台商品审核流程，商家不能自行通过审核或绕过复审继续公开售卖。
订单列表和详情只返回当前店铺且订单商品商户快照匹配的子订单视角；跨店父订单中的其他店铺商品会被裁剪，订单顶部金额、子订单金额、物流状态也按当前店铺子订单重算，不暴露父订单总额、支付流水号、支付回调地址、客户端 IP 或幂等键等平台 / 买家侧内部支付字段；店铺发货只能调用自己店铺且商户快照匹配的子订单发货接口，发货前会阻断同店不同商户的异常订单项。商家可在 mall:order:ship 权限范围内读取平台已启用物流承运商并提交 carrierCode，也可在未选择承运商时手填物流公司作为兜底。
商家虚拟交付接口只允许查询、交付、批量导入、查看、重发、作废和审计 merchantId / shopId 均匹配当前店铺访问快照的订单项交付内容；内容默认脱敏，受控查看会写入商家审计日志。
售后列表按售后对应订单商品的商户 / 店铺归属过滤；售后详情和处理动作会复核订单商品 merchantId / shopId 与当前店铺访问快照一致；商家可审批、驳回和登记退货签收，商家侧请求只保留处理备注、驳回原因、退货物流和幂等 Key，平台仲裁、责任归因和退款流水字段会在商家控制台入口被剥离；退款出款仍保留在平台后台，避免商家侧直接触发财务出款或污染平台仲裁快照。
评价列表、店铺信誉和评价回复按当前店铺访问快照强制过滤；商家侧列表和信誉统计会按评价 merchantId / shopId 同时匹配当前访问快照，回复接口会先读取评价归属，再通过商家控制台访问服务校验 mall:review:reply 并复核评价商户快照，跨店、跨商户或缺少归属的历史评价不会暴露给商家处理。
结算单和结算明细只读展示当前店铺范围，要求 mall:merchant-settlement:view；详情读取会同时复核结算单 merchantId / shopId 与当前店铺访问快照一致，明细列表还会同时匹配结算单 id、明细 merchantId 和明细 shopId，避免异常结算快照、同店不同商户明细或跨结算单明细暴露给商家；生成、审核、入账、风控冻结和对账仍由平台后台接口处理；结算净应付直接入账商户主账号 Money 余额，无独立结算账户审核环节。
PC 商家工作台已接入 /account/mall-merchant，账号中心固定展示商家入口：无可管理店铺时展示入驻申请表；如果已有待审核或驳回的入驻申请，页面会展示商户 / 店铺审核状态、提交时间和审核说明，待审核期间暂停重复提交，驳回后允许重新填写申请；profile 返回可管理店铺后，页面提供店铺切换、店铺角色 / 员工维护、商品 / SKU 维护、商品提交审核、店铺子订单发货、虚拟交付查看 / 交付 / 批量导入 / 重发 / 作废 / 日志查看、售后审批 / 驳回 / 退货签收和结算明细只读查看。页面会按当前店铺权限快照加载对应区域数据，缺少商品 / 订单 / 售后 / 团队 / 结算权限时不主动请求对应列表接口，并展示无权限空态；发货、虚拟交付、售后处理、评价回复、团队管理、商品 / SKU 维护和结算查看等按钮与提交函数也按同一权限快照做前置保护，避免店铺员工看到误导性空数据或触发不必要的 403。切换店铺时会清理商品、SKU、发货、虚拟交付、售后、评价回复、团队和结算明细等店铺范围内编辑态，避免旧店铺表单污染新店铺。商品 / SKU 表单覆盖商品类型、虚拟交付类型与说明、图集、原价 / 会员价、积分价模式、排序和 SEO 字段，便于第三方商家自助维护实物 / 虚拟 / 混合商品。
生产运营边界：商家侧只做店铺范围内自助经营动作，商品审核、结算生成 / 审核 / 入账 / 风控 / 对账和退款出款仍由平台 Admin 后台处理。

http

GET    /api/v1/admin/mall/merchants
GET    /api/v1/admin/mall/merchants/{id}
POST   /api/v1/admin/mall/merchants
PUT    /api/v1/admin/mall/merchants/{id}
POST   /api/v1/admin/mall/merchants/{id}/submit
POST   /api/v1/admin/mall/merchants/{id}/approve
POST   /api/v1/admin/mall/merchants/{id}/reject
POST   /api/v1/admin/mall/merchants/{id}/enable
POST   /api/v1/admin/mall/merchants/{id}/disable
DELETE /api/v1/admin/mall/merchants/{id}

GET    /api/v1/admin/mall/shops
GET    /api/v1/admin/mall/shops/{id}
POST   /api/v1/admin/mall/shops
PUT    /api/v1/admin/mall/shops/{id}
POST   /api/v1/admin/mall/shops/{id}/submit
POST   /api/v1/admin/mall/shops/{id}/approve
POST   /api/v1/admin/mall/shops/{id}/reject
POST   /api/v1/admin/mall/shops/{id}/open
POST   /api/v1/admin/mall/shops/{id}/close
DELETE /api/v1/admin/mall/shops/{id}

GET    /api/v1/admin/mall/shop-roles
GET    /api/v1/admin/mall/shop-roles/{id}
POST   /api/v1/admin/mall/shop-roles
PUT    /api/v1/admin/mall/shop-roles/{id}
POST   /api/v1/admin/mall/shop-roles/{id}/enable
POST   /api/v1/admin/mall/shop-roles/{id}/disable
DELETE /api/v1/admin/mall/shop-roles/{id}

GET    /api/v1/admin/mall/shop-staff
GET    /api/v1/admin/mall/shop-staff/{id}
POST   /api/v1/admin/mall/shop-staff
PUT    /api/v1/admin/mall/shop-staff/{id}
POST   /api/v1/admin/mall/shop-staff/{id}/roles
POST   /api/v1/admin/mall/shop-staff/{id}/enable
POST   /api/v1/admin/mall/shop-staff/{id}/disable
DELETE /api/v1/admin/mall/shop-staff/{id}

GET    /api/v1/admin/mall/logistics-carriers
GET    /api/v1/admin/mall/logistics-carriers/{id}
POST   /api/v1/admin/mall/logistics-carriers
PUT    /api/v1/admin/mall/logistics-carriers/{id}
POST   /api/v1/admin/mall/logistics-carriers/{id}/enable
POST   /api/v1/admin/mall/logistics-carriers/{id}/disable
DELETE /api/v1/admin/mall/logistics-carriers/{id}

GET    /api/v1/admin/mall/settlements
GET    /api/v1/admin/mall/settlements/{id}
GET    /api/v1/admin/mall/settlements/{id}/items
POST   /api/v1/admin/mall/settlements/generate
POST   /api/v1/admin/mall/settlements/{id}/approve
POST   /api/v1/admin/mall/settlements/{id}/reject
POST   /api/v1/admin/mall/settlements/{id}/payout/start
POST   /api/v1/admin/mall/settlements/{id}/payout/paid
POST   /api/v1/admin/mall/settlements/{id}/payout/failed
POST   /api/v1/admin/mall/settlements/{id}/risk/freeze
POST   /api/v1/admin/mall/settlements/{id}/risk/release
POST   /api/v1/admin/mall/settlements/{id}/reconcile

POST   /api/v1/admin/mall/products/{id}/submit
POST   /api/v1/admin/mall/products/{id}/approve
POST   /api/v1/admin/mall/products/{id}/reject

GET    /api/v1/admin/mall/categories
GET    /api/v1/admin/mall/categories/export
GET    /api/v1/admin/mall/categories/{id}
POST   /api/v1/admin/mall/categories
PUT    /api/v1/admin/mall/categories/{id}
DELETE /api/v1/admin/mall/categories/{id}
DELETE /api/v1/admin/mall/categories

GET    /api/v1/admin/mall/products
GET    /api/v1/admin/mall/products/export
GET    /api/v1/admin/mall/products/{id}
POST   /api/v1/admin/mall/products
PUT    /api/v1/admin/mall/products/{id}
DELETE /api/v1/admin/mall/products/{id}
DELETE /api/v1/admin/mall/products

GET    /api/v1/admin/mall/products/{productId}/skus
GET    /api/v1/admin/mall/products/{productId}/skus/export
GET    /api/v1/admin/mall/products/{productId}/skus/{id}
POST   /api/v1/admin/mall/products/{productId}/skus
PUT    /api/v1/admin/mall/products/{productId}/skus/{id}
DELETE /api/v1/admin/mall/products/{productId}/skus/{id}
DELETE /api/v1/admin/mall/products/{productId}/skus

商品 / SKU 积分价规则：

- 商品和 SKU 保存、详情、列表导出都会返回 `priceMode`、`pointsPrice` 和 `pointsDiscountAmount`。
- Admin 商品页和 SKU 页支持维护价格模式、积分价和积分抵扣；商品列表可按 `priceMode` 筛选，SKU 新建时默认继承当前商品积分价规则。
- `priceMode` 支持 `cash`、`points`、`points-cash` 和 `cash-with-points-discount`；未传时默认 `cash`。
- `cash` 表示普通现金价，服务端会把 `pointsPrice` 和 `pointsDiscountAmount` 收敛为 `0`。
- `points` 表示纯积分兑换，`pointsPrice` 必须大于 `0`，`price` 可按运营展示需要保留为 `0` 或参考价。
- `points-cash` 表示积分 + 现金组合购买，`pointsPrice` 和 `price` 都必须大于 `0`。
- `cash-with-points-discount` 表示现金商品可用积分抵扣部分金额，`pointsPrice` 和 `pointsDiscountAmount` 都必须大于 `0`，且抵扣金额不能大于现金价。
- SKU 未传积分价字段时继承所属商品规则；传入后可覆盖商品规则。订单预览会按积分价模式返回 `pointsAmount`、`pointsDiscountAmount` 和 `cashPayableAmount`；下单冻结积分，支付成功解冻并扣减，待支付取消解冻，售后退款成功按售后积分快照退回。

会员积分运营：

- 积分资产复用 Money 的 `points:mall` 资产账户和 `money_balance_ledger` 流水，商城和会员积分运营都不直接修改余额表。
- App 会员积分页会读取当前用户积分概览、任务、签到状态和积分流水，展示可用积分、冻结积分、本月获得 / 使用、连续签到和任务列表，并提供签到入口与商城兑换跳转。
- PC 用户中心提供会员积分入口和积分流水页，用户可查看余额、任务、流水并完成签到。
- Admin 后台 `member-points` 菜单提供用户积分账户列表、积分流水查询、规则配置、手动发放 / 扣减和过期任务执行入口。
- 积分规则支持签到奖励、连续签到奖励、订单支付奖励、管理员调整和积分过期策略；签到、订单奖励和人工发放会写入积分来源明细，用户概览按来源明细统计即将过期积分，scheduler 任务 `member-points.expire` 会周期扫描并通过 Money 流水扣减已到期积分。
- 订单支付奖励只按订单现金支付金额计算，积分兑换或积分抵扣的部分不会再重复奖励积分；奖励幂等键为订单号维度，重复支付回调 / 状态同步不会重复发放。
- 售后退款成功后会按退款金额比例冲正已奖励积分，冲正幂等键包含订单号和退款单号，避免重复退款回调重复扣回。
- 商城首单和商品评价奖励走 starter-common 中立任务事件：订单首次进入已支付状态时发布 `first-order`，商品评价创建成功后发布 `review-reward`；Member Points 监听事件后写 Money 积分流水，Mall 不直接修改积分余额。
- 手动调整必须传 `operationKey` 和 `reason`，后端会把操作人、原因、traceId 和幂等键写入积分流水备注与业务引用，便于审计追踪。

GET    /api/v1/admin/mall/seckill-activities
GET    /api/v1/admin/mall/seckill-activities/{id}
POST   /api/v1/admin/mall/seckill-activities
PUT    /api/v1/admin/mall/seckill-activities/{id}
PUT    /api/v1/admin/mall/seckill-activities/{id}/status
DELETE /api/v1/admin/mall/seckill-activities/{id}
DELETE /api/v1/admin/mall/seckill-activities

GET    /api/v1/admin/mall/orders
GET    /api/v1/admin/mall/orders/export
GET    /api/v1/admin/mall/orders/{id}
GET    /api/v1/admin/mall/orders/{id}/timeline
GET    /api/v1/admin/mall/orders/{id}/deliveries
GET    /api/v1/admin/mall/orders/deliveries/pending
GET    /api/v1/admin/mall/orders/deliveries/pending/summary
GET    /api/v1/admin/mall/orders/deliveries/inventory-warnings
POST   /api/v1/admin/mall/orders/{id}/deliveries
POST   /api/v1/admin/mall/orders/{id}/deliveries/batch
POST   /api/v1/admin/mall/orders/deliveries/{deliveryId}/reveal
POST   /api/v1/admin/mall/orders/deliveries/{deliveryId}/resend
POST   /api/v1/admin/mall/orders/deliveries/{deliveryId}/revoke
GET    /api/v1/admin/mall/orders/deliveries/{deliveryId}/logs
GET    /api/v1/admin/mall/orders/{id}/payment/status
POST   /api/v1/admin/mall/orders/{id}/payment/sync
POST   /api/v1/admin/mall/orders/expired/release
POST   /api/v1/admin/mall/orders/{id}/ship
POST   /api/v1/admin/mall/orders/{id}/sub-orders/{shopId}/ship
POST   /api/v1/admin/mall/orders/{id}/cancel
POST   /api/v1/admin/mall/orders/{id}/invoice/issue

GET    /api/v1/admin/mall/after-sales
GET    /api/v1/admin/mall/after-sales/export
GET    /api/v1/admin/mall/after-sales/{id}
POST   /api/v1/admin/mall/after-sales/{id}/approve
POST   /api/v1/admin/mall/after-sales/{id}/reject
POST   /api/v1/admin/mall/after-sales/{id}/close
POST   /api/v1/admin/mall/after-sales/{id}/refund
POST   /api/v1/admin/mall/after-sales/{id}/return-receipt

GET    /api/v1/admin/mall/coupon-templates
GET    /api/v1/admin/mall/coupon-templates/export
GET    /api/v1/admin/mall/coupon-templates/{id}
POST   /api/v1/admin/mall/coupon-templates
PUT    /api/v1/admin/mall/coupon-templates/{id}
DELETE /api/v1/admin/mall/coupon-templates/{id}
DELETE /api/v1/admin/mall/coupon-templates

GET    /api/v1/admin/mall/user-coupons
GET    /api/v1/admin/mall/user-coupons/export
GET    /api/v1/admin/mall/user-coupons/{id}

GET    /api/v1/admin/install/quickstart-cleanups/mall
POST   /api/v1/admin/install/quickstart-cleanups/mall

GET    /api/v1/admin/mall/payment-records
GET    /api/v1/admin/mall/payment-records/export
GET    /api/v1/admin/mall/transaction-events
GET    /api/v1/admin/mall/transaction-events/export
GET    /api/v1/admin/mall/fulfillment-records
GET    /api/v1/admin/mall/fulfillment-records/export
GET    /api/v1/admin/mall/inventory-records
GET    /api/v1/admin/mall/inventory-records/export
POST   /api/v1/admin/mall/inventory-records/adjust
POST   /api/v1/admin/mall/inventory-records/recalculate
POST   /api/v1/admin/mall/inventory-records/release-compensation

后台运维记录：

GET /admin/categories/export 复用后台分类列表 parentId、keyword 和 status 筛选条件，返回 text/csv;charset=UTF-8 附件。CSV 只输出分类编码、名称、父级、图标、排序、状态和审计时间，不导出商品或 SKU 明细。
GET /admin/products/export 复用后台商品列表 keyword、categoryId、categoryCode、productType、minPrice、maxPrice、status 和 sort 筛选条件，返回 text/csv;charset=UTF-8 附件。CSV 只输出商品运营元数据、价格库存、状态和 SEO 信息，不导出商品详情正文、图片 URL、虚拟交付提示或扩展 JSON。
GET /admin/products/{productId}/skus/export 导出指定商品下的 SKU 运营快照，返回 text/csv;charset=UTF-8 附件。CSV 只输出 SKU 编码、规格 JSON、价格、币种、库存、状态、排序和审计时间，不导出商品详情正文或图片 URL。
GET /admin/seckill-activities 支持按关键词、商品、活动状态和时间窗口筛选秒杀活动；后台页面可创建 / 更新活动、切换草稿 / 已开启 / 已关闭状态和删除活动。活动库存与商品 / SKU 库存同时受后端校验，前端只提交运营配置，不直接改库存锁定记录。
GET /admin/orders 与 GET /admin/orders/export 复用后台订单列表 status、merchantId 和 shopId 筛选条件；merchantId / shopId 会命中包含该商户或店铺子订单的父订单。导出返回 text/csv;charset=UTF-8 附件，CSV 只输出订单号、用户、金额快照、支付摘要、物流 / 发票状态和交易时间点，不导出收货详细地址、手机号、支付回跳 URL 或客户端 IP。
GET /admin/after-sales/export 复用后台售后列表 status 筛选条件，返回 text/csv;charset=UTF-8 附件。CSV 只输出售后编号、用户 / 订单关联、售后类型、金额、审核 / 退款 / 退货 / 虚拟交付状态、商户责任、平台仲裁结果和关键时间点，不导出用户描述、凭证链接、退货物流单号或幂等操作 key。
GET /admin/coupon-templates/export 复用后台优惠券模板 keyword、couponType、receiveType、scopeType 和 status 筛选条件，返回 text/csv;charset=UTF-8 附件。CSV 只输出模板规则、优惠金额 / 折扣、适用范围、领取数量、有效期和状态，不导出用户领券明细。
GET /admin/user-coupons/export 复用后台用户券 userId、templateId、status、couponType 和 keyword 筛选条件，返回 text/csv;charset=UTF-8 附件。CSV 只输出用户券快照、模板折扣、有效期、锁定 / 使用订单和来源场景，不导出领取 / 锁定 / 核销生命周期日志。
GET /admin/payment-records 投影订单支付和售后退款记录，支持 keyword、orderNo、afterSaleNo、recordType、recordStatus、provider、channel、paymentMethod 等查询参数。
GET /admin/payment-records/export 复用后台支付记录 keyword、orderNo、afterSaleNo、recordType、recordStatus、provider、channel 和 paymentMethod 筛选条件，返回 text/csv;charset=UTF-8 附件。CSV 只输出支付 / 退款运营快照和交易编号，不导出失败原因、审计备注或幂等请求号。
GET /admin/transaction-events 投影订单、支付、物流、发票、售后、退款和虚拟交付事件，适合后台查看交易链路。
GET /admin/transaction-events/export 复用后台交易事件 keyword、orderNo、afterSaleNo、eventType 和 eventStatus 筛选条件，返回 text/csv;charset=UTF-8 附件。CSV 只输出事件 ID、订单 / 售后关联、事件类型、状态、金额、币种、Provider 和发生时间，不导出售后描述、凭证 ID、物流单号、发票号或长文本备注。
GET /admin/fulfillment-records 投影物流、发票、退货和虚拟交付记录，适合履约运维页面读取。
GET /admin/fulfillment-records/export 复用后台履约记录 keyword、orderNo、afterSaleNo、recordType 和 recordStatus 筛选条件，返回 text/csv;charset=UTF-8 附件。CSV 只输出履约 ID、订单 / 售后关联、履约类型、状态、物流公司、发票类型、通知摘要和关键时间点，不导出物流单号、发票抬头、凭证 ID / URL 或长文本备注。
GET /admin/inventory-records 返回商品和 SKU 当前库存快照，适合库存看板；B2B2C 场景可按 merchantId / shopId 收窄到指定商户或店铺。
GET /admin/inventory-records/export 复用后台库存记录 keyword、productId、skuId、merchantId、shopId、changeType、sourceType 和 direction 筛选条件，返回 text/csv;charset=UTF-8 附件。CSV 只输出商品 / SKU 关联、商户 / 店铺归属、库存变更类型、来源、方向、数量快照和关键时间点，不导出幂等键、操作键、审计备注或操作人信息。
POST /admin/inventory-records/adjust 按商品或 SKU 人工调整库存；请求字段为 productId、可选 skuId、changeQuantity、operationKey 和 remark，changeQuantity 可正可负，调整后库存不能小于 0。
POST /admin/inventory-records/recalculate 按商品 SKU 库存汇总重算商品库存；请求字段为 productId、operationKey 和 remark。商品没有 SKU 时保持当前库存。
POST /admin/inventory-records/release-compensation 对异常未释放的商品或 SKU 库存执行正向补偿；请求字段为 productId、可选 skuId、正数 quantity、sourceNo、operationKey 和 remark。
三个写接口均返回 MallInventoryRecordVO，包含 changeType、sourceType、sourceNo、direction、quantityBefore、changeQuantity、quantityAfter、operationKey 和 auditRemark，供后台页面展示操作结果。当前版本不新增库存流水表，operationKey 作为操作关联号回显，不承诺持久化幂等。

权限标识：

txt

mall:merchant:view
mall:merchant:create
mall:merchant:update
mall:merchant:review
mall:merchant:status
mall:merchant:delete
mall:shop:view
mall:shop:create
mall:shop:update
mall:shop:review
mall:shop:status
mall:shop:delete
mall:shop-role:view
mall:shop-role:create
mall:shop-role:update
mall:shop-role:status
mall:shop-role:delete
mall:shop-staff:view
mall:shop-staff:create
mall:shop-staff:update
mall:shop-staff:status
mall:shop-staff:role
mall:shop-staff:delete
mall:logistics-carrier:view
mall:logistics-carrier:create
mall:logistics-carrier:update
mall:logistics-carrier:status
mall:logistics-carrier:delete
mall:category:view
mall:category:create
mall:category:update
mall:category:delete
mall:product:view
mall:product:create
mall:product:update
mall:product:delete
mall:product-sku:view
mall:product-sku:create
mall:product-sku:update
mall:product-sku:delete
mall:seckill:view
mall:seckill:create
mall:seckill:update
mall:seckill:status
mall:seckill:delete
mall:order:view
mall:order:payment-sync
mall:order:ship
mall:order:cancel
mall:order:invoice
mall:virtual-delivery:view
mall:virtual-delivery:deliver
mall:virtual-delivery:revoke
mall:after-sale:view
mall:after-sale:handle
mall:after-sale:refund
mall:after-sale:return
mall:coupon-template:view
mall:coupon-template:create
mall:coupon-template:update
mall:coupon-template:delete
mall:user-coupon:view
mall:payment-record:view
mall:transaction-event:view
mall:fulfillment-record:view
mall:inventory-record:view
mall:inventory-record:adjust
mall:inventory-record:recalculate
mall:inventory-record:release

后台有副作用动作说明：

发货、取消订单、同步支付、开票、虚拟交付、售后审批、售后发起退款、退货收货和库存写动作都使用独立权限码。
发货、开票、虚拟交付和售后处理接口支持 operationKey，前端建议使用页面操作流水号或按钮提交 UUID，避免重复提交。虚拟交付批量导入传入请求级 operationKey 时，后端会按导入顺序生成逐条幂等键。
当前审计主要通过权限码、业务事件、状态字段和操作时间字段承载；后续如需更强审计，可在应用层接操作日志模块。
/mall/operations 是后台副作用动作的只读操作确认台，用于集中查看接口、权限码、幂等键、审计语义和接入要求；真正写操作仍在订单、售后、虚拟交付等业务页面完成，不在该页面直接发送副作用请求。
/mall/after-sales 已直接接入审核通过、驳回、关闭、发起退款和退货签收表单，前端会生成 operationKey 并提交责任归因与平台仲裁字段；退款流水号可选，状态、权限、审批流、支付通道退款和余额 / 积分 / 优惠券返还仍以后端 contract 为准。

后台操作入口：

页面	路由	主要用途	关键接口 / 权限
商户管理	`/mall/merchants`	维护 B2B2C 商户入驻资料、资质、启停和审核状态	`/api/v1/admin/mall/merchants`，`mall:merchant:*`
店铺管理	`/mall/shops`	维护 B2B2C 店铺资料、开闭状态和审核状态	`/api/v1/admin/mall/shops`，`mall:shop:*`
店铺员工	`/mall/shop-staff`	维护已审核开启店铺的角色、权限集合、员工分配、启停和删除	`/api/v1/admin/mall/shop-roles`、`/api/v1/admin/mall/shop-staff`，`mall:shop-role:`、`mall:shop-staff:`
商户结算	`/mall/merchant-settlements`	按商户 / 店铺生成结算单，处理审核、余额入账、失败登记、风控冻结 / 解除和对账登记	`/api/v1/admin/mall/settlements/*`，`mall:merchant-settlement:`
物流承运商	`/mall/logistics-carriers`	维护发货可引用的物流承运商、查询链接模板、启停和排序	`/api/v1/admin/mall/logistics-carriers`，`mall:logistics-carrier:*`
商品分类	`/mall/categories`	维护分类层级、编码、图标、排序和发布状态	`/api/v1/admin/mall/categories`，`mall:category:*`
商品管理	`/mall/products`	维护商品基础信息、商品类型、虚拟交付提示、上下架和 SEO 信息	`/api/v1/admin/mall/products`，`mall:product:*`
SKU 管理	`/mall/product-skus`	维护商品规格、价格、库存和 SKU 状态	`/api/v1/admin/mall/products/{productId}/skus`，`mall:product-sku:*`
秒杀活动	`/mall/seckill-activities`	维护秒杀活动商品、SKU、秒杀价、活动库存、限购、时间窗口和上下线状态	`/api/v1/admin/mall/seckill-activities`，`mall:seckill:*`
订单管理	`/mall/orders`	查看订单、时间线、本地支付状态，执行整单 / 店铺子订单发货、支付同步和虚拟交付查看 / 交付 / 重发 / 作废	`/api/v1/admin/mall/orders/*`，`mall:order:`、`mall:virtual-delivery:*`
售后管理	`/mall/after-sales`	查看售后申请、审批 / 拒绝 / 关闭、登记退货收货和发起退款	`/api/v1/admin/mall/after-sales/*`，`mall:after-sale:`
优惠券模板	`/mall/coupon-templates`	维护满减、折扣、运费券模板和领取规则	`/api/v1/admin/mall/coupon-templates`，`mall:coupon-template:*`
用户优惠券	`/mall/user-coupons`	查看用户券状态、券码、锁定订单和使用订单	`/api/v1/admin/mall/user-coupons`，`mall:user-coupon:view`
支付记录	`/mall/payment-records`	只读查看订单支付和售后退款投影	`/api/v1/admin/mall/payment-records`，`mall:payment-record:view`
交易事件	`/mall/transaction-events`	只读查看订单、支付、物流、发票、售后、退款和虚拟交付事件	`/api/v1/admin/mall/transaction-events`，`mall:transaction-event:view`
履约凭证	`/mall/fulfillment-records`	只读查看物流、发票、退货和虚拟交付履约记录，可带交付上下文跳转操作确认台	`/api/v1/admin/mall/fulfillment-records`，`mall:fulfillment-record:view`
库存流水	`/mall/inventory-records`	查看商品和 SKU 当前库存快照、执行人工调账、SKU 汇总重算、释放补偿和虚拟 / 混合商品库存预警	`/api/v1/admin/mall/inventory-records/*`，`mall:inventory-record:`
操作接入清单	`/mall/operations`	展示支付同步、发货、开票、售后处理和虚拟交付写动作 contract	后台各副作用接口及对应 `mall:*` 权限

虚拟交付后台操作建议：

人工交付：从后台订单页的虚拟交付抽屉进入，提交 orderItemId、deliveryType、contentTitle、contentValue、contentMask、accessUrl、accessExpiresAt、operationKey 和备注。敏感内容由后端加密和审计，前端不长期缓存明文。
批量导入：用于一批卡密、授权码、账号或资源链接按待处理交付项顺序填充。请求级 operationKey 会生成逐条幂等键，失败时应把后端返回的错误原因展示给运营人员。
受控查看：管理员查看已交付内容必须走 POST /api/v1/admin/mall/orders/deliveries/{deliveryId}/reveal，用于写入查看审计；列表页和只读记录页只展示掩码。
重发：用于重新写入交付内容或补发资源链接，必须提交新的 operationKey，并保留旧审计日志。
作废：用于误发、售后冻结或运营废弃场景，作废后清空用户可 reveal 的明文内容和访问地址。

与前端视图联动

PC / App 视图可以先接入：

http

GET /api/v1/mall/categories
GET /api/v1/mall/products
GET /api/v1/mall/products/{id}
GET /api/v1/mall/products/{id}/reviews
GET /api/v1/admin/mall/reviews/shops/{shopId}
GET /api/v1/admin/mall/reviews/shops/{shopId}/reputation
POST /api/v1/admin/mall/reviews/{id}/reply
GET /api/v1/mall/merchant-console/reviews
GET /api/v1/mall/merchant-console/reviews/reputation
POST /api/v1/mall/merchant-console/reviews/{id}/reply
POST /api/v1/mall/products/{id}/favorites
DELETE /api/v1/mall/products/{id}/favorites
GET /api/v1/mall/me/favorites
GET /api/v1/mall/seckill-activities
GET /api/v1/mall/seckill-activities/{id}
GET /api/v1/mall/me/reviews
POST /api/v1/mall/reviews
GET /api/v1/mall/cart/items
POST /api/v1/mall/cart/items
PUT /api/v1/mall/cart/items/{id}
PUT /api/v1/mall/cart/items/batch
DELETE /api/v1/mall/cart/items/{id}
DELETE /api/v1/mall/cart/items
GET /api/v1/mall/addresses
POST /api/v1/mall/addresses
PUT /api/v1/mall/addresses/{id}
PUT /api/v1/mall/addresses/{id}/default
DELETE /api/v1/mall/addresses/{id}
POST /api/v1/mall/orders
POST /api/v1/mall/orders/preview
POST /api/v1/mall/orders/coupons
POST /api/v1/mall/seckill-activities/{id}/orders
GET /api/v1/mall/orders
GET /api/v1/mall/orders/{id}
GET /api/v1/mall/orders/{id}/deliveries
POST /api/v1/mall/orders/deliveries/{deliveryId}/reveal
GET /api/v1/mall/orders/{id}/payment/status
POST /api/v1/mall/orders/{id}/pay
POST /api/v1/mall/orders/{id}/payment/sync
POST /api/v1/mall/orders/{id}/cancel
POST /api/v1/mall/orders/{id}/receipt/confirm
POST /api/v1/mall/orders/{id}/invoice
GET /api/v1/mall/orders/{id}/after-sale-items
POST /api/v1/mall/orders/{id}/after-sales
GET /api/v1/mall/me/after-sales
GET /api/v1/mall/after-sales/{id}
POST /api/v1/mall/after-sales/{id}/return-logistics
GET /api/v1/mall/coupons/claimable
POST /api/v1/mall/coupons/{templateId}/claim
GET /api/v1/mall/coupons/mine
GET /api/v1/mall/coupons/mine/{id}

商城首页、分类页、商品搜索筛选、商品详情页、秒杀活动卡片、商品评价列表、我的收藏页、我的评价页、购物车、地址管理、秒杀结算、普通结算、订单列表、订单详情、虚拟交付查看、支付入口、支付状态同步、取消订单、确认收货、发票申请和售后服务可以先通过这些接口完成。

App / PC 的支付入口统一打开收银台：结算、订单详情和历史支付页都只负责把订单号交给收银台或在支付回跳后同步订单状态，不在 Mall 页面内单独展示法币 / Web3 代币支付方式。App 端统一收银台使用 cashier 分包路由，入口为 /cashier/index，支付终态页为 /cashier/result。

PC 买家侧按“浏览商品 → 加入购物车 → 确认订单 → 选择 / 新增收货地址 → 统一收银台 → 支付结果 → 我的订单”的国内电商路径组织。购物车会在页面重新可见或浏览器重新聚焦时刷新真实购物车；订单列表对可同步支付状态的订单提供“刷新支付”，用于用户从支付页、钱包页或第三方环境返回后手动确认订单状态；结算和地址页通过 addressId 串联地址选择，不依赖浏览器本地订单或假数据兜底。

App 结算页会在提交前展示“下单前检查”，提前提示收货地址、购物车商品、库存不足、优惠券不可用、订单预览失败、支付方式和发票申请等边界；这些提示只辅助用户理解，最终库存、优惠、金额和支付可用性仍以后端预览、下单和支付接口校验结果为准。

App 和 PC 商城首页会展示进行中的秒杀活动。点击活动后进入同一个结算页，但路由携带 seckillActivityId，结算页只读取该活动并调用秒杀下单接口，不读取购物车、不展示优惠券叠加；订单创建成功后继续沿用现有订单详情和支付链路。

App / PC 买家侧已显示 B2B2C 店铺归属：商品详情、购物车、结算、订单详情会展示平台自营 / 店铺 / 商户信息；普通结算页优先展示后端预览返回的 subOrders，未返回预览时按当前商品行归属分组展示分店履约；订单详情展示父订单下的子订单履约、物流和金额摘要。

三端页面和截图：

端	页面	路由
App	商城首页首屏	`pages/mall/index`
App	商城首页长图	`pages/mall/index`
App	商品详情	`mall/detail`
App	购物车	`mall/cart`
App	结算	`mall/checkout`
App	订单详情	`mall/order-detail`
App	售后详情	`mall/after-sales-detail`
App	我的优惠券	`pages/member/coupons`
PC	商城首页	`/pc/mall`
PC	商品详情	`/pc/mall/{id}`
PC	购物车	`/pc/mall/cart`
PC	结算	`/pc/mall/checkout`
PC	订单详情	`/pc/account/orders/{id}`
PC	售后详情	`/pc/account/after-sales/{id}`
Admin	商品管理	`/mall/products`
Admin	订单管理	`/mall/orders`
Admin	售后管理	`/mall/after-sales`
Admin	履约凭证	`/mall/fulfillment-records`
Admin	操作接入清单	`/mall/operations`

截图只用于说明当前页面形态和入口位置。实际交易金额、库存、优惠、发货、虚拟交付和售后状态以后端接口返回为准，前端不得用截图或本地数据伪造可购买状态。

后续方向

商品追评和评价审核；商家回复、店铺信誉统计和商品浏览历史已落地。
运费模板、更多活动发券和活动组合规则；优惠券、会员价和秒杀活动价已接入交易链路，秒杀活动已具备库存锁定、限购、支付确认、取消释放和活动价快照，后续可继续扩展团购、众筹等交易增强。
积分商城：商品 / SKU 积分价规则、订单预览金额拆分、积分冻结 / 扣减、取消释放、售后退积分、订单奖励积分、退款奖励冲正、到期积分扫描和三端会员积分入口已落地；后续可继续增强积分补偿券和更多营销任务。
积分账本边界：积分余额、冻结、扣减、退回、过期和人工调整归 Member Points + Money 底座；Mall 只保存订单侧积分快照并发布订单支付 / 售后退款事件，不在订单模块私写积分流水。
团购：归 Mall 交易增强，支持团购活动、成团人数、成团时限、参团订单、未成团自动取消 / 退款和团购通知；库存、订单、支付和售后继续归 Mall。
商品众筹 / 预售众筹：归 Mall 交易增强，只按商品众筹、预售和目标达成后履约规划；不做证券、股权或真实金融募集语义。未达成目标时按订单快照退款，达成后进入发货或虚拟交付流程。
虚拟商品与自动发货：physical / virtual / mixed 商品类型、交付类型快照和 mall_virtual_delivery_item 交付项表已落地；支付成功后按订单项幂等生成交付项，资源链接类可第一阶段自动交付，人工虚拟权益进入待交付状态；纯虚拟订单自动完成可通过配置显式开启，混合订单只自动交付虚拟部分。
虚拟交付安全：第一阶段提供受控 reveal、后台 operationKey 幂等补发、批量导入、真实库存池预警、后台重发、后台作废、售后查看状态快照、敏感内容加密、多版本密钥轮换、密钥 Provider 扩展边界和交付审计；默认 config provider 不引入云厂商依赖，Vault / KMS 可按需实现 MallVirtualDeliveryKeyProvider。
虚拟商品售后：申请时会记录未查看 / 未领取或已查看 / 已领取状态快照；后续自动退款、人工审核或冻结自动发货策略应基于该快照和后台审核规则执行。
更完整的支付回调验签、退款状态回查 / 对账补偿和 Queue 异步任务。
订单状态通知和售后通知已有事件与 Notification 底座，后续补充更多模板和多通道通知。
B2B2C 商户 / 店铺 contract、店铺员工 RBAC、商品 / SKU 归属、商品审核、跨店父订单、店铺子订单履约、售后责任 / 仲裁首段、App / PC 买家侧体验、商户结算 / 平台佣金 / 结算明细账本、余额入账 / 风控 / 对账首段、Admin 商户结算控制台和订单 / 售后 / 商户结算事件装配已落地。

Mall ​

配置 ​

数据模型 ​

内置演示数据 ​

公共只读接口 ​

商品类型 ​

用户交易接口 ​

后台管理接口 ​

商家自助控制台接口 ​

与前端视图联动 ​

后续方向 ​

Mall

配置

数据模型

内置演示数据

公共只读接口

商品类型

用户交易接口

后台管理接口

商家自助控制台接口

与前端视图联动

后续方向