stock_cursor_v0/功能实现/1_自选股分组管理使用说明.md

自选股分组管理使用说明

功能概述

自选股分组管理功能允许用户将股票分类到不同的分组中，实现更精细的股票管理。

核心特性

✅ 多分组支持 - 预设 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. 获取所有分组

GET /api/watchlist/groups

响应示例:

{
  "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. 创建新分组

POST /api/watchlist/groups
Content-Type: application/json

{
  "name": "科技股",
  "description": "科技板块相关",
  "color": "purple"
}

可选颜色: red, blue, green, purple, orange, yellow

3. 更新分组信息

PUT /api/watchlist/groups/{group_id}
Content-Type: application/json

{
  "name": "新名称",
  "description": "新描述",
  "color": "green"
}

4. 删除分组

DELETE /api/watchlist/groups/{group_id}

注意: 默认分组不能删除，删除分组会同时删除分组内的所有股票。

5. 重新排序分组

POST /api/watchlist/groups/reorder
Content-Type: application/json

{
  "group_ids": [2, 1, 3, 4]
}

6. 获取分组内的股票

GET /api/watchlist/groups/{group_id}/stocks?with_quotes=true

参数:

• with_quotes (bool): 是否包含实时行情，默认 true

响应示例:

{
  "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. 添加股票到分组

POST /api/watchlist/groups/{group_id}/stocks
Content-Type: application/json

{
  "code": "600519",
  "note": "优质白马股"
}

8. 批量添加股票

POST /api/watchlist/groups/{group_id}/stocks/batch
Content-Type: application/json

{
  "codes": ["600519", "300750", "002594"]
}

响应示例:

{
  "ok": true,
  "added": 3,
  "skipped": 0
}

9. 从分组中移除股票

DELETE /api/watchlist/stocks/{item_id}

10. 移动股票到另一个分组

POST /api/watchlist/stocks/{item_id}/move
Content-Type: application/json

{
  "target_group_id": 2
}

11. 更新股票备注

PUT /api/watchlist/stocks/{item_id}/note
Content-Type: application/json

{
  "note": "待突破压力位"
}

12. 重新排序股票

POST /api/watchlist/stocks/reorder
Content-Type: application/json

{
  "item_ids": [3, 1, 2, 5, 4]
}

13. 跨分组搜索股票

GET /api/watchlist/search?keyword=茅台

响应示例:

{
  "ok": true,
  "results": [
    {
      "id": 1,
      "code": "600519",
      "name": "贵州茅台",
      "group_id": 1,
      "group_name": "核心自选",
      "group_color": "red",
      "note": "长期持有"
    }
  ]
}

---

使用示例

示例 1: 创建分组并添加股票

# 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: 移动股票到不同分组

# 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: 添加备注并排序

# 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]}'

---

初始化

首次使用

cd backend
source .venv/bin/activate
python cli.py init

这会自动创建 4 个默认分组：

1. 核心自选 (红色) - 重点关注的核心股票
2. 观察池 (蓝色) - 待观察的潜力股
3. 持仓股 (绿色) - 当前持仓的股票
4. 概念股 (紫色) - 热门概念板块

---

数据迁移

如果你之前使用的是旧版 watchlist.json 文件，可以通过以下方式迁移：

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. 分组配色: 用颜色快速识别分组性质（红=重点，蓝=观察，绿=持仓）

---

与其他功能集成

与预警系统集成

为分组内的股票批量设置预警：

# 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}'

与回测系统集成

批量回测分组内的股票：

# 获取分组内股票列表，逐个回测
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年
功能状态: ✅ 已完成并测试