docs(contribution): add detailed comments for backfill task and findAccountsWithIncompleteUnlock

Explain the starvation root cause, unlock rules, pre-planting user scenario,
and future scalability considerations (cursor-based pagination).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

backend/services/contribution-service/src/application/schedulers/contribution.scheduler.ts

@@ -283,8 +283,20 @@ export class ContributionScheduler implements OnModuleInit {
   }
 
   /**
-   * 每10分钟扫描并补发未完全解锁的贡献值
+   * 每10分钟扫描并补发未完全解锁的贡献值（全量处理，无数量上限）
-   * 处理因下级先于上级认种导致的层级/奖励档位未能及时分配的情况
+   *
+   * 处理场景：
+   *   1. 下级先于上级认种：下级认种时上级层级/奖励档位不足，贡献值暂存为 LEVEL_OVERFLOW，
+   *      待上级后续达到解锁条件后由本任务补发给上级。
+   *   2. 预种用户（预先支付费用但稍后正式认种）：其直推下级在 synced_adoptions 中的
+   *      status = MINING_ENABLED 后，本任务会检测到上级解锁条件满足并补发对应算力。
+   *
+   * 解锁规则（见 ContributionCalculatorService）：
+   *   - 层级解锁：直推认种数 ≥ 1 → 5级，≥ 3 → 10级，≥ 5 → 15级（满解锁）
+   *   - 奖励档位：hasAdopted → 1档，直推 ≥ 2 → 2档，直推 ≥ 4 → 3档（满解锁）
+   *
+   * 注意：全量处理（无 LIMIT）避免账户因排序靠后而被永久跳过（starvation 问题）。
+   * Redis 锁 9 分钟，每 10 分钟触发一次，保证同一时间只有一个实例运行。
    */
   @Cron('*/10 * * * *')
   async processContributionBackfill(): Promise<void> {

backend/services/contribution-service/src/infrastructure/persistence/repositories/contribution-account.repository.ts

@@ -239,10 +239,21 @@ export class ContributionAccountRepository implements IContributionAccountReposi
    * @param limit 返回的最大数量
    * @returns 解锁状态不完整的账户列表
    */
+  /**
+   * 查找所有解锁状态不完整的账户，用于 processContributionBackfill 定时补发任务。
+   *
+   * 满足以下任一条件的账户视为"不完整"：
+   *   - unlockedLevelDepth < 15：层级算力尚未解锁到第15级（需要直推认种用户数达到5个才能满解锁）
+   *   - unlockedBonusTiers < 3：奖励档位尚未全部解锁（需要直推认种用户数达到4个才能满解锁）
+   *
+   * 注意事项：
+   *   - 不设数量上限（无 LIMIT），确保每次定时任务都能处理全量账户，避免因账户排序靠后而永久跳过。
+   *   - 原因：此前限制 100 条 + 按 updatedAt ASC 排序，导致最近更新的账户（如预种用户）因排在第
+   *     100 名之后，永远无法被处理（饥饿问题 / starvation）。
+   *   - 当账户量增长到数万级别时，可考虑改为游标分页（cursor-based pagination）逐批处理，
+   *     以控制单次 cron 任务的执行时长。当前规模（约 100-500 个账户）无性能压力。
+   */
   async findAccountsWithIncompleteUnlock(): Promise<ContributionAccountAggregate[]> {
-    // 查找已认种但未达到满解锁状态的账户：
-    // - unlockedLevelDepth < 15 或
-    // - unlockedBonusTiers < 3
     const records = await this.client.contributionAccount.findMany({
       where: {
         hasAdopted: true,