fin_data_unify_plat/DEVELOPMENT_TASKS_V2.2.md

# 金融数据中台 v2.2 - 开发任务书

**任务类型**: 功能集成开发  
**优先级**: 🔴 P0 - 重要  
**创建时间**: 2026-04-06 04:35  
**要求完成**: 2026-04-18 (12 人天)  
**执行人**: Agent Developer  

---

## 📋 项目背景

基于外部工程评估结果，决定集成 `python_market_data_service` 工程的核心功能到金融数据中台 v2.2。

**评估报告**: 
- 产品评分: 89.75/100 (A 级优秀)
- 技术评分: 80.0/100 (B 级良好)
- 综合评分: 85.4/100 (A 级优秀)
- ROI: 176-280%

---

## 🎯 开发目标

### 核心功能 (P0 - 必须完成)

| 功能 | 说明 | 工作量 | 优先级 |
|------|------|--------|--------|
| 股票 K 线查询 | 支持 8 周期 (1m~1month)、复权计算 | 1.5 天 | P0 |
| 期货 K 线查询 | 支持多周期、含持仓量/结算价 | 1.5 天 | P0 |
| 复权计算 | 前复权 (qfq)/后复权 (hfq)/不复权 | 1 天 | P0 |

### 增强功能 (P1 - 建议完成)

| 功能 | 说明 | 工作量 | 优先级 |
|------|------|--------|--------|
| 数据源适配器池 | 支持多数据源热切换 | 2 天 | P1 |
| 批量查询接口 | 支持最多 100 只股票批量查询 | 0.5 天 | P1 |
| 交易日历 | 股票/期货交易日历查询 | 0.5 天 | P1 |

### 可选功能 (P2 - 时间允许可完成)

| 功能 | 说明 | 工作量 | 优先级 |
|------|------|--------|--------|
| 期货合约查询 | 根据品种获取可交易合约列表 | 0.5 天 | P2 |
| 管理后台 | 数据源状态监控、健康检查 | 1 天 | P2 |

---

## 📁 代码位置

### 待集成代码
**源路径**: `/app/share_data/python_market_data_service/`

| 模块 | 源路径 | 目标路径 |
|------|--------|----------|
| API 路由 | `app/api/routes.py` | `backend/app/api/v2/kline.py` |
| 服务层 | `app/services/` | `backend/app/services/kline/` |
| 数据访问 | `app/repositories/` | `backend/app/repositories/kline/` |
| 适配器 | `app/adapters/` | `backend/app/adapters/` (复用现有) |
| 数据模型 | `app/models/` | `backend/app/models/kline.py` |
| 数据库迁移 | - | `backend/app/db/migrations_v2_2.py` |

### 现有代码 (复用)
| 模块 | 路径 | 说明 |
|------|------|------|
| amazingData SDK | `backend/app/adapters/amazing_adapter/` | 主数据源 |
| WebSocket | `backend/app/websocket/` | 保持现有架构 |
| 告警引擎 | `backend/app/services/alert_engine.py` | 保持现有 |
| 质量监控 | `backend/app/services/quality_monitor.py` | 增强 |

---

## 🔧 技术要求

### 1. 代码重构要求

#### 必须修复的问题
```python
# ❌ 问题代码 (源工程)
async def _fetch_from_adapter(self, ...):
    loop = asyncio.new_event_loop()
    asyncio.set_event_loop(loop)
    loop.run_until_complete(adapter.connect(config))

# ✅ 修复方案
async def _fetch_from_adapter(self, ...):
    # 直接使用当前事件循环
    items = await adapter.connect(config)
    return items
```

#### API 认证完善
```python
# ❌ 当前实现 (不完整)
def verify_api_key(x_api_key: Optional[str] = Header(None)):
    if not x_api_key:
        raise HTTPException(status_code=401, detail="Missing API Key")
    return x_api_key  # 未验证有效性

# ✅ 完善实现
async def verify_api_key(x_api_key: str = Header(...)):
    key_info = await api_key_store.get(x_api_key)
    if not key_info or key_info.expired:
        raise HTTPException(status_code=401, detail="Invalid or expired API Key")
    return key_info
```

#### CORS 配置收紧
```python
# ❌ 过于宽松
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    ...
)

# ✅ 收紧配置
app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://your-domain.com"],
    allow_credentials=True,
    allow_methods=["GET", "POST", "OPTIONS"],
    allow_headers=["Authorization", "Content-Type"],
)
```

### 2. 数据库设计

#### 新增表结构
```sql
-- 股票 K 线表 (日线)
CREATE TABLE stock_klines_1d (
    id BIGSERIAL PRIMARY KEY,
    symbol_id VARCHAR(20) NOT NULL,
    ts TIMESTAMP NOT NULL,
    open NUMERIC(18,4) NOT NULL,
    high NUMERIC(18,4) NOT NULL,
    low NUMERIC(18,4) NOT NULL,
    close NUMERIC(18,4) NOT NULL,
    volume BIGINT NOT NULL,
    amount NUMERIC(20,4) NOT NULL,
    trade_date DATE NOT NULL,
    is_limit_up BOOLEAN DEFAULT FALSE,
    is_limit_down BOOLEAN DEFAULT FALSE,
    total_market_cap NUMERIC(20,2),
    float_market_cap NUMERIC(20,2),
    inst_holding_ratio NUMERIC(5,2),
    trading_days INTEGER,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 期货 K 线表 (日线)
CREATE TABLE futures_klines_1d (
    id BIGSERIAL PRIMARY KEY,
    symbol_id VARCHAR(20) NOT NULL,
    ts TIMESTAMP NOT NULL,
    open NUMERIC(18,4) NOT NULL,
    high NUMERIC(18,4) NOT NULL,
    low NUMERIC(18,4) NOT NULL,
    close NUMERIC(18,4) NOT NULL,
    volume BIGINT NOT NULL,
    open_interest BIGINT NOT NULL,
    settlement_price NUMERIC(18,4),
    trade_date DATE NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 索引
CREATE INDEX idx_stock_klines_symbol_ts ON stock_klines_1d(symbol_id, ts DESC);
CREATE INDEX idx_futures_klines_symbol_ts ON futures_klines_1d(symbol_id, ts DESC);
```

### 3. API 接口设计

#### 股票 K 线查询
```python
# GET /v2/kline/stock/{symbol}
# 参数: start, end, freq, adjust

# 响应
{
    "code": 0,
    "message": "success",
    "data": {
        "symbol": "000001.SZ",
        "name": "平安银行",
        "freq": "1d",
        "adjust": "qfq",
        "count": 8,
        "items": [
            {
                "symbol": "000001.SZ",
                "time": "2026-03-01T00:00:00",
                "open": 10.50,
                "high": 10.80,
                "low": 10.40,
                "close": 10.65,
                "volume": 1500000,
                "amount": 15975000.00,
                "trade_date": "2026-03-01",
                "is_limit_up": false,
                "is_limit_down": false,
                "total_market_cap": 250000000000.00,
                "float_market_cap": 200000000000.00
            }
        ]
    }
}
```

#### 期货 K 线查询
```python
# GET /v2/kline/futures/{symbol}
# 参数：start, end, freq

# 响应
{
    "code": 0,
    "message": "success",
    "data": {
        "symbol": "AG2605.SHF",
        "name": "银 2605",
        "freq": "1d",
        "count": 8,
        "items": [
            {
                "symbol": "AG2605.SHF",
                "time": "2026-03-01T00:00:00",
                "open": 7850.0,
                "high": 7920.0,
                "low": 7830.0,
                "close": 7890.0,
                "volume": 125000,
                "open_interest": 85000,
                "settlement_price": 7880.0,
                "trade_date": "2026-03-01"
            }
        ]
    }
}
```

---

## 📝 开发任务清单

### 阶段 1: 核心功能 (5 天)

#### Day 1-2: 股票 K 线服务
- [ ] 阅读源代码 (`/app/share_data/python_market_data_service/app/services/stock_service.py`)
- [ ] 创建 `backend/app/services/kline/stock_service.py`
- [ ] 创建 `backend/app/repositories/kline/stock_repository.py`
- [ ] 创建 `backend/app/models/kline.py` (股票 K 线模型)
- [ ] 创建数据库迁移脚本 `backend/app/db/migrations_v2_2.py`
- [ ] 创建 API 路由 `backend/app/api/v2/kline.py` (股票部分)
- [ ] 编写单元测试

#### Day 3-4: 期货 K 线服务
- [ ] 阅读源代码 (`/app/share_data/python_market_data_service/app/services/futures_service.py`)
- [ ] 创建 `backend/app/services/kline/futures_service.py`
- [ ] 创建 `backend/app/repositories/kline/futures_repository.py`
- [ ] 更新 `backend/app/models/kline.py` (期货 K 线模型)
- [ ] 更新数据库迁移脚本
- [ ] 更新 API 路由 `backend/app/api/v2/kline.py` (期货部分)
- [ ] 编写单元测试

#### Day 5: 复权计算
- [ ] 阅读源代码 (复权计算逻辑)
- [ ] 创建 `backend/app/services/kline/adjustment_service.py`
- [ ] 实现前复权 (qfq) 算法
- [ ] 实现后复权 (hfq) 算法
- [ ] 集成到股票 K 线查询
- [ ] 编写单元测试

### 阶段 2: 增强功能 (3 天)

#### Day 6-7: 数据源适配器池
- [ ] 阅读源代码 (`/app/share_data/python_market_data_service/app/adapters/`)
- [ ] 创建 `backend/app/adapters/kline_adapter_pool.py`
- [ ] 实现 AmazingData 适配器 (复用现有)
- [ ] 实现 Tushare 适配器 (新增)
- [ ] 实现数据源热切换逻辑
- [ ] 编写单元测试

#### Day 8: 批量查询 + 交易日历
- [ ] 创建 `backend/app/api/v2/kline_batch.py` (批量查询)
- [ ] 创建 `backend/app/services/kline/calendar_service.py` (交易日历)
- [ ] 创建 `backend/app/repositories/kline/calendar_repository.py`
- [ ] 编写单元测试

### 阶段 3: 测试与优化 (2 天)

#### Day 9: 集成测试
- [ ] 配合 Tester 完成集成测试
- [ ] 修复测试发现的 Bug
- [ ] 性能优化

#### Day 10: 代码审查 + 修复
- [ ] 配合 Architect 完成代码审查
- [ ] 修复审查发现的问题
- [ ] 完善文档

### 阶段 4: 文档与部署 (2 天)

#### Day 11: 文档
- [ ] 更新 API 文档
- [ ] 编写部署文档
- [ ] 编写使用手册

#### Day 12: 部署
- [ ] 生产环境部署
- [ ] 监控配置
- [ ] 告警配置

---

## ✅ 验收标准

### 功能验收
| 功能 | 验收标准 | 状态 |
|------|----------|------|
| 股票 K 线查询 | 8 周期支持、复权计算正确 | ⬜ |
| 期货 K 线查询 | 多周期支持、含持仓量 | ⬜ |
| 复权计算 | 前复权/后复权结果准确 | ⬜ |
| 数据源切换 | 热切换成功、不影响服务 | ⬜ |
| 批量查询 | 100 只股票批量查询正常 | ⬜ |

### 代码质量
| 指标 | 要求 | 状态 |
|------|------|------|
| 单元测试覆盖率 | >80% | ⬜ |
| 代码规范 | 遵循 PEP8 | ⬜ |
| 文档完整性 | API 文档完整 | ⬜ |
| 安全性 | API 认证完善、CORS 收紧 | ⬜ |

### 性能指标
| 指标 | 要求 | 状态 |
|------|------|------|
| K 线查询延迟 | <100ms (缓存命中) | ⬜ |
| K 线查询延迟 | <500ms (数据库) | ⬜ |
| 批量查询 (100 只) | <2s | ⬜ |
| 并发支持 | >500 QPS | ⬜ |

---

## 📞 协作方式

| 角色 | Agent ID | 职责 |
|------|----------|------|
| 协调者 | coordinator | 进度跟踪、资源协调 |
| 架构师 | architect | 代码审查、技术方案 |
| 产品经理 | product_manager | 需求确认、产品验收 |
| 开发工程师 | developer | 代码开发、单元测试 |
| 测试工程师 | tester | 集成测试、性能测试 |

---

## 📢 进度汇报

**汇报频率**: 每日汇报  
**汇报内容**:
- 今日完成工作
- 遇到的问题
- 明日计划
- 需要协助的事项

**汇报方式**: 通过 coordinator Agent 汇报

---

## 🚨 风险预警

如遇到以下情况，立即通知 coordinator：

1. **技术阻塞**: 无法解决的技术问题超过 2 小时
2. **进度延迟**: 预计延迟超过 1 天
3. **需求变更**: 需要调整功能范围
4. **资源不足**: 需要额外资源支持

---

**任务创建人**: Agent Coordinator  
**创建时间**: 2026-04-06 04:35  
**任务状态**: 🟢 进行中  
**预计完成**: 2026-04-18  

---

**请 Developer Agent 开始执行开发任务！**