中文版

Property Archive and Delete — P2

Adds two ways to take a rental property off the platform: permanent delete for a property no tenant ever interacted with, and a reversible archive for every other property. Archive closes open enquiries and emails tenants, never touches a current or upcoming tenancy, and keeps tenant history readable; it ships on the rental app, v1 and the Partner API.

  • Predecessor Partner API — P1: Foundation and Supply Side (2026-10-03)
  • Status Approved

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

Summary

Landlords and partners get two ways to take a property off the platform: a permanent delete for a property no tenant ever interacted with, and a reversible archive for everything else. Archive closes open enquiries and emails the tenants, never touches a current or upcoming tenancy, and keeps every tenant's history readable.

  • Status Design approved in conversation; written spec awaiting review
  • Programme P2 of the Partner API programme (2026-10-03-partner-api-p1-design.md §2)
  • Areas backend/go, frontend/solidstart/apps/rental, frontend/astro/apps/rental (API guide)
  • Surfaces Rental app (session), v1 landlord key, Partner API

Decisions

Taken by the product owner on 2026-10-06.

E1 · Two operations
Permanent delete for a property no tenant ever interacted with; archive (reversible soft removal) for every other property.
E2 · Delete eligibility
None of the property's listings, in any status, ever had a viewing request, offer, agreement or tenancy, and no tenancy names the property. Having been live does not matter.
E3 · Archive blockers
Only a current or upcoming tenancy, or an agreement awaiting signatures, refuses archive. Everything else open is closed automatically and affected tenants are emailed.
E4 · Restore
An archived property can be restored at any time. Its listings stay withdrawn.
E5 · Who
The landlord may delete, archive and restore from the rental app and with a v1 key holding properties:write. A partner may do so only for properties it created (origin_partner_id = the partner).
E6 · Storage and verbs
Archive is a new archived_at column with explicit actions: POST …/archive, POST …/restore, DELETE = permanent only. deleted_at is not reused.
Which operation applies. DELETE on a property with tenant history returns 409 property_has_history ; the caller archives instead
Which operation applies. DELETE on a property with tenant history returns 409 property_has_history; the caller archives instead.
Selected

A · archived_at + explicit verbs

History views
Keep working
Data destruction
Only on explicit DELETE
Cost
One column, named filters

Archive, restore and delete are separate calls; only property-scoped "active" queries add a filter.

Rejected

B · Single smart DELETE

History views
Keep working
Data destruction
Unpredictable to caller
Cost
One call

DELETE deletes or archives on its own. A retry after a timeout could archive what the caller expected gone; breaks "DELETE means gone".

Rejected

C · Reuse deleted_at

History views
Break
Data destruction
Only on explicit DELETE
Cost
Unscoped() everywhere

GetByID would hide archived properties from agreement and tenancy views; fixing it inverts the safety of the default scope.

Non-goals

  • No change to tenancy, agreement, payment, handover or message behaviour or visibility.
  • No bulk archive or delete; no scheduled purge of archived properties.
  • No storage sweep for objects left behind by a failed post-commit removal.
  • No change to the test-data purge (PurgeTestProperties).
  • No admin-initiated archive or delete.

Lifecycle

States

active is archived_at IS NULL ; archived has it set. Delete removes the row; there is no deleted state
active is archived_at IS NULL; archived has it set. Delete removes the row; there is no deleted state.

Delete eligibility (E2)

A property is delete-eligible when none of these exist, counting soft-deleted rows and every status:

  • a rental_viewing_requests row on any of its listings;
  • a rental_offers row on any of its listings;
  • a rental_tenancy_agreements row on any of its listings;
  • a rental_tenancies row with property_id = the property.

One EXISTS query computes it; can_delete and DELETE share it. Not eligible → 409 property_has_history.

Archive (E3)

Otherwise, in one transaction after locking the property row:

  1. Withdraw listings

    Every listing in draft, pending_review, rejected, live or suspended moves to withdrawn through a new state-machine event archive. withdraw keeps its live-only rule.

  2. Close viewing requests

    pending or countered → declined with reason "This property is no longer available"; confirmed → cancelled.

  3. Close offers

    pending or countered → declined with the same reason.

  4. Mark archived

    archived_at = now(), archived_by_actor set.

  5. Business audit row

    With counts of listings withdrawn, viewings declined, viewings cancelled, offers declined.

After commit: NotifyViewingDeclined, NotifyViewingCancelled, NotifyOfferDeclined per affected tenant. A mailer error is logged and does not undo the archive. Archiving an archived property → 200, no change, no email.

While archived

Excluded

hidden
  • Default property lists (landlord, v1, partner)
  • Duplicate-address detection
  • Catalog and dashboard already exclude it: archive left no live listing and no open request

Refused

409 property_archived
  • Property update
  • Listing create, upsert and submit
  • Photo upload, delete, reorder and gallery sync; proof upload
  • v1 and partner property upsert matching it by external_ref — a sync never recreates or silently restores

Unchanged

readable
  • Tenancies, agreements, payments, handover, messages
  • The property detail for its parties
  • GetByID is not filtered

Restore (E4)

In one transaction after locking the property row: clear archived_at and archived_by_actor; run the same duplicate-address check a new property gets (checkAndRaiseDuplicateFlag, usecase/property.go:470); business audit row. Listings stay withdrawn; a new listing goes through review as usual. Photos, proofs and external refs are unchanged. Restoring an active property → 200, no change.

Delete

  1. Lock the property row and re-run eligibility.
  2. Read photo and proof storage keys, including soft-deleted rows (Unscoped).
  3. Write the business audit row with the property id and an address snapshot.
  4. Unscoped hard delete: cascades remove listings, photos, proofs, external refs, duplicate flags and hints, and listing checks.
  5. After commit: PhotoStore.Remove and ProofStore.Delete per key. A storage error is logged and the request still returns 204.

A second DELETE → 404 property_not_found.

API and surfaces

One PropertyLifecycleUseCase serves every surface.

OperationRental app (session)v1 (landlord key)Partner (P1 surface)Success
ArchivePOST /api/rental/properties/{id}/archivePOST /api/v1/rental/properties/{id}/archivePOST /api/partner/v1/landlords/{lid}/properties/{id}/archive200 property
RestorePOST /api/rental/properties/{id}/restorePOST /api/v1/rental/properties/{id}/restorePOST /api/partner/v1/landlords/{lid}/properties/{id}/restore200 property
DeleteDELETE /api/rental/properties/{id}DELETE /api/v1/rental/properties/{id}DELETE /api/partner/v1/landlords/{lid}/properties/{id}204
  • Session routes sit behind the existing RequireLandlord; ownership by EnsureOwner, mismatch → 404 property_not_found.
  • v1 and partner routes require properties:write.
  • Partner routes also require origin_partner_id = the calling partner, else 404 property_not_found; no active grant → 404 landlord_not_found.
  • Archive and restore are idempotent by state; no Idempotency-Key storage.

List filter and response fields

?archived=true
On GET …/properties on all three surfaces: archived only. Default stays active only, so existing callers see no change.
archived_at
Nullable timestamp in the property body on all surfaces — additive.
can_delete
Boolean in the owner property detail only (rental app session route), computed by the eligibility query.
archive_impact
Owner detail only: { listings, viewing_requests_declined, viewing_requests_cancelled, offers_declined } — the counts archive would change now. The archive confirmation shows them.

v1 contract

Additive: three operations, one response field, one query parameter, three error codes. The test at v1_routes_test.go:1740 that pins DELETE /properties/{id} as unmounted is retired. Updated:

  • backend/go/openapi/rental-v1.yaml and its drift test;
  • frontend/astro/apps/rental/src/docs/landlord-api-v1.md;
  • the key form's "what each bundle grants" list for manage-listings (frontend/solidstart/apps/rental/src/features/rental/api/landlord-keys.ts) adds "archive, restore and delete properties".

Partner contract

Rental app (landlord)

  • Property detail (routes/landlord/[id].tsx):
    • Archive with a confirmation naming what will close (the listing, N viewing requests, N offers) from archive_impact;
    • Delete permanently shown only when can_delete, with a confirmation that requires typing the property's address line;
    • Restore when archived; edit actions hidden while archived.
  • Property list (routes/landlord/index.tsx): Active / Archived toggle; archived rows show "Archived on {date}".
  • Tenancy, agreement, payment and handover pages of an archived property open as today.

Data

Schema (migrator_rental.go)

rental_properties.archived_at       TIMESTAMPTZ NULL
rental_properties.archived_by_actor TEXT NULL CHECK (archived_by_actor IN ('landlord','api_key','partner'))
CHECK ((archived_at IS NULL) = (archived_by_actor IS NULL))
INDEX (owner_user_id, created_at DESC) WHERE archived_at IS NULL AND deleted_at IS NULL

Listing state machine: EventArchive from draft, pending_review, rejected, live, suspended to withdrawn (code only).

Queries that gain archived_at IS NULL

QueryLocation
ListByOwner (default; ?archived=true uses IS NOT NULL)property_repository.go:281
ListAddressReferences:305
FindByFingerprint and building/postcode match:317-343
FindCrossLandlordFingerprintMatches:392
Dup-check sweep and postcode candidates:409-435
Partner property list (P1)partner handler

Errors and concurrency

  • property_has_active_tenancy Archive with a tenancy ends_on >= today (KL) or an agreement awaiting_signatures 409
  • property_has_history Delete of a non-eligible property 409
  • property_archived A refused write on an archived property 409
  • property_not_found Not yours, already deleted, or a partner acting on a property it did not create reused 404

v1 and partner routes use the v1 envelope; session routes use the rental module's existing error shape with the same codes.

Locks and racing writers

  • Archive, restore and delete start with SELECT … FOR UPDATE on the property row.
  • Viewing-request, offer and agreement creation take SELECT … FOR SHARE on the property row before inserting, and refuse an archived property with 409 property_archived.
One race outcome: the delete wins and the request finds the listing gone. If the request commits first, the delete's re-check sees it and returns 409 property_has_history . An agreement racing an archive resolves the same way
One race outcome: the delete wins and the request finds the listing gone. If the request commits first, the delete's re-check sees it and returns 409 property_has_history. An agreement racing an archive resolves the same way.

Audit

Business audit (audit_log)
One row per archive, restore and delete, in the same transaction, with the existing actor fields (actor_type, api_key_id, api_key_name, and partner_id on partner routes). Archive adds counts of listings withdrawn, viewings declined, viewings cancelled, offers declined. Delete adds the property id and an address snapshot.
Row audit (audit_trails)
rental_properties already has fn_audit_trail(), so archive, restore and delete of the property row are trailed, including the deleted row's last state.

What exists today

Facts read from the repository (19 rows)
FactWhere
rental_properties and rental_listings use gorm.DeletedAt; GORM reads skip soft-deleted rowspersistence/postgresql/property_repository.go:20-51, listing_repository.go:18-47
Agreement and tenancy use cases load the property with GetByID (soft-delete scoped)application/usecase/agreement.go, usecase/tenancy.go
Hard delete exists for test data only: HardDelete is Unscoped().Delete; candidates exclude properties with a reachable tenancyproperty_repository.go:351-384, usecase/property.go:441-468
Foreign keys from properties ON DELETE CASCADE: listings, photos, proofs, external refs, duplicate flags and hintsmigrations/migrator_rental.go:55,82,94,1422,1461-1462,1640-1641
Foreign keys from listings ON DELETE CASCADE: viewing requests, offers, tenancy agreements, listing checksmigrator_rental.go:247,334,379,1517
rental_tenancies.property_id has no foreign key; agreement_id is ON DELETE RESTRICT; tenancies have no status column (current/upcoming by starts_on/ends_on)migrator_rental.go:550-561
Status sets: viewing requests pending, countered, confirmed, completed, declined, withdrawn, cancelled; offers pending, countered, accepted, declined, withdrawn; agreements awaiting_signatures, completed, voidedmigrator_rental.go:250-251,350-352,398-399
Listing state machine: withdraw only from live; withdrawn and rented terminal; draft/pending_review/rejected/suspended have no path to a terminal statedomain/entity/listing.go:73-162
Landlord close paths and emails: viewing Decline (NotifyViewingDeclined), viewing Cancel (NotifyViewingCancelled), offer Decline (NotifyOfferDeclined)usecase/viewing_request.go:772-857, usecase/offer.go:331, port/ports.go:561-573
Agreement creation refuses a conflicting tenancy or active agreement (PropertyTenancyOverlapError)usecase/agreement.go:158-171,256-268
Catalog reads only live listings of non-deleted propertieslisting_repository.go:408-413
Dashboard counts live listings, pending viewings, pending/countered offers, confirmed upcoming viewingspersistence/postgresql/dashboard_reader.go:69-139
Property-scoped duplicate queriesproperty_repository.go:305-315,317-343,392,409-435
History readers joining propertieslandlord_agreement_reader.go:46, landlord_tenancy_reader.go:28, thread_repository.go:124, viewing_request_repository.go:287, handover_response_check_repository.go:278
Storage ports: PhotoStore.Remove(ctx, key), ProofStore.Delete(ctx, key)port/ports.go:206-217,251-265
Row-audit trigger exists on rental_properties, rental_offers, rental_tenancy_agreements; none on rental_listings, photos, proofs, viewing requestsmigrator_rental.go:200,370,430
v1 test pinning DELETE /api/v1/rental/properties/{id} as unmountedadapter/inbound/http/v1_routes_test.go:1740
Landlord property pagesfrontend/solidstart/apps/rental/src/routes/landlord/index.tsx, [id].tsx
Landlord API guidefrontend/astro/apps/rental/src/docs/landlord-api-v1.md

Testing

Integration suites on the disposable pg-test database (:55432).

Eligibility
Each of viewing request, offer, agreement, tenancy alone blocks delete; a soft-deleted viewing request blocks; a property that went live without enquiries is eligible; can_delete equals the DELETE outcome in every case.
Delete
Cascades remove listings, photos, proofs, external refs, flags and hints; storage removal called with the read keys after commit; storage error still 204; second DELETE 404; audit row with snapshot.
Archive
Current tenancy, upcoming tenancy and awaiting_signatures agreement each block; ended tenancy does not; each non-terminal listing status → withdrawn; pending/countered viewings declined, confirmed cancelled, offers declined, one email each; mailer failure keeps the archive; second archive 200 and no email.
While archived
Absent from default list, present with ?archived=true; not matched by duplicate detection; every refused write → 409 property_archived; agreement, tenancy, payment and handover views load.
Restore
Listings stay withdrawn; new listing allowed; duplicate check reruns; photos and refs intact.
Races
Delete vs new viewing request; archive vs new agreement — one consistent outcome each.
Surfaces
v1 requires properties:write; partner acts on its own property, gets 404 on another partner's or the landlord's own; v1 drift and partner drift include the new routes and codes; the old v1 unmounted-DELETE test is removed.
Rental app
Archive confirmation, delete visible only with can_delete, Active/Archived toggle, restore, archived history pages — in the browser with ego on UAT.