English

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

概要

房东和合作方可以用两种方式让房产下线:对从未有租客互动过的房产执行永久删除,其余房产则使用可撤销的归档。归档会关闭未结的咨询并通知租客,绝不影响当前或即将开始的租约,并保留每位租客的历史记录可供查阅。

  • 状态 设计已在对话中批准;书面规格待审阅
  • 项目 Partner API 项目的 P2(2026-10-03-partner-api-p1-design.md §2)
  • 涉及范围 backend/go、frontend/solidstart/apps/rental、frontend/astro/apps/rental(API 指南)
  • 入口 租赁应用(会话)、v1 房东密钥、Partner API

决策

由产品负责人于 2026-10-06 做出。

E1 · 两种操作
对从未有租客互动过的房产执行永久删除;其余所有房产使用归档(可撤销的软移除)。
E2 · 删除资格
该房产的任何房源(任何状态)都从未有过看房请求、报价、协议或租约,且没有任何租约指向该房产。是否曾经上线不影响资格。
E3 · 归档阻断条件
只有当前或即将开始的租约、或待签署的协议会拒绝归档。其余未结事项会自动关闭,并通知受影响的租客。
E4 · 恢复
已归档的房产可随时恢复。其房源保持已撤回状态。
E5 · 谁可以操作
房东可在租赁应用中,或使用拥有 properties:write 的 v1 密钥执行删除、归档和恢复。合作方只能对自己创建的房产(origin_partner_id = 该合作方)执行这些操作。
E6 · 存储与动作
归档使用新的 archived_at 列和显式动作:POST …/archive、POST …/restore,DELETE 仅表示永久删除。不复用 deleted_at。
适用哪种操作。对有租客历史的房产执行 DELETE 会返回 409 property_has_history ,调用方应改为归档。
适用哪种操作。对有租客历史的房产执行 DELETE 会返回 409 property_has_history,调用方应改为归档。
已选

A · archived_at + 显式动作

历史视图
正常可用
数据销毁
仅在显式 DELETE 时
代价
一列,加具名过滤

归档、恢复和删除是三个独立调用;只有按房产维度的“活跃”查询需要增加过滤条件。

否决

B · 单一智能 DELETE

历史视图
正常可用
数据销毁
调用方无法预知
代价
一次调用

DELETE 自行决定删除还是归档。超时后的重试可能把调用方以为已删除的房产归档;违背“DELETE 即消失”的约定。

否决

C · 复用 deleted_at

历史视图
失效
数据销毁
仅在显式 DELETE 时
代价
处处 Unscoped()

GetByID 会让协议和租约视图看不到已归档房产;修复它会颠覆默认作用域带来的安全性。

非目标

  • 不改变租约、协议、付款、交接或消息的行为与可见性。
  • 不提供批量归档或删除;不定期清除已归档房产。
  • 不清扫提交后删除失败遗留的存储对象。
  • 不改动测试数据清除(PurgeTestProperties)。
  • 不提供由管理员发起的归档或删除。

生命周期

状态

active 即 archived_at IS NULL ; archived 表示已设置该值。删除会移除该行;不存在“已删除”状态。
active 即 archived_at IS NULL;archived 表示已设置该值。删除会移除该行;不存在“已删除”状态。

删除资格(E2)

当以下各项都不存在时(包括软删除的行和所有状态),房产才可删除:

  • 其任一房源上的 rental_viewing_requests 行;
  • 其任一房源上的 rental_offers 行;
  • 其任一房源上的 rental_tenancy_agreements 行;
  • property_id 等于该房产的 rental_tenancies 行。

由一个 EXISTS 查询计算;can_delete 与 DELETE 共用该查询。不符合资格 → 409 property_has_history。

归档(E3)

否则,在锁定房产行后,于同一事务中:

  1. 撤回房源

    所有处于 draft、pending_review、rejected、live 或 suspended 的房源,通过新的状态机事件 archive 变为 withdrawn。withdraw 仍只允许从 live 撤回。

  2. 关闭看房请求

    pending 或 countered → declined,理由为“This property is no longer available”;confirmed → cancelled。

  3. 关闭报价

    pending 或 countered → declined,理由相同。

  4. 标记为已归档

    设置 archived_at = now() 和 archived_by_actor。

  5. 业务审计记录

    记录撤回的房源数、拒绝的看房数、取消的看房数和拒绝的报价数。

提交后:对每位受影响的租客发送 NotifyViewingDeclined、NotifyViewingCancelled、NotifyOfferDeclined。邮件发送出错只记录日志,不会撤销归档。对已归档房产再次归档 → 200,无变化,不发邮件。

归档期间

排除

隐藏
  • 默认房产列表(房东、v1、合作方)
  • 重复地址检测
  • 目录和仪表板本就会排除它:归档后已没有上线房源和未结请求

拒绝

409 property_archived
  • 房产更新
  • 房源创建、upsert 和提交
  • 照片上传、删除、排序和图库同步;产权证明上传
  • 按 external_ref 匹配到它的 v1 与合作方房产 upsert —— 同步绝不会重建或静默恢复它

不变

可读
  • 租约、协议、付款、交接、消息
  • 相关方仍可查看房产详情
  • GetByID 不加过滤

恢复(E4)

锁定房产行后在同一事务中:清除 archived_at 和 archived_by_actor;运行与新房产相同的重复地址检查(checkAndRaiseDuplicateFlag,usecase/property.go:470);写入业务审计记录。房源保持 withdrawn;新房源照常走审核流程。照片、产权证明和外部引用不变。恢复一个活跃房产 → 200,无变化。

删除

  1. 锁定房产行并重新检查资格。
  2. 读取照片和产权证明的存储键,包括软删除的行(Unscoped)。
  3. 写入包含房产 id 与地址快照的业务审计记录。
  4. Unscoped 硬删除:级联移除房源、照片、产权证明、外部引用、重复标记与提示,以及房源检查。
  5. 提交后:对每个键调用 PhotoStore.Remove 和 ProofStore.Delete。存储出错只记录日志,请求仍返回 204。

第二次 DELETE → 404 property_not_found。

API 与入口

所有入口由同一个 PropertyLifecycleUseCase 提供服务。

操作租赁应用(会话)v1(房东密钥)合作方(P1 入口)成功
归档POST /api/rental/properties/{id}/archivePOST /api/v1/rental/properties/{id}/archivePOST /api/partner/v1/landlords/{lid}/properties/{id}/archive200 房产
恢复POST /api/rental/properties/{id}/restorePOST /api/v1/rental/properties/{id}/restorePOST /api/partner/v1/landlords/{lid}/properties/{id}/restore200 房产
删除DELETE /api/rental/properties/{id}DELETE /api/v1/rental/properties/{id}DELETE /api/partner/v1/landlords/{lid}/properties/{id}204
  • 会话路由位于现有的 RequireLandlord 之后;所有权由 EnsureOwner 校验,不匹配 → 404 property_not_found。
  • v1 和合作方路由需要 properties:write。
  • 合作方路由还要求 origin_partner_id = 调用方合作方,否则 404 property_not_found;没有有效授权 → 404 landlord_not_found。
  • 归档和恢复按状态天然幂等;无需存储 Idempotency-Key。

列表过滤与响应字段

?archived=true
用于三个入口的 GET …/properties:只返回已归档房产。默认仍只返回活跃房产,现有调用方不受影响。
archived_at
所有入口的房产响应中可为空的时间戳 —— 新增字段。
can_delete
布尔值,仅出现在业主房产详情(租赁应用会话路由),由资格查询计算。
archive_impact
仅业主详情:{ listings, viewing_requests_declined, viewing_requests_cancelled, offers_declined } —— 此刻归档将改变的数量。归档确认框会显示这些数字。

v1 契约

纯新增:三个操作、一个响应字段、一个查询参数、三个错误码。v1_routes_test.go:1740 中把 DELETE /properties/{id} 固定为未挂载的测试将被移除。需更新:

  • backend/go/openapi/rental-v1.yaml 及其漂移测试;
  • frontend/astro/apps/rental/src/docs/landlord-api-v1.md;
  • 密钥表单中 manage-listings 的“各权限包授予内容”列表(frontend/solidstart/apps/rental/src/features/rental/api/landlord-keys.ts)新增“归档、恢复和删除房产”。

合作方契约

租赁应用(房东)

  • 房产详情(routes/landlord/[id].tsx):
    • 归档:确认框根据 archive_impact 列出将被关闭的内容(房源、N 个看房请求、N 个报价);
    • 永久删除:仅在 can_delete 为真时显示,确认时需输入房产的地址行;
    • 已归档时显示恢复;归档期间隐藏编辑操作。
  • 房产列表(routes/landlord/index.tsx):活跃 / 已归档切换;已归档行显示“Archived on {date}”。
  • 已归档房产的租约、协议、付款和交接页面照常打开。

数据

表结构(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

房源状态机:EventArchive 从 draft、pending_review、rejected、live、suspended 变为 withdrawn(仅代码改动)。

增加 archived_at IS NULL 的查询

查询位置
ListByOwner(默认;?archived=true 使用 IS NOT NULL)property_repository.go:281
ListAddressReferences:305
FindByFingerprint 及楼宇/邮编匹配:317-343
FindCrossLandlordFingerprintMatches:392
重复检查扫描与邮编候选:409-435
合作方房产列表(P1)合作方 handler

错误与并发

  • property_has_active_tenancy 归档时存在 ends_on >= today(吉隆坡日期)的租约或 awaiting_signatures 的协议 409
  • property_has_history 删除不符合资格的房产 409
  • property_archived 对已归档房产的被拒写入 409
  • property_not_found 不属于你、已删除,或合作方操作并非自己创建的房产 复用 404

v1 和合作方路由使用 v1 错误信封;会话路由使用租赁模块现有的错误格式,错误码相同。

锁与并发写入

  • 归档、恢复和删除首先对房产行执行 SELECT … FOR UPDATE。
  • 看房请求、报价和协议的创建在插入前对房产行执行 SELECT … FOR SHARE,并以 409 property_archived 拒绝已归档房产。
一种竞争结果:删除先完成,请求发现房源已不存在。如果请求先提交,删除时的重新检查会发现它并返回 409 property_has_history 。协议与归档的竞争以同样方式解决。
一种竞争结果:删除先完成,请求发现房源已不存在。如果请求先提交,删除时的重新检查会发现它并返回 409 property_has_history。协议与归档的竞争以同样方式解决。

审计

业务审计(audit_log)
每次归档、恢复和删除在同一事务中写一行,带有现有的操作者字段(actor_type、api_key_id、api_key_name,合作方路由还有 partner_id)。归档额外记录撤回的房源数、拒绝的看房数、取消的看房数和拒绝的报价数。删除额外记录房产 id 和地址快照。
行审计(audit_trails)
rental_properties 已有 fn_audit_trail(),因此房产行的归档、恢复和删除都会留痕,包括被删除行的最后状态。

现状

从代码库读取的事实(19 行)
事实位置
rental_properties 和 rental_listings 使用 gorm.DeletedAt;GORM 读取会跳过软删除的行persistence/postgresql/property_repository.go:20-51、listing_repository.go:18-47
协议和租约用例通过 GetByID 加载房产(受软删除作用域影响)application/usecase/agreement.go、usecase/tenancy.go
硬删除仅用于测试数据:HardDelete 即 Unscoped().Delete;候选排除有可达租约的房产property_repository.go:351-384、usecase/property.go:441-468
房产的外键 ON DELETE CASCADE:房源、照片、产权证明、外部引用、重复标记与提示migrations/migrator_rental.go:55,82,94,1422,1461-1462,1640-1641
房源的外键 ON DELETE CASCADE:看房请求、报价、租约协议、房源检查migrator_rental.go:247,334,379,1517
rental_tenancies.property_id 没有外键;agreement_id 为 ON DELETE RESTRICT;租约没有状态列(当前/即将开始由 starts_on/ends_on 判断)migrator_rental.go:550-561
状态集合:看房请求 pending, countered, confirmed, completed, declined, withdrawn, cancelled;报价 pending, countered, accepted, declined, withdrawn;协议 awaiting_signatures, completed, voidedmigrator_rental.go:250-251,350-352,398-399
房源状态机:withdraw 只能从 live 发起;withdrawn 和 rented 为终态;draft/pending_review/rejected/suspended 没有进入终态的路径domain/entity/listing.go:73-162
房东关闭路径与邮件:看房 Decline(NotifyViewingDeclined)、看房 Cancel(NotifyViewingCancelled)、报价 Decline(NotifyOfferDeclined)usecase/viewing_request.go:772-857、usecase/offer.go:331、port/ports.go:561-573
协议创建会拒绝冲突的租约或有效协议(PropertyTenancyOverlapError)usecase/agreement.go:158-171,256-268
目录只读取未删除房产的 live 房源listing_repository.go:408-413
仪表板统计上线房源、pending 看房、pending/countered 报价、confirmed 的即将看房persistence/postgresql/dashboard_reader.go:69-139
按房产维度的重复查询property_repository.go:305-315,317-343,392,409-435
关联房产的历史读取器landlord_agreement_reader.go:46、landlord_tenancy_reader.go:28、thread_repository.go:124、viewing_request_repository.go:287、handover_response_check_repository.go:278
存储端口:PhotoStore.Remove(ctx, key)、ProofStore.Delete(ctx, key)port/ports.go:206-217,251-265
行审计触发器存在于 rental_properties、rental_offers、rental_tenancy_agreements;rental_listings、照片、产权证明、看房请求没有migrator_rental.go:200,370,430
把 DELETE /api/v1/rental/properties/{id} 固定为未挂载的 v1 测试adapter/inbound/http/v1_routes_test.go:1740
房东房产页面frontend/solidstart/apps/rental/src/routes/landlord/index.tsx、[id].tsx
房东 API 指南frontend/astro/apps/rental/src/docs/landlord-api-v1.md

测试

集成测试在一次性的 pg-test 数据库(:55432)上运行。

资格
看房请求、报价、协议、租约任意一项单独存在即阻止删除;软删除的看房请求也会阻止;上线过但无咨询的房产可删除;can_delete 在所有情况下都与 DELETE 结果一致。
删除
级联移除房源、照片、产权证明、外部引用、标记与提示;提交后用读取的键调用存储删除;存储出错仍返回 204;第二次 DELETE 返回 404;审计记录含快照。
归档
当前租约、即将开始的租约和 awaiting_signatures 协议各自都会阻止;已结束租约不会;每个非终态房源状态 → withdrawn;pending/countered 看房被拒绝、confirmed 被取消、报价被拒绝,各发一封邮件;邮件失败不影响归档;第二次归档返回 200 且不发邮件。
归档期间
不出现在默认列表,?archived=true 时出现;不参与重复检测;所有被拒写入 → 409 property_archived;协议、租约、付款和交接视图正常加载。
恢复
房源保持已撤回;可创建新房源;重复检查重新运行;照片和引用完好。
竞争
删除对新看房请求;归档对新协议 —— 各自得到一致的单一结果。
入口
v1 需要 properties:write;合作方可操作自己的房产,对其他合作方或房东自己的房产返回 404;v1 与合作方漂移测试覆盖新路由和错误码;移除旧的 v1 未挂载 DELETE 测试。
租赁应用
归档确认、仅在 can_delete 时可见的删除、活跃/已归档切换、恢复、已归档历史页面 —— 在 UAT 上用 ego 在浏览器中验证。