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
概要
房东和合作方可以用两种方式让房产下线:对从未有租客互动过的房产执行永久删除,其余房产则使用可撤销的归档。归档会关闭未结的咨询并通知租客,绝不影响当前或即将开始的租约,并保留每位租客的历史记录可供查阅。
决策
由产品负责人于 2026-10-06 做出。
- E1 · 两种操作
- 对从未有租客互动过的房产执行永久删除;其余所有房产使用归档(可撤销的软移除)。
- E2 · 删除资格
- 该房产的任何房源(任何状态)都从未有过看房请求、报价、协议或租约,且没有任何租约指向该房产。是否曾经上线不影响资格。
- E3 · 归档阻断条件
- 只有当前或即将开始的租约、或待签署的协议会拒绝归档。其余未结事项会自动关闭,并通知受影响的租客。
- E4 · 恢复
- 已归档的房产可随时恢复。其房源保持已撤回状态。
- E5 · 谁可以操作
- 房东可在租赁应用中,或使用拥有
properties:write的 v1 密钥执行删除、归档和恢复。合作方只能对自己创建的房产(origin_partner_id= 该合作方)执行这些操作。 - E6 · 存储与动作
- 归档使用新的
archived_at列和显式动作:POST …/archive、POST …/restore,DELETE仅表示永久删除。不复用deleted_at。
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 表示已设置该值。删除会移除该行;不存在“已删除”状态。删除资格(E2)
当以下各项都不存在时(包括软删除的行和所有状态),房产才可删除:
- 其任一房源上的
rental_viewing_requests行; - 其任一房源上的
rental_offers行; - 其任一房源上的
rental_tenancy_agreements行; property_id等于该房产的rental_tenancies行。
由一个 EXISTS 查询计算;can_delete 与 DELETE 共用该查询。不符合资格 → 409 property_has_history。
归档(E3)
否则,在锁定房产行后,于同一事务中:
-
撤回房源
所有处于
draft、pending_review、rejected、live或suspended的房源,通过新的状态机事件archive变为withdrawn。withdraw仍只允许从 live 撤回。 -
关闭看房请求
pending或countered→declined,理由为“This property is no longer available”;confirmed→cancelled。 -
关闭报价
pending或countered→declined,理由相同。 -
标记为已归档
设置
archived_at = now()和archived_by_actor。 -
业务审计记录
记录撤回的房源数、拒绝的看房数、取消的看房数和拒绝的报价数。
提交后:对每位受影响的租客发送 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,无变化。
删除
- 锁定房产行并重新检查资格。
- 读取照片和产权证明的存储键,包括软删除的行(
Unscoped)。 - 写入包含房产 id 与地址快照的业务审计记录。
Unscoped硬删除:级联移除房源、照片、产权证明、外部引用、重复标记与提示,以及房源检查。- 提交后:对每个键调用
PhotoStore.Remove和ProofStore.Delete。存储出错只记录日志,请求仍返回204。
第二次 DELETE → 404 property_not_found。
API 与入口
所有入口由同一个 PropertyLifecycleUseCase 提供服务。
| 操作 | 租赁应用(会话) | v1(房东密钥) | 合作方(P1 入口) | 成功 |
|---|---|---|---|---|
| 归档 | POST /api/rental/properties/{id}/archive | POST /api/v1/rental/properties/{id}/archive | POST /api/partner/v1/landlords/{lid}/properties/{id}/archive | 200 房产 |
| 恢复 | POST /api/rental/properties/{id}/restore | POST /api/v1/rental/properties/{id}/restore | POST /api/partner/v1/landlords/{lid}/properties/{id}/restore | 200 房产 |
| 删除 | 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。协议与归档的竞争以同样方式解决。审计
- 业务审计(
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, voided | migrator_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在浏览器中验证。