紹介コードで友達を招く仕組みを、重いバックエンドなしで設計する

// utils/referralCode.ts
// 紛らわしい文字を除いた 28 文字。8 桁で約 4.7 兆通り
const ALPHABET = "ABCDEFGHJKMNPQRSTUVWXYZ23456789";
 
export function generateReferralCode(length = 8): string {
  let code = "";
  const bytes = new Uint8Array(length);
  // Expo では expo-crypto の getRandomValues を使う
  crypto.getRandomValues(bytes);
  for (let i = 0; i < length; i++) {
    code += ALPHABET[bytes[i] % ALPHABET.length];
  }
  return code;
}

// convex/referrals.ts
import { mutation } from "./_generated/server";
import { v } from "convex/values";
 
export const ensureMyCode = mutation({
  args: { ownerId: v.string(), candidate: v.string() },
  handler: async (ctx, { ownerId, candidate }) => {
    // すでに自分のコードがあれば再利用（再発行で番号が変わらないようにする）
    const existing = await ctx.db
      .query("referralCodes")
      .withIndex("by_owner", (q) => q.eq("ownerId", ownerId))
      .unique();
    if (existing) return existing.code;
 
    // 候補コードが衝突していないか確認
    const clash = await ctx.db
      .query("referralCodes")
      .withIndex("by_code", (q) => q.eq("code", candidate))
      .unique();
    if (clash) {
      throw new Error("CODE_TAKEN"); // クライアント側で別候補を作って再試行
    }
 
    await ctx.db.insert("referralCodes", {
      ownerId,
      code: candidate,
      createdAt: Date.now(),
    });
    return candidate;
  },
});

<!-- 紹介リンクの着地ページ（例: https://example.com/i/ABCD2345 ) -->
<script>
  const code = location.pathname.split("/").pop();
  // クリップボードへ（ユーザー操作起点が必要なブラウザもあるためボタンも用意）
  navigator.clipboard?.writeText("ref:" + code).catch(() => {});
  // ストアへ誘導
  const ua = navigator.userAgent;
  const store = /android/i.test(ua)
    ? "https://play.google.com/store/apps/details?id=YOUR_PACKAGE"
    : "https://apps.apple.com/app/idYOUR_APP_ID";
  document.getElementById("go").href = store;
</script>

// hooks/useDeferredReferral.ts
import * as Clipboard from "expo-clipboard";
import AsyncStorage from "@react-native-async-storage/async-storage";
 
const FLAG = "referral.checkedClipboard";
const PENDING = "referral.pendingCode";
 
export async function captureDeferredReferralOnce(): Promise<string | null> {
  // 初回起動の1回だけ実行する（再起動で何度も読まない）
  if (await AsyncStorage.getItem(FLAG)) return null;
  await AsyncStorage.setItem(FLAG, "1");
 
  try {
    const text = await Clipboard.getStringAsync();
    if (text?.startsWith("ref:")) {
      const code = text.slice(4).trim();
      if (/^[A-Z0-9]{6,12}$/.test(code)) {
        await AsyncStorage.setItem(PENDING, code);
        return code;
      }
    }
  } catch {
    // 失敗しても致命ではない（紹介が付かないだけ）
  }
  return null;
}

import * as Linking from "expo-linking";
 
// アプリ起動時のリンクから ?ref= を拾う（インストール済み経由）
const url = await Linking.getInitialURL();
if (url) {
  const { queryParams } = Linking.parse(url);
  if (typeof queryParams?.ref === "string") {
    await AsyncStorage.setItem(PENDING, queryParams.ref);
  }
}

// convex/referrals.ts
export const claimReferral = mutation({
  args: { code: v.string(), inviteeId: v.string(), deviceId: v.string() },
  handler: async (ctx, { code, inviteeId, deviceId }) => {
    const owner = await ctx.db
      .query("referralCodes")
      .withIndex("by_code", (q) => q.eq("code", code))
      .unique();
    if (!owner) return { ok: false, reason: "INVALID_CODE" };
 
    // 自己紹介を禁止
    if (owner.ownerId === inviteeId) return { ok: false, reason: "SELF" };
 
    // 同一招待者は一度だけ
    const already = await ctx.db
      .query("referrals")
      .withIndex("by_invitee", (q) => q.eq("inviteeId", inviteeId))
      .unique();
    if (already) return { ok: false, reason: "ALREADY_CLAIMED" };
 
    // 端末重複の簡易チェック（同じ端末で何度も招待される荒らし対策）
    const sameDevice = await ctx.db
      .query("referrals")
      .withIndex("by_device", (q) => q.eq("deviceId", deviceId))
      .collect();
    if (sameDevice.length >= 1) return { ok: false, reason: "DEVICE_LIMIT" };
 
    await ctx.db.insert("referrals", {
      referrerId: owner.ownerId,
      inviteeId,
      deviceId,
      code,
      status: "pending", // 報酬はまだ確定していない
      claimedAt: Date.now(),
    });
    return { ok: true };
  },
});

// convex/referrals.ts
export const fulfillReferral = mutation({
  args: { inviteeId: v.string() },
  handler: async (ctx, { inviteeId }) => {
    const ref = await ctx.db
      .query("referrals")
      .withIndex("by_invitee", (q) => q.eq("inviteeId", inviteeId))
      .unique();
    if (!ref) return { ok: false, reason: "NO_REFERRAL" };
 
    // すでに確定済みなら何もしない（冪等性の要）
    if (ref.status === "fulfilled") return { ok: true, idempotent: true };
 
    // 条件判定はサーバー側で行う（クライアントの自己申告を信じない）
    const milestone = await ctx.db
      .query("milestones")
      .withIndex("by_user", (q) => q.eq("userId", inviteeId))
      .unique();
    if (!milestone || milestone.savedCount < 3) {
      return { ok: false, reason: "CONDITION_NOT_MET" };
    }
 
    // 状態を fulfilled に進めてから両者へ付与（順序が大事）
    await ctx.db.patch(ref._id, { status: "fulfilled", fulfilledAt: Date.now() });
    await grantReward(ctx, ref.referrerId, "referrer");
    await grantReward(ctx, inviteeId, "invitee");
    return { ok: true };
  },
});