贡献与工程约束

本地验证

项目要求 Node.js 20.19 至 24.x。后端与 Web 前端分别维护锁文件，依赖变更后必须同步提交对应的 package-lock.json。

cd backend
npm ci
npm test
npm audit --omit=dev

cd ../frontend
npm ci
npm run build
npm audit

开发 Web 前端时分别运行后端 npm run dev 与前端 npm run dev。生产环境只服务 frontend/dist/，不要手工修改构建产物或给资源 URL 追加版本号。

app.use(expressErrorHandler) 必须保持为最后一个 app.use；CI 的架构测试会检查这一点。
Express 4 使用 express-async-errors 捕获异步路由拒绝；该补丁必须在注册任何路由前加载。
限流器、下载安全计数和 OSS 用量缓存仍是进程内状态，PM2 必须保持单实例 fork 模式。扩容前先迁移到共享状态存储。
npm ci 依赖严格同步的 lock 文件；禁止在部署脚本中删除 package-lock.json。
Express 中间件顺序是安全边界：requestId/安全头/CORS/HTTPS/静态资源/API 限流/请求体/CSRF，不得无验证调整。
桌面安装包目录 frontend/downloads/ 是运行时发布目录，更新前必须备份且不得放进 frontend/dist/ 的清理生命周期。
桌面安装包必须作为 Gitea Release 附件发布；Git 只提交 frontend/desktop-release.json，禁止提交 .exe。
更新 Release 元数据时必须核对标签、文件名、字节数和 SHA256，并运行 npm run check:desktop-release。