79 lines
3.3 KiB
Markdown
79 lines
3.3 KiB
Markdown
# 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*
|