サブスク学習プラットフォームのアーキテクチャ徹底解剖：マルチチャネル課金・冪等な決済・代理店コミッション・型安全規律

apps/
  front/   … 受講者向け Next.js 16（App Router / RSC / Mantine）
  admin/   … 運営管理ダッシュボード（サーバーアクション中心）
packages/
  subscription/   … 料金解決・NFT特典・銀行振込の状態機械（純粋関数）
  commission/     … 代理店コミッションの追記専用台帳
  auth/           … サインイン・OTP・tokenVersion
  session-manager/… JWT セッション（jose / __Host- Cookie）
  mirai-teracy-prisma/ … Prisma スキーマと Repository
  never-error/ ui / logger / mail / line-messaging / …

export const resolvePricingClassification = (
  input: PricingClassificationInput
): PricingClassification => {
  const parsed = pricingClassificationInputSchema.parse(input); // 境界で Zod 検証
  const { nftEntitlement, nftPurchasedAt, idMatches } = parsed;
  const refinedEntitlement = refineEntitlementByIdAndDate(
    nftEntitlement, nftPurchasedAt, idMatches,
  );

  // 優先順位を固定した「決定木」。上から順に最初に一致したものを返す。
  if (idMatches.inBankTransfer) {
    return { flow: "BANK_TRANSFER_SKIP", bucket: null, availablePlans: [], /* … */ };
  }
  if (idMatches.inMonthlyPayer) {
    return { flow: "UTAGE_MONTHLY_SKIP", bucket: null, availablePlans: [], /* … */ };
  }
  if (idMatches.inYearlyPayer) {
    return { flow: "STRIPE_CHECKOUT", bucket: "K01", availablePlans: ["yearly"], /* … */ };
  }
  if (idMatches.inStudentList || idMatches.inAlpha) {
    return { flow: "STRIPE_CHECKOUT", bucket: "K02", availablePlans: ["monthly", "yearly"], /* … */ };
  }
  if (idMatches.inOldProLate) {
    return { flow: "STRIPE_CHECKOUT", bucket: "K02", availablePlans: ["monthly", "yearly"], /* … */ };
  }
  if (refinedEntitlement === "NEW_LIGHT" || refinedEntitlement === "OLD_LITE") {
    return { flow: "STRIPE_CHECKOUT", bucket: "K13", availablePlans: ["monthly"], /* … */ };
  }
  return { flow: "STRIPE_CHECKOUT", bucket: "K13", availablePlans: ["monthly", "yearly"], /* … */ };
};

const isBetterCandidate = (candidate: ScoredHolding, incumbent: ScoredHolding): boolean => {
  // 1) 無料月数が長いほうを優先
  if (candidate.freeMonths !== incumbent.freeMonths) {
    return candidate.freeMonths > incumbent.freeMonths;
  }
  // 2) 同点なら購入日のランクで決定的に
  const candidateRank = purchasedAtRank(candidate.purchasedAt);
  const incumbentRank = purchasedAtRank(incumbent.purchasedAt);
  if (candidateRank !== incumbentRank) return candidateRank > incumbentRank;
  // 3) それでも同点なら enum 文字列で安定ソート（毎回同じ結果に収束）
  return candidate.rawEntitlement < incumbent.rawEntitlement;
};

export const OLD_PRO_PURCHASE_DATE_BOUNDARY = new Date("2026-02-01T00:00:00+09:00");

export const refineEntitlementByPurchaseDate = (
  entitlement: NftEntitlement | null,
  purchasedAt: Date | null,
): NftEntitlement | null => {
  if (entitlement !== "OLD_PRO") return entitlement;
  if (purchasedAt === null) return "OLD_PRO"; // 購入日不明なら refine しない
  return purchasedAt.getTime() < OLD_PRO_PURCHASE_DATE_BOUNDARY.getTime()
    ? "OLD_PRO_EARLY"
    : "OLD_PRO_LATE";
};

model StripeWebhookEvents {
  id            String    @id @default(uuid())
  stripeEventId String    @unique   // ← 同じイベントは 2 行目を作れない
  eventType     String
  processedAt   DateTime?
  rawPayload    Json
  // …
}

// apps/front/src/lib/stripe/webhook-handlers/subscription-updated.ts
if (
  existingSubscription.lastProcessedEventCreatedAt !== null &&
  event.created < existingSubscription.lastProcessedEventCreatedAt
) {
  return {
    success: true,
    message: `Skipping stale event ${event.id} (event.created=${event.created} < last=${existingSubscription.lastProcessedEventCreatedAt})`,
  };
}

const PII_KEYS: ReadonlySet<string> = new Set([
  "billing_details", "shipping", "customer_email", "customer_phone", "address",
  "email", "phone", "name", "card", "us_bank_account", "sepa_debit",
  "fingerprint", "last4", "exp_month", "exp_year", "wallet",
  "client_ip", "client_secret", "ip_address", "user_agent", /* … */
]);

const redactPii = (value: unknown): RedactedJson => {
  if (value === null || typeof value === "string" ||
      typeof value === "number" || typeof value === "boolean") {
    return value;
  }
  if (Array.isArray(value)) return value.map(redactPii);
  if (typeof value === "object") {
    const result: { [key: string]: RedactedJson } = {};
    for (const [key, val] of Object.entries(value)) {
      // PII キーは中身を見ずに丸ごと "<redacted>" へ。それ以外は再帰。
      result[key] = PII_KEYS.has(key) ? "<redacted>" : redactPii(val);
    }
    return result;
  }
  return "<null>";
};

// packages/subscription/src/bank-transfer/state-machine.ts
export const GRACE_PERIOD_DAYS = 7;
export const CANCELED_THRESHOLD_DAYS = 30;

const resolveNextStatus = (
  currentStatus: BankTransferSubscriptionStatus,
  daysSinceExpiry: number,
): BankTransferSubscriptionStatus => {
  if (currentStatus === "CANCELED") return "CANCELED";        // 終端は不可逆
  if (daysSinceExpiry < 0) {
    return currentStatus === "REACTIVATED" ? "REACTIVATED" : "ACTIVE";
  }
  if (daysSinceExpiry < GRACE_PERIOD_DAYS) return "GRACE_PERIOD";   // 0–6 日
  if (daysSinceExpiry < CANCELED_THRESHOLD_DAYS) return "SUSPENDED"; // 7–29 日
  return "CANCELED";                                                 // 30 日〜
};

const REMINDER_THRESHOLDS = [
  { stage: "T_MINUS_0",  thresholdDays: 0 },
  { stage: "T_MINUS_7",  thresholdDays: 7 },
  { stage: "T_MINUS_14", thresholdDays: 14 },
  { stage: "T_MINUS_30", thresholdDays: 30 },
] as const;

export const selectReminderToSend = (
  input: ReminderSelectionInput,
): BankTransferReminderStage | null => {
  if (input.currentStatus === "CANCELED") return null;
  if (input.currentStatus === "GRACE_PERIOD") {
    // 既に送っていれば null（冪等）
    return input.remindersSent.has("OVERDUE_GRACE") ? null : "OVERDUE_GRACE";
  }
  if (input.currentStatus === "SUSPENDED") return null;

  const currentStage = findCurrentStage(/* daysUntilExpiry */);
  if (currentStage !== null && !input.remindersSent.has(currentStage)) {
    return currentStage;
  }
  return null;
};

// packages/commission/src/usecase/ledger/idempotency.ts
export const buildLedgerIdempotencyKey = (input: {
  readonly scope: CommissionScope;        // partner:<id> / user:<id>
  readonly periodYearMonth: number;        // 例: 202606
  readonly currency: CommissionCurrency;
  readonly revision: number;
}): string => {
  if (!Number.isInteger(input.revision) || input.revision < 0) {
    throw new RangeError(`revision must be a non-negative integer; got ${input.revision}`);
  }
  const scopeSegment = scopeToSegment(input.scope);
  return `${scopeSegment}:${input.periodYearMonth}:${input.currency}:r${input.revision}`;
};

model CommissionLedgerEntry {
  // …
  payableMinor               Int    @map("payable_minor")
  carryOverFromPreviousMinor Int    @default(0) @map("carry_over_from_previous_minor")
  carryOverToNextMinor       Int    @default(0) @map("carry_over_to_next_minor")
  /// 形式: `${scopeKey}:${ym}:${currency}:r${revision}`。同月再計算は revision を増やす。
  idempotencyKey             String @unique @map("idempotency_key")
}

// packages/commission/src/rate/calcReward.ts
const BASIS_POINTS_DENOMINATOR = 10_000n;

export const calcReward = (input: CalcRewardInput): CalcRewardResult => {
  const grossBig =
    (BigInt(input.monthlySalesMinor) * BigInt(input.rateBasisPoints)) /
    BASIS_POINTS_DENOMINATOR;
  const totalBig =
    grossBig + BigInt(input.upperAgentBonusMinor) + BigInt(input.carryOverInMinor);
  const minimumBig = BigInt(input.minimumPayoutMinor);

  if (totalBig >= minimumBig) {
    // 支払う：繰り越しは 0
    return { grossRewardMinor, payableMinor: Number(totalBig), carryOverOutMinor: 0 };
  }
  // 最低額に満たない：今月は払わず、全額を翌月へ繰り越す
  return { grossRewardMinor, payableMinor: 0, carryOverOutMinor: Number(totalBig) };
};

// packages/auth/src/auth.ts
const DUMMY_PASSWORD_HASH = bcrypt.hashSync(randomUUID(), DEFAULT_SALT_ROUNDS); // 12 rounds

async signIn({ email, password }: SignInInput): Promise<boolean> {
  const normalizedEmail = normalizeEmail(email);
  const user = await this.userDataSource.findUserByEmail(normalizedEmail);
  // 未知ユーザーでも比較は必ず走らせる（早期 return で時間差を作らない）
  const passwordHash = user?.passwordHash ?? DUMMY_PASSWORD_HASH;
  const isValid = await bcrypt.compare(password, passwordHash);
  if (!user || !user.passwordHash || !isValid) return false;
  if (user.otpLockedUntil && user.otpLockedUntil.getTime() > Date.now()) return false;
  await this.sendSignInOtp({ userId: user.id, email: normalizedEmail });
  return true;
}

private async enforceTimingFloor(startedAt: number): Promise<void> {
  const remaining = this.passwordResetTimingFloorMs - (Date.now() - startedAt); // 既定 600ms
  if (remaining <= 0) return;
  await new Promise<void>((resolve) => { setTimeout(resolve, remaining); });
}

// packages/session-manager/src/session-manager.ts
const sessionPayloadSchema = z.object({
  sub: z.string(),
  emailVerified: z.boolean().optional(),
  otpVerified: z.boolean().optional(),
  sid: z.string().optional(),
  v: z.number().optional(), // ユーザー世代（強制ログアウト用途）
});

// packages/auth/src/otp/constants.ts
export const OTP_LENGTH = 6;
export const OTP_TTL_SECONDS = 60 * 5;   // 5 分
export const OTP_MAX_ATTEMPTS = 5;

// packages/auth/src/otp/otp-utils.ts
export const hashOtpCode = (code: string, secret: string): string =>
  createHmac("sha256", secret).update(code).digest("hex");

// packages/never-error/src/index.ts
export class NeverError extends Error {
  public override readonly name = "NeverError";
  constructor(value: never, message?: string) {
    super(message ?? `Unhandled discriminant value (exhaustive check failed): ${stringifySafely(value)}`);
    if (typeof Error.captureStackTrace === "function") {
      Error.captureStackTrace(this, NeverError);
    }
  }
}

function describe(flow: PricingFlow): string {
  switch (flow) {
    case "STRIPE_CHECKOUT":      return "Stripe で課金";
    case "BANK_TRANSFER_SKIP":   return "銀行振込（Stripe を通さない）";
    case "UTAGE_MONTHLY_SKIP":   return "外部移行コホート";
    default:
      // flow を増やしてここを更新し忘れると、ここで型エラーになる
      throw new NeverError(flow);
  }
}

// apps/admin/src/lib/usecases/partner-admin/suspend-partner.ts
export const suspendPartner = async (
  transaction: Prisma.TransactionClient,   // ← トランザクションは外から注入
  input: SuspendPartnerInput,
  deps: SuspendPartnerDeps,
): Promise<void> => {
  const partnerRepo = new PartnerRepository(transaction);
  const before = await partnerRepo.findById(input.partnerId);
  if (before === null) throw new Error(`Partner not found: ${input.partnerId}`);

  const after = await partnerRepo.suspend(input.partnerId);
  await recordAuditLog(transaction, {          // ← 監査ログも同じ tx で
    actorUserId: input.actorUserId,
    action: "partner_status_update",
    targetType: "partner",
    targetId: input.partnerId,
    payload: { before: before.status, after: after.status },
  });
};

// apps/admin/src/app/(authenticated)/partners/[id]/actions.ts
export const suspendPartnerAction = async (partnerId: string): Promise<void> => {
  const admin = await requireAdmin();            // ← 認可はアクション境界で
  await prismaClient.$transaction((tx) =>
    suspendPartner(tx, { partnerId, actorUserId: admin.id }, { /* deps */ }),
  );
  revalidatePath(`/partners/${partnerId}`);      // ← 再検証もアクションが所有
};

// 同一ファイルの再アップロードは no-op（ALREADY_IMPORTED）
const existingHistory = await deps.prisma.idListUploadHistories.findUnique({
  where: {
    actorUserId_checksumSha256_listType: {
      actorUserId: input.actorUserId,
      checksumSha256: input.checksumSha256,
      listType: input.listType,
    },
  },
});
if (existingHistory !== null) {
  return { ok: true, outcome: "ALREADY_IMPORTED", history: existingHistory };
}

const buildImportArtifact = async (file: File): Promise<ImportArtifact> => {
  const buffer = Buffer.from(await file.arrayBuffer());
  return {
    checksum: createHash("sha256").update(buffer).digest("hex"),
    csvText: buffer.toString("utf8"),
    safeFilename: sanitizeUploadFilename(file.name),
  };
};

export const escapeCsvField = (value: string): string => {
  if (/["\n\r,]/.test(value)) {
    return `"${value.replace(/"/g, '""')}"`;
  }
  return value;
};