bindbox-game/docs/玩家管理Bug修复/DESIGN_玩家管理Bug修复.md

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

整体架构图

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

请求参数:

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

响应结构:

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:

type listInventoryRequest struct {
    Page      int    `form:"page"`
    PageSize  int    `form:"page_size"`
    Keyword   string `form:"keyword"`  // 新增：搜索关键词
}

查询逻辑增加:

if req.Keyword != "" {
    query = query.Where(db.Products.Name.Like("%" + req.Keyword + "%"))
}

前端修改

在 player-detail-drawer.vue 资产Tab中:

1. 增加搜索输入框
2. 调用API时传递 keyword 参数

---

数据流图

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	修改	资产列表添加搜索