BeeX ID 设计方案

一、国家隔离前提

flowchart LR
  subgraph ID["Indonesia 数据中心"]
    ID_API["api-id"]
    ID_DB[("beex_id_prod")]
    ID_U["usr_xxx"]
    ID_API --> ID_DB
    ID_U --> ID_DB
  end
  subgraph MY["Malaysia 数据中心"]
    MY_API["api-my"]
    MY_DB[("beex_my_prod")]
    MY_U["usr_xxx"]
    MY_API --> MY_DB
    MY_U --> MY_DB
  end
  subgraph BI["未来 BI / 集团报表"]
    KEY["country_code + user_id"]
  end
  ID_DB -.汇总.-> BI
  MY_DB -.汇总.-> BI
        

二、为什么不用数据库自增 ID 对外暴露

数据库内部可以有自增主键，但 API、日志、飞书通知、App、H5、三方回调里不应该直接暴露自增 ID。原因不是跨国混库，而是安全、稳定和可维护。

三、ID 分层模型

BeeX 建议区分三类标识：数据库内部主键、业务对象 ID、用户可传播码。三者不要混用。

flowchart TB
  DBID["内部主键
id=102938"] --> USER["用户记录"]
  UID["业务用户ID
usr_mqp36o6byndywnreeeks"] --> USER
  REF["邀请码
BX2IINJQXX"] --> USER
  USER --> API["接口 / 日志 / 飞书通知
使用 user_id"]
  USER --> SHARE["邀请 / 裂变
使用 referral_code"]
  USER --> DB["数据库关联
可使用内部主键或 user_id"]
        

四、命名与格式规范

当前 BeeX 的 ID 风格是 {prefix}_{random}。前缀用于识别对象类型，随机部分保证难枚举。

五、数据库与接口建议

1. 数据库字段

2. 接口返回

3. 日志和通知

飞书订单通知、日志反馈、异常告警里应该使用业务 ID，例如 userId、orderId、feedbackId。必要时再补充手机号脱敏值、设备 ID、平台订单号。

六、前端展示与复制规则

ID 本身不是给普通用户记忆的，但运营、客服、测试会经常复制它。因此展示可以压缩，复制必须完整。

七、生成规则

生成规则要简单、稳定、可在多服务中复用。

八、未来扩展策略

1. 单国家内分库分表

如果印尼单国用户量变大，需要在印尼数据中心内部做分片，业务 ID 可以保持不变。分片规则可以基于用户 ID 的哈希，或者基于内部主键范围，但不影响前端、三方回调和飞书通知。

2. 跨国家 BI 汇总

国家之间不混库，但 BI 可能需要汇总。汇总层使用 country_code + user_id 作为联合业务键，而不是要求各国家生产库使用同一个用户命名空间。

3. 账号迁移

如果未来出现“用户从一个国家迁移到另一个国家”的特殊需求，应作为业务迁移流程处理，生成目标国家的新用户记录，并保留迁移关系表。不要用同一个用户 ID 跨国家复用。

九、常见误区