仓位管理系统 - 产品设计文档

版本: v1.0 创建日期: 2026-03-10 作者: 小老弟 状态: 设计阶段

1. 产品概述

1.1 产品定位

面向个人投资者的轻量级仓位管理和分析工具，支持A股和港股，提供仓位追踪、自动更新和一键分析功能。

1.2 目标用户

  • 散户投资者
  • 需要管理多个持仓的个人投资者
  • 希望获得技术面分析建议的用户

1.3 核心价值

  • 自动化仓位管理，减少手动计算
  • 每日自动更新，及时掌握持仓价值
  • 一键分析，快速获得投资建议
  • Web界面，随时随地访问

2. 功能需求

2.1 核心功能

2.1.1 仓位管理

  • 功能描述: 管理用户的持仓股票和仓位信息
  • 用户操作:
    • 添加/编辑/删除持仓
    • 手动输入股票代码、持仓金额、目标仓位占比
    • 自动计算实际仓位占比
  • 数据字段:
    • 股票代码（A股/港股/ETF）
    • 股票名称（自动获取）
    • 持仓金额（手动输入）
    • 目标仓位占比（手动输入）
    • 实际仓位占比（自动计算）
    • 最新价格（自动获取）
    • 持仓数量（自动计算）
    • 当日涨跌幅（自动获取）

2.1.2 自动更新

  • 功能描述: 每天晚上定时任务自动更新持仓数据
  • 更新内容:
    • 获取最新价格
    • 计算当前持仓金额（价格 × 数量）
    • 计算实际仓位占比
    • 计算总资产和收益
  • 执行时间: 每天收盘后（例如 23:00）
  • 执行方式: Cron 定时任务

2.1.3 一键分析

  • 功能描述: 一键分析所有持仓或单个股票
  • 分析内容:
    • 技术面分析（趋势、RSI、MACD、布林带）
    • 综合评级
    • 操作建议（买入/卖出/持有）
    • 支撑阻力位
  • 展示方式: 汇总报告 + 单股详情

2.2 辅助功能

2.2.1 数据导入导出

  • 支持导出持仓数据为 CSV
  • 支持导入 CSV 批量添加持仓

2.2.2 历史记录

  • 记录每日持仓快照
  • 支持查看历史持仓变化
  • 支持查看历史收益曲线

2.2.3 告警通知

  • 单日涨跌幅超过阈值告警
  • 仓位偏离目标告警
  • 可选：发送到微信/邮件

3. 界面设计

3.1 页面结构

3.1.1 首页（持仓总览）

┌─────────────────────────────────────────────┐
│  仓位管理系统              [一键分析] [刷新] │
├─────────────────────────────────────────────┤
│                                             │
│  总资产: ¥100,000        收益: +5.2%      │
│  今日收益: +¥1,200       持仓数量: 5      │
│                                             │
├─────────────────────────────────────────────┤
│  持仓列表                                   │
│  ┌───────────────────────────────────────┐ │
│  │ 代码  名称      金额    占比   操作  │ │
│  ├───────────────────────────────────────┤ │
│  │ AAPL  苹果     20000   20%   [分析]│ │
│  │ TSLA  特斯拉   15000   15%   [分析]│ │
│  │ 600519 茅台    30000   30%   [分析]│ │
│  │ ...                                  │ │
│  └───────────────────────────────────────┘ │
│                                             │
│  [添加持仓] [批量导入] [导出数据]            │
└─────────────────────────────────────────────┘

3.1.2 添加/编辑持仓页面

┌─────────────────────────────────────────────┐
│  添加/编辑持仓              [保存] [取消] │
├─────────────────────────────────────────────┤
│                                             │
│  股票代码: [__________] [搜索]             │
│  股票名称: 腾讯控股 (自动获取)            │
│  市场选择: [A股▼] [港股▼] [美股▼]         │
│                                             │
│  持仓金额: ¥[______]                       │
│  目标仓位占比: [__]%                        │
│                                             │
│  [自动查询价格] 最新价格: ¥320.00           │
│  [自动计算数量] 持仓数量: 312              │
│                                             │
│  备注: [________________________]            │
│                                             │
└─────────────────────────────────────────────┘

3.1.3 分析报告页面

┌─────────────────────────────────────────────┐
│  分析报告: AAPL             [返回] [导出]  │
├─────────────────────────────────────────────┤
│                                             │
│  当前价格: $185.23     涨跌: +1.5%        │
│  持仓数量: 100         持仓金额: $18,523  │
│                                             │
│  【技术分析】                               │
│  趋势: 上涨 (中)    评级: 买入 ✅         │
│  RSI: 65.00 (偏强)   MACD: 金叉 🎯         │
│                                             │
│  【操作建议】                               │
│  💡 建议持有或逢低加仓                      │
│  ⚠️  短期阻力位: $190                      │
│  ✅ 短期支撑位: $180                       │
│                                             │
│  【图表】                                   │
│  [K线图 + MA20/MA50]                        │
│                                             │
└─────────────────────────────────────────────┘

3.2 响应式设计

  • 支持桌面端（1920x1080+）
  • 支持平板端（768x1024）
  • 支持移动端（375x667）

4. 技术架构

4.1 整体架构

┌─────────────┐
│   前端      │  (HTML/CSS/JavaScript)
│  Web UI     │
└──────┬──────┘
       │ HTTP/REST API
┌──────▼──────────────┐
│    后端 API         │  (Python Flask/FastAPI)
│  - 持仓管理         │
│  - 数据获取         │
│  - 技术分析         │
└──────┬──────────────┘
       │
┌──────▼──────────────┐
│   数据层           │
│  - SQLite         │  (持仓数据)
│  - yfinance      │  (股票数据)
│  - pandas-ta     │  (技术分析)
└───────────────────┘

┌───────────────────┐
│  定时任务        │  (Cron)
│  每日自动更新    │
└───────────────────┘

4.2 技术选型

4.2.1 前端

  • 框架: 原生 HTML/CSS/JavaScript（轻量级）或 Vue.js（更好的交互）
  • UI库: Bootstrap 5 或 Tailwind CSS
  • 图表: Chart.js 或 Apache ECharts
  • 理由: 简单、快速、易维护

4.2.2 后端

  • 框架: Flask 3.0（轻量级）或 FastAPI（现代化）
  • 理由:
    • Flask: 成熟稳定，文档丰富
    • FastAPI: 性能更好，自动生成API文档

4.2.3 数据存储

  • 主数据库: SQLite
    • 理由: 轻量级，无需额外安装，适合个人使用
    • 文件: /var/www/position-management/positions.db
  • 缓存: 可选，用于缓存股票数据

4.2.4 股票数据

  • A股:
    • 选项1: yfinance（A股代码：600519.SS）
    • 选项2: akshare（纯A股数据，更稳定）
    • 选项3: tushare（需要token，更专业）
  • 港股:
    • 选项1: yfinance（港股代码：0700.HK）
    • 选项2: yfinance（指数代码：HSTECH.HK）

推荐: 使用 yfinance 统一获取 A股和港股数据

4.2.5 技术分析

  • 库: pandas-ta
  • 已安装: ✅ 已安装完成

4.2.6 定时任务

  • 方式: Cron
  • 执行: 每天收盘后（例如 23:00）
  • 脚本: /root/.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-positions.py

4.3 目录结构

/var/www/position-management/
├── app/                      # 后端应用
│   ├── __init__.py
│   ├── main.py              # Flask/FastAPI 主入口
│   ├── models.py            # 数据模型
│   ├── routes.py            # 路由
│   ├── services/
│   │   ├── stock_service.py # 股票数据服务
│   │   ├── analysis.py      # 技术分析服务
│   │   └── position.py      # 仓位管理服务
│   └── utils/
│       ├── database.py       # 数据库工具
│       └── cache.py         # 缓存工具
├── templates/               # 前端模板（如果用服务端渲染）
│   ├── index.html
│   ├── add_position.html
│   └── analysis.html
├── static/                  # 静态文件
│   ├── css/
│   ├── js/
│   └── img/
├── data/
│   └── positions.db        # SQLite 数据库
├── scripts/
│   └── update_positions.py  # 定时任务脚本
└── requirements.txt         # Python 依赖

5. 数据库设计

5.1 数据表

5.1.1 positions（持仓表）

CREATE TABLE positions (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    symbol TEXT NOT NULL,              -- 股票代码
    name TEXT,                         -- 股票名称
    market TEXT NOT NULL,               -- 市场：A股/港股/美股
    target_percent REAL,                -- 目标仓位占比
    holding_amount REAL,                -- 持仓金额
    holding_quantity REAL,              -- 持仓数量
    current_price REAL,                 -- 最新价格
    actual_percent REAL,                -- 实际仓位占比
    daily_change REAL,                 -- 当日涨跌幅
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

5.1.2 position_history（持仓历史表）

CREATE TABLE position_history (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    position_id INTEGER,
    total_amount REAL,                 -- 总资产
    total_change REAL,                  -- 总收益
    record_date DATE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (position_id) REFERENCES positions(id)
);

5.2 索引

  • positions: symbol (唯一索引)
  • position_history: position_id, record_date

6. API 设计

6.1 持仓管理 API

�6.1.1 获取所有持仓

GET /api/positions
Response: [
  {
    "id": 1,
    "symbol": "600519.SS",
    "name": "贵州茅台",
    "market": "A股",
    "target_percent": 30.0,
    "holding_amount": 30000.0,
    "holding_quantity": 10.5,
    "current_price": 2857.14,
    "actual_percent": 30.0,
    "daily_change": 1.2
  }
]

6.1.2 获取单个持仓

GET /api/positions/:id
Response: { ... }

6.1.3 添加持仓

POST /api/positions
Request: {
  "symbol": "600519.SS",
  "market": "A股",
  "target_percent": 30.0,
  "holding_amount": 30000.0
}
Response: { "id": 1, "status": "success" }

6.1.4 更新持仓

PUT /api/positions/:id
Request: { ... }
Response: { "status": "success" }

6.1.5 删除持仓

DELETE /api/positions/:id
Response: { "status": "success" }

6.1.6 手动更新所有持仓

POST /api/positions/update
Response: {
  "total_amount": 100000.0,
  "total_change": 5.2,
  "updated_count": 5,
  "status": "success"
}

6.2 股票数据 API

6.2.1 搜索股票

GET /api/stocks/search?query=腾讯
Response: [
  {
    "symbol": "0700.HK",
    "name": "腾讯控股",
    "market": "港股",
    "current_price": 320.00
  }
]

6.2.2 获取股票详情

GET /api/stocks/:symbol
Response: {
  "symbol": "0700.HK",
  "name": "腾讯控股",
  "current_price": 320.00,
  "daily_change": 1.5,
  "52w_high": 350.00,
  "52w_low": 250.00
}

6.3 分析 API

6.3.1 分析单个股票

POST /api/analyze/:symbol
Response: {
  "symbol": "0700.HK",
  "name": "腾讯控股",
  "current_price": 320.00,
  "trend": "上涨",
  "strength": "中",
  "rsi": 65.0,
  "rsi_signal": "偏强",
  "macd": 15.85,
  "macd_signal": "金叉",
  "bollinger": "偏强",
  "support": 300.0,
  "resistance": 340.0,
  "score": 75,
  "rating": "买入",
  "advice": "建议持有或逢低加仓"
}

6.3.2 分析所有持仓

POST /api/analyze/all
Response: [
  {
    "symbol": "0700.HK",
    "analysis": { ... }
  },
  ...
]

6.4 统计 API

6.4.1 获取总览

GET /api/summary
Response: {
  "total_amount": 100000.0,
  "total_change": 5200.0,
  "total_change_percent": 5.2,
  "today_change": 1200.0,
  "today_change_percent": 1.2,
  "position_count": 5
}

7. 可行性分析

7.1 技术可行性 ✅

组件可行性说明
前端Web UI✅成熟技术，实现简单
后端API✅Flask/FastAPI 成熟稳定
数据存储✅SQLite 轻量级，适合个人使用
A股数据⚠️yfinance 有一定限制，可考虑 akshare
港股数据✅yfinance 支持良好
技术分析✅pandas-ta 已安装，功能完善
定时任务✅Cron 成熟稳定
公网访问✅你已有公网IP和域名

7.2 风险与挑战

7.2.1 数据源风险

风险:

  • yfinance API 可能不稳定或被限制
  • A股数据可能有延迟
  • 数据准确性需要验证

缓解措施:

  • 多数据源备份（yfinance + akshare）
  • 实现数据缓存，减少API调用
  • 增加数据验证机制

7.2.2 计算准确性

风险:

  • 持仓数量计算依赖价格，可能有误差
  • 分红、拆股等事件会影响计算

缓解措施:

  • 支持手动修正持仓数量
  • 记录交易日志，可追溯

7.2.3 安全性

风险:

  • 公网访问可能被攻击
  • 敏感数据泄露

缓解措施:

  • 添加基本认证（用户名/密码）
  • HTTPS 加密
  • 定期备份数据
  • 限制访问IP（可选）

7.3 成本分析

项目成本说明
开发成本低预计 1-2 周完成 v1.0
服务器成本无使用现有 VPS
数据成本无使用免费数据源（yfinance）
维护成本低主要是 Bug 修复和功能迭代

8. 实施建议

8.1 开发阶段规划

Phase 1: MVP（最小可行产品）- 1周

目标: 实现核心功能

  • ✅ 持仓管理（添加/编辑/删除/查看）
  • ✅ 手动更新持仓数据
  • ✅ 简单的总览页面
  • ✅ SQLite 数据库
  • ✅ 基础后端 API

不做:

  • ❌ 自动更新定时任务
  • ❌ 技术分析
  • ❌ 历史记录
  • ❌ 告警通知

Phase 2: 自动更新 - 2-3天

目标: 实现每日自动更新

  • ✅ Cron 定时任务
  • ✅ 自动获取最新价格
  • ✅ 自动计算持仓金额和占比
  • ✅ 记录每日快照

Phase 3: 技术分析 - 2-3天

目标: 集成技术分析功能

  • ✅ 一键分析 API
  • ✅ 分析报告页面
  • ✅ 重用现有分析脚本

Phase 4: 优化和增强 - 1周

目标: 提升用户体验

  • ✅ 响应式设计
  • ✅ 图表可视化
  • ✅ 历史记录查看
  • ✅ 导入导出
  • ✅ 告警通知（可选）

8.2 技术选型建议

8.2.1 前端

推荐: Vue.js 3 + Element Plus

  • 理由:
    • Vue.js 学习成本低，文档丰富
    • Element Plus 提供现成的 UI 组件
    • 响应式支持好
    • 适合快速开发

备选: 原生 HTML + Bootstrap

  • 理由: 更轻量，无依赖
  • 缺点: 开发效率较低，代码复用性差

8.2.2 后端

推荐: FastAPI

  • 理由:
    • 性能好
    • 自动生成 API 文档
    • 类型提示支持
    • 现代化

备选: Flask

  • 理由: 更成熟，社区更活跃
  • 缺点: 性能相对较低

8.2.3 数据源

A股推荐: akshare

  • 理由:
    • 纯A股数据源，更稳定
    • 无需额外配置
    • 实时性较好

港股推荐: yfinance

  • 理由:
    • 支持良好
    • 数据准确

8.3 部署建议

8.3.1 目录

建议部署到: /var/www/position-management

8.3.2 Web服务器

使用 Nginx 反向代理（你已有 1Panel，可配置）

8.3.3 域名

使用现有域名，子域名: portfolio.yourdomain.com 或 stock.yourdomain.com

8.3.4 访问控制

  • 方案1: HTTP 基本认证（简单）
  • 方案2: OAuth2（复杂，不推荐）
  • 方案3: IP 白名单（最简单）

9. 未来迭代方向

9.1 v1.1（短期）

  • A股使用 akshare 数据源
  • 添加图表可视化（收益曲线）
  • 支持多个投资组合
  • 添加用户认证

9.2 v1.2（中期）

  • 添加基本面分析
  • 添加新闻资讯聚合
  • 添加社交功能（分享分析）
  • 移动端 App

9.3 v2.0（长期）

  • 添加回测功能
  • 添加策略构建器
  • 添加 AI 助手
  • 多市场支持（美股、日股等）

10. 注意事项

10.1 数据准确性与合规

  • 免责声明: 必须在页面显著位置添加免责声明
    • “本系统提供的分析仅供参考，不构成投资建议”
    • “投资有风险，入市需谨慎”
  • 数据来源: 明确标注数据来源
  • 数据延迟: 说明数据更新频率和可能的延迟

10.2 安全性

  • 认证: 实现基本的用户认证
  • 加密: 使用 HTTPS（Let’s Encrypt 免费证书）
  • 备份: 定期备份数据库
  • 日志: 记录操作日志

10.3 可维护性

  • 文档: 保持代码和文档同步
  • 版本控制: 使用 Git 管理代码
  • 测试: 编写单元测试
  • 日志: 实现完善的日志系统

11. 附录

11.1 参考项目

  • 股票分析脚本: /root/.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-analysis.py
  • 港股分析脚本: /root/.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-hk-tech-internet-v2.py

11.2 依赖清单

# Python 依赖
flask==3.0.0
fastapi==0.104.0
uvicorn==0.24.0
sqlalchemy==2.0.23
yfinance==0.2.32
pandas-ta==0.3.14
pandas==2.1.3
numpy==1.26.2

# 可选
akshare==1.12.60

11.3 时间表

阶段时间里程碑
Phase 1: MVP1周核心功能上线
Phase 2: 自动更新2-3天定时任务运行
Phase 3: 技术分析2-3天分析功能上线
Phase 4: 优化增强1周v1.0 正式发布

文档版本: v1.0 最后更新: 2026-03-10 下次更新: Phase 1 完成后更新