Add tests and documentation for club affairs reminder feature

Co-authored-by: LazuliKao <46601807+LazuliKao@users.noreply.github.com>

Author: Copilot

src/HuaJiBot.NET.Plugin.Calendar/ClubAffairsReminder.README.md

@@ -0,0 +1,101 @@
+# 社团事务临期提醒功能
+
+## 功能介绍
+
+社团事务临期提醒功能是 Calendar 插件的一部分，用于帮助社团成员更好地管理即将到期的事务，避免遗漏重要事项。
+
+## 功能特性
+
+### 1. 每周汇总预告
+
+在配置的时间（默认：每周一上午 9:00）发送一条汇总消息，列出接下来一周内即将到期的社团事务。
+
+**示例消息：**
+
+```
+📢 社团事务一周预告（10月20日～10月26日）
+以下事务将在一周内到期，请相关负责人提前准备：
+
+1️⃣ [10月22日] 迎新晚会节目单提交（负责人：李华）
+2️⃣ [10月24日] 社团经费报销材料上交（负责人：张敏）
+3️⃣ [10月25日] 社团展板更新完成（负责人：王强）
+
+✅ 请大家合理安排时间，确保事项按时完成。
+—— 社团事务提醒机器人 🤖
+```
+
+### 2. 每日临期提醒
+
+在配置的时间（默认：每天上午 9:00）发送单条提醒消息，提醒明天即将截止的事务。
+
+**示例消息：**
+
+```
+⏰ 临期提醒
+明天（10月25日）截止的社团事务：
+
+• 社团展板更新完成（负责人：王强）
+
+请务必在截止前完成相关工作！
+—— 社团事务提醒机器人 🤖
+```
+
+## 配置说明
+
+在插件配置文件中，可以通过 `ClubAffairsReminder` 节点进行配置：
+
+```json
+{
+  "ClubAffairsReminder": {
+    "EnableWeeklySummary": true,
+    "EnableDailyReminder": true,
+    "WeeklySummaryHour": 9,
+    "DailyReminderHour": 9,
+    "WeeklySummaryDayOfWeek": 1
+  }
+}
+```
+
+### 配置项说明
+
+| 配置项 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `EnableWeeklySummary` | bool | `true` | 是否启用每周汇总提醒 |
+| `EnableDailyReminder` | bool | `true` | 是否启用每日提醒 |
+| `WeeklySummaryHour` | int | `9` | 每周汇总发送时间（小时，0-23） |
+| `DailyReminderHour` | int | `9` | 每日提醒发送时间（小时，0-23） |
+| `WeeklySummaryDayOfWeek` | int | `1` | 每周汇总发送在星期几（0=周日，1=周一，...，6=周六） |
+
+## 负责人信息提取
+
+系统会自动从事务描述中提取负责人信息。支持以下格式：
+
+- `负责人：张三`
+- `负责人:张三`
+- `责任人：张三`
+- `责任人:张三`
+
+## 过滤规则
+
+提醒消息遵循现有的 `ReminderGroups` 配置，支持白名单、黑名单和默认模式：
+
+- **Default（默认）**：发送所有事务提醒
+- **WhiteList（白名单）**：仅发送包含指定关键词的事务
+- **BlackList（黑名单）**：不发送包含指定关键词的事务
+
+关键词匹配会检查事务的概要（Summary）、描述（Description）和地点（Location）字段。
+
+## 工作原理
+
+1. 系统每小时检查一次当前时间
+2. 在配置的时间点，检查是否需要发送提醒
+3. 使用日期记录防止同一天重复发送
+4. 根据过滤规则筛选要发送的群组和事务
+5. 自动提取负责人信息并格式化消息
+
+## 注意事项
+
+- 提醒功能需要正确配置 `ReminderGroups` 才能发送消息
+- 系统使用网络时间（NetworkTime）确保时间准确性
+- 日历数据需要成功同步才能发送提醒
+- 如果某一天没有即将到期的事务，不会发送空消息

src/HuaJiBot.NET.UnitTest/ClubAffairsReminderTest.cs

@@ -0,0 +1,110 @@
+namespace HuaJiBot.NET.UnitTest;
+
+internal class ClubAffairsReminderTest
+{
+    [Test]
+    public void TestWeeklySummaryDayOfWeek()
+    {
+        // Test that Monday is correctly identified for weekly summary
+        var monday = new DateTimeOffset(2024, 10, 21, 9, 0, 0, TimeSpan.FromHours(8)); // Monday
+        var tuesday = new DateTimeOffset(2024, 10, 22, 9, 0, 0, TimeSpan.FromHours(8)); // Tuesday
+        
+        Assert.That(monday.DayOfWeek, Is.EqualTo(DayOfWeek.Monday));
+        Assert.That(tuesday.DayOfWeek, Is.Not.EqualTo(DayOfWeek.Monday));
+    }
+
+    [Test]
+    public void TestTimeComparison()
+    {
+        // Test that hour comparison works correctly for reminder timing
+        var nineAm = new DateTimeOffset(2024, 10, 21, 9, 0, 0, TimeSpan.FromHours(8));
+        var tenAm = new DateTimeOffset(2024, 10, 21, 10, 0, 0, TimeSpan.FromHours(8));
+        
+        Assert.That(nineAm.Hour, Is.EqualTo(9));
+        Assert.That(tenAm.Hour, Is.EqualTo(10));
+    }
+
+    [Test]
+    public void TestDateComparison()
+    {
+        // Test date comparison for preventing duplicate reminders
+        var date1 = new DateTimeOffset(2024, 10, 21, 9, 0, 0, TimeSpan.FromHours(8));
+        var date2 = new DateTimeOffset(2024, 10, 21, 10, 0, 0, TimeSpan.FromHours(8));
+        var date3 = new DateTimeOffset(2024, 10, 22, 9, 0, 0, TimeSpan.FromHours(8));
+        
+        Assert.That(date1.Date, Is.EqualTo(date2.Date));
+        Assert.That(date1.Date, Is.Not.EqualTo(date3.Date));
+    }
+
+    [Test]
+    public void TestWeekRange()
+    {
+        // Test that week range calculation is correct
+        var start = new DateTimeOffset(2024, 10, 21, 9, 0, 0, TimeSpan.FromHours(8));
+        var end = start.AddDays(7);
+        
+        var expectedEnd = new DateTimeOffset(2024, 10, 28, 9, 0, 0, TimeSpan.FromHours(8));
+        Assert.That(end, Is.EqualTo(expectedEnd));
+    }
+
+    [Test]
+    public void TestDayRange()
+    {
+        // Test that tomorrow calculation is correct
+        var today = new DateTimeOffset(2024, 10, 21, 9, 0, 0, TimeSpan.FromHours(8));
+        var tomorrow = today.Date.AddDays(1);
+        var dayAfterTomorrow = tomorrow.AddDays(1);
+        
+        var expectedTomorrow = new DateTimeOffset(2024, 10, 22, 0, 0, 0, TimeSpan.FromHours(8));
+        var expectedDayAfter = new DateTimeOffset(2024, 10, 23, 0, 0, 0, TimeSpan.FromHours(8));
+        
+        Assert.That(tomorrow, Is.EqualTo(expectedTomorrow));
+        Assert.That(dayAfterTomorrow, Is.EqualTo(expectedDayAfter));
+    }
+
+    [Test]
+    public void TestNumberEmoji()
+    {
+        // Test emoji mapping
+        var testCases = new Dictionary<int, string>
+        {
+            { 1, "1️⃣" },
+            { 2, "2️⃣" },
+            { 3, "3️⃣" },
+            { 4, "4️⃣" },
+            { 5, "5️⃣" },
+            { 6, "6️⃣" },
+            { 7, "7️⃣" },
+            { 8, "8️⃣" },
+            { 9, "9️⃣" },
+            { 10, "🔟" },
+        };
+
+        foreach (var testCase in testCases)
+        {
+            var emoji = GetNumberEmoji(testCase.Key);
+            Assert.That(emoji, Is.EqualTo(testCase.Value));
+        }
+        
+        // Test fallback for numbers > 10
+        Assert.That(GetNumberEmoji(11), Is.EqualTo("11."));
+    }
+
+    private string GetNumberEmoji(int number)
+    {
+        return number switch
+        {
+            1 => "1️⃣",
+            2 => "2️⃣",
+            3 => "3️⃣",
+            4 => "4️⃣",
+            5 => "5️⃣",
+            6 => "6️⃣",
+            7 => "7️⃣",
+            8 => "8️⃣",
+            9 => "9️⃣",
+            10 => "🔟",
+            _ => $"{number}.",
+        };
+    }
+}