v1.2.0

NPClassworksKV v1.2.0 · Hitori（后藤一里）

版本概述

v1.2.0 是基于 v1.1.5 的学校互联服务更新，以 Hitori（后藤一里） 为代号，按正式版发布，配套 NPClassworks v1.2.0 和 NPEduTools InDev 20261002（Pre）。

本次新增 NPEP 身份与配对、设备状态、通知收件与回执、考试／日常远程操作、考试方案、原生噪音统计及学校排程政策。服务端负责鉴权、命令和数据，桌面负责系统操作与采样，网页负责学校管理和结果展示。原有作业、账号、通知、模板、考勤与实时同步业务继续保留。

网页和 KV 按正式版准备；配套桌面仍为预发布。真实班级大屏、学校排程和长期运行现场验收尚未完成，NPEP 联动建议先在单台设备试用。

新增功能

NPEP 身份、配对与设备状态

• 提供学校／班级范围内的设备配对、状态上报、暂停／恢复与管理员撤销，配对即授权当前学校互联能力。
• 使用持久化部署身份、代际及设备凭据核对连接；备份恢复后不能直接把旧设备身份当作新的有效授权。
• 根据设备协议和能力提供控制接口，区分设备在线、命令已受理与实际执行成功；保留错误和回执供后续核实。

通知投递

• 新增设备 HTTP 轮询收件、通知版本核对及持久化回执；按设备所属学校与班级计算可见范围。
• 次要通知的 popupEnabled 与网页采用相同语义；普通、重要、紧急通知仍须弹窗。关闭次要弹窗不等于删除通知或拒绝收件。
• 未指定失效时间的新通知默认显示一天，与前端编辑器预览一致；已保存的明确失效时间不批量改写。

远程模式与考试方案

• 提供单台设备的完整考试／日常切换请求、执行步骤、核实和结果记录。桌面联动软件运行、Windows 登录自启动及自动录课暂停；服务端回执不代替现场实时状态。
• 支持部分完成、失败和后续重试，避免把某一步已执行误报为全部完成。
• 新增考试方案存储、修订核验、投递与明确的开始放映请求，保留摘要和设备证据；需要 ExamAware 1.5.2 与桥接 0.4.0。

原生噪音与学校排程

• 提供原生监测启停、状态与结束报告接口，只接收统计，不接收原始录音。
• 报告包含会话、设备／算法、时长、覆盖率、能量平均、峰值及削波信息；按会话去重，支持断线补传。
• 每台设备保留最近 30 天、最多 200 份报告，网页显示最近 20 份；不把旧网页本地历史转成原生报告。
• 新增年级／班级每周政策，支持继承、覆盖、停用与修订冲突检查，记录设备执行信息及报告来源。无法关联来源时保持未知。
• 0.7 提供学校排程与来源关联，沿用 0.6 的原生报告结构；旧设备不能因在线而被当作支持新版排程。

体验与性能优化

• 设备状态、命令与报告分开记录，网页可明确区分历史完成结果和最近上报。
• 报告保留范围有上限；通知与命令使用持久化处理记录，减少重连重复展示或重复操作。
• /check 等服务版本信息读取统一包元数据；本版调整为 v1.2.0 / Hitori（后藤一里），不再以残留 v1.1.0 标识新功能组合。
• 更新服务页与浏览器图标，采用与 NPClassworks 一致的暖橙色品牌资源。

Bug 修复与运维改进

• 修复受限检出权限导致生产镜像内脚本为 root 所有、node 用户不可读取的问题，构建阶段核对运行时文件权限。
• 备份文件名增加唯一性保护，避免同时间重复备份覆盖已有数据库转储。
• 完善 NPEP 配置读写、启用门槛与恢复前检查；普通重启保留部署身份，恢复流程按代际失效规则处理旧授权。
• Windows 原生 PostgreSQL 调试、准备本地数据库与统一前后端启动流程，减少直接依靠生产环境排错。
• 生产发布继续执行后端、数据库、配套前端全栈与 N1 专用门槛；默认关闭的 NPEP 功能开关不免除这些测试。

安全与权限保障

• 控制请求仍需校验学校管理权限、设备范围、有效绑定、凭据及能力版本；配对授权不允许跨校访问。
• 重复请求和过期／被撤销设备继续执行协议检查，不以网络重试扩大权限。
• NPEP 默认关闭；启用需要一致的环境开关、外部持久化身份与数据库登记，缺失或不一致时拒绝入口。
• 统计为 dBFS 信号数据，不是校准声压级，不生成班级噪音排名；本版没有原音频上传或摄像头功能。

测试与发布保障

• 本次版本与说明准备后，重新运行发布组合、生产配置及 NPEP 配置／通知／模式／方案／噪音／排程相关测试，59 项通过、无跳过；本轮未重复真实数据库集成验收。
• 已合并功能通过后端质量和真实 PostgreSQL 集成 CI；网页配套 CI 完成真实全栈 37 项及独立 N1 配对验收 1 项。
• 本地既有后端单元测试 355 项通过，17 项数据库条件测试跳过；跳过不计为通过，数据库验收由独立集成阶段覆盖。
• N4 统一隔离验收完成网页、后端、桌面契约与原生 PostgreSQL／HTTP／Host 检查；现场大屏、学校时间及长期运行测试仍待补充。
• 本次 Release 草稿与版本元数据准备不等同于服务器部署、数据库迁移完成或生产功能开关已开启。

升级与兼容性说明

新增数据库迁移

相对于 v1.1.5 新增以下 7 项，应使用完整 Prisma 迁移链，不手工挑选 SQL：

迁移	作用
20260920120000_npep_n1	部署身份、设备配对与状态
20260924000000_npep_n2_notifications	通知收件与持久化回执
20260926000000_npep_runtime_control	远程模式操作与执行证据
20260927000000_npep_exam_plans	考试方案及投递记录
20260930000000_npep_noise	原生监测命令与统计报告
20261001000000_npep_noise_schedules	学校政策与修订请求
20261001010000_npep_noise_schedule_runtime	设备排程执行及报告来源关联

升级顺序与配置

1. 升级前备份 PostgreSQL、生产配置与正在运行的版本，并核对恢复方法。NPEP 外部身份目录是独立持久化数据，不包含在单独数据库转储中，需单独保留。
2. 先升级 KV，执行 prisma migrate deploy 并确认 /ready，再更新 NPClassworks v1.2.0，最后升级已配对桌面。保持现有前端／API 分离部署；不因本版更改域名或服务器部署代理配置。
3. 未启用 NPEP 的服务保持 NPEP_ENABLED=false 即可先使用原有业务；启用流程见仓库部署说明。已激活服务保留原 deployment.json 与身份卷，不要重复首次初始化或重新激活。
4. 本地开发使用 pnpm 与原生 PostgreSQL：安装锁定依赖、配置 deploy/.env.debug 后执行 pnpm debug:prepare，从前端仓库运行 pnpm dev 统一启动；配置与凭据不进入发行附件。
5. 新桌面可能执行已保存的学校规则，更新前检查年级继承、班级范围和时段。学校排程依赖 ClassIsland 学校时间，当前 Host 的已确认离线规则租期最长 24 小时；服务器禁用不能立即撤销离线采样，需要立即停止时在设备端操作。

回退

新增迁移不删除旧业务字段。应用回退时先保留新表和身份，不直接把数据库恢复当作普通代码回退；恢复数据库会丢失备份之后的写入，并需按 NPEP 恢复流程处理代际与旧授权。不要清除生产持久化卷或用旧身份文件覆盖当前身份。

文件说明与反馈

文件	作用
release-v1.2.0.md	功能、迁移、升级与回退说明，可离线保存
GitHub Source code (zip / tar.gz)	发布标签对应的后端源码和迁移，发布后自动提供；需要安装依赖、配置数据库并部署

源码附件不包含生产配置、部署凭据、设备令牌、数据库转储或现运行镜像；GitHub Release 草稿不自动更新服务器。问题请通过 GitHub Issues 反馈，并对日志与诊断信息脱敏。

Full Changelog

查看后端完整变更：v1.1.5...v1.2.0

v1.1.5

NPClassworksKV v1.1.5 · Ikuyo（喜多郁代）

版本概述

v1.1.5 是 NPClassworksKV 配套 NPClassworks v1.1.5 的功能与可靠性更新。

本次更新提供账号同步的个人作业模板、跨日期需带物品查询、选做与提交说明，以及面向学生和大屏的作业更正回顾接口。同时完善教师确认的版本核验、模板并发与兼容校验，继续沿用现有发布权限、修订历史和实时同步机制。

新增功能

个人作业模板

• 新增个人作业模板的列表、创建、修改和删除接口，按已鉴权账号隔离；模板随账号保存，可跨设备使用。
• 模板支持名称、标题、正文、选做内容、需带物品及提交说明，支持 〔页码〕 等纯文本填空项。
• 每个账号最多保存 50 个模板，每个模板最多 10 种填空项；服务端验证字段类型、长度和填空语法。
• 修改与删除要求携带 expectedRevision，缺少有效版本返回 428，版本冲突返回 409；匹配同一版本的并发修改只接受一次。
• 复用已有 AccountPreference 存储，不新增模板表。创建时串行核验账号容量，修改、删除在数据库行锁事务内读取版本并写入。

需带物品与作业补充信息

• 作业元数据支持需带物品及独立携带日期，服务端验证内容长度和有效日期；无作业标记也可附带准备事项。
• 公开和大屏 feed 增加 includePreparations=true，在非周查询中纳入携带日期符合范围的跨日期作业，为前端集中清单提供数据，并保留现有分页与可见性条件。
• 支持最多 6000 字的选做内容和最多 500 字的提交说明；不允许通知或“今日无作业”记录携带非空的选做、上交要求。
• 修改已发布作业时支持最多 300 字的 correctionReason，写入本次修订快照。旧原因不会随复制、恢复或下一次编辑自动沿用。
• 选做内容参与教师待处理中心的版本差异摘要，便于识别正文之外的修改。

作业更正回顾

• 新增公开接口 /api/v2/publications/feed/:id/corrections，以及大屏接口 /api/v2/classroom-screens/feed/:id/corrections。
• 按北京时间指定日期查询修订，比较连续且当时已经发布的版本，返回改前、改后、修订号和修改时间。
• 返回标题、正文、截止时间、选做、提交说明、需带物品及更正原因等允许展示的字段；不返回账号信息、任意元数据或完整原始快照。
• 使用 beforeRevision 向前分页，每页最多扫描 20 条候选修订，并提供后续游标；没有可展示差异时仍可继续读取后面的页面。
• 首次创建、草稿转发布、定时发布前的修改、撤回记录、已清理正文及仅更正原因变化，不作为可展示的内容更正。

体验与性能优化

• 按需扩展查询：跨日期物品查询通过显式参数启用，未使用参数的旧客户端保留原作业板查询范围；周查询继续采用已有规则。
• 更正记录分页读取：按修订号分批扫描，批量读取对应前一版本，避免一次返回所有历史快照。
• 模板旧客户端兼容：编辑时省略需带物品、提交说明或选做字段，保留服务端已有值；明确发送空字符串时才清除。
• 复用现有发布流程：明日清单、假期汇总、历史作业复用和文字分享由前端组合现有接口实现，不引入另一套发布或权限体系。

Bug 修复

教师确认与模板保存

• 修复当前版本已经确认时，旧版本确认请求被直接当作成功的问题。即使走重复确认分支，也先核验请求版本；不同版本返回 409，同版本重复确认仍可成功。
• 修复模板兼容合并后绕过填空项总数校验的问题。事务内合并旧客户端省略的字段后，重新验证最终完整模板；拒绝无效修改时保留原内容和版本。
• 为模板修改、删除及容量限制增加事务保护，减少多设备同时操作造成的版本覆盖或超出上限。

作业元数据与日期

• 复制为新草稿及大屏整日复制作业时，默认移除来源的携带安排，避免新作业继承旧物品日期；历史恢复仍保留该版本原有携带信息供核对。
• 统一清理沿用的更正原因，仅接受符合条件的本次教师编辑原因，避免来源版本的说明被误认为本次修改理由。
• 严格区分无作业标记与选做、提交说明的适用条件，拒绝含义矛盾的作业元数据。
• 修复无效作业板日期转换时抛出异常的问题，先检查日期有效性，再交由既有参数校验返回错误。

安全与权限保障

• 模板归属隔离：服务端使用当前鉴权账号确定归属，不接受客户端指定其他账号；列表、修改和删除均限制在该账号范围内。
• 更正查询范围：公开查询核验教学空间及有效学期；大屏查询从绑定计算可访问范围，不接受客户端扩大范围。
• 历史内容可见性：当前作业必须已发布、到达发布时间且仍对查询范围可见；前后两个修订也必须共享可见教学空间，避免展示调入该班前的无关历史。
• 最小化返回内容：更正接口只返回允许公开的业务字段，并设置 Cache-Control: no-store。
• 原有发布、修改、恢复及大屏写入继续执行既有权限和版本检查；新增元数据不作为扩大写入权限的依据。

测试与运维改进

• 新增模板字段与填空校验、需带物品、提交说明、选做内容、更正差异及非法日期的后端单元测试。
• 配套真实 PostgreSQL 全链路回归覆盖模板账号隔离、并发容量与版本冲突、旧客户端字段保留及合并后校验。
• 增加延迟旧版本确认、跨日期物品分页、复制与历史恢复、更正可见性、草稿隔离和撤回后拒绝访问等真实接口与浏览器场景。
• 继续使用现有后端验证、数据库测试和前后端组合测试作为部署检查；本次没有修改服务器部署代理协议。

升级与兼容性说明

• 建议与 NPClassworks v1.1.5 配套升级，继续支持 newfires.top 与 api.newfires.top 的分离部署方式。
• 相比 v1.1.0，本次复用已有 AccountPreference 和 Publication.contentJson，无新增数据库迁移。现有 Docker 启动前执行 prisma migrate deploy 的流程保持不变，无需手动修改 deploy/agent/server.js。
• 建议先更新后端，再更新前端。旧前端不会展示选做、提交说明、需带物品等新增信息；模板与更正回顾需要本版后端接口支持。
• 前端“仅显示教师已确认”和“待处理中心仅展示今日”是显示规则调整。后端保留实际确认状态与完整待处理查询能力，不批量确认或删除旧作业。
• 携带日期到期后由前端从当前清单隐藏，数据及修订历史继续保留。本轮不改变既有历史正文清理策略。
• 更正回顾依赖仍可用的连续修订，已清理正文无法重新生成差异；未返回更正不等同于证明作业从未修改。

Full Changelog

[查看后端完整变更：v1.1.0...v1.1.5](v1.1.0...v1.1.5)

v1.1.0

NPClassworksKV v1.1.0 · Ikuyo（喜多郁代）

版本概述

v1.1.0 是 NPClassworksKV 配套 NPClassworks v1.1.0 的功能与可靠性更新，版本代号为 Ikuyo（喜多郁代）。

本次更新提供一周作业查询、次要通知和版本化班级名单管理，重点完善通知认证、账号会话撤销、授课范围、发布分页与实时事件，并将真实前后端组合验证纳入后端部署流程。

新增功能

一周作业与无作业标记支持

• 公开及大屏 feed 接口支持 weekStart 和 weekView=board|due，按作业板日期或截止日期查询一周内的已发布作业。
• 截止日期按北京时间计算，支持查询在更早日期布置、但在所选周截止的作业。
• 校验并支持前端“今日无作业”标记的结构与内容，沿用现有发布、草稿、定时、修改、撤回和修订流程。
• 周查询继续执行班级范围、发布状态和学期/教学空间有效性检查，不把草稿、未到发布时间或已撤回内容混入结果。

次要通知与弹窗规则

• 通知优先级增加 MINOR（次要），为前端 Teams 默认提示音和可选弹窗提供等级信息。
• 次要通知支持保存弹窗选项；普通、重要、紧急通知执行必须弹窗的规则，并在服务端验证，避免仅依赖前端限制。
• 发布、编辑、复制与历史恢复中的优先级及通知元数据采用一致的校验，减少不同操作产生不一致通知状态。

行政班名单管理

• 新增学校管理员读取和保存行政班名单的接口，与大屏共用班级名单服务。
• 保存使用 expectedRevision 核验名单版本，避免管理员和多台大屏互相覆盖更改。
• 校验学生身份、所属班级、重复学号、姓名及名单人数，移出学生采用停用，保留历史考勤。
• 名单写入和完整前后名单审计在同一事务提交；提交后通过 classroom.roster.updated 通知相关大屏，事件不广播学生姓名。

体验与性能优化

• 发布 feed 游标分页：支持稳定游标及分页元数据，前端可读取完整列表，减少固定数量截断和并发翻页造成的问题。
• 运行指标对应实际请求：增加 HTTP 请求总数、失败数、请求耗时和当前 Socket.IO 连接数；使用固定路由模板作为标签，不为每次采样扫描业务表。
• 完整刷新投放范围：历史恢复后向受影响的工作区发送更新，覆盖目标变化涉及的旧范围与新范围。
• 名单一致性：管理员和大屏保存都在事务中锁定班级、比较版本、写入学生与审计，冲突时拒绝覆盖并返回明确状态。

Bug 修复

通知发布与生命周期

• 修复账号发布的通知被错误标为“待教师确认”的问题。通知不走学科作业的教师确认流程，发布后的认证信息与实际账号操作保持一致。
• 修复通知编辑、定时发布内容更新、复制和恢复路径中的认证归属处理，避免保留与当前操作不一致的认证信息。
• 增加针对现存错误通知状态的数据修复，依据当前账号修订恢复认证字段，不改写正文、修订号或较早的历史记录。
• 修复复制通知继承原通知过期时间的问题，新通知按自身发布时间开始新的有效期。
• 完善通知过期、撤回及版本变化时的可见性和回执校验，拒绝把旧版本状态当成当前版本确认。

作业范围与历史恢复

• 进一步区分账号对发布内容的编辑权限和教师确认权限，避免较宽的管理权限被误当作所有学科的确认资格。
• 对发布目标及授课范围进行一致验证，拒绝跨学校、越权目标或已停用教学空间的写入。
• 修复历史恢复后部分旧目标工作区未收到实时更新的问题，减少客户端继续显示已移出范围的内容。
• 完善日期窗口、发布状态、分页边界及游标参数校验，保持公开列表、大屏列表和实际发布规则一致。

学校结构与班级名单

• 加强学校内教学空间身份冲突和已停用走班教学班的处理，避免重复或失效空间继续成为有效操作目标。
• 防止名单保存引用其他班级的学生，或通过无版本请求覆盖新版名单。
• 并发保存名单时只接受匹配当前版本的请求；版本冲突不执行部分写入，保留已保存学生与考勤关系。

安全与权限修复

• 账号会话撤销即时核验：访问令牌校验结合持久化账号会话状态，关闭单次会话后，旧访问令牌不能继续借刷新或续签路径使用该会话。
• 大屏凭据边界：继续在实际写入事务中检查绑定、凭据和授权，完善账号会话撤销及学校角色变化后的拒绝路径。
• 确认范围校验：通知与作业使用各自的认证规则，教师确认作业时依据实际授课权限，不直接沿用宽泛的编辑授权。
• 名单管理授权：服务端核验学校管理身份、行政班归属和名单中每个学生的身份；校验与写入共同置于事务保护下。

测试与运维改进

• 后端生产部署除普通测试和真实 PostgreSQL 测试外，还要求真实前后端全链路检查成功。
• 全链路验证使用本次触发的后端提交，配合明确记录版本的前端，输出两仓提交信息，便于追踪被验证的组合。
• 增加持久化账号会话、通知认证、次要通知、周查询、feed 分页、名单权限与并发保存的回归测试。
• 扩充真实 HTTP、Socket.IO 和隔离 PostgreSQL 测试，减少仅靠源码匹配或内存 API 得出功能正确结论的情况。
• 修正开发入口路径，使用 Node 自带 watch 与 env-file 加载方式，移除对未声明 nodemon 及平台专用环境变量写法的依赖。
• 完善依赖安装、容器构建与部署验证流程；保留现有签名部署请求和服务器代理。

升级与兼容性说明

• 建议与 NPClassworks v1.1.0 · Ikuyo（喜多郁代） 配套升级，继续支持 newfires.top 与 api.newfires.top 的分离部署方式。
• 相比 1.0.1 文档所描述的维护版本，本轮包含以下新增迁移：
  • 20260908000000_minor_notice_priority：增加 MINOR 通知优先级。
  • 20260909000000_account_notice_certification：修复符合条件的现存账号通知及其当前修订认证字段。
• 使用仓库现有 Docker 自动部署流程时，启动命令先运行 prisma migrate deploy；已应用的迁移不会重复执行。此前已持续部署相关提交的服务器，可能已经应用这两项迁移，本次修改版本号不新增迁移。
• 无需手动修改 deploy/agent/server.js。 自定义非 Docker 启动方式仍需按原有流程先应用尚未执行的数据库迁移。
• 名单管理沿用现有学生数据表，不新增名单版本字段。旧版大屏可继续读取名单，但缺少 expectedRevision 的保存返回 428；版本不一致返回 409。请更新前端并重新读取名单后再编辑。
• 次要通知需要新版前端正确显示和播放提示音。已有旧大屏页面不会因后端升级自动获得新等级处理逻辑，应在保存当前输入后更新应用。
• 本轮统一将后端 package.json 从此前遗留的 1.0.0 更新为 1.1.0；/check 和 /ready 的版本及代号随同一配置返回。历史文档中的 1.0.1 仍代表上一轮维护更新，不因旧包版本号遗漏而失效。
• 新指标中的 Socket.IO 连接数不是独立设备数或已鉴权大屏数；失败计数包含业务冲突等 4xx 响应，使用时需结合路由与状态码判断。

Full Changelog

[查看后端完整变更：v1.0.1...v1.1.0](v1.0.1...v1.1.0)

v1.0.1

NPClassworksKV v1.0.1 · Nijika（伊地知虹夏）

版本概述

v1.0.1 是 NPClassworksKV 基于 v1.0.0 的维护更新。

本次更新重点改进作业提交的一致性、权限撤销后的写入保护、通知回执和历史清理，并优化待处理中心查询及自动部署验证，为现有前端功能提供更可靠的后端支持。

新增功能

无。 本版本不新增业务功能，主要完善现有接口的正确性、安全性、性能和运维保障。

体验与性能优化

• 减少重复作业：大屏创建与离线补传支持稳定请求标识，同一请求的并发提交和重试返回已有结果，避免重复创建作业、修订及创建事件。
• 历史列表分页：教师和大屏的修订历史接口支持按版本游标分页，默认每页 20 条，减少一次性返回全部完整快照的开销。
• 待处理中心按页读取详情：在数据库内完成范围筛选、分类、排序和汇总，先选出当前页，再加载该页正文与认证快照，减少将全部候选作业载入服务进程的开销。
• 分页结果更一致：待处理中心为同时间记录补充稳定排序，并在同一数据库事务快照中读取汇总与当前页，减少单次响应内数据不一致的情况。
• 历史清理持续推进：按稳定游标遍历候选记录，减少因前面一批记录始终不可清理，导致后续符合条件的历史长期积压。

Bug 修复

作业提交与版本一致性

• 修复服务器已保存、响应丢失后重试可能再次创建作业的问题。请求身份、首次创建和修订快照在同一事务中保存，并以唯一索引保障去重。
• 同一请求标识携带不同内容时返回冲突，避免把另一份输入误当作原请求的成功结果。
• 将创建请求身份与后续编辑来源分离，教师修改、确认或撤回作业后，旧请求重试不会覆盖这些后续操作。

通知回执

• 修复旧版本的迟到回执覆盖新版已确认状态的问题。
• 修复同一版本的并发回执、同批重复条目使确认状态倒退的问题；同版本状态只向前推进。
• 修复并发首次回执出现唯一约束冲突，以及通知撤回后等待中的请求仍创建回执的问题。
• 在回执写事务内重新核验大屏凭据、通知版本和发布状态，保证批次写入顺序与结果一致。

历史清理

• 修复只检查最早 200 条候选，后面的可清理记录可能一直得不到处理的问题。
• 修复分页边界、相同时间戳及数据库微秒时间精度下可能跳过候选记录的问题。
• 修复清理等待期间班级已重新启用，或历史已成为当前、已认证版本后，仍按旧状态清理内容的问题。
• 保留现有历史清理条件和时长；当前版本、已认证版本、近期记录及通知历史继续受到保护。

安全与权限修复

• 学校所有者保护：阻止 ADMIN 授予 OWNER、降级或删除现有 OWNER，以及通过账号创建或批量导入覆盖 OWNER 的路径。
• 最后所有者保护：成员变更和账号写入在事务内重新检查角色，防止并发操作使学校失去最后一位 OWNER。
• 草稿可见范围：修复只读教师在未指定班级的列表中看到无权草稿的问题，使列表与详情的授权规则保持一致。
• 通知历史保护：阻止大屏通过恢复历史修改教师通知，或将作业恢复为通知快照。
• 初始化令牌校验：初始化密钥缺失时明确拒绝请求，不接受以空密钥签名的令牌。
• 撤销与写入并发保护：大屏创建、补传、修改、历史恢复和考勤保存均在写事务内重新核验绑定与凭据。撤销先提交时，旧令牌不能继续写入；已先取得授权锁的写事务完成后，撤销再生效。

测试与运维改进

• 将真实 PostgreSQL 集成测试加入生产部署前验证，失败或超时不再继续请求部署代理。
• 增加真实 HTTP 权限测试和隔离数据库并发测试，覆盖角色降权、大屏停用与解绑、幂等提交、通知回执、历史分页及清理。
• 补充学校迁移包篡改场景测试，完善对损坏或被修改数据包的拒绝验证。
• 在隔离数据库中实际运行备份与恢复脚本，核对账号、学校成员、教学空间、大屏凭据、作业及修订关系，并验证校验失败时拒绝恢复。
• 升级脚本在取得部署锁后固定前后端提交 SHA，校验兼容性声明，并记录本次部署版本；成功部署或回滚时同步更新版本记录。
• 部署代理程序和签名请求格式保持不变。固定提交取自取得部署锁时的仓库引用，不保证等同于某次 GitHub Actions 的触发提交。

升级与兼容性说明

• 建议与 NPClassworks v1.0.1 配套升级，现有同源和独立 API 域名部署方式均继续支持。
• 相比 v1.0.0，本版包含迁移 20260905000000_screen_publication_idempotency，为作业增加可空的创建请求身份字段及复合唯一索引；无需重建学校或重新录入已有作业。
• 使用现有 Docker 自动部署流程时，启动命令会先执行 prisma migrate deploy，成功后启动后端；无需手动登录服务器执行这项迁移。自定义非 Docker 部署需在启动新版服务前应用迁移。
• 无需手动修改或重启 deploy/agent/server.js。 版本配对检查随升级脚本更新；首次安装新脚本的那次升级仍由服务器原有脚本执行，后续调用才使用新检查。
• 不带请求标识的旧客户端仍可提交，但不具备本次请求级幂等保证；升级前已创建且没有记录请求标识的数据不能追溯建立去重关系。
• 历史接口不带分页参数时仍返回旧数组格式，兼容尚未刷新的旧前端。现有通知回执、作业恢复和考勤接口格式保持不变。

详细说明见[自动部署文档](./automatic-deployment.md)、[提交幂等说明](./screen-publication-idempotency.md)和[版本配对说明](./deployment-version-pairing.md)。

Full Changelog

[查看后端完整变更：v1.0.0...v1.0.1](v1.0.0...v1.0.1)

v1.0.0

NPClassworksKV v1.0.0 · Nijika（伊地知虹夏）

NPClassworksKV v1.0.0 是 NPClassworks 的首个正式配套后端版本，提供学校组织、账号权限、作业通知、班级大屏和运维管理能力。

主要变化

• 从旧 KV 数据接口升级为基于 PostgreSQL 与 Prisma 的学校业务数据模型。
• 增加学校、学期、年级、行政班、教学班、学科和教学关系管理。
• 增加学校管理员、年级组长、班主任和任课教师的职责叠加与授权范围。
• 支持本地短账号、PIN/口令登录、大屏独立账号及可选 OAuth 配置。
• 增加作业与通知、教师确认、修订历史、重复检测和乐观并发控制。
• 支持教师多班发布，以及各目标班级后续独立修改。
• 增加通知送达记录、大屏心跳、离线提交和大屏值守审计。
• 增加后端 OOBE、组织与教师 JSON 导入、可视化管理接口和完整学期切换流程。
• 增加学校迁移包、自动备份、恢复、升级和回滚工具。
• 支持同源或独立 API 域名部署，并增加 CORS 与生产环境检查。
• 增加带签名鉴权的部署代理，无需向 GitHub Actions 提供 SSH 密码。
• 停用不再使用的 Classworks 1 接口、UUID 登录流程和旧设备服务。

部署与升级

• 推荐与 NPClassworks 前端 v1.0.0 配套部署。
• 新实例应从空数据库启动，通过 OOBE 创建学校和生产管理员账号。
• 升级早期测试实例前，必须先备份 PostgreSQL，再执行数据库迁移。
• 非 Docker 部署需要自行配置 Node.js 22、pnpm 10、PostgreSQL、进程守护和反向代理。
• 生产环境必须正确设置公开地址、前端来源、数据库连接和登录密钥。

详细步骤见[新手部署教程](./beginner-deployment-guide.md)和[自动部署说明](./automatic-deployment.md)。

FAQ

NPClassworksKV 是 ClassworksKV 的直接替代品吗？

不是直接替换。它源自 ClassworksKV，但数据结构、接口、权限和部署方式均已大幅调整，旧前端不能直接连接本版本。

能迁移原公共 Classworks 实例的数据吗？

本版本不提供旧 UUID 作业数据迁移。学校迁移工具用于 NPClassworks 实例之间的数据转移。

必须使用 Docker 吗？

不是，但 Docker Compose 是当前文档覆盖最完整的部署方式。手动部署需要由维护者自行处理依赖、数据库迁移、守护进程、HTTPS 与备份。

Novark Power 会提供托管后端吗？

目前及可预见的较长时期内不会提供面向公众的官方实例。部署者需要自行维护服务器、数据库、域名、HTTPS 和备份。

FullChangeLog

[查看后端完整变更：b01c2c2...v1.0.0](b01c2c2...v1.0.0)

Compare 链接会在仓库创建 v1.0.0 标签后生效。

致谢

感谢 ClassworksKV 原作者及贡献者为后端提供基础。

NPClassworksKV 由[星火动力（NOVARK POWER）](https://novark.ink/) 维护，遵循 GNU AGPL-3.0 许可证。