# LLM-admin

**Repository Path**: llm-agent_2/llm-admin

## Basic Information

- **Project Name**: LLM-admin
- **Description**: 量化交易系统
后端
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-12
- **Last Updated**: 2026-01-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LLM-admin

FastAPI + SQLAlchemy + Alembic 的后台服务。

- 推荐使用项目虚拟环境：`./.venv/bin/python`
- API 前缀：`/llm-admin/api/v1`

## 快速开始（本机开发）

1）安装依赖（已创建 `.venv` 的前提下）：

```bash
./.venv/bin/pip install -r requirements.txt
```

2）启动依赖（PostgreSQL / Redis）：

```bash
docker compose up -d postgres redis
```

3）迁移 + 初始化（会创建默认管理员）：

```bash
./.venv/bin/alembic upgrade head
./.venv/bin/python -m app.db.init_db
```

4）启动服务：

```bash
./.venv/bin/python -m uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload
```

健康检查：

```bash
curl -s http://127.0.0.1:8000/health
```

## 配置要点

常用环境变量（可放到 `.env`）：

- 本机跑 uvicorn + docker compose 跑 DB：`POSTGRES_SERVER=localhost`
- docker compose 跑全套：`POSTGRES_SERVER=postgres`

数据库重建（会清空 public schema，请谨慎）：

```bash
./.venv/bin/python scripts/reset_db.py --yes
```

## 行情数据源说明

- 业务接口中 `source` 支持：`COMBO` / `YAHOO` / `AKSHARE` / `USMART` / `FUTU`
- 不传 `source` 时：使用“当前用户默认源”
- `COMBO`：组合源（会在 Yahoo 与 AKShare 间做路由与兜底）
- `USMART` / `FUTU`：券商源（需要登录/鉴权信息；未接入时会显示不可用）

quote/history 返回统一 envelope（包含 `normalized` 与 `raw`），便于分析侧可拔插。

## CSV 备份服务（异步 + 定时）

- 触发 1：添加自选股成功后，会 best-effort 投递异步任务生成/追加该股票的 CSV（不影响接口返回）。
- 触发 2：Celery Beat 会在各市场“收盘后”定时触发按市场批量追加（CN/HK/US）。
- 备份目录：默认 `./backups/stock_data/{market}/{symbol}.csv`，可用环境变量 `BACKUP_DIR` 覆盖根目录。
- CSV 字段（含自动表头升级）：`date, open, high, low, close, volume, turnover, adjust_factor, prev_close, change_pct, turnover_rate, market_cap, adj_close`

字段口径说明：

- `prev_close` / `change_pct`：按 CSV 相邻交易日 `close` 推导。
- `turnover`：优先使用数据源返回（若无则近似为 `close * volume`）。
- `turnover_rate`：优先使用标准口径 `volume / float_shares * 100`（需要 DB 中有 `float_shares`）；否则兜底为 `turnover / market_cap * 100`。
- `market_cap`：会从 DB 的 `stocks.market_cap` 回填到每天行（含旧行空值回填）。

为支持标准换手率口径，`stocks` 表新增了以下字段：

- `shares_outstanding`（总股本）
- `float_shares`（流通股本）
- `free_float_market_cap`（流通市值）

本机启动 Celery worker：

```bash
./.venv/bin/celery -A app.celery_tasks.celery_app:celery_app worker -l info
```

本机启动 Celery beat（定时任务）：

```bash
./.venv/bin/celery -A app.celery_tasks.celery_app:celery_app beat -l info
```

手动触发某市场备份（管理员接口，异步投递）：

```bash
curl -s -X POST http://127.0.0.1:8000/llm-admin/api/v1/admin/backup/market/CN/run \
  -H "Authorization: Bearer $TOKEN"
```

## 常用接口（curl）

### 1）登录获取 Token

```bash
curl -s -X POST http://127.0.0.1:8000/llm-admin/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"login_type":"password","username":"admin","password":"123456"}'
```

```bash
export TOKEN="<access_token>"
```

### 2）切换“当前用户”的默认行情数据源

支持值：`COMBO` / `USMART` / `FUTU`。

查询：

```bash
curl -s http://127.0.0.1:8000/llm-admin/api/v1/system/config/market-data-source \
  -H "Authorization: Bearer $TOKEN"
```

设置：

```bash
curl -s -X PUT http://127.0.0.1:8000/llm-admin/api/v1/system/config/market-data-source \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"active_source":"COMBO"}'
```

### 3）stocks：搜索

```bash
curl -s -X POST http://127.0.0.1:8000/llm-admin/api/v1/stocks/search \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"AAPL","source":"COMBO"}'
```

### 4）stocks：实时行情 / 历史行情

```bash
curl -s "http://127.0.0.1:8000/llm-admin/api/v1/stocks/AAPL/quote?source=COMBO" \
  -H "Authorization: Bearer $TOKEN"
```

```bash
curl -s "http://127.0.0.1:8000/llm-admin/api/v1/stocks/AAPL/history?period=1mo&interval=1d&source=COMBO" \
  -H "Authorization: Bearer $TOKEN"
```

### 5）watchlist：列表 / 添加 / 移除

```bash
curl -s -X POST http://127.0.0.1:8000/llm-admin/api/v1/stocks/watchlist/list \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

```bash
curl -s -X POST "http://127.0.0.1:8000/llm-admin/api/v1/stocks/watchlist/list/AAPL?source=COMBO" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"nickname":"","notes":""}'
```

```bash
curl -s -X DELETE http://127.0.0.1:8000/llm-admin/api/v1/stocks/watchlist/list/AAPL \
  -H "Authorization: Bearer $TOKEN"
```

## 诊断脚本（可选）

```bash
./.venv/bin/python scripts/db_health_check.py
```