fanziqi 22787b3e0a docs: add AI documentation suite and comprehensive code review report

- 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

2026-03-03 19:01:18 +08:00

3.4 KiB

Raw Blame History

generated_by	version	created	last_updated	source_commit	coverage
repo-insight	1	2026-03-03	2026-03-03	`0d9dffa`	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	Project purpose, tech stack, repo layout, entry points, environment variables
01-architecture-map.md	Multi-process architecture, component diagram, signal pipeline data flow, risk guard rules, frontend polling
02-module-cheatsheet.md	Module-by-module index: role, public interfaces, dependencies for all 20 backend + 15 frontend files
03-api-contracts.md	All REST endpoints, auth flows, request/response shapes, error conventions
04-data-model.md	All PostgreSQL tables, columns, partitioning strategy, storage design decisions
05-build-run-test.md	构建/运行/部署命令，环境变量，PM2 配置，回测和模拟盘操作
06-decision-log.md	9 项关键技术决策：PG 消息总线、循环间隔、双写、分区、自研 JWT 等
07-glossary.md	交易术语（CVD/ATR/R/tier）+ 工程术语（paper trading/warmup/circuit break）
99-open-questions.md	11 个未解决问题：users 表双定义冲突、依赖不完整、硬编码密码、无测试等

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)

3.4 KiB Raw Blame History Unescape Escape