# 用户详情页面实现计划

## 1. 页面概述

创建独立的用户详情页面 `/users/[id]`，展示用户的完整信息。

## 2. 页面结构

```
/users/[id]/page.tsx
├── 用户基本信息卡片
│   ├── 头像、昵称、账户序号
│   ├── 手机号（脱敏）
│   ├── KYC 状态
│   ├── 注册时间、最后活跃时间
│   └── 用户状态（正常/冻结）
│
├── 推荐关系树（倒树形结构）
│   ├── 当前用户为根节点
│   ├── 向上显示推荐人链路（ancestor_path）
│   ├── 向下显示直推用户列表
│   ├── 点击任意节点可切换查看该节点的关系树
│   └── 显示每个节点的基本信息（序号、昵称、认种量）
│
├── 认种信息 Tab
│   ├── 认种汇总
│   │   ├── 个人认种总量
│   │   ├── 团队认种总量
│   │   ├── 首次认种时间
│   │   └── 最近认种时间
│   └── 认种分类账明细（表格）
│       ├── 订单号
│       ├── 认种数量
│       ├── 金额
│       ├── 状态
│       ├── 省市选择
│       └── 时间
│
├── 钱包信息 Tab
│   ├── 钱包汇总
│   │   ├── USDT 余额（可用/冻结）
│   │   ├── DST 余额
│   │   ├── 算力余额
│   │   ├── 待领取收益
│   │   ├── 可结算收益
│   │   └── 已结算收益
│   └── 钱包分类账明细（表格）
│       ├── 流水ID
│       ├── 类型（充值/提现/收益/扣款等）
│       ├── 资产类型
│       ├── 金额
│       ├── 余额快照
│       ├── 关联订单
│       └── 时间
│
└── 授权信息 Tab
    ├── 授权汇总
    │   ├── 授权角色列表（社区合伙人/省公司/市公司等）
    │   ├── 授权状态
    │   ├── 授权区域
    │   └── 权益激活状态
    └── 授权分类账明细（表格）
        ├── 月度考核记录
        │   ├── 考核月份
        │   ├── 月度目标/完成
        │   ├── 累计目标/完成
        │   ├── 考核结果
        │   └── 区域排名
        └── 系统账户流水（如果是省/市公司）
            ├── 流水ID
            ├── 账户类型
            ├── 流水类型
            ├── 金额
            ├── 余额
            └── 时间
```

## 3. 需要创建的文件

### 3.1 前端文件

```
frontend/admin-web/src/
├── app/(dashboard)/users/[id]/
│   ├── page.tsx                    # 用户详情页面
│   └── user-detail.module.scss     # 页面样式
│
├── components/features/users/
│   ├── ReferralTree/
│   │   ├── ReferralTree.tsx        # 推荐关系树组件
│   │   ├── ReferralTree.module.scss
│   │   └── index.ts
│   ├── PlantingTab/
│   │   ├── PlantingTab.tsx         # 认种信息 Tab
│   │   ├── PlantingTab.module.scss
│   │   └── index.ts
│   ├── WalletTab/
│   │   ├── WalletTab.tsx           # 钱包信息 Tab
│   │   ├── WalletTab.module.scss
│   │   └── index.ts
│   └── AuthorizationTab/
│       ├── AuthorizationTab.tsx    # 授权信息 Tab
│       ├── AuthorizationTab.module.scss
│       └── index.ts
│
├── services/
│   └── userDetailService.ts        # 用户详情相关 API
│
├── hooks/
│   └── useUserDetail.ts            # 用户详情相关 hooks（扩展）
│
└── types/
    └── userDetail.types.ts         # 用户详情相关类型
```

### 3.2 后端文件（admin-service）

```
backend/services/admin-service/src/
├── application/
│   ├── queries/
│   │   ├── get-user-full-detail.query.ts
│   │   ├── get-user-referral-tree.query.ts
│   │   ├── get-user-planting-ledger.query.ts
│   │   ├── get-user-wallet-ledger.query.ts
│   │   └── get-user-authorization-detail.query.ts
│   └── handlers/
│       └── (对应的 handler 文件)
│
├── interfaces/http/controllers/
│   └── user-detail.controller.ts   # 用户详情 API 控制器
│
└── infrastructure/persistence/repositories/
    └── user-detail-query.repository.impl.ts
```

## 4. API 端点设计

### 4.1 获取用户完整信息
```
GET /v1/admin/users/:accountSequence/full-detail
Response: {
  basicInfo: { ... },
  referralInfo: {
    myReferralCode: string,
    usedReferralCode: string,
    referrerId: string,
    referrerSequence: string,
    ancestorPath: string,
    depth: number,
    directReferralCount: number,
    activeDirectCount: number
  }
}
```

### 4.2 获取推荐关系树
```
GET /v1/admin/users/:accountSequence/referral-tree
Query: { direction: 'up' | 'down', depth?: number }
Response: {
  currentUser: { accountSequence, nickname, personalAdoptions },
  ancestors: [...],  // 向上的推荐人链
  directReferrals: [...] // 直推用户列表
}
```

### 4.3 获取认种分类账
```
GET /v1/admin/users/:accountSequence/planting-ledger
Query: { page, pageSize, startDate?, endDate? }
Response: {
  summary: {
    totalOrders: number,
    totalTreeCount: number,
    totalAmount: string,
    firstPlantingAt: string,
    lastPlantingAt: string
  },
  items: [...],
  total: number,
  page: number,
  pageSize: number
}
```

### 4.4 获取钱包分类账
```
GET /v1/admin/users/:accountSequence/wallet-ledger
Query: { page, pageSize, assetType?, entryType?, startDate?, endDate? }
Response: {
  summary: {
    usdtAvailable: string,
    usdtFrozen: string,
    dstAvailable: string,
    hashpower: string,
    pendingUsdt: string,
    settleableUsdt: string,
    settledTotalUsdt: string
  },
  items: [...],
  total: number,
  page: number,
  pageSize: number
}
```

### 4.5 获取授权信息
```
GET /v1/admin/users/:accountSequence/authorization-detail
Response: {
  roles: [{
    id: string,
    roleType: string,
    regionCode: string,
    regionName: string,
    displayTitle: string,
    status: string,
    benefitActive: boolean,
    authorizedAt: string
  }],
  assessments: [{
    assessmentMonth: string,
    monthlyTarget: number,
    monthlyCompleted: number,
    cumulativeTarget: number,
    cumulativeCompleted: number,
    result: string,
    rankingInRegion: number
  }],
  systemAccountLedger: [...] // 如果是省/市公司
}
```

## 5. 数据来源（CDC 同步表）

| 数据 | 来源表 | admin-service 视图表 |
|------|--------|---------------------|
| 用户基本信息 | identity.user_accounts | user_query_view |
| 推荐关系 | referral.referral_relationships | referral_query_view |
| 认种订单 | planting.planting_orders | planting_order_query_view |
| 认种资金分配 | planting.fund_allocations | fund_allocation_view |
| 钱包余额 | wallet.wallet_accounts | wallet_account_query_view |
| 钱包流水 | wallet.wallet_ledger_entries | wallet_ledger_entry_view |
| 授权角色 | authorization.authorization_roles | authorization_role_query_view |
| 月度考核 | authorization.monthly_assessments | monthly_assessment_query_view |
| 系统账户流水 | authorization.system_account_ledgers | system_account_ledger_view |

## 6. 推荐关系树组件设计

### 6.1 数据结构
```typescript
interface ReferralNode {
  accountSequence: string;
  nickname: string | null;
  avatar: string | null;
  personalAdoptions: number;
  depth: number;
  isCurrentUser: boolean;
  children?: ReferralNode[];
}
```

### 6.2 交互设计
- 初始显示当前用户及其直接推荐人（向上1级）和直推用户（向下1级）
- 点击任意节点，该节点变为中心，重新加载其上下级关系
- 使用树形布局，父节点在上，子节点在下
- 节点显示：头像 + 序号 + 昵称 + 认种量
- 当前查看的用户节点高亮显示

### 6.3 实现方案
- 使用 CSS Flexbox/Grid 实现树形布局
- 或使用 react-d3-tree 库
- 或使用 @ant-design/charts 的组织架构图

## 7. Tab 切换设计

```typescript
type TabType = 'planting' | 'wallet' | 'authorization';

const tabs = [
  { key: 'planting', label: '认种信息' },
  { key: 'wallet', label: '钱包信息' },
  { key: 'authorization', label: '授权信息' },
];
```

## 8. 实现顺序

1. **Phase 1: 基础结构**
   - 创建页面路由和基本布局
   - 实现用户基本信息卡片
   - 更新用户列表页面的"查看详情"链接

2. **Phase 2: 后端 API**
   - 实现 user-detail.controller.ts
   - 添加查询推荐关系的 repository 方法
   - 添加查询分类账的 repository 方法

3. **Phase 3: 推荐关系树**
   - 实现 ReferralTree 组件
   - 实现节点点击切换功能

4. **Phase 4: 认种信息**
   - 实现 PlantingTab 组件
   - 显示汇总和明细表格

5. **Phase 5: 钱包信息**
   - 实现 WalletTab 组件
   - 显示汇总和明细表格

6. **Phase 6: 授权信息**
   - 实现 AuthorizationTab 组件
   - 显示角色列表、考核记录

## 9. 样式规范

- 使用现有的设计系统颜色变量
- 卡片间距: 24px
- 表格使用现有的 Table 组件样式
- Tab 使用自定义样式，与现有风格保持一致
- 树形结构使用清晰的连接线

## 10. 注意事项

1. **性能优化**
   - 分类账明细使用分页加载
   - 推荐关系树按需加载（点击时才加载子节点）
   - 使用 React Query 缓存数据

2. **错误处理**
   - 用户不存在时显示友好提示
   - 网络错误时显示重试按钮
   - 数据为空时显示空状态提示

3. **权限控制**
   - 确保只有登录的管理员可以访问
   - 敏感信息（如完整手机号）不显示

4. **响应式设计**
   - 表格在小屏幕上可横向滚动
   - 推荐关系树在小屏幕上可缩放
