商户权益分销系统 - 需求说明

本页为烘焙预约小程序项目中的「商户权益分销系统」需求说明，遵循通用 MCP 规范，仅更新文档，不包含具体代码实现。

一、模块概述

本需求文档拆分为两个子模块：

• 模块一：商户权益卡发放与核销系统——侧重卡券的生成、发放、激活、核销与流水管理。
• 模块二：商户权益分销系统（EPS）——侧重分销角色、订单关联、收益计算与分销统计。

二者共同为烘焙预约小程序提供「权益套餐卡售卖 + 卡券发放/激活 + 分销推广 + 收益结算 + 核销闭环」能力。

• 适用范围：商户端 / 平台端管理后台，以及用户端的小程序权益展示与核销。
• 技术框架：后端 cool-admin-midway、管理后台 cool-admin-vue、小程序 cool-unix。
• 数据表前缀建议：本模块新增表统一采用 eps_ 前缀，与预约模块 bake_ 区分。

二、核心业务逻辑

2.1 权益卡发放与激活（模块一）

通过实体卡或电子卡的方式，将权益以「卡券」形式发放给用户，并在客户端完成激活绑定。

• 发放方式：
  • 线下实体卡：批量生成卡号 + 激活码，导出 Excel/CSV，线下售卖或派发。
  • 电子卡：后台生成电子卡券，通过短信/公众号/客服发送卡号 + 激活码。
  • 线上购买：用户在小程序内购买权益卡时，自动生成并激活一张卡券实例。
• 激活流程：
  • 客户端入口：「我的」-「我的权益」中增加「输入卡号/激活码」入口。
  • 用户输入卡号 + 激活码后，系统校验状态与有效期，成功后绑定到当前用户并标记为已激活。
  • 同一张卡仅允许激活一次，若需要可由后台进行冻结/作废或特殊处理。
• 发放与激活细节：
  • 批量生成与导出：支持按数量、卡号前缀、有效期策略等参数批量生成卡券；导出 Excel/CSV 模板包含批次号、活动名称等元信息。
  • 数据校验与异常处理：生成时校验卡号不重复、批次号唯一；激活时校验卡号格式、激活码是否匹配、卡券状态与有效期，并返回详细错误原因。
  • 安全与风控：管理端列表默认对卡号与激活码做打码展示，限制单账号/IP/设备在时间窗口内的激活失败次数，并记录来源信息便于审计。

2.2 权益套餐卡使用与核销（模块一）

商户可以配置包含多个商品或服务的「权益套餐卡」，并通过卡券形式售卖与核销。

• 基础信息：名称、副标题、封面图、展示标签（如「爆款」「限时」）、排序、上下架状态。
• 权益内容：多个权益明细，每条包含名称、说明、单次原价、可用次数、是否需要预约。
• 使用规则：
  • 按明细粒度记录可用次数，并在卡级别保留总次数字段用于统计。
  • 支持固定有效期（起止日期）与「购买后 N 天有效」两种模式。
  • 适用门店支持多选，默认全部门店可用。
  • 可配置同一用户单日最大核销次数，防止异常使用。

2.3 分销体系（模块二）

• 分销角色：
  • 主理人：可查看名下所有门店或指定门店的分销数据。
  • 分店店长：只能查看绑定门店的分销订单与收益。
• 分销绑定关系：
  • 每个分销商拥有专属链接/二维码，链接中携带 distributorId。
  • 用户通过该链接/二维码下单购买权益卡后，建立「用户-分销商」绑定关系。
  • 订单记录对应的 distributorId、角色类型与来源渠道。
• 分销层级：当前版本仅支持单层分销（一个用户对应一个分销商）。

2.4 收益逻辑（模块二）

• 预估收益：在用户完成支付时，根据权益卡的分佣配置生成，对应订单金额的预计分成。
• 可提现收益：在商户完成核销时，根据本次核销对应金额，将部分预估收益转为可提现余额。
• 计算规则：
  • 支持平台级默认分佣比例与单张权益卡自定义分佣比例（后者优先）。
  • 单次核销金额可按「订单总额 × 核销次数比例」或权益明细单价进行换算。
  • 分销金额 = 对应核销金额 × 分销比例。

2.5 核销闭环（跨模块）

1. 用户在小程序「我的权益」中选择一张未用完的权益卡，点击「出示核销码」。
2. 系统生成一次性核销码（或二维码），包含权益卡 ID、用户 ID、剩余次数、分销商摘要信息。
3. 商户在管理后台或门店端 PC 扫码/输入核销码，完成有效性校验与剩余次数校验。
4. 在事务中写入核销记录、扣减剩余次数、更新分销商预估收益与可提现余额。
5. 核销结果实时反馈给用户与商户，并可在「核销历史」页面中查询。

三、后端需求（Midway.js / cool-admin-midway）

3.1 核心数据表（需求级字段）

以下为本模块的核心数据实体，具体字段以 database_schema 文档和 Entity 实现为准：

表名	说明	关键字段（需求层）
eps_equity_card	权益套餐卡定义	cardNo、title、subTitle、coverUrl、tags、totalTimes、remainTimes、validType、validStart/validEnd、validDays、applyShopIds、status、price、commissionRate、configJson
eps_equity_card_instance	权益卡实例/卡券	cardId、cardNo、activeCode、status、bindUserId、bindOrderId、totalTimes、remainTimes、validStart/validEnd、remark
eps_order	权益订单/分销关联	orderNo、userId、cardId、payPrice、distributorId、distributorRole、estimatedCommission、settledCommission、status
eps_verification_log	权益核销记录	orderId、cardId、userId、shopId、verifyCode、times、amount、commissionAmount、status、operatorId
eps_distributor	分销商信息	userId、role、name、shopId、qrcodeUrl、totalEstimated、totalSettled、balance、status

3.2 Service 层

• 权益卡定义 Service（模块一）：提供标准 CRUD 能力，支持配置适用门店、有效期、分佣比例与 JSON 套餐内容。
• 卡券实例/发放与激活 Service（模块一）：
  • 负责批量生成卡券，导出卡号+激活码。
  • 处理用户端输入卡号/激活码的激活逻辑。
  • 提供卡券状态管理（未激活/已激活/已用完/冻结/作废）。
• 核销 Service（模块一）：
  • 校验核销码有效性、权益有效期与剩余次数、门店适用范围等。
  • 在事务内完成核销记录写入、卡券剩余次数更新、关联订单结算字段更新。
• 分销结算 Service（模块二）：
  • 根据平台/权益卡配置计算预估分佣金额。
  • 提供按日期或分销商维度的收益统计能力。

3.3 Controller 接口

• BaseService 标准 CRUD：
  • 模块一：eps_equity_card、eps_equity_card_instance。
  • 模块二：eps_distributor、eps_order。
• 自定义接口（模块一：卡券与核销）：
  • POST /admin/eps/equityCardInstance/batchGenerate：批量生成卡券。
  • GET /admin/eps/equityCardInstance/export：导出卡号与激活码。
  • POST /admin/eps/equityCardInstance/changeStatus：冻结/作废/恢复卡券。
  • POST /admin/eps/equityCard/verify：核销接口。
• 自定义接口（模块二：分销与统计）：
  • GET /admin/eps/distribute/stats：分销统计接口，支持按分销商和时间区间查询。

四、前端需求（Vue3 + Element Plus / cool-admin-vue）

4.1 商户管理后台（模块一：卡券）

• 权益卡发布页面：
  • 表单字段：名称、副标题、封面图上传、售价、标签、上下架状态、有效期、适用门店、分佣比例。
  • 套餐内容配置：JSON 编辑器或结构化表单，支持多条权益项的增删改。
  • UI 风格需与现有 CRUD 模块保持一致。
• 卡券发放与激活管理页面：
  • 展示卡号、激活码（部分脱敏）、关联权益卡、状态、绑定用户、来源、有效期等信息。
  • 支持批量生成卡券（配置数量、前缀、有效期等），以及导出卡券列表。
  • 支持冻结/作废/恢复单张或多张卡券。
• 核销历史列表：
  • 字段：核销时间、用户、权益卡名称、门店、核销次数、金额、分佣金额、操作人。
  • 筛选：时间区间、门店、权益卡、分销商、核销状态。

4.2 平台管理后台（模块二：分销）

• 分销商审核与管理：列表展示状态、收益统计，支持审核通过/拒绝、禁用/启用、查看明细。
• 分佣比例配置：支持全局默认与按角色（主理人/店长）配置不同分佣比例，展示覆盖关系说明。
• 分销订单监控：提供按日期/分销商的订单和收益图表与列表，并支持导出。

五、开发工作量与报价

本节在现有烘焙预约项目模块基础上，对「商户权益卡发放与核销系统」和「商户权益分销系统」两个子模块分别进行工时与报价评估，并整体略有上调。

5.1 模块一：商户权益卡发放与核销系统

子模块	功能范围	报价工作时(人天)	前端(人天)	后端(人天)	报价
权益卡定义管理	权益卡实体、Service、Controller 及后台发布/编辑页面（含 JSON 套餐配置）	9.0	4.5	4.5	¥3,600
卡券发放与激活	卡券实例表、批量生成/导出、状态管理、客户端输入卡号/激活码激活	9.0	3.0	6.0	¥3,600
核销闭环与流水	核销码生成、扫码核销接口、核销记录列表与查询统计	6.0	1.5	4.5	¥2,400
模块一小计		24.0	9.0	15.0	¥9,600

5.2 模块二：商户权益分销系统

子模块	功能范围	报价工作时(人天)	前端(人天)	后端(人天)	报价
分销商管理	分销商信息 Entity、审批流程、列表与详情页面	7.5	1.5	6.0	¥3,000
分销收益与结算	预估收益与核销结算逻辑、统计接口与分销统计页面	7.5	3.0	4.5	¥3,000
分销订单监控	分销订单列表、图表统计、导出	6.0	3.0	3.0	¥2,400
模块二小计		21.0	7.5	13.5	¥8,400

报价口径与《需求评估文档》保持一致：日均单价 ¥400/人天，报价工作时按 0.5 天取整，可与其他模块并行开发。本模块的报价综合考虑了卡券安全与风控、批量导入导出、核销流水对账、多维统计等带来的实现与测试成本。

文档版本：v1.2 · 最后更新：2026-03-13

← 返回文档总览