chore: update project structure for new workspace layout

2026-03-25 23:07:52 +08:00
parent e18d0ed3e6
commit fd21c8e1a1
21 changed files with 1641 additions and 402 deletions
@@ -1,329 +1,132 @@
-# akshare → vn.py 数据适配器系统
+# zhaoyun-data - 赵云数据工程工作区

-## 项目概述
+## 🧮 负责人：赵云（数据工程将军）
+**依据**：AGENTS.md角色配置  
+**职责**：数据获取、清洗验证、质量检查  
+**状态**：按照workflow-rules.md标准结构完成融合

-本项目实现了从 akshare 数据源获取A股历史数据，并批量写入 vn.py SQLite 数据库的完整解决方案。
+## 📁 目录结构（符合workflow-rules.md标准）

-**作者**: 赵云（数据护军）
-**完成日期**: 2026-03-24
+### research/ - 调研报告目录
+- 数据工程相关调研任务报告
+- 按任务日期和描述组织
+- 当前：暂无调研任务，待诸葛亮军师分配

---
+### scripts/ - 数据处理脚本
+- **data_acquisition/** - 数据获取脚本（批量下载器等）
+- **data_cleaning/** - 数据清洗脚本（待补充）
+- **data_validation/** - 数据验证脚本（适配器测试等）
+- **data_quality/** - 质量检查脚本（待补充）
+- **common_tools/** - 通用工具（AKShare-vnPy适配器等）

-## 功能特性
+### data/ - 数据存储目录
+- **raw/** - 原始数据（文章链接等）
+- **processed/** - 处理后的数据（聚宽精华文章数据等）
+- **running_data/** - 运行数据（测试数据库等）

-### 1. 数据适配器 (`akshare_vnpy_adapter.py`)
+### reports/ - 报告文档
+- 数据工程工作报告
+- 任务完成报告
+- 技术文档和说明

- ✅ 自动初始化 vn.py 数据库表结构
- ✅ 获取全市场A股股票列表
- ✅ 下载单只/全市场历史K线数据
- ✅ 数据格式自动转换（akshare → vn.py）
- ✅ 批量插入优化（使用 executemany）
- ✅ 数据完整性验证
- ✅ 支持日期范围筛选
- ✅ 支持复权类型选择（不复权/前复权/后复权）
+### references/ - 参考资料链接
+- 链接到通用知识库
+- 外部资源参考链接
+- 当前：待补充

-### 2. 批量下载器 (`batch_downloader.py`)
+## ✅ 融合成果总结

- ✅ 断点续传支持（保存进度到JSON文件）
- ✅ 失败重试机制
- ✅ 进度实时保存
- ✅ 统计信息跟踪
- ✅ 测试模式（可限制下载数量）
+### 已完成的核心数据工程成果

-### 3. 测试脚本 (`test_adapter.py`)
+#### 1. 聚宽精华文章数据处理
+- **数据规模**：11篇核心技术文章完整数据
+- **技术深度**：每篇超过500字深度技术分析
+- **存储位置**：`data/processed/jq_essence_articles/`

- ✅ 单元测试
- ✅ 完整流程验证
- ✅ 数据完整性验证
+#### 2. 数据获取与处理工具
+- **批量下载器**：`scripts/data_acquisition/batch_downloader.py`
+- **适配器测试**：`scripts/data_validation/test_adapter.py`
+- **数据转换工具**：`scripts/common_tools/akshare_vnpy_adapter.py`

---
+#### 3. 数据资源库
+- **原始数据**：聚宽文章链接库（`data/raw/articles_links.csv`）
+- **处理数据**：结构化聚宽文章数据
+- **运行数据**：测试数据库（`data/running_data/database_test.db`）

-## 数据库结构
+#### 4. 技术文档与报告
+- **实施报告**：数据工程实施详细报告
+- **验证报告**：数据质量验证报告
+- **任务报告**：已完成任务总结报告

-### DbBarData 表（K线数据）
+## 🎯 工作流程（依据workflow-rules.md）

-| 字段 | 类型 | 说明 |
-|------|------|------|
-| id | INTEGER | 主键（自增） |
-| symbol | TEXT | 股票代码 |
-| exchange | TEXT | 交易所（SH/SZ/BJ） |
-| datetime | TEXT | K线时间 |
-| interval | TEXT | 周期（1d/1w/1m等） |
-| open_price | REAL | 开盘价 |
-| high_price | REAL | 最高价 |
-| low_price | REAL | 最低价 |
-| close_price | REAL | 收盘价 |
-| volume | REAL | 成交量 |
-| turnover | REAL | 成交额（元） |
-| open_interest | REAL | 持仓量 |
-
-### DbTickData 表（TICK数据）
-
-包含完整五档行情数据（预留）
-
---
-
-## 使用方法
-
-### 1. 基本用法
-
-```python
-from akshare_vnpy_adapter import AkshareToVnpyAdapter
-
-# 创建适配器
-adapter = AkshareToVnpyAdapter('database.db')
-
-try:
-    # 初始化数据库
-    adapter.initialize_database()
-
-    # 下载单只股票
-    inserted = adapter.download_and_insert_stock_daily(
-        code='600519',  # 茅台
-        start_date='20240101',
-        end_date='20241231'
-    )
-    print(f"插入 {inserted} 条K线")
-
-    # 验证数据完整性
-    integrity = adapter.verify_data_integrity()
-    print(integrity)
-
-finally:
-    adapter.close()
+### 独立任务流程
+```
+诸葛亮军师分配任务 → 赵云执行 → 成果提交到对应目录 → 诸葛亮审核 → 归档
 ```

-### 2. 批量下载全市场数据
-
-```python
-from batch_downloader import BatchDownloader
-
-downloader = BatchDownloader(
-    db_path='database.db',
-    progress_file='download_progress.json'
-)
-
-try:
-    # 批量下载
-    stats = downloader.download(
-        start_date='20240101',  # 开始日期
-        max_stocks=None,        # None=全部，可设置如100测试
-        resume=True,            # 断点续传
-        retry_failed=True       # 重试失败的
-    )
-
-    # 验证数据
-    integrity = downloader.verify()
-
-finally:
-    downloader.close()
+### 协作任务流程
+```
+确定主导将军 → 主导将军建协作目录 → 赵云提交数据工程成果 → 主导将军整合 → 交付
 ```

-### 3. 运行测试
+### 赵云数据工程流程
+1. **数据获取**：使用`data_acquisition/`脚本获取原始数据
+2. **数据清洗**：使用`data_cleaning/`脚本处理数据质量问题
+3. **数据验证**：使用`data_validation/`脚本验证数据准确性
+4. **质量检查**：使用`data_quality/`脚本监控数据质量
+5. **存储归档**：将数据存储到`data/`相应子目录

-```bash
-# 运行单元测试
-python3 test_adapter.py
+## 🔧 当前可用资源

-# 运行完整下载（测试模式：50只股票）
-python3 batch_downloader.py
+### 数据资源
+- **聚宽文章库**：11篇核心技术文章完整数据
+- **文章链接库**：完整的聚宽文章索引
+- **测试数据库**：数据工程测试环境

-# 修改配置后运行完整下载（全市场）
-# 编辑 batch_downloader.py 中的 config
-python3 batch_downloader.py
-```
+### 工具资源
+- **数据获取工具**：支持批量下载和断点续传
+- **数据验证工具**：确保数据质量和一致性
+- **数据转换工具**：支持不同数据源格式统一
+
+### 文档资源
+- **技术文档**：详细的数据处理方法说明
+- **工作报告**：完整的任务执行记录
+- **参考指南**：数据工程最佳实践
+
+## 📊 质量保证
+
+### 数据质量标准
+1. **完整性**：确保数据字段无缺失
+2. **准确性**：验证数据值准确无误
+3. **一致性**：保持数据格式统一
+4. **时效性**：及时更新数据资源
+5. **可靠性**：确保数据来源和处理可追溯
+
+### 代码质量标准
+1. **规范标准**：Python代码符合PEP8规范
+2. **文档完整**：关键逻辑有详细注释
+3. **错误处理**：完善的异常处理机制
+4. **可维护性**：清晰的代码结构和模块化设计
+
+## 🔄 协作与沟通
+
+### 任务接收方式
+- 诸葛亮军师通过`sessions_send`直接分配任务
+- 及时确认任务要求和完成标准
+
+### 成果提交方式
+- 独立任务：成果提交到赵云工作区对应目录
+- 协作任务：成果提交到主导将军的协作目录
+- 文档标准：重要文档及时更新，保持同步
+
+### 沟通机制
+- 重要事项及时通知相关方
+- 定期更新工作进展状态
+- 使用统一的知识库共享资源

 ---

-## 数据格式映射
+**赵云承诺**：将严格按照AGENTS.md职责和工作流规则，高质量完成数据工程任务，为三国量化项目提供坚实的数据基础！🧮

-### akshare → vn.py 字段映射
-
-| akshare | vn.py | 说明 |
-|---------|-------|------|
-| date | datetime | 日期时间 |
-| open | open_price | 开盘价 |
-| high | high_price | 最高价 |
-| low | low_price | 最低价 |
-| close | close_price | 收盘价 |
-| volume | volume | 成交量 |
-| money | turnover | 成交额 |
-| - | open_interest | 持仓量（默认0） |
-
-### 交易所映射
-
-| 股票代码前缀 | 交易所 |
-|-------------|--------|
-| 6xxxxx | SH（上交所） |
-| 0xxxxx | SZ（深交所） |
-| 3xxxxx | SZ（深交所） |
-| 8xxxxx | BJ（北交所） |
-
---
-
-## 性能优化
-
-### 1. 批量写入
-
- 使用 `executemany` 代替逐条插入
- 默认批量大小：1000 条/批
-
-### 2. 事务控制
-
- 每个批次在一个事务中完成
- 自动提交或回滚
-
-### 3. 索引优化
-
- `(symbol, exchange, interval, datetime)` 联合索引
- `datetime` 单独索引
-
-### 4. 连接管理
-
- 复用数据库连接
- 自动关闭
-
---
-
-## 断点续传
-
-进度保存在 `download_progress.json` 文件中：
-
-```json
-{
-  "last_code": "600519",
-  "completed": ["000001", "000002", "600000", ...],
-  "failed": ["600123", "600456", ...],
-  "start_time": "2026-03-24T12:00:00",
-  "stats": {
-    "total": 5000,
-    "success": 3000,
-    "failed": 5,
-    "total_bars": 1500000
-  }
-}
-```
-
---
-
-## 数据完整性验证
-
-验证结果示例：
-
-```python
-{
-  "total_bars": 150.5万,
-  "total_stocks": 3000,
-  "min_date": "2024-01-01 09:30:00",
-  "max_date": "2026-03-23 15:00:00",
-  "low_count_samples": 0,
-  "has_duplicates": false,
-  "duplicates_count": 0,
-  "status": "OK"
-}
-```
-
---
-
-## 配置文件
-
-### batch_downloader.py 配置
-
-```python
-config = {
-    'db_path': '/path/to/database.db',
-    'progress_file': '/path/to/download_progress.json',
-    'start_date': '20240101',      # 开始日期
-    'max_stocks': None,            # None=全部，测试时可设置
-    'resume': True,                # 断点续传
-    'retry_failed': True           # 重试失败的
-}
-```
-
---
-
-## 日志文件
-
- `akshare_vnpy_adapter.log` - 适配器日志
- `batch_downloader.log` - 批量下载日志
-
---
-
-## 错误处理
-
-### 1. 网络错误
-
-自动重试（akshare内置重试机制）
-
-### 2. 数据库错误
-
- 重复数据自动忽略（UNIQUE约束）
- 事务回滚保证一致性
-
-### 3. 格式转换错误
-
- 记录错误日志
- 跳过错误数据，继续处理
-
---
-
-## 已知限制
-
-1. **网络依赖**: 需要稳定网络连接访问 akshare API
-2. **数据频率**: akshare有访问频率限制，批量下载需要控制并发
-3. **数据范围**: 历史数据可能有限（新股上市时间短）
-4. **TICK数据**: 当前只实现了K线数据，TICK数据待扩展
-
---
-
-## 下一步计划
-
-1. ✅ akshare 数据适配器 - **已完成**
-2. ⏸️ 聚宽（jqdatasdk）适配器 - 待开发
-3. ⏸️ Tushare Pro 适配器 - 待开发
-4. ⏸️ Wind 适配器 - 待调研
-5. ⏸️ TICK数据支持 - 待扩展
-6. ⏸️ 分钟K线支持 - 待扩展
-
---
-
-## 性能指标（预期）
-
- **K线数据**: 5000只股票 × 500交易日 = 250万条
- **数据库大小**: 约 200-300 MB
- **下载时间**: 约 2-4 小时（网络依赖）
- **写入速度**: 约 5000-10000 条/秒
-
---
-
-## 技术栈
-
- Python 3.8+
- akshare（数据源）
- SQLite（存储）
- pandas（数据处理）
- tqdm（进度条显示）
-
---
-
-## 许可证
-
-MIT License
-
---
-
-## 贡献
-
-欢迎提交 Issue 和 Pull Request！
-
---
-
-## 联系方式
-
-作者：赵云（数据护军）
-项目：三国之量化交易
-仓库：sanguo_quant_live
-
---
-
-*"数据为兵，策略为将，风控为帅" — 赵云*
+**常山赵子龙，数据工程工作区已按照标准完成融合，随时准备执行任务！**