English

Landlord API — Enquiries & Offers (v1)

A landlord's AI agent can read and reply to viewing requests, and read offers, through the Landlord Rental API v1 with the existing Enquiries & offers permission. The agent never sees tenant contact details and never takes a legally binding action; offers stay read-only in the portal.

  • Predecessor Landlord API slices 1–3 (foundation, idempotent sync, media sync)
  • ADRs 0056 · 0063
  • Status Approved

View source markdown ↗ generated by claude-opus-5-5 · diagrams mermaid

摘要

房东的 AI 助手可以通过 Landlord Rental API v1,使用现有的 Enquiries & offers 权限,读取并回复看房请求,以及读取报价。助手永远拿不到租客的联系方式,也不会执行任何具有法律约束力的操作:报价保持只读,在门户中处理。

  • 状态 草稿 · 2026-10-03
  • 基于 Landlord API 第 1–3 阶段(基础、幂等同步、媒体同步)
  • 权限范围 enquiries:read、enquiries:write
  • 接口面 /api/v1/rental 下新增 9 个 v1 操作
  • 涉及范围 backend/go、租房门户、租房市场文档
  • 相关 ADR 0056, 0063

目标

成功的标准是:助手能回答“有什么需要我处理?”,能在会话中回复租客,并能确认、改约或拒绝看房时间,同时永远拿不到租客联系方式,也不执行任何具有法律约束力的操作。

决策

D1 · 助手能做什么

读取 + 回复
  • 读取看房请求、会话和报价。
  • 发送会话消息。
  • 确认、改约或拒绝看房时间。
  • 报价只读:接受、还价、拒绝仍在门户中进行。

D2 · 租客个人数据

仅名字
  • 始终只返回名字。
  • 绝不返回全名、电话、邮箱、NRIC、用户 id 或精确的 address_line。

D3 · 测试密钥

跟随房源模式
  • 看房请求沿用其房源的测试/正式模式。
  • 模式不符时返回 404。不新增 is_test 列。

D4 · 向租客披露

sent_via = api
  • 由 API 密钥产生的消息和系统消息会被标记。
  • 租客看到“Sent via {房东名字}'s assistant”;房东看到“Sent via your assistant”。

D6 · 权限词汇

Bun 无改动
  • 沿用 enquiries:read / enquiries:write。

D7 · D8 · 读取与重试

安全
  • v1 读取从不设置 read_at。
  • 仅消息发送支持 Idempotency-Key。

D5 · v1 层如何构建?

在 v1_enquiry_handler.go 中新建专用 v1 处理器,调用现有用例,并拥有自己的响应 DTO 和错误映射。

v1 契约差异足够大(仅名字规则、测试/正式隔离、分页、冻结的错误信封),独立的适配层更简单;门户处理器保持不动,门户不会回归。

否决:在门户处理器中加 v1 分支(回归风险最高,且这些处理器不走错误渲染器);新增 v1 专用用例方法(把适配层策略放进共享能力层,并重复状态规则)。

接口

所有路由都挂在 /api/v1/rental 下,并经过现有的 v1 管道。

#方法与路径权限范围用途
1GET /viewing-requestsenquiries:read房东的看房请求,按最近活动排序。筛选 status、listing_id。分页。
2GET /viewing-requests/{id}enquiries:read单个请求。
3POST /viewing-requests/{id}/confirmenquiries:write{ "confirmed_time" },须为 proposed_times 之一。从 pending 开始。
4POST /viewing-requests/{id}/counterenquiries:write{ "proposed_times" },1–3 个未来的 RFC 3339 时间。从 pending 开始。
5POST /viewing-requests/{id}/declineenquiries:write{ "reason" },必填。从 pending 或 countered 开始。
6GET /viewing-requests/{id}/messagesenquiries:read会话,最早的在前,分页。不会把消息标为已读。
7POST /viewing-requests/{id}/messagesenquiries:write{ "body" },1–2,000 个字符。仅在可写时。支持 Idempotency-Key。
8GET /offersenquiries:read房东的报价。筛选 status、viewing_request_id。分页。
9GET /offers/{id}enquiries:read单个报价。

看房请求

{
  "id": "…",
  "listing_id": "…",
  "property_id": "…",
  "status": "pending | countered | confirmed | completed | declined | withdrawn | cancelled",
  "proposed_times": ["2026-10-10T10:00:00+08:00"],
  "confirmed_time": null,
  "decline_reason": null,
  "tenant": { "first_name": "Aisha" },
  "listing": { "building_name": "Arcoris", "area": "Mont Kiara", "monthly_rent": 2800 },
  "unread_count": 2,
  "last_message_at": "…",
  "created_at": "…",
  "updated_at": "…"
}

消息

{
  "id": "…",
  "viewing_request_id": "…",
  "sender": "landlord | tenant",
  "sent_via": "api | null",
  "body": "…",
  "created_at": "…",
  "read_at": null
}

sender 是角色,从不是用户 id。

报价

标识
id、viewing_request_id、listing_id
状态
pending | countered | accepted | declined | withdrawn,以及 decline_reason 和 last_actor(landlord | tenant)
条款
monthly_rent、start_date、term_months、security_deposit_months、utility_deposit_months、advance_rent_months、special_conditions
时间戳
created_at、updated_at
绝不返回
用户 id

分页

与 GET /properties 相同的 {items, pagination} 信封和 page/limit 规则:limit 默认 20,最大 100,超出范围回落到 20。

行为

访问

  1. API 密钥认证
  2. 按密钥限流
  3. 审计上下文
  4. 房东角色
  5. RequireKeyScope("enquiries", "read" | "write");缺少权限范围返回 403 insufficient_permission。

归属与模式隔离

只有当 owner_user_id 等于密钥的用户,并且房源的 is_test 等于密钥的模式时,请求才可见。其他情况一律返回 404。报价通过其看房请求的房源来判断。列表查询在 SQL 中同时应用这两个条件,使分页计数正确。

每次查找和列表查询都按房东与房源模式过滤。
每次查找和列表查询都按房东与房源模式过滤。

租客数据

v1 DTO 的 tenant.first_name 来自门户在确认前使用的同一数据源,与状态无关。RequestDetail 中的联系方式公开字段(全名、电话、address_line)从不复制到 v1 DTO。

操作

每个操作都原样调用现有用例,因此规则与门户一致。租客收到的通知与房东在门户中操作时相同。

  • confirm 从 pending;时间须在 proposed_times 中;重复确认同一时间是幂等的;房东须已登记电话 200
  • counter 从 pending;1–3 个未来时间;追加现有的系统消息 200
  • decline 从 pending 或 countered;必须填写原因;向租客发送现有的拒绝邮件 200
  • message IsThreadWritable:进行中的请求、处于报价/协议阶段的已完成请求,或租约结束后 ≤ 30 天;运行聊天检查和管理员提醒 201
看房请求状态;标有 (API) 的转换可由助手执行。
看房请求状态;标有 (API) 的转换可由助手执行。

“Sent via assistant”标签

  • 在 rental_messages 上新增可空列 sent_via TEXT('api' 或 NULL)。
  • 当请求上下文中 actor_type = api_key 时设为 'api',包括房东输入的消息,以及由 API 触发的改约和拒绝所产生的系统消息。
  • 租客会话显示“Sent via {房东名字}'s assistant”;房东会话显示“Sent via your assistant”。文案提供 en、ms、zh。
  • 现有记录保持 NULL。

读取无副作用

GET /viewing-requests/{id}/messages 使用不更新 read_at 的读取路径。助手读取不影响门户中的未读计数。

错误

所有接口使用冻结的 v1 信封 { "error": { "code", "message", "fields?" }, "request_id" }。v1 处理器把用例错误映射为错误码;内部错误文本从不返回给调用方。

沿用的错误码:validation_failed、所有 401/403/429 错误码、internal_error、auth_unavailable、rate_limit_unavailable、route_not_found、method_not_allowed、idempotency_conflict。

状态新错误码何时
404viewing_request_not_found不存在、不属于该房东,或模式不符。
404offer_not_found报价的同样规则。
400landlord_phone_required房东未登记电话时尝试确认。
409viewing_request_status_conflict当前状态不允许该操作。
409thread_closed向已不可写的会话发送消息。

validation_failed(带 fields)涵盖:confirmed_time 不在 proposed_times 中或已过去;proposed_times 为空、超过 3 个或已过去;拒绝时缺少 reason;消息 body 为空或过长;未知的 status 筛选值。

前端与文档

密钥表单
启用 Enquiries & offers(默认不勾选),移除“no endpoint yet”。“Money, agreements, tenants”保持禁用。frontend/solidstart/apps/rental
会话视图
在租客和房东会话中显示 sent_via 标签;i18n en/ms/zh。
仪表盘 API 卡片
提及回复看房请求。
API 指南
frontend/astro/apps/rental/src/docs/landlord-api-v1.md:新增“Enquiries and offers”章节(权限、仅名字规则、状态与允许的操作、“回复看房请求”流程、新错误码)。新增助手规则:拒绝看房前先与房东确认;报价在门户中处理。

契约与测试

backend/go/openapi/rental-v1.yaml 新增 9 个操作、结构定义、5 个新错误码,并在消息发送上声明 Idempotency-Key。漂移测试和契约表保证一致。

Go 测试

  • 为全部 9 个路由添加契约表行(方法、路径、权限范围、状态、响应字段)。
  • 黄金无 PII 测试:任何 v1 看房请求、消息或报价响应都不包含 phone、email、full_name、nric、tenant_user_id 或 address_line,已确认的请求也一样。
  • 隔离:其他房东的请求和模式不符的请求返回 404,且不出现在列表和计数中。
  • 读取无副作用:v1 读取后 read_at 仍为 NULL。
  • 操作:确认、改约、拒绝在允许的状态下成功,否则返回 409 viewing_request_status_conflict;landlord_phone_required;thread_closed。
  • 标签:通过密钥发送的消息存储 sent_via = 'api',通过门户发送的存储 NULL。
  • 幂等的消息发送:重放返回 Idempotent-Replay: true,且不会创建第二条记录。

前端测试

  • 租客和房东会话中的标签渲染。
  • 更新密钥表单权限包测试(Enquiries & offers 已启用、默认不勾选)。

迁移

新增一个可空列 rental_messages.sent_via。无需回填;尚无生产环境。

风险