# 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*