feat: 支持班级灵动岛云端配置与跨端同步
This commit is contained in:
1 parent
4449fbd0a1
commit
f6dd59aa25
40 files changed
+1208
-719
No files matched your search
+12
-9
@@ -5,8 +5,9 @@ description: 经典提醒、自定义常驻方案、课程与课件传输。
|
||||
|
||||
# 灵动岛
|
||||
|
||||
灵动岛是客户端的独立透明窗口,不占任务栏。设置中可选择经典 fixed 或自定义 custom,默认 fixed。
|
||||
自定义当前即常驻模式;旧 residentEnabled 字段只作兼容,不是另一个独立开关。
|
||||
灵动岛是客户端的独立透明窗口,不占任务栏。每个班的岛内方案由 Web 管理端「班级灵动岛」维护,
|
||||
教室端登录本班后自动同步;未配置的班使用经典 fixed,默认 fixed。自定义当前即常驻模式;
|
||||
旧 residentEnabled 字段只作兼容,不是另一个独立开关。
|
||||
两种布局共用一个原生窗口,切布局不会新开第二个岛。
|
||||
|
||||
## 两种消息展示
|
||||
@@ -33,19 +34,21 @@ description: 经典提醒、自定义常驻方案、课程与课件传输。
|
||||
| 展开详情 |  |
|
||||
| 紧急通知 |  |
|
||||
|
||||
## 编辑自定义方案
|
||||
## 在 Web 管理端编辑班级方案
|
||||
|
||||
“设置 → 灵动岛 → 自定义 → 编辑岛内组件”进入主窗口设置页。
|
||||
Web 管理端打开「班级与人员 → 班级灵动岛」,先选择班级,再编辑这个班独立的方案。
|
||||
页面上方排列当前组件,右上角选择配置方案;刷新图标重置当前方案,加号新建方案,文件夹菜单提供方案设置、复制、删除及 JSON 导入导出。
|
||||
下方组件库常驻显示文本、分割线、课程表、日期、时钟、天气简报、倒计时和组合容器。通知、作业和叫人通过岛内铃铛及共用消息面板展示,组件库不再提供这些消息选项;已有方案中的消息节点仍兼容。
|
||||
从组件库拖入上方的行或容器以添加,拖动已有组件调整顺序或跨行移动;也可点击组件库添加到选中的容器或当前行。
|
||||
分别编辑常态 rows 与无消息展开 expandedRows,点选组件打开内容、外观、尺寸与隐藏条件设置;行可以新增、排序、设为主要行或删除。
|
||||
“进入编辑模式”切换为实际内容预览,支持预览缩放;退出后回到组件标签排列。轮播和滚动容器在编辑时展示全部子组件,便于选择和排列。
|
||||
“预览组件外观”展示接近教室端的最终岛体,支持预览缩放;常态行固定 40px 高并保持水平、垂直居中。
|
||||
返回结构排列后继续拖拽。轮播和滚动容器在结构排列中展示全部子组件,便于选择和排列。
|
||||
倒计时可指定目标名称与日期,也可按课表倒数至上课、下课或放学。
|
||||
天气简报需填写地点名称及经纬度,使用 [Open-Meteo](https://open-meteo.com/en/docs) 的天气数据,每 15 分钟更新;断网时保留本次客户端运行中的缓存并标明“缓存”。天气提示根据天气概况生成,不提供官方气象预警。
|
||||
方案保存到本机 config.json.islandLayout,不增加服务端同步。
|
||||
编辑预览不创建额外桌面窗口;打开编辑页不自动切布局,应用后启用自定义方案。
|
||||
保存按序进行,失败可重试,主题与关怀模式沿用客户端设置。
|
||||
方案保存到班级记录,仅本班班主任或管理员可写;班级账号和教室客户端只读本班方案。
|
||||
保存后服务端广播 `class:updated`,客户端立即拉取;断线时保留本机上一次已同步方案。
|
||||
客户端设置页不再提供岛内组件编辑入口,只展示当前是否使用服务端下发方案。
|
||||
提醒阈值与指针避让仍按教室本机偏好保存,不随班级布局覆盖。
|
||||
|
||||
## 外观、位置与输入
|
||||
|
||||
@@ -54,7 +57,7 @@ description: 经典提醒、自定义常驻方案、课程与课件传输。
|
||||
强调色支持自定义、壁纸调色板、跟随系统和屏幕调色板四种来源;自定义背景与前景可分别关闭,关闭后回落当前亮/暗主题。前景色会派生 100% / 85.5% / 77.3% / 52.9% / 36.5% 五级文字 alpha。外观页的圆角滑块同步修改当前自定义方案的常态圆角,与编辑器设置一致。
|
||||
左右边距只在左/右停靠时生效,居中锚点仍在屏幕中线。
|
||||
触摸屏自动进入触摸模式,保留触摸命中和失焦宽限;鼠标模式按光标控制输入穿透。
|
||||
自定义常驻内容支持鼠标避让淡化及反转,交互入口、展开/编辑和触摸操作按实现暂停避让。
|
||||
自定义常驻内容支持鼠标避让淡化及反转,交互入口、展开和触摸操作按实现暂停避让。
|
||||
应用内动画开关决定岛动画,不能用主窗口的减少动态效果说明替代岛自身规则。
|
||||
|
||||
经典几何与配色参考见[设计令牌](../dev/winisland-design-tokens.md),实现入口见[当前实现约定](../dev/implementation.md)。
|
||||
|
||||
+13
-12
@@ -12,18 +12,19 @@ API 前缀 /api,JWT 使用 Authorization: Bearer。成功/失败结构以 `lib
|
||||
|
||||
## 身份与班级
|
||||
|
||||
| 方法与路径(省略 /api) | 行为及边界 |
|
||||
| ----------------------------------------------------------------------- | -------------------------------------------------------------- |
|
||||
| POST /auth/login、/auth/class-login | 员工/班级登录,共享登录限流;学生无账号 |
|
||||
| GET /auth/me;POST /auth/logout;PATCH /auth/password | 当前身份、退出、员工本人改密码 |
|
||||
| GET/POST /classes;GET/PATCH/DELETE /classes/:id | 班级查询/管理,读取 class:read;写入 class:manage 且仅管理员 |
|
||||
| PATCH /classes/:id/class-account、/classes/:id/head-teacher | 班级凭据 class:account + 班主任;班主任分配仅管理员 |
|
||||
| PUT /classes/:id/subject-teachers | 任课关系设置,Course 为唯一来源 |
|
||||
| GET/PATCH /classes/:id/student-grade-query | 查看/修改班级个人成绩查询开关,班级端不能修改 |
|
||||
| GET/POST /classes/:id/students;DELETE /classes/:id/students/:studentId | 本班名单及维护,受名单功能权限和班级关系约束 |
|
||||
| /students、/teachers | 名单与账号 CRUD;读/写使用不同权限键,具体角色限制读取对应模块 |
|
||||
| POST /teachers/:id/reset-password | 指定新密码或默认重置;学生无对应接口 |
|
||||
| /permissions/me、/catalog、/groups、/users | 当前有效权限、目录、组与账号分组 |
|
||||
| 方法与路径(省略 /api) | 行为及边界 |
|
||||
| ----------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
|
||||
| POST /auth/login、/auth/class-login | 员工/班级登录,共享登录限流;学生无账号 |
|
||||
| GET /auth/me;POST /auth/logout;PATCH /auth/password | 当前身份、退出、员工本人改密码 |
|
||||
| GET/POST /classes;GET/PATCH/DELETE /classes/:id | 班级查询/管理,读取 class:read;写入 class:manage 且仅管理员 |
|
||||
| PATCH /classes/:id/class-account、/classes/:id/head-teacher | 班级凭据 class:account + 班主任;班主任分配仅管理员 |
|
||||
| PUT /classes/:id/subject-teachers | 任课关系设置,Course 为唯一来源 |
|
||||
| GET/PATCH /classes/:id/student-grade-query | 查看/修改班级个人成绩查询开关,班级端不能修改 |
|
||||
| GET/PATCH /classes/:id/island-layout | 班级灵动岛方案;读取 class:read,写入 class:settings + 班主任,班级端只读本班 |
|
||||
| GET/POST /classes/:id/students;DELETE /classes/:id/students/:studentId | 本班名单及维护,受名单功能权限和班级关系约束 |
|
||||
| /students、/teachers | 名单与账号 CRUD;读/写使用不同权限键,具体角色限制读取对应模块 |
|
||||
| POST /teachers/:id/reset-password | 指定新密码或默认重置;学生无对应接口 |
|
||||
| /permissions/me、/catalog、/groups、/users | 当前有效权限、目录、组与账号分组 |
|
||||
|
||||
## 教学与文件
|
||||
|
||||
|
||||
@@ -24,11 +24,16 @@ description: 课表、周次、学年、岛、设备与课件的现行实现入
|
||||
年度升级由 `term.promotionPlan`、`term.promotionAt` 和 `PromotionRun.year` 管理,先存快照;运行期到点执行,启动漏跑需管理员预览补跑。
|
||||
毕业班归档,其余升一级,新班不复制任课关系。转出学生由 `lib/students.ts` 统一过滤。
|
||||
|
||||
## 岛与本机配置
|
||||
## 岛、班级方案与本机配置
|
||||
|
||||
方案存 `config.json.islandLayout`,默认 fixed。当前 custom 即常驻,归一化将兼容字段 residentEnabled 与 custom 对齐。
|
||||
每个班的方案存 `Class.islandLayoutJson`,默认未配置时回落本机 `config.json.islandLayout` 的 fixed。
|
||||
Web 管理端「班级灵动岛」用 `class:read` 读取、`class:settings` + 班主任关系写入;班级端只能读本班。
|
||||
保存后广播 `class:updated`,客户端按登录班级拉取并写入本机配置,供离线启动沿用。
|
||||
客户端合并服务端方案时保留本机提醒阈值与指针避让;未配置的班回退经典 default,避免沿用上一个班。
|
||||
当前 custom 即常驻,归一化将兼容字段 residentEnabled 与 custom 对齐。
|
||||
`LayoutIslandApp.vue` 选择经典 `IslandApp.vue` 或 `CustomIslandRuntime.vue`,只有一个原生岛窗口。
|
||||
自定义常态行与无消息展开行独立编辑,通知列表复用 `ClassicNotifications.vue`;编辑页是主窗口设置子路由。
|
||||
自定义常态行与无消息展开行独立编辑,通知列表复用 `ClassicNotifications.vue`;
|
||||
编辑器和预览在 Web 管理端,教室客户端不再注册布局编辑路由。
|
||||
自定义模式通过铃铛提示新消息,点击查看;经典模式普通通知上课暂存、普通叫人可点开胶囊、紧急消息自动展开。
|
||||
课程提醒配置独立保存,课件传输期间由 `CoursewareTransfer.vue` 显示进度。
|
||||
|
||||
|
||||
@@ -74,15 +74,15 @@ ClassIsland 源值中的颜色采用 Avalonia `AARRGGBB`,写入 CSS 时统一
|
||||
|
||||
### 主界面对照
|
||||
|
||||
| ClassIsland 概念 | ClassHelper 实体 |
|
||||
| ----------------------- | ------------------------------------------------------------------ |
|
||||
| MainWindow | 独立 `island.html` + 主进程透明 `BrowserWindow` |
|
||||
| MainWindowLine | `CustomIslandRuntime.vue` 的 `.layout-row` 与行级 CSS 变量 |
|
||||
| ComponentPresenter | `ComponentNode.vue` 根节点的宽高、透明度、隐藏与裁剪 |
|
||||
| 日期/时钟/天气/课程组件 | `ComponentNode.vue`、`WeatherBrief.vue` 等共享组件 |
|
||||
| Fluent/Classic 主题 | `custom-runtime.css` / `custom-island.css` / `classic-island.css` |
|
||||
| 编辑模式视图 | 主窗口 `IslandEditorView.vue`、`IslandEditorNode.vue` 与右侧检查器 |
|
||||
| 提醒宿主 | `ClassicNotifications.vue`,嵌入自定义岛或经典岛 |
|
||||
| ClassIsland 概念 | ClassHelper 实体 |
|
||||
| ----------------------- | ------------------------------------------------------------------------------------------------ |
|
||||
| MainWindow | 独立 `island.html` + 主进程透明 `BrowserWindow` |
|
||||
| MainWindowLine | `CustomIslandRuntime.vue` 的 `.layout-row` 与行级 CSS 变量 |
|
||||
| ComponentPresenter | `ComponentNode.vue` 根节点的宽高、透明度、隐藏与裁剪 |
|
||||
| 日期/时钟/天气/课程组件 | `ComponentNode.vue`、`WeatherBrief.vue` 等共享组件 |
|
||||
| Fluent/Classic 主题 | `custom-runtime.css` / `custom-island.css` / `classic-island.css` |
|
||||
| 编辑与预览视图 | Web 管理端 `IslandLayoutsView.vue`、`IslandEditorNode.vue`、`IslandPreviewNode.vue` 与右侧检查器 |
|
||||
| 提醒宿主 | `ClassicNotifications.vue`,嵌入自定义岛或经典岛 |
|
||||
|
||||
## 动画与命中
|
||||
|
||||
@@ -98,6 +98,6 @@ ClassIsland 源值中的颜色采用 Avalonia `AARRGGBB`,写入 CSS 时统一
|
||||
## 修改入口
|
||||
|
||||
外观范围改 shared,经典样式改 classic-island.css,自定义样式改 custom-runtime.css 和 custom-island.css,
|
||||
原生窗口与命中改 main/island.ts。组件结构/设置改 shared/island-layout.ts 并同步编辑器和运行时。
|
||||
原生窗口与命中改 main/island.ts。组件结构/设置改 shared/island-layout.ts 并同步 Web 编辑器和运行时。
|
||||
改 token 后运行 `pnpm check:design-tokens`,它会校验亮/暗键集合、必备 token、kebab-case 与岛内裸颜色。
|
||||
展示行为见[灵动岛](../app/island.md),测试见[验收与测试](testing.md)。
|
||||
+19
-19
@@ -8,25 +8,25 @@ description: 当前功能说明、开发契约与实现入口,避免重复维
|
||||
本文为现行文档入口。功能规则在对应章节维护;源码行为发生变化时,同步修改对应章节。
|
||||
旧任务书、历史审查结论和旧构建验收数字不作为当前功能依据。
|
||||
|
||||
| 主题 | 文档 | 工作区源码入口 |
|
||||
| ------------------ | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
|
||||
| 架构与模块 | [架构总览](dev/architecture.md) | `server/src/modules/registry.ts` |
|
||||
| 日课表、作息与轮换 | [课表](app/schedules.md) | `server/src/lib/class-plan.ts`、`modules/class-plans/` |
|
||||
| 学生、教师、班级 | [班级、学生与教师](app/classes.md) | `server/src/lib/access.ts`、`modules/students/` |
|
||||
| 权限组与岗位范围 | [角色与权限](dev/permissions.md) | `shared/src/permissions.ts`、`server/src/lib/authz/`、`server/src/lib/permissions.ts` |
|
||||
| 作业 | [作业](app/homeworks.md) | `server/src/modules/homeworks/` |
|
||||
| AI 助手 | [解析与确认发布](app/assistant.md) | `server/src/modules/ai/`、`web-admin/src/views/AssistantView.vue` |
|
||||
| 通知与叫人 | [通知](app/notifications.md)、[叫人](app/calls.md) | `server/src/modules/notifications/`、`calls/` |
|
||||
| 课件 | [课件上传与传输](app/courseware.md) | 三端 `courseware` 模块与 `shared/src/courseware.ts` |
|
||||
| 成绩与隐私 | [成绩](app/grades.md) | `server/src/modules/grades/` |
|
||||
| 经典与自定义常驻岛 | [灵动岛](app/island.md) | `desktop-client/src/island/LayoutIslandApp.vue`、`CustomIslandRuntime.vue` |
|
||||
| 导入 | [表格与课表导入](app/imports.md) | `server/src/modules/imports/`、`class-plans/profile-import.service.ts` |
|
||||
| API 与实时 | [REST API](dev/api.md)、[实时事件](dev/realtime.md) | `server/src/modules/`、`realtime/`、`shared/src/constants.ts` |
|
||||
| 数据模型与迁移 | [数据模型](dev/data-model.md) | `server/prisma/schema.prisma`、`migrations/` |
|
||||
| 数据库管理 | [数据库管理](management/database.md)、[MySQL](management/mysql.md) | `server/src/lib/snapshot.ts`、`modules/database/` |
|
||||
| 安装与升级 | [生产部署](management/production.md)、[Linux](management/linux-deploy.md)、[更新](management/upgrade.md) | `deploy/`、`scripts/dist-server.mjs` |
|
||||
| 验证与发布 | [验收](dev/testing.md)、[发布](dev/release.md) | 根 `package.json`、`scripts/`、`.github/workflows/` |
|
||||
| 当前实现约定 | [实现约定](dev/implementation.md) | 课表、升级、岛、课件与设备维护的关键边界 |
|
||||
| 主题 | 文档 | 工作区源码入口 |
|
||||
| ------------------ | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
|
||||
| 架构与模块 | [架构总览](dev/architecture.md) | `server/src/modules/registry.ts` |
|
||||
| 日课表、作息与轮换 | [课表](app/schedules.md) | `server/src/lib/class-plan.ts`、`modules/class-plans/` |
|
||||
| 学生、教师、班级 | [班级、学生与教师](app/classes.md) | `server/src/lib/access.ts`、`modules/students/` |
|
||||
| 权限组与岗位范围 | [角色与权限](dev/permissions.md) | `shared/src/permissions.ts`、`server/src/lib/authz/`、`server/src/lib/permissions.ts` |
|
||||
| 作业 | [作业](app/homeworks.md) | `server/src/modules/homeworks/` |
|
||||
| AI 助手 | [解析与确认发布](app/assistant.md) | `server/src/modules/ai/`、`web-admin/src/views/AssistantView.vue` |
|
||||
| 通知与叫人 | [通知](app/notifications.md)、[叫人](app/calls.md) | `server/src/modules/notifications/`、`calls/` |
|
||||
| 课件 | [课件上传与传输](app/courseware.md) | 三端 `courseware` 模块与 `shared/src/courseware.ts` |
|
||||
| 成绩与隐私 | [成绩](app/grades.md) | `server/src/modules/grades/` |
|
||||
| 经典与自定义常驻岛 | [灵动岛](app/island.md) | `desktop-client/src/island/LayoutIslandApp.vue`、`CustomIslandRuntime.vue`;Web `IslandLayoutsView.vue` |
|
||||
| 导入 | [表格与课表导入](app/imports.md) | `server/src/modules/imports/`、`class-plans/profile-import.service.ts` |
|
||||
| API 与实时 | [REST API](dev/api.md)、[实时事件](dev/realtime.md) | `server/src/modules/`、`realtime/`、`shared/src/constants.ts` |
|
||||
| 数据模型与迁移 | [数据模型](dev/data-model.md) | `server/prisma/schema.prisma`、`migrations/` |
|
||||
| 数据库管理 | [数据库管理](management/database.md)、[MySQL](management/mysql.md) | `server/src/lib/snapshot.ts`、`modules/database/` |
|
||||
| 安装与升级 | [生产部署](management/production.md)、[Linux](management/linux-deploy.md)、[更新](management/upgrade.md) | `deploy/`、`scripts/dist-server.mjs` |
|
||||
| 验证与发布 | [验收](dev/testing.md)、[发布](dev/release.md) | 根 `package.json`、`scripts/`、`.github/workflows/` |
|
||||
| 当前实现约定 | [实现约定](dev/implementation.md) | 课表、升级、岛、课件与设备维护的关键边界 |
|
||||
|
||||
表中的包路径均相对仓库 `packages/`;脚本和部署目录相对仓库根。
|
||||
源码总入口:[GitHub 仓库](https://github.com/LoveChengke/ClassHelper)。
|
||||
|
||||
Reference in new issue
Block a user