# asset-tracker

个人资产管理系统（MVP）

## MVP 范围

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

## 技术栈

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

## 快速启动

```bash
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 刷新）

## 错误响应结构（统一）

```json
{
  "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 快速部署

```bash
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 生产部署

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

## 备份与恢复

```bash
# 备份
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/邮件）
- 估值快照与趋势图
- 多币种折算