Passport Tier 팬덤 단위 · 활동 Badge · 진화 Emblem · Eclipse 참여 기록

app/firebase/functions/src/fandom/fandom.ts

@@ -609,13 +609,39 @@ async function closeExpiredEclipses(
         defended, qualifiedParticipants: qualified,
         endedAt: occurredAt, ...(defended ? {} : { appliedAt: occurredAt }),
       });
-      return true;
+      return defended ? 'success' : true;
     });
     if (changed) closed++;
+    if (changed === 'success') await recordEclipseSuccess(fandomRef.id, doc.ref);
   }
   return closed;
 }
 
+/**
+ * Eclipse 성공 참여 PASSPORT 기록 — UX·FX 정렬기준 v1.5 **§5.2** 「인정 횟수(60회) 이상 + 최종 성공 시 회차당
+ * 1회 성공 참여 기록」. 신규 Badge type 을 만들지 않고 PASSPORT 기록으로 남긴다(§5.2 「Badge 확장은 별도 검토」).
+ * 문서 ID 가 회차라 재실행에도 한 번이다.
+ */
+export async function recordEclipseSuccess(
+  fandomId: string, roundRef: FirebaseFirestore.DocumentReference,
+): Promise<number> {
+  const db = getFirestore();
+  const qualified = await roundRef.collection('participants').where('qualified', '==', true).get();
+  for (const p of qualified.docs) {
+    try {
+      await db.doc(`users/${p.id}/passportHistory/eclipse_${fandomId}_${roundRef.id}`).create({
+        kind: 'eclipse_success', fandomId, eclipseId: roundRef.id,
+        validShakes: p.get('validShakes') ?? null,
+        occurredAt: FieldValue.serverTimestamp(),
+      });
+    } catch (error) {
+      const code = (error as { code?: number | string }).code;
+      if (code !== 6 && code !== 'already-exists') throw error;
+    }
+  }
+  return qualified.size;
+}
+
 /**
  * `fn-fpi-aggregate` — FPI 집계(§4) · **1 분 주기**(별첨 B 「FPI 집계」 확정).
  *