English

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.

View source markdown ↗ generated by claude-sonnet-5-5 · diagrams mermaid

目前的凭证核对只比较金额、币种、日期和参考号。本规格新增收款人核对(凭证收款人 vs 新增的按租约保存的收款户名)和账期核对(凭证日期 vs 所选账单的到期日),并通过新的 ai_differs_fields 列表让结论自己说明原因。最终仍由房东决定;界面绝不显示"已核实"。

  • 状态设计已在聊天中确认(2026-09-30),等待书面规格评审
  • 范围backend/go, frontend/solidstart/apps/rental
  • AI 功能键rental:payment_proof_extract
  • 原则AI 提取;确定性代码匹配;由人决定

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" 列表的模式。
D6Jev 只在上传时运行一次,结果保存并在提交时复用。上传后凭证收款人不会变,租约收款户名也在上传时读取。提交时只重新计算普通代码部分。
D7之后修改收款户名不会改变旧结果结论在上传时已保存。房东可对比详情页显示的两个名称。
D8不新增调用上限每次读取凭证最多一次 Jev 调用,而凭证读取本身已限制为每份租约每天 10 次。

4. 数据

一次迁移。

表列类型含义
tenanciespayee_nametext NOT NULL DEFAULT ''收款户名。空 = 未设置。
payment_recordsai_differs_fieldstext[] NOT NULL DEFAULT '{}'不一致的字段。取值:amount, currency, paid_on, reference, payee, period。
payment_recordsai_payee_matchtext 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同现状同现状
payeePayeeMatch == mismatchPayeeMatch == unknown
periodext.PaidOn 与 EarliestChargeDueOn 均已设置,且 ext.PaidOn(UTC 日)< EarliestChargeDueOn − 1 month从不。凭证日期无法读取时,日期已被报告为无法读取,账期检查跳过。
日期轴上的账期规则:凭证日期早于最早账单到期日减一个月则不一致;从该界限起(包括到期日之后)账期一致。 账期不一致 账期一致 迟付:不标记 到期日 − 1 个月 最早 DueOn 较旧凭证 凭证日期
账期规则(D4):凭证日期与所选账单中最早的 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。
上传时的收款人比较。结果保存在 payment_records.ai_payee_match;提交时直接读取,从不调用 Jev。
  1. 清理两个名称:NormalizeReference(转大写、去除多余空格)。
  2. 租约 payee_name 为空 → PayeeMatch = ""。不发起调用。
  3. 凭证 PayeeName 为空 → unknown。
  4. 清理后的名称相等 → match。不调用 Jev。
  5. 否则,若已接入收款人裁判,则调用一次。概率 ≥ 提供方阈值为 match,更低为 mismatch,失败为 unknown。
  6. 未接入裁判(开关关闭)→ 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-name403
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 显示结论。