529 lines
12 KiB
Markdown
529 lines
12 KiB
Markdown
# 持仓成本可视化增强使用说明
|
||
|
||
## 功能概述
|
||
|
||
持仓成本可视化增强功能提供精确的交易成本计算、持仓成本线标注、盈亏分布分析等功能，帮助用户更直观地了解持仓成本和盈亏情况。
|
||
|
||
### 核心特性
|
||
|
||
✅ **精确成本计算** - 印花税、佣金、过户费精确计算（符合A股规则）
|
||
✅ **成本线标注** - K线图上标注持仓成本线
|
||
✅ **成本历史追踪** - 记录每次买入/卖出后的成本变化
|
||
✅ **盈亏分布图** - 可视化展示盈利/亏损持仓分布
|
||
✅ **交易成本预估** - 下单前估算实际成本
|
||
✅ **成本明细拆解** - 详细展示每笔交易的成本构成
|
||
|
||
---
|
||
|
||
## 交易成本规则（A股）
|
||
|
||
### 成本构成
|
||
|
||
| 费用类型 | 费率 | 适用范围 | 说明 |
|
||
|---------|------|---------|------|
|
||
| **印花税** | 0.1% | 仅卖出 | 固定费率 |
|
||
| **佣金** | 0.03% | 买入+卖出 | 最低5元 |
|
||
| **过户费** | 0.001% | 买入+卖出 | 仅沪市 |
|
||
|
||
### 计算示例
|
||
|
||
**买入示例**（沪市）:
|
||
```
|
||
股票代码: 600519（贵州茅台）
|
||
成交价格: 1680元
|
||
成交数量: 100股
|
||
|
||
成交金额 = 1680 × 100 = 168,000元
|
||
佣金 = 168,000 × 0.0003 = 50.4元
|
||
过户费 = 168,000 × 0.00001 = 1.68元
|
||
印花税 = 0元（买入无印花税）
|
||
|
||
总成本 = 168,000 + 50.4 + 1.68 = 168,052.08元
|
||
成本率 = 0.031%
|
||
```
|
||
|
||
**卖出示例**（沪市）:
|
||
```
|
||
成交金额 = 168,000元
|
||
佣金 = 50.4元
|
||
过户费 = 1.68元
|
||
印花税 = 168,000 × 0.001 = 168元
|
||
|
||
总成本 = 220.08元
|
||
实际到账 = 168,000 - 220.08 = 167,779.92元
|
||
成本率 = 0.131%
|
||
```
|
||
|
||
---
|
||
|
||
## API 接口
|
||
|
||
### 1. 获取持仓成本线
|
||
|
||
```bash
|
||
GET /api/portfolio/cost_line/{code}
|
||
```
|
||
|
||
**用途**: K线图上标注成本线
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"code": "600519",
|
||
"name": "贵州茅台",
|
||
"current_position": {
|
||
"qty": 100,
|
||
"avg_cost": 1680.5,
|
||
"total_cost": 168050.0,
|
||
"current_price": 1720.0,
|
||
"market_value": 172000.0,
|
||
"unrealized_pnl": 3950.0,
|
||
"unrealized_pct": 2.35,
|
||
"trades_count": 2
|
||
},
|
||
"cost_history": [
|
||
{
|
||
"date": "2024-01-15",
|
||
"cost": 1650.0,
|
||
"qty": 100,
|
||
"action": "买入",
|
||
"trade_price": 1650.0,
|
||
"trade_qty": 100
|
||
},
|
||
{
|
||
"date": "2024-02-10",
|
||
"cost": 1680.5,
|
||
"qty": 100,
|
||
"action": "补仓",
|
||
"trade_price": 1710.0,
|
||
"trade_qty": 50
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
**前端使用**（ECharts 标注成本线）:
|
||
```javascript
|
||
// 在 K 线图上添加成本线
|
||
const costLineData = await fetch(`/api/portfolio/cost_line/600519`).then(r => r.json());
|
||
|
||
if (costLineData.ok && costLineData.current_position) {
|
||
const avgCost = costLineData.current_position.avg_cost;
|
||
|
||
option.series.push({
|
||
type: 'line',
|
||
name: '持仓成本',
|
||
data: Array(dates.length).fill(avgCost),
|
||
lineStyle: { color: '#FFA500', width: 2, type: 'dashed' },
|
||
z: 10
|
||
});
|
||
}
|
||
```
|
||
|
||
### 2. 获取持仓成本分布
|
||
|
||
```bash
|
||
GET /api/portfolio/cost_distribution
|
||
```
|
||
|
||
**用途**: 盈亏分布可视化
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"profitable": [
|
||
{
|
||
"code": "600519",
|
||
"name": "贵州茅台",
|
||
"qty": 100,
|
||
"avg_cost": 1680.5,
|
||
"current_price": 1720.0,
|
||
"market_value": 172000.0,
|
||
"cost_value": 168050.0,
|
||
"unrealized": 3950.0,
|
||
"unrealized_pct": 2.35
|
||
}
|
||
],
|
||
"unprofitable": [
|
||
{
|
||
"code": "300750",
|
||
"name": "宁德时代",
|
||
"qty": 50,
|
||
"avg_cost": 220.0,
|
||
"current_price": 210.0,
|
||
"market_value": 10500.0,
|
||
"cost_value": 11000.0,
|
||
"unrealized": -500.0,
|
||
"unrealized_pct": -4.55
|
||
}
|
||
],
|
||
"breakeven": [],
|
||
"summary": {
|
||
"total_positions": 2,
|
||
"profitable_count": 1,
|
||
"unprofitable_count": 1,
|
||
"breakeven_count": 0,
|
||
"win_rate": 50.0
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3. 估算交易成本
|
||
|
||
```bash
|
||
POST /api/portfolio/estimate_cost
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"code": "600519",
|
||
"price": 1680.0,
|
||
"qty": 100,
|
||
"side": "buy"
|
||
}
|
||
```
|
||
|
||
**用途**: 下单前预估实际成本
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"code": "600519",
|
||
"price": 1680.0,
|
||
"qty": 100,
|
||
"side": "buy",
|
||
"cost_detail": {
|
||
"amount": 168000.0,
|
||
"commission": 50.4,
|
||
"stamp_tax": 0.0,
|
||
"transfer_fee": 1.68,
|
||
"total_cost": 52.08,
|
||
"cost_rate": 0.031
|
||
},
|
||
"net_amount": 168052.08,
|
||
"message": "买入需支付: 168052.08 元（含交易成本 52.08 元）"
|
||
}
|
||
```
|
||
|
||
### 4. 获取持仓成本明细
|
||
|
||
```bash
|
||
GET /api/portfolio/cost_breakdown/{code}
|
||
```
|
||
|
||
**用途**: 查看累计交易成本拆解
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"code": "600519",
|
||
"name": "贵州茅台",
|
||
"total_cost": 168052.08,
|
||
"purchase_amount": 168000.0,
|
||
"commission": 50.4,
|
||
"stamp_tax": 0.0,
|
||
"transfer_fee": 1.68,
|
||
"cost_rate": 0.031,
|
||
"trades": [
|
||
{
|
||
"date": "2024-01-15",
|
||
"price": 1680.0,
|
||
"qty": 100,
|
||
"amount": 168000.0,
|
||
"cost_detail": {
|
||
"amount": 168000.0,
|
||
"commission": 50.4,
|
||
"stamp_tax": 0.0,
|
||
"transfer_fee": 1.68,
|
||
"total_cost": 52.08,
|
||
"cost_rate": 0.031
|
||
}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 使用场景
|
||
|
||
### 场景 1: K线图上标注成本线
|
||
|
||
**前端实现示例**:
|
||
```javascript
|
||
// 获取K线数据
|
||
const klineData = await fetch(`/api/kline?symbol=600519&days=60`).then(r => r.json());
|
||
|
||
// 获取成本线数据
|
||
const costData = await fetch(`/api/portfolio/cost_line/600519`).then(r => r.json());
|
||
|
||
if (costData.ok && costData.current_position) {
|
||
const avgCost = costData.current_position.avg_cost;
|
||
const currentPrice = costData.current_position.current_price;
|
||
|
||
// ECharts 配置
|
||
const option = {
|
||
title: {
|
||
text: `${costData.name} - 成本: ${avgCost} 当前: ${currentPrice}`
|
||
},
|
||
series: [
|
||
{
|
||
type: 'candlestick',
|
||
data: klineData.ohlc
|
||
},
|
||
{
|
||
type: 'line',
|
||
name: '持仓成本',
|
||
data: Array(klineData.dates.length).fill(avgCost),
|
||
lineStyle: {
|
||
color: '#FFA500',
|
||
width: 2,
|
||
type: 'dashed'
|
||
},
|
||
markLine: {
|
||
data: [{ yAxis: avgCost, name: `成本 ${avgCost}` }]
|
||
}
|
||
}
|
||
]
|
||
};
|
||
}
|
||
```
|
||
|
||
### 场景 2: 盈亏分布饼图
|
||
|
||
```javascript
|
||
const distData = await fetch('/api/portfolio/cost_distribution').then(r => r.json());
|
||
|
||
if (distData.ok) {
|
||
const option = {
|
||
title: { text: '持仓盈亏分布' },
|
||
series: [{
|
||
type: 'pie',
|
||
data: [
|
||
{
|
||
value: distData.profitable.length,
|
||
name: `盈利 ${distData.profitable.length}`,
|
||
itemStyle: { color: '#26a69a' }
|
||
},
|
||
{
|
||
value: distData.unprofitable.length,
|
||
name: `亏损 ${distData.unprofitable.length}`,
|
||
itemStyle: { color: '#ef5350' }
|
||
}
|
||
]
|
||
}]
|
||
};
|
||
}
|
||
```
|
||
|
||
### 场景 3: 下单前成本计算
|
||
|
||
```javascript
|
||
// 用户输入买入价格和数量
|
||
const buyPrice = 1680;
|
||
const buyQty = 100;
|
||
|
||
const estimate = await fetch('/api/portfolio/estimate_cost', {
|
||
method: 'POST',
|
||
headers: { 'Content-Type': 'application/json' },
|
||
body: JSON.stringify({
|
||
code: '600519',
|
||
price: buyPrice,
|
||
qty: buyQty,
|
||
side: 'buy'
|
||
})
|
||
}).then(r => r.json());
|
||
|
||
if (estimate.ok) {
|
||
alert(`${estimate.message}\n\n成本明细:\n` +
|
||
`佣金: ${estimate.cost_detail.commission}元\n` +
|
||
`过户费: ${estimate.cost_detail.transfer_fee}元\n` +
|
||
`印花税: ${estimate.cost_detail.stamp_tax}元`);
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 完整示例
|
||
|
||
### Python 脚本示例
|
||
|
||
```python
|
||
import requests
|
||
import json
|
||
|
||
BASE_URL = "http://localhost:8000"
|
||
|
||
# 1. 查看持仓成本线
|
||
def show_cost_line(code):
|
||
resp = requests.get(f"{BASE_URL}/api/portfolio/cost_line/{code}")
|
||
data = resp.json()
|
||
|
||
if data["ok"]:
|
||
pos = data["current_position"]
|
||
print(f"\n{data['name']} ({code})")
|
||
print(f"持仓数量: {pos['qty']}股")
|
||
print(f"平均成本: {pos['avg_cost']}元")
|
||
print(f"当前价格: {pos['current_price']}元")
|
||
print(f"浮动盈亏: {pos['unrealized_pnl']}元 ({pos['unrealized_pct']}%)")
|
||
|
||
print("\n成本变化历史:")
|
||
for h in data["cost_history"]:
|
||
print(f"{h['date']} {h['action']}: 成本={h['cost']}元, 持仓={h['qty']}股")
|
||
|
||
# 2. 查看盈亏分布
|
||
def show_distribution():
|
||
resp = requests.get(f"{BASE_URL}/api/portfolio/cost_distribution")
|
||
data = resp.json()
|
||
|
||
if data["ok"]:
|
||
print(f"\n持仓总数: {data['summary']['total_positions']}")
|
||
print(f"盈利: {data['summary']['profitable_count']}")
|
||
print(f"亏损: {data['summary']['unprofitable_count']}")
|
||
print(f"胜率: {data['summary']['win_rate']}%")
|
||
|
||
print("\n盈利股票:")
|
||
for s in data["profitable"]:
|
||
print(f"{s['name']}: +{s['unrealized']}元 (+{s['unrealized_pct']}%)")
|
||
|
||
print("\n亏损股票:")
|
||
for s in data["unprofitable"]:
|
||
print(f"{s['name']}: {s['unrealized']}元 ({s['unrealized_pct']}%)")
|
||
|
||
# 3. 估算交易成本
|
||
def estimate_cost(code, price, qty, side="buy"):
|
||
resp = requests.post(f"{BASE_URL}/api/portfolio/estimate_cost", json={
|
||
"code": code,
|
||
"price": price,
|
||
"qty": qty,
|
||
"side": side
|
||
})
|
||
data = resp.json()
|
||
|
||
if data["ok"]:
|
||
print(f"\n{data['message']}")
|
||
cost = data["cost_detail"]
|
||
print(f"\n成本明细:")
|
||
print(f" 成交金额: {cost['amount']}元")
|
||
print(f" 佣金: {cost['commission']}元")
|
||
print(f" 印花税: {cost['stamp_tax']}元")
|
||
print(f" 过户费: {cost['transfer_fee']}元")
|
||
print(f" 总成本: {cost['total_cost']}元 ({cost['cost_rate']}%)")
|
||
|
||
# 运行示例
|
||
if __name__ == "__main__":
|
||
show_cost_line("600519")
|
||
show_distribution()
|
||
estimate_cost("600519", 1680, 100, "buy")
|
||
```
|
||
|
||
---
|
||
|
||
## 最佳实践
|
||
|
||
### 1. 成本线使用建议
|
||
|
||
- **买入参考**: 当价格接近成本线时考虑加仓
|
||
- **止损参考**: 设置成本线下方一定比例作为止损位
|
||
- **目标价参考**: 成本线上方设置分批止盈位
|
||
|
||
### 2. 成本计算注意事项
|
||
|
||
- **沪深区别**: 深市（000、002、300开头）无过户费
|
||
- **最低佣金**: 单笔佣金不足5元按5元收取
|
||
- **印花税**: 只在卖出时收取，买入无需支付
|
||
|
||
### 3. 盈亏分析建议
|
||
|
||
- **定期检查**: 每周查看盈亏分布，调整持仓结构
|
||
- **及时止损**: 亏损超过-8%的持仓需要重新评估
|
||
- **落袋为安**: 盈利超过+20%考虑分批止盈
|
||
|
||
---
|
||
|
||
## 与其他功能集成
|
||
|
||
### 与自选股分组集成
|
||
|
||
```bash
|
||
# 将持仓股添加到"持仓股"分组
|
||
curl -X POST http://localhost:8000/api/watchlist/groups/3/stocks/batch \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"codes":["600519","300750"]}'
|
||
```
|
||
|
||
### 与预警系统集成
|
||
|
||
```bash
|
||
# 为持仓股设置成本价预警（跌破成本-5%）
|
||
AVG_COST=1680
|
||
STOP_LOSS=$(echo "$AVG_COST * 0.95" | bc)
|
||
|
||
curl -X POST http://localhost:8000/api/alerts \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"code":"600519","kind":"price_below","threshold":'$STOP_LOSS',"note":"跌破成本-5%"}'
|
||
```
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
### Q: 为什么计算的成本和实际有差异？
|
||
A: 可能原因：
|
||
1. 交易记录未完整录入
|
||
2. 券商佣金费率不同（本系统默认万三）
|
||
3. 分红、配股等特殊情况未计入
|
||
|
||
### Q: 如何修改佣金费率？
|
||
A: 编辑 `backend/position_cost.py` 中的 `COST_CONFIG` 配置：
|
||
```python
|
||
COST_CONFIG = {
|
||
"commission_rate": 0.0003, # 改为实际佣金率
|
||
"commission_min": 5.0, # 改为实际最低佣金
|
||
}
|
||
```
|
||
|
||
### Q: 成本线为什么不显示？
|
||
A: 检查：
|
||
1. 该股票是否有交易记录
|
||
2. 当前是否有持仓（已清仓则无成本线）
|
||
3. 接口返回是否成功
|
||
|
||
### Q: 补仓后成本如何计算？
|
||
A: 使用加权平均法：
|
||
```
|
||
新成本 = (原持仓成本 + 补仓金额 + 补仓费用) / 新持仓数量
|
||
```
|
||
|
||
---
|
||
|
||
## 技术实现
|
||
|
||
### 核心模块
|
||
- `backend/position_cost.py` - 成本计算核心逻辑
|
||
- `backend/portfolio.py` - 原有持仓管理
|
||
- `backend/main.py` - API 接口定义
|
||
|
||
### 算法说明
|
||
|
||
**移动加权平均成本法**:
|
||
```python
|
||
if side == "buy":
|
||
total_cost += price * qty + fee
|
||
total_qty += qty
|
||
avg_cost = total_cost / total_qty
|
||
else: # sell
|
||
avg_cost = total_cost / total_qty
|
||
pnl = (price - avg_cost) * qty - fee
|
||
total_cost -= avg_cost * qty
|
||
total_qty -= qty
|
||
```
|
||
|
||
---
|
||
|
||
**实现完成时间**: 2024年
|
||
**功能状态**: ✅ 已完成并测试
|