# Mining Admin Service (挖矿管理服务) 开发指导

## 1. 服务概述

### 1.1 核心职责
Mining Admin Service 是挖矿系统的管理中枢，负责配置管理、系统监控、数据报表等后台管理功能。

**主要功能：**
- 系统参数配置（贡献值递增比例、分配比例等）
- 系统开关控制（转账开关等）
- 系统账户管理（运营/省/市/总部账户）
- 全局状态监控与报表
- 用户算力/积分股查询
- 历史数据初始化（老用户算力计算）
- 操作日志与审计

### 1.2 技术栈
- **框架**: NestJS + TypeScript
- **数据库**: PostgreSQL (CRUD为主)
- **ORM**: Prisma
- **消息队列**: Kafka (接收其他服务事件)
- **缓存**: Redis

### 1.3 端口分配
- HTTP: 3023
- 数据库: rwa_mining_admin

---

## 2. 架构设计

### 2.1 目录结构

```
mining-admin-service/
├── src/
│   ├── api/
│   │   ├── controllers/
│   │   │   ├── config.controller.ts               # 配置管理API
│   │   │   ├── system-account.controller.ts       # 系统账户API
│   │   │   ├── user-query.controller.ts           # 用户查询API
│   │   │   ├── dashboard.controller.ts            # 仪表盘API
│   │   │   ├── report.controller.ts               # 报表API
│   │   │   ├── initialization.controller.ts       # 初始化API
│   │   │   ├── audit-log.controller.ts            # 审计日志API
│   │   │   └── health.controller.ts
│   │   └── dto/
│   │       ├── request/
│   │       │   ├── update-config.request.ts
│   │       │   ├── query-user.request.ts
│   │       │   └── initialize-users.request.ts
│   │       └── response/
│   │           ├── config.response.ts
│   │           ├── dashboard.response.ts
│   │           ├── user-detail.response.ts
│   │           └── report.response.ts
│   │
│   ├── application/
│   │   ├── commands/
│   │   │   ├── update-contribution-config.command.ts
│   │   │   ├── update-distribution-config.command.ts
│   │   │   ├── toggle-transfer.command.ts
│   │   │   ├── initialize-legacy-users.command.ts
│   │   │   ├── create-system-account.command.ts
│   │   │   └── manual-adjustment.command.ts
│   │   ├── queries/
│   │   │   ├── get-dashboard-stats.query.ts
│   │   │   ├── get-user-contribution-detail.query.ts
│   │   │   ├── get-user-mining-detail.query.ts
│   │   │   ├── get-global-state.query.ts
│   │   │   ├── get-system-accounts.query.ts
│   │   │   ├── get-audit-logs.query.ts
│   │   │   └── generate-report.query.ts
│   │   ├── services/
│   │   │   ├── config-management.service.ts
│   │   │   ├── initialization.service.ts
│   │   │   ├── report-generator.service.ts
│   │   │   └── audit.service.ts
│   │   └── event-handlers/
│   │       ├── contribution-calculated.handler.ts
│   │       ├── shares-distributed.handler.ts
│   │       ├── trade-completed.handler.ts
│   │       └── price-updated.handler.ts
│   │
│   ├── domain/
│   │   ├── aggregates/
│   │   │   ├── system-config.aggregate.ts
│   │   │   ├── system-account.aggregate.ts
│   │   │   └── audit-log.aggregate.ts
│   │   ├── repositories/
│   │   │   ├── system-config.repository.interface.ts
│   │   │   ├── system-account.repository.interface.ts
│   │   │   ├── audit-log.repository.interface.ts
│   │   │   └── synced-data.repository.interface.ts
│   │   ├── value-objects/
│   │   │   ├── config-key.vo.ts
│   │   │   └── audit-action.vo.ts
│   │   └── events/
│   │       ├── config-updated.event.ts
│   │       └── initialization-completed.event.ts
│   │
│   ├── infrastructure/
│   │   ├── persistence/
│   │   │   ├── prisma/
│   │   │   │   └── prisma.service.ts
│   │   │   ├── repositories/
│   │   │   │   ├── system-config.repository.impl.ts
│   │   │   │   ├── system-account.repository.impl.ts
│   │   │   │   ├── audit-log.repository.impl.ts
│   │   │   │   └── synced-data.repository.impl.ts
│   │   │   └── unit-of-work/
│   │   │       └── unit-of-work.service.ts
│   │   ├── kafka/
│   │   │   ├── contribution-event-consumer.service.ts
│   │   │   ├── mining-event-consumer.service.ts
│   │   │   ├── trading-event-consumer.service.ts
│   │   │   ├── event-publisher.service.ts
│   │   │   └── kafka.module.ts
│   │   ├── redis/
│   │   │   ├── config-cache.service.ts
│   │   │   └── stats-cache.service.ts
│   │   ├── external/
│   │   │   ├── contribution-client.service.ts
│   │   │   ├── mining-client.service.ts
│   │   │   └── trading-client.service.ts
│   │   └── infrastructure.module.ts
│   │
│   ├── shared/
│   │   ├── guards/
│   │   │   └── admin-auth.guard.ts
│   │   └── decorators/
│   │       └── audit-log.decorator.ts
│   ├── config/
│   ├── app.module.ts
│   └── main.ts
│
├── prisma/
│   ├── schema.prisma
│   └── migrations/
├── package.json
├── tsconfig.json
├── Dockerfile
└── docker-compose.yml
```

---

## 3. 数据库设计

### 3.1 数据库类型
Mining Admin Service 以**查询和配置管理**为主，使用 PostgreSQL 作为主数据库，大部分表为 CRUD 操作。

### 3.2 核心表结构

```sql
-- ============================================
-- 系统配置表
-- ============================================

-- 通用配置表（Key-Value）
CREATE TABLE system_configs (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),

    config_key VARCHAR(100) NOT NULL UNIQUE,
    config_value TEXT NOT NULL,
    config_type VARCHAR(20) NOT NULL,              -- STRING / NUMBER / BOOLEAN / JSON
    description VARCHAR(200),

    is_active BOOLEAN DEFAULT TRUE,
    version INT DEFAULT 1,

    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_by VARCHAR(50)                         -- 操作人
);

-- 初始化配置数据
INSERT INTO system_configs (config_key, config_value, config_type, description) VALUES
('contribution.base_value', '22617', 'NUMBER', '基础贡献值'),
('contribution.increment_percentage', '0.003', 'NUMBER', '递增百分比 0.3%'),
('contribution.unit_size', '100', 'NUMBER', '单位大小(100棵)'),
('contribution.start_tree_number', '1000', 'NUMBER', '起始树编号'),
('distribution.personal_rate', '0.70', 'NUMBER', '个人分配比例 70%'),
('distribution.operation_rate', '0.12', 'NUMBER', '运营账户比例 12%'),
('distribution.province_rate', '0.01', 'NUMBER', '省公司比例 1%'),
('distribution.city_rate', '0.02', 'NUMBER', '市公司比例 2%'),
('distribution.team_rate', '0.15', 'NUMBER', '团队比例 15%'),
('distribution.level_rate_per', '0.005', 'NUMBER', '每级比例 0.5%'),
('distribution.bonus_rate_per', '0.025', 'NUMBER', '每档奖励比例 2.5%'),
('mining.transfer_enabled', 'false', 'BOOLEAN', '转账功能开关'),
('trading.buy_fee_rate', '0.10', 'NUMBER', '买入手续费率 10%'),
('trading.sell_fee_rate', '0.10', 'NUMBER', '卖出手续费率 10%');

-- 贡献值递增配置表（历史记录）
CREATE TABLE contribution_increment_configs (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),

    base_contribution DECIMAL(20,10) NOT NULL,
    increment_percentage DECIMAL(10,6) NOT NULL,
    unit_size INT NOT NULL,
    start_tree_number INT NOT NULL,

    effective_from DATE NOT NULL,
    effective_to DATE,
    is_active BOOLEAN DEFAULT TRUE,

    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    created_by VARCHAR(50)
);

-- 分配比例配置表（历史记录）
CREATE TABLE distribution_rate_configs (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),

    rate_type VARCHAR(30) NOT NULL,                -- PERSONAL/OPERATION/PROVINCE/CITY/TEAM_LEVEL/TEAM_BONUS
    rate_value DECIMAL(10,6) NOT NULL,
    level_depth INT,                               -- TEAM_LEVEL时使用
    bonus_tier INT,                                -- TEAM_BONUS时使用

    effective_from DATE NOT NULL,
    effective_to DATE,
    is_active BOOLEAN DEFAULT TRUE,

    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    created_by VARCHAR(50)
);

-- ============================================
-- 系统账户表
-- ============================================

CREATE TABLE system_accounts (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),

    account_type VARCHAR(20) NOT NULL,             -- OPERATION / PROVINCE / CITY / HEADQUARTERS
    account_name VARCHAR(100) NOT NULL,
    account_code VARCHAR(50) UNIQUE,               -- 账户编码

    -- 关联信息（省/市公司时使用）
    region_code VARCHAR(20),
    region_name VARCHAR(100),

    -- 余额（从其他服务同步）
    contribution_balance DECIMAL(30,10) DEFAULT 0,
    share_balance DECIMAL(30,10) DEFAULT 0,
    green_points_balance DECIMAL(30,10) DEFAULT 0,

    -- 特殊标记
    contribution_never_expires BOOLEAN DEFAULT FALSE,

    is_active BOOLEAN DEFAULT TRUE,

    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- 初始化数据
INSERT INTO system_accounts (account_type, account_name, account_code, contribution_never_expires) VALUES
('OPERATION', '运营账户', 'SYS_OPERATION', TRUE),
('HEADQUARTERS', '总部账户', 'SYS_HEADQUARTERS', TRUE),
('PROVINCE', '省公司账户', 'SYS_PROVINCE', FALSE),
('CITY', '市公司账户', 'SYS_CITY', FALSE);

-- ============================================
-- 仪表盘统计快照表
-- ============================================

CREATE TABLE dashboard_snapshots (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    snapshot_time TIMESTAMP WITH TIME ZONE NOT NULL,

    -- 全局状态
    total_users INT DEFAULT 0,
    total_adopted_users INT DEFAULT 0,
    total_trees INT DEFAULT 0,

    -- 算力统计
    total_contribution DECIMAL(30,10) DEFAULT 0,
    effective_contribution DECIMAL(30,10) DEFAULT 0,

    -- 积分股统计
    total_supply DECIMAL(30,10),
    black_hole_amount DECIMAL(30,10),
    circulation_pool DECIMAL(30,10),
    current_price DECIMAL(30,18),

    -- 交易统计
    total_trade_volume DECIMAL(30,10) DEFAULT 0,
    today_trade_volume DECIMAL(30,10) DEFAULT 0,
    total_trade_count INT DEFAULT 0,
    today_trade_count INT DEFAULT 0,

    -- 分配统计
    total_distributed DECIMAL(30,10) DEFAULT 0,
    today_distributed DECIMAL(30,10) DEFAULT 0,

    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
CREATE INDEX idx_dashboard_snapshots_time ON dashboard_snapshots(snapshot_time);

-- ============================================
-- 同步数据表（从其他服务汇总）
-- ============================================

-- 用户汇总视图表（定期同步）
CREATE TABLE synced_user_summaries (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    account_sequence VARCHAR(20) NOT NULL UNIQUE,

    -- 基本信息
    phone VARCHAR(20),
    status VARCHAR(20),

    -- 认种信息
    total_trees INT DEFAULT 0,
    first_adoption_date DATE,
    last_adoption_date DATE,

    -- 推荐信息
    referrer_account_sequence VARCHAR(20),
    direct_referral_count INT DEFAULT 0,
    direct_referral_adopted_count INT DEFAULT 0,
    total_team_size INT DEFAULT 0,

    -- 算力信息
    personal_contribution DECIMAL(30,10) DEFAULT 0,
    team_level_contribution DECIMAL(30,10) DEFAULT 0,
    team_bonus_contribution DECIMAL(30,10) DEFAULT 0,
    total_contribution DECIMAL(30,10) DEFAULT 0,
    effective_contribution DECIMAL(30,10) DEFAULT 0,

    -- 积分股信息
    share_balance DECIMAL(30,10) DEFAULT 0,
    total_mined DECIMAL(30,10) DEFAULT 0,
    total_sold DECIMAL(30,10) DEFAULT 0,
    total_bought DECIMAL(30,10) DEFAULT 0,

    -- 同步状态
    last_synced_at TIMESTAMP WITH TIME ZONE,

    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
CREATE INDEX idx_synced_user_summaries_phone ON synced_user_summaries(phone);

-- ============================================
-- 审计日志表
-- ============================================

CREATE TABLE audit_logs (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),

    -- 操作信息
    action_type VARCHAR(50) NOT NULL,              -- CONFIG_UPDATE / ACCOUNT_CREATE / MANUAL_ADJUST / INIT_USERS / TOGGLE_SWITCH
    action_target VARCHAR(100),                    -- 操作目标（如配置key、账户ID等）
    action_detail JSONB,                           -- 操作详情

    -- 操作前后值
    before_value JSONB,
    after_value JSONB,

    -- 操作人
    operator_id VARCHAR(50) NOT NULL,
    operator_name VARCHAR(100),
    operator_ip VARCHAR(50),

    -- 操作结果
    result VARCHAR(20) NOT NULL,                   -- SUCCESS / FAILED
    error_message TEXT,

    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
CREATE INDEX idx_audit_logs_action ON audit_logs(action_type);
CREATE INDEX idx_audit_logs_time ON audit_logs(created_at);
CREATE INDEX idx_audit_logs_operator ON audit_logs(operator_id);

-- ============================================
-- 初始化任务表
-- ============================================

CREATE TABLE initialization_tasks (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),

    task_type VARCHAR(50) NOT NULL,                -- LEGACY_USER_CONTRIBUTION / GLOBAL_STATE / SYSTEM_ACCOUNTS
    task_status VARCHAR(20) NOT NULL,              -- PENDING / RUNNING / COMPLETED / FAILED

    -- 进度
    total_count INT DEFAULT 0,
    processed_count INT DEFAULT 0,
    failed_count INT DEFAULT 0,

    -- 参数
    task_params JSONB,

    -- 结果
    result_summary JSONB,
    error_message TEXT,

    started_at TIMESTAMP WITH TIME ZONE,
    completed_at TIMESTAMP WITH TIME ZONE,

    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    created_by VARCHAR(50)
);

-- ============================================
-- 已处理事件（幂等性）
-- ============================================

CREATE TABLE processed_events (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    event_id VARCHAR(100) NOT NULL UNIQUE,
    event_type VARCHAR(50) NOT NULL,
    source_service VARCHAR(50),
    processed_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
```

---

## 4. 核心业务逻辑

### 4.1 老用户算力初始化

```typescript
/**
 * 初始化老用户算力
 * 这是系统上线时的一次性任务
 */
async initializeLegacyUserContributions(): Promise<InitializationResult> {
  // 创建初始化任务
  const task = await this.initTaskRepo.create({
    taskType: 'LEGACY_USER_CONTRIBUTION',
    taskStatus: 'RUNNING',
    startedAt: new Date(),
  });

  try {
    // 1. 获取所有已认种用户
    const adoptedUsers = await this.userRepo.findAllAdoptedUsers();

    await this.initTaskRepo.updateProgress(task.id, {
      totalCount: adoptedUsers.length,
    });

    let processedCount = 0;
    let failedCount = 0;

    // 2. 批量处理用户
    for (const user of adoptedUsers) {
      try {
        // 调用 contribution-service 计算算力
        await this.contributionClient.calculateUserContribution(user.accountSequence);
        processedCount++;
      } catch (error) {
        this.logger.error(`Failed to initialize user ${user.accountSequence}`, error);
        failedCount++;
      }

      // 更新进度
      if ((processedCount + failedCount) % 100 === 0) {
        await this.initTaskRepo.updateProgress(task.id, {
          processedCount,
          failedCount,
        });
      }
    }

    // 3. 完成任务
    await this.initTaskRepo.complete(task.id, {
      processedCount,
      failedCount,
      resultSummary: {
        totalUsers: adoptedUsers.length,
        successCount: processedCount,
        failedCount,
      },
    });

    // 4. 记录审计日志
    await this.auditService.log({
      actionType: 'INIT_USERS',
      actionDetail: { taskId: task.id },
      afterValue: { processedCount, failedCount },
      result: 'SUCCESS',
    });

    return { taskId: task.id, processedCount, failedCount };

  } catch (error) {
    await this.initTaskRepo.fail(task.id, error.message);
    throw error;
  }
}
```

### 4.2 配置管理

```typescript
/**
 * 更新系统配置
 * 所有配置更新都需要记录审计日志
 */
@AuditLog('CONFIG_UPDATE')
async updateConfig(key: string, value: string, operatorId: string): Promise<void> {
  const existing = await this.configRepo.findByKey(key);

  if (!existing) {
    throw new ConfigNotFoundException(key);
  }

  const beforeValue = existing.configValue;

  // 验证值格式
  this.validateConfigValue(key, value, existing.configType);

  // 更新配置
  await this.configRepo.update(key, {
    configValue: value,
    updatedBy: operatorId,
    version: existing.version + 1,
  });

  // 清除缓存
  await this.configCache.invalidate(key);

  // 发布配置更新事件
  await this.eventPublisher.publish('mining-admin.config-updated', {
    eventId: uuid(),
    configKey: key,
    beforeValue,
    afterValue: value,
    updatedBy: operatorId,
    updatedAt: new Date().toISOString(),
  });
}

/**
 * 切换转账开关
 */
@AuditLog('TOGGLE_SWITCH')
async toggleTransfer(enabled: boolean, operatorId: string): Promise<void> {
  const key = 'mining.transfer_enabled';

  await this.updateConfig(key, String(enabled), operatorId);

  // 通知 mining-service
  await this.miningClient.updateTransferSwitch(enabled);
}
```

### 4.3 仪表盘统计

```typescript
/**
 * 获取仪表盘统计数据
 */
async getDashboardStats(): Promise<DashboardStatsDto> {
  // 优先从缓存获取
  const cached = await this.statsCache.get('dashboard');
  if (cached) {
    return cached;
  }

  // 聚合各服务数据
  const [
    globalState,
    contributionStats,
    tradingStats,
    userStats,
  ] = await Promise.all([
    this.miningClient.getGlobalState(),
    this.contributionClient.getNetworkStats(),
    this.tradingClient.getTodayStats(),
    this.getUserStats(),
  ]);

  const stats: DashboardStatsDto = {
    // 全局状态
    currentPrice: globalState.currentPrice,
    blackHoleAmount: globalState.blackHoleAmount,
    circulationPool: globalState.circulationPool,
    minuteBurnRate: globalState.minuteBurnRate,

    // 算力统计
    networkTotalContribution: contributionStats.totalContribution,
    networkEffectiveContribution: contributionStats.effectiveContribution,

    // 用户统计
    totalUsers: userStats.totalUsers,
    adoptedUsers: userStats.adoptedUsers,
    totalTrees: userStats.totalTrees,

    // 交易统计
    todayTradeVolume: tradingStats.volume,
    todayTradeCount: tradingStats.count,

    // 分配统计
    totalDistributed: globalState.totalDistributed,
    distributionPhase: globalState.distributionPhase,
    dailyDistribution: globalState.dailyDistribution,

    updatedAt: new Date().toISOString(),
  };

  // 缓存 30 秒
  await this.statsCache.set('dashboard', stats, 30);

  // 保存快照
  await this.dashboardSnapshotRepo.create(stats);

  return stats;
}
```

### 4.4 用户详情查询

```typescript
/**
 * 查询用户算力和挖矿详情
 */
async getUserDetail(accountSequence: string): Promise<UserDetailDto> {
  const [
    contribution,
    shareAccount,
    miningRecords,
    tradeOrders,
    referralInfo,
  ] = await Promise.all([
    this.contributionClient.getUserContribution(accountSequence),
    this.miningClient.getUserShareAccount(accountSequence),
    this.miningClient.getUserMiningRecords(accountSequence, { limit: 30 }),
    this.tradingClient.getUserOrders(accountSequence, { limit: 30 }),
    this.getUserReferralInfo(accountSequence),
  ]);

  return {
    accountSequence,

    // 算力信息
    contribution: {
      personal: contribution.personalContribution,
      teamLevel: contribution.teamLevelContribution,
      teamBonus: contribution.teamBonusContribution,
      total: contribution.totalContribution,
      effective: contribution.effectiveContribution,
      hasAdopted: contribution.hasAdopted,
      directReferralAdoptedCount: contribution.directReferralAdoptedCount,
      unlockedLevelDepth: contribution.unlockedLevelDepth,
      unlockedBonusTiers: contribution.unlockedBonusTiers,
    },

    // 积分股信息
    shares: {
      available: shareAccount.availableBalance,
      frozen: shareAccount.frozenBalance,
      totalMined: shareAccount.totalMined,
      totalSold: shareAccount.totalSold,
      totalBought: shareAccount.totalBought,
      perSecondEarning: shareAccount.perSecondEarning,
    },

    // 推荐信息
    referral: referralInfo,

    // 最近挖矿记录
    recentMiningRecords: miningRecords,

    // 最近交易记录
    recentTradeOrders: tradeOrders,
  };
}
```

---

## 5. 服务间通信

### 5.1 订阅的事件

| Topic | 来源服务 | 数据内容 | 处理方式 |
|-------|---------|---------|---------|
| `contribution.contribution-calculated` | contribution-service | 用户算力计算完成 | 更新本地用户汇总 |
| `mining.shares-distributed` | mining-service | 积分股分配完成 | 更新分配统计 |
| `mining.price-updated` | mining-service | 价格更新 | 更新仪表盘 |
| `trading.trade-completed` | trading-service | 交易完成 | 更新交易统计 |

### 5.2 发布的事件

| Topic | 事件类型 | 订阅者 |
|-------|---------|-------|
| `mining-admin.config-updated` | ConfigUpdated | contribution/mining/trading |

### 5.3 调用其他服务

```typescript
// 调用 contribution-service
this.contributionClient.getUserContribution(accountSequence);
this.contributionClient.calculateUserContribution(accountSequence);
this.contributionClient.getNetworkStats();

// 调用 mining-service
this.miningClient.getGlobalState();
this.miningClient.getUserShareAccount(accountSequence);
this.miningClient.getUserMiningRecords(accountSequence);
this.miningClient.updateTransferSwitch(enabled);

// 调用 trading-service
this.tradingClient.getUserOrders(accountSequence);
this.tradingClient.getTodayStats();
this.tradingClient.getKlineData(period);
```

---

## 6. API 设计

### 6.1 配置管理 API

```
GET    /api/admin/configs                    # 获取所有配置
GET    /api/admin/configs/:key               # 获取单个配置
PUT    /api/admin/configs/:key               # 更新配置
POST   /api/admin/configs/toggle-transfer    # 切换转账开关
```

### 6.2 系统账户 API

```
GET    /api/admin/system-accounts            # 获取所有系统账户
GET    /api/admin/system-accounts/:id        # 获取单个账户详情
POST   /api/admin/system-accounts            # 创建系统账户
PUT    /api/admin/system-accounts/:id        # 更新系统账户
```

### 6.3 用户查询 API

```
GET    /api/admin/users                      # 用户列表（分页）
GET    /api/admin/users/:accountSequence     # 用户详情
GET    /api/admin/users/:accountSequence/contribution-records  # 算力明细
GET    /api/admin/users/:accountSequence/mining-records        # 挖矿明细
GET    /api/admin/users/:accountSequence/trade-orders          # 交易记录
```

### 6.4 仪表盘 API

```
GET    /api/admin/dashboard                  # 仪表盘统计
GET    /api/admin/dashboard/realtime         # 实时数据（WebSocket推送）
GET    /api/admin/dashboard/charts           # 图表数据
```

### 6.5 报表 API

```
GET    /api/admin/reports/daily              # 日报表
GET    /api/admin/reports/contribution       # 算力报表
GET    /api/admin/reports/mining             # 挖矿报表
GET    /api/admin/reports/trading            # 交易报表
POST   /api/admin/reports/export             # 导出报表
```

### 6.6 初始化 API

```
POST   /api/admin/initialization/legacy-users   # 初始化老用户算力
POST   /api/admin/initialization/global-state   # 初始化全局状态
GET    /api/admin/initialization/tasks          # 获取初始化任务列表
GET    /api/admin/initialization/tasks/:id      # 获取任务详情
```

### 6.7 审计日志 API

```
GET    /api/admin/audit-logs                 # 审计日志列表
GET    /api/admin/audit-logs/:id             # 审计日志详情
```

---

## 7. 审计日志装饰器

```typescript
/**
 * 审计日志装饰器
 * 自动记录操作前后的值变化
 */
export function AuditLog(actionType: string) {
  return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
    const originalMethod = descriptor.value;

    descriptor.value = async function (...args: any[]) {
      const auditService = this.auditService;
      const operatorId = this.getCurrentOperatorId();

      // 记录操作前状态（如果需要）
      let beforeValue = null;
      if (actionType === 'CONFIG_UPDATE') {
        beforeValue = await this.getBeforeValue(args);
      }

      try {
        const result = await originalMethod.apply(this, args);

        // 记录成功日志
        await auditService.log({
          actionType,
          actionTarget: this.getActionTarget(args),
          actionDetail: this.getActionDetail(args),
          beforeValue,
          afterValue: this.getAfterValue(args, result),
          operatorId,
          result: 'SUCCESS',
        });

        return result;
      } catch (error) {
        // 记录失败日志
        await auditService.log({
          actionType,
          actionTarget: this.getActionTarget(args),
          actionDetail: this.getActionDetail(args),
          beforeValue,
          operatorId,
          result: 'FAILED',
          errorMessage: error.message,
        });

        throw error;
      }
    };

    return descriptor;
  };
}
```

---

## 8. 关键注意事项

### 8.1 权限控制
- 所有 API 需要管理员认证
- 敏感操作需要二次确认
- 配置修改需要记录操作人

### 8.2 数据一致性
- 本地汇总数据定期与源服务同步
- 仪表盘数据缓存有 TTL
- 重要操作使用事务

### 8.3 审计要求
- 所有配置变更记录审计日志
- 记录操作前后值
- 保留操作人信息和 IP

### 8.4 性能优化
- 使用 Redis 缓存频繁查询的数据
- 仪表盘统计定期快照
- 用户列表查询分页

---

## 9. 开发检查清单

- [ ] 实现配置管理 API
- [ ] 实现系统账户管理
- [ ] 实现用户查询 API
- [ ] 实现仪表盘统计
- [ ] 实现老用户初始化功能
- [ ] 实现审计日志记录
- [ ] 配置与其他服务的 HTTP 客户端
- [ ] 配置 Kafka Consumer
- [ ] 实现管理员认证
- [ ] 编写测试

---

## 10. 启动命令

```bash
# 开发环境
npm run start:dev

# 生成 Prisma Client
npx prisma generate

# 运行迁移
npx prisma migrate dev

# 生产环境
npm run build && npm run start:prod
```