Files
2026-10-19 17:21:23 +08:00

148 lines
6.5 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 邮箱与图片验证码登录
用户端默认端口 `8991`。除 `GET /api/auth/captcha`、`POST /api/auth/login` 和跨域预检外,所有 `/api/**` 业务接口都需要 `Authorization: Bearer <token>`,包括组件详情、匹配、需求会话、私有图片和 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 '登录用户归属摘要,历史匿名归属保留至过期';
```