Web 层

Web 层与注意事项

• 登入/注册/班级码加入是 HTML 表单路由，不属于 /api：登入 POST /user/password、注册 POST /user/register、班级码 POST /classes/join。它们需要网页 CSRF 令牌，不能用 API 的 Bearer 方式调用。
• Cookie 与 API 的边界：网页会话来自 Express Session（MySQL 存储，默认 7 天）。API 令牌是无状态签名，默认 30 天；两者互不替代。网页写操作使用 Cookie + CSRF 令牌；API 的 Cookie 写操作没有 CSRF 令牌，改用来源校验（优先 Origin，缺失时看 Referer，必须与请求 Host 同源）；两种来源头都没有的原生客户端不受此校验。Bearer 写操作也不做来源校验。
• 不存在的接口：任何未匹配的 /api/* 请求返回 JSON 404，error.code=NOT_FOUND，消息包含方法和原始路径；不会渲染网页 404。
• 错误信息与隐私：生产环境的 500 统一返回“服务器开小差了”，不暴露 SQL/堆栈；登入和注册错误也会收敛提示，避免枚举学号。文档和示例中不要写入真实学号、姓名、班级码、密码、令牌、签名密钥或服务器 IP。
• 兼容性：当前路径未版本化。客户端应对未知字段保持宽容，不要依赖字段顺序；新增字段属于兼容变更，删除或改义字段需要同步更新本文档。