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.
摘要
房东的 AI 助手可以通过 Landlord Rental API v1,使用现有的 Enquiries & offers 权限,读取并回复看房请求,以及读取报价。助手永远拿不到租客的联系方式,也不会执行任何具有法律约束力的操作:报价保持只读,在门户中处理。
目标
成功的标准是:助手能回答“有什么需要我处理?”,能在会话中回复租客,并能确认、改约或拒绝看房时间,同时永远拿不到租客联系方式,也不执行任何具有法律约束力的操作。
决策
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 管道。
| # | 方法与路径 | 权限范围 | 用途 |
|---|---|---|---|
| 1 | GET /viewing-requests | enquiries:read | 房东的看房请求,按最近活动排序。筛选 status、listing_id。分页。 |
| 2 | GET /viewing-requests/{id} | enquiries:read | 单个请求。 |
| 3 | POST /viewing-requests/{id}/confirm | enquiries:write | { "confirmed_time" },须为 proposed_times 之一。从 pending 开始。 |
| 4 | POST /viewing-requests/{id}/counter | enquiries:write | { "proposed_times" },1–3 个未来的 RFC 3339 时间。从 pending 开始。 |
| 5 | POST /viewing-requests/{id}/decline | enquiries:write | { "reason" },必填。从 pending 或 countered 开始。 |
| 6 | GET /viewing-requests/{id}/messages | enquiries:read | 会话,最早的在前,分页。不会把消息标为已读。 |
| 7 | POST /viewing-requests/{id}/messages | enquiries:write | { "body" },1–2,000 个字符。仅在可写时。支持 Idempotency-Key。 |
| 8 | GET /offers | enquiries:read | 房东的报价。筛选 status、viewing_request_id。分页。 |
| 9 | GET /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。
行为
访问
- API 密钥认证
- 按密钥限流
- 审计上下文
- 房东角色
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 -
messageIsThreadWritable:进行中的请求、处于报价/协议阶段的已完成请求,或租约结束后 ≤ 30 天;运行聊天检查和管理员提醒 201
“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。
| 状态 | 新错误码 | 何时 |
|---|---|---|
| 404 | viewing_request_not_found | 不存在、不属于该房东,或模式不符。 |
| 404 | offer_not_found | 报价的同样规则。 |
| 400 | landlord_phone_required | 房东未登记电话时尝试确认。 |
| 409 | viewing_request_status_conflict | 当前状态不允许该操作。 |
| 409 | thread_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。无需回填;尚无生产环境。