Files

T

richjohnrambo 219ecadf4c feat: complete registration invitation and auth redesign

2026-08-19 00:30:11 +08:00

31 KiB

Raw Blame History

IM HotGo 注册短信开关与邀请码管理改造交接文档

文档状态：已按数据库直连方案实现，作为现状与后续 Kafka 演进说明对应实施顺序：注册改造计划第 4 项（HotGo 后台） HotGo 项目：/Users/youshunlai/go_workspace/im_manager IM 服务项目：/Users/youshunlai/go_workspace/im_server 编写日期：2026-08-18

1. 文档用途

本文供新的开发会话直接接手 HotGo 项目使用。阅读本文后，应能明确：

为什么要在 HotGo 中增加注册短信开关和邀请码管理。
哪些数据属于 HotGo 控制库，哪些数据属于 IM 租户业务库。
HotGo 后端、前端、菜单权限、统一租户身份、审计和配置需要修改什么。
HotGo 与 IM 如何通过租户业务库协作，以及后续如何迁移到 Kafka。
如何验证实现没有破坏租户隔离，也没有泄露邀请码明文。

本文指导 HotGo 项目改造。HotGo 负责邀请码生成和管理；IM 仍独占客户端注册、短信验证码和邀请码使用记录事务。

2. 开发前必须阅读

在修改 /Users/youshunlai/go_workspace/im_manager 前，先阅读以下文档：

/Users/youshunlai/go_workspace/im_server/docs/IM-注册、邀请码与认证数据模型改造需求文档.md
/Users/youshunlai/go_workspace/im_server/docs/IM-前后端对接文档.md 中 1.4、1.5 注册章节
/Users/youshunlai/go_workspace/im_server/docs/IM-后台需求文档.md 中租户权限、用户管理和审计章节
/Users/youshunlai/go_workspace/im_server/docs/IM-独立库多租户改造方案.md

规则冲突时按以下优先级处理：

本文针对 HotGo 的落地边界和接口约定。
《IM 注册、邀请码与认证数据模型改造需求文档》。
《IM 独立库多租户改造方案》。
其他较早的需求和设计文档。

IM-服务端多租户改造方案.md 已废弃，不得作为实现依据。当前多租户方案是“一套 IM 服务、一个 HotGo 控制库、每租户一个独立 IM 业务库”。

3. 需求前因后果

3.1 注册页面最终规则

客户端注册页面同时展示用户名、手机号、短信验证码、密码和邀请码，但用户名与手机号是二选一关系：

手机号非空时，以手机号方式为准，忽略用户名输入。
手机号方式注册后，im_users.username 和 im_users.phone 都保存规范化后的 +86 手机号。
手机号为空时使用普通用户名，用户名必须匹配 ^[a-z0-9]{1,10}$，此时 phone=NULL。
普通用户名方式不能自助找回密码，只能由企业管理员重置。
邀请码固定为 5 位 ASCII 大小写英文字母，区分大小写、租户内唯一，有效期内可供多人使用。

3.2 为什么需要短信开关

短信服务在不同部署环境中可能暂未启用，因此需要平台级开关：

场景	短信开关开启	短信开关关闭
点击获取验证码	IM 服务真实调用短信服务商	IM 服务返回正常挑战和倒计时，但不调用服务商
手机号注册	必须验证短信；邀请码不能绕过	必须提供有效邀请码，可无验证码注册
用户名注册	不发送短信，必须提供有效邀请码	不发送短信，必须提供有效邀请码
客户端是否知道开关	不直接暴露	不直接暴露

HotGo 只负责管理开关值。是否调用短信服务商、是否允许注册，全部由 IM 服务端判定。

3.3 为什么当前改为 HotGo 直接访问租户库

邀请码属于 IM 租户业务数据：

每个租户有独立业务库。
邀请码批次和主表位于 hotgo 控制库，使用明细位于对应租户业务库。
HotGo 邀请码管理直接访问控制库；密码重置等租户业务功能仍通过 im_tenant.id 和服务端保存的 DSN 选择租户库。
当前部署中 HotGo 到 IM 的内部 HTTP 地址不可达，继续维护 HMAC 管理 API 会增加一套没有必要的调用链。

因此当前采用“控制库主数据 + 租户库使用事实”的混合边界：HotGo 负责邀请码生成、查询、导出和撤销；IM 从控制库校验邀请码，并在租户库记录使用关系和 outbox 事件。两端各自只写自己负责的数据。

密码重置等需要 IM 立即感知的操作写入 im_business_events_outbox。当前 IM 轮询消费，后续改为 Kafka 时保留事件契约，只替换传输层。

4. 系统边界

flowchart LR
    A["HotGo 管理后台浏览器"] -->|HotGo 登录 Token| B["HotGo 后端"]
    B -->|读写全局开关| C[("hotgo.hg_sys_config")]
    B -->|读取管理员 tenant_id| D[("hotgo.im_tenant")]
    B -->|管理邀请码| G[("hotgo.im_registration_invite_batches")]
    B -->|管理邀请码| H[("hotgo.im_registration_invite_codes")]
    B -->|其他租户业务按服务端 DSN| F[("租户 IM 业务库")]
    F --> I["im_registration_invite_uses"]
    J["IM 注册与发码接口"] -->|短时缓存读取| C
	J -->|按 tenant_id 校验| H
	J -->|记录使用关系与事件| F
	B -->|写 security.password_reset| K["im_business_events_outbox"]
	F --> K
    K -->|当前轮询，后续 Kafka| J

4.1 HotGo 负责

在 hg_sys_config 保存全局注册短信开关。
只允许平台超级管理员修改开关。
为邀请码提供管理页面、表单、权限和审计入口。
从当前登录管理员身份解析可信的 IM tenant_id。
通过 imtenant.DB() 直连所选租户业务库，不接受浏览器传入 DSN。
对邀请码明文查询、查看和导出执行独立权限校验。

4.2 IM 服务负责

读取并缓存短信开关。
实际发送或抑制短信。
注册时大小写敏感地校验邀请码，并记录邀请码与新用户的使用关系。
邀请码使用后不改变 active 状态。
消费 security.password_reset 事件并清退在线会话。
登录时以 auth_version 拒绝密码重置前签发的旧 Token。
消费 registration.invite_used，将租户库使用统计幂等投影到控制库。

4.3 明确禁止

浏览器直接连接租户数据库。
浏览器通过 Header、Query 或 Body 自报可信 tenant_id。
HotGo 后端根据浏览器传入的 db_name 或 db_dsn 连接数据库。
HotGo 修改 im_registration_invite_uses；该表只允许 IM 注册事务写入。
HotGo 绕过 outbox 直接修改在线会话状态。
在普通访问日志、错误日志、埋点或 URL 中记录完整邀请码。

5. 当前 HotGo 项目现状

目标仓库 /Users/youshunlai/go_workspace/im_manager 基于 GoFrame 2、Vue 3 和 Naive UI。

已确认的现状：

通用配置后端位于 server/api/admin/config、server/internal/controller/admin/sys/config.go、server/internal/logic/sys/config.go。
通用配置前端位于 web/src/views/system/config 和 web/src/api/sys/config.ts。
hg_sys_config 支持 group/key/type/value/default_value，前端不能通过通用接口新增不存在的配置项。
sys_switch 字典实际定义为“开启=1、关闭=2”。
HotGo 管理接口权限按“路由路径 + HTTP Method”使用 Casbin 校验，前端按钮权限也使用路由路径，例如 hasPermission(['/notice/edit'])。
hotgo.im_tenant 是全系统唯一租户注册表，由 HotGo 维护，不存在另一套需要映射的“IM 租户”。
后台管理员通过 hg_admin_member.tenant_id 直接引用 im_tenant.id，登录身份必须携带该字段；不再使用独立租户绑定表。
hg_sys_log 会保存 GET Query 和 POST Body；现有逻辑只自动掩码名称包含 password 的 POST 字段，邀请码查询参数会泄漏，必须补充脱敏。

6. 建议开发顺序

阶段 A：先完成 HotGo 基础边界

增加全局短信开关配置种子和专用读写接口。
增加 hg_admin_member.tenant_id 外键与登录身份解析，统一使用 im_tenant.id。
增加租户库直连、Snowflake ID 和数据库事件写入能力。
增加邀请码相关菜单、路由权限和后台代理接口。
增加邀请码管理页面。
增加敏感字段日志脱敏和操作审计。

阶段 B：与 IM 服务联调

核对 IM 租户库迁移已执行且表结构一致。
核对服务凭证、租户上下文和操作人上下文可被 IM 验证。
联调单个生成、批量生成、分页查询、撤销、详情和导出。
联调短信开关在 IM 服务缓存时间内生效。

IM 管理接口未完成时，可以通过接口 Client 抽象和测试 Stub 开发页面，但不得用 HotGo 直写租户数据库作为临时方案。

7. 全局注册短信开关

7.1 数据定义

在 HotGo 控制库 hg_sys_config 中增加且只保留一条配置：

group         = im
name          = 注册短信发送
type          = bool
key           = register_sms_enabled
value         = 1
default_value = 1
status        = 1
is_default    = 1

建议的 MySQL 幂等种子：

INSERT INTO hg_sys_config
    (`group`, `name`, `type`, `key`, `value`, `default_value`, `sort`, `tip`, `is_default`, `status`, `created_at`, `updated_at`)
SELECT
    'im', '注册短信发送', 'bool', 'register_sms_enabled', '1', '1', 10,
    '控制 IM 注册验证码是否真实发送', 1, 1, NOW(), NOW()
WHERE NOT EXISTS (
    SELECT 1 FROM hg_sys_config
    WHERE `group` = 'im' AND `key` = 'register_sms_enabled'
);

同时为 (group, key) 增加唯一约束。加索引前先检查并清理重复配置，不能让 IM 服务随机读到多条值。

ALTER TABLE hg_sys_config
    ADD UNIQUE KEY uk_hg_sys_config_group_key (`group`, `key`);

新装数据库种子、实际部署迁移及项目保留的 MySQL/PostgreSQL/SQLite 初始化脚本应按项目发布策略同步，不能只改一份示例 SQL。

7.2 `sys_switch` 映射陷阱

sys_switch 字典值与真实配置值不相同：

UI 字典值	UI 含义	`hg_sys_config.value`
`1`	开启	`1`
`2`	关闭	`0`

实现要求：

页面加载时将后端 bool 值映射为字典值：true -> 1，false -> 2。
页面提交时反向映射：1 -> true，2 -> false。
不得把字典值 2 原样写入 bool 配置；GoFrame 的 bool 转换可能把非零值当成 true。
数据库只允许保存可解释为 1/0 的值。

7.3 后端接口

不要直接让页面复用通用 /config/update。新增专用接口，以便强制执行平台管理员校验：

方法	HotGo 路径	权限
GET	`/imRegistration/config/get`	平台超级管理员
POST	`/imRegistration/config/update`	平台超级管理员

读取响应：

{
  "registerSmsEnabled": true,
  "updatedAt": "2026-08-18T16:00:00+08:00"
}

更新请求：

{
  "registerSmsEnabled": false
}

后端必须在业务逻辑层再次调用 service.AdminMember().VerifySuperId(ctx, contexts.GetUserId(ctx))，不能只依赖菜单是否可见。更新时只允许修改固定的 group=im/key=register_sms_enabled，不接受前端传 group 或 key。

7.4 页面位置

建议在 web/src/views/system/config/system.vue 增加“IM 注册”设置项，并新增：

web/src/views/system/config/ImRegistrationSetting.vue

页面只展示一个“注册短信发送”开关和保存按钮。选项通过 dict.loadOptions(['sys_switch']) 加载，并按 7.2 做显式映射。

7.5 IM 服务读取约定

HotGo 不需要额外暴露公开配置接口。IM 服务直接从控制库读取：

SELECT value
FROM hg_sys_config
WHERE `group` = 'im'
  AND `key` = 'register_sms_enabled'
  AND status = 1
LIMIT 1;

约定：

种子默认值为开启。
IM 服务缓存建议为 30 秒，缓存时长可配置。
临时读取失败时优先使用最近一次成功值。
进程启动后无缓存且配置缺失、停用或非法时，按“开启”处理，防止邀请码绕过短信验证，并记录告警。
HotGo 更新后不承诺立即生效，验收标准为 30 秒内生效。

8. 统一租户身份

8.1 唯一租户主键

hotgo.im_tenant.id 是 HotGo 和 IM 服务共同使用的唯一 tenant_id。HotGo 负责维护租户注册信息和业务库路由，IM 服务根据该 ID 选择租户业务库。不得再创建 im_admin_tenant_binding 或其他租户映射表。

8.2 管理员租户归属

后台管理员记录直接引用统一租户：

ALTER TABLE hg_admin_member
    ADD COLUMN tenant_id BIGINT NULL COMMENT '统一租户ID，引用 im_tenant.id',
    ADD INDEX idx_hg_admin_member_tenant (tenant_id),
    ADD CONSTRAINT fk_hg_admin_member_im_tenant
        FOREIGN KEY (tenant_id) REFERENCES im_tenant(id);

平台账号的 tenant_id 可以为空。租户管理员及其创建的下级后台账号必须继承同一个 im_tenant.id。只有平台超级管理员可以为后台账号选择或修改租户，租户域管理员提交的 tenantId 必须被后端忽略并以当前登录身份为准。

8.3 解析规则

租户管理员请求邀请码接口时：

从 HotGo 登录上下文取得 member_id、tenant_id 和部门类型。
仅允许合法的租户级管理员角色进入；普通用户和商户角色不得管理邀请码。
tenant_id 必须大于 0，并且对应的 im_tenant 必须存在且为 active。
将该 tenant_id 写入 IM 服务调用上下文。
忽略并拒绝浏览器提交的 tenantId。

平台超级管理员可以跨租户查看邀请码；列表和导出未选择租户时查询全部。创建、批次查看、撤销及其他写操作必须先选择一个 im_tenant。此选择只对 VerifySuperId 通过的管理员开放，HotGo 后端仍要检查目标租户存在且 active。

后台用户管理应提供仅平台超级管理员可见的租户选择控件。租户管理员未关联 im_tenant.id 时返回明确错误“当前管理员未关联租户”，不能回退到默认租户。

9. 租户库直连与事件通道

9.1 数据库选择

HotGo 从可信登录上下文取得 im_tenant.id。邀请码批次和邀请码主表直接通过 imtenant.RegistryDB() 访问 HotGo 控制库；只有密码重置等租户业务操作才通过 imtenant.DB() 打开租户业务库。浏览器传入的 tenantId 只允许平台超级管理员选择，租户管理员始终使用登录关系中的租户 ID；任何请求都不能提交或覆盖 DSN。

若配置了 database.imRegistry，租户注册表从该连接读取；未配置时回退到 HotGo 默认库。业务操作始终使用按租户动态建立的连接组。

9.2 Snowflake 配置

HotGo 直接新增 IM 表记录时使用与 IM 相同位布局的 Snowflake ID：

imDirectDb:
  snowflakeWorkerId: 1023

也可由 IM_DIRECT_DB_SNOWFLAKE_WORKER_ID 覆盖。每个 HotGo 写库实例必须使用唯一 worker ID，并且不能与 IM 节点重叠。当前单实例默认预留 1023，多实例部署前必须分配 worker ID。

9.3 写入职责

HotGo 可以写：

HotGo 控制库中的 im_registration_invite_batches、im_registration_invite_codes。
管理员重置密码时的 im_auth.secret 和 im_user_security。
管理操作产生的 im_business_events_outbox。

IM 独占写入：

客户端注册事务及用户创建。
租户业务库中的 im_registration_invite_uses 以及同事务的 registration.invite_used outbox 事件。
客户端登录、改密、短信找回等认证事务。

9.4 Kafka 演进

管理员重置密码在数据库事务内写入：

{
  "event_type": "security.password_reset",
  "payload": {
    "user_id": 198000000000000001,
    "auth_version": 2,
    "operator_id": 10001,
    "request_id": "..."
  }
}

当前 IM 在注册写入 outbox 后立即触发一次消费，并每秒按在线会话涉及的租户轮询 pending 事件。security.password_reset 消费后清退该用户会话；registration.invite_used 消费时从租户使用明细重新聚合 COUNT/MAX(used_at)，覆盖 HotGo 控制库的 usage_count/last_used_at，成功后标记 delivered。离线用户不依赖密码重置轮询，后续登录时由 auth_version 直接拒绝旧 Token。

邀请码使用事件契约：

{
  "event_type": "registration.invite_used",
  "payload": {
    "tenant_id": 1,
    "invite_code_id": 198000000000000001,
    "user_id": 198000000000000002,
    "request_id": "acc-request-id",
    "used_at": "2026-08-19T10:00:00.000Z"
  }
}

迁移 Kafka 时，生产者继续在业务事务内写 outbox，由独立投递器发布同一事件；消费者保持事件类型与 payload 不变。Kafka 投递确认后再标记 outbox delivered，避免数据库提交成功但消息丢失。

10. 邀请码接口契约

10.1 数据表契约

HotGo 在控制库直接维护带 tenant_id 的 im_registration_invite_batches 和 im_registration_invite_codes。邀请码状态仅为 active/expired/revoked，使用后仍为 active；im_registration_invite_uses 只由 IM 注册事务写入租户库。控制库中的 usage_count/last_used_at 由 outbox 消费器幂等投影，HotGo 列表不跨租户库做联表聚合。

平台超级管理员在列表和导出接口中可不传 tenantId 以查询全部租户；创建、批次查看、撤销等写操作必须明确选择一个 active 租户。租户管理员只能查询和操作登录关系绑定的 im_tenant.id。

邀请码明文不得放入 URL。查询完整邀请码时必须使用 HotGo POST Body，普通请求日志需对 inviteCode 脱敏。

10.2 HotGo 对浏览器接口

沿用 HotGo 现有命名风格，建议增加：

方法	HotGo 路径	说明
POST	`/imInvite/list`	分页查询，过滤条件放在 JSON Body
POST	`/imInvite/create`	单个生成
POST	`/imInvite/batchCreate`	批量生成
GET	`/imInvite/batchView`	批次详情
POST	`/imInvite/revoke`	单个撤销
POST	`/imInvite/batchRevoke`	批量撤销
POST	`/imInvite/export`	明文导出，过滤条件放在 JSON Body

HotGo controller 只做 DTO 转换、调用 service 和包装响应。租户解析、平台管理员判断、权限复核、审计和租户库访问放在 logic/service 层。

10.3 单个生成

HotGo 请求：

{
  "expiresAt": "2026-09-01T00:00:00+08:00",
  "remark": "新员工入职",
  "idempotencyKey": "7be3de87-994f-46c6-86bd-844ffb54f83f"
}

规则：

expiresAt 必填，必须晚于服务端当前时间。
remark 最长 255 字符。
推荐单个生成也传幂等键，避免提交成功但响应超时时重复创建。
邀请码由 HotGo 使用 crypto/rand 生成并依靠租户库唯一索引兜底，HotGo 不接受用户自定义 code。

响应数据：

{
  "id": 198000000000000001,
  "code": "AbCdE",
  "status": "active",
  "expiresAt": "2026-09-01T00:00:00+08:00",
  "remark": "新员工入职",
  "createdBy": 10001,
  "createdAt": "2026-08-18T16:10:00+08:00"
}

10.4 批量生成

HotGo 请求：

{
  "quantity": 100,
  "expiresAt": "2026-09-01T00:00:00+08:00",
  "remark": "2026年8月新员工入职",
  "idempotencyKey": "4dc7f13e-448c-4b49-b056-57a2fde18f95"
}

规则：

quantity 为 1 到 1000，由 HotGo 校验。
同一个提交动作必须复用同一个幂等键，直到得到明确成功响应。
前端可在打开弹窗时生成 UUID，失败重试时复用；成功或关闭弹窗后废弃。
HotGo 在批次表保存幂等键；相同参数重试返回原批次，不重复生成。

响应数据：

{
  "batchId": 198000000000000100,
  "quantity": 100,
  "activeCount": 100,
  "usageCount": 0,
  "revokedCount": 0,
  "expiredCount": 0,
  "expiresAt": "2026-09-01T00:00:00+08:00",
  "createdAt": "2026-08-18T16:15:00+08:00"
}

10.5 分页查询

列表请求使用 POST JSON Body，支持字段：

page, perPage, inviteCode, status, batchId, createdBy,
createdAtStart, createdAtEnd, expiresAtStart, expiresAtEnd

要求：

inviteCode 仅支持完整 5 位精确查询，不做模糊查询，不转换大小写。
status 为 active/expired/revoked，邀请码使用后仍保持 active。
HotGo 查询前将 expires_at <= now 的 active 记录更新为 expired，不依赖定时任务。
默认按 created_at DESC, id DESC 排序。
perPage 设置合理上限，建议不超过 100。

列表字段至少包括：

{
  "id": 198000000000000001,
  "batchId": 198000000000000100,
  "code": "AbCdE",
  "status": "active",
  "expiresAt": "2026-09-01T00:00:00+08:00",
  "usageCount": 12,
  "lastUsedAt": "2026-08-20T09:30:00+08:00",
  "createdBy": 10001,
  "remark": "新员工入职",
  "createdAt": "2026-08-18T16:10:00+08:00"
}

10.6 撤销

只有 active 且未过期的邀请码可撤销；已有使用记录不影响撤销。
已过期、已撤销的邀请码不能恢复为 active。
批量撤销只撤销批次内仍可撤销的码，并返回各状态统计。
页面操作前显示确认框，确认内容不必重复显示完整邀请码。
最终状态由租户库条件更新结果决定，不以前端状态为准。

10.7 导出

导出必须具备独立 /imInvite/export 权限。
导出过滤条件与列表一致。
HotGo 后端分页读取租户库并流式写出，不把整份文件加载到内存。
建议输出带 UTF-8 BOM 的 CSV，字段至少包含邀请码、状态、批次、到期时间、累计使用次数、最后使用时间、创建人、创建时间和备注。
文件名建议为 registration-invite-codes-YYYYMMDD-HHmmss.csv。
每次导出必须写审计，但审计详情不得包含邀请码明文列表。

11. 页面和交互

建议页面路径：

web/src/views/im/registrationInvite/index.vue
web/src/views/im/registrationInvite/model.ts
web/src/views/im/registrationInvite/CreateModal.vue
web/src/views/im/registrationInvite/BatchCreateModal.vue
web/src/views/im/registrationInvite/BatchViewModal.vue
web/src/api/im/registrationInvite.ts

页面放在“IM 管理 / 注册邀请码”菜单下。使用现有 BasicForm、BasicTable、TableAction、usePermission 和 Naive UI 组件。

页面必须具备：

完整邀请码、状态、批次 ID、创建人、创建时间和到期时间筛选。
单个生成按钮。
批量生成按钮。
导出按钮。
列表展示完整邀请码、状态、到期时间、批次、使用情况、创建信息和备注。
active 行提供撤销操作，其他状态不显示撤销操作。
批次详情展示总数、active、used、expired、revoked 统计。
所有日期时间明确按本地时区展示，提交时发送带时区的 RFC 3339 时间。
加载、空数据、接口错误、重复提交和无权限状态处理完整。

邀请码区分大小写，任何输入组件、复制操作和查询参数都不得自动转为大写或小写。

12. 菜单与权限

HotGo 的权限标识使用接口路径。建议创建以下按钮权限：

/imRegistration/config/get
/imRegistration/config/update
/imInvite/list
/imInvite/create
/imInvite/batchCreate
/imInvite/batchView
/imInvite/revoke
/imInvite/batchRevoke
/imInvite/export

权限分配：

能力	平台超级管理员	租户管理员	其他角色
查看/修改短信开关	允许	禁止	禁止
选择任意 IM 租户管理邀请码	允许	禁止	禁止
管理当前绑定租户邀请码	允许	按权限允许	禁止
查看邀请码明文	允许	需独立权限	禁止
导出邀请码明文	允许	需独立权限	禁止

服务端 Casbin、业务逻辑层租户范围校验、前端按钮隐藏三层都要实现。前端隐藏按钮不是安全边界。

13. 日志脱敏与审计

13.1 必须修复现有访问日志泄露

server/internal/logic/sys/log.go 当前会保存 Query 和 Body，且只掩码 password。至少增加以下字段名的大小写不敏感脱敏：

inviteCode
invite_code
serviceSecret
service_secret
authorization

建议抽成统一的递归敏感字段过滤器，同时处理 Query、JSON Body、Form 和 Header。Header 中已有简化逻辑也必须确认不会保存内部服务凭证。

对 /imInvite/list 的明文精确查询，邀请码只能放在 POST Body，hg_sys_log.post_data 中只能出现 ******。hg_sys_log.get_data、Nginx URL 和其他访问日志中都不能出现真实邀请码。HTTP Client 的 debug 日志同样不得打印完整 URL、Query、请求体或响应体。

13.2 业务审计

仅靠普通访问日志不够。建议在 HotGo 控制库增加独立审计表，或者接入项目已有的等价不可变审计设施。最低字段为：

CREATE TABLE im_admin_operation_audit (
    id           BIGINT NOT NULL AUTO_INCREMENT,
    request_id   VARCHAR(64) NOT NULL,
    tenant_id    BIGINT NULL,
    operator_id  BIGINT NOT NULL,
    action       VARCHAR(64) NOT NULL,
    target_type  VARCHAR(32) NOT NULL,
    target_id    BIGINT NULL,
    result       VARCHAR(16) NOT NULL,
    ip           VARCHAR(64) NOT NULL DEFAULT '',
    detail_json  JSON NULL,
    created_at   DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
    PRIMARY KEY (id),
    KEY idx_im_admin_audit_tenant_time (tenant_id, created_at),
    KEY idx_im_admin_audit_operator_time (operator_id, created_at),
    UNIQUE KEY uk_im_admin_audit_request_action (request_id, action)
);

必须审计：

短信开关修改，记录旧值和新值。
单个生成和批量生成，记录 code ID 或 batch ID、数量和到期时间，但不记录 code 明文。
邀请码明文查询和详情查看，记录查询行为，但不记录搜索明文。
单个撤销和批量撤销。
明文导出，记录过滤条件摘要和导出数量，不记录明文内容。
后台管理员租户归属变更。

IM 服务也应写自己的业务审计。HotGo 审计记录后台操作者，IM 审计记录实际租户库操作，两者通过 request_id 关联。

14. 错误处理

HotGo 应将数据库错误稳定映射为后台可理解的错误，不向浏览器返回 DSN、SQL、堆栈或内部配置。

至少处理：

场景	HotGo 行为
当前管理员未关联租户	返回明确业务错误，不使用默认租户
目标租户停用	拒绝操作
无查看/导出权限	403
邀请码已过期或已撤销	显示不可撤销，不本地修改状态
幂等键重复且请求相同	返回原结果
幂等键重复但参数不同	返回幂等冲突
租户库连接失败	返回“租户业务库暂不可用”，保留 Request ID
数据库写入失败	事务回滚，返回统一后台错误并记录脱敏日志
导出数据过大	使用服务端限制或异步导出，不耗尽内存

15. 建议代码落点

遵循现有 HotGo 分层，建议新增或修改：

server/api/admin/imregistration/
server/api/admin/iminvite/
server/internal/controller/admin/admin/im_registration.go
server/internal/controller/admin/admin/im_invite.go
server/internal/model/input/adminin/im_registration.go
server/internal/model/input/adminin/im_invite.go
server/internal/service/im.go
server/internal/logic/admin/im_registration.go
server/internal/logic/admin/im_invite.go
server/internal/library/imtenant/db.go
server/internal/library/imtenant/snowflake.go
server/internal/router/admin.go
server/internal/logic/sys/log.go
web/src/api/im/registrationInvite.ts
web/src/views/im/registrationInvite/
web/src/views/system/config/ImRegistrationSetting.vue
web/src/views/system/config/system.vue

如果新增 im_admin_operation_audit，按 HotGo 现有 GoFrame DAO 生成流程生成 dao/do/entity，不要手工修改标有 “Code generated” 的文件。禁止新增 im_admin_tenant_binding。

同时提交：

生产数据库幂等迁移。
新装数据库初始化数据。
菜单和按钮权限种子。
默认角色授权或明确的部署授权步骤。
Snowflake worker 配置示例，但不提交真实 DSN。

16. 测试清单

16.1 短信开关

无配置时 IM 按开启处理并告警。
平台超级管理员可查看和修改。
租户管理员即使手工调用接口也不能修改。
UI 选择“关闭”后数据库保存 0，不是 2。
UI 重新加载时 0 正确显示为“关闭”。
IM 服务在 30 秒内读取到新值。
开关审计包含操作者、旧值、新值和 Request ID。

16.2 租户隔离

租户 A 管理员只能看到租户 A 邀请码。
修改 Query、Body 或 Header 中的 tenant ID 不能访问租户 B。
未绑定管理员不能回退到 default 租户。
停用租户不能生成、查询、撤销或导出。
平台超级管理员选择租户后只能操作所选租户，切换时列表立即清空并重新请求。

16.3 邀请码

单个生成返回恰好 5 位 [A-Za-z]。
批量生成数量正确，最大值限制生效。
AbCdE 和 abcde 可作为不同邀请码精确查询。
重复提交相同幂等键不产生第二个批次。
active 可撤销，expired/revoked 不可撤销。
同一 active 邀请码可供多个不同用户注册，累计使用次数正确增长且状态保持 active。
列表、详情和导出权限相互独立。
导出文件数量、过滤条件和明文字段正确。

16.4 安全和日志

hg_sys_log.get_data/post_data/header_data 中找不到真实邀请码和服务 secret。
应用日志中找不到邀请码明文、内部 Token 和 Authorization。
每个敏感操作都有 HotGo 审计和 IM 审计，并可通过 Request ID 对应。
无权限接口返回 403，不能只依赖前端按钮隐藏。
数据库连接和 SQL 错误不泄露内部实现信息。

17. 完成标准

满足以下条件才能认为 HotGo 第 4 项完成：

全局注册短信开关可由平台超级管理员配置，关闭值正确保存为 0。
IM 服务能在约定缓存时间内读取开关，缺失和异常时采用安全默认值。
HotGo 管理员身份能可靠映射到 im_tenant.id，不存在默认租户回退。
邀请码单个、批量、查询、详情、撤销和导出全部通过所选租户库完成。
平台与租户权限、跨租户隔离和服务端复核全部通过测试。
邀请码明文只出现在授权页面和授权导出中，不进入普通日志。
配置修改和邀请码敏感操作均有可关联的审计记录。
后端 Go 测试、前端类型检查/构建和核心页面联调通过。

18. 新会话可直接使用的任务说明

在新的开发会话中可直接发送：

请修改 HotGo 项目 /Users/youshunlai/go_workspace/im_manager。
先完整阅读 /Users/youshunlai/go_workspace/im_server/docs/IM-HotGo注册短信开关与邀请码管理改造交接文档.md，
再阅读其中列出的上游 IM 文档。按照交接文档的开发顺序完成 HotGo 的注册短信全局开关、
统一租户身份、租户库直连、邀请码管理后台、菜单权限、日志脱敏和审计。
只允许通过服务端 `im_tenant` 注册信息选择租户库，不要信任浏览器自报 tenant_id 或 DSN，
不要修改 `im_registration_invite_uses`，不要把邀请码明文写入普通日志。
开始前先检查 im_manager 当前工作区已有改动，并保留与本任务无关的用户修改。

31 KiB Raw Blame History Unescape Escape