# Requirements: Bindbox Game 盈亏统计函数

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

## v1 Requirements

Requirements for initial release. Each maps to roadmap phases.

### Core P&L Functions

- [ ] **PNL-01**: 函数接收 ProfitLossParams 参数结构体，所有字段可选（资产类型、维度ID、时间范围）
- [ ] **PNL-02**: Revenue 计算口径为 actual_amount + discount_amount，排除已退款/取消订单（status=3,4）
- [ ] **PNL-03**: Game-pass 订单通过 finance.IsGamePassOrder 三条件检测（source_type=4、order_no LIKE 'GP%'、remark含use_game_pass），与现金收入严格互斥
- [ ] **PNL-04**: Game-pass 订单收入通过 finance.ComputeGamePassValue 计算（draw_count × activity_price）
- [ ] **PNL-05**: Prize cost 通过 finance.ComputePrizeCostWithMultiplier 计算，包含道具卡倍率
- [ ] **PNL-06**: Profit 通过 finance.ComputeProfit 计算，返回 int64 分 + float64 利润率
- [ ] **PNL-07**: 排除已作废库存（remark LIKE '%void%' 或 status=2）不计入成本
- [ ] **PNL-08**: 兼容 order_id=0 或 NULL 的历史数据（不受订单状态过滤影响）

### Query Dimensions

- [ ] **DIM-01**: QueryUserProfitLoss 接收 []int64 用户ID，空切片=统计全部用户
- [ ] **DIM-02**: QueryActivityProfitLoss 接收 []int64 活动ID，空切片=统计全部活动
- [ ] **DIM-03**: 时间范围过滤使用 *time.Time（nil=不限），不使用零值作哨兵
- [ ] **DIM-04**: AssetType 可选过滤，nil/All(0)=统计全部资产类型

### Return Structure

- [ ] **RET-01**: ProfitLossResult 包含汇总数据：总收入、总成本、净盈亏、利润率
- [ ] **RET-02**: ProfitLossResult 包含 []ProfitLossBreakdown 按资产类型拆分明细
- [ ] **RET-03**: 所有金额以 int64 分为单位，不使用 float64 存储金额

### Asset Types

- [ ] **AST-01**: 定义 AssetType 枚举：Points(1)、Coupon(2)、ItemCard(3)、Product(4)、Fragment(5)、All(0)
- [ ] **AST-02**: 每种资产类型对应不同的数据源表和 JOIN 路径
- [ ] **AST-03**: Fragment 成本从 fragment_synthesis_logs 表获取

### Code Quality

- [ ] **QUA-01**: 新函数放在 internal/service/finance/ 包下
- [ ] **QUA-02**: Service 构造器仅注入 DbR（读库），包内不出现 GetDbW() 调用
- [ ] **QUA-03**: 每个 Scan() 调用必须检查 .Error 并返回错误，不静默吞掉
- [ ] **QUA-04**: 复用现有 finance.* 工具函数（ClassifyOrderSpending、IsGamePassOrder 等），不重复实现
- [ ] **QUA-05**: 使用 fan-out + in-memory merge 查询模式（多次独立 Scan，Go 层合并）

## v2 Requirements

Deferred to future release.

### Performance & Caching

- **PERF-01**: Redis TTL 缓存包装（查询延迟超过 2s 时启用）
- **PERF-02**: 增量/时间桶聚合 + 物化统计表

### Integration

- **INT-01**: 抖音/直播间订单纳入用户维度盈亏统计
- **INT-02**: 新增对应 Admin API endpoint 供前端调用

## Out of Scope

| Feature | Reason |
|---------|--------|
| 复用现有 Dashboard 盈亏逻辑 | 现有逻辑耦合 HTTP 上下文，计算口径不一致 |
| Service 层内置缓存 | 缓存属于调用层责任，不应在 Service 函数内实现 |
| 分页 | 聚合函数返回完整结果集，分页由 API 层处理 |
| 返回格式化金额字符串 | 格式化属于展示层，Service 返回 int64 分 |
| 物化表预计算 | 需要 schema 变更和写权限，v1 直接查询 |
| 实时推送盈亏变化 | 需要事件基础设施，超出 v1 范围 |

## Traceability

| Requirement | Phase | Status |
|-------------|-------|--------|
| PNL-01 | Phase 1 | Pending |
| PNL-02 | Phase 1 | Pending |
| PNL-03 | Phase 1 | Pending |
| PNL-04 | Phase 1 | Pending |
| PNL-05 | Phase 1 | Pending |
| PNL-06 | Phase 1 | Pending |
| PNL-07 | Phase 1 | Pending |
| PNL-08 | Phase 1 | Pending |
| DIM-01 | Phase 1 | Pending |
| DIM-02 | Phase 1 | Pending |
| DIM-03 | Phase 1 | Pending |
| DIM-04 | Phase 1 | Pending |
| RET-01 | Phase 1 | Pending |
| RET-02 | Phase 2 | Pending |
| RET-03 | Phase 1 | Pending |
| AST-01 | Phase 1 | Pending |
| AST-02 | Phase 2 | Pending |
| AST-03 | Phase 2 | Pending |
| QUA-01 | Phase 1 | Pending |
| QUA-02 | Phase 1 | Pending |
| QUA-03 | Phase 1 | Pending |
| QUA-04 | Phase 1 | Pending |
| QUA-05 | Phase 1 | Pending |

**Coverage:**
- v1 requirements: 23 total
- Mapped to phases: 23
- Unmapped: 0 ✓

---
*Requirements defined: 2026-03-21*
*Last updated: 2026-03-21 after roadmap creation*