# 用户与鉴权 · 当前契约与本地实现

更新：2026-11-20。当前应用管理、租户关联、入口归属、工具应用归属及模块目录同步已在本地实现，并接入本地用户中心 Mock。正式用户中心的加解密协议、目录与认证接口仍按本方案对接。登录、会话与权限执行的既有兼容链路没有宣称全部迁移。

## 主体、应用与订购租户

- 主体以 corpCode、corpName 展示。应用表 config.ai_applications 保存独立 id、corpCode、corpName、businessId、businessInfoName，(corpCode,businessId) 唯一。
- 每次订购产生全局唯一 tenantNo。同一主体可购买多个 B 端智能体租户，分别服务商城、PMS、分时预约；应用与租户 1:N。
- 应用租户表保存 id、corpCode、businessId、tenantNo、issuer、starts_at、expires_at、openStatus、serial_digest、serial_payload、source_updated_at、received_at，以及公共审计字段。收到的 tenantName 在写库前移除，serial_payload 也不保留该字段。
- source_updated_at 来自 lastUpdateTime 毫秒时间戳，核对来源更新顺序；received_at 是中台成功处理通知的接收时间，用于追踪延迟。两者都不代表订购有效期。
- 不另存 last_serial，密文保留 SHA-256 摘要，完整解密 JSON 保存到受控 serial_payload。productCode/productName、版本、accountNo、来源 id 等附属字段仅留档，不直接转成系统ID、操作人或本地主键。
- 中台应用的 id 为 bigint 自增主键，JSON 以十进制字符串返回。旧应用标识通过 application_key 兼容既有入口和登录配置。订购租户及绑定记录继续使用各自的 bigint 主键。
- 本地用户中心按主体、系统、租户和租户归属四类数据提供目录。业务系统编码供展示，绑定与模块通过系统 ID 关联。

## 租户关联与模块

绑定表 iam.ai_tenant_bindings 含以下业务字段：id、tenantNo、corpCode、bindBusinessId、bindBusinessInfoName、bindTenantNo。公共创建人、修改人和时间由登录态与服务端填充，不添加 bound_*、unbound_* 或AI侧应用名称快照。

先关联业务租户再新增入口。同一B/C应用内，一个业务租户只能关联一个AI订购租户；换绑时提交当前绑定 ID，保留原绑定历史并同步当前租户的入口至目标模块。重复提交相同关联幂等返回。保存前按AI租户的可信corpCode重新向用户中心查询候选，核验主体、租户状态和有效期；事务锁防止并发重复关联。关系用索引与服务端逻辑约束，不建物理外键。

系统及模块独立于主体。主体用于订购和租户管理。关联业务租户时，以该租户所属应用的 businessId、businessInfoName 分别作为模块编码、名称。在当前 AI 系统内首次绑定就创建，后续同一应用复用同一模块。本地 B 端已关联 PMS（4）、分时预约（23）和智游宝商城（32）。目录支持按业务系统 ID 过滤。

## 入口、工具与目录同步

- 入口固定属于一个AI订购租户，保存后不能换租户；菜单同步到该租户关联的模块。
- 工具定义选择一个B/C应用，新增默认B。应用内多个租户共享工具定义。工具被入口已发布配置引用后，在相应模块的菜单下注册工具按钮。
- 应用管理按主体展示各应用及其订购租户。助理列表与新增表单共同显示当前应用和租户。入口固定归属已关联的订购租户，注册工具时选择 B/C 应用及工具组。
- 模块内登记菜单、按钮、权限组。选系统、模块和工具组可以批量同步该应用已发布的组内按钮。权限组仅用于整理和同步，账号鉴权按具体入口和工具执行。
- 中台维护配置主数据和已发布挂载关系，用户中心维护目录副本并独立给账号授权。配置变更后自动同步；模块内按订购租户分别替换快照，空 entries 只清空该租户的入口及按钮。失败保留配置和错误，可重试，相同内容沿用revision。界面仅在完整确认后显示同步成功。
- 同步状态存config.ai_application_catalog_sync，按(business_id,tenant_no)唯一，保存module_id、module_code、digest、revision及确认结果；不向绑定表重复加入模块业务字段。工具归属存config.ai_application_tools，当前tool_id唯一。

B 端、C 端各自使用用户中心应用表的一个固定系统 ID。主体选择系统后，每次新订购产生一个全局唯一的 tenantNo。主体下的应用记录用于聚合该主体的订购租户。

## 与统一用户中心的接口

订购开通仅使用接收订购序列号接口。按主体查询候选租户属于租户绑定场景。

**注意事项**　当前历史序列号缺少 `businessId`。用户中心在加密前将应用表的 `id` 以字符串写入这个字段。中台发现字段缺失时拒绝入库。

| 接口 | 提供方 | 关键数据 |
| --- | --- | --- |
| POST /api/internal/subscription-notifications | AI中台 | 外层serial长密文；解密后corpCode、corpName、businessId、businessInfoName、tenantNo、effectiveAt、expirationDate、openStatus、lastUpdateTime、contractVersion必填 |
| GET /api/internal/tenants | 用户中心 | corpCode、可选businessInfoName过滤、page、pageSize；返回8个租户业务字段及分页，含完整有效期 |
| POST /api/internal/permission-modules | 用户中心 | businessId、tenantNo、bindBusinessId、bindBusinessInfoName、bindTenantNo、corpCode、name，关联并创建或复用业务应用模块 |
| POST /api/internal/module-permission-catalog | 用户中心 | businessId、moduleId、AI tenantNo、revision、entries及各菜单toolGroups/tools；原子接收模块内该租户快照并确认资源ID |
| GET /api/internal/permission-catalog | 用户中心 | businessId、可选 moduleId、可选 moduleCode（关联业务系统 ID）；返回实际模块、菜单、按钮及修订号 |

详细入参、出参和完整JSON示例见交互方案的接口定义。商业中心仅作为上游背景，中台不直接对接商业中心。历史appName映射businessInfoName，expirationTime映射expirationDate；有效期须明确提供，不用创建时间推断。目标openStatus定义1未开通/2已开通/3停用/4关闭，正式接口由用户中心适配历史枚举。

## 本地演示与验收边界

本地用户中心Mock使用AES-256-GCM加密样例后调用中台接收接口；服务端验证及解密、事务写入、页面刷新均为实际本地交互。密钥从私有服务配置派生，不进入页面。此约定仅用于开发联调，生产环境禁用；不声称兼容现网长序列号。

“解析入库演示”为独立Remotion Player页面，展示原始JSON、业务字段与留档字段、字段映射及提交结果。点击阶段标签即可观看该步转场，约 1.2 秒后停留在结果。支持缺字段和重复推送两种分支。此动画不写数据库；应用管理中的“模拟订购推送”才执行本地加密推送流程。

原生Archify方案保留全局场景、订购开通、租户绑定、登录授权和用户鉴权，并新增“权限目录同步”独立场景。源码、生成回执与交互验收见ua-delivery.json。
