外观
合约手册 / TGEX KNOWLEDGE BASE
系统架构
本页回答三件事：合约系统分成哪几层、各组件管什么、持仓与保证金的权威态落在哪里。业务结果见[业务概述](/pages/0801)；规则与对象见[交易规则](/pages/0803)、[核心设计](/pages/0804)。
| 图例（读后文流程时沿用） | 含义 |
|---|---|
| 同步主路径 | 开仓 / 平仓 / 撤单 / 查询要等委托→撮合给出结果 |
| 异步旁路 | 深度与成交推送、标记价刷新、强平扫描、资金费、落库；不挡开平仓回包 |
范围说明：本文描述平台永续合约平时交易的 V1 主路径。期权、外部期货绑定不在本图。热数据见缓存总览。
设计取舍
- 受理与撮合分离：合约委托负责校验与编排；撮合持有订单簿、合约钱包与持仓热数据，真正改占用与仓位。
- 交易热路径权威在撮合进程内：内存 + Redis 热态，MySQL 异步落库，不替代运行中的权威钱包 / 持仓。
- 行情产出标记 / 指数，撮合消费后做风控：强平扫描由标记价（及风险配置）驱动，不是用户下单 RPC 的同步步骤。
- 资金费与划转走旁路：与开平仓同步链分开；到账、结算通过消息进入撮合改账通道。
因此合约比现货多了「持仓 + 保证金 + 标记价风控」三条轴；不要把合约撮合理解成「只比价的现货撮合换皮」。
分层与职责
| 层 | 组件 | 职责 |
|---|---|---|
| 接入层 | 应用网关 | App / 网页 / API：开平仓、撤单、持仓与杠杆查询、行情订阅 |
| 合约核心 | 委托 · 撮合 · 行情 | 受理校验、撮合与热状态、指数/标记与推送 |
| 协同服务 | 用户 · 币种 · 账务 | 可交易态、合约产品与杠杆配置、现货↔合约资金协同 |
| 基础设施 | 消息队列 · 存储 | 深度/成交/标记价/强平等消息；热缓冲与冷库 |
合约核心
| 组件 | 职责 | 边界 |
|---|---|---|
| 合约委托 | 入参与产品规则校验；编排调撮合；撤单、持仓查询、止盈止损等门面 | 受理成功 ≠ 已全部成交；不持订单簿权威 |
| 合约撮合 | 订单簿与事件链；合约账户 / 持仓热缓存；成交改仓；消费标记价做强平扫描 | 交易与风控当下的钱包、持仓权威在此 |
| 合约行情 | 指数 / 标记、盘口、成交、K 线；WS / 推送 | 产出价格与展示；强平执行仍在撮合 |
协同服务
| 组件 | 在主路径上的位置 |
|---|---|
| 用户服务 | 委托校验：用户能否交易 |
| 币种 / 产品配置 | 合约交易对、杠杆档、涨跌幅等 |
| 账务服务 | 现货与合约账户间划转、费用流水等；不挡开平仓同步主链 |
模块级清单见功能全景。
主路径与旁路
同步主路径
用户 / 机器人 → 网关 → 合约委托（校验）→ 合约撮合（占用 / 改仓 / 进簿）→ 回包回包表示委托已受理（开仓占用保证金或平仓占用可平数量等已按规则处理）。是否全部成交看撮合后续。见开仓主流程、平仓主流程。
异步旁路
| 旁路 | 路径 | 文档 |
|---|---|---|
| 深度 / 成交 | 撮合 → MQ → 行情 → 客户端 | 行情推送流程 |
| 指数 / 标记价 | 行情计算 → MQ → 撮合刷新 → 可能触发强平扫描 | 强平与清算 |
| 强平执行 | 撮合强平队列 → 系统强平单 → 改仓与账户 | 强平与清算 |
| 资金协同 | 账务 / 划转消息 → 撮合改合约钱包 | 保证金与资金协同 |
| 落库 | 撮合热态 → Redis → 异步 MySQL | 缓存与存储说明见缓存总览 |
职责对照速查
| 问题 | 答案 |
|---|---|
| 谁给可追踪的委托编号？ | 合约委托（编排撮合受理成功后） |
| 谁改持仓数量与开仓均价？ | 合约撮合（成交时） |
| 合约账户可用 / 占用以谁为准？ | 撮合进程内合约账户热缓存 |
| 谁算标记价？谁据标记价强平？ | 行情产出；撮合扫描并执行 |
| 谁推盘口与持仓相关展示？ | 行情（异步）；持仓权威仍在撮合 |
工程对照
| 图上名称 | 工程 | 关注点 |
|---|---|---|
| 应用网关 | coinex-app（/contract/*） | 接入与转发 |
| 合约委托 | coinex-contract-entrust | 校验、编排、查询 |
| 合约撮合 | coinex-contract-match | 订单簿、钱包/持仓热缓存、强平 |
| 合约行情 | coinex-contract-market | 指数/标记、盘口、推送 |
| 账务服务 | coinex-account | 划转与流水协同 |
| 币种 / 产品 | coinex-coin 等 | 合约产品与杠杆配置 |
网关上另有外部期货类入口时，与本文平台永续主路径分开，不要混读。
读后续文档时用得上的事实
- 开平仓交易模式常见：开多、开空、平多、平空。
- 保证金模式常见：逐仓、全仓；杠杆在开仓校验中受限。
- 强平是标记价旁路触发的系统单，与用户主动平仓分流。