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
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".
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:
| Risk | Example | Today |
|---|---|---|
| Wrong payee (收款人) | Money went to another account, and the receipt is claimed as rent | Missed. PayeeName is read but never compared. |
| Old receipt for a new charge | A March receipt is uploaded for the September rent, and the tenant types the March date | Missed. 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
| # | Decision | Why |
|---|---|---|
| D1 | The payee is compared against a new pay-to account name, not the landlord's display name | Bank receipts show the account holder name. Display names ("Mr Tan") and spouse or company accounts would raise many false alarms. |
| D2 | The pay-to name is stored per tenancy | One field on an existing record, with no new landlord settings record. Retyped about once a year. The tenant sees it on the same page. |
| D3 | The period check is a date rule in plain code | Every 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). |
| D4 | Period 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. |
| D5 | One verdict plus ai_differs_fields | The queue keeps one badge. The detail page says why. Follows the existing "Unreadable" list pattern. |
| D6 | Jev 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. |
| D7 | A later change to the pay-to name does not change old results | The verdict is saved at upload. The landlord can compare the two names shown on the detail page. |
| D8 | No new call cap | At most one Jev call per receipt read, and receipt reads are already capped at 10 per tenancy per day. |
4. Data
One migration.
| Table | Column | Type | Meaning |
|---|---|---|---|
tenancies | payee_name | text NOT NULL DEFAULT '' | Pay-to account name. Empty = not set. |
payment_records | ai_differs_fields | text[] NOT NULL DEFAULT '{}' | Fields that differ. Values: amount, currency, paid_on, reference, payee, period. |
payment_records | ai_payee_match | text 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.
| Field | Differs when | Unreadable when |
|---|---|---|
| amount, currency, paid_on, reference | As today | As today |
payee | PayeeMatch == mismatch | PayeeMatch == unknown |
period | ext.PaidOn and EarliestChargeDueOn are both set, and ext.PaidOn (UTC day) < EarliestChargeDueOn − 1 month | Never. When the receipt date is unreadable, the date is already reported unreadable and the period is skipped. |
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
UnreadableFieldsis never changed.ai_payee_matchis returned on the payment record, and the detail page shows "Payee could not be checked" when it isunknown. - The 1-month limit is one named constant,
PeriodEarlyLimitMonths = 1. It is subtracted with the same calendar-month logic asScheduleMonthBoundary(clamping on short months, never rawAddDate). - 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
payment_records.ai_payee_match; submit reads it and never calls Jev.- Clean up both names:
NormalizeReference(upper-case, extra spaces removed). - The tenancy
payee_nameis empty →PayeeMatch = "". No call is made. - The receipt
PayeeNameis empty →unknown. - The cleaned names are equal →
match. No Jev call. - Otherwise, if a payee judge is wired, call it once. A probability ≥ the provider threshold gives
match, a lower probability givesmismatch, and a failure givesunknown. - No judge is wired (switch off) →
unknown.
5.3 Jev payee judge
- Port
port.PayeeJudgewithJudge(ctx, PayeeJudgeInput) (float64, error)- Adapter
backend/go/internal/modules/rental/adapter/outbound/typesafe/payee_judge.go, shaped likeduplicate_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_callsfor replay, as for the other Jev features.
5.4 Config and wiring
TYPESAFE_RENTAL_PAYEE_ENABLED(defaultfalse) andTYPESAFE_PAYEE_PROVIDER(defaultjev), read inconfig.gonext to the duplicate values.IsRentalPayeeEnabled()= rental switch and payee switch both on.module.goresolves 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.examplelists 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_namefor both landlord and tenant.
6. Frontend
App: frontend/solidstart/apps/rental. New text uses Paraglide messages (m.rental_…).
| Screen | Route / component | Change |
|---|---|---|
| Landlord tenancy page | /landlord/tenancies/<id>, TenancyLedgerView | A "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>, TenancyLedgerView | Read-only "Pay to: …". Hidden when empty. |
| Tenant pay page | /tenant/tenancies/<id>/pay, PaymentWizard step 1 | The same "Pay to: …" line above the form. Hidden when empty. |
| Landlord payment detail | /landlord/payments/<id>, PaymentReviewDetail | A "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/payments | No change. |
Plumbing
api/payments.ts:ai_differs_fields?: string[]andai_payee_match?: '' | 'match' | 'mismatch' | 'unknown'onPaymentRecord.api/tenancies.ts:payee_name?: stringon the tenancy, plussetPayeeName(tenancyId, name).paymentSignals.ts:getPaymentSignalPresentationreturnsdiffersFields,hasDiffersFieldsandpayeeUnchecked(ai_payee_match === 'unknown'). Both review screens read it from there. The detail page showspayeeUncheckedas one more line under the "Unreadable" list.
7. Error handling
| Case | Result |
|---|---|
| Jev fails, times out or returns bad output | unknown → payee unreadable. The upload succeeds and the error is logged. |
| Payee switch off | Exact 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-landlord | 403 |
PUT payee-name longer than 200 characters | 422 |
| The pay-to name changes after upload | Old results stay (D7). |
8. Testing
| Level | What | Where |
|---|---|---|
| Go unit | ComputeAIAgreement 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 unit | The 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 usecase | Upload 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 + migration | PUT 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 unit | getPaymentSignalPresentation 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 smoke | On 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_on400 on pay step 1: fixed in73f43b55on the frontend.withPaidOnTimestampinapi/payments.tssendsYYYY-MM-DDT00:00:00Z. Not yet checked in a browser; the browser smoke in §8 covers it.- "No screen shows the AI result":
/landlord/paymentsand/landlord/payments/<id>already show the verdict throughgetPaymentSignalPresentation.