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 |
设备排程执行及报告来源关联 |
升级顺序与配置
- 升级前备份 PostgreSQL、生产配置与正在运行的版本，并核对恢复方法。NPEP 外部身份目录是独立持久化数据，不包含在单独数据库转储中，需单独保留。
- 先升级 KV，执行
prisma migrate deploy并确认/ready，再更新 NPClassworks v1.2.0，最后升级已配对桌面。保持现有前端／API 分离部署；不因本版更改域名或服务器部署代理配置。 - 未启用 NPEP 的服务保持
NPEP_ENABLED=false即可先使用原有业务；启用流程见仓库部署说明。已激活服务保留原deployment.json与身份卷，不要重复首次初始化或重新激活。 - 本地开发使用 pnpm 与原生 PostgreSQL：安装锁定依赖、配置
deploy/.env.debug后执行pnpm debug:prepare，从前端仓库运行pnpm dev统一启动；配置与凭据不进入发行附件。 - 新桌面可能执行已保存的学校规则，更新前检查年级继承、班级范围和时段。学校排程依赖 ClassIsland 学校时间，当前 Host 的已确认离线规则租期最长 24 小时；服务器禁用不能立即撤销离线采样，需要立即停止时在设备端操作。
回退
新增迁移不删除旧业务字段。应用回退时先保留新表和身份，不直接把数据库恢复当作普通代码回退；恢复数据库会丢失备份之后的写入，并需按 NPEP 恢复流程处理代际与旧授权。不要清除生产持久化卷或用旧身份文件覆盖当前身份。
文件说明与反馈
| 文件 | 作用 |
|---|---|
release-v1.2.0.md |
功能、迁移、升级与回退说明，可离线保存 |
GitHub Source code (zip / tar.gz) |
发布标签对应的后端源码和迁移，发布后自动提供；需要安装依赖、配置数据库并部署 |
源码附件不包含生产配置、部署凭据、设备令牌、数据库转储或现运行镜像；GitHub Release 草稿不自动更新服务器。问题请通过 GitHub Issues 反馈，并对日志与诊断信息脱敏。