front/docs/客户裂变与营销体系设计方案.md

客户裂变与营销体系设计方案

文档状态：产品 + 表结构 + 接口 + 页面交互（评审通过后再开发）
编写日期：2026-07-23
关联系统：OMS 业务（docs/oms系统设计-050801.md）、客户域 / RBAC（docs/rbac系统设计-060801.md）
关联规范：docs/oms系统设计-050801.md §3（表/接口模板）、docs/前端页面设计规范.md
DDL 脚本：oms0414-back/sql/migrate_marketing_module.sql
目标读者：产品、运营、研发、测试

---

1　背景与目标

1.1 业务背景

跨境物流 OMS 以 客户下单 → 余额支付 → 渠道履约 为主链路。当前 t_customer 已有 客户分组（CustomerGroup / VIP）、余额与资金流水、主子客户（ParentCustomerId） 等基础能力，但缺少：

• 可传播的 获客归因（谁引荐了谁）；
• 与下单行为绑定的 成长体系（积分 / 等级）；
• 下单时可用的 营销工具（优惠券）；
• 对引荐人可见的 业绩与分成 闭环。

1.2 建设目标

维度	目标
获客	老客户成为分销节点，注册链接 + 二维码降低分享门槛，新客可追踪来源
留存	积分等级让高频客户有可见成长路径，与 VIP 权益挂钩
转化	优惠券在查价 / 下单环节直接抵扣，提高首单与复购
激励	引荐人可查看下级客户订单成交额，按规则获得分成
可运营	管理端可配置规则，无需改代码即可调整活动

1.3 设计原则

1. 与现有 ID 体系一致：业务归属一律使用 t_customer.Id（CustomerId），不用 JWT mapId 直接落库。
2. 与资金体系一致：余额变动走 t_customer_account_flow；佣金走 CommissionBalance，扩展 BizType 枚举。
3. 与订单计费一致：优惠券、等级折扣在 查价 / 下单 / 支付 链路上统一计算，前端只展示 priceBreakdown。
4. 主子客户边界清晰：营销权益一律归 主客户；子账号仅做业务数据隔离，不参与营销。
5. 规则可见、误操作可拦：页面须讲清业务规则，高危操作二次确认 + 服务端双保险（见 §16）。

---

2　已确认业务规则

#	决策	设计落点
1	子账号不参与营销	积分/券/分成/引荐码/等级均挂在 主客户；ResolveMarketingMainCustomerId
2	MemberLevel 替换 CustomerGroup	计价读 t_member_level.PriceTierKey；CustomerGroup 只读保留后废弃
3	分成独立账户	t_customer.CommissionBalance；可 提现 或 转入余额
4	默认分成	实付每 1000 元 → 2 元（floor 整段），BaseAmount=1000, CommissionAmount=2
5	等级与券可叠加	见 §11 叠加计费公式
6	分成触发条件	订单 deliverySuccess（派送成功） 后计算；支付成功 不 最终入账
7	引荐层级	首版 仅一级；注册后 不可 自助改绑（运营可人工修正 + 审计）
8	1 单 1 券	下单仅可选用一张券；未支付锁定 30 分钟 后自动释放
9	子账号下单	计价/券/积分/分成均归 主客户；子账号下单页须提示可能消耗主账号券
10	在途不展示分成金额	派送成功前仅展示下级订单与实付，不展示预估分成
11	分成规则快照	写 commission_detail 时快照规则参数，改规则不追溯
12	PayableAmount=0	不发积分、不产生分成
13	Salesman 与 Referrer	分开统计；分成 仅认 ReferrerCustomerId

---

3　现状与可复用能力

3.1 已有能力

能力	现状	营销方案中的用法
客户主数据	t_customer：Balance、CustomerGroup、ParentCustomerId	扩展引荐、积分、等级、CommissionBalance
个人中心	views/user/profile	邀请、等级、券、佣金入口
客户门户	customerPortalOnly、loginType=1	裂变分享、券包、收益看板
订单与支付	订单创建、余额扣款、BizType=orderPay	积分发放、券核销、分成统计
充值	t_recharge_record	佣金转余额与充值体系衔接
字典	t_dict_type / t_dict	券类型、积分、分成模式
微信	/wechat/customer/*	注册链接 H5 / 小程序 scene

3.2 新建能力域

┌─────────────────────────────────────────────────────────────────┐
│                     客户营销域（Marketing）                       │
├──────────────┬──────────────┬──────────────┬────────────────────┤
│ 裂变归因      │ 积分等级      │ 优惠券        │ 推荐分成            │
│ Referral     │ Points/Tier  │ Coupon       │ Commission         │
└──────┬───────┴──────┬───────┴──────┬───────┴─────────┬──────────┘
       └──────────────┴──────────────┴─────────────────┘
                              │
                    订单查价 / 下单 / 支付 / 派送成功
                              │
                    t_customer + t_customer_account_flow

---

4　整体玩法架构

flowchart LR
  A[客户 A 个人中心] -->|生成链接/二维码| B[客户 B 注册]
  B -->|写入引荐关系| C[归因库]
  B -->|首单/下单| D[订单]
  D -->|实付金额| E[积分发放]
  E -->|累计积分| F[等级升级]
  F -->|等级权益| G[运费折扣/专属券]
  D -->|选券| H[优惠券核销]
  D -->|派送成功| I[引荐分成]
  I -->|结算| J[客户 A 佣金账户]
  C --> I

角色	端	主要能力
主客户（引荐人）	客户门户	分享链接/二维码、下级列表、等级积分、券包、收益明细
被引荐客户	注册页 / 门户	注册绑定引荐人；下单获积分、用券
运营 / 管理员	管理后台	等级、券、分成规则、发券、数据报表
财务	管理后台	分成审核、提现审核、对账

---

5　模块一：裂变推荐

5.1 功能

个人中心 提供：

1. 专属注册链接：https://{domain}/wechat/register?ref={inviteCode}（公众号 OAuth 注册；PC 备用 /register?ref=）
2. 注册二维码：前端本地生成 PNG；小程序码 scene 同码（若启用）
3. 归因：ReferrerCustomerId、ReferralBindTime、ReferralChannel（微信注册为 wechat）
4. ref 暂存：localStorage 7 天 last-touch + OAuth state 双保险

5.2 规则

规则项	默认值	说明
绑定时机	注册成功一次性写入	未登录访问 cookie/localStorage 暂存 ref
是否可改绑	否（客户侧）	运营后台可人工修正 + 审计；只影响改绑后的新订单（见 §24.5）
老客点链接	不覆盖	已有 ReferrerCustomerId 的客户再次访问 ref 链接 不更新 归因
ref 归因策略	last-touch	cookie 7 天内以 最后一次 有效 ref 为准（仅对新注册生效）
自引荐	禁止	同手机/同主体注册小号需风控拦截（见 §19）
层级	一级
链接有效期	长期；cookie 7 天
注册页展示	校验 ref 后展示	「您由 {昵称/编号} 邀请注册」，增强确认、减少错绑纠纷
与 Salesman	并存	内部销售与客户引荐 分开统计；分成只认 Referrer
引荐人停用	邀请码 Disabled	已绑定下级关系保留；该码 不可再带来新注册

5.3 拓展玩法

邀请海报、话术模板、邀请排行榜、邀请任务、渠道参数 utm_source。

---

6　模块二：积分等级

6.1 功能

管理员：等级 CRUD（名称、累计积分门槛、价区键、额外折扣率、权益文案）。
客户侧：支付成功后发积分；累计达标自动升级（首版 不自动降级）。

6.2 积分规则（建议默认）

规则	示例
按实付	1 元 = 1 积分（基数 = PayableAmount）
首单加倍	可配置 ×2
单笔上限	10 000 分
过期	首版可不做过期

6.3 与 CustomerGroup 关系

已确认：MemberLevel 替换 CustomerGroup。计价入口改为 PriceTierKey；管理端客户编辑用等级下拉。

原 CustomerGroup	MemberLevel	PriceTierKey
Normal	普通会员	普通客户
Vip1	银卡	VIP1
Vip2	金卡	VIP2
Vip3+	钻石	VIP3

---

7　模块三：优惠券

7.1 券模板配置

配置项	说明
券类型	满减、折扣、无门槛立减、运费券
面额/折扣	满 100 减 10、9.5 折等
库存	全站上限 + 每客户领取上限
有效期	固定日期 / 领取后 N 天
适用范围	最低金额、产品/渠道/国家
状态	草稿 / 进行中 / 已结束

7.2 券类型枚举

类型	计算
fixed_off	满足 minAmount 减 faceValue
percent_off	应付 × 折扣率，可封顶
direct_off	直接减 faceValue
shipping_off	仅抵扣运费（P1 可简化为比例）

7.3 生命周期

创建模板 → 领取/发放 → 实例 Available
  → 下单 Locked（30 分钟）→ 支付成功 Used
  → 取消/超时未支付 → 释放 Available（定时 Job）

用券约束：

规则	说明
每单张数	1 单 1 券（首版不可叠加多张）
满减门槛	按 AmountAfterLevel（等级折后金额） 判断 MinOrderAmount
锁定超时	下单预占后 30 分钟 未支付自动释放；改单/重新查价须重新校验
应付为 0	允许下单时，不发积分、不产生分成（§2 #12）
批量发券	目标为子账号编号时 自动归并主客户 并记入操作日志

订单记录：CouponInstanceId、CouponDiscountAmount、MemberLevelDiscountAmount 等快照，便于退款。

---

8　模块四：推荐分成

8.1 客户侧

• 下级列表、订单笔数/实付汇总
• 分成明细：待派送 / 待结算 / 已结算 三分（见 §16）；派送成功前不展示分成金额
• 佣金转余额 / 提现申请

8.2 统计口径

指标	口径
成交金额	实付（已扣券），不含全额退款
有效订单（分成）	OrderStatus = deliverySuccess
分成基数	剩余实付；派送成功时 计算
归因范围	仅直接下级
单月封顶	MonthlyCap（可 NULL=不限）；自然月累计达顶后 超出部分不计（§24.4）
零元单	PayableAmount=0 不产生 分成

8.3 结算流程

支付成功 → 门户仅展示下级订单与实付（不展示分成金额）
  → deliverySuccess → 写 commission_detail Pending + 规则快照，EligibleTime
  → EligibleTime + FreezeDays 且无退款
  → Settled，CommissionBalance += 金额，写 referralCommission 流水

不触发：派送失败、问题件、已删除、全额退款、未达派送成功。

8.4 默认公式（floor 整段）

CommissionAmount = floor(BasePayableAmount / 1000) × 2

例：实付 2500 → 4 元。结算服务入口：ReferralCommissionService.OnOrderDeliverySuccessAsync(orderId)；禁止在支付回调写最终分成。

8.5 佣金提现 / 转余额

WithdrawType	行为
2 转余额	审核通过 → CommissionBalance 减、Balance 增，commissionToBalance
1 提现	审核通过 → CommissionBalance 减，commissionWithdraw；线下打款

---

9　组合营销策略

新客裂变闭环：A 分享 → B 注册 → 新人券包 → B 首单双倍积分 → A 首单分成 + 感谢券 → B 升级复购。
老客唤醒：保级提醒、沉睡客户发券。
大促：限时券 + 等级折扣（配置叠加或取最优）。
与销售协同：ReferrerCustomerId 与 Salesman 分开统计。

---

10　主客户解析

sessionCustomer = OmsSessionHelper.ResolveSessionCustomerAsync(...)
marketingCustomer =
  sessionCustomer.ParentCustomerId == null
    ? sessionCustomer
    : 查 ParentCustomerId 对应主客户

场景	使用 Id
引荐码、积分、券、佣金	主客户 Id
订单 CustomerId	不变（可为子账号，数据隔离）
营销计价、快照	下单时用 主客户 等级/券

Helper：Oms.Application/Shared/MarketingCustomerHelper.cs
子账号调用营销 API 归并主客户；前端 ParentCustomerId != null 隐藏 全部营销入口。

子账号下单（须写进下单页提示）：

项	规则
计价等级/价区	用 主客户 MemberLevelId / PriceTierKey
可用券	主客户券包；核销记主客户
积分	支付成功后记 主客户
引荐分成	订单 CustomerId 解析到主客户 → 取其 ReferrerCustomerId 作为引荐人
门户 UI	隐藏营销中心；下单页 须提示「本单将使用主账号会员价/优惠券（如有）」

---

11　等级 + 优惠券叠加计费

11.1 计算步骤

步骤	字段	公式
① 价区	PriceTierKey	主客户等级 → 卖价 JSON 键
② 等级价小计	ReceivableSubtotal	按价区计价后的合计
③ 等级额外折	LevelDiscountAmount	round(ReceivableSubtotal × ExtraDiscountRate, 2)
④ 券前金额	AmountAfterLevel	ReceivableSubtotal - LevelDiscountAmount
⑤ 券抵扣	CouponDiscountAmount	按券类型，且 ≤ AmountAfterLevel
⑥ 应付	PayableAmount	max(0, AmountAfterLevel - CouponDiscountAmount)

11.2 示例

金卡 VIP2 + 额外 1%：价区价 90 → 等级折 0.9 → 89.1 → 满 80 减 10 → 应付 79.1 元。

11.3 积分与分成基数

用途	基数	时机
积分	PayableAmount	支付成功
引荐分成	下级 PayableAmount	派送成功

11.4 退款

对象	规则
券	全额退款退回 Available；部分不退
积分	按比例扣回
分成	未派送成功不产生；Pending 按剩余实付重算；已 Settled 负向流水扣回（§24.3）

11.5 priceBreakdown 出参

{
  "receivableSubtotal": 90.00,
  "levelDiscountAmount": 0.90,
  "couponDiscountAmount": 10.00,
  "payableAmount": 79.10,
  "memberLevelId": 3,
  "memberLevelName": "金卡会员",
  "priceTierKey": "VIP2",
  "couponInstanceId": 1001
}

---

12　数据表结构与实体规范

必须遵循 docs/oms系统设计-050801.md §3.1～§3.2；DDL 脚本：oms0414-back/sql/migrate_marketing_module.sql。

12.1 必备字段（聚合根 / 业务单据表）

凡 C# 实体继承 OmsAuditedAggregateRoot 的表，建表 必须 包含：

字段	类型	说明
Id	INT AUTO_INCREMENT	主键
IsDeleted	TINYINT DEFAULT 0	软删除：0-否，1-是
ConcurrencyStamp	CHAR(36)	并发戳；默认 '00000000-0000-0000-0000-000000000000'（禁止 DEFAULT (UUID())，见 OMS §3.1.2）
CreateUserId	INT DEFAULT 0	创建人（CurrentUser.GetId<int>()，禁止前端传入）
CreateTime	DATETIME	创建时间
UpdateUserId	INT NULL	更新人
UpdateTime	DATETIME NULL	更新时间

流水 / 审计类（如 t_customer_points_flow、t_marketing_audit_log）对齐 t_customer_account_flow：同样继承 OmsAuditedAggregateRoot，含 ConcurrencyStamp 与完整审计列。

逻辑外键：不设物理 FK，仅索引 + 注释（与 db.sql 一致）。

12.2 实体基类映射

表	C# 实体	基类	聚合
t_member_level	MemberLevel	OmsAuditedAggregateRoot	Marketing
t_member_points_rule	MemberPointsRule	OmsAuditedAggregateRoot	Marketing
t_customer_referral_code	CustomerReferralCode	OmsAuditedAggregateRoot	Marketing
t_coupon_template	CouponTemplate	OmsAuditedAggregateRoot	Marketing
t_coupon_instance	CouponInstance	OmsAuditedAggregateRoot	Marketing
t_referral_commission_rule	ReferralCommissionRule	OmsAuditedAggregateRoot	Marketing
t_referral_commission_detail	ReferralCommissionDetail	OmsAuditedAggregateRoot	Marketing
t_commission_withdraw_request	CommissionWithdrawRequest	OmsAuditedAggregateRoot	Marketing
t_customer_points_account	CustomerPointsAccount	OmsAuditedAggregateRoot	Marketing（含 Version 乐观锁）
t_customer_points_flow	CustomerPointsFlow	OmsAuditedAggregateRoot	Marketing
t_marketing_audit_log	MarketingAuditLog	OmsAuditedAggregateRoot	Marketing

路径：Oms.Domain/MarketingAggregate/Entities/*、Repositories/I*Repository.cs。

12.3 业务字段与编号规范

表	业务必填 / 特征字段
t_customer（扩展）	ReferrerCustomerId、MemberLevelId、CommissionBalance；扩展列 无 ConcurrencyStamp（主表已有）
t_customer_referral_code	CustomerId UNIQUE、InviteCode UNIQUE、Status
t_member_level	LevelCode UNIQUE、PriceTierKey、MinPoints、Sort、Status（EnableStatus）
t_coupon_template	TemplateCode UNIQUE、CouponType、Status；IssuedQuantity ≤ TotalQuantity
t_coupon_instance	CouponCode UNIQUE、TemplateId、CustomerId、ValidStartTime/EndTime、LockExpireTime
t_referral_commission_detail	OrderId+ReferrerCustomerId UNIQUE、RuleSnapshotJson、EligibleTime
t_commission_withdraw_request	SerialNumber UNIQUE（规则 CMW{yyyyMMddHHmmss}{6位随机}）、AuditBy/AuditTime（对齐充值审核）
t_customer_points_flow	BizType、BizId、BizNo（订单号）；无 SerialNumber，以 Id + Biz 索引
t_order（扩展）	营销快照：MemberLevelId、PriceTierKey、ReceivableSubtotal、LevelDiscountAmount、CouponInstanceId、CouponDiscountAmount、PayableAmount

佣金入账：CommissionBalance 变动须同步写 t_customer_account_flow，BizType = referralCommission / commissionToBalance / commissionWithdraw / marketingAdjust（与 §11 资金体系一致）。

12.4 表清单与 ER

表	说明
t_customer（扩展）	Referrer*、MemberLevelId、CommissionBalance
t_customer_referral_code	主客户邀请短码
t_member_level / t_member_points_rule	等级与积分规则
t_customer_points_account / _flow	积分账户与流水
t_coupon_template / t_coupon_instance	券模板与实例
t_referral_commission_rule / _detail	分成规则与明细
t_commission_withdraw_request	提现/转余额（对齐 t_recharge_record 审核字段）
t_marketing_audit_log	高危操作审计
t_order（扩展）	营销快照

erDiagram
  t_customer ||--o| t_customer_referral_code : "主客户 1:1"
  t_customer ||--o| t_customer_points_account : "主客户 1:1"
  t_customer }o--|| t_member_level : MemberLevelId
  t_customer ||--o{ t_coupon_instance : CustomerId
  t_coupon_template ||--o{ t_coupon_instance : TemplateId
  t_customer ||--o{ t_referral_commission_detail : ReferrerCustomerId
  t_order ||--o| t_referral_commission_detail : OrderId

---

13　关键业务流程

13.1 注册带引荐

/register?ref=ABC123 → 缓存 ref → 提交注册
  → 校验 InviteCode → ReferrerCustomerId
  → 创建客户 → （可选）新人券

13.2 下单用券 + 积分 + 分成

查价 + availableCoupons → 选券重算
  → 支付成功 → 核销券 → 积分 → 检查升级
  → （分成）等 deliverySuccess
  → OnOrderDeliverySuccessAsync → Pending
  → Job 冻结期满 → Settled

13.3 退款

回退积分、取消/调整 Pending 分成、按规则退券。

---

14　接口设计

必须遵循 docs/oms系统设计-050801.md §3.2～§3.3 与现有 Service 模板（如 KpiAreaService、RechargeService、CustomerAccountFlowService）。

14.0 公共约定

项	约定
暴露方式	Fake 框架：ApplicationService + [HttpPost] / [HttpGet]，无手写 Controller
Swagger 分组	[ApiExplorerSettings(GroupName = "OMS-Marketing")]
管理端路由	POST /marketing/{resource}/{action}（list / create / update / delete），与 /channel/kpi-area/* 一致
门户读接口	GET /marketing/{resource}/{action} + [FromQuery]（对齐 /customer/account-flow/list）
门户写接口	POST /marketing/{resource}/{action} + JSON Body
分页入参	Page（从 1）、PageSize；OmsDocHelper.NormalizePage / NormalizePageSize（上限 200）
分页出参	OmsPageResult<T>：Items + Total（long，非 totalCount）
主键操作	删除/详情用 IdInput（Dtos/Shared/IdInput.cs）
保存	*SaveInput：Id? 为空 create，有值 update（对齐 KpiAreaSaveInput）
审计	Create/Update/Delete 写 CreateUserId/UpdateUserId；禁止信任前端传操作人
客户会话	门户须 loginType=1；MarketingCustomerHelper.ResolveMarketingMainCustomerIdAsync
管理端	loginType=0；列表 不 注入单一 CustomerId；门户列表 强制 主客户 Id
权限码	见 §20；前端 meta.permission 对齐（后端细粒度拦截待 RBAC 完善，Service 内仍须校验）

DTO 目录（Oms.Application/Dtos/Marketing/）：

MemberLevelListInput / MemberLevelSaveInput / MemberLevelOutput
CouponTemplateListInput / CouponTemplateSaveInput / CouponTemplateOutput
CouponGrantInput / CouponInstanceListInput / CouponInstanceOutput
ReferralCommissionRuleSaveInput / CommissionDetailListInput / ...
MarketingReferralMyInviteOutput / MarketingMemberOverviewOutput / ...

Service 目录（Oms.Application/Services/Marketing/）：

类	职责
MarketingMemberLevelService	等级 CRUD
MarketingPointsRuleService	积分规则、调账、流水查询
MarketingCouponTemplateService	券模板 CRUD、停发
MarketingCouponGrantService	批量发券
MarketingCommissionRuleService	分成规则
MarketingCommissionAdminService	分成明细、提现审核
MarketingReferralAdminService	引荐树、改绑
MarketingPortalReferralService	门户：邀请、下级
MarketingPortalMemberService	门户：等级、积分
MarketingPortalCouponService	门户：券包、领取
MarketingPortalCommissionService	门户：收益、提现

14.1 客户门户接口

方法	路径	入参	出参
GET	/marketing/referral/my-invite	—	ReferralMyInviteOutput
GET	/marketing/referral/referees	ReferralRefereeListInput（Page, PageSize）	OmsPageResult<ReferralRefereeOutput>
GET	/marketing/referral/validate-code	code（AllowAnonymous）	ReferralValidateCodeOutput
GET	/marketing/member/overview	—	MemberOverviewOutput
GET	/marketing/member/points-flow	PointsFlowListInput	OmsPageResult<PointsFlowOutput>
GET	/marketing/coupon/my-list	CouponMyListInput（status）	OmsPageResult<CouponInstanceOutput>
GET	/marketing/coupon/available-for-order	CouponAvailableInput	List<CouponAvailableOutput>
POST	/marketing/coupon/receive	IdInput（templateId）	CouponInstanceOutput
GET	/marketing/commission/overview	—	CommissionOverviewOutput
GET	/marketing/commission/details	CommissionDetailListInput	OmsPageResult<CommissionDetailOutput>
GET	/marketing/commission/withdraw/list	CommissionWithdrawListInput	OmsPageResult<CommissionWithdrawOutput>
POST	/marketing/commission/transfer-to-balance	CommissionTransferInput	—
POST	/marketing/commission/withdraw/apply	CommissionWithdrawApplyInput	CommissionWithdrawOutput

注册扩展（/customer/* 或 Auth）：CustomerCreateInput 增加 InviteCode? → ReferrerCustomerId。

14.2 管理端接口

方法	路径	说明	权限
POST	/marketing/member-level/list	分页列表	Marketing.Level.View
POST	/marketing/member-level/create	新增	.Create
POST	/marketing/member-level/update	更新	.Update
POST	/marketing/member-level/delete	软删	.Delete
POST	/marketing/points-rule/get	当前规则	Marketing.PointsRule.Edit
POST	/marketing/points-rule/update	更新规则	同上
POST	/marketing/points-flow/list	积分流水	Marketing.Points.View
POST	/marketing/points/adjust	人工调账	Marketing.Points.Adjust
POST	/marketing/coupon-template/list	券模板列表	Marketing.Coupon.Template.View
POST	/marketing/coupon-template/create	创建	.Create
POST	/marketing/coupon-template/update	更新	.Update
POST	/marketing/coupon-template/publish	Draft→Active	.Update
POST	/marketing/coupon-template/end	停发	.Update
POST	/marketing/coupon/grant	批量发券	Marketing.Coupon.Grant
POST	/marketing/coupon-instance/list	券实例查询	Marketing.Coupon.Template.View
POST	/marketing/commission-rule/get	当前分成规则	Marketing.Commission.Rule.Edit
POST	/marketing/commission-rule/update	更新规则	同上
POST	/marketing/commission-detail/list	分成明细	Marketing.Commission.View
POST	/marketing/commission-detail/adjust	人工调整	Marketing.Commission.Adjust
POST	/marketing/commission-withdraw/list	提现列表	Marketing.Commission.Withdraw.View
POST	/marketing/commission-withdraw/approve	审核通过	.Audit
POST	/marketing/commission-withdraw/reject	驳回	.Audit
POST	/marketing/referral/tree	一级引荐关系	Marketing.Referral.View
POST	/marketing/referral/rebind	改绑	Marketing.Referral.Rebind

14.3 订单扩展（OrderService，非 Marketing Service）

方法	路径	变更
POST	/order/price-check	入参 couponInstanceId?；出参 priceBreakdown、availableCoupons
POST	/order/parcel/create 等	营销快照；支付成功写积分；不含分成结算
内部	订单 → deliverySuccess	ReferralCommissionService.OnOrderDeliverySuccessAsync

---

15　枚举与字典

补充 docs/itfx枚举说明.md 与 t_dict：

字典/枚举	值
coupon_type	fixed_off, percent_off, direct_off, shipping_off
coupon_template_status	0 Draft, 1 Active, 2 Ended
coupon_instance_status	1 Available, 2 Locked, 3 Used, 4 Expired
commission_status	1 Pending, 2 Settled, 3 Cancelled
commission_withdraw_type	1 External, 2 ToBalance
points_change_type	1 Earn, 2 Consume, 3 Adjust, 4 RefundClawback

---

16　页面交互与防误操作

营销涉及资金与折扣，页面 必须 讲清规则并防止误操作。

16.1 交互设计原则

原则	说明
规则可见	每页顶部固定区域说明规则、适用对象、生效时机
后果可预期	保存/发放前展示影响范围 + 数量/金额估算
误操作可拦	高危操作二次确认；批量操作输入确认词 确认发放
前后端双保险	UI + 服务端校验库存、状态、主客户归属
可审计	关键操作写 t_marketing_audit_log

布局遵循 docs/前端页面设计规范.md：table-toolbar、FormPro/ModalPro、var(--app-primary-color)。

16.2 规则说明组件

页面级（必选）：容器顶部 .marketing-page-tip：

<a-alert type="info" :show-icon="true" class="marketing-page-tip">
  {{ t('marketing.pageTip.xxx') }}
</a-alert>

• 文案 3～5 行，写清主客户/子账号、生效时机、不可撤销项
• 资金风险用 warning；不要只写「请谨慎操作」

弹窗内：ModalPro 顶部 a-alert（同渠道配置 modal-form-tip）。
字段级：价区键、额外折扣率、冻结天数用 tooltip 或 extra 说明。

状态标签（分成/券/提现）：

状态	颜色	说明
待派送成功	arcoblue	未达派送成功，不展示分成金额，仅展示订单与实付
待结算 Pending	orange	已派送成功，冻结期内
已结算 Settled	green	已入佣金账户
已取消 Cancelled	gray	退款/派送失败/人工取消

16.3 页面须展示的业务规则（i18n：marketing.rule.*）

全局：营销权益归主客户；等级替换客户组且不追溯历史订单；叠加顺序见 §11；引荐仅一级、不可自助改绑。

裂变：链接绑定主客户；注册数 ≠ 下单数；以下级实付为准。

积分等级：支付成功后发积分；自动升级不自动降级；改 MinPoints/价区键只影响之后。

优惠券：不可转让；停发不影响已领券；改面额不影响已发券；批量发券受库存与上限约束。

分成（重点）：仅 deliverySuccess 后计算；默认 1000→2 元 floor（999 元 = 0 分成，页内须举例）；Pending → 冻结 → CommissionBalance；支付成功 不展示分成金额；单月可有封顶 MonthlyCap。

下单：展示完整 priceBreakdown 四行；选券必须重新查价；不可用券展示原因。

16.4 管理端分页面要求

页面	要点
等级配置	tip 说明价区键；改价区/额外折扣 Modal 摘要；禁止删已用等级
积分规则	tip 支付成功发放；改比例不追溯；人工调账必填原因 ≥10 字
券模板	分步向导；发布二次确认；停发说明已领券仍有效；总量只允许增大
批量发券（高危）	warning tip；预览 N/M 人、库存 X；超 100 人或 >5000 元输入 确认发放
分成规则	tip 加粗派送成功条件；保存新旧对比；禁止一键重算历史
分成明细	列 EligibleTime；禁止 Pending 直接改 Settled
提现审核	展示余额与申请额；拒绝必填原因；禁止一键全部通过
引荐改绑（高危）	仅管理员；原因 ≥20 字；警告不影响已结算；写审计日志

16.5 客户门户分页面要求

页面	要点
子账号	隐藏全部营销入口
邀请好友	tip：一级、不可改绑、派送成功 才有分成
我的等级	价区对人话翻译；进度条 + 积分规则 tooltip
我的优惠券	Tab 三分；≤3 天过期 orange
推荐收益	tip 三分待派送/待结算/已结算；待派送不展示分成金额；派送成功后显示金额
下单选券	priceBreakdown 默认展开；换券 Toast + 金额高亮；提交确认券抵扣；子账号须提示消耗主账号券

16.6 高危操作分级

级别	操作	UI
L1	查看、导出	无
L2	单条发券、编辑草稿、小额转余额	popconfirm / Modal
L3	批量发券、发布模板、改分成规则、改价区键	Modal + 摘要；超阈值确认词
L4	引荐改绑、强制入账、大额调账	L3 + 原因 + 审计

16.7 后端防线（与 UI 配套）

场景	校验
发券	库存、PerCustomerLimit、Active、主客户
核销	归属、有效期、门槛；Locked 防并发
改等级	禁止删已引用；不 retroactive
分成	必须 deliverySuccess；EligibleTime + FreezeDays；MonthlyCap；规则快照；退款扣回
佣金转出	余额足够；无冲突申请；进行中申请冻结可用额
引荐改绑	禁自引荐、禁环、审计；不 retroactive 历史单

审计表 t_marketing_audit_log：Action、OperatorId、TargetType/Id、BeforeJson/AfterJson、Remark。

16.8 典型营销事故与防护

事故	防护
误发大量无门槛券	确认词 + 库存硬顶 + Job 限流
改错价区键	保存前受影响客户数 + 试算
支付后显示「已赚分成」	门户三分状态 + 文案
券重复核销	Locked + 释放 Job
子账号看到佣金	前端隐藏 + API 主客户解析
派送失败仍分成	仅 deliverySuccess 写 Pending
以为改规则会追溯	每页 tip + 保存 Modal

16.9 i18n 与验收

• 文案走 marketing.*，确认框含具体数字
• 示例：marketing.confirm.grantCoupon = 「将向 {count} 个客户发放「{templateName}」共 {total} 张，预估最大抵扣 {amount} 元，发放后不可撤回。」

验收 checklist：

• 每页有 marketing-page-tip
• Modal 有规则 tip
• L2+ 二次确认；L3 含摘要/确认词
• 下单完整 priceBreakdown + 选券重查价
• 子账号无营销入口；下单有「使用主账号价/券」提示
• 推荐收益 待派送不展示分成金额；待结算/已结算区分清晰
• 关键操作有审计日志
• 遵循 §24 边界规则

---

17　管理端功能清单

菜单	功能
营销 · 等级配置	CRUD 等级、价区键、额外折扣
营销 · 积分规则	获取比例、上限、调账
营销 · 券模板	创建/停发/库存
营销 · 手动发券	按客户编号批量发放
营销 · 分成规则	1000/2、冻结期、封顶
营销 · 分成明细	查询、人工调整
营销 · 引荐关系	一级关系、改绑
营销 · 数据看板	注册来源、券核销、分成支出

---

18　客户门户功能清单

入口	功能
邀请好友	链接、二维码、邀请记录
我的等级	等级、积分、进度、权益
积分明细	流水（含订单号）
我的优惠券	可用/已用/过期
推荐收益	下级、汇总、分成（在途/待结算/已结算）
下单/查价	选券、priceBreakdown

---

19　风控与合规

风险	措施
刷单骗积分/券	延迟发放、异常审核、IP 频率限制
自引荐/小号	手机唯一、同 IP 阈值
券囤积	领取上限、短有效期
分成套利	仅派送成功后计算、冻结期、退款扣回、MonthlyCap、PayableAmount=0 不计
运营误操作	§16 确认词、tip、审计
人工刷派送成功	ForceTrigger + L4；默认仅轨迹入口
子账号误用主账号券	下单页提示 + API 主客户解析
多级分销	首版仅一级
金额一致性	服务端计费为准
主子账号	权益归主客户；子账号隐藏入口

---

20　权限码

Marketing.Level.View / .Create / .Update / .Delete
Marketing.PointsRule.Edit
Marketing.Points.View / .Adjust
Marketing.Coupon.Template.View / .Create / .Update
Marketing.Coupon.Grant
Marketing.Commission.Rule.Edit
Marketing.Commission.View
Marketing.Commission.Adjust
Marketing.Commission.ForceTrigger
Marketing.Commission.Withdraw.View / .Audit
Marketing.Referral.View / .Rebind
Marketing.Emergency.Disable

门户接口：无 Permission，仅 loginType=1 + 主客户解析。

---

21　涉及改动清单

21.1 后端（oms0414-back）

模块	路径	说明
SQL	sql/migrate_marketing_module.sql	遵循 §12.1 必备字段
Domain	Oms.Domain/MarketingAggregate/	Entities + Enums + Repositories
Domain	CustomersAggregate/Customer.cs、OrdersAggregate/Order.cs	扩展字段
Application	Shared/MarketingCustomerHelper.cs	主客户解析
Application	Services/Marketing/*.cs	见 §14.0 Service 清单
Application	Dtos/Marketing/*.cs	ListInput / SaveInput / Output
Application	Services/Orders/*	查价、支付、派送成功钩子
Application	Jobs/CommissionSettleJob.cs	冻结期结算
Auth/Customer	注册 InviteCode	归因

实体与仓储命名：与渠道模块一致，如 IMemberLevelRepository、MemberLevelRepository（SqlSugar 实现放 Infrastructure 层）。

21.2 前端（oms0414）

模块	改动
门户	views/user/profile/**、注册页 ?ref=
管理端	views/marketing/**（遵循 §16）
下单	选券 UI、priceBreakdown
API/路由/i18n	api/marketing/**、router/.../marketing.ts

21.3 文档

文件	改动
docs/itfx枚举说明.md	营销枚举
docs/oms系统设计-050801.md	营销模块索引（可选）

---

22　分阶段实施

阶段	交付	依赖
M1	DDL + MarketingCustomerHelper + MemberLevel 替换 CustomerGroup 计价	SQL
M2	引荐码、注册归因、邀请页（§16.5）	M1
M3	券模板/发券/核销 + 查价 breakdown（§16.4 券相关）	M1
M4	积分发放 + 等级升级	M3
M5	分成 + 结算 Job + 佣金账户 + 提现（§16 分成文案）	M2,M3
M6	管理端营销菜单 + 报表 + 审计	M2–M5

建议顺序：M1 → M2 → M3 → M4 → M5 → M6。

---

23　待实现细节（编码时再定）

1. floor 整段 vs 比例分成 — 当前默认 floor（999 元 = 0 分成，已在 §24.4 说明）。
2. shipping_off 首版是否简化为整单比例抵扣。
3. 转余额 是否 ≤500 元免审；最低提现额 与手续费。
4. CustomerGroup 列 何时物理删除（建议运行 2 版本后）。
5. 积分是否可消耗（首版仅升级用，不抵扣运费）。
6. 注册入口 PC / 微信 H5 / 小程序范围与 ref 跨端一致性。
7. 销售店铺单、代客下单 是否一律参与营销（建议：仅客户余额支付的业务订单，见 §24.8）。
8. 价区键缺失 时降级普通价还是报错（建议：降级普通价 + 管理端告警）。

---

24　边界与争议规则

本节为 §2 已确认规则的 展开说明，开发与客户/管理端文案 必须一致。

24.1 优惠券

#	规则
1	1 单 1 券；不可叠加多张
2	下单预占 Locked，30 分钟 未支付由 Job 释放为 Available
3	满减/折扣门槛基数 = AmountAfterLevel（等级价 + 额外折扣后）
4	改产品/重量/国家后 重新查价，券可能失效，须返回不可用原因
5	全额退款 → 券退回；部分退款不退券
6	运营批量发券：客户编号为子账号 → 解析到主客户 再发放
7	PayableAmount=0 → 允许支付则 不发积分、不产生分成

24.2 引荐归因

#	规则
1	仅新注册 写入 ReferrerCustomerId；老客户点链接 不覆盖
2	cookie last-touch，有效期 7 天；链接本身长期有效
3	注册页校验 ref 成功后展示邀请人信息
4	禁止自引荐；同手机号/同证件（若采集）/异常 IP 频率限制
5	后台创建客户可手工录入引荐人，ReferralChannel=manual
6	引荐人账号停用 → 邀请码 Disabled；已有下级关系保留
7	Salesman 与 Referrer 分开统计；分成 只认 ReferrerCustomerId

24.3 分成、退款与状态机

#	规则
1	门户：派送成功前 不展示分成金额，只展示下级订单列表与实付
2	触发：OrderStatus → deliverySuccess；OnOrderDeliverySuccessAsync 幂等（一单一引荐人一条明细）
3	写 Pending 时 快照规则：BaseAmount、CommissionAmount、FreezeDays、MonthlyCap（JSON 或冗余列）
4	部分退款：冻结期内 Pending 按剩余实付重算；已 Settled → marketingAdjust 负向流水 扣减 CommissionBalance（不足扣到 0，记欠账备注）
5	状态回退（deliverySuccess → 其他）：Pending → Cancelled；已 Settled → 走扣回
6	人工改状态为派送成功：默认 与轨迹回写同一入口；若管理端强改须 Marketing.Commission.ForceTrigger + L4 审计
7	floor 整段：实付 999 元 → 0 分成；邀请页/规则页须举例说明

MonthlyCap（单月封顶）：

• 统计维度：引荐人主客户 + 自然月（EligibleTime 所在月）
• 结算 Job 入账前：若 本月已 Settled + 本笔 > MonthlyCap，则本笔 按剩余额度截断或整笔 Cancelled（实现时二选一，推荐 截断入账）
• MonthlyCap=NULL 表示不限；管理端配置页与门户 tip 须说明

24.4 积分与等级

#	规则
1	积分在 支付成功 后发放；基数 PayableAmount；升级即时生效（同一支付回调内检查）
2	首版 不自动降级；运营调高 MinPoints 不批量降级 存量客户
3	运营 手动改客户等级：只改 MemberLevelId，不修改 TotalPoints
4	禁用某等级：禁止 新分配，存量客户 沿用到下次升级
5	TotalPoints 用于定级；AvailablePoints 首版与 Total 同步（仅升级用时不消耗）
6	产品卖价 JSON 无对应 PriceTierKey 时：回退 普通客户 价并记告警（§23 #8）

24.5 引荐改绑

#	规则
1	仅管理端、Marketing.Referral.Rebind、原因 ≥20 字、审计日志
2	不影响 已 Settled 分成
3	Pending / 未产生分成 的订单：以 下单时 订单快照的 RefereeCustomerId → ReferrerCustomerId 为准；改绑 不 retroactive 改历史单
4	改绑后 新订单 按新引荐关系计算

24.6 佣金提现与转余额

#	规则
1	进行中提现/转余额申请 冻结 对应 CommissionBalance 可用额度
2	拒绝须填原因，客户门户可见
3	转余额：commissionToBalance 流水，与充值记录 分开对账
4	最低提现额、手续费见 §23（编码前产品确认）

24.7 隐私与展示

#	规则
1	引荐人看下级：默认展示 客户编号 + 注册时间 + 是否首单/是否已有派送成功单；姓名/手机 脱敏（如编号完整、手机中间四位 *）
2	下级订单列表：运单号、状态、实付可见；不展示 下级收件人 PII

24.8 参与范围与应急

#	规则
1	默认参与：客户门户 余额支付 的业务订单（parcel 主链路）；草稿/已删除不参与
2	销售店铺单、代客下单：若 CustomerId 指向真实客户且走同一支付链路则 参与，否则首版 排除（以订单类型字段为准，编码时落枚举）
3	全局应急开关 Marketing.Emergency.Disable：停发券、停新分成 Pending（已 Pending 仍走冻结结算），管理端一键 + 审计

24.9 管理端须补充的页面说明

• 分成规则页：MonthlyCap、floor 举例（999=0）、派送成功条件
• 批量发券：子账号编号自动归主客户
• 引荐改绑：仅影响新单
• 客户编辑：手动改等级不碰积分

---

25　附录：名词对照

名词	说明
引荐人	分享链接的主客户 A
被引荐人/下级	通过 A 注册的客户 B
实付 / PayableAmount	等级折扣、券抵扣后应付金额
核销	券标记已用并绑定订单
冻结期	派送成功后至佣金入账的等待期
待派送	已支付、未达派送成功；不展示分成金额
待结算	已派送成功、冻结期内
已结算	已入 CommissionBalance
规则快照	写分成明细时固化的 BaseAmount/CommissionAmount 等，改配置不追溯
MonthlyCap	引荐人自然月分成上限，NULL=不限

---

文档结束。 评审通过后按 M1→M6 开工；页面开发须满足 §16 交互与 §24 边界规则。