ClassHelper/AGENTS.md

AGENTS.md — ClassHelper（Class Helper）

本文件供本仓库的 AI 编码代理使用。先读这里，再改代码。当前工作目录为 F:\ClassHelper。 现行规则按工作区源码维护；产品说明见 docs/app/，开发契约见 docs/dev/，部署见 docs/management/。 查证路径见 docs/reference.md。文档与代码冲突时，阅读实现及其校验规则后同步修正文档，不沿用历史报告中的结论。

1. 项目与目录

pnpm monorepo，根 package.json 是版本单一来源。文档、注释、界面文案及提交描述使用中文。 远端为 LoveChengke/ClassHelper，默认分支 master。

目录	用途
packages/shared/src/	三端共享类型、权限、常量、动效、岛方案与课件契约
packages/server/	Express、Prisma、Socket.IO；API 前缀 /api
packages/web-admin/	Vue Web 管理端，PWA
packages/desktop-client/	Electron 主进程、preload、主窗口与独立灵动岛渲染进程
scripts/	版本、构建、验证、打包、图标与 Pages 脚本
deploy/	Windows/Linux/Docker 部署与运维模板
docs/	docfx 文档；images/ 为展示图，screenshots/ 为回归截图
website/	纯静态官网与下载页
releases/	按组件和版本存放本地交付物，gitignored

不要在文档中手抄模块、表、权限键、测试用例的总数；分别查注册表、schema、共享目录与本次验证输出。

2. 服务端与数据边界

• 模块由 packages/server/src/modules/registry.ts 注册；新增或下线功能改注册表，不另改 app.ts 挂载。
• 路由用 middleware/validate.ts 与 zod；响应复用 lib/http.ts，错误交给统一中间件。
• 学生是 Student 名单记录，没有账号、角色或密码。教师/管理员存 User；班级登录读取 Class.code/passwordHash，会话角色 CLASS_DEVICE，主体 id 为班级 id。
• 任课关系只在 Course(classId, name, teacherId)。班主任不自动获得别的科目的作业、成绩写权限，统一走 lib/authz/assert.ts 的 assertContentWrite。班级端可录作业，不可写成绩；员工还须对应功能权限。
• 功能、范围、关系统一由 lib/authz/ 判定，所有服务显式传权限键。ADMIN 固定全部能力；TEACHER 永久忽略管理员专用键；CLASS_DEVICE 为空集，接口明确允许并校验本班。权限管理仅 ADMIN。
• 岗位模板只管能力与建议范围，生效范围存 UserPermissionGroup.scope/scopeValue，使用 TEACHING/HEAD/GRADE/DIVISION/ALL。无显式分配的教师使用默认模板与固定 TEACHING；空或未知年级拒绝。按键独立合并范围，无键查询为空集；班级账号/学期设置永远要求本班班主任，科目写检查原/目标科目。具体断言和迁移见 docs/dev/permissions.md。
• 只有一份 prisma/schema.prisma，切库改 provider；保持 SQLite/MySQL 通用，不加 Prisma enum 或 @db.*。模型变动同步迁移、lib/snapshot.ts 的 SNAPSHOT_TABLES 与旧库兼容逻辑。
• deleteTeacher 必须保护班主任、课程任课、发布的作业/通知和所属课件，避免级联删除业务内容。
• 作业和通知按本地 assignDate 归类，使用 dayKeyLocal/isDayKey/shiftDayKey，不用 UTC 日期切片。
• 批量通知/作业逐班返回结果；跨班作业按科目名匹配既有课程，找不到则该班失败，不自动把发布者设为任课老师。
• 两个登录接口共用登录限流。附件链接校验 scheme；表格文件上限 8 MB、JSON 请求体 12 MB，超限映射 413。
• AI 助手只解析待确认动作，前端确认后调既有发布接口；参数重新校验，Key 加密存储且不回传。自动化用 mock，不访问外网。

3. 课表、周次、成绩与学年

• 课表真值是 ClassPlan/ClassPlanEntry/TimeLayoutItem；旧 Schedule 与 TimeLayout.items 保留迁移审计用途，不双写或回读复活旧业务。
• /api/schedules/* 是新模型兼容门面。启用解析统一走 lib/class-plan.ts，在线客户端不得另写启用优先级。
• 时间点有上课、课间、分割线、行动四种；课程显式引用时间点外键。排序不能靠数组下标代替关联。
• 支持 1–9 周轮换、群组、预定及临时层；完整档案导入走 profile-import.service.ts，不经过单双周有损格式。
• 全校时间表写入仅管理员；班级时间表按存储 classId 校验 schedule:write 与班主任关系，引用班级也校验。日课表/名单在 TEACHING/HEAD 范围要求班主任，显式年级/部/全校分配可在范围内维护。离线整套课表导入可建立班级自有作息，不把 JSON 的 TeacherName 当授权。
• 周次统一 loadTermContext/resolveCurrentWeek：班级逐周区间优先于全校区间，缺省再线性推算。开学日会参考班级设置、第 1 周区间、全校设置与环境兜底，详见 lib/term.ts。
• 全校周数上限存 term.maxWeeks，默认 30、范围 1–60；服务端 getMaxTermWeeks()，shared 做归一化与离线兜底。班级周数不超全校上限。
• 关闭个人成绩查询后，班级端仍可看服务端集体聚合；个人明细、原始全班成绩和排名拒绝读取。稀疏样本及补集抑制，不下发原始成绩后在客户端聚合。
• 总分开关属于 Exam；排名同学生同科取最高分，并列排名为 1、2、2、4。客户端只展示，不能修改成绩查询或考试配置。
• 年度升级由 term.promotionAt 配置，PromotionRun.year 保证幂等，升级前保存快照。运行期到点自动执行，启动漏跑先预览补跑；开发机启动不得擅自升级业务数据。
• 高三归档，其余升一级；新班仅建骨架，不复制班主任/任课关系。转出过滤复用 lib/students.ts，学号不复用，归档页保留历史与撤回转出。

4. 客户端、灵动岛与课件

• preload 仅暴露 contextBridge 白名单，不暴露 ipcRenderer；跨桥接传纯数据，不传 Vue Proxy。契约写在 src/types/desktop.d.ts。
• 保留 CSP、导航同源校验与弹窗限制。安装包不能含凭据，保留 check-bundle-secrets 构建门禁。
• 离线缓存按服务端与班级隔离，缓存故障不应阻断在线读取。退出、切服务器时清理会话状态，设备 deviceKey 保持不变，渲染层不能改写它。
• 设备维护只走 /api/clients/*，管理页 ClientsView.vue；心跳、进度、回执仅接受本班 CLASS_DEVICE，deviceKey 不可跨班迁移。心跳约 30 秒，90 秒窗口判在线；未登录不报，401/403 退避，切配置重置计时并隔离迟到响应。
• 远控须 remote:control，只允许 shutdown/restart/logoff/lock，客户端立即执行、持久去重并回执。冒烟始终假执行，不得真关机/重启/注销/锁屏。
• 安装包登记/删除为管理员 client:update；班级推送用 client:update-push；服务端缓存包并登记 SHA256，教室机从本服务下载；无哈希拒收，按立即/放学后/空闲策略执行，关闭自动更新不得强装。冒烟不运行安装器。
• 灵动岛方案保存在本机 config.json.islandLayout，默认 layout=fixed；custom 当前即常驻模式，旧 residentEnabled 是兼容字段。新尺寸上报仅在 custom 模式执行。
• LayoutIslandApp.vue 选择经典 IslandApp.vue 或 CustomIslandRuntime.vue，共用一个原生岛窗口；课件传输状态优先显示 CoursewareTransfer.vue。
• 经典模式：普通通知/作业上课暂存；普通叫人保留可点击胶囊；紧急消息立即展开。自定义常驻模式：消息先提示铃铛数量，用户主动展开；上课也可主动查看。不要把两个模式规则混写。
• 自定义方案的常态 rows 与无消息展开 expandedRows 分开编辑。课程、时钟、容器等使用 shared 组件契约；测量自然内容并按工作区约束适配。
• 保留经典岛连续圆角、投影常驻、触摸输入、失焦宽限与固定窗口几何护栏。不要调用 setBackgroundMaterial() 破坏逐像素透明。左右边距仅左/右停靠生效。
• 消息按 id 去重，通知/叫人双播不得重复；列表布局复用 shared 度量。崩溃恢复保持限流，冒烟不得自重启。
• 课件权限和任课范围独立校验：拥有文件、文件可见范围与本人授课班级共同约束推送，岗位范围不代替任课授权。
• 课件最大 512 MB，流式收发、临时文件、SHA256 校验；客户端不自动运行文件，每设备独立回执。JSON 快照只含元数据，完整备份另带文件目录。

5. 实时、界面与资源

• 事件名与房间名取 shared 常量。班级房间为 class:{id}:{channel}，教师按每域读键及范围订阅，班级端仅本班全部通道；握手回查数据库身份。业务用 emitToClass/emitToSession，由总线选择事件域。
• 会话房间为 session:{id}；教师/管理员 id 为账号 id，班级端为班级 id。students 是班级端广播房间，不是个人学生账号房间。
• 新实时事件同步服务端、Web 订阅、客户端订阅。成绩实时载荷不可泄漏个人成绩。
• Web 菜单分组在 config/navigation.ts，标题/图标/权限取路由；守卫与服务端都检查权限，前端隐藏不能代替鉴权。
• 侧栏折叠用 CSS 保持 DOM，关怀模式放大字号/控件，不改变几何令牌。使用语义色，动效统一 shared 令牌；图标新增后检查注册表。
• 图标源是 build/classhelper.png 与设计导出的 .ico，pnpm icons 派生其余资源。ICO 原样透传，客户端兜底 build/icon.* 同步保留。
• Web 品牌图用 /logo.png，客户端用 BRAND_LOGO_URL，避免 file:// 绝对路径问题。
• 官网和文档站共用一个 Pages 站点，scripts/build-pages.mjs 拼装根站与 /docs/；文档不写指向 docs 树外的相对链接，源码用 GitHub 绝对链接。
• 展示图引用 docs/images/，回归图放 docs/screenshots/。官网 .reveal-grad 不拆逐字节点，动效改 token 表。
• ClassIsland 联动插件、设备令牌、提醒渠道与镜像接口已退役；保留离线 JSON 导入和设计参考，不恢复在线联动依赖。

6. 本机命令与验证

脚本以根/各包 package.json 为准；端口：后端 4000，Web dev 5173，客户端 dev 5174，官网 5180，文档 5181。 先构建 shared 再启动下游。新环境按需执行 install → db:generate → server db:deploy → build:shared；db:seed/db:reset 会清业务表，只用于明确选择的演示/隔离库。

本机 Node 路径为 D:\Node.js\node.exe。受限终端的 pnpm 可能解析到运行时兜底版本，先看 Get-Command pnpm 与 pnpm --version。 仓库锁定 pnpm 11.8.0，可用 C:\Users\hck16\AppData\Local\node\corepack\v1\pnpm\11.8.0\bin\pnpm.cjs。 经 DSH 转发壳时可设置：

$env:PATH = 'C:\Users\hck16\AppData\Local\deepseek-harness\bin;' + $env:PATH
$env:DSH_NODE = 'D:\Node.js\node.exe'
$env:DSH_PNPM_BIN = 'C:\Users\hck16\AppData\Local\node\corepack\v1\pnpm\11.8.0\bin\pnpm.cjs'
Remove-Item Env:DSH_PNPM -ErrorAction SilentlyContinue
pnpm --version

受限 electron-builder 调 pnpm list 曾报 ERR_SQLITE_ERROR，这是进程访问限制，不据此认定依赖缺失。 Prisma 使用 driver adapter；本机优先应用已有迁移，不用 migrate dev 排查 Windows 初始化问题。 本地 HTTP 探测绕过代理；运行中数据库及 WAL/SHM 不按临时文件清理。

命令	范围
pnpm lint / pnpm typecheck / pnpm check:icons	代码静态门禁；按改动范围执行
pnpm docs:check	文档严格构建，警告即失败
pnpm verify:e2e	自动创建临时 SQLite 和账号，无需先开开发服务，禁止外网
pnpm verify:web:isolated	构建 Web 后运行隔离服务和隐藏 UI 回归
pnpm verify:courseware / pnpm verify:v14	课件/课表等隔离专项
pnpm verify:desktop / pnpm verify:packaged --exe <路径>	默认后台快速检查，不创建可见岛或托盘
pnpm verify:desktop:online	显式联网，使用临时教师和班级
pnpm verify:desktop:visual / packaged 的 --visual	显式视觉模式，动画、透明度、截图；会使用桌面

禁止为验收回退到真实班级、重置其密码或发送测试通知。验收数量只记录本次实际输出。 仅文档修改做格式、链接、构建检查，不为此反复占用桌面或重打安装包。 Prettier 用 LF，只格式化本次改动；不要为旧基线批量格式化源码。 改 Linux 交付脚本还要 bash 语法检查和 Linux 真机/CI 验证；改打包逻辑需打包后副本复验。

7. 发布与工作区清理

• 版本只由 scripts/version.mjs 修改；日常维护不涨版，指定固定版本重构建时保持该版本。发布流程见 docs/dev/release.md。
• 本地 pnpm dist:all 产出 Windows 服务端和客户端；Linux 正式包由 release-linux-server.yml 在 Linux runner 构建，非 Linux 交叉构建仅供验证。
• 本地文件名与 Release 的 ASCII 上传名不同，校验清单应明确映射；保留当前版本清单、更新日志及最新包。
• releases/ 只放交付物及少量构建信息，不留 win-unpacked、服务端 staging、解包副本；staging 在 .cache/server-staging/，成功后脚本删除。
• 2026-10-18 按用户要求清除 1.4.0 旧重构建归档，只保留 client/1.4.0、server/1.4.0 与当前清单/说明。以后同号重构建可临时留回滚副本，最新包验证完成且用户要求清理时再删除。
• 递归删除/移动前核实绝对路径在指定工作区，禁止误删源代码、真实数据库、配置、凭据、工具缓存或其他版本交付物。
• 不清理 node_modules、.pnpm-store、.cache/{nuget,npm-cache,dotnet-home,mingit}、packages/*/dist、生成的 Prisma Client，除非任务明确要求。
• 保留已有未提交工作；提交前查看 diff，中文 Conventional Commits 描述。只有用户要求发布/同步时才执行远端发布链。