1343 Bot Id Fix 3907817a

# Bot ID 显示不完整问题修复方案

## 问题描述

在云端查询 Bot 数据时，Bot ID 显示不完整，只显示了 5 位数字（如 43836, 48076），而正常的 Bot ID 应该是 10 位数字（如 1769588427, 1769586345）。

## 根本原因

### 1. 数据库 Schema 问题

**位置**: `functions/lib/db/schema.ts:40`

```typescript
// ❌ 错误：使用 integer 类型
botId: integer("bot_id"),
```

**问题**:
- PostgreSQL `integer` 类型范围：-2,147,483,648 到 2,147,483,647
- Bot ID（如 1769588427）超出了此范围的一半
- 导致存储时数据被截断或转换错误

### 2. SQL 查询未做类型转换

**位置**: 多个知识库 SQL 文档

```sql
-- ❌ 错误：直接返回 bot_id
SELECT bot_id, ...
FROM my_shell_prod.art_task
```

**问题**:
- MySQL 的 `art_task` 表中 `bot_id` 可能是 BIGINT 类型
- 直接返回时，JavaScript Number 类型可能截断大整数
- 需要在 SQL 层转换为字符串

## 解决方案

### 方案 1: 修复数据库 Schema（推荐）

**修改 schema.ts**:

```typescript
// ✅ 正确：使用 text 类型存储 bot_id
botId: text("bot_id"),
```

**创建 migration**:

```sql
-- Migration: 将 bot_id 从 integer 改为 text
ALTER TABLE daaf_bot_revenue_snapshots
ALTER COLUMN bot_id TYPE TEXT;

ALTER TABLE daaf_daily_summary_snapshots
ALTER COLUMN bot_id TYPE TEXT;

ALTER TABLE daaf_cost_daily_snapshots
ALTER COLUMN bot_id TYPE TEXT;
```

**更新插入逻辑**:

确保所有插入数据的代码将 `bot_id` 作为字符串处理：

```typescript
// ✅ 正确
botId: String(row.bot_id),  // 显式转换为字符串

// ❌ 错误
botId: row.bot_id,  // 可能是 number，会被截断
```

### 方案 2: SQL 查询时转换（临时方案）

如果暂时无法修改 schema，在所有 SQL 查询中添加类型转换：

**MySQL 查询**:

```sql
-- ✅ 正确：使用 CAST 转换为字符串
SELECT
  CAST(bot_id AS CHAR) as bot_id,  -- 将 bot_id 转换为字符串
  slug_id,
  MAX(bot_name) as bot_name,
  SUM(actual_energy_cost) / 100 as bot_cost
FROM my_shell_prod.art_task
WHERE status IN ('done', 'cancel')
GROUP BY bot_id, slug_id
ORDER BY bot_cost DESC;
```

**PostgreSQL 查询**:

```sql
-- ✅ 正确：使用 CAST 转换为字符串
SELECT
  CAST(bot_id AS TEXT) as bot_id,  -- 将 bot_id 转换为字符串
  bot_name,
  ...
FROM daaf_bot_revenue_snapshots
WHERE snapshot_date >= CURRENT_DATE - INTERVAL '7 days'
GROUP BY bot_id, bot_name;
```

## 已修复的文件

### 知识库 SQL 文档

以下文件的 SQL 查询已添加 `CAST(bot_id AS CHAR)` 转换：

1. ✅ `bot-margin-analysis.md` - Line 324
2. ✅ `main-site-energy-analysis.md` - Line 132
3. ✅ `main-site-creator-analysis.md` - Line 136

### 待修复的文件

以下文件需要修改：

#### 1. Schema 定义
- [ ] `functions/lib/db/schema.ts` - 将 `botId: integer("bot_id")` 改为 `botId: text("bot_id")`

#### 2. Migration 文件
- [ ] 创建新的 migration 文件，执行 `ALTER COLUMN bot_id TYPE TEXT`

#### 3. 数据插入代码
- [ ] `functions/lib/cost-snapshot.ts` - 确保 bot_id 作为字符串插入
- [ ] `functions/lib/daily-margin.ts` - 确保 bot_id 作为字符串插入
- [ ] 其他所有插入 snapshot 表的代码

#### 4. PostgreSQL 查询
- [ ] `team-update/bot-revenue-attribution-analysis.md` - 添加 CAST 转换（如果 schema 未修复）

## 验证方法

### 1. 验证数据库

```sql
-- 查看 bot_id 的数据类型
SELECT column_name, data_type
FROM information_schema.columns
WHERE table_name = 'daaf_bot_revenue_snapshots'
  AND column_name = 'bot_id';

-- 查看实际数据
SELECT bot_id, bot_name, task_count
FROM daaf_bot_revenue_snapshots
WHERE snapshot_date = CURRENT_DATE
ORDER BY task_count DESC
LIMIT 10;
```

**预期结果**:
- `data_type` 应该是 `text` (修复后)
- `bot_id` 应该显示完整的 10 位数字，如 "1769588427"

### 2. 验证 API 响应

```bash
# 调用 API 查询 Bot 数据
curl -X GET 'https://your-api.com/api/bot-revenue?days=7'

# 检查响应中的 bot_id
# ✅ 正确: "bot_id": "1769588427"
# ❌ 错误: "bot_id": 43836
```

### 3. 前端显示

在前端 UI 中查看 Bot ID：
- ✅ 正确显示：1769588427 (10位)
- ❌ 错误显示：43836 (5位)

## 注意事项

### JavaScript Number 精度问题

JavaScript Number 类型的安全整数范围：
- 最小：`Number.MIN_SAFE_INTEGER` = -(2^53 - 1) = -9007199254740991
- 最大：`Number.MAX_SAFE_INTEGER` = 2^53 - 1 = 9007199254740991

Bot ID（10位数字，如 1769588427）在安全范围内，但：
1. **PostgreSQL integer 类型范围更小**（-2,147,483,648 到 2,147,483,647）
2. **建议始终用字符串存储 ID**，避免任何精度问题

### 最佳实践

对于所有 ID 类型的字段（bot_id, user_id, task_id 等）：
1. ✅ **数据库**: 使用 `TEXT` 或 `VARCHAR` 类型
2. ✅ **API**: 作为字符串传输 `"1769588427"`
3. ✅ **前端**: 作为字符串处理和显示
4. ❌ **避免**: 使用数值类型存储或传输大整数 ID

## 参考资料

- [PostgreSQL Integer Types](https://www.postgresql.org/docs/current/datatype-numeric.html)
- [JavaScript Number.MAX_SAFE_INTEGER](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER)
- [MySQL CAST Function](https://dev.mysql.com/doc/refman/8.0/en/cast-functions.html)

---

**文档创建时间**: 2026-01-29
**修复状态**: 知识库 SQL 已修复，Schema 和 Migration 待实施
**优先级**: 高 - 影响所有 Bot 数据查询和显示