文档更新

2026-05-03 04:41:46 +08:00 · 2026-05-03 04:41:46 +08:00 · 9caeae7928
commit 9caeae7928
parent f55113069c
1 changed files with 155 additions and 59 deletions
--- a/README.md
+++ b/README.md
@ -4,15 +4,16 @@

 ![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)
-![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)
 ![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**

-资产管理 · 交易记录 · 持仓分析 · 多币种支持
+资产管理 · 交易记录 · 持仓分析 · 多币种支持 · 实时汇率

-[功能介绍](#功能特性) · [技术栈](#技术栈) · [快速开始](#快速开始) · [项目结构](#项目结构) · [数据库设计](#数据库设计)
+[![Docker](https://img.shields.io/badge/Docker-Ready-2496ED?logo=docker&style=flat-square)](#快速部署)

 </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,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
-│   ├── dashboard/                # 仪表盘页面
-│   │   ├── page.tsx             # 持仓总览
-│   │   ├── assets/page.tsx      # 资产管理
-│   │   ├── transactions/page.tsx# 交易历史
-│   │   └── layout.tsx           # 仪表盘布局
-│   ├── layout.tsx               # 根布局
-│   ├── page.tsx                 # 根页面（重定向）
-│   └── globals.css              # 全局样式
+│   ├── dashboard/               # 仪表盘页面
+│   │   ├── page.tsx            # 持仓总览
+│   │   ├── assets/page.tsx     # 资产管理
+│   │   ├── transactions/page.tsx # 交易历史
+│   │   └── layout.tsx          # 仪表盘布局
+│   ├── layout.tsx              # 根布局
+│   ├── page.tsx                # 根页面（重定向）
+│   └── globals.css             # 全局样式
 ├── src/
 │   ├── actions/                 # Server Actions
-│   │   ├── asset.ts             # 资产操作
-│   │   ├── transaction.ts       # 交易操作
-│   │   └── portfolio.ts         # 持仓计算
+│   │   ├── asset.ts            # 资产操作
+│   │   ├── transaction.ts      # 交易操作
+│   │   ├── portfolio.ts        # 持仓计算
+│   │   ├── snapshots.ts        # 组合快照
+│   │   ├── exchange.ts         # 汇率
+│   │   └── market.ts           # 市场数据
 │   ├── components/
-│   │   ├── assets/              # 资产组件
-│   │   ├── transactions/        # 交易组件
-│   │   └── ui/                 # UI 基础组件
-│   ├── db/                      # 数据库层
-│   │   ├── index.ts             # Drizzle 客户端
-│   │   └── schema.ts            # 数据库 Schema
+│   │   ├── dashboard/          # 仪表盘组件
+│   │   │   ├── allocation-chart.tsx
+│   │   │   └── net-worth-chart.tsx
+│   │   ├── assets/             # 资产相关组件
+│   │   ├── transactions/       # 交易相关组件
+│   │   └── ui/                 # shadcn/ui 组件
+│   ├── db/
+│   │   ├── index.ts            # Drizzle 客户端
+│   │   └── schema.ts           # 数据库 Schema
 │   └── lib/
-│       └── formatters.ts        # 格式化工具
-├── drizzle/                      # 数据库迁移
-├── public/                       # 静态资源
+│       ├── 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. 点击开始导入

 ### 主题切换