DIY Rental Platform — Slice 3: Offers, Tenancy Agreements, and E-Signature

概览

• 阶段 第三阶段 — 报价、租约、电子签署
• 状态 设计已批准，尚未实现
• 前置条件 第二阶段（看房）必须先合并
• 解锁 第四阶段 — 租金收缴追踪
• 司法辖区 马来西亚 — ECA 2006、LPA 1976 s.37、PDPA 2010
• 新增 ADR 0058、0059、0060

依赖

第一阶段（房源列表，已合并于 58c47ceb）与第二阶段（看房，仅完成设计）

新增表

rental_offers、rental_tenancy_agreements、rental_agreement_signatures

修改的表

rental_contacts 新增 full_name、nric、address_line

新增依赖库

无 —— github.com/phpdave11/gofpdf 已被发票模块使用

新增角色令牌

无 —— 仅使用行级校验，与第一、第二阶段一致

术语表

CONTEXT.md — Offer、Tenancy Agreement、Issue、Frozen Document、Void、Special Conditions、NRIC

成功标准

• 已确认看房的租客可以提出条件，房东可以还价或接受。
• 房东接受后，平台生成一份用真实数据填充的租约 PDF。
• 双方在平台内签署，签署后的 PDF 双方均可下载。
• 签署文件具备防篡改证据：每一次签署都记录所签文件的哈希值。
• 房源以 rented 状态离开公开市场页面。
• 没有任何资金流经平台。

范围与非目标

关键决策

架构

internal/modules/rental/ 中的模块是真实代码，不是计划。第一阶段已交付六边形分层、 module.go 中的函数选项式装配、fn_audit_trail() 触发器注册（ADR-0002）， 以及一个刻意不提供签名 URL 的 storage.Storage。 第三阶段只是继续填充同样的形状，在装配层不发明任何新东西。

HTTP 接口

POST   /api/rental/viewing-requests/:id/offers     tenant creates an offer
GET    /api/rental/offers/:id                      either party
POST   /api/rental/offers/:id/counter              landlord
POST   /api/rental/offers/:id/reoffer              tenant
POST   /api/rental/offers/:id/accept               landlord → issues the agreement
POST   /api/rental/offers/:id/decline              landlord
POST   /api/rental/offers/:id/withdraw             tenant
GET    /api/rental/agreements/:id                  either party, NRIC masked
GET    /api/rental/agreements/:id/document         frozen PDF, streamed
GET    /api/rental/agreements/:id/signed-document  composite, lazily generated
POST   /api/rental/agreements/:id/sign             either party
POST   /api/rental/agreements/:id/void             either party, reason required
GET    /api/rental/me/agreements                   list, for the panel's landing view

counter 与 reoffer 是两条独立路由而不是一个 PATCH， 因为它们的授权规则与状态转移都不同；合并它们只会产生一个「根据调用者分支」的处理函数。 报价始终通过其看房请求访问，本身没有列表接口， 这让「报价挂在看房请求之下」不仅体现在数据结构里，也体现在 API 形态上。

邮件

Mailer 上共九个方法。每一个都携带指向授权 Go 处理函数的链接，绝不附带 PDF 附件。

撤回报价不发送任何邮件 —— 线程里已经显示了，而且房东并没有损失什么。

数据模型

三张新表，一张现有表新增三列。全部写在 migrator_rental.go 中。

rental_offers

id、request_id、listing_id、tenant_user_id、 landlord_user_id、monthly_rent、start_date、 term_months、security_deposit_months、 utility_deposit_months、advance_rent_months、 special_conditions、status、decline_reason、 last_actor_user_id、created_at、updated_at

CREATE UNIQUE INDEX idx_rental_offers_live
    ON rental_offers (request_id)
 WHERE status IN ('pending', 'countered');

landlord_user_id

反规范化存储，使行级授权检查无需 join。第二阶段的 rental_viewing_requests 对同一个人使用同一个列名；第一阶段已上线的 rental_properties.owner_user_id 保留原名，因为它记录的是谁拥有该房产 —— 这与谁是某次租约中的房东是不同的关系。

special_conditions

自由文本，与其他条件一样属于可协商项。还价的一方可以修改它，每次修改都会落入消息线程。

decline_reason

可为空：房东拒绝时可选填；完成时的清扫自动拒绝落选报价时，会写入一段服务端格式化的文字。刻意不设 withdraw_reason。

押金默认值

马来西亚惯例 —— 2 个月押金、0.5 个月水电押金、1 个月预付租金 —— 与租金一样可协商。绝不存储马币金额：它们是 monthly_rent × months，在渲染时计算。

校验

start_date 不得早于今天；term_months 介于 1 至 36 之间。

rental_tenancy_agreements

id、offer_id（唯一）、listing_id、property_id、 landlord_user_id、tenant_user_id、template_version、 terms（jsonb）、document_key、document_sha256、 signed_document_key、status、issued_at、 completed_at、voided_at、void_reason、 created_at、updated_at

CREATE UNIQUE INDEX idx_rental_agreements_live_listing
    ON rental_tenancy_agreements (listing_id)
 WHERE status <> 'voided';

document_key 指向冻结的未签署 PDF，其值就是该文件字节的 SHA-256。 signed_document_key 指向最终的合成文件，同样采用内容寻址， 在有人第一次下载之前为 null。

rental_agreement_signatures

id、agreement_id、signer_user_id、signer_role （landlord 或 tenant）、full_name、nric、 document_sha256、signed_at、ip、user_agent

• 在 (agreement_id, signer_user_id) 上唯一 —— 这个约束就是防重复签署的全部防线，而不是应用逻辑。
• document_sha256 按每次签署存储，因为它记录的是签署人实际看到的哈希。若两者出现不一致，说明文件被动过，这就从「无法追究」变成了「可被检测」。
• full_name 与 nric 是签署人在签署那一刻所声明的内容 —— 这与其个人资料当前的值是不同的事实。full_name 存储的是原样输入的内容，而不是用于比对的归一化形式。
• ip 与 user_agent 只存在于此处。合成 PDF 不会打印它们。

rental_contacts 与身份证号码处理

新增三列：full_name、nric、address_line。 full_name 是身份证上印刷的姓名，未必等于 users.name。 这是一个真实的列，而不是 Better Auth 数据的副本；何况 ADR-0006 本来就禁止回写 users。

身份证号码属于《2010 年个人资料保护法》下的敏感个人资料。它以明文存储 —— 整个数据库只有一个 Postgres，租赁模块里也没有别的东西加密 —— 但每一个 API 响应都会将其遮蔽为 ******-**-**34。出生日期同样被遮蔽：身份证号码的结构是 YYMMDD-PB-###G， 保留前六位就等于公开完整出生日期，而出生日期本身也是个人资料。最后两位已足以让本人确认号码是自己的。

完整值只出现在生成的 PDF 内部，而 PDF 绝不会作为邮件附件发送。 一边遮蔽 API、一边把同一个号码寄进两个邮箱，等于把整套防护措施全部作废。

审计触发器

rental_offers 与 rental_tenancy_agreements 会挂上 fn_audit_trail() 触发器，与现有的 trg_audit_rental_properties 注册在一起（ADR-0002）。rental_agreement_signatures 不挂： 那些行本来就是只追加的，触发器只会重复一遍。

状态机

报价

stateDiagram-v2
    [*] --> pending: tenant offers
    pending --> countered: landlord counters
    countered --> pending: tenant re-offers
    pending --> accepted: landlord accepts
    countered --> accepted: tenant accepts landlord terms
    pending --> declined: landlord declines
    countered --> declined: landlord declines
    pending --> withdrawn: tenant withdraws
    countered --> withdrawn: tenant withdraws
    accepted --> [*]
    declined --> [*]
    withdrawn --> [*]
    

每一次还价与再报价都会插入一行携带新条件的 rental_messages， 因此即使列上只保存当前立场，线程仍保留完整的谈判过程。

租约

stateDiagram-v2
    [*] --> awaiting_signatures: offer accepted
    awaiting_signatures --> completed: every expected signer has signed
    awaiting_signatures --> voided: either party voids
    completed --> [*]
    voided --> [*]
    

房源 —— 对第一阶段的唯一改动

stateDiagram-v2
    [*] --> draft
    draft --> pending_review: submit
    pending_review --> live: approve
    pending_review --> rejected: reject
    rejected --> pending_review: resubmit
    live --> pending_review: edit demotion
    live --> suspended: suspend
    suspended --> live: restore
    live --> withdrawn: withdraw
    live --> rented: complete
    pending_review --> rented: complete
    suspended --> rented: complete
    rented --> [*]
    withdrawn --> [*]
    

授权

不新增角色令牌，不使用 RequireOrgRole，不改动 Better Auth。仅使用行级校验，与第一、第二阶段完全一致。

流程

A —— 租客报价

1. 租客从一次已确认的看房请求进入提出报价。
2. 若租客尚未填写 full_name、nric 或 address_line，先用一个简短表单收集。
3. 表单预填房源的要价与 2 / 0.5 / 1 的押金惯例。特别条款初始为空。
4. 提交后创建一行状态为 pending 的 rental_offers。
5. 一行描述条件（包含特别条款）的 rental_messages 进入现有线程。
6. 向房东发送邮件。

还价与再报价在同一行上重复第 4 至 6 步，由 last_actor_user_id 记录当前是哪一方的条件。

B —— 房东接受，签发租约

flowchart TD
    A["1 · Read both contact rows, re-check details, snapshot into terms"] --> B["2 · Render PDF from the snapshot"]
    B --> C["3 · Take SHA-256 of the rendered bytes"]
    C --> D["4 · Upload to rental/agreements/<sha256>.pdf"]
    D --> E{"Transaction begins"}
    E --> F["5 · Offer moves to accepted · guarded by the partial unique index"]
    F --> G["6 · Agreement row written as awaiting_signatures · guarded by the double-let index"]
    G --> H["Commit · both parties emailed a link"]
    E -.->|rollback| I["Offer unchanged · orphan object is self-healing"]
    

C —— 签署

任一方都可以先签；顺序无关紧要。

1. 下载 PDF

   由一个 Go 处理函数提供，它会校验调用者是双方之一 —— 不存在公开 URL，因为 storage.Storage 根本没有签名 URL 的接口。

2. 输入、勾选、提交

   签署人输入身份证姓名与号码，并勾选同意。

3. 与快照比对，然后写入

   用例校验输入值，然后插入一行携带 document_sha256、IP 与 User-Agent 的签署记录。

4. 唯一索引拒绝第二次尝试

   防线是 (agreement_id, signer_user_id)，而不是应用逻辑。

D —— 完成

当每一位应签署人都有记录行时，签署插入操作即完成该租约。 应签署人集合由租约自身的 landlord_user_id 与 tenant_user_id 推导得出 —— 而不是硬编码的「数到二」—— 因此日后加入联名租客只需改这段推导，其他一概不动。 完成的那次插入还会设置 completed_at、清扫落选报价，并在同一事务内把房源移到 rented。

签署页会打印每一方的姓名、其所声明的身份证号码、带时区的时间戳，以及文件的 SHA-256。 它不会打印 IP 地址或 User-Agent。这些留在数据库里，若日后发生争议再行提供。 证据无论如何都在；而把 IP 打印进一份双方可能转发给中介或群聊的文件里， 等于把对方的一部分网络身份交出去，却换不到任何法律上的好处。

错误处理

测试

状态机

对报价与租约的每一条合法与非法转移做表驱动测试，包括 accepted 的终结规则与对称作废。

报价挽回

拒绝一份报价后，断言同一 request_id 上可以插入新报价；断言第二份有效报价被部分唯一索引拒绝。

黄金 PDF，两个时区

用固定的 terms 快照在两个不同 TZ 值下各渲染一次，断言 SHA-256 相同。只渲染一次的测试会通过，而最可能出问题的地方却查不出来。

合成件确定性

对合成件做同样的测试，其创建日期固定为 completed_at，签署按 signed_at 排序。

并发

同时触发两次签署；断言恰好一次完成、一次房源转移、一个 409。

重复出租

并发接受同一房源上的两份报价；断言恰好签发一份租约，另一位调用者得到 409。

签发原子性

在流程 B 的第 4 步注入存储失败；断言没有租约行且报价未变，再断言重试写入的是同一个存储键。

完成时的房源转移

分别在房源处于 live、pending_review 与 suspended 时完成租约；断言三种情况都变为 rented。断言存在未作废租约时 EventWithdraw 返回 409。

签署比对

仅大小写或空格不同的姓名可以成功签署；仅横线不同的身份证号码可以成功签署；真正不同的值被拒绝且不写入任何行。

身份证遮蔽

一个黄金测试断言没有任何接口会返回未遮蔽的身份证号码，包括出生日期的任何一位数字，与第一阶段公开房源 API 的黄金测试同一精神。

无附件

断言每一次邮件调用都携带链接，且不含 PDF 正文。

作废证据

在一份签署之后作废；断言原因为必填、签署记录行仍在，且双方都收到通知。

授权

第三位已登录用户在每一个接口上都被拒绝。

交付顺序

1. rental_contacts 新列、身份证号码写入时归一化与校验、身份证遮蔽
2. rental_offers 表、部分唯一索引，以及报价状态机
3. 报价接口、租客资料卡口、线程消息、特别条款
4. PDF 渲染器、流程 B 中的确定性固定项，以及双时区黄金测试
5. 租约签发 —— 先渲染上传，再执行流程 B 中的短事务
6. 签署、归一化比对、按推导签署人集合完成、落选报价清扫
7. 房源 rented 状态、来自三个来源的 EventComplete、撤回拦截（改动第一阶段）
8. 首次下载时生成合成 PDF
9. 邮件 —— 九个方法，仅链接
10. 面板界面

风险

这一阶段解锁了什么

第四阶段 —— 租金收缴追踪、催缴阶梯、逾期通知 PDF —— 需要一份当事人明确、租金明确、起始日期明确、 租期明确的租约。一行已完成的 rental_tenancy_agreements 正是这份记录。 这里构建的 PDF 渲染器也正是第四阶段逾期通知所要复用的； 而本阶段留下的「同一房产租期重叠」缺口，将是租期结束日期首先要堵上的问题。