# 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 -> 广播行情)
```