Controtto

🚀 📊 自托管投资损益追踪工具 - Controtto

Controtto 是一款采用 Go 语言开发的自托管 P&L（利润与损失）跟踪工具，借助 HTMX 实现，无需 JavaScript。它以 SQLite 文件存储交易记录，具备多种实用的计算功能，能帮助用户高效管理投资损益。

🚀 快速开始

Controtto 是一个强大的自托管投资损益追踪工具，你可以通过以下步骤快速上手：

• 查看实时演示：访问 demo.contre.io 查看实时演示，数据库每小时重置一次。
• 进行安装与配置：按照后续的安装指南进行操作，完成依赖安装和环境配置。

✨ 主要特性

• 丰富的计算功能：支持平均买入价、当前资产价值、交易历史记录、导入/导出交易数据（参考示例文件）以及利润与损失计算等功能。
• 多 API 支持：使用四种主要 API 获取资产价格，包括 Binance、BingX、Alpha Vantage 和 Tiingo。
  • Binance：公共 API，无需令牌。
  • BingX：公共 API，无需令牌。
  • Alpha Vantage：提供股票数据，免费但有速率限制。需获取令牌并设置 CONTROTTO_AVANTAGE_TOKEN 环境变量。
  • Tiingo：提供股票、加密货币和外汇数据。需创建账户并获取令牌后设置 CONTROTTO_TIINGO_TOKEN 环境变量。

📦 安装指南

安装依赖项与配置环境

# 安装依赖项
go mod tidy

# 配置环境文件
mv .env.example .env

# 读取环境变量
. <(cat .env | grep -v -e '^$' | grep -v "#" | awk '{}')

构建与运行

go run ./cmd/main.go # 或构建可执行文件：go build ./cmd/main.go

开发环境配置

# 安装 Air 工具
go install github.com/cosmtrek/air@latest

# 使用 Air 启动应用
air -c air.toml

# 访问 http://localhost:3000 查看结果

使用 Podman 运行容器

我们提供了 Docker 镜像，镜像地址为 hub.docker.com/r/contre95/controtto。如需使用，请将 podman 替换为 docker。

mkdir data

# 启动容器
podman container run --rm -p 8000:8000 -v $(pwd)/data:/data contre95/controtto

💻 使用示例

基础用法

你可以通过以下步骤使用 Controtto 进行基本的投资损益追踪：

1. 完成安装与配置。
2. 启动应用后，访问相应的地址（如开发环境下的 http://localhost:3000 ）。
3. 按照界面提示进行交易数据的导入、查看交易历史记录、计算利润与损失等操作。

高级用法

如果你需要使用特定的 API 获取资产价格，需要进行相应的配置：

• Alpha Vantage：获取令牌并设置 CONTROTTO_AVANTAGE_TOKEN 环境变量。
• Tiingo：创建账户并获取令牌后设置 CONTROTTO_TIINGO_TOKEN 环境变量。

📚 详细文档

测试部分

go test -cover ./...

# 预期结果示例：
# ?       controtto/cmd   [无测试文件]
# ?       controtto/src/app/managing      [无测试文件]
# ?       controtto/src/domain/pnl        [无测试文件]
# ?       controtto/src/gateways/markets  [无测试文件]
# ?       controtto/src/gateways/sqlite   [无测试文件]
# ?       controtto/src/presenters        [无测试文件]
# ok      controtto/src/app/querying      0.003s  coverage: 40.7% of statements

待办事项（TODO）

• 增加更多测试用例。
• 添加日志记录和监控功能。
• 实现账户管理功能，追踪总净值。
• 移除所有 CSS，并使用自定义 style.css 和 Tailwind CDN。