QUICKSTART.md

# 海关数据系统 - 快速启动指南

## 前置要求

- Docker & Docker Compose
- Python 3.14+
- Git

## 1. 克隆项目

```bash
git clone <repository-url>
cd customs-data
```

## 2. 环境配置

```bash
# 复制环境变量模板
cp .env.template .env

# 编辑 .env，至少配置以下必需项：
# - DATABASE_URL
# - CLICKHOUSE_URL
# - ELASTICSEARCH_URL
# - REDIS_URL
```

### 可选配置（推荐）

```bash
# 配置至少一个告警渠道
FEISHU_WEBHOOK_URL=https://open.feishu.cn/open-apis/bot/v2/hook/xxx

# 配置邮件通知（用于导出和订阅）
SENDGRID_API_KEY=SG.xxx
NOTIFICATION_FROM_EMAIL=noreply@customs-data.com
```

## 3. 启动依赖服务

```bash
# 启动 PostgreSQL、ClickHouse、Elasticsearch、Redis
docker compose up -d db clickhouse elasticsearch redis

# 等待服务就绪（约30秒）
docker compose ps
```

## 4. 初始化数据库

```bash
# 创建 Python 虚拟环境
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

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

# 初始化数据库表
python init_db.py
```

## 5. 启动服务

### 方式一：Docker Compose（推荐）

```bash
# 启动所有服务（API、Worker、Scheduler）
docker compose up -d

# 查看日志
docker compose logs -f api worker
```

### 方式二：本地开发模式

```bash
# 终端 1：启动 API 服务
uvicorn apps.api.main:app --host 0.0.0.0 --port 8000 --reload

# 终端 2：启动 Celery Worker
celery -A packages.core.celery_app worker --loglevel=info

# 终端 3：启动 Celery Beat（定时任务）
celery -A packages.core.celery_app beat --loglevel=info
```

## 6. 验证服务

### 6.1 健康检查

```bash
# 基础健康检查
curl http://localhost:8000/api/v1/health/

# 完整健康检查（需要 API Key）
curl -H "X-API-Key: dev_key_12345" \
  http://localhost:8000/api/v1/health/full
```

### 6.2 查看 API 文档

打开浏览器访问：http://localhost:8000/docs

## 7. 运行测试

```bash
# 运行所有测试
pytest tests/ -v

# 运行特定测试
pytest tests/baseline/test_api_contracts.py -v
```

## 8. 数据同步示例

### 同步巴西数据

```bash
# 手动触发巴西数据同步
python -m apps.worker.run_brazil

# 或通过 API 触发（需要 API Key）
curl -X POST -H "X-API-Key: dev_key_12345" \
  http://localhost:8000/api/v1/admin/sync/brazil
```

### 历史回补

```bash
# 回补巴西 2023 年数据
python apps/worker/run_backfill.py BR 2023-01-01 2023-12-31
```

## 9. API 使用示例

### 9.1 搜索贸易记录

```bash
curl -X POST http://localhost:8000/api/v1/trade/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: dev_key_12345" \
  -d '{
    "source_country": "BR",
    "product_name": "mobile phone",
    "start_date": "2024-01-01",
    "page": 1,
    "limit": 20
  }'
```

### 9.2 创建订阅

```bash
curl -X POST http://localhost:8000/api/v1/subscription/ \
  -H "Content-Type: application/json" \
  -H "X-API-Key: dev_key_12345" \
  -d '{
    "user_email": "user@example.com",
    "target_hs_code": "851712"
  }'
```

### 9.3 提交导出任务

```bash
curl -X POST http://localhost:8000/api/v1/export/ \
  -H "Content-Type: application/json" \
  -H "X-API-Key: paid_key_12345" \
  -d '{
    "country": "BR",
    "start_date": "2024-01-01",
    "end_date": "2024-12-31",
    "email": "user@example.com"
  }'
```

### 9.4 查询任务状态

```bash
curl http://localhost:8000/api/v1/export/status/{task_id} \
  -H "X-API-Key: paid_key_12345"
```

## 10. 监控与告警

### 查看健康状态

```bash
# PostgreSQL 健康检查
curl -H "X-API-Key: dev_key_12345" \
  http://localhost:8000/api/v1/health/postgres

# ClickHouse 健康检查
curl -H "X-API-Key: dev_key_12345" \
  http://localhost:8000/api/v1/health/clickhouse

# Elasticsearch 健康检查
curl -H "X-API-Key: dev_key_12345" \
  http://localhost:8000/api/v1/health/elasticsearch

# 数据一致性检查
curl -H "X-API-Key: dev_key_12345" \
  http://localhost:8000/api/v1/health/consistency
```

### 查看日志

```bash
# Docker 日志
docker compose logs -f api worker

# 本地日志文件
tail -f logs/app.log
```

## 11. 常见问题

### Q: PostgreSQL 连接失败
```bash
# 检查服务状态
docker compose ps db

# 重启服务
docker compose restart db
```

### Q: Elasticsearch 内存不足
```bash
# 增加 Elasticsearch 内存限制（docker-compose.yml）
environment:
  - "ES_JAVA_OPTS=-Xms512m -Xmx512m"
```

### Q: Celery Worker 未启动
```bash
# 检查 Redis 连接
docker compose ps redis

# 查看 Worker 日志
docker compose logs worker
```

### Q: 测试失败
```bash
# 确保测试数据库初始化
TEST_DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5434/customs_data_test \
python init_db.py

# 重新运行测试
pytest tests/ -v --tb=short
```

## 12. 停止服务

```bash
# 停止所有服务
docker compose down

# 停止并删除数据卷（清空数据）
docker compose down -v
```

## 13. 下一步

- 查看 [开发完成总结](docs/开发完成总结.md) 了解系统功能
- 查看 [项目现状与未完成项梳理](docs/项目现状与未完成项梳理.md) 了解开发进度
- 查看 [国家与数据源接入清单](docs/国家与数据源接入清单.md) 了解数据覆盖
- 配置告警 Webhook 接收实时通知
- 配置 SendGrid 接收邮件通知
- 添加更多真实数据源连接器

## 14. 技术支持

- 文档：`docs/` 目录
- 测试：`tests/` 目录
- 示例：`temporary/` 目录
- 问题反馈：提交 Issue

---

**祝使用愉快！** 🎉