功能详解

本章按模块介绍 CSMS 的核心功能及其使用方式。

积分管理

CSMS 的核心是对学生操行分（综合素质评价）的实时管理。

• 积分调整：班级管理员可对学生执行加分 / 扣分，支持填写事由。
• 积分模板：预置常用积分项（如「作业优秀 +2」「迟到 -1」），录入时一键套用，保证口径统一。
• 撤销 / 修正：支持对误操作的积分记录进行撤销，所有变更留痕。
• 审计：每一次积分变动都会记录操作人、时间、前后值与事由，可在统计中追溯。

积分记录与模板存储在各校分库（score_logs、score_templates 表）。管理端接口见 。

可视化座位表

• 拖拽式编辑班级座位布局，支持行列自定义。
• 一键生成当前座位图，并将学生与座位绑定。
• 布局配置与座位数据分别保存在 seat_layout_config 与 seat_data 表，便于还原与迁移。

数据统计

提供多维度的积分与排名统计：

• 班级维度：班级内学生积分排名（TOP 10 榜单、A–Z / 中文 localeCompare 排序）。
• 年级维度：年级下各班级横向对比。
• 全校维度：超级管理员可跨年级、跨班级汇总。
• 多级筛选：超级管理员支持全校 / 年级 / 班级筛选；年级管理员支持全年级 / 班级筛选。

图表由 Chart.js 渲染，支持拟合曲线与趋势分析。

公告系统

• 超级管理员可发布校级公告，支持富文本与 XSS 过滤（sanitizeHtml）。
• 公告面向全校 / 指定范围展示，学生端首页可见。

安全认证

• 管理员采用 Session + BCrypt 认证，登录限流（M1 已修复）防爆破。
• 超级管理员可免密登录任意管理员账号，便于运维与排障。
• 敏感操作（如 API 凭证签发 / 吊销）需要二次验密。
• 学生端使用独立的 Token 认证（/api/student/**），与管理员 Session 物理隔离。

邮件通知系统

• 触发场景：学校入驻审核结果（通过 / 拒绝）自动发往申请邮箱。
• 模板管理：邮件模板支持在线编辑，可插入变量占位符（申请人姓名、学校名称、账号、密码、学校 ID）。
• 邮件服务：支持 SMTP 与 Resend 两种后端。
• 安全：模板内容经过 XSS 过滤，避免注入。

PWA 渐进式 Web 应用

• 支持安装到桌面 / 主屏幕，以全屏独立应用运行（Android 自适应图标 + iOS 全屏）。
• Workbox 预缓存静态资源 + 运行时缓存；API 请求 /api/* 强制走网络、永不缓存，保证积分 / 学生等数据实时准确。
• 自动更新（registerType: autoUpdate）。
• 品牌图标：浏览器标签 / 应用内 logo 为「CS 字母徽标 + 星星」（CS = ClassScoreManageSystem，星星寓意步步高升 / 评分之星）；PWA 主屏幕图标为火箭主体（寓意成长与超越）。
• 需 HTTPS 环境才能提示「安装到主屏幕」（npm run dev 本地不提示）。

外部开放 API（v1）

CSMS 面向第三方系统（如校园一卡通、教务平台、自动排座脚本）提供开放 API：

• 物理隔离：/api/v1/** 外部接口与 /api/** 内部接口分离，第三方无法触碰系统级数据。
• 凭证鉴权：Authorization: Bearer 或 X-API-Token，sha256 入库、明文仅签发时可见一次。
• 范围与权限双控：学校 / 年级 / 班级 3 种范围 + 12 项细粒度权限（students:delete / structure:delete 危险权限默认不勾选）。
• 安全三铁律：① 系统数据不可操作；② 写操作仅限校级及以下；③ 必须携带 api_token。
• 限流：全量 600/min + 写操作 120/min，超限返回 429 + Retry-After。
• 幂等：支持 Idempotency-Key 头。
• 审计：每次调用（含鉴权失败 / 限流）写日志，保留 30 天。

完整端点、错误码与 curl 示例见 。