bindbox-game/.planning/PROJECT.md

Bindbox Game 盈亏统计函数

What This Is

为 Bindbox Game 平台新增两个 Service 层通用盈亏统计函数，支持按用户维度和活动维度查询平台盈亏情况。函数接收资产类型、维度 ID、时间范围等参数，返回汇总数据和按资产类型拆分的明细。

Core Value

提供可复用的盈亏统计方法，使平台运营能从用户和活动两个维度快速了解各类资产的收支状况。

Requirements

Validated

• ✓ 活动盈亏分析 Dashboard 接口 — existing (DashboardActivityProfitLoss)
• ✓ 用户消费看板接口 — existing (GetUserSpendingDashboard)
• ✓ 支付订单查询 — existing (pay orders API)
• ✓ 用户积分、优惠券、道具卡、库存数据模型 — existing (GORM models)

Active

• 用户维度盈亏统计函数：输入资产类型+用户ID(支持多个)+时间范围，返回汇总+分类拆分
• 活动维度盈亏统计函数：输入资产类型+活动ID+时间范围，返回汇总+分类拆分
• 参数全部可选：不传资产类型则统计全部类型，不传ID则统计全量
• 支持5种资产类型：积分、优惠券、道具卡、实物商品、碎片
• 平台视角计算口径：收入=用户实际支付(金额+优惠券+次卡) - 成本=用户获取的资产奖品
• 支持时间范围筛选

Out of Scope

• 前端 UI / Admin API endpoint — 本次只做 Service 层方法
• 复用现有 Dashboard 盈亏逻辑 — 全新实现
• 实时计算 / 缓存 — 首版直接查询数据库

Context

• 现有代码中已有 DashboardActivityProfitLoss 等接口做活动级别盈亏，但计算口径和复用性不满足需求
• 项目使用 Go 1.24 + Gin + GORM，分层架构 (Handler → Service → Repository)
• 数据库为 MySQL 读写分离，统计查询走从库
• 资产相关数据分布在多张表：支付订单、积分流水、优惠券记录、库存记录、道具卡记录、碎片记录等

Constraints

• Tech Stack: Go, GORM, MySQL — 遵循现有项目架构
• Performance: 统计查询走从库 (DbR)，避免影响写库性能
• Compatibility: 新函数放在 internal/service/finance/ 下，不修改现有接口

Key Decisions

Decision	Rationale	Outcome
全新实现而非复用 Dashboard 逻辑	现有逻辑耦合度高，计算口径不一致	— Pending
Service 层方法	通用性优先，后续可被多处调用	— Pending
平台视角 (收入-成本)	运营核心关注平台盈亏而非用户盈亏	— Pending

Evolution

This document evolves at phase transitions and milestone boundaries.

After each phase transition (via /gsd:transition):

1. Requirements invalidated? → Move to Out of Scope with reason
2. Requirements validated? → Move to Validated with phase reference
3. New requirements emerged? → Add to Active
4. Decisions to log? → Add to Key Decisions
5. "What This Is" still accurate? → Update if drifted

After each milestone (via /gsd:complete-milestone):

1. Full review of all sections
2. Core Value check — still the right priority?
3. Audit Out of Scope — reasons still valid?
4. Update Context with current state

---

Last updated: 2026-03-21 after initialization