feat: flag and docs

Author: cssxsh

mirai-core-api/src/commonMain/kotlin/contact/Member.kt

@@ -14,7 +14,7 @@ package net.mamoe.mirai.contact
 
 import me.him188.kotlin.jvm.blocking.bridge.JvmBlockingBridge
 import net.mamoe.mirai.Bot
-import net.mamoe.mirai.data.GroupHonorType
+import net.mamoe.mirai.contact.active.GroupHonorFlag
 import net.mamoe.mirai.event.events.*
 import net.mamoe.mirai.message.MessageReceipt
 import net.mamoe.mirai.message.action.MemberNudge
@@ -87,14 +87,14 @@ public interface Member : User {
     /**
      * 群荣誉标识.
      */
-    public val honor: Set<GroupHonorType>
+    public val honor: Set<GroupHonorFlag>
 
     /**
      * 群荣誉等级. 取值为 0~100
      *
      * 这个等级是在 手机端 群荣誉功能中显示的等级
      */
-    public val active: Int
+    public val temperature: Int
 
     /**
      * 禁言这个群成员 [durationSeconds] 秒, 在机器人无权限操作时抛出 [PermissionDeniedException].

mirai-core-api/src/commonMain/kotlin/contact/active/Active.kt

@@ -10,10 +10,46 @@
 package net.mamoe.mirai.contact.active
 
 import kotlinx.coroutines.flow.Flow
+import net.mamoe.mirai.contact.Group
 import net.mamoe.mirai.utils.MiraiExperimentalApi
 import net.mamoe.mirai.contact.Member
+import net.mamoe.mirai.contact.announcement.OfflineAnnouncement
+import net.mamoe.mirai.contact.announcement.OnlineAnnouncement
+import net.mamoe.mirai.utils.NotStableForInheritance
 import java.util.stream.Stream
 
+/**
+ * 表示一个群活跃度管理.
+ *
+ * ## 获取 [Active] 实例
+ *
+ * 只可以通过 [Group.active] 获取一个群的活跃度管理, 即 [Active] 实例.
+ *
+ * ### 等级头衔列表
+ *
+ * 通过 [rankTitles] 可以获取和设置一个群的等级头衔列表,
+ * 通过 [rankShow] 可以获取和设置一个群的等级头衔是否显示
+ *
+ * 设置时，修改将异步发送到服务器
+ *
+ * ### 活跃度记录
+ *
+ * 通过 [asFlow] 或 [asStream] 可以获取群活跃度记录*惰性*流,
+ * 在从流中收集数据时才会请求服务器获取数据. 通常建议在 Kotlin 使用协程的 [asFlow], 在 Java 使用 [asStream].
+ *
+ * 若要获取全部活跃度记录, 可使用 [toList].
+ *
+ * ### 活跃度图表
+ *
+ * 通过 [getChart] 可以获取活跃度图表，
+ * 包括
+ * * 每日总人数 [ActiveChart.members]
+ * * 每日活跃人数 [ActiveChart.actives]
+ * * 每日申请人数 [ActiveChart.sentences]
+ * * 每日入群人数 [ActiveChart.join]
+ * * 每日退群人数 [ActiveChart.exit]
+ */
+@NotStableForInheritance
 public interface Active {
 
     /**
@@ -37,17 +73,23 @@ public interface Active {
     public var rankShow: Boolean
 
     /**
+     * 创建一个能获取该群内所有群活跃度记录的 [Flow]. 在 [Flow] 被使用时才会分页下载 [OnlineAnnouncement].
      *
+     * 异常不会抛出, 只会记录到网络日志. 当获取发生异常时将会终止获取, 不影响已经成功获取的 [ActiveRecord] 和 [Flow] 的[收集][Flow.collect].
      */
     public fun asFlow(): Flow<ActiveRecord>
 
     /**
+     * 创建一个能获取该群内所有群活跃度记录的 [Stream]. 在 [Stream] 被使用时才会分页下载 [OnlineAnnouncement].
+     *
+     * 异常不会抛出, 只会记录到网络日志. 当获取发生异常时将会终止获取, 不影响已经成功获取的 [ActiveRecord] 和 [Stream] 的[收集][Stream.collect].
      *
+     * 实现细节: 为了适合 Java 调用, 实现类似为阻塞式的 [asFlow], 因此不建议在 Kotlin 使用. 在 Kotlin 请使用 [asFlow].
      */
     public fun asStream(): Stream<ActiveRecord>
 
     /**
-     *
+     * 获取活跃度图表数据
      */
     public suspend fun getChart(): ActiveChart?
 }

mirai-core-api/src/commonMain/kotlin/contact/active/ActiveChart.kt

@@ -9,6 +9,9 @@
 
 package net.mamoe.mirai.contact.active
 
+/**
+ * 活跃度数据图表
+ */
 public interface ActiveChart {
     public val actives: Map<String, Int>
     public val sentences: Map<String, Int>

mirai-core-api/src/commonMain/kotlin/contact/active/ActiveRecord.kt

@@ -11,10 +11,32 @@ package net.mamoe.mirai.contact.active
 
 import net.mamoe.mirai.contact.NormalMember
 
+/**
+ * 活跃数据记录
+ */
 public interface ActiveRecord {
+    /**
+     * 发言者名称
+     */
     public val senderName: String
+
+    /**
+     * 发言者 ID
+     */
     public val senderId: Long
+
+    /**
+     * 发言者的群员实例
+     */
     public val sender: NormalMember?
+
+    /**
+     * 活跃连续天数
+     */
     public val continuation: Int
+
+    /**
+     * 发言条数
+     */
     public val sentences: Int
 }

mirai-core-api/src/commonMain/kotlin/contact/active/GroupHonorFlag.kt

@@ -0,0 +1,26 @@
+/*
+ * Copyright 2019-2022 Mamoe Technologies and contributors.
+ *
+ * 此源代码的使用受 GNU AFFERO GENERAL PUBLIC LICENSE version 3 许可证的约束, 可以在以下链接找到该许可证.
+ * Use of this source code is governed by the GNU AGPLv3 license that can be found through the following link.
+ *
+ * https://github.com/mamoe/mirai/blob/dev/LICENSE
+ */
+
+package net.mamoe.mirai.contact.active
+
+/**
+ * 群荣誉标志
+ */
+public enum class GroupHonorFlag(private val value: Int) {
+    TALKATIVE(1),       // 龙王
+    PERFORMER(2),       // 群聊之火
+    LEGEND(3),          // 群聊炽焰
+    STRONG_NEWBIE(5),   // 冒尖小春笋
+    EMOTION(6);         // 快乐源泉
+
+    public companion object {
+        @JvmStatic
+        public fun deserializeFromInt(value: Int): GroupHonorFlag? = values().find { it.value == value }
+    }
+}

mirai-core-api/src/commonMain/kotlin/data/GroupHonorListData.kt

@@ -34,9 +34,9 @@ public enum class GroupHonorType(public val value: Int) {
     EXCLUSIVE(8),       // 特殊头衔
     MANAGE(9);          // 管理头衔
 
-    public companion object {
+    internal companion object {
         @JvmStatic
-        public fun deserializeFromInt(value: Int): GroupHonorType = values().first { it.value == value }
+        internal fun deserializeFromInt(value: Int): GroupHonorType = values().first { it.value == value }
     }
 }
 

mirai-core-api/src/commonMain/kotlin/data/MemberInfo.kt

@@ -11,6 +11,7 @@ package net.mamoe.mirai.data
 
 import net.mamoe.mirai.LowLevelApi
 import net.mamoe.mirai.contact.MemberPermission
+import net.mamoe.mirai.contact.active.GroupHonorFlag
 
 @LowLevelApi
 public interface MemberInfo : UserInfo {
@@ -52,12 +53,12 @@ public interface MemberInfo : UserInfo {
     public val point: Int
 
     /**
-     * 群荣誉
+     * 群荣誉标志
      */
-    public val honor: Set<GroupHonorType>
+    public val honor: Set<GroupHonorFlag>
 
     /**
      * 活跃度
      */
-    public val active: Int
+    public val temperature: Int
 }

mirai-core/src/commonMain/kotlin/contact/AbstractMember.kt

@@ -11,7 +11,7 @@ package net.mamoe.mirai.internal.contact
 
 import net.mamoe.mirai.contact.Member
 import net.mamoe.mirai.contact.MemberPermission
-import net.mamoe.mirai.data.GroupHonorType
+import net.mamoe.mirai.contact.active.GroupHonorFlag
 import net.mamoe.mirai.data.MemberInfo
 import net.mamoe.mirai.internal.contact.info.MemberInfoImpl
 import net.mamoe.mirai.utils.cast
@@ -32,8 +32,8 @@ internal sealed class AbstractMember(
     override val specialTitle: String get() = info.specialTitle
     override val rank: Int get() = info.rank
     override val point: Int get() = info.point
-    override val honor: Set<GroupHonorType> get() = info.honor
-    override val active: Int get() = info.active
+    override val honor: Set<GroupHonorFlag> get() = info.honor
+    override val temperature: Int get() = info.temperature
 
     override var permission: MemberPermission by info::permission
 }

mirai-core/src/commonMain/kotlin/contact/info/MemberInfoImpl.kt

@@ -11,7 +11,7 @@ package net.mamoe.mirai.internal.contact.info
 
 import kotlinx.serialization.Serializable
 import net.mamoe.mirai.contact.MemberPermission
-import net.mamoe.mirai.data.GroupHonorType
+import net.mamoe.mirai.contact.active.GroupHonorFlag
 import net.mamoe.mirai.data.MemberInfo
 import net.mamoe.mirai.internal.network.QQAndroidClient
 import net.mamoe.mirai.internal.network.protocol.data.jce.StTroopMemberInfo
@@ -33,8 +33,8 @@ internal data class MemberInfoImpl(
     override val isOfficialBot: Boolean = false,
     override val rank: Int = 1,
     override val point: Int = 0,
-    override val honor: Set<GroupHonorType> = emptySet(),
-    override val active: Int = 0
+    override val honor: Set<GroupHonorFlag> = emptySet(),
+    override val temperature: Int = 0
 ) : MemberInfo {
     constructor(
         client: QQAndroidClient,
@@ -75,11 +75,11 @@ internal data class MemberInfoImpl(
                 val type = bytes[index]
                 if (type.toInt() == 8) {
                     val value = bytes.getOrNull(index + 1) ?: break
-                    add(GroupHonorType.deserializeFromInt(value.toInt()))
+                    add(GroupHonorFlag.deserializeFromInt(value.toInt()) ?: continue)
                 }
             }
         },
-        active = jceInfo.vecGroupHonor?.let { bytes ->
+        temperature = jceInfo.vecGroupHonor?.let { bytes ->
             for (index in bytes.indices step 2) {
                 val type = bytes[index]
                 if (type.toInt() == 16) {