777 lines
27 KiB
Markdown
777 lines
27 KiB
Markdown
# User ID Technical Design
|
||
|
||
本文档定义数值型用户主键、默认短号、临时靓号的职责边界、数据库模型、跨服务通信规则和修改流程。核心原则：`user_id` 是唯一用户主键，后端和客户端响应都使用它；`display_user_id` 只做展示、搜索、登录名和运营入口。
|
||
|
||
## Terminology
|
||
|
||
| Field | Meaning | Mutable | Unique | Used By Internal Services |
|
||
| --- | --- | --- | --- | --- |
|
||
| `user_id` | 数值型用户 ID，服务间主关联和客户端响应统一使用 | No | Yes | Yes |
|
||
| `default_display_user_id` | 用户本身的默认短号 | Yes by explicit change | Yes while owned | No |
|
||
| `current_display_user_id` | 当前对外展示、搜索、登录的短号 | Yes | Yes while effective | No |
|
||
| `pretty_display_user_id` | 用户申请的临时靓号 | Yes by lease | Yes while leased | No |
|
||
| `display_user_id` | API 中返回的当前展示号，等同 `current_display_user_id` | Yes | Yes while effective | No |
|
||
| `display_user_id_kind` | 当前展示号来源，`default` 或 `pretty` | Yes | No | No |
|
||
| `display_user_id_expires_at_ms` | 当前靓号过期时间；默认短号为空 | Yes | No | No |
|
||
|
||
示例：
|
||
|
||
```text
|
||
user_id: 918274650129384448
|
||
default_display_user_id: 163000
|
||
current_display_user_id: 888888
|
||
display_user_id_kind: pretty
|
||
display_user_id_expires_at_ms: 1777000000000
|
||
```
|
||
|
||
`user_id` 是内部关系主键，也可以作为接口响应中的用户 ID。`default_display_user_id` 是用户本身的号。临时靓号有效期内会覆盖当前展示号；过期后必须恢复到 `default_display_user_id`。
|
||
|
||
所有展示号唯一性都限定在 `app_code` 内。不同 App 可以使用同一个 `display_user_id`，但同一个 App 内只能有一个当前有效归属。
|
||
|
||
## Design Principles
|
||
|
||
1. HTTP、客户端 JSON 和 JWT claims 中的 `user_id` 一律返回数值型用户 ID 的字符串形式。
|
||
2. 跨服务通信一律传数值型 `user_id`。
|
||
3. 数据库主关联一律存数值型 `user_id`，并用 `app_code` 做租户作用域。
|
||
4. outbox、审计、账单、房间状态、IM session、活动记录一律存数值型 `user_id`。
|
||
5. `display_user_id` 只允许出现在展示、搜索、分享、登录名、客服查询和运营配置入口。
|
||
6. 任何通过 `display_user_id` 发起的请求，都必须先在 `user-service` 解析成内部 `user_id`，后续链路只传内部 `user_id`。
|
||
7. `display_user_id` 可修改，所以不能作为幂等键、外键、账务主体或事件主体。
|
||
8. 临时靓号不能修改 `user_id`，也不能删除或转移用户的默认短号。
|
||
9. 当前展示号的真实来源必须可解释：默认短号来自永久归属，临时靓号来自有效租约。
|
||
10. `ResolveDisplayUserID`、密码登录和用户资料查询都必须先处理过期靓号，再返回当前有效短号。
|
||
11. 靓号过期恢复必须事务化，不能只靠缓存 TTL。
|
||
|
||
## Ownership
|
||
|
||
`user-service` 是 `user_id` 和 `display_user_id` 的唯一 owner。
|
||
|
||
| Capability | Owner | Rule |
|
||
| --- | --- | --- |
|
||
| 生成 `user_id` | `user-service` | 注册或三方首次登录时生成 |
|
||
| 分配默认短号 | `user-service` | 新用户创建时按 App 序列分配，首号 `163000` |
|
||
| 修改默认短号 | `user-service` | 事务内检查唯一性和冷却期 |
|
||
| 申请临时靓号 | `user-service` | 创建靓号租约并覆盖当前展示号 |
|
||
| 过期临时靓号 | `user-service` | 恢复当前展示号为默认短号 |
|
||
| 解析 `display_user_id` | `user-service` | 只返回当前有效归属 |
|
||
| 房间状态 | `room-service` | 只保存 `user_id` |
|
||
| 钱包账务 | `wallet-service` | 只保存 `user_id` |
|
||
| IM 连接 | 腾讯云 IM | identifier 使用内部长 `user_id` 的十进制字符串 |
|
||
| 活动结算 | `activity-service` | 只保存 `user_id` |
|
||
|
||
其他服务不能自己缓存长期 `display_user_id -> user_id` 绑定作为事实来源。短期缓存必须有 TTL，并允许 user-service 失效或回源。
|
||
|
||
## Role Identity Facts
|
||
|
||
用户 ID 和短号不表达业务身份。主播、Agency、BD、BD Leader、coin_seller 都是挂在同一个 `user_id` 下的业务事实，不应该把身份塞进 `display_user_id` 或 JWT 文案里。
|
||
|
||
| Identity | Table | Can Coexist | Account Boundary |
|
||
| --- | --- | --- | --- |
|
||
| `host` | `host_profiles` | 可和 BD、BD Leader、coin_seller 并存 | 主播收益余额在 `wallet-service` |
|
||
| `agency owner` | `agencies` + owner membership | 可和 BD、BD Leader、coin_seller 并存 | Agency 工资结算后入钱包 |
|
||
| `bd` | `bd_profiles(role='bd')` | 可和 host、Agency、coin_seller 并存 | BD 工资结算后入钱包 |
|
||
| `bd_leader` | `bd_profiles(role='bd_leader')` | 可和 host、Agency、coin_seller 并存 | BD Leader 工资结算后入钱包 |
|
||
| `coin_seller` | `coin_seller_profiles` | 可和 Agency、BD、BD Leader 并存 | 币商专用资产 `COIN_SELLER_COIN` |
|
||
|
||
`coin_seller` 是币商身份，拥有独立于玩家普通 `COIN` 的币商金币账户。币商给玩家转金币时，内部链路只能使用数值型 `user_id`：gateway 校验当前用户是 active `coin_seller`，wallet-service 扣减该用户 `COIN_SELLER_COIN` 并给目标用户增加普通 `COIN`。`display_user_id` 只可用于后台或客户端搜索目标用户，解析后必须转换成内部 `user_id` 再进入账务。
|
||
|
||
## Database Model
|
||
|
||
### `users`
|
||
|
||
用户主表保存不可变主键、默认短号、当前展示号快照，以及注册资料和来源快照。
|
||
|
||
```sql
|
||
CREATE TABLE users (
|
||
app_code VARCHAR(32) NOT NULL DEFAULT 'lalu',
|
||
user_id BIGINT NOT NULL PRIMARY KEY,
|
||
default_display_user_id VARCHAR(32) NOT NULL,
|
||
current_display_user_id VARCHAR(32) NOT NULL,
|
||
current_display_user_id_kind VARCHAR(32) NOT NULL,
|
||
current_display_user_id_expires_at_ms BIGINT NULL,
|
||
username VARCHAR(64) NULL,
|
||
gender VARCHAR(32) NULL,
|
||
country VARCHAR(64) NULL,
|
||
invite_code VARCHAR(64) NULL,
|
||
register_ip VARCHAR(64) NULL,
|
||
register_user_agent VARCHAR(512) NULL,
|
||
country_by_ip VARCHAR(64) NULL,
|
||
register_device_id VARCHAR(128) NULL,
|
||
register_device VARCHAR(128) NULL,
|
||
os_version VARCHAR(64) NULL,
|
||
avatar VARCHAR(512) NULL,
|
||
birth_date DATE NULL,
|
||
app_version VARCHAR(64) NULL,
|
||
build_number VARCHAR(64) NULL,
|
||
source VARCHAR(64) NULL,
|
||
install_channel VARCHAR(64) NULL,
|
||
campaign VARCHAR(128) NULL,
|
||
platform VARCHAR(16) NULL,
|
||
language VARCHAR(32) NULL,
|
||
timezone VARCHAR(64) NULL,
|
||
status VARCHAR(32) NOT NULL,
|
||
created_at_ms BIGINT NOT NULL,
|
||
updated_at_ms BIGINT NOT NULL,
|
||
UNIQUE KEY uk_users_default_display_user_id (app_code, default_display_user_id),
|
||
UNIQUE KEY uk_users_current_display_user_id (app_code, current_display_user_id)
|
||
);
|
||
```
|
||
|
||
`current_display_user_id` 是读优化快照，不是变更历史来源。它必须和 `user_display_user_ids` 的当前有效记录保持一致。
|
||
|
||
快照规则：
|
||
|
||
| Case | `current_display_user_id` | `current_display_user_id_kind` | `current_display_user_id_expires_at_ms` |
|
||
| --- | --- | --- | --- |
|
||
| 没有靓号 | `default_display_user_id` | `default` | `NULL` |
|
||
| 靓号有效 | 靓号 | `pretty` | 靓号过期时间 |
|
||
| 靓号过期后 | `default_display_user_id` | `default` | `NULL` |
|
||
|
||
### `user_display_user_ids`
|
||
|
||
短号归属历史表。默认短号和临时靓号都进入这张表。
|
||
|
||
```sql
|
||
CREATE TABLE user_display_user_ids (
|
||
app_code VARCHAR(32) NOT NULL DEFAULT 'lalu',
|
||
id BIGINT NOT NULL PRIMARY KEY,
|
||
display_user_id VARCHAR(32) NOT NULL,
|
||
user_id BIGINT NOT NULL,
|
||
display_user_id_kind VARCHAR(32) NOT NULL,
|
||
status VARCHAR(32) NOT NULL,
|
||
assigned_at_ms BIGINT NOT NULL,
|
||
activated_at_ms BIGINT NULL,
|
||
expires_at_ms BIGINT NULL,
|
||
released_at_ms BIGINT NULL,
|
||
release_reason VARCHAR(64) NULL,
|
||
created_at_ms BIGINT NOT NULL,
|
||
updated_at_ms BIGINT NOT NULL,
|
||
live_display_user_id VARCHAR(32)
|
||
GENERATED ALWAYS AS (
|
||
CASE
|
||
WHEN status IN ('active', 'held', 'reserved', 'blocked') THEN display_user_id
|
||
ELSE NULL
|
||
END
|
||
) STORED,
|
||
active_user_id BIGINT
|
||
GENERATED ALWAYS AS (
|
||
CASE WHEN status = 'active' THEN user_id ELSE NULL END
|
||
) STORED,
|
||
UNIQUE KEY uk_user_display_user_ids_live (app_code, live_display_user_id),
|
||
UNIQUE KEY uk_user_display_user_ids_active_user (app_code, active_user_id),
|
||
KEY idx_user_display_user_ids_user_id (app_code, user_id)
|
||
);
|
||
```
|
||
|
||
`status` 建议：
|
||
|
||
```text
|
||
active
|
||
held
|
||
expired
|
||
released
|
||
reserved
|
||
blocked
|
||
```
|
||
|
||
状态含义：
|
||
|
||
| Status | Meaning |
|
||
| --- | --- |
|
||
| `active` | 当前可被普通业务解析的展示号 |
|
||
| `held` | 默认短号仍归用户所有，但被临时靓号覆盖，普通业务不解析 |
|
||
| `expired` | 临时靓号到期 |
|
||
| `released` | 曾经归属用户，已经释放 |
|
||
| `reserved` | 系统预留，不允许普通用户申请 |
|
||
| `blocked` | 运营阻断，不允许分配 |
|
||
|
||
生成列用于模拟部分唯一索引：同一个短号不能同时处于 `active`、`held`、`reserved` 或 `blocked`；同一个用户只能有一个 `active` 当前展示号。历史 `expired`、`released` 记录可以保留多条。
|
||
|
||
### `pretty_display_user_id_leases`
|
||
|
||
靓号租约表保存临时覆盖关系。它是“过期恢复默认短号”的事实来源。
|
||
|
||
```sql
|
||
CREATE TABLE pretty_display_user_id_leases (
|
||
lease_id VARCHAR(64) NOT NULL PRIMARY KEY,
|
||
display_user_id VARCHAR(32) NOT NULL,
|
||
user_id BIGINT NOT NULL,
|
||
status VARCHAR(32) NOT NULL,
|
||
starts_at_ms BIGINT NOT NULL,
|
||
expires_at_ms BIGINT NOT NULL,
|
||
payment_receipt_id VARCHAR(64) NULL,
|
||
source VARCHAR(32) NOT NULL,
|
||
created_at_ms BIGINT NOT NULL,
|
||
updated_at_ms BIGINT NOT NULL,
|
||
active_display_user_id VARCHAR(32)
|
||
GENERATED ALWAYS AS (
|
||
CASE WHEN status = 'active' THEN display_user_id ELSE NULL END
|
||
) STORED,
|
||
active_user_id BIGINT
|
||
GENERATED ALWAYS AS (
|
||
CASE WHEN status = 'active' THEN user_id ELSE NULL END
|
||
) STORED,
|
||
UNIQUE KEY uk_pretty_display_user_id_active (active_display_user_id),
|
||
UNIQUE KEY uk_pretty_display_user_id_active_user (active_user_id),
|
||
KEY idx_pretty_display_user_id_leases_user (user_id, status),
|
||
KEY idx_pretty_display_user_id_leases_expire (status, expires_at_ms)
|
||
);
|
||
```
|
||
|
||
`status` 建议：
|
||
|
||
```text
|
||
active
|
||
expired
|
||
cancelled
|
||
refunded
|
||
```
|
||
|
||
首版规则：
|
||
|
||
- 一个用户同一时间只能有一个 active 靓号租约。
|
||
- 一个靓号同一时间只能租给一个用户。
|
||
- 申请新靓号不会改变 `default_display_user_id`。
|
||
- 靓号有效期内，默认短号处于 `held`，不能被其他用户申请。
|
||
- 靓号过期后，必须把 `users.current_display_user_id` 恢复为 `users.default_display_user_id`。
|
||
|
||
### `display_user_id_change_logs`
|
||
|
||
短号修改审计表。
|
||
|
||
```sql
|
||
CREATE TABLE display_user_id_change_logs (
|
||
id BIGINT NOT NULL PRIMARY KEY,
|
||
user_id BIGINT NOT NULL,
|
||
old_display_user_id VARCHAR(32) NOT NULL,
|
||
new_display_user_id VARCHAR(32) NOT NULL,
|
||
old_display_user_id_kind VARCHAR(32) NOT NULL,
|
||
new_display_user_id_kind VARCHAR(32) NOT NULL,
|
||
change_type VARCHAR(32) NOT NULL,
|
||
lease_id VARCHAR(64) NULL,
|
||
reason VARCHAR(64) NOT NULL,
|
||
operator_user_id BIGINT NULL,
|
||
request_id VARCHAR(64) NOT NULL,
|
||
created_at_ms BIGINT NOT NULL,
|
||
KEY idx_display_user_id_change_logs_user_id (user_id),
|
||
KEY idx_display_user_id_change_logs_request_id (request_id)
|
||
);
|
||
```
|
||
|
||
修改短号必须写审计。审计失败不能静默忽略；如果审计和主变更不能同事务完成，需要进入 user-service outbox 补偿。
|
||
|
||
### `user_country_change_logs`
|
||
|
||
国家修改日志只服务资料审计和冷却期，不参与 `display_user_id` 解析。
|
||
|
||
```sql
|
||
CREATE TABLE user_country_change_logs (
|
||
id BIGINT NOT NULL PRIMARY KEY,
|
||
user_id BIGINT NOT NULL,
|
||
old_country VARCHAR(64) NULL,
|
||
new_country VARCHAR(64) NOT NULL,
|
||
request_id VARCHAR(96) NOT NULL,
|
||
changed_at_ms BIGINT NOT NULL,
|
||
KEY idx_user_country_change_logs_user_changed (user_id, changed_at_ms),
|
||
KEY idx_user_country_change_logs_request_id (request_id)
|
||
);
|
||
```
|
||
|
||
同一用户修改国家按滚动 30 天冷却。冷却期检查必须在锁定 `users` 行后的事务内读取最新日志，不能只依赖 gateway 侧判断。
|
||
|
||
## ID Generation
|
||
|
||
### `user_id`
|
||
|
||
`user_id` 使用 int64，在服务间 RPC、数据库关系、客户端响应和内部审计中统一使用。人工输入、搜索、分享和登录名使用 `display_user_id`。
|
||
|
||
要求：
|
||
|
||
- `user_id` 全局唯一。
|
||
- 不可变。
|
||
- 客户端不能自报或修改 `user_id`。
|
||
- `user_id` 不依赖数据库自增暴露业务规模。
|
||
|
||
可选实现：
|
||
|
||
```text
|
||
Snowflake-like ID
|
||
Sonyflake-like ID
|
||
database segment allocator
|
||
```
|
||
|
||
当前实现由 user-service 创建 `user_id`。
|
||
|
||
### `display_user_id`
|
||
|
||
`display_user_id` 推荐用字符串保存，即使首版只允许数字。
|
||
|
||
原因：
|
||
|
||
- 后续可能支持靓号、带前缀号、运营号段。
|
||
- 字符串可以保留前导零。
|
||
- 可以统一处理大小写和格式归一化。
|
||
|
||
首版格式可以定为：
|
||
|
||
```text
|
||
^[1-9][0-9]{5,10}$
|
||
```
|
||
|
||
格式规则必须由 user-service 校验。客户端校验只做体验，不作为安全边界。
|
||
|
||
## Pretty Display User ID Model
|
||
|
||
临时靓号是短号的一种，但它不是永久改号。它只是在有效期内覆盖当前展示号。
|
||
|
||
有效展示号计算规则：
|
||
|
||
```text
|
||
if active_pretty_lease exists and now < expires_at_ms:
|
||
display_user_id = pretty_display_user_id
|
||
display_user_id_kind = pretty
|
||
display_user_id_expires_at_ms = expires_at_ms
|
||
else:
|
||
display_user_id = default_display_user_id
|
||
display_user_id_kind = default
|
||
display_user_id_expires_at_ms = null
|
||
```
|
||
|
||
首版不做多个靓号叠加。用户已有 active 靓号时，再申请其他靓号返回 `DISPLAY_USER_ID_PRETTY_ACTIVE`。如果后续要支持续期，只允许对同一个靓号延长 `expires_at_ms`，不能生成第二条 active 租约。
|
||
|
||
默认短号和临时靓号的关系：
|
||
|
||
| Scenario | Behavior |
|
||
| --- | --- |
|
||
| 新用户注册 | 分配默认短号，当前展示号等于默认短号 |
|
||
| 申请靓号成功 | 当前展示号改为靓号，默认短号变为 `held` |
|
||
| 靓号有效期内搜索 | 只能通过靓号解析到用户 |
|
||
| 靓号有效期内密码登录 | 只能通过当前靓号登录 |
|
||
| 靓号过期 | 当前展示号恢复默认短号 |
|
||
| 靓号过期后搜索 | 靓号不再解析，默认短号重新解析 |
|
||
|
||
默认短号在 `held` 期间仍属于原用户，不能被其他用户申请、租赁或永久占用。
|
||
|
||
## Cross-Service Contract
|
||
|
||
内部 proto 字段统一使用：
|
||
|
||
```protobuf
|
||
int64 user_id = 1;
|
||
```
|
||
|
||
禁止在内部主链路使用：
|
||
|
||
```protobuf
|
||
string display_user_id = 1;
|
||
```
|
||
|
||
允许 user-service 暴露解析接口：
|
||
|
||
```protobuf
|
||
service UserIdentityService {
|
||
rpc ResolveDisplayUserID(ResolveDisplayUserIDRequest) returns (ResolveDisplayUserIDResponse);
|
||
rpc GetUserIdentity(GetUserIdentityRequest) returns (GetUserIdentityResponse);
|
||
rpc ApplyPrettyDisplayUserID(ApplyPrettyDisplayUserIDRequest) returns (ApplyPrettyDisplayUserIDResponse);
|
||
}
|
||
|
||
message ResolveDisplayUserIDRequest {
|
||
string display_user_id = 1;
|
||
}
|
||
|
||
message ResolveDisplayUserIDResponse {
|
||
int64 user_id = 1;
|
||
string display_user_id = 2;
|
||
string status = 3;
|
||
string default_display_user_id = 4;
|
||
string display_user_id_kind = 5;
|
||
int64 display_user_id_expires_at_ms = 6;
|
||
}
|
||
|
||
message GetUserIdentityRequest {
|
||
int64 user_id = 1;
|
||
}
|
||
|
||
message GetUserIdentityResponse {
|
||
int64 user_id = 1;
|
||
string display_user_id = 2;
|
||
string status = 3;
|
||
string default_display_user_id = 4;
|
||
string display_user_id_kind = 5;
|
||
int64 display_user_id_expires_at_ms = 6;
|
||
}
|
||
|
||
message ApplyPrettyDisplayUserIDRequest {
|
||
int64 user_id = 1;
|
||
string pretty_display_user_id = 2;
|
||
int64 lease_duration_ms = 3;
|
||
string payment_receipt_id = 4;
|
||
}
|
||
|
||
message ApplyPrettyDisplayUserIDResponse {
|
||
int64 user_id = 1;
|
||
string display_user_id = 2;
|
||
string default_display_user_id = 3;
|
||
string display_user_id_kind = 4;
|
||
int64 display_user_id_expires_at_ms = 5;
|
||
string lease_id = 6;
|
||
}
|
||
```
|
||
|
||
`ResolveDisplayUserID` 只能返回当前有效归属。默认短号被靓号覆盖时处于 `held`，普通解析接口不能返回它。历史归属查询必须使用运营或审计接口，不能给普通业务链路使用。
|
||
|
||
## Service Usage Rules
|
||
|
||
### gateway-service
|
||
|
||
gateway 可以接收客户端传入的 `display_user_id`，但只能用于调用 `user-service.ResolveDisplayUserID`。
|
||
|
||
解析后：
|
||
|
||
```text
|
||
display_user_id -> user_id -> downstream RPC
|
||
```
|
||
|
||
gateway 不缓存永久映射。
|
||
|
||
密码登录入口也按当前展示号解析。用户有 active 靓号时，默认短号暂时不能登录；靓号过期后，默认短号恢复登录能力。
|
||
|
||
### room-service
|
||
|
||
Room Cell 中只保存：
|
||
|
||
```text
|
||
OwnerID int64
|
||
HostID int64
|
||
MicSeat.UserID int64
|
||
OnlineUsers map[int64]
|
||
AdminUsers map[int64]bool
|
||
BanUsers map[int64]bool
|
||
MuteUsers map[int64]bool
|
||
```
|
||
|
||
房间状态、snapshot、command log、outbox 事件都不能保存 `display_user_id` 作为身份字段。
|
||
|
||
如果房间广播需要展示短号，由客户端或网关资料接口通过 user-service 补全；Room Cell 不承担资料拼装。
|
||
|
||
### Tencent Cloud IM
|
||
|
||
腾讯云 IM identifier 只使用不可变长 `user_id` 的十进制字符串：
|
||
|
||
```text
|
||
user_id
|
||
```
|
||
|
||
单聊消息、系统通知、群消息和后续回调校验都使用 `user_id`。
|
||
|
||
客户端通过短号发起私聊时，必须先解析成 `user_id`。
|
||
|
||
### wallet-service
|
||
|
||
账务主体只允许是：
|
||
|
||
```text
|
||
user_id
|
||
```
|
||
|
||
账单、ledger、幂等记录、余额账户都不能用 `display_user_id`。
|
||
|
||
### activity-service
|
||
|
||
活动积分、奖励、风控、排行榜内部主体只用 `user_id`。
|
||
|
||
活动榜单展示短号时，展示层再补资料。活动结算不能依赖短号。
|
||
|
||
## User Creation Flow
|
||
|
||
新用户创建时必须同时分配 `user_id` 和 `default_display_user_id`。创建完成后，`current_display_user_id` 等于默认短号。
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant U as user-service
|
||
participant DB as MySQL
|
||
|
||
U->>U: generate user_id
|
||
U->>U: allocate default_display_user_id from 163000 sequence
|
||
U->>DB: begin transaction
|
||
U->>DB: insert users(default=current)
|
||
U->>DB: insert user_display_user_ids(default,active)
|
||
U->>DB: commit
|
||
```
|
||
|
||
如果默认短号唯一冲突，重新生成候选短号后重试。重试次数必须有限，超过后返回 `DISPLAY_USER_ID_ALLOCATE_FAILED`。
|
||
|
||
## Change Default Display User ID Flow
|
||
|
||
修改默认短号必须事务化。首版建议禁止在 active 靓号期间修改默认短号，避免“过期恢复哪个号”的用户理解成本；如果业务必须支持，需要在变更日志中明确记录新的恢复目标。
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant C as Client
|
||
participant G as gateway-service
|
||
participant U as user-service
|
||
participant DB as MySQL
|
||
|
||
C->>G: ChangeDisplayUserID
|
||
G->>U: ChangeDisplayUserID(user_id,new_default_display_user_id)
|
||
U->>U: validate format and cooldown
|
||
U->>DB: begin transaction
|
||
U->>DB: lock user row
|
||
U->>DB: reject if active pretty lease exists
|
||
U->>DB: lock current default display_user_id
|
||
U->>DB: check new display_user_id uniqueness
|
||
U->>DB: mark old default display_user_id released
|
||
U->>DB: insert new default display_user_id active
|
||
U->>DB: update users.default_display_user_id
|
||
U->>DB: update users.current_display_user_id
|
||
U->>DB: insert display_user_id_change_logs
|
||
U->>DB: commit
|
||
```
|
||
|
||
修改成功后，user-service 可以发布用户资料变更事件，供客户端资料缓存或服务端资料缓存刷新。腾讯云 IM 的 identifier 不随短号变化。
|
||
|
||
## Apply Pretty Display User ID Flow
|
||
|
||
申请临时靓号必须先确认靓号可用、租期合法、支付结果有效。金币扣费或订单支付归属账务服务；user-service 只消费可信的 `payment_receipt_id` 或运营授权结果。
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant C as Client
|
||
participant G as gateway-service
|
||
participant U as user-service
|
||
participant DB as MySQL
|
||
|
||
C->>G: ApplyPrettyDisplayUserID
|
||
G->>U: ApplyPrettyDisplayUserID(user_id,pretty_display_user_id,duration,receipt)
|
||
U->>U: validate format, duration, receipt
|
||
U->>DB: begin transaction
|
||
U->>DB: lock user row
|
||
U->>DB: reject if user already has active pretty lease
|
||
U->>DB: check pretty display_user_id availability
|
||
U->>DB: mark default display_user_id held
|
||
U->>DB: insert pretty_display_user_id_leases(active)
|
||
U->>DB: insert user_display_user_ids(pretty,active,expires_at)
|
||
U->>DB: update users.current_display_user_id=pretty
|
||
U->>DB: insert display_user_id_change_logs(change_type=pretty_apply)
|
||
U->>DB: commit
|
||
```
|
||
|
||
申请成功后：
|
||
|
||
- `ResolveDisplayUserID(pretty)` 返回该用户。
|
||
- `ResolveDisplayUserID(default)` 不返回该用户。
|
||
- `GetUserIdentity(user_id)` 返回 `display_user_id_kind=pretty` 和 `display_user_id_expires_at_ms`。
|
||
- 密码登录使用当前靓号，默认短号暂时不能作为登录名。
|
||
|
||
## Expire Pretty Display User ID Flow
|
||
|
||
靓号过期有两条触发路径：
|
||
|
||
| Path | Rule |
|
||
| --- | --- |
|
||
| 定时任务 | 扫描 `pretty_display_user_id_leases(status=active, expires_at_ms<=now)` |
|
||
| 懒过期 | `ResolveDisplayUserID`、`GetUserIdentity`、密码登录发现快照过期时触发 |
|
||
|
||
过期恢复必须走同一段事务逻辑：
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant U as user-service
|
||
participant DB as MySQL
|
||
|
||
U->>DB: begin transaction
|
||
U->>DB: lock user row
|
||
U->>DB: lock active pretty lease
|
||
U->>DB: mark pretty lease expired
|
||
U->>DB: mark pretty display_user_id expired
|
||
U->>DB: mark default display_user_id active
|
||
U->>DB: update users.current_display_user_id=default
|
||
U->>DB: clear users.current_display_user_id_expires_at_ms
|
||
U->>DB: insert display_user_id_change_logs(change_type=pretty_expire)
|
||
U->>DB: commit
|
||
```
|
||
|
||
过期成功后：
|
||
|
||
- 旧靓号不能继续登录、搜索或分享解析。
|
||
- 默认短号恢复为当前展示号。
|
||
- user-service 必须失效 `user_id -> display_user_id` 和相关 `display_user_id -> user_id` 缓存。
|
||
- 如果过期事务失败，不能只删缓存；必须重试事务或告警。
|
||
|
||
## Display User ID Reuse
|
||
|
||
默认建议：短号释放或靓号过期后进入冷却期，不立即复用。
|
||
|
||
状态流转：
|
||
|
||
```text
|
||
default: active -> held -> active
|
||
default change: active -> released -> reserved -> active
|
||
pretty lease: active -> expired -> reserved -> active
|
||
```
|
||
|
||
首版可以先不复用已释放默认短号；靓号是否可再次出租由运营库存规则决定，但必须有冷却期和历史归属审计。
|
||
|
||
如果后续要复用：
|
||
|
||
- 需要冷却期。
|
||
- 需要运营规则。
|
||
- 需要历史归属审计。
|
||
- 普通业务查询只能返回当前有效归属。
|
||
|
||
## API And Proto Additions
|
||
|
||
建议在：
|
||
|
||
```text
|
||
api/proto/user/v1/user.proto
|
||
```
|
||
|
||
增加：
|
||
|
||
```protobuf
|
||
message UserIdentity {
|
||
int64 user_id = 1;
|
||
string display_user_id = 2;
|
||
string status = 3;
|
||
string default_display_user_id = 4;
|
||
string display_user_id_kind = 5;
|
||
int64 display_user_id_expires_at_ms = 6;
|
||
}
|
||
|
||
message GetUserIdentityRequest {
|
||
int64 user_id = 1;
|
||
}
|
||
|
||
message GetUserIdentityResponse {
|
||
UserIdentity identity = 1;
|
||
}
|
||
|
||
message ResolveDisplayUserIDRequest {
|
||
string display_user_id = 1;
|
||
}
|
||
|
||
message ResolveDisplayUserIDResponse {
|
||
UserIdentity identity = 1;
|
||
}
|
||
|
||
message ChangeDisplayUserIDRequest {
|
||
RequestMeta meta = 1;
|
||
int64 user_id = 2;
|
||
string new_display_user_id = 3;
|
||
}
|
||
|
||
message ChangeDisplayUserIDResponse {
|
||
UserIdentity identity = 1;
|
||
}
|
||
|
||
message ApplyPrettyDisplayUserIDRequest {
|
||
RequestMeta meta = 1;
|
||
int64 user_id = 2;
|
||
string pretty_display_user_id = 3;
|
||
int64 lease_duration_ms = 4;
|
||
string payment_receipt_id = 5;
|
||
}
|
||
|
||
message ApplyPrettyDisplayUserIDResponse {
|
||
UserIdentity identity = 1;
|
||
string lease_id = 2;
|
||
}
|
||
|
||
message ExpirePrettyDisplayUserIDRequest {
|
||
RequestMeta meta = 1;
|
||
int64 user_id = 2;
|
||
string lease_id = 3;
|
||
}
|
||
|
||
message ExpirePrettyDisplayUserIDResponse {
|
||
UserIdentity identity = 1;
|
||
}
|
||
```
|
||
|
||
HTTP 外部接口由 gateway 暴露：
|
||
|
||
```text
|
||
GET /api/v1/users/by-display-user-id/{display_user_id}
|
||
GET /api/v1/users/{user_id}/identity
|
||
POST /api/v1/users/me/display-id/change
|
||
POST /api/v1/users/me/display-id/pretty/apply
|
||
```
|
||
|
||
具体路径可以后续和 OpenAPI 一起定，但内部 proto 必须先保证主链路只用 `user_id`。
|
||
|
||
## Error Reasons
|
||
|
||
user-service 需要增加这些 reason：
|
||
|
||
| Reason | gRPC Code | Meaning |
|
||
| --- | --- | --- |
|
||
| `DISPLAY_USER_ID_INVALID` | `InvalidArgument` | 短号格式非法 |
|
||
| `DISPLAY_USER_ID_EXISTS` | `AlreadyExists` | 短号已被当前有效、持有、预留或阻断 |
|
||
| `DISPLAY_USER_ID_COOLDOWN` | `FailedPrecondition` | 修改短号冷却期未结束 |
|
||
| `COUNTRY_CHANGE_COOLDOWN` | `FailedPrecondition` | 修改国家冷却期未结束 |
|
||
| `DISPLAY_USER_ID_NOT_FOUND` | `NotFound` | 当前有效短号不存在 |
|
||
| `DISPLAY_USER_ID_ALLOCATE_FAILED` | `Internal` | 默认短号分配失败 |
|
||
| `DISPLAY_USER_ID_PRETTY_NOT_AVAILABLE` | `FailedPrecondition` | 靓号不可申请、已被租用或被预留 |
|
||
| `DISPLAY_USER_ID_PRETTY_ACTIVE` | `FailedPrecondition` | 用户已有 active 靓号租约 |
|
||
| `DISPLAY_USER_ID_LEASE_EXPIRED` | `FailedPrecondition` | 靓号租约已经过期 |
|
||
| `DISPLAY_USER_ID_PAYMENT_REQUIRED` | `FailedPrecondition` | 申请靓号缺少有效支付凭证 |
|
||
|
||
gateway 映射到 HTTP envelope 时沿用相同 `code`。
|
||
|
||
## Caching Rules
|
||
|
||
允许缓存：
|
||
|
||
```text
|
||
user_id -> display_user_id
|
||
display_user_id -> user_id
|
||
```
|
||
|
||
限制：
|
||
|
||
- `display_user_id -> user_id` 必须短 TTL。
|
||
- 靓号缓存 TTL 不能超过 `display_user_id_expires_at_ms - now`。
|
||
- 申请靓号后必须失效默认短号和新靓号相关缓存。
|
||
- 靓号过期后必须失效旧靓号、默认短号和用户身份缓存。
|
||
- 修改默认短号后必须主动失效相关缓存。
|
||
- 账务、房间、活动不能依赖缓存中的短号做身份判断。
|
||
- 缓存 miss 必须回源 user-service。
|
||
- 缓存命中也必须尊重 `expires_at_ms`，不能返回已过期靓号。
|
||
|
||
## Migration Impact
|
||
|
||
后续修改现有 proto 时：
|
||
|
||
- 所有跨服务用户字段保持 `int64 user_id`。
|
||
- 如果要额外返回短号，只能追加 `string display_user_id`，不能替换 `user_id`。
|
||
- 如果返回当前展示号，必须同时考虑追加 `display_user_id_kind` 和 `display_user_id_expires_at_ms`，避免客户端把临时靓号误认为永久短号。
|
||
- 历史 outbox 事件不补写短号。
|
||
- 客户端显示短号时通过用户资料接口或缓存补全。
|
||
|
||
## Test Matrix
|
||
|
||
必须覆盖：
|
||
|
||
- 新用户创建时生成唯一 `user_id` 和默认 `display_user_id`。
|
||
- 默认短号冲突时可重试。
|
||
- 通过当前有效 `display_user_id` 解析到正确 `user_id`。
|
||
- 不存在的短号返回 `DISPLAY_USER_ID_NOT_FOUND`。
|
||
- 修改短号成功后旧短号不再解析到用户。
|
||
- 修改短号遇到已占用短号返回 `DISPLAY_USER_ID_EXISTS`。
|
||
- 冷却期内修改返回 `DISPLAY_USER_ID_COOLDOWN`。
|
||
- 申请靓号成功后，当前展示号变为靓号，默认短号进入 `held`。
|
||
- 靓号有效期内，默认短号不能被普通解析接口解析。
|
||
- 靓号有效期内，密码登录使用当前靓号。
|
||
- 用户已有 active 靓号时再次申请其他靓号返回 `DISPLAY_USER_ID_PRETTY_ACTIVE`。
|
||
- 靓号过期后，当前展示号恢复默认短号。
|
||
- 靓号过期后，旧靓号不再解析到用户。
|
||
- 懒过期和定时过期并发执行时，只能有一个事务成功。
|
||
- 房间、钱包、IM、活动 proto 和存储仍只使用 `user_id` 作为主体。
|
||
|
||
## Final Rule
|
||
|
||
`user_id` 是系统身份，`default_display_user_id` 是用户本身的门牌号，临时靓号只是限时覆盖当前门牌号。
|
||
|
||
服务之间传 `user_id`。客户端展示、搜索、分享可以用 `display_user_id`。
|