22787b3e0a
- Generate full AI-consumable docs (docs/ai/): system overview, architecture, module cheatsheet, API contracts, data model, build guide, decision log, glossary, and open questions (deep tier coverage) - Add PROBLEM_REPORT.md: categorized bug/risk summary - Add DETAILED_CODE_REVIEW.md: full line-by-line review of all 15 backend files, documenting 4 fatal issues, 5 critical deployment bugs, 4 security vulnerabilities, and 6 architecture defects with prioritized fix plan
53 lines
3.4 KiB
Markdown
53 lines
3.4 KiB
Markdown
---
|
||
generated_by: repo-insight
|
||
version: 1
|
||
created: 2026-03-03
|
||
last_updated: 2026-03-03
|
||
source_commit: 0d9dffa
|
||
coverage: deep
|
||
---
|
||
|
||
# Arbitrage Engine — AI Documentation Index
|
||
|
||
**Project**: `arbitrage-engine`
|
||
**Summary**: Full-stack crypto perpetual futures funding-rate arbitrage monitoring and V5.x CVD/ATR-based short-term trading signal engine. Python/FastAPI backend + Next.js frontend + PostgreSQL + Binance USDC-M Futures.
|
||
|
||
## Generated Documents
|
||
|
||
| File | Description |
|
||
|------|-------------|
|
||
| [00-system-overview.md](./00-system-overview.md) | Project purpose, tech stack, repo layout, entry points, environment variables |
|
||
| [01-architecture-map.md](./01-architecture-map.md) | Multi-process architecture, component diagram, signal pipeline data flow, risk guard rules, frontend polling |
|
||
| [02-module-cheatsheet.md](./02-module-cheatsheet.md) | Module-by-module index: role, public interfaces, dependencies for all 20 backend + 15 frontend files |
|
||
| [03-api-contracts.md](./03-api-contracts.md) | All REST endpoints, auth flows, request/response shapes, error conventions |
|
||
| [04-data-model.md](./04-data-model.md) | All PostgreSQL tables, columns, partitioning strategy, storage design decisions |
|
||
| [05-build-run-test.md](./05-build-run-test.md) | 构建/运行/部署命令，环境变量，PM2 配置，回测和模拟盘操作 |
|
||
| [06-decision-log.md](./06-decision-log.md) | 9 项关键技术决策：PG 消息总线、循环间隔、双写、分区、自研 JWT 等 |
|
||
| [07-glossary.md](./07-glossary.md) | 交易术语（CVD/ATR/R/tier）+ 工程术语（paper trading/warmup/circuit break） |
|
||
| [99-open-questions.md](./99-open-questions.md) | 11 个未解决问题：users 表双定义冲突、依赖不完整、硬编码密码、无测试等 |
|
||
|
||
## Recommended Reading Order
|
||
|
||
1. **Start here**: `00-system-overview.md` — 了解项目定位和结构。
|
||
2. **Architecture**: `01-architecture-map.md` — 理解 7+ 进程的交互方式。
|
||
3. **Data**: `04-data-model.md` — 任何 DB 相关工作的必读；注意时间戳格式不统一问题。
|
||
4. **API**: `03-api-contracts.md` — 前端开发或 API 对接时参考。
|
||
5. **Module detail**: `02-module-cheatsheet.md` — 修改特定文件前的参考。
|
||
6. **Ops**: `05-build-run-test.md` — 部署和运维操作。
|
||
7. **Concepts**: `07-glossary.md` — 不熟悉量化术语时查阅。
|
||
8. **Risks**: `99-open-questions.md` — 开始开发前必读，了解已知风险点。
|
||
|
||
## Coverage Tier
|
||
**Deep** — 包含完整的模块签名读取、核心业务模块深度阅读（signal_engine 全文、evaluate_signal 评分逻辑、backtest.py）、构建运行指南、决策日志、术语表和开放问题。
|
||
|
||
## Key Facts for AI Agents
|
||
- **Signal engine is the core**: `backend/signal_engine.py` — change with care; affects all trading modes.
|
||
- **Strategy tuning via JSON**: modify `backend/strategies/v51_baseline.json` or `v52_8signals.json` to change signal weights/thresholds without code changes.
|
||
- **No ORM**: raw SQL via `asyncpg`/`psycopg2`; schema in `db.py:SCHEMA_SQL`.
|
||
- **Auth is custom JWT**: no third-party auth library; hand-rolled HMAC-SHA256 in `auth.py`.
|
||
- **`TRADE_ENV=testnet` default**: production use requires explicit env override + strong JWT_SECRET.
|
||
- **Dual timestamp formats**: `ts` = Unix seconds, `time_ms`/`entry_ts`/`timestamp_ms` = Unix milliseconds — do not confuse.
|
||
|
||
## Generation Timestamp
|
||
2026-03-03T00:00:00 (UTC)
|