基本使用
本页面介绍 ClassIntra 的系统访问、首次配置、桌面操作、主要功能与常见问题，帮助你快速上手校园内网 WebOS。
访问系统
ClassIntra 启动后，通过浏览器访问：
| 模式 | 访问地址 | 说明 |
|---|---|---|
| 开发模式 | http://localhost:5001 | Vite dev server，自动代理 API 到 :9001 |
| 生产模式 | http://localhost:9001 | Express 直接服务静态文件 + API |
| 首次配置 | http://localhost:5001/setup（或 :9001/setup） | 班级初始化向导 |
端口说明
5001—— Vite dev server（仅开发模式）9001—— Express HTTP（开发 + 生产，REST API + 静态文件）10001—— WebSocket（本地聊天实时通信）10011—— Relay WebSocket（跨班级消息中继）
首次配置流程
首次启动必须访问 /setup 完成班级初始化，五步完成：
1. 访问 setup 页面
浏览器打开 http://localhost:5001/setup（生产模式为 http://localhost:9001/setup）。
2. 导入预注册名单
在 setup 页面批量导入学生姓名，或预先编辑 server/config/pre-records.json：
{
"class08": ["张三", "李四", "王五"],
"class18": ["赵六", "钱七"]
}系统会自动为每位学生分配 YYCCNN 格式学号（届数 + 班级号 + 序号）。
3. 选择班管
每班选一人担任班级管理员（班管 ID 末两位为 00），班管的 user_id 需写入 .env 的 ADMIN_USER_IDS（如 250100 表示 25 届 01 班班管）。
4. 创建班级群
系统根据届数与班级编号自动创建班级群聊，预注册名单中的学生注册后自动加入对应班级群。
5. 确认保存
确认信息无误后保存，系统写入 .env + pre-records.json 并初始化数据库。完成后重启服务使配置生效。
首次配置注意
/setup页面仅在数据库未初始化时可访问，完成配置后自动禁用- 完成配置后需重启服务（
Ctrl + C后重新pnpm dev）使.env生效 - 重新配置需删除
server/database/classintra.db（会清除所有数据）
登录系统
完成首次配置后，访问首页进入登录界面。使用用户 ID + 密码登录：
- 用户 ID：
YYCCNN格式学号（如250801= 25 届 08 班 01 号） - 密码：首次注册时设置
注册流程
学生首次使用需注册：
- 在登录页点击「注册」
- 输入真实姓名（必须与预注册名单一致）
- 设置密码
- 系统自动匹配学号并分配
user_id - 注册成功后即可登录
班管权限
学生注册后，系统检查其 user_id 是否匹配 ADMIN_USER_IDS，匹配则自动授予管理员权限，无需额外操作。
开发者账号
在 .env 中设置 DEV_PASSWORD 后，可使用 ID 999999 的开发者账号登录，用于测试与调试。
桌面操作
登录后进入 ClassIntra 桌面，呈现类 iOS 启动台界面，专为横屏平板优化。
应用图标
桌面以图标网格排列所有已安装应用，点击即可打开。应用按分页组织，左右滑动切换分页。
| 操作 | 方式 |
|---|---|
| 打开应用 | 点击应用图标 |
| 切换分页 | 左右滑动 / 点击分页指示器 |
| 查看全部应用 | 在 Dock 栏点击「全部应用」 |
Dock 栏
位于屏幕底部，提供常用应用快捷入口：
- 常驻 4-6 个常用应用图标
- 点击图标快速打开
- 支持拖拽排序
分页
桌面支持多分页，左右滑动切换：
- 分页指示器位于 Dock 栏上方
- 每页可放置 24 个应用图标（6×4 网格，横屏）
- 支持拖拽应用图标跨页移动
壁纸切换
在「设置」应用中可自定义壁纸：
- 支持纯色、渐变、图片壁纸
- 壁纸文件存放于
Resources/public/wallpapers/ - 支持自定义上传
锁屏
ClassIntra 通过连续点击手势锁屏与解锁，无需密码：
| 操作 | 手势 | 判定条件 |
|---|---|---|
| 锁屏 | 在屏幕任意位置连续点击 5 次 | 5 次点击在 1 秒内完成 |
| 解锁 | 在屏幕右上角区域连续点击 10 次 | 10 次点击在 3 秒内完成（右上角判定区域为屏幕宽度右侧 30% 且高度顶部 30%） |
锁屏后的行为：
- 全屏黑底，中央显示锁图标与「锁屏中」提示
- 底部显示当前 WIFI 名称与班级名称/IP 信息
- 锁屏时音乐自动暂停并静音，解锁后恢复播放
- 后台应用继续运行，解锁后回到原页面
管理员开关
锁屏功能可在管理后台 → 应用管控 → 系统功能中由管理员开启/关闭。关闭后锁屏手势不再生效，已锁屏的设备会自动解锁（断网保护锁除外）。开关变更通过 WebSocket 实时下发，无需刷新页面。
通知中心（超能岛）
ClassIntra 的通知中心称为「超能岛」（SuperIsland），是位于屏幕顶部的类 iOS 灵动岛组件，也是系统的核心交互枢纽。
形态与模式
超能岛是一个模式状态机，根据当前系统状态自动切换形态：
| 模式 | 触发场景 | 显示内容 |
|---|---|---|
| 紧凑（compact） | 桌面默认状态 | 圆形小岛，显示应用图标 + 简短文字（如广播内容） |
| 分屏（split） | 2 个及以上实时活动 | 左右双区，各显示一个活动 |
| 通知（notification） | 收到新消息/通知 | 弹出式气泡，按优先级（urgent/normal/low）着色，自动收起 |
| 操作面板（actions） | 点击紧凑岛展开 | 快捷入口网格（应用、浏览器、快捷操作） |
| 历史面板（history） | 从操作面板进入 | 历史通知列表 |
| 音乐岛（music-compact / music-expanded） | 后台播放音乐 | 紧凑态显示歌名与歌词，展开态显示进度、歌词、播放控制 |
| 天气预警（weather-compact） | 收到天气预警广播 | 滚动预警文字，点击跳转天气应用 |
| 视频岛（video-compact / video-expanded） | CampusBili 视频播放 | 紧凑态显示视频标题，展开态提供播放控制 |
| 分享胶囊（share-capsule） | 在浏览器中分享内容 | 胶囊样式展示分享内容卡片 |
| 浏览器（browser） | 从操作面板打开浏览器 | 快捷浏览器入口 |
交互手势
| 手势 | 效果 |
|---|---|
| 点击紧凑岛 | 展开操作面板（有视频播放时优先展开视频控制） |
| 点击通知气泡 | 跳转到对应会话/页面 |
| 长按（500ms） | 展开操作面板 |
| 左滑 / 右滑通知 | 关闭当前通知 |
| 上滑音乐岛 | 关闭音乐岛（本次播放不再显示） |
| 点击岛外区域 | 收起展开的面板 |
实时活动
应用可通过 Vuex island 模块的 START_ACTIVITY / UPDATE_ACTIVITY / END_ACTIVITY 向超能岛推送实时活动（如倒计时、课表提醒）。详见 开发指南 — SDK 参考。
主要功能
ClassIntra 内置 8 大模块，覆盖班级日常使用：
| 功能 | 入口 | 说明 |
|---|---|---|
| 💬 聊天 | 聊天图标 | 公共聊天、班级群聊、私聊、表情、消息撤回、群公告 |
| 🤖 AI 对话 | AI 对话图标 | OpenAI 兼容 / DeepSeek 双引擎、Tavily 联网搜索、LaTeX 渲染 |
| 📝 论坛 | 社区图标 | 发帖、评论、点赞、收藏、Markdown + LaTeX、签到经验 |
| 📁 云盘 | 资源仓库图标 | 文件浏览、PDF 预览、MKV/MP4 视频流播放、客上传 |
| 📒 笔记 | 笔意图标 | Markdown 编辑、代码高亮、Mermaid 流程图、KaTeX 公式 |
| 🎵 音乐 | 音乐图标 | 在线播放列表、LRC 歌词同步、背景播放 |
| 🌤️ 天气 | 天气图标 | 实时天气、7 日预报、空气质量、降雨预警动画 |
| ⚙️ 设置 | 设置图标 | 主题、壁纸、锁屏、个人资料、应用管理 |
应用管控
管理员/班干可在管理后台远程启用或禁用桌面上的每个应用，被禁用的应用图标会从桌面隐藏。详见 应用管控。
管理后台
管理后台是班管/管理员的管理中枢，入口位于桌面「管理后台」图标（仅管理员可见）。
功能概述
| 模块 | 功能 |
|---|---|
| 用户管理 | 查看全班用户、封禁/解封、重置密码、调整等级 |
| 广播通知 | 向全班发送系统通知，支持置顶 |
| 班干委任 | 设置/撤销班管权限 |
| 应用管控 | 远程启用/禁用桌面应用，按用户/班级粒度控制 |
| 操作日志 | 记录所有管理操作，便于审计 |
| 群公告 | 设置班级群公告 |
| 资源管理 | 管理云盘文件、视频资源 |
权限说明
管理后台仅对 ADMIN_USER_IDS 匹配的用户开放。普通学生访问会被拒绝并返回 403。班管权限通过预注册名单 + ID 匹配自动授予，无需手动配置。
跨班级联动
多班级部署时，管理后台可配置跨班级中继（通过 RELAY_SERVERS 与 COHORT 环境变量），实现公共聊天室消息实时同步。详见 部署运维。
常见问题
Q1：忘记密码怎么办？
联系班管或管理员，在「管理后台 → 用户管理」中重置密码。班管可通过预注册名单验证身份后重置。
Q2：注册时提示「姓名不在预注册名单」？
预注册名单由 setup 向导导入。若姓名不匹配：
- 确认姓名拼写与名单完全一致（包括标点）
- 联系班管在
server/config/pre-records.json中补充 - 重新执行 setup 或手动编辑名单后重启服务
Q3：登录后看不到某些应用？
应用可能被管理员通过「应用管控」禁用。联系班管在管理后台启用对应应用。也可能是该应用未安装，详见 开发指南。
Q4：AI 对话无响应？
检查 server/.env 中是否配置 AI_API_KEY 或 DEEPSEEK_API_KEY。AI 服务需外网调用，校园内网部署时需配置代理或使用内网 AI 服务。
Q5：天气信息不显示？
检查 server/.env 中是否配置 QWEATHER_KEY（和风天气 API Key）。前往 和风天气开发者平台 免费申请。
Q6：视频无法播放？
ClassIntra 通过 ffmpeg 流式转码播放 MKV/MP4。请确认：
- 服务器已安装 ffmpeg 并加入 PATH
- 视频文件位于
Resources/public/或通过云盘上传 - 浏览器支持 fragmented MP4（Chrome 80+ 均支持）
Q7：如何切换深色/浅色主题？
在「设置 → 主题」中选择深色、浅色或跟随系统。主题切换基于 CSS 变量，无闪烁。
Q8：锁屏后无法解锁怎么办？
ClassIntra 锁屏无需密码，解锁方式是在屏幕右上角区域连续点击 10 次（3 秒内）。若手势不生效：
- 确认点击位置在屏幕右上角（右侧 30% 宽度 × 顶部 30% 高度区域内）
- 确认点击速度足够快（10 次在 3 秒内完成）
- 若仍无法解锁，可联系管理员在管理后台 → 应用管控 → 系统功能关闭锁屏开关，锁屏会自动解除（断网保护锁除外）
下一步
了解基本操作后，建议继续阅读：