148 lines
6.5 KiB
Markdown
148 lines
6.5 KiB
Markdown
# 邮箱与图片验证码登录
|
||
|
||
用户端默认端口 `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 '登录用户归属摘要,历史匿名归属保留至过期';
|
||
```
|