f

deploy/sql/利润统计面板改造说明.md

@@ -0,0 +1,149 @@
+# 利润统计面板改造说明
+
+## 改造内容
+
+将利润统计从原来的卡片布局改为右侧栏面板，并展示详细的成本和收入明细。
+
+## 修改文件
+
+### 1. 后端API定义
+
+**文件：** `ycc-proxy-server/app/main/api/desc/admin/dashboard.api`
+
+**修改内容：**
+- 在 `AdminProfitStatistics` 中添加了三个明细字段：
+  - `TodayDetail AdminProfitDetail` - 今日明细
+  - `MonthDetail AdminProfitDetail` - 当月明细
+  - `TotalDetail AdminProfitDetail` - 总计明细
+- 新增 `AdminProfitDetail` 类型，包含：
+  - `Revenue` - 营收
+  - `Commission` - 佣金
+  - `Rebate` - 返利
+  - `CompanyTax` - 税务成本
+  - `ApiCost` - API调用成本
+  - `TaxIncome` - 提现收税
+  - `Profit` - 利润
+  - `ProfitRate` - 利润率
+
+### 2. 后端逻辑
+
+**文件：** `ycc-proxy-server/app/main/api/internal/logic/admin_dashboard/admingetdashboardstatisticslogic.go`
+
+**修改内容：**
+- 在 `calculateProfitStatistics` 方法中，为今日、当月、总计三个时间范围都填充了明细数据
+- 明细数据包含所有成本和收入的详细金额
+
+### 3. 前端类型定义
+
+**文件：** `ycc-proxy-admin/apps/web-antd/src/api/dashboard/dashboard.ts`
+
+**修改内容：**
+- 添加了 `ProfitDetail` 接口
+- 更新了 `ProfitStatistics` 接口，添加三个明细字段
+
+### 4. 前端主页面
+
+**文件：** `ycc-proxy-admin/apps/web-antd/src/views/dashboard/analytics/index.vue`
+
+**修改内容：**
+- 移除了利润统计卡片（从4列布局改为3列布局）
+- 改为左右布局：左侧是统计卡片和图表，右侧是利润统计面板
+- 添加了响应式布局，小屏幕下右侧面板会移到下方
+
+### 5. 前端利润面板组件（新建）
+
+**文件：** `ycc-proxy-admin/apps/web-antd/src/views/dashboard/analytics/analytics-profit-panel.vue`
+
+**功能：**
+- 展示利润总额和利润率
+- 通过Tab切换今日/当月/总计
+- 详细展示收入明细（营收、提现收税）
+- 详细展示成本明细（代理佣金、代理返利、税务成本、API调用成本）
+- 分别计算收入合计和成本合计
+
+## 布局说明
+
+### 桌面端（>1200px）
+```
+┌─────────────────────────────────┬──────────────┐
+│                                 │              │
+│  统计卡片（3列）                │  利润统计    │
+│                                 │  面板        │
+│  趋势图表                       │  （固定）    │
+│                                 │              │
+└─────────────────────────────────┴──────────────┘
+```
+
+### 移动端（≤1200px）
+```
+┌─────────────────────────────────┐
+│  统计卡片（3列）                │
+│                                 │
+│  趋势图表                       │
+│                                 │
+│  利润统计面板                   │
+│  （移到下方）                   │
+└─────────────────────────────────┘
+```
+
+## 明细数据说明
+
+### 收入项
+1. **营收**：订单金额总和（status = 'paid'）
+2. **提现收税**：代理提现税总和（tax_status = 2）
+
+### 成本项
+1. **代理佣金**：代理佣金总和（status != 3）
+2. **代理返利**：代理返利总和（status != 3）
+3. **税务成本**：订单金额的 6%
+4. **API调用成本**：天元API成功调用的成本总和
+
+### 利润计算
+```
+利润 = 营收 + 提现收税 - 代理佣金 - 代理返利 - 税务成本 - API调用成本
+利润率 = (利润 / 营收) × 100%
+```
+
+## 使用步骤
+
+### 1. 生成API类型（后端）
+
+运行API生成脚本：
+```bash
+cd ycc-proxy-server
+# 运行gen_api脚本生成types
+```
+
+### 2. 编译验证
+
+```bash
+# 后端编译
+cd ycc-proxy-server
+go build
+
+# 前端编译
+cd ycc-proxy-admin
+npm run build
+```
+
+### 3. 测试验证
+
+1. 打开后台统计面板
+2. 查看右侧利润统计面板
+3. 切换今日/当月/总计Tab
+4. 验证各项成本和收入明细是否正确显示
+5. 验证收入合计和成本合计计算是否正确
+
+## 注意事项
+
+1. **必须运行gen_api脚本**：修改了API定义后，需要运行gen_api脚本生成新的types.go文件
+2. **数据准确性**：确保API调用成本数据已正确记录在 `tianyuanapi_call_log` 表中
+3. **响应式布局**：在小屏幕设备上，右侧面板会自动移到下方，确保良好的用户体验
+
+## UI特性
+
+- **固定定位**：右侧面板在桌面端使用sticky定位，滚动时保持可见
+- **颜色区分**：收入用绿色（+），成本用红色（-），利润根据正负显示不同颜色
+- **Tab切换**：可以快速切换查看不同时间范围的明细
+- **合计显示**：分别显示收入合计和成本合计，方便查看
+