wtf-backend/ARCHITECTURE.md

WTFX Backend Architecture Rules (后端架构铁律)

核心定位：WTFX 采用 Python + FastAPI + PostgreSQL + Redis 的模块化单体 (Modular Monolith) 架构。 适用对象：所有开发者与 AI Coding Agent。在编写或修改任何后端代码之前，必须严格遵守本规范。

---

1. 架构核心铁律 (Non-Negotiable Rules)

1. 【分层单向依赖】：
   • 依赖调用链严格为：API Route -> Domain Service -> Repository -> Database/Infrastructure。
   • 严禁反向或跨层调用（如 Route 直连 DB，或 Repo 调用 Service）。
2. 【禁止 Route 直连数据库】：
   • API 路由层（app/api/）只允许做：入参校验 (Pydantic Schema)、鉴权依赖注入、调用 Domain Service、返回标准响应。
   • 严禁在 Route 中执行 SQL 或 ORM 查询。
3. 【Domain 纯净性】：
   • 业务领域层（app/domains/）代表纯粹的业务大脑，严禁导入 FastAPI 或任何 HTTP/WebSocket 相关的 Web 框架依赖。
4. 【资金与状态变更强制走 Ledger】：
   • 严禁直接执行 user.balance += amount 等无据操作。
   • 所有账户资金变动（充值、下注扣款、保证金冻结/解冻、手续费、获胜兑付）必须通过 LedgerService 生成不可变的复式记账流水 (LedgerEntry)。
5. 【外部第三方服务强制使用 Adapter 隔离】：
   • 链上 RPC、Hyperliquid、价格预言机等外部系统交互必须统一封装在 app/infrastructure/ 适配器中。
   • Domain 业务层只依赖抽象接口（如 TradingProvider / ChainClient），不感知底层具体 API 细节。
6. 【事件总线驱动，解耦 WebSocket】：
   • 业务状态变更（如订单成交、市场毕业）只向 EventBus 发送领域事件。
   • WebSocket 模块（app/ws/）独立订阅事件并广播给在线客户端，业务逻辑层严禁直接依赖 WS 连接对象。
7. 【Model 与 Schema 严格分离】：
   • models/ 映射数据库实体，schemas/ 定义 API 输入输出结构体。
   • 严禁将数据库 Model 直接作为 API Response 返回，防止敏感字段（密码哈希、内部风控分等）意外泄露。

---

2. 目录职责分工

wtf-backend/
├── app/
│   ├── main.py                     # 应用入口与生命周期管理 (Lifespan)
│   ├── config.py                   # Pydantic Settings 环境变量配置
│   ├── logging.py                  # 结构化日志配置
│   │
│   ├── api/                        # HTTP 接口接入层 (只做请求解析与转发)
│   │   ├── dependencies.py         # 共享依赖注入 (DB Session, 当前用户, Auth)
│   │   └── routes/                 # 各业务模块的路由入口
│   │       ├── auth.py             # Web3 SIWE 钱包登录与 JWT
│   │       ├── markets.py          # 预测市场查询与建盘
│   │       ├── orders.py           # 交易下单与撤单
│   │       ├── positions.py        # 用户持仓查询
│   │       └── wallet.py           # 充值、提现与流水
│   │
│   ├── domains/                    # 业务领域大脑 (纯业务逻辑，无 Web 依赖)
│   │   ├── market/                 # 市场状态机与联合曲线规则
│   │   ├── trading/                # 交易撮合与风控检查
│   │   ├── ledger/                 # 【核心】不可变流水账本
│   │   ├── wallet/                 # 钱包余额状态管理
│   │   ├── settlement/             # 预测到期结算与兑付
│   │   └── user/                   # 用户信息与邀请返佣
│   │
│   ├── infrastructure/             # 外部世界适配层 (数据库、缓存、链上、三方 API)
│   │   ├── database/               # PostgreSQL 连接池与异步 Session 工厂
│   │   ├── redis/                  # Redis 缓存与 Streams 事件总线
│   │   ├── blockchain/             # EVM RPC 监听与合约调用客户端
│   │   └── external/               # Hyperliquid / CLOB 等外部交易适配器
│   │
│   ├── models/                     # SQLAlchemy 2.0 异步数据库实体
│   │   ├── market.py
│   │   ├── order.py
│   │   ├── position.py
│   │   ├── ledger.py
│   │   └── user.py
│   │
│   ├── schemas/                    # Pydantic v2 请求与响应数据传输对象 (DTO)
│   │   ├── market.py
│   │   ├── order.py
│   │   ├── ledger.py
│   │   └── common.py
│   │
│   └── ws/                         # WebSocket 实时网关 (行情推流与用户私有信道)
│       ├── manager.py              # 连接池与订阅频道管理
│       └── handlers.py             # WS 消息解析与心跳
│
├── migrations/                     # Alembic 数据库迁移脚本
├── tests/                          # 单元测试与集成测试
├── Dockerfile                      # 生产镜像构建文件
├── docker-compose.yml              # 本地开发与服务器运行编排
└── requirements.txt                # 锁定依赖项

---

3. 核心业务流程标准示例 (How to Write Code)

正确的下单流程示例 (Trading Flow):

[Client] ---> POST /api/v1/orders
                 │
                 ▼
          [orders.py (Route)]
                 │ (1. 解析 CreateOrderRequest Schema)
                 │ (2. 依赖注入 TradingService)
                 ▼
       [TradingService (Domain)]
                 │ (1. 风险检查 RiskCheck)
                 │ (2. 冻结资金: 调用 LedgerService.freeze_balance)
                 │ (3. 创建订单: 调用 OrderRepository.create)
                 │ (4. 抛出事件: EventBus.publish("OrderCreated"))
                 ▼
          [PostgreSQL] (Commit Transaction)
                 │
                 ▼
          [WS Gateway] (异步监听到 OrderCreated -> 广播行情)