feat: migrate workbench services

2026-10-10 23:34:06 +08:00
parent c13fb72849
commit 81e3cf1d03
88 changed files with 7358 additions and 15333 deletions
@@ -0,0 +1,101 @@
+# 注册登录对接文档
+
+接口公共前缀为 `/v1`，旧的应用名路径前缀不再提供兼容路由。
+
+## 1 数据模型
+
+账户以 `olons_admin.hg_app_member` 为主档：
+
+- 手机号写入 `mobile_cipher`、`mobile_hash` 和 `mobile_mask`。
+- 登录密码使用 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_mask": "138****8000",
+    "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 或敏感数据密钥未正确配置 |