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
房东的 AI 助手可以读取入住交接报告(Handover Report),包括租客的争议讨论串,并能构建草稿:区域、条目和照片。提交 Baseline、回复租客以及 AI 授权仍由房东本人在门户中完成。服务端计算的 readiness 区块会告诉助手何时该提醒房东去提交。
- 前置
- 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 内工作;离开该状态的每一次转换都是人的操作。starts_on − 7 至 starts_on + 3,马来西亚日期)与七天租客审阅期,示例为在 starts_on 当天提交的 Baseline。starts_on + 3 之后拒绝创建。3. 接口
全部位于 /api/v1/rental 下。读取需要 handover:read;写入需要 handover:write。
| # | 方法与路径 | 用途 |
|---|---|---|
| 1 | GET /tenancies/{id}/handover-report | 租约的入住报告,或 404 handover_report_not_found。 |
| 2 | POST /tenancies/{id}/handover-report | 创建草稿。新建时 201;重复调用时 200 并返回已有报告。 |
| 3 | GET /handover-reports/{id} | 报告(§3.1)。 |
| 4 | POST /handover-reports/{id}/areas | 创建区域 {name, sort_order}。Idempotency-Key。 |
| 5 | PATCH /handover-areas/{id} | 重命名或调整助手创建的区域顺序。 |
| 6 | DELETE /handover-areas/{id} | 删除助手创建的区域。 |
| 7 | POST /handover-areas/{id}/entries | 创建条目。Idempotency-Key。 |
| 8 | PATCH /handover-entries/{id} | 更新助手创建的条目。 |
| 9 | DELETE /handover-entries/{id} | 删除助手创建的条目。 |
| 10 | POST /handover-reports/{id}/media | Multipart file,可选 area_id 或 entry_id。Idempotency-Key 必填,并作为 upload_request_id。 |
| 11 | PATCH /handover-media/{id} | 把助手上传的暂存照片关联到区域或条目。 |
| 12 | DELETE /handover-media/{id} | 在 draft 状态下删除助手上传的照片。 |
| 13 | GET /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 不提供租客侧访问。
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。区域和条目的创建使用共享的 v1IdempotencyUseCase.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 MB | 400 validation_failed,fields: ["file"] |
上传时缺少 Idempotency-Key | 400 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(上传时必填);HandoverReportschema;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 本已要求的两项提交校验收紧。