tdm_server_rust/entity/
reward.rs

1//! 奖励/悬赏实体 (Reward Entities)
2//!
3//! 定义组内奖励系统的全部数据结构，涵盖奖品定义、活动余额、
4//! 兑换记录、抽奖券、中奖结果和转账日志。
5//!
6//! ## 核心流程
7//!
8//! ```text
9//! 管理员创建活动 → 分配兑换/抽奖余额 → 组员用券兑换奖品或参与抽奖
10//! → 中奖者公布 → 管理员填写物流单号 → 奖品发放
11//! ```
12//!
13//! ## 券种
14//!
15//! - **兑换券 (exchange)**: 直接兑换指定奖品，先到先得
16//! - **抽奖券 (lucky)**: 投入奖池，活动结束时随机抽取中奖者
17//!
18//! ## 类型列表
19//!
20//! | 类型 | 用途 |
21//! |------|------|
22//! | [`Rewardtb`] | 奖品定义（名称、价格、类型） |
23//! | [`EventBalanceDto`] | 组员在某个活动的兑换/抽奖余额 |
24//! | [`RewardRecordResultDto`] | 兑换记录（含物流信息） |
25//! | [`RewardTicketResultDto`] | 抽奖券投入结果 |
26//! | [`RewardTicketTransferLog`] | 券转账日志 |
27
28use chrono::{DateTime, Utc};
29use serde::{Deserialize, Serialize};
30
31/// 奖品定义（对齐 Java `Rewardtb` / OpenAPI `rewardId` 等字段）
32#[derive(Debug, Clone, Serialize, Deserialize)]
33#[serde(rename_all = "camelCase")]
34pub struct Rewardtb {
35    /// 奖品 ID
36    pub reward_id: Option<i32>,
37    /// 奖品名称
38    pub name: Option<String>,
39    /// 奖品图片 URL
40    pub image: Option<String>,
41    /// 所属活动名称
42    pub from_event: Option<String>,
43    /// 所属活动 ID
44    pub from_event_id: Option<i32>,
45    /// 奖励类别：1 全员发放 / 2 兑换 / 3 抽奖
46    pub reward_category: Option<i16>,
47    /// 实物类别：1 书籍 / 2 周边 / 3 游戏
48    pub physical_category: Option<i16>,
49    /// 兑换所需奖券数量
50    pub price: Option<i32>,
51    /// 入库总量（-1 为无限）
52    pub total_number: Option<i32>,
53    /// 库存（-1 为无限）
54    pub stock: Option<i32>,
55    /// 兑换截止日期（对齐 Java `yyyy-MM-dd'T'HH:mm:ssZ`）
56    pub dead_line: Option<String>,
57    /// 赞助者
58    pub sponsor: Option<String>,
59    /// 赞助者 ID
60    pub sponsor_id: Option<i32>,
61}
62
63/// 活动余额
64///
65/// 组员在指定活动中的兑换券和抽奖券余额。
66/// 用于前端展示"我的余额"页面。
67///
68/// ## 字段说明
69///
70/// | 字段 | 说明 |
71/// |------|------|
72/// | `user_id` | 组员 ID |
73/// | `event_id` | 活动 ID |
74/// | `exchange_balance` | 剩余兑换券数 |
75/// | `lucky_balance` | 剩余抽奖券数 |
76/// | `total_tickets` | 累计获得的总券数 |
77///
78/// ## 对应 Java 类
79///
80/// Java `EventBalanceDTO`。
81#[derive(Debug, Clone, Serialize, Deserialize)]
82#[serde(rename_all = "camelCase")]
83pub struct EventBalanceDto {
84    /// 组员 ID
85    pub user_id: i32,
86    /// 活动 ID
87    pub event_id: i32,
88    /// 剩余兑换券数
89    pub exchange_balance: Option<i32>,
90    /// 剩余抽奖券数
91    pub lucky_balance: Option<i32>,
92    /// 累计获得的总券数
93    pub total_tickets: Option<i32>,
94}
95
96/// 兑换记录
97///
98/// 记录组员用兑换券换取奖品的每一笔交易。
99/// 包含奖品信息、兑换时间和物流单号。
100///
101/// ## 字段说明
102///
103/// | 字段 | 说明 |
104/// |------|------|
105/// | `reward_record_id` | 兑换记录 ID |
106/// | `reward_id` | 奖品 ID |
107/// | `exchange_time` | 兑换时间 |
108/// | `exchange_number` | 兑换数量 |
109/// | `tracking_number` | 物流单号（发货后由管理员填写） |
110/// | `reward_name` | 奖品名称（冗余，便于展示） |
111/// | `reward_image` | 奖品图片 URL |
112/// | `get_method` | 获取方式编号 |
113#[derive(Debug, Clone, Serialize, Deserialize, Default)]
114#[serde(rename_all = "camelCase")]
115pub struct RewardRecordResultDto {
116    /// 兑换记录 ID
117    pub reward_record_id: Option<i32>,
118    /// 奖品 ID
119    pub reward_id: Option<i32>,
120    /// 兑换时间
121    pub exchange_time: Option<DateTime<Utc>>,
122    /// 兑换数量
123    pub exchange_number: Option<i32>,
124    /// 物流单号（管理员填写）
125    pub tracking_number: Option<String>,
126    /// 奖品名称（冗余展示字段）
127    pub reward_name: Option<String>,
128    /// 奖品图片 URL
129    pub reward_image: Option<String>,
130    /// 获取方式编号
131    pub get_method: Option<i32>,
132}
133
134/// 抽奖券投入结果
135///
136/// 记录组员在某个奖品上投入的抽奖券数和当前状态。
137///
138/// ## 字段说明
139///
140/// | 字段 | 说明 |
141/// |------|------|
142/// | `ticket_number` | 投入的券数 |
143/// | `member_id` | 组员 ID |
144/// | `reward_id` | 目标奖品 ID |
145/// | `status` | 状态（0-参与中，1-已开奖） |
146/// | `reward_name` | 奖品名称 |
147/// | `reward_image` | 奖品图片 URL |
148/// | `gacha_time` | 最晚加注时间（开奖截止时间） |
149#[derive(Debug, Clone, Serialize, Deserialize, Default)]
150#[serde(rename_all = "camelCase")]
151pub struct RewardTicketResultDto {
152    /// 投入的抽奖券数
153    pub ticket_number: Option<i32>,
154    /// 组员 ID
155    pub member_id: Option<i32>,
156    /// 目标奖品 ID
157    pub reward_id: Option<i32>,
158    /// 参与状态
159    pub status: Option<i32>,
160    /// 奖品名称
161    pub reward_name: Option<String>,
162    /// 奖品图片 URL
163    pub reward_image: Option<String>,
164    /// 开奖截止时间
165    pub gacha_time: Option<DateTime<Utc>>,
166}
167
168/// 抽奖券详情
169///
170/// 单张抽奖券的详细追踪信息，包括来源活动和当前状态。
171///
172/// ## 对应 Java 类
173///
174/// Java `RewardTicketsDetailDTO`。
175#[derive(Debug, Clone, Serialize, Deserialize)]
176#[serde(rename_all = "camelCase")]
177pub struct RewardTicketsDetailDto {
178    /// 奖券唯一 ID
179    pub reward_ticket_id: Option<String>,
180    /// 来源活动 ID
181    pub from_event_id: Option<i32>,
182    /// 关联奖品 ID
183    pub reward_id: Option<i32>,
184    /// 奖券状态
185    pub status: Option<i32>,
186}
187
188/// 中奖者信息
189///
190/// 活动开奖后记录每个奖品的中奖组员。
191///
192/// ## 对应 Java 类
193///
194/// Java `RewardWinnerDTO`。
195#[derive(Debug, Clone, Serialize, Deserialize)]
196#[serde(rename_all = "camelCase")]
197pub struct RewardWinnerDto {
198    /// 中奖组员 ID
199    pub member_id: i32,
200    /// 中奖组员名
201    pub member_name: Option<String>,
202    /// 中奖的奖券 ID
203    pub ticket_id: Option<String>,
204}
205
206/// 奖励账户基本信息
207///
208/// 组员余额账户的轻量视图，用于快速查询组员是否已开户。
209///
210/// ## 对应 Java 类
211///
212/// Java `RewardAccountBasicInfoDTO`。
213#[derive(Debug, Clone, Serialize, Deserialize)]
214#[serde(rename_all = "camelCase")]
215pub struct RewardAccountBasicInfoDto {
216    /// 组员 ID
217    pub member_id: Option<i32>,
218    /// 余额账户 ID
219    pub balance_account_id: Option<i32>,
220}
221
222/// 券转账请求
223///
224/// 组员将自己的兑换券或抽奖券转给其他组员。
225///
226/// ## 对应 Java 类
227///
228/// Java `RewardTicketTransferRequest`。
229#[derive(Debug, Clone, Deserialize)]
230#[serde(rename_all = "camelCase")]
231pub struct RewardTicketTransferRequest {
232    /// 活动 ID
233    pub event_id: i32,
234    /// 券类型（1-兑换券，2-抽奖券）
235    pub ticket_type: i32,
236    /// 接收方组员 ID
237    pub target_member_id: i32,
238    /// 转账数量
239    pub amount: i32,
240}
241
242/// 券转账日志
243///
244/// 记录每一笔券转账的双方、活动、数量和时间的完整审计日志。
245///
246/// ## 字段说明
247///
248/// | 字段 | 说明 |
249/// |------|------|
250/// | `log_id` | 日志自增 ID，插入后生成 |
251/// | `from_member_id` | 转出方组员 ID |
252/// | `to_member_id` | 接收方组员 ID |
253/// | `event_id` | 所属活动 ID |
254/// | `ticket_type` | 券类型 |
255/// | `amount` | 转账数量 |
256/// | `transfer_time` | 转账时间戳 |
257#[derive(Debug, Clone, Serialize, Deserialize)]
258#[serde(rename_all = "camelCase")]
259pub struct RewardTicketTransferLog {
260    /// 日志自增 ID
261    pub log_id: Option<i64>,
262    /// 转出方组员 ID
263    pub from_member_id: i32,
264    /// 接收方组员 ID
265    pub to_member_id: i32,
266    /// 所属活动 ID
267    pub event_id: i32,
268    /// 券类型（1-兑换，2-抽奖）
269    pub ticket_type: i32,
270    /// 转账数量
271    pub amount: i32,
272    /// 转账时间戳
273    pub transfer_time: Option<DateTime<Utc>>,
274}
tdm_server_rust/entity/reward.rs

tdm_server_rust/entity/
reward.rs
