113 lines
6.1 KiB
Markdown
113 lines
6.1 KiB
Markdown
# 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 -> 广播行情)
|
||
```
|