bindbox-game/.trae/documents/订单记录增强与渠道分析按月统计计划.md

订单记录与渠道分析优化计划

本计划旨在解决用户提出的两个问题：

1. 订单记录优化：补充缺失的“开奖状态”和“活动信息”。
2. 渠道分析优化：将渠道分析的统计维度调整为按“月份”划分。

1. 需求分析与对齐 (Align)

• 需求 1 (订单记录):

  • 问题: 订单列表（Admin/App 端）缺乏上下文信息，无法知道订单属于哪个活动，以及是否中奖。

  • 解决方案:

    • 在订单列表中关联 ActivityDrawLogs 表，通过 OrderID 关联。

    • 如果在 ActivityDrawLogs 中找到记录，说明已开奖，可以获取 IsWinner (是否中奖) 和 RewardID (奖品信息)。

    • 通过 ActivityDrawLogs 的 IssueID -> ActivityIssues -> Activities 链条，或者直接通过商品信息反查活动，来获取活动名称。

    • 注意：ActivityDrawLogs 是通过 OrderID 关联的 (comment:抽奖票据订单ID)。

  • 实现细节: 修改 internal/service/user/orders_list.go 中的 ListOrdersWithItems，在返回结构中增加 ActivityInfo 和 DrawInfo。

• 需求 2 (渠道分析):

  • 问题: 渠道分析目前按天统计，用户希望按月统计。

  • 解决方案: 修改 GetStats 方法，将 SQL 中的 DATE_FORMAT 格式从 %Y-%m-%d 改为 %Y-%m，并调整日期范围计算逻辑（按月计算）。

  • 交互调整: 前端默认请求的时间范围应适应按月展示（如最近 6-12 个月）。也可以 手动选择时间类型 区间等

2. 架构设计 (Architect)

2.1 订单列表数据增强

• 数据模型扩展:

  • 在 internal/service/user/orders_list.go 中，扩展 OrderWithItems 结构体（或新建 OrderWithDetail），增加：

    • ActivityName: 活动名称

    • IssueNumber: 期号

    • IsDraw: 是否已开奖

    • IsWinner: 是否中奖

    • RewardLevel: 中奖等级

• 查询逻辑:

  • 查询 orders 后，收集 order_ids。

  • 批量查询 activity_draw_logs WHERE order_id IN (?)。

  • 批量查询 activity_issues (通过 logs 中的 issue_id)。

  • 批量查询 activities (通过 issues 中的 activity_id)。

  • 将这些信息组装回订单列表。

2.2 渠道分析按月统计

• 后端调整:

  • 修改 GetStats 签名或内部逻辑。考虑到用户明确说“只需要按月份”，我们可以直接修改默认行为。

  • SQL: DATE_FORMAT(created_at, '%Y-%m')

  • Range: 最近 12 个月。

3. 任务拆解 (Atomize)

3.1 渠道分析优化 (优先执行，改动小)

1. Modify Backend: 修改 internal/service/channel/channel.go 中的 GetStats 方法。

   • 调整日期格式为 %Y-%m。

   • 调整循环逻辑，生成月份列表。

   • 调整默认天数/月数为 12。

2. Modify Frontend: 修改 web/admin/src/views/operations/channels/index.vue。

   • 调整图表 X 轴显示。

   • 调整 API 调用参数（如果需要）。

3.2 订单列表增强

1. Modify Service: 修改 internal/service/user/orders_list.go。

   • 定义新的结构体字段。

   • 在 ListOrders / ListOrdersWithItems 中增加查询 ActivityDrawLogs 和相关表的逻辑。

2. Verify: 确保管理端和 APP 端调用该 Service 的地方都能正常展示新字段（可能需要同步修改 Controller 或 API 定义）。

   • 检查 internal/api/admin/users_admin.go 和 internal/api/user/orders_app.go。

4. 执行步骤 (Automate)

1. Step 1: 修改 channel.go 实现按月统计。
2. Step 2: 修改 orders_list.go 实现订单详情增强。
3. Step 3: 验证并修复可能受影响的 API 响应结构。