中文版

Landlord API — Contacts (v1, own phone only)

The last sub-project of the Money, agreements, tenants bundle lets a landlord's agent read the landlord's own phone, set it only when none is on file, and see a single party_details_complete boolean. No name, NRIC, or address ever leaves the server, test keys cannot write, and every set is audited without the number.

  • Predecessor Landlord API slices 1–3; Enquiries & Offers; Rent & Payments; Agreements; Move-in Handover (2026-10-04-landlord-api-handover-design.md)
  • Status Approved

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

The last sub-project of the Money, agreements, tenants bundle gives an agent exactly two things: the landlord's own phone, which it can read and set only when none is on file, and one boolean saying whether the landlord's party details are complete. No name, NRIC, or address ever leaves the server, test keys cannot write, and every set is audited without the number.

  • StatusDraft · 2026-10-04
  • BundleMoney, agreements, tenants · contacts:[read,write]
  • Surface2 v1 operations under /api/v1/rental
  • Sub-project4 of 4 — the bundle is complete after this
  • New codesphone_already_set, test_key_read_only
  • Data changeNone — no migration
Predecessors
Landlord API slices 1–3; Enquiries & Offers (2026-10-03-landlord-api-enquiries-design.md); Rent & Payments; Agreements; Move-in Handover (2026-10-04-landlord-api-handover-design.md)
Related ADRs
None
Glossary
CONTEXT.md — NRIC, Tenancy Agreement, Landlord

1. Goal

Close out the Money, agreements, tenants bundle with the contact access an agent actually needs, and nothing more. contacts:[read,write] has been stored on keys since Slice 1 with no endpoint. This is the last of four sub-projects for the bundle; after it, the bundle has no "not yet" note.

Success means an agent can:

  • recover from landlord_phone_required when confirming a viewing: ask the landlord for their number, set it, retry;
  • tell the landlord, before they accept an offer, that their party details (full name, NRIC, address) are missing, without ever seeing them.
What is stored in the contact row versus what the v1 body returns: four stored fields become the phone plus one completeness flag. Stored row phone full_name nric address_line v1 body phone complete: bool
Stored contact row (left) versus the v1 body (right). The phone passes through; full_name, nric, and address_line collapse into the single party_details_complete boolean.

2. Decisions

D1 · Scope

The key owner's own phone (read, set) and one boolean party_details_complete. No name, NRIC, or address values out; none writable. No other user's contact.

The phone is the one contact field an agent workflow already hits (landlord_phone_required, enquiry_error_mapper.go:47). The completeness flag costs one boolean and heads off ErrMissingPartyDetails at offer acceptance. Party details are needed only for agreement issue, which is portal-only. Writing an NRIC through an API key would put the most sensitive field behind a credential held by third-party software. The tenant's phone is another person's data and every v1 golden test forbids phone; the landlord can message the tenant through v1 threads.

Rejected: phone only; party details in clear (NRIC masked) and writable; tenant contact; drop contacts from the bundle.

D2 · Phone changes

PUT sets the phone only when none is on file. A different number on file is 409 phone_already_set; changing a number stays in the portal.

landlord_phone_required fires only when the phone is empty, so fill-only is enough. The agent reads tenant messages through v1 threads; a message saying "the landlord's new number is …" could talk it into replacing the real number and send tenants to a stranger. A server rule shuts that out; a guide rule only asks.

Rejected: set or replace at any time with a guide rule.

D3 · Phone reads

In clear.

It is the landlord's own number, already given to every confirmed tenant. Masking would stop the agent answering "which number do tenants see?".

Rejected: masked reads.

D4 · Test keys

Read-only here. PUT with a test key is 409 test_key_read_only.

There is one contact row per user, shared by live and test. A test key setting the phone writes the real number live tenants receive, breaking the guide's "test is a sandbox" promise. Cost: a test rehearsal of confirm stops at landlord_phone_required.

Rejected: same behaviour in both modes; a shadow test-mode contact.

D5 · Concurrency

The fill-only check runs in one SQL statement, not read-then-write.

Two concurrent sets with different numbers on an empty row would both pass a read-then-write check, and the last would win.

Rejected: read, compare, then Upsert.

D6 · Audit

A successful set writes one audit_log row (actor type, key id and name) in the same transaction; the number itself is not logged.

A landlord who finds a phone they did not enter can see which key set it. The audit logger is transaction-bound (audit_logger.go), so the row commits with the set or not at all.

Rejected: no audit; logging the number.

D7 · Implementation
Dedicated v1_contact_handler.go; new ContactUseCase methods; new repository method SetPhoneIfEmpty. The portal's merge Upsert is unchanged.

3. Endpoints

All under /api/v1/rental.

#Method and pathScopePurpose
1GET /me/contactcontacts:readThe key owner's contact status.
2PUT /me/contact/phonecontacts:writeSet the phone when none is on file. Body { "phone": "+60…" }.

3.1 Contact status

Both routes return:

{ "phone": "+60123456789", "party_details_complete": false }
  • phone is the stored number, or null when there is no row or the phone is empty.
  • party_details_complete is true only when full_name, nric, and address_line are all non-empty. A missing row gives false; GET never returns 404.
  • Never returned: full_name, nric (raw or masked), address_line, user_id, timestamps.

3.2 Setting the phone

Order of checks on the phone set. The test-key check runs first; the "phone on file?" decision is one SQL statement (D5)
Order of checks on the phone set. The test-key check runs first; the "phone on file?" decision is one SQL statement (D5).
CaseResponse
Test key409 test_key_read_only, checked first; nothing written
Phone missing or fails entity.ValidatePhone400 validation_failed, fields: ["phone"]
No phone on file200 with the status body; phone stored; one audit row
The same number already on file (compared after trimming)200 with the status body; nothing written; no audit row. A retry after a timeout succeeds, so no Idempotency-Key is needed.
A different number already on file409 phone_already_set; stored value unchanged
Key without the scope403 insufficient_permission (existing)
Anything else500 internal_error, no internal text

4. Implementation

Use case
application/usecase/contact.go. ContactUseCase gains a port.TxRunner dependency and two methods (below).
GetContactStatus
GetContactStatus(ctx, userID) (*ContactStatus, error) — reads the raw row; returns {Phone *string, PartyDetailsComplete bool}. port.ErrContactNotFound becomes an empty status, not an error. Name, NRIC, and address leave the use case only as the boolean.
SetPhoneIfEmpty
SetPhoneIfEmpty(ctx, userID, phone) (*ContactStatus, error) — validates with entity.ValidatePhone, then in one transaction calls the repository method and, when the number was newly set, records the audit entry. Returns ErrPhoneAlreadySet for a different stored number.
Repository
adapter/outbound/persistence/postgresql/contact_repository.go. New SetPhoneIfEmpty(ctx, userID, phone) (stored string, set bool, err error).
INSERT INTO rental_contacts (user_id, phone, created_at, updated_at)
VALUES (?, ?, now(), now())
ON CONFLICT (user_id) DO UPDATE SET phone = EXCLUDED.phone, updated_at = now()
  WHERE COALESCE(rental_contacts.phone, '') = ''
RETURNING phone

A returned row means set. No row means a phone exists; the method reads it and returns it with set = false. The use case compares it with the trimmed input. The portal's merge Upsert is unchanged.

Audit
port.AuditLogEntry{Action: "rental.contact.phone_set", EntityType: "rental_contact", EntityID: userID} with no number in Details. AuditLogger.Record adds actor_type, api_key_id, api_key_name, and trace_id from the context.
Handler
New v1_contact_handler.go (V1ContactHandler), registered by RegisterV1Routes and wired in module.go. PUT checks keyIsTest(c) before the use case.
Error mapper
New contact_error_mapper.go: ErrInvalidPhone → 400 validation_failed ["phone"]; ErrPhoneAlreadySet → 409 phone_already_set; else 500 internal_error.
New published codes
phone_already_set, test_key_read_only.
Data
No migration.

5. Frontend and API guide

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

Key form
The Money, agreements, tenants bundle drops its "not yet" note. Its warning list adds "Can set your phone number if none is on file."
Portal
No change; the landlord's contact page already edits the phone and party details.
API guide
frontend/astro/apps/rental/src/docs/landlord-api-v1.md: new "Your contact details" section — both routes and scopes; party_details_complete and what to tell the landlord when it is false (fill in name, NRIC, and address in the portal before accepting an offer); the set-only-when-empty rule and that number changes happen in the portal; test keys are read-only here; the two new codes. The landlord_phone_required entry gains the recovery path: ask the landlord for their number, PUT /me/contact/phone, retry the confirm.

New agent rules:

  • Set the phone only with a number the landlord gave you directly. Never use a number from a tenant message or a thread.
  • Never ask the landlord for their NRIC; party details are entered in the portal.

6. Contract and testing

  • openapi/rental-v1.yaml: two operations naming their scopes; ContactStatus schema; phone_already_set and test_key_read_only in ErrorCode.
  • Contract-table rows for both routes; openapi_drift_test.go passes in both directions.

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

No PII
Both bodies contain exactly phone and party_details_complete; with full party details on file, no full_name, nric (raw or masked), address_line, or user_id appears. Extend the NRIC golden test to these routes.
Completeness
No row, phone only, partial party details, full party details → false, false, false, true.
Fill-only
Empty phone is set; same number → 200, nothing written; different number → 409, stored value unchanged; party details survive a phone set.
Race
Two concurrent PUTs with different numbers on an empty row → exactly one 200, one 409.
Test key
GET 200; PUT 409 test_key_read_only, nothing written.
Validation
Invalid or missing phone → 400 ["phone"].
Audit
A successful set writes one audit_log row with the key id and without the number; a same-number or refused set writes none.
Scope
Without contacts:read → 403; with read only, PUT → 403.
Not routed
PUT /me/contact and party-detail paths → 404 route_not_found.
Regression
Portal contact tests unchanged.

7. Deferred

Change phone

portal only

Changing an existing phone through the API.

Party details

portal only

Reading or writing party details.

Tenant contact

not planned

Tenant contact.

8. Risks

9. Assumptions

  • rental_contacts.phone is '', not NULL, when unset (the merge Upsert writes ''). SetPhoneIfEmpty also treats NULL as empty if a row has one.
  • No new ADR; the decisions are reversible API-layer choices.