English

Partner API — Self-Service Signup and Key Management

Verified human accounts can create an active external partner and manage API keys without administrator involvement. A dedicated portal gives each account sole ownership of one partner while preserving separate service identities, landlord consent, and once-only secret disclosure.

  • Status Approved

View source markdown ↗ generated by openai-codex/gpt-6.1-sol · diagrams mermaid

已验证的人类账号无需管理员即可创建已启用的外部合作伙伴,并管理其 API 密钥。一个创建者拥有一个合作伙伴;独立门户保留独立服务身份、房东授权以及仅展示一次的凭据。

决策与评审状态

  • 资格开放注册 · 已验证人类账号
  • 所有权一个账号 · 一个合作伙伴
  • 界面独立 SolidStart 门户
  • 凭据具名、明确权限的密钥

直接记录创建者所有权

合作伙伴记录中使用可为空且唯一的 owner_user_id;每个自助合作伙伴只有一个创建者,每个账号最多拥有一个合作伙伴。

单一所有者模型无需成员查询或角色系统。权限仅限该合作伙伴,不是全平台管理员权限。

未采用:独立所有权表在目前无需多个所有者时增加表和查询;组织与邀请机制则增加不必要的成员语义。

决策选定约定
注册无需邀请或管理员审批;创建合作伙伴或签发密钥前必须验证邮箱。
新合作伙伴已启用、外部类型;默认值由服务器指定,客户端不可选择。
人类身份与 API 身份创建者登录管理合作伙伴;独立的非交互式服务用户持有密钥。
密钥生命周期多个具名密钥、明确权限、可选有效期、安全列表和撤销。
更改凭据已签发密钥的权限和有效期固定:签发替代密钥并撤销旧密钥。
现有合作伙伴与回调管理员创建的合作伙伴仍由管理员管理;不认领或回填所有权。Webhook 仍由管理员管理。

目标与访问边界

合作伙伴开发者应能注册、创建合作伙伴身份并取得可用凭据,无需管理员手动配置。持续自助管理包括允许的资料修改、额外密钥、安全元数据查看和撤销。

密钥权限、房东授权与资源可见性共同收窄允许访问的范围;注册不能绕过任何一层。 密钥权限上限 房东授权 可见资源 允许访问
逐层约束访问,而非新增授权:已签发的密钥仍需通过现有房东授权和资源可见性检查。

架构与身份

人类会话授权管理操作;独立服务身份继续作为 Partner API 密钥背后的身份。两个后端分别执行自己的持久化所有权检查。
人类会话授权管理操作;独立服务身份继续作为 Partner API 密钥背后的身份。两个后端分别执行自己的持久化所有权检查。

独立门户

frontend/solidstart/apps/partner 复用共享认证、UI 和服务器代理约定。注册、登录、验证、账号恢复、入驻、资料和密钥共用现有身份存储。代理传递人类上下文,而非用 API 密钥冒充所有者。

Go 合作伙伴管理边界

负责合作伙伴记录、创建者所有权、资料修改和入驻编排。所有者分配与合作伙伴插入一起提交;数据库唯一性确保每个账号最多一个合作伙伴,并保留标识名和服务用户的唯一性。

Bun 凭据管理边界

负责人类认证、真实服务用户配置、签发、列表和撤销。每次密钥操作都解析人类会话及当前持久化所有权。两个后端的数据映射共用所有者列;Bun 不维护第二份登记。

所有权与授权规则

  • 管理员创建的合作伙伴可将 owner_user_id 留空;非空时必须唯一。沿用现有认证 ID 表示,不假定账号 ID 是 UUID。
  • 所有权由服务器分配。拒绝客户端提供的所有者、服务身份、类型、状态及其他特权修改字段。
  • 知道合作伙伴或密钥 ID 不会带来权限。每次操作都检查持久化所有权;访问其他合作伙伴或密钥时返回未找到,不泄露元数据。
  • 撤销同时检查合作伙伴密钥配置及服务用户引用。服务用户账号绝不是人类创建者。
  • 不转移所有权,也不绑定现有管理员创建的合作伙伴。创建者权限来自所有权,而非全局认证角色。
  • 使用现有 Cookie 会话 CSRF/来源保护,只配置新门户允许的来源;不信任任意来源。

注册与入驻

  1. 注册或登录

    使用共享账号系统中的新建或现有人类账号。

  2. 验证邮箱

    未验证时显示指引。验证成功前,后端阻止合作伙伴创建和密钥签发。

  3. 解析现有所有权

    现有所有者进入概览,不提供第二个合作伙伴的创建流程。

  4. 创建合作伙伴

    按现有验证规则填写显示名称和唯一标识名,并说明标识名不可更改。服务器创建已启用的外部合作伙伴,分配人类创建者和独立服务身份。

  5. 单独签发首个密钥

    必须填写密钥名称并明确选择非空的有效权限;有效期可选。创建合作伙伴不会自动签发全权限密钥。

  6. 仅展示一次,然后管理元数据

    提供复制功能及不可再次取回的警告。离开展示界面后返回安全元数据。首个密钥步骤失败或被放弃,不影响已创建的合作伙伴。

并发与恢复

恢复必须证明所有权,而非只匹配标识名或服务身份。结果不确定绝不意味着可以认领其他合作伙伴。
恢复必须证明所有权,而非只匹配标识名或服务身份。结果不确定绝不意味着可以认领其他合作伙伴。
  • 先检查现有所有权和标识名是否可用;插入时再次通过唯一性约束保证。
  • 保留邮箱的恢复只接受真实非交互式服务用户。交互式账号冲突仍是冲突,不进行账号转换。
  • 只有持久化所有者就是当前认证创建者时,才返回现有合作伙伴。名称、标识名、服务用户 ID 和保留邮箱都不是所有权证据。
  • 冲突或插入结果不确定后,解析已提交状态:可返回同一所有者的记录;不能认领其他所有者或管理员管理的身份。
  • 一个账号并发提交不同标识名,最多产生一个合作伙伴。不能修改获胜记录,也不能对未提交候选记录签发密钥。
  • 竞争失败或插入失败可能留下未使用的真实服务用户,且没有入驻创建的密钥或房东授权。不新增破坏性清理任务;之后创建该标识名只能按相同安全规则复用。

资料与暂停

所有者可修改
显示名称与有效的已登记授权跳转 URL;保留现有授权匹配及安全规则。
所有者不可修改
标识名、类型、状态、服务身份和所有权。
暂停的合作伙伴
仍可读取资料/密钥元数据并撤销密钥。资料修改、新密钥签发及使用现有密钥的资源请求均被阻止。
管理员
保留管理、暂停以及独占的重新启用权限。

密钥与敏感信息生命周期

  • 必须具名并明确选择有效权限。未选择绝不等于全权限;拒绝未知动作和静默扩权。
  • 权限是上限,不是授权。仅限授权访问的记录仍需现有房东许可。
  • 可选有效期遵循现有认证约定。拒绝无效或非正时长,而非静默签发永不过期的密钥。
  • 服务器强制 configId: 'partner'、持久化服务用户以及现有前缀 grp_。客户端元数据不能选择身份或绕过所有权。
  • 已签发权限与有效期不可编辑:创建替代密钥,然后撤销旧密钥。
  • 签发响应不可缓存,展示界面仅为临时状态。界面关闭或所有者退出登录时清除密钥。
  • 密钥不得进入 URL、日志、持久化浏览器存储、分析系统或元数据查询缓存。响应丢失后元数据仍须可管理。
  • 撤销验证人类所有权和服务/配置绑定。过期或已撤销密钥不能授权 Partner API 调用。

错误与真实状态

复用现有后端错误格式与前端处理。保留非敏感表单输入供修正,不保留密钥用于恢复。重复入驻可恢复已提交且拥有的合作伙伴;签发不承诺幂等展示。

条件必需结果
没有人类会话要求认证并引导登录。
未验证账号创建或签发要求验证;不执行修改。
已拥有合作伙伴解析现有所有权以导航/恢复;不创建第二个合作伙伴。
其他所有者的标识名或服务身份返回冲突;不认领、不泄露管理元数据。
无效名称、标识名、权限、有效期、跳转地址或特权字段验证错误;没有成功修改。
其他所有者的合作伙伴或密钥未找到;不更改元数据或凭据。
暂停后修改资料或签发禁止操作;安全读取和撤销仍可用。
认证、数据库或配置服务不可用可重试的服务错误;不伪造成功或退回不安全的所有权判定。

现有代码与集成

依赖现有 Partner API 身份、密钥验证、房东授权、共享认证及前端服务器代理约定。已观察到这些基础,并不意味着自助功能已实现。

具体集成参考
  • backend/go/internal/modules/rental/domain/entity/partner.go:合作伙伴身份、启用/暂停状态、外部/第一方类型、服务用户和跳转地址;当前没有人类所有者。
  • backend/go/internal/modules/rental/application/usecase/admin_partner.go:验证创建、配置 Bun 服务用户并恢复部分冲突。管理员恢复不等于人类所有权证据。
  • backend/go/internal/modules/rental/adapter/outbound/client/bun_partner_client.go:现有内部配置客户端。
  • backend/bun/apps/monolith/src/api-gateway/routes/internal.routes.ts:创建/恢复 partner+{slug}@partners.invalid;恢复要求角色为 partner 且无凭据账号,拒绝交互式账号冲突。
  • backend/bun/apps/monolith/src/api-gateway/routes/admin-partner-keys.routes.ts:管理员专用密钥创建、权限目录、服务用户绑定、合作伙伴配置/前缀以及安全元数据。
  • 现有 Bun 管理员签发在省略权限时默认使用完整目录。所有者签发必须改为要求明确选择。
  • 前端管理员辅助模块投影安全元数据并签发/撤销密钥;它不是创建者授权依据。

验证与成功标准

保留确定性的授权、并发、恢复和凭据回归检查。只有测试不足以证明:还需按仓库批准的浏览器流程,在安全 UAT/一次性环境中实际操作门户和 Partner API。

  1. 新建和现有已验证账号无需管理员即可创建已启用外部合作伙伴并签发可用的所选权限密钥。
  2. 未认证、未验证和服务用户身份不能创建人类拥有的合作伙伴或签发自助密钥。
  3. 并发请求保证单一所有者/合作伙伴;重试不能绑定其他所有者或管理员管理的记录。
  4. 第二个账号不能通过已知 ID 或伪造字段查看、编辑、签发或撤销另一个账号的合作伙伴凭据。
  5. 安全元数据不含密钥/哈希字段;原始密钥仅在签发时出现,不进入存储、日志或缓存列表。
  6. 拒绝缺失/空选择和目录外资源/动作。签发权限必须完全匹配;授权与可见性约束继续生效。
  7. 实际 API 调用拒绝过期/已撤销密钥。暂停阻止资源使用、资料编辑和签发,同时保留安全读取/撤销。
  8. 配置成功后插入失败、插入响应丢失的恢复必须安全。签发失败/响应丢失后合作伙伴仍可管理,但不能恢复密钥。
  9. 拒绝无效跳转地址;保留授权匹配与安全规则。
  10. 现有管理员创建的合作伙伴、管理员密钥签发与服务配置继续工作,无需认领或回填。

非目标与下一审批关卡

  • 不提供组织、成员、邀请、合作伙伴切换、所有权转移、合作伙伴删除或管理员审批队列。
  • 不新增认证系统、不开放无限制房东访问、不提供密钥取回或已签发权限编辑。
  • 不提供 Webhook 自助管理,也不更改现有咨询/报价/Webhook 资源约定。

Webhook 设计,2026-10-09-partner-api-webhooks-design.md,仍是管理员配置回调的依据。合作伙伴无需回调即可完成入驻;配置回调仍是独立的管理员操作。