344 lines
11 KiB
Markdown
344 lines
11 KiB
Markdown
# IM 个人/企业注册登录前后端对接说明
|
||
|
||
## 1. 目标
|
||
|
||
当前客户端没有独立的企业码进入页面，登录页和注册页由用户选择“个人用户”或“企业用户”。前端提交登录和注册时必须显式带类型，后端不能再通过企业码是否为空来推断个人/企业。
|
||
|
||
核心规则：
|
||
|
||
1. 前端新增字段 `registration_type`，类型为 int，取值只能是 `0` 或 `1`。
|
||
2. `registration_type=1` 时，后端按个人注册处理，内部租户使用 `default`，数据写入 `default` 租户业务库。
|
||
3. `registration_type=0` 时，前端必须提交企业码，后端必须校验企业存在、启用且允许注册。
|
||
4. 登录新增字段 `login_type`，类型为 int，取值同样是 `0` 企业、`1` 个人。
|
||
5. 企业登录或企业注册都不允许使用 `default`。
|
||
6. `default` 是系统保留的个人租户码，不允许作为企业码输入。
|
||
|
||
一句话规则：**注册类型由 `registration_type` 决定，登录类型由 `login_type` 决定；个人落 `default`，企业必须校验企业码。**
|
||
|
||
## 2. 前端注册字段
|
||
|
||
注册页提交发码和最终注册时都带同一组注册上下文字段：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `registration_type` | int | 是 | `0` 表示企业注册，`1` 表示个人注册 |
|
||
| `tenant_code` | string | 企业注册必填 | 企业码；个人注册不填或传空字符串 |
|
||
|
||
前端规则：
|
||
|
||
| `registration_type` | `tenant_code` | 后端处理 |
|
||
| --- | --- | --- |
|
||
| `1` | 空 | 允许提交，后端内部使用 `default` |
|
||
| `1` | 非空 | 后端拒绝，避免误入库 |
|
||
| `0` | 空 | 后端拒绝，提示请输入企业码 |
|
||
| `0` | `default`、`Default`、`DEFAULT` | 后端拒绝 |
|
||
| `0` | 其他值 | 后端在注册链路中校验 |
|
||
|
||
用户在企业注册模式输入 `default` 时，建议提示：
|
||
|
||
```text
|
||
default 是系统保留企业码。个人注册请选择个人用户，企业注册请输入企业提供的企业码。
|
||
```
|
||
|
||
## 3. 企业码校验
|
||
|
||
不新增单独的企业码校验接口，也不要求前端在注册前调用 `/v1/im/tenants/resolve`。
|
||
|
||
后端在注册发码和最终注册链路中校验：
|
||
|
||
1. `registration_type=1`
|
||
- 不要求企业码。
|
||
- 即使请求 Header 或内部路由使用 `default`，也属于服务端内部租户，不是用户输入企业码。
|
||
- 创建用户时写入 `default` 租户业务库。
|
||
|
||
2. `registration_type=0`
|
||
- `tenant_code` 必填。
|
||
- `tenant_code` 大小写不敏感等于 `default` 时拒绝。
|
||
- 查询企业是否存在、启用、允许注册。
|
||
- 通过后在对应企业租户业务库创建用户。
|
||
|
||
企业不存在、停用或不允许注册时，客户端统一提示：
|
||
|
||
```text
|
||
企业不存在或不可用
|
||
```
|
||
|
||
客户端不要区分不存在、停用、禁用注册等内部原因。
|
||
|
||
`/v1/im/tenants/resolve` 只保留给服务发现、品牌配置、历史企业入口等场景使用；当前注册页不依赖它完成主流程。
|
||
|
||
## 4. 前端登录字段
|
||
|
||
登录页提交 WebSocket `{login}` 时带登录上下文字段：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `login_type` | int | basic 登录必填 | `0` 表示企业登录，`1` 表示个人登录 |
|
||
| `tenant_code` | string | 企业登录必填 | 企业码；个人登录不填、传空字符串或内部传 `default` |
|
||
|
||
登录规则：
|
||
|
||
| `login_type` | `tenant_code` / `hi.tenant` | 后端处理 |
|
||
| --- | --- | --- |
|
||
| `1` | `default` | 个人登录，允许 |
|
||
| `1` | 非 `default` | 拒绝，避免个人登录误进企业租户 |
|
||
| `0` | 空 | 拒绝，提示请输入企业码 |
|
||
| `0` | `default`、`Default`、`DEFAULT` | 拒绝，统一提示“企业不存在或不可用” |
|
||
| `0` | 其他值 | 企业登录，后端按该租户认证 |
|
||
|
||
企业用户如果在企业入口输入 `default`，后端返回策略错误，错误参数为 `what=tenant_code`、`reason=TENANT_CODE_FORBIDDEN`；客户端统一展示：
|
||
|
||
```text
|
||
企业不存在或不可用
|
||
```
|
||
|
||
个人登录 `{login}` 示例：
|
||
|
||
```json
|
||
{
|
||
"login": {
|
||
"id": "login-1",
|
||
"scheme": "basic",
|
||
"login_type": 1,
|
||
"tenant_code": "",
|
||
"secret": "base64(account:password)"
|
||
}
|
||
}
|
||
```
|
||
|
||
企业登录 `{login}` 示例：
|
||
|
||
```json
|
||
{
|
||
"login": {
|
||
"id": "login-1",
|
||
"scheme": "basic",
|
||
"login_type": 0,
|
||
"tenant_code": "acme",
|
||
"secret": "base64(account:password)"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 5. 个人注册流程
|
||
|
||
个人注册必须显式提交 `registration_type=1`。
|
||
|
||
1. 用户选择个人注册。
|
||
2. 前端提交 `registration_type=1`，`tenant_code` 为空。
|
||
3. 注册发码、验证码校验、WebSocket `hi`、`acc` 注册链路使用服务端内部租户 `default`。
|
||
4. 服务端将用户创建到 `default` 租户对应的业务库。
|
||
|
||
发码示例：
|
||
|
||
```http
|
||
POST /v1/im/auth/verification-codes
|
||
X-MeetingIM-APIKey: <api_key>
|
||
X-IM-Schema: 1
|
||
X-Tenant-Code: default
|
||
X-Request-ID: <uuid>
|
||
```
|
||
|
||
```json
|
||
{
|
||
"scene": "register",
|
||
"registration_type": 1,
|
||
"tenant_code": "",
|
||
"phone": "19122421333"
|
||
}
|
||
```
|
||
|
||
WebSocket 握手示例：
|
||
|
||
```json
|
||
{
|
||
"hi": {
|
||
"id": "hi-1",
|
||
"ver": "0.25",
|
||
"ua": "ios/1.0.0",
|
||
"platf": "ios",
|
||
"lang": "zh-CN",
|
||
"tenant": "default"
|
||
}
|
||
}
|
||
```
|
||
|
||
最终注册 `{acc}` 示例：
|
||
|
||
```json
|
||
{
|
||
"acc": {
|
||
"id": "acc-1",
|
||
"user": "new",
|
||
"scheme": "basic",
|
||
"registration_type": 1,
|
||
"tenant_code": "",
|
||
"username": "henry",
|
||
"phone": "19122421333",
|
||
"secret": "base64(henry:password)",
|
||
"login": true,
|
||
"cred": [
|
||
{
|
||
"meth": "tel",
|
||
"val": "19122421333",
|
||
"resp": "verification_token",
|
||
"params": {"challenge_id": "challenge-id"}
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
## 6. 企业注册流程
|
||
|
||
企业注册必须显式提交 `registration_type=0`。
|
||
|
||
1. 用户选择企业注册。
|
||
2. 用户填写企业码，例如 `acme`。
|
||
3. 前端直接提交用户输入的企业码，不做企业码存在性或保留字拦截。
|
||
4. 获取验证码、提交注册时都带 `registration_type=0` 和 `tenant_code=acme`。
|
||
5. 后端在注册链路中校验企业是否存在且可用。
|
||
6. 校验通过后，服务端在该企业租户业务库中创建用户；校验不通过时返回“企业不存在或不可用”。
|
||
|
||
注册发码请求：
|
||
|
||
```http
|
||
POST /v1/im/auth/verification-codes
|
||
X-MeetingIM-APIKey: <api_key>
|
||
X-IM-Schema: 1
|
||
X-Tenant-Code: acme
|
||
X-Request-ID: <uuid>
|
||
```
|
||
|
||
```json
|
||
{
|
||
"scene": "register",
|
||
"registration_type": 0,
|
||
"tenant_code": "acme",
|
||
"phone": "19122421333"
|
||
}
|
||
```
|
||
|
||
WebSocket `hi`：
|
||
|
||
```json
|
||
{
|
||
"hi": {
|
||
"id": "hi-1",
|
||
"ver": "0.25",
|
||
"ua": "android/1.0.0",
|
||
"platf": "android",
|
||
"lang": "zh-CN",
|
||
"tenant": "acme"
|
||
}
|
||
}
|
||
```
|
||
|
||
最终注册 `{acc}` 示例：
|
||
|
||
```json
|
||
{
|
||
"acc": {
|
||
"id": "acc-1",
|
||
"user": "new",
|
||
"scheme": "basic",
|
||
"registration_type": 0,
|
||
"tenant_code": "acme",
|
||
"username": "henry",
|
||
"phone": "19122421333",
|
||
"secret": "base64(henry:password)",
|
||
"login": true,
|
||
"cred": [
|
||
{
|
||
"meth": "tel",
|
||
"val": "19122421333",
|
||
"resp": "verification_token",
|
||
"params": {"challenge_id": "challenge-id"}
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
## 7. 后端校验规则
|
||
|
||
后端负责注册链路的最终校验，前端不做企业码拦截。
|
||
|
||
1. `registration_type` 缺失或不是 `0|1`
|
||
- 拒绝注册。
|
||
- 返回 `MALFORMED_REQUEST`，提示客户端升级或检查参数。
|
||
|
||
2. `registration_type=1`
|
||
- 不从空企业码推断，而是由该字段明确进入个人注册。
|
||
- 内部租户码设置为 `default`。
|
||
- 拒绝用户提交的非空 `tenant_code`，避免误入库。
|
||
- 注册时写入 `default` 租户业务库。
|
||
|
||
3. `registration_type=0`
|
||
- `tenant_code` 必填。
|
||
- 先 trim 首尾空格。
|
||
- 如果大小写不敏感等于 `default`，拒绝注册。
|
||
- 否则查询租户是否存在、是否启用、是否允许注册。
|
||
- 校验通过后绑定对应租户。
|
||
|
||
建议错误：
|
||
|
||
```json
|
||
{
|
||
"code": 30000,
|
||
"reason": "MALFORMED_REQUEST",
|
||
"message": "invalid registration_type or tenant_code"
|
||
}
|
||
```
|
||
|
||
企业不可用时，客户端展示：
|
||
|
||
```text
|
||
企业不存在或不可用
|
||
```
|
||
|
||
## 8. 缓存和本地数据隔离
|
||
|
||
客户端本地缓存、Token、会话、草稿、附件缓存必须继续按 `tenant_code + user_id` 隔离。
|
||
|
||
个人注册用户登录后，缓存键中的 `tenant_code` 使用 `default`。企业用户登录后，使用对应企业码。切换个人/企业身份时必须清理当前连接并重新 `hi`，不能在同一个 WebSocket 中切换租户。
|
||
|
||
## 9. 验收用例
|
||
|
||
| 场景 | 预期 |
|
||
| --- | --- |
|
||
| `login_type=1`，`hi.tenant=default` | 个人登录成功进入 `default` 租户认证 |
|
||
| `login_type=1`，`hi.tenant=acme` | 拒绝登录 |
|
||
| `login_type=0`，企业码空 | 拒绝登录，提示请输入企业码 |
|
||
| `login_type=0`，企业码为 `default` | 拒绝登录，提示企业不存在或不可用 |
|
||
| `login_type=0`，企业码有效 | 在该企业租户认证 |
|
||
| `registration_type=1`，企业码空，手机号注册 | 成功进入 `default` 租户注册链路 |
|
||
| `registration_type` 缺失 | 拒绝注册，返回参数错误 |
|
||
| `registration_type=1`，企业码非空 | 拒绝或忽略，建议拒绝，避免误入库 |
|
||
| `registration_type=0`，企业码空 | 拒绝注册，提示请输入企业码 |
|
||
| `registration_type=0`，企业码为 `default` | 拒绝注册 |
|
||
| `registration_type=0`，企业码不存在 | 发码或注册失败，提示企业不存在或不可用 |
|
||
| `registration_type=0`，企业码已停用 | 统一提示企业不存在或不可用 |
|
||
| `registration_type=0`，企业码有效 | 注册写入该企业租户库 |
|
||
| 个人用户注册成功后登录 | `tenant_code=default`，可正常登录、收发消息 |
|
||
|
||
## 10. 对客户端的明确要求
|
||
|
||
1. 登录页和注册页都必须明确区分个人和企业。
|
||
2. basic 登录必须提交 `login_type`。
|
||
3. 发码和最终注册都必须提交 `registration_type`。
|
||
4. 个人登录/注册提交类型 `1`，不要让用户输入或看到 `default`。
|
||
5. 企业登录/注册提交类型 `0` 和用户输入的企业码。
|
||
6. 企业用户手动输入 `default` 也直接提交，由后端返回错误，客户端按后端错误展示提示。
|
||
7. 不需要为了注册主流程调用 `/v1/im/tenants/resolve`。
|
||
|
||
## 11. 对后端的明确要求
|
||
|
||
1. basic 登录链路必须以 `login_type` 作为个人/企业登录的判定来源。
|
||
2. 注册链路必须以 `registration_type` 作为个人/企业注册的判定来源。
|
||
3. 不允许仅根据企业码是否为空推断个人注册或个人登录。
|
||
4. 登录、注册、发码、验证码校验、WebSocket `hi/login/acc` 链路保持同一租户上下文。
|
||
5. 显式企业码 `default` 必须拒绝，防止用户绕过企业码校验。
|
||
6. 企业登录/注册的企业码必须校验存在、启用、允许登录/注册。
|
||
7. 日志中要能看出来源是 `personal_default` 还是 `enterprise_code`，方便排查误入库问题。
|