feat: add tenant entry registration APIs
This commit is contained in:
richjohnrambo
@@ -0,0 +1,66 @@
|
||||
-- IM 企业入口注册与问题反馈 SQL
|
||||
-- 更新时间：2026-08-24
|
||||
--
|
||||
-- 执行范围：hotgo 控制库。
|
||||
-- 说明：未登录企业注册、入口问题反馈发生在租户绑定前，因此公共附件和申请单不放入租户业务库。
|
||||
-- 文件对象通过 IM 服务端当前 media handler 存储；生产环境应配置 media.use_handler=oss。
|
||||
|
||||
USE hotgo;
|
||||
|
||||
CREATE TABLE IF NOT EXISTS im_public_uploads (
|
||||
id BIGINT NOT NULL AUTO_INCREMENT,
|
||||
file_id VARCHAR(64) NOT NULL,
|
||||
purpose VARCHAR(64) NOT NULL,
|
||||
mime_type VARCHAR(128) NOT NULL DEFAULT '',
|
||||
size BIGINT NOT NULL DEFAULT 0,
|
||||
etag VARCHAR(128) NOT NULL DEFAULT '',
|
||||
location VARCHAR(2048) NOT NULL DEFAULT '',
|
||||
expires_at DATETIME(3),
|
||||
created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
|
||||
uploaded_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
|
||||
PRIMARY KEY(id),
|
||||
UNIQUE INDEX uk_im_public_uploads_file(file_id),
|
||||
INDEX idx_im_public_uploads_purpose(purpose, created_at),
|
||||
INDEX idx_im_public_uploads_expires(expires_at)
|
||||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci;
|
||||
|
||||
CREATE TABLE IF NOT EXISTS im_tenant_applications (
|
||||
id BIGINT NOT NULL AUTO_INCREMENT,
|
||||
application_id VARCHAR(64) NOT NULL,
|
||||
credit_code VARCHAR(18) NOT NULL,
|
||||
enterprise_email VARCHAR(255) NOT NULL DEFAULT '',
|
||||
license_file_id VARCHAR(64) NOT NULL DEFAULT '',
|
||||
tenant_code_hint VARCHAR(64) NOT NULL DEFAULT '',
|
||||
client_context JSON,
|
||||
idempotency_key VARCHAR(128) NOT NULL,
|
||||
status VARCHAR(32) NOT NULL DEFAULT 'received',
|
||||
estimated_review_hour INT NOT NULL DEFAULT 24,
|
||||
submitted_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
|
||||
created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
|
||||
updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3),
|
||||
PRIMARY KEY(id),
|
||||
UNIQUE INDEX uk_im_tenant_applications_app(application_id),
|
||||
UNIQUE INDEX uk_im_tenant_applications_idempotency(idempotency_key),
|
||||
INDEX idx_im_tenant_applications_credit(credit_code),
|
||||
INDEX idx_im_tenant_applications_status(status, id)
|
||||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci;
|
||||
|
||||
CREATE TABLE IF NOT EXISTS im_tenant_entry_feedbacks (
|
||||
id BIGINT NOT NULL AUTO_INCREMENT,
|
||||
feedback_id VARCHAR(64) NOT NULL,
|
||||
description TEXT NOT NULL,
|
||||
contact VARCHAR(255) NOT NULL DEFAULT '',
|
||||
tenant_code_hint VARCHAR(64) NOT NULL DEFAULT '',
|
||||
screenshot_file_ids JSON,
|
||||
client_context JSON,
|
||||
idempotency_key VARCHAR(128) NOT NULL,
|
||||
status VARCHAR(32) NOT NULL DEFAULT 'received',
|
||||
submitted_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
|
||||
created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
|
||||
updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3),
|
||||
PRIMARY KEY(id),
|
||||
UNIQUE INDEX uk_im_tenant_entry_feedbacks_feedback(feedback_id),
|
||||
UNIQUE INDEX uk_im_tenant_entry_feedbacks_idempotency(idempotency_key),
|
||||
INDEX idx_im_tenant_entry_feedbacks_status(status, id),
|
||||
INDEX idx_im_tenant_entry_feedbacks_hint(tenant_code_hint, id)
|
||||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci;
|
||||
@@ -463,6 +463,109 @@ X-Tinode-APIKey: <预置的普通 API Key>
|
||||
}
|
||||
```
|
||||
|
||||
### 1.1.1 企业注册-登录入口.png
|
||||
|
||||
<img src="images/企业注册-登录入口.png" alt="企业注册-登录入口" width="360">
|
||||
|
||||
**状态：已实现。**
|
||||
|
||||
- 页面入口：企业码登录页右上角展示“企业注册”，底部展示“遇到问题？”。两个入口均为未登录入口，但必须使用客户端预置的普通 API Key，不需要用户 Token。
|
||||
- 点击“企业注册”：进入 1.1.2 企业资料提交流程。客户端保留当前已输入的 `tenant_code` 作为可选线索，但不得把它当成已解析企业身份。
|
||||
- 点击“遇到问题？”：进入 1.1.4 问题反馈页。若用户已输入企业码，提交反馈时带 `tenant_code_hint`；未输入时可为空。
|
||||
- 埋点和日志：可记录入口点击事件，但不得记录 API Key、完整联系方式、证照图片 URL 或上传文件真实地址。
|
||||
- 入口展示：入口文案必须避开系统状态栏、安全区域和键盘遮挡；网络不可用时仍允许进入填写页，提交时再提示网络错误。
|
||||
|
||||
### 1.1.2 企业注册-填写注册信息.png
|
||||
|
||||
<img src="images/企业注册-填写注册信息.png" alt="企业注册-填写注册信息" width="360">
|
||||
|
||||
**状态：已实现。**
|
||||
|
||||
- 页面步骤：展示“填写企业信息、确定信息、提交审核”三步，当前处于第 1 步。提交前客户端在本页完成格式校验，服务端仍做最终校验。
|
||||
- 必填字段：`credit_code` 18 位统一社会信用代码，客户端仅去掉首尾空格并转大写展示；提交值必须匹配 `^[0-9A-Z]{18}$`。不得提交中文、空格或短码。
|
||||
- 可选字段：`license_file_id` 营业执照图片文件 ID，`enterprise_email` 企业邮箱。邮箱用于接收审核结果和后续通知，填写时必须符合邮箱格式。
|
||||
- 扫描识别：扫码或 OCR 只能作为填充辅助，提交前仍以输入框中的 `credit_code` 为准；识别失败不阻塞手动填写。
|
||||
- 图片上传：营业执照先调用公开用途受限上传接口，`purpose=enterprise_license`，支持 `jpg/png/webp/pdf`，单文件不超过 10MB。服务端通过当前 media handler 存储对象，生产环境必须配置 `oss` handler；上传成功返回 `file_id` 后再提交申请；未上传营业执照时 `license_file_id` 可为空。
|
||||
- 提交接口：`POST /v1/im/tenant-applications`，未登录可调用，必须带 `X-Tinode-APIKey`、`X-IM-Schema: 1`、`X-Request-ID` 和 `Idempotency-Key`。
|
||||
- 请求体：
|
||||
|
||||
```json
|
||||
{
|
||||
"credit_code": "91310000MA1K000000",
|
||||
"enterprise_email": "admin@example.com",
|
||||
"license_file_id": "file_01K...",
|
||||
"tenant_code_hint": "acme",
|
||||
"client_context": {
|
||||
"platform": "android",
|
||||
"app_version": "1.0.0",
|
||||
"device_model": "Pixel 8"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- 成功响应：服务端创建企业注册申请单，状态为 `received` 或 `pending_review`。客户端进入 1.1.3，不得重复提交同一个幂等键。
|
||||
|
||||
```json
|
||||
{
|
||||
"application_id": "entapp_01K...",
|
||||
"status": "received",
|
||||
"estimated_review_hours": 24,
|
||||
"submitted_at": "2026-08-24T08:30:15.123Z"
|
||||
}
|
||||
```
|
||||
|
||||
- 失败处理：`INVALID_CREDIT_CODE` 显示统一社会信用代码格式错误；`INVALID_EMAIL` 定位邮箱输入；`FILE_UNAVAILABLE` 允许重新上传；`APPLICATION_DUPLICATED` 提示已有申请正在审核；`RATE_LIMITED` 按服务端退避时间禁用提交按钮。
|
||||
|
||||
### 1.1.3 企业注册-提交成功提示.png
|
||||
|
||||
<img src="images/企业注册-提交成功提示.png" alt="企业注册-提交成功提示" width="360">
|
||||
|
||||
**状态：已实现。**
|
||||
|
||||
- 触发条件：1.1.2 提交接口返回成功后，在当前页展示 Toast：“提交成功，我们会尽快联系你”。
|
||||
- 状态保存：客户端保存 `application_id,status,submitted_at,estimated_review_hours` 到本地短期缓存，用于返回页面时展示“已提交”状态。该缓存不代表审核结果，最终状态以服务端和邮件/通知为准。
|
||||
- 防重复：提交成功后禁用提交按钮；用户返回后再次进入企业注册页，可显示已提交提示并允许重新填写新申请，但必须使用新的 `Idempotency-Key`。
|
||||
- 审核通知：审核结果默认通过 `enterprise_email` 触达；如果后续后台接入站内通知或短信，客户端只按服务端下发的公开状态展示，不自行推断审核通过。
|
||||
- 文案规则：页面底部审核时长应使用服务端返回的 `estimated_review_hours` 或后台配置，不写死。
|
||||
|
||||
### 1.1.4 企业注册-问题反馈.png
|
||||
|
||||
<img src="images/企业注册-问题反馈.png" alt="企业注册-问题反馈" width="360">
|
||||
|
||||
**状态：已实现。**
|
||||
|
||||
- 使用场景：企业码不可用、企业注册资料提交异常、审核通知未收到、登录入口无法进入等未登录阶段问题。
|
||||
- 输入字段：`description` 必填，长度 10～1000 字符；`contact` 可选，用于客服回访；`tenant_code_hint` 可选，来自用户输入；`screenshot_file_ids` 最多 9 个。
|
||||
- 截图上传：截图先调用公开用途受限上传接口，`purpose=tenant_entry_feedback`，支持 `jpg/png/webp`，单张不超过 10MB。服务端通过当前 media handler 存储对象，生产环境必须配置 `oss` handler；上传失败时允许单张重试或删除。
|
||||
- 提交接口：`POST /v1/im/tenant-entry-feedback`，未登录可调用，必须带 `X-Tinode-APIKey`、`X-IM-Schema: 1`、`X-Request-ID` 和 `Idempotency-Key`。
|
||||
- 请求体：
|
||||
|
||||
```json
|
||||
{
|
||||
"description": "企业码 acme 提示不可用，无法进入企业。",
|
||||
"contact": "user@example.com",
|
||||
"tenant_code_hint": "acme",
|
||||
"screenshot_file_ids": ["file_01K..."],
|
||||
"client_context": {
|
||||
"platform": "ios",
|
||||
"app_version": "1.0.0",
|
||||
"network": "wifi"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- 成功响应：客户端展示“已收到反馈，我们会尽快处理”，并清空草稿和已提交截图引用。
|
||||
|
||||
```json
|
||||
{
|
||||
"feedback_id": "entryfb_01K...",
|
||||
"status": "received",
|
||||
"submitted_at": "2026-08-24T08:35:15.123Z"
|
||||
}
|
||||
```
|
||||
|
||||
- 失败处理：`DESCRIPTION_REQUIRED` 或 `DESCRIPTION_TOO_LONG` 定位描述框；`TOO_MANY_FILES` 提示最多 9 张；`FILE_UNAVAILABLE` 提示重新上传失效图片；`RATE_LIMITED` 禁用提交并展示稍后重试。
|
||||
|
||||
### 1.2 登录页面.png
|
||||
|
||||
<img src="images/登录页面.png" alt="登录页面" width="360">
|
||||
@@ -642,6 +745,9 @@ X-Tinode-APIKey: <预置的普通 API Key>
|
||||
| 接口 | 输入示例 | 成功 `data` 示例 |
|
||||
| --- | --- | --- |
|
||||
| `POST /v1/im/tenants/resolve` | Header `X-Tenant-Code: default`；Body `{"tenant_code":"default","platform":"ios","app_version":"1.0.0"}` | `{"tenant":{"code":"default","name":"Default Tenant","tenant_desc":null,"branding":{}},"endpoints":{"websocket":"wss://api.118im.com/v0/channels","api":"https://api.118im.com/v1/im","file":"https://api.118im.com/v0/file"},"auth_methods":["password","sms"],"password_policy":{"min_length":8,"max_length":64},"app_update":{"type":"none"}}` |
|
||||
| `POST /v1/im/public/uploads` 企业注册/反馈附件上传 | Multipart `purpose=enterprise_license\|tenant_entry_feedback`、`file=@license.png` | `{"file_id":"file_01K...","purpose":"enterprise_license","mime_type":"image/png","size":1024000,"expires_at":"2026-08-25T08:30:15Z"}` |
|
||||
| `POST /v1/im/tenant-applications` 企业注册申请 | `{"credit_code":"91310000MA1K000000","enterprise_email":"admin@example.com","license_file_id":"file_01K...","tenant_code_hint":"acme","client_context":{"platform":"android","app_version":"1.0.0"}}` | `{"application_id":"entapp_01K...","status":"received","estimated_review_hours":24,"submitted_at":"2026-08-24T08:30:15.123Z"}` |
|
||||
| `POST /v1/im/tenant-entry-feedback` 企业入口问题反馈 | `{"description":"企业码 acme 提示不可用，无法进入企业。","contact":"user@example.com","tenant_code_hint":"acme","screenshot_file_ids":["file_01K..."],"client_context":{"platform":"ios","app_version":"1.0.0"}}` | `{"feedback_id":"entryfb_01K...","status":"received","submitted_at":"2026-08-24T08:35:15.123Z"}` |
|
||||
| `POST /v1/im/auth/verification-codes` 注册发码 | `{"scene":"register","phone":"15500000000"}` | `{"challenge_id":"chg_123","phone_mask":"+861****000","expires_in_seconds":300,"resend_after_seconds":60}` |
|
||||
| `POST /v1/im/auth/verification-codes/{challenge_id}/verify` | `{"code":"123456"}` | `{"verification_token":"verify_token_123","expires_in_seconds":300}` |
|
||||
| `POST /v1/im/auth/verification-codes` 找回密码发码 | `{"scene":"reset_password","phone":"15500000000"}` | `{"challenge_id":"chg_reset_123","phone_mask":"+861****000","expires_in_seconds":300,"resend_after_seconds":60}` |
|
||||
|
||||
Reference in New Issue
Block a user