refactor: 将表结构定义从 storage 迁移到各 API 文件
- 移除 storage.py 集中式建表逻辑,改为各 API 文件自管理 - base_sync.py 新增 ensure_table_exists() 和表探测机制 - api_daily/api_pro_bar/api_bak_basic 添加 TABLE_SCHEMA 定义 - api_financial_sync 添加完整利润表字段定义 - sync.py 更新职责文档,明确仅同步每日更新数据 - AGENTS.md 添加 v2.1 架构变更历史和 AI 行为准则
This commit is contained in:
61
AGENTS.md
61
AGENTS.md
@@ -296,6 +296,34 @@ uv run python -c "from src.data.sync import sync_all; sync_all(max_workers=20)"
|
||||
|
||||
## 架构变更历史
|
||||
|
||||
### v2.1 (2026-02-28) - 同步模块规范更新
|
||||
|
||||
#### sync.py 职责划分
|
||||
**变更**: 明确 `sync.py` 只包含每日更新的数据同步
|
||||
**原因**: 区分高频(每日)和低频(季度/年度)数据,避免不必要的 API 调用
|
||||
**规范**:
|
||||
- `sync.py` / `sync_all_data()`: **仅包含每日更新的数据**
|
||||
- 日线数据 (`api_daily`)
|
||||
- Pro Bar 数据 (`api_pro_bar`)
|
||||
- 交易日历 (`api_trade_cal`)
|
||||
- 股票基本信息 (`api_stock_basic`)
|
||||
- 历史股票列表 (`api_bak_basic`)
|
||||
|
||||
- **不应放入 `sync.py` 的季度/低频数据**:
|
||||
- 财务数据 (`financial_data/` 目录): 利润表、资产负债表、现金流量表等
|
||||
- 名称变更 (`api_namechange`): 已移除自动同步,建议手动定期同步
|
||||
|
||||
- **季度数据同步方式**:
|
||||
```python
|
||||
# 财务数据单独同步(不在 sync_all_data 中)
|
||||
from src.data.api_wrappers.financial_data.api_financial_sync import sync_financial
|
||||
sync_financial() # 增量同步利润表
|
||||
|
||||
# 名称变更手动同步
|
||||
from src.data.api_wrappers import sync_namechange
|
||||
sync_namechange(force=True)
|
||||
```
|
||||
|
||||
### v2.0 (2026-02-23) - 重要更新
|
||||
|
||||
#### 存储层重构
|
||||
@@ -325,7 +353,34 @@ uv run python -c "from src.data.sync import sync_all; sync_all(max_workers=20)"
|
||||
`get_today_date()`、`get_next_date()`、`DEFAULT_START_DATE` 等函数统一在 `src/data/utils.py` 中管理
|
||||
其他模块应从 `utils.py` 导入这些函数,避免重复定义
|
||||
|
||||
### v1.x (历史版本)
|
||||
|
||||
初始版本,使用 HDF5 存储
|
||||
数据同步逻辑集中在 `sync.py`
|
||||
## AI 行为准则
|
||||
|
||||
### LSP 检测报错处理
|
||||
|
||||
**⚠️ 强制要求:当进行 LSP 检测时报错,必定是代码格式问题。**
|
||||
|
||||
如果 LSP 检测报错,必须按照以下流程处理:
|
||||
|
||||
1. **问题定位**
|
||||
- 报错必定是由基础格式错误引起:缩进错误、引号括号不匹配、代码格式错误等
|
||||
- 必须读取对应的代码行,精确定位错误
|
||||
|
||||
2. **修复方式**
|
||||
- ✅ **必须**:读取报错文件,检查具体代码行
|
||||
- ✅ **必须**:修复格式错误(缩进、括号匹配、引号闭合等)
|
||||
- ❌ **禁止**:删除文件重新修改
|
||||
- ❌ **禁止**:自行 rollback 文件
|
||||
- ❌ **禁止**:新建文件重新修改
|
||||
- ❌ **禁止**:忽略错误继续执行
|
||||
|
||||
3. **验证要求**
|
||||
- 修复后必须重新运行 LSP 检测确认无错误
|
||||
- 确保修改仅针对格式问题,不改变代码逻辑
|
||||
|
||||
**示例场景**:
|
||||
```
|
||||
LSP 报错:Syntax error on line 45
|
||||
✅ 正确做法:读取文件第 45 行,发现少了一个右括号,添加后重新检测
|
||||
❌ 错误做法:删除文件重新写、或者忽略错误继续
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user