# 自选股分组管理使用说明

## 功能概述

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

### 核心特性

✅ **多分组支持** - 预设 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年  
**功能状态**: ✅ 已完成并测试