注册登录对接文档

接口公共前缀为 /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

X-API-Key: <api key>
X-Request-ID: <request id>
X-Device-ID: <optional device id>

3 注册

POST /v1/auth/register
Content-Type: application/json

{
  "username": "alice01",
  "phone": "13800138000",
  "password": "Secret123",
  "referral_code": "ABCD2345",
  "privacy_accepted": true
}

referral_code 可选；传入时必须匹配当前租户下正常会员的 invite_code。

4 登录

POST /v1/auth/login
Content-Type: application/json

{
  "phone": "13800138000",
  "password": "Secret123"
}

界面的“记住密码”由客户端安全存储，不作为接口字段上传。

5 成功响应

{
  "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 退出登录

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 或敏感数据密钥未正确配置

2.6 KiB Raw Blame History