Files
ClassHelper/packages/shared/src/constants.ts
T
LoveChengke 4449fbd0a1
发布官网与文档站 / build (push) Waiting to run
feat(desktop): 完善灵动岛设计令牌与外观配置
2026-11-17 18:57:32 +08:00

911 lines
32 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
import type {
ClientCommandKind,
GradeLevelType,
NotificationPriority,
StudentGender,
StudentStatus,
UserRole,
} from './types.js';
/** 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',
/** 叫人:老师点名让学生过来 */
calls: '/calls',
grades: '/grades',
students: '/students',
teachers: '/teachers',
/** 导入:模板下载 / 表格导入 / ClassIsland 课表时间配置 */
imports: '/imports',
/** 毕业归档:届别档案、归档详情、学年升级(仅管理员) */
archives: '/archives',
/** 学期周次:逐周日期区间、按开学日期自动生成、联网拉取调休建议(仅管理员) */
term: '/term',
/** 数据库管理(仅管理员):状态/备份/导入导出/一键切换 */
database: '/database',
/** 更新检查:Web 端经服务端转发查 GitHub 上的最新 Release(浏览器受 CSP 限制不能直连) */
update: '/update',
/** 权限组:权限目录、组的增删改、成员分配、当前账号生效权限 */
permissions: '/permissions',
/** ClassHelper 客户端设备:心跳、设备清单、统一下发更新与远控指令 */
clients: '/clients',
/** 大模型助手:设置(仅管理员)、一句话解析、使用记录 */
ai: '/ai',
/** 系统设置与诊断:开发者模式、服务端开机自启、运行诊断(仅管理员) */
system: '/system',
dashboard: '/dashboard/summary',
} as const;
/**
* 账号角色。
*
* **没有 STUDENT** —— 学生不是账号,只是班级名单记录(`Student` 表),没有密码、没有登录入口。
* `CLASS_DEVICE` = 教室里绑定到某个班的 ClassHelper 班级端。
*/
export const USER_ROLES: readonly UserRole[] = ['ADMIN', 'TEACHER', 'CLASS_DEVICE'];
export const ROLE_LABELS: Record<UserRole, string> = {
ADMIN: '系统管理员',
TEACHER: '教师',
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: '科任老师',
};
/* ------------------------------------------------------------------ 学生名单 */
export const STUDENT_STATUSES: readonly StudentStatus[] = ['active', 'graduated', 'transferred', 'inactive'];
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: '自定义等级',
};
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 班级端在线判定窗口(毫秒)。
*
* @deprecated 旧联动在线窗口兼容导出,当前设备在线状态使用 CLIENT_ONLINE_WINDOW_MS。
*/
export const CLASS_HELPER_ONLINE_WINDOW_MS = 60_000;
/** @deprecated 旧联动状态页刷新间隔,现行设备页不使用。 */
export const CLASS_HELPER_STATUS_REFRESH_SECONDS = 30;
/** 通知优先级 */
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',
};
/**
* 优先级权重(越大越重要)。
*
* 灵动岛列表排序和同 id 消息合并共用,保证展示顺序与优先级合并一致。
*/
export const PRIORITY_RANK: Record<NotificationPriority, number> = {
LOW: 0,
NORMAL: 1,
HIGH: 2,
URGENT: 3,
};
/** 星期: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];
/**
* 统一授课科目目录(**全校固定**):作业、课表、成绩的"科目"都从这里选,
* 不需要按班级一个个建课 —— 选中后由前端自动为该班建好同名课程(已存在则复用)。
* 顺序按用户给定的作息习惯:文化课 → 技术 → 体艺 → 班会与早晚读 → 通用技术 → 听力。
*/
export const SUBJECT_CATALOG: readonly string[] = [
'语文',
'数学',
'英语',
'政治',
'历史',
'物理',
'化学',
'地理',
'生物',
'信息技术',
'体育',
'美术',
'音乐',
'班会',
'早读',
'晚读',
'通用技术',
'听力',
] as const;
/**
* 单双周标签与取值(课表用)。
* 语义与 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;
/**
* 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;
}
/** 灵动岛默认外观(设置页个性化项的初始值,也是区间校验的单一来源) */
export const DEFAULT_ISLAND_APPEARANCE = {
height: 44,
width: 268,
radius: 20,
opacity: 1,
/** 默认强调色与 ClassIsland 的 PrimaryColor 对齐。 */
accent: CLASSISLAND_TOKENS.colors.light.primaryColor,
/** 0=自定义,1=壁纸主题色,2=跟随系统,3=屏幕主题色;未知值回落兜底色。 */
accentSource: 0,
accentPalette: [CLASSISLAND_TOKENS.colors.light.primaryColor] as string[],
accentPaletteIndex: 0,
fontSize: 13,
animations: true,
speed: 1,
position: 'top-center',
alwaysOnTop: true,
/** 纯黑底(WinIsland default 风格) */
style: 'black',
/** 空闲时完全隐藏(与原行为一致;打开后空闲会留一条细缝) */
idleSliver: false,
/**
* 距屏幕左右边缘的距离(px):停靠左/右时生效。
* 默认与原行为一致(8px)—— 加这个设置是为了能调,不是为了改默认外观。
*/
marginX: 8,
/** 距屏幕上下边缘的距离(px):停靠顶/底时生效 */
marginY: 8,
/** 是否跟随鼠标所在屏幕(多显示器教室电脑:鼠标在哪块屏就在哪块屏显示) */
followCursorDisplay: false,
} 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 },
fontSize: { min: 11, max: 20 },
speed: { min: 0.5, max: 2 },
marginX: { min: 0, max: 200 },
marginY: { min: 0, max: 160 },
} as const;
/** 停靠位置可选值(与 WinIsland 的 DockPosition 一致:顶/底 × 左/中/右) */
export const ISLAND_POSITIONS = [
'top-center',
'top-left',
'top-right',
'bottom-center',
'bottom-left',
'bottom-right',
] as const;
export const ISLAND_POSITION_LABELS: Record<(typeof ISLAND_POSITIONS)[number], string> = {
'top-center': '顶部居中',
'top-left': '左上角',
'top-right': '右上角',
'bottom-center': '底部居中',
'bottom-left': '左下角',
'bottom-right': '右下角',
};
/** ClassIsland `ColorSource` 的显示顺序与中文说明。 */
export const ISLAND_ACCENT_SOURCES = [
{ value: 0, label: '自定义颜色' },
{ value: 1, label: '壁纸主题色' },
{ value: 2, label: '跟随系统' },
{ value: 3, label: '屏幕主题色' },
] as const;
/** 视觉风格可选值(参考 WinIsland 的 island_style) */
export const ISLAND_STYLES = ['black', 'glass', 'tinted'] as const;
export const ISLAND_STYLE_LABELS: Record<(typeof ISLAND_STYLES)[number], string> = {
black: '纯黑(灵动岛默认)',
glass: '毛玻璃(半透明)',
tinted: '主题色渐变',
};
/**
* 空闲细缝尺寸(参考 WinIsland hidden_width = 5:空闲态是一条很窄的圆角柱)。
* 宽度固定 6px,高度取胶囊高度的一部分,视觉上就是一条"小黑条"。
*/
export const ISLAND_SLIVER_WIDTH = 6;
/**
* 各形态相对"胶囊"的尺寸增量(**单一事实来源**,主进程与渲染进程共用):
* - 主进程据此计算"固定包围盒窗口"有多大(窗口只为最大形态留位置,开合时不改窗口);
* - 渲染进程据此计算岛的目标尺寸并做弹簧形变。
* 取值参考 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;
/** 岛内文本的排版系数(相对基础字号,集中在这里方便统一调整) */
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;
/**
* 展开态"多条通知列表"的排版度量(单位:**基础字号的倍数**,即与 `--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,
),
};
}
/** 默认学期周次上限 */
export const DEFAULT_WEEK_COUNT = 20;
/** WebSocket 事件名(服务端广播 / 客户端监听保持一致) */
export const SOCKET_EVENTS = {
coursewareChanged: 'courseware:changed',
notificationNew: 'notification:new',
notificationDeleted: 'notification:deleted',
homeworkNew: 'homework:new',
homeworkUpdated: 'homework:updated',
homeworkStatus: 'homework:status',
gradeUpdated: 'grade:updated',
scheduleUpdated: 'schedule:updated',
clientReleaseProgress: 'client:release-progress',
classUpdated: 'class:updated',
/** "叫人":老师点名让某位同学去找他(定向到班级会话 session:{classId} 房间) */
callNew: 'call:new',
connected: 'connected',
} as const;
/** 班级事件域;订阅资格按对应读能力逐域求值。 */
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',
};
/** ClassIsland JSON 导入:时间点类型(与 TimeLayoutItem.TimeType 一致) */
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: '上课',
1: '课间休息',
2: '分割线',
3: '行动',
};
/**
* 作业录入的默认快捷短语(客户端「设置 → 作业录入」可增删)。
*
* 教室里老师录作业的常见口径:科目简称(P=拼音)、本子类型(大本/小本)、
* 作业动作(背诵/默写/听写/预习/订正)—— 点一下就追加到内容里,少打字。
*/
export const HOMEWORK_PHRASE_DEFAULTS = [
'P',
'大本',
'小本',
'卷子',
'背诵',
'默写',
'听写',
'预习',
'订正',
'读书',
] as const;
/** 单条快捷短语的最大长度(防止把整篇作业粘进去) */
export const HOMEWORK_PHRASE_MAX_LENGTH = 20;
/** 快捷短语最多几条 */
export const HOMEWORK_PHRASE_MAX_COUNT = 24;
/**
* "叫人"快捷短语(Web 管理端一键选择,ClassHelper 班级端灵动岛同步展示)。
* 自定义消息会替换/补全这些短语;`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}`;
}
/** Socket.IO 房间名生成规则:与后端保持一致,客户端订阅时复用 */
export const SOCKET_ROOMS = {
classChannel: (classId: string, channel: SocketChannel): string => `class:${classId}:${channel}`,
/** @deprecated 仅供旧协议测试识别,生产不再订阅。 */
class: (classId: string): string => `class:${classId}`,
/**
* 会话自身的房间:老师/管理员是账号 id,ClassHelper 班级端是班级 id。
* 「叫人」等定向消息发给它。注意**没有"学生房间"** —— 学生不是账号,没有客户端会订阅。
*/
session: (sessionId: string): string => `session:${sessionId}`,
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',
/**
* 新手引导「已看过」标记(Web 管理端 localStorage)。
* 值为引导版本号:改版引导内容后版本 +1,看过旧版的老用户会再收到一次新版引导。
* EXE 客户端的引导版本保存在主进程配置 `onboardingVersion`。
*/
onboarding: 'classhelper.onboarding',
} 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;
/* ------------------------------------------------------------------ 更新检查 */
/**
* 更新来源:本项目用 **GitHub Releases** 分发交付物(服务端 / 客户端安装包与便携版),
* 因此"有没有新版本"就是问 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;
/* -------------------------------------------- 客户端设备(ClassHelper 桌面端) */
/**
* 桌面客户端向服务端上报心跳的间隔(30 秒,与班级端在线状态刷新一致)。
*
* 为什么**不用 Socket.IO 事件**下发更新与远控:教室机的连接经常断(代理、休眠、重启),
* 而「这台机器什么版本、要不要更新、有没有待执行命令」必须下次上线就能补上,
* 所以统一用「DB 记状态 + 客户端定时拉取」的范式,
* 不引入新的长连接握手。
*/
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';