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

本文档给出在当前项目（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）

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

```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. 触发与结算流程（建议）

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

1) 记录（触发）：
   - 当 `mall_orders` 的支付状态变为 `paid` 且订单确认时（建议在后端或 DB trigger 触发），执行：
     - 计算规则（读取 `mall_referral_rules` 或活动配置），得出每个受益人应得金额；
     - 写入 `mall_pending_rewards(order_id=..., user_id=order.user_id, total_reward=..., payload=...)`。使用 `order_id` 唯一约束保证幂等。

2) 延后结算（稳定期/反欺诈/退货窗口）：
   - 为避免退款/争议导致误发，建议设置结算延迟（例如订单完成后 24-72 小时或在订单 `completed` 且不在退款期时）。
   - 使用周期性任务（Postgres cron、Supabase scheduled function 或后端 worker），查找 `mall_pending_rewards` 中 `status='pending'` 且 `created_at` 超过阈值的记录，调用结算逻辑。

3) 最终结算：
   - 将 pending 转为 settled：
     - 按 `payload` 把相应金额写入 `mall_settled_rewards`（多行，记录每个受益人/类型）；
     - 如果为 cashback：同时在用户余额（例如 `ak_users_balance`）做入账；
     - 如果为 red_envelope：在 `mall_red_envelopes` 创建红包记录并发送通知；
     - 更新 `mall_pending_rewards.status='settled'` 并记录 `settled_at`。

4) 退款/回滚场景：
   - 若订单在结算前退款：在退款流程里查找 `mall_pending_rewards` 并把 `status='cancelled'`（并记录原因）。
   - 若已结算但需回滚：必须走人工/自动对账流程，生成负向账务（在 `mall_settled_rewards` 中写入负值记录）并从用户余额或红包池中扣回（并记录审计日志）。

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

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

```sql
-- 插入幂等 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）

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

```sql
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 定期调用：

```sql
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 范围）来避免并发重复处理。

示例（避免重复处理）：

```sql
-- 结算任务应以行锁模式取待处理记录
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` 必须作为法务/财务审计凭证，不要删除。对回滚产生的负向条目也要记录。
- 配置：运营界面要支持对规则的开启/关闭、黑名单（不参与裂变的用户）与白名单。

---

如果你愿意，我可以：

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

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