# CoolBotDataSys - 酷博特数据分析系统

**版本：** v0.0.1  
**日期：** 2026-04-06

多源数据采集、存储、清洗、分析全链路自动化平台。

## 功能模块

| 模块 | 描述 |
|------|------|
| 爬虫引擎 | 一尘网连体纪念钞数据采集（每小时增量 + 每日全量） |
| REST API | 藏品管理、价格追踪、帖子查询、统计报表 |
| 数据分析 | 龙钞/马钞价格分类统计、求购/出售趋势分析 |
| LLM 辅助 | 阿里云通义千问价格提取（可选） |

## 技术栈

- **后端：** Python 3.12 + FastAPI + uvicorn
- **数据库：** PostgreSQL（RDS）+ Redis（本地缓存）
- **爬虫：** requests + BeautifulSoup（轻量定向采集）
- **定时任务：** APScheduler + cron

## 目录结构

```
coolbot-data/
├── api/                    # FastAPI 应用
│   ├── main.py             # 应用入口、路由注册
│   ├── middleware/         # 响应封装
│   ├── models/             # Pydantic 模型
│   └── routes/             # API 路由
│       ├── collections.py  # 藏品管理
│       ├── prices.py       # 价格查询
│       ├── health.py       # 健康检查
│       └── yichens.py      # 一尘数据（含统计报表）
├── crawlers/               # 爬虫模块
│   ├── base.py             # 爬虫基类（分页/重试/延时）
│   ├── crawl_today.py      # 今日增量采集
│   └── yichens_spider.py   # 全量历史采集
├── scripts/                # 运维脚本
│   ├── daily_crawl.sh      # 每日爬虫 cron
│   ├── daily_report.py     # 飞书日报推送
│   └── crawl_cron.sh       # cron 调度脚本
├── alembic/                # 数据库迁移
├── config/                 # YAML 配置
├── cache.py                # Redis 缓存
├── database.py             # PostgreSQL 连接
├── scheduler.py            # APScheduler 调度
├── llm_price_extract.py    # LLM 价格提取
└── requirements.txt        # Python 依赖
```

## 快速启动

```bash
# 1. 安装依赖
pip install -r requirements.txt

# 2. 配置环境变量
cp .env.example .env
# 编辑 .env 填入数据库密码等

# 3. 启动 API 服务
python -m uvicorn api.main:app --host 0.0.0.0 --port 8080

# 4. 启动定时爬虫
python scheduler.py
```

## API 文档

启动服务后访问：http://localhost:8080/docs

### 核心接口

| 接口 | 方法 | 描述 |
|------|------|------|
| /health | GET | 服务健康检查 |
| /api/v1/statistics | GET | 系统统计 |
| /api/v1/yichens/posts | GET | 帖子列表（支持分页/筛选） |
| /api/v1/yichens/statistics | GET | 一尘数据统计 |
| /api/v1/yichens/report/stats | GET | 龙钞分类统计（收购/出售细分） |
| /api/v1/yichens/report/categories | GET | 分类统计（今/近1小时） |
| /api/v1/collections | GET/POST | 藏品管理 |
| /api/v1/prices/latest | GET | 最新价格 |
| /api/v1/crawl-jobs/trigger | POST | 手动触发爬虫 |

## 数据库表

- collections - 藏品主表
- price_history - 价格历史
- yichens_posts - 一尘帖子（核心）
- yichens_users - 一尘用户
- yichens_replies - 帖子回复
- yichens_follows - 关注关系
- crawl_logs - 爬虫运行日志
- scheduled_tasks - 调度任务
- sys_config - 系统配置

## 爬虫调度

```cron
# 每15分钟增量采集
*/15 * * * * cd /root/coolbot-data && source venv/bin/activate && python3 crawlers/crawl_today.py >> logs/crawl_update.log 2>&1

# 每天8点全量采集
0 8 * * * cd /root/coolbot-data && source venv/bin/activate && python3 crawlers/yichens_spider.py >> logs/crawl_daily.log 2>&1
```

## 环境变量

详见 .env.example

## Git

```bash
git clone http://caibotmi:Caibotmi123@101.37.160.219/caibotmi/CoolBotDataSys.git
```