文档更新
This commit is contained in:
parent
f55113069c
commit
9caeae7928
186
README.md
186
README.md
@ -4,15 +4,16 @@
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
**跨境外汇投资组合追踪系统 | Cross-Border Portfolio Tracker**
|
||||
|
||||
资产管理 · 交易记录 · 持仓分析 · 多币种支持
|
||||
资产管理 · 交易记录 · 持仓分析 · 多币种支持 · 实时汇率
|
||||
|
||||
[功能介绍](#功能特性) · [技术栈](#技术栈) · [快速开始](#快速开始) · [项目结构](#项目结构) · [数据库设计](#数据库设计)
|
||||
[](#快速部署)
|
||||
|
||||
</div>
|
||||
|
||||
@ -24,40 +25,50 @@ Omniledger 是一款专业的**跨境外汇投资组合追踪应用**，帮助
|
||||
|
||||
### 核心优势
|
||||
|
||||
- **多资产类型支持** - 股票、加密货币、现金全覆盖
|
||||
- **多币种管理** - 支持不同货币的交易和换算
|
||||
- **高精度计算** - 采用 Big.js 确保金融计算精度
|
||||
- **实时持仓计算** - 自动聚合交易记录生成持仓报告
|
||||
| 特性 | 说明 |
|
||||
|------|------|
|
||||
| **多资产类型** | 股票、加密货币、现金全覆盖 |
|
||||
| **多币种管理** | 支持 USD/HKD/CNY/JPY 等多币种交易和换算 |
|
||||
| **高精度计算** | 采用 Big.js 确保金融计算精度（36位精度，18位小数）|
|
||||
| **实时持仓** | 自动聚合交易记录生成持仓报告 |
|
||||
| **历史走势** | 每日快照记录，净值曲线可视化 |
|
||||
| **主题切换** | 浅色/深色模式，流畅过渡动画 |
|
||||
|
||||
---
|
||||
|
||||
## 功能特性
|
||||
|
||||
### 资产管理
|
||||
- 添加/查看资产（支持 STOCK/CRYPTO/CASH 三种类型）
|
||||
- 统一的资产符号体系，防止重复
|
||||
- 资产基础货币设置
|
||||
### 仪表盘
|
||||
|
||||
- 总资产概览（人民币计价）
|
||||
- 持仓盈亏与总盈亏实时计算
|
||||
- 净值走势图表（Recharts 实现）
|
||||
- 资产分布饼图
|
||||
|
||||
### 持仓明细
|
||||
|
||||
- 支持展开/收起每项资产的流水明细
|
||||
- 显示：现价、市值、持仓量、摊薄成本、平均成本
|
||||
- 浮动盈亏与累计盈亏（金额 + 百分比）
|
||||
- 一键导出 CSV
|
||||
|
||||
### 交易记录
|
||||
- 支持多种交易类型：买入(BUY)、卖出(SELL)、分红(DIVIDEND)、空投(AIRDROP)、手续费(FEE)
|
||||
- 高精度数值存储（36位精度，18位小数）
|
||||
- 交易手续费精确记录
|
||||
- 实时汇率支持
|
||||
|
||||
### 持仓总览
|
||||
- 实时持仓计算
|
||||
- 自动聚合同资产交易
|
||||
- 持仓卡片直观展示
|
||||
- 支持交易类型：买入(BUY)、卖出(SELL)、分红(DIVIDEND)、空投(AIRDROP)、手续费(FEE)
|
||||
- 高精度数值存储
|
||||
- 支持修改和删除交易
|
||||
|
||||
### 交易历史
|
||||
- 完整的交易流水账
|
||||
- 按执行时间排序
|
||||
- 交易详情一览无余
|
||||
### 资产管理
|
||||
|
||||
### 主题切换
|
||||
- 浅色/深色模式
|
||||
- 系统主题自动检测
|
||||
- 流畅的过渡动画
|
||||
- 添加/查看资产（STOCK/CRYPTO/CASH 三种类型）
|
||||
- 统一的资产符号体系
|
||||
- 批量导入历史价格
|
||||
|
||||
### 历史数据
|
||||
|
||||
- 自动记录每日组合快照
|
||||
- 重构历史走势功能
|
||||
- 支持导入历史价格数据
|
||||
|
||||
---
|
||||
|
||||
@ -69,12 +80,14 @@ Omniledger 是一款专业的**跨境外汇投资组合追踪应用**，帮助
|
||||
|------|------|------|
|
||||
| Next.js | 16.2.4 | React 框架 |
|
||||
| React | 19.2.4 | UI 库 |
|
||||
| TypeScript | 5.3.3 | 类型安全 |
|
||||
| TypeScript | 5.x | 类型安全 |
|
||||
| Tailwind CSS | 3.4.17 | 样式框架 |
|
||||
| shadcn/ui | - | UI 组件库 |
|
||||
| Radix UI | - | UI 组件底层 |
|
||||
| React Hook Form | 7.74.0 | 表单处理 |
|
||||
| Zod | 4.3.6 | 数据验证 |
|
||||
| Recharts | 3.8.1 | 图表库 |
|
||||
| Lucide React | 1.11.0 | 图标库 |
|
||||
| Sonner | 2.0.7 | Toast 提示 |
|
||||
|
||||
### 后端
|
||||
|
||||
@ -106,7 +119,7 @@ cd stock-portfolio_byQwen3.6
|
||||
npm install
|
||||
|
||||
# 配置环境变量
|
||||
cp .env.local.example .env.local
|
||||
cp .env.example .env.local
|
||||
# 编辑 .env.local，配置数据库连接
|
||||
|
||||
# 数据库初始化
|
||||
@ -133,6 +146,28 @@ npm run dev
|
||||
|
||||
---
|
||||
|
||||
## 快速部署
|
||||
|
||||
### Docker Compose
|
||||
|
||||
```bash
|
||||
# 构建并启动
|
||||
docker-compose up -d
|
||||
|
||||
# 查看日志
|
||||
docker-compose logs -f
|
||||
```
|
||||
|
||||
访问 [http://localhost:8080](http://localhost:8080)
|
||||
|
||||
### 环境变量
|
||||
|
||||
```env
|
||||
DATABASE_URL=postgresql://user:password@localhost:5432/omniledger
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 项目结构
|
||||
|
||||
```
|
||||
@ -149,17 +184,25 @@ npm run dev
|
||||
│ ├── actions/ # Server Actions
|
||||
│ │ ├── asset.ts # 资产操作
|
||||
│ │ ├── transaction.ts # 交易操作
|
||||
│ │ └── portfolio.ts # 持仓计算
|
||||
│ │ ├── portfolio.ts # 持仓计算
|
||||
│ │ ├── snapshots.ts # 组合快照
|
||||
│ │ ├── exchange.ts # 汇率
|
||||
│ │ └── market.ts # 市场数据
|
||||
│ ├── components/
|
||||
│ │ ├── assets/ # 资产组件
|
||||
│ │ ├── transactions/ # 交易组件
|
||||
│ │ └── ui/ # UI 基础组件
|
||||
│ ├── db/ # 数据库层
|
||||
│ │ ├── dashboard/ # 仪表盘组件
|
||||
│ │ │ ├── allocation-chart.tsx
|
||||
│ │ │ └── net-worth-chart.tsx
|
||||
│ │ ├── assets/ # 资产相关组件
|
||||
│ │ ├── transactions/ # 交易相关组件
|
||||
│ │ └── ui/ # shadcn/ui 组件
|
||||
│ ├── db/
|
||||
│ │ ├── index.ts # Drizzle 客户端
|
||||
│ │ └── schema.ts # 数据库 Schema
|
||||
│ └── lib/
|
||||
│ └── formatters.ts # 格式化工具
|
||||
├── drizzle/ # 数据库迁移
|
||||
│ ├── formatters.ts # 格式化工具
|
||||
│ └── utils.ts # 通用工具
|
||||
├── drizzle/ # 数据库迁移文件
|
||||
├── scripts/ # 辅助脚本
|
||||
├── public/ # 静态资源
|
||||
└── package.json
|
||||
```
|
||||
@ -170,13 +213,24 @@ npm run dev
|
||||
|
||||
### 表结构
|
||||
|
||||
#### users 用户表
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | UUID | 主键 |
|
||||
| username | VARCHAR(50) | 用户名（唯一） |
|
||||
| password_hash | VARCHAR(255) | 密码哈希 |
|
||||
| created_at | TIMESTAMP | 创建时间 |
|
||||
|
||||
#### assets 资产表
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | UUID | 主键 |
|
||||
| symbol | VARCHAR(20) | 资产符号（唯一） |
|
||||
| name | VARCHAR(100) | 资产名称 |
|
||||
| type | ENUM | STOCK/CRYPTO/CASH |
|
||||
| exchange | VARCHAR(10) | 交易所（默认 US）|
|
||||
| baseCurrency | VARCHAR(10) | 基础货币 |
|
||||
| latestPrice | NUMERIC(36,18) | 最新价格 |
|
||||
| created_at | TIMESTAMP | 创建时间 |
|
||||
|
||||
#### transactions 交易表
|
||||
@ -185,7 +239,7 @@ npm run dev
|
||||
| id | UUID | 主键 |
|
||||
| assetId | UUID | 关联资产 |
|
||||
| txType | ENUM | BUY/SELL/DIVIDEND/AIRDROP/FEE |
|
||||
| quantity | NUMERIC(36,18) | 数量（高精度） |
|
||||
| quantity | NUMERIC(36,18) | 数量 |
|
||||
| price | NUMERIC(36,18) | 价格 |
|
||||
| fee | NUMERIC(36,18) | 手续费 |
|
||||
| txCurrency | VARCHAR(10) | 交易货币 |
|
||||
@ -193,24 +247,66 @@ npm run dev
|
||||
| executedAt | TIMESTAMP | 执行时间 |
|
||||
| createdAt | TIMESTAMP | 创建时间 |
|
||||
|
||||
#### exchange_rates 汇率表
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | UUID | 主键 |
|
||||
| fromCurrency | VARCHAR(10) | 源货币 |
|
||||
| toCurrency | VARCHAR(10) | 目标货币 |
|
||||
| rate | NUMERIC(20,8) | 汇率 |
|
||||
| updatedAt | TIMESTAMP | 更新时间 |
|
||||
|
||||
#### portfolio_snapshots 组合快照表
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | UUID | 主键 |
|
||||
| date | DATE | 日期（唯一）|
|
||||
| totalValueCny | NUMERIC(36,18) | 总值（CNY）|
|
||||
| totalCostCny | NUMERIC(36,18) | 总成本（CNY）|
|
||||
| createdAt | TIMESTAMP | 创建时间 |
|
||||
| updatedAt | TIMESTAMP | 更新时间 |
|
||||
|
||||
#### asset_prices_history 资产价格历史
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | UUID | 主键 |
|
||||
| assetId | UUID | 关联资产 |
|
||||
| price | NUMERIC(36,18) | 价格 |
|
||||
| date | DATE | 日期 |
|
||||
| updateTime | TIMESTAMP | 更新时间 |
|
||||
|
||||
#### exchange_rates_history 汇率历史
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | UUID | 主键 |
|
||||
| fromCurrency | VARCHAR(10) | 源货币 |
|
||||
| toCurrency | VARCHAR(10) | 目标货币 |
|
||||
| rate | NUMERIC(20,8) | 汇率 |
|
||||
| fetchTime | TIMESTAMP | 抓取时间 |
|
||||
|
||||
---
|
||||
|
||||
## 开发指南
|
||||
|
||||
### 添加新资产
|
||||
|
||||
1. 进入「资产」页面
|
||||
1. 进入「资产管理」页面
|
||||
2. 点击「添加资产」按钮
|
||||
3. 填写资产信息（符号、类型、基础货币）
|
||||
3. 填写资产信息（符号、名称、类型、基础货币）
|
||||
4. 提交保存
|
||||
|
||||
### 记录交易
|
||||
|
||||
1. 进入「持仓总览」或「交易历史」页面
|
||||
2. 点击「记录交易」按钮
|
||||
3. 选择资产和交易类型
|
||||
4. 填写交易详情（数量、价格、手续费等）
|
||||
5. 提交保存
|
||||
1. 在「持仓总览」中点击资产的「添加」按钮
|
||||
2. 选择交易类型（买入/卖出/分红/空投/手续费）
|
||||
3. 填写交易详情（数量、价格、手续费、日期等）
|
||||
4. 提交保存
|
||||
|
||||
### 导入历史价格
|
||||
|
||||
1. 在「持仓总览」中点击资产的「导入价格」按钮
|
||||
2. 从 Excel 复制粘贴数据，格式：`日期, 价格`（每行一条）
|
||||
3. 点击开始导入
|
||||
|
||||
### 主题切换
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user