feat(integrations,classisland,server,web,desktop): ClassIsland 联动插件——上报课表与上课状态、下发提醒并回执、教室端推送通道

教室机器上的 ClassIsland 现在可以直接和班级小助手互通：插件走 /api/integrations/classisland/*，用设备令牌（X-ClassIsland-Token，库里只存 sha256）独立鉴权，不占用 JWT 通道。 - 服务端：新增 integrations 模块（上报 / 待弹出 / 回执 / 课表镜像 / 回写），两个迁移（设备令牌表、Class.notificationChannel）；通知、叫人、联动页下发统一复用 pushToClassIsland，避免"某个页面发的通知不联动" - 插件：packages/classisland-plugin（.NET 8，独立于 pnpm workspace）——BridgeService 上报与提醒轮询、ScheduleMapper/ClassPlanWriter 课表镜像、Avalonia 设置页、ClassHelperNotificationProvider 在 ClassIsland 上弹出提醒；本地/内网地址强制直连，躲开系统代理返回的假 404 - 客户端：设置页可选提醒通道（both / client / classisland），并订阅相应实时事件 - Web 端：新增「ClassIsland 联动」页（设备管理与提醒下发） - 校验与打包：verify:classisland（需后端）、verify:classisland-plugin（静态契约 54 项）、build/dist:classisland-plugin 产出 .cipx - 文档：README 与 AGENTS.md 同步新增联动说明，docs/screenshots/classisland 留三张真机截图门禁：pnpm lint 0 error、pnpm typecheck 四包通过、verify:classisland-plugin 54/54 通过。运行期仍需在装了 ClassIsland 的机器上实测（步骤见 AGENTS.md §8）。
2026-09-27 14:59:12 +08:00
1 parent fe41ebb7d6
commit d0830f6830
@@ -0,0 +1,167 @@
+<controls:SettingsPageBase x:Class="ClassHelper.ClassIslandPlugin.Views.BridgeSettingsPage"
+      xmlns="https://github.com/avaloniaui"
+      xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+      xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
+      xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
+      xmlns:local="clr-namespace:ClassHelper.ClassIslandPlugin.Views"
+      xmlns:controls="clr-namespace:ClassIsland.Core.Abstractions.Controls;assembly=ClassIsland.Core"
+      xmlns:ci="clr-namespace:ClassIsland.Core.Controls;assembly=ClassIsland.Core"
+      xmlns:fa="clr-namespace:FluentAvalonia.UI.Controls;assembly=FluentAvalonia"
+      mc:Ignorable="d"
+      d:DesignHeight="450" d:DesignWidth="800"
+      d:DataContext="{d:DesignInstance local:BridgeSettingsPage}"
+      Loaded="OnLoaded"
+      Unloaded="OnUnloaded">
+    <ScrollViewer>
+        <StackPanel Classes="settings-container animated-intro" Spacing="0">
+            <!-- 连接 -->
+            <TextBlock Text="连接班级小助手"
+                       Theme="{StaticResource SubtitleTextBlockStyle}" />
+            <TextBlock Margin="0 6 0 12" TextWrapping="Wrap"
+                       Text="填入班级小助手后端的地址与设备令牌。设备令牌在班级小助手 Web 端「ClassIsland 联动」页面里为本班新建设备后生成，只显示一次。" />
+
+            <TextBox Watermark="http://127.0.0.1:4000"
+                     Text="{Binding Settings.ServerUrl, Mode=TwoWay}" />
+            <TextBox Margin="0 8 0 0"
+                     Watermark="chci_..."
+                     PasswordChar="●"
+                     Text="{Binding Settings.DeviceToken, Mode=TwoWay}" />
+
+            <StackPanel Orientation="Horizontal" Margin="0 12 0 0" Spacing="8">
+                <Button Content="立即上报" Command="{Binding ReportCommand}" IsEnabled="{Binding !Bridge.Busy}" />
+                <Button Content="检查连接" Command="{Binding TestCommand}" IsEnabled="{Binding !Bridge.Busy}" />
+                <Button Content="拉取待提醒" Command="{Binding PullCommand}" IsEnabled="{Binding !Bridge.Busy}" />
+                <Button Content="重建档案课表" Command="{Binding MirrorCommand}"
+                        IsEnabled="{Binding Settings.MirrorSchedule}" />
+            </StackPanel>
+
+            <!-- 状态 -->
+            <Border Margin="0 16 0 0" Padding="12" CornerRadius="4"
+                    Background="{DynamicResource SystemFillColorNeutralBackgroundBrush}">
+                <StackPanel Spacing="4">
+                    <TextBlock Text="{Binding StatusText}" TextWrapping="Wrap" FontWeight="SemiBold" />
+                    <TextBlock Text="{Binding Bridge.LastReportMessage}" TextWrapping="Wrap" />
+                    <TextBlock Text="{Binding DetailText}" TextWrapping="Wrap" Opacity="0.8" />
+                </StackPanel>
+            </Border>
+
+            <!-- 同步 -->
+            <TextBlock Margin="0 24 0 0" Text="同步内容"
+                       Theme="{StaticResource SubtitleTextBlockStyle}" />
+            <TextBlock Margin="0 6 0 12" TextWrapping="Wrap"
+                       Text="课表以「合并」方式写入班级小助手：同一星期、同一时间的课目会被更新，不会产生重复行。" />
+
+            <fa:SettingsExpander Header="上报课表到班级小助手"
+                                 Description="把 ClassIsland 里启用的课表同步给班级小助手，Web 端与桌面客户端即可看到课程表。">
+                <fa:SettingsExpander.IconSource>
+                    <ci:FluentIconSource Glyph="&#xE8A5;" />
+                </fa:SettingsExpander.IconSource>
+                <fa:SettingsExpander.Footer>
+                    <ToggleSwitch IsChecked="{Binding Settings.UploadSchedule, Mode=TwoWay}" />
+                </fa:SettingsExpander.Footer>
+            </fa:SettingsExpander>
+
+            <fa:SettingsExpander Header="把班级课表镜像回 ClassIsland"
+                                 Description="反方向同步：把班级小助手上排好的课表写回 ClassIsland，会新建一份以「班级小助手-」开头的档案课表，不会修改老师原有的课表。">
+                <fa:SettingsExpander.IconSource>
+                    <ci:FluentIconSource Glyph="&#xE8F1;" />
+                </fa:SettingsExpander.IconSource>
+                <fa:SettingsExpander.Footer>
+                    <ToggleSwitch IsChecked="{Binding Settings.MirrorSchedule, Mode=TwoWay}" />
+                </fa:SettingsExpander.Footer>
+            </fa:SettingsExpander>
+
+            <fa:SettingsExpander Header="自动上报"
+                                 Description="应用启动、课表变化以及每隔一段时间各上报一次；关闭后只能用上面的「立即上报」手动触发。">
+                <fa:SettingsExpander.IconSource>
+                    <ci:FluentIconSource Glyph="&#xE895;" />
+                </fa:SettingsExpander.IconSource>
+                <fa:SettingsExpander.Footer>
+                    <ToggleSwitch IsChecked="{Binding Settings.AutoReport, Mode=TwoWay}" />
+                </fa:SettingsExpander.Footer>
+            </fa:SettingsExpander>
+
+            <Grid Margin="0 8 0 0" ColumnDefinitions="*,Auto">
+                <StackPanel>
+                    <TextBlock Text="上报间隔（秒）" />
+                    <TextBlock Text="最小 15 秒；教室机器建议 60 秒。" Opacity="0.7" TextWrapping="Wrap" />
+                </StackPanel>
+                <NumericUpDown Grid.Column="1" Width="140"
+                               Minimum="15" Maximum="3600" Increment="15"
+                               FormatString="0"
+                               IsEnabled="{Binding Settings.AutoReport}"
+                               Value="{Binding Settings.ReportIntervalSeconds, Mode=TwoWay}" />
+            </Grid>
+
+            <!-- 提醒 -->
+            <TextBlock Margin="0 24 0 0" Text="提醒"
+                       Theme="{StaticResource SubtitleTextBlockStyle}" />
+            <TextBlock Margin="0 6 0 12" TextWrapping="Wrap"
+                       Text="老师在班级小助手上发布的提醒会以 ClassIsland 的全屏提醒呈现；未弹出的提醒在应用重开后会自动补发，确认弹出后不再重复。" />
+
+            <fa:SettingsExpander Header="接收班级小助手提醒"
+                                 Description="关闭后本机会忽略老师在班级小助手上发布的提醒（提醒仍会留在班级通知中心）。">
+                <fa:SettingsExpander.IconSource>
+                    <ci:FluentIconSource Glyph="&#xE8BD;" />
+                </fa:SettingsExpander.IconSource>
+                <fa:SettingsExpander.Footer>
+                    <ToggleSwitch IsChecked="{Binding Settings.ReceiveNotifications, Mode=TwoWay}" />
+                </fa:SettingsExpander.Footer>
+            </fa:SettingsExpander>
+
+            <fa:SettingsExpander Header="语音朗读"
+                                 Description="提醒弹出时按 ClassIsland 的语音设置为全机朗读提醒内容。">
+                <fa:SettingsExpander.IconSource>
+                    <ci:FluentIconSource Glyph="&#xE8D6;" />
+                </fa:SettingsExpander.IconSource>
+                <fa:SettingsExpander.Footer>
+                    <ToggleSwitch IsChecked="{Binding Settings.SpeechEnabled, Mode=TwoWay}" />
+                </fa:SettingsExpander.Footer>
+            </fa:SettingsExpander>
+
+            <Grid Margin="0 8 0 0" ColumnDefinitions="*,Auto">
+                <StackPanel>
+                    <TextBlock Text="默认显示时长（秒）" />
+                    <TextBlock Text="老师在下发单条提醒时可以另外指定更长的时长。" Opacity="0.7" TextWrapping="Wrap" />
+                </StackPanel>
+                <NumericUpDown Grid.Column="1" Width="140"
+                               Minimum="1" Maximum="120" Increment="1"
+                               FormatString="0"
+                               Value="{Binding Settings.NotificationDurationSeconds, Mode=TwoWay}" />
+            </Grid>
+
+            <Grid Margin="0 8 0 0" ColumnDefinitions="*,Auto">
+                <StackPanel>
+                    <TextBlock Text="提醒轮询间隔（秒）" />
+                    <TextBlock Text="老师按下发送到教室弹出之间的最大延迟（插件不持有长连接，是轮询取回提醒）。默认 10 秒。"
+                               Opacity="0.7" TextWrapping="Wrap" />
+                </StackPanel>
+                <NumericUpDown Grid.Column="1" Width="140"
+                               Minimum="5" Maximum="600" Increment="5"
+                               FormatString="0"
+                               IsEnabled="{Binding Settings.ReceiveNotifications}"
+                               Value="{Binding Settings.NotificationPollSeconds, Mode=TwoWay}" />
+            </Grid>
+
+            <!-- 调试 -->
+            <TextBlock Margin="0 24 0 0" Text="调试"
+                       Theme="{StaticResource SubtitleTextBlockStyle}" />
+            <fa:SettingsExpander Header="显示调试信息"
+                                 Description="显示设备标识、时钟差等细节，排查「为什么同步不上」时打开。">
+                <fa:SettingsExpander.IconSource>
+                    <ci:FluentIconSource Glyph="&#xE7EF;" />
+                </fa:SettingsExpander.IconSource>
+                <fa:SettingsExpander.Footer>
+                    <ToggleSwitch IsChecked="{Binding Settings.ShowDebugInfo, Mode=TwoWay}" />
+                </fa:SettingsExpander.Footer>
+            </fa:SettingsExpander>
+
+            <StackPanel Margin="0 8 0 0" Spacing="2" IsVisible="{Binding Settings.ShowDebugInfo}">
+                <TextBlock Text="{Binding DebugText}" TextWrapping="Wrap" FontFamily="Consolas,monospace" />
+            </StackPanel>
+
+            <TextBlock Margin="0 24 0 0" Opacity="0.6" TextWrapping="Wrap"
+                       Text="提示：班级小助手 Web 端 →「ClassIsland 联动」可以新建/重置设备令牌、开关同步项，并实时看到本机当前上的课。" />
+        </StackPanel>
+    </ScrollViewer>
+</controls:SettingsPageBase>
@@ -0,0 +1,198 @@
+using System.ComponentModel;
+using System.Runtime.CompilerServices;
+using Avalonia.Threading;
+using ClassHelper.ClassIslandPlugin.Models;
+using ClassHelper.ClassIslandPlugin.Services;
+using ClassIsland.Core.Abstractions.Controls;
+using ClassIsland.Core.Attributes;
+using ClassIsland.Core.Enums.SettingsWindow;
+using CommunityToolkit.Mvvm.Input;
+
+namespace ClassHelper.ClassIslandPlugin.Views;
+
+/// <summary>
+/// 「班级小助手联动」设置页。
+///
+/// 页面上的绑定源就是本页自己（<c>DataContext = this</c>）：<see cref="Settings"/> 暴露全部配置项，
+/// <see cref="Bridge"/> 暴露运行状态。这样 XAML 里能直接写 <c>{Binding Settings.Xxx}</c>，
+/// 不需要再套一层 ViewModel，改配置项时也少一处"两边同步"的机会。
+/// </summary>
+// 图标用 Fluent 字体的码位（与 ClassIsland 内置设置页写法一致）：未选中/选中同一枚插头图标
+[SettingsPageInfo(
+    "classhelper.classisland.bridge.settings",
+    "班级小助手联动",
+    "\uE71B",
+    "\uE71B",
+    SettingsPageCategory.External)]
+public partial class BridgeSettingsPage : SettingsPageBase, INotifyPropertyChanged
+{
+    public BridgeSettingsPage(PluginSettings settings, BridgeService bridge)
+    {
+        Settings = settings;
+        Bridge = bridge;
+
+        ReportCommand = new AsyncRelayCommand(ReportAsync);
+        TestCommand = new AsyncRelayCommand(TestAsync);
+        PullCommand = new AsyncRelayCommand(PullAsync);
+        MirrorCommand = new AsyncRelayCommand(MirrorAsync);
+
+        InitializeComponent();
+        DataContext = this;
+        Raise(nameof(StatusText));
+    }
+
+    public PluginSettings Settings { get; }
+
+    public BridgeService Bridge { get; }
+
+    public IAsyncRelayCommand ReportCommand { get; }
+    public IAsyncRelayCommand TestCommand { get; }
+    public IAsyncRelayCommand PullCommand { get; }
+    public IAsyncRelayCommand MirrorCommand { get; }
+
+    private PropertyChangedEventHandler? _propertyChanged;
+
+    /// <summary>
+    /// 显式实现 <see cref="INotifyPropertyChanged"/>：<c>AvaloniaObject</c> 自带一个同名但类型不同的事件，
+    /// 直接声明会遮蔽基类成员。显式实现既不影响 Avalonia 的绑定查找（它按接口取），也不会有歧义。
+    /// </summary>
+    event PropertyChangedEventHandler? INotifyPropertyChanged.PropertyChanged
+    {
+        add => _propertyChanged += value;
+        remove => _propertyChanged -= value;
+    }
+
+    /* ---------------------------------------------------------------- 绑定用的展示文本 */
+
+    /// <summary>一句话结论：还没配 / 已配置 / 已连接 / 连接异常。</summary>
+    public string StatusText
+    {
+        get
+        {
+            if (!Settings.IsConfigured) return "尚未配置：请填写服务器地址与设备令牌";
+            if (!Bridge.IsAttached) return "已填写配置，等待 ClassIsland 课程服务就绪";
+            return Bridge.LastReportOk ? "已连接" : "连接异常";
+        }
+    }
+
+    public string DetailText
+    {
+        get
+        {
+            var week = Bridge.LastServerWeek?.ToString() ?? "—";
+            return $"最后上报：{Bridge.LastReportAtText}　教学周：{week}　" +
+                   $"课表 {Bridge.LastScheduleEntryCount} 节 / 节次 {Bridge.LastTimeLayoutItemCount} 条　" +
+                   $"已弹出提醒：{Bridge.NotificationCount} 条";
+        }
+    }
+
+    /// <summary>调试信息（设置页里打开"显示调试信息"才可见）。</summary>
+    public string DebugText
+    {
+        get
+        {
+            var lines = new List<string>
+            {
+                $"服务器地址：{(string.IsNullOrWhiteSpace(Settings.ServerUrl) ? "(未填)" : Settings.ServerUrl)}",
+                $"设备令牌：{(string.IsNullOrWhiteSpace(Settings.DeviceToken) ? "(未填)" : Mask(Settings.DeviceToken))}",
+                $"设备标识：{(string.IsNullOrWhiteSpace(Settings.DeviceKey) ? "(未生成)" : Settings.DeviceKey)}",
+                $"课程服务：{(Bridge.IsAttached ? "已接入" : "未接入")}",
+                $"与服务端时钟差：{Bridge.ClientTimeOffsetText}",
+                $"ClassIsland 版本：{SafeVersion()}",
+                $"配置目录：{PluginConfigFolder}",
+            };
+            return string.Join(Environment.NewLine, lines);
+        }
+    }
+
+    /// <summary>设置页所在的插件配置目录（从插件入口拿；拿不到时留空）。</summary>
+    private string PluginConfigFolder =>
+        ClassIsland.Shared.IAppHost.TryGetService<ClassIsland.Core.Abstractions.PluginBase>()?.PluginConfigFolder ?? "—";
+
+    private static string SafeVersion()
+    {
+        try { return ClassIsland.Core.AppBase.AppVersion ?? "—"; }
+        catch { return "—"; }
+    }
+
+    /// <summary>令牌只露头尾，避免设置页截图时把可用凭证泄露出去。</summary>
+    private static string Mask(string token) =>
+        token.Length <= 14 ? token : $"{token[..12]}…{token[^4..]}";
+
+    /* ---------------------------------------------------------------- 交互 */
+
+    private async Task ReportAsync()
+    {
+        await Bridge.ReportAsync("手动").ConfigureAwait(true);
+    }
+
+    /// <summary>不带课表上报一次：用来快速验证"地址 + 令牌"是否可用，不会因为课表为空而出错。</summary>
+    private async Task TestAsync()
+    {
+        await Bridge.ReportAsync("连接检查", includeSchedule: false).ConfigureAwait(true);
+    }
+
+    private async Task PullAsync()
+    {
+        await Bridge.PullPendingAsync().ConfigureAwait(true);
+    }
+
+    private async Task MirrorAsync()
+    {
+        await Bridge.MirrorScheduleAsync().ConfigureAwait(true);
+    }
+
+    private void OnSettingsChanged(object? sender, PropertyChangedEventArgs args)
+    {
+        // 影响上报链路的改动需要立刻重建定时器；纯界面项（如"显示调试信息"）不用管
+        if (args.PropertyName is nameof(PluginSettings.ServerUrl)
+            or nameof(PluginSettings.DeviceToken)
+            or nameof(PluginSettings.AutoReport)
+            or nameof(PluginSettings.ReportIntervalSeconds)
+            or nameof(PluginSettings.ReceiveNotifications)
+            or nameof(PluginSettings.NotificationPollSeconds))
+        {
+            Bridge.RestartTimer();
+        }
+
+        Raise(nameof(StatusText));
+        Raise(nameof(DebugText));
+    }
+
+    private void OnBridgeChanged(object? sender, PropertyChangedEventArgs args)
+    {
+        // Bridge 的属性变化可能来自线程池（HttpClient 回调），绑定必须在 UI 线程上更新
+        if (Dispatcher.UIThread.CheckAccess())
+        {
+            RaiseStateProperties();
+        }
+        else
+        {
+            Dispatcher.UIThread.Post(RaiseStateProperties);
+        }
+    }
+
+    private void RaiseStateProperties()
+    {
+        Raise(nameof(StatusText));
+        Raise(nameof(DetailText));
+        Raise(nameof(DebugText));
+    }
+
+    private void OnLoaded(object sender, Avalonia.Interactivity.RoutedEventArgs args)
+    {
+        // 改完地址/令牌/间隔要重建定时器，否则"改了设置但上报节奏还是旧的"
+        Settings.PropertyChanged += OnSettingsChanged;
+        // 运行状态（上一次上报结果 / 待弹出提醒数）变了要刷新状态卡片
+        Bridge.PropertyChanged += OnBridgeChanged;
+    }
+
+    private void OnUnloaded(object sender, Avalonia.Interactivity.RoutedEventArgs args)
+    {
+        Settings.PropertyChanged -= OnSettingsChanged;
+        Bridge.PropertyChanged -= OnBridgeChanged;
+    }
+
+    private void Raise([CallerMemberName] string? propertyName = null) =>
+        _propertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));
+}