# 玩家管理Bug修复 - 架构设计

## 整体架构图

```mermaid
graph TB
    subgraph Frontend["前端 Vue3"]
        PM[玩家管理页面]
        PD[用户详情抽屉]
        PL[盈亏分析组件]
        AD["活动分析抽屉(已有)"]
    end
    
    subgraph Backend["后端 Go/Gin"]
        UA[users_admin.go]
        UP[users_profit_loss.go]
        AA[activities_admin.go]
    end
    
    PM --> |分页请求| UA
    PD --> |资产列表+搜索| UA
    PL --> |盈亏趋势| UP
    PL --> |盈亏明细| UP
```

---

## Bug 1: 分页修复

### 问题分析
```
player-manage/index.vue
    └── useTable hook
        ├── handleCurrentChange(newCurrent)
        │   └── getData(params)  // params中需要包含正确的page参数
        └── 问题：searchParams可能覆盖新的页码
```

### 修复方案
在 `index.vue` 中，`handleSearch` 函数调用 `getDataDebounced` 时传递了搜索参数，这可能导致分页参数被覆盖。

需要检查的代码路径:
1. `ArtTable` 组件发出 `pagination:current-change` 事件
2. `useTable` 的 `handleCurrentChange` 接收新页码
3. 确保页码正确传递给 API 请求

---

## Bug 2: 活动盈亏仪表盘

### 现有组件
- `ActivityAnalysisDrawer.vue`: 单活动数据分析
- 计算: 总营收、总成本、毛利润、参与人数

### 待确认/完善
- 检查计算逻辑是否正确
- 确保数据展示完整

---

## Bug 3: 用户盈亏明细

### 新增API

#### 后端: `GET /api/admin/users/{user_id}/stats/profit_loss_details`

**请求参数**:
```go
type profitLossDetailsRequest struct {
    Page     int    `form:"page"`
    PageSize int    `form:"page_size"`
    RangeType string `form:"rangeType"`  // today, 7d, 30d, all
}
```

**响应结构**:
```go
type profitLossDetailItem struct {
    OrderID         int64   `json:"order_id"`
    OrderNo         string  `json:"order_no"`
    CreatedAt       string  `json:"created_at"`
    ActualAmount    int64   `json:"actual_amount"`      // 实际支付金额(分)
    RefundAmount    int64   `json:"refund_amount"`      // 退款金额(分)
    NetCost         int64   `json:"net_cost"`           // 净投入(分)
    PrizeValue      int64   `json:"prize_value"`        // 获得奖品价值(分)
    PointsEarned    int64   `json:"points_earned"`      // 获得积分
    PointsValue     int64   `json:"points_value"`       // 积分价值(分)
    CouponUsedValue int64   `json:"coupon_used_value"`  // 使用优惠券价值(分)
    ItemCardUsed    string  `json:"item_card_used"`     // 使用的道具卡名称
    ItemCardValue   int64   `json:"item_card_value"`    // 道具卡价值(分)
    NetProfit       int64   `json:"net_profit"`         // 净盈亏
    ActivityName    string  `json:"activity_name"`      // 活动名称
    PrizeName       string  `json:"prize_name"`         // 奖品名称
    SourceType      int     `json:"source_type"`        // 来源类型
}

type profitLossDetailsResponse struct {
    Page     int                    `json:"page"`
    PageSize int                    `json:"page_size"`
    Total    int64                  `json:"total"`
    List     []profitLossDetailItem `json:"list"`
    Summary  struct {
        TotalCost     int64 `json:"total_cost"`
        TotalValue    int64 `json:"total_value"`
        TotalProfit   int64 `json:"total_profit"`
    } `json:"summary"`
}
```

### 前端组件修改

在 `player-profit-loss-chart.vue` 中增加:
1. "查看明细" 按钮
2. 明细表格（支持分页）
3. 显示字段：时间、订单号、支付金额、获得价值、使用优惠券/道具卡、净盈亏

---

## Bug 4: 资产搜索

### 后端修改

修改 `users_admin.go` 中的 `ListUserInventory`:
```go
type listInventoryRequest struct {
    Page      int    `form:"page"`
    PageSize  int    `form:"page_size"`
    Keyword   string `form:"keyword"`  // 新增：搜索关键词
}
```

查询逻辑增加:
```go
if req.Keyword != "" {
    query = query.Where(db.Products.Name.Like("%" + req.Keyword + "%"))
}
```

### 前端修改

在 `player-detail-drawer.vue` 资产Tab中:
1. 增加搜索输入框
2. 调用API时传递 `keyword` 参数

---

## 数据流图

```mermaid
sequenceDiagram
    participant User as 用户
    participant FE as 前端
    participant BE as 后端
    participant DB as 数据库
    
    Note over User, DB: Bug 3: 盈亏明细查询
    User->>FE: 点击"查看明细"
    FE->>BE: GET /users/:id/stats/profit_loss_details
    BE->>DB: 查询订单+奖品+优惠券+道具卡
    DB-->>BE: 返回数据
    BE-->>FE: JSON响应
    FE-->>User: 展示明细列表
```

---

## 文件变更清单

| 文件 | 变更类型 | 说明 |
|------|---------|------|
| `web/admin/src/views/player-manage/index.vue` | 修改 | 修复分页问题 |
| `web/admin/src/hooks/core/useTable.ts` | 检查 | 确认分页逻辑 |
| `web/admin/src/views/player-manage/modules/player-profit-loss-chart.vue` | 修改 | 添加明细列表 |
| `web/admin/src/views/player-manage/modules/player-detail-drawer.vue` | 修改 | 添加资产搜索 |
| `web/admin/src/api/player-manage.ts` | 修改 | 添加明细API调用 |
| `internal/api/admin/users_profit_loss.go` | 修改 | 添加明细API |
| `internal/api/admin/users_admin.go` | 修改 | 资产列表添加搜索 |