Partner API — Enquiries and Offers
Authorised partners can read and respond to tenant viewing requests, exchange thread messages, and read offers through the Partner API, limited to properties they created. Consent-only permissions, scoped SQL readers, existing landlord workflows, and audit attribution preserve privacy and access boundaries without granting offer negotiation or acceptance authority.
- Predecessor Partner API foundation (P1), property lifecycle (P2), and P3 shared landlord scope and consent presentation
- Status Approved
让获授权的合作伙伴处理房源管理与租约运营之间的租客咨询:读取看房请求、回应看房时间、在会话中交换消息,以及读取租赁报价。访问仅限于调用方合作伙伴创建的物业;报价协商和接受仍不在 API 范围内。
决策概览
| 决策 | 已确定的选择 |
|---|---|
| 操作范围 | 与房东 v1 完全一致:看房读取/操作、会话读取/发消息,以及仅限读取的报价。 |
| 物业可见性 | 不可变的 origin_partner_id 必须与调用方匹配。不提供涵盖所有物业的可选授权。 |
| 同意 | enquiries:read 和 enquiries:write 均需房东批准。 |
| 实现 | 复用 V1EnquiryHandler 和现有工作流;传入显式的 port.LandlordScope,并在 SQL 中过滤。 |
| 身份 | 以房东身份操作;保留 sent_via: "api",并在审计中记录真实合作伙伴。 |
| 重试 | 复用消息发送幂等机制,使用按房东限定作用域的合作伙伴键。不新增看房操作幂等契约。 |
| 生命周期 | 已归档的历史记录仍可读取。操作和消息遵循现有租赁工作流规则。 |
目标与成功标准
合作伙伴先从第一方白标渠道开始,随后纳入外部门户和 CRM。他们需要在房源管理与 P3 租约运营之间的空档为已授权房东提供服务,但无权协商或接受报价。
成功意味着在合作伙伴接口上提供看房请求列表/详情、确认/改提时间/拒绝、会话读取/发送消息,以及报价列表/详情。租客信息披露和业务行为与现有房东 v1 API 一致。
- 项目范围
- P1 明确延期的咨询与报价事项;不改变 P1–P3 验收标准。
- 依赖
- P1 Partner API 基础、P2 物业生命周期,以及 P3 共享房东作用域和同意展示。
- 负责范围
backend/go、backend/bun、frontend/solidstart/apps/rental和frontend/solidstart/apps/panel。- 并行工作
- 源文档记录了其他会话中的 P2 前端和 P3 后端/前端实现工作。与其交付的接口集成;不要重复这部分工作。
架构与备选方案
共享处理器,显式读取器
复用 V1EnquiryHandler,并将咨询读取器迁移至 P3 的 port.LandlordScope。
单一咨询工作流保留 v1 响应组织方式和业务行为。SQL 可见性过滤确保详情访问、分页内容及总数与 P3 一致。
独立的合作伙伴处理器/读取器可减少对 v1 调用方的变更,但会重复响应组织和可见性逻辑。在未修改的读取器外围逐资源检查,会将授权逻辑分散在检查与查询之间,而且分页仍需修改 SQL。
现有基础,不代表实现已完成
已观察到的代码边界与源设计
adapter/inbound/http/v1_routes.go使用enquiries:read/enquiries:write挂载九条咨询路由;更深层的报价操作路径刻意在认证前返回404。adapter/inbound/http/v1_enquiry_handler.go组织看房请求、消息及报价的响应,不包含用户 ID 或结构化租客联系方式。操作辅助函数在工作流执行前读取可见请求,并在执行后再次读取。- 发送消息前检查可见性;重放通过
GetOwnerMessage解析。PeekMessages读取永不将消息标记为已读。 ViewingRequestUseCase:ListOwnerPage、GetOwnerView、PeekMessages、GetOwnerMessage。OfferUseCase:ListLandlordPage、GetLandlordView。这些当前接收(ownerID/landlordID, isTest),而非感知合作伙伴的作用域。adapter/outbound/persistence/postgresql/message_repository.go当前写入sent_via = 'api'标记的条件仅为actor_type == 'api_key'。- P1 结合密钥权限上限、房东授权和正式模式房东作用域;
partner_scope.go包含按房东限定作用域的幂等键辅助函数。 - P3 引入
port.LandlordScope{UserID, IsTest, PartnerID}、仅可经同意授予的权限约束、共享的多语言权限范围展示,以及管理面板中的仅可经同意授权分组。复用这些已交付的集成接口。
docs/superpowers/specs/ 中的源设计:2026-10-03-partner-api-p1-design.md、2026-10-03-landlord-api-enquiries-design.md 和 2026-10-07-partner-api-p3-design.md。
API 契约
基础路径:/api/partner/v1/landlords/:landlord_id。以下相对路径保留房东 v1 请求体和响应。
| 方法 | 相对路径 | 所需权限范围 |
|---|---|---|
GET | /viewing-requests | enquiries:read |
GET | /viewing-requests/:id | enquiries:read |
POST | /viewing-requests/:id/confirm | enquiries:write |
POST | /viewing-requests/:id/counter | enquiries:write |
POST | /viewing-requests/:id/decline | enquiries:write |
GET | /viewing-requests/:id/messages | enquiries:read |
POST | /viewing-requests/:id/messages | enquiries:write |
GET | /offers | enquiries:read |
GET | /offers/:id | enquiries:read |
- 看房列表过滤条件
status、listing_id。- 报价列表过滤条件
status、viewing_request_id。- 写入请求体字段
- 确认:
confirmed_time;改提时间:proposed_times;拒绝:reason;消息:body。 - 保留的契约
- 现有请求体验证、响应字段、时间戳、排序及分页封装。
授权与读取器边界
三项可见性谓词
- 房东匹配
解析现有房源/物业关系;房东或业主必须与
scope.UserID匹配。 - 模式匹配
现有物业/房源模式规则必须与
scope.IsTest匹配。合作伙伴请求仅限正式模式。 - 来源匹配
当
scope.PartnerID存在时,物业的origin_partner_id必须与其匹配。租赁应用创建的物业及其他合作伙伴创建的物业均不可见。
使用 P3 的显式 port.LandlordScope 和现有处理器作用域构造约定。不要将存储库授权隐藏在上下文值中,也不要引入第二种作用域类型。房东 v1 不含合作伙伴 ID,保留现有正式/测试模式可见性。
会话与写入访问门控
PeekMessages和GetOwnerMessage在读取消息前通过带作用域的读取器解析父请求;重放保留消息所属会话的检查。- 操作辅助函数在确认/改提时间/拒绝之前使用完整作用域解析请求,并对刷新后的响应使用相同作用域。消息发送前执行相同的作用域检查。
- 现有用例约束所有权、合法状态转换、会话可写性、消息验证及生命周期规则。
- 来源不可变:不新增物业来源修改或锁定策略,也不新增咨询归档策略。
- 将所有受影响的调用方和测试替身迁移至显式作用域。不保留旧签名别名或兼容包装器;门户工作流的其余部分保持不变。
权限范围、同意与管理
在授权词汇和仅可经同意授权的集合中,仅新增 enquiries:read 和 enquiries:write。不创建独立的 offers 或 messages 权限范围。
- 管理员设置权限上限
在 P3 的仅可经同意授权分组中,为 Bun 的合作伙伴密钥权限映射及管理面板表单新增这两个名称。密钥权限上限不等于房东同意;现有密钥/授权不会自动扩展。
- 房东认领并批准
由合作伙伴创建的房东必须认领账户并批准连接请求。请求可在密钥权限上限内包含这些权限范围;批准是唯一授权途径。
- 批准替换权限范围集合
重新批准会替换权限范围,而非合并。如需保留此前权限,必须将其包含在请求中。现有撤销及密钥/合作伙伴停用约束继续生效。
面向房东的标签
| 权限范围 | 英文标签 | 含义 |
|---|---|---|
enquiries:read | 读取咨询与报价 | 查看看房请求、相关会话及报价。 |
enquiries:write | 回应咨询 | 确认、提出其他时间或拒绝看房请求,以及发送消息。 |
扩展 P3 的英语、马来语和中文共享标签。同意页面和已连接应用使用相同的租客记录分组,并说明合作伙伴创建的物业上的咨询及租约记录。保留未知未来权限范围的可见原始名称回退。不新增合作伙伴仪表板或租客界面。
消息、归属与幂等性
身份与渠道
- 发送者
- 房东仍为
SenderUserID。 - API 渠道
- 为合作伙伴行为主体扩展标记写入,涵盖普通消息和操作生成的系统消息:
sent_via: "api"。普通会话消息保留现有行为。 - 租客信息披露
- 保留现有由 API 标记驱动的租客/房东助理披露。不增加合作伙伴专属品牌标识或发送者角色。
- 审计
- 通过现有合作伙伴审计机制记录实际合作伙伴。在上下文中保留合作伙伴行为主体;不要仅为获得标记写入而将其转换为
api_key。 - 读取副作用
- 消息 GET 和单条消息重放查找永不将消息标记为已读。
消息发送重试
复用现有执行器和 scopedIdempotencyKey,使同一合作伙伴密钥可跨房东复用客户端键而不冲突。保留方法、路径、原始请求体指纹及资源类型语义。
| 情况 | 响应 |
|---|---|
| 首次成功发送 | 201。 |
| 匹配的重放 | 原始消息、200、Idempotent-Replay: true。 |
| 键复用冲突 | 现有 409 响应。 |
| 无幂等请求头 | 现有普通消息发送行为。 |
看房操作保留现有 v1 重试行为,包括对已确认的相同时间再次确认时保持不变。不新增幂等请求头要求或后台重试系统。
错误与生命周期
- 隐藏的看房请求或会话
404 viewing_request_not_found。- 隐藏的报价
404 offer_not_found。- 错误来源
adapter/inbound/http/enquiry_error_mapper.go中的现有错误代码;复用 v1 咨询错误呈现及合作伙伴认证/授权错误。- 验证与状态转换
- 现有状态码和错误响应体保持不变。不新增未找到错误代码。
- 历史记录与写入
- 已归档的历史记录仍可读取;写入遵循现有租赁工作流规则,而非一律施加归档限制。
验证与验收
- SQL 列表/详情在不同房东、合作伙伴及测试/正式模式之间隔离,包括没有合作伙伴来源的物业。
- 即使隐藏行原本会占满整页,分页和总数也仅包含可见匹配项;现有过滤条件仍然正确。
- 密钥权限上限与有效授权两者均必需。创建房东不能配置仅可经同意授予的权限范围;已批准的连接请求可以。
- 看房操作/消息可用于已获授权的自有物业请求,且不能影响其他物业的请求。
- 普通消息与操作生成的消息携带
sent_via: "api";会话行为保持不变,并保留合作伙伴审计归属。 - 读取不会将消息标记为已读。重放返回原始消息且不产生重复;冲突失败;按房东限定作用域的键相互隔离;授权已撤销或资源不可访问时,重放不得泄露内容。
- 报价读取可用,而报价操作仍不列出。房东 v1 正式/测试模式契约保持不变。
运行时与浏览器证据
使用获准的测试环境和隔离测试数据。通过真实且已获批准的授权,实际执行看房列表/详情、一次看房操作、消息发送/重放、报价列表/详情,以及一次访问不可访问物业的尝试。
浏览器验证遵循前端浏览器规则,覆盖同意标签和管理面板权限范围选择。验证全部三种语言映射及有代表性的已渲染译文,不编写仅锁定措辞的测试。
契约文档
更新独立的 Partner OpenAPI 及现有 API 文档,涵盖路由、所需权限范围、物业可见性、仅可经同意授予的权限、归属和重试。不改变房东 v1 的公开契约。
非目标与交付边界
- 报价创建/还价/接受/拒绝/撤回;租客侧看房操作;取消已确认看房。
- 将消息标记为已读;独立收件箱 API;所有物业授权;新增联系方式披露;带合作伙伴品牌的租客界面。
- Webhooks、沙盒模式、自助注册、开发者门户及无关重构。