kennethcheng
6ceb4a8e9b
- 🔧 账户名称优化：改为港股账户、美股账户、A股账户、加密货币账户 - ✨ 成交总额自动计算：根据数量 × 价格自动计算 - 🗑️ 删除持仓功能：支持通过卖出全部来删除持仓 - 🎨 Select 组件显示优化：修复了下拉框显示问题 - 📝 代码注释中文化
402 lines
11 KiB
Markdown
402 lines
11 KiB
Markdown
# 个人投资持仓管理系统
|
||
|
||
> 现代化、全面化的个人投资组合管理平台，支持多市场（美股、A股、港股、加密货币）统一管理。
|
||
|
||
|
||
|
||
|
||
|
||
|
||
---
|
||
|
||
## 功能特性
|
||
|
||
### 核心功能
|
||
|
||
| 功能 | 描述 |
|
||
|------|------|
|
||
| **多市场支持** | 美股 (US)、A股 (CN)、港股 (HK)、加密货币 (CRYPTO) |
|
||
| **资金流水管理** | 入金、出金记录 |
|
||
| **交易流水管理** | 买入、卖出、分红、利息、费用 |
|
||
| **持仓统计** | 实时市值、平均成本、浮动盈亏 |
|
||
| **多币种转换** | 自动将各币种资产折算为 USD |
|
||
| **资产配置图** | 饼图展示各市场占比 |
|
||
| **数据导入导出** | CSV 格式导入导出 |
|
||
|
||
### 交易类型
|
||
|
||
| 类型 | 说明 |
|
||
|------|------|
|
||
| `BUY` | 买入 |
|
||
| `SELL` | 卖出 |
|
||
| `DEPOSIT` | 入金 |
|
||
| `WITHDRAW` | 出金 |
|
||
| `DIVIDEND` | 分红 |
|
||
| `INTEREST` | 利息 |
|
||
| `FEE` | 费用/手续费 |
|
||
|
||
---
|
||
|
||
## 技术架构
|
||
|
||
### 技术栈
|
||
|
||
```
|
||
前端：
|
||
├── Next.js 16 (App Router)
|
||
├── React 19
|
||
├── TypeScript 5
|
||
├── Tailwind CSS 4
|
||
├── shadcn/ui (组件库)
|
||
├── Recharts (图表)
|
||
└── Sonner (Toast 通知)
|
||
|
||
后端：
|
||
├── Next.js API Routes
|
||
├── Prisma ORM
|
||
└── PostgreSQL 16
|
||
|
||
实时数据：
|
||
└── Alpha Vantage API
|
||
```
|
||
|
||
### 数据库模型
|
||
|
||
```
|
||
┌─────────────┐ ┌─────────────┐
|
||
│ User │───1:N─│ Account │
|
||
└─────────────┘ └─────────────┘
|
||
│
|
||
│ 1:N
|
||
┌─────────────┼─────────────┐
|
||
│ │ │
|
||
▼ ▼ ▼
|
||
┌───────────┐ ┌───────────┐ ┌───────────┐
|
||
│Position │ │Transaction│ │ExchangeRate│
|
||
└───────────┘ └───────────┘ └───────────┘
|
||
│
|
||
▼
|
||
┌───────────┐
|
||
│ Security │
|
||
└───────────┘
|
||
```
|
||
|
||
### 表结构说明
|
||
|
||
| 表名 | 说明 |
|
||
|------|------|
|
||
| `User` | 用户表（预留多用户扩展） |
|
||
| `Account` | 账户表（按市场类型分组） |
|
||
| `Security` | 证券参考表（代码、名称、精度） |
|
||
| `Transaction` | 交易流水表 |
|
||
| `Position` | 持仓表（查询优化） |
|
||
| `ExchangeRate` | 汇率参考表 |
|
||
|
||
### 字段精度设计
|
||
|
||
| 字段类型 | 精度 | 说明 |
|
||
|----------|------|------|
|
||
| 价格/金额 | `Decimal(20,4)` | 避免浮点精度丢失 |
|
||
| 数量 | `Decimal(20,8)` | 加密货币支持8位小数 |
|
||
| 汇率 | `Decimal(20,8)` | 高精度汇率转换 |
|
||
|
||
---
|
||
|
||
## API 接口
|
||
|
||
### 账户管理
|
||
|
||
| 接口 | 方法 | 描述 |
|
||
|------|------|------|
|
||
| `/api/accounts` | GET | 获取账户列表 |
|
||
| `/api/accounts` | POST | 创建账户 |
|
||
|
||
### 交易管理
|
||
|
||
| 接口 | 方法 | 描述 |
|
||
|------|------|------|
|
||
| `/api/transactions` | GET | 获取交易流水（支持分页） |
|
||
| `/api/transactions` | POST | 记录交易（自动更新持仓/余额） |
|
||
|
||
### 持仓管理
|
||
|
||
| 接口 | 方法 | 描述 |
|
||
|------|------|------|
|
||
| `/api/positions` | GET | 获取持仓列表 |
|
||
|
||
### 仪表盘
|
||
|
||
| 接口 | 方法 | 描述 |
|
||
|------|------|------|
|
||
| `/api/dashboard/stats` | GET | 资产统计概览 |
|
||
| `/api/dashboard/analytics` | GET | 持仓分析（含实时价格） |
|
||
|
||
### 数据导入
|
||
|
||
| 接口 | 方法 | 描述 |
|
||
|------|------|------|
|
||
| `/api/import/transactions` | POST | 批量导入交易记录 |
|
||
|
||
### 证券管理
|
||
|
||
| 接口 | 方法 | 描述 |
|
||
|------|------|------|
|
||
| `/api/securities` | GET | 搜索证券 |
|
||
| `/api/securities` | POST | 添加证券 |
|
||
|
||
### 汇率管理
|
||
|
||
| 接口 | 方法 | 描述 |
|
||
|------|------|------|
|
||
| `/api/exchange-rates` | GET | 获取汇率列表 |
|
||
| `/api/exchange-rates` | POST | 更新汇率 |
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
### 环境要求
|
||
|
||
- Node.js 20+
|
||
- PostgreSQL 16+
|
||
- npm 或 yarn
|
||
|
||
### 安装步骤
|
||
|
||
```bash
|
||
# 1. 克隆项目
|
||
git clone <repository-url>
|
||
cd stock-portfolio
|
||
|
||
# 2. 安装依赖
|
||
npm install
|
||
|
||
# 3. 配置环境变量
|
||
cp .env.example .env
|
||
# 编辑 .env 填入数据库连接信息
|
||
|
||
# 4. 初始化数据库
|
||
npx prisma migrate dev --name init
|
||
npx prisma db seed
|
||
|
||
# 5. 启动开发服务器
|
||
npm run dev
|
||
```
|
||
|
||
### 环境变量
|
||
|
||
```env
|
||
# 数据库连接
|
||
DATABASE_URL="postgresql://postgres:password@localhost:5432/stock_portfolio"
|
||
|
||
# Alpha Vantage API Key（用于获取实时股价）
|
||
ALPHA_VANTAGE_API_KEY="your-api-key"
|
||
|
||
# HTTP 代理（可选，用于解决 API 访问问题）
|
||
HTTP_PROXY="http://192.168.48.171:7893"
|
||
HTTPS_PROXY="http://192.168.48.171:7893"
|
||
```
|
||
|
||
---
|
||
|
||
## 使用指南
|
||
|
||
### 添加交易记录
|
||
|
||
1. 点击右上角「**记录交易**」按钮
|
||
2. 选择账户和交易类型
|
||
3. 输入证券代码（支持搜索）
|
||
4. 填写数量、价格（成交总额自动计算）
|
||
5. 点击「**确认记录**」
|
||
6. 在确认对话框中核实信息，点击「**确认**」
|
||
|
||
### 导入批量交易
|
||
|
||
1. 点击右上角「**导入**」按钮
|
||
2. 点击「**下载模板**」获取 CSV 模板
|
||
3. 按照模板格式填写交易数据
|
||
4. 选择填写好的 CSV 文件
|
||
5. 预览导入数据（有效/错误标记）
|
||
6. 点击「**导入**」执行批量导入
|
||
|
||
### 导出数据
|
||
|
||
1. 点击右上角「**导出**」按钮
|
||
2. 自动下载持仓 CSV 文件
|
||
3. 在「交易流水」标签页也可导出交易记录
|
||
|
||
### 字段说明
|
||
|
||
#### 交易模板 CSV 格式
|
||
|
||
```csv
|
||
时间,类型,证券代码,数量,价格,金额,手续费,币种,备注
|
||
2024-01-15 10:30:00,BUY,AAPL,10,185.50,1855.00,1.00,USD,买入苹果
|
||
```
|
||
|
||
| 字段 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| 时间 | 是 | 格式：`YYYY-MM-DD HH:mm:ss` |
|
||
| 类型 | 是 | `BUY`/`SELL`/`DEPOSIT`/`WITHDRAW`/`DIVIDEND` |
|
||
| 证券代码 | 否 | 买入/卖出/分红时填写 |
|
||
| 数量 | 否 | 股票数量 |
|
||
| 价格 | 否 | 单价 |
|
||
| 金额 | 是 | 总金额 |
|
||
| 手续费 | 否 | 交易手续费 |
|
||
| 币种 | 是 | `USD`/`CNY`/`HKD`/`USDT` |
|
||
| 备注 | 否 | 任意备注信息 |
|
||
|
||
---
|
||
|
||
## 成本计算
|
||
|
||
### 平均成本法 (Average Cost)
|
||
|
||
系统采用**平均成本法**计算持仓成本：
|
||
|
||
```
|
||
新平均成本 = (现有成本 × 现有数量 + 新买入成本) / (现有数量 + 新买入数量)
|
||
```
|
||
|
||
### 示例
|
||
|
||
```
|
||
初始：买入 10 股 AAPL，价格 $150
|
||
→ 平均成本 = $150
|
||
|
||
再次：买入 10 股 AAPL，价格 $160
|
||
→ 新平均成本 = ($150×10 + $160×10) / 20 = $155
|
||
```
|
||
|
||
---
|
||
|
||
## 多币种处理
|
||
|
||
### 汇率转换
|
||
|
||
系统以 **USD** 为基准货币，将所有资产折算为 USD 进行汇总：
|
||
|
||
| 币种 | 汇率 (示例) |
|
||
|------|-------------|
|
||
| USD | 1.0 |
|
||
| CNY | 0.137 |
|
||
| HKD | 0.129 |
|
||
| USDT | 1.0 |
|
||
|
||
### 更新汇率
|
||
|
||
通过 `/api/exchange-rates` 接口或数据库直接更新汇率参考表。
|
||
|
||
---
|
||
|
||
## 界面预览
|
||
|
||
### 资产概览
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ [Logo] 投资持仓管理 [账户▼] [导入] [导出] [记录交易] │
|
||
├─────────────────────────────────────────────────────────┤
|
||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||
│ │ 总资产 │ │ 浮动盈亏 │ │ 持仓市值 │ │ 账户数量 │ │
|
||
│ │ $125,430 │ │ +$3,250 │ │ $98,200 │ │ 4 │ │
|
||
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
|
||
└─────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 持仓明细
|
||
|
||
| 证券 | 市场 | 数量 | 成本价 | 当前价 | 市值 | 盈亏 |
|
||
|------|------|------|--------|--------|------|------|
|
||
| AAPL | 美股 | 50 | $150.00 | $178.50 | $8,925 | +$1,425 (+19.0%) |
|
||
| MSFT | 美股 | 20 | $380.00 | $415.20 | $8,304 | +$704 (+9.3%) |
|
||
| BTC | 加密 | 0.5 | $60,000 | $67,500 | $33,750 | +$3,750 (+12.5%) |
|
||
|
||
---
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
stock-portfolio/
|
||
├── prisma/
|
||
│ ├── schema.prisma # 数据库模型
|
||
│ ├── seed.ts # 初始化数据
|
||
│ └── migrations/ # 数据库迁移
|
||
├── src/
|
||
│ ├── app/
|
||
│ │ ├── api/ # API 路由
|
||
│ │ │ ├── accounts/
|
||
│ │ │ ├── transactions/
|
||
│ │ │ ├── positions/
|
||
│ │ │ ├── securities/
|
||
│ │ │ ├── exchange-rates/
|
||
│ │ │ ├── dashboard/
|
||
│ │ │ └── import/
|
||
│ │ ├── page.tsx # 主页面
|
||
│ │ ├── layout.tsx # 布局
|
||
│ │ └── globals.css # 全局样式
|
||
│ ├── components/
|
||
│ │ └── ui/ # shadcn/ui 组件
|
||
│ ├── lib/
|
||
│ │ ├── api.ts # API 调用封装
|
||
│ │ ├── prisma.ts # Prisma 客户端
|
||
│ │ ├── import-export.ts # 导入导出工具
|
||
│ │ └── price-service.ts # 价格服务
|
||
│ └── types/
|
||
│ └── index.ts # 类型定义
|
||
├── .env # 环境变量
|
||
├── .env.example # 环境变量示例
|
||
├── package.json
|
||
├── tsconfig.json
|
||
├── next.config.ts
|
||
└── README.md
|
||
```
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
### Q: 实时价格如何获取？
|
||
|
||
A: 系统使用 Alpha Vantage API 获取美股实时价格。需要配置 `ALPHA_VANTAGE_API_KEY` 环境变量。
|
||
|
||
### Q: 支持哪些市场？
|
||
|
||
A: 目前支持美股 (US)、A股 (CN)、港股 (HK)、加密货币 (CRYPTO) 四个市场。
|
||
|
||
### Q: 成本计算使用什么算法？
|
||
|
||
A: 系统使用**平均成本法 (Average Cost)** 计算持仓成本。
|
||
|
||
### Q: 基准货币是什么？
|
||
|
||
A: 系统以 **USD** 为基准货币，所有资产会折算为 USD 进行汇总展示。
|
||
|
||
---
|
||
|
||
## 许可证
|
||
|
||
MIT License - 详见 [LICENSE](LICENSE) 文件
|
||
|
||
---
|
||
|
||
## 更新日志
|
||
|
||
### v1.0.1 (2026-04-12)
|
||
|
||
- 🔧 账户名称优化：改为港股账户、美股账户、A股账户、加密货币账户
|
||
- ✨ 成交总额自动计算：根据数量 × 价格自动计算
|
||
- 🗑️ 删除持仓功能：支持通过卖出全部来删除持仓
|
||
- 🎨 Select 组件显示优化：修复了下拉框显示问题
|
||
- 📝 代码注释中文化
|
||
|
||
### v1.0.0 (2026-04-12)
|
||
|
||
- ✨ 初始版本发布
|
||
- 支持多市场账户管理
|
||
- 支持交易记录（买入/卖出/入金/出金/分红）
|
||
- 支持持仓统计和盈亏计算
|
||
- 支持数据导入导出（CSV）
|
||
- 支持 Alpha Vantage 实时价格
|
||
- 响应式深色模式界面
|