English Documentation | 简体中文文档
基于 Cloudflare Pages + Pages Functions + 私有 R2 强一致性对象存储 构建的轻量级、企业级安全、全端自适应无服务器班级积分与学生评价管理系统。
- 4 核心文件，零外部运行时依赖：全站由恰好 4 个纯原生文件（
_worker.js、login.html、admin.html、teacher.html）组成。原生 ES2022 JavaScript + 现代语义化 HTML5 + CSS3 变量与响应式网格，无 Webpack/Vite 等繁复构建产物，无外部 CDN 脚本，加载毫秒级响应。 - 强一致性 R2 存储：完全基于 Cloudflare 私有 R2 Standard 强一致性对象存储，依托对象 ETag 乐观锁保障多名教师高并发记分零覆盖。
- 极简极低运维成本：Cloudflare 后台仅需配置唯一加密密钥
ADMIN，存储绑定名固定为R2，零数据库实例，免费额度即可支持普通学校全年稳定运行。
- 超级管理员（admin）：负责教师账号维护（建号、重置密码、归档/恢复、彻底删除）、班级目录维护、教师-班级多对多绑定配置、期次全局维护、全局密码策略设置与系统公告发布。
- 任课教师（Teacher）：支持自主修改登录密码；管理所辖班级的学生、评分项目、小组与期次（增删改、排序、软归档与彻底删除、全班毕业清空），仅对授权绑定的班级拥有操作权限。
- 严格路径白名单与角色互斥：对外严格仅开放
/login、/admin、/teacher及/api/*，所有非法路径探测、隐藏文件和根路径强制 302 重定向到/login.html；教师禁入管理台，管理员禁入教师台，未登录统一拦截。
- 视觉双重呼吸闪烁强提醒：
- 工具栏提示区升级为醒目的【
⚠️ N 个单元格尚未保存】高对比告警胶囊（Alert Pill），与【保存 (N)】核心按钮在存在未保存修改时呈现 1.5s 正弦波双重呼吸闪烁动效（pill-pulse与save-pulse），时刻提醒教师记分后及时保存； - 全按钮整体变色闪烁：【保存】按钮在常规墨绿/青蓝主色与警示色之间整按钮背景色、边框与外发光全域呼吸变色交替，告警胶囊同步在浅底与实心高亮强警示态（
#fff字体）之间全域呼吸变色，彻底消除微弱外发光在深色模式下不易察觉的缺陷； - 动态解耦警示色与发光色（
--unsaved-alert/--unsaved-alert-bg），严格联动既有视觉无障碍调色盘（Okabe-Ito 朱红#d55e00、蓝黄色弱红紫#cc79a7、高对比单色及自定义颜色）； - 动效平滑减弱（
@media (prefers-reduced-motion: reduce)）自动平滑放缓为 2.5s 柔和正弦过渡，兼顾无障碍舒适性与强警示可见性，杜绝粗暴掐断动画导致用户误以为没有闪烁；窄屏手机端自适应简写（如⚠️ 3 项待保存），杜绝工具栏折行； - 点击【保存】瞬间两个元素立即停止闪烁，丝滑进入加载等待态。
- 工具栏提示区升级为醒目的【
- 静默云草稿引擎与校园弱网强互斥：
- 采用 2.5s 防抖 + 30s 周期保底 + 5s 最小间隔 + 10s 超时熔断 + Diff Guard 指纹比对 智能调度，全流程零弹窗、零打扰静默上云；
- 校园弱网强互斥：点击【保存】瞬间通过
AbortController.abort()强制腰斩途中云草稿请求；state.saving = true期间锁死草稿引擎，杜绝陈旧草稿覆盖最新成绩； - 离开即时抢救：监听
visibilitychange与pagehide事件，利用fetch的keepalive: true保证切屏或关机瞬间未保存草稿可靠上云； - 7 天自动过期策略：逾期草稿视为失效并自动丢弃清理。
- 多教师与跨设备物理隔离：
- R2 专属隔离路径：
drafts/${classId}_${username}.json，一人一档彻底物理隔离； - 班级内多位教师同时打分互不干扰；同一位教师在办公室与教室多设备切换时无缝同步暂存草稿。
- R2 专属隔离路径：
- 居中模态恢复与防误触确认：
- 教师进入班级时若探测到有效云草稿，居中弹出
<dialog id="cloudDraftDialog">，清晰呈现草稿保存时间与修改单元格项数； - 提供【一键恢复到表格】与【放弃并清空此草稿】；点击放弃时强制触发原生确认弹窗，杜绝手滑误删。
- 教师进入班级时若探测到有效云草稿，居中弹出
- 官方成绩正式保存原子销毁闭环：
- 教师点击【保存】成功提交正式成绩后，后端同事务原子物理删除该教师在 R2 中的对应云草稿，杜绝旧草稿回弹反弹。
-
纯前端零后端改动：100% 仅在
teacher.html内联实现，零外部依赖，零额外 API 请求与 R2 负载。 - 通俗化带班生活场景语言（零技术黑话）：全白话设计，杜绝 AES 等复杂密码学术专有名词，清晰讲解打字带正负号自动算分、普通数字不计分防污染、两周一期新建全员清零重起、期末总评双模式、班会点评完加锁封存与解锁补录、学生/项目/小组管理与软归档恢复、毕业换届冷静10秒清空全员学生保留规则、单列点击排序、多级高级排序与全同分拼音 A-Z 升序保底，以及以“保险箱与时光机”为视角的班级备份下载防篡改、上传还原与紧急快照撤销等。
- 8 大主题快捷导航胶囊（自适应弹性换行）：快速入门、记分与期次、加锁防误触、班级管理、毕业换届、榜单与解惑、备份与快照、视觉无障碍，启用弹性换行排布，所有药丸一览无余，彻底杜绝按钮遮挡截断。
-
移动端严密防折行与超窄屏精修：
- 公告小红点位置精准修正至右上角外侧边缘，彻底杜绝遮挡“公”字；
- 顶栏按钮设置
white-space: nowrap与flex-shrink: 0，杜绝文字折成两行； - 移动端按钮自适应缩写（
📢图标、改密、退出、🔓 可编辑从 11 字缩减为 4 字）； -
$\le 480\text{px}$ 手机屏幕下自动隐藏冗余的账号胶囊，释放超 40px 横向空间，保持顶栏单行平整舒展。
-
零门槛随时随地快速秒关：吸顶常驻
×按钮、底部【我知道了】主按钮、键盘Esc键、轻触外部暗色遮罩层任意位置秒关，纯按需唤起，系统绝不主动弹窗打扰日常记分。
-
科学色盲友好配色方案（基于 Okabe-Ito / CUD 标准）：
为应对红绿色盲/色弱、蓝黄色盲/色弱与低视力全色盲教师的实际教学需要，基于《Nature Methods》推崇的国际科学标准设计 4 组专业配色预设：
-
默认经典 (Classic)：绿增蓝减（正分
#059669/ 负分#2563eb），彻底打破红绿对立冲突； -
红绿友好 (Protan/Deutan)：蓝增橙减（正分
#0072b2/ 负分#d55e00），在红绿色弱及色盲视界中依然具备高色相与明度辨识度； -
蓝黄友好 (Tritan)：青增洋红减（正分
#009e73/ 负分#cc79a7），避开蓝黄混淆轴； -
高对比/单色 (High Contrast)：深墨绿与纯黑（正分
#0f5132/ 负分#000000），完美适配全色盲及强光白板投影。
-
默认经典 (Classic)：绿增蓝减（正分
- 全开放自主配色与柔和底色渲染： 提供正分、负分、未保存草稿三种状态的原生拾色器，允许教师按个人心智习惯定制（如习惯负分红/正分绿等）；支持一键开启“负分单元格底色柔和浅染（8% 低饱和光晕）”，强化视线聚焦与快速查阅。
- 双重实时变色联动与微缩看板吸顶预览： 调色弹窗内嵌高拟真积分板微缩预览卡片（表头、正分、负分、草稿标记与累计总分），吸顶常驻于标题正下方（脱离滚动区），彻底避免弹窗限高时内容被截断看不见；调色瞬间微缩卡片与后方整个主积分大表格同步毫秒级联动变色，所见即所得。
-
暗黑模式智能对比度增强（HSL Lightness Boost）：
切换深色主题时，若教师自定义的颜色明度过低（如深红或黑底），系统自动将其 HSL 亮度提升至安全阈值（Lightness
$\ge$ 68%），杜绝暗黑模式下的文字发暗难辨。 -
教师账号独立隔离与零后端负载：
配色配置通过
cloud-score:a11y-theme:${username}严格隔离保存于浏览器本地，同电脑不同教师互不干扰；100% 纯 CSS 变量驱动，零云端 R2/KV 读写，支持一键秒恢复系统默认。
- 云端快照与单时间线回滚：
- 管理员在后台专属【💾 数据备份与快照】视图中随时手动拍摄命名快照，支持快照列表浏览、备注修改与快照删除；
- 自动记录系统全量数据（教师账号、班级结构、全期次积分、密码策略、系统公告与更新日志）及班级/学生/教师/期次统计；
- 回滚前后端强制自动拍摄
[系统自动] 覆盖前急救快照（带时间戳备注），保障二次救急通道；自动清理孤立班级，并在恢复后即时注销所有活动教师 Session（保持当前管理员会话），彻底阻断教师端本地草稿反向覆盖。
- 本地全量 JSON 备份一键导出与覆盖导入：
- 零外部依赖，支持直接从网页端一键下载完整系统备份
.json文件（支持导出当前数据或指定历史快照）； - 支持直接上传本地
.json备份文件恢复覆盖当前数据，后端请求体上限放宽至 25MB（MAX_BACKUP_BODY_BYTES），适应全校几十个班级的大规模数据； - 上传覆盖同样自动校验合法性、拍摄急救快照并注销活动教师会话。
- 零外部依赖，支持直接从网页端一键下载完整系统备份
- 四重防误触安全锁（差异对比 + 倒计时 + 数学题 + 弹窗确认）：
- 无论快照回滚还是本地文件覆盖，统一强制触发安全恢复确认流程：
- 基础数据差异对比看板：清晰列出当前在线数据与目标备份在班级数、教师数、学生数、期次数、时间戳上的对比及增减趋势徽标；
- 10 秒强制冷静倒计时：确认按钮强制锁定倒数 10 秒；
- 动态随机数学挑战题：随机加减乘口算题，口算输入校验；
- 浏览器原生终极确认弹窗；
- 支持勾选“一并恢复公告与更新日志”（默认不勾选，避免冲掉最新系统公告）。
- 无论快照回滚还是本地文件覆盖，统一强制触发安全恢复确认流程：
- Cloudflare 免费额度保护：
- 单次备份/快照写入与读取仅涉及 1 次 R2 Class A/B 调用，R2 出站流量终身免费（$0 Egress），消耗免费额度不足 0.1%，完全无超额风险。
- 班级隔离与数据安全保障：
- 教师在顶部工具栏专属【💾 备份与快照】（紧邻【班级设置】）中操作，数据权限严格限定在任课教师所绑定的班级内；
- 无论后续教师转接、解绑还是换班，备份数据与班级 ID 严格绑定，严禁跨班导入或覆盖（后端严格校验
classId匹配并拒绝 403/400），彻底杜绝班级数据交叉污染与错乱； - 管理员拥有最高优先级，管理员覆盖操作可管理全校所有班级；管理员删除班级时系统原子级联清理该班级的所有快照索引与快照数据文件。
- AES-256-GCM 认证加密防篡改信封（.csbak）：
- 针对教师本地备份文件可能被记事本打开恶意改分的风险，教师端导出的备份文件采用底层认证加密信封（
.csbak扩展名），严防明文查看与非授权篡改； - 高安全级密钥派生机制：系统在
system/catalog.json中维护由部署初始化生成的 32 字节高熵随机主密钥security.backupMasterKey，加密与解密时结合classId作为盐，通过 HKDF-SHA-256 派生班级专属加密密钥；管理员在后台修改 ADMIN 密码完全不影响历史备份解密； - 任何文件字节的篡改（包括密文或 16 字节 GCM 认证标签）在解密导入时均会被底层精准检测并拒绝（
400 BACKUP_TAMPERED）。
- 针对教师本地备份文件可能被记事本打开恶意改分的风险，教师端导出的备份文件采用底层认证加密信封（
- 规范命名与身份追溯：
- 导出的备份文件强制在文件名中嵌入班级名、班级号、操作教师账号与时间戳（如
cloud-score-backup_初一1班_class_xxxx_teacher1_20261001-120000.csbak），清晰可溯。
- 导出的备份文件强制在文件名中嵌入班级名、班级号、操作教师账号与时间戳（如
- 班级专属云端快照与自动急救：
- 教师可在班级面板随时手动拍摄云端快照（最多保留 10 个手动快照，支持备注修改与删除）；
- 每次执行快照回滚或本地文件覆盖导入前，系统强制自动拍摄
[系统自动] 教师覆盖前急救快照（FIFO 自动滚动保留最近 2 次，不占用手动快照名额），确保误操作时随时有一键反悔后悔药； - 操作完成后立即清空操作教师本地
sessionStorage对应班级的草稿，防止旧草稿反向覆盖脏写。
- 四重防误触安全锁（差异对比 + 倒计时 + 数学题 + 确认弹窗）：
- 基础数据差异对比看板（项目数、学生数、小组数、期次数、积分记录数以及备份时间）与增减徽标；
- 10 秒强制冷静倒计时；
- 动态随机加减乘口算题验证；
- 浏览器原生终极确认弹窗。
- 两周周期循环记分与自动结转：针对学校每两周召开班会点评积分的教学习惯，教师在班会结束后点击【+ 开启新期】，系统自动将上一期积分归档并锁定，新一期自动继承全部学生名单与评分项目，所有积分清空归零开始新一轮记分。
- 期次双向锁定与主动防误触（v1.7.1 全新）：
- 顶部工具栏期次锁常驻联动：未锁定时展示
🔓 可编辑 (点击锁定)，已锁定时展示🔒 已锁定 (点击解锁)，点击即可双向切换； - 纠错补录后随时重新加锁：历史往期不仅支持一键解锁修正历史分数，纠错保存完成后教师可随时主动重新加锁，重新封存为只读防误触状态；
- 当前期次主动封存：某个周期点评结束但暂未开启新一期前，教师可随时主动锁定当前期次，防止日常误点修改；
- 未保存草稿智能防线：本地存在未保存草稿时主动拦截加锁，提示先保存再锁定，彻底杜绝数据意外丢失；
- 期次设置管理弹窗（⚙）快捷切换：期次设置弹窗内提供配套的锁定/解锁按钮，状态智能跟随联动；点击锁定单元格或按 Enter 键自动弹出解锁确认。
- 顶部工具栏期次锁常驻联动：未锁定时展示
- 期末总评双模式汇总视图：在期次下拉框中选择【📊 期末总评分汇总】，教师可自由切换两种点评对照模式，均支持单列排序与多级高级排序：
- 模式 A（按期次对照）：表头展示各期次得分小计与全期累计总分（
姓名 | 第1期 | 第2期 | ... | 全期总分）； - 模式 B（按评分项目累计）：表头展示各自定义评分项目全期累加总和（
姓名 | 语文全期 | 数学全期 | ... | 全期总分）。
- 模式 A（按期次对照）：表头展示各期次得分小计与全期累计总分（
- 平滑无缝向后兼容：旧版本班级数据自动平滑迁移为“第 1 期”，现有接口与数据结构无损升级，确保历史积分记录零丢失。
- 全实体彻底物理删除（永久清理）：
- 支持学生、评分项目、小组、期次、教师账号及班级目录的彻底物理永久删除，满足学生毕业、转学、教师离职、撤班或清除临时测试数据的实际需求；
- 免归档直接物理删除：在使用中列表里，【删除】按钮直接摆放在【归档】按钮旁边，支持一键直接彻底移除；在已归档列表中同样提供【彻底删除】；
- 单次 R2 对象原子级联清理：删除学生/项目/小组时，单次请求内原子级联清理该实体在当前及所有历史期次中的全部打分单元格，解绑组员关联，杜绝脏数据孤岛与垃圾残留；物理删除班级时原子调用
R2.delete，彻底释放存储空间。
- 全班学生毕业清空（Graduation Purge）安全锁：
- 针对初三/高三学生毕业离校整班换届场景，在班级设置中提供【全班学生毕业清空】功能；
- 原子清空该班级全部学生名单及全期次个人历史积分，同时完整保留班级评分项目、期次与小组结构，供新一届学生无缝接续使用。
- 三重安全防误触防线：
- 第一重防线：10 秒强制冷静等待，倒计时归零前输入框与提交按钮强制置灰禁用；
- 第二重防线：动态随机算式验证，前端生成趣味加减乘混合算式（如
23 + 19 = ?或7 × 8 = ?，支持换题），算对后方可点亮确认； - 第三重防线：浏览器原生终极确认，二次阻断误触可能。
- 教师端与管理员后台 100% 权限对齐：
- 管理员后台班级管理全面补齐【期次】Tab，支持新增期次、编辑期次、锁定/解锁切换、归档与直接删除；
- 教师可操作的所有直接删除与毕业清空，管理员在管理后台均可同等操作。
- 全局密码强度策略：管理员可在后台随时开启/关闭密码强度要求，支持按需组合：
- 最小长度（6–32 位自定义）；
- 强制包含大写字母（A-Z）；
- 强制包含小写字母（a-z）；
- 强制包含阿拉伯数字（0-9）；
- 强制包含特殊符号（标点符号）。
- 双轨免限机制：管理员创建教师或重置密码时直接遵循底层安全基线（6–128 位），不受自定义复杂策略限制，极大方便管理员批量分发简易初始口令；教师端自主改密时严格受全局策略限制。
- 初始密码状态精准跟踪：教师账号精准记录
initialPasswordChanged；新创建教师与管理员重置密码后自动标为【初始密码】，在管理员教师列表中以高对比度橙色徽章醒目提示。 - 教师登录改密弹窗与实时正反馈：未改密教师登录后自动弹出改密模态框；支持管理员配置【提醒模式（可跳过）】与【强制模式（禁关闭/Esc）】；新密码输入框下方动态渲染规则勾选清单（✓/○），提供直观正反馈。
- 一键全员改密应急操作：后台提供【
⚠️ 一键要求所有教师改密】操作（带二次防误触确认），一键批量置位所有有效教师，从容应对全校级安全合规升级。
- 纯前端零后端交互：完全在客户端内存与表格渲染计算流程中执行，零网络请求、零存储负担。
- 多级自定义优先级：教师可在工具栏打开【⚡ 高级排序】面板，自由增删多个优先级条件（个人总分、小组总分、各自定义评分项目），并独立指定升序或降序；支持通过【↑】【↓】一键调整优先级顺序。
- 强制汉字拼音 A-Z 升序保底：当所有设置的优先等级分值均相同时，系统自动执行汉字拼音（
Intl.Collator("zh-Hans-CN")）升序保底，确保排版次序绝对确定、无歧义。 - 彩色状态标记框与互斥联动：表格上方醒目展示高级排序生效状态卡片，支持一键
[×]清除；点击表头单列排序时自动优先让位；按账号和班级在本地隔离记忆，切换班级时自动重置为默认录入顺序。
- 公告与时间线双模块：管理员可在后台编辑面向全体教师的【置顶通知】（支持富文本排版）与【版本更新日志】卡片时间线（版本号、日期、详细更新说明）。
- 新公告发布与静默保存：支持一键发布新公告触发全员教师重新弹出；支持静默保存修正错别字而不打扰教师。
- 教师端原生模态框展示：教师登录后自动居中弹出原生
<dialog>窗口，支持勾选【无新公告时不再弹出】（基于教师账号隔离的本地 Cookie 记录）；顶栏常驻【📢 公告】入口与未读小红点，方便教师随时调出复看。
-
自然语言混合记分智能解析：单元格支持混合输入文字注释与分值（如
[主动发言+2] 迟到-1$\rightarrow$ 小计+1）；仅统计带显式+或-的数字，普通无符号数字（如日期20260901）不计分并给出友好黄色警示。 -
离线草稿暂存与防误关拦截：未提交修改即时保存在
sessionStorage，意外刷新或断网重连后无缝恢复；存在未保存修改时，自动激活浏览器原生beforeunload弹窗拦截，杜绝误关导致心血白费。 - 乐观并发冲突逐项仲裁：当多名教师并发修改同一学生的同一单元格时，弹出直观的版本差异对比面板，支持逐项选择保留服务器最新版或本地草稿版。
- 全端浅色 / 深色模式：默认自动跟随操作系统
prefers-color-scheme: dark，页面右上角提供独立的 ☀️/🌙/🌓 三态切换按钮，全站界面与弹窗均采用深度定制的高品质护眼配色。 - 桌面端（PC）：冻结左侧姓名列、顶部表头与右侧总分列；支持键盘上下左右方向键无缝跳格快速录入；编辑弹窗正居中聚焦。
- 移动端（手机）防异常专属排版（v1.5.1）：
- 44px 紧凑顶栏针对性隐藏长文本链接，杜绝顶栏折行撑破与横向滚动条，各操作按钮触控精准；
- 主内容区顶部提供仅 20px 高的轻量流式指示行，在表格滚动记分时自然滑出视野，零挤占记分屏幕空间；
- 悬浮工具栏双行紧凑排布（~68px 高），单屏横向容纳 6 个以上评分项目，支持平滑横向滑动浏览全部项目；
- 记分编辑抽屉靠顶排布（
top: 12px），彻底避开手机虚拟软键盘遮挡。
- 纯数学计算题验证码：加减乘整数动态算式挑战，防机器人碰撞与暴力破解，彻底告别图形验证码加载失败与小屏扭曲问题。
- 复合防爆破与校园网防误伤体系：
IP + 账号组合键锁定：单账号在某 IP 连续输错 8 次仅锁定该账号 2 分钟，同校园网出口（NAT）下的其他教师完全不受影响，彻底杜绝“一人输错，全校被封”的误伤与恶意 DoS 漏洞；- 阶梯式渐进延时：4
5 次连续失败强制延迟 2 秒响应，67 次延迟 4 秒，大幅拉长自动化爆破脚本的时间成本； - 单 IP 宽松全局频控：15 分钟内累计失败 60 次触发 10 分钟全局网络保护，严密防范跨账号“密码喷洒”撞库；
- 管理端安全监控与一键解封：管理员后台（
admin.html）提供【🛡️ 登录安全】面板，脱敏展示受限名单，支持单项精准解封与一键解除所有锁定。
- 严格 CSP 与安全 Cookie：全站启用严格 Content-Security-Policy 内联脚本 SHA-256 哈希校验，禁止内联动态拼接；Cookie 强制启用
HttpOnly; SameSite=Strict; Secure; Path=/（生产环境使用__Host-前缀）。
整个生产运行系统由恰好 4 个纯原生核心文件构成，无多余子目录，极简纯粹：
├── _worker.js # Cloudflare Pages Advanced Mode 聚合后端 API 路由与安全鉴权
├── login.html # 统一登录认证、深浅色切换与数学计算题验证码
├── admin.html # 管理员控制台（教师/班级管理、期次管理、密码策略与系统公告）
├── teacher.html # 教师积分台（高密度记分、期次加锁解锁、使用教程中心、毕业清空、高级排序与改密）
├── LICENSE # MIT 开源协议许可文本
├── README.md # 详细中文说明文档
└── README.en.md # Detailed English Documentation
system/catalog.json # 教师账号、PBKDF2 哈希、班级目录、密码策略、备份主密钥与初始密码标记
system/announcement.json # 系统公告置顶通知、版本更新日志与发布版本标识
system/snapshots.json # 管理员云端快照索引与快照数据容器（单时间线快照、元数据与备份摘要）
classes/{classId}.json # 班级稳定结构、期次配置、个人/小组积分、修订版本号与变更回执
classes/{classId}_snapshots.json # 班级云端快照索引（手动快照配额10个、自动急救快照FIFO保留2个）
classes/snapshots/{classId}_{snapshotId}.json # 班级快照数据实体（结构、期次与全期积分矩阵）
drafts/{classId}_{username}.json # 教师私有云端草稿暂存（一人一档物理隔离，7天自动过期）
sessions/{tokenHash}.json # 不透明会话、角色权限、CSRF 凭证与固定过期时间
captchas/{id}.json # 一次性数学挑战哈希、IP 摘要与过期时间
guards/{ipHash}.json # 登录失败计数时间窗口与临时 IP 封禁记录
双模管理（软归档 vs 物理彻底删除）：
- 软归档（Archive）：暂时封存实体，随时可一键【恢复】，历史打分与组员关系完整保留；
- 物理彻底删除（Delete）：物理抹除实体，单次写入内原子级联清除该实体在当前及所有期次中的全部积分，防止垃圾孤岛数据残留。
| 维度 | 建议指标 / 边界 | 说明 |
|---|---|---|
| 有效班级数量 | 最多 20 个班级 | 支持年级多班并行管理 |
| 教师账号数量 | 最多 100 个教师 | 支持多对多权限交叉绑定 |
| 每班学生容量 | 最多 100 名学生 | 满足超大班额教学需要 |
| 每班评分项目 | 最多 30 个项目 | 自定义德智体美劳等多维度考评 |
| 每班小组数量 | 最多 20 个小组 | 支持合作学习分组评价 |
| 班级期次数量 | 无严格限制（建议每学期 5–15 期） | 支持两周一期循环评比与期末总评 |
| 单单元格限制 | 最多 500 字符，分值绝对值最大 1,000,000 |
容纳翔实的日常评语备注 |
| 单批次保存 | 单次 API 请求最多提交 500 个单元格修改 | 满足整班批量保存打分需求 |
-
获取并准备 4 个核心部署文件：
-
下载源码：在本项目 GitHub 页面右上角点击绿色 Code 按钮
$\rightarrow$ Download ZIP（或使用git clone下载到本地）； - 解压文件：解压下载的 ZIP 压缩包；
-
准备上传文件：选中解压目录中的 4 个核心生产文件：
-
_worker.js（后端 API 路由与安全鉴权引擎） -
admin.html（管理员控制台） -
login.html（统一安全登录页） -
teacher.html（教师记分册工作台）
-
-
打包为平级 ZIP：选中这 4 个文件，右键打包为 ZIP 压缩包（例如命名为
deploy.zip；Windows: 右键发送到 -> 压缩(zipped)文件夹，Mac: 右键压缩 4 个项目）；⚠️ 关键提示（必看）： 千万不要直接上传从 GitHub 下载的原始 ZIP 压缩包！因为 GitHub 自动打包的压缩包内部包裹了一层形如Cloud-Score-main/的子文件夹，会导致 Cloudflare 无法在根目录识别到_worker.js服务端核心。请务必解压后将上述 4 个文件直接打包为纯平级 ZIP（解压即直接见 4 个核心文件，内部无任何层级目录），或者在浏览器上传时直接拖入这 4 个文件所在的文件夹。
-
下载源码：在本项目 GitHub 页面右上角点击绿色 Code 按钮
-
创建 Cloudflare Pages 项目并上传：
- 登录 Cloudflare Dashboard 控制台；
- 进入 Workers & Pages
$\rightarrow$ Create Application$\rightarrow$ Pages$\rightarrow$ Direct Upload； - 输入项目名称（如
cloud-score）； - 将刚才打包好的平级 ZIP 压缩包（或包含这 4 个核心文件的文件夹）拖入上传区域，点击 Deploy site。
-
配置 R2 存储桶与管理员密钥（关键步骤）：
-
创建 R2 存储桶：在 Cloudflare 控制台左侧进入 R2，点击 Create bucket 创建一个私有存储桶（如
cloud-score-data，保持 Public Access 为关闭状态）； -
绑定存储桶与密钥：回到刚才创建的 Pages 项目详情页
$\rightarrow$ Settings$\rightarrow$ Functions：-
R2 bucket bindings：点击 Add binding，Variable name 必须严格填纯大写
R2，选择刚才创建的 Bucket； -
Environment variables：点击 Add variable，选择 Type 为 Secret（加密变量），Variable name 必须严格填纯大写
ADMIN，Value 输入管理员初始强密码（建议 20 位以上包含大小写字母与数字的随机口令）；
-
R2 bucket bindings：点击 Add binding，Variable name 必须严格填纯大写
- 重新部署生效：回到 Pages 项目主页，点击 Deploy a new version（部署新版本），再次拖入上传一次刚才打包好的平级 ZIP（或文件夹），使环境变量与 R2 绑定正式激活生效。
-
创建 R2 存储桶：在 Cloudflare 控制台左侧进入 R2，点击 Create bucket 创建一个私有存储桶（如
-
初始化登录：
- 访问你的 Pages 默认域名（
https://<project-name>.pages.dev）或绑定的自定义域名； - 系统将自动跳转至
/login.html； - 账号输入
admin，密码输入你在 Secret 中配置的ADMIN密码，计算数学题即可进入管理后台建班、添加教师、设置密码策略。
- 访问你的 Pages 默认域名（
-
Fork 或导入 GitHub 仓库：
- 将本项目 Fork 到你自己的 GitHub 账号；
- 在 Cloudflare Pages 中点击 Connect to Git，选中你的仓库；
-
构建设置（本项目已内置原生
_worker.js，无需安装任何 npm 依赖或执行构建）：- Framework preset（框架预设）：选择
None； - Build command（构建命令）：完全留空；
- Build output directory（构建输出目录）：完全留空（或填
/）；
- Framework preset（框架预设）：选择
-
配置 R2 与 Secret 变量：
- 在项目设置的 Settings
$\rightarrow$ Functions 中绑定 R2 存储桶（变量名严格大写R2）与 Secret 密钥（变量名严格大写ADMIN）； - 重新触发一次部署即可。
- 在项目设置的 Settings
- 排查原因：Functions 运行时未正确读取到绑定的 R2 存储桶或加密 Secret。
-
解决方案：
- 检查 Pages 的 Settings
$\rightarrow$ Functions 中 R2 绑定的变量名是否为严格纯大写的R2（不能写成r2或其他名称）； - 检查环境变量中是否配置了类型为 Secret 且变量名为严格纯大写的
ADMIN； - 配置变量后必须重新部署一次（上传 ZIP 或推送提交）才能让绑定生效。
- 检查 Pages 的 Settings
- 排查原因：系统内置复合登录安全防线。单一账号在某 IP 连续输错 8 次密码后，仅该账号进入 2 分钟短冷静期（同一网络下其他教师完全不受影响）；若同一 IP 累计失败达到 60 次，将触发 10 分钟全局网络保护。
- 解决方案：单账号锁定只需等待 2 分钟冷却结束即可自动恢复登录；管理员也可随时登录管理后台（
admin.html），在教师管理工具栏点击【🛡️ 登录安全】，直接查看被锁账号/IP 并点击【🔓 解除】或【一键解除所有锁定】立即恢复。
- 排查原因：v1.5.0 起引入了初始密码状态跟踪机制。由管理员新创建的教师或被管理员重置密码的教师，账号会被自动标记为【初始密码】状态。
- 解决方案：教师根据界面实时规则指引设置一次个人新密码即可，改密成功后将自动进入工作台并不再弹出提示。管理员亦可在后台切换为“提醒模式”或直接关闭密码强度策略。
- 单个学生毕业/转学：在教师端【班级设置】或管理员后台【学生】列表中，点击该学生右侧的【删除】（或归档后的【彻底删除】），系统将彻底物理抹除该学生名单，并原子级联清理该学生在所有期次中的全部个人历史积分。
- 全班学生毕业离校换届：在【班级设置】底部点击【全班学生毕业清空】，经过 10 秒强制倒计时冷静与随机数学计算题安全验证后确认，即可一键清空全班学生名单及所有期次的个人积分，同时完好保留评分项目与期次配置供新一届学生直接使用。
- 班级撤销彻底删除：管理员可在管理后台班级详情顶部点击【删除班级】（或归档后【彻底删除】），系统将原子解绑所有任课教师并物理删除该班级对应的云端 R2 存储文件。
本项目遵循 MIT License 开源协议，个人与教育机构可免费商用、修改与私有部署。