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
Money, agreements, tenants 权限包的最后一个子项目只给助手两样东西:房东本人的电话号码(可读取,且仅在尚未登记时可设置),以及一个表示房东当事人资料是否完整的布尔值。姓名、NRIC 和地址从不离开服务端,测试密钥不能写入,每次设置都会记录审计但不记录号码本身。
- 前置
- 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、地址)不完整,而自己从不看到这些资料。
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 下。
| # | 方法与路径 | 权限 | 用途 |
|---|---|---|---|
| 1 | GET /me/contact | contacts:read | 密钥所有者的联系人状态。 |
| 2 | PUT /me/contact/phone | contacts: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 设置电话
| 情形 | 响应 |
|---|---|
| 测试密钥 | 409 test_key_read_only,最先检查;不写入任何内容 |
缺少电话或未通过 entity.ValidatePhone | 400 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依赖和两个方法(见下)。GetContactStatusGetContactStatus(ctx, userID) (*ContactStatus, error)—— 读取原始行;返回{Phone *string, PartyDetailsComplete bool}。port.ErrContactNotFound转为空状态而不是错误。姓名、NRIC 和地址只以布尔值的形式离开用例。SetPhoneIfEmptySetPhoneIfEmpty(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→ 400validation_failed["phone"];ErrPhoneAlreadySet→ 409phone_already_set;其他 → 500internal_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:两个操作并注明权限;ContactStatusschema;在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。 - 测试密钥
GET200;PUT409test_key_read_only,不写入。- 校验
- 电话无效或缺失 → 400
["phone"]。 - 审计
- 成功设置会写入一行带密钥 id、不含号码的
audit_log;相同号码或被拒绝的设置不写入。 - 权限
- 没有
contacts:read→ 403;只有read时PUT→ 403。 - 不提供路由
PUT /me/contact和当事人资料路径 → 404route_not_found。- 回归
- 门户联系人测试保持不变。
7. 推迟事项
更改电话
仅限门户通过 API 更改已有的电话。
当事人资料
仅限门户读取或写入当事人资料。
租客联系人
无计划租客联系人。
8. 风险
9. 假设
- 未设置时
rental_contacts.phone为''而不是NULL(合并式Upsert写入'')。如果某行为NULL,SetPhoneIfEmpty也视为空。 - 不新增 ADR;这些决策是可逆的 API 层选择。