DTO 与数据模型

DTO 是什么

DTO（Data Transfer Object）是 Dominion 暴露给附属的运行时数据视图。它们适合读取和展示，不是让附属绕过 Provider 直接改数据库的入口。

DominionDTO

DominionDTO 表示一个领地，常用字段如下：

方法	含义
getId()	领地 ID
getName()	领地名称
getOwner() / getOwnerDTO()	所有者 UUID / 玩家 DTO
getWorld() / getWorldUid()	当前世界对象 / 世界 UUID
getCuboid()	领地三维边界
getParentDomId()	父领地 ID；-1 表示没有父领地
getTpLocation()	传送点；未设置时返回领地中心位置
getJoinMessage() / getLeaveMessage()	进入和离开消息
getGroups() / getMembers()	组和成员列表
getServerId()	创建/管理该领地的服务器 ID
getColorR()、getColorG()、getColorB()、getColor()、getColorHex()	地图颜色的不同表示

如果世界已经卸载或不存在，getWorld() 可能为 null；getWorldUid() 仍然有值。需要访问世界对象时先检查 getWorld()。

领地 flag 可以按单个 flag 或整体 Map 读取：

boolean allowsCreeper = dominion.getEnvFlagValue(Flags.CREEPER_EXPLODE);
boolean guestCanOpen = dominion.getGuestFlagValue(Flags.CONTAINER);
Map<EnvFlag, Boolean> environment = dominion.getEnvironmentFlagValue();
Map<PriFlag, Boolean> guest = dominion.getGuestPrivilegeFlagValue();

MemberDTO

MemberDTO 表示玩家在某个领地中的成员关系：

方法	含义
getId()	成员记录 ID
getPlayerUUID()	成员玩家 UUID
getDomID()	所属领地 ID
getGroupId()	所属组 ID；-1 表示未加入组
getPlayer()	对应的 PlayerDTO
getFlagValue(PriFlag)	该成员的个人权限值
getFlagsValue()	该成员的个人权限 Map

没有为成员单独保存某个 flag 时，getFlagValue 会返回该 flag 的默认值。实际玩家是否能执行操作，应优先用主 API 的 checkPrivilegeFlag，不要只读取成员 Map 后自行复制权限合并逻辑。

GroupDTO

GroupDTO 表示领地内的权限组：

• getId()：组 ID；getDomID()：所属领地 ID；
• getNamePlain()：不含颜色的名称，适合日志、比较和持久化展示；
• getNameRaw()：带 Dominion 颜色编码的原始名称；
• getNameColoredComponent()：Adventure Component；
• getNameColoredBukkit()：Bukkit ChatColor 字符串；
• getFlagValue(PriFlag) / getFlagsValue()：组权限；
• getMembers()：该组成员。

组名可以包含颜色信息。除非确实需要渲染，不要用 getNameRaw() 作为唯一标识；组 ID 才是稳定的关联值。

PlayerDTO

PlayerDTO 保存 Dominion 认识的玩家数据：getId()、getUuid()、getLastKnownName()、getUsingGroupTitleID() 和 getSkinUrl()。找不到玩家时，查询方法通常返回 null；PlayerDTO.UNKNOWN 是一个明确的占位对象，其 ID 和 UUID 是特殊的未知值，不能当作真实玩家。

TemplateDTO

TemplateDTO 是玩家拥有的一组可复用权限值，提供 getId()、getCreator()、getName()、getFlagValue(PriFlag) 和 getFlagsValue()。模板的创建、修改和应用通过 TemplateProvider 完成。

写入边界

下面这些 DTO 方法虽然存在，但附属不应在业务代码中直接使用：

• DominionDTO.setOwner、setName、setCuboid、set...FlagValue 等；
• MemberDTO.setFlagValue；
• GroupDTO.setName、setFlagValue；
• 直接改动由 get...() 返回的可变对象后期待 Dominion 自动同步。

请使用Provider 或对应的事件流程。这样才能让缓存、数据库、经济和其他附属看到一致的状态。