# 邮箱与图片验证码登录 用户端默认端口 `8991`。除 `GET /api/auth/captcha`、`POST /api/auth/login` 和跨域预检外,所有 `/api/**` 业务接口都需要 `Authorization: Bearer `,包括组件详情、匹配、需求会话、私有图片和 SSE。JSON 返回统一为 `{code, message, data, requestId}`。 此流程沿用参考项目:邮箱与图片验证码登录,首次自动注册;不发送邮件、不验证邮箱归属。`user_type` 不作为客户端可提交字段。用户端仅返回唯一 `userCode`,不暴露数据库主键。 ## 1. 接口 ### 获取验证码 `GET /api/auth/captcha`,无需登录,响应设置 `Cache-Control: no-store`。 ```json { "code": "OK", "message": "success", "data": { "captchaCode": "一次性验证码编码", "image": "data:image/png;base64,...", "expiresIn": 120 }, "requestId": "请求编号" } ``` 图片为 180×60 PNG,包含 5 位数字或大写字母。`image` 可直接作为验证码图片的 `src`。有效期默认 120 秒,答案忽略大小写和首尾空格。每次有效参数的登录提交都会消费对应验证码,答错后也必须重新获取。 ### 登录 `POST /api/auth/login`,`Content-Type: application/json`,无需登录。 ```json {"email":"user@example.com","captchaCode":"验证码编码","captchaAnswer":"ABCDE"} ``` 邮箱去除首尾空格、转小写后校验,最长 254 字符;验证码编码和答案必填,最长分别为 64、32 字符。成功示例: ```json { "code": "OK", "message": "success", "data": { "token": "登录凭证", "tokenType": "Bearer", "expiresIn": 86400, "user": { "userCode": "0123456789ABCDEF0123456789ABCDEF", "nickname": "用户_01234567", "email": "user@example.com" } }, "requestId": "请求编号" } ``` 首次登录创建 `ACTIVE / NORMAL` 用户,昵称为“用户_用户编码前8位”。同邮箱并发首次登录复用同一用户。用户编码创建后不可修改。 Token 是 32 字节安全随机值的无填充 Base64URL 编码,有效期默认 24 小时;访问不续期。同一用户可持有多个 Token。 ### 当前用户与退出 - `GET /api/users/me`:返回 `data={userCode,nickname,email}`。 - `POST /api/auth/logout`:撤销当前 Token,返回 `data=null`,其他登录态继续有效。再次使用已撤销 Token 返回 401。 以上接口均须携带 Bearer Token。用户被后台禁用后,登录返回 403,已有 Token 在下一次业务请求时被拒绝。 | HTTP 状态 | code | 处理方式 | | --- | --- | --- | | 400 | `CAPTCHA_INVALID` | 验证码错误、过期或已消费,重新获取图片 | | 401 | `UNAUTHORIZED` | 未登录、Token 无效或账号已不可用,重新登录 | | 403 | `ACCOUNT_DISABLED` | 用户已禁用,联系管理员 | | 422 | `INVALID_REQUEST` | 检查邮箱、必填字段、长度或未知字段 | | 503 | `DATABASE_UNAVAILABLE` | 数据库暂不可用,稍后重试 | | 503 | `USER_CODE_EXHAUSTED` | 用户编码分配重试失败,稍后重试 | ## 2. 前端调用与需求归属 ```javascript const challenge = (await (await fetch('/api/auth/captcha')).json()).data; // 将 challenge.image 展示给用户,answer 为用户输入的图片答案。 const response = await fetch('/api/auth/login', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ email, captchaCode: challenge.captchaCode, captchaAnswer: answer }) }); if (!response.ok) throw await response.json(); const { token } = (await response.json()).data; const current = await fetch('/api/users/me', { headers: { Authorization: `Bearer ${token}` } }); // 私有图片需要认证头,通过 Blob URL 展示,Token 不放在 URL 中。 const imageResponse = await fetch(previewUrl, { headers: { Authorization: `Bearer ${token}` } }); if (!imageResponse.ok) throw await imageResponse.json(); const objectUrl = URL.createObjectURL(await imageResponse.blob()); imageElement.src = objectUrl; // 图片不再使用时执行 URL.revokeObjectURL(objectUrl)。 ``` POST SSE 同样在 fetch 的 headers 中携带 `Authorization`,详见 [需求联调文档](robot-demand-api.md)。不再需要访客 Cookie 或 `credentials: 'include'`。 会话归属由服务端认证的 `userCode` 决定,存储为 `SHA-256("user:" + userCode)`。同一用户在不同设备登录后可通过原业务编码访问自己的会话;其他用户访问返回 404。客户端不传 `userId`、`userCode` 或归属摘要来指定所有者。 历史匿名 Cookie 不授予访问权,也不会触发会话认领。历史匿名数据保留至现有过期任务清理。 ## 3. 配置与运行 | 环境变量 | 默认值 | 说明 | | --- | --- | --- | | `APP_AUTH_CAPTCHA_TTL` | `PT2M` | 验证码有效期,至少 1 秒 | | `APP_AUTH_TOKEN_TTL` | `PT24H` | 登录态有效期,至少 1 秒 | | `APP_DEMAND_ALLOWED_ORIGINS` | 沿用各环境配置 | `/api/**` 跨域白名单,允许 Authorization 请求头 | 验证码和登录态分别使用最多 10000 条的 Caffeine 缓存。当前按单实例部署;重启、缓存容量淘汰或有效期结束后凭证失效。用户和会话数据持久化保留;多实例共享登录态需后续切换为共享存储。 用户端和[管理端](../../cadworld-adminapi/docs/auth-api.md)分别引入自己的安全模块,独立保存 Token 和验证码。后台用户管理使用邮箱,删除入口改为禁用账号;上传与审计使用真实登录管理员。 ## 4. 发布前手动执行的迁移 SQL 以下 SQL 基于提供的邮箱版 `sys_user`(索引名 `uk_sys_user_phone`,索引列为 `email`),仅执行一次;已有该字段或索引的环境先核对结构。应用不自动迁移,仓库 `.sql` 文件未修改。先执行 SQL,再发布用户端和管理端新代码。 ```sql ALTER TABLE `sys_user` ADD COLUMN `user_code` char(32) CHARACTER SET ascii COLLATE ascii_bin NULL COMMENT '用户唯一编码,对外使用且创建后不可修改' AFTER `id`; UPDATE `sys_user` SET `user_code` = UPPER(REPLACE(UUID(), '-', '')) WHERE `user_code` IS NULL; ALTER TABLE `sys_user` MODIFY COLUMN `user_code` char(32) CHARACTER SET ascii COLLATE ascii_bin NOT NULL COMMENT '用户唯一编码,对外使用且创建后不可修改', ADD UNIQUE KEY `uk_sys_user_code` (`user_code`), RENAME INDEX `uk_sys_user_phone` TO `uk_sys_user_email`; ALTER TABLE `robot_demand_conversation` MODIFY COLUMN `owner_hash` char(64) CHARACTER SET ascii COLLATE ascii_bin NOT NULL COMMENT '登录用户归属摘要,历史匿名归属保留至过期'; ```