# AI 提号数据库与检索需求整理

## 目标

用户上传 Brief 或需求文件后，服务端自动完成需求解析、达人库检索、外部 API 兜底、推荐排序和名单导出。系统应优先使用自有达人库；自有库不足时再调用 JustOne API 补充候选，并将 JustOne 返回的原始数据全部沉淀，作为后续自有库建设和 RAG 检索的数据缓存。

## 检索优先级

1. 已清洗达人库：来自公司明确归类的达人表、用户上传的本地资源库，以及后续人工确认后的达人数据。
2. 未清洗接口缓存：JustOne API 等外部接口返回的原始数据，不论当前是否符合 Brief，都需保存。
3. 外部 API 兜底：当数据库无法召回足够候选时，调用 JustOne API 搜索。

## 数据有效期

- 已清洗达人库以业务更新为准，可长期保存，并记录来源、更新时间和字段完整度。
- 未清洗接口缓存默认有效期 30 天。超过 30 天的数据不参与自动推荐，只保留为历史归档和后续分析材料。

## RAG 友好的线上表结构建议

### creator_profile_clean

用于已清洗、可直接推荐的达人主表。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | uuid / bigint | 主键 |
| platform | varchar | 平台，如 xiaohongshu、douyin |
| platform_user_id | varchar | 平台账号 ID |
| display_name | varchar | 昵称 |
| gender | varchar | 性别 |
| fans_count | bigint | 粉丝数，统一存真实数量 |
| liked_collect_count | bigint | 赞藏/互动数，统一存真实数量 |
| content_type | text | 原始内容类型文本 |
| content_tags | jsonb | 结构化内容标签 |
| persona_tags | jsonb | 人设/风格标签 |
| city | varchar | 业务城市 |
| geo_location | varchar | 真实地理位置 |
| profile_url | text | 主页链接 |
| cooperation_method | varchar | 合作方式 |
| image_price | int | 图文报价 |
| video_price | int | 视频报价 |
| min_price | int | 最低报价 |
| source_kind | varchar | uploaded/company/confirmed_api |
| source_file | text | 上传文件或来源 |
| source_confidence | int | 来源可信度 |
| updated_at | timestamp | 最近更新时间 |
| embedding_text | text | 用于向量化的拼接文本 |
| embedding | vector | 向量字段，后续接 pgvector/Milvus 等 |

建议唯一索引：`(platform, platform_user_id)`。

### provider_raw_cache

用于保存 JustOne API 等接口返回的未清洗原始数据。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | uuid / bigint | 主键 |
| provider | varchar | justone/tikhub 等 |
| endpoint | text | 请求接口 |
| request_params | jsonb | 请求参数 |
| response_body | jsonb | 原始响应 |
| fetched_at | timestamp | 获取时间 |
| expires_at | timestamp | 默认 fetched_at + 30 天 |
| normalized_status | varchar | pending/normalized/rejected |
| archive_path | text | 本地归档路径 |

建议索引：`provider, fetched_at, expires_at`，以及对 `request_params` 建 GIN 索引。

### provider_creator_raw_cache

用于保存外部 API 返回后解析出的“逐达人未清洗缓存”。它和 `provider_raw_cache` 的关系是：`provider_raw_cache` 保留完整原始响应，便于追溯；`provider_creator_raw_cache` 将响应中的每个达人拆出来，便于后续 RAG 检索、去重、清洗和人工确认。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | uuid / bigint | 主键 |
| provider | varchar | justone/tikhub 等 |
| endpoint | text | 请求接口 |
| request_params | jsonb | 请求参数 |
| platform | varchar | 平台，如 xiaohongshu、douyin |
| platform_user_id | varchar | 平台账号 ID |
| display_name | varchar | 昵称 |
| fans_count | bigint | 粉丝数，统一存真实数量 |
| liked_collect_count | bigint | 赞藏/互动数 |
| content_type | text | 原始内容类型文本 |
| content_tags | jsonb | 解析出的内容标签 |
| persona_tags | jsonb | 解析出的人设/风格标签 |
| city | varchar | 城市 |
| geo_location | varchar | 地理位置 |
| profile_url | text | 平台主页链接 |
| cooperation_method | varchar | 合作方式 |
| image_price | int | 图文报价 |
| video_price | int | 视频报价 |
| min_price | int | 最低报价 |
| cooperation_status | varchar | 合作状态 |
| raw_creator | jsonb | 单个达人原始解析对象 |
| fetched_at | timestamp | 获取时间 |
| expires_at | timestamp | 默认 fetched_at + 30 天 |
| normalized_status | varchar | raw/normalized/rejected |
| embedding_text | text | 用于向量化的拼接文本 |
| embedding | vector | 向量字段，后续接 pgvector/Milvus 等 |

建议唯一索引：`(provider, platform, platform_user_id)`。建议索引：`platform, city, expires_at`，以及对 `content_tags` 建 GIN 索引。

### creator_profile_retrieval_view

用于统一查询“当前可参与检索的达人数据”。该视图合并：

- `creator_profile_clean` 中的已清洗达人；
- `provider_creator_raw_cache` 中未过期的外部 API 未清洗达人。

视图字段应保持和推荐检索需要的字段一致，并增加 `cache_layer` 标识来源层级：

| cache_layer | 说明 |
| --- | --- |
| clean | 已清洗/本地上传/人工确认达人 |
| provider_raw | 外部 API 未清洗缓存达人，且 `expires_at > now()` |

日常排查总可检索数量时建议查询：

```sql
select cache_layer, source_provider, platform, count(*)
from creator_profile_retrieval_view
group by cache_layer, source_provider, platform;
```

### creator_retrieval_event

用于记录每次 Brief 检索过程，方便复盘。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | uuid / bigint | 主键 |
| task_id | varchar | 提号任务 ID |
| query_text | text | Brief/检索文本 |
| criteria | jsonb | 结构化搜索条件 |
| local_hit_count | int | 本地库命中数 |
| provider_hit_count | int | 外部 API 命中数 |
| final_count | int | 最终候选数 |
| created_at | timestamp | 发生时间 |

## 本地开发阶段实现策略

当前开发环境已经升级为本地 PostgreSQL：

- 数据库：`tihao_ai`
- 应用用户：`tihao_ai_app`
- 初始化脚本：`npm run db:init`
- 表结构脚本：`server/db/schema.sql`
- Clean 达人表：`creator_profile_clean`
- 未清洗接口原始响应表：`provider_raw_cache`
- 未清洗接口逐达人缓存表：`provider_creator_raw_cache`
- 当前可检索达人视图：`creator_profile_retrieval_view`
- 检索事件表：`creator_retrieval_event`
- JustOne 原始响应归档：`docs/provider-archives/`

本地先使用 `double precision[]` 保存向量，并通过 PostgreSQL 函数 `cosine_similarity` 做余弦相似度检索。上线环境如安装 `pgvector`，可将 `embedding` 字段迁移为 `vector` 类型，并保留当前服务层的查询编排逻辑。