# 贡献与工程约束

## 本地验证

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

```bash
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 追加版本号。

## 不可破坏的约束

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

## 改动原则

- 路由继续按业务域渐进迁移，每次只迁移一个域并运行全部测试。
- 新抽取的纯函数必须直接测试生产模块；禁止在测试文件复制实现。
- 安全或配额核心逻辑应做一次变异验证：临时改坏生产实现，确认对应测试失败后立即还原。
- 日志使用 `req.log` 或公共 logger，禁止记录密码、令牌、Cookie、Access Key 或完整授权头。