English

Landlord API — Move-in Handover (v1, read + draft)

A landlord's AI agent can read the move-in Handover Report in every state, including the tenant's dispute threads, and build the draft's areas, entries, and photos through the Landlord Rental API v1. Submitting the Baseline, replying to the tenant, and AI consent stay the landlord's own acts in the portal, and a server-computed readiness block tells the agent when to send the landlord to submit.

  • Predecessor Landlord API slices 1–3; Enquiries & Offers; Rent & Payments; Agreements (2026-10-03-landlord-api-agreements-design.md); Slice 5 (2026-08-28-rental-platform-slice5-move-in-handover-design.md)
  • ADRs 0062
  • Status Approved

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

房东的 AI 助手可以读取入住交接报告(Handover Report),包括租客的争议讨论串,并能构建草稿:区域、条目和照片。提交 Baseline、回复租客以及 AI 授权仍由房东本人在门户中完成。服务端计算的 readiness 区块会告诉助手何时该提醒房东去提交。

  • 状态草稿 · 2026-10-04
  • 权限包Money, agreements, tenants · handover:[read,write]
  • 接口面/api/v1/rental 下 13 个 v1 操作
  • 子项目4 个中的第 3 个(之后是 Contacts)
  • 数据变更3 张表新增可空 created_via
  • 门户变更提交拒绝空草稿和未就绪照片
前置
Landlord API 切片 1–3;Enquiries & Offers;Rent & Payments;Agreements(2026-10-03-landlord-api-agreements-design.md);Slice 5(2026-08-28-rental-platform-slice5-move-in-handover-design.md)
相关 ADR
0062(共享通知事件)
术语表
CONTEXT.md — Handover Report、Baseline、Acceptance(交接报告的接受)、Tenancy

1. 目标

房东的 AI 助手通过 Landlord Rental API v1,用持有 Money, agreements, tenants 权限包(handover:[read,write])的密钥,替房东承担入住交接的工作。这是该权限包四个子项目中的第三个;之后是 Contacts。

助手可以

v1
  • 读取租约在任何状态下的入住交接报告,包括租客的争议讨论串,并告诉房东哪些事项需要处理、截止何时。
  • 构建草稿:区域、条目和照片。
  • 在草稿就绪时告诉房东,由房东在门户中提交。

仅限门户

房东本人操作
  • 提交 Baseline
  • 回复或解决讨论串
  • AI 授权与 AI 分析

2. 决策

D1 · 范围

可读取任何状态下的报告。可创建草稿;创建、更新、删除区域和条目;上传、关联、删除照片。提交、回复、接受、最终 PDF、AI 授权和 AI 分析留在门户中。

真正繁琐的是起草:把实地巡查整理成区域、条目和照片。房源可以下架;已提交的 Baseline 不能撤回。

已否决:只读(没有减轻任何工作);确认后由助手提交;助手回复争议。

D2 · 租客内容

完整讨论串:开启动作、目标、每条评论、行为方角色、时间戳,以及双方回复中的照片。不返回用户 id、姓名、IP、user agent、AI 字段或接受审计数据。

争议评论是审阅的实质内容,房东必须在七天内于门户中答复。房东本来就能看到这些内容。v1 的规则是"房东看不到的不给,身份数据不给"。不同于协议的 void_reason(已作废交易的结束说明),助手需要这些内容向房东汇报。租客照片拍的是房屋,不是租客本人。

已否决:只给讨论文字、不给租客照片;只给讨论状态。

D3 · 助手标记

区域、条目和媒体上加 created_via = 'api'。门户草稿编辑器显示"由你的助手添加"。不进入 Baseline、最终快照、它们的哈希或 PDF。

把提交留在门户中,只有在房东能看出需要检查什么时才有保护作用。房东通过提交成为内容的所有者,而 Baseline 只记录各方实际做过的事;再加一个作者声明还会改变哈希背后的规范快照。

已否决:不加标记;在 Baseline 和 PDF 中加标记。

D4 · 照片输入

仅支持 multipart 上传。Idempotency-Key 映射到 upload_request_id。不支持从 URL 导入。

交接照片是押金证据。URL 导入容易混入房源照片或旧相册,还会增加服务端抓取任意 URL 的风险。助手本来就持有房东分享的文件。

已否决:从 URL 导入。

D5 · 编辑

助手可以创建任何内容,但只能更新或删除 created_via = 'api' 的条目,且仅在 draft 状态下。

草稿中的风险是助手删掉房东在现场拍的照片,而此时钥匙可能已经交接。只能改自己的内容既消除了这一风险,又允许助手修正自己的错误。

已否决:完全控制草稿;只能创建。由助手提出修改、经房东批准后生效的方案已推迟(§10)。

D6 · 就绪状态

报告正文中包含服务端计算的 readiness,由与提交共用的同一个领域函数产生。

目前就绪检查只在浏览器中运行(handover.go:1271-1302 是服务端的提交检查)。在指南中重述规则会逐渐偏离。

已否决:由助手根据原始数据自行推断就绪状态。

D7 · 空报告

没有区域的草稿视为未就绪,门户提交也会拒绝。

目前零区域也能提交,因为没有任何规则失败(handover.go:1271-1302)。空 Baseline 对双方都是陷阱。尚无真实用户,无需迁移。

已否决:只在 readiness 中报告 no_areas。

D8 · 测试密钥
报告采用其租约所属物业的模式。模式不匹配视为 404。
D9 · 实现
专用 v1_handover_handler.go。先做限定范围的可见性检查,再调用现有 HandoverUseCase 方法。白名单 DTO 由实时行(草稿)或冻结的 Baseline(提交后)构建;从不使用原始快照。

生命周期与操作方

交接报告的状态。助手只在 draft 内工作;离开该状态的每一次转换都是人的操作。
交接报告的状态。助手只在 draft 内工作;离开该状态的每一次转换都是人的操作。
提交窗口从 starts_on 前 7 天到 starts_on 后 3 天;提交后租客有 7 天审阅期。 提交窗口 审阅期:7 天 starts_on − 7 starts_on starts_on + 3 审阅截止
提交窗口(starts_on − 7 至 starts_on + 3,马来西亚日期)与七天租客审阅期,示例为在 starts_on 当天提交的 Baseline。starts_on + 3 之后拒绝创建。

3. 接口

全部位于 /api/v1/rental 下。读取需要 handover:read;写入需要 handover:write。

#方法与路径用途
1GET /tenancies/{id}/handover-report租约的入住报告,或 404 handover_report_not_found。
2POST /tenancies/{id}/handover-report创建草稿。新建时 201;重复调用时 200 并返回已有报告。
3GET /handover-reports/{id}报告(§3.1)。
4POST /handover-reports/{id}/areas创建区域 {name, sort_order}。Idempotency-Key。
5PATCH /handover-areas/{id}重命名或调整助手创建的区域顺序。
6DELETE /handover-areas/{id}删除助手创建的区域。
7POST /handover-areas/{id}/entries创建条目。Idempotency-Key。
8PATCH /handover-entries/{id}更新助手创建的条目。
9DELETE /handover-entries/{id}删除助手创建的条目。
10POST /handover-reports/{id}/mediaMultipart file,可选 area_id 或 entry_id。Idempotency-Key 必填,并作为 upload_request_id。
11PATCH /handover-media/{id}把助手上传的暂存照片关联到区域或条目。
12DELETE /handover-media/{id}在 draft 状态下删除助手上传的照片。
13GET /handover-media/{id}/content图片字节。?variant=thumbnail 或 original(默认)。报告中的任何照片,包括租客回复中的照片。

写入 2、4、5、7、8、10、11 的响应是受影响对象的 §3.1 结构(报告、区域、条目或媒体项)。删除返回 204。

条目正文遵循 Slice 5 §6.3:entry_type 为 condition | inventory | access_device | meter_reading,各类型的必填与禁用字段相同。meter_value 是十进制字符串;meter_unit 为 kwh | m3。

3.1 报告

{
  "id": "…",
  "tenancy_id": "…",
  "status": "draft",
  "submitted_at": null,
  "review_due_on": null,
  "finalized_at": null,
  "finalization_reason": null,
  "baseline_sha256": null,
  "readiness": {
    "ready": false,
    "problems": [{ "code": "area_without_photo", "area_id": "…" }],
    "warnings": [{ "code": "staged_photo_unattached", "media_id": "…" }],
    "baseline_images_remaining": 63,
    "submit_window": { "opens_on": "2026-10-25", "closes_on": "2026-11-04" }
  },
  "areas": [{
    "id": "…", "name": "Master bedroom", "sort_order": 1, "created_via": "api",
    "media_ids": ["…"],
    "entries": [{
      "id": "…", "entry_type": "meter_reading", "label": "Electricity meter",
      "condition_note": null, "quantity": null,
      "meter_value": "10234.500", "meter_unit": "kwh",
      "sort_order": 1, "created_via": null, "media_ids": ["…"]
    }]
  }],
  "media": [{
    "id": "…", "status": "ready", "stage": "attached",
    "area_id": "…", "entry_id": null, "response_id": null,
    "uploaded_by": "landlord", "created_via": "api",
    "mime_type": "image/jpeg", "pixel_width": 3024, "pixel_height": 4032,
    "quality_warnings": ["low_resolution"], "uploaded_at": "2026-10-26T03:00:00Z"
  }],
  "threads": [{
    "id": "…", "target_type": "entry", "target_id": "…",
    "status": "open", "opened_by": "tenant", "last_actor": "landlord",
    "last_action": "reply", "awaiting": "tenant",
    "events": [{
      "id": "…", "actor": "tenant", "action": "dispute_entry",
      "comment": "Aircon leaks onto the floor.", "media_ids": ["…"],
      "created_at": "2026-10-27T09:00:00Z"
    }]
  }]
}
  • status 为 draft | tenant_review | finalized;finalization_reason 为 tenant_accepted | deadline_elapsed | null。
  • 数据来源。 处于 draft 时,区域、条目和媒体来自实时行。提交后来自冻结的 Baseline;媒体为 Baseline 中的媒体加上回复中的媒体。从不读取快照中的 landlord_display_name、tenant_display_name 和 property_address。
  • review_due_on 和 submit_window 的日期为马来西亚日历日期(YYYY-MM-DD)。submit_window 为 starts_on − 7 至 starts_on + 3(Slice 5 §4.3)。时间戳为 RFC 3339 UTC。
  • readiness 仅在 draft 时存在;否则为 null。
  • created_via 为 "api" 或 null。Baseline 中的项目按 id 从实时行读取它;它不在快照中。
  • uploaded_by 是上传者的角色(landlord | tenant),由上传者 id 对照租约双方得出。
  • 讨论串:status 为 open | resolved;last_action 为 dispute_entry | report_omission | reply | resolve | withdraw 之一(已撤回的讨论串为 resolved,且 last_action: withdraw)。opened_by、last_actor 和 actor 都是角色。awaiting 是在未结讨论串中下一个可以操作的一方(回复交替进行),已解决时为 null。讨论串按首个事件时间排序;事件从旧到新。
  • 区域上的 media_ids 列出直接关联到该区域的照片;条目上的列出关联到该条目的照片;事件上的列出其回复照片。

4. 可见性

当报告所属租约按租约规则可见时,报告才可见:landlord_user_id = 密钥用户,且物业的 is_test 与密钥模式一致。区域、条目和媒体通过 报告 → 租约 解析。任何不可见的内容都视为不存在。格式错误的 id 也视为不存在。v1 不提供租客侧访问。

每个 v1 调用都会解析到租约,并在任何用例方法执行前通过房东 + 模式检查。
每个 v1 调用都会解析到租约,并在任何用例方法执行前通过房东 + 模式检查。

5. 写入

每次写入先执行限定范围的可见性检查,再调用现有 HandoverUseCase 方法(CreateMoveInReport、CreateArea、UpdateArea、DeleteArea、CreateEntry、UpdateEntry、DeleteEntry、UploadMedia、AttachMedia、DeleteMedia)。加锁、额度、条目类型校验和窗口规则都不重复实现。

created_via
迁移为 rental_handover_areas、rental_handover_entries 和 rental_handover_media 添加可空的 created_via TEXT CHECK (created_via IN ('api'))。当 middleware.GetActorTypeFromContext(ctx) == "api_key" 时,仓储层将其设为 'api',与 MessageRepository 设置 sent_via 的方式相同。现有行保持 NULL;不回填。
所有权
更新和删除用例方法增加所有权规则:调用方通过 API 密钥操作时,目标必须满足 created_via = 'api',否则返回 ErrHandoverItemNotEditable。门户调用不受影响。所有写入仍要求 draft(ErrHandoverNotDraft → v1 上同一个 409 代码)。
上传
POST /handover-reports/{id}/media 必须带 Idempotency-Key,并作为 upload_request_id 传入。重放时返回已有的媒体生命周期(Slice 5 §6.4),并带 Idempotent-Replay: true。区域和条目的创建使用共享的 v1 IdempotencyUseCase.Execute。

6. 就绪状态

新的领域函数 entity.EvaluateBaselineReadiness(areas, entries, media, startsOn, now) 返回全部问题和警告。SubmitBaseline 在其加锁事务中调用它,并针对第一个问题返回错误,因此除 D7 外门户行为不变。

  • no_areas 草稿中没有区域。新增(D7) 门户提交返回 ErrBaselineHasNoAreas。 问题
  • area_without_photo 某区域(area_id)没有直接关联且已就绪的照片。现有规则 问题
  • meter_without_photo 某抄表条目(entry_id)没有关联且已就绪的照片。现有规则 问题
  • photo_not_ready 某已关联照片(media_id)处于 uploading 或 failed。Slice 5 §10B 要求所有图片就绪;当前代码会跳过这类照片而不是拒绝。 问题
  • outside_submit_window 今天的马来西亚日期不在 submit_window 内。现有规则 问题
  • staged_photo_unattached 某已就绪照片(media_id)仍在暂存。它不会进入 Baseline。 警告

当 problems 为空时 ready 为 true。baseline_images_remaining 为 100 减去按现有额度计数的报告 Baseline 照片数。

7. 错误

新增公开错误码:handover_report_not_found、handover_item_not_found、handover_item_not_editable、handover_window_not_open、handover_window_closed、handover_image_limit_reached、upload_expired。

情形响应
报告不可见,或租约没有报告404 handover_report_not_found
区域、条目或媒体不可见或不存在404 handover_item_not_found
报告不在 draft,或该项目不是助手创建的409 handover_item_not_editable
在 starts_on − 7 之前创建409 handover_window_not_open
在 starts_on + 3 之后创建409 handover_window_closed
每份报告 100 张或每个目标 10 张的 Baseline 额度409 handover_image_limit_reached
非 JPEG 或 PNG、HEIC、尺寸不安全、超过 5 MB400 validation_failed,fields: ["file"]
上传时缺少 Idempotency-Key400 validation_failed,fields: ["Idempotency-Key"]
字段与条目类型不符、读数为负、单位错误、区域名重复、关联目标同时存在或都缺失400 validation_failed,并指明字段
24 小时暂存清理后重试上传410 upload_expired
相同 Idempotency-Key、不同请求体409 idempotency_conflict(已有)
媒体存储不可用503 media_unavailable(已有)
密钥缺少权限403 insufficient_permission(已有)
其他任何情况500 internal_error,不含内部信息

8. 前端与 API 指南

独立变更:frontend/solidstart/openspec/changes/landlord-api-handover-ui。

草稿编辑器
created_via = 'api' 的区域、条目和照片显示"由你的助手添加";通过 Paraglide 流程提供 en/ms/zh。
门户提交
空报告被拒时的文案("提交前请至少添加一个区域"),以及照片仍在处理中的文案;en/ms/zh。
密钥表单
Money 权限包的标签改为 "no contacts yet"。
API 指南
frontend/astro/apps/rental/src/docs/landlord-api-v1.md:新增"入住交接"章节 —— 生命周期、提交窗口、七天审阅;助手起草、房东在门户中提交和回复;条目类型与字段;读数为十进制字符串;上传、暂存、关联、额度、Idempotency-Key;readiness;讨论串与 awaiting;只能改自己内容的规则;错误码。

新增助手规则:

  • 只上传房东为本次交接拍摄的照片。不要复用房源照片。
  • 要修正房东的条目时,添加一个修正后的条目,并请房东删除原条目。
  • 当 readiness.ready 为 true 时,提醒房东在 submit_window.closes_on 之前到门户中提交。
  • 报告每一个 awaiting 为 landlord 的未结讨论串,并附上 review_due_on。

9. 契约与测试

  • openapi/rental-v1.yaml:13 个操作及其权限;multipart 上传请求体;二进制内容响应;区域创建、条目创建和上传上的 Idempotency-Key(上传时必填);HandoverReport schema;ErrorCode 中的七个新代码。
  • 每条路由都有契约表行;openapi_drift_test.go 双向通过。

在 pg-test(:55432)上运行集成测试,并与记录的 rental 基线对比:

黄金无 PII 测试
draft、tenant_review 和 finalized 状态的报告正文都不包含 §3.1"从不返回"中的任何键。测试数据:快照中含姓名和地址的已提交报告、双方带照片的讨论串、一条 AI 建议和一次接受。把 NRIC 黄金测试扩展到这些路由。
隔离
其他房东、模式错误、密钥用户是租客 → 报告及所有子路由 404;未知和格式错误的 id → 404。
草稿与冻结
提交后正文等于 Baseline;提交后直接在数据库中修改的实时行不会出现。
所有权
助手可更新和删除自己的区域、条目和照片;房东创建的项目 → 409 handover_item_not_editable;提交后的任何写入 → 409。
created_via
API 写入时设置,门户写入为 NULL;固定测试数据的 Baseline 哈希不受该列影响。
就绪状态
每个问题和警告各一个用例,马来西亚时间的窗口边界,baseline_images_remaining。
提交重构
现有提交测试保持不变并通过;门户提交空报告以及带处理中照片的报告现在会失败。
上传
Idempotency-Key 重放返回相同媒体并带 Idempotent-Replay: true;缺少 key → 400;额度 → 409;文件无效 → 400;清理之后 → 410;内容接口对 Baseline 和租客回复照片都能返回原图和缩略图。
不提供路由
提交、回复、接受、文档、AI 路由 → 404 route_not_found。
权限
只有 handover:read 的密钥 → 写入 403。

10. 推迟事项

提议修改

以后

由助手对房东的项目提出修改,经房东在门户中批准后生效。

助手提交

以后

在房东明确确认后由助手提交 Baseline。

回复

以后

助手回复和解决争议。

URL 导入

以后

从 URL 导入照片。

11. 风险

12. 假设

  • 讨论串归约(entity.ReduceThreads)是 status、last_action 和 awaiting 的来源;v1 层不添加任何讨论串规则。
  • 不新增 ADR;这些决策是可逆的 API 层选择,加上 Slice 5 本已要求的两项提交校验收紧。