查询 API

Assiah 提供丰富的邮箱查询与操作方法，涵盖邮件查询、操作、偏好设置、黑名单和管理员功能。所有方法返回 CompletableFuture。

邮箱查询

方法	返回值	说明
queryMailbox(query: MailboxQuery)	CompletableFuture<List<Mail>>	分页查询邮箱
getMail(ownerId: UUID, mailId: String)	CompletableFuture<Mail?>	获取邮件详情
getMailThread(ownerId: UUID, mailId: String)	CompletableFuture<List<Mail>>	获取邮件会话链
getUnreadCount(ownerId: UUID)	CompletableFuture<Long>	获取未读邮件数量

分页查询

import kim.hhhhhy.assiah.api.AssiahAPI

// 构造器方式
val query = MailboxQuery(
    ownerId = playerUUID,
    folder = MailFolder.INBOX,
    page = 1,
    pageSize = 20
)
AssiahAPI.queryMailbox(query).thenAccept { mails ->
    mails.forEach { println("${it.title} - ${it.sender}") }
}

DSL 方式

import kim.hhhhhy.assiah.api.dsl.*

AssiahAPI.queryMailbox(playerUUID) {
    folder = MailFolder.INBOX
    page = 1
    pageSize = 20
    readStatus = ReadStatus.UNREAD  // 只查未读
}.thenAccept { mails ->
    // 处理结果
}

获取邮件详情与会话

// 获取单封邮件
AssiahAPI.getMail(playerUUID, mailId).thenAccept { mail ->
    if (mail != null) {
        println("标题: ${mail.title}")
        println("正文: ${mail.body}")
        println("附件数: ${mail.attachments.size}")
    }
}

// 获取邮件会话链（原始邮件 + 所有回复）
AssiahAPI.getMailThread(playerUUID, mailId).thenAccept { thread ->
    thread.forEach { println("[${it.timestamp}] ${it.title}") }
}

// 获取未读数
AssiahAPI.getUnreadCount(playerUUID).thenAccept { count ->
    println("未读邮件: $count")
}

邮件操作

方法	返回值	说明
claimMail(ownerId: UUID, mailId: String)	CompletableFuture<Boolean>	领取邮件附件
deleteMail(ownerId: UUID, mailId: String)	CompletableFuture<Boolean>	删除邮件（移入回收站）
restoreTrashMail(ownerId: UUID, mailId: String)	CompletableFuture<Boolean>	从回收站恢复邮件
archiveMail(ownerId: UUID, mailId: String)	CompletableFuture<Boolean>	归档邮件
markAsRead(ownerId: UUID, mailId: String)	CompletableFuture<Boolean>	标记为已读
markAsUnread(ownerId: UUID, mailId: String)	CompletableFuture<Boolean>	标记为未读
replyMail(ownerId: UUID, mailId: String, request: SendMailRequest)	CompletableFuture<SendResult>	回复邮件
forwardMail(ownerId: UUID, mailId: String, target: UUID)	CompletableFuture<SendResult>	转发邮件
batchOperate(ownerId: UUID, mailIds: List<String>, operation: String)	CompletableFuture<Int>	批量操作

基础操作

val ownerId = player.uniqueId

// 领取附件
AssiahAPI.claimMail(ownerId, mailId).thenAccept { success ->
    if (success) player.sendMessage("附件已领取")
}

// 删除邮件（移入回收站）
AssiahAPI.deleteMail(ownerId, mailId)

// 从回收站恢复
AssiahAPI.restoreTrashMail(ownerId, mailId)

// 归档
AssiahAPI.archiveMail(ownerId, mailId)

// 标记已读/未读
AssiahAPI.markAsRead(ownerId, mailId)
AssiahAPI.markAsUnread(ownerId, mailId)

回复与转发

// 回复邮件
val reply = SendMailRequest(
    sender = playerUUID,
    receiver = originalSenderUUID,
    title = "Re: 原始标题",
    body = "收到，谢谢！"
)
AssiahAPI.replyMail(playerUUID, originalMailId, reply)

// 转发邮件给其他玩家
AssiahAPI.forwardMail(playerUUID, mailId, targetUUID)

批量操作

// 批量标记已读
val mailIds = listOf("mail_1", "mail_2", "mail_3")
AssiahAPI.batchOperate(playerUUID, mailIds, "read").thenAccept { count ->
    println("成功操作 $count 封邮件")
}

// 支持的操作: "read", "unread", "delete", "archive", "claim"

偏好设置与黑名单

方法	返回值	说明
getPreference(ownerId: UUID)	CompletableFuture<Preference>	获取用户偏好设置
updatePreference(ownerId: UUID, preference: Preference)	CompletableFuture<Boolean>	更新偏好设置
listBlockedPlayers(ownerId: UUID)	CompletableFuture<List<UUID>>	获取黑名单列表
blockPlayer(ownerId: UUID, target: UUID)	CompletableFuture<Boolean>	拉黑玩家
unblockPlayer(ownerId: UUID, target: UUID)	CompletableFuture<Boolean>	取消拉黑

// 获取偏好设置
AssiahAPI.getPreference(playerUUID).thenAccept { pref ->
    println("通知开关: ${pref.notifyEnabled}")
}

// 更新偏好设置
AssiahAPI.updatePreference(playerUUID, Preference(
    notifyEnabled = true,
    autoClaimEnabled = false
))

// 黑名单管理
AssiahAPI.blockPlayer(playerUUID, targetUUID)
AssiahAPI.unblockPlayer(playerUUID, targetUUID)

AssiahAPI.listBlockedPlayers(playerUUID).thenAccept { blocked ->
    blocked.forEach { println("已拉黑: $it") }
}

管理员方法

方法	返回值	说明
inspectMailbox(ownerId: UUID)	CompletableFuture<List<Mail>>	管理员查看任意玩家邮箱
resendMail(mailId: String)	CompletableFuture<SendResult>	重新发送邮件
moveMailFolder(ownerId: UUID, mailId: String, folder: MailFolder)	CompletableFuture<Boolean>	移动邮件到指定文件夹

// 管理员查看任意玩家邮箱
AssiahAPI.inspectMailbox(targetUUID).thenAccept { mails ->
    mails.forEach { println("${it.title} - ${it.sender}") }
}

// 重新发送失败的邮件
AssiahAPI.resendMail(mailId)

// 移动邮件到指定文件夹
AssiahAPI.moveMailFolder(playerUUID, mailId, MailFolder.ARCHIVE)

枚举类型

MailFolder

值	说明
INBOX	收件箱
SENT	已发送
DRAFT	草稿箱
TRASH	回收站
ARCHIVE	归档

AttachmentType

值	说明
ITEM	物品附件
TEXT	文本附件
KETHER	Kether 脚本附件
CURRENCY	货币附件

SourceType

值	说明
PLAYER	玩家发送
SYSTEM	系统发送
BROADCAST	群发

RelationType

值	说明
ORIGINAL	原始邮件
REPLY	回复
FORWARD	转发

ClaimStatus

值	说明
UNCLAIMED	未领取
CLAIMED	已领取
NO_ATTACHMENT	无附件

ReadStatus

值	说明
READ	已读
UNREAD	未读