# 平台数据详情页数据展示逻辑

## 概述

平台数据详情页（`/analytics/platform-detail/:platform`）用于展示指定平台在指定时间范围内的详细统计数据，包括汇总统计、每日汇总数据和账号详细数据。

## 数据流程

### 1. 前端数据请求

**文件位置**: `client/src/views/Analytics/PlatformDetail/index.vue`

**请求接口**: `GET /api/work-day-statistics/platform-detail`

**请求参数**:
- `platform`: 平台类型（必填，如：douyin、xiaohongshu、baijiahao、weixin_video）
- `startDate`: 开始日期（必填，格式：YYYY-MM-DD）
- `endDate`: 结束日期（必填，格式：YYYY-MM-DD）

**请求示例**:
```typescript
const data = await request.get('/api/work-day-statistics/platform-detail', {
  params: {
    platform: 'douyin',
    startDate: '2026-01-27',
    endDate: '2026-01-27',
  },
});
```

### 2. 后端数据处理

**文件位置**: 
- 路由: `server/src/routes/workDayStatistics.ts`
- 服务: `server/src/services/WorkDayStatisticsService.ts`

**处理流程**:

1. **获取平台账号列表**
   - 根据 `userId` 和 `platform` 查询该平台下的所有账号
   - 如果没有账号，返回空数据

2. **计算每日汇总数据**
   - 遍历日期范围内的每一天
   - 对每个账号：
     - 获取该账号的所有作品ID
     - 计算该日期的增量数据：
       - **播放量增量** = 当日累计播放量 - 前一日累计播放量
       - **评论量增量** = 当日累计评论量 - 前一日累计评论量
       - **点赞量增量** = 当日累计点赞量 - 前一日累计点赞量
       - **涨粉量** = 当日粉丝数 - 前一日粉丝数
     - 将所有账号的增量数据累加到对应日期

3. **计算账号详细数据**
   - 对每个账号：
     - 计算整个时间范围内的增量数据：
       - **播放量增量** = 结束日期累计播放量 - 开始日期累计播放量
       - **评论量增量** = 结束日期累计评论量 - 开始日期累计评论量
       - **点赞量增量** = 结束日期累计点赞量 - 开始日期累计点赞量
       - **涨粉量** = 结束日期粉丝数 - 开始日期粉丝数
     - 获取更新时间（该账号在时间范围内的最新更新时间）

4. **计算汇总统计**
   - 将所有账号的增量数据累加：
     - `totalAccounts`: 账号总数
     - `viewsCount`: 总播放量增量
     - `commentsCount`: 总评论量增量
     - `likesCount`: 总点赞量增量
     - `fansIncrease`: 总涨粉量

### 3. 后端响应格式

```typescript
{
  success: true,
  data: {
    summary: {
      totalAccounts: number;        // 账号总数
      totalIncome: number;           // 总收益（目前为 0）
      viewsCount: number;            // 总播放量增量
      commentsCount: number;         // 总评论量增量
      likesCount: number;            // 总点赞量增量
      fansIncrease: number;          // 总涨粉量
      recommendationCount: number | null; // 推荐量（部分平台支持）
    };
    dailyData: Array<{
      date: string;                  // 日期（YYYY-MM-DD）
      income: number;                // 收益（目前为 0）
      recommendationCount: number | null; // 推荐量
      viewsCount: number;            // 播放量增量
      commentsCount: number;         // 评论量增量
      likesCount: number;            // 点赞量增量
      fansIncrease: number;          // 涨粉量
    }>;
    accounts: Array<{
      id: number;                    // 账号ID
      nickname: string;               // 账号昵称
      username: string;              // 账号用户名
      avatarUrl: string | null;      // 头像URL
      platform: string;              // 平台类型
      income: number | null;         // 收益（目前为 null）
      recommendationCount: number | null; // 推荐量
      viewsCount: number | null;     // 播放量增量（可能为 null）
      commentsCount: number;         // 评论量增量
      likesCount: number;            // 点赞量增量
      fansIncrease: number;          // 涨粉量
      updateTime: string;            // 更新时间（MM-DD HH:mm）
    }>;
  }
}
```

### 4. 前端数据展示

**文件位置**: `client/src/views/Analytics/PlatformDetail/index.vue`

**数据解包**:
- `request` 拦截器会自动解包响应，将 `{ success: true, data: {...} }` 转换为 `{...}`
- 前端直接使用解包后的数据

**数据赋值**:
```typescript
// 更新汇总数据
if (data.summary) {
  summaryData.value = {
    totalAccounts: data.summary.totalAccounts ?? 0,
    viewsCount: data.summary.viewsCount ?? 0,
    commentsCount: data.summary.commentsCount ?? 0,
    likesCount: data.summary.likesCount ?? 0,
    fansIncrease: data.summary.fansIncrease ?? 0,
  };
}

// 更新每日数据
dailyData.value = Array.isArray(data.dailyData) ? data.dailyData : [];

// 更新账号列表
accountList.value = Array.isArray(data.accounts) ? data.accounts : [];
```

**展示区域**:

1. **汇总统计卡片**（第 57-93 行）
   - 账号总数
   - 播放(阅读)量
   - 评论量
   - 点赞量
   - 涨粉量

2. **每日汇总数据表格**（第 95-113 行）
   - 时间列：显示日期
   - 播放(阅读)量列：显示每日增量
   - 评论量列：显示每日增量
   - 点赞量列：显示每日增量
   - 涨粉量列：显示每日增量

3. **账号详细数据表格**（第 115-163 行）
   - 账号列：显示头像和昵称
   - 平台列：显示平台名称
   - 播放(阅读)量列：显示账号增量（如果为 null 显示"获取失败"）
   - 评论量列：显示账号增量
   - 点赞量列：显示账号增量
   - 涨粉量列：显示账号增量
   - 更新时间列：显示最后更新时间
   - 操作列：提供"详情"按钮跳转到账号详情页

## 数据计算逻辑

### 播放量/评论量/点赞量计算

**数据来源**: `work_day_statistics` 表

**计算方式**:
1. 对于每个作品，获取指定日期的最新累计数据
2. 计算增量 = 当日累计值 - 前一日累计值
3. 将所有作品的增量累加

**SQL 逻辑**:
```sql
-- 获取指定日期的最新累计数据
SELECT
  COALESCE(SUM(wds.play_count), 0) AS views,
  COALESCE(SUM(wds.like_count), 0) AS likes,
  COALESCE(SUM(wds.comment_count), 0) AS comments
FROM work_day_statistics wds
INNER JOIN (
  SELECT wds2.work_id, MAX(wds2.record_date) AS record_date
  FROM work_day_statistics wds2
  WHERE wds2.work_id IN (...)
    AND wds2.record_date <= ?
  GROUP BY wds2.work_id
) latest
ON latest.work_id = wds.work_id AND latest.record_date = wds.record_date
```

### 粉丝数计算

**数据来源**: `user_day_statistics` 表

**计算方式**:
1. 获取指定日期的粉丝数记录
2. 如果没有记录，获取 <= 指定日期的最近一条记录
3. 计算增量 = 当日粉丝数 - 前一日粉丝数

**查询逻辑**:
```typescript
// 获取当日粉丝数
const dayUserStat = await userDayStatisticsRepository
  .createQueryBuilder('uds')
  .where('uds.account_id = :accountId', { accountId })
  .andWhere('DATE(uds.record_date) = :d', { d: dateStr })
  .getOne();

// 如果没有记录，获取最近一条
const recentUserStat = await userDayStatisticsRepository
  .createQueryBuilder('uds')
  .where('uds.account_id = :accountId', { accountId })
  .andWhere('DATE(uds.record_date) <= :d', { d: dateStr })
  .orderBy('uds.record_date', 'DESC')
  .getOne();
```

## 常见问题

### 1. 为什么数据不显示？

**可能原因**:
1. **平台参数缺失**: 检查路由参数或查询参数中是否有 `platform`
2. **日期参数错误**: 检查 `startDate` 和 `endDate` 格式是否正确
3. **账号不存在**: 该平台下没有账号数据
4. **数据为空**: 该时间范围内没有统计数据

**调试方法**:
- 打开浏览器控制台，查看日志输出
- 检查网络请求，查看接口返回的数据
- 确认后端日志，查看数据查询结果

### 2. 为什么播放量显示为 null？

**原因**: 
- 该账号在指定时间范围内没有作品数据
- 或者作品数据获取失败

**处理**: 
- 前端会显示"获取失败"文本
- 检查该账号是否有作品，以及作品统计数据是否正常

### 3. 为什么增量数据为 0？

**可能原因**:
1. **时间范围问题**: 如果开始日期和结束日期相同，且该日期没有数据，增量可能为 0
2. **数据未更新**: 该时间范围内的数据还没有统计
3. **确实没有增量**: 该时间范围内确实没有新增数据

**检查方法**:
- 查看每日汇总数据，确认是否有数据
- 检查账号的更新时间，确认数据是否已同步

### 4. 数据更新频率

**数据来源**:
- 作品统计数据：通过定时任务或手动触发更新
- 账号粉丝数据：通过定时任务或手动触发更新

**更新时间**:
- 账号列表中的 `updateTime` 字段显示该账号在时间范围内的最新更新时间

## 修复记录

### 2026-01-28

**问题**: 数据不显示

**原因**: 
- 前端数据赋值逻辑使用了 `||` 运算符，导致 0 值被误判为 falsy
- 当 `data.summary` 存在但某些字段为 0 时，会使用默认值而不是实际值

**修复**:
- 改用 `??` 运算符（空值合并运算符）
- 添加类型检查和数组检查
- 改进日志输出，便于调试

**修改文件**:
- `client/src/views/Analytics/PlatformDetail/index.vue` (第 324-340 行)