2026-10-11 11:49:32 +08:00
import type {
ClientCommandKind ,
GradeLevelType ,
NotificationPriority ,
StudentGender ,
StudentStatus ,
UserRole ,
} from './types.js' ;
2026-09-11 21:57:38 +08:00
/** API 前缀 */
export const API_PREFIX = '/api' ;
/** REST 路径集中管理,避免前端散落硬编码字符串 */
export const API_PATHS = {
auth : {
login : '/auth/login' ,
logout : '/auth/logout' ,
me : '/auth/me' ,
changePassword : '/auth/password' ,
},
classes : '/classes' ,
courses : '/courses' ,
schedules : '/schedules' ,
homeworks : '/homeworks' ,
notifications : '/notifications' ,
2026-09-12 13:57:46 +08:00
/** 叫人:老师点名让学生过来 */
calls : '/calls' ,
2026-09-11 21:57:38 +08:00
grades : '/grades' ,
students : '/students' ,
teachers : '/teachers' ,
2026-09-12 15:35:01 +08:00
/** 导入:模板下载 / 表格导入 / ClassIsland 课表时间配置 */
imports : '/imports' ,
2026-10-06 19:41:18 +08:00
/** 毕业归档:届别档案、归档详情、学年升级(仅管理员) */
archives : '/archives' ,
/** 学期周次:逐周日期区间、按开学日期自动生成、联网拉取调休建议(仅管理员) */
term : '/term' ,
2026-10-02 11:18:47 +08:00
/** 数据库管理(仅管理员):状态/备份/导入导出/一键切换 */
database : '/database' ,
2026-10-05 16:39:38 +08:00
/** 更新检查:Web 端经服务端转发查 GitHub 上的最新 Release(浏览器受 CSP 限制不能直连) */
update : '/update' ,
2026-10-11 11:49:32 +08:00
/** 权限组:权限目录、组的增删改、成员分配、当前账号生效权限 */
permissions : '/permissions' ,
/** ClassHelper 客户端设备:心跳、设备清单、统一下发更新与远控指令 */
clients : '/clients' ,
/** 大模型助手:设置(仅管理员)、一句话解析、使用记录 */
ai : '/ai' ,
/** 系统设置与诊断:开发者模式、服务端开机自启、运行诊断(仅管理员) */
system : '/system' ,
2026-09-11 21:57:38 +08:00
dashboard : '/dashboard/summary' ,
} as const ;
2026-10-06 19:41:18 +08:00
/**
* 账号角色。
*
* **没有 STUDENT** —— 学生不是账号,只是班级名单记录(`Student` 表),没有密码、没有登录入口。
* `CLASS_DEVICE` = 教室里绑定到某个班的 ClassHelper 班级端。
*/
export const USER_ROLES : readonly UserRole [] = [ 'ADMIN' , 'TEACHER' , 'CLASS_DEVICE' ];
2026-09-11 21:57:38 +08:00
export const ROLE_LABELS : Record < UserRole , string > = {
ADMIN : '系统管理员' ,
TEACHER : '教师' ,
2026-10-06 19:41:18 +08:00
CLASS_DEVICE : 'ClassHelper 班级端' ,
};
/** 教师与管理员(staff)角色 */
export const STAFF_ROLES : readonly UserRole [] = [ 'ADMIN' , 'TEACHER' ];
/* ------------------------------------------------------------------ 班级教师结构 */
/**
* 班级内的教师角色:
* - `HEAD` 班主任:每个班 1 人(`Class.teacherId`)
* - `SUBJECT` 科任老师:按科目配置(`Course.teacherId`,即"班级 + 科目 + 教师")
*
* 同一教师可以在同一个班同时是班主任和某科科任老师 —— 系统里只保留**一个**教师账号,
* 两处都指向它,权限在 `resolveClassRole()` 里合并,不重复建号、不产生冲突。
*/
export const CLASS_TEACHER_ROLES = [ 'HEAD' , 'SUBJECT' ] as const ;
export type ClassTeacherRole = ( typeof CLASS_TEACHER_ROLES )[ number ];
export const CLASS_TEACHER_ROLE_LABELS : Record < ClassTeacherRole , string > = {
HEAD : '班主任' ,
SUBJECT : '科任老师' ,
};
/* ------------------------------------------------------------------ 学生名单 */
2026-10-17 03:06:46 +08:00
export const STUDENT_STATUSES : readonly StudentStatus [] = [ 'active' , 'graduated' , 'transferred' , 'inactive' ];
2026-10-06 19:41:18 +08:00
export const STUDENT_STATUS_LABELS : Record < StudentStatus , string > = {
active : '在读' ,
graduated : '已毕业' ,
transferred : '已转出' ,
inactive : '停用' ,
};
/** Element Plus tag 类型(学生状态徽标配色,三端统一) */
export const STUDENT_STATUS_TAG_TYPES : Record < StudentStatus , 'success' | 'info' | 'warning' | 'danger' > = {
active : 'success' ,
graduated : 'info' ,
transferred : 'warning' ,
inactive : 'danger' ,
};
export const STUDENT_GENDERS : readonly StudentGender [] = [ '' , 'MALE' , 'FEMALE' ];
export const STUDENT_GENDER_LABELS : Record < StudentGender , string > = {
'' : '未填' ,
MALE : '男' ,
FEMALE : '女' ,
};
/* ------------------------------------------------------------------ 班级称呼与届别 */
/** 默认学制(年):入学年份 + 它 = 毕业年份。高中与初中都是 3 年 */
export const DEFAULT_SCHOOLING_YEARS = 3 ;
/**
* 班级称呼:`XXXX级X班`(入学年份 + 班号)。
*
* 用入学年份而不是「高一(1)班」这类写法,是因为后者每年都要改一遍,
* 而前者一路跟着这届学生到毕业 —— 升级只改 `Class.grade`,称呼不变。
*/
export function formatClassName ( enrollmentYear : number , classIndex : number ) : string {
return ` ${ enrollmentYear } 级 ${ classIndex } 班` ;
}
/** 届别名:`2026 级` */
export function formatYearLabel ( enrollmentYear : number ) : string {
return ` ${ enrollmentYear } 级` ;
}
/** 毕业年份(入学年份 + 学制) */
export function graduationYearOf ( enrollmentYear : number , schoolingYears = DEFAULT_SCHOOLING_YEARS ) : number {
return enrollmentYear + schoolingYears ;
}
/**
* 按当前时间推断「本学年的起始年份」:学年在 9 月切换,
* 9 月及以后算今年起始,之前算去年起始(8 月及以前仍属上一学年)。
*/
export function currentAcademicYearStart ( now : Date = new Date ()) : number {
return now . getMonth () >= 8 ? now . getFullYear () : now . getFullYear () - 1 ;
}
/* ------------------------------------------------------------------ 成绩等级 */
/** 等级口径可选值:百分制 / 等级制 A-D / 自定义等级 */
export const GRADE_LEVEL_TYPES : readonly GradeLevelType [] = [ 'percent' , 'letter' , 'custom' ];
export const GRADE_LEVEL_TYPE_LABELS : Record < GradeLevelType , string > = {
percent : '百分制' ,
letter : '等级制(A/B/C/D) ' ,
custom : '自定义等级' ,
2026-09-11 21:57:38 +08:00
};
2026-10-06 19:41:18 +08:00
export const GRADE_LEVEL_TYPE_HINTS : Record < GradeLevelType , string > = {
percent : '按分数录入,等级由得分率自动换算(教师仍可逐条手动改)' ,
letter : '直接给 A / B / C / D,分数可留空' ,
custom : '自己定义等级文本(如 优 / 良 / 合格 / 待提高)' ,
};
/** 等级制的默认档位(仅 UI 快捷选项,自定义等级不受限制) */
export const DEFAULT_LETTER_LEVELS : readonly string [] = [ 'A' , 'B' , 'C' , 'D' ];
/* ------------------------------------------------------------------ ClassHelper 班级端 */
/**
* ClassHelper 班级端在线判定窗口(毫秒)。
*
2026-10-18 11:53:37 +08:00
* @deprecated 旧联动在线窗口兼容导出,当前设备在线状态使用 CLIENT_ONLINE_WINDOW_MS。
2026-10-06 19:41:18 +08:00
*/
export const CLASS_HELPER_ONLINE_WINDOW_MS = 60 _000 ;
2026-10-18 11:53:37 +08:00
/** @deprecated 旧联动状态页刷新间隔,现行设备页不使用。 */
2026-10-06 19:41:18 +08:00
export const CLASS_HELPER_STATUS_REFRESH_SECONDS = 30 ;
2026-09-11 21:57:38 +08:00
/** 通知优先级 */
export const NOTIFICATION_PRIORITIES : readonly NotificationPriority [] = [ 'LOW' , 'NORMAL' , 'HIGH' , 'URGENT' ];
export const PRIORITY_LABELS : Record < NotificationPriority , string > = {
LOW : '低' ,
NORMAL : '普通' ,
HIGH : '重要' ,
URGENT : '紧急' ,
};
/** Element Plus tag 类型,三端统一文案与配色 */
export const PRIORITY_TAG_TYPES : Record < NotificationPriority , 'info' | 'primary' | 'warning' | 'danger' > = {
LOW : 'info' ,
NORMAL : 'primary' ,
HIGH : 'warning' ,
URGENT : 'danger' ,
};
2026-10-02 00:24:58 +08:00
/**
* 优先级权重(越大越重要)。
*
2026-10-18 11:53:37 +08:00
* 灵动岛列表排序和同 id 消息合并共用,保证展示顺序与优先级合并一致。
2026-10-02 00:24:58 +08:00
*/
export const PRIORITY_RANK : Record < NotificationPriority , number > = {
LOW : 0 ,
NORMAL : 1 ,
HIGH : 2 ,
URGENT : 3 ,
};
2026-09-11 21:57:38 +08:00
/** 星期:1=周一 ... 7=周日(与数据库 dayOfWeek 一致) */
export const WEEKDAY_LABELS : Record < number , string > = {
1 : '周一' ,
2 : '周二' ,
3 : '周三' ,
4 : '周四' ,
5 : '周五' ,
6 : '周六' ,
7 : '周日' ,
};
export const WEEKDAYS : readonly number [] = [ 1 , 2 , 3 , 4 , 5 , 6 , 7 ];
2026-09-13 08:39:11 +08:00
/**
2026-09-13 10:34:46 +08:00
* 统一授课科目目录(**全校固定**):作业、课表、成绩的"科目"都从这里选,
* 不需要按班级一个个建课 —— 选中后由前端自动为该班建好同名课程(已存在则复用)。
* 顺序按用户给定的作息习惯:文化课 → 技术 → 体艺 → 班会与早晚读 → 通用技术 → 听力。
2026-09-13 08:39:11 +08:00
*/
export const SUBJECT_CATALOG : readonly string [] = [
'语文' ,
'数学' ,
'英语' ,
'政治' ,
'历史' ,
2026-09-13 10:34:46 +08:00
'物理' ,
'化学' ,
2026-09-13 08:39:11 +08:00
'地理' ,
2026-09-13 10:34:46 +08:00
'生物' ,
2026-09-13 08:39:11 +08:00
'信息技术' ,
'体育' ,
'美术' ,
2026-09-13 10:34:46 +08:00
'音乐' ,
'班会' ,
'早读' ,
'晚读' ,
'通用技术' ,
'听力' ,
2026-09-13 08:39:11 +08:00
] as const ;
2026-09-12 23:48:59 +08:00
/**
* 单双周标签与取值(课表用)。
* 语义与 ClassIsland 课表一致:WeekCountDivTotal=1 → 每周;=2 时 WeekCountDiv=1 → 单周、=2 → 双周。
*/
export const WEEK_PARITY_LABELS : Record < 'ALL' | 'ODD' | 'EVEN' , string > = {
ALL : '每周' ,
ODD : '单周' ,
EVEN : '双周' ,
};
export const WEEK_PARITY_VALUES : readonly ( 'ALL' | 'ODD' | 'EVEN' )[] = [ 'ALL' , 'ODD' , 'EVEN' ];
/** 一个学期按多少周为一个单双周循环(ClassIsland WeekCountDivTotal 的默认值) */
export const WEEK_PARITY_CYCLE = 2 ;
2026-11-17 18:57:32 +08:00
/**
* ClassIsland 岛层设计 token 的 TypeScript 单一来源。
*
* CSS 变量在 `packages/ui/src/tokens.css` 中按 `--ci-*` 一一映射;窗口几何、
* 主进程安全区与设置页范围直接复用本对象,避免 TypeScript 与 CSS 各写一套。
* 应用外壳仍使用 `--ch-*` / `--ch-ui-*`,本对象只服务于岛与课程信息层。
*/
export const CLASSISLAND_TOKENS = {
colors : {
light : {
primaryColor : '#00BFFF' ,
secondaryColor : '#7FFFD4' ,
accentFallback : '#1E90FF' ,
accentPaletteFallback : '#1E90FF' ,
/** ClassIsland 原值 #E4000000( AARRGGBB),CSS 写作 RRGGBBAA。 */
text1 : '#000000E4' ,
/** ClassIsland 浅色主题对 InformativeSecondary 的覆盖值。 */
text2 : '#000000C0' ,
text3 : '#00000072' ,
text4 : '#0000005C' ,
text5 : '#0000002E' ,
textOnAccent : '#FFFFFFFF' ,
bgBase : '#F3F3F3' ,
bgSecondary : '#EEEEEE' ,
bgTertiary : '#F9F9F9' ,
fillSecondary : '#0000000A' ,
smoke : '#00000066' ,
islandBgCustom : '#000000' ,
strokeIsland : '#00000014' ,
strokeControl : '#00000024' ,
strokeDivider : '#00000014' ,
strokeFlyout : '#0000001B' ,
fillStrong : '#00000072' ,
strokeCard : '#00000016' ,
strokeDrag : '#1E90FF' ,
strokeTutorial : '#1E90FF' ,
aqi1 : '#228B22' ,
aqi2 : '#CCCC00' ,
aqi3 : '#FF8C00' ,
aqi4 : '#CD5C5C' ,
aqi5 : '#8B0000' ,
aqi6 : '#800080' ,
weatherRain : '#0000FF' ,
glowClass : '#FFFF00' ,
danger : '#CD5C5C' ,
warningCritical : '#C42B1C' ,
warningCaution : '#9D5D00' ,
warningCautionBackground : '#FFF4CE' ,
},
dark : {
primaryColor : '#00BFFF' ,
secondaryColor : '#7FFFD4' ,
accentFallback : '#1E90FF' ,
accentPaletteFallback : '#1E90FF' ,
text1 : '#FFFFFFFF' ,
/** ClassIsland 深色主题对 InformativeSecondary 的覆盖值。 */
text2 : '#FFFFFFDA' ,
text3 : '#FFFFFFC5' ,
text4 : '#FFFFFF87' ,
text5 : '#FFFFFF5D' ,
textOnAccent : '#FFFFFFFF' ,
bgBase : '#202020' ,
bgSecondary : '#1C1C1C' ,
bgTertiary : '#282828' ,
fillSecondary : '#FFFFFF14' ,
smoke : '#00000066' ,
islandBgCustom : '#000000' ,
strokeIsland : '#FFFFFF26' ,
strokeControl : '#FFFFFF3D' ,
strokeDivider : '#FFFFFF26' ,
strokeFlyout : '#FFFFFF33' ,
fillStrong : '#FFFFFF8A' ,
strokeCard : '#FFFFFF26' ,
strokeDrag : '#00BFFF' ,
strokeTutorial : '#00BFFF' ,
aqi1 : '#3CB371' ,
aqi2 : '#FFFF00' ,
aqi3 : '#FFA500' ,
aqi4 : '#CD5C5C' ,
aqi5 : '#8B0000' ,
aqi6 : '#9370DB' ,
weatherRain : '#00BFFF' ,
glowClass : '#FFFF00' ,
danger : '#CD5C5C' ,
warningCritical : '#FF99A4' ,
warningCaution : '#FCE100' ,
warningCautionBackground : '#433519' ,
},
},
fonts : {
app : "'HarmonyOS Sans SC', 'Microsoft YaHei UI', 'Noto Sans CJK SC', 'Noto Sans SC', 'PingFang SC', 'Source Han Sans SC', SimHei, 'WenQuanYi Micro Hei', sans-serif" ,
island :
"'HarmonyOS Sans SC', 'Microsoft YaHei UI', 'Noto Sans CJK SC', 'Noto Sans SC', 'PingFang SC', 'Source Han Sans SC', SimHei, 'WenQuanYi Micro Hei', sans-serif" ,
harmonyOsSans : "'HarmonyOS Sans SC', 'Microsoft YaHei UI', SimHei" ,
backend : "'Microsoft YaHei UI'" ,
iconFluent : "'FluentSystemIcons-Resizable'" ,
iconLucide : "'lucide'" ,
iconSf : "'SF-Symbols'" ,
},
fontWeights : {
thin : 100 ,
extraLight : 200 ,
light : 300 ,
normal : 400 ,
medium : 500 ,
semiBold : 600 ,
bold : 700 ,
extraBold : 800 ,
black : 900 ,
},
fontSizes : {
secondary : 14 ,
body : 16 ,
emphasized : 18 ,
large : 20 ,
version : 9 ,
caption : 12 ,
controlBase : 13 ,
label : 14 ,
title : 16 ,
rolling : 17 ,
oobeBody : 18 ,
brand : 20 ,
weather : 22 ,
oobeTitle : 32 ,
inputMin : 1 ,
inputMax : 40 ,
inputStep : 0.5 ,
},
radii : {
island : 8 ,
islandLocal : 0 ,
islandMax : 20 ,
islandStep : 0.5 ,
popup : 6 ,
card : 4 ,
control : 4 ,
drawer : '8px 8px 0 0' ,
pill : 999 ,
iconButton : 14 ,
oobeButton : 24 ,
},
spacing : {
islandHeight : 40 ,
islandPadX : 12 ,
islandMinWidth : 20 ,
componentGap : 12 ,
lineGap : 5 ,
settingsMaxWidth : 960 ,
popupPad : 12 ,
progressHeight : 3 ,
editbarBottom : 64 ,
splashWidth : 400 ,
splashHeight : 100 ,
},
shadows : {
island : '0 4px 8px 2px #00000048' ,
mask : '0 8px 32px 0 #00000066' ,
drawer : '0 8px 32px 0 #00000066' ,
drawerX : '0 0 8px #00000033' ,
classicMask : '0 0 8px #000000' ,
adorn : '0 0 8px #00000066' ,
},
opacity : {
islandBackground : 0.5 ,
line : 1 ,
pointerFaded : 0.05 ,
maskFrom : 0 ,
maskTo : 1 ,
},
layers : {
windowBottom : 0 ,
windowTop : 1 ,
content : 0 ,
mask : 1 ,
drag : 1 ,
drawer : 10 ,
timelineAdorn : 9999 ,
guide : 10000 ,
/** 原值 33550336;Web 层用浏览器最大安全整数哨兵表达同一语义。 */
sentinel : 2147483647 ,
},
dpi : {
/** ClassIsland 的所有视觉值都以 96 DPI 的 CSS px 为基准。 */
basis : 96 ,
scale : 1 ,
scaleMin : 0.75 ,
scaleMax : 2.5 ,
scaleStep : 0.05 ,
verticalSafeArea : 20 ,
tutorialSafeArea : 150 ,
effectScale : 1 ,
},
misc : {
rippleStroke : 200 ,
maskFade : 'linear-gradient(to bottom, #FFFFFF00, #FFFFFF00 65%, #FFFFFFFF)' ,
scrimTutorial : '#00000099' ,
debugBackground : '#22222277' ,
splashBackground : '#11111188' ,
brandGradientA : '#0C0E1F' ,
brandGradientB : '#0D1111' ,
brandDark : '#0D1111' ,
},
} as const ;
/** ClassIsland `IntToFontWeightConverter` 的逐值映射;其他值回落 Normal。 */
export function classislandFontWeight ( value : unknown ) : number {
if (
typeof value === 'number' &&
value >= CLASSISLAND_TOKENS . fontWeights . thin &&
value <= CLASSISLAND_TOKENS . fontWeights . black &&
value % 100 === 0
) {
return value ;
}
return CLASSISLAND_TOKENS . fontWeights . normal ;
}
2026-09-12 15:19:13 +08:00
/** 灵动岛默认外观(设置页个性化项的初始值,也是区间校验的单一来源) */
export const DEFAULT_ISLAND_APPEARANCE = {
height : 44 ,
width : 268 ,
radius : 20 ,
opacity : 1 ,
2026-11-17 18:57:32 +08:00
/** 默认强调色与 ClassIsland 的 PrimaryColor 对齐。 */
accent : CLASSISLAND_TOKENS.colors.light.primaryColor ,
/** 0=自定义,1=壁纸主题色,2=跟随系统,3=屏幕主题色;未知值回落兜底色。 */
accentSource : 0 ,
accentPalette : [ CLASSISLAND_TOKENS . colors . light . primaryColor ] as string [],
accentPaletteIndex : 0 ,
2026-09-12 15:19:13 +08:00
fontSize : 13 ,
animations : true ,
speed : 1 ,
position : 'top-center' ,
alwaysOnTop : true ,
2026-09-12 17:41:05 +08:00
/** 纯黑底(WinIsland default 风格) */
style : 'black' ,
/** 空闲时完全隐藏(与原行为一致;打开后空闲会留一条细缝) */
idleSliver : false ,
2026-09-27 16:34:01 +08:00
/**
* 距屏幕左右边缘的距离(px):停靠左/右时生效。
* 默认与原行为一致(8px)—— 加这个设置是为了能调,不是为了改默认外观。
*/
marginX : 8 ,
/** 距屏幕上下边缘的距离(px):停靠顶/底时生效 */
marginY : 8 ,
/** 是否跟随鼠标所在屏幕(多显示器教室电脑:鼠标在哪块屏就在哪块屏显示) */
followCursorDisplay : false ,
2026-09-12 15:19:13 +08:00
} as const ;
/** 个性化设置项的合法区间(前端滑块与后端校验共用,避免越界导致布局错乱) */
export const ISLAND_APPEARANCE_RANGES = {
height : { min : 36 , max : 72 },
width : { min : 220 , max : 420 },
radius : { min : 8 , max : 32 },
opacity : { min : 0.4 , max : 1 },
2026-09-12 17:41:05 +08:00
fontSize : { min : 11 , max : 20 },
2026-09-12 15:19:13 +08:00
speed : { min : 0.5 , max : 2 },
2026-09-27 16:34:01 +08:00
marginX : { min : 0 , max : 200 },
marginY : { min : 0 , max : 160 },
2026-09-12 15:19:13 +08:00
} as const ;
2026-09-12 17:41:05 +08:00
/** 停靠位置可选值(与 WinIsland 的 DockPosition 一致:顶/底 × 左/中/右) */
export const ISLAND_POSITIONS = [
'top-center' ,
'top-left' ,
'top-right' ,
'bottom-center' ,
'bottom-left' ,
'bottom-right' ,
] as const ;
2026-09-12 15:19:13 +08:00
export const ISLAND_POSITION_LABELS : Record < ( typeof ISLAND_POSITIONS )[ number ], string > = {
'top-center' : '顶部居中' ,
'top-left' : '左上角' ,
'top-right' : '右上角' ,
'bottom-center' : '底部居中' ,
2026-09-12 17:41:05 +08:00
'bottom-left' : '左下角' ,
'bottom-right' : '右下角' ,
2026-09-12 15:19:13 +08:00
};
2026-09-12 17:41:05 +08:00
2026-11-17 18:57:32 +08:00
/** ClassIsland `ColorSource` 的显示顺序与中文说明。 */
export const ISLAND_ACCENT_SOURCES = [
{ value : 0 , label : '自定义颜色' },
{ value : 1 , label : '壁纸主题色' },
{ value : 2 , label : '跟随系统' },
{ value : 3 , label : '屏幕主题色' },
] as const ;
2026-09-12 17:41:05 +08:00
/** 视觉风格可选值(参考 WinIsland 的 island_style) */
export const ISLAND_STYLES = [ 'black' , 'glass' , 'tinted' ] as const ;
export const ISLAND_STYLE_LABELS : Record < ( typeof ISLAND_STYLES )[ number ], string > = {
black : '纯黑(灵动岛默认)' ,
2026-09-27 18:08:51 +08:00
glass : '毛玻璃(半透明)' ,
2026-09-12 17:41:05 +08:00
tinted : '主题色渐变' ,
};
/**
* 空闲细缝尺寸(参考 WinIsland hidden_width = 5:空闲态是一条很窄的圆角柱)。
* 宽度固定 6px,高度取胶囊高度的一部分,视觉上就是一条"小黑条"。
*/
export const ISLAND_SLIVER_WIDTH = 6 ;
2026-09-12 18:46:20 +08:00
/**
* 各形态相对"胶囊"的尺寸增量(**单一事实来源**,主进程与渲染进程共用):
* - 主进程据此计算"固定包围盒窗口"有多大(窗口只为最大形态留位置,开合时不改窗口);
* - 渲染进程据此计算岛的目标尺寸并做弹簧形变。
* 取值参考 WinIsland:胶囊 120× 27 → 展开 360×200(宽 ×3、高 ×7.4),我们按内容需要取略小的比例。
*/
export const ISLAND_SIZE_DELTA = {
expanded : { width : 156 , height : 186 },
urgent : { width : 172 , height : 202 },
call : { width : 188 , height : 218 },
} as const ;
/** 阴影/光晕留白(窗口比最大形态多出的透明边,保证投影不被窗口裁掉) */
export const ISLAND_SHADOW_PAD = 10 ;
2026-09-12 17:41:05 +08:00
/** 岛内文本的排版系数(相对基础字号,集中在这里方便统一调整) */
export const ISLAND_TYPE_SCALE = {
/** 展开卡标题 */
title : 1.08 ,
/** 正文 */
body : 0.95 ,
/** 次要说明 / 元信息 */
meta : 0.78 ,
/** 徽标 / 按钮 */
badge : 0.76 ,
/** 胶囊主标题 */
pillTitle : 0.92 ,
/** 胶囊副标题 */
pillSub : 0.74 ,
} as const ;
2026-10-02 00:24:58 +08:00
/**
* 展开态"多条通知列表"的排版度量(单位:**基础字号的倍数**,即与 `--island-font` 同源)。
*
* 为什么这份常量必须放在 shared:列表比普通展开卡高得多,**窗口包围盒要跟着长高**,
* 否则卡片底部(那排按钮)会被窗口裁掉 —— 而窗口尺寸只有主进程能改、行高只有渲染进程知道。
* 两边用同一份度量各算一次"该显示几行 / 卡片多高",就不会出现"渲染进程以为放得下、窗口却不够高"的漂移。
*
* 与 `IslandApp.vue` 里 `.expanded-layer`、`.list-row`、`.list-hint`、`.foot` 的 CSS 逐项对应,
* **改 CSS 必须同步改这里**。
*/
export const ISLAND_LIST_METRICS = {
/** 卡片上下内边距 */
paddingY : 1.4 ,
/** 卡片内各块(标题行 / 批次标题 / 列表 / 按钮行)之间的间距 */
gap : 0.7 ,
/** 顶部标题行(图标 + 徽标 + 时间 + 收起按钮) */
headerHeight : 1.7 ,
/** 批次标题("共 N 条待处理通知",单行) */
titleHeight : 1.4 ,
/** 单条通知行高 */
rowHeight : 2.7 ,
/** 行间距(含提示行上方的间距) */
rowGap : 0.4 ,
/** "展开更多 / 更多请前往应用内操作"那一行(含上方间距) */
hintHeight : 2.5 ,
/** 底部按钮行(含上方间距、分隔线与内边距) */
footerHeight : 3.45 ,
/** 默认只显示前几条 —— 用户要求「只显示前三个,下面显示展开更多」 */
defaultVisibleRows : 3 ,
/** 兜底上限:再多也交给"前往应用内操作",避免窗口长到离谱 */
maxRows : 20 ,
/** 高度余量:浮点排版误差不至于让最后一行贴着裁切边 */
safetyPad : 6 ,
} as const ;
/** 列表布局结算结果(主进程据此算窗口包围盒,渲染进程据此渲染) */
export interface IslandListLayout {
/** 实际要展示的通知行数 */
rows : number ;
/** 底部提示行的形态:more=可"展开更多"; app=放不下,请去应用内看;null=没有更多了 */
hint : 'more' | 'app' | null ;
/** 卡片高度(CSS px) */
height : number ;
}
/** 列表卡片里"除通知行之外"的固定高度(CSS px):内边距 + 标题行 + 批次标题 + 底部按钮行 + 可选提示行 */
function islandListChromeHeight ( fontSize : number , withHint : boolean ) : number {
const m = ISLAND_LIST_METRICS ;
const base = ( m . paddingY * 2 + m . headerHeight + m . titleHeight + m . footerHeight + m . gap * 3 ) * fontSize ;
return base + ( withHint ? m . hintHeight * fontSize : 0 );
}
/** n 行通知(含行间距)占用的高度(CSS px) */
function islandListRowsHeight ( fontSize : number , rows : number ) : number {
const m = ISLAND_LIST_METRICS ;
if ( rows <= 0 ) return 0 ;
return ( rows * m . rowHeight + ( rows - 1 ) * m . rowGap ) * fontSize ;
}
/** 在给定高度里最多放得下几行通知(至少 1 行,至多 maxRows) */
function islandListFittingRows ( fontSize : number , maxHeight : number , withHint : boolean ) : number {
const m = ISLAND_LIST_METRICS ;
const chrome = islandListChromeHeight ( fontSize , withHint ) + m . safetyPad ;
const unit = ( m . rowHeight + m . rowGap ) * fontSize ;
const rowUnit = m . rowHeight * fontSize ;
const room = maxHeight - chrome ;
if ( room < rowUnit ) return 1 ;
return Math . max ( 1 , Math . min ( m . maxRows , Math . floor (( room + m . rowGap * fontSize ) / unit )));
}
/**
* 结算"多条通知"的展开卡布局(**主进程与渲染进程共用**):
* - 默认只显示前 `defaultVisibleRows` 条,多余的放进"展开更多";
* - 放不下的部分(快到屏幕下沿的任务栏了)不再撑高卡片,改为提示"更多请前往应用内操作";
* - 返回的 `height` 就是卡片(以及窗口包围盒)应有的高度。
*/
export function islandListLayout ( input : {
/** 待处理通知总数 */
count : number ;
/** 基础字号(外观设置) */
fontSize : number ;
/** 当前屏幕/停靠位置下卡片可用的最大高度(CSS px) */
maxHeight : number ;
/** 是否已点过"展开更多" */
expanded : boolean ;
}) : IslandListLayout {
const m = ISLAND_LIST_METRICS ;
const total = Math . max ( 0 , Math . floor ( input . count ));
// 先按"用户意图"决定想显示几行;再受屏幕高度限制
const desired = input . expanded ? Math . min ( total , m . maxRows ) : Math . min ( total , m . defaultVisibleRows );
const wantsHint = desired < total ;
const fitting = islandListFittingRows ( input . fontSize , input . maxHeight , wantsHint );
const rows = Math . max ( 1 , Math . min ( desired , fitting ));
const hint : IslandListLayout [ 'hint' ] =
rows >= total ? null : input . expanded || rows >= fitting ? 'app' : 'more' ;
return {
rows ,
hint ,
height : Math.min (
input . maxHeight ,
islandListChromeHeight ( input . fontSize , hint !== null ) +
islandListRowsHeight ( input . fontSize , rows ) +
m . safetyPad ,
),
};
}
2026-09-11 21:57:38 +08:00
/** 默认学期周次上限 */
export const DEFAULT_WEEK_COUNT = 20 ;
/** WebSocket 事件名(服务端广播 / 客户端监听保持一致) */
export const SOCKET_EVENTS = {
2026-10-18 11:53:37 +08:00
coursewareChanged : 'courseware:changed' ,
2026-09-11 21:57:38 +08:00
notificationNew : 'notification:new' ,
2026-10-17 03:06:46 +08:00
notificationDeleted : 'notification:deleted' ,
2026-09-11 21:57:38 +08:00
homeworkNew : 'homework:new' ,
homeworkUpdated : 'homework:updated' ,
homeworkStatus : 'homework:status' ,
gradeUpdated : 'grade:updated' ,
scheduleUpdated : 'schedule:updated' ,
2026-10-17 09:32:52 +08:00
clientReleaseProgress : 'client:release-progress' ,
2026-09-11 21:57:38 +08:00
classUpdated : 'class:updated' ,
2026-10-18 11:53:37 +08:00
/** "叫人":老师点名让某位同学去找他(定向到班级会话 session:{classId} 房间) */
2026-09-12 13:57:46 +08:00
callNew : 'call:new' ,
2026-09-11 21:57:38 +08:00
connected : 'connected' ,
} as const ;
2026-10-31 09:40:23 +08:00
/** 班级事件域;订阅资格按对应读能力逐域求值。 */
export const SOCKET_CHANNELS = [ 'core' , 'homework' , 'notification' , 'grade' , 'courseware' ] as const ;
export type SocketChannel = ( typeof SOCKET_CHANNELS )[ number ];
export const SOCKET_EVENT_CHANNELS : Record < string , SocketChannel > = {
'class:updated' : 'core' ,
'schedule:updated' : 'core' ,
'homework:new' : 'homework' ,
'homework:updated' : 'homework' ,
'homework:status' : 'homework' ,
'notification:new' : 'notification' ,
'notification:deleted' : 'notification' ,
'call:new' : 'notification' ,
'grade:updated' : 'grade' ,
'courseware:changed' : 'courseware' ,
};
2026-10-17 03:06:46 +08:00
/** ClassIsland JSON 导入:时间点类型(与 TimeLayoutItem.TimeType 一致) */
2026-09-27 14:59:12 +08:00
export const CLASSISLAND_TIME_TYPES = {
class : 0 ,
break : 1 ,
divider : 2 ,
action : 3 ,
} as const ;
/**
* ClassIsland 的时间点类型 -> 本系统的节次类型。
* 3(行动)在本系统里按"分割线"处理:它不占课时,只做视觉分隔。
*/
export const CLASSISLAND_TIME_TYPE_LABELS : Record < number , string > = {
0 : '上课' ,
2026-10-25 16:41:29 +08:00
1 : '课间休息' ,
2026-09-27 14:59:12 +08:00
2 : '分割线' ,
3 : '行动' ,
};
2026-09-27 16:34:01 +08:00
/**
* 作业录入的默认快捷短语(客户端「设置 → 作业录入」可增删)。
*
* 教室里老师录作业的常见口径:科目简称(P=拼音)、本子类型(大本/小本)、
* 作业动作(背诵/默写/听写/预习/订正)—— 点一下就追加到内容里,少打字。
*/
export const HOMEWORK_PHRASE_DEFAULTS = [
'P' ,
'大本' ,
'小本' ,
'卷子' ,
'背诵' ,
'默写' ,
'听写' ,
'预习' ,
'订正' ,
'读书' ,
] as const ;
/** 单条快捷短语的最大长度(防止把整篇作业粘进去) */
export const HOMEWORK_PHRASE_MAX_LENGTH = 20 ;
/** 快捷短语最多几条 */
export const HOMEWORK_PHRASE_MAX_COUNT = 24 ;
2026-09-12 13:57:46 +08:00
/**
2026-10-06 19:41:18 +08:00
* "叫人"快捷短语(Web 管理端一键选择,ClassHelper 班级端灵动岛同步展示)。
2026-09-12 13:57:46 +08:00
* 自定义消息会替换/补全这些短语;`message` 为空时用短语本身。
*/
export const CALL_QUICK_PHRASES : readonly string [] = [
'请到办公室找我' ,
'请到讲台找我' ,
'请带上作业本找我' ,
'请带上试卷找我' ,
'请到实验室找我' ,
'请到门卫处找我' ,
'请到教室门口等我' ,
'请马上来一趟' ,
] as const ;
/** 叫人消息标题模板:请 XXX 同学找 XXX 老师(老师名字已含"老师"时不重复追加) */
export function buildCallTitle ( studentName : string , teacherName : string ) : string {
const teacher = /老师|教师|主任|校长/ . test ( teacherName ) ? teacherName : ` ${ teacherName } 老师` ;
return `请 ${ studentName } 同学找 ${ teacher } ` ;
}
2026-09-11 21:57:38 +08:00
/** Socket.IO 房间名生成规则:与后端保持一致,客户端订阅时复用 */
export const SOCKET_ROOMS = {
2026-10-31 09:40:23 +08:00
classChannel : ( classId : string , channel : SocketChannel ) : string => `class: ${ classId } : ${ channel } ` ,
/** @deprecated 仅供旧协议测试识别,生产不再订阅。 */
2026-09-11 21:57:38 +08:00
class : ( classId : string ) : string => `class: ${ classId } ` ,
2026-10-06 19:41:18 +08:00
/**
* 会话自身的房间:老师/管理员是账号 id,ClassHelper 班级端是班级 id。
* 「叫人」等定向消息发给它。注意**没有"学生房间"** —— 学生不是账号,没有客户端会订阅。
*/
session : ( sessionId : string ) : string => `session: ${ sessionId } ` ,
2026-09-11 21:57:38 +08:00
teacher : ( teacherId : string ) : string => `teacher: ${ teacherId } ` ,
role : ( role : UserRole ) : string => `role: ${ role } ` ,
students : 'students' ,
teachers : 'teachers' ,
} as const ;
/** 本地持久化键(Web 端 localStorage / EXE 端 IndexedDB 命名空间) */
export const STORAGE_KEYS = {
token : 'classhelper.token' ,
user : 'classhelper.user' ,
serverUrl : 'classhelper.serverUrl' ,
cachePrefix : 'classhelper.cache' ,
lastSyncAt : 'classhelper.lastSyncAt' ,
2026-10-02 11:18:47 +08:00
/**
* 新手引导「已看过」标记(Web 管理端 localStorage)。
* 值为引导版本号:改版引导内容后版本 +1,看过旧版的老用户会再收到一次新版引导。
2026-11-07 16:27:38 +08:00
* EXE 客户端的引导版本保存在主进程配置 `onboardingVersion`。
2026-10-02 11:18:47 +08:00
*/
onboarding : 'classhelper.onboarding' ,
2026-09-11 21:57:38 +08:00
} as const ;
/** 桌面客户端默认后端地址 */
export const DEFAULT_SERVER_URL = 'http://127.0.0.1:4000' ;
/** 默认端口与分页 */
export const DEFAULT_SERVER_PORT = 4000 ;
export const DEFAULT_PAGE_SIZE = 20 ;
export const MAX_PAGE_SIZE = 200 ;
2026-10-05 16:39:38 +08:00
/* ------------------------------------------------------------------ 更新检查 */
/**
2026-10-18 11:53:37 +08:00
* 更新来源:本项目用 **GitHub Releases** 分发交付物(服务端 / 客户端安装包与便携版),
2026-10-05 16:39:38 +08:00
* 因此"有没有新版本"就是问 GitHub 上最新的那个 Release。
*
* 仓库是**公开**的,匿名调用即可(不需要 token);但匿名限流是 60 次/小时/IP,
* 所以服务端与客户端都把结果缓存 `UPDATE_CHECK_CACHE_TTL_MS`,不要每次开页面都打一次。
*/
export const GITHUB_REPO = { owner : 'LoveChengke' , repo : 'ClassHelper' } as const ;
/** 最新 Release 的 API 地址(GitHub 保证它不含草稿与预发布版) */
export const GITHUB_RELEASES_LATEST_API = `https://api.github.com/repos/ ${ GITHUB_REPO . owner } / ${ GITHUB_REPO . repo } /releases/latest` ;
/** 给人看的 Release 列表页(「前往下载」按钮打开它) */
export const GITHUB_RELEASES_PAGE = `https://github.com/ ${ GITHUB_REPO . owner } / ${ GITHUB_REPO . repo } /releases` ;
/** GitHub API 强制要求 User-Agent,不带会直接 403 */
export const UPDATE_CHECK_USER_AGENT = 'ClassHelper-UpdateCheck' ;
/** 检查结果缓存时长(30 分钟):既避开匿名限流,也不至于让用户等太久才知道有新版本 */
export const UPDATE_CHECK_CACHE_TTL_MS = 30 * 60 * 1000 ;
/** 单次检查的超时:教室机 / 机房的网络常常很慢,但也不能把界面卡住 */
export const UPDATE_CHECK_TIMEOUT_MS = 8 _000 ;
2026-10-11 11:49:32 +08:00
/* -------------------------------------------- 客户端设备(ClassHelper 桌面端) */
/**
* 桌面客户端向服务端上报心跳的间隔(30 秒,与班级端在线状态刷新一致)。
*
* 为什么**不用 Socket.IO 事件**下发更新与远控:教室机的连接经常断(代理、休眠、重启),
* 而「这台机器什么版本、要不要更新、有没有待执行命令」必须下次上线就能补上,
2026-10-17 03:06:46 +08:00
* 所以统一用「DB 记状态 + 客户端定时拉取」的范式,
2026-10-11 11:49:32 +08:00
* 不引入新的长连接握手。
*/
export const CLIENT_HEARTBEAT_INTERVAL_MS = 30 _000 ;
/** 「在线」判定窗口:容忍连续丢两次心跳(30 秒 × 3) */
export const CLIENT_ONLINE_WINDOW_MS = 90 _000 ;
/** 远控命令种类:只有这四种,全部用系统命令实现 */
export const CLIENT_COMMAND_KINDS : readonly ClientCommandKind [] = [ 'shutdown' , 'restart' , 'logoff' , 'lock' ];
export const CLIENT_COMMAND_LABELS : Record < ClientCommandKind , string > = {
shutdown : '关机' ,
restart : '重启' ,
logoff : '注销' ,
lock : '锁屏' ,
};
/** 命令有效期:超过这个时间还没被拉走就作废(避免机器离线几天后一开机就被昨天的命令关掉) */
export const CLIENT_COMMAND_EXPIRE_MS = 10 * 60 * 1000 ;
/** 客户端回执里 result 的长度上限(一句中文足够) */
export const CLIENT_COMMAND_RESULT_MAX = 200 ;
/**
* 自动安装更新前的「空闲」判据:主窗口已隐藏满这么久才装。
* 上课时段(渲染进程上报的课表状态)与窗口可见都会把安装往后推。
*/
export const CLIENT_UPDATE_IDLE_MS = 5 * 60 * 1000 ;
/** 服务端缓存客户端安装包的目录(相对 `<serverRoot>/../data`,见 update 模块) */
export const CLIENT_RELEASE_DIR = 'client-releases' ;