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。