fix(contribution-service): 优化账户查询API返回有意义的业务状态

- 新增 ContributionAccountStatus 枚举区分三种状态：
  - ACTIVE: 账户正常，有算力数据
  - INACTIVE: 用户存在但暂无认种记录
  - USER_NOT_FOUND: 账户不存在
- 移除 404 错误响应，统一返回 200 并通过 status 和 message 字段描述状态
- 为不同状态提供友好的中文提示信息

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

backend/services/contribution-service/src/api/controllers/contribution.controller.ts

@@ -1,4 +1,4 @@
-import { Controller, Get, Param, Query, NotFoundException } from '@nestjs/common';
+import { Controller, Get, Param, Query } from '@nestjs/common';
 import { ApiTags, ApiOperation, ApiResponse, ApiParam } from '@nestjs/swagger';
 import { GetContributionAccountQuery } from '../../application/queries/get-contribution-account.query';
 import { GetContributionStatsQuery } from '../../application/queries/get-contribution-stats.query';
@@ -40,13 +40,12 @@ export class ContributionController {
   @ApiOperation({ summary: '获取账户算力信息' })
   @ApiParam({ name: 'accountSequence', description: '账户序号' })
   @ApiResponse({ status: 200, type: ContributionAccountResponse })
-  @ApiResponse({ status: 404, description: '账户不存在' })
   async getAccount(@Param('accountSequence') accountSequence: string): Promise<ContributionAccountResponse> {
-    const account = await this.getAccountQuery.execute(accountSequence);
-    if (!account) {
-      throw new NotFoundException(`Account ${accountSequence} not found`);
-    }
-    return account;
+    // 始终返回 200，通过 status 字段区分账户状态：
+    // - ACTIVE: 账户正常，有算力数据
+    // - INACTIVE: 用户存在但暂无认种记录
+    // - USER_NOT_FOUND: 账户不存在
+    return this.getAccountQuery.execute(accountSequence);
   }
 
   @Get('accounts/:accountSequence/records')

backend/services/contribution-service/src/api/dto/response/contribution-account.response.ts

@@ -1,6 +1,31 @@
 import { ApiProperty } from '@nestjs/swagger';
 
+/**
+ * 账户状态枚举
+ */
+export enum ContributionAccountStatus {
+  /** 正常 - 账户存在且有算力数据（自己认种或有下级认种产生的待解锁算力） */
+  ACTIVE = 'ACTIVE',
+  /** 未激活 - 用户存在但自己和团队均未认种，暂无任何算力 */
+  INACTIVE = 'INACTIVE',
+  /** 用户不存在 - 系统中不存在该账户序号 */
+  USER_NOT_FOUND = 'USER_NOT_FOUND',
+}
+
 export class ContributionAccountResponse {
+  @ApiProperty({
+    description: '账户状态',
+    enum: ContributionAccountStatus,
+    example: ContributionAccountStatus.ACTIVE,
+  })
+  status: ContributionAccountStatus;
+
+  @ApiProperty({
+    description: '状态说明',
+    example: '账户正常',
+  })
+  message: string;
+
   @ApiProperty({ description: '账户序号' })
   accountSequence: string;
 

backend/services/contribution-service/src/application/queries/get-contribution-account.query.ts

@@ -1,9 +1,13 @@
 import { Injectable } from '@nestjs/common';
 import { ContributionAccountRepository } from '../../infrastructure/persistence/repositories/contribution-account.repository';
 import { ContributionRecordRepository } from '../../infrastructure/persistence/repositories/contribution-record.repository';
+import { SyncedDataRepository } from '../../infrastructure/persistence/repositories/synced-data.repository';
 import { ContributionAmount } from '../../domain/value-objects/contribution-amount.vo';
+import { ContributionAccountStatus } from '../../api/dto/response/contribution-account.response';
 
 export interface ContributionAccountDto {
+  status: ContributionAccountStatus;
+  message: string;
   accountSequence: string;
   personalContribution: string;
   teamLevelContribution: string;
@@ -39,18 +43,77 @@ export class GetContributionAccountQuery {
   constructor(
     private readonly accountRepository: ContributionAccountRepository,
     private readonly recordRepository: ContributionRecordRepository,
+    private readonly syncedDataRepository: SyncedDataRepository,
   ) {}
 
   /**
    * 获取账户算力信息
+   * 区分三种状态：
+   * 1. ACTIVE - 账户存在且有算力数据
+   * 2. NOT_ADOPTED - 用户存在但尚未认种，返回零算力
+   * 3. USER_NOT_FOUND - 用户不存在
    */
-  async execute(accountSequence: string): Promise<ContributionAccountDto | null> {
+  async execute(accountSequence: string): Promise<ContributionAccountDto> {
+    // 1. 先查询 contribution_accounts 表
     const account = await this.accountRepository.findByAccountSequence(accountSequence);
-    if (!account) {
-      return null;
+    if (account) {
+      return this.toDto(account);
     }
 
-    return this.toDto(account);
+    // 2. 账户不存在，检查用户是否存在（通过 synced_referrals 或 synced_users 表）
+    const referral = await this.syncedDataRepository.findSyncedReferralByAccountSequence(accountSequence);
+    const user = await this.syncedDataRepository.findSyncedUserByAccountSequence(accountSequence);
+
+    if (referral || user) {
+      // 用户存在但自己和团队均未认种，返回零算力的默认数据
+      return this.createInactiveResponse(accountSequence);
+    }
+
+    // 3. 用户完全不存在
+    return this.createUserNotFoundResponse(accountSequence);
+  }
+
+  /**
+   * 创建"未激活"状态的响应
+   * 用户存在但自己和团队均未认种，暂无任何算力
+   */
+  private createInactiveResponse(accountSequence: string): ContributionAccountDto {
+    return {
+      status: ContributionAccountStatus.INACTIVE,
+      message: '您和团队暂无认种记录，完成认种后即可获得算力。邀请好友认种可获得最高15级层级算力和3档团队加成算力。',
+      accountSequence,
+      personalContribution: '0',
+      teamLevelContribution: '0',
+      teamBonusContribution: '0',
+      totalContribution: '0',
+      hasAdopted: false,
+      directReferralAdoptedCount: 0,
+      unlockedLevelDepth: 0,
+      unlockedBonusTiers: 0,
+      isCalculated: false,
+      lastCalculatedAt: null,
+    };
+  }
+
+  /**
+   * 创建"用户不存在"状态的响应
+   */
+  private createUserNotFoundResponse(accountSequence: string): ContributionAccountDto {
+    return {
+      status: ContributionAccountStatus.USER_NOT_FOUND,
+      message: '账户不存在，请确认账户序号是否正确',
+      accountSequence,
+      personalContribution: '0',
+      teamLevelContribution: '0',
+      teamBonusContribution: '0',
+      totalContribution: '0',
+      hasAdopted: false,
+      directReferralAdoptedCount: 0,
+      unlockedLevelDepth: 0,
+      unlockedBonusTiers: 0,
+      isCalculated: false,
+      lastCalculatedAt: null,
+    };
   }
 
   /**
@@ -102,6 +165,8 @@ export class GetContributionAccountQuery {
 
   private toDto(account: any): ContributionAccountDto {
     return {
+      status: ContributionAccountStatus.ACTIVE,
+      message: '账户正常',
       accountSequence: account.accountSequence,
       personalContribution: account.personalContribution.value.toString(),
       teamLevelContribution: account.teamLevelContribution.value.toString(),