From 485798d551933dbc90b3d3681de07247b7c476ba Mon Sep 17 00:00:00 2001
From: win <win@windeMacBook-Pro.local>
Date: Sat, 21 Mar 2026 16:17:37 +0800
Subject: [PATCH] docs: initialize project

---
 .planning/PROJECT.md | 78 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 78 insertions(+)
 create mode 100644 .planning/PROJECT.md

diff --git a/.planning/PROJECT.md b/.planning/PROJECT.md
new file mode 100644
index 0000000..cd40a15
--- /dev/null
+++ b/.planning/PROJECT.md
@@ -0,0 +1,78 @@
+# 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*