102 lines
2.6 KiB
Markdown
102 lines
2.6 KiB
Markdown
# 注册登录对接文档
|
|
|
|
接口公共前缀为 `/v1`，旧的应用名路径前缀不再提供兼容路由。
|
|
|
|
## 1 数据模型
|
|
|
|
账户以 `olons_admin.hg_app_member` 为主档：
|
|
|
|
- 手机号完整写入 `mobile`，同一租户内唯一，不再保存加密、哈希或脱敏辅助列。
|
|
- 登录密码使用 bcrypt 写入 `password_hash`。
|
|
- 推荐码通过上级会员的 `invite_code` 建立 `parent_id`、`level` 和 `tree`。
|
|
- 注册事务同时创建 `hg_app_member_profile` 和 CNY `hg_wallet_account`。
|
|
|
|
## 2 公共 Header
|
|
|
|
```http
|
|
X-API-Key: <api key>
|
|
X-Request-ID: <request id>
|
|
X-Device-ID: <optional device id>
|
|
```
|
|
|
|
## 3 注册
|
|
|
|
```http
|
|
POST /v1/auth/register
|
|
Content-Type: application/json
|
|
```
|
|
|
|
```json
|
|
{
|
|
"username": "alice01",
|
|
"phone": "13800138000",
|
|
"password": "Secret123",
|
|
"referral_code": "ABCD2345",
|
|
"privacy_accepted": true
|
|
}
|
|
```
|
|
|
|
`referral_code` 可选；传入时必须匹配当前租户下正常会员的 `invite_code`。
|
|
|
|
## 4 登录
|
|
|
|
```http
|
|
POST /v1/auth/login
|
|
Content-Type: application/json
|
|
```
|
|
|
|
```json
|
|
{
|
|
"phone": "13800138000",
|
|
"password": "Secret123"
|
|
}
|
|
```
|
|
|
|
界面的“记住密码”由客户端安全存储，不作为接口字段上传。
|
|
|
|
## 5 成功响应
|
|
|
|
```json
|
|
{
|
|
"code": 0,
|
|
"data": {
|
|
"member_id": 9,
|
|
"member_no": "MABCDEFGHIJKLMNOPQRST",
|
|
"username": "alice01",
|
|
"phone": "13800138000",
|
|
"invite_code": "EFGH6789",
|
|
"token": "...",
|
|
"token_type": "Bearer",
|
|
"expires_at": "2026-10-23T10:00:00Z"
|
|
},
|
|
"request_id": "uuid",
|
|
"server_time": "2026-10-09T10:00:00Z"
|
|
}
|
|
```
|
|
|
|
Token 是 32 字节随机会话凭证的 Base64URL 编码。Redis 只使用 Token SHA-256 摘要作为 Key，不存储原始 Token。
|
|
|
|
## 6 退出登录
|
|
|
|
```http
|
|
POST /v1/auth/logout
|
|
Authorization: Bearer <token>
|
|
```
|
|
|
|
退出成功后删除当前 Redis 会话，`data` 为 `null`。缺少、格式错误或已失效的 Token 返回 HTTP 401 和 `AUTH_REQUIRED`。
|
|
|
|
## 7 错误 reason
|
|
|
|
| reason | HTTP | 说明 |
|
|
| --- | --- | --- |
|
|
| `USERNAME_INVALID_FORMAT` | 400 | 账户名格式错误 |
|
|
| `PHONE_INVALID_FORMAT` | 400 | 手机号格式错误 |
|
|
| `PASSWORD_INVALID_FORMAT` | 400 | 密码格式错误 |
|
|
| `REFERRAL_CODE_INVALID` | 400 | 推荐码无效 |
|
|
| `PRIVACY_POLICY_NOT_ACCEPTED` | 400 | 未同意隐私政策 |
|
|
| `ACCOUNT_ALREADY_REGISTERED` | 409 | 账户名或手机号已注册 |
|
|
| `INVALID_CREDENTIALS` | 401 | 手机号或密码错误 |
|
|
| `AUTH_REQUIRED` | 401 | 缺少或无效的登录会话 |
|
|
| `RATE_LIMITED` | 429 | 15 分钟内登录失败次数过多 |
|
|
| `SERVICE_UNAVAILABLE` | 503 | Redis 或敏感数据密钥未正确配置 |
|