2483 Tasks 85acf149

# Implementation Tasks

## 1. 环境准备和依赖安装
- [ ] 1.1 使用 `uv add finnhub-python` 添加 Finnhub SDK 依赖
- [ ] 1.2 验证 finnhub-python 已正确安装
- [ ] 1.3 创建 Finnhub API Key 配置(添加到 .env 文件)

## 2. 批量获取脚本开发

### 2.1 核心功能实现
- [ ] 2.1.1 创建脚本 `scripts/fetch_hk_daily_from_finnhub.py`
- [ ] 2.1.2 实现代码格式转换函数 `ts_code_to_finnhub` 和 `finnhub_to_ts_code`
- [ ] 2.1.3 实现字段映射函数 `_map_finnhub_to_tushare`
- [ ] 2.1.4 实现派生字段计算(计算 pre_close, change, pct_chg)
- [ ] 2.1.5 实现 Finnhub API 调用封装
- [ ] 2.1.6 实现精确的速率控制类 `FinnhubRateLimiter` (60次/分钟)

### 2.2 数据库集成
- [ ] 2.2.1 实现从 ods_hk_basic 表获取股票列表的函数
- [ ] 2.2.2 实现数据写入 ods_hk_daily 表的函数
- [ ] 2.2.3 实现进度记录和断点续传功能

### 2.3 批量获取逻辑
- [ ] 2.3.1 实现主函数 `fetch_all_hk_stocks`
- [ ] 2.3.2 实现单只股票数据获取函数
- [ ] 2.3.3 实现错误处理和重试机制(最多3次)
- [ ] 2.3.4 实现进度显示和日志记录

## 3. 单元测试

### 3.1 代码转换测试
- [ ] 3.1.1 测试 TuShare 代码转 Finnhub 代码(各种边界情况)
- [ ] 3.1.2 测试 Finnhub 代码转 TuShare 代码
- [ ] 3.1.3 测试代码转换的幂等性

### 3.2 字段映射测试
- [ ] 3.2.1 测试基础字段映射
- [ ] 3.2.2 测试派生字段计算(pre_close, change, pct_chg)
- [ ] 3.2.3 测试时间戳转换
- [ ] 3.2.4 测试缺失字段处理(amount = null)

### 3.3 速率控制测试
- [ ] 3.3.1 测试速率控制逻辑(确保每秒最多1次调用)
- [ ] 3.3.2 测试连续调用场景

## 4. 集成测试

### 4.1 单只股票测试
- [ ] 4.1.1 测试获取 00001.HK (长和)的历史数据
- [ ] 4.1.2 测试获取 00700.HK (腾讯)的历史数据
- [ ] 4.1.3 验证数据格式与 TuShare 格式一致
- [ ] 4.1.4 验证数据库写入成功
- [ ] 4.1.5 验证数据可被查询服务正常查询

### 4.2 小规模批量测试
- [ ] 4.2.1 测试批量获取 10 只港股的历史数据
- [ ] 4.2.2 验证速率控制正常工作(每秒1次)
- [ ] 4.2.3 验证错误处理和重试机制
- [ ] 4.2.4 验证进度输出正确

## 5. 全量数据获取(必须完成)

### 5.1 准备工作
- [ ] 5.1.1 确认 ods_hk_basic 表中有港股列表数据
- [ ] 5.1.2 如果没有,先运行 `uv run cli.py load-hk-basic` 获取港股列表
- [ ] 5.1.3 确认数据库连接正常
- [ ] 5.1.4 确认 Finnhub API Key 配置正确

### 5.2 执行批量获取
- [ ] 5.2.1 执行脚本: `uv run scripts/fetch_hk_daily_from_finnhub.py`
- [ ] 5.2.2 监控获取进度和日志输出
- [ ] 5.2.3 记录成功获取的股票数量和失败数量
- [ ] 5.2.4 处理失败的股票(分析日志,必要时重试)

### 5.3 数据质量验证
- [ ] 5.3.1 统计入库的记录总数
- [ ] 5.3.2 检查是否有重复记录
- [ ] 5.3.3 验证数据覆盖的时间范围(至少一年)
- [ ] 5.3.4 抽查若干股票的数据完整性

### 5.4 查询服务验证
- [ ] 5.4.1 通过查询服务查询港股日线数据
- [ ] 5.4.2 验证前端股票详情页可正常显示港股 K 线图
- [ ] 5.4.3 验证股票列表可正常显示港股数据

## 6. 文档更新
- [ ] 6.1 更新 README.md,说明港股日线数据使用 Finnhub 数据源
- [ ] 6.2 创建脚本使用说明文档 `scripts/README_HK_DAILY.md`
- [ ] 6.3 更新 .env.example,添加 FINNHUB_API_KEY 配置项
- [ ] 6.4 记录 Finnhub API Key 申请流程

## 7. 清理工作
- [ ] 7.1 删除测试文件 test_*.py
- [ ] 7.2 代码审查和优化
- [ ] 7.3 归档本次变更到 openspec/archive/

## 关键里程碑

- ✅ **M1**: 单元测试全部通过
- ✅ **M2**: 单只股票集成测试通过
- ✅ **M3**: 小规模批量获取测试通过(10只股票)
- ⚠️ **M4**: 全量数据获取完成(所有港股至少一年历史数据) - **必须完成**
- ✅ **M5**: 查询服务验证通过
- ✅ **M6**: 文档更新完成

## 注意事项

1. **M4 是必须完成的里程碑**: 必须成功获取港股所有股票至少一年的历史日线数据,才能认为任务完成
2. **速率控制**: 严格控制在 60 次/分钟以内,避免触发 Finnhub API 限制
3. **API Key 安全**: Finnhub API Key 必须存储在 .env 文件中,不要提交到 Git
4. **错误处理**: 对于获取失败的股票,要记录详细日志,便于后续分析
5. **数据质量**: 确保数据格式正确,避免数据污染
6. **使用 uv**: 所有依赖管理使用 `uv add`,不要使用 pip

## 预估时间

- 环境准备: 0.5 小时
- 脚本开发: 2 小时
- 单元测试: 1 小时
- 集成测试: 1 小时
- 全量获取: 4-8 小时 (取决于股票数量和速率限制)
- 文档更新: 0.5 小时

**总计**: 约 9-13 小时