KennethCheng/stock-portfolio_byQwen3.6
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

文档更新

Browse Source
This commit is contained in:
kennethcheng 2026-05-03 04:41:46 +08:00
parent f55113069c
commit 9caeae7928
1 changed files with 155 additions and 59 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

214
README.md
View File

@ -4,15 +4,16 @@
![Next.js](https://img.shields.io/badge/Next.js-16.2.4-black?style=flat-square&logo=next.js) ![Next.js](https://img.shields.io/badge/Next.js-16.2.4-black?style=flat-square&logo=next.js)
![React](https://img.shields.io/badge/React-19.2.4-61DAFB?style=flat-square&logo=react) ![React](https://img.shields.io/badge/React-19.2.4-61DAFB?style=flat-square&logo=react)
![TypeScript](https://img.shields.io/badge/TypeScript-5.3.3-3178C6?style=flat-square&logo=typescript) ![TypeScript](https://img.shields.io/badge/TypeScript-5.7-3178C6?style=flat-square&logo=typescript)
![PostgreSQL](https://img.shields.io/badge/PostgreSQL-16.0-336791?style=flat-square&logo=postgresql) ![PostgreSQL](https://img.shields.io/badge/PostgreSQL-16.0-336791?style=flat-square&logo=postgresql)
![Tailwind CSS](https://img.shields.io/badge/Tailwind_CSS-3.4.17-06B6D4?style=flat-square&logo=tailwindcss) ![Tailwind CSS](https://img.shields.io/badge/Tailwind_CSS-3.4.17-06B6D4?style=flat-square&logo=tailwindcss)
![Drizzle ORM](https://img.shields.io/badge/Drizzle_ORM-0.45.2-f5f5f5?style=flat-square&logo=drizzle)
**跨境外汇投资组合追踪系统 | Cross-Border Portfolio Tracker** **跨境外汇投资组合追踪系统 | Cross-Border Portfolio Tracker**
资产管理 · 交易记录 · 持仓分析 · 多币种支持 资产管理 · 交易记录 · 持仓分析 · 多币种支持 · 实时汇率
[功能介绍](#功能特性) · [技术栈](#技术栈) · [快速开始](#快速开始) · [项目结构](#项目结构) · [数据库设计](#数据库设计) [![Docker](https://img.shields.io/badge/Docker-Ready-2496ED?logo=docker&style=flat-square)](#快速部署)
</div> </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 框架 | | Next.js | 16.2.4 | React 框架 |
| React | 19.2.4 | UI 库 | | React | 19.2.4 | UI 库 |
| TypeScript | 5.3.3 | 类型安全 | | TypeScript | 5.x | 类型安全 |
| Tailwind CSS | 3.4.17 | 样式框架 | | Tailwind CSS | 3.4.17 | 样式框架 |
| shadcn/ui | - | UI 组件库 | | Radix UI | - | UI 组件底层 |
| React Hook Form | 7.74.0 | 表单处理 | | React Hook Form | 7.74.0 | 表单处理 |
| Zod | 4.3.6 | 数据验证 | | Zod | 4.3.6 | 数据验证 |
| Recharts | 3.8.1 | 图表库 |
| Lucide React | 1.11.0 | 图标库 | | Lucide React | 1.11.0 | 图标库 |
| Sonner | 2.0.7 | Toast 提示 |
### 后端 ### 后端
@ -106,7 +119,7 @@ cd stock-portfolio_byQwen3.6
npm install npm install
# 配置环境变量 # 配置环境变量
cp .env.local.example .env.local cp .env.example .env.local
# 编辑 .env.local，配置数据库连接 # 编辑 .env.local，配置数据库连接
# 数据库初始化 # 数据库初始化
@ -133,34 +146,64 @@ 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
```
---
## 项目结构 ## 项目结构
``` ```
├── app/ # Next.js App Router ├── app/ # Next.js App Router
│ ├── dashboard/ # 仪表盘页面 │ ├── dashboard/ # 仪表盘页面
│ │ ├── page.tsx # 持仓总览 │ │ ├── page.tsx # 持仓总览
│ │ ├── assets/page.tsx # 资产管理 │ │ ├── assets/page.tsx # 资产管理
│ │ ├── transactions/page.tsx# 交易历史 │ │ ├── transactions/page.tsx # 交易历史
│ │ └── layout.tsx # 仪表盘布局 │ │ └── layout.tsx # 仪表盘布局
│ ├── layout.tsx # 根布局 │ ├── layout.tsx # 根布局
│ ├── page.tsx # 根页面（重定向） │ ├── page.tsx # 根页面（重定向）
│ └── globals.css # 全局样式 │ └── globals.css # 全局样式
├── src/ ├── src/
│ ├── actions/ # Server Actions │ ├── actions/ # Server Actions
│ │ ├── asset.ts # 资产操作 │ │ ├── asset.ts # 资产操作
│ │ ├── transaction.ts # 交易操作 │ │ ├── transaction.ts # 交易操作
│ │ └── portfolio.ts # 持仓计算 │ │ ├── portfolio.ts # 持仓计算
│ │ ├── snapshots.ts # 组合快照
│ │ ├── exchange.ts # 汇率
│ │ └── market.ts # 市场数据
│ ├── components/ │ ├── components/
│ │ ├── assets/ # 资产组件 │ │ ├── dashboard/ # 仪表盘组件
│ │ ├── transactions/ # 交易组件 │ │ │ ├── allocation-chart.tsx
│ │ └── ui/ # UI 基础组件 │ │ │ └── net-worth-chart.tsx
│ ├── db/ # 数据库层 │ │ ├── assets/ # 资产相关组件
│ │ ├── index.ts # Drizzle 客户端 │ │ ├── transactions/ # 交易相关组件
│ │ └── schema.ts # 数据库 Schema │ │ └── ui/ # shadcn/ui 组件
│ ├── db/
│ │ ├── index.ts # Drizzle 客户端
│ │ └── schema.ts # 数据库 Schema
│ └── lib/ │ └── lib/
│ └── formatters.ts # 格式化工具 │ ├── formatters.ts # 格式化工具
├── drizzle/ # 数据库迁移 │ └── utils.ts # 通用工具
├── public/ # 静态资源 ├── drizzle/ # 数据库迁移文件
├── scripts/ # 辅助脚本
├── public/ # 静态资源
└── package.json └── package.json
``` ```
@ -170,13 +213,24 @@ npm run dev
### 表结构 ### 表结构
#### users 用户表
| 字段 | 类型 | 说明 |
|------|------|------|
| id | UUID | 主键 |
| username | VARCHAR(50) | 用户名（唯一） |
| password_hash | VARCHAR(255) | 密码哈希 |
| created_at | TIMESTAMP | 创建时间 |
#### assets 资产表 #### assets 资产表
| 字段 | 类型 | 说明 | | 字段 | 类型 | 说明 |
|------|------|------| |------|------|------|
| id | UUID | 主键 | | id | UUID | 主键 |
| symbol | VARCHAR(20) | 资产符号（唯一） | | symbol | VARCHAR(20) | 资产符号（唯一） |
| name | VARCHAR(100) | 资产名称 |
| type | ENUM | STOCK/CRYPTO/CASH | | type | ENUM | STOCK/CRYPTO/CASH |
| exchange | VARCHAR(10) | 交易所（默认 US）|
| baseCurrency | VARCHAR(10) | 基础货币 | | baseCurrency | VARCHAR(10) | 基础货币 |
| latestPrice | NUMERIC(36,18) | 最新价格 |
| created_at | TIMESTAMP | 创建时间 | | created_at | TIMESTAMP | 创建时间 |
#### transactions 交易表 #### transactions 交易表
@ -185,7 +239,7 @@ npm run dev
| id | UUID | 主键 | | id | UUID | 主键 |
| assetId | UUID | 关联资产 | | assetId | UUID | 关联资产 |
| txType | ENUM | BUY/SELL/DIVIDEND/AIRDROP/FEE | | txType | ENUM | BUY/SELL/DIVIDEND/AIRDROP/FEE |
| quantity | NUMERIC(36,18) | 数量（高精度） | | quantity | NUMERIC(36,18) | 数量 |
| price | NUMERIC(36,18) | 价格 | | price | NUMERIC(36,18) | 价格 |
| fee | NUMERIC(36,18) | 手续费 | | fee | NUMERIC(36,18) | 手续费 |
| txCurrency | VARCHAR(10) | 交易货币 | | txCurrency | VARCHAR(10) | 交易货币 |
@ -193,24 +247,66 @@ npm run dev
| executedAt | TIMESTAMP | 执行时间 | | executedAt | TIMESTAMP | 执行时间 |
| createdAt | 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. 点击「添加资产」按钮 2. 点击「添加资产」按钮
3. 填写资产信息（符号、类型、基础货币） 3. 填写资产信息（符号、名称、类型、基础货币）
4. 提交保存 4. 提交保存
### 记录交易 ### 记录交易
1. 进入「持仓总览」或「交易历史」页面 1. 在「持仓总览」中点击资产的「添加」按钮
2. 点击「记录交易」按钮 2. 选择交易类型（买入/卖出/分红/空投/手续费）
3. 选择资产和交易类型 3. 填写交易详情（数量、价格、手续费、日期等）
4. 填写交易详情（数量、价格、手续费等） 4. 提交保存
5. 提交保存
### 导入历史价格
1. 在「持仓总览」中点击资产的「导入价格」按钮
2. 从 Excel 复制粘贴数据，格式：`日期, 价格`（每行一条）
3. 点击开始导入
### 主题切换 ### 主题切换
@ -220,4 +316,4 @@ npm run dev
## 许可证 ## 许可证
MIT License MIT License