Add FuzzyEventTypeImplementation opt-in annotation for event type clarity

Author: ForteScarlet

simbot-api/api/simbot-api.api

@@ -1452,6 +1452,9 @@ public final class love/forte/simbot/event/EventResult_jvmKt {
 	public static final fun collectCollectableReactively (Llove/forte/simbot/event/StandardEventResult$CollectableReactivelyResult;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
 }
 
+public abstract interface annotation class love/forte/simbot/event/FuzzyEventTypeImplementation : java/lang/annotation/Annotation {
+}
+
 public abstract interface class love/forte/simbot/event/GroupMemberChangeEvent : love/forte/simbot/event/ChangeEvent, love/forte/simbot/event/ChatGroupMemberEvent {
 	public abstract synthetic fun content (Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
 	public synthetic fun getContent ()Ljava/lang/Object;
@@ -1848,7 +1851,7 @@ public abstract interface class love/forte/simbot/event/OrganizationEvent : love
 	public fun getContentReserve ()Llove/forte/simbot/suspendrunner/reserve/SuspendReserve;
 }
 
-public abstract interface class love/forte/simbot/event/OrganizationJoinRequestEvent : love/forte/simbot/event/OrganizationEvent {
+public abstract interface class love/forte/simbot/event/OrganizationJoinRequestEvent : love/forte/simbot/event/OrganizationRequestEvent {
 	public fun getRequester ()Llove/forte/simbot/definition/User;
 	public fun getRequesterAsync ()Ljava/util/concurrent/CompletableFuture;
 	public abstract fun getRequesterId ()Llove/forte/simbot/common/id/ID;

simbot-api/src/commonMain/kotlin/love/forte/simbot/event/ActorEvent.kt

@@ -1,10 +1,10 @@
 /*
- *     Copyright (c) 2024. ForteScarlet.
+ *     Copyright (c) 2024-2025. ForteScarlet.
  *
  *     Project    https://github.com/simple-robot/simpler-robot
  *     Email      [email protected]
  *
- *     This file is part of the Simple Robot Library.
+ *     This file is part of the Simple Robot Library (Alias: simple-robot, simbot, etc.).
  *
  *     This program is free software: you can redistribute it and/or modify
  *     it under the terms of the GNU Lesser General Public License as published by
@@ -33,6 +33,7 @@ import love.forte.simbot.suspendrunner.STP
  * @author ForteScarlet
  */
 @STP
+@SubclassOptInRequired(FuzzyEventTypeImplementation::class)
 public interface ActorEvent : BotEvent, ContentEvent {
     /**
      * 被作为事件中心的 [Actor]。
@@ -46,6 +47,7 @@ public interface ActorEvent : BotEvent, ContentEvent {
  * @author ForteScarlet
  */
 @STP
+@SubclassOptInRequired(FuzzyEventTypeImplementation::class)
 public interface ContactEvent : ActorEvent {
     /**
      * 被作为事件中心的 [Contact]。
@@ -59,6 +61,7 @@ public interface ContactEvent : ActorEvent {
  * @author ForteScarlet
  */
 @STP
+@SubclassOptInRequired(FuzzyEventTypeImplementation::class)
 public interface OrganizationEvent : ActorEvent {
     /**
      * 被作为事件中心的 [Organization]。
@@ -72,6 +75,7 @@ public interface OrganizationEvent : ActorEvent {
  * @author ForteScarlet
  */
 @STP
+@SubclassOptInRequired(FuzzyEventTypeImplementation::class)
 public interface ChatRoomEvent : ActorEvent {
     /**
      * 被作为事件中心的 [ChatRoom]。
@@ -86,6 +90,7 @@ public interface ChatRoomEvent : ActorEvent {
  * @author ForteScarlet
  */
 @STP
+@SubclassOptInRequired(FuzzyEventTypeImplementation::class)
 public interface ChatGroupEvent : ChatRoomEvent, OrganizationEvent {
     /**
      * 被作为事件中心的 [ChatGroup]。
@@ -99,6 +104,7 @@ public interface ChatGroupEvent : ChatRoomEvent, OrganizationEvent {
  * @author ForteScarlet
  */
 @STP
+@SubclassOptInRequired(FuzzyEventTypeImplementation::class)
 public interface GuildEvent : OrganizationEvent {
     /**
      * 被作为事件中心的 [Guild]。
@@ -111,6 +117,7 @@ public interface GuildEvent : OrganizationEvent {
  * 此类型由一些存在组织信息、但组织信息不是主要信息的事件类型实现。
  */
 @STP
+@SubclassOptInRequired(FuzzyEventTypeImplementation::class)
 public interface OrganizationSourceEvent : BotEvent, SourceEvent {
     /**
      * 事件中的 [Organization].
@@ -124,6 +131,7 @@ public interface OrganizationSourceEvent : BotEvent, SourceEvent {
  * @author ForteScarlet
  */
 @STP
+@SubclassOptInRequired(FuzzyEventTypeImplementation::class)
 public interface ChannelEvent : ActorEvent, OrganizationSourceEvent {
     /**
      * 事件中的 [channel][content] 所属的 [Guild]。
@@ -143,6 +151,7 @@ public interface ChannelEvent : ActorEvent, OrganizationSourceEvent {
  * @author ForteScarlet
  */
 @STP
+@SubclassOptInRequired(FuzzyEventTypeImplementation::class)
 public interface ChatChannelEvent : ChannelEvent, ChatRoomEvent {
     /**
      * 被作为事件中心的 [ChatChannel]。
@@ -156,6 +165,7 @@ public interface ChatChannelEvent : ChannelEvent, ChatRoomEvent {
  * @author ForteScarlet
  */
 @STP
+@SubclassOptInRequired(FuzzyEventTypeImplementation::class)
 public interface MemberEvent : ActorEvent, OrganizationSourceEvent {
     /**
      * 事件中 [member][content] 所属的 [Organization]。
@@ -175,6 +185,7 @@ public interface MemberEvent : ActorEvent, OrganizationSourceEvent {
  * @author ForteScarlet
  */
 @STP
+@SubclassOptInRequired(FuzzyEventTypeImplementation::class)
 public interface ChatGroupMemberEvent : MemberEvent {
     /**
      * 事件中 [member][content] 所属的 [ChatGroup]。
@@ -193,6 +204,7 @@ public interface ChatGroupMemberEvent : MemberEvent {
  * @author ForteScarlet
  */
 @STP
+@SubclassOptInRequired(FuzzyEventTypeImplementation::class)
 public interface GuildMemberEvent : MemberEvent {
     /**
      * 事件中 [member][content] 所属的 [Guild]。

simbot-api/src/commonMain/kotlin/love/forte/simbot/event/BotStageEvent.kt

@@ -33,6 +33,7 @@ import love.forte.simbot.bot.BotManager
  *
  * @author ForteScarlet
  */
+@SubclassOptInRequired(FuzzyEventTypeImplementation::class)
 public interface BotStageEvent : InternalNotificationEvent, BotEvent {
     /**
      * 相关的 bot.
@@ -45,11 +46,13 @@ public interface BotStageEvent : InternalNotificationEvent, BotEvent {
  *
  * @author ForteScarlet
  */
+@OptIn(FuzzyEventTypeImplementation::class)
 public interface BotRegisteredEvent : BotStageEvent
 
 /**
  * 当一个 Bot **首次** 启动成功后的事件。
  *
  * @author ForteScarlet
  */
+@OptIn(FuzzyEventTypeImplementation::class)
 public interface BotStartedEvent : BotStageEvent

simbot-api/src/commonMain/kotlin/love/forte/simbot/event/Event.kt

@@ -1,10 +1,10 @@
 /*
- *     Copyright (c) 2024. ForteScarlet.
+ *     Copyright (c) 2024-2025. ForteScarlet.
  *
  *     Project    https://github.com/simple-robot/simpler-robot
  *     Email      [email protected]
  *
- *     This file is part of the Simple Robot Library.
+ *     This file is part of the Simple Robot Library (Alias: simple-robot, simbot, etc.).
  *
  *     This program is free software: you can redistribute it and/or modify
  *     it under the terms of the GNU Lesser General Public License as published by
@@ -35,6 +35,7 @@ import love.forte.simbot.suspendrunner.STP
  *
  * @author ForteScarlet
  */
+@SubclassOptInRequired(FuzzyEventTypeImplementation::class)
 public interface Event : IDContainer {
     /**
      * 事件的ID。
@@ -56,6 +57,7 @@ public interface Event : IDContainer {
  *
  * @author ForteScarlet
  */
+@SubclassOptInRequired(FuzzyEventTypeImplementation::class)
 public interface ComponentEvent : Event {
     /**
      * 所属组件
@@ -68,6 +70,7 @@ public interface ComponentEvent : Event {
  *
  * @author ForteScarlet
  */
+@SubclassOptInRequired(FuzzyEventTypeImplementation::class)
 public interface BotEvent : ComponentEvent {
     /**
      * 相关的 [Bot]。
@@ -88,6 +91,7 @@ public interface BotEvent : ComponentEvent {
  * 一个事件中可以提供的主、次要信息会优先使用 [ContentEvent] 和 [SourceEvent] 提供。
  */
 @STP
+@SubclassOptInRequired(FuzzyEventTypeImplementation::class)
 public interface ContentEvent : Event {
     /**
      * 这个事件的主要事件中心值。
@@ -101,6 +105,7 @@ public interface ContentEvent : Event {
  * 一个事件中可以提供的主、次要信息会优先使用 [ContentEvent] 和 [SourceEvent] 提供。
  */
 @STP
+@SubclassOptInRequired(FuzzyEventTypeImplementation::class)
 public interface SourceEvent : Event {
     /**
      * 这个事件的“源头”。
@@ -114,6 +119,7 @@ public interface SourceEvent : Event {
  * @author ForteScarlet
  */
 @STP
+@SubclassOptInRequired(FuzzyEventTypeImplementation::class)
 public interface ChangeEvent : ContentEvent {
     /**
      * 发生了变化的主体。

simbot-api/src/commonMain/kotlin/love/forte/simbot/event/FuzzyEventTypeImplementation.kt

@@ -0,0 +1,63 @@
+/*
+ *     Copyright (c) 2025. ForteScarlet.
+ *
+ *     Project    https://github.com/simple-robot/simpler-robot
+ *     Email      [email protected]
+ *
+ *     This file is part of the Simple Robot Library (Alias: simple-robot, simbot, etc.).
+ *
+ *     This program is free software: you can redistribute it and/or modify
+ *     it under the terms of the GNU Lesser General Public License as published by
+ *     the Free Software Foundation, either version 3 of the License, or
+ *     (at your option) any later version.
+ *
+ *     This program is distributed in the hope that it will be useful,
+ *     but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *     Lesser GNU General Public License for more details.
+ *
+ *     You should have received a copy of the Lesser GNU General Public License
+ *     along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ *
+ */
+
+package love.forte.simbot.event
+
+/**
+ * 通过 [SubclassOptInRequired] 标记某个事件类型为一个 “模糊的事件类型”。
+ * 这类事件通常拥有更明确的子类型，因此也更推荐实现这些更具体的类型，
+ * 而它们的存在主要是为了提供一个更为通用的事件类型或者仅仅提供一些额外能力（例如 `XxxAware` 之类的事件），
+ * 以便于在事件监听或类型判断上发挥作用。
+ *
+ * 举个例子，[MessageEvent] 代表了一个 Bot 收到消息的事件，用户可以通过监听它来得知所有的与消息相关的事件。
+ *
+ * ```kotlin
+ * eventDispatcher.process<MessageEvent> { event ->
+ *     ...
+ * }
+ * ```
+ *
+ * 但是在组件进行具体实现的时候，[MessageEvent] 所代表的含义就比较模糊：它即可能代表群消息，也可能代表私聊消息。
+ * 因此应该根据 [ChatGroupMessageEvent] 或 [ContactMessageEvent] 这类末端更具体的类型进行实现或扩展，
+ * 而不是直接实现 [MessageEvent]。
+ *
+ * ```kotlin
+ * // 推荐实现更具体的事件类型
+ * class MyMessageEventImpl : ChatGroupMessageEvent {
+ *     ...
+ * }
+ * ```
+ *
+ * 如果你清楚你的事件类型是一个模糊的事件类型，那么你可以使用这个注解来标记它。
+ * 此注解主要用于警告此问题的存在，以便于开发者更好地进行事件类型的设计，但不会对代码进行任何限制。
+ *
+ * @since 4.11.0
+ *
+ * @author ForteScarlet
+ */
+@RequiresOptIn(
+    message = "This is a fuzzy event type. It is recommended to implement a more specific event type.",
+    level = RequiresOptIn.Level.WARNING
+)
+@Target(AnnotationTarget.CLASS, AnnotationTarget.ANNOTATION_CLASS)
+public annotation class FuzzyEventTypeImplementation

simbot-api/src/commonMain/kotlin/love/forte/simbot/event/InternalEvent.kt

@@ -39,6 +39,7 @@ package love.forte.simbot.event
  * @since 4.11.0
  * @author ForteScarlet
  */
+@SubclassOptInRequired(FuzzyEventTypeImplementation::class)
 public interface InternalEvent : Event
 
 /**
@@ -47,6 +48,7 @@ public interface InternalEvent : Event
  *
  * @since 4.11.0
  */
+@SubclassOptInRequired(FuzzyEventTypeImplementation::class)
 public interface InternalNotificationEvent : InternalEvent
 
 /**
@@ -65,6 +67,7 @@ public interface InternalNotificationEvent : InternalEvent
  * @since 4.11.0
  *
  */
+@SubclassOptInRequired(FuzzyEventTypeImplementation::class)
 public interface InternalInterceptionEvent : InternalEvent
 
 /**

simbot-api/src/commonMain/kotlin/love/forte/simbot/event/InternalMessageInteractionEvent.kt

@@ -40,6 +40,7 @@ import love.forte.simbot.message.MessageReceipt
  *
  * @author ForteScarlet
  */
+@SubclassOptInRequired(FuzzyEventTypeImplementation::class)
 public interface InternalMessageInteractionEvent : InternalEvent {
     /**
      * 进行消息交互的实体。
@@ -62,6 +63,7 @@ public interface InternalMessageInteractionEvent : InternalEvent {
  *
  * @since 4.11.0
  */
+@SubclassOptInRequired(FuzzyEventTypeImplementation::class)
 public interface InternalMessagePreSendEvent :
     InternalInterceptionEvent,
     InternalMessageInteractionEvent {
@@ -97,6 +99,7 @@ public interface InternalMessagePreSendEvent :
  *
  * @since 4.11.0
  */
+@SubclassOptInRequired(FuzzyEventTypeImplementation::class)
 public interface InternalMessagePostSendEvent : InternalMessageInteractionEvent {
     /**
      * 在消息发送时

simbot-api/src/commonMain/kotlin/love/forte/simbot/event/MemberChangeEvent.kt

@@ -1,5 +1,5 @@
 /*
- *     Copyright (c) 2024. ForteScarlet.
+ *     Copyright (c) 2024-2025. ForteScarlet.
  *
  *     Project    https://github.com/simple-robot/simpler-robot
  *     Email      [email protected]
@@ -35,6 +35,7 @@ import love.forte.simbot.suspendrunner.STP
  * @author ForteScarlet
  */
 @STP
+@OptIn(FuzzyEventTypeImplementation::class)
 public interface MemberChangeEvent : ChangeEvent, MemberEvent {
     /**
      * 发送了变化的 [Member]。
@@ -49,6 +50,7 @@ public interface MemberChangeEvent : ChangeEvent, MemberEvent {
  * @author ForteScarlet
  */
 @STP
+@OptIn(FuzzyEventTypeImplementation::class)
 public interface GuildMemberChangeEvent : ChangeEvent, GuildMemberEvent {
     /**
      * 变化成员所在 [Guild]
@@ -68,6 +70,7 @@ public interface GuildMemberChangeEvent : ChangeEvent, GuildMemberEvent {
  * @author ForteScarlet
  */
 @STP
+@OptIn(FuzzyEventTypeImplementation::class)
 public interface GroupMemberChangeEvent : ChangeEvent, ChatGroupMemberEvent {
     /**
      * 变化成员所在 [ChatGroup]