asset-tracker/README.md

asset-tracker

个人资产管理系统（MVP）

MVP 范围

• 用户登录鉴权（JWT）
• 资产分类管理（分类列表/新增）
• 资产管理（新增/列表/更新/删除）
• 仪表盘汇总（总资产、分类占比、未来30天到期）
• 到期提醒（预生成 reminders + 定时扫描发送状态）

技术栈

• Go 1.22+
• Gin
• GORM + SQLite
• robfig/cron

快速启动

cd asset-tracker
go mod tidy
go run ./cmd/server

服务默认监听：http://127.0.0.1:9530

默认账号（首次启动自动创建）：

• username: admin
• password: admin123

强烈建议通过环境变量覆盖：DEFAULT_USERNAME DEFAULT_PASSWORD JWT_SECRET

鉴权流程

1. POST /api/v1/auth/login 获取 access_token（refresh_token 写入 HttpOnly Cookie）
2. 后续请求添加 Header：Authorization: Bearer <access_token>
3. access 过期后调用 POST /api/v1/auth/refresh（优先用 Cookie 刷新）

错误响应结构（统一）

{
  "code": "ASSET_INVALID_STATUS",
  "message": "status must be active or inactive",
  "details": null,
  "request_id": "d3f4a1b2c3d4e5f6"
}

所有响应都会带 X-Request-Id，便于日志排查。

关键接口

• POST /api/v1/auth/login
• POST /api/v1/auth/refresh
• POST /api/v1/categories
• GET /api/v1/categories
• POST /api/v1/assets
• GET /api/v1/assets?page=1&page_size=20&status=active
• PUT /api/v1/assets/:id
• DELETE /api/v1/assets/:id
• GET /api/v1/dashboard/summary
• GET /api/v1/reminders?status=failed&page=1&page_size=20
• GET /healthz
• GET /readyz

详细 API 见：openapi.yaml

生产部署必备项清单

• 设置强 JWT 密钥（JWT_SECRET），禁止使用默认值
• APP_ENV=production（生产环境会强校验 JWT_SECRET）
• 配置 ACCESS_TTL_MINUTES、REFRESH_TTL_HOURS（按安全策略）
• 启用服务守护（systemd 或 docker compose restart）
• 开启健康检查（/healthz）与日志采集
• 使用 HTTPS 反向代理（确保 Cookie Secure 生效）

systemd 快速部署

cd /root/.openclaw/workspace/asset-tracker
cp .env.production.example .env.production
# 编辑 .env.production，设置强 JWT_SECRET

bash deploy/systemd/install_systemd.sh
systemctl enable --now asset-tracker
systemctl status asset-tracker --no-pager

Docker Compose 生产部署

cd /root/.openclaw/workspace/asset-tracker/deploy
export JWT_SECRET='replace_with_strong_random_secret'
docker compose up -d --build

备份与恢复

# 备份
DB_PATH=./data/asset-tracker.db ./scripts/backup_db.sh

# 恢复
./scripts/restore_db.sh ./backups/asset-tracker-YYYYmmdd_HHMMSS.db.gz ./data/asset-tracker.db

后续建议

• 真实通知通道（Telegram/邮件）
• 估值快照与趋势图
• 多币种折算