中文版

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

Receipt checking today compares only amount, currency, date and reference. This spec adds a payee check (receipt payee vs a new per-tenancy pay-to account name) and a period check (receipt date vs the chosen charges' due dates), and makes the verdict explain itself through a new ai_differs_fields list. The landlord still decides; the UI never says "verified".

  • StatusDesign approved in chat (2026-09-30), awaiting written-spec review
  • Areabackend/go, frontend/solidstart/apps/rental
  • AI feature keyrental:payment_proof_extract
  • PrincipleAI extracts; deterministic code matches; a human decides

1. Why

A tenant uploads a transfer receipt (转账凭证). The receipt reader, an LLM vision model with AI feature key rental:payment_proof_extract, reads it. Then entity.ComputeAIAgreement compares what it read against what the tenant typed. Today that compare checks only amount, currency, date (±48h) and reference. Two risks are not checked:

RiskExampleToday
Wrong payee (收款人)Money went to another account, and the receipt is claimed as rentMissed. PayeeName is read but never compared.
Old receipt for a new chargeA March receipt is uploaded for the September rent, and the tenant types the March dateMissed. The receipt date is only compared with the typed date, never with the charge.

2. What this delivers

  • The landlord sets a pay-to account name (收款户名) on each tenancy. The tenant sees it on the tenancy page and the pay page.
  • Each receipt is also checked for payee (receipt payee vs the tenancy's pay-to name) and period (账期: receipt date vs the chosen charges' due dates).
  • The payee compare uses plain code for an exact match and Jev for a non-exact match, such as "TAN AH K" vs "Tan Ah Kow Enterprise".
  • The verdict stays one value. A new list, ai_differs_fields, says which fields differ. The landlord payment detail page shows that list.

3. Decisions

#DecisionWhy
D1The payee is compared against a new pay-to account name, not the landlord's display nameBank receipts show the account holder name. Display names ("Mr Tan") and spouse or company accounts would raise many false alarms.
D2The pay-to name is stored per tenancyOne field on an existing record, with no new landlord settings record. Retyped about once a year. The tenant sees it on the same page.
D3The period check is a date rule in plain codeEvery receipt has a date. The note (备注) with the month is often empty. A mismatched receipt that gets reused is already caught by the duplicate signals (same file or same reference).
D4Period rule: differs when receipt date < (earliest chosen charge DueOn − 1 month)Catches old receipts. Late payment is never flagged, so paying overdue rent (欠租) is fine.
D5One verdict plus ai_differs_fieldsThe queue keeps one badge. The detail page says why. Follows the existing "Unreadable" list pattern.
D6Jev runs once, at upload. The result is saved and reused at submit.The receipt payee cannot change after upload, and the tenancy pay-to name is read at upload time. Submit only recomputes plain code.
D7A later change to the pay-to name does not change old resultsThe verdict is saved at upload. The landlord can compare the two names shown on the detail page.
D8No new call capAt most one Jev call per receipt read, and receipt reads are already capped at 10 per tenancy per day.

4. Data

One migration.

TableColumnTypeMeaning
tenanciespayee_nametext NOT NULL DEFAULT ''Pay-to account name. Empty = not set.
payment_recordsai_differs_fieldstext[] NOT NULL DEFAULT '{}'Fields that differ. Values: amount, currency, paid_on, reference, payee, period.
payment_recordsai_payee_matchtext NOT NULL DEFAULT ''Saved payee result: match, mismatch, unknown, or empty when the payee was not checked.

payee_name is trimmed and at most 200 characters. An empty value clears it.

5. Backend

5.1 Verdict: ComputeAIAgreement

File: backend/go/internal/modules/rental/domain/entity/payment_extraction.go. It gets two new inputs and returns the differs list:

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)

Precedence is unchanged: differs > fields_unreadable > agrees, and not_applicable when ext is nil.

FieldDiffers whenUnreadable when
amount, currency, paid_on, referenceAs todayAs today
payeePayeeMatch == mismatchPayeeMatch == unknown
periodext.PaidOn and EarliestChargeDueOn are both set, and ext.PaidOn (UTC day) < EarliestChargeDueOn − 1 monthNever. When the receipt date is unreadable, the date is already reported unreadable and the period is skipped.
Period rule on a date axis: a receipt dated before the earliest charge due date minus one month differs; a receipt from that limit onward, including after the due date, does not differ on period. Period differs Period agrees Late: not flagged Due − 1 month Earliest DueOn Older receipt Receipt date
Period rule (D4): receipt date against the earliest chosen charge's DueOn. Only receipts older than one month before the due date differ.
  • PayeeMatch == "" (the pay-to name is empty) → the payee is skipped. It is neither differs nor unreadable.
  • The differs list holds every field that differs, not only the first one. The list is empty unless the verdict is differs.
  • The extraction's UnreadableFields is never changed. ai_payee_match is returned on the payment record, and the detail page shows "Payee could not be checked" when it is unknown.
  • The 1-month limit is one named constant, PeriodEarlyLimitMonths = 1. It is subtracted with the same calendar-month logic as ScheduleMonthBoundary (clamping on short months, never raw AddDate).
  • A deposit charge also has a DueOn, so the same rule applies to it.

Both callers pass the new input. payment.go:444 is the upload call and payment.go:542 is the submit call.

5.2 Payee compare

Payee compare at upload. The result is saved in payment_records.ai_payee_match; submit reads it and never calls Jev.
Payee compare at upload. The result is saved in payment_records.ai_payee_match; submit reads it and never calls Jev.
  1. Clean up both names: NormalizeReference (upper-case, extra spaces removed).
  2. The tenancy payee_name is empty → PayeeMatch = "". No call is made.
  3. The receipt PayeeName is empty → unknown.
  4. The cleaned names are equal → match. No Jev call.
  5. Otherwise, if a payee judge is wired, call it once. A probability ≥ the provider threshold gives match, a lower probability gives mismatch, and a failure gives unknown.
  6. No judge is wired (switch off) → unknown.

5.3 Jev payee judge

Port
port.PayeeJudge with Judge(ctx, PayeeJudgeInput) (float64, error)
Adapter
backend/go/internal/modules/rental/adapter/outbound/typesafe/payee_judge.go, shaped like duplicate_judge.go
Thresholds
PayeeThresholds = map[string]float64{"jev": 0.7}
State sent to Jev
{"receipt_payee": "...", "account_name": "..."}. Nothing else: no IDs, amounts or tenant data.
Noul question
Is the receipt payee the same person or company as the account name? Initials, missing words, truncation and "SDN BHD"/"ENTERPRISE" suffixes may still match.
Logging
Every call is logged in typesafe_calls for replay, as for the other Jev features.

5.4 Config and wiring

  • TYPESAFE_RENTAL_PAYEE_ENABLED (default false) and TYPESAFE_PAYEE_PROVIDER (default jev), read in config.go next to the duplicate values.
  • IsRentalPayeeEnabled() = rental switch and payee switch both on.
  • module.go resolves the provider and builds the judge the same way as the duplicate judge. An unknown provider, or one with no threshold entry, fails module start-up. With the switch off, no judge is built.
  • .env.example lists both new variables.

5.5 Pay-to name API

  • PUT /tenancies/:id/payee-name, body {"payee_name": "..."}, returns the tenancy.
  • Only the landlord of that tenancy may call it (the property's OwnerUserID). Anyone else gets 403.
  • More than 200 characters after trimming → 422.
  • The existing tenancy responses include payee_name for both landlord and tenant.

6. Frontend

App: frontend/solidstart/apps/rental. New text uses Paraglide messages (m.rental_…).

ScreenRoute / componentChange
Landlord tenancy page/landlord/tenancies/<id>, TenancyLedgerViewA "Pay-to account name" row with Edit. The inline form has one text field and Save, and calls setPayeeName. When the name is empty, a hint says "Set this so receipts can be checked."
Tenant tenancy page/tenant/tenancies/<id>, TenancyLedgerViewRead-only "Pay to: …". Hidden when empty.
Tenant pay page/tenant/tenancies/<id>/pay, PaymentWizard step 1The same "Pay to: …" line above the form. Hidden when empty.
Landlord payment detail/landlord/payments/<id>, PaymentReviewDetailA "Does not match" list from ai_differs_fields, shown under the verdict badge like the "Unreadable" list. One plain label per field, e.g. payee → "Paid to a different name", period → "Receipt date is too early for this charge". For payee, the receipt name and the tenancy name are shown side by side.
Landlord review queue/landlord/paymentsNo change.

Plumbing

  • api/payments.ts: ai_differs_fields?: string[] and ai_payee_match?: '' | 'match' | 'mismatch' | 'unknown' on PaymentRecord.
  • api/tenancies.ts: payee_name?: string on the tenancy, plus setPayeeName(tenancyId, name).
  • paymentSignals.ts: getPaymentSignalPresentation returns differsFields, hasDiffersFields and payeeUnchecked (ai_payee_match === 'unknown'). Both review screens read it from there. The detail page shows payeeUnchecked as one more line under the "Unreadable" list.

7. Error handling

CaseResult
Jev fails, times out or returns bad outputunknown → payee unreadable. The upload succeeds and the error is logged.
Payee switch offExact match still works. A non-exact name → unknown.
Receipt reader not run (no consent, cap, failure)not_applicable, as today. No payee or period check.
PUT payee-name by a non-landlord403
PUT payee-name longer than 200 characters422
The pay-to name changes after uploadOld results stay (D7).

8. Testing

LevelWhatWhere
Go unitComputeAIAgreement table: payee ""/match/mismatch/unknown × period too early / exactly at the limit / late × the existing fields. Checks the precedence, that the differs list names every mismatch, that the list is empty when the verdict is not differs, and month-end clamping (e.g. a due date of 31 Mar gives a limit of 28/29 Feb).entity/payment_extraction_test.go
Go unitThe payee judge state holds only the two names. The threshold is read per provider. An unknown provider or a missing threshold fails start-up.typesafe/payee_judge_test.go, module tests
Go usecaseUpload with a fake judge: an exact match makes zero calls, a non-exact name makes one call and saves the result, and a judge error gives unknown. Submit reuses the saved result with zero calls and recomputes the period from the final chosen charges.usecase payment tests
Go handler + migrationPUT payee-name: landlord OK, tenant 403, stranger 403, 201 characters → 422, empty clears the name. The new columns exist with their defaults. Runs on the local pg-test container (:55432).http/, migrations/ tests
Frontend unitgetPaymentSignalPresentation differs list. PaymentReviewDetail shows the "Does not match" list and both names for payee. TenancyLedgerView shows the edit form to the landlord and the read-only line to the tenant, and hides it when empty.Vitest, next to each component
Browser smokeOn UAT with ego-browser: the landlord sets the pay-to name; the tenant sees "Pay to", pays and uploads a receipt with another payee name; the landlord detail page shows "Paid to a different name".Manual run, not a saved test

9. Out of scope

  • Reading the month from the receipt note.
  • Pre-filling the pay form from the AI result.
  • A pay-to name per property or per landlord.
  • Changing the review queue badge.

10. Notes from the handoff check (2026-09-30)

The handoff note listed two blockers. Both were already solved in the code:

  • paid_on 400 on pay step 1: fixed in 73f43b55 on the frontend. withPaidOnTimestamp in api/payments.ts sends YYYY-MM-DDT00:00:00Z. Not yet checked in a browser; the browser smoke in §8 covers it.
  • "No screen shows the AI result": /landlord/payments and /landlord/payments/<id> already show the verdict through getPaymentSignalPresentation.