Line data Source code
1 : /**
2 : * @file account.hpp
3 : * @brief 虚拟交易账户数据结构
4 : *
5 : * 定义模拟交易系统中的账户数据结构，包含资金、保证金、盈亏等信息。
6 : * 用于追踪用户的虚拟资金状态。
7 : */
8 :
9 : #pragma once
10 :
11 : #include <string>
12 : #include <cstdint>
13 : #include <chrono>
14 :
15 : namespace fix40 {
16 :
17 : // ============================================================================
18 : // 账户结构
19 : // ============================================================================
20 :
21 : /**
22 : * @struct Account
23 : * @brief 虚拟交易账户
24 : *
25 : * 用户的虚拟资金账户，包含余额、可用资金、冻结保证金等信息。
26 : * 系统通过此结构追踪用户的资金状态和交易表现。
27 : *
28 : * @par 资金关系
29 : * - 可用资金 = 余额 + 持仓盈亏 - 冻结保证金 - 占用保证金
30 : * - 动态权益 = 余额 + 持仓盈亏
31 : * - 风险度 = 占用保证金 / 动态权益
32 : *
33 : * @par 使用示例
34 : * @code
35 : * Account account;
36 : * account.accountId = "user001";
37 : * account.balance = 1000000.0;
38 : * account.available = 1000000.0;
39 : *
40 : * double equity = account.getDynamicEquity();
41 : * double risk = account.getRiskRatio();
42 : * @endcode
43 : */
44 : struct Account {
45 : // -------------------------------------------------------------------------
46 : // 标识符
47 : // -------------------------------------------------------------------------
48 : std::string accountId; ///< 账户ID（唯一标识）
49 :
50 : // -------------------------------------------------------------------------
51 : // 资金信息
52 : // -------------------------------------------------------------------------
53 : double balance; ///< 账户余额（静态权益，初始资金 + 平仓盈亏）
54 : double available; ///< 可用资金（可用于开仓的资金）
55 : double frozenMargin; ///< 冻结保证金（挂单占用，尚未成交）
56 : double usedMargin; ///< 占用保证金（持仓占用，已成交）
57 :
58 : // -------------------------------------------------------------------------
59 : // 盈亏信息
60 : // -------------------------------------------------------------------------
61 : double positionProfit; ///< 持仓盈亏（浮动盈亏，根据最新价实时计算）
62 : double closeProfit; ///< 平仓盈亏（已实现盈亏，累计值）
63 :
64 : // -------------------------------------------------------------------------
65 : // 时间戳
66 : // -------------------------------------------------------------------------
67 : std::chrono::system_clock::time_point updateTime; ///< 最后更新时间
68 :
69 : // -------------------------------------------------------------------------
70 : // 构造函数
71 : // -------------------------------------------------------------------------
72 :
73 : /**
74 : * @brief 默认构造函数
75 : *
76 : * 初始化所有数值字段为 0，时间戳为当前时间。
77 : */
78 1453 : Account()
79 2906 : : balance(0.0)
80 1453 : , available(0.0)
81 1453 : , frozenMargin(0.0)
82 1453 : , usedMargin(0.0)
83 1453 : , positionProfit(0.0)
84 1453 : , closeProfit(0.0)
85 1453 : , updateTime(std::chrono::system_clock::now())
86 1453 : {}
87 :
88 : /**
89 : * @brief 带初始余额的构造函数
90 : *
91 : * @param id 账户ID
92 : * @param initialBalance 初始余额（同时初始化余额和可用资金）
93 : *
94 : * @note 新账户的可用资金等于初始余额，因为没有冻结或占用的保证金
95 : */
96 776 : Account(const std::string& id, double initialBalance)
97 776 : : accountId(id)
98 776 : , balance(initialBalance)
99 776 : , available(initialBalance)
100 776 : , frozenMargin(0.0)
101 776 : , usedMargin(0.0)
102 776 : , positionProfit(0.0)
103 776 : , closeProfit(0.0)
104 776 : , updateTime(std::chrono::system_clock::now())
105 776 : {}
106 :
107 : // -------------------------------------------------------------------------
108 : // 计算方法
109 : // -------------------------------------------------------------------------
110 :
111 : /**
112 : * @brief 计算动态权益
113 : *
114 : * 动态权益 = 余额 + 持仓盈亏
115 : * 反映账户的实时价值，包含未实现的浮动盈亏。
116 : *
117 : * @return 动态权益值
118 : */
119 311 : double getDynamicEquity() const {
120 311 : return balance + positionProfit;
121 : }
122 :
123 : /**
124 : * @brief 计算风险度
125 : *
126 : * 风险度 = 占用保证金 / 动态权益
127 : * 用于评估账户的风险水平，值越高风险越大。
128 : *
129 : * @return 风险度（0.0 ~ 1.0+），动态权益为0或负时返回0
130 : *
131 : * @note 当动态权益 <= 0 时返回 0，避免除零错误和负值风险度
132 : */
133 106 : double getRiskRatio() const {
134 106 : double equity = getDynamicEquity();
135 106 : return equity > 0 ? usedMargin / equity : 0.0;
136 : }
137 :
138 : /**
139 : * @brief 重新计算可用资金
140 : *
141 : * 可用资金 = 余额 + 持仓盈亏 - 冻结保证金 - 占用保证金
142 : * 在资金状态变化后调用此方法更新可用资金。
143 : */
144 108 : void recalculateAvailable() {
145 108 : available = balance + positionProfit - frozenMargin - usedMargin;
146 108 : }
147 :
148 : // -------------------------------------------------------------------------
149 : // 比较操作符（用于测试）
150 : // -------------------------------------------------------------------------
151 :
152 : /**
153 : * @brief 相等比较操作符
154 : *
155 : * 比较两个账户的所有字段是否相等（不包括时间戳）。
156 : * 主要用于属性测试中的 round-trip 验证。
157 : *
158 : * @param other 另一个账户
159 : * @return 如果所有字段相等则返回 true
160 : *
161 : * @note 此操作符使用精确比较，适用于序列化/反序列化的 round-trip 测试。
162 : * 如需比较计算结果，请使用带容差的比较方法。
163 : */
164 304 : bool operator==(const Account& other) const {
165 304 : return accountId == other.accountId &&
166 303 : balance == other.balance &&
167 303 : available == other.available &&
168 303 : frozenMargin == other.frozenMargin &&
169 303 : usedMargin == other.usedMargin &&
170 910 : positionProfit == other.positionProfit &&
171 607 : closeProfit == other.closeProfit;
172 : }
173 :
174 : /**
175 : * @brief 不等比较操作符
176 : *
177 : * @param other 另一个账户
178 : * @return 如果任意字段不相等则返回 true
179 : */
180 1 : bool operator!=(const Account& other) const {
181 1 : return !(*this == other);
182 : }
183 : };
184 :
185 : } // namespace fix40
|
