akoo/akmon

Files

akoo 77a2bab985 Initial commit of akmon project

2026-01-20 08:04:15 +08:00

12 KiB

Raw Permalink Blame History

商品购买裂变红包 / 返现设计与实现

本文档给出在当前项目（Supabase/Postgres + ak_users + mall_orders 架构）中实现“商品购买裂变红包/返现”的可运行设计。包含表结构建议、触发与结算流程、后端实现（Supabase RPC/触发器或后端任务）、前端接口、幂等与回滚、测试与上线要点，以及示例 SQL/函数。

假设：项目已有用户表 ak_users(id uuid) 与订单表 mall_orders(id uuid, user_id uuid, total_amount numeric, payment_status text, order_status text, created_at timestamptz, updated_at timestamptz)。如不同请按实际表名字段映射。

1. 核心概念和需求

触发时机：订单支付并最终确认（例如 payment_status='paid' 且 order_status='completed'）。
奖励分类：
- 现金返现（cashback）：计入用户余额或可提现账户。
- 裂变红包（red_envelope）：作为可使用优惠券/红包发放给邀请人或按规则分发。
支付幂等：每个订单只会触发一次奖励（以 order_id 为幂等键）。
结算策略：两阶段（pending -> settled）：先写 pending_reward，订单稳定后结算（防止支付回滚/退款带来的误发）。
支持多级分润（level 1/2/3）与比例/固定金额配置。

1.1 典型场景：邀请返现裂变

玩法定义：老用户分享邀请链接/二维码，新用户（被邀请人）完成首单或指定商品购买后，系统按照配置向邀请人发放返现金额、红包余额或实物礼品。
奖励归类：属于裂变红包/推荐返现活动，可选择 cashback（直接入账余额）或 red_envelope（发放红包券码），也可以组合赠礼。
业务目标：通过“邀请→消费→返利”实现用户增长与复购；常搭配排行榜、任务进度等激励组件。
风控提示：需针对批量刷单、虚假邀请做风控校验，例如限制同设备、同支付账号、同地址的重复奖励。

2. 推荐的数据表（SQL）

以下为最小表集合，便于实现与审计：

-- 奖励规则（可在后台管理）
CREATE TABLE mall_referral_rules (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  name text NOT NULL,
  active boolean DEFAULT true,
  level int DEFAULT 1, -- 支持 1、2、3 等
  pct numeric, -- 百分比（例如 0.05 表示5%），与 amount 二选一
  amount numeric, -- 固定金额
  applies_to jsonb DEFAULT '{}'::jsonb, -- 可按商品/类/活动精细化
  created_at timestamptz DEFAULT now()
);

-- 待发放的奖励记录（幂等，基于 order_id）
CREATE TABLE mall_pending_rewards (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  order_id uuid NOT NULL UNIQUE,
  user_id uuid NOT NULL, -- 触发此奖励的订单用户
  total_reward numeric NOT NULL DEFAULT 0,
  payload jsonb DEFAULT '{}'::jsonb, -- 详细分配（各级金额/受益人）
  status text DEFAULT 'pending', -- pending | cancelled | settled
  created_at timestamptz DEFAULT now(),
  settled_at timestamptz NULL
);

-- 已结算奖励（审计/账务）
CREATE TABLE mall_settled_rewards (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  pending_id uuid NOT NULL REFERENCES mall_pending_rewards(id),
  user_id uuid NOT NULL, -- 实际被入账的用户（受益人）
  kind text NOT NULL, -- 'cashback' | 'red_envelope' | 'coupon'
  amount numeric NOT NULL,
  meta jsonb DEFAULT '{}'::jsonb,
  created_at timestamptz DEFAULT now()
);

-- 红包/券表（如果发红包或发券）
CREATE TABLE mall_red_envelopes (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id uuid NOT NULL, -- 收到红包的用户
  code text NULL, -- 可选券码
  amount numeric NOT NULL,
  expires_at timestamptz NULL,
  used boolean DEFAULT false,
  created_at timestamptz DEFAULT now()
);

说明：业务可根据需要把 mall_settled_rewards 作为记账凭证，并在发放现金时同时修改用户余额表（例如 ak_users_balance）或调用第三方支付/钱包服务。

3. 触发与结算流程（建议）

流程分三步：记录->延后结算->最终发放。

记录（触发）：
- 当 mall_orders 的支付状态变为 paid 且订单确认时（建议在后端或 DB trigger 触发），执行：
  - 计算规则（读取 mall_referral_rules 或活动配置），得出每个受益人应得金额；
  - 写入 mall_pending_rewards(order_id=..., user_id=order.user_id, total_reward=..., payload=...)。使用 order_id 唯一约束保证幂等。
延后结算（稳定期/反欺诈/退货窗口）：
- 为避免退款/争议导致误发，建议设置结算延迟（例如订单完成后 24-72 小时或在订单 completed 且不在退款期时）。
- 使用周期性任务（Postgres cron、Supabase scheduled function 或后端 worker），查找 mall_pending_rewards 中 status='pending' 且 created_at 超过阈值的记录，调用结算逻辑。
最终结算：
- 将 pending 转为 settled：
  - 按 payload 把相应金额写入 mall_settled_rewards（多行，记录每个受益人/类型）；
  - 如果为 cashback：同时在用户余额（例如 ak_users_balance）做入账；
  - 如果为 red_envelope：在 mall_red_envelopes 创建红包记录并发送通知；
  - 更新 mall_pending_rewards.status='settled' 并记录 settled_at。
退款/回滚场景：
- 若订单在结算前退款：在退款流程里查找 mall_pending_rewards 并把 status='cancelled'（并记录原因）。
- 若已结算但需回滚：必须走人工/自动对账流程，生成负向账务（在 mall_settled_rewards 中写入负值记录）并从用户余额或红包池中扣回（并记录审计日志）。

4. 示例：在 Postgres 中通过触发器记录 pending（示例）

下例为简单示例：在订单 payment_status 从其它值变为 paid 时插入 pending（实际项目请把 business logic 放到后端服务或严格写在 plpgsql 中并做好权限与审计）。

-- 插入幂等 pending 的 helper
CREATE OR REPLACE FUNCTION mall_insert_pending_reward_if_paid() RETURNS trigger AS $$
BEGIN
  IF (TG_OP = 'UPDATE') THEN
    IF (NEW.payment_status = 'paid' AND OLD.payment_status IS DISTINCT FROM 'paid') THEN
      -- 计算 reward 简化示例：按订单 total_amount 的 3% 给上级（假设有 inviter_id 在 ak_users）
      PERFORM 1; -- placeholder
      -- 幂等插入
      INSERT INTO mall_pending_rewards(order_id, user_id, total_reward, payload)
      VALUES (NEW.id, NEW.user_id, 0, jsonb_build_object('note','to calculate'))
      ON CONFLICT (order_id) DO NOTHING;
    END IF;
  END IF;
  RETURN NEW;
END;
$$ LANGUAGE plpgsql;

CREATE TRIGGER trg_orders_paid_pending
AFTER UPDATE ON mall_orders
FOR EACH ROW
WHEN (OLD.payment_status IS DISTINCT FROM NEW.payment_status)
EXECUTE FUNCTION mall_insert_pending_reward_if_paid();

注意：上例仅记录 pending，实际计算建议在后端 microservice 中完成（因为规则可能包含复杂逻辑、外部数据或调用）。

5. 后端实现建议（两种可选方案）

方案 A：在后端服务（Node/TS）中实现完整逻辑：
- 优点：代码易维护、测试、可复用第三方服务；适合复杂规则/风控。可在订单 webhook/异步 worker 中处理。
- 步骤：订单支付 webhook -> 计算 reward -> 写入 mall_pending_rewards -> 调度结算任务或 push 到队列。
方案 B：尽量用 Postgres（Supabase）函数与 scheduled function：
- 优点：部署简单、与 DB 紧耦合且事务一致性好。
- 步骤：trigger 插入 pending -> 定期运行 RPC（pg cron 或 Supabase scheduled）执行结算函数，函数内更新余额/插入 mall_settled_rewards。

推荐：更复杂的促销与风控建议走后端服务；轻量玩法可用方案 B。

6. 示例结算函数（伪代码/PLPGSQL）

下例演示一个简单的结算过程：

CREATE OR REPLACE FUNCTION mall_settle_pending_rewards(batch_limit int DEFAULT 100) RETURNS int AS $$
DECLARE
  rec record;
  cnt int := 0;
BEGIN
  FOR rec IN SELECT * FROM mall_pending_rewards WHERE status='pending' AND created_at < now() - interval '24 hours' LIMIT batch_limit
  LOOP
    -- 按 payload 计算并发放。此处示例将 total_reward 拆为单个 cashback 发给 user_id
    PERFORM pg_sleep(0); -- placeholder
    INSERT INTO mall_settled_rewards(pending_id, user_id, kind, amount, meta)
    VALUES (rec.id, rec.user_id, 'cashback', rec.total_reward, rec.payload);

    -- 真实系统要在事务中同时更新用户余额表 ak_users_balance
    UPDATE mall_pending_rewards SET status='settled', settled_at = now() WHERE id = rec.id;
    cnt := cnt + 1;
  END LOOP;
  RETURN cnt;
END;
$$ LANGUAGE plpgsql;

然后通过 Supabase 的 scheduled function 或 dbcron 定期调用：

SELECT mall_settle_pending_rewards(100);

7. 前端与 API 设计

下单端：不直接处理裂变；仅依赖后端/DB 的异步结算。
管理端（运营配置）：
- CRUD 接口：/api/admin/referral-rules 管理 mall_referral_rules。
- 查询待结算与已结算记录：/api/admin/pending-rewards、/api/admin/settled-rewards。
用户端：
- 查询可用红包/余额：/api/user/wallet、/api/user/red-envelopes。
- 接收推送/消息通知：当红包或返现金额发放时推送给目标用户。

接口示例（REST）：

POST /api/admin/referral-rules
GET  /api/admin/pending-rewards?status=pending
POST /api/admin/settle-pending (触发手动结算)

GET /api/user/wallet
GET /api/user/red-envelopes

8. 幂等与并发说明

在写入 mall_pending_rewards 时加上 UNIQUE(order_id)，并在插入时使用 ON CONFLICT DO NOTHING 以保证幂等。
结算任务要使用 SELECT ... FOR UPDATE SKIP LOCKED 等模式或分片（按 id 范围）来避免并发重复处理。

示例（避免重复处理）：

-- 结算任务应以行锁模式取待处理记录
WITH to_settle AS (
  SELECT id FROM mall_pending_rewards WHERE status='pending' AND created_at < now() - interval '24 hours' LIMIT 50 FOR UPDATE SKIP LOCKED
)
UPDATE mall_pending_rewards SET status='processing' FROM to_settle WHERE mall_pending_rewards.id = to_settle.id RETURNING mall_pending_rewards.*;
-- 然后在后续进程中处理这些记录并最终设为 settled

9. 测试计划

单元/集成测试：
- 用不同规则组合（百分比/固定）构造订单并验证 pending payload 与 settled 结果。
- 模拟退款：在 pending 未结算时触发退款，确认 pending 被取消。
- 模拟并发：同时多 worker 调度结算，确保 SKIP LOCKED 能防止重复发放。
手工/跑批测试：在测试库中用 cron 调用 mall_settle_pending_rewards 并核对 mall_settled_rewards 与用户余额。

10. 上线与运营注意点

风控：先小规模上线（例如仅 1% 订单或某活动订单）观察异常。记录每笔 reward 的来源、触发时机与受益人以便追溯。
审计：mall_settled_rewards 必须作为法务/财务审计凭证，不要删除。对回滚产生的负向条目也要记录。
配置：运营界面要支持对规则的开启/关闭、黑名单（不参与裂变的用户）与白名单。

如果你愿意，我可以：

根据你仓库中的真实订单/用户表把上面 SQL 改成精确的字段和外键；
帮你实现一个 Supabase scheduled function + plpgsql 结算示例并测试；
或者把完整后端 Node/TS worker 示例（含队列、事务与幂等）写出来。

告诉我你希望我继续做哪一步，我会直接在仓库里添加/编辑相应文件。

12 KiB Raw Permalink Blame History Unescape Escape

商品购买裂变红包 / 返现 设计与实现