# v7.4.1 Input 文档（合并版）

> **版本**：v7.4.1
> **功能名**：Twitter/X 搜索与详情页（合并版）
> **状态**：📝 Input 阶段（扩展版）
> **前置背景**：[@v740_background.md](./v740_background.md)
> **变更记录**：v1（搜索功能）→ v2（搜索+详情页合并）

---

## 一、背景与目标

### 1.1 版本合并决策（2026-03-16）

**原始规划**：
- v7.4.1：Twitter 搜索数据补齐（头像、粉丝量、筛选条件）
- v7.4.2：Twitter 详情页（频道详情、推文展示、互动数据）

**合并原因**：
与数据组确认后，数据积累已达规模，无需分阶段交付：

| 指标 | 数值 | 说明 |
|------|------|------|
| 账号总数 | 1000万+ | 已采集 Twitter 账号 |
| 万粉以上占比 | 20%+ | 约 200万+ 有效创作者账号 |
| 推文采集 | 最近20条/频道 | 持续更新中 |
| 数据字段 | 25+ 字段 | 含互动数据、地理位置、认证状态等 |

**合并后范围**：
- ✅ Twitter 搜索数据补齐 + 筛选扩展
- ✅ **新增**：Twitter 频道详情页
- ✅ **新增**：最近推文列表展示
- ✅ **新增**：账号级互动率计算

### 1.2 前置版本结论（v7.4.0）

v7.4.0 已上线"其他社媒搜索"功能，包含 Facebook 和 Twitter 两个平台：
- 使用**桥接逻辑**：实际搜索 YouTube 数据，取"关联了 Twitter 的频道"作为过滤条件
- 展示形式：左侧 Twitter 样式占位 + 右侧 YouTube/TikTok/Instagram 原始数据
- **数据缺口**：缺少 Twitter 头像、粉丝量等真实数据展示

### 1.3 本版本目标

**核心目标**：
1. 补齐 Twitter 搜索数据展示（头像、粉丝量、筛选条件）
2. **新增** Twitter 频道详情页，支持查看频道数据和最近推文

**差异化价值**：
- AspireIQ 明确不支持 Twitter/X，仅聚焦视觉平台
- NoxInfluencer 完整支持 Twitter 搜索+详情页，形成差异化

---

## 二、需求清单

### 2.1 搜索模块

#### 数据展示补齐

| 数据项 | 当前状态 | 目标状态 | 说明 |
|--------|----------|----------|------|
| Twitter 头像 | 占位图/无 | 展示真实头像 | P0 |
| Twitter 粉丝量 | 不展示 | 展示粉丝量 | P0 |
| Twitter 账号名称 | 展示 | 保持 | 已有 |
| Twitter 账号 URL | 展示 | 保持 | 已有 |
| **认证状态** | 不展示 | 展示蓝V/传统认证 | P1（新增）|
| **数据更新时间** | 不展示 | 展示更新时效 | P1（新增）|

#### 筛选条件扩展

| 筛选条件 | 优先级 | 说明 |
|----------|--------|------|
| Twitter 粉丝量范围 | P0 | 基于 `followers` 字段 |
| **国家/地区** | P1 | 基于 `country` / `location` 字段 |
| **认证状态** | P1 | 蓝V/传统认证/未认证 |

### 2.2 详情页模块（新增）

#### 频道 Overview

| 模块 | 内容 | 优先级 |
|------|------|--------|
| 头部信息 | 头像、名称、@handle、认证标识 | P0 |
| Bio 信息 | 个人简介、地理位置、个人网站 | P0 |
| 关键指标 | 粉丝量、关注数、发帖总数 | P0 |

#### 数据卡片

| 卡片 | 内容 | 优先级 |
|------|------|--------|
| **粉丝趋势** | 近30天粉丝增长趋势图 | P1 |
| **互动率** | 账号级互动率（基于20条推文计算）| P1 |
| **发帖频率** | 平均发帖频率统计 | P1 |
| 数据时效 | 数据更新时间展示 | P1 |

#### 最近推文列表

| 功能 | 说明 | 优先级 |
|------|------|--------|
| 推文列表 | 最近20条推文 | P0 |
| 推文内容 | 文本、媒体缩略图 | P0 |
| 互动数据 | 点赞、转发、评论、浏览量 | P0 |
| **排序方式** | 默认按时间倒序，支持按互动排序 | P1 |

#### 受众画像（如有数据）

| 画像维度 | 说明 | 优先级 |
|----------|------|--------|
| 受众地区 | 粉丝地理分布 | P2（数据待确认）|
| 受众性别/年龄 | 性别比例、年龄分布 | P2（数据待确认）|

---

## 三、业务规则

### 3.1 数据匹配规则

**搜索模块**：
- 仅展示【与 YouTube 频道有关联关系】的 Twitter 账号数据
- 如无关联 Twitter 账号，保持现有逻辑（不展示 Twitter 占位卡片）

**详情页模块**：
- 支持直接从搜索结果点击进入详情页
- **待确认**：是否支持直接通过 Twitter handle/URL 访问详情页？

### 3.2 数据计算规则

#### 账号级互动率计算

基于20条最新推文聚合计算：

```
互动率 = (Σ likes + Σ retweets + Σ comments) / (Σ views) × 100%
```

- 分子：所有推文互动数总和（点赞+转发+评论）
- 分母：所有推文浏览量总和
- 当 views 为0时，使用粉丝量作为分母

**待确认**：
- 数据组是否已预计算账号级互动率？
- 如无预计算，是否由后端实时聚合？

#### 发帖频率计算

```
发帖频率 = 20条推文 / (最早推文日期 - 最新推文日期)
```

#### 粉丝趋势计算

- 需对比历史数据，计算近30天粉丝增长
- **待确认**：历史数据存储策略？

### 3.3 数据时效性

- 使用已收集的离线数据（非实时 API 查询）
- 数据更新频率：**待与数据组确认**
- 建议展示数据更新时间（如 "3小时前更新"）

### 3.4 边界情况

| 场景 | 处理规则 |
|------|----------|
| YouTube 频道关联了 Twitter，但 Twitter 数据未收集到 | 左侧 Twitter 卡片如何处理？（待 Design 阶段定义） |
| Twitter 头像获取失败 | 使用占位图还是隐藏头像？（待 Design 阶段定义） |
| 推文数据不足20条 | 展示实际采集到的数量，互动率基于实际数量计算 |
| 互动数据缺失（views=0）| 使用粉丝量作为分母计算互动率 |

---

## 四、关键问题待确认

| # | 问题 | 影响 | 建议方案 |
|---|------|------|----------|
| 1 | 账号级互动率是否已预计算？ | 决定实时计算 vs 直接使用 | 优先使用预计算字段 |
| 2 | 数据更新频率？ | 决定详情页数据时效展示 | 每日/每周更新 |
| 3 | **详情页 URL 结构设计？** | 影响路由和分享功能 | `/twitter/{handle}` 或 `/twitter/{id}` |
| 4 | 推文展示排序方式？ | 默认按时间倒序？支持按互动排序？ | 默认时间倒序，P1支持互动排序 |
| 5 | 是否支持直接访问详情页（非搜索进入）？ | 影响详情页数据获取逻辑 | 支持，通过 handle/ID 查询 |
| 6 | 粉丝趋势历史数据存储策略？ | 影响趋势图实现 | 需数据组确认 |

---

## 五、非功能性需求

### 5.1 性能

- 搜索响应时间保持与 v7.4.0 持平
- 详情页加载时间 < 2s
- Twitter 数据查询不增加明显延迟（使用预计算/索引）

### 5.2 兼容性

- 保持与 v7.4.0 相同的浏览器支持范围
- 详情页移动端适配（响应式或独立移动端布局）

---

## 六、数据字段清单

> **数据来源**：`kol_twitter_v1` 索引 + `kol_twitter_tweets_2026` 索引
> **样例文件**：[@twitter_data_sample_raw.json](./twitter_data_sample_raw.json) + [@twitter_tweet_sample_raw.json](./twitter_tweet_sample_raw.json)
> **字段说明**：[@twitter_data_fields.md](./twitter_data_fields.md)

### 6.1 搜索模块可用字段

#### P0 - 必须展示

| 字段 | 含义 | 样例值 |
|------|------|--------|
| `avatar` | Twitter 头像 URL | `https://res-kol.../f9b87041...png` |
| `followers` | **粉丝数量** | `424573` |
| `alias` | @用户名（handle）| `nananat96` |
| `username` | 显示名称 | `Natalia` |
| `biography` | 个人简介 | `MIDZY 👑 IG : nananat...` |

#### P1 - 建议展示

| 字段 | 含义 | 样例值 |
|------|------|--------|
| `location` | 地理位置（自由文本）| `Jakarta` |
| `country` | **国家代码**（ISO）| `ID` |
| `is_blue_verified` | 蓝V认证 | `false` |
| `is_verified` | 传统认证 | `null` |
| `generated_at` | 数据更新时间戳 | `1773655902219` |

### 6.2 详情页可用字段

#### 账号基础信息

| 字段 | 含义 | v7.4.1 |
|------|------|--------|
| `followers` | 粉丝数 | ✅ 展示 |
| `following` | 关注数 | ✅ 展示 |
| `posts_number` | 发帖总数 | ✅ 展示 |
| `register_date` | 注册日期 | ⬜ 可选 |
| `external_url` | 个人网站 | ✅ 展示 |

#### 推文互动数据（最近20条）

| 字段 | 含义 | 用途 |
|------|------|------|
| `likes` | 点赞数 | 展示+互动率计算 |
| `retweets` | 转发数 | 展示+互动率计算 |
| `comments` | 评论数 | 展示+互动率计算 |
| `views` | 浏览量 | 展示+互动率分母 |
| `bookmarks` | 收藏数 | ⬜ 可选展示 |
| `quotes` | 引用数 | ⬜ 可选展示 |

---

## 七、竞品现状

### 直接竞品分析

| 竞品 | Twitter/X 支持 | 核心特色 | 数据库规模 |
|------|---------------|----------|-----------|
| **Traackr** | ✅ 支持 | 30+ 筛选器，Reach/Resonance/Relevance 三评分 | 6M-13M+ |
| **Upfluence** | ✅ 支持 | 20+ 筛选，Relevancy+Influence 双评分 | 3M-12M+ |
| **Klear** | ✅ 支持 | AI 匹配度摘要，True Reach，语义搜索 | 30M+ |
| **HypeAuditor** | ✅ 支持 | AQS 质量评分 1-100，Lookalike 搜索 | 68M-205M |
| **AspireIQ** | ❌ **不支持** | 仅支持 IG/TikTok/Pinterest/YouTube/FB | 500K-170M |

### 关键洞察

1. **AspireIQ 放弃 Twitter 支持**：明确不支持 Twitter/X，仅聚焦视觉平台。NoxInfluencer v7.4.1 完整支持 Twitter 搜索+详情页，形成差异化。

2. **行业基线功能**：粉丝量范围筛选、地理位置筛选、互动率展示是所有竞标配齐的基础能力，v7.4.1 需优先支持。

3. **详情页标准**：竞品详情页均包含：
   - 频道基础信息（头像、Bio、关键指标）
   - 数据趋势图表（粉丝增长、互动趋势）
   - 最近内容列表（含互动数据）
   - 受众画像（如有数据）

> **完整竞品调研报告**：详见 `02_Research_Analysis/twitter_search_竞研/05_insights/竞品洞察.md`

---

## 八、参考文档

- [v740_background.md](./v740_background.md) - v7.4.0 背景文档
- [twitter_data_sample_raw.json](./twitter_data_sample_raw.json) - Twitter 账号数据样例
- [twitter_tweet_sample_raw.json](./twitter_tweet_sample_raw.json) - Twitter 推文数据样例
- [twitter_data_fields.md](./twitter_data_fields.md) - Twitter 字段说明文档
- `02_Research_Analysis/twitter_search_竞研/05_insights/竞品洞察.md` - 竞品调研报告
- `__main__.md` 版本速查表

---

## 九、变更记录

| 日期 | 版本 | 变更内容 | 作者 |
|------|------|----------|------|
| 2026-03-16 | v1 | 初始版本（仅搜索功能）| Claude |
| 2026-03-16 | v2 | 补充 Twitter 数据字段分析 | Claude |
| 2026-03-16 | v3 | 补充推文数据样例，更新互动率结论 | Claude |
| 2026-03-16 | **v2** | **版本合并：扩展为搜索+详情页** | Claude |

---

*文档生成时间: 2026-03-16*
*基于数据组提供的账号+推文真实样例*
*版本合并决策：数据积累已达规模（1000万+账号，20条推文/频道）*