English

Partner Portal — Developer Integration Experience

Add public, guided integration documentation to the partner portal so developers can make their first authenticated UAT request and implement landlord and listing workflows correctly. Generate the read-only API reference from the shipped Partner OpenAPI contract, with explicit consent, permission, visibility, retry, and test-data guidance.

  • Predecessor 2026-10-09-partner-self-serve-onboarding-design
  • Status Approved

View source markdown ↗ generated by openai-codex/gpt-6-luna · diagrams mermaid

为合作伙伴开发者提供公开的分步指引,从首次通过认证的 UAT 请求走向正确的房东及房源业务流程。API 参考必须与已交付的 OpenAPI 契约一致,说明账号认领与授权所需的人工步骤,且不得把文档变成携带凭证的请求执行器。

决策与权衡

  • 受众合作伙伴集成开发者
  • 界面合作伙伴门户内的公开文档
  • 环境现有 UAT,而非沙箱
  • 语言英语 / 马来语 / 中文

分步文档与契约生成的参考

在专用门户中提供快速入门、业务指南、UAT 测试、错误恢复及只读端点参考。

开发者需要理解权限、授权、账号认领、资源可见性及业务顺序,而不只是获取凭证或查看端点结构。目标是在没有未说明前提或工作人员解释的情况下,完成成功请求及获得授权的物业与房源提交流程。

未采用:仅提供 API 参考会让开发者自行拼凑流程。交互式 API 浏览器会增加密钥处理与意外写入风险,且并非需求所必需。

访问方式
文档公开;账号、资料及密钥管理仍须认证。
示例
可复制的 cURL,使用环境变量占位符,附带预期结果及每个标识符的获取说明。
契约
仓库中的 Partner OpenAPI 文档提供方法、路径、结构、响应及操作细节。
密钥
文档不得嵌入、获取或持久化真实开发者凭证。

架构与内容职责

指南解释集成顺序;仓库中的契约决定端点细节。文档没有请求执行器,也不会查询所有者密钥。
指南解释集成顺序;仓库中的契约决定端点细节。文档没有请求执行器,也不会查询所有者密钥。
公开路由职责
/docs概览、环境提示及阅读顺序。
/docs/quickstartUAT 前提、受限权限密钥设置、首次请求及响应解读。
/docs/guides/...业务流程及前提条件,包括 webhooks 接收指南。
/docs/reference从 Partner OpenAPI 生成的只读参考。
/docs/testingUAT 访问、专用测试数据、预期结果及清理限制。
/docs/errors现有错误及可操作的恢复说明。

解释性指南

版本控制中的说明负责流程顺序、前提、安全解释及示例叙述。指南链接到对应参考操作;影响流程的 API 变更必须同步更新指南。

权威 API 参考

backend/go/openapi/partner-v1.yaml负责端点细节。在门户构建时生成参考,而非只保留数据结构。

参考必须呈现:

  • x-key-scope(密钥权限上限)与x-grant-scope(房东授权)作为两项独立要求。空的x-grant-scope(如创建连接请求)显示为“无需房东授权”,而不是缺失数据。
  • 全局x-error-codes状态码表。
  • 顶层webhooks: partnerEvent条目显示为合作伙伴接收的出站回调,绝不显示为可调用的操作。
  • 契约对交接操作的条件挂载说明,避免显示为在所有部署中都可用。

构建时验证 OpenAPI 及指南/参考内部链接。不得维护另一份手写端点目录,也不得运行时获取可能与应用版本不一致的远程契约。现有后端契约漂移检查仍是核对已挂载操作的权威依据。

部署信息

醒目且一致地展示配置中的 UAT API 基础 URL。从已批准的门户部署配置解析:不得猜测主机、使用无关房东 API 的默认地址、暴露内部服务 URL、虚构生产 URL 或提供生产环境选择。契约的servers为/,不提供主机。配置缺失或无效时文档构建失败;页面绝不发布虚构或占位主机。

示例使用基础 URL、密钥及资源 ID 变量。说明每个值的来源;绝不代入所有者的真实密钥。

先验证认证的快速入门

  1. 理解 UAT

    调用会读取及修改真实 UAT 数据。Partner API 没有测试/正式模式标志。

  2. 设置身份与凭证

    注册或登录、验证账号、创建合作伙伴,再签发具名且明确选择权限的密钥。链接到已交付的管理页面,不重复实现控件。快速入门仅在自助门户交付后发布;在此之前,创建合作伙伴、签发密钥及登记重定向 URL 都是平台管理员步骤,任何过渡内容都必须明确说明。

  3. 在服务端保存密钥

    使用环境变量。不得把密钥放入前端代码、版本库、URL 或持久化浏览器存储。

  4. 证明认证有效

    调用GET /api/partner/v1/me,使用x-api-key,目标为文档给出的 UAT 基础 URL。

  5. 解读并继续

    说明返回的合作伙伴身份及权限上限,再进入新房东或现有房东流程。

提供可复制的 cURL、已实现的响应结构、预期结果及各变量的获取说明。页面是指南,不是浏览器 API 客户端。

业务流程指南

每份指南包括前提、密钥权限与房东授权范围、标识符获取、有序请求、预期响应/状态、人工参与、失败恢复、支持的重试及适用清理步骤。示例来自已实现的契约,而非仅存在于设计中的端点。

账号认领与房东授权是两件不同的事。流程说明真实的人工与审核步骤,不绕过它们,也不暗示创建账号会授予必须经同意的权限。
账号认领与房东授权是两件不同的事。流程说明真实的人工与审核步骤,不绕过它们,也不暗示创建账号会授予必须经同意的权限。

接入新房东

  • 解释账号创建结果、稳定的合作伙伴引用标识及重复尝试的处理。
  • 认领密钥仅通过平台邮件发送,绝不交给合作伙伴。解释认领状态及提交房源前必须认领账号的要求。
  • 创建账号既不会静默关联现有账号,也不会授予必须经同意的权限。

连接现有房东

  • 门户交付后通过门户登记重定向 URL(此前由平台管理员登记);redirect_uri必须与已登记 URL 完全一致。
  • 批准链接由合作伙伴递送。POST /connect-requests把approve_url及expires_at返回给合作伙伴,平台不会代为发送。该链接只能使用一次,24 小时后过期,轮询也不会再次返回;丢失响应只能重新创建请求。
  • 说明批准、拒绝、过期及访问权判定。区分授权凭证与账号认领凭证(后者只通过平台邮件发送),以及密钥权限上限与房东授权。
  • 重新批准会替换整组授权范围:省略的权限被移除,而非继续累加。密钥或已知房东 ID 不会提供无限制访问。

准备并提交房源

  • 创建/查找已获授权的物业,提供媒体及产权证明,准备房源并提交审核。
  • 说明前提、提交后的审核状态、合作伙伴来源可见性及归属规则。
  • 提交不等于发布。不得建议通过更换标识符或凭证访问被隐藏的资源。

支持的后续操作

涵盖已交付的租约、协议、付款、交接、联系方式、咨询及报价操作。遵循支持的方法、状态转换、权限上限、必须经同意的权限及物业来源边界。交接操作是否可用取决于部署是否接入交接处理器。

报价只读:不支持创建、还价、接受、拒绝或撤回。归档历史遵循各资源契约;不得承诺查看整个房东账号。

接收 Webhook

合作伙伴 Webhook 已交付,因此由 webhooks 指南说明接收端,内容依据契约的webhooks: partnerEvent条目:

  • 投递条件:已启用的端点绑定有效、未过期且可读的密钥;有效的enquiries:read授权;合作伙伴创建的物业;五种事件类型。
  • 信封:只含最少标识符,是信号而非状态快照。
  • 签名:Webhook-Signature: v1=<hex HMAC-SHA256>,对<Webhook-Timestamp>.<原始请求体>计算,密钥为 base64 解码后的值;五分钟时间窗口、常量时间比较,且Webhook-Id必须等于请求体id。
  • 确认与投递:持久保存后才返回2xx;至少一次、无序投递——按id去重,并通过已授权的读取接口获取当前状态。
  • 结果:408/429/5xx在 24 小时内重试;3xx及其他4xx为终止结果;端点停用期间的事件不会补发。

UAT 测试与清理

  1. 使用专用测试身份

    说明如何获取房东账号及创建合作伙伴所属资源。不得依赖任意现有 UAT 账号、物业、授权或 ID。

  2. 说明真实前提

    区分 API 创建的测试数据与人工认领、授权及管理员审核。在受影响流程开始前说明必要的工作人员设置,不把它隐藏在看似自助的步骤之后。

  3. 通过支持的操作清理

    使用已支持的归档/删除/撤销操作,并解释限制。不得承诺完整重置或销毁他人记录。撤销凭证或授权不会删除业务数据。

错误、重试与密钥处理

解释现有错误格式{error:{code,message,fields?},request_id},并保留请求 ID 用于诊断。不增加新的错误契约。

情况所需指引
密钥无效、过期或被撤销区分凭证失败与房东访问权限。
权限不足或授权缺失/被撤销区分密钥权限上限与房东授权;不得建议无差别扩大权限或重复申请授权。
资源被隐藏404可能表示没有访问权,而非仅表示删除。
验证失败或业务前提未满足解释相关字段/状态前提及修正方式。
限流或服务不可用按该操作已记录的规则重试,并保留请求 ID。
幂等冲突或写入结果不确定说明相同请求重放、变更请求体冲突及该操作的结果核对规则;没有适用契约时不得盲目重放写入。

逐端点描述支持的Idempotency-Key行为,以及账号创建独立的合作伙伴引用标识语义。丢失写入响应不意味着可随意重试。不得承诺幂等地重新返回密钥明文。

本地化与无障碍

说明内容、导航、提示及复制反馈使用门户的英语/马来语/中文约定。请求、字段名、路径、权限标识、请求头及接口错误代码保持不变。

检查认领、授权、权限、可见性、UAT 安全及重试的翻译,确保含义一致。提供无障碍标题、导航、代码块、复制控件及状态反馈。移动端阅读必须保留请求内容及参考访问。不增加独立视觉框架,也不进行无关的门户/租赁界面改造。

验证与验收

实施时结合构建检查、现有契约覆盖、真实 UAT 请求及已渲染文档验证。编写本设计不要求产品代码、运行时测试或门户构建。

  1. 未登录用户可阅读全部文档(包括 Webhook 指南);管理路由仍受保护。
  2. 从仓库中的 OpenAPI 生成参考,分别显示密钥/授权要求(包括“无需授权”)、x-error-codes、不可调用的partnerEvent及交接操作的条件挂载。无效输入、损坏的指南/操作内部链接或缺失/无效的基础 URL 配置必须导致构建验证失败,而不是发布不完整参考。
  3. 自助门户交付后,遵循账号设置及快速入门完成/me调用,不存在未说明前提或嵌入凭证。
  4. 使用专用 UAT 账号执行新房东及现有房东授权流程;观察身份、认领/授权状态及权限,而不只检查成功状态码。只有创建响应包含approve_url,轮询从不返回;由合作伙伴递送该链接。
  5. 按文档物业流程到达房源提交/审核状态;演示认领前提并区分提交与发布。
  6. 使用获授权的测试数据执行代表性的后续读写及拒绝案例;证明权限上限、授权、来源边界及不支持操作的限制。不得把不可用操作(包括未接入的交接路由)宣传为可执行。
  7. 用本地签名的测试数据验证 Webhook 签名示例:接受有效签名;拒绝被篡改的请求体、过期时间戳或不匹配的Webhook-Id。证据中不含真实密钥;真实 UAT 投递为可选项。
  8. 在不输出凭证的情况下演示代表性的幂等重放/冲突及错误恢复。保留后端操作/契约回归测试,不增加源码文本或重复目录测试。
  9. 确认真实 UAT 提示/基础 URL、标识符获取、人工步骤及清理限制。不得虚构生产主机或沙箱/测试密钥行为。
  10. 使用仓库批准的 ego-lite 浏览器流程检查已渲染导航、参考链接、复制控件、无障碍、移动端阅读及三种语言。指南内容及页面框架随语言切换;参考中的契约描述保持英文。复制的示例只含占位符。
  11. UAT 写入前遵循仓库安全规则:开发环境及已记录的 UAT 数据库主机/名称。自动化数据库集成测试使用可丢弃数据库。撤销演示密钥,并仅进行受支持的自有测试数据清理。

现有基础、依赖与范围

已观察到的基础与具体来源引用
  • backend/go/openapi/partner-v1.yaml描述/api/partner/v1下 59 个显式挂载的操作,通过x-api-key认证。它不包含前端/会话认领及授权端点,并记录权限上限、授权、正式模式可见性、来源限制、认领前提、错误、限流及端点特定幂等行为。其servers为/。
  • 契约包含每个操作的x-key-scope/x-grant-scope、顶层x-error-codes表及顶层webhooks: partnerEvent回调。交接操作仅在接入交接处理器时挂载。
  • 合作伙伴 Webhook 投递已实现:backend/go/internal/modules/rental/下的 Go worker、管理端处理器及持久化,后台的PartnerWebhookSection,以及接收/接入指南docs/backend/go/guides/partner-api-webhooks.md。配置仅限管理员。
  • 授权重定向 URI 目前只能通过管理员合作伙伴端点(admin_partner_handler.go)及后台合作伙伴页面编辑;所有者编辑随自助门户提供。
  • backend/bun/apps/monolith/src/api-gateway/routes/admin-partner-keys.routes.ts在签发合作伙伴密钥时移除metadata.mode。
  • docs/superpowers/specs/2026-10-03-partner-api-p1-design.md将沙箱/测试模式延期,并规定在 UAT 进行集成测试。合作伙伴请求无法访问房东 API 的测试模式记录。
  • docs/superpowers/specs/2026-10-09-partner-self-serve-onboarding-design.md定义专用门户及所有者操作。编写时frontend/solidstart/apps/partner尚不存在;本设计扩展该前提,不代表它已交付。
  • 现有房东开发者指南位于frontend/astro/apps/rental/src/pages/developers/及src/docs/landlord-api-v1.md。其按部署注入主机的方式可用于避免手写 URL,但不能据此复制房东路径或密钥前缀。

基于已交付的自助门户及后端契约实施。frontend/solidstart/openspec/changes/partner-self-serve-portal/design.md仍负责认证、所有权、资料及密钥生命周期。本次仅增加文档与导航。

明确不在范围内

不包含专用沙箱、生产部署、环境切换、合作伙伴测试/正式密钥、交互式 API 浏览器、SDK 生成、新业务端点、绕过授权、Webhook 自助功能(配置、测试发送、重放)、翻译契约描述、自动测试数据创建/重置、诊断仪表盘或无关重构/租赁用户改动。

批准与实施关卡

  1. 书面规范已批准

    经审阅修订后于 2026-10-10 批准。

  2. 审阅 OpenSpec 产物

    partner-developer-integration-experience的提案、设计、规格及任务在此关卡前生成,现已同步更新;审阅后选择执行方式。

  3. 实施并验证

    基于真实门户/API 前提交付,同时收集 UAT 与浏览器证据。

提交设计文档或 OpenSpec 产物并不授权实施。来源规范规定验证与依赖关卡,不增加部署基础设施或数据迁移。