Line data Source code
1 : /**
2 : * @file account_manager.hpp
3 : * @brief 账户管理模块
4 : *
5 : * 提供账户的创建、查询、资金冻结/释放等功能。
6 : * 支持与存储层集成进行持久化。
7 : */
8 :
9 : #pragma once
10 :
11 : #include <string>
12 : #include <unordered_map>
13 : #include <optional>
14 : #include <mutex>
15 : #include <vector>
16 : #include "app/model/account.hpp"
17 :
18 : namespace fix40 {
19 :
20 : // 前向声明
21 : class IStore;
22 :
23 : /**
24 : * @class AccountManager
25 : * @brief 账户管理器
26 : *
27 : * 负责账户的创建、查询、资金冻结/释放等操作。
28 : * 支持与IStore接口集成进行数据持久化。
29 : *
30 : * @par 线程安全
31 : * 所有公共方法都是线程安全的，使用互斥锁保护内部数据。
32 : *
33 : * @par 保证金生命周期
34 : * 1. 下单时：freezeMargin() - 冻结保证金
35 : * 2. 成交时：confirmMargin() - 冻结转占用
36 : * 3. 撤单/拒绝时：unfreezeMargin() - 释放冻结
37 : * 4. 平仓时：releaseMargin() - 释放占用
38 : *
39 : * @par 使用示例
40 : * @code
41 : * AccountManager mgr;
42 : *
43 : * // 创建账户
44 : * auto account = mgr.createAccount("user001", 1000000.0);
45 : *
46 : * // 下单时冻结保证金
47 : * mgr.freezeMargin("user001", 50000.0);
48 : *
49 : * // 成交时转为占用保证金
50 : * mgr.confirmMargin("user001", 50000.0, 50000.0);
51 : *
52 : * // 平仓时释放占用保证金
53 : * mgr.releaseMargin("user001", 50000.0);
54 : * @endcode
55 : */
56 : class AccountManager {
57 : public:
58 : // -------------------------------------------------------------------------
59 : // 构造函数
60 : // -------------------------------------------------------------------------
61 :
62 : /**
63 : * @brief 默认构造函数
64 : *
65 : * 创建不带持久化的账户管理器。
66 : */
67 : AccountManager();
68 :
69 : /**
70 : * @brief 带存储接口的构造函数
71 : *
72 : * @param store 存储接口指针（可为nullptr）
73 : *
74 : * @note 当 store 不为空时，会在构造阶段从存储中加载已存在的账户，
75 : * 用于服务端重启后的资金状态恢复。
76 : */
77 : explicit AccountManager(IStore* store);
78 :
79 : /**
80 : * @brief 析构函数
81 : */
82 552 : ~AccountManager() = default;
83 :
84 : // 禁用拷贝
85 : AccountManager(const AccountManager&) = delete;
86 : AccountManager& operator=(const AccountManager&) = delete;
87 :
88 : // -------------------------------------------------------------------------
89 : // 账户管理
90 : // -------------------------------------------------------------------------
91 :
92 : /**
93 : * @brief 创建账户
94 : *
95 : * 创建一个新的虚拟账户，初始余额和可用资金相等。
96 : *
97 : * @param accountId 账户ID
98 : * @param initialBalance 初始余额
99 : * @return 创建的账户
100 : *
101 : * @note 如果账户已存在，返回现有账户
102 : */
103 : Account createAccount(const std::string& accountId, double initialBalance);
104 :
105 : /**
106 : * @brief 获取账户
107 : *
108 : * @param accountId 账户ID
109 : * @return 账户信息，不存在时返回 std::nullopt
110 : */
111 : std::optional<Account> getAccount(const std::string& accountId) const;
112 :
113 : /**
114 : * @brief 检查账户是否存在
115 : *
116 : * @param accountId 账户ID
117 : * @return 存在返回 true
118 : */
119 : bool hasAccount(const std::string& accountId) const;
120 :
121 : /**
122 : * @brief 获取所有账户ID
123 : *
124 : * @return 账户ID列表
125 : */
126 : std::vector<std::string> getAllAccountIds() const;
127 :
128 : /**
129 : * @brief 获取账户数量
130 : *
131 : * @return 账户数量
132 : */
133 : size_t size() const;
134 :
135 : // -------------------------------------------------------------------------
136 : // 保证金操作
137 : // -------------------------------------------------------------------------
138 :
139 : /**
140 : * @brief 冻结保证金（下单时）
141 : *
142 : * 从可用资金中冻结指定金额作为挂单保证金。
143 : *
144 : * @param accountId 账户ID
145 : * @param amount 冻结金额
146 : * @return 成功返回 true，资金不足或账户不存在返回 false
147 : *
148 : * @par 资金变化
149 : * - available -= amount
150 : * - frozenMargin += amount
151 : */
152 : bool freezeMargin(const std::string& accountId, double amount);
153 :
154 : /**
155 : * @brief 释放冻结保证金（撤单/拒绝时）
156 : *
157 : * 将冻结的保证金释放回可用资金。
158 : *
159 : * @param accountId 账户ID
160 : * @param amount 释放金额
161 : * @return 成功返回 true，账户不存在返回 false
162 : *
163 : * @par 资金变化
164 : * - available += amount
165 : * - frozenMargin -= amount
166 : */
167 : bool unfreezeMargin(const std::string& accountId, double amount);
168 :
169 : /**
170 : * @brief 确认保证金（成交时：冻结转占用）
171 : *
172 : * 将冻结的保证金转为占用保证金。
173 : *
174 : * @param accountId 账户ID
175 : * @param frozenAmount 原冻结金额
176 : * @param usedAmount 实际占用金额（可能与冻结金额不同）
177 : * @return 成功返回 true，账户不存在返回 false
178 : *
179 : * @par 资金变化
180 : * - frozenMargin -= frozenAmount
181 : * - usedMargin += usedAmount
182 : * - available += (frozenAmount - usedAmount) // 多冻结的部分返还
183 : */
184 : bool confirmMargin(const std::string& accountId, double frozenAmount, double usedAmount);
185 :
186 : /**
187 : * @brief 释放占用保证金（平仓时）
188 : *
189 : * 平仓后释放占用的保证金。
190 : *
191 : * @param accountId 账户ID
192 : * @param amount 释放金额
193 : * @return 成功返回 true，账户不存在返回 false
194 : *
195 : * @par 资金变化
196 : * - usedMargin -= amount
197 : * - available += amount
198 : */
199 : bool releaseMargin(const std::string& accountId, double amount);
200 :
201 : // -------------------------------------------------------------------------
202 : // 盈亏操作
203 : // -------------------------------------------------------------------------
204 :
205 : /**
206 : * @brief 更新持仓盈亏
207 : *
208 : * 更新账户的浮动盈亏，同时更新可用资金。
209 : *
210 : * @param accountId 账户ID
211 : * @param profit 新的持仓盈亏值（不是增量）
212 : * @return 成功返回 true，账户不存在返回 false
213 : */
214 : bool updatePositionProfit(const std::string& accountId, double profit);
215 :
216 : /**
217 : * @brief 记录平仓盈亏
218 : *
219 : * 平仓时记录已实现盈亏，更新余额。
220 : *
221 : * @param accountId 账户ID
222 : * @param profit 平仓盈亏（正为盈利，负为亏损）
223 : * @return 成功返回 true，账户不存在返回 false
224 : *
225 : * @par 资金变化
226 : * - balance += profit
227 : * - closeProfit += profit
228 : * - available += profit
229 : */
230 : bool addCloseProfit(const std::string& accountId, double profit);
231 :
232 : // -------------------------------------------------------------------------
233 : // 清理方法
234 : // -------------------------------------------------------------------------
235 :
236 : /**
237 : * @brief 清空所有账户
238 : */
239 : void clear();
240 :
241 : private:
242 : /**
243 : * @brief 持久化账户（内部方法）
244 : *
245 : * @param account 要持久化的账户
246 : */
247 : void persistAccount(const Account& account);
248 :
249 : /// 账户映射表：accountId -> Account
250 : std::unordered_map<std::string, Account> accounts_;
251 :
252 : /// 存储接口（可为nullptr）
253 : IStore* store_;
254 :
255 : /// 互斥锁，保护 accounts_
256 : mutable std::mutex mutex_;
257 : };
258 :
259 : } // namespace fix40
|
