AINode 租户管理 API
AINode 主题在 /admin/extensions/tenants 注册租户管理页面。浏览器与 AINode 客户管理页一样,通过现有 /api/proxy/external 调用页面固定的 path=/api/admin/tenants...;上游凭证不会返回浏览器。
通用代理解析出的上游路径只要等于 /api/admin 或以 /api/admin/ 开头,就强制要求 APay 管理员会话;普通用户会话和 x-auth 不能使用 AINode 管理凭证。代理沿用 APay integration_token 设置,并回退到旧版 NUXT_SESSION_PASSWORD,最终值必须等于 AINode 的 internal.token。新建租户返回的 integrationToken 不能调用 AINode 管理接口。
接口
GET /api/proxy/external?path=/api/admin/tenants
返回租户名称、Code、状态、直登设置、API Key 分组 keyGroupId/keyGroupName、钱包数、创建时间、出资模式、批发折扣快照和预存款余额。页面同时调用 GET /api/proxy/external?path=/api/admin/key-groups 加载可选分组;租户只能绑定该列表中的分组。
POST /api/proxy/external?path=/api/admin/tenants
创建租户,请求体包含 name、code、allowDirectLogin 和 keyGroupId。Code 会转为小写,必须匹配 ^[a-z0-9][a-z0-9_-]{1,62}$,且不能是 default。keyGroupId 必须是当前可选分组的正整数 ID,传 0 表示暂不分组。
响应只在创建时返回一次 integrationToken。后台页面仅在内存中展示,关闭结果弹窗即清空,不写入本地存储、Cookie、APay 数据库或应用日志。创建请求关闭自动重试。
PUT /api/proxy/external?path=/api/admin/tenants/{id}
修改租户的 API Key 分组。AINode 的租户更新接口不是局部 PATCH,所以请求体必须携带列表最新快照中的完整字段:name、code、status、allowDirectLogin 和新的 keyGroupId。keyGroupId=0 表示解除当前分组关联。APay 代理会重建允许字段并拒绝额外字段、非法状态、非法租户 ID 或负分组 ID;页面只允许选择当前分组列表中的 ID。
POST /api/proxy/external?path=/api/admin/tenants/{id}/rotate-token
轮换租户 integrationToken。AINode 数据库只保存 Token 的 SHA-256 哈希,旧 Token 无法读取;轮换成功后旧 Token 立即失效,响应中的新 integrationToken 仅显示一次并在关闭弹窗时从页面内存清空。
轮换请求关闭自动重试,也没有幂等键。若 HTTP 超时或响应丢失,旧 Token 可能已经失效,但管理员可能没有拿到新 Token;页面必须显示“结果待确认”,不得假定成功或自动再次轮换。先检查使用方访问状态,确认后再决定是否发起下一次轮换。
GET /api/proxy/external?path=/api/admin/tenants/{id}/deposit
返回当前出资配置和预存款余额,以及实付充值、赠送、历史补录、管理员纠偏净额、实际发行扣减、发行面值、影子发行和流水重算余额。只有流水独立重算余额与实际余额一致时,ledger.balanced 才为 true。
POST /api/proxy/external?path=/api/admin/tenants/{id}/deposit
给租户正向加款。APay 首版只允许正数入账和以下类型:
deposit_topup:实付充值;deposit_grant:赠送或返点;opening_balance:历史期初余额补录;admin_adjust:正向管理员纠偏。
请求体包含:最多八位小数且大于零的十进制字符串 amount、最长 1,000 字的必填 remark、type 和 UUID requestId。APay 将 UUID 映射为 apay-tenant-deposit:{tenantId}:{requestId},作为 AINode 的 eventId。AINode 在同一个数据库事务中更新余额并写入流水,唯一事件 ID 索引会拒绝重复请求。
浏览器不会自动重试,错误或超时后继续保留相同请求 ID。结果不确定时,管理员必须先刷新余额和流水再决定是否重试。明确成功后才清空表单并生成新的请求 ID。本接口不开放负向扣减、退款、出资模式、折扣、豁免开关或租户删除。
GET /api/proxy/external?path=/api/admin/tenants/{id}/ledger&limit=50&offset=0
按最新优先返回资金流水。limit 范围为 1–200,后台页面每次加载 50 条。每条记录可包含类型、方向、面值、实扣金额、批发折扣快照、是否影响预存款、前后余额、余额类型、关联用户/钱包/交易 ID、事件 ID、备注和创建时间。
AINode 当前不返回总数,也没有服务端筛选或导出。代理会转发当前 APay 管理员 ID,AINode 也会保存为 operator_admin_id,但现有流水响应既不返回该字段,也不返回 metadata。由于调用入口是 /api/proxy/external 而不是 APay /api/admin/**,它不在 APay 管理操作日志插件的覆盖范围内;上游暴露操作者或 APay 增加专用代理审计前,流水页只能以备注、事件 ID 和关联交易 ID 作为可见审计线索。
金额和 ID 精度
AINode 以 10^8 刻度的有符号整数保存美元金额。APay 在 JSON 解析前把刻度金额与 64 位流水/交易 ID 转成字符串,浏览器继续以字符串和整数运算完成展示,最多显示八位小数,避免 JavaScript Number 精度丢失。
租户 ID 使用正的 32 位整数。页面通过代理发送受限的流水 limit、offset。
对账与回滚边界
AINode 的余额更新和流水新增在同一事务提交,因此被拒绝或回滚的请求两者都不会变化。但 HTTP 响应丢失仍可能发生在事务成功提交后,所以重试必须沿用原请求 ID,并先检查余额和流水。若返回 balanced: false,说明可能存在绕过流水的余额修改或其他账务不一致;应暂停充值并排查,不能直接再充一笔掩盖差异。