English

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

Money, agreements, tenants 权限包的最后一个子项目只给助手两样东西:房东本人的电话号码(可读取,且仅在尚未登记时可设置),以及一个表示房东当事人资料是否完整的布尔值。姓名、NRIC 和地址从不离开服务端,测试密钥不能写入,每次设置都会记录审计但不记录号码本身。

  • 状态草稿 · 2026-10-04
  • 权限包Money, agreements, tenants · contacts:[read,write]
  • 接口面/api/v1/rental 下 2 个 v1 操作
  • 子项目4 个中的第 4 个 —— 完成后权限包即完整
  • 新错误码phone_already_set、test_key_read_only
  • 数据变更无 —— 不需要迁移
前置
Landlord API 切片 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)
相关 ADR
无
术语表
CONTEXT.md — NRIC、Tenancy Agreement、Landlord

1. 目标

用助手真正需要的联系人访问权限来收尾 Money, agreements, tenants 权限包,不多给。contacts:[read,write] 自 Slice 1 起就存储在密钥上,但一直没有接口。这是该权限包四个子项目中的最后一个;完成后,权限包不再显示"尚未"提示。

成功的标准是助手能够:

  • 在确认看房遇到 landlord_phone_required 时恢复:向房东索取号码、设置号码、重试;
  • 在房东接受报价之前告诉房东其当事人资料(全名、NRIC、地址)不完整,而自己从不看到这些资料。
联系人行中存储的内容与 v1 正文返回的内容对比:四个存储字段变为电话加一个完整性标志。 存储的行 phone full_name nric address_line v1 正文 phone 完整:布尔值
存储的联系人行(左)与 v1 正文(右)对比。电话原样返回;full_name、nric 和 address_line 合并为单个 party_details_complete 布尔值。

2. 决策

D1 · 范围

密钥所有者本人的电话(读取、设置)以及一个布尔值 party_details_complete。不输出姓名、NRIC 或地址的值,也都不可写。不涉及其他用户的联系人。

电话是助手工作流中已经会碰到的唯一联系人字段(landlord_phone_required,enquiry_error_mapper.go:47)。完整性标志只多一个布尔值,就能在接受报价时避免 ErrMissingPartyDetails。当事人资料只在签发协议时需要,而签发仅限门户。通过 API 密钥写入 NRIC,会把最敏感的字段放在第三方软件持有的凭证之后。租客的电话是另一个人的数据,而每个 v1 黄金测试都禁止 phone;房东可以通过 v1 讨论串给租客发消息。

已否决:只给电话;明文返回当事人资料(NRIC 打码)并允许写入;租客联系人;从权限包中移除 contacts。

D2 · 更改电话

PUT 只在尚未登记电话时设置。已登记不同号码时返回 409 phone_already_set;更改号码留在门户中进行。

landlord_phone_required 只在电话为空时触发,因此只填空已经足够。助手会通过 v1 讨论串读取租客消息;一条写着"房东的新号码是……"的消息可能诱使它替换真实号码,把租客引向陌生人。服务端规则可以彻底挡住这一点;指南规则只是提出要求。

已否决:随时可设置或替换,仅靠指南规则约束。

D3 · 读取电话

明文返回。

这是房东本人的号码,每个已确认看房的租客都已拿到。打码会让助手无法回答"租客看到的是哪个号码?"。

已否决:打码读取。

D4 · 测试密钥

在此只读。用测试密钥 PUT 返回 409 test_key_read_only。

每个用户只有一行联系人数据,真实与测试共用。测试密钥设置电话会写入真实租客收到的号码,打破指南"测试即沙盒"的承诺。代价:用测试密钥演练确认流程时会停在 landlord_phone_required。

已否决:两种模式行为相同;为测试模式单独建一份影子联系人。

D5 · 并发

只填空检查在一条 SQL 语句中完成,而不是先读后写。

在空行上用不同号码并发设置两次,会同时通过先读后写的检查,最后写入的胜出。

已否决:先读取、比较,再 Upsert。

D6 · 审计

成功设置时在同一事务中写入一行 audit_log(行为方类型、密钥 id 和名称);不记录号码本身。

房东发现一个自己没填写的号码时,可以查到是哪个密钥设置的。审计记录器与事务绑定(audit_logger.go),因此审计行与设置一起提交,否则都不提交。

已否决:不审计;在审计中记录号码。

D7 · 实现
专用 v1_contact_handler.go;新的 ContactUseCase 方法;新的仓储方法 SetPhoneIfEmpty。门户的合并式 Upsert 不变。

3. 接口

全部位于 /api/v1/rental 下。

#方法与路径权限用途
1GET /me/contactcontacts:read密钥所有者的联系人状态。
2PUT /me/contact/phonecontacts:write在尚未登记时设置电话。请求体 { "phone": "+60…" }。

3.1 联系人状态

两条路由都返回:

{ "phone": "+60123456789", "party_details_complete": false }
  • phone 为已存储的号码;没有记录行或电话为空时为 null。
  • 只有当 full_name、nric 和 address_line 都非空时,party_details_complete 才为 true。没有记录行时为 false;GET 从不返回 404。
  • 从不返回: full_name、nric(原值或打码)、address_line、user_id、时间戳。

3.2 设置电话

设置电话时的检查顺序。测试密钥检查最先执行;"是否已登记电话"的判断在一条 SQL 语句中完成(D5)。
设置电话时的检查顺序。测试密钥检查最先执行;"是否已登记电话"的判断在一条 SQL 语句中完成(D5)。
情形响应
测试密钥409 test_key_read_only,最先检查;不写入任何内容
缺少电话或未通过 entity.ValidatePhone400 validation_failed,fields: ["phone"]
尚未登记电话200 并返回状态正文;存储电话;一行审计记录
已登记相同号码(去除首尾空白后比较)200 并返回状态正文;不写入;无审计记录。超时后重试也会成功,因此不需要 Idempotency-Key。
已登记不同号码409 phone_already_set;存储值不变
密钥缺少权限403 insufficient_permission(已有)
其他任何情况500 internal_error,不含内部信息

4. 实现

用例
application/usecase/contact.go。ContactUseCase 增加 port.TxRunner 依赖和两个方法(见下)。
GetContactStatus
GetContactStatus(ctx, userID) (*ContactStatus, error) —— 读取原始行;返回 {Phone *string, PartyDetailsComplete bool}。port.ErrContactNotFound 转为空状态而不是错误。姓名、NRIC 和地址只以布尔值的形式离开用例。
SetPhoneIfEmpty
SetPhoneIfEmpty(ctx, userID, phone) (*ContactStatus, error) —— 用 entity.ValidatePhone 校验,然后在一个事务中调用仓储方法,并在号码是新设置时记录审计。存储号码不同时返回 ErrPhoneAlreadySet。
仓储
adapter/outbound/persistence/postgresql/contact_repository.go。新增 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

返回了行表示已设置。没有返回行表示已存在电话;方法读取并返回它,同时 set = false。用例将其与去除首尾空白后的输入比较。门户的合并式 Upsert 不变。

审计
port.AuditLogEntry{Action: "rental.contact.phone_set", EntityType: "rental_contact", EntityID: userID},Details 中不含号码。AuditLogger.Record 从上下文中补充 actor_type、api_key_id、api_key_name 和 trace_id。
处理器
新的 v1_contact_handler.go(V1ContactHandler),由 RegisterV1Routes 注册并在 module.go 中装配。PUT 在调用用例之前检查 keyIsTest(c)。
错误映射
新的 contact_error_mapper.go:ErrInvalidPhone → 400 validation_failed ["phone"];ErrPhoneAlreadySet → 409 phone_already_set;其他 → 500 internal_error。
新增公开错误码
phone_already_set、test_key_read_only。
数据
不需要迁移。

5. 前端与 API 指南

独立变更:frontend/solidstart/openspec/changes/landlord-api-contacts-ui。

密钥表单
Money, agreements, tenants 权限包去掉"尚未"提示。其警告列表增加 "Can set your phone number if none is on file."
门户
不变;房东的联系人页面本来就可以编辑电话和当事人资料。
API 指南
frontend/astro/apps/rental/src/docs/landlord-api-v1.md:新增"你的联系资料"章节 —— 两条路由及其权限;party_details_complete,以及当它为 false 时如何告知房东(接受报价前在门户中填写姓名、NRIC 和地址);只在为空时设置的规则,以及更改号码需在门户中进行;测试密钥在此只读;两个新错误码。landlord_phone_required 条目增加恢复步骤:向房东索取号码、PUT /me/contact/phone、重试确认。

新增助手规则:

  • 只用房东直接告诉你的号码来设置电话。绝不使用租客消息或讨论串中的号码。
  • 绝不向房东索要 NRIC;当事人资料在门户中填写。

6. 契约与测试

  • openapi/rental-v1.yaml:两个操作并注明权限;ContactStatus schema;在 ErrorCode 中加入 phone_already_set 和 test_key_read_only。
  • 两条路由都有契约表行;openapi_drift_test.go 双向通过。

在 pg-test(:55432)上运行集成测试,并与记录的 rental 基线对比:

无 PII
两个正文都恰好只包含 phone 和 party_details_complete;在当事人资料完整时,不出现 full_name、nric(原值或打码)、address_line 或 user_id。把 NRIC 黄金测试扩展到这些路由。
完整性
无记录行、只有电话、当事人资料不完整、当事人资料完整 → false、false、false、true。
只填空
空电话被设置;相同号码 → 200,不写入;不同号码 → 409,存储值不变;设置电话后当事人资料保持不变。
竞态
在空行上用不同号码并发两次 PUT → 恰好一个 200,一个 409。
测试密钥
GET 200;PUT 409 test_key_read_only,不写入。
校验
电话无效或缺失 → 400 ["phone"]。
审计
成功设置会写入一行带密钥 id、不含号码的 audit_log;相同号码或被拒绝的设置不写入。
权限
没有 contacts:read → 403;只有 read 时 PUT → 403。
不提供路由
PUT /me/contact 和当事人资料路径 → 404 route_not_found。
回归
门户联系人测试保持不变。

7. 推迟事项

更改电话

仅限门户

通过 API 更改已有的电话。

当事人资料

仅限门户

读取或写入当事人资料。

租客联系人

无计划

租客联系人。

8. 风险

9. 假设

  • 未设置时 rental_contacts.phone 为 '' 而不是 NULL(合并式 Upsert 写入 '')。如果某行为 NULL,SetPhoneIfEmpty 也视为空。
  • 不新增 ADR;这些决策是可逆的 API 层选择。