跳到主要内容

PRD-017 邮件系统

文档编号：PRD-017
版本：v1.0
状态：已通过
适用端：服务端 / 客户端
关联模块：RecordServer、MailManager、ItemManager

1. 背景与目标​

邮件承担系统补发、活动奖励、交易结算与玩家留言。当前存在附件过期未清理、批量领取重复发奖、附件满包丢失等问题。本 PRD 统一邮件类型、附件、过期、领取与删除。

2. 核心规则​

2.1 邮件类型​

类型发件人可删除附件过期
系统邮件系统是可带30 天
奖励邮件运营是可带30 天
交易邮件拍卖/交易是可带30 天
玩家邮件玩家是不可带7 天
补偿邮件GM是可带90 天

2.2 附件与领取​

  • 每封邮件最多 4 个附件。
  • 领取时校验背包空间，空间不足则整封不领取。
  • 支持一键领取所有可领取邮件，逐封事务处理。
  • 附件过期未领取，邮件删除且不补发（高价值邮件可配置延长）。

2.3 状态​

  • 未读/已读、有附件/无附件、已领取/未领取。
  • 已领取附件从邮件移除，邮件保留正文。
  • 删除有未领取附件的邮件需二次确认。

3. 服务端设计​

3.1 数据结构​

struct Mail {
    uint64_t mail_id;
    uint64_t role_id;
    uint8_t  type;
    uint32_t sender_id;
    std::string title, body;
    std::vector<MailAttachment> attachments;
    uint64_t expire_ms;
    bool     read;
    bool     claimed;
};

3.2 协议​

方向协议说明
S→CSC_MailList邮件列表
S→CSC_MailDetail邮件正文/附件
C→SCS_MailClaim领取单封
C→SCS_MailClaimAll一键领取
C→SCS_MailDelete删除
C→SCS_MailRead标记已读
S→CSC_MailNew新邮件提醒

3.3 发送与领取​

发送：校验收件人/附件/过期时间 → 写 DB → 推送 SC_MailNew
领取：校验邮件归属/未领取/背包空间 → 扣附件 → 加背包 → 标记已领取 → 写日志
  • 发送附件使用事务，物品从来源扣除与邮件写入同时成功。
  • 领取按 mail_id 幂等，重复请求返回已领取。
  • 一键领取逐封处理，某封失败不影响其他邮件。

4. 客户端设计​

  • 邮件列表：发件人、标题、时间、附件图标、未读标记。
  • 详情：正文、附件格、领取/删除按钮。
  • 一键领取：显示可领取数量，领取后汇总弹窗。
  • 附件过期倒计时，剩余 3 天高亮。
  • 背包满时提示并保留邮件，不自动删除。

5. 配置​

Mail.xml：type、expire_days、max_attachments、can_reply、auto_delete。

6. 边界与异常​

场景处理
背包满领取拒绝，邮件保留
附件物品被删除发送时校验，领取时按替代物/邮件说明处理
重复领取幂等，不重复发奖
邮件过期定时清理，高价值邮件延期
玩家改名邮件按 role_id 绑定，不按名字
服务器重启从 DB 恢复，未领取状态不变

7. 验收标准​

  • 五类邮件发送、阅读、领取、删除正确。
  • 附件领取与背包事务一致，无复制/丢失。
  • 一键领取逐封处理，失败不影响其他。
  • 过期清理与倒计时准确。
  • 邮件日志可按 role_id/mail_id 追溯。