docs: rewrite architecture README with module references

2026-06-04 09:58:22 +08:00 · 2025-12-15 16:02:05 +08:00
parent 85cf8c4986
commit 0e4978002b
2 changed files with 253 additions and 1074 deletions
@@ -1,4 +1,4 @@
-# 🏗️ NOFX Architecture Documentation
+# NOFX Architecture Documentation

 **Language:** [English](README.md) | [中文](README.zh-CN.md)

@@ -6,570 +6,159 @@ Technical documentation for developers who want to understand NOFX internals.

 ---

-## 📋 Overview
+## Overview
+
+NOFX is a full-stack AI trading platform for cryptocurrency and US stock markets:

-NOFX is a full-stack AI trading platform with:
 - **Backend:** Go (Gin framework, SQLite)
 - **Frontend:** React/TypeScript (Vite, TailwindCSS)
- **Architecture:** Microservice-inspired modular design
+- **AI Models:** DeepSeek, Qwen, OpenAI (GPT-5.2), Claude, Gemini, Grok, Kimi
+- **Exchanges:** Binance, Bybit, OKX, Hyperliquid, Aster, Lighter

 ---

-## 📁 Project Structure
+## System Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                              NOFX Platform                                  │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐│
+│  │  Strategy   │  │  Backtest   │  │   Debate    │  │   Live Trading      ││
+│  │   Studio    │  │   Engine    │  │    Arena    │  │   (Auto Trader)     ││
+│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘  └──────────┬──────────┘│
+│         │                │                │                    │           │
+│         └────────────────┴────────────────┴────────────────────┘           │
+│                                    │                                        │
+│                          ┌─────────▼─────────┐                              │
+│                          │   Core Services   │                              │
+│                          │  - Market Data    │                              │
+│                          │  - AI Providers   │                              │
+│                          │  - Risk Control   │                              │
+│                          └─────────┬─────────┘                              │
+│                                    │                                        │
+│         ┌──────────────────────────┼──────────────────────────┐            │
+│         │                          │                          │            │
+│  ┌──────▼──────┐         ┌─────────▼─────────┐      ┌────────▼────────┐   │
+│  │  Exchanges  │         │     Database      │      │   Frontend UI   │   │
+│  │  (CEX/DEX)  │         │    (SQLite)       │      │   (React SPA)   │   │
+│  └─────────────┘         └───────────────────┘      └─────────────────┘   │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Module Documentation
+
+### Core Modules
+
+| Module | Description | Documentation |
+|--------|-------------|---------------|
+| **Strategy Studio** | Strategy configuration, coin selection, data assembly, AI prompts | [STRATEGY_MODULE.md](STRATEGY_MODULE.md) |
+| **Backtest Engine** | Historical simulation, performance metrics, AI decision replay | [BACKTEST_MODULE.md](BACKTEST_MODULE.md) |
+| **Debate Arena** | Multi-AI collaborative decision making with voting consensus | [DEBATE_MODULE.md](DEBATE_MODULE.md) |
+
+### Module Overview
+
+#### Strategy Module
+Complete strategy configuration system including:
+- Coin source selection (static list, AI500 pool, OI ranking)
+- Market data indicators (K-lines, EMA, MACD, RSI, ATR)
+- Prompt construction (system prompt, user prompt, sections)
+- AI response parsing and decision execution
+- Risk control enforcement
+
+**[Read Full Documentation →](STRATEGY_MODULE.md)**
+
+#### Backtest Module
+Historical trading simulation engine:
+- Multi-symbol, multi-timeframe backtesting
+- AI decision replay with caching
+- Performance metrics (Sharpe, drawdown, win rate)
+- Real-time progress streaming via SSE
+- Checkpoint and resume support
+
+**[Read Full Documentation →](BACKTEST_MODULE.md)**
+
+#### Debate Module
+Multi-AI collaborative decision system:
+- 5 AI personalities (Bull, Bear, Analyst, Contrarian, Risk Manager)
+- Multi-round debate with market context
+- Weighted voting and consensus algorithm
+- Auto-execution to live trading
+- Real-time SSE streaming
+
+**[Read Full Documentation →](DEBATE_MODULE.md)**
+
+---
+
+## 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)
-│   └── api_client.go               # Market data acquisition API
-│   └── websocket_client.go         # Market data acquisition WebSocket interface
-│   └── combined_streams.go         # Market data acquisition: Combined streaming (single link to subscribe to multiple cryptocurrencies)
-│   └── monitor.go                  # Market data cache
-│   └── types.go                    # market structure
-
-├── provider/                       # Data provider management
-│   └── data_provider.go            # AI500 + OI Top data provider
-│
-├── 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
+├── main.go                    # Entry point
+├── api/                       # HTTP API (Gin framework)
+├── trader/                    # Trading execution layer
+├── strategy/                  # Strategy engine
+├── backtest/                  # Backtest simulation engine
+├── debate/                    # Debate arena engine
+├── market/                    # Market data service
+├── mcp/                       # AI model clients
+├── store/                     # Database operations
+├── auth/                      # JWT authentication
+├── manager/                   # Multi-trader management
+└── web/                       # React frontend
+    ├── src/pages/             # Page components
+    ├── src/components/        # Shared components
+    └── src/lib/api.ts         # API client
 ```

 ---

-## 🔧 Core Dependencies
+## 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/lib/pq` | PostgreSQL database driver | v1.10+ |
-| `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 |
+| Package | Purpose |
+|---------|---------|
+| `gin-gonic/gin` | HTTP API framework |
+| `adshao/go-binance` | Binance API client |
+| `markcheno/go-talib` | Technical indicators |
+| `golang-jwt/jwt` | JWT authentication |

-### Frontend (React + TypeScript)
+### Frontend (React)

-| 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 |
+| Package | Purpose |
+|---------|---------|
+| `react` | UI framework |
+| `recharts` | Charts and visualizations |
+| `swr` | Data fetching |
+| `zustand` | State management |
+| `tailwindcss` | CSS framework |

 ---

-## 🗂️ System Architecture
+## Quick Links

-### 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)*
+- [Strategy Module](STRATEGY_MODULE.md) - How strategies work
+- [Backtest Module](BACKTEST_MODULE.md) - How backtesting works
+- [Debate Module](DEBATE_MODULE.md) - How AI debates work
+- [Getting Started](../getting-started/README.md) - Setup guide
+- [FAQ](../faq/README.md) - Frequently asked questions

 ---

-## 📚 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
+## 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)
+- Read the module documentation above
+- Check [Open Issues](https://github.com/NoFxAiOS/nofx/issues)
+- Join our community

-**Need clarification?**
- Open a [GitHub Discussion](https://github.com/tinkle-community/nofx/discussions)
- Ask in Telegram
+**Repository:** https://github.com/NoFxAiOS/nofx

 ---

-## 📚 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)
+[← Back to Documentation](../README.md)
@@ -1,4 +1,4 @@
-# 🏗️ NOFX 架构文档
+# NOFX 架构文档

 **语言:** [English](README.md) | [中文](README.zh-CN.md)

@@ -6,568 +6,158 @@

 ---

-## 📋 概述
+## 概述

-NOFX 是一个全栈 AI 交易平台：
- **后端：** Go (Gin 框架, SQLite)
- **前端：** React/TypeScript (Vite, TailwindCSS)
- **架构：** 微服务启发的模块化设计
+NOFX 是一个支持加密货币和美股市场的全栈 AI 交易平台：
+
+- **后端:** Go (Gin 框架, SQLite)
+- **前端:** React/TypeScript (Vite, TailwindCSS)
+- **AI 模型:** DeepSeek, Qwen, OpenAI (GPT-5.2), Claude, Gemini, Grok, Kimi
+- **交易所:** Binance, Bybit, OKX, Hyperliquid, Aster, Lighter

 ---

-## 📁 项目结构
+## 系统架构
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                              NOFX 平台                                      │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐│
+│  │   策略      │  │   回测      │  │   辩论      │  │     实盘交易        ││
+│  │   工作室    │  │   引擎      │  │   竞技场    │  │   (自动交易员)      ││
+│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘  └──────────┬──────────┘│
+│         │                │                │                    │           │
+│         └────────────────┴────────────────┴────────────────────┘           │
+│                                    │                                        │
+│                          ┌─────────▼─────────┐                              │
+│                          │     核心服务      │                              │
+│                          │  - 行情数据       │                              │
+│                          │  - AI 模型       │                              │
+│                          │  - 风险控制       │                              │
+│                          └─────────┬─────────┘                              │
+│                                    │                                        │
+│         ┌──────────────────────────┼──────────────────────────┐            │
+│         │                          │                          │            │
+│  ┌──────▼──────┐         ┌─────────▼─────────┐      ┌────────▼────────┐   │
+│  │   交易所    │         │      数据库       │      │    前端 UI      │   │
+│  │  (CEX/DEX)  │         │    (SQLite)       │      │   (React SPA)   │   │
+│  └─────────────┘         └───────────────────┘      └─────────────────┘   │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 模块文档
+
+### 核心模块
+
+| 模块 | 描述 | 文档 |
+|------|------|------|
+| **策略工作室** | 策略配置、币种选择、数据组装、AI 提示词 | [STRATEGY_MODULE.md](STRATEGY_MODULE.md) |
+| **回测引擎** | 历史模拟、性能指标、AI 决策回放 | [BACKTEST_MODULE.md](BACKTEST_MODULE.md) |
+| **辩论竞技场** | 多 AI 协作决策，投票共识机制 | [DEBATE_MODULE.md](DEBATE_MODULE.md) |
+
+### 模块概览
+
+#### 策略模块
+完整的策略配置系统，包括：
+- 币种来源选择（静态列表、AI500 币池、OI 排行）
+- 市场数据指标（K线、EMA、MACD、RSI、ATR）
+- 提示词构建（系统提示词、用户提示词、分段配置）
+- AI 响应解析和决策执行
+- 风险控制强制执行
+
+**[阅读完整文档 →](STRATEGY_MODULE.md)**
+
+#### 回测模块
+历史交易模拟引擎：
+- 多币种、多时间周期回测
+- AI 决策回放与缓存
+- 性能指标（夏普比率、最大回撤、胜率）
+- SSE 实时进度推送
+- 断点续测支持
+
+**[阅读完整文档 →](BACKTEST_MODULE.md)**
+
+#### 辩论模块
+多 AI 协作决策系统：
+- 5 种 AI 性格（多头、空头、分析师、逆势者、风控）
+- 多轮辩论与市场数据上下文
+- 加权投票与共识算法
+- 自动执行到实盘交易
+- SSE 实时流推送
+
+**[阅读完整文档 →](DEBATE_MODULE.md)**
+
+---
+
+## 项目结构

 ```
 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）
-│   └── api_client.go               # 行情获取 Api接口
-│   └── websocket_client.go         # 行情获取 Websocket接口
-│   └── combined_streams.go         # 行情获取 组合流式(单链接订阅多个币种)
-│   └── monitor.go                  # 行情数据缓存
-│   └── types.go                    # market结构体
-│
-├── provider/                       # 数据源管理
-│   └── data_provider.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 配置
+├── main.go                    # 程序入口
+├── api/                       # HTTP API (Gin 框架)
+├── trader/                    # 交易执行层
+├── strategy/                  # 策略引擎
+├── backtest/                  # 回测模拟引擎
+├── debate/                    # 辩论竞技场引擎
+├── market/                    # 行情数据服务
+├── mcp/                       # AI 模型客户端
+├── store/                     # 数据库操作
+├── auth/                      # JWT 认证
+├── manager/                   # 多交易员管理
+└── web/                       # React 前端
+    ├── src/pages/             # 页面组件
+    ├── src/components/        # 共享组件
+    └── src/lib/api.ts         # API 客户端
 ```

 ---

-## 🔧 核心依赖
+## 核心依赖

 ### 后端 (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/lib/pq` | PostgreSQL 数据库驱动 | v1.10+ |
-| `github.com/golang-jwt/jwt/v5` | JWT 认证 | v5.0+ |
-| `github.com/pquerna/otp` | 2FA/TOTP 支持 | v1.4+ |
-| `golang.org/x/crypto` | 密码哈希（bcrypt） | 最新 |
+| 包 | 用途 |
+|---------|---------|
+| `gin-gonic/gin` | HTTP API 框架 |
+| `adshao/go-binance` | Binance API 客户端 |
+| `markcheno/go-talib` | 技术指标计算 |
+| `golang-jwt/jwt` | JWT 认证 |

-### 前端 (React + TypeScript)
+### 前端 (React)

-| 包 | 用途 | 版本 |
-|---------|---------|---------|
-| `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` | UI 框架 |
+| `recharts` | 图表可视化 |
+| `swr` | 数据获取 |
+| `zustand` | 状态管理 |
+| `tailwindcss` | CSS 框架 |

 ---

-## 🗂️ 系统架构
+## 快速链接

-### 高层架构概览
-
-```
-┌──────────────────────────────────────────────────────────────────┐
-│                         表现层                                   │
-│    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            │     │
-│  └──────────────┘  └──────────────┘  └────────────────────┘     │
-└──────────────────────────────────────────────────────────────────┘
-```
-
-### 组件图
-
-*（即将推出：详细的组件交互图）*
+- [策略模块](STRATEGY_MODULE.md) - 策略如何运作
+- [回测模块](BACKTEST_MODULE.md) - 回测如何运作
+- [辩论模块](DEBATE_MODULE.md) - AI 辩论如何运作
+- [快速开始](../getting-started/README.zh-CN.md) - 部署指南
+- [常见问题](../faq/README.md) - FAQ

 ---

-## 📚 核心模块
-
-### 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)
+- 阅读上方的模块文档
+- 查看 [Open Issues](https://github.com/NoFxAiOS/nofx/issues)
+- 加入我们的社区

-**需要澄清？**
- 开启 [GitHub 讨论](https://github.com/tinkle-community/nofx/discussions)
- 在 Telegram 提问
-
---
-
-## 📚 相关文档
-
- [快速开始](../getting-started/README.zh-CN.md) - 设置和部署
- [贡献指南](../../CONTRIBUTING.md) - 如何贡献
- [社区](../community/README.md) - 悬赏和认可
+**代码仓库:** https://github.com/NoFxAiOS/nofx

 ---