TypeSafe Jev — Payment Proof Double-Check
Extends receipt checking with a payee check against a new per-tenancy pay-to account name (plain-code exact match, Jev for non-exact) and a period check of the receipt date against the chosen charges' due dates. The verdict stays one value, and a new ai_differs_fields list tells the landlord which fields differ.
- ADRs 0068
- Status Approved
目前的凭证核对只比较金额、币种、日期和参考号。本规格新增收款人核对(凭证收款人 vs 新增的按租约保存的收款户名)和账期核对(凭证日期 vs 所选账单的到期日),并通过新的 ai_differs_fields 列表让结论自己说明原因。最终仍由房东决定;界面绝不显示"已核实"。
1. 为什么
租客上传转账凭证(转账凭证)。凭证读取器是一个 LLM 视觉模型,AI 功能键为 rental:payment_proof_extract,负责读取凭证。随后 entity.ComputeAIAgreement 把读到的内容与租客填写的内容比较。目前只检查金额、币种、日期(±48 小时)和参考号。有两个风险未被检查:
| 风险 | 示例 | 现状 |
|---|---|---|
| 收款人错误(收款人) | 钱转到了别的账户,却把凭证当作租金凭证 | 漏检。PayeeName 已读取但从未比较。 |
| 用旧凭证冲新账单 | 为 9 月租金上传了 3 月的凭证,租客填写了 3 月的日期 | 漏检。凭证日期只与租客填写的日期比较,从不与账单比较。 |
2. 交付内容
- 房东为每份租约设置收款户名(收款户名)。租客在租约页和付款页可以看到。
- 每张凭证还会核对收款人(凭证收款人 vs 租约的收款户名)和账期(账期:凭证日期 vs 所选账单的到期日)。
- 收款人比较:完全一致由普通代码判断,不完全一致(如 "TAN AH K" 对 "Tan Ah Kow Enterprise")交给 Jev。
- 结论仍是单一值。新列表
ai_differs_fields说明哪些字段不一致,房东的付款详情页会显示该列表。
3. 决策
| # | 决策 | 原因 |
|---|---|---|
| D1 | 收款人与新增的收款户名比较,而不是房东的显示名称 | 银行凭证显示的是账户持有人姓名。显示名称("Mr Tan")以及配偶或公司账户会造成大量误报。 |
| D2 | 收款户名按租约保存 | 只在现有记录上加一个字段,无需新增房东设置记录。大约一年重新填写一次。租客在同一页面可以看到。 |
| D3 | 账期检查是普通代码中的日期规则 | 每张凭证都有日期。带月份的备注(备注)常常为空。被重复使用的不匹配凭证已由重复信号(同一文件或同一参考号)捕获。 |
| D4 | 账期规则:凭证日期 <(所选账单中最早的 DueOn − 1 个月)时为 differs | 能捕获旧凭证。迟付永远不会被标记,因此补缴欠租(欠租)没有问题。 |
| D5 | 一个结论加上 ai_differs_fields | 队列仍只有一个标记,详情页说明原因。沿用现有 "Unreadable" 列表的模式。 |
| D6 | Jev 只在上传时运行一次,结果保存并在提交时复用。 | 上传后凭证收款人不会变,租约收款户名也在上传时读取。提交时只重新计算普通代码部分。 |
| D7 | 之后修改收款户名不会改变旧结果 | 结论在上传时已保存。房东可对比详情页显示的两个名称。 |
| D8 | 不新增调用上限 | 每次读取凭证最多一次 Jev 调用,而凭证读取本身已限制为每份租约每天 10 次。 |
4. 数据
一次迁移。
| 表 | 列 | 类型 | 含义 |
|---|---|---|---|
tenancies | payee_name | text NOT NULL DEFAULT '' | 收款户名。空 = 未设置。 |
payment_records | ai_differs_fields | text[] NOT NULL DEFAULT '{}' | 不一致的字段。取值:amount, currency, paid_on, reference, payee, period。 |
payment_records | ai_payee_match | text NOT NULL DEFAULT '' | 保存的收款人结果:match, mismatch, unknown,未检查收款人时为空。 |
payee_name 会去除首尾空白,最长 200 个字符。空值表示清除。
5. 后端
5.1 结论:ComputeAIAgreement
文件:backend/go/internal/modules/rental/domain/entity/payment_extraction.go。新增两个输入,并返回不一致列表:
type AgreementInput struct {
SubmittedAmountSen int
SubmittedPaidOn *time.Time
SubmittedReference string
PayeeMatch PayeeMatch // "", match, mismatch, unknown
EarliestChargeDueOn *time.Time // nil when no charge is chosen
}
func ComputeAIAgreement(in AgreementInput, ext *ReceiptExtraction) (AIAgreement, []string)
优先级不变:differs > fields_unreadable > agrees;ext 为 nil 时为 not_applicable。
| 字段 | 何时为 differs | 何时为无法读取 |
|---|---|---|
| amount, currency, paid_on, reference | 同现状 | 同现状 |
payee | PayeeMatch == mismatch | PayeeMatch == unknown |
period | ext.PaidOn 与 EarliestChargeDueOn 均已设置,且 ext.PaidOn(UTC 日)< EarliestChargeDueOn − 1 month | 从不。凭证日期无法读取时,日期已被报告为无法读取,账期检查跳过。 |
DueOn 比较。只有早于到期日一个月以上的凭证才会不一致。PayeeMatch == ""(收款户名为空)→ 跳过收款人检查,既不是 differs 也不是无法读取。- 不一致列表包含所有不一致的字段,而不只是第一个。除非结论为
differs,否则列表为空。 - 提取结果的
UnreadableFields永不修改。ai_payee_match随付款记录返回,当其为unknown时详情页显示 "Payee could not be checked"。 - 1 个月的界限是一个命名常量
PeriodEarlyLimitMonths = 1。减法使用与ScheduleMonthBoundary相同的日历月逻辑(短月份取月末,绝不直接使用AddDate)。 - 押金账单同样有
DueOn,因此适用同一规则。
两个调用方都传入新的输入。payment.go:444 是上传调用,payment.go:542 是提交调用。
5.2 收款人比较
payment_records.ai_payee_match;提交时直接读取,从不调用 Jev。- 清理两个名称:
NormalizeReference(转大写、去除多余空格)。 - 租约
payee_name为空 →PayeeMatch = ""。不发起调用。 - 凭证
PayeeName为空 →unknown。 - 清理后的名称相等 →
match。不调用 Jev。 - 否则,若已接入收款人裁判,则调用一次。概率 ≥ 提供方阈值为
match,更低为mismatch,失败为unknown。 - 未接入裁判(开关关闭)→
unknown。
5.3 Jev 收款人裁判
- 端口
port.PayeeJudge,方法Judge(ctx, PayeeJudgeInput) (float64, error)- 适配器
backend/go/internal/modules/rental/adapter/outbound/typesafe/payee_judge.go,结构与duplicate_judge.go相同- 阈值
PayeeThresholds = map[string]float64{"jev": 0.7}- 发送给 Jev 的状态
{"receipt_payee": "...", "account_name": "..."}。仅此而已:不含 ID、金额或租客数据。- Noul 问题
- 凭证收款人与账户名称是否为同一个人或公司?缩写、缺少单词、截断以及 "SDN BHD"/"ENTERPRISE" 后缀仍可视为匹配。
- 日志
- 每次调用都记录在
typesafe_calls中用于回放,与其他 Jev 功能相同。
5.4 配置与接线
TYPESAFE_RENTAL_PAYEE_ENABLED(默认false)和TYPESAFE_PAYEE_PROVIDER(默认jev),在config.go中与重复检查的配置放在一起读取。IsRentalPayeeEnabled()= 租赁开关与收款人开关均开启。module.go解析提供方,并以与重复检查裁判相同的方式构建裁判。未知提供方或没有阈值条目的提供方会导致模块启动失败。开关关闭时不构建裁判。.env.example列出这两个新变量。
5.5 收款户名 API
PUT /tenancies/:id/payee-name,请求体{"payee_name": "..."},返回租约。- 只有该租约的房东可以调用(房产的
OwnerUserID)。其他人返回 403。 - 去除空白后超过 200 个字符 → 422。
- 现有租约响应对房东和租客都包含
payee_name。
6. 前端
应用:frontend/solidstart/apps/rental。新文案使用 Paraglide 消息(m.rental_…)。
| 页面 | 路由 / 组件 | 变更 |
|---|---|---|
| 房东租约页 | /landlord/tenancies/<id>, TenancyLedgerView | 新增带"编辑"的 "Pay-to account name" 行。内联表单只有一个文本框和保存按钮,调用 setPayeeName。名称为空时提示 "Set this so receipts can be checked."。 |
| 租客租约页 | /tenant/tenancies/<id>, TenancyLedgerView | 只读的 "Pay to: …"。为空时隐藏。 |
| 租客付款页 | /tenant/tenancies/<id>/pay, PaymentWizard 第 1 步 | 表单上方同样的 "Pay to: …" 一行。为空时隐藏。 |
| 房东付款详情 | /landlord/payments/<id>, PaymentReviewDetail | 在结论标记下方显示来自 ai_differs_fields 的 "Does not match" 列表,形式同 "Unreadable" 列表。每个字段一个通俗标签,例如 payee → "Paid to a different name",period → "Receipt date is too early for this charge"。对于 payee,并排显示凭证上的名称和租约上的名称。 |
| 房东审核队列 | /landlord/payments | 无变更。 |
接线
api/payments.ts:在PaymentRecord上新增ai_differs_fields?: string[]和ai_payee_match?: '' | 'match' | 'mismatch' | 'unknown'。api/tenancies.ts:租约新增payee_name?: string,以及setPayeeName(tenancyId, name)。paymentSignals.ts:getPaymentSignalPresentation返回differsFields、hasDiffersFields和payeeUnchecked(ai_payee_match === 'unknown')。两个审核页面都从这里读取。详情页把payeeUnchecked作为 "Unreadable" 列表下方的一行显示。
7. 错误处理
| 情形 | 结果 |
|---|---|
| Jev 失败、超时或返回错误输出 | unknown → 收款人无法读取。上传成功,错误写入日志。 |
| 收款人开关关闭 | 完全一致仍然有效。不完全一致的名称 → unknown。 |
| 凭证读取器未运行(无授权、达到上限、失败) | 同现状为 not_applicable。不做收款人或账期检查。 |
非房东调用 PUT payee-name | 403 |
PUT payee-name 超过 200 个字符 | 422 |
| 上传后收款户名被修改 | 旧结果保持不变(D7)。 |
8. 测试
| 层级 | 内容 | 位置 |
|---|---|---|
| Go 单元 | ComputeAIAgreement 表驱动:收款人 ""/match/mismatch/unknown × 账期过早 / 恰在界限 / 迟付 × 现有字段。检查优先级、不一致列表列出每个不匹配项、结论不是 differs 时列表为空,以及月末取整(例如到期日 3 月 31 日,界限为 2 月 28/29 日)。 | entity/payment_extraction_test.go |
| Go 单元 | 收款人裁判的状态只包含两个名称。阈值按提供方读取。未知提供方或缺少阈值会导致启动失败。 | typesafe/payee_judge_test.go,模块测试 |
| Go 用例 | 用假裁判测试上传:完全一致零次调用,不完全一致的名称调用一次并保存结果,裁判出错则为 unknown。提交时零调用复用已保存结果,并根据最终所选账单重新计算账期。 | usecase 付款测试 |
| Go 处理器 + 迁移 | PUT payee-name:房东成功,租客 403,陌生人 403,201 个字符 → 422,空值清除名称。新列存在且带默认值。在本地 pg-test 容器(:55432)上运行。 | http/, migrations/ 测试 |
| 前端单元 | getPaymentSignalPresentation 的不一致列表。PaymentReviewDetail 显示 "Does not match" 列表,并在 payee 时显示两个名称。TenancyLedgerView 向房东显示编辑表单、向租客显示只读行,为空时隐藏。 | Vitest,与各组件放在一起 |
| 浏览器冒烟 | 在 UAT 上用 ego-browser:房东设置收款户名;租客看到 "Pay to",付款并上传收款人名称不同的凭证;房东详情页显示 "Paid to a different name"。 | 手动运行,不保存为测试 |
9. 范围之外
- 从凭证备注中读取月份。
- 用 AI 结果预填付款表单。
- 按房产或按房东设置收款户名。
- 修改审核队列的标记。
10. 交接检查笔记(2026-09-30)
交接说明列出了两个阻塞项,代码中均已解决:
- 付款第 1 步
paid_on返回 400:已在前端的73f43b55中修复。api/payments.ts中的withPaidOnTimestamp发送YYYY-MM-DDT00:00:00Z。尚未在浏览器中验证;§8 的浏览器冒烟会覆盖。 - "没有页面显示 AI 结果":
/landlord/payments和/landlord/payments/<id>已经通过getPaymentSignalPresentation显示结论。