English

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

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

让获授权的合作伙伴处理房源管理与租约运营之间的租客咨询:读取看房请求、回应看房时间、在会话中交换消息,以及读取租赁报价。访问仅限于调用方合作伙伴创建的物业;报价协商和接受仍不在 API 范围内。

决策概览

  • 受众白标合作伙伴,随后扩展至门户和 CRM
  • 接口/api/partner/v1
  • 操作权限看房操作和消息;报价只读
  • 边界明确同意及合作伙伴创建的物业
决策已确定的选择
操作范围与房东 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-requestsenquiries:read
GET/viewing-requests/:idenquiries:read
POST/viewing-requests/:id/confirmenquiries:write
POST/viewing-requests/:id/counterenquiries:write
POST/viewing-requests/:id/declineenquiries:write
GET/viewing-requests/:id/messagesenquiries:read
POST/viewing-requests/:id/messagesenquiries:write
GET/offersenquiries:read
GET/offers/:idenquiries:read
看房列表过滤条件
status、listing_id。
报价列表过滤条件
status、viewing_request_id。
写入请求体字段
确认:confirmed_time;改提时间:proposed_times;拒绝:reason;消息:body。
保留的契约
现有请求体验证、响应字段、时间戳、排序及分页封装。

授权与读取器边界

三项可见性谓词

  1. 房东匹配

    解析现有房源/物业关系;房东或业主必须与 scope.UserID 匹配。

  2. 模式匹配

    现有物业/房源模式规则必须与 scope.IsTest 匹配。合作伙伴请求仅限正式模式。

  3. 来源匹配

    当 scope.PartnerID 存在时,物业的 origin_partner_id 必须与其匹配。租赁应用创建的物业及其他合作伙伴创建的物业均不可见。

使用 P3 的显式 port.LandlordScope 和现有处理器作用域构造约定。不要将存储库授权隐藏在上下文值中,也不要引入第二种作用域类型。房东 v1 不含合作伙伴 ID,保留现有正式/测试模式可见性。

会话与写入访问门控

  • PeekMessages 和 GetOwnerMessage 在读取消息前通过带作用域的读取器解析父请求;重放保留消息所属会话的检查。
  • 操作辅助函数在确认/改提时间/拒绝之前使用完整作用域解析请求,并对刷新后的响应使用相同作用域。消息发送前执行相同的作用域检查。
  • 现有用例约束所有权、合法状态转换、会话可写性、消息验证及生命周期规则。
  • 来源不可变:不新增物业来源修改或锁定策略,也不新增咨询归档策略。
  • 将所有受影响的调用方和测试替身迁移至显式作用域。不保留旧签名别名或兼容包装器;门户工作流的其余部分保持不变。

消息、归属与幂等性

身份与渠道

发送者
房东仍为 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 咨询错误呈现及合作伙伴认证/授权错误。
验证与状态转换
现有状态码和错误响应体保持不变。不新增未找到错误代码。
历史记录与写入
已归档的历史记录仍可读取;写入遵循现有租赁工作流规则,而非一律施加归档限制。

验证与验收

  1. SQL 列表/详情在不同房东、合作伙伴及测试/正式模式之间隔离,包括没有合作伙伴来源的物业。
  2. 即使隐藏行原本会占满整页,分页和总数也仅包含可见匹配项;现有过滤条件仍然正确。
  3. 密钥权限上限与有效授权两者均必需。创建房东不能配置仅可经同意授予的权限范围;已批准的连接请求可以。
  4. 看房操作/消息可用于已获授权的自有物业请求,且不能影响其他物业的请求。
  5. 普通消息与操作生成的消息携带 sent_via: "api";会话行为保持不变,并保留合作伙伴审计归属。
  6. 读取不会将消息标记为已读。重放返回原始消息且不产生重复;冲突失败;按房东限定作用域的键相互隔离;授权已撤销或资源不可访问时,重放不得泄露内容。
  7. 报价读取可用,而报价操作仍不列出。房东 v1 正式/测试模式契约保持不变。

运行时与浏览器证据

使用获准的测试环境和隔离测试数据。通过真实且已获批准的授权,实际执行看房列表/详情、一次看房操作、消息发送/重放、报价列表/详情,以及一次访问不可访问物业的尝试。

浏览器验证遵循前端浏览器规则,覆盖同意标签和管理面板权限范围选择。验证全部三种语言映射及有代表性的已渲染译文,不编写仅锁定措辞的测试。

契约文档

更新独立的 Partner OpenAPI 及现有 API 文档,涵盖路由、所需权限范围、物业可见性、仅可经同意授予的权限、归属和重试。不改变房东 v1 的公开契约。

非目标与交付边界

  • 报价创建/还价/接受/拒绝/撤回;租客侧看房操作;取消已确认看房。
  • 将消息标记为已读;独立收件箱 API;所有物业授权;新增联系方式披露;带合作伙伴品牌的租客界面。
  • Webhooks、沙盒模式、自助注册、开发者门户及无关重构。