liuyu/nofx
1
0
Fork 0
mirror of https://github.com/NoFxAiOS/nofx.git synced 2026-07-10 06:20:58 +08:00
Code Issues Packages Projects Releases Wiki Activity

Feat: Update docs

Browse Source 
- 重构文档结构
- 更新文档内容
- 制定roadmap
- 提供中/EN 双语文档
This commit is contained in:
zbhan
2025-11-01 15:05:24 -04:00
parent 9b9b269dca
commit 18820fc319
36 changed files with 5756 additions and 1149 deletions
Download Patch File Download Diff File Expand all files Collapse all files

570
docs/architecture/README.md Normal file
View File

@@ -0,0 +1,570 @@
# 🏗️ NOFX Architecture Documentation
**Language:** [English](README.md) | [中文](README.zh-CN.md)
Technical documentation for developers who want to understand NOFX internals.
---
## 📋 Overview
NOFX is a full-stack AI trading platform with:
- **Backend:** Go (Gin framework, SQLite)
- **Frontend:** React/TypeScript (Vite, TailwindCSS)
- **Architecture:** Microservice-inspired modular design
---
## 📁 Project Structure
```
nofx/
├── main.go # Program entry (multi-trader manager)
├── config.json # ~~Multi-trader config~~ (Now via web interface)
├── trading.db # SQLite database (traders, models, exchanges)
│
├── api/ # HTTP API service
│ └── server.go # Gin framework, RESTful API
│
├── trader/ # Trading core
│ ├── auto_trader.go # Auto trading main controller
│ ├── interface.go # Unified trader interface
│ ├── binance_futures.go # Binance API wrapper
│ ├── hyperliquid_trader.go # Hyperliquid DEX wrapper
│ └── aster_trader.go # Aster DEX wrapper
│
├── manager/ # Multi-trader management
│ └── trader_manager.go # Manages multiple trader instances
│
├── config/ # Configuration & database
│ └── database.go # SQLite operations and schema
│
├── auth/ # Authentication
│ └── jwt.go # JWT token management & 2FA
│
├── mcp/ # Model Context Protocol - AI communication
│ └── client.go # AI API client (DeepSeek/Qwen/Custom)
│
├── decision/ # AI decision engine
│ ├── engine.go # Decision logic with historical feedback
│ └── prompt_manager.go # Prompt template system
│
├── market/ # Market data fetching
│ └── data.go # Market data & technical indicators (TA-Lib)
│
├── pool/ # Coin pool management
│ └── coin_pool.go # AI500 + OI Top merged pool
│
├── logger/ # Logging system
│ └── decision_logger.go # Decision recording + performance analysis
│
├── decision_logs/ # Decision log storage (JSON files)
│ ├── {trader_id}/ # Per-trader logs
│ └── {timestamp}.json # Individual decisions
│
└── web/ # React frontend
├── src/
│ ├── components/ # React components
│ │ ├── EquityChart.tsx # Equity curve chart
│ │ ├── ComparisonChart.tsx # Multi-AI comparison chart
│ │ └── CompetitionPage.tsx # Competition leaderboard
│ ├── lib/api.ts # API call wrapper
│ ├── types/index.ts # TypeScript types
│ ├── stores/ # Zustand state management
│ ├── index.css # Binance-style CSS
│ └── App.tsx # Main app
├── package.json # Frontend dependencies
└── vite.config.ts # Vite configuration
```
---
## 🔧 Core Dependencies
### Backend (Go)
| Package | Purpose | Version |
|---------|---------|---------|
| `github.com/gin-gonic/gin` | HTTP API framework | v1.9+ |
| `github.com/adshao/go-binance/v2` | Binance API client | v2.4+ |
| `github.com/markcheno/go-talib` | Technical indicators (TA-Lib) | Latest |
| `github.com/mattn/go-sqlite3` | SQLite database driver | v1.14+ |
| `github.com/golang-jwt/jwt/v5` | JWT authentication | v5.0+ |
| `github.com/pquerna/otp` | 2FA/TOTP support | v1.4+ |
| `golang.org/x/crypto` | Password hashing (bcrypt) | Latest |
### Frontend (React + TypeScript)
| Package | Purpose | Version |
|---------|---------|---------|
| `react` + `react-dom` | UI framework | 18.3+ |
| `typescript` | Type safety | 5.8+ |
| `vite` | Build tool | 6.0+ |
| `recharts` | Charts (equity, comparison) | 2.15+ |
| `swr` | Data fetching & caching | 2.2+ |
| `zustand` | State management | 5.0+ |
| `tailwindcss` | CSS framework | 3.4+ |
| `lucide-react` | Icon library | Latest |
---
## 🗂️ System Architecture
### High-Level Overview
```
┌──────────────────────────────────────────────────────────────────┐
│ PRESENTATION LAYER │
│ React SPA (Vite + TypeScript + TailwindCSS) │
│ - Competition dashboard, trader management UI │
│ - Real-time charts (Recharts), authentication pages │
└──────────────────────────────────────────────────────────────────┘
↓ HTTP/JSON API
┌──────────────────────────────────────────────────────────────────┐
│ API LAYER (Gin Router) │
│ /api/traders, /api/status, /api/positions, /api/decisions │
│ Authentication middleware (JWT), CORS handling │
└──────────────────────────────────────────────────────────────────┘
↓
┌──────────────────────────────────────────────────────────────────┐
│ BUSINESS LOGIC LAYER │
│ ┌──────────────────┐ ┌──────────────────┐ ┌────────────────┐ │
│ │ TraderManager │ │ DecisionEngine │ │ MarketData │ │
│ │ - Multi-trader │ │ - AI reasoning │ │ - K-lines │ │
│ │ orchestration │ │ - Risk control │ │ - Indicators │ │
│ └──────────────────┘ └──────────────────┘ └────────────────┘ │
└──────────────────────────────────────────────────────────────────┘
↓
┌──────────────────────────────────────────────────────────────────┐
│ DATA ACCESS LAYER │
│ ┌──────────────┐ ┌──────────────┐ ┌────────────────────┐ │
│ │ SQLite DB │ │ File Logger │ │ External APIs │ │
│ │ - Traders │ │ - Decisions │ │ - Binance │ │
│ │ - Models │ │ - Performance│ │ - Hyperliquid │ │
│ │ - Exchanges │ │ analysis │ │ - Aster │ │
│ └──────────────┘ └──────────────┘ └────────────────────┘ │
└──────────────────────────────────────────────────────────────────┘
```
### Component Diagram
*(Coming soon: detailed component interaction diagram)*
---
## 📚 Core Modules
### 1. Trader System (`trader/`)
**Purpose:** Trading execution layer with multi-exchange support
**Key Files:**
- `auto_trader.go` - Main trading orchestrator (100+ lines)
- `interface.go` - Unified trader interface
- `binance_futures.go` - Binance API wrapper
- `hyperliquid_trader.go` - Hyperliquid DEX wrapper
- `aster_trader.go` - Aster DEX wrapper
**Design Pattern:** Strategy pattern with interface-based abstraction
**Example:**
```go
type ExchangeClient interface {
GetAccount() (*AccountInfo, error)
GetPositions() ([]*Position, error)
CreateOrder(*OrderParams) (*Order, error)
// ... more methods
}
```
---
### 2. Decision Engine (`decision/`)
**Purpose:** AI-powered trading decision making
**Key Files:**
- `engine.go` - Decision logic with historical feedback
- `prompt_manager.go` - Template system for AI prompts
**Features:**
- Chain-of-Thought reasoning
- Historical performance analysis
- Risk-aware decision making
- Multi-model support (DeepSeek, Qwen, custom)
**Flow:**
```
Historical Data → Prompt Generation → AI API Call →
Decision Parsing → Risk Validation → Execution
```
---
### 3. Market Data System (`market/`)
**Purpose:** Fetch and analyze market data
**Key Files:**
- `data.go` - Market data fetching and technical indicators
**Features:**
- Multi-timeframe K-line data (3min, 4hour)
- Technical indicators via TA-Lib:
- EMA (20, 50)
- MACD
- RSI (7, 14)
- ATR (volatility)
- Open Interest tracking
---
### 4. Manager (`manager/`)
**Purpose:** Multi-trader orchestration
**Key Files:**
- `trader_manager.go` - Manages multiple trader instances
**Responsibilities:**
- Trader lifecycle (start, stop, restart)
- Resource allocation
- Concurrent execution coordination
---
### 5. API Server (`api/`)
**Purpose:** HTTP API for frontend communication
**Key Files:**
- `server.go` - Gin framework RESTful API
**Endpoints:**
```
GET /api/traders # List all traders
POST /api/traders # Create trader
POST /api/traders/:id/start # Start trader
GET /api/status # System status
GET /api/positions # Current positions
GET /api/decisions/latest # Recent decisions
```
---
### 6. Database Layer (`config/`)
**Purpose:** SQLite data persistence
**Key Files:**
- `database.go` - Database operations and schema
**Tables:**
- `users` - User accounts (with 2FA support)
- `ai_models` - AI model configurations
- `exchanges` - Exchange credentials
- `traders` - Trader instances
- `equity_history` - Performance tracking
- `system_config` - Application settings
---
### 7. Authentication (`auth/`)
**Purpose:** User authentication and authorization
**Features:**
- JWT token-based auth
- 2FA with TOTP (Google Authenticator)
- Bcrypt password hashing
- Admin mode (simplified single-user)
---
## 🔄 Request Flow Examples
### Example 1: Create New Trader
```
User Action (Frontend)
↓
POST /api/traders
↓
API Server (auth middleware)
↓
Database.CreateTrader()
↓
TraderManager.StartTrader()
↓
AutoTrader.Run() → goroutine
↓
Response: {trader_id, status}
```
### Example 2: Trading Decision Cycle
```
AutoTrader (every 3-5 min)
↓
1. FetchAccountStatus()
↓
2. GetOpenPositions()
↓
3. FetchMarketData() → TA-Lib indicators
↓
4. AnalyzeHistory() → last 20 trades
↓
5. GeneratePrompt() → full context
↓
6. CallAI() → DeepSeek/Qwen
↓
7. ParseDecision() → structured output
↓
8. ValidateRisk() → position limits, margin
↓
9. ExecuteOrders() → exchange API
↓
10. LogDecision() → JSON file + database
```
---
## 📊 Data Flow
### Market Data Flow
```
Exchange API
↓
market.FetchKlines()
↓
TA-Lib.Calculate(EMA, MACD, RSI)
↓
DecisionEngine (as context)
↓
AI Model (reasoning)
```
### Decision Logging Flow
```
AI Response
↓
decision_logger.go
↓
JSON file: decision_logs/{trader_id}/{timestamp}.json
↓
Database: performance tracking
↓
Frontend: /api/decisions/latest
```
---
## 🗄️ Database Schema
### Core Tables
**users**
```sql
- id (INTEGER PRIMARY KEY)
- username (TEXT UNIQUE)
- password_hash (TEXT)
- totp_secret (TEXT)
- is_admin (BOOLEAN)
- created_at (DATETIME)
```
**ai_models**
```sql
- id (INTEGER PRIMARY KEY)
- name (TEXT)
- model_type (TEXT) -- deepseek, qwen, custom
- api_key (TEXT)
- api_url (TEXT)
- enabled (BOOLEAN)
```
**traders**
```sql
- id (TEXT PRIMARY KEY)
- name (TEXT)
- ai_model_id (INTEGER FK)
- exchange_id (INTEGER FK)
- initial_balance (REAL)
- current_equity (REAL)
- status (TEXT) -- running, stopped
- created_at (DATETIME)
```
*(More details: database-schema.md - coming soon)*
---
## 🔌 API Reference
### Authentication
**POST /api/auth/login**
```json
Request: {
"username": "string",
"password": "string",
"totp_code": "string" // optional
}
Response: {
"token": "jwt_token",
"user": {...}
}
```
### Trader Management
**GET /api/traders**
```json
Response: {
"traders": [
{
"id": "string",
"name": "string",
"status": "running|stopped",
"balance": 1000.0,
"roi": 5.2
}
]
}
```
*(Full API reference: api-reference.md - coming soon)*
---
## 🧪 Testing Architecture
### Current State
- ⚠️ No unit tests yet
- ⚠️ Manual testing only
- ⚠️ Testnet verification
### Planned Testing Strategy
**Unit Tests (Priority 1)**
```
trader/binance_futures_test.go
- Mock API responses
- Test precision handling
- Validate order construction
```
**Integration Tests (Priority 2)**
```
- End-to-end trading flow (testnet)
- Multi-trader scenarios
- Database operations
```
**Frontend Tests (Priority 3)**
```
- Component tests (Vitest + React Testing Library)
- API integration tests
- E2E tests (Playwright)
```
*(Testing guide: testing-guide.md - coming soon)*
---
## 🔧 Development Tools
### Build & Run
```bash
# Backend
go build -o nofx
./nofx
# Frontend
cd web
npm run dev
# Docker
docker compose up --build
```
### Code Quality
```bash
# Format Go code
go fmt ./...
# Lint (if configured)
golangci-lint run
# Type check TypeScript
cd web && npm run build
```
---
## 📈 Performance Considerations
### Backend
- **Concurrency:** Each trader runs in separate goroutine
- **Database:** SQLite (good for <100 traders)
- **API Rate Limits:** Handled per exchange
- **Memory:** ~50-100MB per trader
### Frontend
- **Data Fetching:** SWR with 5-10s polling
- **State:** Zustand (lightweight)
- **Bundle Size:** ~500KB (gzipped)
---
## 🔮 Future Architecture Plans
### Planned Improvements
1. **Microservices Split** (if scaling needed)
- Separate decision engine service
- Market data service
- Execution service
2. **Database Migration**
- Mysql for production (>100 traders)
- Redis for caching
3. **Event-Driven Architecture**
- WebSocket for real-time updates
- Message queue (RabbitMQ/NATS)
4. **Kubernetes Deployment**
- Helm charts
- Auto-scaling
- High availability
---
## 🆘 For Developers
**Want to contribute?**
- Read [Contributing Guide](../../CONTRIBUTING.md)
- Check [Open Issues](https://github.com/tinkle-community/nofx/issues)
- Join [Telegram Community](https://t.me/nofx_dev_community)
**Need clarification?**
- Open a [GitHub Discussion](https://github.com/tinkle-community/nofx/discussions)
- Ask in Telegram
---
## 📚 Related Documentation
- [Getting Started](../getting-started/README.md) - Setup and deployment
- [Contributing](../../CONTRIBUTING.md) - How to contribute
- [Community](../community/README.md) - Bounties and recognition
---
[← Back to Documentation Home](../README.md)

570
docs/architecture/README.zh-CN.md Normal file
View File

@@ -0,0 +1,570 @@
# 🏗️ NOFX 架构文档
**语言:** [English](README.md) | [中文](README.zh-CN.md)
为希望了解 NOFX 内部实现的开发者提供的技术文档。
---
## 📋 概述
NOFX 是一个全栈 AI 交易平台：
- **后端：** Go (Gin 框架, SQLite)
- **前端：** React/TypeScript (Vite, TailwindCSS)
- **架构：** 微服务启发的模块化设计
---
## 📁 项目结构
```
nofx/
├── main.go # 程序入口（多交易员管理器）
├── config.json # ~~多交易员配置~~ (现通过Web界面)
├── trading.db # SQLite 数据库（交易员、模型、交易所）
│
├── api/ # HTTP API 服务
│ └── server.go # Gin 框架，RESTful API
│
├── trader/ # 交易核心
│ ├── auto_trader.go # 自动交易主控制器
│ ├── interface.go # 统一交易员接口
│ ├── binance_futures.go # Binance API 包装器
│ ├── hyperliquid_trader.go # Hyperliquid DEX 包装器
│ └── aster_trader.go # Aster DEX 包装器
│
├── manager/ # 多交易员管理
│ └── trader_manager.go # 管理多个交易员实例
│
├── config/ # 配置与数据库
│ └── database.go # SQLite 操作和模式
│
├── auth/ # 认证
│ └── jwt.go # JWT token 管理 & 2FA
│
├── mcp/ # Model Context Protocol - AI 通信
│ └── client.go # AI API 客户端（DeepSeek/Qwen/自定义）
│
├── decision/ # AI 决策引擎
│ ├── engine.go # 带历史反馈的决策逻辑
│ └── prompt_manager.go # 提示词模板系统
│
├── market/ # 市场数据获取
│ └── data.go # 市场数据与技术指标（TA-Lib）
│
├── pool/ # 币种池管理
│ └── coin_pool.go # AI500 + OI Top 合并池
│
├── logger/ # 日志系统
│ └── decision_logger.go # 决策记录 + 性能分析
│
├── decision_logs/ # 决策日志存储（JSON 文件）
│ ├── {trader_id}/ # 每个交易员的日志
│ └── {timestamp}.json # 单个决策
│
└── web/ # React 前端
├── src/
│ ├── components/ # React 组件
│ │ ├── EquityChart.tsx # 权益曲线图表
│ │ ├── ComparisonChart.tsx # 多 AI 对比图表
│ │ └── CompetitionPage.tsx # 竞赛排行榜
│ ├── lib/api.ts # API 调用包装器
│ ├── types/index.ts # TypeScript 类型
│ ├── stores/ # Zustand 状态管理
│ ├── index.css # Binance 风格样式
│ └── App.tsx # 主应用
├── package.json # 前端依赖
└── vite.config.ts # Vite 配置
```
---
## 🔧 核心依赖
### 后端 (Go)
| 包 | 用途 | 版本 |
|---------|---------|---------|
| `github.com/gin-gonic/gin` | HTTP API 框架 | v1.9+ |
| `github.com/adshao/go-binance/v2` | Binance API 客户端 | v2.4+ |
| `github.com/markcheno/go-talib` | 技术指标（TA-Lib） | 最新 |
| `github.com/mattn/go-sqlite3` | SQLite 数据库驱动 | v1.14+ |
| `github.com/golang-jwt/jwt/v5` | JWT 认证 | v5.0+ |
| `github.com/pquerna/otp` | 2FA/TOTP 支持 | v1.4+ |
| `golang.org/x/crypto` | 密码哈希（bcrypt） | 最新 |
### 前端 (React + TypeScript)
| 包 | 用途 | 版本 |
|---------|---------|---------|
| `react` + `react-dom` | UI 框架 | 18.3+ |
| `typescript` | 类型安全 | 5.8+ |
| `vite` | 构建工具 | 6.0+ |
| `recharts` | 图表（权益、对比） | 2.15+ |
| `swr` | 数据获取与缓存 | 2.2+ |
| `zustand` | 状态管理 | 5.0+ |
| `tailwindcss` | CSS 框架 | 3.4+ |
| `lucide-react` | 图标库 | 最新 |
---
## 🗂️ 系统架构
### 高层架构概览
```
┌──────────────────────────────────────────────────────────────────┐
│ 表现层 │
│ React SPA (Vite + TypeScript + TailwindCSS) │
│ - 竞赛仪表板、交易员管理 UI │
│ - 实时图表 (Recharts)、认证页面 │
└──────────────────────────────────────────────────────────────────┘
↓ HTTP/JSON API
┌──────────────────────────────────────────────────────────────────┐
│ API 层 (Gin Router) │
│ /api/traders, /api/status, /api/positions, /api/decisions │
│ 认证中间件 (JWT)、CORS 处理 │
└──────────────────────────────────────────────────────────────────┘
↓
┌──────────────────────────────────────────────────────────────────┐
│ 业务逻辑层 │
│ ┌──────────────────┐ ┌──────────────────┐ ┌────────────────┐ │
│ │ TraderManager │ │ DecisionEngine │ │ MarketData │ │
│ │ - 多交易员 │ │ - AI 推理 │ │ - K线数据 │ │
│ │ 编排 │ │ - 风险控制 │ │ - 技术指标 │ │
│ └──────────────────┘ └──────────────────┘ └────────────────┘ │
└──────────────────────────────────────────────────────────────────┘
↓
┌──────────────────────────────────────────────────────────────────┐
│ 数据访问层 │
│ ┌──────────────┐ ┌──────────────┐ ┌────────────────────┐ │
│ │ SQLite DB │ │ 文件日志 │ │ 外部 APIs │ │
│ │ - Traders │ │ - Decisions │ │ - Binance │ │
│ │ - Models │ │ - Performance│ │ - Hyperliquid │ │
│ │ - Exchanges │ │ analysis │ │ - Aster │ │
│ └──────────────┘ └──────────────┘ └────────────────────┘ │
└──────────────────────────────────────────────────────────────────┘
```
### 组件图
*（即将推出：详细的组件交互图）*
---
## 📚 核心模块
### 1. 交易系统 (`trader/`)
**用途：** 支持多交易所的交易执行层
**关键文件：**
- `auto_trader.go` - 主交易编排器（100+ 行）
- `interface.go` - 统一的交易员接口
- `binance_futures.go` - Binance API 包装器
- `hyperliquid_trader.go` - Hyperliquid DEX 包装器
- `aster_trader.go` - Aster DEX 包装器
**设计模式：** 基于接口抽象的策略模式
**示例：**
```go
type ExchangeClient interface {
GetAccount() (*AccountInfo, error)
GetPositions() ([]*Position, error)
CreateOrder(*OrderParams) (*Order, error)
// ... 更多方法
}
```
---
### 2. 决策引擎 (`decision/`)
**用途：** AI 驱动的交易决策制定
**关键文件：**
- `engine.go` - 带历史反馈的决策逻辑
- `prompt_manager.go` - AI 提示词模板系统
**特性：**
- 思维链推理
- 历史表现分析
- 风险感知决策
- 多模型支持（DeepSeek、Qwen、自定义）
**流程：**
```
历史数据 → 提示词生成 → AI API 调用 →
决策解析 → 风险验证 → 执行
```
---
### 3. 市场数据系统 (`market/`)
**用途：** 获取和分析市场数据
**关键文件：**
- `data.go` - 市场数据获取和技术指标
**特性：**
- 多时间周期 K线数据（3分钟、4小时）
- 通过 TA-Lib 计算技术指标：
- EMA (20, 50)
- MACD
- RSI (7, 14)
- ATR（波动率）
- 持仓量跟踪
---
### 4. 管理器 (`manager/`)
**用途：** 多交易员编排
**关键文件：**
- `trader_manager.go` - 管理多个交易员实例
**职责：**
- 交易员生命周期（启动、停止、重启）
- 资源分配
- 并发执行协调
---
### 5. API 服务器 (`api/`)
**用途：** 前端通信的 HTTP API
**关键文件：**
- `server.go` - Gin 框架 RESTful API
**端点：**
```
GET /api/traders # 列出所有交易员
POST /api/traders # 创建交易员
POST /api/traders/:id/start # 启动交易员
GET /api/status # 系统状态
GET /api/positions # 当前持仓
GET /api/decisions/latest # 最近决策
```
---
### 6. 数据库层 (`config/`)
**用途：** SQLite 数据持久化
**关键文件：**
- `database.go` - 数据库操作和模式
**表：**
- `users` - 用户账户（支持 2FA）
- `ai_models` - AI 模型配置
- `exchanges` - 交易所凭证
- `traders` - 交易员实例
- `equity_history` - 绩效跟踪
- `system_config` - 应用程序设置
---
### 7. 认证 (`auth/`)
**用途：** 用户认证和授权
**特性：**
- 基于 JWT token 的认证
- 使用 TOTP 的 2FA（Google Authenticator）
- Bcrypt 密码哈希
- 管理员模式（简化的单用户模式）
---
## 🔄 请求流程示例
### 示例 1：创建新交易员
```
用户操作（前端）
↓
POST /api/traders
↓
API 服务器（认证中间件）
↓
Database.CreateTrader()
↓
TraderManager.StartTrader()
↓
AutoTrader.Run() → goroutine
↓
响应: {trader_id, status}
```
### 示例 2：交易决策周期
```
AutoTrader（每 3-5 分钟）
↓
1. FetchAccountStatus()
↓
2. GetOpenPositions()
↓
3. FetchMarketData() → TA-Lib 指标
↓
4. AnalyzeHistory() → 最近 20 笔交易
↓
5. GeneratePrompt() → 完整上下文
↓
6. CallAI() → DeepSeek/Qwen
↓
7. ParseDecision() → 结构化输出
↓
8. ValidateRisk() → 仓位限制、保证金
↓
9. ExecuteOrders() → 交易所 API
↓
10. LogDecision() → JSON 文件 + 数据库
```
---
## 📊 数据流
### 市场数据流
```
交易所 API
↓
market.FetchKlines()
↓
TA-Lib.Calculate(EMA, MACD, RSI)
↓
DecisionEngine（作为上下文）
↓
AI 模型（推理）
```
### 决策日志流
```
AI 响应
↓
decision_logger.go
↓
JSON 文件: decision_logs/{trader_id}/{timestamp}.json
↓
数据库: 绩效跟踪
↓
前端: /api/decisions/latest
```
---
## 🗄️ 数据库架构
### 核心表
**users**
```sql
- id (INTEGER PRIMARY KEY)
- username (TEXT UNIQUE)
- password_hash (TEXT)
- totp_secret (TEXT)
- is_admin (BOOLEAN)
- created_at (DATETIME)
```
**ai_models**
```sql
- id (INTEGER PRIMARY KEY)
- name (TEXT)
- model_type (TEXT) -- deepseek, qwen, custom
- api_key (TEXT)
- api_url (TEXT)
- enabled (BOOLEAN)
```
**traders**
```sql
- id (TEXT PRIMARY KEY)
- name (TEXT)
- ai_model_id (INTEGER FK)
- exchange_id (INTEGER FK)
- initial_balance (REAL)
- current_equity (REAL)
- status (TEXT) -- running, stopped
- created_at (DATETIME)
```
*（更多详情：database-schema.md - 即将推出）*
---
## 🔌 API 参考
### 认证
**POST /api/auth/login**
```json
请求: {
"username": "string",
"password": "string",
"totp_code": "string" // 可选
}
响应: {
"token": "jwt_token",
"user": {...}
}
```
### 交易员管理
**GET /api/traders**
```json
响应: {
"traders": [
{
"id": "string",
"name": "string",
"status": "running|stopped",
"balance": 1000.0,
"roi": 5.2
}
]
}
```
*（完整 API 参考：api-reference.md - 即将推出）*
---
## 🧪 测试架构
### 当前状态
- ⚠️ 尚无单元测试
- ⚠️ 仅手动测试
- ⚠️ 测试网验证
### 计划的测试策略
**单元测试（优先级 1）**
```
trader/binance_futures_test.go
- 模拟 API 响应
- 测试精度处理
- 验证订单构造
```
**集成测试（优先级 2）**
```
- 端到端交易流程（测试网）
- 多交易员场景
- 数据库操作
```
**前端测试（优先级 3）**
```
- 组件测试（Vitest + React Testing Library）
- API 集成测试
- E2E 测试（Playwright）
```
*（测试指南：testing-guide.md - 即将推出）*
---
## 🔧 开发工具
### 构建与运行
```bash
# 后端
go build -o nofx
./nofx
# 前端
cd web
npm run dev
# Docker
docker compose up --build
```
### 代码质量
```bash
# 格式化 Go 代码
go fmt ./...
# Lint（如果配置）
golangci-lint run
# TypeScript 类型检查
cd web && npm run build
```
---
## 📈 性能考虑
### 后端
- **并发：** 每个交易员在独立的 goroutine 中运行
- **数据库：** SQLite（适用于 <100 个交易员）
- **API 速率限制：** 按交易所处理
- **内存：** 每个交易员 ~50-100MB
### 前端
- **数据获取：** SWR，5-10 秒轮询
- **状态：** Zustand（轻量级）
- **包大小：** ~500KB（gzipped）
---
## 🔮 未来架构计划
### 计划改进
1. **微服务拆分**（如需扩展）
- 独立的决策引擎服务
- 市场数据服务
- 执行服务
2. **数据库迁移**
- 生产环境使用 Mysql (>100 个交易员）
- Redis 缓存
3. **事件驱动架构**
- WebSocket 实时更新
- 消息队列（RabbitMQ/NATS）
4. **Kubernetes 部署**
- Helm charts
- 自动扩展
- 高可用性
---
## 🆘 开发者资源
**想要贡献？**
- 阅读[贡献指南](../../CONTRIBUTING.md)
- 查看[开放问题](https://github.com/tinkle-community/nofx/issues)
- 加入 [Telegram 社区](https://t.me/nofx_dev_community)
**需要澄清？**
- 开启 [GitHub 讨论](https://github.com/tinkle-community/nofx/discussions)
- 在 Telegram 提问
---
## 📚 相关文档
- [快速开始](../getting-started/README.zh-CN.md) - 设置和部署
- [贡献指南](../../CONTRIBUTING.md) - 如何贡献
- [社区](../community/README.md) - 悬赏和认可
---
[← 返回文档首页](../README.md)