Initial commit of akmon project

2026-01-20 08:04:15 +08:00
commit 77a2bab985
1309 changed files with 343305 additions and 0 deletions
--- a/doc_mall/裂变红包.md
+++ b/doc_mall/裂变红包.md
@@ -0,0 +1,236 @@
+# 商品购买裂变红包 / 返现 设计与实现
+
+本文档给出在当前项目（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 示例（含队列、事务与幂等）写出来。
+
+告诉我你希望我继续做哪一步，我会直接在仓库里添加/编辑相应文件。
+
+
+