English

TypeSafe Jev — Handover Dispute Sorting and Escalation

Jev helps with move-in handover disputes without grading damage: it matches a tenant's missing-item report to an existing report item for the landlord, and checks every thread comment for four fixed escalation reasons that only admins see. The original severity score is replaced because slice 5 bans AI severity grading toward the parties.

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

摘要

Jev 用两种不涉及损坏评级的方式协助入住交接争议:把租客的"漏报"与报告中已有的物品匹配(仅房东可见),并对每条线程留言检查四个固定的升级原因(仅管理员可见)。原构想中的严重度评分被替换,因为第 5 期设计禁止 AI 向双方给出严重度评级。

  • 构想 Jev #5 — 争议分类
  • 范围 backend/go、rental 应用、panel 应用
  • 房东可见 类型标签、类型筛选、漏报匹配提示
  • 租客可见 仅类型标签
  • 管理员可见 "交接升级"列表 + 邮件
  • 开关 TYPESAFE_RENTAL_HANDOVER_ENABLED(默认关闭)
状态
设计已在对话中批准(2026-10-02),等待书面规格评审
相关
第 5 期入住交接 §4.7 与 §5.1(AI 不得评定严重度);Jev 聊天消息检查(管理员发现列表、邮件提醒、重试扫描);ADR-0066(原始文本发送至 TypeSafe);决策模型提供方(提供方开关、按提供方设定阈值);ADR-0068(调用日志与重放)

为什么

在入住交接报告的租客审阅阶段,租客可以开启两种线程,之后双方轮流回复。

动作目标示例
dispute_entry(争议)一个物品(HandoverEntry)"沙发:干净",但实际有污渍
report_omission(漏报)一个房间(HandoverArea)"空调遥控器不见了"
  1. 漏报只指向房间。房东必须自己判断它是真正的新问题,还是与报告中已有物品相同("空调遥控器"对应物品"遥控器 x2")。普通代码无法匹配这类情况。
  2. 平台上没有人看到严重问题。线程中可能提到煤气味、停水、黑色霉菌或威胁,但只有双方会读到。

交付内容

房东

分类
  • 每条线程显示类型标签,由普通代码设定
  • 按类型筛选
  • 漏报线程:Jev 找到匹配时显示"可能与已有物品相关:沙发(客厅)"

管理员

升级
  • 任一方每条带留言的事件都检查四个原因
  • 任一"是" → 进入新的 panel 列表"交接升级"
  • 每条线程向所有管理员发一封邮件

租客

不变
  • 只新增类型标签
  • 永远看不到匹配提示或任何升级

决策

H1 · 用什么取代严重度评分?

四个固定的是/否升级原因,仅管理员可见。

保留第 5 期对双方的禁令。每条提醒都说明原因,管理员可以据此行动。

否决:仅管理员可见的 1–5 分(更接近被禁止的评级,且不说明原因);管理员和房东都可见的 1–5 分(违反第 5 期对一方的规则)。

H2 · 线程类型从哪里来?

普通代码:目标物品的 EntryType,report_omission 则为"报告漏项"。

类型永远正确且不需调用。留言本身已说明是哪种分歧。

否决:由 Jev 从固定列表中选择分歧种类(多一个需调校的 AI 字段,有时会错)。

H4 · Jev 检查哪些事件?

匹配只在开启 report_omission 的事件上运行。升级检查在租客或房东的每条带留言的事件上运行。

线程主题不会变。威胁或危险可能出现在任何回复中。

否决:仅开启事件(会漏掉之后的威胁);每个事件两项检查都跑(每次回复都重新分类同一线程)。

H6 · 谁能看到匹配提示?

房东和管理员。租客看不到。

它帮助负责回复的一方。若展示给租客,会像是平台在否定其主张。

否决:双方都可见(像在偏袒);仅管理员(房东得不到帮助)。

H7 · 管理员能做什么?

标记 reviewed 或 false_alarm。其他处理在应用外进行。

沿用已测试的 #1 模式。管理员操作不会改变报告。

延后:延长审阅期限。否决:通知双方(会让他们知道被 AI 标记)。

#决策原因
H3Jev 只做 (a) 将漏报匹配到已有物品,(b) 回答四个原因这是普通代码做不到的两件事
H5只用文字,不用照片Jev 是文本判定器。照片需要视觉模型,有其自身的成本和同意规则。
H8结果存放在新表中,而不是 rental_handover_responses回复是只追加的证据,会进入最终快照
H9检查与事件在同一事务中排队,由扫描任务执行用户无需等待 Jev,进程中断也不会丢失检查
H10每份报告最多 100 次检查回复需双方轮流,因此这是安全上限,而非常态限制
H11新 ADR 同时说明将留言文本发送给 TypeSafe 的隐私问题,以及为何仅管理员可见的升级不属于第 5 期禁止的评级与聊天功能需要 ADR-0066 的原因相同

升级原因

提到安全风险

safety_hazard

对人有危险:煤气味、电线外露、火花、栏杆或阳台松动、天花板开裂、玻璃破碎。

"卧室插座一插电就冒火花"

提到无法居住

not_livable

缺少基本需求:没水、没电、马桶无法使用、严重漏水或积水、门锁不上。

"入住以来整个单位都没水"

提到健康风险

health_risk

大面积霉菌、虫害(蟑螂、老鼠、臭虫)、污水。

"浴室天花板布满黑色霉菌"

提到威胁或辱骂

threat_or_abuse

一方威胁、骚扰或辱骂另一方。

"你不修的话我就去你家"

数据

一个迁移。新表 rental_handover_response_checks:

列类型含义
response_iduuid PRIMARY KEY REFERENCES rental_handover_responses(id)被检查的事件
report_iduuid NOT NULL用于每份报告上限和管理员链接
thread_iduuid NOT NULL用于每条线程只发一封邮件
statustext NOT NULLpending、done、skipped、failed(CHECK)
ask_matchboolean NOT NULL仅对开启 report_omission 的事件为真
escalation_reasonstext[] NOT NULL DEFAULT '{}'四个代码的子集
match_entry_iduuid NULL匹配到的物品;"无匹配"时为 null
attemptsint NOT NULL DEFAULT 0目前失败的 Jev 调用次数
checked_attimestamptz NULL保存为 done 的时间
alerted_attimestamptz NULL为此线程发送管理员邮件的时间
review_statustext NOT NULL DEFAULT 'open'open、reviewed、false_alarm(CHECK)
reviewed_by、reviewed_attext NULL、timestamptz NULL管理员审阅
created_attimestamptz NOT NULL事件时间

索引:

  • (created_at) WHERE status = 'pending',供扫描任务使用。
  • (created_at DESC) WHERE escalation_reasons <> '{}',供管理员列表使用。
检查行状态。管理员 review_status (open → reviewed / false_alarm)只适用于带原因的 done 行。
检查行状态。管理员 review_status(open → reviewed / false_alarm)只适用于带原因的 done 行。

后端

在 AppendResponse 中排队

文件:backend/go/internal/modules/rental/application/usecase/handover.go。在现有事务中、回复插入之后,当以下条件全部成立时插入一条 pending 检查行:

  • IsRentalHandoverCheckEnabled() 已开启;
  • 该事件有非空留言;
  • 该报告的检查行少于 100 条,否则该行保存为 skipped。

仅当 Action == report_omission 且线程是新开时,ask_match 为真。事务回滚则不留下任何行。

扫描任务

HandoverCheckSweepUseCase,在共享的 scheduler.RunPeriodic 上每分钟运行一次,与消息检查扫描一起启动。

从线程事件到管理员邮件。用户永远不需要等待 Jev。
从线程事件到管理员邮件。用户永远不需要等待 Jev。
  1. 检查开关

    两个开关都关闭 → 不做任何事。

  2. 认领

    最多 20 条 pending 行,最旧的优先(FOR UPDATE SKIP LOCKED)。

  3. 加载上下文

    回复本身、其目标(物品名称与状况备注,或房间名)、房间名、作者角色;当 ask_match 时,还有报告中每个物品,格式为"房间 – 物品"并附 id。

  4. 判定

    在 10 秒超时内调用判定器一次。

  5. 成功则保存

    done、原因、match_entry_id 和 checked_at。

  6. 失败则重试

    attempts + 1。达到 5 次,或 created_at 超过 24 小时 → failed。单行失败不会中断本轮。

  7. 提醒

    原因非空,且同一 thread_id 中没有行设置了 alerted_at → 给所有管理员发邮件并设置 alerted_at。邮件失败会记录日志;该行仍显示在管理员列表中。

即使报告在某行仍为 pending 时已定稿,该行仍会被检查。

Jev 判定器

  • 端口 port.HandoverCheckJudge,方法 Judge(ctx, HandoverCheckInput) (HandoverCheckResult, error)。
  • 适配器 backend/go/internal/modules/rental/adapter/outbound/typesafe/handover_check_judge.go,结构仿照 duplicate_judge.go。
  • 状态:comment、author_role、target_label、target_condition_note、room;匹配时还有 items,格式为 [{key, label}]。key 是生成的短标签(i1、i2、…),在代码中映射回物品 id。不含用户 id、姓名、地址或租约数据。
  • 问题:四个 Noul 问题(每个原因一个),匹配时再加一个 Choice 问题 matched_entry,选项为物品 key 和 none。
  • 留言只作为状态数据传入,绝不放进问题里。
  • Caller{rental, handover_check, <response id>};每次调用都记录在 typesafe_calls。cmd/replay-typesafe 支持 handover_check。
  • 判定器把四个概率和匹配结果返回给用例。只存储代码和物品 id,不存储概率。
  • EscalationThresholds reason = yes when p ≥ threshold按提供方 0.7
  • MatchThresholds match when top choice ≠ none AND p ≥ threshold按提供方 0.7
  • per-report cap check rows per report 100
  • sweep batch pending rows per 1-minute run 20
  • give up attempts ≥ 5 OR created_at older than 24h → failed 5

配置与装配

  • TYPESAFE_RENTAL_HANDOVER_ENABLED(默认 false)、TYPESAFE_HANDOVER_PROVIDER(默认 jev),在 config.go 中与其他 TypeSafe 配置一起读取。
  • IsRentalHandoverCheckEnabled() = rental 开关与 handover 开关同时开启。
  • module.go 解析提供方并构建判定器,方式与重复判定器相同。开关开启时,未知提供方或任一阈值表中缺少该提供方,都会导致模块启动失败。开关关闭时,不启动判定器和扫描任务。
  • .env.example 列出这两个变量。

API

路由调用者变更
交接报告详情(已有)房东每条线程新增 matched_entry_id(无匹配或未检查时为 null)
交接报告详情(已有)租客不变:从不返回 matched_entry_id
GET /api/rental/admin/handover-escalations?status=open|all管理员升级事件,按时间倒序:id、时间、房产、报告 id、线程 id、作者角色、原因、留言、目标名称、审阅状态
GET /api/rental/admin/handover-escalations/:id管理员整条线程,按时间正序,附目标和该线程的照片 id
POST /api/rental/admin/handover-escalations/:id/review管理员请求体 {"status": "reviewed"|"false_alarm"};记录操作人和时间
GET /api/rental/admin/handover-escalations/:id/media/:media_id管理员返回该线程的一张照片。目前 GET /handover-media/:id/content 只对双方开放。不属于该升级线程的照片 → 404。

前端

Rental 应用(frontend/solidstart/apps/rental)

位置变更
HandoverThreadList每条线程显示类型标签:"状况"、"物品清单"、"门禁设备"、"仪表读数"、"报告漏项"。双方都能看到。
HandoverThreadList,仅房东按类型筛选(默认"全部")
HandoverThreadList,仅房东带 matched_entry_id 的漏报线程:"可能与已有物品相关:{item}({room})",链接到该物品。绝不使用"重复"或"已覆盖"等字眼。
检查进行中不显示任何内容;下次刷新时出现提示
全部 状况 物品清单 报告漏项
客厅 报告漏项

租客:"空调遥控器不见了。"

可能与已有物品相关:遥控器 x2(客厅)
HandoverThreadList 中房东看到的漏报线程:类型筛选、类型标签和匹配提示。租客只看到标签。

Panel 应用(frontend/solidstart/apps/panel)

位置变更
侧边栏"交接升级",位于"聊天发现"旁边
/admin/rental/handover-escalations列表:时间、房产、报告、作者角色、原因标签、留言、状态。筛选 Open(默认)/ All。
行详情整条线程,附目标和照片;标记已审阅与标记误报

邮件

主题"Rental handover escalation"。正文包含原因标签和指向 panel 行的链接,不含留言文本,与聊天提醒相同。幂等键 rental:handover-escalation:<thread id>。

措辞

错误处理

情况结果
Jev 失败、超时或返回无效输出保持 pending;下一轮重试;5 次或 24 小时 → failed。无提示,无升级。
开关关闭不产生新行。已有的 pending 行等待。重新开启不会补检旧事件。
无留言的事件(resolve、withdraw)不产生行
单份报告已有 100 次检查后续事件 → skipped
匹配到的物品之后被删除不会发生:提交后房间与物品不可更改(第 5 期)
管理员邮件发送失败记录日志;该行仍在管理员列表中;不重试
同一线程两次升级只发一封邮件(alerted_at)
留言中的提示注入留言只作为状态数据;校准集包含注入用例
检查进行中报告已定稿仍会检查

测试

TDD:先写失败的测试,再写代码。Go 测试在 pg-test(:55432)上运行,绝不在 UAT 上运行。

层级内容位置
Go 单元状态只含所列 key;物品 key 映射回物品 id;阈值按提供方;恰好等于阈值 → 是 / 匹配;首选为 none 或低于阈值 → 无匹配;未知提供方或缺少阈值会失败typesafe/handover_check_judge_test.go、pin_test.go、模块测试
Go 用例仅在有留言且开关开启时创建行;同一事务(回滚 → 无行);ask_match 只用于开启 report_omission;第 101 次检查 → skippedusecase 交接测试
Go 扫描每轮 20 条;SKIP LOCKED 认领;失败 → 重试;第 5 次失败或 24 小时 → failed;单个坏行不会中断本轮;两次升级只发一封邮件;开关关闭 → 不做事usecase 扫描测试
Go handler房东详情带 matched_entry_id;租客详情永远不带;任何一方响应或最终快照都不含原因;管理员列表与审阅的 401 / 403 / 404 / 400 情况;审阅记录操作人和时间http/ 测试
迁移表、status 与 review_status 上的 CHECK、索引;重复运行不产生变化migrations/ 测试
前端单元每种类型都有标签;匹配提示与筛选仅房东可见;panel 列表、筛选、审阅按钮;黄金测试确保每个原因代码在两个应用中都有 en / ms / zh 文本Vitest
校准(非 CI)已标注的马来西亚英语、马来语和 Manglish 留言,含陷阱("safety pin missing"、"kill the bugs")和注入用例。在 UAT 以外开启开关前设定阈值cmd/ 脚本,同 #1
浏览器冒烟在 UAT 用 /ego-browser:租客开启一条漏报和一条"插座冒火花"争议;房东看到标签和匹配提示;管理员看到升级、收到邮件并标记已审阅手动运行

范围之外

  • 管理员延长审阅期限(review_due_on)。计划后续实现;需要为最终快照制定专门规则。
  • 通知双方有管理员在跟进。
  • 以照片作为输入。
  • 退租报告与押金决定。
  • 任何形式的严重度评分。
  • 检查聊天消息(构想 #1 已经覆盖)。

上线门槛

在以下条件满足前,TYPESAFE_RENTAL_HANDOVER_ENABLED 在 UAT 以外保持关闭:

  1. ADR 通过

    H11 中的 ADR 已撰写并通过。

  2. 校准

    校准运行确定两个阈值。

  3. 告知

    用户告知内容涵盖交接留言发送至 TypeSafe,以及管理员审阅升级线程。