中文版

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

A landlord's AI agent gets read access to the move-in Handover Report, including the tenant's dispute threads, and can build the draft: areas, entries, and photos. Submitting the Baseline, replying to the tenant, and AI consent stay the landlord's own acts in the portal. A server-computed readiness block tells the agent when to send the landlord to submit.

  • StatusDraft · 2026-10-04
  • BundleMoney, agreements, tenants · handover:[read,write]
  • Surface13 v1 operations under /api/v1/rental
  • Sub-project3 of 4 (Contacts follows)
  • Data changeNullable created_via on 3 tables
  • Portal changeSubmit refuses empty drafts and unready photos
Predecessors
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)
Related ADRs
0062 (shared notification events)
Glossary
CONTEXT.md — Handover Report, Baseline, Acceptance (of a Handover Report), Tenancy

1. Goal

A landlord's AI agent can take the move-in handover chore off the landlord through the Landlord Rental API v1, with a key holding the Money, agreements, tenants bundle (handover:[read,write]). This is the third of four sub-projects for the bundle; Contacts follows.

The agent can

v1
  • Read the tenancy's move-in Handover Report in any state, including the tenant's dispute threads, and tell the landlord what needs attention and by when.
  • Build the draft: areas, entries, and photos.
  • Tell the landlord when the draft is ready, so the landlord submits it in the portal.

Portal only

landlord's act
  • Submit the Baseline
  • Reply to or resolve a thread
  • AI consent and AI analysis

2. Decisions

D1 · Scope

Read the report in every state. Create the draft; create, update, and delete areas and entries; upload, attach, and delete photos. Submit, responses, acceptance, the final PDF, AI consent, and AI analysis stay in the portal.

Drafting is the real chore: turning a walkthrough into areas, entries, and photos. A listing can be withdrawn; a submitted Baseline cannot.

Rejected: read only (no chore removed); agent submit after confirmation; agent dispute replies.

D2 · Tenant content

Full threads: opening action, target, every comment, actor role, timestamps, and both parties' reply photos. No user ids, names, IPs, user agents, AI fields, or acceptance audit data.

Dispute comments are the review's substance and the landlord must answer them in the portal within seven days. The landlord already sees them. The v1 rule is "nothing the landlord cannot see, and no identity data". Unlike the agreement void_reason (closing text on a dead deal), the agent needs this to brief the landlord. Tenant photos show the unit, not the tenant.

Rejected: thread text without tenant photos; thread state only.

D3 · Assistant marker

created_via = 'api' on areas, entries, and media. The portal draft editor shows "Added by your assistant". Not in the Baseline, the final snapshot, their hashes, or the PDF.

Keeping submit in the portal only protects the landlord if they can see what to check. The landlord owns the content by submitting, and the Baseline records only what each party actually did; adding a second author claim would also change the canonical snapshot behind the hash.

Rejected: no marker; marker in the Baseline and PDF.

D4 · Photo input

Multipart upload only. Idempotency-Key maps onto upload_request_id. No URL import.

Handover photos are deposit evidence. A URL import invites listing photos or old albums and adds server-side fetches of arbitrary URLs. The agent already holds the files the landlord shared.

Rejected: import from URL.

D5 · Editing

The agent creates anything, but updates or deletes only items with created_via = 'api', and only while draft.

The danger in a draft is the agent deleting a photo the landlord took on site after the keys changed hands. Own-items-only removes it and still lets the agent fix its own mistakes.

Rejected: full draft control; create only. Agent-proposed edits to landlord items with landlord approval is deferred (§10).

D6 · Readiness

Server-computed readiness on the report body, from one domain function shared with submit.

Today the readiness check runs in the browser only (handover.go:1271-1302 is the server's submit check). Rules restated in the guide would drift.

Rejected: agent derives readiness from raw rows.

D7 · Empty report

A draft with no areas is not ready, and portal submit refuses it.

Submit currently passes with zero areas because no rule fails (handover.go:1271-1302). An empty Baseline is a trap for both parties. No live users, so nothing to migrate.

Rejected: report no_areas in readiness only.

D8 · Test keys
A report takes the mode of its tenancy's property. A mismatch reads as 404.
D9 · Implementation
Dedicated v1_handover_handler.go. A scoped visibility check, then the existing HandoverUseCase method. Allowlisted DTOs built from live rows (draft) or the frozen Baseline (after submission); never the raw snapshot.

Lifecycle and who acts

Handover Report states. The agent works only inside draft ; every transition out of it is a person's act
Handover Report states. The agent works only inside draft; every transition out of it is a person's act.
Submit window runs from starts_on minus 7 days to starts_on plus 3 days; after submission the tenant has a 7-day review. Submit window Review: 7 days starts_on − 7 starts_on starts_on + 3 review due
Submit window (starts_on − 7 to starts_on + 3, Malaysian dates) and the seven-day tenant review, shown for a Baseline submitted on starts_on. Creation is refused after starts_on + 3.

3. Endpoints

All under /api/v1/rental. Reads need handover:read; writes need handover:write.

#Method and pathPurpose
1GET /tenancies/{id}/handover-reportThe tenancy's move-in report, or 404 handover_report_not_found.
2POST /tenancies/{id}/handover-reportCreate the draft. 201 when created; 200 with the existing report on repeat.
3GET /handover-reports/{id}The report (§3.1).
4POST /handover-reports/{id}/areasCreate an area {name, sort_order}. Idempotency-Key.
5PATCH /handover-areas/{id}Rename or reorder an agent-made area.
6DELETE /handover-areas/{id}Delete an agent-made area.
7POST /handover-areas/{id}/entriesCreate an entry. Idempotency-Key.
8PATCH /handover-entries/{id}Update an agent-made entry.
9DELETE /handover-entries/{id}Delete an agent-made entry.
10POST /handover-reports/{id}/mediaMultipart file, optional area_id or entry_id. Idempotency-Key is required and becomes upload_request_id.
11PATCH /handover-media/{id}Attach an agent-uploaded staged photo to an area or entry.
12DELETE /handover-media/{id}Delete an agent-uploaded photo while draft.
13GET /handover-media/{id}/contentImage bytes. ?variant=thumbnail or original (default). Any photo in the report, including tenant reply photos.

The response for writes 2, 4, 5, 7, 8, 10, 11 is the affected object in the §3.1 shape (the report, an area, an entry, or a media item). Deletes return 204.

Entry bodies follow Slice 5 §6.3: entry_type is condition | inventory | access_device | meter_reading, with the same required and forbidden fields per type. meter_value is a decimal string; meter_unit is kwh | m3.

3.1 Report

{
  "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 is draft | tenant_review | finalized; finalization_reason is tenant_accepted | deadline_elapsed | null.
  • Source. While draft, areas, entries, and media come from the live rows. After submission they come from the frozen Baseline; media are the Baseline's media plus response media. The snapshot's landlord_display_name, tenant_display_name, and property_address are never read.
  • review_due_on and submit_window dates are Malaysian calendar dates (YYYY-MM-DD). submit_window is starts_on − 7 through starts_on + 3 (Slice 5 §4.3). Timestamps are RFC 3339 UTC.
  • readiness is present only while draft; otherwise null.
  • created_via is "api" or null. Baseline items read it from the live row by id; it is not in the snapshot.
  • uploaded_by is the uploader's role (landlord | tenant), derived from the uploader id against the tenancy parties.
  • Threads: status is open | resolved; last_action is one of dispute_entry | report_omission | reply | resolve | withdraw (a withdrawn thread is resolved with last_action: withdraw). opened_by, last_actor, and actor are roles. awaiting is the party who may act next on an open thread (replies alternate), null when resolved. Threads are ordered by first event time; events oldest first.
  • media_ids on an area lists photos attached to the area itself; on an entry, photos attached to the entry; on an event, its reply photos.

4. Visibility

A report is visible when its tenancy is visible under the tenancy rule: landlord_user_id = key user and the property's is_test matches the key mode. Areas, entries, and media resolve through report → tenancy. Anything not visible reads as not found. A malformed id reads as not found. There is no tenant-side v1 access.

Every v1 call resolves to the tenancy and passes the landlord + mode check before any use-case method runs
Every v1 call resolves to the tenancy and passes the landlord + mode check before any use-case method runs.

5. Writes

Each write runs the scoped visibility check, then the existing HandoverUseCase method (CreateMoveInReport, CreateArea, UpdateArea, DeleteArea, CreateEntry, UpdateEntry, DeleteEntry, UploadMedia, AttachMedia, DeleteMedia). Locking, budgets, entry-type validation, and the window rules are not duplicated.

created_via
A migration adds nullable created_via TEXT CHECK (created_via IN ('api')) to rental_handover_areas, rental_handover_entries, and rental_handover_media. The repositories set it to 'api' when middleware.GetActorTypeFromContext(ctx) == "api_key", as MessageRepository sets sent_via. Existing rows stay NULL; no backfill.
Ownership
The update and delete use-case methods gain an ownership rule: when the caller acts through an API key, the target must have created_via = 'api', else ErrHandoverItemNotEditable. Portal callers are unaffected. Every write still requires draft (ErrHandoverNotDraft → the same 409 code on v1).
Upload
Idempotency-Key is required on POST /handover-reports/{id}/media and is passed as upload_request_id. A replay returns the existing media lifecycle (Slice 5 §6.4), with Idempotent-Replay: true. Area and entry creates use the shared v1 IdempotencyUseCase.Execute.

6. Readiness

New domain function entity.EvaluateBaselineReadiness(areas, entries, media, startsOn, now) returns all problems and warnings. SubmitBaseline calls it inside its locked transaction and returns the error for the first problem, so portal behaviour is unchanged except D7.

  • no_areas The draft has no area. new (D7) Portal submit gets ErrBaselineHasNoAreas. problem
  • area_without_photo An area (area_id) has no attached, ready photo of its own. existing rule problem
  • meter_without_photo A meter-reading entry (entry_id) has no attached, ready photo. existing rule problem
  • photo_not_ready An attached photo (media_id) is uploading or failed. Slice 5 §10B requires every image ready; current code skips such photos instead of refusing. problem
  • outside_submit_window Today's Malaysian date is outside submit_window. existing rule problem
  • staged_photo_unattached A ready photo (media_id) is staged. It is excluded from the Baseline. warning

ready is true when problems is empty. baseline_images_remaining is 100 minus the report's baseline photos counted against the existing budget.

7. Errors

New published codes: 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.

CaseResponse
Report not visible, or the tenancy has no report404 handover_report_not_found
Area, entry, or media not visible or unknown404 handover_item_not_found
Report not draft, or the item is not agent-made409 handover_item_not_editable
Create before starts_on − 7409 handover_window_not_open
Create after starts_on + 3409 handover_window_closed
100-per-report or 10-per-target baseline budget409 handover_image_limit_reached
Not JPEG or PNG, HEIC, unsafe dimensions, over 5 MB400 validation_failed, fields: ["file"]
Missing Idempotency-Key on upload400 validation_failed, fields: ["Idempotency-Key"]
Wrong fields for the entry type, negative meter, bad unit, duplicate area name, both or neither attach target400 validation_failed naming the field
Upload retry after the 24-hour staged sweep410 upload_expired
Same Idempotency-Key, different body409 idempotency_conflict (existing)
Media store unavailable503 media_unavailable (existing)
Key without the scope403 insufficient_permission (existing)
Anything else500 internal_error, no internal text

8. Frontend and API guide

Separate change: frontend/solidstart/openspec/changes/landlord-api-handover-ui.

Draft editor
Areas, entries, and photos with created_via = 'api' show "Added by your assistant"; en/ms/zh via the Paraglide workflow.
Portal submit
Copy for the empty-report refusal ("Add at least one area before submitting") and for a photo still processing; en/ms/zh.
Key form
The money bundle label becomes "no contacts yet".
API guide
frontend/astro/apps/rental/src/docs/landlord-api-v1.md: new "Move-in handover" section — lifecycle, submit window, seven-day review; that the agent drafts and the landlord submits and replies in the portal; entry types and fields; meter values as decimal strings; upload, staging, attaching, budgets, Idempotency-Key; readiness; threads and awaiting; the own-items editing rule; error codes.

New agent rules:

  • Upload only photos the landlord took for this handover. Never reuse listing photos.
  • To correct a landlord's item, add a corrected one and ask the landlord to delete the original.
  • When readiness.ready is true, tell the landlord to submit in the portal before submit_window.closes_on.
  • Report every open thread where awaiting is landlord, with review_due_on.

9. Contract and testing

  • openapi/rental-v1.yaml: the 13 operations with scopes; multipart upload body; binary content response; Idempotency-Key on area create, entry create, and upload (required on upload); the HandoverReport schema; the seven new codes in ErrorCode.
  • Contract-table rows for every route; openapi_drift_test.go passes in both directions.

Integration tests on pg-test (:55432), compared against a recorded rental baseline:

Golden no-PII
Report bodies in draft, tenant_review, and finalized contain none of the §3.1 "never returned" keys. Fixture: a submitted report whose snapshot has names and address, threads from both parties with photos, an AI suggestion, and an acceptance. Extend the NRIC golden test to these routes.
Isolation
Other landlord, wrong mode, key user as tenant → 404 on the report and every child route; unknown and malformed ids → 404.
Draft vs frozen
After submission the body equals the Baseline; a live row changed directly in the database after submission does not appear.
Ownership
The agent updates and deletes its own area, entry, and photo; landlord-made items → 409 handover_item_not_editable; any write after submission → 409.
created_via
Set by API writes, NULL from portal writes; the Baseline hash of a fixed fixture is unchanged by the column.
Readiness
One case per problem and warning, window boundaries in Malaysia time, baseline_images_remaining.
Submit refactor
Existing submit tests pass unchanged; portal submit of an empty report and of a report with a processing photo now fail.
Upload
Idempotency-Key replay returns the same media with Idempotent-Replay: true; missing key → 400; budget → 409; bad file → 400; after the sweep → 410; content returns original and thumbnail for baseline and tenant reply photos.
Not routed
Submit, responses, accept, document, AI routes → 404 route_not_found.
Scope
A key with handover:read only → 403 on writes.

10. Deferred

Proposed edits

later

Agent-proposed edits to landlord items, applied after landlord approval in the portal.

Agent submit

later

Agent submit of the Baseline after explicit landlord confirmation.

Replies

later

Agent dispute replies and resolve.

URL import

later

Photo import from URL.

11. Risks

12. Assumptions

  • Thread reduction (entity.ReduceThreads) is the source of status, last_action, and awaiting; the v1 layer adds no thread rules.
  • No new ADR; the decisions are reversible API-layer choices plus two submit-validation tightenings already required by Slice 5.