# 注册登录对接文档

接口公共前缀为 `/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 或敏感数据密钥未正确配置 |