436 lines
9.0 KiB
Markdown
436 lines
9.0 KiB
Markdown
# 自选股分组管理使用说明
|
||
|
||
## 功能概述
|
||
|
||
自选股分组管理功能允许用户将股票分类到不同的分组中，实现更精细的股票管理。
|
||
|
||
### 核心特性
|
||
|
||
✅ **多分组支持** - 预设 4 个分组（核心自选、观察池、持仓股、概念股），支持自定义创建
|
||
✅ **分组快速切换** - 快速查看不同分组的股票
|
||
✅ **拖拽排序** - 分组和股票都支持拖拽排序
|
||
✅ **批量操作** - 批量添加、移动股票
|
||
✅ **股票备注** - 每只股票可添加个人备注
|
||
✅ **跨分组搜索** - 快速查找股票所在分组
|
||
✅ **颜色标识** - 每个分组有独立颜色标识
|
||
|
||
---
|
||
|
||
## 数据结构
|
||
|
||
### 分组表 (watchlist_groups)
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | int | 分组 ID |
|
||
| name | string | 分组名称 |
|
||
| description | string | 分组描述 |
|
||
| color | string | 颜色标识 (red/blue/green/purple) |
|
||
| sort_order | int | 排序号 |
|
||
| is_default | bool | 是否默认分组（不可删除） |
|
||
| created_at | datetime | 创建时间 |
|
||
|
||
### 股票项表 (watchlist_items)
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | int | 项目 ID |
|
||
| group_id | int | 所属分组 ID |
|
||
| code | string | 股票代码 |
|
||
| name | string | 股票名称 |
|
||
| sort_order | int | 排序号 |
|
||
| note | string | 个人备注 |
|
||
| added_at | datetime | 添加时间 |
|
||
|
||
---
|
||
|
||
## API 接口
|
||
|
||
### 1. 获取所有分组
|
||
|
||
```bash
|
||
GET /api/watchlist/groups
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"groups": [
|
||
{
|
||
"id": 1,
|
||
"name": "核心自选",
|
||
"description": "重点关注的核心股票",
|
||
"color": "red",
|
||
"count": 5,
|
||
"is_default": true,
|
||
"sort_order": 0
|
||
},
|
||
{
|
||
"id": 2,
|
||
"name": "观察池",
|
||
"description": "待观察的潜力股",
|
||
"color": "blue",
|
||
"count": 3,
|
||
"is_default": false,
|
||
"sort_order": 1
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 2. 创建新分组
|
||
|
||
```bash
|
||
POST /api/watchlist/groups
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"name": "科技股",
|
||
"description": "科技板块相关",
|
||
"color": "purple"
|
||
}
|
||
```
|
||
|
||
**可选颜色**: `red`, `blue`, `green`, `purple`, `orange`, `yellow`
|
||
|
||
### 3. 更新分组信息
|
||
|
||
```bash
|
||
PUT /api/watchlist/groups/{group_id}
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"name": "新名称",
|
||
"description": "新描述",
|
||
"color": "green"
|
||
}
|
||
```
|
||
|
||
### 4. 删除分组
|
||
|
||
```bash
|
||
DELETE /api/watchlist/groups/{group_id}
|
||
```
|
||
|
||
**注意**: 默认分组不能删除，删除分组会同时删除分组内的所有股票。
|
||
|
||
### 5. 重新排序分组
|
||
|
||
```bash
|
||
POST /api/watchlist/groups/reorder
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"group_ids": [2, 1, 3, 4]
|
||
}
|
||
```
|
||
|
||
### 6. 获取分组内的股票
|
||
|
||
```bash
|
||
GET /api/watchlist/groups/{group_id}/stocks?with_quotes=true
|
||
```
|
||
|
||
**参数**:
|
||
- `with_quotes` (bool): 是否包含实时行情，默认 true
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"group": {
|
||
"id": 1,
|
||
"name": "核心自选",
|
||
"description": "重点关注的核心股票",
|
||
"color": "red"
|
||
},
|
||
"stocks": [
|
||
{
|
||
"id": 1,
|
||
"code": "600519",
|
||
"name": "贵州茅台",
|
||
"price": 1680.5,
|
||
"pct": 2.3,
|
||
"change": 37.8,
|
||
"amount": 125.6,
|
||
"note": "长期持有",
|
||
"added_at": "2024-01-15"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 7. 添加股票到分组
|
||
|
||
```bash
|
||
POST /api/watchlist/groups/{group_id}/stocks
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"code": "600519",
|
||
"note": "优质白马股"
|
||
}
|
||
```
|
||
|
||
### 8. 批量添加股票
|
||
|
||
```bash
|
||
POST /api/watchlist/groups/{group_id}/stocks/batch
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"codes": ["600519", "300750", "002594"]
|
||
}
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"added": 3,
|
||
"skipped": 0
|
||
}
|
||
```
|
||
|
||
### 9. 从分组中移除股票
|
||
|
||
```bash
|
||
DELETE /api/watchlist/stocks/{item_id}
|
||
```
|
||
|
||
### 10. 移动股票到另一个分组
|
||
|
||
```bash
|
||
POST /api/watchlist/stocks/{item_id}/move
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"target_group_id": 2
|
||
}
|
||
```
|
||
|
||
### 11. 更新股票备注
|
||
|
||
```bash
|
||
PUT /api/watchlist/stocks/{item_id}/note
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"note": "待突破压力位"
|
||
}
|
||
```
|
||
|
||
### 12. 重新排序股票
|
||
|
||
```bash
|
||
POST /api/watchlist/stocks/reorder
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"item_ids": [3, 1, 2, 5, 4]
|
||
}
|
||
```
|
||
|
||
### 13. 跨分组搜索股票
|
||
|
||
```bash
|
||
GET /api/watchlist/search?keyword=茅台
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"results": [
|
||
{
|
||
"id": 1,
|
||
"code": "600519",
|
||
"name": "贵州茅台",
|
||
"group_id": 1,
|
||
"group_name": "核心自选",
|
||
"group_color": "red",
|
||
"note": "长期持有"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 使用示例
|
||
|
||
### 示例 1: 创建分组并添加股票
|
||
|
||
```bash
|
||
# 1. 创建分组
|
||
curl -X POST http://localhost:8000/api/watchlist/groups \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"name":"科技股","description":"科技板块","color":"purple"}'
|
||
|
||
# 假设返回的 group_id 是 5
|
||
|
||
# 2. 批量添加股票
|
||
curl -X POST http://localhost:8000/api/watchlist/groups/5/stocks/batch \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"codes":["300750","688981","002594"]}'
|
||
|
||
# 3. 查看分组内股票
|
||
curl http://localhost:8000/api/watchlist/groups/5/stocks
|
||
```
|
||
|
||
### 示例 2: 移动股票到不同分组
|
||
|
||
```bash
|
||
# 1. 搜索股票
|
||
curl "http://localhost:8000/api/watchlist/search?keyword=宁德"
|
||
|
||
# 假设找到 item_id 是 3
|
||
|
||
# 2. 移动到观察池（假设 group_id 是 2）
|
||
curl -X POST http://localhost:8000/api/watchlist/stocks/3/move \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"target_group_id":2}'
|
||
```
|
||
|
||
### 示例 3: 添加备注并排序
|
||
|
||
```bash
|
||
# 1. 给股票添加备注
|
||
curl -X PUT http://localhost:8000/api/watchlist/stocks/3/note \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"note":"关注突破1000元压力位"}'
|
||
|
||
# 2. 重新排序（把最重要的放前面）
|
||
curl -X POST http://localhost:8000/api/watchlist/stocks/reorder \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"item_ids":[3,1,5,2,4]}'
|
||
```
|
||
|
||
---
|
||
|
||
## 初始化
|
||
|
||
### 首次使用
|
||
|
||
```bash
|
||
cd backend
|
||
source .venv/bin/activate
|
||
python cli.py init
|
||
```
|
||
|
||
这会自动创建 4 个默认分组：
|
||
1. **核心自选** (红色) - 重点关注的核心股票
|
||
2. **观察池** (蓝色) - 待观察的潜力股
|
||
3. **持仓股** (绿色) - 当前持仓的股票
|
||
4. **概念股** (紫色) - 热门概念板块
|
||
|
||
---
|
||
|
||
## 数据迁移
|
||
|
||
如果你之前使用的是旧版 `watchlist.json` 文件，可以通过以下方式迁移：
|
||
|
||
```python
|
||
import json
|
||
import requests
|
||
|
||
# 读取旧数据
|
||
with open('backend/watchlist.json') as f:
|
||
old_codes = json.load(f)
|
||
|
||
# 添加到默认分组（核心自选，假设 id 是 1）
|
||
requests.post(
|
||
'http://localhost:8000/api/watchlist/groups/1/stocks/batch',
|
||
json={'codes': old_codes}
|
||
)
|
||
```
|
||
|
||
---
|
||
|
||
## 最佳实践
|
||
|
||
### 分组建议
|
||
|
||
1. **核心自选** - 重点关注、深度研究的 10-20 只股票
|
||
2. **观察池** - 符合选股条件但尚未买入的 20-50 只
|
||
3. **持仓股** - 当前实际持仓的股票
|
||
4. **概念股** - 按热点题材分类（新能源、半导体、医药等）
|
||
|
||
### 使用技巧
|
||
|
||
1. **定期清理**: 每周清理观察池中不再关注的股票
|
||
2. **备注记录**: 记录买入理由、目标价、止损位等关键信息
|
||
3. **排序管理**: 按重要性或涨跌幅排序，优先级高的放前面
|
||
4. **分组配色**: 用颜色快速识别分组性质（红=重点，蓝=观察，绿=持仓）
|
||
|
||
---
|
||
|
||
## 与其他功能集成
|
||
|
||
### 与预警系统集成
|
||
|
||
为分组内的股票批量设置预警：
|
||
|
||
```bash
|
||
# 1. 获取分组内股票
|
||
curl http://localhost:8000/api/watchlist/groups/1/stocks?with_quotes=false
|
||
|
||
# 2. 为每只股票设置预警
|
||
for code in codes:
|
||
curl -X POST http://localhost:8000/api/alerts \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"code":"'$code'","kind":"price_above","threshold":100}'
|
||
```
|
||
|
||
### 与回测系统集成
|
||
|
||
批量回测分组内的股票：
|
||
|
||
```bash
|
||
# 获取分组内股票列表，逐个回测
|
||
curl http://localhost:8000/api/watchlist/groups/1/stocks?with_quotes=false
|
||
|
||
for code in codes:
|
||
curl "http://localhost:8000/api/backtest?symbol=$code&fast=5&slow=20"
|
||
done
|
||
```
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
### Q: 可以创建多少个分组？
|
||
A: 没有硬性限制，但建议控制在 10 个以内，便于管理。
|
||
|
||
### Q: 一只股票可以在多个分组中吗？
|
||
A: 可以。同一只股票可以添加到多个分组，互不影响。
|
||
|
||
### Q: 删除分组会删除股票的历史数据吗？
|
||
A: 不会。只删除分组和分组关联关系，不影响股票的行情、交易等数据。
|
||
|
||
### Q: 如何快速找到某只股票在哪些分组？
|
||
A: 使用跨分组搜索接口：`/api/watchlist/search?keyword=股票名称或代码`
|
||
|
||
### Q: 分组排序和股票排序如何保存？
|
||
A: 调用对应的 reorder 接口后立即保存到数据库，重启服务不会丢失。
|
||
|
||
---
|
||
|
||
## 技术实现
|
||
|
||
### 核心模块
|
||
- `backend/watchlist_manager.py` - 分组管理核心逻辑
|
||
- `backend/models.py` - 数据模型（WatchlistGroup、WatchlistItem）
|
||
- `backend/main.py` - API 接口定义
|
||
|
||
### 数据库索引
|
||
- `group_id` - 加速分组查询
|
||
- `code` - 加速股票代码查询
|
||
- `(group_id, code)` - 唯一约束，防止重复添加
|
||
|
||
---
|
||
|
||
**实现完成时间**: 2024年
|
||
**功能状态**: ✅ 已完成并测试
|